Kednos PL/I for OpenVMS Systems
Reference Manual

The A format item (both uppercase and lowercase) describes the representation of a character string in the input or output stream. The form of the A format item is as follows:

A [(w)]

w

A nonnegative integer or an integer expression that specifies the width in characters of the field in the stream. If it is not included (PUT EDIT only), the field width equals the length of the converted output source.

Input with GET EDIT

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.

Output with PUT EDIT

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).

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

Input Examples

The input stream shown in the following table is a field of characters beginning at the current position in the stream and continuing to the right. The # character is used to signify 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
A(10)	##SHRUBBERY#...	CHAR(10)	##SHRUBBER
A(6)	##SHRUBBERY#...	CHAR(10)	##SHRU####
A(6)	##SHRUBBERY#...	CHAR(10) VAR	##SHRU
A(10)	##1.2345####...	DECIMAL(4,1)	001.2
A(5)	##1.2345####...	DECIMAL(4,2)	01.20
A(6)	##1.2345####...	DECIMAL(4,2)	01.23

Output Examples

The output source value shown in the table that follows is either a constant or the value of a variable that is written with the associated format item.

Output Source Value	Format Item	Output Value
'STRING'	A(10)	STRING####
'STRING'	A	STRING
1.2345	A(2)	##
1.2345	A	##1.2345
-1.2345	A(4)	#-1.
-1.2345	A	#-1.2345
''	A(10)	##########
''	A	[no output]
0	A(3)	###
0	A	###0
-12345	A(6)	##-123
-12345	A	##-12345

9.2.4.2 B Format Items

The B format items B, B1, B2, B3, and B4 describe representations of bit strings in an input or output stream. Note that the B can be typed lowercase. The form of the B format items is as follows:

B[m] (w)

m

The integer 1, 2, 3, or 4, specifying the radix factor, that is, 2^m. B and B1 have the same meaning. When the radix factor is omitted or is 1, the bit string is represented by the characters 0 and 1 (binary) in the stream. When the radix factor is 2, the bit string is represented by the characters 0, 1, 2, and 3 (base 4). When the radix factor is 3, the bit string is represented by the characters 0, 1, 2, 3, 4, 5, 6, and 7 (octal). When the radix factor is 4, the bit string is represented by the characters 0 through 9 and A through F (hexadecimal).

w

A nonnegative integer or integer expression that specifies the width in characters of the field in the stream.

The interpretation of the B format items on input and output is described below.

Input with GET EDIT

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).

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.

Output with PUT EDIT

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). 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 is truncated or padded with spaces on the right if necessary. If w is not included, the output string has the same length as the converted output source. If w is zero, the B format item and its associated output source are skipped.

Examples

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.

Input Examples

The input stream shown in the following table is a field of characters beginning at the current position in the stream and continuing to the right. The # character is used to signify 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
B(12)	111000111110...	BIT(12)	'111000111110'B
B(12)	######110011...	BIT(12)	'110011000000'B
B2(6)	123123...	BIT(12)	'011011011011'B
B3(4)	1775...	BIT(12)	'001111111101'B
B4(3)	1FA...	BIT(12)	'000111111010'B

Output Examples

The output source value shown in the following 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
4095	B	111111111111
4095	B(11)	11111111111
4095	B2	333333
4095	B3	7777
4095	B4	FFF

9.2.4.3 COLUMN Format item

The COLUMN format item sets a stream file to a specific character position within a line. In other words, COLUMN determines the position at which the next data will be output or from which the next data will be input. The COLUMN format item refers to an absolute character position in a line; for information on how to refer to a relative position, see Section 9.2.4.12.

The form of the COLUMN format item is:

w

A nonnegative integer or expression that identifies the wth position from the beginning of the current line. The value of the converted expression must be zero or positive. If the value of the converted expression is zero, a value of 1 is assumed.

If the file is already at the specified position, no operation is performed. If the file is already beyond the specified position, the format item is applied to the next line.

The interpretation of the COLUMN format item on input and output is given below.

Input with GET EDIT

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.

Output with PUT EDIT

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.

Examples

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'

9.2.4.4 E Format Item

The E format item describes the representation of a fixed- or floating-point value as a decimal floating-point number in a stream.

The form of the item is:

E(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.

Input with GET EDIT

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 following forms:

Form	Example
mantissa	124333
sign mantissa	-123.333
sign mantissa sign exponent	-123.333-12
sign mantissa E exponent	-123.333E12
sign mantissa E sign exponent	-123.343E-12

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.

Output with PUT EDIT

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 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 for the exponent itself. (On OpenVMS VAX systems for values of type H-float, the value of w should be 8 greater than the number of digits, respectively.)

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.

Examples

The next tables show the relationship between the internal and external representations of numbers that are read or written with the E 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
E(6,0)	124333...	DECIMAL(10,2)	124333.00
E(6,0)	-123333...	DECIMAL(10,2)	-12333.00
E(8)	-123.333...	DECIMAL(8,5)	-123.33300
E(11)	-123.333-12...	FLOAT DEC(7)	-1.233330E-10
E(11,3)	-123343E-12...	FLOAT DEC(15)	-1.23343000000000E-10

Output Examples

The output source value shown in the 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 signify a space.