PARSE

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 on 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 EXTERNAL and PARSE PULL, a data string is removed from the queue, for PARSE LINEIN (and PARSE PULL if the queue is empty), a line is taken from the default input stream, 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 the ARG instruction in ARG for details and examples.)

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

PARSE EXTERNAL

This is a subkeyword provided in z/VM. The next string from the terminal input buffer is parsed. This queue may contain data that is the result of external asynchronous events—such as user console input, or messages. If that queue is empty, a console read results. Note that this mechanism should not be used for typical console input, for which PULL is more general, but rather it could be used for special applications (such as debugging) when the program stack cannot be disturbed.

You can find the number of lines currently in the queue with the EXTERNALS built-in function. (See EXTERNALS.)

PARSE LINEIN

parses the next line from the default input stream. (See Input and Output Streams for a discussion of REXX input and output.) PARSE LINEIN is a shorter form of the instruction

If no line is available, program execution will usually pause until a line is complete. Note that PARSE LINEIN should be used only when direct access to the character input stream is necessary. Usual line-by-line dialogue with the user should be carried out with the PULL or PARSE PULL instructions, to maintain generality.

To check if any lines are available in the default input stream, use the built-in function LINES. (See LINES (Lines Remaining).) Also see LINEIN (Line Input) for a description of the LINEIN function.

PARSE NUMERIC

This is a subkeyword provided in VM. The current numeric controls (as set by the NUMERIC instruction, see NUMERIC) are available. 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 the PULL instruction in PULL.

Note: PULL and PARSE PULL read from the program stack. If that is empty, they read from the terminal input buffer; and if that too is empty, a console read results. (See the PULL instruction, PULL, for further details.)

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 characters CMS, followed by either COMMAND, FUNCTION, or SUBROUTINE, depending on whether the program was called as some kind of host command (for example, exec or macro), or from a function call in an expression, or with the CALL instruction. These two tokens are followed by the program file name, file type, and file mode; each separated from the previous token by one or more blanks. (The file type and file mode may be unknown if the program is being run from storage, in which case the SOURCE string has one * for each unknown value.) Following the file mode is the name by which the program was called (because of synonyms, this may not be the same as the file name). It may be in mixed case and is truncated to 8 characters if necessary. (If it cannot be determined, ? is used as a placeholder.) The final word is the initial (default) address for commands.

If the language processor was called from a program that set up a subcommand environment, the file type is usually the name of the default address for commands—see Issuing Subcommands from Your Program for details. Note that if a PSW is used for the default address, the PARSE SOURCE string uses ? in the initial address for commands position.

The string parsed might, therefore, look like this:

CMS COMMAND REXTRY EXEC * rext CMS

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 words delimited by blanks:

The string REXX370, signifying the 370 implementation
The language level description (for example, 4.00),
The language processor release date (for example, 31 May 1992).