>>-PARSE--+-------+--+-ARG-----------------------+-------------->
          '-UPPER-'  +-EXTERNAL------------------+   
                     +-NUMERIC-------------------+   
                     +-PULL----------------------+   
                     +-SOURCE--------------------+   
                     +-VALUE-+------------+-WITH-+   
                     |       '-expression-'      |   
                     +-VAR--name-----------------+   
                     '-VERSION-------------------'   

>--+---------------+--;----------------------------------------><
   '-template_list-'      

PARSE assigns data (from various sources) to one or more variables according to the rules of parsing (see Parsing).

The template_list is often a single template but may be several templates separated by commas. If specified, each template is a list of symbols separated by blanks or patterns or both.

Each template is applied to a single source string. Specifying multiple templates is never a syntax error, but only the PARSE ARG variant can supply more than one non-null source string. See Parsing multiple strings for information about parsing multiple source strings.

If you do not specify a template, no variables are set but action is taken to prepare the data for parsing, if necessary. Thus for PARSE PULL, a data string is removed from the queue, and for PARSE VALUE, expression is evaluated. For PARSE VAR, the specified variable is accessed. If it does not have a value, the NOVALUE condition is raised, if it is enabled.

If you specify the UPPER option, the data to be parsed is first translated to uppercase (that is, lowercase a–z to uppercase A–Z). Otherwise, no uppercase translation takes place during the parsing.

The following list describes the data for each variant of the PARSE instruction.

PARSE ARG

parses the string or strings passed to a program or internal routine as input arguments. See ARG for details and examples of the ARG instruction.

Tip: You can also retrieve or check the argument strings to a REXX program or internal routine with the ARG built-in function (see ARG (Argument)).

PARSE EXTERNAL

In TSO/E, PARSE EXTERNAL reads from the:

• Terminal (TSO/E foreground)
• Input stream, which is SYSTSIN (TSO/E background).

In non-TSO/E address spaces, PARSE EXTERNAL reads from the input stream as defined by the file name in the INDD field in the module name table (see Module name table). The system default is SYSTSIN. PARSE EXTERNAL returns a field based on the record that is read from the INDD file. If SYSTSIN has no data, the PARSE EXTERNAL instruction returns a null string.

PARSE NUMERIC

The current numeric controls (as set by the NUMERIC instruction) are available (see NUMERIC). These controls are in the order DIGITS FUZZ FORM.

Example:

Parse Numeric Var1

After this instruction, Var1 would be equal to: 9 0 SCIENTIFIC. See NUMERIC and the built-in functions DIGITS, FORM, and FUZZ.

PARSE PULL

parses the next string from the external data queue. If the external data queue is empty, PARSE PULL reads a line from the default input stream (the user's terminal), and the program pauses, if necessary, until a line is complete. You can add data to the head or tail of the queue by using the PUSH and QUEUE instructions, respectively. You can find the number of lines currently in the queue with the QUEUED built-in function. (See QUEUED.) Other programs in the system can alter the queue and use it as a means of communication with programs written in REXX. See also PULL for the PULL instruction.

PULL and PARSE PULL read from the data stack. In TSO/E, if the data stack is empty, PULL and PARSE PULL read from the:

• Terminal (TSO/E foreground)
• Input stream, which is SYSTSIN (TSO/E background).

In non-TSO/E address spaces, if the data stack is empty, PULL and PARSE PULL read from the input stream as defined by the file name in the INDD field in the module name table (see Module name table). The system default is SYSTSIN. If SYSTSIN has no data, the PULL and PARSE PULL instructions return a null string.

PARSE SOURCE

parses data describing the source of the program running. The language processor returns a string that is fixed (does not change) while the program is running.

The source string contains the following tokens:

1. The characters TSO
2. The string COMMAND, FUNCTION, or SUBROUTINE depending on whether the program was called as some kind of host command (for example, as an exec from TSO/E READY mode), or from a function call in an expression, or using the CALL instruction.
3. Usually, name of the exec in uppercase. If the name is not known, this token is a question mark (?). If the name is an extended execname, this field is the full name, possibly greater than 8-characters and not converted to uppercase. If the execname contains any blank characters (which is possible in an execname of file system), the blank characters are replaced by null characters (X'00') within this token. See Format of the exec block and Format of the in-storage control block for more information about how the exec load routine can load an extended execname.
4. Name of the DD from which the exec was loaded. If the name is not known, this token is a question mark (?).
5. Name of the data set from which the exec was loaded. If the name is not known, this token is a question mark (?). If the name contains any blank characters (which is possible in a dsname of file system), the blank characters are replaced by null characters (X'00') within this token.
6. Name of the exec as it was called, that is, the name is not folded to uppercase. If the name is not known, this token is a question mark (?).

   If the name returned in token3 is an extended name, this token is a question mark (?).

7. Initial (default) host command environment in uppercase. For example, this token may be TSO or MVS™.
8. Name of the address space in uppercase. For example, the value may be MVS (non-TSO/E) or TSO/E or ISPF. If the exec was called from ISPF, the address space name is ISPF.

   The value is taken from the parameter block (see Characteristics of a Language Processor Environment). Note that the initialization exit routines may change the name specified in the parameters module. If the name of the address space is not known, this token is a question mark (?).

9. Eight character user token. This is the token that is specified in the PARSETOK field in the parameters module (see Characteristics of a Language Processor Environment).

For example, the string parsed might look like one of the following:

TSO COMMAND PROGA SYSXR07 EGGERS.ECE.EXEC ? TSO TSO/E ?

TSO SUBROUTINE PROGSUB SYSEXEC ? ? TSO ISPF ?

TSO SUBROUTINE /u/cmddir/pgm.cmd PATH /u/cmddir/pgm.cmd
? SH OMVS OpenMVS

PARSE VALUE

parses the data that is the result of evaluating expression. If you specify no expression, then the null string is used. Note that WITH is a subkeyword in this context and cannot be used as a symbol within expression.

Thus, for example:

PARSE VALUE time() WITH  hours ':' mins ':' secs

gets the current time and splits it into its constituent parts.

PARSE VAR name

parses the value of the variable name. The name must be a symbol that is valid as a variable name (that is, it cannot start with a period or a digit). Note that the variable name is not changed unless it appears in the template, so that for example:

PARSE VAR string word1 string

removes the first word from string, puts it in the variable word1, and assigns the remainder back to string. Similarly

PARSE UPPER VAR string word1 string

in addition translates the data from string to uppercase before it is parsed.

PARSE VERSION

parses information describing the language level and the date of the language processor. This information consists of five blank-delimited words:

1. A word describing the language, which is the string “REXX370”
2. The language level description, for example, “3.46”
3. Three tokens describing the language processor release date, for example, “31 May 2001”.