Rexx
Rexx
REXX Language
Document revision 4
2 January 2023
NetPhantom®
© Copyright Nexum International SARL, 2023. All rights reserved.
Information in this document is subject to change without notice. Companies, names, and
data used in examples are fictitious unless otherwise noted. No part of this document may
be reproduced or transmitted in any form or by any means, electronic or mechanical, for
any purpose, without the express written permission of Nexum International.
This manual is based on portions of the Personal REXX Language Reference, copyright
1994-1995 by Quercus Systems. Used by permission of Quercus Systems.
Telephone: +377 99 90 32 66
Web: https://netphantom.com
E-mail: [email protected]
Support
Phone: +377 99 90 32 66
E-mail: [email protected]
Contents • i
Contents
1 Getting Started in REXX ................................................................................................ 1
1.1 Introduction to REXX .......................................................................................... 1
1.2 Writing a REXX Procedure .................................................................................. 1
2 Using Fundamental REXX Elements ............................................................................. 3
2.1 Basic Elements of REXX ..................................................................................... 3
2.2 Comments............................................................................................................. 3
2.3 Strings................................................................................................................... 4
2.4 Instructions ........................................................................................................... 4
SAY Instruction .............................................................................................. 4
PULL and PARSE PULL Instructions ............................................................ 4
EXIT Instruction ............................................................................................. 5
2.5 Assignments ......................................................................................................... 5
2.6 Labels ................................................................................................................... 5
3 Working with Variables and Arithmetic ....................................................................... 7
3.1 Introduction .......................................................................................................... 7
3.2 Variables............................................................................................................... 7
3.3 Value .................................................................................................................... 7
3.4 Working with Arithmetic...................................................................................... 8
Operators ......................................................................................................... 9
Addition .......................................................................................................... 9
Subtraction ...................................................................................................... 9
Multiplication .................................................................................................. 9
Division ........................................................................................................... 9
Evaluating Expressions ................................................................................... 9
4 REXX Features .............................................................................................................. 11
4.1 Introduction to REXX Features .......................................................................... 11
4.2 Making Decisions (IF THEN) ........................................................................... 11
Grouping Instructions Using DO and END................................................... 12
4.3 The ELSE Instruction ......................................................................................... 12
4.4 SELECT, END, WHEN, OTHERWISE, and NOP Instructions ........................ 12
4.5 True and False Operators .................................................................................... 14
4.6 The Logical Operators, NOT, AND, OR ............................................................ 14
5 Automating Repetitive Tasks - Using Loops ............................................................... 17
5.1 Introduction to Loops ......................................................................................... 17
5.2 Repetitive Loops ................................................................................................. 17
5.3 Conditional Loops .............................................................................................. 18
DO WHILE and DO UNTIL ......................................................................... 18
LEAVE.......................................................................................................... 19
DO FOREVER .............................................................................................. 19
5.4 Parsing Words .................................................................................................... 20
6 Advanced REXX Functions .......................................................................................... 21
6.1 Introduction to Advanced REXX Functions ....................................................... 21
6.2 Functions ............................................................................................................ 21
Built-in Functions.......................................................................................... 21
6.3 DATATYPE() .................................................................................................... 22
6.4 SUBSTR() .......................................................................................................... 22
6.5 CALL ................................................................................................................. 23
6.6 REXX.CMD File Commands ............................................................................. 24
6.7 Error Messages ................................................................................................... 24
7 Keyword Instructions .................................................................................................... 27
7.1 Introduction to Keyword Instructions ................................................................. 27
7.2 ADDRESS .......................................................................................................... 27
7.3 ARG ................................................................................................................... 28
7.4 CALL ................................................................................................................. 28
7.5 DO ...................................................................................................................... 29
Simple DO Group ......................................................................................... 30
Simple Repetitive Loops ............................................................................... 30
Controlled Repetitive Loops ......................................................................... 30
Conditional Phrases (WHILE and UNTIL) ................................................... 32
7.6 DROP ................................................................................................................. 32
7.7 EXIT ................................................................................................................... 33
7.8 IF ........................................................................................................................ 33
7.9 INTERPRET ...................................................................................................... 34
7.10 ITERATE ......................................................................................................... 36
7.11 LEAVE ............................................................................................................. 36
7.12 NOP .................................................................................................................. 37
7.13 NUMERIC........................................................................................................ 37
NUMERIC FORM ........................................................................................ 38
NUMERIC FUZZ ......................................................................................... 38
FUZZ ............................................................................................................. 38
7.14 OPTIONS ......................................................................................................... 38
7.15 PARSE.............................................................................................................. 39
PARSE ARG ................................................................................................. 39
PARSE LINEIN ............................................................................................ 39
PARSE PULL ............................................................................................... 40
PARSE SOURCE .......................................................................................... 40
PARSE VALUE ............................................................................................ 40
PARSE VAR name ....................................................................................... 40
PARSE VERSION ........................................................................................ 40
7.16 PROCEDURE .................................................................................................. 41
7.17 PULL ................................................................................................................ 42
7.18 PUSH ................................................................................................................ 42
7.19 QUEUE ............................................................................................................ 43
7.20 RETURN .......................................................................................................... 43
7.21 SAY .................................................................................................................. 43
7.22 SELECT ........................................................................................................... 44
7.23 SIGNAL ........................................................................................................... 45
Using SIGNAL with the INTERPRET Instruction ....................................... 45
7.24 TRACE ............................................................................................................. 45
Alphabetic Character (Word) Options........................................................... 46
Prefix Option ................................................................................................. 47
Numeric Options ........................................................................................... 47
Format of TRACE Output ............................................................................. 47
8 Functions ........................................................................................................................ 49
8.1 Syntax ................................................................................................................. 49
Calls to Functions and Subroutines ............................................................... 49
Search Order.................................................................................................. 50
Errors during Execution ................................................................................ 51
Return Values ................................................................................................ 51
Built-in Functions.......................................................................................... 52
8.2 ABBREV ............................................................................................................ 52
8.3 ABS (Absolute Value) ........................................................................................ 53
8.4 ADRESS ............................................................................................................. 53
8.5 API Functions ..................................................................................................... 53
RXFUNCADD .............................................................................................. 53
RXFUNCDROP ............................................................................................ 53
RXFUNCQUERY ......................................................................................... 53
RXQUEUE .................................................................................................... 53
8.6 ARG ................................................................................................................... 53
8.7 BEEP .................................................................................................................. 54
8.9 BITAND ............................................................................................................. 55
8.10 BITOR .............................................................................................................. 55
8.11 BITXOR ........................................................................................................... 55
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.
Now you are ready to run the REXX procedure you have written. Type the name of the
procedure at the 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"
Specifies that the instruction that follows is to be run if the tested condition is not true.
SAY "Hello" who
Here is what would happen if a person named Bill tried the HELLO program:
Hello! I am REXX.
What is your name?
Bill
Hello BILL
If Bill does not type his name, but types a blank space, this happens:
Hello! I am REXX.
What is your name?
Hello Stranger
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.
• Comments
• Strings
• Instructions
• Assignments
• Labels
• Internal Functions
2.2 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:
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.
2.3 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"
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."""
2.4 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"
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.
The following procedure does not work correctly if the PULL instruction comes before the
SAY instruction.
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.
2.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.
2.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
3.2 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.
3.3 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
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
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
When you run the VARIABLE procedure, it looks like this on your screen:
abc
abc def
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:
Running the porgram
HERE IS no PERSON I WANT TO MEET
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
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.
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
Subtraction
The operator for subtraction is the minus sign (-). An instruction to subtract two numbers is:
SAY 8 - 3
Multiplication
The operator for multiplication is the asterisk (*). An instruction to multiply two numbers
is:
SAY 2 * 2
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
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 push button.
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 =
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 REXX Features
4.1 Introduction to 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:
Two instructions that let you make decisions in your procedures are the IF and SELECT
instructions. The IF instruction 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.
The DO instruction and its END instruction tell the interpreter to treat any instructions
between them as a single instruction.
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:
Are you going to the meeting?
yes
SELECT
WHEN expression1
THEN instruction1
WHEN expression2
THEN instruction2
WHEN expression3
THEN instruction3
...
OTHERWISE
instruction
instruction
instruction
END
• 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.
• If, and only if, all of the specified expressions are false, then processing continues with
the instruction following OTHERWISE.
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.
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.
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.
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 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' */
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:
The num is a whole number, which is the number of times the loop is to be run.
When you run the LOOP.CMD, you see this on your screen:
Thank-you
Thank-you
Thank-you
Thank-you
Thank-you
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.
When a loop ends, the procedure continues with the instruction following the end of the
loop, which is identified by 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.
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.
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.
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.
6.2 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.
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 this
documentation.
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.
6.3 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
If you want the user to type only whole numbers, you could use another form of the
DATATYPE() function:
DATATYPE(number, whole)
• whole - refers to the type of data to be tested. In this example, the data must be a
whole number.
6.4 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:
• The position of the first character that is to be contained in the result (characters are
numbered 1,2,3...in the string).
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. */
6.5 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.
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. */
displayed:
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!
Note: In the preceding example, the whole command except for COPY is
in quotation marks for the following reasons:
• If the colon (:) were not in quotation marks, the REXX interpreter would treat a: and b:
as labels.
• If the asterisk (*) were not in quotation marks, the REXX interpreter would attempt to
multiply the value of a: by .LST.
• It is also acceptable to include the entire command in quotation marks so that "COPY
a:*.LST b:" is displayed.
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 a 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 operating system 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.
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.
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, he 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'
7 Keyword Instructions
7.1 Introduction to 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.
7.2 ADDRESS
ADDRESS [environment [expression] ]
or
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.
7.3 ARG
ARG [template]
ARG is used to retrieve the argument strings provided to a program or internal routine and
assign them to variables.
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' */
7.4 CALL
CALL name [ [expression1] [,] [expression2]…[,] [expression20] ]
or
or
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:
• An internal routine
• An external routine
• 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:
The exception is that the variable result becomes uninitialized if no result is returned by the
routine invoked.
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
Built-in routines
External routines
7.5 DO
DO [repetitor] [conditional];[instruction1] [instruction2 ]…[instruction20] END
[name]
conditional: WHILE-exprw
or: UNTIL-expru
Syntax Notes:
• 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.
• The exprw or expru options (if present) can be any expression that evaluates to 1 or 0.
• The TO, BY, and FOR phrases can be in any order, if used.
• 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.
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.
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
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.
(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 */
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.
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 */
7.6 DROP
DROP name1 name 2…name20
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. */
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. */
7.7 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.
7.8 IF
IF-expression [;] THEN [;] instruction [ELSE [;] instruction]
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?'
7.9 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: 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.
Example:
/* Here we have a small program. */
Trace Int
name='Kitty'
indirect='name'
interpret 'say "Hello"' indirect'"!"'
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!
Note: 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.
7.10 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 */
If more than one active loop uses the same control variable, the
innermost loop is the one selected by ITERATE.
7.11 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 */
If more than one active loop uses the same control variable, the
innermost one is the one selected by LEAVE.
7.12 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.
7.13 NUMERIC
NUMERIC DIGITS [expression]
or
or
The NUMERIC instruction is used to change the way in which arithmetic operations are
carried out.
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
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
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
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
7.14 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:
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: 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.
7.15 PARSE
PARSE [UPPER] ARG [template list]
PARSE is used to assign data from various sources to one or more variables.
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.
PARSE LINEIN
The next line from the default character input stream is parsed. PARSE LINEIN is a shorter
form of the following instruction:
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 operating system name 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.
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.
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
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").
7.16 PROCEDURE
PROCEDURE [EXPOSE [name1] [name2]…[name20] ]
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
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. */
Only one PROCEDURE instruction in each level of routine call is allowed; all others (and
those met outside of internal routines) are in error.
See the CALL instruction for details and examples of how routines are invoked.
7.17 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:
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.
7.18 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 */
The number of lines currently in the queue can be found with the QUEUED built-in
function.
7.19 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.
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.
7.20 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.
7.21 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: Data from the SAY instruction is sent to the default output
stream (STDOUT:) However, the standard rules for redirecting
output apply to SAY output.
The SAY instruction does not format data; line wrapping is handled
Example:
data=100
Say data 'divided by 4 =>' data/4
/* Would display: "100 divided by 4 => 25" */
7.22 SELECT
SELECT; WHEN expression [;] THEN [;] instruction [OTHERWISE ] [;] [intruction]
] END
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 */
7.23 SIGNAL
SIGNAL lablename
or
or
or
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.
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.
7.24 TRACE
TRACE [number]
or
TRACE [? ?2 type]
where type can be All, Commands, Error, Failure, Intermediates, Labels, Normal, Off, or
Results
or
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 keystrokes for this instruction is
especially convenient since TRACE is usually entered manually during interactive
debugging.
• A number option
• One of the valid prefix, alphabetic character (word) options, or both, shown in this
panel
• Null.
• A number option
• 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).
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.
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, switches 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.
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.
8 Functions
8.1 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()
or
function-name(parm1,…parm20 [,])
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
*/
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
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.
1. Functions that have been loaded into the macrospace for pre-order execution
7. Functions that have been loaded into the macrospace for post-order execution.
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 */
• 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.
• 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.
• 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 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.
• 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.
• 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.
• 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.
• 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.
8.2 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.
ABS returns the absolute value of number. The result has no sign and is formatted
according to the current NUMERIC settings.
8.4 ADRESS
ADRESS()
ADDRESS returns the name of the environment to which host commands are currently
being submitted. Trailing blanks are removed from the result.
RXFUNCADD
RXFUNCADD(name,module,procedure)
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.
8.6 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 nth 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 nth argument string. Valid options
(of which only the capitalized letter is significant and all others are ignored) are:
Exists Returns 1 if the nth 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.
Notes: You can retrieve and directly parse the argument strings to a
program or internal routine using the ARG or PARSE ARG
instructions.
8.7 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
8.9 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.
8.10 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.
8.11 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.
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.
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 */
8.13 CENTER/CENTRE
CENTER or CENTRE(string,length [,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.
8.14 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. 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.
Note: CHARIN returns all characters that appear in the stream including
control characters such as line feed, carriage return, and end of file.
8.15 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 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. 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.
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).
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
8.16 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, the default input stream will be used.
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.
8.17 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.
8.18 CONDITION
CONDITION([option])
CONDITION returns the condition information associated with the current trapped
condition. You can request four pieces of information:
The following options (of which only the capitalized letter is needed, all others are ignored)
can be used to obtain the following information:
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.
8.19 COPIES
COPIES(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 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.
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.
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.
8.22 DATATYPE
DATATYPE(string [,type])
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 Returns 1 if string is a REXX whole number under the current setting of
number 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.
8.23 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 582, 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. 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.
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.
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.
8.25 DELWORD
DELWORD(string,n [,length])
DELWORD deletes the substring of string that starts at the nth 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.
8.26 DIGITS
DIGITS()
Here is an example:
DIGITS() -> 9 /* by default */
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.
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.
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).
8.29 DIRECTORY
DIRECTORY([newdictionary])
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'
8.30 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.
8.31 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.
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 environment. */
n = ENDLOCAL() /* restores the initial environment */
8.32 FILESPEC
FILESPEC(option,filespec)
If the requested string is not found, then FILESPEC returns a null string (" ").
part = "name"
say FILESPEC(part,thisfile) /* says "EXAMPLE.EXE" */
8.33 FORM
FORM()
Here is an example:
FORM() -> 'SCIENTIFIC' /* by default */
8.34 FORMAT
FORMAT(number [, [before] [, [ after] [, [expp] [,expt] ]] ])
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.
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.
8.35 FUZZ
FUZZ()
Here is an example:
FUZZ() -> 0 /* by default */
8.36 INSERT
INSERT(new,target [, [n] [, [length] [,pad] ] ])
INSERT inserts the string new, padded to length length, into the string target after the nth
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.
8.37 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.
8.38 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]).
8.39 LENGTH
LENGTH(string)
8.40 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. The default count is 1.
For persistent streams, a read position is maintained for each stream. 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-.
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.
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.) */
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.
8.41 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.
For persistent streams, a write position is maintained for each stream. 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.
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 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).
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 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.
8.42 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.
8.43 MAX
MAX(number[,number2][,number3]…[,number20])
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.
8.44 MIN
MIN(number[,number2][,number3]…[,number20])
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.
8.45 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.
8.46 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.
8.47 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 */
8.48 RANDOM
RANDOM([max])
or
RANDOM([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.
Note 3: The actual random number generator used may differ from
implementation to implementation.
8.49 REVERSE
REVERSE(string)
8.50 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.
8.51 SETLOCAL
SETLOCAL()
SETLOCAL saves the current working drive and directory, and the current values of the
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 */
Note: Unlike their counterparts in the OS/2 Batch language (the Setlocal
and Endlocal statements), the REXX SETLOCAL and
ENDLOCAL functions can be nested.
8.52 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.
8.53 SOURCELINE
SOURCELINE([n])
SOURCELINE returns the line number of the final line in the source file if you omit n, or
returns the nth 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.
8.54 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.
8.55 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:
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. This response can be used to
indicate that the state of the stream cannot be determined.
Stream Commands
The following stream commands are used to:
• Position the read or write position within a persistent stream (for example, a file)
• 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 the new position in the stream if
the read or write position is successfully located; an appropriate error
message is displayed otherwise
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 Returns the date and time stamps of a stream.
DATETIME' stream('..\file.txt','c','query
datetime')
8.56 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.
8.57 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.
8.58 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.
8.59 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).
Note: You should specify name as a literal string (or derived from an
expression) to prevent substitution before it is passed to the
function.
8.60 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 started 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 started 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).
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.
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.
8.61 TRACE
TRACE([option])
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.
8.62 TRANSLATE
TRANSLATE(string [, [tableo] [, [tablei] [,pad] ] ])
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.
8.63 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.
8.64 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.
8.65 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.
8.66 WORD
WORD(string,n)
WORD returns the nth 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).
8.67 WORDINDEX
WORDINDEX(string,n)
WORDINDEX returns the position of the first character in the nth 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.
8.68 WORDLENGTH
WORDLENGTH(string,n)
WORDLENGTH returns the length of the nth blank-delimited word in string. n must be a
positive whole number. If here are fewer than n words in the string, 0 is returned.
8.69 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.
8.70 WORDS
WORDS(string)
8.71 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.
Blanks can optionally be added (at byte boundaries only, not leading or trailing) to aid
readability; they are ignored.
You can combine X2B() may be combined with the functions D2X() and C2X() to convert
decimal numbers or character strings into binary form.
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.
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 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.