OS/2 Procedures Language 2/REXX


Inf-HTML [About][Toc][Index] 0.9b (c) 1995 Peter Childs


PARSE





 >>--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. 
Note:    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. 
 Note:    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"). 
 Note:    PARSE VERSION information should be parsed on a word basis 
          rather than on an absolute column position basis. 
   

Inf-HTML End Run - Successful