The SSPrefillData script for Win-Test will "pre-fill" data into the logging window for the
ARRL Sweepstakes contest, using data from an Extra Data file file.

Change History:
      11/04/16 - Do not overwrite prec, check, or section if already filled in.  Maintains
                 position of current cursor.  Does not change spacebar order when stepping
                 through fields.
      11/17/14 - Restore previous contents of serial no. field, if any, instead of
                 clearing it.  Tnx NR5M.
      11/04/14 - Maintain state of ExchangeSent flag for ESM users.  Tnx W0YK.
               - Fold file name in argument to UPPERCASE before testing for file name changes
                 Tnx W0YK.
               - Update comments to show how to call this script from a scenario.  Tnx W0YK.
               - Fix bug:  cursor was ending up in Precedence field instead of Number received
                 field (in secondary radio window).  Tnx W0YK.
               - Format of sample .xdt file adjusted for column alignment.  Tnx W0YK.
      12/05/13 - Modified to reposition cursor to beginning of each field (except
                 callsign field) to make it easier to overtype the data.  Tnx NR5M.

Pre-requisite:
      Win-Test version 4.11 or later
      If needed, download Win-Test from http://download.win-test.com/v4/bin (password required)
      If you can't remember your password, read:
         http://docs.win-test.com/wiki/FAQ:Problems_Registering_and_Running
      Download the Win-Test prefill file from
         http://www.nccc.cc/members/ss-2013/SS_2013_wintest_prefill.xdt (NCCC password required)
      or use the link on the NCCC Sweepstakes Page:
         http://www.nccc.cc/members/sweepstakes-main.html

      -or-

      Create a text file in the following format, one line per callsign:

         # TITLE Sample Prefill data
         4U1WB       U 4U1WB          89  MDC 
         AA0A        U AA0A           60  MO  
         AA0AI       A AA0AI          75  IA   
         ...

      and save it in the "Extras" folder.  See SamplePrefillData.xdt as an example.

Installation:

   1. Copy SSPrefillData.wts to your Win-Test Scripts directory 
      To open this directory in Windows Explorer, start Win-Test and select
      File | Explore | /scripts directory from the menu.
   2. In Win-Test, select Tools | Scripts Manager (or type SCRIPTS [Enter] in the logging window)
   3. Highlight SSPrefillData and click the [Properties...] button
   4. Click the [Define] button
   5. Press the [TAB] or left-paren [ ( ] key or whatever key you wish to use to run the script.
      (Note:  do NOT assign it to the Spacebar key or to the Enter key)
   6. In the "Argument:" box, specify the Win-Test prefill file name, IN QUOTES, e.g.
      Argument:  "SamplePrefillData.xdt"
      (Use the double-quote character).
      This file must be stored in the "Extras" folder (File | Explore | /extras directory)
   7. Press [OK]
   8. Press [OK] again
   9. To have the script pre-fill data automatically without having to press a special key, 
      modify the scenario messages as follows (see image file SampleScenario.png)
      (This assumes that the Primary radio is used for RUN, and the secondary only for S&P)

      a. From the Win-Test menu:  

         Operating | Technique | Advanced SO2R (select to enable)
         Operating | Edit the scenarios

      b. Primary Radio scenario:

            For Phone:
               F2:      $R2R2 $F2 #SSPREFILLDATA("SAMPLEPREFILLDATA.XDT") $R1R2
            For CW:
               INSERT:  $R2R2 $INSERT #SSPREFILLDATA("SAMPLEPREFILLDATA.XDT") $R1R2

         Secondary Radio scenario:

            For both Phone and CW:
               F4:      $R1R1 $F4 #SSPREFILLDATA("SAMPLEPREFILLDATA.XDT") $R1R2

      ** NOTE **  Use the SAME file name in each message.

   10. Type MSGS [Enter] in the logging window and reprogram your CW messages for Sweepstakes
       as shown in the sample image file:  SampleCWMsgs.png.
       ESM users must have the $SETEXCHANGESENT and $RSTEXCHANGESENT macros as shown.

How to use:

   1. Press [TAB] or [ ( ] once to load the .XDT file into memory.
      The first time you do this after launching Win-Test, a pop-up message box appears
      indicating the number of pre-fill entries loaded into memory, and the full file name.

      Press Esc or Spacebar to close the message box.

      If you see an error message similar to this:

         File SSPrefill.wts:0: attempt to index global 'SS_2013_wintest_prefill' (a nil value)

      It means you forgot to surround the script argument (the .xdt file name) with double-quotes
      in the argument box or scenario message.  See "Installation" section, step 6 and step 9.b.

   2. Enter a callsign like AA0A in the logging window and press [TAB],
      or press [Enter] if using ESM mode.
     
      If the call is found in the .xdt file, all available exchange data will be pre-filled
      into the logging window after the exchange is sent, and the cursor will be positioned
      to the QSO number received field.

   3. Press [Spacebar] to jump from field to field, verifying that the exchange data being
      sent by the operator matches what was copied from the pre-fill file.  Over-type anything
      that doesn't match the database.

   4. (Optional but recommended)
      a. Press Alt-X to open the Extra Information Window
      b. Right click on the window and select "Extra data files ..." from the pop-up menu
      c. Click [Add]
      d. Select the same .xdt file used above
      e. Click [Open]
      f. Click [OK]
      g. Enter a known callsign like AA0A and move the Extra Information Window so the
         columns line up with the logging window.

Please email me if you use this program and find any bugs.  Please describe step-by-step what to
do to reproduce the problem.

Send screen shots of pop-up messages.  These can be saved by pressing Alt-PrintScreen
to copy the active window to the Windows clipboard, then Paste the image into an email or
into Windows Paint and save as a .PNG file.

73,
Bob, N6TV
n6tv@arrl.net
11 November 2016 06:09 UTC
