Kednos PL/I for OpenVMS Systems
Reference Manual

This section describes the S and T floating-point formats supported by OpenVMS Alpha systems. OpenVMS Alpha also supports the F, D, and G floating-point formats described in Section 3.2.4.5.

IEEE S_floating Format

The following PL/I types are represented using S_floating data, which occupies four contiguous bytes:

FLOAT BINARY (P) P <= 24 FLOAT DECIMAL (P) P <= 7

Bits are labeled from the right, 0 through 31, as shown in Figure 3-4.

Figure 3-4 IEEE S_floating Data Representation

The form of S_floating data is sign magnitude, with bit 31 the sign bit (0 for positive numbers, 1 for negative numbers), bits 30:23 an exponent, and bits 22:0 a normalized 24-bit fraction including the redundant most significant fraction bit not represented. The value of data is in the range 1.17549435E-38 (normalized) to 3.40282347E38. The precision is approximately one part in 2**23; that is, typically seven decimal digits.

When loaded into a 64-bit register, the S_floating value resides in bits 29-63.

IEEE T_floating Format

The following PL/I types are represented using T_floating data, which occupies eight contiguous bytes:

FLOAT BINARY (P) 24 < P <= 53 FLOAT DECIMAL (P) 7 < P <= 15

Bits are labeled from the right, 0 through 63, as shown in Figure 3-5.

Figure 3-5 IEEE T_floating Data Representation

The form of T_floating data is sign magnitude, with bit 63 the sign bit (0 for positive numbers, 1 for negative numbers), bits 62:52 an exponent, and bits 51:0 a normalized 53-bit fraction including the redundant most significant fraction bit not represented. The value of data is in the approximate range 2.225073859E-380 (normalized) to 1.797693135E308. The precision is approximately one part in 2**52; that is, typically fifteen decimal digits.

3.2.5 Pictured Data

Use pictured data when you want to manipulate a quantity arithmetically and accept or display its value using a special format.

A picture specification (or picture) describes both the numeric attributes of a pictured variable and its input/output (I/O) format. A simple picture might look like this in a DECLARE statement:

DECLARE CREDIT PICTURE '$99999V.99DB';

This statement declares the variable CREDIT as a pictured variable. The characters within the apostrophes describe its format.

The formatting possible with pictured data is useful in many applications, but pictured data is much less efficient than fixed-point decimal data for strictly computational use.

This section discusses the following topics:

• The picture characters that make up a specification in the PICTURE attribute and in the P format item. It also describes picture syntax.
• The process by which a value is assigned to a pictured variable or written out with the P format item.
• The process by which a pictured value is assigned to other variables or acquired with the P format item.
• Editing by picture.
• The internal representation of pictured variables.

The formatting possible with pictured data is useful in many applications, but pictured data is less efficient than fixed-point decimal data in computations. Therefore, do not use pictured data unless you need the formatting.

3.2.5.1 Picture Characters

Table 3-6 summarizes the PL/I picture characters, their meaning, and whether they effect numeric interpretation and internal representation. The paragraphs following the table describe the picture characters and syntax. All picture characters are shown here in uppercase, but their lowercase equivalents can be used.

Table 3-6 Picture Characters

Character	Meaning	Numeric Interpretation	Internal Representation
V	Position of assumed decimal point	yes	no
9	Decimal digit, including leading zeros	yes	yes
Z	Decimal digit with leading-zero suppression	yes	yes
*	Decimal digit with asterisk for leading zero	yes	yes
Y	Decimal digit with space for any zero	yes	yes
(n)	Iteration factor for subsequent character	yes	yes
T	Position of digit and encoded plus sign or minus sign	yes	yes
I	Position of digit and encoded plus sign if number >= 0	yes	yes
R	Position of digit and encoded minus sign if number < 0	yes	yes
$	Position(s) of (drifting) dollar sign	yes	yes
+	Position(s) of (drifting) plus sign if number >= 0	yes	yes
-	Position(s) of (drifting) minus sign if number < 0	yes	yes
S	Position(s) of (drifting) plus sign or minus sign	yes	yes
,	Position at which comma is inserted	no	yes
.	Position at which decimal point is inserted	no	yes
/	Position at which slash is inserted	no	yes
B	Position at which space is inserted	no	yes
CR	Positions at which <BIT_STRING>(CR) is inserted if number < 0	no	yes
DB	Positions at which <BIT_STRING>(DB) is inserted if number < 0	no	yes

Decimal Place Character (V)

The V character shows the position of the assumed decimal point, or the scale factor for the fixed-point decimal value. The V character has no effect on the internal representation of the pictured value and does not cause a decimal point to appear in the internal representation or in the output (use the period insertion character for this purpose). The following rules apply to the V character:

• Only one V character can appear in a picture.
• If a picture does not contain the V character, the V is assumed to be at the right end of the picture. That is, the pictured value has a scale factor of 0.
• When a fixed-point value is assigned to a pictured variable, the integral portion of the assigned value is described by the picture characters to the left of the V; the fractional portion of the assigned value is described by the picture characters to the right of the V. Values with too many or too few digits are handled as follows:
  • If the assigned value has fewer integral digits than are indicated by the picture characters to the left, then the integral value of the pictured variable is extended on the left with zeros. If the assigned value has too many integral digits, the value of the pictured variable is undefined and the FIXEDOVERFLOW condition is signaled.
  • If the assigned value has fewer fractional digits than are indicated in the picture, then the fractional value of the pictured variable is extended on the right with zeros. If the assigned value has too many fractional digits, then the excess fractional digits are truncated on the right; no condition is signaled. Thus, if the V character is the last character in the picture or is omitted, assigned fixed-point values are truncated to integers.

The following example shows the effect of the V character:

DECLARE PRICE PICTURE '$$9V.99', BAD_PRICE PICTURE '$$9.99'; PRICE = .98; /* Output as $0.98 */ BAD_PRICE = .98; /* Output as $0.00 */ PRICE = 98; /* Output as $98.00 */ BAD_PRICE = 98; /* Output as $0.98 */

In this example, note that the variable PRICE, which contains the V character, represents the value properly. The variable BAD_PRICE, which contains only the period insertion character, has an assumed V character at the end of the picture, which causes the variable to misrepresent the value.

Digit Characters (9, Z, *, Y)

The characters 9, Z, and Y, and the asterisk character (*) mark the positions occupied by decimal digits. The number of these characters present in a picture specifies the number of digits, or precision, of the fixed-point decimal value of the pictured variable. The following rules apply to these characters:

• The position occupied by 9 always contains a decimal digit, whether or not the digit is significant in the numeric interpretation of the pictured value. Leading zeros at positions occupied by a 9 are output.
• The position occupied by Z contains a decimal digit only if the digit is significant in the integral portion of the numeric interpretation; if the digit is a leading 0, it is replaced by a space. Several additional rules apply to the Z character:
  • The Z character must not appear in the same picture with the asterisk character (*). It must not appear to the right of the characters 9, T, I, or R nor to the right of a drifting string.
  • If the Z character appears to the right of the V character, then all digits to the right of the V must be indicated by Z characters. Fractional zeros are then suppressed only if all fractional digits are 0 and all of the integral digits are suppressed; in that case, the internal representation contains only spaces in the digit positions.
• The position occupied by the asterisk character (*) functions identically with the Z character, except that leading zeros are replaced by asterisks instead of spaces.
• The position occupied by the Y character contains a decimal digit only if the digit is not 0. All zeros in the indicated positions, whether significant or not, are replaced by spaces.

Iteration Factor (n)

You can precede any picture character that can appear more than once in a picture by an iteration factor, which must be a positive integer constant enclosed in parentheses. For example:

'(4)9'

This picture is the same as the following one:

'9999'

Encoded-Sign Characters (T, I, R)

You can use the characters T, I, and R, which are encoded-sign characters, wherever 9 is valid. Each represents a digit that has the sign of the pictured value encoded in the same position. You can use only one encoded-sign character in a picture.

An encoded-sign character cannot be used in a picture that contains one of the following characters: S, +, -, CR, or DB (described in the following text).

The meanings of the characters are:

• The T character indicates that the position contains an encoded minus sign if the numeric value is less than 0 and an encoded plus sign if the numeric value is greater than or equal to 0.
• The I character indicates an encoded plus sign if the numeric value is greater than or equal to 0. Otherwise, the position contains an ordinary digit.
• The R character indicates an encoded minus sign if the numeric value is less than 0. Otherwise, the position contains an ordinary digit.

Table 3-7 lists the encoded-sign characters and their ASCII equivalents.

Table 3-7 ASCII Representation of Encoded-Sign Characters

Digit	ASCII Character	Digit	ASCII Character
+0	{	-0	}
+1	A	-1	J
+2	B	-2	K
+3	C	-3	L
+4	D	-4	M
+5	E	-5	N
+6	F	-6	O
+7	G	-7	P
+8	H	-8	Q
+9	I	-9	R

Drifting Characters ($, +, -, S)

The dollar sign ($), plus sign (+), minus sign (-), and S character are drifting characters. You can use the drifting characters to indicate digits, and they also indicate a symbol to be inserted when, for example, a pictured value is written out by PUT LIST. The meanings of the characters are:

• The dollar sign ($) causes a dollar sign to be inserted.
• The plus sign (+) causes a plus sign to be inserted if the numeric value is greater than or equal to 0.
• The minus sign (-) causes a minus sign to be inserted if the numeric value is less than 0.
• The S character causes a plus sign to be inserted if the numeric value is greater than or equal to 0, and a minus sign if the value is less than 0.

If one of these characters is used alone in the picture, it marks the position at which a special symbol or space is always inserted, and it has no effect on the value's numeric interpretation. In this case, the character must appear either before or after all characters that specify digit positions.

However, if a series of n of these characters appears, then the rightmost n-1 of the characters in the series also specify digit positions. If the digit is a leading 0, the leading 0 is suppressed, and the leftmost character drifts to the right; the character appears either in the position of the last drifting character in the series or immediately to the left of the first significant digit, whichever comes first.

Used this way, the n-1 drifting characters also define part of the numeric precision of the pictured variable, because they describe at least some of the positions occupied by decimal digits. For an example of this behavior by a drifting character (the dollar sign), refer to the V decimal place character description.

The following additional rules apply to drifting characters:

• A drifting string is a series of more than one of the same type of drifting character. Only one drifting string can appear in the picture; any other drifting characters can be used only singly and therefore designate insertion characters, not digits.
• The Z and asterisk (*) cannot appear to the right of a drifting string.
• A digit position cannot be specified (for instance, with a 9) to the left of a drifting string.
• A drifting string can contain the V character and one of the insertion characters, which are defined as follows:
  • If the drifting string contains an insertion character, it is inserted in the internal representation only if a significant digit appears to its left. In the position of the insertion character, a space appears if the leftmost significant digit is more than one position to the right; the drifting symbol appears if the next position to the right contains the leftmost significant digit.
  • If the drifting string contains a V character, all digit positions to the right of the V (the fractional digits) must also be part of the drifting string. In this case, insignificant fractional digits are suppressed only when all integral and fractional digits are zeros: they are replaced by spaces in the internal representation. If any digit is not 0, all fractional digits appear as actual digits.
  • Any insertion characters immediately to the right of a drifting string are considered part of it.

Insertion Characters (, . / B)

The insertion characters indicate that characters are inserted between digits in the pictured value. The insertion characters are the comma (,), period (.), slash (/), and the space (B). The B character indicates that a space is always inserted at the indicated position.

The drifting characters ($, +, -, S) also function as insertion characters when used singly (that is, not as part of a drifting string).

The period (.) does not imply a decimal place character V (see the example in the description of the V character, described earlier).

The following rules describe insertion by the comma, period, and slash insertion characters.

• In general, the insertion character itself is inserted in the internal representation of the pictured value. In particular, this is true if the insertion character is the first character in the picture, or if all the picture characters to its left are characters that do not specify decimal digits.
• If 0 suppression occurs, the insertion character is inserted only in these cases:
  • If a significant digit appears immediately to its left
  • If the V character appears immediately to its left, and the fractional part of the numeric value contains significant digits
• If the position preceding the insertion character is occupied by an asterisk or drifting string and the preceding position is taken by a leading 0, then the preceding character also indicates the character to be inserted in the position of the insertion character. If, however, the preceding position is taken by a leading 0 and does not have an asterisk or drifting string, then the insertion character's position is a space in the internal representation of the pictured value.
• To guarantee that the decimal point is in the same position in both the numeric and character interpretations, the V and period characters must be adjacent. However, if the period precedes the V, then it is suppressed if there are no significant integral digits, even though all the fractional digits are significant. This property can make fractions appear to be integers when the internal (character) value is displayed. Consequently, the period should immediately follow the V character; it will then be in the correct location and will appear whenever any fractional digit is significant. The following example shows the correct and incorrect placement of the period:

  DECLARE NUM PICTURE 'ZZZV.ZZ', BAD_NUM PICTURE 'ZZZ.VZZ'; NUM=0.02; /* Output as .02 */ BAD_NUM=0.02; /* Output as 02 */

• You can use other insertion characters, such as the comma, to separate the integral and fractional portions of a number. Do not use the comma with GET LIST input, because in that context it separates different data items in the input stream.

Credit (CR) and Debit (DB) Characters

These picture characters are always specified as the character pairs CR and DB. If either pair is included, it appears if the numeric value is less than zero. In each case, the associated positions contain two spaces if the numeric value is greater than or equal to 0.

The characters are inserted with the same case as used in the picture. If the lowercase form cr is used in the picture, lowercase letters are inserted in the pictured value; if the combination Cr is used, then Cr is inserted.

The credit and debit characters cannot be combined in one picture, nor can they be used in the same picture as any other character that specifies the sign of the value (S, plus sign (+), and minus sign (-) characters). In addition, they must appear to the right of all picture characters specifying digits.

Picture Syntax

After all its iterations are expanded and all its insertion characters are removed, a picture must satisfy the following syntax rules (the notation character, or ellipsis (...), indicates a series of the same character, with no embedded characters).

Picture:

Examples

Valid Pictures

'S99V.99'

The picture specifies a signed fixed-point number with a precision of 4 (p=4) and a scale factor of 2 (q=2). The sign of the number is always included in its representation, in the first position. A period is inserted at the position of the assumed decimal point.

'****99'

The picture specifies a 6-digit integer, with the first four leading zeros replaced by asterisks.

'****V.**'

The picture specifies a fixed-point number with p=6, q=2. The first four leading zeros are replaced by asterisks in the integral portion. Both fractional digits always appear unless all six digits are 0. A period is inserted at the position of the assumed decimal point.

'ZZ99V.99'

The picture specifies a fixed-point number with p=6, q=2. The first two digits in the integral portion are replaced with spaces if they are zeros. Two digits always appear on either side of the decimal point.

'(4)SV.99'

The picture specifies a fixed-point number with p=5, q=2. (The iteration factor 4 specifies a string of four S characters, one of which specifies a sign and three of which specify digits.) A plus (+) or minus (-) symbol is inserted to the immediate left of the first significant integral digit, or to the left of the decimal point if no integral digit is significant. Any insignificant integral digits are replaced with spaces or with the sign symbol.

'ZZZ,ZZZV.99'

The picture specifies a fixed-point number with p=8, q=2. If the integral portion has four or more significant digits, a comma is inserted between the third and fourth digit; otherwise, both the leading zeros and the comma are suppressed. The decimal point always appears followed by two fractional digits.

'ZZZ.ZZZV,99'

The picture specifies a fixed-point number with p=8, q=2. If the integral portion has four or more significant digits, a period is inserted between the third and fourth; otherwise, both the leading zeros and the period are suppressed. The decimal point (indicated by a comma) always appears followed by two fractional digits.

'ZZZ/ZZZ/ZZZ'

The picture specifies a fixed-point number with p=9, q=0. A slash is inserted between the 3-digit groups unless the digit preceding the slash is a suppressed 0.

Invalid Pictures

'999ZZZZV.99'

The picture is invalid because a 9 occurs to the left of Z.

'$$$-99v.99'

The picture is invalid because it contains two drifting strings (<BIT_STRING>($$$) and <BIT_STRING>(- -)).

'(4)-V.ZZZ'

The picture is invalid because fractional digits in this case must be pictured either with a drifting minus sign or with 9s.