PULL

>>-PULL--+---------------+--;----------------------------------><
         +-template_list-+

PULL reads a string from the head of the external data queue. (See Input and Output Streams for a discussion of Rexx input and output.) It is a short form of the following instruction:

>>-PARSE UPPER PULL--+---------------+--;----------------------><
                     +-template_list-+

The current head of the queue is read as one string. Without a template_list specified, no further action is taken and the string is thus effectively discarded. The template_list can be a single template or list of templates separated by commas, but PULL parses only one source string. Each template consists of one or more symbols separated by blanks, patterns, or both.

If you specify several comma-separated templates, variables in templates other than the first one are assigned the null string. The string is translated to uppercase (that is, lowercase a-z to uppercase A-Z) and then parsed into variables according to the rules described in Parsing. Use the PARSE PULL instruction if you do not desire uppercase translation.

Note: If the current data queue is empty, PULL reads from the standard input (typically, the keyboard). If there is a PULL from the standard input, the program waits for keyboard input with no prompt. The length of data read by the PULL instruction is restricted to the length of strings contained by variables.

Example:

Say "Do you want to erase the file?  Answer Yes or No:"
Pull answer .
if answer="NO" then say "The file will not be erased."

Here the dummy placeholder, a period (.), is used in the template to isolate the first word the user enters.

If the external data queue is empty, a line is read from the default input stream and the program pauses, if necessary, until a line is complete. (This is as though PARSE UPPER LINEIN had been processed. See PARSE LINEIN.)

The QUEUED built-in function (see QUEUED) returns the number of lines currently in the external data queue.