WAITFOR

WAITFOR

Specifies a pause until conditions are met

All connections

Syntax
Syntax Description
Syntax
Syntax
Syntax
Usage Notes

Syntax

WAITFOR pause-specification-1
<. . . pause-specification-n >;

Syntax Description

pause-specification: is the criteria used to determine when the pause is terminated for the WAITFOR statement and processing continues.

Details

The WAITFOR statement directs the SAS System on the local host to do one of the following:

pause for a specified time
pause for a specified time or until specified characters from the remote host are received
pause until specified characters from the remote host are received.

Typically, a WAITFOR statement is used after a TYPE statement sends input to the remote host that causes the local host to wait for the remote host's response to the input. For example, in the sample scripts in Starting and Stopping SAS/CONNECT Software, a WAITFOR statement follows the TYPE statement that invokes the SAS System on the remote host. The WAITFOR statement is also used after any TYPE statement that sends a 3270 AID key to the remote host.

You can include one or more pause specifications in a WAITFOR statement. When you include more than one pause specification, use commas to separate the clauses.

The value of pause-specification can be either of the following:

time-clause<:timeout-label>

where

time-clause

specifies a time period in the form n SECONDS.
n is the number of seconds that the local host is to wait. If you specify 0 SECONDS, a time-out occurs almost immediately. In most cases, you should specify a value greater than 0. You can specify only one time clause in a WAITFOR statement.

:timeout-label

specifies the label of a statement later in the script. The label must be preceded by a colon (:). When you specify a label, script execution passes to the labeled statement after a time-out occurs. If no label is specified, execution proceeds with the statement that follows the WAITFOR statement.

<screen-location> text-clause<:text-label>

where

screen-location

indicates the screen location at which the specified text clause should be found. This specification applies only to 3270 connections. If screen-location is specified, it must precede the text-clause to which it applies. The screen location is specified by the following, where n is any valid column or row number:

<COL n><ROW n>

Maximum values depend on the 3270 model being emulated (see the following table). If you specify a row without a column, the WAITFOR statement scans all columns of the given row. If you specify a column without a row, all rows of the column are scanned. The entire screen is scanned if you do not include a screen specification.

text-clause

specifies a string that the local host waits to receive from the remote host. The string can be

a character literal enclosed in quotes

a hex string enclosed in quotes.

When text-clause is specified, the SAS System on the local host reads input from the remote host, searching for the specified string. With 3270 connections, the SAS System on the local host scans the remote host screen (instead of reading characters sequentially).

:text-label

specifies the label of a statement later in the script. The label must be preceded by a colon (:). When you specify a label, script execution passes to the labeled statement after a time-out (if the label follows a time clause) or after the specified string has been read (if the label follows a text clause). If no label is specified, execution proceeds with the statement that follows the WAITFOR statement.

Maximum Values for Screen Rows and Columns by 3270 Model Number
3270 Model Maximum Row Maximum Column

model 2 24 80

model 3 32 80

model 4 43 80

model 5 27 132

***Maximum Values for Screen Rows and Columns by 3270 Model Number***
3270 Model	Maximum Row	Maximum Column
model 2	24	80
model 3	32	80
model 4	43	80
model 5	27	132

Usage Notes

You must specify either a time clause or a text clause in the WAITFOR statement. Optionally, you can specify multiple text clauses, or you can combine a time clause and one or more text clauses. Labels and screen location specifications are optional.
If the only specification in the WAITFOR statement is a time clause, there is a pause during the script's execution. When the specified time has elapsed, control passes to the next statement in the script. For example, the following WAITFOR statement causes a 2-second pause in script execution:
```
waitfor 2 seconds;
```
If the WAITFOR statement contains a time clause followed by a label, a pause occurs and control passes to the labeled statement. The following WAITFOR statement causes a 2-second pause and then passes control to the script statement labeled STARTUP:
```
waitfor 2 seconds :startup;
```
If the WAITFOR statement contains a time clause and a text clause, the local host waits the specified time for the specified characters from the remote host. If the local host does not receive the expected characters before the time expires, a time-out occurs and control passes to the next statement or to the labeled statement (if a label is specified by the time clause). For example, when the following WAITFOR statement executes, the local host pauses for 5 seconds and reads any input sent by the remote host:
```
waitfor 'Enter your password', 
   5 seconds :nohost;
```
If the following string is sent by the remote host within 5 seconds, no time-out occurs and control passes to the next statement in the script:
```
Enter your password
```
If the string is not received within 5 seconds, a time-out occurs and control passes to the statement labeled NOHOST.
You can specify labels for both text clauses and time clauses, as in this example:
```
waitfor 'Enter your password' :startlnk, 
   5 seconds :nohost;
```
This WAITFOR statement is like the preceding example except that a label is specified after the text clause. Therefore, if the following string is sent by the remote host within 5 seconds, no time-out occurs and control passes to the statement labeled STARTLNK:
```
Enter your password
```
If the string is not received within 5 seconds, a time-out occurs and control passes to the statement labeled NOHOST, as in the previous example.
If you do not specify a time clause (that is, if you specify only a text clause), a time-out cannot occur, and the local host waits indefinitely for the specified text response from the remote host. Therefore, you should generally specify a time clause to avoid being trapped in an infinite wait.
If you specify multiple text clauses in a WAITFOR statement, the commas that separate the clauses imply a logical OR operator. In other words, only one of the text clauses needs to be satisfied (true).
The following is an example of a WAITFOR statement that uses a screen location specification (applicable to 3270 connections only):
```
waitfor row 20 'ready' 8 seconds :noready;
```
This statement directs the local host to wait for the string READY to appear somewhere on row 20. If the string is found, execution continues with the next script statement. If the string is not found, a time-out occurs after 8 seconds and control passes to the statement labeled NOREADY.

Chapter Contents
Previous
Next
Top of Page