WAITFOR

Specifies a pause until specific conditions are met.

Syntax

Details

Comparisons

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.

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

time-clause<:timeout-label>

time-clause: specifies a time period in the form n SECONDS.

n is the number of seconds that the client waits before processing continues. 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 that exists 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 is specified after the WAITFOR statement.

text-clause<:text-label>

text-clause

specifies a string that the client waits to receive from the server. The string can be the following

a character string that is enclosed in quotation marks
a hexadecimal string that is enclosed in quotation marks

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

:text-label: specifies the label of a statement that exists 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 is specified after the WAITFOR statement.

Details

The WAITFOR statement directs SAS on the client to do one of the following:

pause for a specified time
pause for a specified time or until specified characters from the server are received
pause until specified characters from the server are received

Usually, a WAITFOR statement is used after a TYPE statement sends input to the server that causes the client to wait for the server's response to the input. For example, in the sample scripts, a WAITFOR statement follows the TYPE statement that invokes SAS on the server.

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.

Comparisons

You must specify either a time clause or a text clause in the WAITFOR statement. Or you can specify multiple text clauses or 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 client waits the specified time for the specified characters from the server. If the client 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 client pauses for 5 seconds and reads any input sent by the server:
```
waitfor 'Enter your password',
   5 seconds :nohost;
```
If the following string is sent by the server 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. For example:
```
waitfor 'Enter your password' :startlnk,
   5 seconds :nohost;
```
This WAITFOR statement is the same as the preceding example except that a label is specified after the text clause. Therefore, if the following string is sent by the server 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 client waits indefinitely for the specified text response from the server. Usually, you should 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, so only one of the text clauses needs to be satisfied (true).