General format for a data-directed data specification, either for input or output, is as follows:
DATA[(data-list)]
General rules:
1. The data list is described in "Data Lists" in this chapter. For input, the data list cannot contain
subscripted names. Names of structure elements in the data list need only have enough qualification to resolve any ambiguity; full qualification is not required. On input, if the stream contains an unrecognisable element-variable or a name that does not have a counterpart in the data list, the NAME condition is raised.
2. Omission of the data list implies that a data list is assumed. This assumed data list contains all the names that are known to the block and to any containing blocks.
140 as PL/I CKT AND OPT LRM PART I
On input, if the stream contains an unrecognisable element-variable or an unknown name, the NAME condition is raised. If the assumed data list contains a name that is not included in the stream, the value of the
associated variable remains unchanged.
On output, all items in the assumed data list are transmitted. Where two or more blocks containing the PUT statement each have declarations of items which have the same name, all the items will be transmitted, the known item appearing first.
3. Recognition of a semicolon or an end-of-file in an input stream causes transmission to cease, whether or not a data list is specified. On output, a semicolon is written into the stream after the last data item transmitted by each PUT statement.
Data-Directed Data in the Stream
The data in the stream associated with data-directed transmission is in the form of a list of element assignments. For problem data, they have the following general format (the optionally signed constants, like the variable names and the equal signs, are in character form):
element-variable
=
data value [{bl,Jelement-variable=
data value] ••• ;General rules for problem data:
1. The element variable may be a
subscripted name. Subscripts must be optionally signed decimal integer constants.
2. On input, the element assignments may be separated by either a blank (~ in the above format) or a comma.
Redundant blanks are ignored. On output, the assignments are separated by a blank. (For PRINT files, items are separated according to program tab settings.)
3. Each data value in the stream has One of the forms described for list-directed transmission.
4. On input a semi-colon following an element assignment terminates the list of element assignments to be
transmitted
by
the execution of a single GET DATA statement, and thereby determines the number of elementaSSignments that are actually
transmitted by a particular statement.
On output a semi-colon is transmitted on completion of a PUT DATA statement.
5. Locator qualifiers cannot appear in the stream. The locator qualifier declared with the based variable is used to establish the generation.
Based variables that have not been declared with a locator qualifier cannot be transmitted.
Under the optimizing compiler, the following restrictions apply to based variables in the data list:
a. The variable must not be based on an OFFSET variable.
b. The variable must not be a member of a structure declared with the REFER option.
c. The pointer on which the variable is based must not be based,
defined, or a parameter, and i t must not be a member of an array or structure.
6. Under the optimizing compiler, defined variables in the data list must not have been defined:
a. On a controlled variable.
b. On an array with one or more adjustable bounds.
c. With a POSITION attribute that specifies other than a constant.
Data-Directed Data Specification for Input
General rules for data-directed input:
1. If the data specification does not include a data list, the names in the stream may be any names known at the point of transmission. Qualified names in the input stream must be fully qualified. The name must not contain mOre than 256 characters.
2. If a data l i s t is used, each element of the data list must be an element, array, or structure variable. Names cannot be subscripted, but qualified names are allowed in the data list.
All names in the stream should appear in the data list; however, the order of the names need not be the same, and the data l i s t may include names that do not appear in the stream. For example, consider the following data
list, where A, B, C, and D are names of element variables:
DATA (B, A,
c,
D)This data list may be associated with the following input data stream:
A= 2.5, B= .0047, D= 125, Z= 'ABC';
Note: C appears in the data l i s t but not in the stream: its value remains unaltered. Z, which is not in the data list, raises the NAME condition.
3. If the data list includes the name of an array, subscripted references to that array may appear in the stream although subscripted names cannot appear in the data list. The entir~
array need not appear in the stream;
only those elements that actually appear in the stream will be assigned.
If a subscript is out of range, or is missing, the NAME condition is raised.
Let X be the name of a two-dimensional array declared as follows:
DECLARE X (2,3);
Consider the following data list and input data stream:
Data Specification Input Data Stream DATA (X) X(l,l)= 7.95,
X(1,2)= 8085, X(1,3)= 73:
Although the data l i s t has only the name of the array, the associated input stream may contain values for individual elements of the array. In this case, only three elements are assigned: the remainder of the array is unchanged.
4. If the data list includes the names of structure elements, then fully
qualified names must appear in the stream, although full qualification is not required in the data list.
Consider the following structures:
DECLARE 1 CARDIN, 2 PARTNO, 2 DESCRP, 2 PRICE, 3 RETAIL, 3 WHSL;
If i t is desired to read a value for CARDIN. PRICE. RETAIL, the data
specification and input data stream could have the following forms:
Data Specification Input Data Stream DATA (CARDIN.RETAIL) CARDIN. PRICE.
RETAIL = 4.28;
Chapter 11: Stream-oriented Transmission 141
5. Interleaved subscripts cannot appear in qualified names in the stream. All subscripts must be moved all the way to the right, following the last name of the qualified name. For example, assume that Y is declared as follows:
DECLARE 1 Y{5,5),2 A(10),3 B, 3 C, 3 D;
An
element name would have to appear in the stream as follows:Y.A.B(2,3,8)= 8.72
The name in the data list could not contain the subscript.
Data-Directed Data Specification for Output
General rules for data-directed output:
1. An element of the data list may be an element, array, or structure variable, or a repetitive specification
involving any of these elements or further repetitive specifications.
Subscripted names can appear. For problem data, the names appearing in the data list, together with their values, are transmitted in the form of a list of element assignments
separated by blanks and terminated by a semicolon. (For PRINT files, items are separated according to program tab settings.)
The rules applying to program control data are given in chapter 15,
"Execution-time Facilities of the Checkout Compiler."
2. Array variables in the data list are treated as a list of the contained subscripted elements in row-major order.
Consider an array declared as follows:
DECLARE X (2,4) FIXED;
If X appears in a data list as follows:
DATA (X)
on output, the output data stream would have the form:
X(l,l)= 1 X(1,2)= 2 X(1,3)= 3 X{1,4)= 4 X(2,1)= 5 X,(2,2)= 6 X(2,3)= 7 X(2,4)= 8;
~ In actual output, more than one
142 OS PL/I CRT AND OPTLRM PART I
blank would follow the equal sign. In conversion from coded arithmetic to character, leading zeros are converted to blanks, and up to three additional blanks may appear at the beginning of the field.
3. Subscript expressions that appear in a data list are evaluated and replaced by their values.
4. Items that are part of a structure appearing in the data l i s t are transmitted with the full
qualification, but subscripts follow the qualified names rather than being interleaved. For example, if ada~a
list is specified for a structur"e element transmitted under data-directed output as follows:
DATA (Y(1,-3).Q)
the associated data field in the output stream is of the form:
Y.Q{1,-3)= 3.756;
5. Structure names in the data list are interpreted as a list of the contained element or elements, and any contained arrays are treated as above.
For example, consider the follOWing structure:
1 A, 2 B, 2 C, 3 D
If a data list for data-directed output is as follows:
DATA (A)
and the values of Band Dare 2 and 17, respectively, the associated data fields in the output stream would be as follows:
A.B= 2 A.C.D= 17;
6. In the following cases, data-directed output is not valid for subsequent data-directed input:
a. When the character-string value of a riumeric character variable does not represent a valid optionally Signed arithmetic constant. For example, this is always true for complex numeric character
variables.
b. When a program control variable is transmitted such a variable must not be specified in an input data list.
r---,
AB: PROCEDURE:Input Stream DECLARE (A(6), B(7» FIXED;
GET FILE (X) DATA (B):
B(l)=l, B(2)=2, B(3)=3,
B(4)=1, BlS)=2, B(6)=3, B(1)=4;
00 I = 1 TO 6:
A (I) = B (1+1) + B (I):
output Stream END:
A(l)= 3 A(2)= S A(3)= 4 A(4)= 3 PUT FILE (Y) DATA (A):
A(S)= S A(6)= 1:
END AB;
L---J
Figure 11.2. Example of data-directed transmission (both input and output)
Length of Data-Directed output Fields
The length of the data field on the external medium is a function of the attributes declared for the variable and, since the name is also included, the length of the fully qualified subscripted name.
The field length for output items converted from coded arithmetic data, numeric
character data, and bit-string data is the same as that for list-directed output data, and is governed by the rules for data conversion to character type as described in section F, "Data Conversion and
Expression Evaluation".
For character-string data, the contents of the character string are written out enclosed in quotation marks. Each quotation mark contained within the character string is represented by two successive quotation marks.
Example
In the example shown in figure 11.2, A is declared as a one-dimensional array of six elements: B is a one-dimensional array of seven elements. The procedure calculates and writes out values for All) = B(I+1) + B(l).