Complex variables are variables that are made up of several elements. These elements can be addressed by means of the common variable name, i.e. the name of the complex variable.
Complex variables must generally be declared explicitly with the DECLARE-VARIABLE command. The particular operands of the DECLARE-VARIABLE command that must be used for declaration depend on whether the complex variable is a list, an array or a structure.
Arrays and lists are declared using the operand MULTIPLE-ELEMENTS = *ARRAY(...)/*LIST(...).
There are also some commands (such as SHOW-VARIABLE or EXECUTE-CMD) which implicitly create lists. Structures are declared using the operand TYPE = *STRUCTURE of the DECLARE-VARIABLE command (for this reason, structures are also known as variables with the data type STRUCTURE). The three types of complex variables are described below.
Lists
Lists are also known as list variables; this term is used particularly when there is a risk of confusing them with SDF lists (an SDF list is a string which is interpreted in accordance with the syntax rules for operand lists in commands).
Lists in SDF-P are complex variables whose elements all have the same data type. List elements can be accessed either sequentially or directly.
List elements can either be simple variables or complex variables of the type structure.
Lists have only a “relative” element name at the user interface. To generate this, the # character is appended to the list name, followed by the number of the element. The element number is the result of the sequence of elements in the list. The first list element (the list header) is always element number 1 (<name>#1). The other list elements are numbered consecutively, beginning with this list header. The element number may be omitted when addressing the list header (<name>#).
Lists can be processed sequentially in FOR loops: if the current list element contains a valid value, the FOR loop is executed. The loop is repeated until the list has been processed (for details of FOR loops, see section “Defining loops”).
List declaration
Lists are explicitly declared by means of the operand MULTIPLE-ELEMENTS = *LIST(...) in the DECLARE-VARIABLE command. The variable attributes declared in this apply for all the elements in the list.
Lists can be implicitly and dynamically extended in the SET-VARIABLE command, by appending a new element at the beginning or end of the list. However, it should be noted that there must be no gaps in the sequence of list elements.
If a restriction is to be put on the number of list elements, this must be effected by means of the LIMIT operand in the DECLARE-VARIABLE command.
Releasing a list
A single list element or a contiguous section of list elements can be released. After releasing the elements, the numbering for the list is updates so that numbering starts at 1 and continues without any gaps.
Example
/DECLARE-VARIABLE L,MULTIPLE-ELEMENTS=*LIST
/L=*STRING-TO-VAR('(1,2,3,4,5,6,7,8)')
/SHOW-VARIABLE L,LIST-INDEX-NUMBER=*YES
L#1 = 1
L#2 = 2
L#3 = 3
L#4 = 4
L#5 = 5
L#6 = 6
L#7 = 7
L#8 = 8
/FREE-VARIABLE L#3
/SHOW-VARIABLE L,LIST-INDEX-NUMBER=*YES
L#1 = 1
L#2 = 2
L#3 = 4
L#4 = 5
L#5 = 6
L#6 = 7
L#7 = 8
/FREE-VARIABLE *LIST(LIST-NAME=L,FROM-INDEX=4),NUMBER-OF-ELEMENTS=3)
/SHOW-VARIABLE L,LIST-INDEX-NUMBER=*YES
L#1 = 1
L#2 = 2
L#3 = 4
L#4 = 8
Outputting a list
It is possible to output individual list elements by means of a FOR loop or using the command /SHOW-VARIABLE <name>#<number>.
Arrays
Arrays are complex variables whose elements are all declared with the same data type.
Array elements can themselves be simple variables or complex variables of the type structure. They can be addressed directly by means of their array element names, which are composed of the array name and an integer array index (see section “Variable names”).
Example 1
ACCOUNT is a simple array and comprises the following elements:
ACCOUNT#-12 ACCOUNT#-1 ACCOUNT#0 ACCOUNT#1 ACCOUNT#2 ACCOUNT#123 ACCOUNT#1234
Example 2
CLIENT is a complex array. The client numbers serve as the index; each array element is a structure containing a client’s address.
CLIENT#123.SURNAME CLIENT#123.FORENAME CLIENT#123.STREET ... CLIENT#358.SURNAME CLIENT#358.FORENAME CLIENT#358.STREET ...
Array declaration
Arrays are declared using the DECLARE-VARIABLE command, with the operand MULTIPLE-ELEMENTS = *ARRAY(...). The other variable attributes declared here apply to all the elements of an array.
Array elements can only be declared implicitly. Explicit declaration of individual elements is not possible.
Arrays are always dynamically extendable. A value range can be defined for the array index by means of the UPPER-BOUND and LOWER-BOUND operands, thus limiting the number of array elements.
Structures
Structures are complex variables whose elements can have different data types and can be accessed directly by means of their alphanumeric element names.
Simple or complex variables of the type list, array or structure can serve as structure elements.
The structure element name is made up of the variable name of the structure and a subname of the SDF data type <structured-name>; these two components are separated by a period (see section “Variable names”).
Structures can be either statically or dynamically extendable, this being specified in the declaration.
Note
Structures play an important part in structured output using structured variable streams. For detailed information, see chapter “S variable streams”.
Example
ADDRESS is a structure in which of the following simple variables are the elements:
ADDRESS.SURNAME ADDRESS.FORENAME ADDRESS.TITLE ADDRESS.HOUSE-NO ADDRESS.STREET ADDRESS.CITY ADDRESS.STATE ADDRESS.ZIP
The structure elements SURNAME, FORENAME, TITLE, STREET, CITY and STATE can be declared with the STRING data type; the structure elements HOUSE-NO and ZIP can be declared with the INTEGER data type.
Structure declarations
Complex variables of the type STRUCTURE are declared using the DECLARE-VARIABLE command, in the NAME operand with TYPE = *STRUCTURE(DEFINITION= ). At this point, it is also determined whether the structure is dynamically extendable or static.
Dynamic structures
A structure is “dynamic” or “dynamically extendable” if the elements are neither declared explicitly by means of a structure layout nor with *BY-SYSCMD.
Dynamic structures are declared explicitly using the DECLARE-VARIABLE command with the operand NAME = ...(TYPE = *STRUCTURE(DEFINITION=*DYNAMIC)).
The elements of dynamic structures can be declared explicitly or implicitly. The setting of the IMPLICIT-DECLARATION operand in the SET-PROCEDURE-OPTIONS command in the procedure head has no effect; it is always possible to declare the elements of dynamic structures implicitly.
Example 1
The dynamic structure DYN-STR is to be declared:
/DECLARE-VARIABLE DYN-STR (TYPE = *STRUCTURE(*DYNAMIC))
An element of this structure is subsequently initialized in an assignment:
/DYN-STR.STR2.ARR#123 = 'ABC'
This assignment yields the following results:
The structure element DYN-STR.STR2 is created as a dynamic structure.
The structure element DYN-STR.STR2.ARR is created as an array with the data type TYPE = *ANY.
The array element DYN-STR.STR2.ARR#123 is created as a simple variable with the data type TYPE = *ANY.
Example 2
/DECLARE-VARIABLE S1 (TYPE = *STRUCTURE(*DYNAMIC))
An element of this structure is initialized in an assignment:
/S1.S2.ARR#1.S3 = 'ABC'
This assignment has the following consequences:
The structure element S1.S2 is created as a dynamic structure.
The structure element S1.S2.ARR is created as an array with the data type TYPE = *STRUCTURE(*DYNAMIC).
The array element S1.S2.ARR#1 is created as a dynamic structure with the data type TYPE = *STRUCTURE(*DYNAMIC).
The structure element S1.S2.ARR#1.S3 is created as a simple variable with the data type TYPE = *ANY.
Example 3
/DECLARE-VARIABLE DYN-STR (TYPE = *STRUCTURE(*DYNAMIC))
/DECLARE-ELEMENT DYN-STR.S.NUMBER(TYPE=*INTEGER)
In this example, the elements are explicitly declared: DYN-STR.S as a dynamic structure and DYN-STR.S.NUMBER as a simple variable with TYPE=*INTEGER.
Example 4
/DECLARE-VARIABLE S1 (TYPE = *STRUCTURE(*DYNAMIC))
/S1#123 = 'ABC' -> Error
The assignment is rejected as errored, since S1 is not declared as an array.
Static structures
Static structures are structures that are not dynamically extendable. A distinction must be made as to whether the static structure was created with *BY-SYSCMD or was defined by means of a structure layout. The section below first introduces the declaration using the structure layout; it then describes the declaration of structures that are used for the output of BS2000 commands.
After the structure declaration has been terminated, no more elements can be added to the structure.
Rules for static structures
Structure declarations must be complete within a procedure, i.e. they must be terminated in the procedure in which they began. This applies to both CALL and INCLUDE procedures.
Declaration blocks can contain control flow commands or procedure calls.
For a procedure call within a structure declaration, the following must be noted:
Procedures may be freely called within a declaration block
If a procedure is called by means of the INCLUDE-PROCEDURE command, the elements that were declared before the call are not visible. Furthermore, no other elements of the interrupted structure can be declared in the INCLUDE procedure.
If an incomplete structure or an incomplete structure layout is accessed in an include procedure, an error occurs.
Abortion of the structure declaration due to end of procedure:
If a procedure is canceled while a structure is being declared, incomplete structures whose scope is PROCEDURE or INCLUDE are automatically deleted and an appropriate warning is issued.
Incomplete structures and structure layouts whose scope is TASK are retained. The structure declaration is implicitly terminated to allow subsequent accessing of the structure or previously declared structure elements. However, no further elements can be declared.
Using *BY-SYSCMD to declare structures
If a static structure is declared with DEFINITION = *BY-SYSCMD, the declaration command for the structure has to be immediately followed by the declaration of the structure elements.
The structure elements must be declared in a structure declaration block. This block is initiated with the BEGIN-STRUCTURE command and terminated with the END-STRUCTURE command. No structure layout name may be specified in the BEGIN-STRUCTURE command.
Consequently, the following steps are required for the declaration:
Declare structure explicitly.
The DECLARE-VARIABLE command must contain the following information:
NAME = variable name
TYPE = *STRUCTURE(DEFINITION = *BY-SYSCMD)Initiate structure declaration block.
The DECLARE-VARIABLE command has to be immediately followed by the BEGIN-STRUCTURE command. The command must not contain a structure layout name (NAME =) or a scope (SCOPE =).
Declare structure elements.
The structure elements must be declared individually by calling the DECLARE-ELEMENT command separately for each one. Structure elements can be declared as simple or complex variables with any data type. If the structure elements are simple variables, they can be initialized with INITIAL-VALUE. All attributes that are not explicitly declared in the DECLARE-ELEMENT command are transferred from the superordinate structure. The NAME operand specifies only the element name and not the structure name.
Terminate structure declaration block.
The declaration block is terminated with the END-STRUCTURE command.
Example 1
Declaration of a structure with simple variables as structure elements:
/DECLARE-VARIABLE M (TYPE = *STRUCTURE(*BY-SYSCMD)) /BEGIN-STRUCTURE / DECLARE-ELEMENT A / DECLARE-ELEMENT B /END-STRUCTURE
Example 2
Declaration of a structure with a complex variable as a structure element:
/DECLARE-VARIABLE M (TYPE = *STRUCTURE(*BY-SYSCMD)) /BEGIN-STRUCTURE / DECLARE-ELEMENT A (TYPE = *STRUCTURE(*BY-SYSCMD)) / BEGIN-STRUCTURE / DECLARE-ELEMENT B / END-STRUCTURE /END-STRUCTURE
The static structure M now exists with the element M.A.B. Since A was also declared as a structure with *BY-SYSCMD, BEGIN-STRUCTURE had to be nested.
Rules for structures with *BY-SYSCMD
The DECLARE-VARIABLE and BEGIN-STRUCTURE commands must be in this order, one after the other.
BEGIN-STRUCTURE must not contain a layout name or a scope.
The structure elements cannot be accessed until the declaration of all elements is terminated. (Exception: the SHOW-VARIABLE command can be used to display the contents of the structure elements at any time.)
Declaring structures with named structure layouts
A structure layout can be regarded as a template with which similar structures are easily created. If a structure layout exists, it can be used in any number of DECLARE-VARIABLE commands; these then generated any number of structures with identical elements.
A “structure layout” is a sequence of SDF-P commands that begins with the BEGIN-STRUCTURE command, followed by DECLARE-ELEMENT commands, and ends with the END-STRUCTURE command.
The individual elements of structures are explicitly declared in these structure layouts. Structure layouts are identified by a unique name. This name must be repeated in the DECLARE-VARIABLE command when the structure is declared.
The individual steps required are thus as follows:
Initiate structure layout (= declaration block for the structure elements)
The structure layout is initiated by the BEGIN-STRUCTURE command.
A name must be specified in the NAME operand (NAME = layout name). This name is used later on to establish a link between the declaration of the variable “variable name” with the type structure in the DECLARE-VARIABLE command and the declaration of the elements of this structure layout.
The structure layout must exist when the DECLARE-VARIABLE command is called.Declare the structure elements
Each layout element is declared individually by a separate call of the DECLARE-ELEMENT command.
The elements can be declared as simple or complex variables of the type LIST, ARRAY or STRUCTURE.
All variable attributes that are not explicitly declared in the DECLARE-ELEMENT command are transferred from the superordinate structure.
Layout elements may not be initialized.Terminate structure layout/declaration block
The END-STRUCTURE command terminates the structure layout.
Declare structure explicitly
In the operand NAME = variablename (TYPE = *STRUCTURE(...)) of the DECLARE-VARIABLE command, a layout name is specified in the parentheses (DEFINITION = layoutname) to establish the link to the previously declared structure layout.
Example
First, structure layout A is declared:
/BEGIN-STRUCTURE A / DECLARE-ELEMENT B / DECLARE-ELEMENT C /END-STRUCTURE
A structure does not yet exist; value assignments are not possible. Afterwards, structures are declared to which structure layout A is to apply:
/DECLARE-VARIABLE KK (TYPE = *STRUCTURE (DEFINITION = A)) /... /DECLARE-VARIABLE CC (TYPE = *STRUCTURE (DEFINITION = A))
Now there are two static structures, KK with the elements KK.B and KK.C, and CC with the elements CC.B and CC.C. These elements can be assigned values at any time.
Rules for structure layouts
When a structure layout is declared, a name must be specified in the initiating BEGIN-STRUCTURE command.
Structure layouts must be declared before the structures.
Each structure layout is available for declaring any number of static structures.
Structure layouts have a separate name space, i.e. variables and structure layouts can have the same name.
Values cannot be assigned to a structure layout. The structure layout is simply a template for subsequent declarations.
Unlike other structure declarations, structure layouts may not be nested; i.e. each declaration block must be terminated with END-STRUCTURE before the next declaration block can be opened with BEGIN-STRUCTURE.
Note
Examples of the declarations of structures, structure layouts and structure elements will also be found under the description of the DECLARE-ELEMENT command on "DECLARE-ELEMENT Declare structure element ".