Input and Output

The LINESIZE option specifies the maximum number of characters that can be output on a single line when the PUT statement writes data to a file with the STREAM and OUTPUT attributes. The format of the LINESIZE option is:

LINESIZE(expression)

The PAGESIZE option is used in the OPEN statement to specify the maximum number of lines that can be written to a print file without signaling the ENDPAGE condition. The format of the PAGESIZE option is:

PAGESIZE(expression)

The TITLE option is specified in an OPEN statement to designate the external file specification of the file to be associated with the PL/I file. The TITLE option is specified only on the OPEN statement for a file. Its format is as follows:

TITLE(expression)

GET EDIT (FIRST,MID_INITIAL,LAST) (A(12),A(1),A(20));

This statement reads the next 12 characters from the default stream input file (SYSIN) and assigns the string to FIRST. It then reads the next character into MID_INITIAL, and then the next 20 characters into LAST.

GET EDIT (SOCIAL_SECURITY) (A(12))
       FILE (SOCIAL) SKIP (12);

This statement opens the stream file SOCIAL if the file was closed, advances 12 lines, reads the first 12 characters of the line, and assigns the characters to the variable SOCIAL_SECURITY.

GET EDIT (N, (A(I) DO I=1 TO N))
       (F(4),SKIP,100 F(10,5));

where the dimension of A is less than or equal to 100. This reads the value of N from the input stream using the format item F(4). The process then skips to the next line (record). It reads N elements into the array A, using the format item F(10,5) for each element.

GET EDIT (NAME.FIRST,NAME.LAST)
       (A(10),X(3),A(20))
       STRING('Philip    A. Rothberg            ');

This statement assigns `Philip ' to the structure member NAME.FIRST, skips the middle initial, period, and space, and assigns `Rothberg ' to NAME.LAST.

The items to be read into the input targets are separated by a space or a single comma. Multiple spaces are treated as a single space, and a comma can be surrounded by spaces. The following rules apply:

isn't or 'isn''t'

GETS: PROCEDURE OPTIONS(MAIN);

DECLARE NAME CHARACTER(80) VARYING;
DECLARE AGE FIXED;
DECLARE (WEIGHT,HEIGHT) FIXED DECIMAL(5,2);
DECLARE SALARY PICTURE '$$$$$$V.$$';
DECLARE DOSAGE FLOAT;

DECLARE INFILE STREAM INPUT FILE;
DECLARE OUTFILE PRINT FILE;

GET FILE(INFILE)
       LIST(NAME,AGE,WEIGHT,HEIGHT,SALARY,DOSAGE);
PUT FILE(OUTFILE)
       LIST(NAME,AGE,WEIGHT,HEIGHT,SALARY,DOSAGE);
END GETS;

If the file INFILE.DAT contains the following data:

'Thomas R. Dooley',33,150.60,5.87,15000.50,4E-6,

then the program GETS writes the following output to OUTFILE.DAT:

Thomas R. Dooley 33 150.60 5.87 $15000.50 4.0000000E-06

In the input file (INFILE.DAT), the string `Thomas R. Dooley' is surrounded by apostrophes so PL/I will not interpret the spaces between words as field separators.

GSTR: PROCEDURE OPTIONS(MAIN);

DECLARE STREXP CHARACTER(80) VARYING;
DECLARE (A,B,C,D,E) FIXED;
DECLARE OUTFILE STREAM OUTPUT FILE;

OPEN FILE(OUTFILE) TITLE('GSTR.OUT');
STREXP = '1,2,3,4,5';
GET STRING(STREXP) LIST(A,B,C,D,E);
PUT FILE(OUTFILE) LIST(A,B,C,D,E);
END GSTR;

The program GSTR writes the following output to GSTR.OUT:

1       2       3       4       5

For other examples, see Section 9.2.6, “Terminal I/O”.

PUT_ED: PROCEDURE OPTIONS(MAIN);

       DECLARE SOURCE FIXED DECIMAL(7,2);
       DECLARE OUTFILE PRINT FILE;

       OPEN FILE(OUTFILE) TITLE('PUT_ED.OUT');

       SOURCE = 12345.67;

       PUT SKIP FILE(OUTFILE) EDIT(SOURCE) (F(8,2));
       PUT SKIP FILE(OUTFILE) EDIT(SOURCE) (E(13));
       PUT SKIP FILE(OUTFILE) EDIT(SOURCE) (A);
       PUT SKIP FILE(OUTFILE) EDIT('American: ',SOURCE)
               (A,P'ZZ,ZZZV.ZZ');
       PUT SKIP FILE(OUTFILE) EDIT('European: ',SOURCE)
               (A,P'ZZ.ZZZV,ZZ');

END PUT_ED;

The program PUT_ED writes the following output to PUT_ED.OUT:

12345.67
       1.234567E+04
       12345.67
American: 12,345.67
European: 12.345,67

PUTL: PROCEDURE OPTIONS(MAIN);

DECLARE I FIXED BINARY,
       F FLOAT,
       P PICTURE '99V.99',
       S CHAR(10);

DECLARE INFILE STREAM INPUT FILE;
DECLARE OUTFILE PRINT FILE;

OPEN FILE(INFILE) TITLE('PUTL.IN');
OPEN FILE(OUTFILE) TITLE('PUTL.OUT');

GET FILE(INFILE) LIST (I,F,P,S);
PUT FILE(OUTFILE) SKIP LIST (I,F,P,S);

END PUTL;

Assume that the file PUTL.IN contains the following data:

2,3.54,22.33,'A string'

Then the program PUTL writes the following output to PUTL.OUT:

2       3.5400000E+00   22.33   A string

For print files, each output item is written at the next tab position. Floating-point values are represented in floating-point notation. Character values are not enclosed in apostrophes.

PUT FILE(REPORT) PAGE SKIP LINE(2);

The PUT statement advances the file REPORT to the beginning of the next page, advances to line 2, and skips to the beginning of the next line (3).

The value w must be included when the A format item is used with GET EDIT. If w has a positive value, a character-string value comprising the next w characters in the input stream is acquired and assigned to the input variable.

The acquired character string is converted, if necessary, to the data type of the input target, following the PL/I data conversion rules. Apostrophes should enclose the stream data only if the apostrophes are intended to be acquired as part of the data.

The output source associated with an A format item is converted, if necessary, to a string of characters. The result is assigned to a string of w characters, which are placed in the output stream. If w is omitted, the length of the output string equals the length of the converted output source. If w is zero, the A format item and the associated output source are skipped.

Output strings are not surrounded automatically by apostrophes. The converted output source is truncated or appended with trailing spaces, according to the value of w. The conversion of a computational data item to a character string is performed following the PL/I data conversion rules (see Section 6.4, “Data Type Conversion of Operands and Expressions”).

Table 9.4, “Input String Formatting” and Table 9.5, “Output String Formatting” show the relationship between the internal and external representations of characters that are read or written with the A format item.

In Table 9.4, “Input String Formatting”, the input stream is a field of characters beginning at the current position in the stream and continuing to the right. The # character signifies a space. The target type is the type of the variable to which the input value is assigned.

In Table 9.5, “Output String Formatting”, the output source value is either a constant or the value of a variable that is written with the associated format item.

The value w must be included when the B format items are used with GET EDIT. The number of characters specified by w is acquired. The input characters are converted to an intermediate bit string of length w*m. If the input target is not a bit-string variable, then this intermediate bit string is converted to the type of the input target, following the PL/I conversion rules (for details, see Section 6.4, “Data Type Conversion of Operands and Expressions”).

The string of characters in the stream can be preceded or followed by spaces, which are ignored. All characters in the input field (except any leading and trailing spaces) must be those implied by the radix factor; otherwise, a CONVERSION condition is signaled. Consequently, input strings should not be enclosed in apostrophes and should not include the suffix Bm.

The output source is converted, if necessary, to a bit string, following the PL/I rules for converting data to bit strings (see Section 6.4, “Data Type Conversion of Operands and Expressions”). If the length of the resulting bit string is not a multiple of the radix factor (m), the bit string is padded with zeros on the right to make its length the next higher multiple.

The bit string is then converted to a character representation appropriate to the radix factor and placed in the output stream. The character representation is left- justified in the field specified by w and truncated or padded with spaces on the right if necessary. If w is unspecified, the output string length is equal to the converted output source. If w is zero, the B format item and its associated output source are skipped.

BFORMAT_XM: PROCEDURE OPTIONS(MAIN);
/* This program prints incorrect values for an integer */
DECLARE I FIXED BINARY(31);
DECLARE BFORM STREAM OUTPUT PRINT FILE;
I = 5;
OPEN FILE(BFORM) TITLE('BFORMXM.OUT');
PUT SKIP FILE(BFORM) EDIT ('Decimal:',I) (A,X,F(2));
PUT SKIP FILE(BFORM) EDIT ('Binary:',I) (A,X,B);
PUT SKIP FILE(BFORM) EDIT ('Base 4:',I) (A,X,B2);
PUT SKIP FILE(BFORM) EDIT ('Octal:',I) (A,X,B3);
PUT SKIP FILE(BFORM) EDIT ('Hexadecimal:',I) (A,X,B4);
END BFORMAT_XM;

This program produces the following output:

Decimal: 5
Binary: 0000000000000000000000000000101
Base 4: 0000000000000022
Octal: 00000000024
Hexadecimal: 0000000A

The base 4, octal, and hexadecimal representations of I are incorrect because the precision of I (31) is not a multiple of 2, 3, or 4. For the B2 and B4 format items, an extra zero bit was appended to the intermediate bit string, in effect multiplying the value of the string by 2. For B3, two extra bits were appended to make the string 33 bits long and thus divisible into an exact number of 3-bit segments. To avoid this problem, the precision of the output source must be a number that is evenly divisible by any radix factor with which it is to be written out, as in the following example:

BFORMAT_XM: PROCEDURE OPTIONS(MAIN);

/* This program prints correct values for an integer */
       DECLARE I FIXED BINARY(24);
       /* 24 is a multiple of 2*3*4 */
       DECLARE BFORM STREAM OUTPUT PRINT FILE;

       I = 5;
       OPEN FILE(BFORM) TITLE('BFORMXM5.OUT');

       PUT SKIP FILE(BFORM) EDIT ('Decimal:',I) (A,X,F(2));
       PUT SKIP FILE(BFORM) EDIT ('Binary:',I) (A,X,B);
       PUT SKIP FILE(BFORM) EDIT ('Base 4:',I) (A,X,B2);
       PUT SKIP FILE(BFORM) EDIT ('Octal:',I) (A,X,B3);
       PUT SKIP FILE(BFORM) EDIT ('Hexadecimal:',I) (A,X,B4);

END BFORMAT_XM;

This version of the program produces the following output:

Decimal: 5
Binary: 000000000000000000000101
Base 4: 000000000011
Octal: 00000005
Hexadecimal: 000005

The output values are correct representations of I because the precision (24) is evenly divisible by 2, 3, or 4.

The tables below show the relationship between the internal and external representations of characters that are read or written with the B format item.

In Table 9.6, “Input with the B Format Item”, the input stream is a field of characters beginning at the current position in the stream and continuing to the right. The # characters signify spaces. The target type is the type of the variable to which the input value is assigned.

In Table 9.7, “Output with the B Format Item”, the output source is either a constant or the value of a variable written out with the associated format item.

The file is positioned at the column specified by w. Characters between the beginning of the line and this column are ignored. If the file is already positioned beyond the specified column, the remainder of the line is skipped and the format item is applied to the next line.

The file is positioned at the column specified by w. Within the current line, positions between the wth column and the position of the last output data are filled with spaces.

If the file is already positioned beyond the specified column, the format item is applied to the next line. If w exceeds the line size, a value of 1 is assumed. See Section 9.1, “Opening and Closing Files”.

COL: PROCEDURE OPTIONS(MAIN);

       DECLARE IN STREAM INPUT FILE;
       DECLARE OUT STREAM OUTPUT FILE;
       DECLARE LETTER CHARACTER(1);

       PUT FILE(OUT) SKIP
               EDIT('123456789012345678901234567890') (A);
       PUT FILE(OUT) SKIP
               EDIT('COL1','COL28') (A,COL(28),A);

       GET FILE(IN) EDIT (LETTER) (A(1));
       PUT FILE(OUT) SKIP(2)
               LIST('Letter in column 1:',LETTER);

       GET FILE(IN)
               EDIT (LETTER) (COL(25),A(1));
       PUT FILE(OUT) SKIP
               LIST ('Letter in column 25:',LETTER);

END COL;

If the stream input file IN.DAT contains the following text:

ABCDEFGHIJKLMNOPQRSTUVWXYZ

then the program COL writes the following output to the stream output file OUT.DAT:

123456789012345678901234567890
COL1                       COL28
'Letter in column 1:' 'A'
'Letter in column 25:' 'Y'

Used with GET EDIT, the E format item acquires a character-string value representing a floating-point decimal value and assigns it, with necessary conversions, to an input target of any computational type. If w is zero, no operation is performed on the input stream, and a null character string is converted and assigned to the input target.

For input, floating-point values can be represented in the stream in the forms listed in Table 9.8, “Representation of Floating-Point Values”.

The mantissa is a fixed-point decimal constant, the sign is a plus (+) or minus (-) symbol, and the exponent is a decimal integer. A zero exponent is assumed if both the letter E and the exponent are omitted.

If, on input, the mantissa includes a decimal point, it overrides the specification of d. If no decimal point is included, then d specifies the number of fractional digits.

The value of w should be large enough to include the mantissa, the optional decimal point in the mantissa, the signs on the exponent and mantissa, the optional letter E, and the exponent. If the field width is too narrow, the stream representation is truncated on the right; if the field width is too wide, excess characters are acquired on the right and may contain invalid input.

Spaces can precede or follow the value in the stream and are ignored. If the entire field contains spaces, zero is assigned to the input target. If the stream representation is not one of the acceptable forms, an ERROR condition is signaled.

Used in a PUT EDIT statement, the E format item converts an output source of any computational type to the following form for representation in the stream:

[-] digit . [fractional-digits] E sign exponent

Typical representations are as follows:

1.E+07
3.33E-10
-2.7186E+00

If d is omitted from the format item, then d = s -1, where s is the precision of the output source expressed in decimal. The decimal value is rounded before being written out.

The exponent is ordinarily a 2-digit decimal integer (for S_floating data) or a 3-digit decimal integer (for T_floating data) and is always signed. The exponent is adjusted so that the first digit of the mantissa is not zero, except that the value 0 is represented as:

0.0000 ... E+00

with a number of zeros to the right of the decimal point equal to the specified number of fractional digits.

To account for negative values with fractional digits, the specified width integer should be 7 greater than the number of digits to be represented in the mantissa: one character for the preceding minus sign, one for the decimal point in the mantissa, one for the letter E, one for the sign of the exponent, and two (or three) for the exponent itself.

If the number's representation is shorter than the specified field, the representation is right-justified in the field and the number is extended on the left with spaces.

If the field specified by w is too narrow, an ERROR condition is signaled.

The next tables show the relationship between the internal and external representations of numbers that are read or written with the E format item.

Table 9.9, “Input with the E Format Item” shows an input stream that is a field of characters beginning at the current position in the stream and continuing to the right. The target type is the type of the variable to which the input value is assigned.

Used with GET EDIT, the F format item acquires a fixed-point decimal value from the next w characters in the stream and converts it to an input target of any computational type. Fixed-point decimal values can be represented in the stream in the following forms:

number
sign number

The number is a fixed-point decimal constant, and the sign is a plus (+) or minus (-) symbol.

The following are valid representations:

124333

-123333

-123.

A CONVERSION condition is signaled if the field is not blank and does not contain a valid representation; otherwise, the fixed-point decimal number is extracted from the field and is assigned to the input target, with any necessary conversions. A decimal point included in the number overrides the specification of d. If no decimal point is included, d specifies the number of fractional digits. If d is omitted, it is assumed to be zero.

The value w should be only large enough to include the number, the optional decimal point in the number, and the optional sign. If w is too small, the stream representation is truncated on the right. If w is too large, extra characters, which might include invalid syntax, are acquired.

If w is zero, a null character string is converted and assigned to the input target, and no operation is performed on the stream.

Spaces can precede or follow the number in the stream and are ignored. If the entire string contains spaces or is a null string, the fixed-point decimal constant 0 is converted and assigned to the input target.

Used in a PUT EDIT statement, the F format item converts an output source of any computational type to one of the following forms for representation in the stream:

integer
integer.fractional-digits
-integer.fractional-digits

Typical representations are:

3234
0.23432
3.33
-3234.33

The decimal value is rounded before being written out. If d is omitted from the format item, the decimal point is not shown, and only the integral part of the number is shown.

If d is larger than the number of fractional digits to be output, trailing zeros are appended to the output number. All leading zeros to the left of the decimal point are suppressed unless the integral part of the number is zero, in which case one zero appears to the left of the decimal point.

To account for negative values with fractional digits, the specified width integer should be 2 greater than the number of digits to be represented: one character for the preceding minus sign and one for the decimal point in the number.

If the number's representation is shorter than the specified field, the representation is right-justified in the field, and the number is extended on the left with spaces.

If the field is too narrow to represent the integral portion of the output number, an ERROR condition is signaled.

The tables below show the relationship between the internal and external representations of numbers that are read or written with the F format item.

Used with the GET EDIT statement, the P format item acquires a pictured value (a field of characters) from the stream file, extracts its fixed-point decimal value, and assigns the value to an input target of any computational type. The picture describes a field of w characters, where w is the total number of picture characters in the picture, exclusive of the V character.

A string of w characters is acquired from the input stream and validated against the picture specified in the format item. The string is valid if it corresponds to an internal representation that would be created by the specified picture if the picture were used to declare a variable of type PICTURE. If the string is valid, its fixed- point decimal value is extracted and assigned to the input target. If necessary, the value is converted to the type of the input target, following the usual rules (see Section 6.4, “Data Type Conversion of Operands and Expressions”). If the string is not valid, the CONVERSION condition is signaled.

When no decimal point appears in the input stream item, the scale factor of the item is assumed to be the number of digit positions specified to the right of the V character in the picture. If no V character appears, the scale factor is zero.

Used with the PUT EDIT statement, the P format item outputs a source of any computational type in the specified format. If necessary, the output source is first converted to a fixed-point decimal value, following the PL/I conversion rules. The fixed-point decimal value is then edited by the picture specified in the format item. The P format item therefore describes an output field of w characters, where w is the total number of characters in the picture, exclusive of the V character. If the output source is a pictured value, then its extracted fixed-point decimal value must be capable of being edited by the picture specified in the P format item. Otherwise, the ERROR condition is signaled.

The following tables show the relationship between the internal and external representations of numbers that are read or written with the P format item.

The FORMAT statement describes a remote format-specification list to be used by GET EDIT or PUT EDIT statements. The FORMAT statement and remote (R) format item are useful when the same format specification is used by a large number of GET EDIT or PUT EDIT statements, or both. In this case, a change to the format specification can be made in the single FORMAT statement, rather than in each GET or PUT statement.

The form of the FORMAT statement is:

[(condition-prefix[,condition-prefix]... ):] label: FORMAT     (format-specification,...);

RFRM: PROCEDURE OPTIONS(MAIN);

       DECLARE SYSIN STREAM INPUT FILE;
       DECLARE SYSPRINT PRINT FILE;
       DECLARE SALARY PICTURE '$$$$$$$$9V.99';
       DECLARE (FIRST,MID,LAST) CHARACTER(80) VARYING;
       DECLARE 1 HIRING,
                        2 DATE CHARACTER(20) VARYING,
                        2 EXPERIENCE FIXED,
                        2 SALARY PICTURE '$$$$$$$$9V.99';
       OPEN FILE(SYSIN) TITLE('RFRM.IN');
       OPEN FILE(SYSPRINT) TITLE('RFRM.OUT');

       GET EDIT (SALARY, FIRST, MID, LAST, DATE, EXPERIENCE,
                       HIRING.SALARY)
                       (F(8,2),R(PERSONNEL_FORMAT));

       PUT SKIP LIST(TRIM(LAST)||', '||TRIM(FIRST)||
               ' '||TRIM(MID)||':  Hired '||TRIM(DATE)||' at '||HIRING.SALARY);
       PUT SKIP LIST(EXPERIENCE,' years prior experience');
       PUT SKIP LIST('Present salary: '||SALARY);

       PERSONNEL_FORMAT: FORMAT (R(NAME), A(20), SKIP, F(2), X,
                       F(8,2));
       NAME: FORMAT(3(SKIP,A(80)));

END RFRM;

Assume the file RFRM.IN contains the following data:

 25005.50
Thomasina
A.
Delacroix
6 July 1976
 2 15003.65

The following output, with spacing as shown, will be written to the print file RFRM.OUT:

Delacroix, Thomasina A.:    Hired 6 July 1976 at   $15003.65
             2   years prior experience
Present salary:    $25005.50

If w is zero, the file is repositioned at the beginning of the current line, allowing overprinting of the line. If w is greater than zero, and either the current line exceeds the page size or the page size is greater than or equal to the current line plus w, then w-1 blank lines are inserted. Otherwise, the remainder of the page (the portion between the current line and the page size) is filled with blank lines, and the ENDPAGE condition is signaled.

TAB: PROCEDURE OPTIONS(MAIN);

       DECLARE OUT STREAM OUTPUT PRINT FILE;

       OPEN FILE(OUT) LINESIZE(60);
       PUT FILE(OUT) SKIP
               EDIT('123456789012345678901234567890') (A);

       PUT FILE(OUT) SKIP EDIT('COL1','?') (A,TAB(2),A);
       PUT FILE(OUT) EDIT('!') (TAB(20),A);
       PUT FILE(OUT) SKIP EDIT('*') (TAB(1),A);
       PUT FILE(OUT) EDIT('abcdefg') (A); /* cc now = 17 */
       PUT FILE(OUT) EDIT('&') (TAB(6),A);
END TAB;

The program TAB writes the following output to the print file OUT.DAT:

123456789012345678901234567890
COL1            ?
!
        *abcdefg
&

The question mark appears in column 17, which is the second tab stop following the string `COL1'. The exclamation point appears in column 1 of the next line because there are fewer than 20 tab stops on the remainder of the line. In the third PUT EDIT statement, the SKIP option first resets the current column to zero. When the TAB format item is executed, it must position the file to the first tab stop that is between column 1 (cc+1) and the end of the line; therefore, the file is positioned, and the asterisk appears, in column 9. Similarly, the fourth statement writes out the string `abcdefg', after which the current column is 17, a tab stop. Because the line size has been established as 60, there are only five tab stops between cc+1 and the end of the line: 25, 33, 41, 49, and 57. Therefore, the format item TAB(6) in the last PUT EDIT statement causes a skip to the next line, and the ampersand appears in column 1.

On input, the next w columns after the current column are skipped.

On output, w spaces are inserted following the current column.

When the output stream is a file, and the end of the current line is reached, the output of spaces continues on the next line until w spaces have been output. The size of the current line is either the default value or the specific value you have established for the file (see Section 9.1, “Opening and Closing Files” for LINESIZE option). If the file is a print file, the ENDPAGE condition is signaled if the page size is reached; on normal return from the ENDPAGE ON-unit, output of spaces continues at the top of the next page until w spaces have been output.

If the output stream is a character-string variable, w spaces are written to the variable. The ERROR condition is signaled if the maximum length of the string is exceeded.

XFOR: PROCEDURE OPTIONS(MAIN);

       DECLARE INLINE CHARACTER(80) VARYING;
       DECLARE FIRSTWORD CHARACTER(80) VARYING;
       DECLARE OUTFILE PRINT FILE;
       DECLARE SPACE1 FIXED;

       GET EDIT(INLINE) (A(80)) OPTIONS(PROMPT('Line>'));

       SPACE1 = INDEX(INLINE,' '); /*position of first wordbreak*/
       FIRSTWORD = SUBSTR(INLINE,1,SPACE1-1);

       PUT STRING(FIRSTWORD) EDIT(FIRSTWORD,'-FIRST WORD TYPED')
                                               (A,X(2),A);
       PUT SKIP FILE(OUTFILE) LIST(FIRSTWORD);

END XFOR;

The GET EDIT statement in the program XFOR inputs a complete line from a user's terminal, after issuing and receiving an answer to the prompt `Line >'. Assume that the interaction is as follows:

Line> beautiful losers Return

The following output will be written to OUTFILE.DAT:

beautiful  -FIRST WORD TYPED

The X format item has correctly inserted two spaces between `beautiful' and `-FIRST WORD TYPED'.

XFOR2: PROCEDURE OPTIONS(MAIN);

       DECLARE INLINE CHARACTER(80) VARYING;
       DECLARE OUTFILE2 PRINT FILE;

       GET EDIT(INLINE) (X(10),A(1000))
               OPTIONS(PROMPT('Line>'));

       PUT SKIP FILE(OUTFILE2) LIST(INLINE);

END XFOR2;

In the program XFOR2, the GET EDIT statement skips the first 10 characters typed after the prompt and then inputs the remainder of the line. Assume that the interaction is:

Line> ABCDEFGHIJKLMNOPQRSTUVWXYZ Return

The following output will be written to OUTFILE2.DAT:

KLMNOPQRSTUVWXYZ

The first 10 letters (A to J) have been ignored on input.

Format-specification lists are used in GET EDIT, PUT EDIT, and FORMAT statements to control the conversion of data between the program and the input or output stream and to precisely control positioning within the input or output stream. This entry describes the syntax of format-specification lists and the manner in which a format list is processed to acquire or transmit data.

This section briefly describes rules and constraints for format-specification lists.

This section describes the manner in which format items are matched to input targets or output sources.

All edit-directed input statements include the following syntax:

EDIT (input-target, ...) (format-specification, ...)

All edit-directed output statements include the following syntax:

EDIT (output-source, ...) (format-specification, ...)

The following examples show typical edit-directed operations. All cases shown are for input (GET EDIT), but the operations for PUT EDIT are similar. The simple cases, shown first, are with input targets that are scalar variable references. The next cases shown are with aggregate (array and structure) references. The last cases shown are with DO specifications.

GET EDIT ( (B(I) DO I=10 TO 4 BY -2) , B(1) )
       ( 2( A(12),A(14) ), A(20) );

B is a 10-element array. Notice that the parentheses surrounding the first input target are in addition to the parentheses surrounding the entire input-target list. The preceding statement executes the format items A(12), A(14), A(12), and A(14), in that order, and assigns the resulting strings to elements B(10), B(8), B(6), and B(4), respectively. It then executes A(20) and assigns the result to B(1).

GET EDIT ( ( (A(I,J) DO J=1 TO 10) DO I=1 TO 20) )
       (F(5),F(6));

In the preceding statement, A is a two-dimensional array of 20 rows and 10 columns. Two hundred decimal integers are acquired and assigned to the array elements in the order A(1,1), A(1,2), ... ,A(20,10). Elements with odd-numbered columns receive 5-digit integers, and those with even-numbered columns, 6-digit integers. Because the DO specifications specify row-major order, the same operation is performed by the next example.

GET EDIT (A) (F(5),F(6));

Because row-major order is the default, nested DO specifications are used to change the order in which values are assigned.

The example has the same effect as the following DO-group:

DO I = 1 TO 20;
       DO J = 1 TO 10;
               GET EDIT(A(I,J)) (F(5),F(6));
               END;
       END;

Compared to a DO construct in an input-target list, however, nested DO groups are much less efficient in execution speed. In addition, some stream I/O statements may have different effects when specified in nested DO-groups as opposed to being specified with the DO construct in the input-target list. For example:

GET SKIP EDIT(input-target, ...) (format-specification, ...);

If you use this syntax in a pair of nested DO groups, as shown previously, the SKIP option is executed on each iteration of the innermost DO group. If you specify the DO construct in the input-target list, the SKIP option is executed only once, before any other input processing is performed.

GET EDIT ( ( CURRENT->PERSON.NAME
       DO CURRENT = FIRST
       REPEAT CURRENT->PERSON.NEXT
       WHILE (CURRENT ^= NULL) ) )
               (A(80));

CURRENT and FIRST are pointers, and PERSON is a based structure declared as:

DECLARE /* Based structure for list elements: */
       1 PERSON BASED,
               2 NEXT POINTER, /* Pointer to next element: */
               2 NAME CHARACTER(80) VARYING;
DECLARE /* NULL function and pointers to first and
               current list elements: */
               NULL BUILTIN,
               (FIRST,CURRENT) POINTER;

The GET EDIT statement reads 80-character strings from the input stream and assigns each to a list member PERSON.NAME. On the first input operation, the string is assigned to FIRST->PERSON.NAME. On subsequent iterations of the DO specification, the pointer to the next element, PERSON.NEXT, is assigned to CURRENT before the input operation. Before each input operation, including the first, the WHILE clause tests to determine whether the end of the queued list has been reached (indicated by the null pointer).

The DO REPEAT construct is often used in this type of application. You should use a WHILE or UNTIL clause in this or any DO REPEAT construct to be sure that the operation has a defined termination. However, the WHILE or UNTIL clause is not required.

SIMPLE_INPUT: PROCEDURE OPTIONS (MAIN);
       /* Simple input from user's terminal */
       DECLARE BADGE_NUMBER FIXED DECIMAL (5),
                       SOCIAL_SECURITY_NUMBER CHARACTER(11);

       GET LIST (BADGE_NUMBER,SOCIAL_SECURITY_NUMBER);
       PUT LIST (BADGE_NUMBER,SOCIAL_SECURITY_NUMBER);

END SIMPLE_INPUT;

PL/I does not display a prompt character on the terminal when a program executes a GET or READ statement. Consequently, it is difficult to tell that a program is trying to read data unless the program executes an output statement containing a prompting message. The program SIMPLE_INPUT would be easier to use if the following statement appeared immediately before GET LIST:

PUT SKIP LIST('Enter badge number, social security number:');

The cursor remains on the same line after the prompt is displayed, so the input can be entered on the same line. The completed line might be:

Enter badge number, social security number: 7,116-40-0482 Return

The GET statement also has a PROMPT statement option that displays a prompt on the user's terminal. See the Endless PL/I for POSIX Systems User's Manual.

TIN: PROCEDURE OPTIONS(MAIN);

       DECLARE STRING CHAR(10) VARYING,
               I FIXED BINARY STATIC INITIAL(0),
               A FLOAT BINARY;
       DECLARE EOF BIT STATIC INITIAL('0'B);

       ON ENDFILE(SYSIN) EOF = '1'B;
       PUT SKIP LIST('Enter string, integer, float>');
       GET LIST(STRING,I,A);
       DO WHILE(^EOF); /* stop when CTRL/D is typed */
               PUT SKIP LIST(STRING,I,A);
               PUT SKIP LIST('Enter string, integer, float>');
               GET LIST(STRING,I,A);
       END;

END TIN;

Here, the user is prompted to enter three values from the default file SYSIN. The three values are immediately written out to the default file SYSPRINT. This sequence continues until the user answers the prompt with a Ctrl/D, which signals the ENDFILE condition for SYSIN; the program then terminates. The following is a sample dialog with the program:

$ RUN TIN Return
Enter string, integer, float>  JONES,27,3.75 Return
JONES  27      3.7500000E+00
Enter string, integer, float>  JONES 27 3.75 Return
JONES  27      3.7500000E+00
Enter string, integer, float> JONES Return
27KEY(Return)
3.75;KEY(Return)
JONES  27      3.7500000E+00
Enter string, integer, float>  DOOLEY Return
KEY(Return)
4E-6;KEY(Return)
DOOLEY 0       4.0000000E-06
Enter string, integer, float> Ctrl+Z
$

Notice that input fields are separated by commas, spaces, or the RETURN key. Notice also that entering a blank line after `DOOLEY' causes the program to set the value of I to zero.

The following topics are of interest in terminal I/O applications:

COPY: PROCEDURE;
       DECLARE INREC CHARACTER(80) VARYING,
                       ENDED BIT(1) STATIC INIT('0'B),
                       (INFILE,OUTFILE) FILE;

       OPEN FILE (INFILE) RECORD INPUT
                       TITLE('RECFILE.DAT');
       OPEN FILE (OUTFILE) RECORD OUTPUT
                       TITLE('COPYFILE.DAT');
       ON ENDFILE(INFILE) ENDED = '1'B;

       READ FILE(INFILE) INTO (INREC);
       DO WHILE (^ENDED);
                       WRITE FILE (OUTFILE) FROM (INREC);
                       READ FILE (INFILE) INTO (INREC);
       END;
       CLOSE FILE(INFILE);
       CLOSE FILE(OUTFILE);
       RETURN;
END;

The program COPY reads a file with variable-length records into a character string with the VARYING attribute and writes the records to a new output file.

It uses a DO-group to read the records in the file sequentially until the end-of-file is reached. It uses the ON statement to establish the action to be taken when the end-of-file occurs: it sets the bit ENDED to '1'B so that the DO-group will not be executed again.

The VARYING character-string variable INREC has a maximum length of 80 characters. If any record in the file is more than 80 characters, the ERROR condition is signaled. If no ERROR ON-unit exists, the program exits.

PRINT_DATA: PROCEDURE OPTIONS(MAIN);
       DECLARE 1 EMPLOYEE BASED (EP),
                               2 NAME,
                                       3 LAST CHAR(30),
                                       3 FIRST CHAR(20),
                                       3 MIDDLE_INIT CHAR(1),
                               2 DEPARTMENT CHAR(4),
                               2 SALARY FIXED DECIMAL (6,2),
                       EP POINTER,
                       EMP_FILE FILE;

       DECLARE EOF BIT(1) STATIC INIT('0'B),
                       NUMBER FIXED BIN(31);

       ON ENDFILE(EMP_FILE) EOF = '1'B;
       OPEN FILE(EMP_FILE) INPUT SEQUENTIAL KEYED;
       READ FILE(EMP_FILE) SET(EP) KEYTO(NUMBER);
       DO WHILE (^EOF);
               PUT SKIP LIST('EMPLOYEE',NUMBER,
                       EMPLOYEE.NAME.FIRST,EMPLOYEE.NAME.LAST,
                       EMPLOYEE.NAME.MIDDLE_INIT);
               READ FILE(EMP_FILE) SET(EP) KEYTO(NUMBER);
               END;
       CLOSE FILE(EMP_FILE);

END;

The PRINT_DATA program accesses a relative file sequentially with READ statements and obtains the key value of each record, that is, the relative record number. The records in the file EMP_FILE are arranged according to employee numbers. Each employee number corresponds to a relative record number in the file. The READ statements read records into the based structure EMPLOYEE and set the pointer EP to the location of the allocated buffer. The READ statements specify the KEYTO option to obtain the record number of each record. The procedure prints the employee numbers and names. When the last record has been read, the program closes the input file and exits.

TRUNC: PROCEDURE;
       DECLARE INREC CHARACTER(80) VARYING,
                       OUTREC CHARACTER(80),
                       ENDED BIT(1) STATIC INIT('0'B),
                       (INFILE,OUTFILE) FILE;

       OPEN FILE (INFILE) RECORD INPUT
               TITLE('RECFILE.DAT');
       OPEN FILE (OUTFILE) RECORD OUTPUT
               TITLE('TRUNCFILE.DAT')
               ENVIRONMENT(FIXED_LENGTH_RECORDS,
               MAXIMUM_RECORD_SIZE(80));

       ON ENDFILE(INFILE) ENDED = '1'B;
       READ FILE(INFILE) INTO (INREC);
       DO WHILE (^ENDED);
               OUTREC = INREC;
               WRITE FILE (OUTFILE) FROM (OUTREC);
               READ FILE (INFILE) INTO (INREC);
       END;

       CLOSE FILE(INFILE);
       CLOSE FILE(OUTFILE);
       RETURN;
END;

The TRUNC procedure reads a file with variable-length records into a character string with the VARYING attribute and creates a sequential output file in which each record has a fixed length of 80 characters.

The ENVIRONMENT attribute for the file OUTFILE specifies the record format and length of each fixed-length record.

When records are written to a file with fixed-length records, the variable specified in the FROM option must have the same length as the records in the target output file. Otherwise, the ERROR condition is signaled. Thus, in this example, each record read from the input file is copied into a fixed-length character-string variable for output.

The TRUNC procedure creates a new version of the file TRUNCFILE.DAT every time it executes.

ADD_EMPLOYEE: PROCEDURE;

       DECLARE 1 EMPLOYEE,
                               2 NAME,
                                       3 LAST CHAR(30),
                                       3 FIRST CHAR(20),
                                       3 MIDDLE_INIT CHAR(1),
                               2 DEPARTMENT CHAR(4),
                               2 SALARY FIXED DECIMAL (6,2),
                       EMP_FILE FILE;

       DECLARE MORE_INPUT BIT(1) STATIC INIT('1'B),
                       NUMBER FIXED DECIMAL (5,0);

       OPEN FILE(EMP_FILE) DIRECT UPDATE;

       DO WHILE (MORE_INPUT);
               PUT SKIP LIST('Employee Number');
               GET LIST (NUMBER);
               PUT SKIP LIST ('Name (Last, First, Middle Initial)');
               GET LIST (EMPLOYEE.NAME.LAST,EMPLOYEE.NAME.FIRST,
                       EMPLOYEE.NAME.MIDDLE_INIT);

               PUT SKIP LIST('Department');
               GET LIST (EMPLOYEE.DEPARTMENT);

               PUT SKIP LIST('Starting salary');
               GET LIST(EMPLOYEE.SALARY);

               WRITE FILE (EMP_FILE)
                       FROM (EMPLOYEE) KEYFROM(NUMBER);

               PUT SKIP LIST('More?');
               GET LIST(MORE_INPUT);
       END;
       CLOSE FILE(EMP_FILE);
       RETURN;
END;

The ADD_EMPLOYEE procedure adds records to the existing relative file EMP_FILE. The file is organized by employee numbers, and each record occupies the relative record number in the file that corresponds to the employee number.

The file is opened with the DIRECT and UPDATE attributes, because records to be written will be chosen by key number. Within the DO- group, the program prompts for data for each new record that will be written to the file. After the data is input, the WRITE statement specifies the KEYFROM option to designate the relative record number. The number itself is not a part of the record but will be used to retrieve the record when the file is accessed for keyed input.

The procedure NEW_SALARY, below, updates the salary field in a relative file containing employee records. The procedure receives two input parameters: the employee number and the new salary. The employee number is the key value for the records in the relative file.

NEW_SALARY: PROCEDURE (EMPLOYEE_NUMBER,PAY);

       DECLARE EMPLOYEE_NUMBER FIXED DECIMAL(5,0),
               PAY FIXED DECIMAL (6,2);



       DECLARE 1 EMPLOYEE,
                               2 NAME,
                                       3 LAST CHAR(30),
                                       3 FIRST CHAR(20),
                                       3 MIDDLE_INIT CHAR(1),
                               2 DEPARTMENT CHAR(4),
                               2 SALARY FIXED DECIMAL (6,2),
                       EMP_FILE FILE;

       OPEN FILE(EMP_FILE) DIRECT UPDATE;
       READ FILE(EMP_FILE) INTO(EMPLOYEE)
                       KEY (EMPLOYEE_NUMBER);
       EMPLOYEE.SALARY = PAY;
       REWRITE FILE(EMP_FILE) FROM(EMPLOYEE)
                       KEY(EMPLOYEE_NUMBER);
       CLOSE FILE(EMP_FILE);
       RETURN;
END;

In this example, the KEY option is specified in the READ statement that obtains the record of interest and in the REWRITE statement that replaces the record, with its new information, in the file. The FROM and KEY options must both be specified on the REWRITE statement.

The sample program CHANGE_HEADER, below, changes the contents of the first record in the sequentially organized file TITLE_PAGE. The file consists of 80-byte, fixed-length records.

CHANGE_HEADER: PROCEDURE OPTIONS(MAIN);

       DECLARE TITLE_PAGE FILE SEQUENTIAL UPDATE,
                       INREC CHARACTER(80) BASED(P),
                       P POINTER;

       OPEN FILE(TITLE_PAGE);
       READ FILE(TITLE_PAGE) SET(P);

       INREC = 'Summary of Courses for Fall 1980';
       REWRITE FILE(TITLE_PAGE);
       CLOSE FILE(TITLE_PAGE);
       RETURN;
END;

In this example, the READ statement specifies the SET option. The input record is read into a buffer, INREC, that is a based character-string variable. The assignment statement modifies the buffer, and the REWRITE statement rewrites the record. Because the REWRITE statement does not specify a FROM option, PL/I uses the contents of the buffer to rewrite the current record in the file (that is, the record that was just read).