Interfacing Rexx to other programs

Cours interfacing Rexx to other programs, tutoriel & guide de travaux pratiques en pdf.

Rexx Language Constructs

In this chapter, the concept and syntax of Rexx clauses are explained. At the end of the chapter there is a section describing how Regina differs from standard Rexx as described in the first part of the chapter.

Definitions
A program in the Rexx language consists of clauses, which are divided into four groups: null clauses, commands, assignments, and instructions. The three latter groups (commands, assignments, and instructions) are collectively referred to as statements. This does not match the terminology in [TRL2], where « instruction » is equivalent to what is known here as « statement », and « keyword instruction » is equivalent to what is known here as « instruction ». However, I find the terminology used here simpler and less confusing.
Incidentally, the terminology used here matches [DANEY].
A clause is defined as all non-clause-delimiters (i.e. blanks and tokens) up to and including a clause delimiter. A token delimiter can be:
• An end-of-line, unless it lies within a comment, or the last token on a line is the line continuation character. An end-of-line within a constant string is considered a syntax error {6}.
• A semicolon character that is not within a comment or constant string.
• A colon character, provided that the sequence of tokens leading up to it consists of a single symbol and whitespace. If a sequence of two symbol tokens is followed by a colon, then this implies SYNTAX condition {20}.
Some systems have the ability to store a text file having a last line unterminated by an end-of-line character sequence. In general, this applies to systems that use an explicit end-of-line character sequence to denote end-of-lines, e.g. Unix and MS-DOS systems. Under these systems, if the last line is unterminated, it will strictly speaking not be a clause, since a clause must include its terminating clause delimiter. However, some interpreters are likely to regard the end-of-file as a clause delimiter too. The functionality of INTERPRET gives some weight to this interpretation. But other systems may ignore that last, unterminated line, or maybe issue a syntax error. (However, there is no SYNTAX condition number adequately covering this situation.
Example: Binary transferring files
Suppose a Rexx program is stored on an MS-DOS machine. Then, an end- of-line sequence is marked in the file as the two characters carriage return and newline. If this file is transferred to a Unix system, then only newline marks the end-of-line. For this to work, the file must be transferred as a text file. If it is (incorrectly) transferred as a binary file, the result is that on the Unix system, each line seems to contain a trailing carriage return character. In an editor, it might look like this:
say ‘hello world’^M
say ‘that »s it’^M
This will probably raise SYNTAX condition {13}.

Null clauses
Null clauses are clauses that consist of only whitespace, or comments, or both; in addition to the terminating clause delimiter. These clauses are ignored when interpreting the code, except for one situation: null clauses containing at least one comment is traced when appropriate. Null clauses not containing any comments are ignored in every respect.
Example: Tracing comments
The tracing of comments may be a major problem, depending on the context. There are basically two strategies for large comments: either box multiple lines as a single comment, or make the text on each line an independent comment, as shown below:
trace all /*
This is a single, large comment, which spans multiple lines.
Such comments are often used at the start of a subroutine or similar, in order to describe both the interface to and the functionality of the function.
/* This is also a large comment, but it is written as */
/* multiple comments, each on its own line. Thus, these */
/* are several clauses while the comment above is a */
/* single comment. */
— These lines also consist of multiple comments, and thus
— multiple clauses. This form of comment was introduced
— in Regina 3.4
During tracing, the first of these will be displayed as one large comment, and during interactive tracing, it will only pause once. The second will be displayed as multiple lines, and will make several pauses during interactive tracing. An interpreter may solve this situation in several ways, the main objective must be to display the comments nicely the to programmer debugging the code. Preferably, the code is shown in a fashion that resembles how it is entered in the file.
If a label is multiple defined, the first definition is used and the rest are ignored. Multiple defined labels is not an SYNTAX condition.
A null clause is not a statement. In some situations, like after the THEN subclause, only a statement is expected. If a null clause is provided, then it is ignored, and the next statement is used instead.
Consider the following code:
parse pull foo
if foo=2 then
say ‘foo is not 2’
else
/* do nothing */
say ‘that »s it’
This will not work the way indentation indicates, since the comment in this example is not a statement. Thus, the ELSE reads beyond the comment, and connects to the SAY instruction which becomes the ELSE part. (That what probably not what the programmer intended.) This code will say that’s it, only when foo is different from 2. A separate instruction, NOP has been provided in order to fill the need that was inadequately attempted filled by the comment in the code fragment above.

Example: Trailing comments
The effect that comments are not statements can be exploited when documenting the program, and simultaneously making the program faster. Consider the following two loops:
In the first loop, there are two clauses, while the second loop contains only one clause, because the comment is appended to an already existing clause. During execution, the interpreter has to spend time ignoring the null clause in the first loop, while the second loop avoids this problem (assuming tracing is not enabled). Thus, the second loop is faster; although only insignificantly faster for small loops. Of course, the comment could have been taken out of the loop, which would be equally fast to the second version above.

Commands
Assignments

Assignments are clauses where the first token is a symbol and the second token is the equal sign (=). This definition opens for some curious effects, consider the following clauses: a == b
This is not a command, but an assignment of the expression = b to the variable a. Of course, the expression is illegal ( =b) and will trigger a SYNTAX condition for syntax error {35}. TRL2 defines the operator == as consisting of two tokens. Thus, in the first of these examples, the second token is =, the third token is also =, while the fourth token is b. 3 = 5
This is an assignment of the value 5 to the symbol 3, but since this is not a variable symbol, this is an illegal assignment, and will trigger the SYNTAX condition for syntax error {31}.
« hello » = foo
This is not an invalid assignment, since the first token in the clause is not a symbol. Instead, this becomes a command.
arg =(foo) bar
The fourth statement is a valid assignment, which will space-concatenate the two variable symbols foo and bar, and assign the result to the variable symbol arg. It is specifically not an ARG instruction, even though it might look like one. If you need an ARG instruction which template starts with an absolute indirect positional pattern, use the PARSE UPPER ARG instruction instead, or prepend a dot in front of the template.
An assignment can assign a value to a simple variable, a stem variable or a compound variable. When assigning to a stem variable, all possible variable symbols having that stem are assigned the value. Note specifically that this is not like setting a default, it is a one time multiple assignment.

Example: Multiple assignment
The difference between Rexx’s multiple assignment and a default value can be seen from the following code:
foo. = ‘bar’
foo.1 = ‘baz’
drop foo.1 /* says « FOO.1 » */
say foo.1
Here, the SAY instruction writes out FOO.1, not bar. During the DROP instruction, the variable FOO.1 regains its original, uninitialized value FOO.1, not the value of its stem variable FOO., i.e. bar, because stem assignments does not set up a default.

Example: Emulating a default value
If you want to set the compound variable to the value of its stem variable, if the stem is initialized, then you may use the following code:
if (symbol(‘foo.’)) then
foo.1 = foo.
else
drop foo.1
In this example, the FOO.1 variable is set to the value of its stem if the stem currently is assigned a value. Else, the FOO.1 variable is dropped.
However, this is probably not exactly the same, since the internal storage of the computer is likely to store variables like FOO.2 and FOO.3 only implicitly (after all, it can not explicitly store every compound having FOO. as stem). After the assignment of the value of FOO. to FOO.1, the FOO.1 compound variable is likely to be explicitly stored in the interpreter.
There is no way you can discover the difference, but the effects are often that more memory is used, and some functionality that dumps all variables may dump FOO.1 but not FOO.2 (which is inconsistent). See section RexxVariablePool.
Example: Space considerations
Even more strange are the effects of the following short example:
Although apparently very simple, there is no way that an interpreter can release all memory referring to FOO.1. After all, FOO.1 has a different value than FOO.2, FOO.3, etc., so the interpreter must store information that tells it that FOO.1 has the uninitialized value.
These considerations may seem like nit-picking, but they will matter if you drop lots of compound variables for a stem which has previously received a value. Some programming idioms do this, so be aware. If you can do without assigning to the stem variable, then it is possible for the interpreter to regain all memory used for that stem’s compound variables.

Instructions
In this section, all instructions in standard Rexx are described.
Extensions are listed later in this chapter.
First some notes on the terminology. What is called an instruction in this document is equivalent to a « unit » of clauses. That is, each instruction can consist of one or more clauses. For instance, the SAY instruction is always a single instruction, but the IF instruction is a multi-clause instruction. Consider the following script, where each clause has been boxed:
Further, the THEN or ELSE parts of this instruction might consist of a DO/END pair, in which case the IF instruction might consists of an virtually unlimited number of clauses.
Then, some notes on the syntax diagrams used in the following descriptions of the instructions. The rules applying to these diagrams can be listed as:
• Anything written in courier font in the syntax diagrams indicates that it should occur as-is in the Rexx program. Whenever something is written in italic font, it means that the term should be substituted for another value, expression, or terms.
• Anything contained within matching pairs of square brackets ([…]) are optional, and may be left out.
• Whenever a pair of curly braces is used, it contains two or more subclauses that are separated by the vertical bar (|). It means that the curly braces will be substituted for one of the subclauses it contains.
• Whenever the ellipsis (…) is used, it indicates that the immediately preceding subclauses may be repeated zero or more times. The scope of the ellipsis is limited to the contents of a set of square brackets or curly braces, if it occurs there.
• Whenever the vertical bar | is used in any of the syntax diagrams, it means that either the term to the left, or the term to the right can be used, but not both, and at least one of the must be used. This « operator » is associative (can be used in sequence), and it has lower priority than the square brackets (the scope of the vertical bar located within a pair of square brackets or curly braces is limited to the text within those square brackets or curly braces.
• Whenever a semicolon (;) is used in the syntax diagram, it indicates that a clause separator must be present at the point. It may either be a semicolon character, or an end-of-line.
• Whenever the syntax diagram is spread out over more lines, it means that any of the lines can be used, but that the individual lines are mutually exclusive. Consider the syntax:
Because in the first of these two syntaxes, the SAY part may be continued at either line.
• Sometimes the syntax of an instruction is so complex that parts of the syntax has been extracted, and is shown below in its expanded state. The following is an example of how this looks:
You can generally identify these situations by the fact that they comes a bit below the real syntax diagram, and that they contains a colon character after the name of the term to be expanded.

1 Introduction to Regina
1.1 Purpose of this document
1.2 Implementation
1.3 Ports of Regina
1.4 Executing Rexx programs with Regina
1.4.1 Switches
1.4.2 External Rexx programs
2 Rexx Language Constructs
2.1 Definitions
2.2 Null clauses
2.3 Commands
2.4 Instructions
2.5 Operators
2.6 Special Variables
2.7 Implementation-Specific Information
3 Rexx Built-in Functions
3.1 General Information
3.2 Regina Built-in Functions
3.3 Implementation specific documentation for Regina
3.4 RexxUtil for Regina
4 Conditions
4.1 What are Conditions
4.2 The Mythical Standard Condition
4.3 The Real Conditions
4.4 Further Notes on Conditions
4.5 Conditions in Regina
4.6 Possible Future extensions
5 Stream Input and Output
5.1 Background and Historical Remarks
5.2 Rexx’s Notion of a Stream
5.3 Short Crash-Course
5.4 Naming Streams
5.5 Persistent and Transient Streams
5.6 Opening a Stream
5.7 Closing a Stream
5.8 Character-wise and Line-wise I/O
5.9 Reading and Writing
5.10 Determining the Current Position
5.11 Positioning Within a File
5.12 Errors: Discovery, Handling, and Recovery
5.13 Common Differences and Problems with Stream I/O
6 Extensions
6.1 Why Have Extensions
6.2 Extensions and Standard Rexx
6.3 Specifying Extensions in Regina
6.4 The Trouble Begins
6.5 The Format of the OPTIONS clause
6.6 The Fundamental Extensions
6.7 Meta-extensions
6.8 Semi-standards
6.9 Standards
7 The Stack
7.1 Background and history
7.2 General functionality of the stack
7.3 The interface between Rexx and the stack
7.4 Strategies for implementing stacks
7.5 Implementations of the stack in Regina
8 Interfacing Rexx to other programs
8.1 Overview of functions in SAA
8.2 The Subcommand Handler Interface
8.3 The External Function Handler Interface
8.4 Executing Rexx Code
8.5 Variable Pool Interface
8.6 The System Exit Handler Interface
8.7 The External Queue Interface
8.8 The Macro Space Interface
8.9 Allocating and De-allocating Space
8.10 Calling back into running Rexx Code
9 Implementation Limits
9.1 Why Use Limits?
9.2 What Limits to Choose?
9.3 Required Limits
9.4 Older (Obsolete) Limits
9.5 What the Standard does not Say
9.6 What an Implementation is Allowed to « Ignore »
9.7 Limits in Regina
10 Regina Features and Implementation
10.1 Regina Restricted Mode
10.2 Native Language Support
10.3 Rexx and Regina binaries: Why?
11 Appendixes
11.1 Definitions
11.2 Bibliography
11.3 GNU Free Documentation License