PCMania 13

home *** CD-ROM | disk | FTP | other *** search

/ PCMania 13 / Pcmania_Ep2_13_CD-01.iso / anywhere / DEFAULT / sample.scraw < prev

Wrap

Text File | 2000-10-10 | 67.1 KB | 1,466 lines

; ******************************************************************* ; * * ; * pcANYWHERE sample script "SAMPLE.SCRAW" * ; * 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.TXT, the host data file HOSTS.TXT, ; and the sample application SCRIPT.BAT. ; ; 2. Read the next host computer's name to call from the DATA.TXT file. ; ; 3. Call the next host computer using a modem as read from the DATA.TXT ; 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.TXT and DATA.TXT files. If any errors ; occurred while the script ran, the LOG.TXT 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. ; * pcANYWHERE 2.0 for Windows 3.1 and Windows 95. ; * pcANYWHERE 5.0 for DOS. ; * Scripts running between pcAnywhere 9.0 to ; pcANYWHERE 5.0 are NOT 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 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 ; http://service1.symantec.com/SUPPORT/pca.nsf/docid/199795132936 ; ; pcANYWHERE Scripting Language Technical Documents ; http://service1.symantec.com/SUPPORT/pca.nsf/docid/19971014101427 ; ; How to Write a Script to Connect to a Host Computer ; http://service1.symantec.com/SUPPORT/pca.nsf/docid/19971027103518 ; ; How to Write a Script to Connect to an Online Service ; http://service1.symantec.com/SUPPORT/pca.nsf/docid/19971020125713 ; ; How to Troubleshoot a Script ; http://service1.symantec.com/SUPPORT/pca.nsf/docid/199791784013 ; ; How to Transfer Files to or From an Online Service Using a Script ; http://service1.symantec.com/SUPPORT/pca.nsf/docid/19978129140 ; ; Additionally, pcAnywhere 9.0 has known documented issues when performing ; file transfers with the Scripting Language. This unfortunately limits ; its effectiveness, as outlined here: ; ; How to Transfer Files to or From a Host Computer Using a Script ; http://service1.symantec.com/SUPPORT/pca.nsf/docid/1997625141045 ; ; Updates to this script can be found on the Symantec web site, at: ; ; pcANYWHERE Files and Updates ; http://www.symantec.com/techsupp/pca/files_pca.html ; ; 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: (541) 465-8430 ; ******************************************************************* ; 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. ; ; 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.TXT. 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.TXT 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.TXT" ; Try to find the LOG.TXT file. If $RESULT == 1 GoTo @OPEN_FILES_LOG_DATA_SCRIPT ; If found, open log file. Create 1 ".\LOG.TXT" "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.TXT" "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.TXT" "W" ; Create the HOSTS.TXT 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.TXT file. Open 2 ".\DATA.TXT" "R" ; Open DATA.TXT 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.TXT 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.TXT. LOG2 = "while accessing the DATA.TXT 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:\" ; Transfer file. ; This line is for pcAnywhere 9.0 only. For pcANYWHERE 2.0 or 5.0, change ; the destination name to be "C:\SCRIPT.BAT", not "C:\" 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 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 @LOOP ; This is used for pcAnywhere 9.0. GoSub @LOOP ; Wait another 5 seconds. GoSub @LOOP ; Wait another 5 seconds. GoSub @LOOP ; Wait another 5 seconds (total of 20). ; If the above multiple looping fails, an "Invalid Script File" error will ; occur if pcAnywhere 9.0 is used, since the intended file to tranfer ; apparently does not yet exist. If so, try adding more "GoSub @LOOP" lines ; until this error no longer occurs. ; GoSub @CHECK_FLAG ; Pause script while SCRIPT.BAT runs. ; Use this line only for pcANYWHERE 2.0 ; or 5.0, not for pcAnywhere 9.0. 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.TXT" ; 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. ; ; Note that this subroutine is not actually used by this script any longer. ; pcAnywhere 9.0 will cause an error "Invalid Script File" if this subroutine ; is used. This is because if the intended file to be transferred does not ; exist, and issue in version 9.0 will cause this error, thereby hanging the ; script. The work around is to use the Loop subroutine instead, creating ; a set delay, and assuming that when it finishes, the intended file to ; be transferred then exists. More information about this issue can be found ; here: ; ; Error: "Invalid Script File" when Script Runs ; http://service1.symantec.com/SUPPORT/pca.nsf/docid/199812362852 ; ; Only pcANYWHERE 2.0 or 5.0 should use this subroutine, if the LOOP subroutine ; cannot be used in its place. @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. ; ; This subroutine is now used to pause the script, instead of the CHECK_FLAG ; subroutine. Please refer to that subroutine for information on this. @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.TXT, the host ; data file DATA.TXT, and the sample application ; SCRIPT.BAT. ; ; NEXT_HOST Reads the next host computer to call by reading ; the DATA.TXT 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. This ; subroutine is no longer used, in lieu of the ; LOOP subroutine. ; ; 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.TXT or the SCRIPT.BAT. Do you experience ; the same issue if you run the original SAMPLE.SCRAW 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 ; Converts Y's value of decimal 5 to string "5" ; X = "6" ; Y = X ; Converts X's value of string "6" to decimal 6 ; ; ; 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. 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 Until 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: AWREM32.EXE <script name>.SCRAW ; C:\PROGRAM FILES\SYMANTEC\PCANYWHERE\AWREM32.EXE C:\SCRIPTS\SAMPLE.SCRAW ; ; pcANYWHERE 2.0: WINAW.EXE -O=R -M=S -N=<script name>.SCRAW ; C:\WINAW\WINAW.EXE -O:R -M:S -N:C:\SCRIPTS\SAMPLE.SCRAW ; ; pcANYWHERE 5.0: AW.EXE /O:S /M:S /N:<script name>.SCRAW ; C:\AW\AW.EXE /O:S /M:S /N:C:\SCRIPTS\SAMPLE.SCRAW ; ; 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.SCRAW ; ; ; 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.TXT. 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.TXT 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.TXT 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.TXT 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.TXT ; file, renaming the old one temporarily, with only the host names to call ; back. After these complete you can then delete the temporary DATA.TXT ; 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 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.