──PARSE─┬───────┬─┬──ARG───────────────────────┬─┬────────────┬─;─
└─UPPER─┘ ├──PULL──────────────────────┤ └──template──┘
├──SOURCE────────────────────┤ list
├──VALUE─┬────────────┬─WITH─┤
│ └─expression─┘ │
├──VAR──name─────────────────┤
└──VERSION───────────────────┘
PARSE is used to assign data from various sources to one or more variables according to the rules and templates described in the section on parsing in the OS/2 Procedures Language 2/REXX Reference.
If specified, a template is a list of symbols separated by blanks or patterns.
If template is not specified, no variables are set but action is taken to get the data ready for parsing if necessary. Thus, for PARSE PULL, a data string is removed from the current data queue; for PARSE LINEIN (and PARSE PULL if the current queue is empty), a line is taken from the default character 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 the UPPER option is specified, the data to be parsed is first translated to uppercase (for example, a lowercase a-z to an uppercase A-Z). Otherwise, no uppercase translation takes place during the parsing.
The data used for each variant of the PARSE instruction is as follows:
PARSE ARG - The strings passed to the program, subroutine, or function as the input argument list, are parsed. See the ARG instruction for details and examples.
┴╓: The argument strings to a REXX program or internal routine can also be retrieved or checked by using the ARG built-in function.
PARSE LINEIN - The next line from the default character input stream is parsed. (See the OS/2 Procedures Language 2/REXX Reference for a discussion of the REXX input model.) PARSE LINEIN is a shorter form of the following instruction:
──PARSE─VALUE─LINEIN()─WITH─┬──────────┬────;──
└─template─┘
If no line is available, program execution will normally pause until a line is complete. Note that PARSE LINEIN should only be used when direct access to the character input stream is necessary. Normal line-by-line dialogue with the user should be carried out with the PULL or PARSE PULL instructions, to maintain generality and programmability.
To check if any lines are available in the default character input stream, use the built-in function LINES.
PARSE PULL - The next string from the queue is parsed. If the queue is empty, lines will be read from the default input, typically the user's keyboard. 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 by using the QUEUED built-in function. The queue remains active as long as the language processor is active. The queue can be altered by other programs in the system and can be used as a means of communication between these programs and programs written in REXX.
┴╓: PULL and PARSE PULL read first from the current data queue; if the queue is empty, they read from the default input stream, STDIN (typically, the keyboard).
PARSE SOURCE - The data parsed describes the source of the program being run.
The source string contains the characters OS/2, followed by either COMMAND, FUNCTION, or SUBROUTINE, depending on whether the program was invoked as a host command or from a function call in an expression or using the CALL instruction. These two tokens are followed by the complete path specification of the program file.
The string parsed might, therefore, be displayed as:
OS/2 COMMAND C:\OS2\REXTRY.CMD
PARSE VALUE - The expression is evaluated, and the result is the data that is parsed. Note that WITH is a subkeyword in this context and so cannot be used as a symbol within expression. For example:
PARSE VALUE time() WITH hours ':' mins ':' secs
gets the current time and splits it up into its constituent parts.
PARSE VAR name - The value of the variable specified by name is parsed. The name must be a symbol that is valid as a variable name; that is, it can not start with a period or a digit. Note that the variable name is not changed unless it appears in the template. For example:
PARSE VAR string word1 string
removes the first word from string and puts it in the variable word1, and assigns the remainder back to string. Similarly:
PARSE UPPER VAR string word1 string
also translates the data from string to uppercase before it is parsed.
PARSE VERSION - Information describing the language level and the date of the language processor is parsed. This consists of five words (delimited by blanks): first the string "REXXSAA", then the language level description ("4.00"), and finally the release date ("13 June 1989").
┴╓: PARSE VERSION information should be parsed on a word basis rather than on an absolute column position basis.