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

PULL reads a string from the head of the external data queue or, if the external data queue is empty, from the standard input stream (typically the keyboard). (See Chapter 14, 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 whitespace, 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 Chapter 9, Parsing. Use the PARSE PULL instruction if you do not desire uppercase translation.

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 Section 7.4.48, “QUEUED”) returns the number of lines currently in the external data queue.