Configuration

Any implementation of this standard will be functioning within a configuration. In practice, the boundary between what is implemented especially to support Rexx and what is provided by the system will vary from system to system. This clause describes what they shall together do to provide the configuration for the Rexx language processing which is described in this standard.
We don’t want to add undue « magic » to this section. It seems we will need the concept of a « reference » (equivalent to a machine address) so that this section can at least have composite objects as arguments. (As it already does but these are not Rexx objects) Possibly we could unify « reference » with « variable pool number » since object one-to-one with its variable pool is a fair model. That way we don’t need a new primitive for comparison of two references.
JAVA is only a « reference » for NetRexx so some generalized JAVA-like support is needed for that. It would provide the answers to what classes were in the context, what their method signatures were etc.

Notation

The interface to the configuration is described in terms of functions. The notation for describing the interface functionally uses the name given to the function, followed by any arguments. This does not constrain how a specific implementation provides the function, nor does it imply that the order of arguments is significant for a specific implementation.
The names of the functions are used throughout this standard; the names used for the arguments are used only in this clause and nnn.
The name of a function refers to its usage. A function whose name starts with
– Config_ is used only from the language processor when processing programs;
– API_ is part of the application programming interface and is accessible from programs which are not written in the Rexx language;
– Trap_ is not provided by the language processor but may be invoked by the language processor. As its result, each function shall return a completion Response. This is a string indicating how the function behaved. The completion response may be the character ‘N’ indicating the normal behavior occurred; otherwise the first character is an indicator of a different behavior and the remainder shall be suitable as a human-readable description of the function’s behavior.
This standard defines any additional results from Config_ functions as made available to the language processor in variables. This does not constrain how a particular implementation should return these results.

Notation for completion response and conditions

As alternatives to the normal indicator ‘N’, each function may return a completion response with indicator ‘X’ or ‘S’; other possible indicators are described for each function explicitly. The indicator ‘X’ means that the function failed because resources were exhausted. The indicator ‘S’ shows that the configuration was unable to perform the function.
Certain indicators cause conditions to be raised. The possible raising of these conditions is implicit in the use of the function; it is not shown explicitly when the functions are used in this standard.
The implicit action is
call #Raise ‘SYNTAX’, Message, Description
where:
#Raise raises the condition, see nnn.
Message is determined by the indicator in the completion response. If the indicator is ‘X’ then
Message is 5.1. If the indicator is ‘S’ then Message is 48.1.
Description is the description in the completion response.
The ‘SYNTAX’ condition 5.1 can also be raised by any other activity of the language processor.

Processing initiation

The processing initiation interface consists of a function which the configuration shall provide to invoke the language processor.
We could do REQUIRES in a macro-expansion way by adding an argument to Config_SourceChar to specify the source file. However, I’m assuming we will prefer to recursively « run » each required file. One of the results of that will be the classes and methods made public by that REQUIRES subject.

API_Start

Syntax:
API_Start(How, Source, Environment, Arguments, Streams, Traps, Provides)
where:
How is one of ‘COMMAND’, ‘FUNCTION’, or ‘SUBROUTINE’ and indicates how the program is invoked.
What does OOI say for How when running REQUIREd files?
Source is an identification of the source of the program to be processed.
Environment is the initial value of the environment to be used in processing commands. This has components for the name of the environment and how the input and output of commands is to be directed.
Arguments is the initial argument list to be used in processing. This has components to specify the number of arguments, which arguments are omitted, and the values of arguments that are not omitted.
Streams has components for the default input stream to be used and the default output streams to be used.
Traps is the list of traps to be used in processing (see nnn). This has components to specify whether each trap is omitted or not.
Semantics:
This function starts the execution of a Rexx program.
If the program was terminated due to a RETURN or EXIT instruction without an expression the completion response is ‘N’.
If the program was terminated due to a RETURN or EXIT instruction with an expression the indicator in the completion response is ‘R’ and the description of the completion response is the value of the expression.
If the program was terminated due to an error the indicator in the completion response is ‘E’ and the description in the completion response comprises information about the error that terminated processing.
If How was ‘REQUIRED’ and the completion response was not ‘E’, the Provides argument is set to reference classes made available. See nnn for the semantics of these classes.

Source programs and character sets

The configuration shall provide the ability to access source programs (see nnn).
Source programs consist of characters belonging to the following categories:
– syntactic_characters;
– extra_letters;
– other_blank_characters;
– other_negators;
– other_characters.
A character shall belong to only one category.

Syntactic_characters

The following characters represent the category of characters called syntactic_characters, identified by their names. The glyphs used to represent them in this document are also shown. Syntactic_characters shall be available in every configuration:
– & ampersand;
– ‘ apostrophe, single quotation mark, single quote;
– * asterisk, star;
– blank, space;
– A-Zcapital letters A through Z;
– : colon;
– , comma;
– 0-9digits zero through nine;
– = equal sign;
– ! exclamation point, exclamation mark;
– > greater-than sign;
– – hyphen, minus sign;
– < less-than sign;
– [ left bracket, left square bracket;
– ( left parenthesis;
– % percent sign;
– . period, decimal point, full stop, dot;
– + plus sign;
– ? question mark;
–  » quotation mark, double quote;
– \ reverse slant, reverse solidus, backslash;
– ] right bracket, right square bracket;
– ) right parenthesis;
– ; semicolon;
– / slant, solidus, slash;
– a-zsmall letters a through z;
– ~ tilde, twiddle;
– _ underline, low line, underscore;
– | vertical line, bar, vertical bar.

Extra_letters

A configuration may have a category of characters in source programs called extra_letters. Extra_letters are determined by the configuration.

Other_blank_characters

A configuration may have a category of characters in source programs called other_blank_characters. Other_blank_characters are determined by the configuration. Only the following characters represent possible characters of this category:
– carriage return;
– form feed;
– horizontal tabulation;
– new line;
– vertical tabulation.

Other_negators

A configuration may have a category of characters in source programs called other_negators.
Other_negators are determined by the configuration. Only the following characters represent possible characters of this category. The glyphs used to represent them in this document are also shown:
– ^ circumflex accent, caret;
– ¬ not sign.

Other_characters

A configuration may have a category of characters in source programs called other_characters.
Other_characters are determined by the configuration.

Configuration characters and encoding

The configuration characters and encoding interface consists of functions which the configuration shall provide which are concerned with the encoding of characters. The following functions shall be provided:
– Config_SourceChar;
– Config_OtherBlankCharacters;
– Config_Upper;
– Config_Compare;
– Config_B2C;
– Config_C2B;
– Config_Substr;
– Config_Length;
– Config_Xrange.

Config_SourceChar

Syntax:
Config_SourceChar()
Semantics:
Supply the characters of the source program in sequence, together with the EOL and EOS events. The EOL event represents the end of a line. The EOS event represents the end of the source program. The EOS event must only occur immediately after an EOL event. Either a character or an event is supplied on each invocation, by setting #Outcome.
If this function is unable to supply a character because the source program encoding is incorrect the indicator of the completion response is ‘E’ and the description of the completion information is the encoding which is incorrect, in hexadecimal notation.

Config_OtherBlankCharacters

Syntax:
Config_OtherBlankCharacters()
Semantics:
Get other_blank_characters (see nnn).
Set #Outcome to a string of zero or more distinct characters in arbitrary order. Each character is one that the configuration considers equivalent to the character Blank for the purposes of parsing.

Config_Upper

Syntax:
Config_Upper(Character)
where:
Character is the character to be translated to uppercase.
Semantics:
Translate Character to uppercase. Set #Outcome to the translated character. Characters which have been subject to this translation are referred to as being in uppercase. Config_Upper applied to a character in uppercase must not change the character.

Config_Lower

Syntax:
Config_Lower(Character)
where:
Character is the character to be translated to lowercase.
Semantics:
Translate Character to lowercase. Set #Outcome to the translated character. Characters which have been subject to this translation are referred to as being in lowercase. Config_Lower applied to a character in lowercase must not change the character. Config_Upper of the outcome of Config_Lower(Character) shall be the original character.

Config_Compare

Syntax:
Config_Compare(Character1, Character2)
where:
Character1 is the character to be compared with Character2.
Character2 is the character to be compared with Character1.
Semantics:
Compare two characters. Set #Outcome to
– ‘equal’ if Character1 is equal to Character2;
– ‘greater’ if Character1 is greater than Character2;
– ‘lesser’ if Character1 is less than Character2.
The function shall exhibit the following characteristics. If Config_Compare(a,b) produces
– ‘equal’ then Config_Compare(b,a) produces ‘equal’;
– ‘greater’ then Config_Compare(b,a) produces ‘lesser’;
– ‘lesser’ then Config_Compare(b,a) produces ‘greater’;
– ‘equal’ and Config_Compare(b,c) produces ‘equal’ then Config_Compare(a,c) produces ‘equal’;
– ‘greater’ and Config_Compare(b,c) produces ‘greater’ then Config_Compare(a,c) produces ‘greater’;
– ‘lesser’ and Config_Compare(b,c) produces ‘lesser’ then Config_Compare(a,c) produces ‘lesser’;
– ‘equal’ then Config_Compare(a,c) and Config_Compare(b,c) produce the same value.
Syntactic characters which are different characters shall not compare equal by Config_Compare, see nnn.

Config_B2C

Syntax:
Config_B2C(Binary)
where:
Binary is a sequence of digits, each ‘0’ or ‘1’. The number of digits shall be a multiple of eight.
Semantics:
Translate Binary to a coded string. Set #Outcome to the resulting string. The string may, or may not, correspond to a sequence of characters.

Config_C2B

Syntax:
Config_C2B(String)
where:
String is a string.
Semantics:
Translate String to a sequence of digits, each ‘0’ or ‘1’. Set #Outcome to the result. This function is the inverse of Config_B2C.

Config_Substr

Syntax:
Config_Substr(String, n)
where:
String is a string.
n is an integer identifying a position within String.
Semantics:
Copy the n-th character from String. The leftmost character is the first character. Set #Outcome to the resulting character.
If this function is unable to supply a character because there is no n-th character in String the indicator of the completion response is ‘M’.
If this function is unable to supply a character because the encoding of String is incorrect the indicator of the completion response is ‘E’ and the description of the completion information is the encoding which is incorrect, in hexadecimal notation.

Config_Length

Syntax:
Config_Length(String)
where:
String is a string.
Semantics:
Set #Outcome to the length of the string, that is, the number of characters in the string.
If this function is unable to determine a length because the encoding of String is incorrect, the indicator of the completion response is ‘E’ and the description of the completion information is the encoding which is incorrect, in hexadecimal notation.

Config_Xrange

Syntax:
Config_Xrange(Character1, Character2)
where:
Character1 is the null string, or a single character.
Character2 is the null string, or a single character.
Semantics:
If Character1 is the null string then let LowBound be a lowest ranked character in the character set according to the ranking order provided by Config_Compare; otherwise let LowBound be Character1. If Character2 is the null string then let HighBound be a highest ranked character in the character set according to the ranking order provided by Config_Compare; otherwise let HighBound be Character2If #Outcome after Config_Compare(LowBound,HighBound) has a value of
– ‘equal’ then #Outcome is set to LowBound;
– ‘lesser’ then #Outcome is set to the sequence of characters between LowBound and HighBound inclusively, in ranking order;
– ‘greater’ then #Outcome is set to the sequence of characters HighBound and larger, in ranking order, followed by the sequence of characters LowBound and smaller, in ranking order.

0 Introduction
History
Purpose
Foreword
5.14 Variable pool
5.13 Traps
5.12.14 Config_Options
5.12.13 Config_Random_Next
5.12.12 Config_Random_Seed
5.12.11 Config_Time
5.12.10 Config_NoSource
5.12.9 Config_Halt_Reset
5.12.8 Config_Halt_Query
5.12.7 Config_Termination
5.12.6 Config_Initialization
5.12.5 Config_Default_Output
5.12.4 Config_Default_Input
5.12.3 Config_Trace_Output
5.12.2 Config_Trace_Input
5.12.1 Config_Trace_Query
5.12 Configuration routines
5.11.1 Config_Constants
5.11 Configuration characteristics
5.10.2 Config_Set
5.10.1 Config_Get
5.10 External variable pools
5.9 Streams
5.8 External data queue
5.7.2 Config_ExternalMethod
5.7.1 Config_ExternalRoutine
5.7 External routines
5.6.1 Config_Command
5.6 Commands
5.5.6 Config_Array_Remove
5.5.5 Config_Array_Hasindex
7.1.5 Var_Expose
7.1.4 Var_Drop
7.1.3 Var_Value
7.1.2 Var_Set
7.1.1 Var_Empty
7.1 Variables
7 Evaluation
6.3 Syntactic equivalence
6.2 Replacement of insertions
6.1.6.1 Error message prefix
6.1.6 Creation of messages
6.1.5 Choice of messages
6.1.4 Nested IF instructions
6.1.3 Clauses and line numbers
6.1.2 Trace-only labels
6.1.1 VAR_SYMBOL matching
6.1 Syntactic information
6.3.2 Syntax level
6.3.1 Syntax elements
6.3 Syntax
6 Syntax constructs
9.5.8 DROP
9.5.7 DO loop tracing
9.5.6 DO
9.5.5 Command to the configuration
9.5.4 CALL
9.5.3 Assignment
9.5.2 ARG
9.5.1 ADDRESS
9.5 Instruction
9.4 Clause termination
9.3 Clause initialization
9.2 Routine initialization
9.1 Method initialization
9 Instructions
8.6 ROUTINE
8.5 METHOD
8.4 CLASS
8.3 REQUIRES
8.2.1 Program initialization and message texts
8.2 Initializing
8.1 Notation
8 Directives
7.1.1 Use of Config_ExternalRoutine
7.5.6 The value of a message term
7.5.5 The value of a method
7.5.4 The value of a function
7.5.3 The value of a label
7.5.2 Evaluation of arguments
7.5.1 Invocation
7.5 Functions
7.4.10 Arithmetic operations
7.4.9 The value of an expression
7.4.8 The value of an and_expression
7.4.7 The value of a comparison
7.4.6 The value of a concatenation
7.4.5 The value of an addition
7.4.4 The value of a multiplication
7.4.3 The value of a power_expression
7.4.2 The value of a prefix_expression
7.4.1 The value of a term
7.4 Expressions and operators
7.3.2 Value of a reserved symbol
7.3.1 Derived names
7.3 Value of a variable
7.2 Symbols
7.1.6 Var_Reset
10.1.4 CHANGESTR
10.1.3 CENTRE
10.1.2 CENTER
10.1.1 ABBREV
10.1 Character built-in functions
10.2.2 Raising the SYNTAX condition
10.2.1 Radix conversion
10.2.2 Date calculations
10.2.1 Argument checking
10.2 Routines used by built-in functions
10.1 Notation
10 Built-in functions
9.6.2 Messages during execution
9.6.1 Raising of conditions
9.6 Conditions and Messages
9.5.36 USE
9.5.35 Trace output
9.5.34 TRACE
9.5.33 SIGNAL
9.5.32 SELECT
9.5.31 SAY
9.5.30 RETURN
9.5.29 REPLY
9.5.28 RAISE
9.5.27 QUEUE
9.5.26 PUSH
9.5.25 PULL
9.5.24 PROCEDURE
9.5.23 PARSE
9.5.22 OPTIONS
9.5.21.3 NUMERIC FUZZ
9.5.21.2 NUMERIC FORM
9.5.21.1 NUMERIC DIGITS
9.5.21 NUMERIC
9.5.20 NOP
9.5.19 LOOP
9.5.18 Message term
9.5.17 LEAVE
9.5.16 Execution of labels
9.5.15 ITERATE
9.5.14 INTERPRET
9.5.13 IF
9.5.12 GUARD
9.5.11 FORWARD
9.5.10 EXPOSE
9.5.9 EXIT
12 Provided classes
11.5 The message class
11.4 The supplier class
11.3.1 The array class
11.3 The string class
11.2.3 The method class
11.2.2 The class class
11.2.1 The object class
11.2 Object, class and method
11.1 Notation
11 Built-in classes
10.6.5 VALUE
10.6.4 TIME
Bibliography