| Previous | Contents | Index |
The F format item describes the representation of a fixed- or floating-point value as a decimal fixed-point number in a stream.
The form of the item is:
F(w[,d]) |
w
A nonnegative integer or expression that specifies the total width in characters of the field in the stream.d
An optional nonnegative integer or expression that specifies the number of fractional digits in the stream representation and whose value is interpreted depending on GET EDIT and PUT EDIT statements as described below.
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:
The number is a fixed-point decimal constant, and the sign is a plus (+) or minus (-) symbol.
The following are valid representations:
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:
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.
Input Examples
The input stream shown in this table 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.
| Format Item | Input Stream | Target Type | Target Value |
|---|---|---|---|
| F(10,2) | -123456.78... | DECIMAL(10,2) | -123456.78 |
| F(10,4) | -1234.56789... | DECIMAL(10,2) | -1234.56 |
| F(8,5) | -.123456789... | DECIMAL(5,5) | -0.12345 |
| F(10) | 1234.56789... | FLOAT DEC(7) | 1.234568E+03 |
Output Examples
The output source value shown in this table is either a constant or the value of a variable that is written out with the associated format item. The # character is used to specify a space.
| Output Source Value | Format Item | Output Value |
|---|---|---|
| -12.234 | F(3,0) | -12 |
| -12.234 | F(6,2) | -12.23 |
| -12.234 | F(7,3) | -12.234 |
| -1.23456E3 | F(8) | ###-1235 |
| -1.23456E3 | F(8,2) | -1234.56 |
| '1000'B3 | F(4) | #512 |
| '1000000000000000'B | F(5) | 32768 |
| '100000'B3 | F(5) | 32768 |
| 'ABCEDF'B4 | F(10) | ##11259615 |
The LINE format item sets a print file to a specific line. It can be used only with print files and the PUT EDIT statement. If necessary, blank lines are inserted between the current file position and the specified line, and subsequent output begins on the specified line.
The LINE format item identifies an absolute line position on the current output page; to specify a line position relative to the current line, see SKIP format item.
The form of the LINE format item is:
LINE(w) |
w
An integer, or an expression, that specifies a line on the current page, where line 1 is the first line. The maximum value for a print file's line number is 32767. If a program generates a value in excess of 32767, a run-time error occurs.
When the LINE format item is executed, the current line is determined. The current line is 1 if the file is at the beginning of a new page. Otherwise, the current line is n+1, where n is the number of complete lines already on the page. The position in the file is then changed as follows:
The picture format item (P) describes a field of characters in the input or output stream. The field can be an input field acquired with GET EDIT or an output field transmitted by PUT EDIT. With GET EDIT, the P format item acquires a pictured value from the input stream. With PUT EDIT, the P format item edits an output source to a specified picture format.
The form of the P format item is:
P 'picture' |
'picture'
A picture of the same syntax as for the PICTURE data attribute. The syntax is summarized in PICTURE attribute (see Section 2.2.38. The field width is the total number of characters, exclusive of V, in the picture.
The interpretation of the P format item, for input and output, is given below.
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). 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.
Input Examples
The input stream shown in this table is a field of characters beginning at the current position in the stream and continuing to the right. The # character is used to specify a space. The target type is the type of the variable to which the input value is assigned.
| Format Item | Input Stream | Target Type | Target Value |
|---|---|---|---|
| P'$$$,$$$,$$9V.99DB' | $10,987,654.00DB... | DECIMAL(10,2) | -10987654.00 |
| P'$$$,$$$,$$9V.99DB' | ########$10.99##... | DECIMAL(10,2) | 10.99 |
| P'SSSSV.SSSSS' | ##-1.12345... | DECIMAL(8,5) | -1.12345 |
| P'SSSSV.SSSSS' | +100.12345... | DECIMAL(8,5) | 100.12345 |
| P'SSSSV.SSSSS' | #100.12345... | DECIMAL(8,5) | [CONVERSION] |
| P'SSSSV.SSSSS' | +1001.2345... | DECIMAL(8,5) | [CONVERSION] |
The last two cases signal the CONVERSION condition. In the first case, the input field has a space instead of a plus symbol or minus symbol in the first position. In the second case, the input field has four digits to the left of the period, and the P format item specifies a maximum of three. The P format item in both cases uses drifting strings of S characters, and, if used to declare a picture variable, the specification could create several different character representations. However, the specification could not have created the last two input fields shown, and they are therefore invalid values.
Note that in the second line in the table, the characters "$10.99" must be surrounded with the number of spaces shown. The drifting dollar signs and the comma insertion characters always specify either digits, the characters themselves, or spaces. Similarly, the characters "DB" in the picture specification specify either these characters or the same number of spaces. If the pictured input value did not contain these spaces, it would be invalid.
Output Examples
The output source value shown in this table is either a constant or the value of a variable that is written out with the associated format item.
Output Source Value Format Item Output Value -12234 P'$$$$$$DB' $12234DB -12234 P 'SSSSSSV.SS' -12234.00 -12.234 P 'T9V.999' J2.234 -1.23456E3 P '-9999V.99' -1234.56 -1.23456E3 P '+ZZZ9V.99' #1234.56
The PAGE format item is used with print files to begin a new page. See Section 9.2.6 for more information on print files.
The form of the PAGE format item is:
PAGE |
Subsequent output begins on line 1 of the next page, and the current
page number for the print file is incremented by 1.
9.2.4.9 R Format Item
The R (remote) format item specifies the label of a FORMAT statement from which some or all of a format specification is obtained by a GET EDIT or PUT EDIT statement.
The form of the R format item is:
R (label) |
label
The label of a FORMAT statement within the same block as the GET EDIT or PUT EDIT statement. If the item occurs in a recursive procedure, the R item and FORMAT statement must occur in the same recursion.
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:
label: FORMAT (format-specification,...); |
label
A valid PL/I label. A label is required and is specified in the GET EDIT or PUT EDIT statement that contains an R format item in its format-specification list.format-specification
A list of one or more format items that match corresponding input targets in a GET EDIT statement, or output sources in a PUT EDIT statement.
Although the FORMAT statement can contain another R format item, the following restrictions apply:
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(LAST||', '||FIRST||' '||MID||':',
'Hired '||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
|
The SKIP format item sets a stream file to a new position relative to the current line. It is used with input and output files.
The form of the SKIP format item is:
SKIP [(w)] |
w
An integer, or an expression, giving the number of lines to be skipped; the expression must not convert to a negative integer and must be greater than zero, except for print files. If w is omitted, a value of 1 is assumed.
If w is 1 or is omitted, the file is positioned at the beginning of the next line. If w is greater than 1, w-1 lines are skipped on input, but the ENDFILE condition is signaled if the end of the file is encountered first. On output, w-1 blank lines are inserted. In both cases, the new position is the beginning of (current line)+w.
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.
9.2.4.11 TAB Format Item
The TAB format item sets a print file to a specified tab stop. It is used only for output to print files. Within a line, tab stops always occur every eight columns, starting at column 1. The form of the TAB format item is:
TAB [(w)] |
w
An integer, or an expression, that identifies the wth tab stop from the current position; w must not be negative. If w equals zero, no operation is performed. If w is omitted, a value of 1 is assumed.
When the TAB format item is executed, the current column (cc) is determined. If the current position is the beginning of a line, page, or file, then cc is one. Otherwise, cc is the column in the current line at which the next output character would appear. For example, if seven characters have already been written on a line, then the cc is column 8; this is where the next output would occur. The file is then repositioned in one of the following ways:
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 <BIT_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 <BIT_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.
| Previous | Next | Contents | Index |