Purpose

>>-PARSE--+-------+--+-ARG-------------------------+------------>
'-UPPER-' +-EXTERNAL--------------------+
+-LINEIN----------------------+
+-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 page 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 (if it is enabled) is
raised.
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 on page 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
(see page ARG (Argument)). function.
- PARSE EXTERNAL
- This is a non-SAA subkeyword provided in REXX/CICS. 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 for special applications
(such as debugging) where the program stack cannot be disturbed.
- PARSE LINEIN
- This is the same as PARSE EXTERNAL.
- PARSE NUMERIC
- This is a non-SAA subkeyword provided in VM. The current
numeric controls (as set by the NUMERIC instruction, see page Purpose) 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 section
NUMERIC and the built-in functions in section
DIGITS, and section
FORM, and section
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. You can find the number of lines currently in the queue
with the QUEUED built-in function, see page 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 on page 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, they read from the console.
(See the PULL instruction,
on page Purpose,
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. It returns a source string containing
the following tokens:
- The characters CICS.
- The string COMMAND, FUNCTION, or SUBROUTINE depending on whether
the program was invoked as some kind of host command, from a function
call in an expression, by a CALL instruction, or as a server process.
- The name of the exec in uppercase. The name of the file (RFS),
or VSE Librarian Sublibrary from which the exec was originally loaded.
The three formats are:
- Library.sublibrary(member)
- RFS fully qualified file identifier
- Dataset name (member)
- Initial (default) host command environment that is always REXXCICS.
- Identifier of the specific CICS/ESA environment, which in this
case is REXX/CICS.
- PARSE VALUE
- parses the data that is the result of evaluating expression.
If you specify no expression, 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, 3.48).
- The language processor release date (for example, 05 April
2000).