Make your own free website on Tripod.com
2.4.14 The PARSE Instruction
     PARSE [ UPPER ] type [ template ] ;
          type = { ARG | LINEIN | PULL | SOURCE | VERSION }
          VALUE [ expr ] WITH
          VAR symbol

The PARSE instruction takes one or more source strings, and then
parses them using the template for directions. The process of
parsing is one where parts of a source string are extracted and
stored in variables. Exactly which parts, is determined by the
patterns.  A complete description of parsing is given in chapter
[not yet written].

Which strings are to be the source of the parsing is defined by
the type subclause, which can be any of:

ARG.
     The data to use as the source during the parsing is the
     argument strings given at the invocation of this procedure
     level. Note that this is the only case where the source may
     consist of multiple strings.

LINEIN.
     Makes the PARSE instruction read a line from the standard
     input stream, as if the LINEIN() built-in function had been
     called. It uses the contents of that line (after stripping
     off end-of-line characters, if necessary) as the source for
     the parsing. This may raise the NOTREADY condition if
     problems occurred during the read.

PULL.
     Retrieves as the source string for the parsing the topmost
     line from the stack. If the stack is empty, the default
     action for reading an empty stack is taken. That is, it will
     read a whole line from the standard input stream, strip off
     any end-of-line characters (if necessary), and use that
     string as the source.

SOURCE.
     The source string for the parsing is a string containing
     information about how this invocation of the REXX interpreter
     was started. This information will not change during the
     execution of a REXX script. The format of the string is:

          system invocation filename
          
     Here, the first space-separated word (system) is a single
     word describing the platform on which the system is running.
     Often, this is the name of the operating system. The second
     word describes how the script was invoked. TRL2 suggests that
     invocation could be COMMAND, FUNCTION, or SUBROUTINE, but
     notes that this may be specific to VM/CMS.

     Everything after the second word is implementation-dependent.
     It is indicated that it should refer to the name of the REXX
     script, but the format is not specified. In practice, the
     format will differ because the format of file names differs
     between various operating systems. Also, the part after the
     second word might contain other types of information. Refer
     to the implementation-specific notes for exact information.

VALUE expr WITH.
     This form will evaluate expr and use the result of that
     evaluation as the source string to be parsed. The token WITH
     may not occur inside expr, since it is a reserved subkeyword
     in this context.

VAR symbol.
     This form uses the current value of the named variable symbol
     (after tail-substitution) as the source string to be parsed.
     The variable may be any variable symbol. If the variable is
     uninitialized, then a NOTREADY condition will be raised.

VERSION.
     This format resembles SOURCE, but it contains information
     about the version of REXX that the interpreter supports. The
     string contains five words, and has the following format:

          language level date month year

     Where language is the name of the language supported by the
     REXX interpreter. This may seem like overkill, since the
     language is REXX, but there may be various different dialects
     of REXX. The word can be just about anything, except for two
     restrictions, the first four letters should be REXX (in upper
     case), and the word should not contain any periods. [TRL2]
     indicates that the remainder of the word (after the fourth
     character) can be used to identify the implementation.

     The second word is the REXX language level supported by the
     interpreter. Note that this is not the same as the version of
     the interpreter, although several implementations makes this
     mistake.  Strictly speaking, neither [TRL1] nor [TRL2] define
     the format of this word, but a numeric format is strongly
     suggested.

     The last three words (date, month, and year) makes up the
     date part of the string.  This is the release date of the
     interpreter, in the default format of the DATE() built-in
     function.

Much confusion seems to be related to the second word of PARSE
VERSION. It describes the language level, which is not the same as
the version number of the interpreter. In fact, most interpreters
have a version numbering which is independent of the REXX language
level. Unfortunately, several interpreters makes the mistake of
using this field as for their own version number. This is very
unfortunate for two reasons; first, it is incorrect, and second,
it makes it difficult to determine which REXX language level the
interpreter is supposed to support.

Chances are that you can find the interpreter version number in
PARSE SOURCE or the first word of PARSE VERSION.

The format of the REXX language level is not rigidly defined, but
TRL1 corresponds to the language level 3.50, while TRL2
corresponds to the language level 4.00. Both implicitly indicate
the that language level description is a number, and states that
an implementation less than a certain number “may be assumed to
indicate a subset” of that language level. However, this must not
be taken to literally, since language level 3.50 has at least two
features which are missing in language level 4.00 (the Scan trace
setting, and the PROCEDURE instruction that is not forced to be
the first instruction in a subroutine). [TRH:PRICE] gives a very
good overview over the varying functionality of different language
levels of REXX up to level 4.00.

With the release of the ANSI REXX Standard [ANSI] in 1996, the
REXX language IS now rigidly defined.  The language level of ANSI
REXX is 5.00. Regina is attempting to keep pace with the ANSI
Standard.  It includes some features of language level 5.00 such
as date and time conversions in the DATE() and TIME() BIFs plus
the new BIFs COUNTSTR() and CHANGESTR().  Regina does not supply
multiple-level error messages as defined in the ANSI Standard, so
does not comply to language level 5.00, but currently is a hybrid
between 4.00 and 5.00. Thus PARSE VERSION will return 4.50 :-)

Note that even though the information of the PARSE SOURCE is
constant throughout the execution of a REXX script, this is not
necessarily correct for the PARSE VERSION. If your interpreter
supports multiple language levels (e.g. through the OPTIONS
instruction), then it will have to change the contents of the
PARSE VERSION string in order to comply with different language
levels. To some extent, this may also apply to PARSE SOURCE, since
it may have to comply with several implementation-specific
standards.

After the source string has been selected by the type subclause in
the PARSE instruction, this string is parsed into the template.
The functionality of templates is common for the PARSE, ARG and
PULL instructions, and is further explained in chapter [not yet
written].



PREV NEXT