Chip 1999 September/CHIPCD_9_99.iso/software/testsoft/pcanywhere/SAMPLE.SCR

Text File | 1999-05-10 | 67KB | 1,437 lines

;  *******************************************************************
;  *                                     *
;  *              pcANYWHERE sample script "SAMPLE.SCR"              *
;  *            Copyright 1998-1999 Symantec Corporation         *
;  *                Created by Larry R. McDowall                    *
;  *                                     *
;  *******************************************************************
;
;
;
;
;    TABLE OF CONTENTS
;    *****************
;
;    Introduction        Describes the purpose of this script.
;    How This Script Works    Brief description of what this script does.
;    Setup and Installation    How to install and use this script.
;    Support            How to obtain support for this script.
;    Main Body of Script    The script's code and subroutines.
;    Technical Overview    This appears after the main body of the script.
;                This section includes extensive descriptions
;                of how this script works.
;
;
;    INTRODUCTION
;    ************
;
;    The purpose of this script is to illustrate how to use key procedures
;     in the pcANYWHERE Scripting Language. For more information on these
;    procedures, please refer to the Technical Overview at the end of this
;    script.
;
;    The following procedures are included in this script:
;
;    * How to check for errors and lost connections.
;    * How to schedule a script.
;    * How to run a script from a command line.
;    * How to use a log file.
;    * How to use a data file to call multiple hosts using a modem.
;    * How to transfer a file.
;    * How to run a program.
;    * How to pause a script while a program runs.
;
;
;    HOW THIS SCRIPT WORKS
;    *********************
;
;    The following describes how this script works:
;
;    1. Create or open the log file LOG.PCA, the host data file HOSTS.PCA,
;       and the sample application SCRIPT.BAT.
;
;    2. Read the next host computer's name to call from the DATA.PCA file.
;
;    3. Call the next host computer using a modem as read from the DATA.PCA
;       file.
;
;    4. Transfer the remote computer's C:\SCRIPT.BAT file to the host
;       computer's C: drive.
;
;    5. Delete the flag file PCA.FLG on both the remote and host computers
;       if it exists on either of them.
;
;    6. Run the SCRIPT.BAT file on the host computer.
;
;    7. Pause the script while the SCRIPT.BAT file runs. The script loops
;       looking for the existence of the new PCA.FLG file that the SCRIPT.BAT
;       file will create once it is finished.
;
;    8. After the script detects the PCA.FLG file which indicates that the
;       SCRIPT.BAT file has finished, disconnect from the host computer.
;
;    9. If there are more host computers to call, the script goes back to
;       number 2 and continues until there are no more hosts to call.
;
;    10. The script closes the LOG.PCA and DATA.PCA files. If any errors
;        occurred while the script ran, the LOG.PCA file is displayed using
;        the Notepad application from Windows.
;
;    11. The script ends.
;
;
;    SETUP AND INSTALLATION
;    **********************
;
;    Step 1. Use a supported version of pcANYWHERE on both the remote and
;        host computers. Apply any updates for each from the Symantec
;        web site or BBS. This script supports the following pcANYWHERE
;        versions running on the specified operating systems:
;
;        * pcAnywhere 9.0 for Windows 95/98, and Windows NT 4.0.
;           * pcANYWHERE32 8.0 for Windows 95/98 and Windows NT 4.0/3.51.
;            * pcANYWHERE 2.0 for Windows 3.1 and Windows 95.
;            * pcANYWHERE 5.0 for DOS.
;        * Scripts running between pcAnywhere 9.0 or pcANYWHERE32 8.0 to
;          pcANYWHERE 5.0 are not currently supported. For more
;          information, please refer to the Symantec Knowledge Base
;          document "How to Write a Script from pcANYWHERE32 to a DOS-
;          based pcANYWHERE".
;        * NOTE: Any version of pcANYWHERE other than those listed above
;          are not supported. If you experience issues when using an old
;          version of pcANYWHERE, it is strongly recommended to upgrade
;          to a current version.
;
;    Step 2. Copy this script to your pcANYWHERE program directory on the
;        remote computer.
;
;    Step 3. There will be one host that will be called twice using a modem,
;        named "MODEM". This remote control item requires the host
;        computer's modem number, along with a logon name and password
;        (if applicable).
;
;        * pcAnywhere 9.0 and pcANYWHERE32 8.0 already have a MODEM item
;              located under the "Remote Control" area. Enter your host's
;              modem number in it's Properties section under the Settings
;          tab.
;        * All other versions of pcANYWHERE will need to have the MODEM
;          remote control item created and then have the host's modem
;          number entered into its properties.
;
;    Step 4. The host computer must be put into "waiting" mode, waiting for
;        an incoming call from the remote computer. Ensure that the
;        modem line used by the host does not have any other device, such
;        as a fax machine or voice mail, attached to it.
;
;    Step 5. Run the script from pcANYWHERE on your remote computer.
;
;
;    SUPPORT
;    *******
;
;    This script is provided as-is. pcANYWHERE Technical Support may answer
;    specific questions about a specific script command, but they cannot
;    assist you in troubleshooting or programming this or other scripts.
;    Support may or may not be given if you modify this script in any
;    way, and then have issues using it. (Does the script work without
;    modifying it?) However, pcANYWHERE Technical Support does offer a Script
;    Consulting service which can help you troubleshoot or program a script.
;
;    Additional information about how to write or troubleshoot a script can
;    be found in the Symantec Knowledge Base. The following documents are
;    important resources there:
;
;       * "How to Obtain Support for the pcANYWHERE Scripting Language"
;       * "pcANYWHERE Scripting Language Technical Documents"
;       * "How to Write a Script to Connect to a Host Computer"
;       * "How to Write a Script to Connect to an Online Service"
;       * "How to Troubleshoot a Script"
;       * "How to Transfer Files to or From a Host Computer Using a Script"
;       * "How to Transfer Files to or From an Online Service Using a Script"
;
;    Updates to this script can be found on the Symantec web site, at:
;
;    Symantec
;    www.symantec.com
;
;    Script Consulting provides two levels of support for your pcANYWHERE
;    Scripting Language needs:
;
;    1. Script Consulting and Troubleshooting. This is a fee-based service.
;       This service covers answering advanced questions about how to use
;       the Scripting Language or how to program it, and also provides
;       troubleshooting for a script that you have written.
;
;    2. Script Programming. This is a fee-based service where a Script
;       Consultant will program a script for you to your specifications.
;
;    If you are interested in obtaining Script Consulting or Programming, you
;    may contact pcANYWHERE Technical Support and request that a Script
;    Consultant contact you to discuss your needs. Please contact our
;    StandardCare support number for this service:
;
;    pcANYWHERE StandardCare Support: [phone]




; *******************************************************************
; VARIABLES - Declares variables for the script to use.
; *******************************************************************

Integer ERR_COUNT             ; Total number of errors during script.
Integer I                 ; Increments to allow script to pause.
Integer LOOP                 ; Sets total number of loops to use.
Integer RES                 ; Sets success/failure of a subroutine.
String CDIR[255]             ; Sets the working directory.
String CDIR2[255]             ; The secondary string for the work dir.
String ERR[255]                 ; Stores $ERROR value if error occurs.
String ERR_AMOUNT[255]             ; Allows log file to save $ERROR value.
String HOST[255]             ; Name of the host computer to call.
String LOG[255]                 ; The primary log description.
String LOG2[255]             ; The secondary log description.
String SOURCE[255]             ; Source file name to file transfer.
CDIR = $CURDIR                 ; Assign CDIR to the working directory.
StrLen CDIR                 ; Check for root drive.
If $RESULT == 3 Then SubStr CDIR 1 2  CDIR  ; If root, remove "\" in path name.


; *******************************************************************
; MAIN - Controls branching to subroutines.
; *******************************************************************
;
; NOTE 1: If you want the script to schedule itself to begin execution at a
; later date and time than when you run it, remove the semicolon to the left of
; the "Wait Until 2359" command found at the beginning of the MAIN
; subroutine.
;
; By default, the script will then begin execution at 11:59 PM on the same day
; it was run. You may want to change the time to start from 2359 to something a
; few minutes from when you will be testing the script. Use 24-hour format for
; the time.
;
; A script runs on the same day it is launched with this method. If you assign
; the time to be 0000, midnight, then the script will not run, but will stay
; as a black terminal window (its dormant mode until it would have normally
; started). This is because midnight has already occurred today. Instead, use
; 2359 or a similar "near-midnight" time for the current day, as in the
; example above.
;
; If you have pcANYWHERE32 8.0, 8.01, or 8.02, and you want to use the Wait
; Until command without a date parameter, then you should apply a special
; update to pcANYWHERE32 to enable it to work with just the time parameter.
; Otherwise, the script will not start at the specified time. With this update,
; a script can be run each day, without having to change the date, and then
; start at the prespecified time. This update can be found here:
;
; FTP Location for AWSCR32.DLL File
; ftp://ftp.symantec.com/public/english_us_canada/products/pcanywhere/
; pcanywhere32/beta/AWSCR32.DLL
;
; Note that the file name is required to be uppercase, whereas the other part
; of the link does not have to be.
;
; To install this, simply copy it over the original AWSCR32.DLL file, in the
; pcANYWHERE32 directory. (Make sure that pcANYWHERE32 is not running when you
; do this.)
;
; For more information on how to schedule a script, please refer to the sections
; "How to Schedule a Script Using a Third Party Scheduler" and "How to Program a
; Script to Schedule Itself" which are both found in the Technical Overview at
; the end of the script.
;
; NOTE 2: If you do not want the script to display the log file if errors
; occurred, add a semicolon to the left of the "If ERR_COUNT > 0 THEN GoSub
; @DISPLAY_LOG" command line near the end of the MAIN subroutine.
;
; Please refer to the DISPLAY_LOG subroutine for information on how to configure
; the display of the log file.
;

@MAIN:                     ; The primary subroutine of the script.
;  Wait Until 2359             ; Schedules script to start at 11:59 PM.
  GoSub @OPEN_FILES             ; Opens necessary files.
  If RES == 1 GoTo @MAIN_END           ; If cannot open log file, abort script.
  If RES == 2 GoTo @MAIN_CLOSE          ; If cannot open other files, end script.

@MAIN_CALL_HOSTS:             ; Main subroutine that controls and calls
                     ; other subroutines.
  RES = 0                 ; Reset subroutine success/failure.
  GoSub @NEXT_HOST             ; Read next host to call from DATA.PCA.
  If RES == 1 GoTo @MAIN_CLOSE          ; If no more hosts to call, end script.
  GoSub @CALL_HOST             ; Call the next host.
  If RES == 1 GoTo @MAIN_CALL_HOSTS  ; If call to host failed, call next host.
  GoSub @TRANSFER_FILE             ; Transfer the SCRIPT.BAT file to host.
  If RES == 1 GoTo @MAIN_DISCONNECT  ; If error, disconnect and call next host.
  If RES == 2 GoTo @MAIN_CALL_HOSTS  ; If lost connection, call next host.
  GoSub @RUN_FILE             ; Run the SCRIPT.BAT on the host.
  If RES == 1 GoTo @MAIN_CALL_HOSTS  ; If lost connection, call next host.

@MAIN_DISCONNECT:             ; Subroutine used to disconnect from host.
  LOG = "Disconnecting from host '"  ; Create a log description.
  StrCat LOG HOST             ; Add host's name to the description.
  StrCat LOG "'."             ; End the description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  If $DCD !=1 Then GoSub @LOST_CONNECTION  ; Lost connection.
  If $DCD == 1 Then Session End         ; Disconnect from the host.
  GoTo @MAIN_CALL_HOSTS             ; Call the next host.

@MAIN_CLOSE:                 ; Subroutine used to end the script.
  ERR_AMOUNT = ERR_COUNT         ; Convert ERR_COUNT to a string.
  LOG = "Script completed with "     ; Create a log description.
  StrCat LOG ERR_AMOUNT             ; Add total errors that occurred.
  LOG2 = " error(s)."             ; Add " errors(s)." to the description.
  StrCat LOG LOG2             ; End the description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  Close 1                 ; Close the log file.
  Close 2                 ; Close the DATA.PCA file.

@MAIN_END:                 ; Subroutine used to end the script.
  If ERR_COUNT > 0 Then GoSub @DISPLAY_LOG  ; If any errors, display log file.
  End                     ; End the script.




; *******************************************************************
; OPEN FILES - Opens or creates necessary files for script to use.
; *******************************************************************

@OPEN_FILES:                 ; Subroutine used to create log file.
  Find First ".\LOG.PCA"         ; Try to find the LOG.PCA file.
  If $RESULT == 1 GoTo @OPEN_FILES_LOG_DATA_SCRIPT  ; If found, open log file.
  Create 1 ".\LOG.PCA" "W"         ; If not found, create it.
  Write Line 1 "**** pcANYWHERE Script Log File ****"  ; Add title.
  Close 1                 ; Close the log file.

@OPEN_FILES_LOG_DATA_SCRIPT:         ; Subroutine used to open necessary files.
  $ERROR = 0                 ; Reset the value of $ERROR to 0.
  Open 1 ".\LOG.PCA" "W"         ; Open the log file.
  ERR = $ERROR                 ; Assign ERR the value of $ERROR.
  If $ERROR < 0 GoTo @OPEN_FILES_ERROR_LOG  ; If error, abort the script.
  Seek 1 0 2                 ; Position the pointer to end of file.
  Write Line 1 " "             ; Write a blank line.
  LOG = "Starting script."         ; Create log description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  $ERROR = 0                 ; Reset the value of $ERROR to 0.
  Create 2 ".\DATA.PCA" "W"         ; Create the HOSTS.PCA file.
  ERR = $ERROR                 ; Assign ERR the value of $ERROR.
  If $ERROR < 0 GoTo @OPEN_FILES_ERROR_DATA  ; If error, end the script.
  Write Line 2 "MODEM"               ; Write 1st name of host to call.
  Write Line 2 "MODEM"             ; Write 2nd name of host to call.
  Close 2                 ; Close the DATA.PCA file.
  Open 2 ".\DATA.PCA" "R"         ; Open DATA.PCA file for read-only.
  $ERROR = 0                 ; Reset the value of $ERROR to 0.
  Create 3 "C:\SCRIPT.BAT" "W"         ; Create the SCRIPT.BAT file.
  ERR = $ERROR                 ; Assign ERR the value of $ERROR.
  If $ERROR < 0 GoTo @OPEN_FILES_ERROR_SCRIPT  ; If error, end the script.
  Write Line 3 "@ECHO OFF"         ; Write "@ECHO OFF" to the file.
  Write Line 3 "C:"             ; Write "C:" to the file.
  Write Line 3 "CD \"             ; Write "CD \" to the file.
  Write Line 3 "DIR /A"             ; Write "DIR /A" to the file.
  Write Line 3 "DIR >PCA.FLG"         ; Write "DIR >PCA.FLG" to the file.
  Close 3                 ; Close the SCRIPT.BAT file.
  RES = 0                 ; Set return code to success.
  Return                 ; Return to the MAIN subroutine.

@OPEN_FILES_ERROR_LOG:             ; Subroutine used if cannot open log.
  LOG = "Error "             ; Create a message description.
  StrCat LOG ERR             ; Add $ERROR value.
  StrCat LOG " while accessing the LOG.PCA file."  ; End message.
  Type Line LOG                 ; Display the message.
  Wait 10                 ; Wait 10 seconds.
  RES = 1                 ; Set return code to failure.
  Return                 ; Return to the MAIN subroutine.

@OPEN_FILES_ERROR_DATA:             ; Subroutine used if cannot open DATA.PCA.
  LOG2 = "while accessing the DATA.PCA file."  ; Create log description.
  GoSub @ERROR                 ; Add the error number.
  RES = 2                 ; Set return code to failure.
  Return                 ; Return to the MAIN subroutine.

@OPEN_FILES_ERROR_SCRIPT:         ; Subroutine used if cannot open
                     ; SCRIPT.BAT.
  LOG2 = "while accessing the SCRIPT.BAT file."  ; Create description.
  GoSub @ERROR                 ; Add the error number.
  RES = 2                 ; Set return code to failure.
  Return                 ; Return to the MAIN subroutine.




; *******************************************************************
; NEXT HOST - Read the next host computer to call from data file.
; *******************************************************************

@NEXT_HOST:                 ; Subroutine used to read next host
                     ; to call.
  $ERROR = 0                 ; Reset the value of $ERROR to 0.
  Read Line 2 HOST             ; Assign HOST to the next host to call.
  If $ERROR < 0 GoTo @NEXT_HOST_DONE ; If error, end the script.
  StrLen HOST                 ; Check if HOST value is valid.
  If $RESULT < 1 GoTo @NEXT_HOST_DONE  ; If error, end the script.
  RES = 0                 ; Set return code to success.
  Return                 ; Return to the MAIN subroutine.

@NEXT_HOST_DONE:             ; Subroutine used if no more hosts to call.
  RES = 1                 ; Set return code to failure.
  Return                 ; Return to the MAIN subroutine.




; *******************************************************************
; CALL HOST - Calls the next host computer.
; *******************************************************************

@CALL_HOST:                 ; Subroutine used to call the next host.
  Session Retry 3             ; Retry calling a host three times.
  Session Delay 1             ; Wait one minute before redialing.
  LOG = "Calling host '"         ; Create a log description.
  StrCat LOG HOST             ; Add the host name.
  StrCat LOG "'."             ; End the description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  Wait 5                 ; Used to wait five seconds before dialing
                     ; the host to enable it to correctly reset
                     ; its modem.
  Session Dial HOST             ; Call the host computer.
  If $DCD != 1 GoTo @CALL_HOST_NO_CONNECTION  ; If no connection, call
                                              ; next host.
  LOG = "Successfully connected to host '"  ; Create a log description.
  StrCat LOG HOST             ; Add the host name to the description.
  StrCat LOG "'."             ; End the description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  RES = 0                 ; Set return code to success.
  Return                 ; Return to the MAIN subroutine.

@CALL_HOST_NO_CONNECTION:            ; Subroutine used for no connection.
  ERR_COUNT = ERR_COUNT + 1          ; Increment how many errors occurred.
  LOG = "Error: unable to connect to host '"  ; Create a log description.
  StrCat LOG HOST             ; Add the host name.
  StrCat LOG "'."             ; End the description.
  GoSub @WRITE_LOG             ; Write description to the log.
  RES = 1                 ; Set return code to failure.
  Return                 ; Return to the MAIN subroutine.




; *******************************************************************
; TRANSFER FILE - Transfers a file from the remote to the host.
; *******************************************************************

@TRANSFER_FILE:                 ; Subroutine used to transfer a file.
  SOURCE = "C:\SCRIPT.BAT"           ; Assign the source name.
  If $DCD != 1 GoTo @TRANSFER_FILE_LOST  ; If lost connection, call next host.
  $ERROR = 0                 ; Reset the value of $ERROR to 0.
  SessOpr Remote Send SOURCE "C:\SCRIPT.BAT"  ; Transfer file.
  ERR = $ERROR                 ; Assign ERR the value of $ERROR.
  If $ERROR < 0 GoTo @TRANSFER_FILE_ERROR  ; If error, call next host.
  LOG = "Transfer of '"             ; Create a log description.
  StrCat LOG SOURCE             ; Add the source file name.
  LOG2 = "' was successful."         ; Add "' was successful." to description.
  StrCat LOG LOG2             ; End the description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  RES = 0                 ; Set return code to success.
  GoSub @LOOP                 ; Allows time for file manager to reset.
                     ; Needed for pcAnywhere 9.0 and
                     ; pcANYWHERE32 8.0 only.
  Return                 ; Return to the MAIN subroutine.

@TRANSFER_FILE_ERROR:             ; Subroutine used if file transfer failed.
  LOG2 = "while transferring '"         ; Create a log description.
  StrCat LOG2 SOURCE             ; Add the source file name.
  StrCat LOG2 "'."             ; End the description.
  GoSub @ERROR                 ; Add the error number.
  RES = 1                 ; Set return code to failure.
  Return                 ; Return to the MAIN subroutine.

@TRANSFER_FILE_LOST:             ; Subroutine used if lost connection.
  GoSub @LOST_CONNECTION         ; Create and save a log description.
  RES = 2                 ; Set return code to failure.
  Return                 ; Return to the MAIN subroutine.




; *******************************************************************
; RUN FILE - Runs a file on the host computer.
; *******************************************************************

@RUN_FILE:                 ; Subroutine used to run a file on host.
  Del "C:\PCA.FLG"             ; Delete flag file on remote.
  If $DCD != 1 GoTo @RUN_FILE_LOST   ; If lost connection, call next host.
  SessOpr Host Run "COMMAND.COM /C DEL C:\PCA.FLG"  ; Delete on host.
  GoSub @LOOP                 ; Pause script for five seconds.
  LOG = "Executing 'C:\SCRIPT.BAT' on the host..."  ; Create description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  If $DCD != 1 GoTo @RUN_FILE_LOST   ; If lost connection, call next host.
  SessOpr Host Run "COMMAND.COM /C C:\SCRIPT.BAT"  ; Run SCRIPT.BAT.
  GoSub @CHECK_FLAG             ; Pause script while SCRIPT.BAT runs.
  RES = 0                 ; Set return code to success.
  Return                 ; Return to MAIN subroutine.

@RUN_FILE_LOST:                 ; Subroutine used if lost connection.
  GoSub @LOST_CONNECTION         ; Create and save a log description.
  RES = 1                 ; Set return code to failure.
  Return                 ; Return to the MAIN subroutine.




; *******************************************************************
; WRITE LOG - Writes a description to the log file.
; *******************************************************************

@WRITE_LOG:                 ; Subroutine used to write log description.
  Write String 1 $DATE             ; Write the current date.
  Write String 1 " "             ; Write a blank space.
  Write String 1 $TIME             ; Write the current time.
  Write String 1 "   "             ; Write a tab.
  Write Line 1 LOG             ; Write the log description.
  Return                 ; Return to the calling subroutine.




; *******************************************************************
; DISPLAY LOG - Displays the log file if any errors occurred.
; *******************************************************************
;
; NOTE: If you do not want the script to display the log file if errors
; occurred, add a semicolon to the left of the "If ERR_COUNT > 0 Then GoSub
; @DISPLAY_LOG" command line near the end of the MAIN subroutine.
;
; Information in the log file is added at the end of it each time the script
; runs. To view the last script session, you will need to go to the bottom of
; the log file after Notepad displays it. Use the Ctrl+End keystrokes or use the
; PageDown key to cycle down to the end.
;
; By default, Notepad will be used to display the log file. If the log file
; becomes too large, you will need to use an alternate text editor such as Write
; or WordPad. If your remote computer's operating system is DOS, you will need
; to use a DOS-based text editor such as the EDIT command. You may also need to
; specify the full path to the EDIT command instead of just it's file name.

@DISPLAY_LOG:                 ; Subroutine used to show log file.
  CDIR2 = "NOTEPAD "                 ; Create beginning of the command.
  StrCat CDIR2 CDIR             ; Add the current working directory.
  StrCat CDIR2 "\LOG.PCA"         ; Add the log file name and end.
  RUN CDIR2                 ; Display log file.
  Return                 ; Return to the MAIN subroutine.




; *******************************************************************
; CHECK FLAG - Loops to pause the script until SCRIPT.BAT finishes.
; *******************************************************************
;
; NOTE 1: If you want to run a program on the remote computer and the script
; needs to pause while this program runs, the below procedure will need to be
; changed slightly. The command "SessOpr Host Send "C:\PCA.FLG" "C:\PCA.FLG""
; will need to be replaced with the commands:
;
;    Find First "C:\PCA.FLG"
;    If $RESULT == 0 GoTo @CHECK_FLAG_FILE
;
; This loops the subroutine if the C:\PCA.FLG file cannot be found on the remote
; computer.

@CHECK_FLAG:                 ; Subroutine used to pause the script.
  LOOP = 0                 ; Reset the value of LOOP to 0.

@CHECK_FLAG_FILE:             ; Subroutine used find flag file.
  GoSub @LOOP                 ; Pause script for five seconds.
  LOOP = LOOP + 1             ; Increment the value of LOOP.
  If LOOP == 24 GoTo @CHECK_FLAG_ERROR  ; If LOOP takes too long, abort.
  If $DCD != 1 GoTo @CHECK_FLAG_LOST ; If lost connection, end loop.
  $ERROR = 0                 ; Reset the value of $ERROR to 0.
  SessOpr Host Send "C:\PCA.FLG" "C:\PCA.FLG"  ; Attempt file transfer.
  If $ERROR == -8 GoTo @CHECK_FLAG_FILE  ; If file not found, loop.
  If $ERROR < 0 GoTo @CHECK_FLAG_OTHER  ; If other error, end loop.
  LOG = "Execution of 'C:\SCRIPT.BAT' on the host was successful."
                     ; Create a log description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  Del "C:\PCA.FLG"             ; Delete the flag file on the remote.
  If $DCD != 1 GoTo @CHECK_FLAG_LOST ; If lost connection, call next host.
  SessOpr Host Run "COMMAND.COM /C DEL PCA.FLG"    ; Delete on the host.
  RES = 0                 ; Set return code to neutral value.
  Return                  ; Return to the RUN_FILE subroutine.

@CHECK_FLAG_ERROR:             ; Subroutine used to time loop out.
  ERR_COUNT = ERR_COUNT + 1          ; Increment how many errors occurred.
  LOG = "Error: execution of 'C:\SCRIPT.BAT' on the host timed out."
                     ; Create a log description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  RES = 0                 ; Set return code to neutral value.
  Return                 ; Return to the RUN_FILE subroutine.

@CHECK_FLAG_LOST:             ; Subroutine used if lost connection.
  GoSub @LOST_CONNECTION         ; Create and save a log description.
  RES = 1                 ; Set return code for failure.
  Return                 ; Return to the RUN_FILE subroutine.

@CHECK_FLAG_OTHER:             ; Subroutine used for generic error.
  LOG2 = "occurred while running 'C:\SCRIPT.BAT' on the host."
                     ; Create a log description.
  GoSub @ERROR                 ; Add the error number.
  RES = 0                 ; Set return code to neutral value.
  Return                 ; Return to the RUN_FILE subroutine.




; *******************************************************************
; LOOP - Pauses script by incrementing an integer.
; *******************************************************************
;
; NOTE: By default, the LOOP subroutine pauses the script for about five
; seconds. This time is determined by the number 50,000. You may need to
; increase or decrease this number depending on the speed of your remote
; computer however.

@LOOP:                     ; Subroutine used to pause the script.
  I = 0                     ; Reset the value of I to 0.

@LOOP_SCRIPT:                 ; Subroutine used loop the script.
  I = I + 1                 ; Increment the value of I.
  If I != 50000 GoTo @LOOP_SCRIPT    ; If not five seconds, loop.
  Return                 ; Return to calling subroutine.




; *******************************************************************
; ERROR - Writes error number to the log file.
; *******************************************************************

@ERROR:                     ; Subroutine used to trap errors.
  ERR_COUNT = ERR_COUNT + 1          ; Increment how many errors occurred.
  LOG = "Error "             ; Create a log description.
  StrCat LOG ERR             ; Add the error number.
  StrCat LOG " occurred "         ; Add " occurred ".
  StrCat LOG LOG2             ; Add the description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  Return                 ; Return to the calling subroutine.




; *******************************************************************
; LOST CONNECTION - Write lost connection information to log file.
; *******************************************************************

@LOST_CONNECTION:             ; Subroutine used to trap lost connections.
  ERR_COUNT = ERR_COUNT + 1          ; Increment how many errors occurred.
  LOG = "Error: lost connection to host '"  ; Create description.
  StrCat LOG HOST             ; Add the host name.
  StrCat LOG "'."             ; End the description.
  GoSub @WRITE_LOG             ; Write the description to the log.
  Return                 ; Return to the calling subroutine.




;    **************************
;    **  TECHNICAL OVERVIEW  **
;    **************************
;
;
;
;
;    TABLE OF CONTENTS FOR TECHNICAL OVERVIEW
;    ****************************************
;
;    Subroutines
;    How to Troubleshoot this Script
;    Checking a Command's Results After it Runs - How to Use $RESULT
;    Checking for Errors When a Script Runs - How to Use $ERROR
;    Checking for Lost Connections - How to Use $DCD
;    How to Use a Network or Cable to Connect to a Host Using a Script
;    How to Convert an Integer to a String Variable
;    How to Schedule a Script Using a Third Party Scheduler
;    How to Program a Script to Schedule Itself
;    How to Run a Script From a Command Line
;    How to Create and Use a Log File
;    How to Use a Data File to Call Multiple Host Computers
;    How to Call a Host Computer
;    How to Transfer Files
;    How to Run a Program
;    How to Pause a Script While a Program Runs
;    Using "Infinite" Loops
;
;
;    SUBROUTINES
;    ***********
;
;    The following briefly describes the subroutines that are found in this
;    script:
;
;    SUBROUTINE NAME        PURPOSE
;    ----------------------------------------------------------------------
;    VARIABLES        Defines variables that will be used.
;
;    MAIN                The primary subroutine of the script which
;                controls other subroutines.
;
;    OPEN_FILES        Creates or opens the log file LOG.PCA, the host
;                data file DATA.PCA, and the sample application
;                SCRIPT.BAT.
;
;    NEXT_HOST          Reads the next host computer to call by reading
;                the DATA.PCA text file.
;
;    CALL_HOST          Calls the next host computer.
;
;    TRANSFER_FILE          Transfers the C:\SCRIPT.BAT file from the remote
;                computer to the host computer's C:\ drive.
;
;    RUN_FILE          Runs the SCRIPT.BAT file on the host computer
;                and branches to the CHECK_FLAG subroutine to
;                pause the script while it runs.
;
;    WRITE_LOG          Writes a text description defined by the calling
;                subroutine to the log file.
;
;    DISPLAY_LOG        If any errors occurred while the script ran,
;                     displays the log file after the script has
;                  finished.
;
;    CHECK_FLAG          Pauses the script while looking for the flag
;                file PCA.FLG on the host computer. This file is
;                created when the SCRIPT.BAT file finishes. When
;                this file is detected by the script, the script
;                then continues where it left off.
;
;    LOOP            Pauses the script by looping an integer. This
;                pauses the script for approximately five
;                seconds.
;
;    ERROR              Writes the error number to the log file.
;
;    LOST_CONNECTION          Writes information about the lost connection to
;                the log file.
;
;
;    HOW TO TROUBLESHOOT THIS SCRIPT
;    *******************************
;
;    This script has been extensively tested before being released for
;    public use. However, other factors could cause issues that would
;    prevent this script from working correctly. Please check the following
;    list to ensure that these are correct on your systems:
;
;    1. Have you modified the script in any way? Often people will change
;       something in the script which would then cause it to not work
;       correctly. This particularly pertains to the file names that the
;       script uses, such as the LOG.PCA or the SCRIPT.BAT. Do you experience
;       the same issue if you run the original SAMPLE.SCR file? If not, then
;       the issue is in your modified version of the script. If so, then you
;       are most likely experiencing some other type of issue.
;
;    2. Did you create the "MODEM" remote control item in the Remote Control
;       section of your pcANYWHERE remote computer? This item is required by
;       the script before it is able to dial your host computer correctly.
;       This process is explained under SETUP AND INSTALLATION at the
;       beginning of this script.
;
;    3. Did you install the script to the pcANYWHERE program directory? This
;       script may not work correctly if installed to an alternate directory.
;       This process is explained under SETUP AND INSTALLATION at the
;       beginning of this script.
;
;    4. Do issues exist between the remote and host computers? Is the speed
;       of the connection slow when connecting manually? Do you receive error
;       messages or lost connections when connecting manually? If so, you
;         will need to resolve these issues before continuing trying to use
;       a script to connect them together.
;
;
;    CHECKING A COMMAND'S RESULTS AFTER IT RUNS - HOW TO USE $RESULT
;    ***************************************************************
;
;    The global variable $RESULT stores the result value of the last script
;    command to run. $RESULT cannot be manually set by the script, such as
;    in "$RESULT = 0", but is only set after a command finishes executing.
;    The value of $RESULT will differ depending on which script command sets
;    it. For more information on what each script command will set the value
;    of $RESULT to, please refer to the appropriate script command in the
;    Creating Scripts book.
;
;    Because $RESULT is set by almost every script command, it is
;    recommended to store the value of $RESULT in a user-defined variable
;    before trying to check it or return a value from a GoSub...Return loop.
;    For example, if you need to check $RESULT by using two consecutive
;    If...Then commands, the first If...Then command will actually set the
;    value of $RESULT itself, giving the second If...Then command an
;    incorrect value because it was checking the previous command.
;
;    This script uses the user defined variable RES to save the success or
;    failure status of called subroutines from the MAIN subroutine. The
;    status could have been passed back to it from the Return command,
;    however as mentioned above, consecutive If...Then statements will change
;    the value of $RESULT. Because of this, the status from a called
;    subroutine is saved to RES, which allows the script to control exactly
;    what values are saved and checked for. For example:
;
;        SessOpr Remote Send "C:\DATA\*.DBF" "C:\NEW\"
;        RES = $RESULT
;        If RES <= 4 GoSub @ERROR
;        If RES > 4 Then @OK
;
;    Please note that the above example is not meant to be run by itself, but
;    has been provided here as an example on how to set and check $RESULT.
;    The first line transfers all *.DBF files from the remote's C:\DATA\
;    directory to the host's C:\NEW\ directory. The second line assigns the
;    value of $RESULT to the variable RES. The third line checks to see if at
;    least five of the *.DBF files were sent successfully (four or less); if
;    not, then the script will branch off to the ERROR subroutine.  The last
;    line double checks to see if four or more files were sent, if so then
;    the script goes to the OK subroutine.
;
;
;    CHECKING FOR ERRORS WHEN A SCRIPT RUNS - HOW TO USE $ERROR
;    **********************************************************
;
;    The global variable $ERROR is similar to the $RESULT global variable,
;    however it is set to the error condition of the last script command to
;    run, whereas $RESULT is set to the result value of the last script
;    command to run. If the value of $ERROR is a negative number, then the
;    script encountered an error. If it is zero, then no errors occurred.
;    It is important to check $ERROR to ensure that script commands worked
;    correctly.
;
;    Unlike $RESULT which is only set by the last script command, the value
;    of $ERROR can be set manually by the script. It is recommended to set
;    $ERROR to zero before running a command and checking it's value. If this
;    is not done, then $ERROR will retain the last error value that set it;
;    if a command runs and no errors occur, this does not reset $ERROR to
;    zero. After the script command runs, check to see if $ERROR is less than
;    zero; if so, than an error occurred. For example:
;
;        $ERROR = 0
;        SessOpr Remote Send "C:\AUTOEXEC.BAT" "C:\NEW.BAT"
;        If $ERROR < 0 GoSub @ERROR
;
;    Please note that the above example is not meant to be run by itself,
;    but has been provided here as an example on how to set and check $ERROR.
;    The first line resets the value of $ERROR to zero. The second line
;    transfers the AUTOEXEC.BAT file to the host's new file NEW.BAT. The
;    third line checks to see if any error occurred; if so, then the script
;    will branch off to the ERROR subroutine.
;
;    This script frequently checks $ERROR. If an error occurs, either a local
;    subroutine is called, or the ERROR subroutine is called. These
;    subroutines write the status of the error to the log file then continue
;    where the script left off.
;
;
;    CHECKING FOR LOST CONNECTIONS - HOW TO USE $DCD
;    ***********************************************
;
;    The global variable $DCD (Data Carrier Detect) is used to check the
;    status of the connection between the remote and host computers when
;    modems are used. If you want to connect using a network or direct
;    connection cable, please refer to the next section called "How to
;    Use a Network or Cable to Connect to a Host Using a Script". It is
;    important to check $DCD to ensure that a valid connection exists.
;
;    If the value of $DCD is a one, then the computers are connected. If
;    it is not equal to one (not necessarily zero), then the computers did
;    not connect or the connection was dropped (lost connection) while in
;    a session. Like $RESULT, $DCD cannot be set manually by the script but
;    is set according to the connection status of the modems.
;
;    Important Note for Lost Connections: The value of $DCD is used to check
;    to see if the remote computer is still connected to the host computer by
;    modems. However, the value of $DCD may be unreliable because if a lost
;    connection occurs, the remote computer's modem may take a few moments to
;    detect and report this. If this is the case, the pcANYWHERE Scripting
;    Language will be unable to detect the lost connection as well. Different
;    timing issues on the remote computer that could play a part in this
;    delay are: the type of modem it uses, the TAPI driver used or it's
;    initialization string, the speed of the remote computer, and the phone
;    lines involved. Because of these facts, you may or may not encounter
;    issues while checking for a lost connection, depending on how the lost
;    connection occurred. For example, if you drop the connection on the host
;    computer by unplugging it's phone line, the remote computer will usually
;    not be able to detect this immediately. However, a lost connection
;    which occurred due to phone line noise, i.e., a real lost connection not
;    a simulated one, should be usually detected and accounted for.
;
;    It is important to check the value of $DCD before running the following
;    commands: SessOpr Remote Send and SessOpr Host Send, SessOpr Remote Run
;    and SessOpr Host Run, and Session End. Also, $DCD should be checked
;    after a Session Dial command to ensure that a connection was established
;    correctly. These five commands can only be run from a session started by
;    the Session Dial command. If they are used and a session is not active,
;    then several issues may occur, such as: an "AWREM32" error message, a
;    "Fatal Exception" error message, an "Invalid Script File" error message,
;    the script hangs, a black Terminal window appears, or script error
;    messages -23 or -26 appear. Therefore, the value of $DCD needs to be a 1
;    before running one of these commands; $DCD should be used to check this
;    before running them. The following is an example on how to check the
;    value of $DCD before running one of these commands:
;
;        If $DCD != 1 GoTo @LOST_CONNECTION
;        SessOpr Host Send "C:\NEW\*.DOC" "C:\DOCS\"
;
;    Please note that the above example is not meant to be run by itself, but
;    has been provided here as an example on how to set and check $DCD. Also,
;    $ERROR checking was left out; normally the script should set $ERROR to
;    zero before running the command, and then check it's value after the
;    command finishes running. (As outlined in the prior example for $ERROR.)
;    The first line checks $DCD to see if it is not equal to one; if it is
;    not, then a lost connection occurred and the script will then branch off
;    to the LOST_CONNECTION subroutine. The second line transfers the all
;    *.DOC files in the host computer's C:\NEW\ directory to the remote
;    computer's C:\DOCS\ directory.
;
;    This script frequently checks $DCD. If a lost connection is found,
;    either a local subroutine is called, or the LOST_CONNECTION subroutine
;    is called. These subroutines write the status of the lost connection
;    to the log file then continue where the script left off.
;
;
;    HOW TO USE A NETWORK OR CABLE TO CONNECT TO A HOST USING A SCRIPT
;    *****************************************************************
;
;    The global variable $DCD (Data Carrier Detect) is used to check for the
;    connection status of modem connections. However, since there is no
;    $DCD value for a network or cable connection, this variable cannot be
;    used to check for these types of connections.
;
;    If you want to use this sample script to connect to a network or cable
;    host, then you will need to remove any line that checks for the value
;    of $DCD. Since $DCD will equal a 0, indicating that no modem connection
;    is present, even though the remote connected correctly to a network or
;    cable host, it will immediately detect it as a lost connection and
;    act accordingly as programmed into this script.
;
;    There is no good way to detect whether or not a remote is connected to
;    a network or direct connect host, however. A direct connect host has
;    no method to determine if it is connected, other than trying to transfer
;    a test file to it to see if the connection is valid. This may cause the
;    script or remote to hang, since the SessOpr Remote Send command should
;    only be used in a valid remote control session. Therefore, this is not
;    a good work around, but is the only one that is known.
;
;    For a network connection, a better work around is to have the script run
;    a batch file to copy a file to a network drive, and then use the IF EXIST
;    batch file command to see if the file was successfully sent. If so, the
;    batch file could create a dummy flag file that the script waits to find.
;    If the script finds this file, then it can assume that the network
;    connection has been successful and then continue the script.
;
;
;    HOW TO CONVERT AN INTEGER TO A STRING VARIABLE
;    **********************************************
;
;    Variable conversion is a straightforward process in the pcANYWHERE
;    Scripting Language. Just assign the string variable to the integer
;    variable, and the conversion is complete.
;
;    It may be more difficult to convert a string to an integer however.
;    The string cannot contain any letters or special characters, otherwise
;    the conversion cannot take place. The following are some examples of
;    performing both types of conversions:
;
;        String X[5]
;        Integer Y
;        Y = 5
;        X = Y        ; Assigns the value of Y, 5, to the string X.
;        X = "6"
;        Y = X        ; Assigns the value of X, 6, to the integer Y.
;
;
;    HOW TO SCHEDULE A SCRIPT USING A THIRD PARTY SCHEDULER
;    ******************************************************
;
;    The recommended method to schedule a script to run at a later date
;    and time is to use a third party scheduler, such as the one
;    supplied with Norton AntiVirus. The scheduler would run the script by
;    using the pcANYWHERE command line syntax. Please refer to the section
;    "How to Run a Script from a Command Line" for more information.
;
;
;    HOW TO PROGRAM A SCRIPT TO SCHEDULE ITSELF
;    ******************************************
;
;    If you do not have a third party scheduler, then you can use either the
;    Wait Until or Session Dial commands to "schedule" your script for you.
;    Both of these commands can use optional date and time parameters to
;    suspend script operations until the date and time that you specify. For
;    example:
;
;        Wait Until 2359 19991221
;
;    The Wait Until command will pause the script from continuing until
;    11:59 PM on December 21st, 1999. (This will only work if the remote
;    pcANYWHERE is pcAnywhere 9.0 or pcANYWHERE32 8.0. All other versions
;       only use the last two digits of the year instead of four digits.) Both
;    the Wait Until and Session Dial commands use a 24-hour time format, so
;    11:59 PM becomes 2359.
;
;    You can run the script any time before the target time, such as when you
;    go home from work for the day. The script will respond with a black
;    terminal window, which is what the script looks like while it is
;    waiting to begin execution. (This window can be minimized if the
;    remote computer is running Windows so that you can continue working on
;    the remote computer.) Once the time is reached, the script then begins
;    it's normal execution.
;
;    A disabled Wait Until command is available for you to use at the
;    beginning of the MAIN subroutine.
;
;    Additional information about using the Wait command can be found in the
;    NOTE 1 section of the MAIN subroutine.
;
;
;    HOW TO RUN A SCRIPT FROM A COMMAND LINE
;    ***************************************
;
;    Each version of pcANYWHERE requires a different command line:
;
;    pcAnywhere 9.0 and pcANYWHERE32 8.0: AWREM32.EXE <script name>.SCR
;    C:\PROGRAM FILES\SYMANTEC\PCANYWHERE\AWREM32.EXE C:\SCRIPTS\SAMPLE.SCR
;
;    pcANYWHERE 2.0:    WINAW.EXE -O=R -M=S -N=<script name>.SCR
;    C:\WINAW\WINAW.EXE -O:R -M:S -N:C:\SCRIPTS\SAMPLE.SCR
;
;    pcANYWHERE 5.0:    AW.EXE /O:S /M:S /N:<script name>.SCR
;    C:\AW\AW.EXE /O:S /M:S /N:C:\SCRIPTS\SAMPLE.SCR
;
;    Please note that the above examples must include full path names to the
;    executable file and the script file. Also, if the path name is longer
;    than eight characters or has spaces, you may need to enclose the path
;    name in quotation marks:
;
;    "C:\PROGRAM FILES\SYMANTEC\PCANYWHERE\AWREM32.EXE" C:\SCRIPTS\SAMPLE.SCR
;
;
;    HOW TO CREATE AND USE A LOG FILE
;    ********************************
;
;    A log file can be created that will record the success or failure of
;    specific procedures when the script runs. The values of $ERROR or $DCD
;    can be checked by other subroutines in the script, and when an error
;    occurs, logged into the log file.
;
;    This script creates a log file called LOG.PCA. Each entry in the log
;    file includes the date and time that they were made, which is performed
;    by the WRITE_LOG subroutine.
;
;    The log file is stored in the pcANYWHERE program directory. To view this
;    log file, use any text editor or word processor. The last script session
;    to run is added to the bottom of the log file information.
;
;    Please refer to the OPEN_FILES and WRITE_LOG subroutines to learn how to
;    create and write to a log file respectively.
;
;    Please note that a log file's scope is to save success or failure
;    information on procedures that the script performs. Events that occur
;    outside of the pcANYWHERE Scripting Language, such as the remote
;    computer hanging while a script runs, it beyond the script's ability to
;    detect and account for.
;
;    Troubleshooting note: if the script hangs or is terminated while it is
;    running, the log file may remain open and you may not be able to run the
;    script again without getting an error, or be able to view the log file.
;    If so, close pcANYWHERE and then load pcANYWHERE again. If you still
;    cannot run the script or view the log file, you will need to reboot the
;    remote computer.
;
;    The following is an example of a log file generated by this script:
;
; **** pcANYWHERE Script Log File ****
;
; 12/22/97 13:47:45   Starting script.
; 12/22/97 13:47:45   Calling host 'MODEM'.
; 12/22/97 13:48:17   Successfully connected to host 'MODEM'.
; 12/22/97 13:48:20   Transfer of 'C:\SCRIPT.BAT' was successful.
; 12/22/97 13:48:23   Executing 'C:\SCRIPT.BAT' on the host...
; 12/22/97 13:48:26   Execution of 'C:\SCRIPT.BAT' on the host was successful.
; 12/22/97 13:48:26   Disconnecting from host 'MODEM'.
; 12/22/97 13:48:33   Calling host 'MODEM'.
; 12/22/97 13:49:04   Successfully connected to host 'MODEM'.
; 12/22/97 13:49:06   Transfer of 'C:\SCRIPT.BAT' was successful.
; 12/22/97 13:49:08   Executing 'C:\SCRIPT.BAT' on the host...
; 12/22/97 13:49:12   Execution of 'C:\SCRIPT.BAT' on the host was successful.
; 12/22/97 13:49:12   Disconnecting from host 'MODEM'.
; 12/22/97 13:49:19   Script completed with 0 error(s).
;
;
;    HOW TO USE A DATA FILE TO CALL MULTIPLE HOST COMPUTERS
;    ******************************************************
;
;    A script can use a text data file to call multiple host computers. This
;    can save you from having to create repetitive blocks of code and allow
;    you to use the same set of code for each host computer.
;
;    This script creates it's own data file, the DATA.PCA file. However, the
;    remote user would normally create this on their own in the pcANYWHERE
;    program directory by using a text editor or word processor. This file
;    must be saved as a standard text file.
;
;    Each line in the data file corresponds to a remote control item of the
;    same name. Each of the remote control items in pcANYWHERE requires the
;    host computer's phone number, and any logon name or password that may
;    also be required. It is not possible to use a list of phone numbers
;    instead of a list of host names: the pcANYWHERE Scripting Language
;    cannot call a host computer using a phone number but requires a remote
;    control item for each host computer that has it's phone number specified
;    in it's properties.
;
;    The DATA.PCA file that this script creates will call the same host
;    MODEM twice, and will look like this:
;
;        MODEM
;        MODEM
;
;    If certain hosts failed to connect or failed in their operations while
;    connected to the remote, a specialized DATA.PCA file can be made with
;    only the names of the ones to be recalled after the main script has run.
;    This is done manually by the remote user. Just create a new DATA.PCA
;    file, renaming the old one temporarily, with only the host names to call
;    back. After these complete you can then delete the temporary DATA.PCA
;    file and rename the original.
;
;    Troubleshooting note: if you misspell a host computer name in your data
;    file, or the host computer name does not exist in the remote control
;    section of the remote computer's pcANYWHERE, the error message "File
;    Not Found" will appear and the script may end abruptly. If this occurs,
;    double check that you have spelled the host computer names correctly and
;    that remote control items exist.
;
;    For information on how to read the data file, please refer to the
;    NEXT_HOST subroutine. This subroutine reads the next host to call from
;    the data file and assign's it's value to the user-defined HOST variable.
;
;
;    HOW TO CALL A HOST COMPUTER
;    ***************************
;
;    The only command that can be used to call a host computer is the Session
;    Dial command. This command calls the host computer using a pcANYWHERE
;    remote control item that has the host computer's phone number, and any
;    logon or password information already configured in it's properties.
;
;    This script uses the subroutine CALL_HOST to call the host computers.
;    This subroutine also configures other options for the connection, such
;    as the retry value if the connection could not be established. Please
;    refer to the CALL_HOST subroutine for more information.
;
;    Several important notes on calling a host computer with a script are
;    listed below:
;
;    * When connected to a host computer, only specific script commands are
;      supported. These include the SessOpr Remote Send, SessOpr Remote Run,
;      SessOpr Host Send, SessOpr Host Run and Session End. While other
;      commands can be used, they may introduce issues. Also, some script
;      commands are designed to be used with online services only, such as
;      the Send File and Receive File commands. These type of commands
;      should not be used while connected to a host computer.
;
;    * The session is non-interactive. If the host computer is in use when
;      the script calls into it, issues may occur. If you attempt to use the
;      host computer remotely while the script runs, issues may occur.
;
;    * A script cannot interact with a program, nor send text or keystrokes
;      to a program. This includes sending keystrokes to data fields, such as
;      logon prompts for a network or email program. This is because a script
;      cannot set focus on a window or a field so that it can send the text
;      to it.
;
;    * If a connection to a host cannot be established, pcANYWHERE will take
;      over and pause until returning control to the script. For example,
;      pcANYWHERE will first display "Waiting for Connection" while it is
;      trying to call the host computer. After it fails, it will display
;      "Timeout Waiting for Connection". Both of these windows will stay on
;      the screen for one minute each. Then control will return to the
;      script, which is set to wait an additional minute before calling the
;      same host back, which it will do three times.
;
;
;    HOW TO TRANSFER FILES
;    *********************
;
;    Files can be transferred between the remote and host computers by using
;    a script. This is performed by the SessOpr Remote Send and the SessOpr
;    Host Send commands respectively. (The Send File and Receive File
;    commands are only used when connected to an online service.)
;
;    This script uses the TRANSFER_FILE subroutine to transfer a single file
;    from the remote computer to the host computer. In addition to this, the
;    source file name is defined by the user-defined SOURCE variable. By
;    using a variable, a more robust method for logging the result of
;    multiple file transfers can be used instead of creating specific log
;    entries. (This script does not use this feature since it only transfers
;    one file. However if you have multiple file transfers that take place,
;    extra code would not need to be created to record the file transfer's
;    results to the log file with the file name that was transferred.)
;
;    Please refer to the FILE_TRANSFER subroutine for more information. Also,
;    for more information on how to perform file transfers, please refer to
;    the Symantec Knowledge Base article called "How to Transfer Files to or
;    From a Host Computer".
;
;    If you are using pcAnywhere 9.0 or pcANYWHERE32 8.0 you will need to add
;     a GoSub @LOOP after each file transfer routine.  File transfers will
;    proceed best if you use a separate routine for each file transfer such
;    as:
;
;
;    @TRANSFER_FILE:
;      SOURCE = "<path><file name>"
;      If $DCD != 1 GoTo @TRANSFER_FILE_LOST
;      $ERROR = 0
;      SessOpr Remote Send SOURCE "<path><file name>"
;      ERR = $ERROR
;      If $ERROR < 0 GoTo @TRANSFER_FILE_ERROR
;      LOG = "Transfer of '"
;      StrCat LOG SOURCE
;      LOG2 = "' was successful."
;      StrCat LOG LOG2
;      GoSub @WRITE_LOG
;      RES = 0
;      GoSub @LOOP
;
;    @TRANSFER_FILE1:
;      SOURCE = "<path><file name>"
;      If $DCD != 1 GoTo @TRANSFER_FILE_LOST
;      $ERROR = 0
;      SessOpr Remote Send SOURCE "<path><file name>"
;      ERR = $ERROR
;      If $ERROR < 0 GoTo @TRANSFER_FILE_ERROR
;      LOG = "Transfer of '"
;      StrCat LOG SOURCE
;      LOG2 = "' was successful."
;      StrCat LOG LOG2
;      GoSub @WRITE_LOG
;      RES = 0
;      GoSub @LOOP
;
;      Return            ;Return to main routine at the end of the last
;                    ;file transfer routine
;
;
;    Please note that the above example is not meant to be run by itself, but
;    has been provided here as an example on how to transfer multiple files with
;     a script.
;
;
;    HOW TO RUN A PROGRAM
;    ********************
;
;    A program can be run on the remote or host computer while in a session.
;    However, if the program is run on a Windows-based computer, the script
;    cannot tell when it has finished running. If the script needs to tell
;    when the program finishes, a special method of detecting this may need
;    to be used. Please refer to the section below called "How to Pause a
;    Script While a Program Runs" for more information.
;
;    A script can use three different commands to run a program:
;
;    * SessOpr Remote Run, to run a program on the remote computer while in a
;      session.
;
;    * SessOpr Host Run, to run a program on the host computer while in a
;      session.
;
;    * Run, to run a program on the remote computer while not in a session.
;
;    All three of these function basically the same, with the exception that
;    the two SessOpr commands cannot be run outside of a session.
;
;    It is recommended to specify the full path name of the program to run.
;    Also, if it is DOS-based, you may need to specify the command
;    interpreter as well. For example, the following command runs the
;    MS-DOS EDIT command:
;
;        Run "COMMAND.COM /C C:\DOS\EDIT.COM"
;
;    The "COMMAND.COM /C" is the command interpreter. The "/C" switch for the
;    command interpreter tells the window to close after it has finished (if
;    the command was run from within Windows). Otherwise, the DOS window will
;    stay open and the user will need to close it manually.
;
;    Windows NT must use the START command to run DOS programs, otherwise
;    control will not be returned. This is the same as using the "/C", but is
;    required for Windows NT.
;
;
;    HOW TO PAUSE A SCRIPT WHILE A PROGRAM RUNS
;    ******************************************
;
;    If a script runs a program on a Windows-based computer, it cannot detect
;    when the program finishes. If the script is required to pause while the
;    program runs, this can be an issue. The reason a script cannot detect
;    when a program finishes is because Windows is a multitasking operating
;    system. The script will run the program, but as a separate task in a
;    window. The script has no control over this window and cannot detect
;    when it closes.
;
;    Several methods are available which allow a script to pause while a
;    program runs, however most are not reliable. The Wait command can pause
;    a script, however it is not recommended to use this command while a
;    session is active. If a lost connection occurs while the Wait command is
;    being used, the remote computer may hang or the script may encounter
;    errors. The SessOpr Remote Run and SessOpr Host Run commands using the
;    optional Wait parameter only work if the application is run on a DOS-
;    based computer. (Not a DOS window run from within Windows.) To correctly
;    pause a script while a program runs, a special procedure will need to be
;    used.
;
;    One procedure of pausing a script is to create a loop that uses computer
;    cycles, such as incrementing an integer variable. This script uses this
;    procedure (the LOOP subroutine) for creating short pauses. However, this
;    process is not accurate enough to be used if the script needs to know
;    exactly when a program is finished.
;
;    The best procedure that can pause a script while a program runs is
;    described below, which uses a flag file to detect when the program has
;    finished running:
;
;    Step 1. The script runs the program.
;
;    Step 2. The script goes into a loop where it tries to detect the
;        existence of a flag file which is created by the program when
;        it finishes. If it cannot find the file, then it continues to
;        search until it is found or a set number of searches have been
;        completed.
;
;    Step 3. After the script detects the flag file, it then continues where
;         it left off.
;
;    This script uses the CHECK_FLAG subroutine to perform this procedure.
;    The following is an excerpt from the CHECK_FLAG subroutine:
;
; @CHECK_FLAG:                 ; Subroutine used to pause the script.
;   LOOP = 0                 ; Reset the value of LOOP to 0.
;
; @CHECK_FLAG_FILE:             ; Subroutine used find flag file.
;   GoSub @LOOP                 ; Pause script for five seconds.
;   LOOP = LOOP + 1             ; Increment the value of LOOP.
;   If LOOP == 24 GoTo @CHECK_FLAG_ERROR  ; If LOOP takes too long, abort.
;   If $DCD != 1 GoTo @CHECK_FLAG_LOST  ; If lost connection, end loop.
;   $ERROR = 0                 ; Reset the value of $ERROR to 0.
;   SessOpr Host Send "C:\PCA.FLG" "C:\PCA.FLG"  ; Attempt file transfer.
;   If $ERROR == -8 GoTo @CHECK_FLAG_FILE  ; If file not found, loop.
;   If $ERROR < 0 GoTo @CHECK_FLAG_OTHER  ; If other error, end loop.
;
;    The @CHECK_FLAG subroutine has a single line. This resets the value of
;    the user-defined LOOP variable to a zero. The LOOP variable is
;    discussed in more detail below.
;
;    The @CHECK_FLAG_FILE subroutine is where the actual check for the
;    existence of the flag file occurs at. The command lines for this
;    excerpt are described below:
;
;    1. GoSub @LOOP. This pauses the script for approximately five seconds
;       by branching to the LOOP subroutine. This is important to use
;       because otherwise the script will loop too quickly while checking
;       for the flag file and could result in memory issues on the remote
;       computer.
;
;    2. LOOP = LOOP + 1. This increments the LOOP variable by one. When the
;       script loops too many times, the CHECK_FLAG subroutine will
;       automatically timeout, as described below.
;
;    3. If LOOP == 24 GoTo @CHECK_FLAG_ERROR. If the CHECK_FLAG_FILE
;       subroutine has looped twenty-four times, about two minutes, abort
;       the subroutine because an error may have occurred that is preventing
;       the flag file from being detected. If this check does not occur, the
;       script may hang and go into an infinite loop. By changing the number
;       24 to a larger or smaller number, the script will wait a longer or
;       shorter amount of time. This is based on a five second pause when the
;       script branches to the LOOP subroutine times the number that it
;       checks here; 24 times 5 seconds is two minutes.
;
;    4. The connection status of the modems is checked. If the remote
;       computer is no longer connected to the host computer, the subroutine
;       is aborted.
;
;    5. The value of $ERROR is reset to zero before trying to detect the flag
;       file by file transferring it to the remote computer.
;
;    6. The script attempts to transfer the flag file PCA.FLG from the host
;       computer to the remote computer.
;
;    7. If the file was not found (error -8), then the subroutine loops back
;       to the beginning and continues until it is able to transfer the file
;       or the LOOP variable times out.
;
;    8. If any other error occurred, the script aborts.
;
;    This script uses the flag file PCA.FLG. Since this file will at some
;    point exist on both the remote and host computers, it needs to be
;    deleted before the CHECK_FLAG subroutine runs. Otherwise, the
;    CHECK_FLAG subroutine will detect it on the host computer, and assume
;    that the program is finished running. The RUN_FILE subroutine is used
;    to delete the PCA.FLG files on both the remote and host computers
;    before it runs the sample application SCRIPT.BAT file on the host
;    computer, then it branches to the CHECK_FLAG subroutine until the
;    real PCA.FLG file has been detected.
;
;    The SCRIPT.BAT file creates the PCA.FLG file when it finishes. All that
;    this file does is the following:
;
;        @ECHO OFF
;        C:
;        CD \
;        DIR /A
;        DIR >PCA.FLG
;
;    The first line sets the echo off for output from any following commands.
;    The second line changes to the C: drive. The third line changes to the
;    root drive of the C: drive. The fourth line then displays the directory
;    of the C: root directory and all files found in it. After it finishes,
;    it creates the dummy file PCA.FLG by piping the contents of the
;    directory to the file name by using a DIR command.
;
;    A batch file only needs the following three lines of code to create the
;    flag file:
;
;        C:
;        CD \
;        DIR >PCA.FLG
;
;    The CHECK_FLAG subroutine requires a batch file to be used so that it
;    can then create the flag file after it has finished with it's normal
;    operations. However, if you have the ability to create a Visual BASIC
;    or other executable application, it can also be used so long as when it
;    finishes, it creates the flag file. However, it is up to you to create
;    your own batch file or executable application.
;
;
;    USING "INFINITE" LOOPS
;    **********************
;
;    Using a subroutine that loops an "infinite" amount of times (over and
;    over again), or loops so many times that it takes a long period of time
;    to complete, is not usually recommended. Such infinite loops are very
;    likely to cause issues on the remote computer, such as causing the
;    script to hang, or cause an Unexpected program error message.
;
;    If you need a subroutine to perform an infinite loop, there are two
;    things which you can do to minimize how many issues may occur. This
;    includes using a check variable that stops the loop if it's value
;    is exceeded, and using a sub-loop to pause the looping for a short
;    period of time to allow the remote to process other computer cycles.
;
;    The CHECK_FLAG subroutine in this script uses the LOOP variable as
;    a check variable. Each time the subroutine loops, the check variable
;    is incremented by one. Once this variable is 24 or more, the script
;    then assumes an error has occurred and aborts the loop.
;
;    The CHECK_FLAG subroutine also uses a sub-loop to pause it from
;    continually looping without delay. At the beginning of the subroutine,
;    the LOOP subroutine is called. This subroutine also performs loops,
;    but does so very quickly by incrementing a variable 40,000 times to
;    simulate approximately a five second delay. After this loop finishes,
;    control returns to the CHECK_FLAG subroutine.