General format for an edit-directed data specification, either for input or output, is as follows:
EDIT {(data-list) (format-list)}
[(data-list) (format-list)] •••
1. The data list, which must be enclosed in parentheses, is described in "Data Lists", above. The format list, which also must be enclosed in parentheses, contains one or more format items.
There are three types of format items:
data format items, which describe data in the stream: control format items, which describe page, line, and spacing operations; and remote format items, which specify the label of a separate statement that contains the format list to be used. Format lists and format items are discussed in more detail in "Format Lists", below.
~ Program-control variables cannot be specified in data lists for edit-directed transmission.
2. For input, data in the stream is considered to be a continuous string of characters not separated into indiVidual data items. The number of characters for each data item is specified
by
a format item in the format list. The characters are treated according to the associated format item.3. For output, the value of each item in the data l i s t is converted to a format specified
by
the associated format item and placed in the stream in a field whose width also is specified by the format item.4. For either input or output, the first data format item is associated with the first item in the data list, the second data format item with the second item in the data list, and so forth. If a format list contains fewer format items than there are items in the associated data list, the format list is re-used; if there are excessive format items, they are
Chapter 11: Stream-oriented Transmission 143
ignored. Suppose a format l i s t contains five data format items and its associated data list specifies ten items to be transmitted. Then the sixth item in the data list will be associated with the first data format item, and so forth. suppose a format l i s t contains ten data format items and its associated data l i s t specifies only five items. Then the sixth
through the tenth format items will be ignored.
5. An array or structure variable in a data l i s t is equivalent to n items in the data list, where n is the number of element items in the array or structure, each of which will be associated with a separate use of a data format item.
6. If a control format item is
encountered, the control action is executed, and the data list item is paired with the next format item.
7. The specified transmission is complete when the last item in the data l i s t has been processed using its
corresponding format item. Subsequent format items, including control format items, are ignored.
8. On output, data items are not automatically separated, but arithmetic data items generally
include leading blanks because of data conversion rules and zero suppression.
Examples:
GET EDIT (NAME, DATA, SALARY) (A(N), X(2), A(6), F(6,2»;
PUT EDIT ('INVENTORY=' IIINUM,INVCODE) (A,F(5»;
The first example specifies that the first N characters in the stream are to be
treated as a character string and aSSigned to NAME; the next two characters are to be skipped: the next six are to be aSSigned to DATA in character format: and the next six characters are to be considered as an optionally signed decimal fixed-point constant and aSSigned to SALARY.
The second example specifies that the character string 'INVENTORY=' is to be concatenated with the value of INUM and placed in the stream in a field whose width is the length of the resultant string.
Then the value of INVCODE is to be converted to character to represent an optionally signed decimal fixed-point integer constant and is then to be placed in the stream right-adjusted in a field with a width of five characters (leading
144 OS PL/I CRT AND OPT LRM PART I
characters may be blanks). Note that values represented by expressions and constants can appear in output data lists only.
Format Lists
Each edit-directed data specification must be associated with a format list.
General format:
(format-list)
where "format list" is defined as:
[:
item
1
n item •••
n (format-list) item
n item
n (format-list)
Syntax rules:
1. Each "item" represents a format item as described below.
2. The letter n represents an iteration factor, which is either an expression enclosed in parentheses or an unsigned decimal integer constant. If i t is the latter, a blank must separate the constant and the following format item. The iteration factor specifies that the associated format item or format l i s t is to be used n successive times. A zero iteration factor
specifies that the associated format item or format l i s t is to be skipped and not used (the data l i s t item will be associated with the next data format item). If an expression is used to represent the iteration
factor, i t is evaluated and converted to an integer, which must be non-negative, once for each set of iterations. The associated format item or format l i s t is that item or list of items immediately to the right of the iteration factor.
General rule:
There are three types of format items:
data format items, control format items, and the remote format item. Data format items specify the external forms that data fields are to take.' Control format items specify the page, line, column, and spacing operations. The remote format item allows format items to be specified in a separate FORMAT statement elsewhere in the block.
Detailed discussions of the various
types of format items appear in section E, -Edit-Directed Format Items-. The
following discussions show how the format items are used in edit-directed data specifications.
Data Format Items
On input, each data format item
specifies the number of characters to be associated with the data item and how to interpret the external data. The data item is assigned to the associated variable named in the data list, with necessary conversion to conform to the attributes of the variable. On output, the value of the associated element in the data list is converted to the character representation specified by the format item and is
inserted into the data stream.
There are six data format items: fixed-point (F), floating-fixed-point (E), complex (C), picture (P), character-string (A), and bit-string (B). They are, in general,
specified as follows:
F (w[,d[,p]]) E (w,d[,s])
C (real-format-item [,real-format-item]) P 'picture-specification'
A
lew)]
B
lew)]
In this list, the letter ~ represents an expression that specifies the number of characters in the field. The letter d specifies the number of digits to the-right of a decimal point: i t may be omitted for fixed-point integers. The real format item of the complex format item represents the appearance of either an F, E or P format item. The picture specification of the P format item can be either a numeric
character specification or a character-string specification~ On output, data associated with
E
and F format items is rounded i f the internal precision exceeds the external precision.A third specification (E) is allowed in the F format item: i t is a scaling factor.
A third specification (!) is allowed in the E format item to specify the number of digits that must be maintained in the first subfield of the floating-point number.
These specifications are discussed in detail in section E, -Edit-Directed Format Items-.
~ Fixed-point binary and floating-pOint binary data items must always be
represented in the input stream with their
values expressed in decimal digits. The F and E format items may then be used to access them, and the values will be converted to binary representation upon assignment. On output, binary items are converted to decimal values and the
associated F or E format items must state the field width and pOint placement in terms of the converted decimal number.
The following examples illustrate the use of format items:
1. GET FILE (INFILE) EDIT (ITEM) (A(20»:
This statement causes the next 20 characters in the file called INFILE to be assigned to ITEM. The value is automatically transformed from its character representation specified by the format item A(20), to the
representation specified by the attributes declared for ITEM.
Note: If the data list and format l i s t were-used for output, the length of a string item need not be specified in the format item if the field width is to be the same as the length of the string, that is, if no blanks are to follOW the string.
2. PUT FILE (MASKFLE) EDIT (MASK) (B);
Assume MASK has the attribute BIT (25); then the above statement writes the value of MASK in the file called MASKFLE as a string of 25 characters consisting of O's and l ' s . A field width specification can be given in the B format item. It must be stated
for input.
----3. PUT EDIT (TOTAL) (F(6,2»;
Assume TOTAL has the attributes FIXED (4,2); then the above statement specifies that the value of TOTAL is to be converted to the character
representation of a fixed-point number and written into the standard output file SYSPRINT. A decimal point is to be inserted before the last two
numeric characters, and the number will be right-adjusted in a field of six characters. Leading zeros will be changed to blanks, and, if neces~ary,
a minus sign will be placed to the left of the first numeric character.
The conversion from internal decimal fixed-point type to character type is performed according to the normal rules for conversion. Extra characters may appear as blanks
preceding the number in the converted string. And, since leading zeros are converted to blanks, additional blanks
Chapter 11: Stream-oriented Transmission 145
may precede the number. If a decimal point or a minus sign appears, either will cause one leading blank to be replaced.
In edit-directed output, the field width specification in the format item
(in this case, the 6 in the F(6,2) format item) can be used to truncate leading zeros. In this specification, one zero is truncated. TOTAL would be converted to a character string of length seven. If all four digits of the converted number are greater than zero, the number, with its inserted decimal point, will require five digit positions; i f the number is negative, another digit position will be
required for the minus Sign.
Consequently, the F(6,2) specification will always allow all digits, the point, and a possible sign to appear, but will remove the extra blank by truncation.
4. GET FILE(A) EDIT (ESTIMATE) (E(10,6»;
This statement obtains the next ten characters from the file called A and interprets them as a floating-point decimal number. A decimal point is assumed before the rightmost six digits of the mantissa. An actual point within the data can override this assumption. The value of the number is converted to the attributes of ESTIMATE and assigned to this variable.
5. GET EDIT (NAME, TOTAL)
(P'AAAAA',P'9999');
When this statement is executed, the standard input file SYSIN is assumed.
The first five characters must be alphabetic or blank and they are assigned to NAME. The next four characters must be nonblank numeric characters and they are assigned to TOTAL.
Control Format Items
The control format items are the spacing format item (X), and the COLUMN, LINE, PAGE, and SKIP format items. The spacing format item specifies relative spacing in the data stream. The PAGE and LINE format items can be used only with PRINT files and, consequently, can only appear in POT statements. All but PAGE generally include expressions. LINE, PAGE, and SKIP can also appear separately as options in the PUT statement; SKIP can appear as an option in the GET statement. The following examples illustrate the use of the control format items:
146 OS PL/I CRT AND OPT LRM PART I
1. GET EDIT (NUMBER, REBATE) (A(S), xeS), A(S»;
This statement treats the next 15 characters from the standard input file, SYSIN, as follows: the first five characters are assigned to NUMBER, the next five characters are spaced over and ignored, and the
remaining five characters are assigned to REBATE.
2. GET FILE(IN) EDIT (MAN, OVERTIME)
(SKIP(l), A(6), COLUMN(60), F(4,2»;
This statement positions the data set aSSOCiated with file IN to a new line;
the first six characters on the line are assigned to MAN, and the four characters beginning at character position 60 are assigned to OVERTIME.
3. PUT FILE (OUT) EDIT (PART, COUNT) (A(4), X(2), F(S»;
This statement places in the file named OUT four characters that
represent the value of PART, then two blank characters, and finally five characters that represent the fixed-point value of COUNT.
4. The'following examples show the use of the COLUMN, LINE, PAGE, and SKIP
format items in combination with one another.
PUT EDIT ('QUARTERLY STATEMENT') (PAGE, LINE(2), A(19»;
PUT EDIT
CACCT#, BOUGHT, SOLD, PAYMENT, BALANCE)
(SKIP(3), A(6), COLUMN(14), F(1,2), COLUMN(30), F(1,2), COLUMN(45), F(1,2),
COLUMN(60), F(1,2»;
The first PUT statement specifies that the heading QUARTERLY STATEMENT is to be written on line two of a new page in the standard output file SYSPRINT.
The second statement specifies that two lines are to be skipped (that is, wskip to the third following lineW)
and the value of ACCT# is to be written, beginning at the first
character of the fifth line; the value of BOUGHT, beginning at character position 14; the value of SOLD, beginning at character position 30;
the value of PAYMENT, beginning at character position 45; and the value of BALANCE at character position 60.
Note: Control format items are executed at
~ime they are encountered in the format list. Any control format l i s t that appears after the data list is exhausted will have