Answers to frequently asked REXX questions

In addition, a comma can be used in the template for PARSE ARG to indicate that the next argument becomes the input string for the following portion of the template.

In its simplest form, the PARSE instruction is used to separate a string into words. A word is considered to be a string of non-blank characters delimited by one or more spaces. When used to separate words, the PARSE instruction processes multiple spaces as if they were a single space. Each successive word, from left to right, is assigned to the variable names specified in the template with special consideration given to the last word. Every variable name included in the template is assigned a new value. If more words exist than there are variable names; everything following the word assigned to the next to the last variable, including the remaining spaces, is assigned to the last variable. Here is an example:

   PARSE VALUE 'The  quick red   fox' WITH,
      a,
      b,
      c

This will result in "The" being assigned to the variable a, "quick" being assigned to the variable b, and "red fox" being assigned to the variable c.

If four variables were specified in the template in this example rather than three, then the first three words would be assigned to the first three variables with the surrounding spaces having been stripped prior to the assignment. The last variable would still have leading spaces though. These spaces could be removed using the STRIP() built-in function in another assignment statement.

If more variables are specified in the template than there are words in the source string, the extra variables are assigned a null string value ('').

A literal string may be used to specify the delimiter that the PARSE instruction uses rather than the implied delimiter of a space. Any number of literal strings and variable names may be specified. For example:

   PARSE VALUE 'Thurs.,   Sept. 29, 1994' WITH,
      day_abbrev ',',
      month_day_year

would result in "Thurs." being assigned to the variable day_abbrev and " Sept. 29, 1994" (note the leading spaces). However,

   PARSE VALUE 'Thurs.,   Sept. 29, 1994' WITH,
      day_abbrev ',',
      month,
      day,
      year

will result in the value "Thurs." being assigned to the variable day_abbrev and the values "Sept.", "29,", and "1994" being assigned to the variables month, day, and year respectively without any extraneous spaces.

Any combination of delimiters may be used in a single parse instruction. If the delimiter is assigned to a variable, the variable name must be enclosed within parentheses. The above example could be written as:

   comma = ','
   PARSE VALUE 'Thurs.,   Sept. 29, 1994' WITH,
      day_abbrev (comma),
      month,
      day,
      year

The next variation of the parsing template is the numeric positional pattern. This is similar to the literal string shown above except that the numeric positional pattern indicates the position at which the next token from the source string begins. In the following example, all spaces are single spaces:

   PARSE VALUE 'Thurs., Sept. 29, 1994' WITH,
      day_abbrev  6,
      .      9,
      month 15,
      day   19,
      year

results in "Thurs." being assigned to the variable day_abbrev, the period placeholder results in the comma and space being bypassed and the values "Sept. ", "29, ", and "1994" being assigned to the variables month, day, and year, respectively. Both month and day would contain a trailing space.

The template may contain a pattern of relative positional values rather than absolute values. The positional numbers may be relative to the last number used;

therefore:

   PARSE VALUE 'Thurs., Sept. 29, 1994' WITH,
      day_abbrev +6,
      .          +2,
      month      +6,
      day        +4,
      year

would yield the identical result as the previous example.

As with literal string patterns, the positional patterns can be specified as a variable by inserting the variable name in the template enclosed in parentheses, in place of the number. An absolute position number is indicated by the use of an equal sign (=). The relative indicator (+, - or =) must precede the left parenthesis. Therefore, the above example could also be written as:

   abbrev_lgth = 7
   month_pos   = abbrev_lgth + 2
   day_pos     = month_pos + 6
   day_lgth    = 4
   PARSE VALUE 'Thurs., Sept. 29, 1994' WITH,
      day_abbrev =(abbrev_lgth),
      .          =(month_pos),
      month      =(day_pos),
      day        +(day_lgth),
      year

Function Usage

Functions play a very important role in REXX since they provide all of the facilities beyond those features provided by the limited keyword instruction set designed into REXX.

The functions provide access and control of OS/2 related functions and data. Other, third party external function modules are available both as freeware, from various OS/2 related BBSs, as shareware, and from commercial vendors.

All REXX functions may be either referenced with the CALL keyword instruction or used any place in a REXX clause where an expression is allowed.

When explicitly called, each parameter passed to the function, except the last, is terminated with a comma. For example, CALL DATE 'N' results in the system date, in the format dd Mon yyyy (where dd represents the current day, Mon represents the current month abbreviation, and yyyy represents the four digit year). This result is stored in the special REXX variable RESULT. The user program may then assign the contents of RESULT to another variable. A CALL to any other function causes the value returned by the call to the DATE() function to be replaced.

The above example could be written using the function as an expression. For example, todays_date = DAY('N'). When any function is used as an expression, the function name must be immediately followed by a left parenthesis (no intervening space is allowed). Any number of spaces may surround the fields which occur within the parenthesis.

It is obviously more meaningful to use the DATE() function as an expression; however, other functions, particularly where the value they return is not significant, are more meaningful to the observer when used with the CALL keyword instruction. Remember that the RESULT special variable is assigned a value when a function is used.

Trap Processing

REXX provides the user with the ability to "trap" unusual occurrences. Trap means to alter the program flow when a specified event occurs and provide the program with the information necessary to identify the event. there are six events which may be monitored: ERROR, FAILURE, HALT, NOTREADY, NOVALUE, and SYNTAX. Each of these conditions is briefly described in the rexx.inf file on your system and can be found by doing a search on the word signal.

While a full explanation of all of these six conditions goes beyond the scope of this column, I do want to describe the use of the NOVALUE condition and how it should be used.

Since REXX is an "untyped data structure" language (meaning that variables need not be previously defined prior to their use, many programmers feel uncomfortable when taking advantage of this convenience in the REXX language. Still others decry this coding style as a negative characteristic of the language.

Much of this negative criticism can be overcome by use of the NOVALUE condition associated with either the CALL or SIGNAL keyword instruction. Either of these two instructions, when used with the NOVALUE condition, cause program flow to be interrupted and redirected to the label specified within the CALL or SIGNAL clause to receive control when an initialized variable is used in a program for any purpose other than to assign a value to it.

When reference is made to variable b, control transfers to the label NOVALUE_TRAP since b is an uninitialized variable (it has not had a value assigned to it).

In summary, the CALL and SIGNAL instructions should always be used in REXX programs of any length to prevent the unintended use of uninitialized variables as well as other exception conditions that can occur within a REXX program.

Registering External Modules in startup.cmd

The RxFuncAdd() function makes a DLL known to the REXX interpreter in any given session. However, the entry points within the DLL are not really registered until one of two conditions occur: either the individual function entry points within the DLL must be called or referenced in an expression or an entry point designed into the DLL which registers all of the other entry points in the DLL must be referenced.

Once a function name, or entry point is registered, it is then available to all sessions. REXXUTIL, which is part of REXX distributed with OS/2 is a DLL that provides an entry point that allows all of the individual functions with the DLL to be registered. That entry point name is SysLoadFuncs.

Since almost every REXX program you use will want to have access to the various functions with REXXUTIL, and since a single CALL to SysLoadFuncs() results in all of the functions in the DLL being available to all other OS/2 sessions, by placing a registration call to REXXUTIL and its self-registering entry point in your startup.cmd file in the root directory of your OS/2 drive, it then will not be necessary to register REXXUTIL in any of your other REXX programs.