Asynchronous communication script commands

Table 3-6 describes the communication script commands that you can enter manually and use in your scripts. Use these commands to build script files that automate your communications activities. Script files are text files containing script commands that perform communications tasks. You can create scripts that call a host system, read mail, transfer files, and so on.

**Table 3-6: Asynchronous communication script commands**
Script command	Description
CAPTURE	Opens a specified capture file and logs all received data to that file. Syntax: <CAPTURE filename> Example: CAPTURE “C:\CSERVE.TXT”
CLOSECAPTURE	Closes a capture file opened previously with a CAPTURE command. Syntax: <CLOSECAPTURE>
DIAL	Dials a phone number and connects to a host modem. Example: DIAL “555-1212”, 10 WAITFOR “Press Enter to Continue” SEND “^M” This example dials 555-1212. The second argument (10) specifies the number of retries if the line is busy. After a connection is made, it waits to receive “Press Enter to Continue” and then sends a carriage return (^M).
DOWNLOAD	Downloads (receives) a file. Syntax: <DOWNLOAD [filename]> Example: PROTOCOL “XMODEM-CRC” DOWNLOAD “C:\MYPROG\ZIPFILE.ZIP” This example receives the file C:\MYPROG\ZIPFILE.ZIP via Xmodem-CRC. Example: PROTOCOL “ZMODEM” This example receives a file via ZMODEM. With the ZMODEM, YMODEM, and YMODEM–G protocols, the filename is not specified because the remote side of a ZMODEM transfer session does not require a file name.
END	Ends the script, but does not close the communications port. Syntax: <END>
HANGUP	Hangs up the phone (disconnects the modem), but does not close communications port.
INPUT	Prompts the user for a string and stores the inputted data string in a specified variable. Syntax: <INPUT MsgStr, VariableName> Example: INPUT “Enter Your Password”, PassWord SEND PassWord SEND “^M” This example displays an input dialog box with the message, “Enter Your Password” and stores the entered text in a variable named PassWord. The stored text in PassWord is sent out the communications port followed by a carriage return (^M).
: (LABEL)	Specifies a label. Like batch files, any word that starts with a colon is treated as a label. Syntax: <:label> Example: :JumpHere
ON TIMEOUT GOTO	Tells the script to jump to a specified label when a timeout occurs. A timeout can be caused by a busy signal on the other end of the line, accessing an inactive modem, etc. Syntax: <ON_TIMEOUT_GOTO: label> Example: ON_TIMEOUT_GOTO :JumpHere
PAUSE	Pauses for a specified number of seconds. Syntax: <PAUSE n> Example: PAUSE 1 This example causes the program to wait one second. Sometimes a pause is required to smooth out the communications process, such as in between a WAITFOR and a SEND command. This may require experimentation.
PORT	Specifies which port to use and opens the port. If no port is specified, scripts use the current port with its current settings. Syntax: <PORT n> Example: PORT 2 This example causes COM2 to be used as the port and opened.
PROTOCOL	Sets the file transfer protocol. Syntax: <PROTOCOL protocol> Example: PROTOCOL “ZMODEM” Protocol is one of the following string identifiers: XMODEM YMODEM-G XMODEM-CRC ZMODEM XMODEM-1 KKERMIT YMODEM COMPUSERVE You must issue this command to set the protocol before a DOWNLOAD command or an UPLOAD command. If you do not, the script uses the current protocol setting for the PDQComm control.
SEND	Sends a string out of the communications port. The Send command treats an unquoted string as a variable, sending the text in the variable. You can embed control codes in the text. These are defined in ASCII as ^A through ^Z corresponding to ASCII values 1 through 31 respectively. Thus ^G is a beep, ^M is a carriage return, ^J is a linefeed, etc. Example: SEND “Hello Over There^M” This example sends the string followed by a carriage return. Example: INPUT “Enter Your Name”, UserName SEND UserName SEND “^M^J” This example asks the user for his/her name, and sends it followed by a Carriage Return (^M)/Line Feed (^J) (CR/LF).
SETTINGS	Specifies the baud rate, parity, data bits, and stop bits. By default, scripts use the current port with its current settings if the communications port is opened. Syntax: <SETTINGS string> Example: SETTINGS “9600,N,8,1” The setting string is composed of four settings and has the following format: “BBBBB,P,D,S” (BBBBB is the baud rate, P is the parity, D is the number of data bits, and S is the number of stop bits.)
STOP	Stops program execution. Use this command to debug your scripts. When a script encounters the STOP command, pfs/Async stops program execution.Syntax: <STOP>
TIMEOUT	Specifies the number of seconds that WAITFOR waits before timing out. Syntax: <TIMEOUT n%> Example: TIMEOUT 30 This example waits 30 seconds before timing out.
UPLOAD	Uploads (transmits) a file. Syntax: <UPLOAD [filename]> Example: PROTOCOL “ZMODEM” UPLOAD “C:\MYPROG\ZIPFILE.ZIP” This example sends the file C:\MYPROG\ZIPFILE.ZIP via Zmodem. Example:PROTOCOL “ZMODEM” UPLOAD “.” This example sends a file via Zmodem. Example:PROTOCOL “COMPUSERVE” UPLOAD This example sends a file via Compuserve B+. With the CompuServe protocol, the file name is not sent. This is because the remote side of a CompuServe transfer session does not require a file name.
WAITFOR	Waits to receive a string over the communications port. Syntax: <WAITFOR string> Example:TIMEOUT 30 DIAL “555-1212” WAITFOR “What Is Your Name?” SEND “ModemWare^M” This example dials 555-1212 and waits up to 30 seconds (specified by TIMEOUT) after connecting to receive “What Is Your Name?” from the host system, and sends ModemWare followed by a carriage return (^M ). If there is timeout or any other error in the WAITFOR script command, the script status is set to FAILURE until the next successful file transfer.

Table 3-6: Asynchronous communication script commands

Script command

Description

CAPTURE

Opens a specified capture file and logs all received data to that file.

Syntax: <CAPTURE filename>

Example: CAPTURE “C:\CSERVE.TXT”

CLOSECAPTURE

Closes a capture file opened previously with a CAPTURE command.

Syntax: <CLOSECAPTURE>

DIAL

Dials a phone number and connects to a host modem.

Example: DIAL “555-1212”,

10 WAITFOR “Press Enter to Continue”

SEND “^M”

This example dials 555-1212. The second argument (10) specifies the number of retries if the line is busy. After a connection is made, it waits to receive “Press Enter to Continue” and then sends a carriage return (^M).

DOWNLOAD

Downloads (receives) a file.

Syntax: <DOWNLOAD [filename]>

Example: PROTOCOL “XMODEM-CRC”

DOWNLOAD “C:\MYPROG\ZIPFILE.ZIP”

This example receives the file C:\MYPROG\ZIPFILE.ZIP via Xmodem-CRC.

Example: PROTOCOL “ZMODEM”

This example receives a file via ZMODEM.

With the ZMODEM, YMODEM, and YMODEM–G protocols, the filename is not specified because the remote side of a ZMODEM transfer session does not require a file name.

END

Ends the script, but does not close the communications port.

Syntax: <END>

HANGUP

Hangs up the phone (disconnects the modem), but does not close communications port.

INPUT

Prompts the user for a string and stores the inputted data string in a specified variable.

Syntax: <INPUT MsgStr, VariableName>

Example: INPUT “Enter Your Password”, PassWord

SEND PassWord

SEND “^M”

This example displays an input dialog box with the message, “Enter Your Password” and stores the entered text in a variable named PassWord. The stored text in PassWord is sent out the communications port followed by a carriage return (^M).

: (LABEL)

Specifies a label. Like batch files, any word that starts with a colon is treated as a label.

Syntax: <:label>

Example: :JumpHere

ON TIMEOUT GOTO

Tells the script to jump to a specified label when a timeout occurs. A timeout can be caused by a busy signal on the other end of the line, accessing an inactive modem, etc.

Syntax: <ON_TIMEOUT_GOTO: label>

Example: ON_TIMEOUT_GOTO :JumpHere

PAUSE

Pauses for a specified number of seconds.

Syntax: <PAUSE n>

Example: PAUSE 1

This example causes the program to wait one second.

Sometimes a pause is required to smooth out the communications process, such as in between a WAITFOR and a SEND command. This may require experimentation.

PORT

Specifies which port to use and opens the port. If no port is specified, scripts use the current port with its current settings.

Syntax: <PORT n>

Example: PORT 2

This example causes COM2 to be used as the port and opened.

PROTOCOL

Sets the file transfer protocol.

Syntax: <PROTOCOL protocol>

Example: PROTOCOL “ZMODEM”

Protocol is one of the following string identifiers:

XMODEM YMODEM-G

XMODEM-CRC ZMODEM

XMODEM-1 KKERMIT

YMODEM COMPUSERVE

You must issue this command to set the protocol before a DOWNLOAD command or an UPLOAD command. If you do not, the script uses the current protocol setting for the PDQComm control.

SEND

Sends a string out of the communications port. The Send command treats an unquoted string as a variable, sending the text in the variable. You can embed control codes in the text. These are defined in ASCII as ^A through ^Z corresponding to ASCII values 1 through 31 respectively. Thus ^G is a beep, ^M is a carriage return, ^J is a linefeed, etc.

Example: SEND “Hello Over There^M”

This example sends the string followed by a carriage return.

Example: INPUT “Enter Your Name”, UserName

SEND UserName

SEND “^M^J”

This example asks the user for his/her name, and sends it followed by a Carriage Return (^M)/Line Feed (^J) (CR/LF).

SETTINGS

Specifies the baud rate, parity, data bits, and stop bits. By default, scripts use the current port with its current settings if the communications port is opened.

Syntax: <SETTINGS string>

Example: SETTINGS “9600,N,8,1”

The setting string is composed of four settings and has the following format:

“BBBBB,P,D,S” (BBBBB is the baud rate, P is the parity, D is the number of data bits, and S is the number of stop bits.)

STOP

Stops program execution. Use this command to debug your scripts. When a script encounters the STOP command, pfs/Async stops program execution.Syntax: <STOP>

TIMEOUT

Specifies the number of seconds that WAITFOR waits before timing out.

Syntax: <TIMEOUT n%>

Example: TIMEOUT 30

This example waits 30 seconds before timing out.

UPLOAD

Uploads (transmits) a file.

Syntax: <UPLOAD [filename]>

Example: PROTOCOL “ZMODEM”

UPLOAD “C:\MYPROG\ZIPFILE.ZIP”

This example sends the file C:\MYPROG\ZIPFILE.ZIP via Zmodem.

Example:PROTOCOL “ZMODEM”

UPLOAD “*.*”

This example sends a file via Zmodem.

Example:PROTOCOL “COMPUSERVE”

UPLOAD

This example sends a file via Compuserve B+.

With the CompuServe protocol, the file name is not sent. This is because the remote side of a CompuServe transfer session does not require a file name.

WAITFOR

Waits to receive a string over the communications port.

Syntax: <WAITFOR string>

Example:TIMEOUT 30

DIAL “555-1212”

WAITFOR “What Is Your Name?”

SEND “ModemWare^M”

This example dials 555-1212 and waits up to 30 seconds (specified by TIMEOUT) after connecting to receive “What Is Your Name?” from the host system, and sends ModemWare followed by a carriage return (^M ). If there is timeout or any other error in the WAITFOR script command, the script status is set to FAILURE until the next successful file transfer.