Liren Large Software Subsidy 14/14.iso/s/s003/16.ddi/REXXPUBS/OS2_BOOK_REXX.INF

OS/2 Help File | 1992-03-30 | 195.5 KB | 7,073 lines

ΓòÉΓòÉΓòÉ 1. The OS/2 Procedures Language 2/REXX ΓòÉΓòÉΓòÉ

The OS/2* Procedures Language 2/REXX (referred to as REXX for the rest of this
information) is designated as the Systems Application Architecture* Procedures
Language for the Office Vision family of products and the OS/2 operating
system.  It was designed to make programming easier to write and debug.
High-quality programming can now be achieved using common English words in a
natural syntax flow that both beginning and experienced programmers can
understand.

REXX uses a few powerful, general-purpose programming functions and common
arithmetical abilities, as well as OS/2 commands, within a simple framework.
Existing batch files can be converted to REXX procedures, with more power and
function.

REXX files only operate in OS/2 sessions, must have a file name extension of
.CMD, and must start with a comment line (/*....*/).  As in batch files, it is
not necessary to type the .CMD extension to start a REXX procedure.

This Information:

This online REXX information is designed to acquaint you with the REXX
language, show you some of its features and capabilities, and give you a  basic
understanding of how it works.  The sections from "Getting Started.." to
"PMREXX" are written as an overview, stressing general concept information,
while the sections on "Instructions" and "Functions" include specific
information about all of the instructions and functions that are part of REXX.
For more complete and detailed information about REXX, see the OS/2 Procedures
Language 2/REXX Reference or User's Guide.


ΓòÉΓòÉΓòÉ 2. Getting Started in REXX ΓòÉΓòÉΓòÉ

A REXX procedure is a program that consists of a series of tasks in one common
processing file or batch file.

Many languages can be used to write programs. BASIC, which is widely used in
home computing, has very few rules, but it requires writing many lines of code
for an intricate program.  Languages such as PL/1, COBOL, C, APL, and PASCAL
have more rules, but allow you to write more functions in fewer lines.

REXX combines the simplicity of a programming language such as BASIC with
features that exist in more powerful languages such as writing fewer lines.  It
is easier to learn, because it uses familiar words and concepts.  REXX allows
you to do simple tasks, yet has the ability to handle complex tasks.

To get started in REXX, you need:

o A Personal Computer with OS/2 Version 2.0 installed.  REXX works only in OS/2
  sessions.
o Knowledge about using a text editor.

Many of us learn by looking at examples, so examples of REXX procedures are
provided in this presentation. First look at the procedure, then study the
explanation of the examples to see what the procedure contains.  If you like,
try the procedure to see how it works.


ΓòÉΓòÉΓòÉ 2.1. Writing a REXX Procedure ΓòÉΓòÉΓòÉ

We shall write the following REXX procedure using a text editor. To write a
REXX procedure named HELLO.CMD while using the text editor follow these
instructions:

 1. Create a text file named HELLO.CMD.
 2. Type the procedure HELLO.CMD, as follows:

        /* An introduction to REXX */
        SAY "Hello! I am REXX"
        SAY "What is your name?"
        PULL who
         IF who = ""
          THEN
          SAY "Hello Stranger"
         ELSE
          SAY "Hello" who
        EXIT

 3. Save the file and exit from the text editor.

Now you are ready to run the REXX procedure you have written.  Type the name of
the procedure at the OS/2 command prompt and press Enter.

hello

When the procedure pauses, you can either type your name or press Enter to see
the other response.

A brief description of each part of HELLO.CMD follows:

/* An introduction to REXX */  A comment explains what the procedure is about.
A comment starts with a /* and ends with a */.  All REXX procedures must start
with a comment on line one and column one of the file.  The comment tells the
command processor that the procedure being run is a REXX procedure and
distinguishes it from simple batch files.

SAY "Hello! I am REXX." SAY "What is your name?"  These instructions cause the
words between the quotation marks to be displayed on your screen.

PULL who  The PULL instruction reads the response entered from the keyboard and
puts it into the system's memory.  Who is the name of the place in memory where
the user's response is put.  Any name can be used with the PULL instruction.

IF who = " "  The IF instruction tests a condition.  The test in this example
determines if who is empty.  It is empty if the user types a space and presses
Enter or just presses Enter.

THEN  Specifies that the instruction that follows is to be run, if the tested
condition is true.

SAY "Hello Stranger"  Displays Hello Stranger on the screen.

ELSE  Specifies that the instruction that follows is to be run if the tested
condition is not true.

SAY "Hello" who  Displays Hello on the screen, followed by whatever is in who.

EXIT  This instruction causes the procedure to stop.

Here is what would happen if a person named Bill tried the HELLO program:

[C:\]hello
Hello! I am REXX.
What is your name?

Bill

Hello BILL

[C:\]
If Bill does not type his name, but types a blank space, this happens:

[C:\]hello
Hello! I am REXX.
What is your name?

Hello Stranger

[C:\]


ΓòÉΓòÉΓòÉ 3. Using Fundamental REXX Elements ΓòÉΓòÉΓòÉ

This section gives you a chance to try some of the elements used in writing
REXX procedures.  Do not worry about making mistakes because you will be guided
through the steps.

Note:   When writing a REXX procedure, it is best to use one line for each
        element. If you want an element to span more than one line, you must
        put a comma (,) at the end of the line to indicate that the element
        continues on the next line.  If you want to put more than one element
        on a line, you must use a semicolon (;) to separate the elements.

A REXX procedure can contain any or all of the following elements:

o Comments
o Strings
o Instructions
o OS/2 Commands
o Assignments
o Labels
o Internal Functions.


ΓòÉΓòÉΓòÉ 3.1. Comments ΓòÉΓòÉΓòÉ

All REXX procedures must begin with a comment starting in column one of line
one.  The comment tells the command interpreter it is about to read and run a
REXX procedure. The symbols for a comment are:

/*          To mark the start of a comment

*/          To mark the end of a comment.

When the interpreter finds a /*, it stops interpreting; when it encounters a
*/, it begins interpreting again with the information following the symbol.
The comment can be a few words, no words, or several lines, as in the following
examples:

/* This is a comment. */

or,

SAY "'Be Prepared!'" /* This comment is on the same line
as the instruction and continues on to the next line */

You can use only /* */ to start a REXX procedure, but it is better to put a
brief description of the procedure between the comment symbols.

The comment can indicate the purpose of the procedure, the kind of input it can
handle, and the kind of output it produces. Comments help you understand the
procedure when you read it later, perhaps to add to it, improve it, or use it
elsewhere in the same procedure or another procedure.

When you write procedures, remember that others may need to use or modify them.
It is a good idea to add comments to the instructions so that anyone can
understand each step.  If you do not use a procedure often, it is helpful to
have reminders to aid your memory. In general, explain your procedure well
enough so that others can understand it.


ΓòÉΓòÉΓòÉ 3.2. Strings ΓòÉΓòÉΓòÉ

A string is any group of characters inside single or double quotation marks.
Either type of quotation marks can be used, but the beginning and the ending
mark must match.  The interpreter stops interpreting when it sees a quotation
mark and the characters that follow remain as they were typed, with uppercase
and lowercase letters.  The interpreter resumes interpreting when it sees a
matching quotation mark.  For example:

'The Greatest Show on Earth'
"The President leads his country"

are both strings.

To use an apostrophe (single quotation mark) or double quotation marks within a
string, use the other quotation mark around the whole string.  For example:

"Don't count your chickens before they hatch."

or

'Do not count your "chickens" before they hatch.'

You also can use a pair of quotation marks (the same as those used to mark the
string) as follows:

SAY "Mary said  ""He's here."""

This is interpreted by REXX as:

Mary said  "He's here."


ΓòÉΓòÉΓòÉ 3.3. Instructions ΓòÉΓòÉΓòÉ

An instruction tells the system to do something.  Instructions can contain one
or more assignments, labels, or commands and they usually start on a new line.
The following are explanations of some of the more common instructions.

SAY Instruction - The format for the SAY instruction is:

SAY expression

The expression can be something you want displayed on the screen or something
to be computed, such as an equation:

SAY 5 + 6 "= eleven"

This displays

11 = eleven

With the SAY instruction, anything not in quotation marks is changed to
uppercase or is processed.  If you want something to appear exactly as it is
typed, enclose it in quotation marks.

PULL and PARSE PULL Instructions -

In a procedure, the usual sequence of instructions is to use SAY to ask a
question and PULL to receive the answer.  The response typed by the user is put
into system memory.  The following procedure does not work correctly if the
PULL instruction comes before the SAY instruction.

Question:  What do you think happens when the following procedure, NAME.CMD, is
run?

/* Using the PULL Instruction */
SAY "Enter your name"
PULL name          /* Puts response
from user into memory */
SAY "Hello" name
EXIT

Answer:  NAME.CMD puts a name in memory and then displays that name anywhere in
the file that the word name appears without the protection of single or double
quotation marks.

If you tried the NAME procedure, you probably noticed that your name was
changed to uppercase.  To keep the characters as you type them, use the PARSE
PULL instruction.  Here is an example called CHITCHAT.CMD that uses the PARSE
PULL instruction:

/* Using the PARSE PULL Instruction */
SAY "Hello! Are you still there?"
SAY "I forgot your name.  What is it?"
PARSE PULL name
SAY name "Are you going to Richard's seminar?"
PULL answer
IF answer = "YES"
 THEN
 SAY "Good.  See you there!"
IF answer = "NO"
 THEN
 SAY "Sorry,  We will miss your input."
EXIT
The PARSE PULL instruction reads everything from the keyboard exactly as it is
typed, in uppercase or lowercase.  In this procedure, the name is displayed
just as you type it.  However, answer is changed to uppercase characters
because the PULL instruction was used.  This ensures that if yes, Yes, or YES
is typed, the same action is taken.

EXIT Instruction

The EXIT instruction tells the procedure to end.  The EXIT instruction should
be used in a procedure that contains subroutines.  Although the EXIT
instruction is optional in some procedures, it is good programming practice to
use it at the end of every procedure.


ΓòÉΓòÉΓòÉ 3.4. OS/2 Commands ΓòÉΓòÉΓòÉ

A command is a word, phrase, or abbreviation that tells the system to do
something.  In REXX, anything that is not a REXX instruction, assignment, or
label is considered a command.  For example, you can use OS/2 commands such as
COPY, BACKUP, PRINT, TYPE, and so on in your procedures.

Here is an example of using the OS/2 command, TYPE, in a REXX procedure:

/* Issuing commands in REXX */
TYPE hello.cmd
EXIT

This means that REXX will cause TYPE to be run.


ΓòÉΓòÉΓòÉ 3.5. Assignments ΓòÉΓòÉΓòÉ

An assignment tells the system that a string should be put in a special place
in system memory.  In the example:

Work = "Building 021"

the string Building 021 is stored as the value Work in system memory.  Because
Work can have different values (be reassigned to mean different things) in
different parts of the procedure, it is called a Variable.


ΓòÉΓòÉΓòÉ 3.6. Labels ΓòÉΓòÉΓòÉ

A label is any word that is followed by a colon (with no space between the word
and the colon) and is not in quotation marks.  For example:

MYNAME:

A label marks the start of a subroutine.  The following example shows one use
of a label (called error) within a procedure:

  .
  .
  .
IF problem  = 'yes' then SIGNAL error
  .
  .
  .
error:
   SAY 'Problem in your data'
   EXIT


ΓòÉΓòÉΓòÉ 4. Working with Variables and Arithmetic ΓòÉΓòÉΓòÉ

In this section, you will see how to use variables and arithmetic and how to
add comments throughout a procedure to describe how it works. Some of the
topics in this section include the following:

Variable                      A piece of data given a unique name

Value                         Contents of a variable

Operators                     Symbols used for arithmetic functions

Addition                      + operator

Subtraction                   - operator

Multiplication                * operator

Division                      /, //, % operators


ΓòÉΓòÉΓòÉ 4.1. Variables ΓòÉΓòÉΓòÉ

A variable is a piece of data with a varying value. Within a procedure, each
variable is known by a unique name and is always referred to by that name.

When you choose a name for a variable, the first character must be one of:

A B C...Z ! ? _

Lowercase letters are also allowed as a first letter.  The interpreter changes
them to uppercase.

The rest of the characters can be any of the preceding characters and also 0
through 9.


ΓòÉΓòÉΓòÉ 4.2. Value ΓòÉΓòÉΓòÉ

The value of a variable can change, but the name cannot.  When you name a
variable (give it a value), it is an assignment.  For example, any statement of
the form,

symbol = expression

is an assignment statement.  You are telling the interpreter to compute what
the expression is and put the result into a variable called a symbol.  It is
the same as saying, "Let symbol be made equal to the result of expression" or
every time symbol appears in the text of a SAY string unprotected by single or
double quotation marks, display expression in its place.  The relationship
between a variable and a value is like that between a post-office box and its
contents; The box number does not change, but the contents of the box may be
changed at any time.  Another example of an assignment is:

num1 = 10

The num1 assignment has the same meaning as the word symbol in the previous
example, and the value 10 has the same meaning as the word expression.

One way to give the variable num1 a new value is by adding to the old value in
the assignment:

num1 = num1 + 3

The value of num1 has now been changed from 10 to 13.

A special concept in REXX is that any variable that is not assigned a value
assumes the uppercase version of the variable as its initial value.  For
example, if you write in a procedure,

list = 2 20 40
SAY list

you see this on your screen:

2 20 40

As you can see, list receives the values it is assigned.  But if you do not
assign any value to list and only write,

SAY list

you see this on your screen:

LIST

Here is a simple procedure called VARIABLE.CMD that assigns values to
variables:

/* Assigning a value to a variable */
a = 'abc'
SAY a
b = 'def'
SAY a b
EXIT

When you run the VARIABLE procedure, it looks like this on your screen:

[C:\]VARIABLE
abc
abc def

[C:\]

Assigning values is easy, but you have to make sure a variable is not used
unintentionally, as in this example named MEETING.CMD:

/* Unintentional interpretation of a variable */
the='no'
SAY Here is the person I want to meet
EXIT

When the procedure is run, it looks like this:

[C:\]MEETING
HERE IS no PERSON I WANT TO MEET

[C:\]

To avoid unintentionally substituting a variable for the word, put the sentence
in quotation marks as shown in this example of MEETING.CMD, which assigns a
variable correctly:

/* Correct interpretation of a variable the*/
the= 'no'
SAY "Here is the person I want to meet"
EXIT


ΓòÉΓòÉΓòÉ 4.3. Working with Arithmetic ΓòÉΓòÉΓòÉ

Your REXX procedures may need to include arithmetic operations of addition,
subtraction, multiplication, and division.  For example, you may want to assign
a numeric value to two variables and then add the variables.

Arithmetic operations are performed the usual way.  You can use whole numbers
and decimal fractions.  A whole number is an integer, or any number that is a
natural number, either positive, negative, or zero, that does not contain a
decimal part (for example, 1, 25, or 50).  A decimal fraction contains a
decimal point (for example, 1.45 or 0.6).

Before you see how these four operations are handled in a procedure, here is an
explanation of what the operations look like and the symbols used.  These are
just a few of the arithmetic operations used in REXX.

Note:   The examples contain a blank space between numbers and operators so
        that you can see the equations better, but the blank is optional.

Operators - The symbols used for arithmetic (+ , -, *, /) are called operators
because they operate on the adjacent terms.  In the following example, the
operators act on the numbers (terms) 4 and 2:

SAY 4 + 2             /* says "6" */
SAY 4 * 2             /* says "8" */
SAY 4 / 2             /* says "2" */

Addition - The operator for addition is the plus sign (+).  An instruction to
add two numbers is:

SAY 4 + 2

The answer you see on your screen is 6.

Subtraction - The operator for subtraction is the minus sign (-).  An
instruction to subtract two numbers is:

SAY 8 - 3

The answer on your screen is 5.

Multiplication - The operator for multiplication is the asterisk (*).  An
instruction to multiply two numbers is:

SAY 2 * 2

The answer on your screen is 4.

Division - For division, there are several operators you can use, depending on
whether or not you want the answer expressed as a whole number.  For example,
for a simple division, the symbol is one slash (/). An instruction to divide
is:

SAY 7 / 2

The answer on your screen is 3.5.

To divide and return just a remainder, the operator is two slashes (//).  To
divide, and return only the whole number portion of an answer and no remainder,
the operator is the percent sign (%).

For examples showing you how to perform four arithmetic operations on
variables, select the Examples pushbutton.

Evaluating Expressions - Expressions are normally evaluated from left to right.
An equation helps to illustrate this point.  Until now, you have seen equations
with only one operator and two terms, such as 4 + 2.  Suppose you had this
equation:

9 - 5 + 4 =

The 9 - 5 would be computed first.  The answer, 4, would be added to 4 for a
final value: 8.

Some operations are given priority over others.  In general, the rules of
algebra apply to equations.  In this equation, the division is handled before
the addition:

10 + 8 / 2 =

The value is 14.

If you use parentheses in an equation, the interpreter evaluates what is in the
parentheses first.  For example:

(10 + 8) / 2 =

The value is 9.


ΓòÉΓòÉΓòÉ 4.4. Writing a REXX Arithmetic Procedure ΓòÉΓòÉΓòÉ

The following is an exercise that will serve as a review of some of the rules
used in the previous examples.  You are to write a procedure that adds two
numbers.  Name the procedure ADD.CMD.

Here is a list of what you need to do in this procedure:

 1. Identify and describe the REXX procedure.
 2. Tell the user to type numbers.
 3. Read the numbers typed and put them into system memory.
 4. Add two numbers and display the answer on the screen.
 5. Tell the interpreter to leave the procedure.

There are many ways to write procedures to accomplish the same task.  To make
it easier in this procedure, the user is asked for each number separately, then
the numbers are added.  The following is the thought process you might use to
write the procedure for ADD.CMD.

 1. First, what identifies a REXX procedure?  If you thought of a comment, you
    were right.
 2. Next, you need to tell the user to enter a number.  The SAY instruction
    prints a message on your screen.
 3. If the number is entered, it needs to be put into computer memory.  The
    PULL instruction collects a response and puts it in memory.
 4. An instruction requesting a second number can look just like the first
    instruction; the second number also needs to be put in memory.
 5. The next instruction is similar to one in the MATH procedure.  In one
    statement, it can tell the interpreter to add the two values in memory and
    display the sum on your screen.  This can be one instruction.  The
    instruction contains a string and the addition operation.
 6. Finally, the EXIT instruction is used to end the procedure.
 7. If you want to test this program, type the procedure listed here and file
    it.

        /* This procedure adds two numbers */
        SAY "Enter the first number."
        PULL num1
        SAY "Enter the second number."
        PULL num2
        SAY "The sum of the two numbers is" num1 + num2
        EXIT

To test ADD.CMD, type ADD at the OS/2 command prompt and try some numbers. Here
is what the procedure should look like when it is run, and your numbers are 3
and 12.

[C:\]ADD
Enter the first number.

3

Enter the second number.

12

The sum of the two numbers is 15

[C:\]


ΓòÉΓòÉΓòÉ 5. REXX Features ΓòÉΓòÉΓòÉ

Some features of REXX that you can use to write more intricate procedures will
be discussed in this section.  You will see how to have a procedure make
decisions by testing a value with the IF instruction.  You will also see how to
compare values and determine if an expression is true or false. A brief
description of the terms covered in this section follows below:

IF                            Used with THEN.  Checks if the expression is
                              true.  Makes a decision about a single
                              instruction.

THEN                          Identifies the instruction to be run if the
                              expression is true.

ELSE                          Identifies the instruction to be run if the
                              expression is false.

SELECT                        Tells the interpreter to select one of a number
                              of instructions.

WHEN                          Used with SELECT.  Identifies an expression to be
                              tested.

OTHERWISE                     Used with SELECT.  Indicates the instruction to
                              be run if expressions tested are false.

DO-END                        Indicates that a group of instructions should be
                              run.

NOP                           Indicates that nothing is to happen for one
                              expression.

Comparisons  > <  =           Indicates greater than, less than, equal to.

NOT Operator  ╨║ or \          Changes the value of a term from true to false,
                              or from false to true.

AND Operator  &               Gives the value of true if both terms are true.

OR Operator  |                Gives the value of true unless both terms are
                              false.


ΓòÉΓòÉΓòÉ 5.1. Making Decisions(IF  THEN) ΓòÉΓòÉΓòÉ

In the procedures discussed in earlier sections, instructions were run
sequentially.  In this section, you will see how you can control the order in
which instructions are run.  Depending upon the user's interaction with your
procedure, you may choose not to run some of your lines of code.

Two instructions that let you make decisions in your procedures are the IF and
SELECT instructions.  The IF instruction is similar to the OS/2 IF command-it
lets you control whether the next instruction is run or skipped.  The SELECT
instruction lets you choose one instruction to run from a group of
instructions.

The IF instruction is used with a THEN instruction to make a decision. The
interpreter runs the instruction if the expression is true; for example:

IF answer = "YES"
 THEN
 SAY "OK!"
In the previous example, the SAY instruction is run only if answer has the
value of YES.

Grouping Instructions Using DO and END

To tell the interpreter to run a list of instructions after the THEN
instruction, use:

DO
   Instruction1
   Instruction2
   Instruction3
END

The DO instruction and its END instruction tell the interpreter to treat any
instructions between them as a single instruction.


ΓòÉΓòÉΓòÉ 5.2. The ELSE Instruction ΓòÉΓòÉΓòÉ

ELSE identifies the instruction to be run if the expression is false.  To tell
the interpreter to select from one of two possible instructions, use:

IF expression
 THEN instruction1
ELSE instruction2

You could include the IF-THEN-ELSE format in a procedure like this:

IF answer = 'YES'
 THEN SAY 'OK!'
ELSE SAY 'why not?'
Try the next example, GOING.CMD, to see how choosing between two instructions
works.

/* Using IF-THEN-ELSE */
SAY "Are you going to the meeting?"
PULL answer
IF answer = "YES"
 THEN
 SAY "I'll look for you."
ELSE
 SAY "I'll take notes for you."
EXIT

When this procedure is run, this is what you will see on your screen:

[C:\]GOING
Are you going to the meeting?

yes

I'll look for you.

[C:\]


ΓòÉΓòÉΓòÉ 5.3. SELECT, END, WHEN, OTHERWISE, and NOP Instructions ΓòÉΓòÉΓòÉ

SELECT tells the interpreter to select one of a number of instructions.  It is
used only with WHEN, THEN, END, and sometimes, OTHERWISE.  The END instruction
marks the end of every SELECT group.  The SELECT instruction looks like this:

SELECT
   WHEN expression1
      THEN instruction1
   WHEN expression2
      THEN instruction2
   WHEN expression3
      THEN instruction3
...
OTHERWISE
   instruction
   instruction
   instruction
END

Note:   An IF-THEN instruction cannot be used with a SELECT instruction unless
        it follows a WHEN or OTHERWISE instruction.  You can read this format
        as follows:

o If expression1 is true, instruction1 is run.  After this, processing
  continues with the instruction following the END.  The END instruction
  signals the end of the SELECT instruction.
o If expression1 is false, expression2 is tested.  Then, if expression2 is
  true, instruction2 is run and processing continues with the instruction
  following the END.
o If, and only if, all of the specified expressions are false, then processing
  continues with the instruction following OTHERWISE.

This diagram shows the SELECT instruction:

A DO-END instruction could be included inside a SELECT instruction as follows:

SELECT
   WHEN expression1 THEN
      DO
        instruction1
        instruction2
        instruction3
     END
.
.
.

You can use the SELECT instruction when you are looking at one variable that
can have several different values associated with it.  With each different
value, you can set a different condition.

For example, suppose you wanted a reminder of weekday activities.  For the
variable day, you can have a value of Monday through Friday.  Depending on the
day of the week (the value of the variable), you can list a different activity
(instruction).  You could use a procedure such as the following, SELECT.CMD,
which chooses from several instructions.

Note:   A THEN or ELSE instruction must be followed by an instruction.

/* Selecting weekday activities */
SAY 'What day is it today?'
Pull day
SELECT
   WHEN day = 'MONDAY'
      THEN
      SAY 'Model A board meeting'
   WHEN day = 'TUESDAY'
      THEN
      SAY "My Team Meeting"
   WHEN day = 'WEDNESDAY'
      THEN NOP                 /* Nothing happens here */
   WHEN day = 'THURSDAY'
      THEN
      SAY "My Seminar"
   WHEN day = 'FRIDAY'
      THEN
      SAY "My Book Review"
OTHERWISE
   SAY  "It is the weekend, anything can happen!"
END
EXIT

NOP Instruction: If you want nothing to happen for one expression, use the NOP
(No Operation) instruction, as shown in the previous example for Wednesday.


ΓòÉΓòÉΓòÉ 5.4. True and False Operators ΓòÉΓòÉΓòÉ

Determining if an expression is true or false is useful in your procedures.  If
an expression is true, the computed result is 1.  If an expression is false,
the computed result is 0.  The following shows some ways to check for true or
false operators.

Comparisons - Some operators you can use for comparisons are:

>             Greater than

<             Less than

=             Equal to

Comparisons can be made with numbers or can be character-to-character.  Some
numeric comparisons are:

The value of 5 > 3 is 1       This result is true.

The value of 2.0 = 002 is 1   This result is true.

The value of 332 < 299 is 0   This result is false.

If the terms being compared are not numbers, the interpreter compares
characters.  For example, the two words (strings) airmail and airplane when
compared character for character have the first three letters the same.  Since
m < p, airmail < airplane.

Equal - An equal sign (=) can have two meanings in REXX, depending on its
position.  For example,

amount = 5              /* This is an assignment */

gives the variable amount, the value of 5. If an equal sign is in a statement
other than as an assignment, it means the statement is a comparison.  For
example,

SAY amount = 5           /* This is a comparison  */

compares the value of amount with 5.  If they are the same, a 1 is displayed,
otherwise, a 0 is displayed.

For more examples of using comparisons, select the Examples pushbutton.


ΓòÉΓòÉΓòÉ 5.5. The Logical Operators, NOT, AND, OR ΓòÉΓòÉΓòÉ

Logical operators can return only the values of 1 or 0.  The NOT operator (╨║ or
\) in front of a term reverses its value either from true to false or from
false to true.

SAY  \ 0         /* gives '1'         */
SAY  \ 1         /* gives '0'         */
SAY  \ (4 = 4)   /* gives '0'         */
SAY  \ 2         /* gives  a  syntax error      */

The AND operator (&) between two terms gives a value of true only if both terms
are true.


SAY ( 3 = 3 ) & ( 5 = 5 )   /* gives '1'                     */
SAY ( 3 = 4 ) & ( 5 = 5 )   /* gives '0'                     */
SAY ( 3 = 3 ) & ( 4 = 5 )   /* gives '0'                     */
SAY ( 3 = 4 ) & ( 4 = 5 )   /* gives '0'                     */

The OR operator ( | ) between two terms gives a value of true unless both terms
are false.

Note:   Depending upon your Personal System keyboard and the code page you are
        using, you may not have the solid vertical bar to select. For this
        reason, REXX also recognizes the use of the split vertical bar as a
        logical OR symbol.  Some keyboards may have both characters.  If so,
        they are not interchangeable; only the character that is equal to the
        ASCII value of 124 works as the logical OR.  This type of mismatch can
        also cause the character on your screen to be different from the
        character on your keyboard.

SAY ( 3 = 3 ) | ( 5 = 5 )   /* gives '1'                     */
SAY ( 3 = 4 ) | ( 5 = 5 )   /* gives '1'                     */
SAY ( 3 = 3 ) | ( 4 = 5 )   /* gives '1'                     */
SAY ( 3 = 4 ) | ( 4 = 5 )   /* gives '0'                     */

For more examples of using the logical operators, select the Examples
pushbutton.


ΓòÉΓòÉΓòÉ 6. Automating Repetitive Tasks - Using Loops ΓòÉΓòÉΓòÉ

If you want to repeat several instructions in a procedure, you can use a loop.
Loops often are used in programming because they condense many lines of
instructions into a group that can be run more than once.  Loops make your
procedures more concise, and with a loop, you can continue asking a user for
input until the correct answer is given.

With loops, you can keep adding or subtracting numbers until you want to stop.
You can define how many times you want a procedure to handle an operation.  You
will see how to use simple loops to repeat instructions in a procedure.

The two types of loops you may find useful are repetitive loops and conditional
loops.  Loops begin with a DO instruction and end with the END instruction.
The following is a list of topics in this section:

DO num loop                   Repeats the loop a fixed number of times.

DO i=1 to 10 loop             Numbers each pass through the loop.  Sets a
                              starting and ending value for the variable.

DO WHILE                      Tests for true or false at the top of the loop.
                              Repeats the loop if true.  If false, continues
                              processing after END.

Do UNTIL                      Tests for true or false at the bottom of the
                              loop. Repeats the loop if false.  If true,
                              continues processing after END.

LEAVE                         Causes the interpreter to exit a loop.

DO FOREVER                    Repeats instructions until the user says to quit.

Getting out of loops          Requires that you press the Ctrl+Break keys.

Parsing words                 Assigns a different variable to each word in a
                              group.


ΓòÉΓòÉΓòÉ 6.1. Repetitive Loops ΓòÉΓòÉΓòÉ

Simple repetitive loops can be run a number of times.  You can specify the
number of repetitions for the loop, or you can use a variable that has a
changing value.

The following shows how to repeat a loop a fixed number of times.

DO num
   instruction1
   instruction2
   instruction3
   ...
END

The num is a whole number, which is the number of times the loop is to be run.

Here is LOOP.CMD, an example of a simple repetitive loop.

/* A simple loop */
DO 5
   SAY 'Thank-you'
END
EXIT

When you run the LOOP.CMD, you see this on your screen:

[C:\]loop
Thank-you
Thank-you
Thank-you
Thank-you
Thank-you

[C:\]

Another type of DO instruction is:

DO XYZ = 1 to 10

This type of DO instruction numbers each pass through the loop so you can use
it as a variable.  The value of XYZ changes (by 1) each time you pass through
the loop.  The 1 (or some number) gives the value you want the variable to have
the first time through the loop.  The 10 (or some number) gives the value you
want the variable to have the last time through the loop.

NEWLOOP.CMD is an example of another loop:

/* Another loop */
sum = 0
DO XYZ = 1 to 7
   SAY 'Enter value' XYZ
   PULL value
   sum = sum + value
END
SAY 'The total is' sum
EXIT

Here are the results of the NEWLOOP.CMD procedure:

[C:\]newloop
Enter value 1

2

Enter value 2

4

Enter value 3

6

Enter value 4

8

Enter value 5

10

Enter value 6

12

Enter value 7

14

The total is 56

[C:\]

When a loop ends, the procedure continues with the instruction following the
end of the loop, which is identified by END.


ΓòÉΓòÉΓòÉ 6.2. Conditional Loops ΓòÉΓòÉΓòÉ

Conditional loops are run when a true or false condition is met.  We will now
look at some instructions used for conditional loops:

DO WHILE and DO UNTIL: The DO WHILE and DO UNTIL instructions are run while or
until some condition is met.  A DO WHILE loop is:

DO WHILE expression
   instruction1
   instruction2
   instruction3
END

The DO WHILE instruction tests for a true or false condition at the top of the
loop; that is, before processing the instructions that follow. If the
expression is true, the instructions are performed.  If the expression is
false, the loop ends and moves to the instruction following END.

The following diagram shows the DO WHILE instruction:

To see a procedure using a DO WHILE loop, select the Examples pushbutton.

DO UNTIL: A DO UNTIL instruction differs from the DO WHILE because it processes
the body of instructions first, then evaluates the expression.  If the
expression is false, the instructions are repeated (a loop).  If the expression
is true, the procedure ends or moves to the next step outside the loop.

The DO UNTIL instruction tests at the bottom of the loop; therefore, the
instructions within the DO loop are run at least once.

An example of a DO UNTIL loop follows:

DO UNTIL expression
   instruction1
   instruction2
   instruction3

END

The following diagram shows the DO UNTIL instruction:

To see a procedure that uses a DO UNTIL loop, select the Examples pushbutton.

LEAVE: You may want to end a loop before the ending conditions are met. You can
accomplish this with the LEAVE instruction.  This instruction ends the loop and
continues processing with the instruction following END. The following
procedure, LEAVE.CMD, causes the interpreter to end the loop.

/* Using the LEAVE instruction in a loop */
SAY 'enter the amount of money available'
PULL salary
spent = 0        /* Sets spent to a value of 0 */
DO UNTIL spent > salary
   SAY 'Type in cost of item or END to quit'
   PULL cost
      IF cost = 'END'
      THEN
      LEAVE
   spent = spent + cost
END
SAY 'Empty pockets.'
EXIT

DO FOREVER: There may be situations when you do not know how many times to
repeat a loop.  For example, you may want the user to type specific numeric
data (numbers to add together), and have the loop perform the calculation until
the user says to stop.  For such a procedure, you can use the DO FOREVER
instruction with the LEAVE instruction.

The following shows the simple use of a DO FOREVER ending when the user stops.

/* Using a DO FOREVER loop to add numbers */
sum = 0
DO FOREVER
   SAY 'Enter number or END to quit'
   PULL value
   IF value = 'END'
      THEN
      LEAVE  /* procedure quits when the user enters "end" */
   sum = sum + value
END
SAY 'The sum is ' sum
EXIT


ΓòÉΓòÉΓòÉ 6.3. Getting Out of Loops ΓòÉΓòÉΓòÉ

To stop most REXX procedures, press the Ctrl+Break keys. REXX recognizes
Ctrl+Break after finishing the current instruction. Occasionaly, if you try a
procedure such as the one that follows, you need to press Ctrl+Break and then
Enter to get out of the loop.

/* Guess the secret password !  */
DO UNTIL answer = "Sesame"
   SAY "Please enter the password . . ."
   PULL answer
END
EXIT

If you are still unable to end the procedure, press the Alt+Esc keys to end the
OS/2 session and stop the procedure.


ΓòÉΓòÉΓòÉ 6.4. Parsing Words ΓòÉΓòÉΓòÉ

The PULL instruction collects a response and puts it into system memory as a
variable.  PULL also can be used to put each word from a group of words into a
different variable.  In REXX, this is called parsing.  The variable names used
in the next example are:  first, second, third, and rest.

SAY 'Please enter three or more words'
PULL first second third rest

Suppose you enter this as your response:

garbage in garbage out

When you press the Enter key, the procedure continues.  However, the variables
are assigned as follows:

The variable first is given the value GARBAGE.
The variable second is given the value IN.
The variable third is given the value GARBAGE.
The variable rest is given the value OUT.

In general, each variable receives a word, without blanks, and the last
variable receives the rest of the input, if any, with blanks. If there are more
variables than words, the extra variables are assigned the null, or empty,
value.


ΓòÉΓòÉΓòÉ 7. Advanced REXX Functions ΓòÉΓòÉΓòÉ

As you become more skilled at programming, you may want to create procedures
that do more and run more efficiently.  Sometimes this means adding a special
function to a procedure or calling a subroutine.

In this section, we shall see how these functions can help to build a better
foundation in REXX.

Functions                         Perform a computation and return a result.

DATATYPE( )                       An internal function that verifies that the
                                  data is a specific type.

SUBSTR( )                         An internal function that selects part of a
                                  string.

CALL                              Causes the procedure to look for a subroutine
                                  label and begin running the instructions
                                  following the label.

REXX.CMD File Commands            Treat commands as expressions.

Error Messages                    Tell you if the command runs correctly. If
                                  the procedure runs correctly, no message is
                                  displayed.


ΓòÉΓòÉΓòÉ 7.1. Functions ΓòÉΓòÉΓòÉ

In REXX, a function call can be written anywhere in an expression.  The
function performs the requested computation and returns a result.  REXX then
uses the result in the expression in place of the function call.

Think of a function as:  You are trying to find someone's telephone number.
You call the telephone operator and ask for the number.  After receiving the
number, you call the person.  The steps you have completed in locating and
calling the person could be labeled a function.

Generally, if the interpreter finds this in an expression,

name(expression)

it assumes that name is the name of a function being called.  There is no space
between the end of the name and the left parenthesis.  If you leave out the
right parenthesis, it is an error.

The expressions inside the parentheses are the arguments. An argument can
itself be an expression; the interpreter computes the value of this argument
before passing it to the function.  If a function requires more than one
argument, use commas to separate each argument.

Built-in Functions - Rexx has more than 50 built-in functions.  A dictionary of
built-in functions is in the Procedures Language 2/REXX Reference.

MAX is a built-in function that you can use to obtain the greatest number of a
set of numbers:

MAX(number, number, ...)

For example:

   MAX(2,4,8,6) = 8
   MAX(2,4+5,6) = 9

Note that in the second example, the 4+5 is an expression. A function call,
like any other expression, usually is contained in a clause as part of an
assignment or instruction.


ΓòÉΓòÉΓòÉ 7.2. DATATYPE( ) ΓòÉΓòÉΓòÉ

When attempting to perform arithmetic on data entered from the keyboard, you
can use the DATATYPE( ) function to check that the data is valid.

This function has several forms.  The simplest form returns the word, NUM, if
the expression inside the parentheses ( ) is accepted by the interpreter as a
number that can be used in the arithmetic operation. Otherwise, it returns the
word, CHAR. For example:

The value of DATATYPE(56) is NUM
The value of DATATYPE(6.2) is NUM
The value of DATATYPE('$5.50') is CHAR
In the following procedure, DATATYPE.CMD, the internal REXX function, DATATYPE(
), is used and the user is asked to keep typing a valid number until a correct
one is typed.

/* Using the DATATYPE( ) Function */
DO UNTIL datatype(howmuch) = 'NUM'
 SAY 'Enter a number'
 PULL howmuch
  IF datatype (howmuch) = 'CHAR'
   THEN
   SAY 'That was not a number.  Try again!'
END
SAY 'The number you entered was' howmuch
EXIT

If you want the user to type only whole numbers, you could use another form of
the DATATYPE( ) function:

DATATYPE (number, whole)

The arguments for this form are:

o number -  refers to the data to be tested.
o whole -  refers to the type of data to be tested.  In this example, the data
  must be a whole number.

This form returns a 1 if number is a whole number, or a 0 otherwise.


ΓòÉΓòÉΓòÉ 7.3. SUBSTR( ) ΓòÉΓòÉΓòÉ

The value of any REXX variable can be a string of characters.  To select a part
of a string, you can use the SUBSTR( ) function.  SUBSTR is an abbreviation for
substring. The first three arguments are:

o The string from which a part is taken.
o The position of the first character that is to be contained in the result
  (characters are numbered 1,2,3...in the string).
o The length of the result.
For example:

S = 'reveal'
SAY substr(S,2,3) /* Says 'eve'. Beginning with the second  */
                  /*  character, takes three characters.    */
SAY substr(S,3,4) /* Says 'veal'. Beginning with the third  */
                  /*  character, takes four characters.     */


ΓòÉΓòÉΓòÉ 7.4. CALL ΓòÉΓòÉΓòÉ

The CALL instruction causes the interpreter to search your procedure until a
label is found that marks the start of the subroutine. Remember, a label (word)
is a symbol followed by a colon (:).  Processing continues from there until the
interpreter finds a RETURN or an EXIT instruction.

A subroutine can be called from more than one place in a procedure. When the
subroutine is finished, the interpreter always returns to the instruction
following the CALL instruction from which it came.

Often each CALL instruction supplies data (called arguments or expressions)
that the subroutine is to use.  In the subroutine, you can find out what data
has been supplied by using the ARG instruction.

The CALL instruction is written in the following form:

CALL name  Argument1, Argument2 ...

For the name, the interpreter looks for the corresponding label (name) in your
procedure.  If no label is found, the interpreter looks for a built-in function
or a .CMD file with that name.

The arguments are expressions.  You can have up to 20 arguments in a CALL
instruction.  An example of a procedure that calls a subroutine follows.  Note
that the EXIT instruction causes a return to the operating system. The EXIT
instruction stops the main procedure from continuing into the subroutine.

In the following example, REXX.CMD, the procedure calls a subroutine from a
main procedure.

/* Calling a subroutine from a procedure */
DO 3
  CALL triple 'R'
  CALL triple 'E'
  CALL triple 'X'
  CALL triple 'X'
  SAY
END
SAY 'R...!'
SAY 'E...!'
SAY 'X...!'
SAY 'X...!'
SAY ' '
SAY 'REXX!'
EXIT          /* This ends the main procedure. */
/*                                                     */
/* Subroutine starts here to repeat REXX three times.  */
/* The first argument is displayed on screen three     */
/* times, with punctuation.                            */
/*                                                     */
TRIPLE:
SAY ARG(1)"    "ARG(1)"   "ARG(1)"!"
RETURN           /* This ends the subroutine.          */

When REXX.CMD is run on your system, the following is displayed:

[C:\]REXX
R   R   R!
E   E   E!
X   X   X!
X   X   X!

R   R   R!
E   E   E!
X   X   X!
X   X   X!

R   R   R!
E   E   E!
X   X   X!
X   X   X!

R...!
E...!
X...!
X...!

REXX!

[C:\]


ΓòÉΓòÉΓòÉ 7.5. REXX.CMD File Commands ΓòÉΓòÉΓòÉ

In a REXX procedure, anything not recognized as an instruction, assignment, or
label is considered a command.  The statement recognized as a command is
treated as an expression.  The expression is evaluated first, then the result
is passed to the operating system.

The following example, COPYLIST.CMD, shows how a command is treated as an
expression.  Note how the special character (*) is put in quotation marks.
COPYLIST.CMD copies files from drive A to drive B.

/* Issuing a command from a procedure.  This example copies  */
/* all files that have an extension of.LST from              */
/* drive A to drive B.                                       */
SAY
COPY "a:*.lst b:"           /* This statement is treated as  */
                            /* an expression.                */
                            /* The result is passed to OS/2. */
EXIT

Note:   In the preceding example, the whole OS/2 command except for COPY is in
        quotation marks for the following reasons:

o If the colon (:) were not in quotation marks, the REXXSAA interpreter would
  treat a: and b: as labels.
o If the asterisk (*) were not in quotation marks, the REXXSAA interpreter
  would attempt to multiply the value of a: by .LST.
o It is also acceptable to include the entire OS/2 command in quotation marks
  so that "COPY a:*.LST b:" is displayed.


ΓòÉΓòÉΓòÉ 7.6. Error Messages ΓòÉΓòÉΓòÉ

There are two basic reasons errors occur when REXX is processing a procedure.

One reason is because of the way the procedure is written; for example,
unmatched quotation marks or commas in the wrong place.  Maybe an IF
instruction was entered without a matching THEN. When such an error occurs, a
REXX error message is issued.

A second reason for an error to occur is because of an OS/2 command that the
REXX procedure has issued.  For example, a COPY command can fail because the
user's disk is full or a file cannot be found.  In this case, a regular OS/2
error message is issued.  When you write commands in your procedures, consider
what might happen if the command fails to run correctly.

When a command is issued from a REXX procedure, the command interpreter gets a
return code and stores it in the REXX special variable, RC (return code).  When
you write a procedure, you can test for these variables to see what happens
when the command is issued.

Here is how you discover a failure.  When commands finish running, they always
provide a return code.  A return code of 0 nearly always means that all is
well.  Any other number usually means that something is wrong. If the command
worked normally (the return code was 0), you see the command prompt:

[C:\]

and you return to the screen you ran your program from in Presentation Manager,
or in the PMREXX application you see printed under the last line of the
procedure,

The REXX procedure has ended.

In the following example, ADD.CMD, there is an error in line 6; the plus sign
(+) has been typed incorrectly as an ampersand (&).

/* This procedure adds two numbers */
SAY "Enter the first number."
PULL num1
SAY "Enter the second number."
PULL num2
SAY "The sum of the two numbers is" num1 & num2
EXIT

When the above procedure, ADD.CMD, is run, the following error message is
displayed.

    6+++ SAY "The sum of the two numbers is" num1 & num2
REX0034: Error 34 running C:\REXX\ADD.CMD,line 6:logical value not 0 or 1

To get help on the error message, type:

HELP REX0034

When help is requested, an error message such as the following is displayed:

REX0034 ***Logical Value not 0 or 1***

Explanation: The expression in an IF, WHEN, DO WHILE, or DO UNTIL
             phrase must result in a '0' or a '1', as must any
             term operated on by a logical operator.

Any command that is valid at the command prompt is valid in a REXX procedure.
The command interpreter treats the command statement the same way as any other
expression, substituting the values of variables, and so on.  (The rules are
the same as for commands entered at the command prompt.)

Return Codes: When the command interpreter has issued a command and the
operating system has finished running it, the command interpreter gets the
return code and stores it in the REXX special variable RC (return code).  In
your procedure, you should test this variable to see what happens when the
command is run.

The following example shows a few lines from a procedure where the return code
is tested:

/* Testing the Return Code in a Procedure. */
'COPY a:*.lst b:'
IF rc = 0   /* RC contains the return code from the COPY command */
THEN
 SAY 'All *lst files copied'
ELSE
 SAY 'Error occurred copying files'


ΓòÉΓòÉΓòÉ 8. PMREXX and REXXTRY ΓòÉΓòÉΓòÉ

PMREXX is a windowed Presentation Manager* application that enables you to
browse the output of your REXX procedures.  REXXTRY is a command that lets you
interactively run one or more REXX instructions.

By using PMREXX, you add the following features to REXX:

o A window for the display of the output of a REXX procedure, such as:

   - The SAY instruction output
   - The STDOUT and STDERR outputs from secondary processes started from a REXX
     procedures file
   - The REXX TRACE output (not to be confused with OS/2 tracing).

o An input window for:

   - The PULL instruction in all of its forms
   - The STDIN data for secondary processes started from a REXX procedures
     file.

o A browsing, scrolling, and clipboard capability for REXX output.
o A selection of fonts for the output window.
o A simple environment for experimenting with REXX instructions through the use
  of the REXXTRY.CMD program.  REXXTRY interactively interprets REXX
  instructions and can be started by typing REXXTRY or PMREXX REXXTRY at an
  OS/2 command prompt


ΓòÉΓòÉΓòÉ 8.1. Starting the PMREXX Program ΓòÉΓòÉΓòÉ

You can start the PMREXX program and a REXX procedure from an OS/2 command
prompt.  You do this by typing PMREXX and a target procedure name that
generates an output or input function, as follows:

PMREXX  filename.CMD arguments

where the arguments and .CMD extension are optional.

Here is a REXX program named SAMPLE.CMD that calls for system environment
variables to be displayed when the various arguments are indicated.

/**/
'@ECHO OFF'
env = 'OS2ENVIRONMENT'
Parse Arg all
Do i=1 to words(all)
   word = translate(word(all,i))
   Say
   If value(word,,env)=''
     Then Say '"'word'" is not in the environment!.'
     Else Say word'="'value(word,,env)'".'
End

To display the current PATH and DPATH statements in the CONFIG.SYS file in a
PMREXX window, type the following:

PMREXX Sample PATH DPATH

Note:   You can move or size the PMREXX.EXE window or select menu-bar choices,
        the same way that you do with other windows.

Once the output of the REXX procedure is displayed in PMREXX, you can select
the menu-bar choices to take advantage of the following PMREXX browsing
features:

Menu-Bar Choice             Description

File                        Save, Save As, and Exit the process

Edit                        Copy, Paste to the input, Clear the output, and
                            Select All lines

Options                     Restart the process, Interactive Trace, and Set
                            font

Actions                     Halt procedure, Trace next clause, Redo the last
                            clause, and Set Trace off

Help                        Help index, General help, Keys help, and Using
                            help.


ΓòÉΓòÉΓòÉ 8.2. The PMREXX Trace Function ΓòÉΓòÉΓòÉ

The trace function in PMREXX turns on interactive tracing for the currently
operating REXX procedure.  This is done by adding the /T parameter to the
PMREXX command before typing the file name at an OS/2 command prompt.

TRACE lets you see just how REXX evaluates expressions while the program is
actually running. To start the trace function from the command prompt, type the
command as follows:

PMREXX /T filename arguments


ΓòÉΓòÉΓòÉ 8.3. The REXXTRY Program ΓòÉΓòÉΓòÉ

REXXTRY is a REXX program.  As with other REXX programs, REXXTRY can be run in
an OS/2 full-screen or window session, or with PMREXX.

You can use REXXTRY to run different REXX instructions and observe the results.
REXXTRY is also useful when you want to perform a REXX operation only once,
since it is easier than creating, running, and erasing a .CMD file.

Here are some examples of how to use the REXXTRY command:

REXXTRY say 1+2

The operation is performed and 3 is displayed.

REXXTRY say 2+3; say 3+4

5 and 7 are displayed.


ΓòÉΓòÉΓòÉ 9. REXX Utility Functions (RexxUtil) ΓòÉΓòÉΓòÉ

RexxUtil is a Dynamic Link Library (DLL) which provides the OS/2* REXX
programmer with many versatile functions.  Primarily, these functions deal with
the following:

o OS/2 system commands.

o User or text screen input/output (I/O).

o OS/2 INI file I/O.

RexxUtil requires that you are already running under OS/2 2.0 with OS/2
Procedures Language 2/REXX installed.

To be able to use a RexxUtil function in a REXX program, you must first add the
function using the built-in function RxFuncAdd.

Example:

call RxFuncAdd 'SysCls', 'RexxUtil', 'SysCls'

The above example would add the SysCls function so that it can be used.

The RexxUtil function, SysLoadFuncs, will automatically load all RexxUtil
functions.  To do this from within a program, add the following instructions:

call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
call SysLoadFuncs

Once the RexxUtil functions are loaded by SysLoadFuncs they are usable by all
OS/2 sessions.

The RexxUtil functions are listed when you select the + sign beside this topic
in the Contents.


ΓòÉΓòÉΓòÉ 9.1. RxMessageBox ΓòÉΓòÉΓòÉ

Function: RxMessageBox

Syntax:   action = RxMessageBox(text, [title], [button], [icon])

   text      The text of the message that appears in the message box.

   title     The title of the message box.  The default title is "Error".

   The style of buttons used with the message box.  The allowed styles are:

      OK                    A single OK button.

      OKCANCEL              An OK button and a Cancel button.

      CANCEL                A single Cancel button.

      ENTER                 A single Enter button.

      ENTERCANCEL           An Enter button and a Cancel button.

      RETRYCANCEL           A Retry button and a Cancel button.

      ABORTRETRYCANCEL      An Abort button, a Retry button and a Cancel
                            button.

      YESNO                 A Yes button and a No button.

      YESNOCANCEL           A Yes button, a No button and a Cancel button.

             The default button style is OK.

   icon      The style of icon displayed in the message box.  The allowed
             styles are:

      NONE                No icon is displayed.

      HAND                The hand icon is displayed.

      QUESTION            A question mark icon is displayed.

      EXCLAMATION         An exclamation mark icon is displayed.

      ASTERISK            An asterisk icon is displayed.

      INFORMATION         The information icon is displayed.

      QUERY               The query icon is displayed.

      WARNING             The warning icon is displayed.

      ERROR               The error icon is displayed.

   action    The button that was selected on the message box. Possible values
             are:

      1         OK key

      2         Cancel key

      3         Abort key

      4         Retry key

      5         Ignore key

      6         Yes key

      7         No key

      8         Enter

Purpose:  Display a message box from a REXX program running in an OS/2 session
          (that is, running in PMREXX or called from a Presentation Manager*
          application).

Examples:

                                       /* Give option to quit        */
  if RxMessageBox("Shall we continue",, "YesNo", "Query") = 7
    Then Exit                          /* quit option given, exit    */


ΓòÉΓòÉΓòÉ 9.2. SysCls ΓòÉΓòÉΓòÉ

Function: SysCls

Syntax:   call SysCls

Purpose:  Clears the screen quickly.


ΓòÉΓòÉΓòÉ 9.3. SysCurPos ΓòÉΓòÉΓòÉ

Function: SysCurPos

Syntax:   pos = SysCurPos(row, col)

   pos       The position of the cursor upon the calling of SysCurPos in the
             form 'row col'.

   row       The row on the screen to move to.

   col       The column on the screen to move to.

             Note:   Position (0,0) is at the upper left.  You may call
             SysCurPos without parameters to check the current cursor position
             without changing it.

Purpose:  Move the cursor to the specified row and column and/or query the
          current/previous cursor position.

                    Example:

                     /* Code */
                     call SysCls
                     parse value SysCurPos() with row col
                     say 'Cursor position is 'row', 'col

                     /* Output */
                     Cursor position is 0, 0


ΓòÉΓòÉΓòÉ 9.4. SysCurState ΓòÉΓòÉΓòÉ

Function: SysCurState

Syntax:   SysCurState state

   state     The desired state which to set the cursor.  Should be one of the
             following:

      'ON'      Display the cursor.

      'OFF'     Hide the cursor.

Purpose:  Use this function to hide or display the cursor.


ΓòÉΓòÉΓòÉ 9.5. SysDriveInfo ΓòÉΓòÉΓòÉ

Function: SysDriveInfo

Syntax:   info = SysDriveInfo(drive)

   info      Drive information returned in the following form: 'drive:  free
             total label' If the drive is not accessible, then info will equal
             ''.

   drive     The drive of interest,  'C:'.

Purpose:  Gives drive information.

                    Example:
                     /* Code */
                     say 'Disk='SysDriveInfo('C:')

                     /* Output */
                     Disk=C: 33392640 83687424 TRIGGER_C

In the above Output example, the items have the following meaning:

o The first item is the drive being queried.
o The first number is the number of bytes that are free.
o The second number is the number of bytes that are used.
o The final item is the drive label.


ΓòÉΓòÉΓòÉ 9.6. SysDriveMap ΓòÉΓòÉΓòÉ

Function: SysDriveMap

Syntax:   map = SysDriveMap([drive], [opt])

   map       A string containing all accessible drives.

   drive     Drive letter with which to start the drive map. The default is C.

   opt       The drivemap report option.  May be any one of the following:

      'USED'         Reports drives which are accessible or in use.  This is
                     the default. This includes all local and remote drives.

      'FREE'         Reports drives which are free or not in use.

      'LOCAL'        Reports only those drives which are local drives.

      'REMOTE'       Reports only those drives which are remote drives such as
                     redirected LAN resources, IFS attached drives, and so on.

      'DETACHED'     Reports drives which are detached LAN resources.

Purpose:  Reports all accessible drives in the form 'C: D: E:...'

                    Example:
                     /* Code */
                     say 'Used drives include:'
                     say SysDriveMap('C:', 'USED')

                     /* Output */
                     Used drives include:
                     C: D: E: F: W:


ΓòÉΓòÉΓòÉ 9.7. SysDropFuncs ΓòÉΓòÉΓòÉ

Function: SysDropFuncs

Syntax:   call SysDropFuncs

Purpose:  Use this function to drop all the loaded RexxUtil functions.  Once
          this function is processed by a REXX program, the RexxUtil functions
          are not accessible in any OS/2 sessions.


ΓòÉΓòÉΓòÉ 9.8. SysFileDelete ΓòÉΓòÉΓòÉ

Function: SysFileDelete

Syntax:   rc = SysFileDelete(file)

Purpose:  Deletes the specified file.  Does not support wildcards.

RC:       Return Codes

   0         File deleted successfully.

   2         Error.  File not found.

   3         Error.  Path not found.

   5         Error.  Access denied.

   26        Error.  Not DOS disk.

   32        Error.  Sharing violation.

   36        Error.  Sharing buffer exceeded.

   87        Error.  Invalid parameter

   206       Error.  Filename exceeds range error


ΓòÉΓòÉΓòÉ 9.9. SysFileTree ΓòÉΓòÉΓòÉ

Function: SysFileTree

Syntax:   rc = SysFileTree(filespec, stem, [options], [tattrib], [nattrib])

   filespec  The filespec to search for.

   stem      The name of the stem variable to place the results.

             Note:   stem.0 contains the number of files and/or directories
             found.

   options   Any logical combination of the following:

      F         Search for files only.

      D         Search for directories only.

      B         Search for both files and directories. (default)

      S         Scan subdirectories recursively. (non-default).

      T         Return time and date fields in the form:

                                YY/MM/DD/HH/MM

      O         Only report fully qualified file names.  The default is to
                report date, time, size, attributes and fully qualified file
                name for each file found.

   tattrib   The target attribute mask used when searching for filespec
             matches. Only filespecs which match the mask will be reported.
             The default mask is '*****' which means the Archive, Directory,
             Hidden, Read-Only, and System bits may be either set or clear.
             The attributes in the mask are positional dependant and in the
             alphabetical order 'ADHRS'.

      Mask Options (Target Mask)

         *         The specified attribute may be either set or clear.

         +         The specified attribute must be set.

         -         The specified attribute must be clear.

         Examples: (Target Mask)

            '***+*'   Find all files which have set Read-Only bits.

            '+**+*'   Find all files which have set Read-Only and Archive bits.

            '*++**'   Find all hidden subdirectories.

            '---+-'   Find all files which have only the Read-Only bit set.

   nattrib   The new attribute mask which will be used to set the attributes of
             each filespec found to match the target mask.  The default mask is
             '*****' which means the Archive, Directory, Hidden, Read-Only, and
             System bits will not be changed.  The attributes in the mask are
             positional dependant and in the alphabetical order 'ADHRS'.

      Mask Options (New Atrribute Mask)

         *         The specified attribute will not be changed.

         +         The specified attribute will be set.

         -         The specified attribute will be cleared.

         Examples: (New Attribute Mask)

            '***+*'   Set the Read-Only bit on all files.

            '-**+*'   Set the Read-Only and clear the Archive bits of each
                      file.

            '+*+++'   Set all attributes on all files, excluding directory
                      attribute.

            '-----'   Clear all attribute on all files.

                      Note:   You cannot set the directory bit on non-directory
                      filespecs.  The attribute field which is displayed in the
                      stem variable is that of the current attribute setting
                      after any changes have been applied.

Purpose:  Finds all files which are equal to the specified filespec, and places
          their descriptions (date time size attr filespec) in a stem variable.

RC:       Return Codes

   0         Successful.

   2         Error.  Not enough memory.

                     Examples:

                      /****<< Syntax Examples.>>***********************/

                      /* Find all subdirectories on C: */
                       call SysFileTree 'c:\*.*', 'file', 'SD'

                      /* Find all Read-Only files */
                       call SysFileTree 'c:\*.*', 'file', 'S', '***+*'

                      /* Clear Archive and Read-Only bits of files which have them set */
                       call SysFileTree 'c:\*.*', 'file', 'S', '+**+*', '-**-*'


                      /****<< Sample Code and Output Example.>>********/

                      /* Code */
                       call SysFileTree 'c:\os2*.', 'file', 'B'
                       do i=1 to file.0
                         say file.i
                       end

                     /* Actual Output */
                    12:15:89  12:00a        4096  A-HRS  C:\OS2LDR
                    12:15:89  12:00a       29477  A-HRS  C:\OS2KRNL
                     5:24:89   4:59p           0  -D---  C:\OS2


ΓòÉΓòÉΓòÉ 9.10. SysFileSearch ΓòÉΓòÉΓòÉ

Function: SysFileSearch

Syntax:   call SysFileSearch target, file, stem, [options]

   target    The string to search for.

   file      The file to search.

   stem      The name of the stem variable to place the results.

             Note:   stem.0 contains the number of lines found.

   options   Any logical combination of the following:

      C         Case sensitive search.

      N         Give line numbers when reporting hits.

                Note:   Default is case insensitive without line numbers.

Purpose:  Finds all lines in specified file which contain a specified target
          string, and places said lines in a stem variable.

RC:       Return Codes

   0         Successful.

   2         Error.  Not enough memory.

   3         Error.  Error opening file.

                    Examples:

                     /* Find DEVICE statements in CONFIG.SYS */
                     call SysFileSearch 'DEVICE', 'C:\CONFIG.SYS', 'file.'
                     do i=1 to file.0
                      say file.i
                     end

                     /* Output */
                     DEVICE=C:\OS2\DOS.SYS
                     DEVICE=C:\OS2\PMDD.SYS
                     DEVICE=C:\OS2\COM02.SYS
                     SET VIDEO_DEVICES=VIO_IBM8514A
                     SET VIO_IBM8514A=DEVICE(BVHVGA,BVH8514A)
                     DEVICE=C:\OS2\POINTDD.SYS
                     DEVICE=C:\OS2\MSPS202.SYS
                     DEVICE=C:\OS2\MOUSE.SYS TYPE=MSPS2$


                     /* Find DEVICE statements in CONFIG.SYS (along with */
                     /* line nums) */
                     call SysFileSearch 'DEVICE', 'C:\CONFIG.SYS', 'file.', 'N'
                     do i=1 to file.0
                      say file.i
                     end

                     /* Output */
                     20 DEVICE=C:\OS2\DOS.SYS
                     21 DEVICE=C:\OS2\PMDD.SYS
                     22 DEVICE=C:\OS2\COM02.SYS
                     33 SET VIDEO_DEVICES=VIO_IBM8514A
                     34 SET VIO_IBM8514A=DEVICE(BVHVGA,BVH8514A)
                     40 DEVICE=C:\OS2\POINTDD.SYS
                     41 DEVICE=C:\OS2\MSPS202.SYS
                     42 DEVICE=C:\OS2\MOUSE.SYS TYPE=MSPS2$


ΓòÉΓòÉΓòÉ 9.11. SysGetKey ΓòÉΓòÉΓòÉ

Function: SysGetKey

Syntax:   key = SysGetKey([opt])

   key       The key which was pressed.

   opt        Any one of the following:

      'ECHO'    Echo the typed character  (Default)

      'NOECHO'  Do not echo the typed character

Purpose:  Gets the next key from the keyboard buffer, or waits for one if none
          exist.  Works like the C function getch().  Unlike the regular REXX
          CHARIN() built-in function, SysGetKey() does not require the
          character to be followed by the Enter key.


ΓòÉΓòÉΓòÉ 9.12. SysGetMessage ΓòÉΓòÉΓòÉ

Function: SysGetMessage

Syntax:   msg = SysGetMessage(num, [file] [str1],...[str9])

   msg       The message associated with the number given.

   num       The message number.

   file      The message file to be searched.  The default message file is
             OSO001.MSG. Message files will be searched for in the system root
             directory ( C:\), the current directory, and along the DPATH.

   str1,...str9 Insertion text variables.  If the message contains insertion
             fields designated by %x, in the range %1 to %9, then the optional
             parameters str1 through str9 may be used to designate the
             replacement strings.

Purpose:  OS/2 applications commonly use message files to provide National
          Language Support (NLS).  Message files contain text strings which any
          application can reference by their associated number.

          Note:   Use the MKMSGF utility contained in the OS/2 Programmer's
                  Toolkit to create message files.  MKMSGF is documented in the
                  Building Programs book included with the toolkit.

                    /*** Sample code segment using SysGetMessage and insertion text vars ***/
                    msg =  SysGetMessage(34, , 'A:', 'diskette labeled "Disk 2"', 'SER0002')
                    say msg

                    /** Output **/
                    The wrong diskette is in the drive.
                    Insert diskette labeled "Disk 2" (Volume Serial Number: SER0002)
                    into drive A:.


ΓòÉΓòÉΓòÉ 9.13. SysIni ΓòÉΓòÉΓòÉ

Function: SysIni

   Syntax - Mode 1: Setting single key value.

             result = SysIni([inifile], app, key, val)

   Syntax - Mode 2: Querying single key value.

             result = SysIni([inifile], app, key)

   Syntax - Mode 3: Deleting a single key.

             result = SysIni([inifile], app, key, 'DELETE:')

   Syntax - Mode 4: Deleting an application and all associated keys.

             result = SysIni([inifile], app, ['DELETE:'])

   Syntax - Mode 5: Querying names of all keys associated with a certain
             application.

             result = SysIni([inifile], app, 'ALL:', 'stem')

   Syntax - Mode 6: Querying names of all applications.

             result = SysIni([inifile], 'ALL:', 'stem')

   result    For successful setting invocations, result will equal ''. For
             successful querying invocations, result will be given the value of
             the specified application keyword.  For successful deleting
             invocations, result will equal ''.

             The error string 'ERROR:' may be returned if an error occurs:

             Possible error conditions:

      o An attempt was made to query or delete an application/key pair which
        does not exist.

      o An error occurred opening the specified INI file. You may have
        specified the current user or system INI file using a relative
        filespec. Make sure to use the full filespec, specifying drive, path,
        and file name.

   inifile   The name of the INI file which you would like to work with.  This
             parameter should be a file specification, or one of the following:

      'USER'    The user INI file (usually C:\OS2\OS2.INI).  This is the
                default.

      'SYSTEM'  The system INI file (usually C:\OS2\OS2SYS.INI).

      'BOTH'    For querying invocations, both the user and system INI files
                will be searched. For setting invocations, the user INI file
                will be written to.

   app       The application name or some other meaningful value with which you
             would like to store keywords (some sort of data).

   key       The name of a keyword which is used to hold data.

   val       The value to associate with the keyword of the specified
             application.

   stem      The name of the stem variable to store the resultant information
             in.  STEM.0 will be set equal to the number of elements.

Purpose:  This function allows limited editing of INI file variables. Variables
          are stored in the INI file under Application Names and their
          associated Key Names or keywords.  SysIni can be used to share
          variables between applications or as a way of implementing GLOBALV in
          the OS/2 operating system.

          Note:   This function works on all types of data stored in an INI
          file (text, numeric, or binary).

                    /* Sample code segments */

                     /***  Save the user entered name under the key 'NAME' of *****
                     ****  the application 'MYAPP'.                           ****/
                     pull name .
                     call SysIni , 'MYAPP', 'NAME', name /* Save the value        */
                     say  SysIni(, 'MYAPP', 'NAME')      /* Query the value       */
                     call SysIni , 'MYAPP'               /* Delete all MYAPP info */
                     exit

                     /****  Type all OS2.INI file information to the screen  *****/
                    call rxfuncadd sysloadfuncs, rexxutil, sysloadfuncs
                    call sysloadfuncs
                       call SysIni 'USER', 'All:', 'Apps.'
                       if Result \= 'ERROR:' then
                         do i = 1 to Apps.0
                           call SysIni 'USER', Apps.i, 'All:', 'Keys'
                           if Result \= 'ERROR:' then
                            do j=1 to Keys.0
                              val = SysIni('USER', Apps.i, Keys.j)
                              say left(Apps.i, 20) left(Keys.j, 20),
                                    'Len=x'''Left(d2x(length(val)),4) left(val, 20)
                            end
                         end


ΓòÉΓòÉΓòÉ 9.14. SysMkDir ΓòÉΓòÉΓòÉ

Function: SysMkDir

Syntax:   rc = SysMkDir(dirspec)

   dirspec   The directory that should be created.

Purpose:  Creates a specified directory quickly.  In case of failure, one of
          many return codes is given so that the exact reason for failure can
          be determined.

RC:       Return Codes

   0         Directory creation was successful.

   2         Error.  File not found.

   3         Error.  Path not found.

   5         Error.  Access denied.

   26        Error.  Not a DOS disk.

   87        Error.  Invalid parameter.

   108       Error.  Drive locked.

   206       Error.  Filename exceeds range.

Example:  call SysMkDir 'c:\rexx'


ΓòÉΓòÉΓòÉ 9.15. SysOS2Ver ΓòÉΓòÉΓòÉ

Function: SysOS2Ver

Syntax:   ver = SysOS2Ver( )

   ver       String containing OS/2 version info in the form 'x.xx'

Purpose:  Returns the OS/2 version information.


ΓòÉΓòÉΓòÉ 9.16. SysRmDir ΓòÉΓòÉΓòÉ

Function: SysRmDir

Syntax:   rc = SysRmDir(dirspec)

   dirspec   The directory that should be deleted.

Purpose:  Deletes a specified directory quickly.  In case of failure, one of
          many return codes is given so that the exact reason for failure can
          be determined.

RC:       Return Codes

   0         Directory removal was successful.

   2         Error.  File not found.

   3         Error.  Path not found.

   5         Error.  Access denied.

   16        Error.  Current directory.

   26        Error.  Not a DOS disk.

   87        Error.  Invalid parameter.

   108       Error.  Drive locked.

   206       Error.  Filename exceeds range.

Example:  call SysRmDir 'c:\rexx'


ΓòÉΓòÉΓòÉ 9.17. SysSearchPath ΓòÉΓòÉΓòÉ

Function: SysSearchPath

Syntax:   filespec = SysSearchPath(path, filename)

   filespec  The complete filespec of the file found, or '' if the filename was
             not located along the path.

   path      Any environment variable that resembles a path, such as 'PATH',
             'DPATH', and so on.

   filename  The file to search the path for.

Purpose:  Searches the specified path for the specified file and returns the
          full filespec of the file if found, otherwise it returns.

                    Example:

                     /* Code */
                     fspec = SysSearchPath('PATH', 'CMD.EXE')
                     say fspec

                     /* Output */
                     C:\OS2\CMD.EXE


ΓòÉΓòÉΓòÉ 9.18. SysSleep ΓòÉΓòÉΓòÉ

Function: SysSleep

Syntax:   call SysSleep secs

   secs      The number of seconds to sleep.

Purpose:  Sleep a specified number of seconds.


ΓòÉΓòÉΓòÉ 9.19. SysTempFileName ΓòÉΓòÉΓòÉ

Function: SysTempFileName

Syntax:   file = SysTempFileName(template, [filter])

   template  The template that describes the temporary file or directory name
             to be returned.  The template should resemble a valid file or
             directory specification with up to 5 filter characters.

   filter    The filter character found in the template.  Each filter character
             found in the template is replaced with a numeric value.  The
             resulting string represents a file or directory that does not
             exist.  The default filter character is ?.

   file      A file or directory that does not currently exist.  If an error
             occurred or if no unique file or directory exists given the
             template provided, a null string is returned.

Purpose:  Returns a unique file or directory name given a certain template.
          Useful when a program requires a temporary file but is not to
          overwrite an existing file.

                    Examples:

                     /* Code */
                     say SysTempFileName('C:\TEMP\MYEXEC.???')
                     say SysTempFileName('C:\TEMP\??MYEXEC.???')
                     say SysTempFileName('C:\MYEXEC@.@@@', '@')

                     /* Output */
                     C:\TEMP\MYEXEC.251
                     C:\TEMP\10MYEXEC.392
                     C:\MYEXEC6.019

          Note:

          Since it is not required that the filter characters be contiguous
          within the template, it is impossible to quickly determine the number
          of files already residing in the target directory that would fit the
          template description.

          SysTempFileName uses a random number algorithm to determine a number
          to replace the filter characters with.  It then tests if the
          resulting file exists.  If it does not, it increments the number,
          replaces the filter characters, and tests for the existence of the
          new file, and so on.  This continues until a free file is found or
          all possibilities have been exhausted.


ΓòÉΓòÉΓòÉ 9.20. SysTextScreenRead ΓòÉΓòÉΓòÉ

Function: SysTextScreenRead

Syntax:   string = SysReadScreen(row, col, [len])

   row       The row from which to start reading.

   col       The column from which to start reading.

   len       The number of characters to read.  The default is to read up to
             the end of the screen.

   string    The character reads from the screen.  This includes carriage
             return and linefeed characters which comprise the end of lines
             should the number of character reads span multiple lines.

Purpose:  Reads a specified number of characters from a specified location of
          the screen.

Limitations  This function only reads in characters and does not consider the
color attributes of each character read.  When restoring the character string
to the screen with say or charout, the previous color settings will be lost.

/* Example which reads in the entire screen */
 screen = SysTextScreenRead( 0, 0 )

/* Example which reads in one line */
 line = SysTextScreenRead( 2, 0, 80 )


ΓòÉΓòÉΓòÉ 9.21. SysTextScreenSize ΓòÉΓòÉΓòÉ

Function: SysTextScreenSize

Syntax:   result = SysTextScreenSize()

   result    The size of the screen.  The format of the result string is 'row
             col'.

Purpose:  This function returns the size of the screen.

/* Example */
call RxFuncAdd 'SysTextScreenSize', 'RexxUtil', 'SysTextScreenSize'
parse value SysTextScreenSize() with row col
say 'Rows='row', Columns='col


ΓòÉΓòÉΓòÉ 9.22. SysGetEA ΓòÉΓòÉΓòÉ

Function: SysGetEA

Syntax:   result = SysGetEA(file, name, variable)

   file      The file containing the extended attribute.

   name      The name of the extended attribute.

   variable  The name of a REXX variable in which the extended attribute value
             is placed.

   result    The function result. If the result is 0, the extended attribute
             has been retrieved and placed in a variable.  A non-zero result is
             the OS/2 return code of the failing function.

Purpose:  Read a named extended attribute from a file.

Examples:

  /* Code    */
  if (SysGetEA("C:\CONFIG.SYS", ".type", "TYPEINFO") = 0 then
    parse var typeinfo 11 type
    say type

  /* Output */
  OS/2 Command File


ΓòÉΓòÉΓòÉ 9.23. SysPutEA ΓòÉΓòÉΓòÉ

Function: SysPutEA

Syntax:   result = SysPutEA(file, name, value)

   file      The file where the extended attribute will be written.

   name      The name of the extended attribute.

   value     The new value of the extended attribute.

   result    The function result. If the result is 0, the extended attribute
             has been written to the file. A non-zero result is the OS/2 return
             code of the failing function.

Purpose:  Write a named extended attribute to a file.

Examples:

  /* Code    */
  type = "OS/2 Command File"
  typeinfo = "DFFF00000100FDFF'x || d2c(length(type)) || '00'x || type
  call SysPutEA "C:\CONFIG.SYS", "TYPE", typeinfo


ΓòÉΓòÉΓòÉ 9.24. SysWaitNamedPipe ΓòÉΓòÉΓòÉ

Function: SysWaitNamedPipe

Syntax:   result = SysWaitNamedPipe(name, [timeout])

   name      The name of the named pipe.  Named pipe names must be of the form
             "\PIPE\pipename".

   timeout   The number of microseconds to wait on the pipe.  If timeout is
             omitted or is zero, the default timeout value is be used. A value
             of -1 can be used to wait until the pipe is no longer busy.

   result    The return code from DosWaitNmPipe. The following return codes are
             of particular interest:

      0         The named pipe is no longer busy.

      2         The named pipe was not found.

      231       The wait timed out before the pipe became available.

Purpose:  Perform a timed wait on a named pipe.

Examples:

  /* Code    */
   Parse value stream(PipeName,'C','OPEN') with PipeState ':' OS2RC
   If OS2RC=231 then call SysWaitNamedPipe(PipeName, -1)


ΓòÉΓòÉΓòÉ 9.25. SysSetIcon ΓòÉΓòÉΓòÉ

Function: SysSetIcon

Syntax:   result = SysSetIcon(filename, iconfilename)

   filename          The name of the file to have the icon set.

   iconfilename      The name of a .ICO file containing icon data.

   result            The return code from WinSetIcon. This returns 1 (TRUE) if
                     the icon was set and 0 (FALSE) if the new icon was not
                     set.

   Purpose:          Associate an icon file with a specified file.

                    Examples:

                      /* Code    */
                       if SysSetIcon(file, "NEW.ICO") then
                         say 'Install successfully completed for' file


ΓòÉΓòÉΓòÉ 9.26. SysRegisterObjectClass ΓòÉΓòÉΓòÉ

Function: SysRegisterObjectClass

Syntax:   result = SysRegisterObjectClass(classname, modulename)

   classname         The name of the new object class.

   modulename        The name of the module containing the object definition.

   result            The return code from WinRegisterObjectClass.  This returns
                     1 (TRUE) if the class was registered and 0 (FALSE) if the
                     new class was not registered.

   Purpose:          Register a new object class definition to the system.

                    Examples:

                      /* Code    */
                       if SysRegisterObjectClass("NewObject","NEWDLL") then
                         say 'Install successfully completed for NewObject'


ΓòÉΓòÉΓòÉ 9.27. SysDeregisterObjectClass ΓòÉΓòÉΓòÉ

Function: SysDeregisterObjectClass

Syntax:   result = SysDeregisterObjectClass(classname)

   classname         The name of the object class to deregister.

   result            The return code from WinDeregisterObjectClass.  This
                     returns 1 (TRUE) if the class was deregistered and 0
                     (FALSE) if the class was not deregistered.

   Purpose:          Deregister an object class definition from the system.

                    Examples:

                      /* Code    */
                       call SysDeregisterObjectClass "OldObject","NEWDLL"


ΓòÉΓòÉΓòÉ 9.28. SysCreateObject ΓòÉΓòÉΓòÉ

Function: SysCreateObject

Syntax:   result = SysCreateObject(classname, title, location <,setup>)

   classname         The name of the object class.

   title             The object title.

   location          The object location.  This can be specified as either a
                     descriptive path (for example, OS/2 System Folder\System
                     Configuration) or a file system path (for example,
                     C:\bin\mytools).

   setup             A WinCreateObject setup string.

   result            The return code from WinCreateObject.  This returns 1
                     (TRUE) if the object was created and 0 (FALSE) if the
                     object was not created.

   Purpose:          Create a new instance of an object class.

                    Examples:

                      /* Code    */
                       if \SysCreateObject("Program","NEWDLL") then
                         say 'Install successfully completed for NewObject'


ΓòÉΓòÉΓòÉ 9.29. SysQueryClassList ΓòÉΓòÉΓòÉ

Function: SysQueryClassList

Syntax:   call  SysQueryClassList stem

   stem      The name of a stem variable in which the entire set of registered
             classes is placed.

   Purpose:  Retrieve the complete list of registered object classes.

                    Examples:

                      /* Code    */
                       call SysQueryClassList "list."
                       do i = 1 to list.0
                         say 'Class' i 'is' list.i
                       end


ΓòÉΓòÉΓòÉ <hidden> Arithmetic Examples ΓòÉΓòÉΓòÉ

This sample procedure named MATH.CMD shows you how to perform four arithmetic
operations on variables:

/* Performing arithmetic operations on variables */
a = 4
b = 2
c = a + b
SAY 'The result of 'a '+' b 'is' c
SAY
c = a * b
SAY 'The result of ' a '*' b 'is' c
SAY
c = a - b
SAY 'The result of ' a '-' b 'is' c
SAY
c = a / b
SAY 'The result of 'a '/' b 'is' c
EXIT
Your screen looks like this:

[C:\]MATH
The result of 4 + 2 is 6

The result of 4 * 2 is 8

The result of 4 - 2 is 2

The result of 4 / 2 is 2

[C:\]


ΓòÉΓòÉΓòÉ <hidden> Using Comparisons ΓòÉΓòÉΓòÉ

The following procedure, TF.CMD, uses comparisons and an equal expression to
determine if numeric expressions are true or false.

/* Determine if expression is true or false  */
/* 1 is true; 0 is false                     */
a = 4
b = 2
c = a > b
SAY 'The result of' a '>' b 'is' c
c = a < b
SAY 'The result of' a '<' b 'is' c
c = a = b
SAY 'The result of' a '=' b 'is' c
EXIT

When you run the procedure, it gives the following results:


[C:\]TF
The result of 4 > 2 is 1
The result of 4 < 2 is 0
The result of 4 = 2 is 0

[C:\]


ΓòÉΓòÉΓòÉ <hidden> Logical Operators - Examples ΓòÉΓòÉΓòÉ

The following procedure, AND.CMD, shows the AND operator checking for two true
statements.

/* Using the AND (&) Operator   */
/* 0 is false; 1 is true        */
a = 4
b = 2
c = 5
d = (a > b) & (b > c)
SAY 'The result of (a > b) & (b > c) is' d
d = (a > b) & (b < c)
SAY 'The result of (a > b) & (b < c) is' d
EXIT

When run on your system, AND.CMD displays the following on your screen as:



[C:\]AND
The result of (a > b) & (b > c) is 0
The result of (a > b) & (b < c) is 1

[C:\]

The following procedure, OR.CMD, shows the OR operator in a true statement
unless both values are false:

/* Using the OR (|) Operator    */
/* 0 is false; 1 is true        */
a = 4
b = 2
c = 5
d = (a > b) | (b > c)
SAY 'The result of (a > b) | (b > c) is' d
d = (a > b) | (b < c)
SAY 'The result of (a > b) | (b < c) is' d
EXIT

When run on your system, the procedure displays the following:


[C:\]OR
The result of (a > b) | (b > c) is 1
The result of (a > b) | (b < c) is 1

[C:\]


ΓòÉΓòÉΓòÉ <hidden> DO WHILE Example ΓòÉΓòÉΓòÉ

A procedure using a DO WHILE loop is DOWHILE.CMD.  It tests for a true or false
condition at the top of the loop.

/* Using a DO WHILE loop */
SAY 'Enter the amount of money available'
PULL salary
spent = 0
DO WHILE spent < salary
   SAY 'Type in cost of item'
   PULL cost
   spent = spent + cost
END
SAY 'Empty pockets.'
EXIT

After running the DOWHILE procedure, you see this on your screen:

[C:\]dowhile
Enter the amount of money available
100
Type in cost of item
57
Type in cost of item
24
Type in cost of item
33
Empty pockets.
[C:\]


ΓòÉΓòÉΓòÉ <hidden> DO UNTIL Example ΓòÉΓòÉΓòÉ

A procedure using a DO UNTIL loop is DOUNTIL.CMD.  It tests for a true or false
condition at the bottom of the loop:

/* Using a DO UNTIL loop */
SAY 'Enter the amount of money available'
PULL salary
spent = 0          /* Sets spent to a value of 0 */
DO UNTIL spent > salary
   SAY 'Type the cost of item'
   PULL cost
   spent = spent + cost
END
SAY 'Empty pockets.'
EXIT

When run, DOUNTIL.CMD displays on your screen as:

[C:\] DOUNTIL
Enter the amount of money available
50
Type the cost of item
37
Type the cost of item
14
Empty pockets.
[C:\]


ΓòÉΓòÉΓòÉ <hidden> OS/2 ΓòÉΓòÉΓòÉ

Trademark of the IBM Corporation.


ΓòÉΓòÉΓòÉ <hidden> Systems Application Architecture ΓòÉΓòÉΓòÉ

Trademark of the IBM Corporation.


ΓòÉΓòÉΓòÉ <hidden> Presentation Manager ΓòÉΓòÉΓòÉ

Trademark of the IBM Corporation.


ΓòÉΓòÉΓòÉ 10. Keyword Instructions ΓòÉΓòÉΓòÉ

A keyword instruction is one or more clauses, the first of which starts with a
keyword that identifies the instruction.  If the instruction has more than one
clause, the clauses are separated by a delimiter, in this case a semicolon (;).

Some keyword instructions, such as those starting with the keyword DO, can
include nested instructions.

In the syntax diagrams, symbols (words) in upper case letters denote keywords;
other words (such as expression) denote a collection of symbols. Keywords are
not case dependent: the symbols if, If, and iF would all invoke the instruction
IF. Also, you usually omit most of the clause delimiters (;) shown because they
are implied by the end of a line.


ΓòÉΓòÉΓòÉ 10.1. ADDRESS ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇADDRESSΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇΓöÇΓöÇ
                 Γö£ΓöÇenvironmentΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöñ
                 Γöé             ΓööΓöÇexpressionΓöÇΓöÿ Γöé
                 ΓööΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇexpression1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                  ΓööΓöÇVALUEΓöÇΓöÿ

Address is used to send a single command to a specified environment, code an
environment, a literal string, or a single symbol, which is taken to be a
constant, followed by an expression. The expression is evaluated, and the
resulting command string is routed to environment. After the command is
executed, environment is set back to whatever it was before, thus temporarily
changing the destination for a single command.

Example:

ADDRESS CMD "DIR C:\STARTUP.CMD"   /*   OS/2   */

If only environment is specified, a lasting change of destination occurs: all
commands that follow (clauses that are neither REXX instructions nor assignment
instructions) will be routed to the given command environment, until the next
ADDRESS instruction is executed. The previously selected environment is saved.

Example:

Suppose that the environment for a text editor is registered by the name EDIT:

address CMD
'DIR C:\STARTUP.CMD'
if rc=0 then 'COPY STARTUP.CMD *.TMP'
address EDIT

Subsequent commands are passed to the editor until the next ADDRESS
instruction.

Similarly, you can use the VALUE form to make a lasting change to the
environment.  Here expression1 (which may be just a variable name) is
evaluated, and the result forms the name of the environment.  The subkeyword
VALUE can be omitted as long as expression1 starts with a special character (so
that it cannot be mistaken for a symbol or string).

Example:

ADDRESS ('ENVIR'||number)

With no arguments, commands are routed back to the environment that was
selected before the previous lasting change of environment was made, and the
current environment name is saved. Repeated execution of ADDRESS alone,
therefore, switches the command destination between two environments
alternately. A null string for the environment name (" ") is the same as the
default environment.


ΓòÉΓòÉΓòÉ 10.2. ARG ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇΓöÇΓöÇARGΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇΓöÇtemplateΓöÇΓöÇΓöÿ

ARG is used to retrieve the argument strings provided to a program or internal
routine and assign them to variables.  It is a short form of the following
instruction:

 ΓöÇΓöÇPARSE UPPER ARGΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇΓöÇΓöÇ
                     ΓööΓöÇΓöÇΓöÇΓöÇtemplateΓöÇΓöÇΓöÇΓöÇΓöÿ

Template is a list of symbols separated by blanks or patterns.

Unless a subroutine or internal function is being run, the interpreter reads
the arguments given on the program invocation, translates them to uppercase
(for example, a lowercase a-z to an uppercase A-Z), and then parses them into
variables. Use the PARSE ARG instruction if you do not want uppercase
translation.

If a subroutine or internal function is being run, the data used will be the
argument strings passed to the routine.

The ARG (and PARSE ARG) instructions can be run as often as desired (typically
with different templates) and always parse the same current input strings.
There are no restrictions on the length or content of the data parsed except
those imposed by the caller.

Example:

/* String passed is "Easy Rider"  */

Arg adjective noun

/* Now:  "ADJECTIVE"  contains 'EASY'           */
/*       "NOUN"       contains 'RIDER'          */

If more than one string is expected to be available to the program or routine,
each can be selected in turn by using a comma in the parsing template.

Example:

/* function is invoked by  FRED('data X',1,5)   */

Fred:  Arg string, num1, num2

/* Now:  "STRING" contains 'DATA X'             */
/*       "NUM1"   contains '1'                  */
/*       "NUM2"   contains '5'                  */

Notes:

o The argument strings to a REXX program or internal routine can also be
  retrieved or checked by using the ARG built-in function.

o The source of the data being processed is also made available on entry to the
  program.  See the PARSE instruction (SOURCE option) for details.


ΓòÉΓòÉΓòÉ 10.3. CALL ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇΓöÇΓöÇCALLΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇnameΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇ

              Γöé           Γöé   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ       Γöé
              Γöé           Γöé                 Γöé       Γöé
              Γöé           ΓööΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇexpressionΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
              Γöé                                      Γöé
              Γö£ΓöÇΓöÇΓöÇOFFΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇERRORΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
              Γöé           Γö£ΓöÇΓöÇFAILUREΓöÇΓöÇΓöÇΓöÇΓöñ            Γöé
              Γöé           Γö£ΓöÇΓöÇHALTΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ            Γöé
              Γöé           ΓööΓöÇΓöÇNOTREADYΓöÇΓöÇΓöÇΓöÿ            Γöé
              Γöé                                      Γöé
              ΓööΓöÇΓöÇONΓöÇΓöÇΓö¼ΓöÇERRORΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
                     Γö£ΓöÇFAILUREΓöÇΓöÇΓöñ ΓööΓöÇNAMEΓöÇtrapnameΓöÇΓöÿ
                     Γö£ΓöÇHALTΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                     ΓööΓöÇNOTREADYΓöÇΓöÿ

CALL is used to invoke a routine (if you specify name) or to control the
trapping of certain conditions (if ON or OFF is specified)

To control trapping, specify OFF or ON and the condition you want to trap.  OFF
turns off the specified condition trap.  ON turns on the specified condition
trap.

To invoke a routine, specify name, which is a symbol or literal string that is
taken as a constant.  The name must be a valid symbol. The routine invoked can
be any of the following:

o An internal routine
o An external routine
o A built-in function.

If a string is used for name (that is, name is specified in quotation marks)
the search for internal labels is bypassed, and only a built-in function or an
external routine is invoked.  Note that the names of built-in functions (and
generally the names of external routines too) are in uppercase; therefore, the
name in the literal string should be in uppercase.

The routine can optionally return a result and is functionally identical to the
clause:

ΓöÇresult=name(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇ;ΓöÇΓöÇ
                Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  Γöé
                Γöé                Γöé  Γöé
                ΓööΓöÇΓö┤Γö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓöÇΓöÿ
                   ΓööΓöÇexpressionΓöÇΓöÿ

The exception is that the variable result becomes uninitialized if no result is
returned by the routine invoked.

The name given in the CALL instruction must be a valid symbol.

The OS/2 interpreter supports the specification of up to 20 expressions,
separated by commas. The expressions are evaluated in order from left to right,
and form the argument strings during execution of the routine. Any ARG or PARSE
ARG instructions or ARG built-in function in the called routine will access
these strings rather than those previously active in the calling program.  You
can omit expressions, if appropriate, by including extra commas.

The CALL then causes a branch to the routine called name using the same
mechanism as function calls. The order in which these are searched for is
described in the section on functions.  A brief summary follows:

Internal routines:  These are sequences of instructions inside the same
                    program, starting at the label that matches name in the
                    CALL instruction. If the routine name is specified in
                    quotation marks, then an internal routine is not considered
                    for that search order.

Built-in routines:  These are routines built in to the language processor for
                    providing various functions.  They always return a string
                    containing the result of the function.

External routines:  Users can write or make use of routines that are external
                    to the language processor and the calling program. An
                    external routine can be written in any language, including
                    REXX, that supports the system-dependent interfaces.  If an
                    external routine, written in REXX, is invoked as a
                    subroutine by the CALL instruction, you can retrieve any
                    argument strings with the ARG or PARSE ARG instructions or
                    the ARG built-in function.


ΓòÉΓòÉΓòÉ 10.4. DO ΓòÉΓòÉΓòÉ


ΓöÇDOΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ;ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ENDΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼;ΓöÇΓöÇ
      ΓööΓöÇrepetitorΓöÇΓöÿ ΓööΓöÇconditionalΓöÇΓöÿ   ΓöéΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉΓöé    ΓööΓöÇnameΓöÇΓöÿ
                                      Γöé             ΓöéΓöé
                                      ΓööΓö┤ΓöÇinstructionΓöÇΓö┤Γöÿ

repetitor:

ΓöÇΓö¼ΓöÇname=expriΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇ
  Γöé            ΓööTOΓöÇexprtΓöÿ ΓööBYΓöÇexprbΓöÿ ΓööFORΓöÇexprfΓöÿ Γöé
  Γö£ΓöÇΓöÇFOREVERΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  ΓööΓöÇΓöÇexprrΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


conditional:

ΓöÇΓöÇΓöÇΓö¼ΓöÇWHILEΓöÇexprwΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇ
    ΓööΓöÇUNTILΓöÇexpruΓöÇΓöÇΓöÿ

DO is used to group instructions together and optionally to execute them
repetitively. During repetitive execution, a control variable (name) can be
stepped through some range of values.

Syntax Notes:

o The exprr, expri, exprb, exprt, and exprf options (if any are present) are
  any expressions that evaluate to a number. The exprr and exprf options are
  further restricted to result in a nonnegative whole number. If necessary, the
  numbers will be rounded according to the setting of NUMERIC DIGITS.

o The exprw or expru options (if present) can be any expression that evaluates
  to 1 or 0.

o The TO, BY, and FOR phrases can be in any order, if used.

o The instructions can include assignments, commands, and keyword instructions
  (including any of the more complex constructs such as IF, SELECT, and the DO
  instruction itself).

o The subkeywords TO, BY, FOR, WHILE, and UNTIL are reserved within a DO
  instruction, in that they cannot name variables in the expressions but they
  can be used as the name of the control variable. FOREVER is similarly
  reserved, but only if it immediately follows the keyword DO.

o The exprb option defaults to 1, if relevant.

Simple DO Group:

If neither repetitor nor conditional is given, the construct merely groups a
number of instructions together.  These are executed once. Otherwise, the group
of instructions is a repetitive DO loop, and they are executed according to the
repetitor phrase, optionally modified by the conditional phrase.

In the following example, the instructions are executed once.

Example:

/* The two instructions between DO and END will both */
/* be executed if A has the value 3.                 */
If a=3 then Do
            a=a+2
            Say 'Smile!'
            End

Simple Repetitive Loops:

If repetitor is omitted but there is a conditional or the repetitor is FOREVER,
the group of instructions will nominally be executed forever, that is, until
the condition is satisfied or a REXX instruction is executed that ends the loop
(for example, LEAVE).

In the simple form of a repetitive loop, exprr is evaluated immediately (and
must result in a nonnegative whole number), and the loop is then executed that
many times.

Example:

/* This displays "Hello" five times */
Do 5
  say 'Hello'
  end

Note that, similar to the distinction between a command and an assignment, if
the first character of exprr is a symbol and the second is an "=" character,
the controlled form of repetitor is expected.

Controlled Repetitive Loops:

The controlled form specifies a control variable, name, which is assigned an
initial value (the result of expri, formatted as though 0 had been added). The
variable is then stepped (that is, the result of exprb is added at the bottom
of the loop) each time the group of instructions is run. The group is run
repeatedly while the end condition (determined by the result of exprt) is not
met. If exprb is positive or zero, the loop will be terminated when name is
greater than exprt. If negative, the loop is terminated when name is less than
exprt.

The expri, exprt, and exprb options must result in numbers.  They are evaluated
once only, before the loop begins and before the control variable is set to its
initial value. The default value for exprb is 1. If exprt is omitted, the loop
is run indefinitely unless some other condition terminates it.

Example:

Do I=3 to -2 by -1        /* Would display:   */
  say i                   /*      3           */
  end                     /*      2           */
                          /*      1           */
                          /*      0           */
                          /*      -1          */
                          /*      -2          */

The numbers do not have to be whole numbers.

Example:

X=0.3                     /* Would display:   */
Do Y=X to X+4 by 0.7      /*     0.3          */
  say Y                   /*     1.0          */
  end                     /*     1.7          */
                          /*     2.4          */
                          /*     3.1          */
                          /*     3.8          */

The control variable can be altered within the loop, and this may affect the
iteration of the loop. Altering the value of the control variable is not
normally considered good programming practice, though it may be appropriate in
certain circumstances.

Note that the end condition is tested at the start of each iteration (and after
the control variable is stepped, on the second and subsequent iterations).
Therefore, the group of instructions can be skipped entirely if the end
condition is met immediately. Note also that the control variable is referred
to by name. If, for example, the compound name A.I is used for the control
variable, altering I within the loop causes a change in the control variable.

The processing of a controlled loop can be bounded further by a FOR phrase. In
this case, exprf must be given and must evaluate to a nonnegative whole number.
This acts just like the repetition count in a simple repetitive loop, and sets
a limit to the number of iterations around the loop if no other condition
terminates it. Similar to the TO and BY expressions, it is evaluated once
only-when the DO instruction is first executed and before the control variable
is given its initial value. Like the TO condition, the FOR condition is checked
at the start of each iteration.

Example:

Do Y=0.3 to 4.3 by 0.7 for 3  /* Would display:    */
  say Y                       /*     0.3           */
  end                         /*     1.0           */
                              /*     1.7           */

In a controlled loop, the name describing the control variable can be specified
on the END clause. This name must match name in the DO clause in all respects
except case (note that no substitution for compound variables is carried out);
a syntax error results if it does not. This enables the nesting of loops to be
checked automatically, with minimal overhead.

Example:

Do K=1 to 10
  ...
  ...
  End k  /* Checks that this is the END for K loop */

Note:   The values taken by the control variable may be affected by the NUMERIC
        settings, since normal REXX arithmetic rules apply to the computation
        of stepping the control variable.

Conditional Phrases (WHILE and UNTIL):

Any of the forms of repetitor (none, FOREVER, simple, or controlled) can be
followed by a conditional phrase, which may cause termination of the loop. If
you specify WHILE or UNTIL, exprw or expru, respectively, is evaluated each
time around the loop using the latest values of all variables (and must
evaluate to either 0 or 1). The group of instructions is repeatedly processed
either while the result is 1 or until the result is 1.

For a WHILE loop, the condition is evaluated at the top of the group of
instructions; for an UNTIL loop, the condition is evaluated at the bottom,
before the control variable has been stepped.

Example:

Do I=1 to 10 by 2 until i>6
  say i
  end
/* Will display: 1, 3, 5, 7 */

Note:   The processing of repetitive loops can also be modified by using the
        LEAVE or ITERATE instructions.


ΓòÉΓòÉΓòÉ 10.5. DROP ΓòÉΓòÉΓòÉ

              ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                         Γöé
 ΓöÇΓöÇΓöÇΓöÇDROPΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇnameΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Each name is a valid variable symbol, optionally enclosed in parentheses (to
denote a subsidiary list), and separated from any other name by one or more
blanks or comments.

DROP is used to unassign variables; that is, to restore them to their original
uninitialized state.

Each variable specified is dropped from the list of known variables. If a
single name is enclosed in parentheses, then its value is used as a subsidiary
list of variables to drop. This stored list must follow the same rules as for
the main list (that is, valid variable names, separated by blanks) but with no
parentheses and no leading or trailing blanks. The variables are dropped in
sequence from left to right. It is not an error to specify a name more than
once, or to DROP a variable that is not known. If an exposed variable is named
(see the PROCEDURE instruction), the variable itself in the older generation is
dropped.

Example:

j=4
Drop  a x.3 x.j
/* would reset the variables: A, X.3, and X.4 */
/* so that reference to them returns their name.    */

Here, a variable name in parentheses is used as a subsidiary list.

Example:

x=4;y=5;z=6;
a='x y z'
DROP (a)    /* will drop x,y, and z */

If a stem is specified (that is, a symbol that contains only one period, as the
last character), all variables starting with that stem are dropped.

Example:

Drop  x.
/* would reset all variables with names starting with X. */


ΓòÉΓòÉΓòÉ 10.6. EXIT ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇΓöÇΓöÇEXITΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ

EXIT is used to leave a program unconditionally. Optionally, EXIT returns a
data string to the caller. The program is terminated immediately, even if an
internal routine is currently being run.  If no internal routine is active,
RETURN and EXIT are identical in their effect on the program that is being run.

If you specify expression, it is evaluated and the string resulting from the
evaluation is then passed back to the caller when the program terminates.

Example:

j=3
Exit j*4
/* Would exit with the string '12' */

If you do not specify expression, no data is passed back to the caller. If the
program was called as an external function, this is detected as an error,
either immediately (if RETURN was used), or on return to the caller (if EXIT
was used).

"Running off the end" of the program is always equivalent to the EXIT
instruction, in that it terminates the whole program and returns no result
string.

Note:   The language processor does not distinguish between invocation as a
        command on the one hand, and invocation as a subroutine or function on
        the other. If the program was invoked through a command interface, an
        attempt is made to convert the returned value to a return code
        acceptable by the REXX caller.  The returned string must be a whole
        number whose value will fit in a 16-bit signed integer (within the
        range -2**15 to 2**15-1).


ΓòÉΓòÉΓòÉ 10.7. IF ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇIFΓöÇexpressionΓöÇΓö¼ΓöÇΓö¼THENΓöÇΓö¼ΓöÇΓö¼instructionΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ
                   Γöö;Γöÿ     Γöö;Γöÿ            ΓööΓöÇELSEΓöÇΓö¼ΓöÇΓö¼instructionΓöÿ
                                                 Γöö;Γöÿ

IF is used to conditionally process an instruction or group of instructions
depending on the evaluation of the expression. The expression must evaluate to
0 or 1.

The instruction after the THEN is processed only if the result of the
evaluation is 1. If you specify an ELSE clause, the instruction after ELSE is
processed only if the result of the evaluation is 0.

Example:

if answer='YES' then say 'OK!'
                else say 'Why not?'

Remember that if the ELSE clause is on the same line as the last clause of the
THEN part, you need a semicolon to terminate that clause.

Example:

if answer='YES' then say 'OK!';  else say 'Why not?'

The ELSE binds to the nearest IF at the same level. The NOP instruction can be
used to eliminate errors and possible confusion when IF constructs are nested,
as in the following example.

Example:

If answer = 'YES' Then
   If name = 'FRED' Then
      say 'OK, Fred.'
   Else
      nop
Else
   say 'Why not?'

Notes:

 1. The instruction can be any assignment, command, or keyword instruction,
    including any of the more complex constructs such as DO, SELECT, or the IF
    instruction itself. A null clause is not an instruction; so putting an
    extra semicolon after the THEN or ELSE is not equivalent to putting a dummy
    instruction (as it would be in C). The NOP instruction is provided for this
    purpose.

 2. The symbol THEN cannot be used within expression, because the keyword THEN
    is treated differently, in that it need not start a clause.  This allows
    the expression on the IF clause to be terminated by the THEN, without a
    semicolon being required.  If this were not so, users of other computer
    languages would experience considerable difficulties.


ΓòÉΓòÉΓòÉ 10.8. INTERPRET ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇΓöÇΓöÇINTERPRETΓöÇΓöÇΓöÇΓöÇexpressionΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

INTERPRET is used to process instructions that have been built dynamically by
evaluating expression.

The expression is evaluated, and is then processed (interpreted) as though the
resulting string was a line inserted into the input file (and bracketed by a
DO; and an END;).

Any instructions (including INTERPRET instructions) are allowed, but note that
constructions such as DO ... END and SELECT ... END must be complete. For
example, a string of instructions being interpreted cannot contain a LEAVE or
ITERATE instruction (valid only within a repetitive DO loop) unless it also
contains the whole repetitive DO ... END construct.

A semicolon is implied at the end of the expression during processing, as a
service to the user.

Example:

data='FRED'
interpret data '= 4'
/* Will a) build the string  "FRED = 4"         */
/*      b) execute  FRED = 4;                   */
/* Thus the variable "FRED" will be set to "4"  */

Example:

data='do 3; say "Hello there!"; end'
interpret data        /* Would display:         */
                      /*  Hello there!          */
                      /*  Hello there!          */
                      /*  Hello there!          */

Notes:

 1. Labels within the interpreted string are not permanent and are therefore
    ignored. Therefore, executing a SIGNAL instruction from within an
    interpreted string causes immediate exit from that string before the label
    search begins.

 2. If you are new to the concept of the INTERPRET instruction and are getting
    results that you do not understand, you might find that executing the
    instruction with TRACE R or TRACE I set is helpful.

    Example:

        /* Here we have a small program. */
        Trace Int
        name='Kitty'
        indirect='name'
        interpret 'say "Hello"' indirect'"!"'

    when run, the following trace is displayed:

        [C:\]kitty
        kitty
             3 *-* name='Kitty'
               >L>   "Kitty"
             4 *-* indirect='name'
               >L>   "name"
             5 *-* interpret 'say "Hello"' indirect'"!"'
               >L>   "say "Hello""
               >V>   "name"
               >O>   "say "Hello" name"
               >L>   ""!""
               >O>   "say "Hello" name"!""
               *-*  say "Hello" name"!"
               >L>    "Hello"
               >V>    "Kitty"
               >O>    "Hello Kitty"
               >L>    "!"
               >O>    "Hello Kitty!"
        Hello Kitty!
        [C:\]

    Lines 3 and 4 set the variables used in line 5. Execution of line 5 then
    proceeds in two stages. First the string to be interpreted is built up,
    using a literal string, a variable (INDIRECT), and another literal. The
    resulting pure character string is then interpreted, as though it were
    actually part of the original program. Since it is a new clause, it is
    traced as such (the second *-* trace flag under line 5) and is then
    executed. Again a literal string is concatenated to the value of a variable
    (NAME) and another literal, and the final result is then displayed as
    follows:

        Hello Kitty!

 3. For many purposes, the VALUE function can be used instead of the INTERPRET
    instruction.  Line 5 in the last example could therefore have been replaced
    by:

        say "Hello" value(indirect)"!"

    INTERPRET is usually only required in special cases, such as when more than
    one statement is to be interpreted at once.


ΓòÉΓòÉΓòÉ 10.9. ITERATE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇΓöÇITERATEΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇΓöÇnameΓöÇΓöÇΓöÿ

ITERATE is used to alter the flow within a repetitive DO loop (that is, any DO
construct other than that with a simple DO loop).

Processing of the group of instructions stops, and control is passed to the DO
instruction just as though the END clause had been encountered. The control
variable (if any) is incremented and tested, as normal, and the group of
instructions is processed again, unless the loop is terminated by the DO
instruction.

If name is not specified, ITERATE steps the innermost active repetitive loop.
If name is specified, it must be the name of the control variable of a
currently active loop which may be the innermost loop; this is the loop that is
stepped. Any active loops inside the one selected for iteration are terminated
(as though by a LEAVE instruction).

Example:

do i=1 to 4
  if i=2 then iterate
  say i
  end
/* Would display the numbers:   1, 3, 4  */

Notes:

 1. If specified, name must match the name on the DO instruction in all
    respects except case. No substitution for compound variables is carried out
    when the comparison is made.

 2. A loop is active if it is currently being processed. If during execution of
    a loop, a subroutine is called or an INTERPRET instruction is processed,
    the loop becomes inactive until the subroutine has returned or the
    INTERPRET instruction has completed. ITERATE cannot be used to step an
    inactive loop.

 3. If more than one active loop uses the same control variable, the innermost
    loop is the one selected by ITERATE.


ΓòÉΓòÉΓòÉ 10.10. LEAVE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇΓöÇLEAVEΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇΓöÇnameΓöÇΓöÇΓöÿ

LEAVE is used to cause an immediate exit from one or more repetitive DO loops
(that is, any DO construct other than a simple DO loop).

Processing of the group of instructions is terminated, and control is passed to
the instruction following the END clause as though the END clause had been
encountered and the termination condition had been met normally.  However, on
exit, the control variable, if any, will contain the value it had when the
LEAVE instruction was processed.

If name is not specified, LEAVE terminates the innermost active repetitive
loop. If name is specified, it must be the name of the control variable of a
currently active loop which may be the innermost loop; that loop (and any
active loops inside it) is then terminated. Control then passes to the clause
following the END clause that matches the DO clause of the selected loop.

Example:

do i=1 to 5
  say i
  if i=3 then leave
  end
/* Would display the numbers:   1, 2, 3  */

Notes:

 1. If specified, name must match the one on the DO instruction in all respects
    except case. No substitution for compound variables is carried out when the
    comparison is made.

 2. A loop is active if it is currently being processed. If during execution of
    a loop, a subroutine is called or an INTERPRET instruction is processed,
    the loop becomes inactive until the subroutine has returned or the
    INTERPRET instruction has completed. LEAVE cannot be used to terminate an
    inactive loop.

 3. If more than one active loop uses the same control variable, the innermost
    one is the one selected by LEAVE.


ΓòÉΓòÉΓòÉ 10.11. NOP ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇΓöÇNOPΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

NOP is a dummy instruction that has no effect.  It can be useful as the target
of a THEN or ELSE clause.

Example:

Select
   when a=b then nop           /* Do nothing */
   when a>b then say 'A > B'
   otherwise     say 'A < B'
end

Note:   Using an extra semicolon instead of the NOP inserts a null clause,
        which is ignored. The second WHEN clause is seen as the first
        instruction expected after the THEN clause, and therefore is treated as
        a syntax error. NOP is a true instruction, however, and is a valid
        target for the THEN clause.


ΓòÉΓòÉΓòÉ 10.12. NUMERIC ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇNUMERICΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇDIGITSΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ;ΓöÇΓöÇ
                 Γöé         ΓööΓöÇexpressionΓöÇΓöÇΓöÿ         Γöé
                 Γö£ΓöÇΓöÇFORMΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöñ
                 Γöé        Γö£ΓöÇSCIENTIFICΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
                 Γöé        Γö£ΓöÇENGINEERINGΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
                 Γöé        ΓööΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇexpressionΓöÇΓöÿ Γöé
                 Γöé          ΓööΓöÇVALUEΓöÇΓöÿ              Γöé
                 ΓööΓöÇΓöÇFUZZΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                          ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ

The NUMERIC instruction is used to change the way in which arithmetic
operations are carried out. The options of this instruction are described in
detail in the OS/2 Procedures Language 2/REXX Reference.

NUMERIC DIGITS controls the precision to which arithmetic operations and
arithmetic built-in functions are evaluated. If expression is omitted, then the
default value of 9 is used.  Otherwise the result of the expression is rounded,
if necessary, according to the current setting of NUMERIC DIGITS. The value
used must be a positive whole number that is larger than the current NUMERIC
FUZZ setting.

There is no limit to the value for DIGITS (except the amount of storage
available), but note that high precisions are likely to require a good deal of
processor time. It is recommended that you use the default value wherever
possible.

You can retrieve the current setting of NUMERIC DIGITS with the DIGITS built-in
function

NUMERIC FORM controls the form of exponential notation used by REXX for the
result of arithmetic operations and arithmetic built-in functions. This may be
either SCIENTIFIC (in which case only one, nonzero digit appears before the
decimal point), or ENGINEERING (in which case the power of ten is always a
multiple of three). The default is SCIENTIFIC. The FORM is set either directly
by the subkeywords SCIENTIFIC or ENGINEERING or is taken from the result of
evaluating the expression following VALUE. The result in this case must be
either SCIENTIFIC or ENGINEERING. You can omit the subkeyword VALUE if the
expression does not begin with a symbol or a literal string (for example, if it
starts with a special character, such as an operator or parenthesis).

You can retrieve the current setting of NUMERIC FORM with the FORM built-in
function

NUMERIC FUZZ controls how many digits, at full precision, are ignored during a
numeric comparison operation. If expression is omitted, the default is 0
digits.  Otherwise expression must evaluate to 0 or a positive whole number
rounded, if necessary, according to the current setting of NUMERIC DIGITS
before it is used. The value used must be a positive whole number that is
smaller than the current NUMERIC DIGITS setting.

FUZZ temporarily reduces the value of DIGITS by the FUZZ value before every
numeric comparison operation. The numbers being compared are subtracted from
each other under a precision of DIGITS minus FUZZ digits and this result is
then compared with 0.

You can retrieve the current NUMERIC FUZZ setting with the FUZZ built-in
function

Note:   The three numeric settings are automatically saved across subroutine
        and internal function calls.  See the CALL instruction for more
        details.


ΓòÉΓòÉΓòÉ 10.13. OPTIONS ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇΓöÇOPTIONSΓöÇΓöÇΓöÇΓöÇΓöÇexpressionΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

OPTIONS is used to pass special requests or parameters to the language
processor.  For example, they can be language processor options or they can
define a special character set.

The expression is evaluated, and the result is examined one word at a time.  If
the words are recognized by the language processor, then they are obeyed.
Words that are not recognized are ignored and assumed to be instructions to a
different processor.

The following words are recognized by the language processors:

ETMODE            Specifies that literal strings containing double-byte
                  character set (DBCS) characters can be used in the program.

NOETMODE          Specifies that literal strings containing DBCS characters
                  cannot be used in the program. NOETMODE is the default.

EXMODE            Specifies that DBCS data in mixed strings is handled on a
                  logical character basis by instructions, operators and
                  functions. DBCS data integrity is maintained.

NOEXMODE          Specifies that any data in strings is handled on a byte
                  basis. The integrity of any DBCS characters might be lost.
                  NOEXMODE is the default.
Notes:

 1. Because of the scanning procedures of the language processor, you are
    advised to place an OPTIONS ETMODE instruction as the first instruction of
    a program containing DBCS literal strings.

 2. To ensure proper scanning of a program containing DBCS literals, type the
    words ETMODE, NOETMODE, EXMODE, and NOEXMODE as literal strings (that is,
    enclosed in quotation marks) in the OPTIONS instruction.

 3. The OPTIONS ETMODE and OPTIONS EXMODE settings are saved and restored
    across subroutine and function calls.

 4. The words ETMODE, EXMODE, NOEXMODE, and NOETMODE can occur several times
    within the result. The word that takes effect is determined by the last
    valid one specified between the pairs ETMODE/NOETMODE and EXMODE/NOEXMODE.


ΓòÉΓòÉΓòÉ 10.14. 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.


ΓòÉΓòÉΓòÉ 10.15. PROCEDURE ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇΓöÇPROCEDUREΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 Γöé          ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
                 Γöé                 Γöé Γöé
                 ΓööΓöÇΓöÇEXPOSEΓöÇΓöÇΓö┤ΓöÇnameΓöÇΓöÇΓö┤ΓöÇΓöÿ

The PROCEDURE instruction can be used within an internal routine (subroutine or
function) to protect all the existing variables by making them unknown to the
instructions that follow. On executing a RETURN instruction, the original
variables environment is restored and any variables used in the routine (which
were not exposed) are dropped.

The EXPOSE option modifies this.  Any variable specified by name is exposed, so
that any reference to it (including setting and dropping) is made to the
environment of the variables that the caller owns. With the EXPOSE option, you
must specify at least one name, a symbol separated from any other name with one
or more blanks. Optionally, you can enclose a single name in parentheses to
denote a subsidiary variable list. Any variables not specified by name on a
PROCEDURE EXPOSE instruction are still protected.  Hence, some limited set of
the caller's variables can be made accessible, and these variables can be
changed (or new variables in this set can be created).  All these changes will
be visible to the caller upon RETURN from the routine.

The variables are exposed in sequence from left to right. It is not an error to
specify a name more than once, or to specify a name that has not been used as a
variable by the caller.

Example:

/* This is the main program */
j=1; x.1='a'
call toft
say j k m       /* would display "1 7 M" */
exit

toft: procedure expose j k x.j
   say j k x.j  /* would display "1 K a"   */
   k=7; m=3     /* note "M" is not exposed */
   return

Note that if X.J in the EXPOSE list had been placed before J, the caller's
value of J would not have been visible at that time, so X.1 would not have been
exposed.

If name is enclosed in parentheses (blanks are not necessary either inside or
outside the parentheses but can be added if desired) then, after that variable
is exposed, the value of the variable is immediately used as a subsidiary list
of variables.  This list of variables must follow the same rules as the main
list except that no parentheses or leading or trailing blanks are allowed. The
variables named in a subsidiary list are also exposed from left to right.

Example:

j=1;k=6;m=9
a ='j k m'
test:procedure expose (a)   /* will expose j, k, and x */

If a stem is specified in names, all possible compound variables whose names
begin with that stem are exposed. (A stem is a symbol containing only one
period, which is the last character.

Example:

lucky7:Procedure Expose i j a. b.
/* This exposes "I", "J", and all variables whose */
/* names start with "A." or "B."                  */
A.1='7'  /* This will set "A.1" in the caller's   */
         /* environment, even if it did not       */
         /* previously exist.                     */

Variables can be exposed through several generations of routines, if desired,
by ensuring that they are included on all intermediate PROCEDURE instructions.

Only one PROCEDURE instruction in each level of routine call is allowed; all
others (and those met outside of internal routines) are in error.

Notes:

 1. An internal routine need not include a PROCEDURE instruction, in which case
    the variables it is manipulating are those the caller owns.

 2. The PROCEDURE instruction must be the first instruction executed after the
    CALL or function invocation, that is, it must be the first instruction
    following the label.

See the CALL instruction for details and examples of how routines are invoked.


ΓòÉΓòÉΓòÉ 10.16. PULL ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇΓöÇΓöÇPULLΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇΓöÇtemplateΓöÇΓöÇΓöÿ

PULL is used to read a string from the head of the currently active REXX data
queue. It is a short form of the instruction:

 ΓöÇΓöÇPARSE UPPER PULLΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ;ΓöÇΓöÇΓöÇΓöÇ
                       ΓööΓöÇΓöÇtemplateΓöÇΓöÇΓöÇΓöÿ

The current head-of-queue is read as one string.  If no template is specified,
no further action is taken, and the string is effectively discarded.  If
specified, a template is a list of symbols separated by blanks or patterns. The
string is translated to uppercase (for example, a lowercase a-z to an uppercase
A-Z), and then parsed into variables according to the rules described in the
section on parsing in the OS/2 Procedures Language 2/REXX Reference.  Use the
PARSE PULL instruction if you do not want uppercase translation.

Note:   If the current data queue is empty, PULL reads instead from STDIN
        (typically, the keyboard). The length of data read by the PULL
        instruction is restricted to the length of strings contained by
        variables.

Example:

Say 'Do you want to erase the file?  Answer Yes or No:'
Pull answer .
if answer='NO' then Say 'The file will not be erased.'

Here the dummy placeholder "." is used on the template to isolate the first
word the user enters.

The number of lines currently in the queue can be found with the QUEUED
built-in function.


ΓòÉΓòÉΓòÉ 10.17. PUSH ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇΓöÇΓöÇPUSHΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ

PUSH is used to stack the string resulting from the evaluation of expression in
LIFO (last in, first out) format onto the currently active REXX data queue. If
you do not specify expression, a null string is stacked.

Example:

a='Fred'
push       /* Puts a null line onto the queue */
push a 2   /* Puts "Fred 2"    onto the queue */

The number of lines currently in the queue can be found with the QUEUED
built-in function.


ΓòÉΓòÉΓòÉ 10.18. QUEUE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇΓöÇQUEUEΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ

QUEUE is used to append the string resulting from expression to the tail of the
currently active REXX data queue. That is, it is added in FIFO (first in, first
out) format.

If you do not specify expression, a null string is queued.

Example:

a='Toft'
queue a 2  /* Enqueues "Toft 2" */
queue      /* Enqueues a null line behind the last */

The number of lines currently in the queue can be found with the QUEUED
built-in function.


ΓòÉΓòÉΓòÉ 10.19. RETURN ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇΓöÇRETURNΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ

RETURN is used to return control (and possibly a result) from a REXX program or
internal routine to the point of its invocation.

If no internal routine (subroutine or function) is active, RETURN and EXIT are
identical in their effect on the program that is being run.

If a subroutine is being processed (see the CALL instruction), expression (if
any) is evaluated, control passes back to the caller, and the REXX special
variable RESULT is set to the value of expression. If expression is omitted,
the special variable RESULT is dropped (becomes uninitialized). The various
settings saved at the time of the CALL (tracing, addresses, and so on) are also
restored.

If a function is being processed, the action taken is identical, except that
expression must be specified on the RETURN instruction. The result of
expression is then used in the original expression at the point where the
function was invoked.

If a PROCEDURE instruction was processed within the routine (subroutine or
internal function), all variables of the current generation are dropped (and
those of the previous generation are exposed) after expression is evaluated and
before the result is used or assigned to RESULT.


ΓòÉΓòÉΓòÉ 10.20. SAY ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇΓöÇSAYΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇΓöÇexpressionΓöÇΓöÇΓöÿ

SAY is used to write to the output stream the result of evaluating expression.
The result is usually displayed to the user, but the output destination can
depend on the implementation. The result of expression can be of any length.

Notes:

 1. Data from the SAY instruction is sent to the default output stream
    (STDOUT:) However, the standard OS/2 rules for redirecting output apply to
    SAY output.

 2. The SAY instruction does not format data; line wrapping is handled by the
    operating system and the hardware. However formatting is accomplished, the
    output data remains a single logical line.

Example:

data=100
Say data 'divided by 4 =>' data/4
/* Would display: "100 divided by 4 => 25"  */


ΓòÉΓòÉΓòÉ 10.21. SELECT ΓòÉΓòÉΓòÉ


             ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                                                       Γöé
 ΓöÇΓöÇSELECT;ΓöÇΓö┤WHENΓöÇexpressionΓöÇΓö¼ΓöÇΓö¼ΓöÇTHENΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇinstructionΓö┤ΓöÇΓöÇ
                              Γöö;Γöÿ      Γöö;Γöÿ

  ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇEND;ΓöÇΓöÇΓöÇΓöÇΓöÇ
        ΓööΓöÇOTHERWISEΓöÇΓö¼ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                    Γöö;Γöÿ Γöé  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  Γöé
                        Γöé               Γöé  Γöé
                        ΓööΓöÇΓöÇΓö┤ΓöÇinstructionΓöÇΓö┤ΓöÇΓöÇΓöÿ

SELECT is used to conditionally process one of several alternative
instructions.

Each expression after a WHEN clause is evaluated in turn and must result in 0
or 1. If the result is 1, the instruction following the THEN clause, which can
be a complex instruction such as IF, DO, or SELECT, is processed and control
then passes to the END clause. If the result is 0, control passes to the next
WHEN clause.

If none of the WHEN expressions evaluate to 1, control passes to the
instructions, if any, after OTHERWISE. In this situation, the absence of
OTHERWISE causes an error.

Example:

  balance = balance - check
  Select
    when balance > 0 then
      say 'Congratulations! You still have' balance 'dollars left.'
    when balance = 0 then do
      say 'Warning, Balance is now zero!  STOP all spending.'
      say "You cut it close this month! Hope you don't have any"
      say "checks left outstanding."
      end
    Otherwise
      say "You have just overdrawn your account."
      say "Your balance now shows" balance "dollars."
      say "Oops!  Hope the bank doesn't close your account."
  end  /* Select */

Notes:

 1. The instruction can be any assignment, command, or keyword instruction,
    including any of the more complex constructs such as DO, IF, or the SELECT
    instruction itself.

 2. A null clause is not an instruction, so putting an extra semicolon after a
    WHEN clause is not equivalent to putting a dummy instruction. The NOP
    instruction is provided for this purpose.

 3. The symbol THEN cannot be used within expression, because the keyword THEN
    is treated differently, in that it need not start a clause.  This allows
    the expression on the WHEN clause to be terminated by the THEN without a ;
    (delimiter) being required.


ΓòÉΓòÉΓòÉ 10.22. SIGNAL ΓòÉΓòÉΓòÉ


 ΓöÇΓöÇSIGNALΓöÇΓöÇΓöÇΓö¼ΓöÇ labelname ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇ;ΓöÇ
              Γö£ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ expression ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
              Γöé Γöö VALUE Γöÿ                            Γöé
              Γö£ΓöÇΓöÇ OFF ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ ERROR ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
              Γöé           Γö£ΓöÇ FAILURE ΓöÇΓöÇΓöÇΓöñ            Γöé
              Γöé           Γö£ΓöÇ HALT ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ            Γöé
              Γöé           Γö£ΓöÇ NOVALUE ΓöÇΓöÇΓöÇΓöñ            Γöé
              Γöé           Γö£ΓöÇ SYNTAX ΓöÇΓöÇΓöÇΓöÇΓöñ            Γöé
              Γöé           ΓööΓöÇ NOTREADY ΓöÇΓöÇΓöÿ            Γöé
              Γöé                                      Γöé
              ΓööΓöÇ ON ΓöÇΓö¼ΓöÇ ERROR ΓöÇΓöÇΓöÇΓö¼Γö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                     Γö£ΓöÇ FAILURE ΓöÇΓöñΓöö NAME ΓöÇ trapname Γöÿ
                     Γö£ΓöÇ HALT ΓöÇΓöÇΓöÇΓöÇΓöñ
                     Γö£ΓöÇ NOVALUE ΓöÇΓöñ
                     Γö£ΓöÇ SYNTAX ΓöÇΓöÇΓöñ
                     ΓööΓöÇ NOTREADY Γöÿ

SIGNAL is used to cause an abnormal change in the flow of control, or, if ON or
OFF is specified, controls the trapping of certain conditions.

To control trapping, you specify OFF or ON and the condition you want to trap.
OFF turns off the specified condition trap.  ON turns on the specified
condition trap.

Note:   For information on condition traps, see the OS/2 Procedures Language
        2/REXX Reference.

To change the flow of control, a label name is derived from labelname or taken
from the result of evaluating the expression after VALUE. The labelname you
specify must be a symbol, treated literally, or a literal string that is taken
as a constant. The subkeyword VALUE can be omitted if expression does not begin
with a symbol or literal string (for example, if it starts with a special
character, such as an operator or parenthesis).  All active pending DO, IF,
SELECT, and INTERPRET instructions in the current routine are then terminated;
that is, they cannot be reactivated. Control then passes to the first label in
the program that matches the required string, as though the search had started
from the top of the program.

Example:

Signal fred;  /* Jump to label "FRED" below */
  ....
  ....
Fred: say 'Hi!'

Because the search effectively starts at the top of the program, if duplicates
are present, control always passes to the first occurrence of the label in the
program

When control reaches the specified label, the line number of the SIGNAL
instruction is assigned to the special variable SIGL. This can aid debugging
because SIGNAL can determine the source of a jump to a label.

Using SIGNAL with the INTERPRET Instruction

If, as the result of an INTERPRET instruction, a SIGNAL instruction is issued
or a trapped event occurs, the remainder of the strings being interpreted are
not searched for the given label. In effect, labels within interpreted strings
are ignored.


ΓòÉΓòÉΓòÉ 10.23. TRACE ΓòÉΓòÉΓòÉ


ΓöÇ TRACE ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ;ΓöÇ
           Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    ΓööΓöÇ number ΓöÇΓöÿ        Γöé
           Γöé            Γöé                        Γöé
           ΓööΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö┤ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
               ΓööΓöÇΓöÇΓöÇ?ΓöÇΓöÇΓöÇΓöÿ   Γö£ΓöÇΓöÇ All ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                           Γö£ΓöÇΓöÇ Commands ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                           Γö£ΓöÇΓöÇ Error ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                           Γö£ΓöÇΓöÇ Failure ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                           Γö£ΓöÇΓöÇ Intermediates ΓöÇΓöÇΓöÇΓöñ
                           Γö£ΓöÇΓöÇ Labels ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                           Γö£ΓöÇΓöÇ Normal ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                           Γö£ΓöÇΓöÇ Off ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                           ΓööΓöÇΓöÇ Results ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Or, alternatively:


ΓöÇΓöÇTRACEΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ;ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇstringΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇsymbolΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
            ΓööΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇexpressionΓöÇΓöÇΓöÇΓöÿ
               ΓööΓöÇVALUEΓöÇΓöÿ

TRACE is used for debugging.  It controls the tracing action taken (that is,
how much is displayed to the user) during execution of a REXX program.  The
syntax of TRACE is more concise than other REXX instructions.  The economy of
key strokes for this instruction is especially convenient since TRACE is
usually entered manually during interactive debugging.

The number is a whole number.

The string or expression evaluates to:

o A number option
o One of the valid prefix, alphabetic character (word) options, or both, shown
  in this panel
o Null.

The symbol is taken as a constant and is:

o A number option
o One of the valid prefix, alphabetic character (word) options, or both, shown
  in this panel.

The tracing action is determined from the option specified following TRACE or
from the result of evaluating expression. If expression is used, you can omit
the subkeyword VALUE as long as expression starts with a special character or
operator (so it is not mistaken for a symbol or string).

Alphabetic Character (Word) Options

Although it is acceptable to enter the word in full, only the uppercase letter
is significant; all other letters are ignored. That is why these are referred
to as alphabetic character options.

TRACE actions correspond to the alphabetic character options as follows:

All                   All clauses are traced (that is, displayed) before
                      execution.

Commands              All host commands are traced before execution, and any
                      error return code is displayed.

Error                 Any host command resulting in an error return code is
                      traced after execution.

Failure               Any host command resulting in a failure is traced after
                      execution. This is the same as the Normal option.

Intermediates         All clauses are traced before execution. Intermediate
                      results during evaluation of expressions and substituted
                      names are also traced.

Labels                Labels passed during execution are traced. This is
                      especially useful with debug mode, when the language
                      processor pauses after each label.  It is also convenient
                      for the user to make note of all subroutine calls and
                      signals.

Normal                Any failing host command is traced after execution. This
                      is the default setting.

                      For the default CMD processor in the OS/2 operating
                      system, an attempt to issue an unknown command raises a
                      FAILURE condition. An attempt to issue a command to an
                      unknown subcommand environment also raises a FAILURE
                      condition; in such a case, the variable RC is set to 2,
                      the OS/2 return code for "file not found".

Off                   Nothing is traced, and the special prefix actions (see
                      below) are reset to OFF.

Results               All clauses are traced before execution.  Final results
                      (contrast with Intermediates, above) of evaluating an
                      expression are traced.  Values assigned during PULL, ARG,
                      and PARSE instructions are also displayed.  This setting
                      is recommended for general debugging.

Prefix Option

The prefix ? is valid either alone or with one of the alphabetic character
options. You can specify the prefix more than once, if desired.  Each
occurrence of a prefix on an instruction reverses the action of the previous
prefix. The prefix must immediately precede the option (no intervening blanks).

The prefix ? modifies tracing and execution.  ? is used to control interactive
debug. During normal execution, a TRACE instruction prefixed with ? causes
interactive debug to be switched on.

When interactive debug is in effect, you can switch it off by issuing a TRACE
instruction with a prefix ?.  Repeated use of the ? prefix, therefore, switchs
you alternately in and out of interactive debug. Or, interactive debug can be
turned off at any time by issuing TRACE O or TRACE with no options.

Numeric Options

If interactive debug is active and if the option specified is a positive whole
number (or an expression that evaluates to a positive whole number), that
number indicates the number of debug pauses to be skipped over. However, if the
option is a negative whole number (or an expression that evaluates to a
negative whole number), all tracing, including debug pauses, is temporarily
inhibited for the specified number of clauses.

If interactive debug is not active, numeric options are ignored.

Format of TRACE Output

Every clause traced will be displayed with automatic formatting (indentation)
according to its logical depth of nesting and so on, and the results (if
requested) are indented an extra two spaces and are enclosed in double
quotation marks so that leading and trailing blanks are apparent.

All lines displayed during tracing have a three-character prefix to identify
the type of data being traced.  The prefixes and their definitions are the
following:

*-*       Identifies the source of a single clause, that is, the data actually
          in the program.

+++       Identifies a trace message.  This can be the nonzero return code from
          a command, the prompt message when interactive debug is entered, an
          indication of a syntax error when in interactive debug, or the
          traceback clauses after a syntax error in the program.

>>>       Identifies the result of an expression (for TRACE R) or the value
          assigned to a variable during parsing, or the value returned from a
          subroutine call.

>.>       Identifies the value assigned to a placeholder during parsing.

The following prefixes are only used if Intermediates (TRACE I) are being
traced:

>C>       The data traced is the name of a compound variable, traced after
          substitution and before use, provided that the name had the value of
          a variable substituted into it.

>F>       The data traced is the result of a function call.

>L>       The data traced is a literal (string, uninitialized variable, or
          constant symbol).

>O>       The data traced is the result of an operation on two terms.

>P>       The data traced is the result of a prefix operation.

>V>       The data traced is the contents of a variable.


ΓòÉΓòÉΓòÉ 11. Functions ΓòÉΓòÉΓòÉ

Syntax

You can include function calls to internal and external routines in an
expression anywhere that a data term (such as a string) would be valid, using
the notation:

 ΓöÇΓöÇfunctionΓöÇname(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇ

                    Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
                    Γöé               Γöé Γöé
                    ΓööΓöÇΓö┤Γö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇΓöÿ
                       ΓööΓöÇexpressionΓöÇΓöÿ

function-name is a literal string or a single symbol, that is taken to be a
constant.

There can be up to a maximum of 20 expressions, separated by commas, between
the parentheses. These expressions are called the arguments to the function.
Each argument expression may include further function calls.

The ( must be adjacent to the name of the function, with no blank in between,
or the construct is not recognized as a function call. (A blank operator is
assumed at this point instead.)

The arguments are evaluated in turn from left to right and they are all then
passed to the function. This then executes some operation (usually dependent on
the argument strings passed, though arguments are not mandatory) and eventually
returns a single character string. This string is then included in the original
expression as though the entire function reference had been replaced by the
name of a variable that contained that data.

For example, the function SUBSTR is built-in to the language processor and
could be used as:

N1='abcdefghijk'
Z1='Part of N1 is: 'Substr(N1,2,7)
/* would set Z1 to 'Part of N1 is: bcdefgh' */

A function call without any arguments must always include the parentheses to be
recognized as a function call.

date()  /* returns the date in the default format dd mon yyyy */

Calls to Functions and Subroutines

The mechanism for calling functions and subroutines is the same. The only
difference is that functions must return data, whereas subroutines need not.
The following types of routines can be called as functions:

Internal  If the routine name exists as a label in the program, the current
          processing status is saved, so that it will later be possible to
          return to the point of invocation to resume processing. Control is
          then passed to the first label in the program that matches the name.
          As with a routine invoked by the CALL instruction, various other
          pieces of status information (TRACE and NUMERIC settings and so on)
          are also saved. See the CALL instruction for details of this. If an
          internal routine is to be called as a function, you must specify an
          expression in any RETURN instruction to return from the function.
          This is not necessary if the function is called only as a subroutine.

          Example:

                    /* Recursive internal function execution... */
                    arg x
                    say x'! =' factorial(x)
                    exit

                    factorial: procedure   /* calculate factorial by..  */
                      arg n                /*  .. recursive invocation. */
                      if n=0 then return 1
                      return  factorial(n-1) * n

          FACTORIAL is unusual in that it invokes itself (this is known as
          recursive invocation).  The PROCEDURE instruction ensures that a new
          variable n is created for each invocation).

Built-in  These functions are always available and are defined later in this
          section.

External  You can write or make use of functions that are external to a program
          and to the language processor. An external function can be written in
          any language, including REXX, that supports the system-dependent
          interfaces used by the language processor to invoke it. Again, when
          called as a function, it must return data to the caller.

Notes:

 1. Calling an external REXX program as a function is similar to calling an
    internal routine.  The external routine is, however, an implicit PROCEDURE
    in that all the caller variables are always hidden and the status of
    internal values (NUMERIC settings and so on) start with their defaults
    (rather than inheriting those of the caller).

 2. Other REXX programs can be called as functions. You can use either EXIT or
    RETURN to leave the invoked REXX program; in either case, you must specify
    an expression.

Search Order

The search order for functions is the same as in the preceding list. That is,
internal labels take first precedence, then built-in functions, and finally
external functions.

Internal labels are not used if the function name is given as a string (that
is, is specified in quotation marks); in this case the function must be
built-in or external. This lets you usurp the name of, for example, a built-in
function to extend its capabilities, but still be able to invoke the built-in
function when needed.

Example:

/* Modified DATE to return sorted date by default */
date: procedure
      arg in
      if in='' then in='Sorted'
      return 'DATE'(in)

Built-in functions have names in uppercase letters.  The name in the literal
string must be in uppercase for the search to succeed, as in the example.  The
same is usually true of external functions.

External functions and subroutines have a system-defined search order.

REXX searches for external functions in the following order:

 1. Functions that have been loaded into the macrospace for pre-order execution
 2. Functions that are part of a function package.
 3. REXX functions in the current directory, with the current extension
 4. REXX functions along environment PATH, with the current extension
 5. REXX functions in the current directory, with the default extension
 6. REXX functions along environment PATH, with the default extension
 7. Functions that have been loaded into the macrospace for post-order
    execution.

Errors during Execution

If an external or built-in function detects an error of any kind, the language
processor is informed, and a syntax error results.  Processing of the clause
that included the function call is therefore terminated. Similarly, if an
external function fails to return data correctly, this is detected by the
language processor and reported as an error.

If a syntax error occurs during the processing of an internal function, it can
be trapped (using SIGNAL ON SYNTAX) and recovery may then be possible. If the
error is not trapped, the program is terminated.

Return Values

A function normally returns a value that is substituted for the function call
when the expression is evaluated.

How the value returned by a function (or any REXX routine) is handled depends
on whether it is called by a function call or called as a subroutine with the
CALL instruction.

A routine called as a subroutine: If the routine returns a value, that value is
stored in the special variable named RESULT. Otherwise, the RESULT variable is
dropped, and its value is the string "RESULT".

A routine called as a function: If the function returns a value, that value is
substituted into the expression at the position where the function was called.
Otherwise, REXX stops with an error message.

Examples:


/* Different ways to call a REXX procedure */
call Beep 500, 100         /* Example 1: a subroutine call */
bc = Beep(500, 100)        /* Example 2: a function call   */
Beep(500, 100)             /* Example 3: result passed as  */
                           /*            a command         */

o In Example 1, the built-in function BEEP is called as a REXX subroutine. The
  return value from BEEP is placed in the REXX special variable RESULT.

o Example 2 shows BEEP called as a REXX function. The return value from the
  function is substituted for the function call. The clause itself is an
  assignment instruction; the return value from the BEEP function is placed in
  the variable bc.

o In Example 3, the BEEP function is processed and its return value is
  substituted in the expression for the function call, just as in Example 2. In
  this case, however, the clause as a whole evaluates to a single expression;
  therefore the evaluated expression is passed to the current default
  environment as a command.

  Note:   Many other languages (such as C) throw away the return value of a
          function if it is not assigned to a variable. In REXX, however, a
          value returned as in Example 3 is passed on to the current
          environment or subcommand handler. If that environment is CMD (the
          default), then this action will result in the operating system
          performing a disk search for what seems to be a command.


Built-in Functions

REXX provides a rich set of built-in functions. These include character
manipulation, conversion, and information functions.

Here are some general notes on the built-in functions:

o The parentheses in a function are always needed, even if no arguments are
  required. The first parenthesis must follow the name of the function with no
  space in between.

o The built-in functions work internally with NUMERIC DIGITS 9 and NUMERIC FUZZ
  0 and are unaffected by changes to the NUMERIC settings, except where stated.

o You can supply a null string where a string is referenced.

o If an argument specifies a length, it must be a nonnegative whole number. If
  it specifies a start character or word in a string, it must be a positive
  whole number, unless otherwise stated.

o Where the last argument is optional, you can always include a comma to
  indicate that you have omitted it; for example, DATATYPE(1,), like
  DATATYPE(1), would return NUM.

o If you specify a pad character, it must be exactly one character long.

o If a function has a suboption you can select by specifying the first
  character of a string, that character can be in uppercase or lowercase
  letters.

o Conversion between characters and hexadecimal involves the machine
  representation of character strings, and hence returns appropriately
  different results for ASCII and EBCDIC machines.

o A number of the functions described in this chapter support the
  double-byte-character-set (DBCS).  A complete list and description of these
  functions is given in the OS/2 Procedures Language 2/REXX Reference.


ΓòÉΓòÉΓòÉ 11.1. ABBREV ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇABBREV(information,info ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                              ΓööΓöÇ,lengthΓöÇΓöÇΓöÿ

ABBREV returns 1 if info is equal to the leading characters of information and
the length of info is not less than length. ABBREV returns 0 if neither of
these conditions is met.

If specified, length must be a nonnegative whole number. The default for length
is the number of characters in info.

Here are some examples:

ABBREV('Print','Pri')      ->    1
ABBREV('PRINT','Pri')      ->    0
ABBREV('PRINT','PRI',4)    ->    0
ABBREV('PRINT','PRY')      ->    0
ABBREV('PRINT','')         ->    1
ABBREV('PRINT','',1)       ->    0

Note:   A null string will always match if a length of 0 (or the default) is
        used. This allows a default keyword to be selected automatically if
        desired. For example:

                say 'Enter option:';   pull option .
                select  /* keyword1 is to be the default */
                  when abbrev('keyword1',option) then ...
                  when abbrev('keyword2',option) then ...
                  ...
                  otherwise nop;
                end;


ΓòÉΓòÉΓòÉ 11.2. ABS (Absolute Value) ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇABS(number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ABS returns the absolute value of number. The result has no sign and is
formatted according to the current NUMERIC settings.

Here are some examples:

ABS('12.3')       ->    12.3
ABS(' -0.307')    ->    0.307


ΓòÉΓòÉΓòÉ 11.3. ADDRESS ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇADDRESS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ADDRESS returns the name of the environment to which host commands are
currently being submitted.  Trailing blanks are removed from the result.

Here are some examples:

ADDRESS( )    ->    'CMD'        /* OS/2 environment */
ADDRESS( )    ->    'EDIT'      /* possible editor */


ΓòÉΓòÉΓòÉ 11.4. API Functions ΓòÉΓòÉΓòÉ

The following built-in REXX functions can be used in a REXX program to
register, drop, or query external function packages and to create and
manipulate external data queues.

RXFUNCADD

 ΓöÇRXFUNCADD(name,module,procedure)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

RXFUNCADD registers the function name, making it available to REXX procedures.
A zero return value signifies successful registration.

RXFUNCDROP

 ΓöÇRXFUNCDROP(name)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

RXFUNCDROP removes (deregisters) the function name from the list of available
functions. A zero return value signifies successful removal.

RXFUNCQUERY

 ΓöÇRXFUNCQUERY(name)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

RXFUNCQUERY queries the list of available functions for a registration of the
name function. The function returns a value of 0 if the function is registered,
and a value of 1 if it is not.

RXQUEUE

 ΓöÇΓöÇRXQUEUE(ΓöÇΓö¼ΓöÇΓöÇ"Get"ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
              Γö£ΓöÇΓöÇ"Set"ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇnewqueuenameΓöÇΓöñ
              Γö£ΓöÇΓöÇ"Delete"ΓöÇΓöÇΓöÇqueuenameΓöÇΓöÇΓöÇΓöÇΓöñ
              ΓööΓöÇΓöÇ"Create"ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                          ΓööΓöÇ,queuenameΓöÇΓöÇΓöÇΓöÿ

RXQUEUE is used in a REXX program to create and delete external data queues and
to set and query their names.


ΓòÉΓòÉΓòÉ 11.5. ARG ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇARG(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          ΓööΓöÇnΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
               ΓööΓöÇ,optionΓöÇΓöÇΓöÇΓöÿ

ARG returns an argument string, or information about the argument strings to a
program or internal routine.

If you do not specify a parameter, the number of arguments passed to the
program or internal routine is returned.

If only n is specified, the n th argument string is returned. If the argument
string does not exist, the null string is returned. n must be a positive whole
number.

If you specify option, ARG tests for the existence of the n th argument string.
Valid options (of which only the capitalized letter is significant and all
others are ignored) are:

Exists      Returns 1 if the n th argument exists; that is, if it was
            explicitly specified when the routine was called. Returns 0
            otherwise.

Omitted     Returns 1 if the nth argument was omitted; that is, if it was not
            explicitly specified when the routine was called. Returns 0
            otherwise.

Here are some examples:

/*  following "Call name;" (no arguments) */
ARG( )        ->    0
ARG(1)        ->    ''
ARG(2)        ->    ''
ARG(1,'e')    ->    0
ARG(1,'O')    ->    1

/*  following "Call name 'a',,'b';" */
ARG( )        ->    3
ARG(1)        ->    'a'
ARG(2)        ->    ''
ARG(3)        ->    'b'
ARG(n)        ->    ''    /* for n>=4 */
ARG(1,'e')    ->    1
ARG(2,'E')    ->    0
ARG(2,'O')    ->    1
ARG(3,'o')    ->    0
ARG(4,'o')    ->    1

Notes:

 1. You can retrieve and directly parse the argument strings to a program or
    internal routine using the ARG or PARSE ARG instructions.
 2. Programs called as commands can have only 0 or 1 argument strings. The
    program has no argument strings if it is called with the name only and has
    1 argument string if anything else (including blanks) is included with the
    command.
 3. Programs called by the REXXSTART entry point can have multiple argument
    strings.


ΓòÉΓòÉΓòÉ 11.6. BEEP ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇBEEP(frequency,duration)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

BEEP sounds the speaker at frequency (Hertz) for duration milliseconds. The
frequency can be any number in the range 37 to 32767 Hertz. The duration can be
any number in the range 1 to 60000 milliseconds.

This routine is most useful when called as a subroutine. A null string is
returned if the routine is successful.

Here is an example:

/* C scale */
note.1 = 262    /* middle C */
note.2 = 294    /*    D     */
note.3 = 330    /*    E     */
note.4 = 349    /*    F     */
note.5 = 392    /*    G     */
note.6 = 440    /*    A     */
note.7 = 494    /*    B     */
note.8 = 524    /*    C     */

do i=1 to 8
  call beep note.i,250    /* hold each note for */
                          /* one-quarter second */
end


ΓòÉΓòÉΓòÉ 11.7. BITAND ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇBITAND(string1ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                        ΓööΓöÇstring2Γöÿ ΓööΓöÇ,padΓöÇΓöÿ

BITAND returns a string composed of the two input strings logically compared,
bit by bit, using the AND operator. The length of the result is the length of
the longer of the two strings. If no pad character is provided, the AND
operation terminates when the shorter of the two strings is exhausted, and the
unprocessed portion of the longer string is appended to the partial result.  If
pad is provided, it is used to extend the shorter of the two strings on the
right, before carrying out the logical operation. The default for string2 is
the zero length (null) string.

Here are some examples:

BITAND('73'x,'27'x)            ->    '23'x
BITAND('13'x,'5555'x)          ->    '1155'x
BITAND('13'x,'5555'x,'74'x)    ->    '1154'x
BITAND('pQrS',,'DF'x)          ->    'PQRS' /* ASCII only  */


ΓòÉΓòÉΓòÉ 11.8. BITOR ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇBITOR(string1ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                   ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                       ΓööΓöÇstring2Γöÿ ΓööΓöÇ,padΓöÇΓöÿ

BITOR returns a string composed of the two input strings logically compared,
bit by bit, using the OR operator. The length of the result is the length of
the longer of the two strings. If no pad character is provided, the OR
operation terminates when the shorter of the two strings is exhausted, and the
unprocessed portion of the longer string is appended to the partial result.  If
pad is provided, it is used to extend the shorter of the two strings on the
right, before carrying out the logical operation. The default for string2 is
the zero length (null) string.

Here are some examples:

BITOR('15'x,'24'x)            ->    '35'x
BITOR('15'x,'2456'x)          ->    '3556'x
BITOR('15'x,'2456'x,'F0'x)    ->    '35F6'x
BITOR('1111'x,,'4D'x)         ->    '5D5D'x
BITOR('pQrS',,'20'x)          ->    'pqrs' /* ASCII only  */


ΓòÉΓòÉΓòÉ 11.9. BITXOR ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇBITXOR(string1ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                        ΓööΓöÇstring2Γöÿ ΓööΓöÇ,padΓöÇΓöÿ

BITXOR returns a string composed of the two input strings logically compared
bit by bit using the exclusive OR operator. The length of the result is the
length of the longer of the two strings. If no pad character is provided, the
XOR operation terminates when the shorter of the two strings is exhausted, and
the unprocessed portion of the longer string is appended to the partial result.
If pad is provided, it is used to extend the shorter of the two strings on the
right, before carrying out the logical operation. The default for string2 is
the zero length (null) string.

Here are some examples:

BITXOR('12'x,'22'x)               ->  '30'x
BITXOR('1211'x,'22'x)             ->  '3011'x
BITXOR('C711'x,'222222'x,' ')     ->  'E53302'x  /* ASCII  */
BITXOR('1111'x,'444444'x)         ->  '555544'x
BITXOR('1111'x,'444444'x,'40'x)   ->  '555504'x
BITXOR('1111'x,,'4D'x)            ->  '5C5C'x


ΓòÉΓòÉΓòÉ 11.10. B2X (Binary to Hexadecimal) ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇB2X(binary_string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Converts binary_string, a string of binary (0 or 1) digits, to an equivalent
string of hexadecimal characters. You can optionally include blanks in
binary_string (at four-digit boundaries only, not leading or trailing) to aid
readability; they are ignored.

The returned string uses uppercase letters for the values A-F, and does not
include blanks.

binary_string can be of any length; if it is the null string, then a null
string is returned. If the number of binary digits in the string is not a
multiple of four, then up to three 0 digits will be added on the left before
the conversion to make a total that is a multiple of four.

Here are some examples:

B2X('11000011')    ==   'C3'
B2X('10111')       ==   '17'
B2X('101')         ==   '5'
B2X('1 1111 0000') ==   '1F0'

B2X( ) can be combined with the functions X2D( ) and X2C( ) to convert a binary
number into other forms. For example:

X2D(B2X('10111'))  ==   '23'   /* decimal 23 */


ΓòÉΓòÉΓòÉ 11.11. CENTER/CENTRE ΓòÉΓòÉΓòÉ

     ΓöîΓöÇCENTER(ΓöÇΓöÉ
 ΓöÇΓöÇΓöñ         Γö£ΓöÇΓöÇstring,length ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
     ΓööΓöÇCENTRE(ΓöÇΓöÿ                 ΓööΓöÇ,padΓöÇΓöÇΓöÿ

CENTER or CENTRE returns a string of length length with string centered in it,
with pad characters added as necessary to make up length. The default pad
character is blank. If the string is longer than length, it will be truncated
at both ends to fit. If an odd number of characters are truncated or added, the
right-hand end loses or gains one more character than the left-hand end.

Here are some examples:

CENTER(abc,7)               ->    '  ABC  '
CENTER(abc,8,'-')           ->    '--ABC---'
CENTRE('The blue sky',8)    ->    'e blue s'
CENTRE('The blue sky',7)    ->    'e blue '

Note:   This function can be called either CENTRE or CENTER, which avoids
errors due to the difference between the British and American spellings.


ΓòÉΓòÉΓòÉ 11.12. CHARIN ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇCHARIN(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
             ΓööΓöÇnameΓöÇΓöÿ  ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                           ΓööΓöÇstartΓöÇΓöÿ  ΓööΓöÇ,lengthΓöÇΓöÿ

CHARIN returns a string of up to length characters read from the character
input stream name. The form of the name is implementation dependent. If name is
omitted, characters are read from the default input stream, STDIN:. The default
length is 1.

For persistent streams, a read position is maintained for each stream. In the
OS/2 operating system, this is the same as the write position. Any read from
the stream will by default start at the current read position.  When the read
is completed, the read position is increased by the number of characters read.
A start value can be given to specify an explicit read position.  This read
position must be positive and within the bounds of the stream, and must not be
specified for a transient stream ( a port or other serial device).  A value of
1 for start refers to the first character in the stream.

If you specify a length of 0, then the read position will be set to the value
of start, but no characters are read and the null string is returned.

In a transient stream, if there are fewer then length characters available,
then execution of the program will normally stop until sufficient characters do
become available.  If, however, it is impossible for those characters to become
available due to an error or other problem, the NOTREADY condition is raised
and CHARIN will return with fewer than the requested number of characters.

Here are some examples:

CHARIN(myfile,1,3)   ->   'MFC'   /* the first 3     */
                                   /* characters      */
CHARIN(myfile,1,0)   ->   ''      /* now at start    */
CHARIN(myfile)       ->   'M'     /* after last call */
CHARIN(myfile,,2)    ->   'FC'    /* after last call */

/* Reading from the default input (here, the keyboard) */
/* User types 'abcd efg' */
CHARIN( )            ->   'a'      /* default is  */
                                             /* 1 character */
CHARIN(,,5)          ->   'bcd e'

Note 1:

CHARIN returns all characters that appear in the stream including control
characters such as line feed, carriage return, and end of file.

Note 2:

When CHARIN is used to read from the keyboard, program execution stops until
you press the Enter key.


ΓòÉΓòÉΓòÉ 11.13. CHAROUT ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇCHAROUT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇnameΓöÇΓöÿ  ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                            ΓööΓöÇstringΓöÇΓöÿ  ΓööΓöÇ,startΓöÇΓöÿ

CHAROUT returns the count of characters remaining after attempting to write
string to the character output stream name. The form of the name is
implementation dependent. If name is omitted, characters in string will be
written to the default output stream, STDOUT: (normally the display) in the
OS/2 operating system. string can be the null string, in which case no
characters are written to the stream and 0 is always returned.

For persistent streams, a write position is maintained for each stream. In the
OS/2 implementation, this is the same as the read position. Any write to the
stream starts at the current write position by default.  When the write is
completed the write position is increased by the number of characters written.
The initial write position is the end of the stream, so that calls to CHAROUT
normally append to the end of the stream.

A start value can be given to specify an explicit write position for a
persistent stream. This write position must be a positive whole number within
the bounds of the stream (though it can specify the character position
immediately after the end of the stream). A value of 1 for start refers to the
first character in the stream.

Note:   In some environments, overwriting a stream with CHAROUT or LINEOUT can
        erase (destroy) all existing data in the stream. However, this is not
        the case in the OS/2 environment.

The string can be omitted for persistent streams. In this case, the write
position is set to the value of start that was given, no characters are written
to the stream, and 0 is returned. If neither start nor string are given, the
write position is set to the end of the stream. This use of CHAROUT can also
have the side effect of closing or fixing the file in environments which
support this concept.  Again, 0 is returned. If you do not specify start or
string, the stream is closed. Again, 0 is returned.

Processing of the program normally stops until the output operation is
effectively complete. If, however, it is impossible for all the characters to
be written, the NOTREADY condition is raised and CHAROUT returns with the
number of characters that could not be written (the residual count).

Here are some examples:

CHAROUT(myfile,'Hi')     ->   0   /* normally */
CHAROUT(myfile,'Hi',5)   ->   0   /* normally */
CHAROUT(myfile,,6)       ->   0   /* now at char 6 */
CHAROUT(myfile)          ->   0   /* at end of stream */
CHAROUT(,'Hi')           ->   0   /* normally */
CHAROUT(,'Hello')        ->   2   /* maybe */

Note:   This routine is often best called as a subroutine. The residual count
        is then available in the variable RESULT.

For example:

Call CHAROUT myfile,'Hello'
Call CHAROUT myfile,'Hi',6
Call CHAROUT myfile


ΓòÉΓòÉΓòÉ 11.14. CHARS ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇCHARS(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇnameΓöÇΓöÿ

CHARS returns the total number of characters remaining in the character input
stream name. The count includes any line separator characters, if these are
defined for the stream, and in the case of persistent streams, is the count of
characters from the current read position to the end of the stream. If name is
omitted, OS/2 will use STDIN: as the default.

The total number of characters remaining cannot be determined for some streams
(for example, STDIN:).  For these streams, the CHARS function returns 1 to
indicate that data is present, or 0 if no data is present. For OS/2 devices,
CHARS always returns 1.

Here are some examples:

CHARS(myfile)     ->   42   /* perhaps */
CHARS(nonfile)    ->   0    /* perhaps */
CHARS()           ->   1    /* perhaps */


ΓòÉΓòÉΓòÉ 11.15. COMPARE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇCOMPARE(string1,string2 ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                               ΓööΓöÇ,padΓöÇΓöÇΓöÿ

COMPARE returns 0 if the strings, string1 and string2, are identical.
Otherwise, COMPARE returns the position of the first character that does not
match. The shorter string is padded on the right with pad if necessary.  The
default pad character is a blank.

Here are some examples:

COMPARE('abc','abc')         ->    0
COMPARE('abc','ak')          ->    2
COMPARE('ab ','ab')          ->    0
COMPARE('ab ','ab',' ')      ->    0
COMPARE('ab ','ab','x')      ->    3
COMPARE('ab-- ','ab','-')    ->    5


ΓòÉΓòÉΓòÉ 11.16. CONDITION ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇCONDITION(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇoptionΓöÇΓöÿ

CONDITION returns the condition information associated with the current trapped
condition.  You can request four pieces of information:

o The name of the current trapped condition
o Any descriptive string associated with that condition
o The instruction executed as a result of the condition trap (CALL or SIGNAL)
o The status of the trapped condition.

The following options (of which only the capitalized letter is needed, all
others are ignored) can be used to obtain the following information:

Condition name    Returns the name of the current trapped condition.

Description       Returns any descriptive string associated with the current
                  trapped condition. If no description is available, a null
                  string is returned.

Instruction       Returns the keyword for the instruction executed when the
                  current condition was trapped.  The keywords are CALL or
                  SIGNAL. This is the default if you omit option.

Status            Returns the status of the current trapped condition.  This
                  can change during execution, and is either:

   ON - the condition is enabled

   OFF - the condition is disabled

   DELAY - any new occurrence of the condition is delayed.

If no condition has been trapped (that is, there is no current trapped
condition) then the CONDITION function returns a null string in all four cases.

Here are some examples:

CONDITION()            ->    'CALL'        /* perhaps */
CONDITION('C')         ->    'FAILURE'
CONDITION('I')         ->    'CALL'
CONDITION('D')         ->    'FailureTest'
CONDITION('S')         ->    'OFF'        /* perhaps */

Note:   The condition information returned by the CONDITION function is saved
        and restored across subroutine calls (including those caused by a CALL
        ON condition trap). Therefore, once a subroutine invoked due to a CALL
        ON trap has returned, the current trapped condition reverts to the
        current condition before the CALL took place. CONDITION returns the
        values it returned before the condition was trapped.


ΓòÉΓòÉΓòÉ 11.17. COPIES ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇCOPIES(string,n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

COPIES returns n concatenated copies of string. n must be a nonnegative whole
number.

Here are some examples:

COPIES('abc',3)    ->    'abcabcabc'
COPIES('abc',0)    ->    ''


ΓòÉΓòÉΓòÉ 11.18. C2D (Character to Decimal) ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇC2D(string ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇ,nΓöÇΓöÇΓöÿ

C2D returns the decimal value of the binary representation of string. If the
result cannot be expressed as a whole number, an error results. That is, the
result must not have more digits than the current setting of NUMERIC DIGITS.

If string is the null string, then 0 is returned.

If n is not specified, string is processed as an unsigned binary number.

Here are some examples:

C2D('09'X)      ->        9
C2D('81'X)      ->      129
C2D('FF81'X)    ->    65409
C2D('a')        ->       97     /* ASCII */

If n is specified, the given string is padded on the left with 00x characters
(note, not sign-extended), or truncated on the left to n characters. The
resulting string of n hexadecimal digits is taken to be a signed binary number:
positive if the leftmost bit is OFF, and negative, in two's complement
notation, if the leftmost bit is ON. If n is 0, then 0 is always returned.

Here are some examples:

C2D('81'X,1)      ->     -127
C2D('81'X,2)      ->      129
C2D('FF81'X,2)    ->     -127
C2D('FF81'X,1)    ->     -127
C2D('FF7F'X,1)    ->      127
C2D('F081'X,2)    ->    -3967
C2D('F081'X,1)    ->     -127
C2D('0031'X,0)    ->        0

Implementation maximum: The input string cannot have more than 250 characters
that will be significant in forming the final result.  Leading sign characters
(00x and ffx) do not count toward this total.


ΓòÉΓòÉΓòÉ 11.19. C2X (Character to Hexadecimal) ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇC2X(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

C2X converts a character string to its hexadecimal representation. The data to
be converted can be of any length. The returned string contains twice as many
bytes as the input string because it is in literal string notation.

Here are some examples:

C2X('0123'X)    ->    '0123'
C2X('ZD8')      ->    '5A4438'     /*   ASCII    */


ΓòÉΓòÉΓòÉ 11.20. DATATYPE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇDATATYPE(string ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                       ΓööΓöÇΓöÇ,typeΓöÇΓöÇΓöÿ

DATATYPE determines whether 'data' is numeric or alphabetic and returns a
result of NUM or CHAR. If only string is specified, the returned result is NUM
if string is a valid REXX number (any format); otherwise CHAR will be the
returned result.

If type is specified, the returned result is 1 if string matches the type;
otherwise, a 0 is returned. If string is null, 0 is returned (except when type
is X, which returns 1). The following is a list of valid types. Only the
capitalized letter is significant (all others are ignored).

Alphanumeric      Returns 1 if string contains only characters from the ranges
                  a-z, A-Z, and 0-9.

Bits              Returns 1 if string contains only the characters 0 and/or 1.

C                 Returns 1 if string is a mixed SBCS/DBCS string.

Dbcs              Returns 1 if string is a pure DBCS string.

Lowercase         Returns 1 if string contains only characters from the range
                  a-z.

Mixed case        Returns 1 if string contains only characters from the ranges
                  a-z and A-Z.

Number            Returns 1 if string is a valid REXX number.

Symbol            Returns 1 if string contains only characters that are valid
                  in REXX symbols. Note that both uppercase and lowercase
                  letters are permitted.

Uppercase         Returns 1 if string contains only characters from the range
                  A-Z.

Whole number      Returns 1 if string is a REXX whole number under the current
                  setting of NUMERIC DIGITS.

heXadecimal       Returns 1 if string contains only characters from the ranges
                  a-f, A-F, 0-9, and blank (so long as blanks only appear
                  between pairs of hexadecimal characters). Also returns 1 if
                  string is a null string.

DATATYPE(' 12 ')         ->   'NUM'
DATATYPE('')             ->   'CHAR'
DATATYPE('123*')         ->   'CHAR'
DATATYPE('12.3','N')     ->    1
DATATYPE('12.3','W')     ->    0
DATATYPE('Fred','M')     ->    1
DATATYPE('','M')         ->    0
DATATYPE('Fred','L')     ->    0
DATATYPE('?20K','S')     ->    1
DATATYPE('BCd3','X')     ->    1
DATATYPE('BC d3','X')    ->    1


ΓòÉΓòÉΓòÉ 11.21. DATE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇDATE(ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
             ΓööΓöÇoptionΓöÇΓöÇΓöÿ

DATE returns, by default, the local date in the format: dd mon yyyy (for
example, 27 Aug 1988), with no leading zero or blank on the day. For mon, the
first three characters of the English name of the month will be used.

The following options (of which only the capitalized letter is needed, all
others are ignored) can be used to obtain alternative formats:

Basedate        Returns the number of complete days (that is, not including the
                current day) since and including the base date, January 1,
                0001, in the format: dddddd (no leading zeros). The expression
                DATE(B)//7  returns a number in the range 0-6, where 0 is
                Monday and 6 is Sunday.

                Note:   The origin of January 1, 0001 is based on the Gregorian
                        calendar. Though this calendar did not exist prior to
                        1582, Basedate is calculated as if it did: 365 days per
                        year, an extra day every four years except century
                        years, and leap centuries if the century is divisible
                        by 400. It does not take into account any errors in the
                        calendar system that created the Gregorian calendar
                        originally.

Days            Returns the number of days, including the current day, so far
                in this year in the format: ddd (no leading zeros)

European        Returns date in the format: dd/mm/yy.

Language        Returns date in an implementation and language dependent or
                local date format. In the OS/2 operating system, the Language
                format is dd Month yyyy. If no local format is available, the
                default format is returned.

                Note:   This format is intended to be used as a whole; REXX
                        programs should not make any assumptions about the form
                        or content of the returned string.

Month           Returns full English name of the current month, for example,
                August

Normal          Returns date in the default format: dd mon yyyy

Ordered         Returns date in the format: yy/mm/dd (suitable for sorting, and
                so on.)

Sorted          Returns date in the format: yyyymmdd (suitable for sorting, and
                so on.)

Usa             Returns date in the format: mm/dd/yy

Weekday         Returns the English name for the day of the week, in mixed
                case. For example, Tuesday.

Here are some examples:

DATE( )        ->    '27 Aug 1988'  /*  perhaps  */
DATE('B')      ->    725975
DATE('D')      ->    240
DATE('E')      ->    '27/08/88'
DATE('L')      ->    '27 August 1988'
DATE('M')      ->    'August'
DATE('N')      ->    '27 Aug 1988'
DATE('O')      ->    '88/08/27'
DATE('S')      ->    '19880827'
DATE('U')      ->    '08/27/88'
DATE('W')      ->    'Saturday'

Note:   The first call to DATE or TIME in one expression causes a time stamp to
        be made which is then used for all calls to these functions in that
        expression. Therefore, if multiple calls to any of the DATE and/or TIME
        functions are made in a single expression, they are guaranteed to be
        consistent with each other.


ΓòÉΓòÉΓòÉ 11.22. DELSTR (Delete String) ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇDELSTR(string,n ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                       ΓööΓöÇΓöÇ,lengthΓöÇΓöÇΓöÿ

DELSTR deletes the substring of string that begins at the nth character, and is
of length length. If length is not specified, the rest of string is deleted. If
n is greater than the length of string, the string is returned unchanged. n
must be a positive whole number.

Here are some examples:

DELSTR('abcd',3)       ->    'ab'
DELSTR('abcde',3,2)    ->    'abe'
DELSTR('abcde',6)      ->    'abcde'


ΓòÉΓòÉΓòÉ 11.23. DELWORD ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇDELWORD(string,n ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                        ΓööΓöÇΓöÇ,lengthΓöÇΓöÇΓöÿ

DELWORD deletes the substring of string that starts at the n th word. The
length option refers to the number of blank-delimited words. If length is
omitted, it defaults to be the remaining words in string. n must be a positive
whole number. If n is greater than the number of words in string, string is
returned unchanged. The string deleted includes any blanks following the final
word involved.

Here are some examples:

DELWORD('Now is the  time',2,2)  ->  'Now time'
DELWORD('Now is the time ',3)    ->  'Now is '
DELWORD('Now is the  time',5)    ->  'Now is the  time'


ΓòÉΓòÉΓòÉ 11.24. DIGITS ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇDIGITS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

DIGITS returns the current setting of NUMERIC DIGITS.

Here is an example:

DIGITS()    ->    9      /* by default */


ΓòÉΓòÉΓòÉ 11.25. D2C (Decimal to Character) ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇD2C(wholenumber ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                       ΓööΓöÇ,nΓöÇΓöÇΓöÿ

D2C returns a character string that is the ASCII representation of the decimal
number. If you specify n, it is the length of the final result in characters
and leading blanks are added to the output character.

If n is not specified, wholenumber must be a nonnegative number and the
resulting length is as needed; therefore, the returned result has no leading
00x characters.

Here are some examples:

D2C(65)      ->   'A'      /* '41'x is an ASCII 'A'    */
D2C(65,1)    ->   'A'
D2C(65,2)    ->   ' A'
D2C(65,5)    ->   '    A'
D2C(109)     ->   'm'      /* '6D'x  is an ASCII 'm'   */
D2C(-109,1)  ->   'У'      /* '147'x is an ASCII 'У'   */
D2C(76,2)    ->   ' L'     /* '76'x  is an ASCII ' L'  */
D2C(-180,2)  ->   ' L'


ΓòÉΓòÉΓòÉ 11.26. D2X (Decimal to Hexadecimal) ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇD2X(wholenumber ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                       ΓööΓöÇ,nΓöÇΓöÇΓöÿ

D2X returns a string of hexadecimal characters that is the hexadecimal
representation of the decimal number.

If n is not specified, wholenumber must be a nonnegative number and the
returned result has no leading 0 characters.

If n is specified, it is the length of the final result in characters; that is,
after conversion the input string is sign-extended to the required length. If
the number is too big to fit into n characters, it is shortened on the left.

Here are some examples:

D2X(9)         ->    '9'
D2X(129)       ->    '81'
D2X(129,1)     ->    '1'
D2X(129,2)     ->    '81'
D2X(129,4)     ->    '0081'
D2X(257,2)     ->    '01'
D2X(-127,2)    ->    '81'
D2X(-127,4)    ->    'FF81'
D2X(12,0)      ->    ''

Implementation maximum: The output string cannot have more than 250 significant
hexadecimal characters, though a longer result is possible if it has additional
leading sign characters (0 and F).


ΓòÉΓòÉΓòÉ 11.27. DIRECTORY ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇDIRECTORY(ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇnewdirectoryΓöÇΓöÿ

DIRECTORY returns the current directory, first changing it to newdirectory if
an argument is supplied and the named directory exists.

The return string includes a drive letter prefix as the first two characters of
the directory name. Specifying a drive letter prefix as part of newdirectory
causes the specified drive to become the current drive. If a drive letter is
not specified, then the current drive remains unchanged.

For example, the following program fragment saves the current directory and
switches to a new directory; it performs an operation there, and then returns
to the former directory.

/* get current directory */
curdir = directory()
/* go play a game */
newdir = directory("d:/usr/games")
if newdir = "d:/usr/games" then
   do
   fortune  /* tell a fortune */
/* return to former directory */
   call directory curdir
   end
else
   say 'Can't find /usr/games'


ΓòÉΓòÉΓòÉ 11.28. ERRORTEXT ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇERRORTEXT(n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ERRORTEXT returns the error message associated with error number n. n must be
in the range 0-99, and any other value is an error. If n is in the allowed
range, but is not a defined REXX error number, the null string is returned.

Here are some examples:

ERRORTEXT(16)    ->    'Label not found'
ERRORTEXT(60)    ->    ''


ΓòÉΓòÉΓòÉ 11.29. ENDLOCAL ΓòÉΓòÉΓòÉ

 ΓöÇENDLOCAL()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ENDLOCAL restores the drive directory and environment variables in effect
before the last SETLOCAL function was executed. If ENDLOCAL is not included in
a procedure, then the initial environment saved by SETLOCAL will be restored
upon exiting the procedure.

ENDLOCAL returns a value of 1 if the initial environment is successfully
restored, and a value of 0 if no SETLOCAL has been issued or if the actions is
otherwise unsuccessful.

Note:   Unlike their counterparts in the OS/2 Batch language (the Setlocal and
        Endlocal statements), the REXX SETLOCAL and ENDLOCAL functions can be
        nested.

Here is an example:

n = SETLOCAL()          /* saves the current environment    */

         /* The program can now change environment   */
         /* variables (with the VALUE function) and  */
         /* then work in that changed envirnonment.  */

n = ENDLOCAL()          /* restores the initial environment */

For additional examples, view the SETLOCAL function.


ΓòÉΓòÉΓòÉ 11.30. FILESPEC ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇFILESPEC(option,filespec)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

FILESPEC returns a selected element of filespec, a given file specification,
identified by one of the following strings for option:

Drive       The drive letter of the given filespec.

Path        The directory path of the given filespec.

Name        The filename of the given filespec.

If the requested string is not found, then FILESPEC returns a null string ("
").

Note:   Only the the initial letter of option is needed.

Here are some examples:

thisfile = "C:\OS2\UTIL\EXAMPLE.EXE"
say FILESPEC("drive",thisfile)     /* says "C:"          */
say FILESPEC("path",thisfile)      /* says "\OS2\UTIL\"  */
say FILESPEC("name",thisfile)      /* says "EXAMPLE.EXE" */

part = "name"
say FILESPEC(part,thisfile)        /* says "EXAMPLE.EXE" */


ΓòÉΓòÉΓòÉ 11.31. FORM ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇFORM()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
FORM returns the current setting of NUMERIC FORM.

Here is an example:

FORM()    ->    'SCIENTIFIC'  /* by default */


ΓòÉΓòÉΓòÉ 11.32. FORMAT ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇFORMAT(numberΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇ
                   ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                       ΓööbeforeΓöÿ Γöö,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                                   ΓööafterΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                                               ΓööexppΓöÿ Γöö,exptΓöÿ

FORMAT returns number rounded and formatted.

The number is first rounded and formatted to standard REXX rules, just as
though the operation number+0 had been carried out. If only number is given,
the result is precisely that of this operation. If any other options are
specified, the number is formatted as follows.

The before and after options describe how many characters are to be used for
the integer part and decimal part of the result respectively. If either or both
of these are omitted, the number of characters used for that part is as needed.

If before is not large enough to contain the integer part of the number, an
error results. If before is too large, the number is padded on the left with
blanks. If after is not the same size as the decimal part of the number, the
number will be rounded (or extended with zeros) to fit. Specifying 0 will cause
the number to be rounded to an integer.

Here are some examples:

FORMAT('3',4)            ->    '   3'
FORMAT('1.73',4,0)       ->    '   2'
FORMAT('1.73',4,3)       ->    '   1.730'
FORMAT('-.76',4,1)       ->    '  -0.8'
FORMAT('3.03',4)         ->    '   3.03'
FORMAT(' - 12.73',,4)    ->    '-12.7300'
FORMAT(' - 12.73')       ->    '-12.73'
FORMAT('0.000')          ->    '0'

The first three arguments are as previously described.  In addition, expp and
expt control the exponent part of the result: expp sets the number of places to
be used for the exponent part; the default is to use as many as needed. The
expt sets the trigger point for use of exponential notation. If the number of
places needed for the integer part exceeds expt, exponential notation is used.
Likewise, exponential notation is used if the number of places needed for the
decimal part exceeds twice expt. The default is the current setting of NUMERIC
DIGITS. If 0 is specified for expt, exponential notation is always used unless
the exponent would be 0. The expp must be less than 10, but there is no limit
on the other arguments. If 0 is specified for the expp field, no exponent is
supplied, and the number is expressed in simple form with added zeros as
necessary (this overrides a 0 value of expt). Otherwise, if expp is not large
enough to contain the exponent, an error results. If the exponent is 0, in this
case (a non-zero expp), then expp+2 blanks are supplied for the exponent part
of the result.

Here are some examples:

FORMAT('12345.73',,,2,2)    ->    '1.234573E+04'
FORMAT('12345.73',,3,,0)    ->    '1.235E+4'
FORMAT('1.234573',,3,,0)    ->    '1.235'
FORMAT('12345.73',,,3,6)    ->    '12345.73'
FORMAT('1234567e5',,3,0)    ->    '123456700000.000'


ΓòÉΓòÉΓòÉ 11.33. FUZZ ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇFUZZ()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

FUZZ returns the current setting of NUMERIC FUZZ.

Here is an example:

FUZZ()    ->    0     /* by default */


ΓòÉΓòÉΓòÉ 11.34. INSERT ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇINSERT(new,targetΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
                       ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                           ΓööΓöÇnΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                                     ΓöölengthΓöÿ Γöö,padΓöÿ

INSERT inserts the string new, padded to length length, into the string target
after the n th character. If specified, n must be a nonnegative whole number.
If n is greater than the length of the target string, padding is added there
also. The default pad character is a blank. The default value for n is 0, which
means insert before the beginning of the string.

Here are some examples:

INSERT(' ','abcdef',3)         ->    'abc def'
INSERT('123','abc',5,6)        ->    'abc  123   '
INSERT('123','abc',5,6,'+')    ->    'abc++123+++'
INSERT('123','abc')            ->    '123abc'
INSERT('123','abc',,5,'-')     ->    '123--abc'


ΓòÉΓòÉΓòÉ 11.35. LASTPOS ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇLASTPOS(needle,haystackΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
                              ΓööΓöÇ,startΓöÇΓöÇΓöÿ

LASTPOS returns the position of the last occurrence of one string, needle, in
another, haystack. If the string needle is not found, 0 is returned. By default
the search starts at the last character of haystack (that is,
start=LENGTH(string)) and scans backwards. You can override this by specifying
start, as the point at which the backward scan starts. start must be a positive
whole number, and defaults to LENGTH(string) if larger than that value.

Here are some examples:

LASTPOS(' ','abc def ghi')      ->    8
LASTPOS(' ','abcdefghi')        ->    0
LASTPOS(' ','abc def ghi',7)    ->    4


ΓòÉΓòÉΓòÉ 11.36. LEFT ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇLEFT(string,lengthΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         ΓööΓöÇ,padΓöÇΓöÇΓöÿ

LEFT returns a string of length length, containing the leftmost length
characters of string. The string returned is padded with pad characters (or
truncated) on the right as needed. The default pad character is a blank. length
must be nonnegative. The LEFT function is exactly equivalent to
SUBSTR(string,1,length[,pad]).

Here are some examples:

LEFT('abc d',8)        ->    'abc d   '
LEFT('abc d',8,'.')    ->    'abc d...'
LEFT('abc  def',7)     ->    'abc  de'


ΓòÉΓòÉΓòÉ 11.37. LENGTH ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇLENGTH(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

LENGTH returns the length of string.

Here are some examples:

LENGTH('abcdefgh')    ->    8
LENGTH('abc defg')    ->    8
LENGTH('')            ->    0


ΓòÉΓòÉΓòÉ 11.38. LINEIN ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇLINEIN(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
             ΓööΓöÇnameΓöÇΓöÿ  ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                           ΓööΓöÇlineΓöÇΓöÿ  ΓööΓöÇ,countΓöÇΓöÿ

LINEIN returns count (0 or 1) lines read from the character input stream name.
The form of the name is implementation dependent. If name is omitted, the line
is read from the default input stream, STDIN: in OS/2. The default count is 1.

For persistent streams, a read position is maintained for each stream. In the
OS/2 operating system, this is the same as the write position. Any read from
the stream starts at the current read position by default. A call to LINEIN
will return a partial line if the current read position is not at the start of
a line. When the read is completed, the read position is moved to the beginning
of the next line. The read position may be set to the beginning of the stream
by giving line a value of 1- the only valid value for line in OS/2.

If a count of 0 is given, then no characters are read and the null string is
returned.

For transient streams, if a complete line is not available in the stream, then
execution of the program will normally stop until the line is complete. If,
however, it is impossible for a line to be completed due to an error or other
problem, the NOTREADY condition is raised and LINEIN returns whatever
characters are available.

Here are some examples:

LINEIN()                      /* Reads one line from the    */
                              /* default input stream;      */
                              /* normally this is an entry  */
                              /* typed at the keyboard      */

myfile = 'ANYFILE.TXT'
LINEIN(myfile)     -> 'Current line' /* Reads one line from  */
                             /* ANYFILE.TXT, beginning     */
                             /* at the current read        */
                             /* position. (If first call,  */
                             /* file is opened and the     */
                             /* first line is read.)       */

LINEIN(myfile,1,1) ->'first line'  /* Opens and reads the first */
                             /* line of ANYFILE.TXT (if    */
                             /* the file is already open,  */
                             /* reads first line); sets    */
                             /* read position on the       */
                             /* second line.               */

LINEIN(myfile,1,0) ->  ''    /* No read; opens ANYFILE.TXT */
                              /* (if file is already open,  */
                              /* sets the read position to  */
                              /* the first line).           */

LINEIN(myfile,,0)  ->  ''  /* No read; opens ANYFILE.TXT */
                              /* (no action if the file is  */
                              /* already open).             */

LINEIN("QUEUE:") -> 'Queue line' /* Read a line from the queue; */
                              /* If the queue is empty, the  */
                              /* program waits until a line  */
                              /* is put on the queue.        */

Note:   If the intention is to read complete lines from the default character
        stream, as in a simple dialogue with a user, use the PULL or PARSE PULL
        instructions instead for simplicity and for improved programmability.
        The PARSE LINEIN instruction is also useful in certain cases.


ΓòÉΓòÉΓòÉ 11.39. LINEOUT ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇLINEOUT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇnameΓöÇΓöÿ  ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                            ΓööΓöÇstringΓöÇΓöÿ  ΓööΓöÇ,lineΓöÇΓöÿ

LINEOUT returns the count of lines remaining after attempting to write string
to the character output stream name. The count is either 0 (meaning the line
was successfully written) or 1 (meaning that an error occurred while writing
the line). string can be the null string, in which case only the action
associated with completing a line is taken. LINEOUT adds a line-feed and a
carriage-return character to the end of string.

The form of the name is implementation dependent. If name is omitted, the line
is written to the default output stream, STDOUT: (normally the display) in
OS/2.

For persistent streams, a write position is maintained for each stream. In the
OS/2 operating system, this is the same as the read position. Any write to the
stream starts at the current write position by default. Characters written by a
call to LINEOUT can be added to a partial line. LINEOUT conceptually terminates
a line at the end of each call. When the write is completed, the write position
is set to the beginning of the line following the one just written. The initial
write position is the end of the stream, so that calls to LINEOUT normally
append lines to the end of the stream.

You can set the write position to the first character of a persistent stream by
giving a value of 1 (the only valid value) for line.

Note:   In some environments, overwriting a stream using CHAROUT or LINEOUT can
        erase (destroy) all existing data in the stream. This is not, however,
        the case in the OS/2 environment.

You can omit the string for persistent streams. If you specify line, the write
position is set to the beginning of the stream, but nothing is written to the
stream, and 0 is returned.  If you specify neither line nor string, the write
position is set to the end of the stream. This use of LINEOUT has the effect of
closing the stream in environments (such as the OS/2 environment) that support
this concept.

Execution of the program normally stops until the output operation is
effectively completed. If, however, it is impossible for a line to be written,
the NOTREADY condition is raised and LINEOUT returns with a result of 1 (that
is, the residual count of lines written).

Here are some examples:

LINEOUT(,'Display this')    /* Writes string to the default   */
                            /* output stream (normally, the   */
                            /* display); returns 0 if         */
                            /* successful                     */

myfile = 'ANYFILE.TXT'
LINEOUT(myfile,'A new line')  /* Opens the file ANYFILE.TXT and */
                              /* appends the string to the end. */
                              /* If the file is already open,   */
                              /* the string is written at the   */
                              /* current write position.        */
                              /* Returns 0 if successful.       */

LINEOUT(myfile,'A new start',1)/* Opens the file (if not already */
                               /* open); overwrites first line   */
                               /* with a new line.               */
                               /* Returns 0 if successful.       */

LINEOUT(myfile,,1)            /* Opens the file (if not already */
                              /* open). No write; sets write    */
                              /* position at first character.   */

LINEOUT(myfile)               /* Closes ANYFILE.TXT             */

LINEOUT is often most useful when called as a subroutine. The return value is
then available in the variable RESULT. For example:

Call LINEOUT 'A:rexx.bat','Shell',1
Call LINEOUT ,'Hello'

Note:   If the lines are to be written to the default output stream without the
        possibility of error, use the SAY instruction instead.


ΓòÉΓòÉΓòÉ 11.40. LINES ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇLINES(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇnameΓöÇΓöÿ

LINES returns 1 if any data remains between the current read position and the
end of the character input stream name, and returns 0 if no data remains. In
effect, LINES reports whether a read action performed by CHARIN or LINEIN will
succeed.

The form of the name is implementation dependent. If you omit name, then the
presence or absence of data in the default input stream (STDIN:) is returned.
For OS/2 devices, LINES always returns 1.

Here are some examples:

LINES(myfile)    ->    0    /* at end of the file   */

LINES()          ->    1    /* data remains in the  */
                            /* default input stream */
                            /* STDIN:         */

LINES("COM1:")   ->    1     /* An OS/2 device name  */
                            /* always returns '1'   */

Note:   The CHARS function returns the number of characters in a persistent
        stream or the presence of data in a transient stream.


ΓòÉΓòÉΓòÉ 11.41. MAX ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇMAX(numberΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓöéΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉΓöé
                Γöé         ΓöéΓöé
                ΓööΓö┤ΓöÇ,numberΓöÇΓö┤Γöÿ

MAX returns the largest number from the list specified, formatted according to
the current setting of NUMERIC DIGITS. You can specify up to 20 numbers and can
nest calls to MAX if more arguments are needed.

Here are some examples:

MAX(12,6,7,9)                              ->    12
MAX(17.3,19,17.03)                         ->    19
MAX(-7,-3,-4.3)                            ->    -3
MAX(1,2,3,4,5,6,7,8,9,MAX(10,11,12,13))    ->    13


ΓòÉΓòÉΓòÉ 11.42. MIN ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇMIN(numberΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓöéΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉΓöé
                Γöé         ΓöéΓöé
                ΓööΓö┤ΓöÇ,numberΓöÇΓö┤Γöÿ

MIN returns the smallest number from the list specified, formatted according to
the current setting of NUMERIC DIGITS. Up to 20 numbers can be specified,
although calls to MIN can be nested if more arguments are needed.

Here are some examples:

MIN(12,6,7,9)         ->     6
MIN(17.3,19,17.03)    ->    17.03
MIN(-7,-3,-4.3)       ->    -7


ΓòÉΓòÉΓòÉ 11.43. OVERLAY ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇOVERLAY(new,target ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇ
                         ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                             ΓööΓöÇnΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                                       ΓöölengthΓöÿ Γöö,padΓöÿ

OVERLAY returns the string target, which, starting at the nth character, is
overlaid with the string new, padded or truncated to length length. If length
is specified, it must be positive or zero. If n is greater than the length of
the target string, padding is added before the new string. The default pad
character is a blank, and the default value for n is 1. If you specify n, it
must be a positive whole number.

Here are some examples:

OVERLAY(' ','abcdef',3)         ->    'ab def'
OVERLAY('.','abcdef',3,2)       ->    'ab. ef'
OVERLAY('qq','abcd')            ->    'qqcd'
OVERLAY('qq','abcd',4)          ->    'abcqq'
OVERLAY('123','abc',5,6,'+')    ->    'abc+123+++'


ΓòÉΓòÉΓòÉ 11.44. POS ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇPOS(needle,haystackΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
                          ΓööΓöÇ,startΓöÇΓöÇΓöÿ

POS returns the position of one string, needle, in another, haystack. (See also
the LASTPOS function.) If the string needle is not found, 0 is returned. By
default, the search starts at the first character of haystack (that is, the
value of start is 1). You can override this by specifying start (which must be
a positive whole number) as the point at which the search starts.

Here are some examples:

POS('day','Saturday')       ->    6
POS('x','abc def ghi')      ->    0
POS(' ','abc def ghi')      ->    4
POS(' ','abc def ghi',5)    ->    8


ΓòÉΓòÉΓòÉ 11.45. QUEUED ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇQUEUED()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

QUEUED returns the number of lines remaining in the currently active REXX data
queue at the time the function is invoked.

Here is an example:

QUEUED()    ->    5    /* Perhaps */


ΓòÉΓòÉΓòÉ 11.46. RANDOM ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇRANDOM(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇ
             Γö£ΓöÇmaxΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
             Γö£ΓöÇmin,ΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
             ΓööΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇmaxΓöÇΓöÿ ΓööΓöÇ,seedΓöÇΓöÿ

RANDOM returns a quasi-random, nonnegative whole number in the range min to max
inclusive. If only one argument is specified, the range will be from 0 to that
number. Otherwise, the default values for min and max are 0 and 999,
respectively. A specific seed (which must be a whole number) for the random
number can be specified as the third argument if repeatable results are
desired.

The magnitude of the range (that is, max minus min) must not exceed 100000.

Here are some examples:

RANDOM()          ->    305
RANDOM(5,8)       ->      7
RANDOM(,,1983)    ->    123  /* reproducible */
RANDOM(2)         ->      0

Notes:

 1. To obtain a predictable sequence of quasi-random numbers, use RANDOM a
    number of times, but specify a seed only the first time. For example, to
    simulate 40 throws of a six-sided, unbiased die, use:

        sequence = RANDOM(1,6,12345)  /* any number would */
                                      /* do for a seed    */
        do 39
           sequence = sequence RANDOM(1,6)
           end
        say sequence

    The numbers are generated mathematically, using the initial seed, so that
    as far as possible they appear to be random. Running the program again will
    produce the same sequence; using a different initial seed almost certainly
    produces a different sequence.
 2. The random number generator is global for an entire program; the current
    seed is not saved across internal routine calls.
 3. The actual random number generator used may differ from implementation to
    implementation.


ΓòÉΓòÉΓòÉ 11.47. REVERSE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇREVERSE(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

REVERSE returns string, swapped end for end.

Here are some examples:

REVERSE('ABc.')    ->    '.cBA'
REVERSE('XYZ ')    ->    ' ZYX'


ΓòÉΓòÉΓòÉ 11.48. RIGHT ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇRIGHT(string,lengthΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                          ΓööΓöÇ,padΓöÇΓöÇΓöÿ

RIGHT returns a string of length length containing the rightmost length
characters of string. The string returned is padded with pad characters (or
truncated) on the left as needed. The default pad character is a blank. length
must be nonnegative.

Here are some examples:

RIGHT('abc  d',8)     ->    '  abc  d'
RIGHT('abc def',5)    ->    'c def'
RIGHT('12',5,'0')     ->    '00012'


ΓòÉΓòÉΓòÉ 11.49. SETLOCAL ΓòÉΓòÉΓòÉ

  ΓöÇΓöÇSETLOCAL()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

SETLOCAL saves the current working drive and directory, and the current values
of the OS/2 environment variables that are local to the current process.

For example, SETLOCAL can be used to save the current environment before
changing selected settings with the VALUE function. To restore the drive,
directory, and environment, use the ENDLOCAL function.

SETLOCAL returns a value of 1 if the initial drive, directory, and environment
are successfully saved, and a value of 0 if unsuccessful. If SETLOCAL is not
followed by an ENDLOCAL function in a procedure, then the initial environment
saved by SETLOCAL will be restored upon exiting the procedure.

Here is an example:

/* current path is 'C:\PROJ\FILES' */
n = SETLOCAL()        /* saves all environment settings    */

/* Now use the VALUE function to change the PATH variable. */
p = VALUE('Path','C:\PROC\PROGRAMS'.'OS2ENVIRONMENT')

/* Programs in directory C:\PROC\PROGRAMS may now be run   */

n = ENDLOCAL()  /* restores initial environment (including */
                /* the changed PATH variable, which is   */
                /* once again 'C:\PROJ\FILES'              */

Note:   Unlike their counterparts in the OS/2 Batch language (the Setlocal and
        Endlocal statements), the REXX SETLOCAL and ENDLOCAL functions can be
        nested.


ΓòÉΓòÉΓòÉ 11.50. SIGN ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇSIGN(number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

SIGN returns a number that indicates the sign of number. number is first
rounded according to standard REXX rules, just as though the operation number+0
had been carried out. If number is less than 0, then -1 is returned; if it is 0
then 0 is returned; and if it is greater than 0, 1 is returned.

Here are some examples:

SIGN('12.3')       ->     1
SIGN(' -0.307')    ->    -1
SIGN(0.0)          ->     0


ΓòÉΓòÉΓòÉ 11.51. SOURCELINE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇSOURCELINE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇΓöÇnΓöÇΓöÇΓöÿ

SOURCELINE returns the line number of the final line in the source file if you
omit n, or returns the n th line in the source file if you specify n.

If specified, n must be a positive whole number, and must not exceed the number
of the final line in the source file.

Here are some examples:

SOURCELINE()    ->   10
SOURCELINE(1)   ->   '/* This is a 10-line program */'


ΓòÉΓòÉΓòÉ 11.52. SPACE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇSPACE(stringΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                       ΓööΓöÇnΓöÇΓöÿ ΓööΓöÇΓöÇ,padΓöÇΓöÇΓöÿ

SPACE formats the blank-delimited words in string with n pad characters between
each word. The n must be nonnegative. If it is 0, all blanks are removed.
Leading and trailing blanks are always removed. The default for n is 1, and the
default pad character is a blank.

Here are some examples:

SPACE('abc  def  ')          ->    'abc def'
SPACE('  abc def',3)         ->    'abc   def'
SPACE('abc  def  ',1)        ->    'abc def'
SPACE('abc  def  ',0)        ->    'abcdef'
SPACE('abc  def  ',2,'+')    ->    'abc++def'


ΓòÉΓòÉΓòÉ 11.53. STREAM ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇSTREAM(nameΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇ
                   ΓööΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                          Γö£ΓöÇC,ΓöÇΓöÇstreamcommandΓöÇΓöñ
                          Γö£ΓöÇDΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                          ΓööΓöÇSΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

STREAM returns a string describing the state of, or the result of an operation
upon, the character stream name. This function is used to request information
on the state of an input or output stream, or to carry out some specific
operation on the stream.

The first argument, name, specifies the stream to be accessed. The second
argument can be one of the following strings (of which only the first letter is
needed) which describes the action to be carried out:

Command        an operation (specified by the streamcommand given as the third
               argument) to be applied to the selected input or output stream.
               The string that is returned depends on the command performed,
               and can be the null string.

Description    Also returns the current state of the specified stream. It is
               identical to the State operation, except that the returned
               string is followed by a colon and, if available, additional
               information about ERROR or NOTREADY states.

State          Returns a string that indicates the current state of the
               specified stream. This is the default operation.

When used with the State option, STREAM returns one of the following strings:

'ERROR'               The stream has been subject to an erroneous operation
                      (possibly during input, output, or through the STREAM
                      function. Additional information about the error may be
                      available by invoking the STREAM function with a request
                      for the implementation-dependent description.

'NOTREADY'            The stream is known to be in a state such that normal
                      input or output operations attempted upon it would raise
                      the NOTREADY condition. For example, a simple input
                      stream may have a defined length; an attempt to read that
                      stream (with the CHARIN or LINEIN built-in functions,
                      perhaps) beyond that limit may make the stream
                      unavailable until the stream has been closed, for
                      example, with LINEIN(name), and then reopened.

'READY'               The stream is known to be in a state such that normal
                      input or output operations can be attempted.  This is the
                      usual state for a stream, though it does not guarantee
                      that any particular operation will succeed.

'UNKNOWN'             The state of the stream is unknown. In OS/2
                      implementations, this generally means that the stream is
                      closed (or has not yet been opened). However, this
                      response can be used in other environments to indicate
                      that the state of the stream cannot be determined.

Note:   The state (and operation) of an input or output stream is global to a
        REXX program, in that it is not saved and restored across function and
        subroutine calls (including those caused by a CALL ON condition trap).

Stream Commands

The following stream commands are used to:

o Open a stream for reading or writing
o Close a stream at the end of an operation
o Position the read or write position within a persistent stream (for example,
  a file)
o Get information about a stream (its existence, size, and last edit date).

The streamcommand argument must be used when you select the operation C
(command). The syntax is:

 ΓöÇΓöÇSTREAM(name,'C',streamcommand)ΓöÇΓöÇΓöÇΓöÇ

In this form, the STREAM function itself returns a string corresponding to the
given streamcommand if the command is successful. If the command is
unsuccessful, STREAM returns an error message string in the same form as that
supplied by the D (Description) operation.

Command strings - The argument streamcommand can be any expression that REXX
evaluates as one of the following command strings:

'OPEN'              Opens the named stream. The default for 'OPEN' is to open
                    the stream for both reading and writing data. To specify
                    whether name is only to be read or only to be written to,
                    add the word READ or WRITE to the command string.

                    The STREAM function itself returns 'READY' if the named
                    stream is successfully opened or an appropriate error
                    message if unsuccessful.

                    Examples:

                                        stream(strout,'c','open')
                                        stream(strout,'c','open write')
                                        stream(strinp,'c','open read')

'CLOSE'             Closes the named stream. The STREAM function itself returns
                    'READY' if the named stream is successfully closed or an
                    appropriate error message otherwise. If an attempt is made
                    to close an unopened file, then STREAM() returns a null
                    string ("").

                    Example:

                                        stream('STRM.TXT','c','close')

'SEEK' offset       Sets the read or write position a given number (offset)
                    within a persistent stream.

                    Note:   In OS/2, the read and write positions are the same.
                            To use this command, the named stream must first be
                            opened (with the 'OPEN' stream command, described
                            previously).

                    The offset number can be preceded by one of the following
                    characters:

   =    Explicitly specifies the offset from the beginning of the stream.  This
        is the default if no prefix is supplied.

   <    Specifies offset from the end of the stream.

   +    Specifies offset forward from the current read or write position.

   -    Specifies offset backward from the current read or write position.

                    The STREAM function itself returns the new position in the
                    stream if the read or write position is successfully
                    located; an appropriate error message is displayed
                    otherwise.

                    Examples:

                                        stream(name,'c','seek =2')
                                        stream(name,'c','seek +15')
                                        stream(name,'c','seek -7')
                                        fromend  = 125
                                        stream(name,'c','seek <'fromend)

Used with these stream commands, the STREAM function returns specific
information about a stream

'QUERY EXISTS'      Returns the full path specification of the named stream, if
                    it exists, and a null string otherwise.

                                        stream('..\file.txt','c','query exists')

'QUERY SIZE'        Returns the size in bytes of a persistent stream.

                                        stream('..\file.txt','c','query size')

'QUERY DATETIME'    Returns the date and time stamps of a stream.

                                        stream('..\file.txt','c','query datetime')


ΓòÉΓòÉΓòÉ 11.54. STRIP ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇSTRIP(stringΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                       ΓööΓöÇoptionΓöÇΓöÿ ΓööΓöÇ,charΓöÇΓöÿ

STRIP removes leading and trailing characters from string based on the option
you specify. Valid options (of which only the capitalized letter is
significant, all others are ignored) are:

Both            Removes both leading and trailing characters from string. This
                is the default.

Leading         Removes leading characters from string.

Trailing        Removes trailing characters from string.

The third argument, char, specifies the character to remove; The default is a
blank.  If you specify char, it must be exactly one character long.

Here are some examples:

STRIP('  ab c  ')        ->    'ab c'
STRIP('  ab c  ','L')    ->    'ab c  '
STRIP('  ab c  ','t')    ->    '  ab c'
STRIP('12.7000',,0)      ->    '12.7'
STRIP('0012.700',,0)     ->    '12.7'


ΓòÉΓòÉΓòÉ 11.55. SUBSTR ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇSUBSTR(string,n ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
                      ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                          ΓööΓöÇlengthΓöÇΓöÿ ΓööΓöÇ,padΓöÇΓöÿ

SUBSTR returns the substring of string that begins at the nth character, and is
of length length and padded with pad if necessary. n must be a positive whole
number.

If length is omitted, the rest of the string will be returned.  The default pad
character is a blank.

Here are some examples:

SUBSTR('abc',2)          ->    'bc'
SUBSTR('abc',2,4)        ->    'bc  '
SUBSTR('abc',2,6,'.')    ->    'bc....'

Note:   In some situations the positional (numeric) patterns of parsing
        templates are more convenient for selecting substrings, especially if
        more than one substring is to be extracted from a string.


ΓòÉΓòÉΓòÉ 11.56. SUBWORD ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇSUBWORD(string,n ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
                       ΓööΓöÇ,lengthΓöÇΓöÇΓöÿ

SUBWORD returns the substring of string that starts at the nth word, and is of
length length, blank-delimited words. n must be a positive whole number. If you
omit length, it defaults to the number of remaining words in string. The
returned string never has leading or trailing blanks, but includes all blanks
between the selected words.

Here are some examples:

SUBWORD('Now is the  time',2,2)    ->    'is the'
SUBWORD('Now is the  time',3)      ->    'the  time'
SUBWORD('Now is the  time',5)      ->    ''


ΓòÉΓòÉΓòÉ 11.57. SYMBOL ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇSYMBOL(name)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

SYMBOL returns the state of the symbol named by name. If name is not a valid
REXX symbol, BAD is returned. SYMBOL returns VAR if it is the name of a
variable (that is, a symbol that has been assigned a value). Otherwise, SYMBOL
returns LIT, indicating that it is either a constant symbol or a symbol that
has not yet been assigned a value (that is, a literal).

As with symbols in REXX expressions, lowercase characters in name are
translated to uppercase and substitution in a compound name occurs if possible.

Note:   You should specify name as a literal string (or derived from an
        expression) to prevent substitution before it is passed to the
        function.

Here are some examples:

/* following: Drop A.3;  J=3 */
SYMBOL('J')      ->   'VAR'
SYMBOL(J)        ->   'LIT' /* has tested "3"     */
SYMBOL('a.j')    ->   'LIT' /* has tested "A.3"   */
SYMBOL(2)        ->   'LIT' /* a constant symbol  */
SYMBOL('*')      ->   'BAD' /* not a valid symbol */


ΓòÉΓòÉΓòÉ 11.58. TIME ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇTIME(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
           ΓööΓöÇoptionΓöÇΓöÿ

TIME returns the local time in the 24-hour clock format hh:mm:ss (hours,
minutes, and seconds) by default; for example:

04:41:37

You can use the following options (for which only the capitalized letter is
needed) to obtain alternative formats, or to gain access to the elapsed-time
clock:

Civil             Returns hh:mmxx, the time in Civil format, in which the hours
                  may take the values 1 through 12, and the minutes the values
                  00 through 59.  The minutes are followed immediately by the
                  letters "am" or "pm" to distinguish times in the morning
                  (midnight 12:00am through 11:59am) from noon and afternoon
                  (noon 12:00pm through 11:59pm).  The hour will not have a
                  leading zero.  The minute field shows the current minute
                  (rather than the nearest minute) for consistency with other
                  TIME results.

Elapsed           Returns sssssssss.uu0000, the number of seconds.hundredths
                  since the elapsed time clock was stared or reset (see below).
                  The returned number has no leading zeros, but always has four
                  trailing zeros in the decimal portion. It is not affected by
                  the setting of NUMERIC DIGITS.

Hours             Returns number of hours since midnight in the format hh (no
                  leading zeros).

Long              Returns time in the format hh:mm:ss.uu0000 (where uu is the
                  fraction of seconds in hundredths of a second).

Minutes           Returns number of minutes since midnight in the format: mmmm
                  (no leading zeros).

Normal            Returns the time in the default format hh:mm:ss, as described
                  above.

Reset             Returns sssssssss.uu0000, the number of seconds.hundredths
                  since the elapsed time clock was stared or reset (see below)
                  and also resets the elapsed-time clock to zero. The returned
                  number has no leading zeros, but always has four trailing
                  zeros in the decimal portion.

Seconds           Returns number of seconds since midnight in the format sssss
                  (no leading zeros).
Here are some examples:

TIME('L')    ->   '16:54:22.120000'   /* Perhaps */
TIME()       ->   '16:54:22'
TIME('H')    ->   '16'
TIME('M')    ->   '1014'           /* 54 + 60*16 */
TIME('S')    ->   '60862'  /* 22 + 60*(54+60*16) */
TIME('N')    ->   '16:54:22'
TIME('C')    ->   '4:54pm'

The Elapsed-Time Clock

The elapsed-time clock may be used for measuring real time intervals. On the
first call to the elapsed-time clock, the clock is started, and both TIME('E')
and TIME('R') will return 0.

The clock is saved across internal routine calls, which is to say that an
internal routine inherits the time clock its caller started.  Any timing the
caller is doing is not affected even if an internal routine resets the clock.

Here is an example of the elapsed-time clock:

time('E')    ->    0          /* The first call */
/* pause of one second here */
time('E')    ->    1.020000   /* or thereabouts */
/* pause of one second here */
time('R')    ->    2.030000   /* or thereabouts */
/* pause of one second here */
time('R')    ->    1.050000   /* or thereabouts */

Note:   See the DATE function about consistency of times within a single
        expression.  The elapsed-time clock is synchronized to the other calls
        to TIME and DATE, so multiple calls to the elapsed-time clock in a
        single expression always return the same result.  For the same reason,
        the interval between two normal TIME and DATE results may be calculated
        exactly using the elapsed-time clock.

Implementation maximum: If the number of seconds in the elapsed time exceed
nine digits (equivalent to over 31.6 years), an error will result.


ΓòÉΓòÉΓòÉ 11.59. TRACE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇTRACE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇoptionΓöÇΓöÿ

TRACE returns trace actions currently in effect.

If option is supplied, it must be the valid prefix (?), one of the alphabetic
character options (that is, starting with A, C, E, F, I, L, N, O, or R)
associated with the TRACE instruction, or both. The function uses option to
alter the effective trace action (such as tracing labels). Unlike the TRACE
instruction, the TRACE function alters the trace action even if interactive
debug is active.

Unlike the TRACE instruction, option cannot be a number.

Here are some examples:

TRACE()       ->   '?R' /* maybe */
TRACE('O')    ->   '?R' /* also sets tracing off    */
TRACE('?I')   ->   'O'  /* now in interactive debug */


ΓòÉΓòÉΓòÉ 11.60. TRANSLATE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇTRANSLATE(string ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇ
                       ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                           ΓööΓöÇtableoΓöÇΓöÿ ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
                                          ΓöötableiΓöÿ Γöö,padΓöÿ

TRANSLATE translates characters in string to other characters, or reorders
characters in a string. If neither translate table is given, string is simply
translated to uppercase (for example, a lowercase a-z to an uppercase A-Z). The
output table is tableo and the input translate table is tablei (the default is
XRANGE('00'x,'FF'x)). The output table defaults to the null string and is
padded with pad or truncated as necessary. The default pad is a blank. The
tables can be of any length; the first occurrence of a character in the input
table is the one that is used if there are duplicates.

Here are some examples:

TRANSLATE('abcdef')                        ->    'ABCDEF'
TRANSLATE('abbc','&','b')                  ->    'a&&c'
TRANSLATE('abcdef','12','ec')              ->    'ab2d1f'
TRANSLATE('abcdef','12','abcd','.')        ->    '12..ef'
TRANSLATE('4123','abcd','1234')            ->    'dabc'

Note:   The last example shows how to use the TRANSLATE function to reorder the
        characters in a string.  In the example, the last character of any
        four-character string specified as the second argument would be moved
        to the beginning of the string.


ΓòÉΓòÉΓòÉ 11.61. TRUNC ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇTRUNC(number ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇ,nΓöÇΓöÇΓöÿ

TRUNC returns the integer part of number, and n decimal places. The default n
is zero, and it returns an integer with no decimal point. If you specify n, it
must be a nonnegative whole number. The number is first rounded according to
standard REXX rules, just as though the operation number+0 had been carried
out. The number is then truncated to n decimal places (or trailing zeros are
added if needed to make up the specified length). The result is never in
exponential form.

Here are some examples:

TRUNC(12.3)           ->    12
TRUNC(127.09782,3)    ->    127.097
TRUNC(127.1,3)        ->    127.100
TRUNC(127,2)          ->    127.00

Note:   The number is rounded according to the current setting of NUMERIC
        DIGITS if necessary before being processed by the function.


ΓòÉΓòÉΓòÉ 11.62. VALUE ΓòÉΓòÉΓòÉ

 ΓöÇVALUE(nameΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ)ΓöÇΓöÇΓöÇ
                 ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                      ΓööΓöÇnewvalueΓöÇΓöÇΓöÿ ΓööΓöÇ,selectorΓöÇΓöÿ

VALUE returns the value of the symbol named by name, and optionally assigns it
a new value. By default, VALUE refers to the current REXX-variables
environment, but other, external collections of variables may be selected. If
you use the function to refer to REXX variables, then name must be a valid REXX
symbol. (You can confirm this by using the SYMBOL function.) Lowercase
characters in name are translated to uppercase. If name is a compound symbol,
then REXX substitutes symbol values to produce the derived name of the symbol.

If you specify newvalue, then the named variable is assigned this new value.
This does not affect the result returned; that is, the function returns the
value of name as it was before the new assignment.

Here are some examples:

     /* After: Drop A3; A33=7; K=3; fred='K'; list.5='Hi' */
     VALUE('a'k)     ->  'A3'
     VALUE('a'k||k)  ->  '7'
     VALUE('fred')   ->  'K'  /* looks up FRED   */
     VALUE(fred)     ->  '3'  /* looks up K      */
     VALUE(fred,5)   ->  '3'  /* and sets K=5    */
     VALUE(fred)     ->  '5'
     VALUE('LIST.'k) ->  'Hi' /* looks up LIST.5 */

To use VALUE to manipulate OS/2 environment variables, selector must be the
string 'OS2ENVIRONMENT' or an expression so evaluated. In this case, the
variable name need not be a valid REXX symbol. When VALUE is used to set or
change the value of an environment variable, the new value is retained after
the REXX procedure ends.

Here are some examples:

/* Given that an external variable FRED has a value of 4      */
share = 'OS2ENVIRONMENT'
say VALUE('fred',7,share)      /* says '4' and assigns        */
                               /* FRED a new value of 7       */

say VALUE('fred',,share)       /* says '7'                    */

/* After this procedure ends, FRED again has a value of 4     */

/* Accessing and changing OS/2 environment entries            */
env = 'OS2ENVIRONMENT'
new = 'C:\LIST\PROD;'
say value('prompt',,env)   /* says '$i[p]' (perhaps)          */
say value('path',new,env)  /* says 'C:\EDIT\DOCS;' (perhaps)  */
                           /* and sets PATH = 'C:LIST\PROD'   */

say value('path',,env)     /* says 'C:LIST\PROD'              */

/* When this procedure ends, PATH = 'C:\LIST\PROD'           */

Notes:

 1. If the VALUE function refers to an uninitialized REXX variable, then the
    default value of the variable is always returned; the NOVALUE condition is
    not raised. NOVALUE is never raised by a reference to an external
    collection of variables.

 2. The VALUE function is used when a variable contains the name of another
    variable, or when a name is constructed dynamically. If the name is
    specified as a single literal string, the symbol is a constant and so the
    whole function call can usually be replaced directly by the string between
    the quotation marks.  (For example, fred=VALUE('k'); is identical to the
    assignment fred=k;,unless the NOVALUE condition is being trapped.

 3. To effect temporary changes to environment variables, use the SETLOCAL and
    ENDLOCAL functions.


ΓòÉΓòÉΓòÉ 11.63. VERIFY ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇVERIFY(string,referenceΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇ
                             ΓööΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
                                 ΓööΓöÇoptionΓöÇΓöÇΓöÿ ΓööΓöÇ,startΓöÇΓöÿ

VERIFY returns a number indicating whether string is composed only of
characters from reference. VERIFY returns the position of the first character
in string that is not also in reference.  If all the characters were found in
reference, 0 is returned.

The third argument, option, can be any expression that results in a string
starting with N or M that represents either Nomatch (the default) or Match..
Only the first character of option is significant and it can be in uppercase or
lowercase, as usual. If Nomatch is specified, the position of the first
character in string that is not also in reference is returned. 0 is returned if
all characters in string were found in reference. If Match is specified, the
position of the first character in string that is in reference is returned, or
0 is returned if none of the characters were found.

The default for start is 1, thus, the search starts at the first character of
string. You can override this by specifying a different start point, which must
be a positive whole number.

VERIFY always returns 0 if string is null or if start is greater than
LENGTH(string). If reference is null, VERIFY returns 0 if you specify Match;
otherwise, 1 is returned.

Here are some examples:

VERIFY('123','1234567890')             ->    0
VERIFY('1Z3','1234567890')             ->    2
VERIFY('AB4T','1234567890')            ->    1
VERIFY('AB4T','1234567890','M')        ->    3
VERIFY('AB4T','1234567890','N')        ->    1
VERIFY('1P3Q4','1234567890',,3)        ->    4
VERIFY('AB3CD5','1234567890','M',4)    ->    6


ΓòÉΓòÉΓòÉ 11.64. WORD ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇWORD(string,n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

WORD returns the n th blank-delimited word in string. n must be a positive
whole number. If there are fewer than n words in string, the null string is
returned. This function is equivalent to SUBWORD(string,n,1).

Here are some examples:

WORD('Now is the time',3)    ->    'the'
WORD('Now is the time',5)    ->    ''


ΓòÉΓòÉΓòÉ 11.65. WORDINDEX ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇWORDINDEX(string,n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

WORDINDEX returns the position of the first character in the n th
blank-delimited word in string. n must be a positive whole number. If there are
fewer than n words in the string, 0 is returned.

Here are some examples:

WORDINDEX('Now is the time',3)    ->    8
WORDINDEX('Now is the time',6)    ->    0


ΓòÉΓòÉΓòÉ 11.66. WORDLENGTH ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇWORDLENGTH(string,n)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

WORDLENGTH returns the length of the n th blank-delimited word in string. n
must be a positive whole number. If there are fewer than n words in the string,
0 is returned.

Here are some examples:

WORDLENGTH('Now is the time',2)       ->    2
WORDLENGTH('Now comes the time',2)    ->    5
WORDLENGTH('Now is the time',6)       ->    0


ΓòÉΓòÉΓòÉ 11.67. WORDPOS ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇWORDPOS(phrase,stringΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                             ΓööΓöÇ,startΓöÇΓöÇΓöÿ

WORDPOS searches string for the first occurrence of the sequence of
blank-delimited words phrase, and returns the word number of the first word of
phrase in string.  Multiple blanks between words in either phrase or string are
treated as a single blank for the comparison, but otherwise the words must
match exactly.

By default, the search starts at the first word in string. You can override
this by specifying start (which must be positive), the word at which to start
the search.

Here are some examples:

WORDPOS('the','now is the time')              ->  3
WORDPOS('The','now is the time')              ->  0
WORDPOS('is the','now is the time')           ->  2
WORDPOS('is   the','now is the time')         ->  2
WORDPOS('is   time ','now is   the time')     ->  0
WORDPOS('be','To be or not to be')            ->  2
WORDPOS('be','To be or not to be',3)          ->  6


ΓòÉΓòÉΓòÉ 11.68. WORDS ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇWORDS(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

WORDS returns the number of blank-delimited words in string.

Here are some examples:

WORDS('Now is the time')    ->    4
WORDS(' ')                  ->    0


ΓòÉΓòÉΓòÉ 11.69. XRANGE ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇXRANGE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇstartΓöÇΓöÿ  ΓööΓöÇ,endΓöÇΓöÇΓöÿ

XRANGE returns a string of all one-byte codes between and including the values
start and end. The default value for start is `00'x, and the default value for
end is `FF'x. If start is greater than end, the values wrap from `FF'x to
`00'x. If specified, start and end must be single characters.

Here are some examples:

XRANGE('a','f')      ->   'abcdef'
XRANGE('03'x,'07'x)  ->   '0304050607'x
XRANGE(,'04'x)       ->   '0001020304'x
XRANGE('i','j')      ->   '898A8B8C8D8E8F9091'x  /* EBCDIC */
XRANGE('FE'x,'02'x)  ->   'FEFF000102'x
XRANGE('i','j')      ->   'ij'                   /* ASCII  */


ΓòÉΓòÉΓòÉ 11.70. X2B (Hexadecimal to Binary). ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇX2B(hexstring)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

X2B converts hexstring (a string of hexadecimal characters) to an equivalent
string of binary digits. hexstring can be of any length; each hexidecimal
character is converted to a string of four binary digits. The returned string
has a length that is a multiple of four, and does not include any blanks.

Blanks can optionally be added (at byte boundaries only, not leading or
trailing) to aid readability; they are ignored.

If hexstring is null, X2B returns 0.

Here are some examples:

X2B('C3')        ==  '11000011'
X2B('7')         ==  '0111'
X2B('1 C1')      ==  '000111000001'

You can combine X2B( ) may be combined with the functions D2X( ) and C2X( ) to
convert decimal numbers or character strings into binary form.

Here are some examples:

X2B(C2X('C3'x))  ==  '11000011'
X2B(D2X('129'))  ==  '10000001'
X2B(D2X('12'))   ==  '1100'


ΓòÉΓòÉΓòÉ 11.71. X2C (Hexadecimal to Character) ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇX2C(hexstring)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

X2C converts hexstring (a string of hexadecimal characters) to character.

hexstring can be of any length. You can optionally add blanks to hexstring (at
byte boundaries only, not leading or trailing positions) to aid readability;
they are ignored.

If necessary, hexstring is padded with a leading 0 to make an even number of
hexadecimal digits.

Here are some examples:

X2C('4865 6c6c 6f') ->  'Hello'     /*  ASCII   */
X2C('3732 73')      ->  '72s'       /*  ASCII   */
X2C('F')          ->    '0F'x


ΓòÉΓòÉΓòÉ 11.72. X2D (Hexadecimal to Decimal) ΓòÉΓòÉΓòÉ

 ΓöÇΓöÇΓöÇX2D(hexstring ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇ,nΓöÇΓöÇΓöÿ

X2D converts hexstring (a string of hexadecimal characters) to decimal. If the
result cannot be expressed as a whole number, an error results. That is, the
result must have no more digits than the current setting of NUMERIC DIGITS.

You can optionally add blanks to hexstring (at byte boundaries only, not
leading or trailing positions) to aid readability; they are ignored.

If hexstring is null, X2D returns 0.

If n is not specified, hexstring is processed as an unsigned binary number.

Here are some examples:

X2D('0E')        ->    14
X2D('81')        ->    129
X2D('F81')       ->    3969
X2D('FF81')      ->    65409
X2D('c6 f0'X)    ->    240

If n is specified, the given sequence of hexadecimal digits is padded on the
left with zeros (note, not sign-extended), or truncated on the left to n
characters. The resulting string of n hexadecimal digits is taken to be a
signed binary number-positive if the leftmost bit is OFF, and negative, in
two's complement notation, if the leftmost bit is ON. If n is 0, X2D returns 0.

Here are some examples:

X2D('81',2)      ->    -127
X2D('81',4)      ->    129
X2D('F081',4)    ->    -3967
X2D('F081',3)    ->    129
X2D('F081',2)    ->    -127
X2D('F081',1)    ->    1
X2D('0031',0)    ->    0


ΓòÉΓòÉΓòÉ 12. Queue Interface ΓòÉΓòÉΓòÉ

REXX provides queuing services entirely separate from the OS/2 interprocess
communications queues. The queues discussed here are solely for the use of REXX
programs.

REXX queues are manipulated within a program by these instructions:

PUSH        Stacks a string on top of the queue (LIFO).

QUEUE       Adds a string to the tail of the queue (FIFO).

PULL        Reads a string from the head of the queue. If the queue is empty,
            input is taken from the console (STDIN:).

To get the number of items remaining in the queue, use the function QUEUED.

Access to Queues

There are two kinds of queues in REXX. Both kinds are accessed and processed by
name.

Session Queues - One session queue is automatically provided for each OS/2
session in operation. Its name is always SESSION, and it is created by REXX the
first time information is put on the queue by a program or procedure. All
processes (programs and procedures) in a session can access the session queue.
However, a given process can only access the session queue defined for its
session, and the session queue is not unique to any single process in the
session.

Private Queues - Private queues are created (and deleted) by your program. You
can name the queue yourself or leave the naming to REXX. In order for your
program to use any queue, it must know the name of the queue.


ΓòÉΓòÉΓòÉ 12.1. RXQUEUE Function ΓòÉΓòÉΓòÉ

Use the RxQueue function in a REXX program to create and delete queues and to
set and query their names. The first parameter determines the function, the
entire function name must be specified but the case of the function parameter
is ignored.

Syntax:


 ΓöÇΓöÇRXQUEUE(ΓöÇΓö¼ΓöÇΓöÇ"Create"ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇ
              Γöé            ΓööΓöÇ,queuename ΓöÇΓöÿ Γöé
              Γö£ΓöÇΓöÇΓöÇ"Delete"ΓöÇΓöÇ queuename ΓöÇΓöÇΓöÇΓöÇΓöñ
              Γö£ΓöÇΓöÇΓöÇ"Get"ΓöÇΓöÇΓöÇΓöÇΓöÇ newqueuename ΓöÇΓöñ
              ΓööΓöÇΓöÇΓöÇ"Set"ΓöÇΓöÇΓöÇΓöÇΓöÇ newqueuename ΓöÇΓöÿ

Parameters:

Create            Creates a queue with the name, queuename (if specified); if
                  no name is specified, then REXX will provide a name. Returns
                  the name of the queue in either case.

Delete            Deletes the named queue; returns 0 if successful, a nonzero
                  number if an error occurs; the possible return values are:

   0           Queue has been deleted.

   5           Not a valid queue name.

   9           Queue named does not exist.

   10          Queue is busy; wait is active.

   12          A memory failure has occurred.

   1000        Initialization error; check file OS/2.INI

Get               Returns the name of the queue currently in use.

Set               Sets the name of the current queue to newqueuename and
                  returns the previous name of the queue.

Example: Sample Queue in a REXX Procedure


/*                                                                */
/*        push/pull WITHOUT multiprogramming support         */
/*                                                                */
push date() time()          /* push date and time            */
do 1000                     /* lets pass some time           */
  nop                       /* doing nothing                 */
end                         /* end of loop                   */
pull a b .                  /* pull them                     */
say 'Pushed at ' a b ', Pulled at ' date()
time() /* say now and then */

/*                                                                    */
/*              push/pull WITH multiprogramming support               */
/*            (no error recovery, or unsupported env tests            */
/*                                                                    */
newq = RXQUEUE('Create')    /* create a unique queue           */
oq = RXQUEUE('Set',newq)    /* establish new queue             */
push date() time()          /* push date and time              */
do 1000                     /* lets spend some time            */
  nop                       /* doing nothing                   */
end                         /* end of loop                     */
pull a b .                  /* get pushed info                 */
say 'Pushed at ' a b ', Pulled at ' date() time() /* tell user     */
call RXQUEUE 'Delete',newq         /* destroy unique queue created  */
call RXQUEUE 'Set',oq         /* reset to default queue (not required)*/

Special Considerations

 1. External programs that must communicate with a REXX procedure by means of
    defined data queues can use the default queue or the session queue, or they
    can receive the data queue name by some interprocess communication
    technique. This could include parameter passing, placement on a prearranged
    logical queue, or use of normal OS/2 Inter-Process Communication mechanisms
    (for example, pipes, shared memory or IPC queues).

 2. Named queues are available across the entire system; therefore, the names
    of queues must be unique within the system.  If a queue named os2que exists
    and this function is issued:

        newqueue = RXQUEUE('Create', 'os2que')

    a new queue is created and the name is chosen by REXX.  This new name is
    returned by the function.

 3. Any external program started inherits as its default queue the queue in use
    by the parent process.

Detached Processes

 1. Detached processes will access a detached session queue that is unique for
    each detached process. Note, however, that this detached session queue is
    not the same as the session queue of the starting session.

 2. REXX programs that are to be run as detached processes cannot perform any
    SAY instructions or any PULL or PARSE PULL instructions that involve
    terminal I/O. However, PULL and PARSE PULL instructions that act on a queue
    are permitted in detached processes.

Multi-Programming Considerations

This data queue mechanism differs from OS/2 standard API queueing in the
following ways:

 1. The queue is NOT owned by a specific process, and as such any process is
    entitled to modify the queue at any time.  The operations that effect the
    queue are atomic, in that the resource will be serialized by the subsystem
    such that no data integrity problems can be encountered.

    However, synchronization of requests such that two processes, accessing the
    same queue, get the data in the order it was placed on the queue is a user
    responsibility and will not be provided by the subsystem support code. This
    selector is owned by the calling application code and must be freed by the
    caller using DosFreeSeg.

 2. A regular OS/2 IPC queue is owned (created) by a specific process. When
    that process terminates, the queue is destroyed. Conversely, the queues
    created by the RxQueue('Create', queuename) call will exist until
    EXPLICITLY deleted. Termination of a program or procedure that created a
    private queue does not force the deletion of the private queue. Any data on
    the queue when the process creating it terminates will remain on the queue
    until either the queue is deleted (by way of the REXX function call
    RxQueue('Create', queuename) or until the data is read.

Data queues must be explicitly deleted by some procedure or program (not
necessarily the creator). Deletion of a queue with remaining items, destroys
those items. If a queue is not deleted, it will be lost and cannot be recovered
accept by randomly attempting to access each queue in the defined series.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

A batch file contains a series of commands that you would enter, one at a time,
at a command prompt for a particular process.  Instead, you simply type the
name of the file.  Using a batch file shortens process time and reduces the
possibility of typing errors.  Batch files in DOS sessions have a .BAT
extension and in OS/2 sessions a .CMD extension.  For more information about
batch files, see the Command Reference.