PROCOMM VERSION 2.4 EDITED OPERATING MANUAL David C. Hart September 26, 1986 NOTE: This file is not intended to replace the operating manual for Procomm Version 2.4. Rather, it partially replaces what is apparently a bad download in circulation. The only section contained herein is that dealing with Command Files as it is my opinion that the 2.3 manual will be sufficient for most other purposes. This file is provided as a service to BBS users and is not intended to infringe upon the rights of the authors of Procomm. 7. C O M M A N D F I L E S Command files are text files you create that contain ProComm commands. You can use command files to perform automatic logons, perform unattended file transfers and many other tasks. You can even link command files to the entries in your dialing directory so that the entire dialing and logon procedure is automated. You can create a command file using virtually any word processor which saves in straight ASCII format; if your word processor normally makes use of special or extended ASCII characters, then you should use its "non-document" mode. A command file may have any valid filename; however, ProComm looks for files with an extension of .CMD when it lists available command files. Command files can be executed from within ProComm or as a command line option when you first invoke the program. If you specify them on the command line, using the "/F" option, they will be executed immediately upon program startup. Execute them from inside the program by pressing Alt-F5. ProComm first searches the current directory for files with the .CMD extension. If any are found, their names are displayed in the window. If none are found, ProComm will look in the directory pointed to by the ProComm environment variable. Again, the names of any files found are displayed in the window. If no files are found in either directory, the message "NO FILES" will be displayed. To execute a command file you may either type the filename or choose from the scrolling window display of available .CMD files. If you type the filename, you may omit the .CMD extension. To choose from the scrolling window, position the highlight on the name of the file you wish to execute and press . PgUp and PgDn will scroll the window one page in either direction. The arrow keys will scroll the window one entry in either direction. Pressing the Home key will position the list at the first page of available command files; pressing End will position it at the last. If you don't see the highlighted entry, use the Alt-Z command to change the color being used for highlighting so that it is different than that being used for regular foreground display. The command file Procomm Version 2.4 Summary of Command File Commands Page 2 window uses the colors displayed in Alt-Z for the file transfer window. Once you begin to enter a command file name at the prompt you may still scroll the window, but you may not select a file for execution from the scrolling display. Abort a command file by pressing during its execution. The command file will abort when the current command has completed (which might take a few seconds). In some cases, such as while dialing or performing a file transfer, two 's are needed: one to abort the task in progress and a second to abort the command file. There is a special command file named PROFILE.CMD which ProComm looks for in the default directory first, then in the directory pointed to by the ProComm environment variable (see Section 1). If PROFILE.CMD is found, it will be executed immediately upon program startup, before any other command file specified as a "/F" command line option. You can use the profile to do such custom setup work as changing to a special directory, turning off the sound, changing line settings, or overriding the default modem initialization string. Command File Syntax Command file commands begin with special command words, listed below. Commands may be entered in either upper- or lower-case. When processing commands ProComm looks only at the first 4 characters. Thus all the following commands are treated the same: TRANSMIT = trans = Tran = TRANSM Each command must appear on a separate line. IF NOT CONNECTED ; this is correct MESSAGE "sorry!" ; ENDIF ; IF NOT CONNECTED MESSAGE "sorry!" ; this is incorrect ENDIF ; Many commands have one or more additional arguments; if the argument is listed in brackets ([]) it is optional, otherwise it is required. Arguments listed within quotation marks (" ") should include the quotation marks; thus the command RUN, if you wish to use it to run WordStar, would be typed RUN "WORDSTAR" Arguments may be separated by blanks or commas. Thus both GETFILE XMODEM "FILE.EXT" and GETFILE,XMODEM,"FILE.EXT" September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 3 are valid. To use the quotation character in a quoted string, precede it with the special escape character ` (the reverse tick mark, or accent grave, ASCII 96). Thus to print the message She said "Goodbye" and then went home. use the command MESSAGE "She said `"Goodbye`" and then went home." Labels are used as targets of GOTOs and GOSUBs. Labels must end with a colon. Below are some valid labels: LABEL1: This_is_a_long_label: JUMP1: split: GO_HERE: Labels must appear on a line by themselves. (Comments are allowed on label lines; executable statements are not). Labels may be of any length; however, only the first 8 characters are used by the interpreter. Thus LABEL_TAG1: and LABEL_TAG2 are the same as far as ProComm is concerned. Comments begin with a semi-colon (;). Any text following a semi-colon is treated as comment text. Below are valid comments: ; This is a comment. LABEL7: ;This is a comment on a label line TRANSMIT "Welcome back" ;And this is a comment as well There are 10 string variables, named S0-S9, which may be set and used in place of quoted strings. They have a maximum length of 80 characters each. They may be set by the ASSIGN, GET and RGET commands. String variables may be used in place of a quoted string in any of the commands marked below with the @ character. For example, the commands ASSIGN S5 "Hello, Mike Todd here" TRANSMIT S5 and TRANSMIT "Hello, Mike Todd here" are functionally the same. One of the most useful applications of string variables is in obtaining and using user responses. Consider the commands below: MESSAGE "Enter the name of the file to upload:" September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 4 GET S4 SENDFILE XMODEM S4 String variables are also a very handy method for passing values between command files. When you chain from command file to command file, using the EXECUTE command, string variable contents are not reset. Thus you may set a variable in one command file, and act on the variable in another. ProComm allows the nesting of commands such as IF, SWITCH and GOSUB. Nesting, however, is limited to 10 levels. Characters that are received from a remote system are stored in the receive buffer. During command file execution, the receive buffer is emptied before each command is executed, with the exceptions noted below. What this means is that before each command is performed, all the characters that have come in are displayed on the screen and are therefore not available to be processed by later commands. The exceptions are the GET, RGET and WAITFOR commands, as well as labels and comments. In these cases the buffer is not emptied, allowing the command to process the accumulated characters. The point here is that if you have a command sequence that looks like: TRANSMIT "password!" PAUSE 5 SET DUPLEX HALF WAITFOR "target" the text you are looking for may come in and be processed before the WAITFOR command has a chance to see it. A better solution would be to change duplex at some other point, and let the WAITFOR command do the extra pausing: SET DUPLEX HALF SET DUPLEX HALF TRANSMIT "password!" TRANSMIT "password!" WAITFOR "target" 35 WAITFOR "target" 35 ; 30 seconds is the default pause Use the commands described below to perform your specific task. Be sure to test your command files thoroughly before using them for unattended communications. The following notations apply to the commands listed below: Commands marked with an asterisk (*) may be tested with the IF command. Commands marked with an at-sign (@) indicate where string variables may be used in place of quoted strings. Sx indicates that you should use one of the string variables. Ellipses (...) mean that you may place a number of command lines in that spot. September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 5 Top Level Commands ALARM [seconds] The ALARM command will sound an alarm to alert you to some event. Use the [seconds] option to determine the amount of time the alarm will sound. If the [seconds] option is not specified ProComm will use the Alarm Time specified in the General SetUp screen. This command is also under control of the Alarm Sound setting. Both Alarm Sound and Alarm Time may be regulated using the SET command described below. Example: ALARM 5 ; sounds the alarm for 5 seconds ASSIGN Sx "string" @ This command assigns the contents of "string" to a user variable. Use ASSIGN to set a user variable from within your command file. Examples: ASSIGN S5 "12345" ; set S5 to contain the string '12345' ASSIGN S6 S5 ; sets S6 to be the same as S5 BREAK [time] The BREAK command is used to send a break to the remote system. The optional [time] argument determines the length of the break in milliseconds. If [time] is not specified, ProComm will use the default as indicated by the Break Length option in the Terminal SetUp screen. Examples: BREAK ; send a break using the default timing BREAK 500 ; send a 500 millisecond break CHDIR "drive and/or directory" @ The CHDIR command will change the logged directory and/or drive. Examples: CHDIR "A:" ; change the logged drive to A: CHDIR "C:\COMM" ; change to \COMM dir on drive C: CHDIR "\COMM" ; change logged dir to \COMM CLEAR [bg fg] The CLEAR command is used to clear the top 24 lines of your screen. The optional parameter [bg fg] (you must use both codes) allows you to change your background (bg) and foreground (fg) colors. If the [bg fg] option is not used, the screen will be cleared to the current colors. If the [bg fg] option is used, ProComm will clear the screen to the new colors as well as reset the current colors to those specified. The codes to use September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 6 for colors are as follows: 0 Black 8 Dk Grey (8-15 are the bright 1 Blue 9 Lt Blue colors) 2 Green 10 Lt Green 3 Cyan 11 Lt Cyan 4 Red 12 Lt Red 5 Magenta 13 Lt Magenta 6 Brown 14 Yellow 7 Lt Grey 15 White Only the codes 0-7 are valid for background colors; any of the sixteen colors may be used for the foreground. Examples: CLEAR 0 10 ; clear screen to lt green on black CLEAR ; clear screen to current colors DIAL "entry" @ DIAL " " The DIAL command is used to call an entry in your dialing directory. Specify the number of the entry, optionally preceded and/or followed by a long distance code identifier as the argument. Examples: DIAL "5" ; call entry number 5 DIAL "#5" ; call entry 5 using ld code '#' If a second command file is linked via the dialing directory to the entry being dialed, the linked command file will not be executed. Place all statements to be executed in the command file which initiates the call. Use the IF LINKED command to avoid secondary dialing in command files linked to dialing directory entries. For example, including the commands IF NOT LINKED ; do not execute the dial command if DIAL "5" ; this file is executing via linkage ENDIF ; to a dialing directory entry in a command file linked to entry number 5 allows you to use that command file both as a stand alone file and linked to the dialing directory entry. This command uses the auto redial facility to place its calls; it will keep re-dialing until a connection is made. To make a call without using auto redial, use the TRANSMIT command. Examples: TRANSMIT "ATDT1 314 449-9401!" ; place the call PAUSE 10 ; wait 10 seconds IF CONNECTED ... ; do these commands if September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 7 ENDIF ; connected Remember, if you sort your dialing directory you will need to change your command files so the entry numbers match. DOS "command" [WAIT] @ * The DOS command allows you to execute DOS commands or other programs from within a ProComm .CMD file. Enter the "command" as it would appear on the DOS command line. For example, to go out to DOS and type a file named FILE.EXT to your printer use the command: DOS "type FILE.EXT > prn" If the optional argument WAIT is included, ProComm will wait for a keystroke after executing the command, before returning to ProComm. To execute this command properly you must make sure of two things. First, you must have enough memory to run the "command". Secondly, COMMAND.COM must be where ProComm can find it. (Either in the boot location or wherever COMSPEC is pointing). While this command returns an error status checkable with the IF command, the error check is very limited. The DOS command will indicate FAILURE only if COMMAND.COM was not found. IF COMMAND.COM was found, even if the command to be executed was invalid, SUCCESS will be returned. Examples: DOS "del FILE.EXT" ; delete a file DOS "sortdisk" ; run a program called sortdisk IF FAILURE MESSAGE "COMMAND.COM not found" ENDIF CAUTION: If you execute a program or command requiring user input be sure you are around to provide it, since the program will wait until you do. EMULATE terminal -or- EMULATE "terminal" The EMULATE command changes the active emulation to that specified. Valid terminal types are: VT100, VT52, IBM3101, TV920, TV950, ADM5, HEATH19, ANSI, ADDSVP and WYSE100. Examples: EMULATE VT100 ; change emulation to VT100 EMULATE "IBM3101" ; emulate the 3101 EXECUTE "cmd file" @ The EXECUTE command allows you to begin execution of a different command file. The currently executing command file will be ended and will not be returned to. The EXECUTE commands allows a one-way chaining of command file execution. The file extension of .CMD need not be specified. September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 8 Remember, string variables are not reset when chaining command files so you may use them to pass values. String variables are reset to null, however, when you begin the first command in the chain. Examples: EXECUTE "CALL_KEN.CMD" ; execute CALL_KEN.CMD GET S0 ; get the option SWITCH S0 ; switch based on option CASE "A" ASSIGN S1 "CHOICEA.CMD" ENDCASE CASE "B" ASSIGN S1 "CHOICEB.CMD" ENDCASE DEFAULT ASSIGN S1 "DEFAULT.CMD" ENDCASE ENDSWITCH EXECUTE S1 EXIT The EXIT command terminates the executing command file and returns you to Terminal Mode. Examples: TRANSMIT "Goodbye" ; log off remote HANGUP ; hangup phone EXIT ; return to Terminal Mode FIND Sx "target" @ * The FIND command looks for an occurrence of the "target" string in the string variable Sx. Test for an occurrence of "target" within Sx using the IF FOUND command. The FIND command is not case sensitive. Examples: MESSAGE "Enter the password:" ; prompt FIND S0 "password" ; look for password IF NOT FOUND ; found ? MESSAGE "Invalid password" ; not found, do this code GOTO SECURITY_BREACH ELSE GOSUB WELCOME ; found, do this ENDIF GET Sx [length] The GET command is used to obtain and store user input. The Sx argument determines which string variable is used to hold the data. The optional [length] variable determines the maximum number of characters that will be accepted. If the [length] argument is not specified, the maximum size of 80 characters is used. September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 9 When responding to a GET command, the user must enter a to signal that his input is complete. The is not included in the string variable. If the [length] argument is used, the user will be allowed to enter up to [length] number of characters, but still must use a to complete his entry. ProComm will beep if the user attempts to enter more than [length] characters. The MGET command is the same as the GET command except that the text the user enters is not displayed; rather each character typed will display as an asterisk (*). This is handy for security-related items such as passwords. Examples: MESSAGE "Enter your choice: (A,B or C)" GET S3 1 SWITCH S3 ... ENDSWITCH MESSAGE "Enter the password" MGET S9 8 FIND S9 "secret" IF NOT FOUND MESSAGE "You are not an authorized user." QUIT ENDIF GETFILE KERMIT XMODEM "filename" @ * WXMODEM "filename" @ * (Widowed XMODEM) RXMODEM " " (Relaxed XMODEM) YMODEM "filename" @ * BYMODEM (YMODEM Batch) TELINK * MODEM7 * ASCII "filename" @ * CISB (CompuServe B) The GETFILE command performs a file download (receive). A number of protocols are currently supported; see the section on file transfers for more information on each protocol. To perform a download you must first initiate the transfer on the remote. When that system indicates that it is ready, begin your transfer. Note that 4 protocols require you to specify the filename to receive; for the other protocols, the filename is provided by the sending system. All transfers may be checked for successful completion using the IF SUCCESS/FAILURE command. Examples: WAITFOR "Begin your transfer now" ; wait till it's ready GETFILE XMODEM "FILE.EXT" ; receive FILE.EXT WAITFOR "Kermit-32>" ; wait for prompt MESSAGE "Enter file to transfer" ; transfer a file with September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 10 GET S1 ; Kermit TRANSMIT "SEND " ; send transfer command TRANSMIT S1 ; the file name TRANSMIT "^M" ; and a CR GETFILE KERMIT ; now get it GOSUB label The GOSUB command provides for an unconditional branch with return. Upon encountering a GOSUB command, the interpreter searches the command file for the label specified. If the label is found, execution will continue with the command immediately following the label. If the label is not found, the command file will terminate with an "Unexpected end of file" error. After successfully branching to the specified label, execution will continue until a RETURN command is found, at which point ProComm will jump back to the point at which the GOSUB was called. Execution resumes at the command immediately following the GOSUB. Each GOSUB must have its associated RETURN. GOSUBs may be nested to a depth of 10 levels. If the end of the command file is encountered within a GOSUB, an "Unexpected end of file" error will occur. If you attempt to nest more than 10 GOSUB calls, a "Stack overflow" error will result. Likewise, if you attempt to RETURN without having a corresponding GOSUB, a "Stack underflow" error will occur. Examples: SWITCH S0 ; switch based on the contents of S0 CASE "ABC" GOSUB LABEL1 ENDCASE CASE "ZXY" GOSUB LABEL2 ENDCASE DEFAULT GOSUB ERROR1 ENDCASE ENDSWITCH ... ; Subroutine area LABEL1: ... RETURN LABEL2: ... RETURN ERROR1: ... RETURN GOTO label The GOTO command performs an unconditional branch to the indicated label. Upon encountering a GOTO command, the interpreter searches the command September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 11 file for the label specified. If the label is found, execution will continue with the command immediately following the label. If the label is not found, the command file will terminate with an "Unexpected end of file" error. Remember, only the first 8 characters of a label are actually used. If two identical labels exists, ProComm will branch to the one closest to the beginning of the file. GOTOs may not be used to jump into the middle of IF or SWITCH statements, although they may be used to branch out of those constructs. They should also not be used to branch into or out of subroutines (code segments designed to be used with the GOSUB command), although they may be used within the boundaries of individual subroutines. Use of a GOTO in these situations will result in unexpected and usually erroneous execution. Examples: IF NOT WAITFOR GOTO ERROR_EXIT ; this is OK ENDIF ... ERROR_EXIT: MESSAGE "Abnormal termination" HANGUP QUIT GOTO LABEL1 ; this is not OK SWITCH S0 CASE "xyz" LABEL1: etc. HANGUP * The HANGUP command attempts to disconnect the phone in the manner described for the Alt-H command in Section 3. Use the IF CONNECTED command to determine if you successfully disconnected. Example: HANGUP ; disconnect the phone HOST The HOST command is used to put ProComm into Host Mode. Example: HOST ; enter host mode IF condition The IF command is used to make decisions. The syntax of the IF statement is IF condition [part 1] ELSE September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 12 [part 2] ENDIF where the ELSE part is optional. The condition is evaluated; if it is true, [part 1] is executed. If it is false, and there is an ELSE, [part 2] is executed. There must be an ENDIF for every IF. IF commands may be nested up to 10 levels deep. Valid conditions for the IF command are SUCCESS CONNECTED FOUND FAILURE LINKED WAITFOR The SUCCESS condition is evaluated as true if the last checkable command was successfully executed. A "checkable" command is a command file command that sets one of the condition flags. Checkable commands are indicated in this chapter by having an asterisk (*) after the command name. For example: RUN "someprog" IF SUCCESS ... ; this segment will execute if "someprog" ran. ENDIF The FAILURE condition is considered true if the last checkable command was not successfully completed. For example, if you had an RGET command that timed out, FAILURE would be considered true: RGET S9 80 5 IF FAILURE ... ; this segment will execute if RGET times out. ENDIF The CONNECTED condition is true if CD (Carrier Detect) is found to be high. CD is high when you are connected to a remote system, or if your modem is forcing the CD lead high. WARNING: be sure that your modem does not force CD high (usually a dip switch setting) or the CONNECTED condition will always be true. IF CONNECTED ... ; perform this segment if you are connected ENDIF The LINKED condition is considered true if the command file that is executing was started because it was linked to an entry in the dialing directory. In other words, if you have a command file called VAX.CMD which is linked to dialing directory entry number 5, and you call entry number 5 and are connected, and VAX.CMD begins execution, an IF command that looks like IF LINKED ... September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 13 ENDIF will be considered true. The primary use for the LINKED condition is so you can write one command file and use it both stand alone and linked to dialing directory entries. IF NOT LINKED DIAL 5 ENDIF In this code segment, the DIAL command will be executed only if the command file was not executed because of a dialing directory link. (More on the NOT option below). The FOUND condition is used to test the result of the last FIND command executed. It is considered true if the "target" was found in the specified string variable. For example, in the sequence ASSIGN S9 "ABCDEFG" FIND S9 "CDE" IF FOUND ... ENDIF the commands denoted by ellipses (...) would be executed, as the FOUND condition would be true. The WAITFOR condition is used to check the result of the last WAITFOR command. If the "target" specified in the WAITFOR command was received, the WAITFOR condition would be true. If the WAITFOR command timed out before receiving the "target", the condition would be false. WAITFOR "ABCDEFG" 15 ; wait 15 seconds for 'ABCDEFG' IF WAITFOR ... ; execute if 'ABCDEFG' was received ELSE ... ; execute if timed out ENDIF The NOT operative may be employed with any of the conditionals. The effect of the NOT is to reverse the value of the condition. For example, if CONNECTED is false, then NOT CONNECTED would be true. The conditions NOT SUCCESS and FAILED are exactly the same. The code segments IF FOUND IF NOT FOUND [part 1] [part 2] ELSE ELSE [part 2] [part 1] ENDIF ENDIF will result in identical execution. September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 14 Examples: IF NOT CONNECTED ... ; do this if no connection ENDIF WAITFOR "Something" IF WAITFOR ... ; do this if it was found ELSE ... ; else do this ENDIF SEND_IT: SENDFILE KERMIT "FILE.EXT" IF NOT SUCCESS MESSAGE "Error in file transfer. Retrying..." GOTO SEND_IT ENDIF ; How to redial without using Alt-R DOIT: TRANSMIT "ATDT123-4567" WAITFOR "CONNECT" 20 IF NOT WAITFOR MESSAGE "No connect. Redialing..." GOTO DOIT ENDIF ISFILE "filename" @ * The ISFILE command is used to determine if a specific file exists in the current directory. Use the IF SUCCESS/FAILURE command to test the results of the ISFILE command. Examples: ISFILE "procomm.doc" IF SUCCESS MESSAGE "Doc file exists" ELSE MESSAGE "Doc file not found" ENDIF MESSAGE "Enter filename" GET S0 ISFILE S0 IF NOT SUCCESS MESSAGE "File does not exist" ENDIF KERMSERVE SENDFILE "filename" @ * September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 15 GETFILE "filename" @ * FINISH LOGOUT The KERMSERVE command may be used to issue a Kermit server command. The available commands are listed above. Examples: MESSAGE "File to send?" ; prompt for filename GET S0 ; get filename KERMSERVE SENDFILE S0 ; send file KERMSERVE FINISH ; issue the FINISH server command KFLUSH The KFLUSH command is used to clear any accumulated keystrokes from the keyboard buffer. Any keystrokes that have been entered, but not processed, will be lost. Examples: KFLUSH ; clear keyboard buffer LOCATE row col The LOCATE command positions the cursor to the location specified by row and col (column). Rows are numbered 0-24, columns 0-79, with 0,0 (row 0, col 0) being the upper left corner of the screen. Examples: CLEAR ; clear the screen LOCATE 10 20 ; position cursor MESSAGE "ENTER CHOICE:" LOCATE 10 44 ; position at end of line GET S8 LOG OPEN ["filename"] @ * CLOSE SUSPEND RESUME The LOG command controls file logging during command file execution. Use the OPEN command to start logging data to disk. If "filename" is not present, the Default Log File as specified in the General SetUp section will be used. Use the CLOSE command to turn off file logging. The SUSPEND command will stop text from being logged temporarily without closing the log file. Use the RESUME command to continue logging after a SUSPEND command. Examples: LOG OPEN ; use default log name ... September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 16 LOG SUSPEND ; put log on hold ... LOG RESUME ; resume logging ... LOG CLOSE ; close log MACRO number -or- MACRO "number" @ The MACRO command will send the string currently assigned to any of the macro keys (Alt-0 through Alt-9). Use the MLOAD command to load individual keyboard macro definition files. Examples: MACRO 5 ; send macro assigned to Alt-5 ASSIGN S8 "2" MACRO S8 ; send macro assigned to Alt-2 MESSAGE "string" @ The MESSAGE command displays a string on the local console. The text is not sent to the remote. The message is displayed at the current cursor position, in the current colors. MESSAGE will always do a CR/LF after each string. The "string" may contain control characters such as CR and LF by using the translation conventions described in Section 2. Use the MESSAGE command for prompts, informational messages, building menus, etc. Examples: MESSAGE "+---------------------+" MESSAGE "| Enter your choice: |" MESSAGE "+---------------------+" LOCATE 2,20 GET S0 1 SWITCH S0 etc. ASSIGN S9 "This is the first line^M^JThis is the second" MESSAGE S9 MLOAD "filename" @ The MLOAD command is used to load a keyboard macro file. Example: MLOAD "SYSTEM1.KEY" ; load a new macro file PAUSE seconds -or- PAUSE "seconds" The PAUSE command halts command file execution for the specified number of seconds. Characters received during a pause are not displayed until after the pause has completed. Examples: September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 17 TRANSMIT "Kermit send file.ext" ; start the transfer PAUSE 3 ; let the remote start KERMIT RECEIVE ; receive the file PRINTER ON PRINTER OFF The PRINTER command is use to control print logging. Use the ON argument to begin logging the session to the printer; use OFF to end logging. ProComm writes the printer log to the DOS device PRN. You can use the MODE command in DOS to redirect printer output. Examples: PRINTER ON ; begin print logging ... PRINTER OFF ; end print logging QUIT The QUIT command terminates the executing command file and exits ProComm as well. Use it only to shut down the entire program. Examples: TRANSMIT "Logoff" ; log off remote HANGUP ; hangup the phone QUIT ; close down ProComm RFLUSH The RFLUSH command is used to clear the input buffer. Any characters that have been received, but not yet displayed, will be lost when this command is issued. It is generally used to clear the input buffer in preparation for some task. Example: RFLUSH ; clear the input buffer RGET Sx [length] [delay] * The RGET command provides services similar to those of the GET command; however, input is taken from the remote computer rather than from the keyboard. The RGET command will complete when a is received or [length] characters have been received. Unlike with the GET command, a is not required if [length] characters have been received. Use the [delay] argument to specify the maximum number of seconds to wait for the string to be received before timing out. If [delay] seconds have elapsed without receiving a or [length] characters, the RGET command will timeout and execution will continue. You can determine if the command September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 18 timed out using the IF SUCCESS/FAILED command. You must specify [length] if you wish to specify [delay]. If length is not specified, the maximum of 80 characters is used; if [delay] is not specified, the default of 30 seconds is used. Examples: TRANSMIT "ATS0=1^M" ; go into auto answer WAIT_IT_OUT: IF NOT CONNECTED ; wait for a connection GOTO WAIT_IT_OUT ENDIF TRANSMIT "ENTER PASSWORD:" RGET S9 8 45 ; wait 45 seconds max IF FAILED ; timed out TRANSMIT "Times up. Goodbye" HANGUP GOTO WAIT_IT_OUT ENDIF FIND S9 "secret" IF NOT FOUND TRANSMIT "Sorry , but you're not authorized." HANGUP GOTO WAIT_IT_OUT ENDIF RUN "program" [WAIT] @ * The RUN command is similar to the DOS command except that it cannot execute internal DOS commands. See the explanation of the DOS command for conditions necessary for the correct execution of this command. A major difference between the DOS and the RUN commands is the error codes returned. RUN will report any non-zero return code from the "program" as FAILURE; only "programs" exiting with a return code of zero will indicate SUCCESS. If the optional argument WAIT is included, ProComm will wait for a keystroke after executing the program, before returning to ProComm. Examples: RUN "filesort" ; execute a program called filesort ASSIGN S0 "filesort" RUN S0 IF FAILURE MESSAGE "filesort returned error" ELSE MESSAGE "filesort executed successfully" ENDIF SENDFILE KERMIT "filename" @ * September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 19 RXMODEM "filename" (Relaxed XMODEM) XMODEM "filename" @ * YMODEM "filename" @ * BYMODEM "filename" (YMODEM Batch) TELINK "filename" @ * MODEM7 "filename" @ * ASCII "filename" @ * CISB "filename" @ * WXMODEM "filename" @ * (Windowed XMODEM) The SENDFILE command performs a file upload (send). Many different protocols are currently supported; see the section on file transfers for more information on each protocol. To perform an upload you must first initiate the transfer on the remote. When that system indicates that it is ready, begin your transfer. All 9 protocols require that you specify the filename to send. All transfers may be checked for successful completion using the IF SUCCESS/FAILURE command. Examples: WAITFOR "Begin your transfer now" ; wait till it's ready SENDFILE XMODEM "FILE.EXT" ; send FILE.EXT WAITFOR "Kermit-32>" ; wait for prompt MESSAGE "Enter file to transfer" ; transfer a file with GET S1 ; Kermit TRANSMIT "RECEIVE" ; send transfer command TRANSMIT S1 ; the file name TRANSMIT "^M" ; and a CR SENDFILE KERMIT S1 ; now send it SET ... The SET command is used to control various system parameters and options. It is fully described in the next section. SNAPSHOT The SNAPSHOT command performs a screen dump as described in Section 3. Example: SNAPSHOT ; dump the screen contents to the .IMG file SWITCH Sx The SWITCH command provides special multi-way decision making. A SWITCH compares the value of a string variable against a number of constants and branches accordingly. The syntax of a SWITCH command is: SWITCH S2 ; switch based on S2 September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 20 CASE "target1" ; if S2 = 'target1' ... ; do these commands ENDCASE ; until here CASE "target2" ; any number of cases ... ENDCASE ; needed for each case DEFAULT ; if no previous case matches ... ; do these commands ENDCASE ENDSWITCH ; ends the SWITCH The string variable Sx contains some value, usually put there by a GET or RGET command. When a SWITCH command is found, ProComm begins looking for a CASE statement that contains a "target" which matches the string variable specified in the SWITCH. The match must be complete, although it is not case sensitive. Thus the values 'ABC', 'abc' or 'AbC' would all match a CASE 'abc' command, but the values 'ABCDE', 'XYZabc' or 'a b c' would not. After finding a CASE that matches, ProComm will continue command file execution starting with the command immediately following the matching CASE. Execution continues until an ENDCASE command is found. At that point ProComm skips to the command immediately following the matching ENDSWITCH command and resumes execution. Note that each CASE statement must have a matching ENDCASE, and each SWITCH a matching ENDSWITCH. There is a special case known as the DEFAULT case. The commands within the DEFAULT case will be executed if no previous CASE matched the string variable. The DEFAULT case is optional and need not be specified. If there is no DEFAULT case, and no other match is found, command file execution will continue with the statement following the ENDSWITCH command. Another special case the _NULL case. The _NULL case will be executed if the string variable being switched on is null, i.e., has no value. For example, if a user enters a CR only in reply to a GET or RGET command, the string variable being gotten will be null. The _NULL case would then be triggered. The correct syntax for the _NULL case is: CASE "_NULL" Examples: (display some menu of options) GET_CHOICE: MESSAGE "Enter your choice" GET S5 SWITCH S5 ; switch based on S5 CASE "A" ; if S5 = 'a' or 'A' GOSUB CHOICEA ; do this ENDCASE CASE "B" ; if S5 = 'b' or 'B' September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 21 GOSUB CHOICEB ; do this ENDCASE CASE "_NULL" ; do this if user pressed GOSUB NULL_CASE ; only CR ENDCASE DEFAULT ; S5 not = to 'A' or 'B' or NULL MESSAGE "Invalid selection" PAUSE 3 GOTO GET_CHOICE ENDCASE ENDSWITCH MESSAGE "Continue? (Yes/No)" ; prompt GET S7 ; get response SWITCH S7 ; switch based on response CASE "NO" ; they said "no" QUIT ; so leave ENDCASE ENDSWITCH One use of a SWITCH command is to get a choice from the user, and then to perform various tasks depending upon the option selected. In the first example, the command file would begin by presenting some list of options. You could easily build a menu using the MESSAGE and LOCATE commands. The command file could then prompt the user for his selection, and GET the selection into a string variable, in this case S5. The command file will branch based on the user's selection. If the user entered the letter 'A', the SWITCH will execute the first case and call the subroutine entitled CHOICEA. After returning from that subroutine, execution will continue with the first statement following the ENDSWITCH command. If the user had entered 'B' as his choice, the CHOICEB subroutine would have been executed. If neither 'A' nor 'B' had been entered by the user the DEFAULT case would execute. In that event the "Invalid selection" message would be displayed, the program would pause for 3 seconds, and then branch back up to the GET_CHOICE label and the process would be repeated. In the second example, if the user had entered 'No' the first case would execute and the command file would QUIT. In all other cases, no part of the SWITCH would execute, and the command file would continue. TRACE ON/OFF The TRACE command allows you to "trace" the execution of a command file. If you set TRACE ON, every command will be printed to the screen, in contrasting colors, as it is executed. TRACE is very handy for debugging errant command files. Examples: TRACE ON ; set trace on TRANSMIT "string" @ The TRANSMIT command sends a character string to the remote. The "string" may contain control characters using the standard translation September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 22 conventions. Examples: MESSAGE "Enter your ID" ; send the prompt GET S6 ; get the ID TRANSMIT S6 ; send the ID TRANSMIT "!" ; plus a CR WAITFOR "First name:" ; Wait for a prompt TRANSMIT "TOM!" ; send the name plus a CR WAITFOR "target" [delay] @ * The WAITFOR command allows you to wait for a particular string to be received from the remote before command file execution continues. The [delay] option tells ProComm how many seconds to wait for the "target" before timing out and continuing execution. If no [delay] is specified, ProComm will wait 30 seconds. Use the IF WAITFOR condition to test the results of a WAITFOR command. Examples: WAITFOR "first name:" 45 ; wait for the string "first name" ; for 45 seconds IF WAITFOR ; if it was found w/o timing out TRANSMIT "TOM!" ; send your name ELSE ; else GOTO ERROR ; go to error processing ENDIF WAITFOR targets are not case sensitive, thus either "FIRST NAME" or "First Name" would successfully complete the command sequence above. You may also include control character in the target using the translation conventions described earlier. Example: WAITFOR "^M^JBUSY" ; wait for CR LF then BUSY WHEN "target" "response" @ The WHEN command is used to transmit a certain "response" text every time a certain "target" text is received. Once a WHEN command is initiated, it will be in effect until a CWHEN (Clear WHEN) command is found or the command file ends. For example, suppose you are calling an online service that displays a "-more-" prompt at the end of each page of display, and waits for you to enter a carriage return before it continues. By specifying the command WHEN "-more-" "^M" at the beginning of the command file, you are instructing ProComm to transmit a CR (^M) every time it receives the string "-more-", thus relieving you of the task of matching every occurrence of "-more-" with a September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 23 WAITFOR "-more-" TRANSMIT "^M" command sequence. Examples: WHEN "continue? (Y/N)" "Y^M" ; send a 'Y' for ... ; every "continue" received CWHEN ; turn off WHEN processing Set Commands All SET commands have the same format: SET parameter value The SET commands are used to change the value of the parameters in the SetUp facility (Alt-S) and the Line Settings window (Alt-P). Available values are separated by slashes (/). Because those parameters are described in detail in other sections, an in-depth discussion is not presented here. The appropriate SetUp section is indicated in parenthesis for each command. SET ASCII (ASCII Transfer Setup) The ASCII transfer SET commands are covered below. SET ALARM ON/OFF (General Setup) Controls alarm sound. SET ATIME seconds SET ATIME (General Setup) Sets amount of time alarm sounds. SET BACKSPACE NONDEST/DEST (Terminal Setup) Controls destructive nature of BS. SET BAUDRATE 300/1200/4800/9600/19200 (Line Settings) Sets the baud rate. SET CR_IN CR/CR_LF (Terminal Setup) Controls incoming CR translation. SET CR_OUT CR/CR_LF (Terminal Setup) Controls outgoing CR translation. SET DATABITS 7/8 (Line Settings) Sets the data bits used. SET DLDIR " " @ (General Setup) Sets the default download drive and directory. September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 24 SET ENQ ON/OFF/CISB (Terminal Setup) Controls response to ENQ (ASCII 5). SET FLOWCTRL ON/OFF (Terminal Setup) Controls use of XON/OFF flow control. SET HOSTPSWD " " (Host Mode Setup) Sets the host mode password. SET PARITY EVEN/ODD/NONE/MARK/SPACE (Line Settings) Controls parity. SET PORT COM1/COM2/COM3/COM4 (Line Settings) Selects serial port to use. SET RDELAY seconds (Modem Setup) Determines timeout period for redials. SET SCROLL ON/OFF (Terminal Setup) Determines scroll setting. SET SHELLPSWD " " @ (Host Mode Setup) Sets the host mode shell password. SET SOUND ON/OFF (General Setup) Controls sound effects. SET STOPBITS 1/2 (Line Settings) Sets the stop bits used. SET SWRITE BIOS/DIRECT (General Setup) Determines the screen write method. SET TRANSLATE ON/OFF (General Setup) Controls use of the translate table. SET TXPACE Determines pacing for all outgoing character strings. SET WRAP ON/OFF (Terminal Setup) Controls line wrap. Set ASCII Commands (ASCII Transfer Setup) SET ASCII BLANKEX ON/OFF Controls expansion of blank lines during ASCII uploads. SET ASCII CHARPACE milliseconds Sets the character pacing (in milliseconds). SET ASCII DN_CR CR/CR_LF/STRIP Controls translation of incoming CRs during ASCII downloads. September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 25 SET ASCII DN_LF LF/CR_LF/STRIP Controls translation of incoming LFs during ASCII downloads. SET ASCII ECHO ON/OFF Controls local echo during ASCII uploads. SET ASCII LINEPACE tenths Sets line pacing timing (in 1/10 seconds). SET ASCII PACECHAR Sets the pace character used. Specify as an ASCII decimal value. SET ASCII UP_CR CR/CR_LF/STRIP Controls translation of outgoing CRs in ASCII uploads. SET ASCII UP_LF LF/CR_LF/STRIP Controls translation of outgoing LFs in ASCII uploads. Set Kermit Commands SET KERMIT CQUOTE char Set the Ctrl quote character. SET KERMIT PACKSIZE number Set the maximum packet size. SET KERMIT PADCHAR char Select the pad character. SET KERMIT PADNUM number Set the number of pad characters. SET KERMIT 8QUOTE char Select the 8th bit quote character. SET KERMIT HANDSHAKE char Select the handshake character. SET KERMIT EOLCHAR char Select the end of line character. SET KERMIT BLOCKCHECK 1/2/3 Select the block check type. 1 = 1 byte checksum, 2 = 2 byte checksum, 3 = 3 byte CRC. SET KERMIT FILETYPE TEXT/BINARY Select the transfer file type. Arguments listed as "char" should use the ASCII decimal value of the desired character. For example, to use XON (ASCII 17) as the HANDSHAKE character, issue the command September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 26 SET KERMIT HANDSHAKE 17 ERROR MESSAGES If an error is encountered during the execution of a command file, an error message will be displayed and command file execution will stop. Error messages begin with the error number (described below), followed by the line number of the line containing the error, followed by the erroneous line itself, for example: ERROR 2, LINE 6: goto missing_label ERROR NUMBER DESCRIPTION 1 ........... Invalid token. 2 ........... Unexpected end of file. 3 ........... Unexpected CASE statement. 4 ........... Unexpected DEFAULT statement. 5 ........... Unexpected ENDCASE statement. 6 ........... Unexpected ENDSWITCH statement. 7 ........... Unexpected ELSE statement. 8 ........... Unexpected ENDIF statement. 9 ........... Unexpected token. 10 ........... Missing token. 11 ........... Stack overflow. 12 ........... Stack underflow. ERROR 1 - Invalid token Indicates that an unidentified keyword was found, or that an invalid argument was included. ERROR 2 - Unexpected end of file Indicates that the end of file was reached while executing some command. May be triggered by IF statements without their corresponding ENDIF; SWITCH statements without an ENDSWITCH; or when attempting to find a label that does not exit. ERROR 3 to 8 - Unexpected [token] Indicates that the given keyword was found in an unexpected place, i.e. an ELSE command with no preceding IF, or a DEFAULT command with no preceding SWITCH. ERROR 9 - Unexpected token Indicates that a keyword or argument was supplied where none are expected. ERROR 10 - Missing token September 26, 1986 Procomm Version 2.4 Summary of Command File Commands Page 27 Indicates that a token or argument was expected, but not supplied. ERROR 11 - Stack overflow Indicates that nesting has gone too deep, i.e. an 11th level in a nested if statement, or an attempt to access an 11th level subroutine. ERROR 12 - Stack underflow Indicates the attempt to return a level when no nesting has occurred. For example a RETURN command when no GOSUB has executed.