Format of the standardized transfer area

Standardized transfer areas are needed for three purposes:

1. SDF passes an analyzed statement to the program.
   Memory space for at least one such area must be reserved in the program. The space to be allocated must be large enough to accommodate any possible statement input that SDF has analyzed for the program.
   The address of this area is to be entered in the OUTPUT operand of the CMDRST and CMDTST macros, and in the INOUT operand of the CMDCST macro.

2. The program passes semantically incorrect statements back to SDF.
   No special memory space for this need be reserved in the program. The program uses the same area into which SDF had previously written the analyzed statement. After the program has detected semantic errors in the statement, it supplements the statement with information for the semantic error dialog, and returns it to SDF.
   The address of this area is to be specified in the INOUT operand of the CMDCST macro.

3. The program passes values to SDF to replace the specified operand values or the default value. For each statement in which such operand values can appear (see ADD-VALUE..., VALUE=<string>(OVERWRITE-POSSIBLE=*YES),... and ADD-OPERAND..., OVERWRITE-POSSIBLE=*YES) one such area is to be allocated in the program and be supplied with values by the program. The addresses of these areas are to be specified in the DEFAULT operand of the CMDRST and CMDTST macros.

The format of the standardized transfer area has been changed as of SDF V4.1.

The new layout is created using the CMDTA macro and must be used with the new CMDRST, CMDTST and CMDCST macros.

In all three cases, the transfer area has the same formal structure (see Figure 7).

The standardized transfer area begins on a word boundary. The header field is in bytes 0 through 39. It contains, amongst other things, the internal statement name and the statement version (see ADD-STMT ...,INTERNAL-NAME=...,STMT-VERSION=...). The array for operands valid for all statements, i.e. for operands defined with RESULT-OPERAND-LEVEL=1 (see ADD-OPERAND), begins with byte 40. It accommodates an8-byte description for each of these operands. The operand descriptions are arranged in the order resulting from the operand positions established in the statement definition (see ADD-OPERAND ...,RESULT-OPERAND-NAME=*POSITION(POSITION=<integer>)). Each operand description contains, among other things, the absolute address where the associated operand value, or the description of the associated list or non-linearized structure, is stored in the transfer area. The description of a non-linearized structure contains an operand array describing the operands contained in the structure. It has the same format as the array for the operands valid for all statements.

In the simplest case, an operand has only one simple value (see Figure 8). An operand description with a simple value likewise contains the syntax attributes for this value.

If the operand value introduces a structure (Figure 9), there is a structure description for this value. This contains an operand array with descriptions for all operands of the structure, as well as for the operands from linearized substructures. The operand descriptions are arranged in the order resulting from the structure-oriented operand positions established in the statement definition (see ADD-OPERAND...,RESULT-OPERAND-NAME=*POSITION(POSITION=<integer>)).
The operand values corresponding to the operands of the structure may introduce further structures and/or consist of a list of values.

Figure 9: Operand valid for all statements, with structure

Values for operands defined with ADD-OPERAND ...,LIST-POSSIBLE=*YES (...,FORM=*NORMAL) are transferred in the form shown in Figure 10. A structure may be attached to a list element. In this case, “value of the list element” is a structure description.

Header field of a standardized transfer area

Byte	Contents	Source of field contents in case of
		analyzed statement to program	errored statement back to SDF	default values to SDF
0 to 7	Standard header	Program	unchanged	Program
8 to 11	Length of the transfer area	Program	unchanged	Program
12 to 19	Internal name of the statement	SDF	unchanged	Program
20 to 23	Reserved
24 to 26	Version of the statement	SDF	unchanged	Program
27 to 35	Reserved
36 to 37	Number of positions in the operand array	SDF	unchanged	Program
38 to 39	Reserved

The internal name of the statement, the statement version and the number of positions in the operand array are stored in the syntax file in the statement definition (see ADD-STMT...,INTERNAL-NAME=...,MAX-STRUC-OPERAND=...,STMT-VERSION=...).
If the actual number of operands is larger than the value specified in MAX-STRUC-OPERAND, the actual number of operands in the transfer area is registered.

If the program passes default values for a statement, the version of the statement in the transfer area must agree with the version of the statement in the syntax file. If no version is registered in the syntax file, 000 (or binary zeros) must be entered, otherwise the default value will be rejected.

If the program supports several versions of a statement, a default value must be passed for each version.

Description of the operands

The operand array and the descriptions therein for the operands of a structure have exactly the same format as the one for the operands valid for all statements.

Byte	Contents	Source of field contents in case of
		analyzed statement to program	errored statement back to SDF	default values to SDF
0 to 3 0 1 2 3	Value description Additional information Description of type Global syntax attributes Type-specific attributes	See below SDF SDF SDF	See below Unchanged - -	See below Program 1) - -
4 to 7	Absolute address (stored aligned) of the value assigned to the operand or, in the case of structures or lists, of the further description	SDF	unchanged	Program 1)

¹Entry only for operands for which there are values to be converted, i.e. when bit 0 of the additional information is set

Additional information

The additional information is contained in the first byte of the value description. The following specifications regarding the additional information apply regardless of whether the additional information appears in an operand description, in the header field of a structure description, in the description of a list element or in an OR list description.

Bit	Value	Meaning	Source of field contents in case of
			analyzed statement to program	errored statement back to SDF	default values to SDF
0	0	Value not available	SDF 1)	unchanged	Program 2)
0	1	Value available	SDF	unchanged	Program 2)
1	0	Value changeable		Program3)
1	1	Value not changeable		Program3)
2	0	Value not errored		Program
2	1	Value errored		Program
3	0	Value is not to be used as default value			Program
3	1	Value is to be used as default value			Program
4 to 7		Reserved			Program

¹ For example: values for operands defined with ADD-OPERAND..., PRESENCE= *EXTERNAL-ONLY, or values in structures not referenced.
² 0 for operands for which there are neither operand values to be converted nor structures containing operands with values to be converted.
1 for operands for which there are either operand values to be converted or structures containing operands with values to be converted.
³ All list values coming after the first changeable list value are considered changeable by SDF, regardless of whether bit 1 is set. In this way, list elements that have already been processed are protected against being overwritten.

Type description

The type description is contained in the second byte of the value description. The following specifications regarding the type description apply regardless of whether the type description appears in an operand description, in the header field of a structure description, in the description of a list element or in an OR list description.

Structure descriptions can be entered by a program in order to specify local default values. Default values can be entered:

• in the internal format (like the OUTPUT operand in the SDF-A statement ADD-VALUE) or

• in the external format as a string analogous to the operand description. The auxiliary data type <input-text> must be used, and the value is analyzed as if it had been entered via the user interface.

Value (decimal)	Meaning
1	Command rest
2	Integer
4	X-string
5	C-string
6	Name
7	Alphanumeric name
8	Structured name
9	Label
11	File name
12	Partially-qualified file name
13	Time
14	Date
15	Composed name
16	Text
17	Catalog identifier (cat-id)
18	Input text
19	Structure
20	List
21	OR list
22	Keyword
23	Reserved for internal use
24	Volume serial number (VSN)
25	X-text
26	Fixed-point number
27	Device
28	Product version
29	POSIX path name
35	POSIX file name
36	Long-integer

Global syntax attributes

The description of the global syntax attributes of an operand value is found in the third byte of the value description. These are attributes which are specified for several data types (see "ADD-VALUE Define operand value").

Global attributes are always output attributes. They are ignored if the program supplies default values, or in correction dialogs.

Bit	Meaning when the bit is set
0	Value is a wildcard selector
1	Value is a wildcard constructor
2 to 7	Reserved

Syntax attributes specific to data type

The description of the data-specific syntax attributes is found in the fourth byte of the value description. These are attributes which are specified for one data type or for a small number of data types.

Data type-specific attributes are likewise output attributes. They are ignored if the program supplies default values, or in correction dialogs.

Data type FILENAME / PARTIAL-FILENAME:

Bit	Meaning when the bit is set
0	File name contains catalog ID
1	File name contains user ID
2	File name contains file generation or file generation group
3	File name contains version
4	File name is temporary
5 to 7	Reserved

Data type NAME:

Bit	Meaning when the bit is set
0	Name contains underscore (_)
1 to 7	Reserved

Data type COMPOSED-NAME:

Bit	Meaning when the bit is set
0	Composed name contains underscore (_)
1	Composed name contains catalog ID
2 to 7	Reserved

Data type TEXT:

Bit	Meaning when the bit is set
0	Text contains separator
1 to 7	Reserved

Data type X-TEXT:

Bit	Meaning when the bit is set
0	X-TEXT has an odd number of bytes
1 to 7	Reserved

Data type POSIX-PATHNAME / POSIX-FILENAME:

Bit	Meaning when the bit is set
0	POSIX path name of file name is absolute
1	POSIX path name or file name is relative
2	POSIX path name or file name was entered in single quotes
3 to 7	Reserved

Data type C-STRING:

Bit	Meaning when the bit is set
0	C-STRING contains a single quote
1 to 7	Reserved

Data type PRODUCT-VERSION:

Bit	Meaning when the bit is set
0	Product version contains correction status
1	Product version contains release status
2 to 7	Reserved

Header field of a structure description

Byte	Contents	Source of field contents in case of
		analyzed statement to program	errored statement back to SDF	default values to SDF
0 to 1	Number of positions in the operand array	SDF	unchanged	Program
2 to 3	Reserved
4 to 7 4 5 6 7	Value description for the operand value introducing the structure Additional information Type description Global syntax attributes Type-specific syntax attributes	- SDF SDF SDF	see above unchanged - -	see above Program - -
8 to 11	Absolute address (stored aligned) of the operand value introducing the structure	SDF	unchanged	Program

The number of positions in the operand array is stored in the statement definition in the syntax file (see ADD-VALUE...,STRUCTURE=*YES(..,MAX-STRUC-OPERAND=...).

The operand array belonging to the structure begins immediately after the header field (see Figure 9). It has exactly the same format as the one for operands valid for all statements.

List element

Byte	Contents	Source of field contents in case of
		analyzed statement to program	errored statement back to SDF	default values to SDF
0 to 3 0 1 2 3	Value description Additional information Description of type Global syntax attributes Type-specific syntax attributes	see above SDF SDF SDF	see above unchanged - -	see above Program1) - -
4 to 7	Absolute address (stored unaligned) of the value assigned to the list element or, in the case of structures, of the further description	SDF	unchanged	Program
8 to 11	Absolute address (stored aligned) of the next list element	SDF	unchanged	Program

¹ Specified only for operands with operand values to be converted, i.e. when bit 0 of the additional information is set.

In the last element of the list, the “absolute address of the next list element” has the value 0 (see Figure 10).

An OR list consists of a single element. The “absolute address of the next list element” is redundant in this case.

For an operand defined with LIST-POSSIBLE=*YES(FORM=*NORMAL), the number of list elements must be restricted (LIMIT=...) so as to prevent an overflow in the standardized transfer area. The size of a list in the standardized transfer area can be calculated by using the following formula.

n * (10 + 2 + l)
where:	n l	is the number of list elements, and is the length of a single list element (rounded to a multiple of 2).

Example:

ADD-OPERAND ... LIST-POSSIBLE=*YES(LIMIT=100,FORM=*NORMAL)

  ADD-VALUE *NAME(1,8)

A list that is defined in this way can occupy up to 2000 bytes in the standardized transfer area
(100 * (10 + 2 + 8) = 2000).

How values are stored

Byte	Contents	Source of field contents in case of
		analyzed statement to program	errored statement back to SDF	default values to SDF
0 to 1	Length specifications	SDF	unchanged	Program
2 to 3	Reserved	-	-	-
4 to ...	Value	SDF	unchanged	Program

How the values are passed depends on the definition in the syntax file (see ADD-VALUE..., OUTPUT=*NORMAL(...). In this regard, the following points apply:

• A value defined with ADD-VALUE TYPE=*INTEGER(...,OUT-FORM=*BINARY) is stored as a signed four-byte string.

• A value defined with ADD-VALUE TYPE=*TIME is stored as a four-byte string, with 2 bytes (binary) for the hours and one byte each for the minutes and seconds.