This chapter defines the conversions that result from assignments to arithmetic variables, bit-string variables, and pictured variables.
Each arithmetic, pictured, or string value can be converted to another value whose data type is any other arithmetic, pictured, or string data type. Conversion is not possible for data other than arithmetic, pictured, or string data.
Conversions occur as a result of using the assignment, arithmetic, relational, or concatenate operators; from the use of certain built-in functions; from GET/ PUT statements during parameter passing; and from statement options such as KEY and KEYFROM.
Each conversion begins with a source value to be converted and a complete or partial data type called the target data type. The target data type is determined by the context that caused the conversion. For example, the data type of the variable on the left side of the assignment operator provides the target data type for the conversion that is to be performed for that assignment. A partial target data type may result from the use of a conversion built-in function such as FIXED, FLOAT, BINARY, DECIMAL, BIT, or CHARACTER, as well as from other contexts, such as the use of arithmetic operators.
The conversion rules described in the section Arithmetic Operators define the target data type for conversions that result from arithmetic or relational operators. The section The Concatenate Operator gives the target data type for conversions that result from using the concatenate operator. Conversion between pointers and offsets is discussed in the section Locator Data.
The following table shows the specific conversions described in this chapter.
| Data Type | Conversion |
|---|---|
| Arithmetic | Arithmetic to Arithmetic
Arithmetic to Bit string Arithmetic to Character string |
| String | Bit string to Arithmetic
Bit string to Character string Character string to Arithmetic Character string to Bit string Format Controlled |
| Pictured | Pictured to Arithmetic
Pictured to Bit string Pictured to Character string Conversion to Pictured Data |
The CEIL function used in many of the conversion rules gives the smallest integer that is greater than or equal to the function's argument. For example,
CEIL(1.1)
produces the value two.
Arithmetic to arithmetic conversion assigns any arithmetic data type to any other arithmetic data type. This type of conversion occurs most frequently as a result of using operands of differing arithmetic types in an arithmetic or relational operation. In all cases, the target base and scale are supplied by the conversion rules of the operator or built-in function, but the target precision is not supplied.
If a target precision is not supplied, it is determined from the data type of the source value (listed vertically) and the target base and scale (listed horizontally), as shown in Table 7-1.
| Target Base And Scale, Precision r[,s] | Source Base And Scale, Precision p[,q] | |||
|---|---|---|---|---|
| Fixed Binary | Fixed Decimal | Float Binary | Float Decimal | |
| Fixed Binary | r = p | r = MIN(CEIL (p*3.32)+1,n) | * | * |
| Fixed Decimal | r= MIN(CEIL(p/3.32)+1, n) | r= p | * | * |
| Float Binary | s=0
r =MIN(p,n) | s = q
r= MIN (CEIL(p*3.32),n) | r= p | r=MIN(CEIL(p*3.32),n) |
| Float Decimal | r=MIN (CEIL(p/3.32),n) | r=MIN(p,n) | r = MIN (CEIL(p/3.32),n) | r= p |
| * | These conversions arise only in cases where the target precision is explicitly known, as in the case of assignment to a fixed-point variable. | |||
| n | The maximum number of digits allowed by Open PL/I for the target base and scale. For precision limits, see your Open PL/I User's Guide. | |||
Conversion of a fixed-point decimal value containing a fraction to floating-point or vice versa produces an approximate value. The result is the number in the target scale and precision that is closest to the source value and is produced by rounding at the last binary or decimal digit position.
Conversion of a fixed-point decimal value containing a fraction to a fixed-point value with no fraction or fewer fractional digits results in truncation of excess digits without rounding. Rounding can be performed by using the ROUND, CEIL, FLOOR, or TRUNC built-in functions, as described in the chapter Open PL/I Built-ins.
If the target precision does not provide sufficient digits to hold all integral digits of the converted value, the program is in error. This error is not detected by Open PL/I and may or may not be detected by another implementation of PL/I. If detected, the ERROR condition is signaled. If undetected, the program produces unpredictable results. Programs that contain this undetected error and produce "correct" results may fail when moved to another implementation of PL/I.
The following shows the target precisions given, in Table 7-1, for some common source values and target data types. Note that for some implementations, the target precision may be limited to a value smaller than what is shown here.
| Source | Target |
|---|---|
| Fixed Binary(15) | Fixed Decimal(6,0) |
| Fixed Binary(31) | Fixed Decimal(11,0) |
| Float Binary(21) | Float Decimal(7) |
| Float Binary(52) | Float Decimal(16) |
| Fixed Decimal(4) | Fixed Binary(15) |
| Fixed Decimal(7) | Fixed Binary(25) |
| Float Decimal(6) | Float Binary(20) |
| Float Decimal(15) | Float Binary(50) |
Arithmetic to bit-string conversion converts the absolute value of an arithmetic value to a bit string, but may not produce the result you expect.
The arithmetic source value is first converted to fixed binary(K) where K is determined by the source data type, as shown in the following table.
| Source Data Type | Value of K |
|---|---|
| Fixed Decimal(P,Q) | MIN(N,MAX(CEIL((P-Q)*3.32),0)) |
| Float Decimal(P) | MIN(N,CEIL(P*3.32)) |
| Fixed Binary(P) | (P) |
| Float Binary(P) | MIN(N,P) |
The absolute value of the resulting integer is considered to be a bit string of length K. If the context that caused the conversion supplied a target length, this bit string is extended on the right with zero bits to make it the length of a longer target, or excess bits are truncated from the right to make it the length of a shorter target. The program is in error and may produce unpredictable results if the value of the source is too large to be converted to an integer of precision (K). For example, if V is a Fixed Binary(15) variable with the value of 5, its value when converted to a bit string of length 15 is '000000000000101'B. If the target is Bit(16), the result is '0000000000001010'B, because padding occurs on the right. If the target is Bit(5), the result is '00000'B, because all excess bits are truncated from the right.
Arithmetic to character-string conversion often arises during list-directed stream output, concatenation, or during assignment to a character string.
The arithmetic source value is first converted to a decimal value having the same scale as the source and with a decimal precision determined by the target precision data shown in Table 7-1.
The decimal value whose precision is now (p,q) is then converted to a character string whose value is given by one of the following cases:
If the decimal value is floating-point, the length of the resulting character string is p+n+4, and its value consists of a minus if the value is negative or a blank if it is not negative, followed by the most significant digit of the mantissa, followed by a decimal point, followed by p-1 digits of the mantissa, followed by the letter E, followed by the sign of the exponent, followed by n exponent digits. The number of exponent digits depends on the implementation, but is constant for a given implementation. In Open PL/I, three exponent digits are produced.
The values in the above examples could result from conversion of a Float Binary(21) value. Seven digits are produced, because Float Binary(21) converts to Float Decimal(7). For more information, see the Table 7-1.
If the decimal value is fixed-point with no fraction (q=0), the length of the resulting character string is p+3, and its value consists of sufficient blanks to fill the p+3 character result, followed by a minus if the value is negative, followed by the p digits of the decimal value with no leading zeros (the value zero has one zero digit).
The values in the previous examples could result from conversion of a Fixed Binary(15) value. The result is nine characters long, because Fixed Binary(15) converts to Fixed Decimal(6), and the result is 6+3 characters long.
If the decimal value is fixed-point with a fraction (q^=0), the length of the resulting character string is p+3, and its value consists of leading blanks (if needed to fill the p+3 character result) followed by a minus if the value is negative, followed by p-q integral digits with no leading zeros (fractions and the value zero have one integral zero digit), followed by a decimal point, followed by q fractional digits.
The values in the previous examples could result from converting a Fixed Decimal(5,2) value.
The extra three characters produced for fixed-point values are intended to allow room for a sign, a zero, and a decimal point.
Bit-string to arithmetic conversion assigns a bit string to any arithmetic data type.
Bit-string to arithmetic conversion produces reasonable results and permits bit strings to be used to hold positive integers. However, because arithmetic operators require arithmetic operands, the BINARY or DECIMAL built-in function should be used to produce an explicit conversion of a bit-string value to a binary or decimal integer value.
The conversion is invalid if the length of the source bit string exceeds N where N is the maximum precision allowed by the implementation for fixed-point binary values. For the maximum precision allowed by Open PL/I, see your Open PL/I User's Guide.
If no target base or scale is given by the context that caused the conversion, fixed binary is supplied by default. If a target precision is not given, the maximum precision allowed for the target base and scale is supplied.
The rightmost bit of the source value is considered to be the units position of a positive binary integer value of precision p, where p is the length of the source bit-string value. The value of that binary integer is then converted to conform to the base, scale, and precision of the target using the normal rules for arithmetic to arithmetic conversion given in the section Arithmetic to Arithmetic Conversion. A null bit-string value converts to zero, as shown in the following examples.
| Source | Result |
|---|---|
| '101'B | 5 |
| "B | 0 |
| '0000'B | 0 |
Bit-string to character-string conversion converts a bit-string value to a character-string value of the same length as the bit string. Each bit of the bit string is converted to a 0 or 1 character in the resulting character string. A null bit string is converted to a null character string.
| Source | Result |
|---|---|
| '0'B | '0' |
| "B | " |
| '1011'B | '1011' |
If the context that caused the conversion gives a target length, the character string is truncated to conform to a shorter target or is padded on the right with blanks to conform to a longer target.
Character-string to arithmetic conversion converts a character string to any arithmetic data type.
If the context that caused the conversion does not give a target base or scale, fixed or decimal is supplied by default. If it does not supply a target precision, the maximum precision allowed by the implementation for the target base and scale is supplied. For the maximum precision allowed by Open PL/I, see your Open PL/I User's Guide.
If the source character-string value is a null string or if it contains all blanks, the value of the result is zero; otherwise, the source string must contain a valid optionally signed constant surrounded by optional blanks. The constant is converted to conform to the data type of the target using the normal rules for arithmetic to arithmetic conversion given in the section Arithmetic to Arithmetic Conversion.
| Source | Result |
|---|---|
 |
5 |
| -7 | |
| -4 | |
| 0 | |
| 0 |
The results in the previous example would be produced by converting a Character(6) source value to a fixed-point integer result value.
Character-string to bit-string conversion converts a string of 0 and 1 characters to the 0s and 1s of a bit string. A character-string source value that contains any characters other than 0 and 1, including spaces, cannot be converted to a bit-string value; any attempt to perform such a conversion results in a signal of the ERROR condition.
A character-string value is converted to a bit-string value of the same length as the character string. Each character is converted to a 0 or a 1 bit in the resulting bit string. A null character string is converted to a null bit string.
If the context that caused the conversion gives a target length (for example, assignment to a bit-string variable or use of the BIT built-in function with two arguments), the converted bit string is padded on the right with zero bits to conform to the longer target, or the rightmost excess bits are truncated to conform to a shorter target.
| Source | Result |
|---|---|
| " | "B |
| '010'S | '010'B |
| ' ' | invalid, ERROR signaled |
Format controlled conversions occur only when a format list is used by a GET or PUT statement to control the conversion of data between the program and an input or output stream, and to control positioning within those streams.
An input conversion occurs when a field of an input line is converted to a value specified by a data format. That value is then assigned to a variable given by the format list of the GET statement. If the data type of the variable differs from the data type of the value produced by the format, an additional conversion results from the assignment.
An output conversion occurs when a value given in the format list of a PUT statement is converted to an output field by a format item.
The following sections describe the five data format items that are used for input and output of data in various formats. These data format items comprise the format specifications that are included in your GET or PUT statements.
The F-Format is used for fixed-point formats, as shown in the following:
F(w) or F(w,d)
where:
w is an integer constant that specifies the width of the field
d is an integer constant that specifies the number of fractional digits in the field.
For F-Format input conversion, a field of w characters from the input line is converted to a fixed-point decimal value of precision (p,q). If the field contains a decimal point, q is the number of digits following the decimal point; otherwise, q is the value of d or is zero if d is omitted. If the field contains all blanks, the result value is zero, and p is the value of MIN(n,w) where n is the maximum precision allowed by the implementation for fixed-point decimal data. (For the maximum precision allowed by Open PL/I, see your Open PL/I User's Guide.) If the field does not consist entirely of blanks, it must contain an optionally signed fixed-point constant with optional leading and/or trailing blanks. In that case, p is the precision of the constant. If an invalid field is read, the Compiler signals ERROR.
| Field | Result | Precision |
|---|---|---|
 | 0 | (5,1) |
-700 | -70.0 | (3,1) |
 0 | 0 | (1,0) |
| 25.6 | 25 | (2,0) |
| 5E+1 | invalid |
For F-Format output conversion, an arithmetic or string value from the format list of a PUT statement is converted to a fixed-point decimal value that is then rounded and formatted as a character string of w characters containing a value with d fractional digits.
If d = 0, or if d is omitted, the source value is converted to a fixed-point decimal value with no fractional digits, and the resulting integer value is placed, right-justified, in the field of w blank characters with leading zeros suppressed. (The value zero has one zero digit.) For negative values, the first significant digit is preceded by a minus sign. If the value and its sign cannot fit in w characters, the ERROR condition is signaled.
The following results are produced by an F(4) format.
| Value | Result |
|---|---|
| 0 |  0 |
| 25 |  25 |
| -8 | -8 |
| 13.5 | 14 |
| 17.08 | 17 |
| 1000 | 1000 |
| -1000 | invalid |
If d^= 0, the source value is converted to a fixed-point decimal value with d+1 fractional digits. The value is rounded by adding 5 to the last fractional digit; the last fractional digit is then deleted. The resulting value is placed, right-justified, in a field of w characters with leading integral zero digits suppressed by blanks (fractional values and zero have one integral zero digit). The leading digit is preceded by a minus sign if the value is negative. If the value, its decimal point, and its sign cannot fit in w characters, the ERROR condition is signaled. For the maximum precision allowed by Open PL/I, see your Open PL/I User's Guide.
The following results are produced by an F(5,2) format.
| Source | Field |
|---|---|
| 0 | 0.00 |
| -1 | -1.00 |
| .005 | 0.01 |
| .0005 | 0.00 |
| 10 | 10.00 |
| -10 | invalid |
The E-Format is used for floating-point formats, as shown in the following.
E(w)
or
E(w,d)
where:
w is an integer constant that specifies the width of the field
d is an integer constant that specifies the number of fractional digits in the field. If d is omitted, d = O.
For E-Format input conversion, a field of w characters from the input line is converted to a floating-point decimal value of precision p. If the field contains a decimal point and/or an exponent, the value of d is ignored; otherwise, d indicates that the last d digits in the field are fractional digits. If a field contains all blanks, p is MIN(n,w), where n is the maximum precision allowed by the implementation for floating-point decimal values; otherwise, p is the precision of the constant contained within the field. The field must either be all blank or must contain an optionally signed fixed-point or floating-point constant preceded or followed by optional blanks.
The following results are produced by an E(6,1) format.
| Field | Result |
|---|---|
 | 0E0 |
| -1 | -0.1E0 |
| -25E10 | -25E10 |
| 7.41 | 7.41E0 |
| 150 | 15E0 |
For E-Format output conversion, an arithmetic or string value from a PUT statement's list is converted to a floating-point decimal value and placed, right-justified, in a field of w blanks.
The result field contains a minus sign if the value is negative, followed by the most significant digit of the mantissa, followed by a decimal point, followed by d digits of the mantissa (if d is omitted, it is taken to be p-1), followed by the letter E, followed by the sign of the exponent, followed by n exponent digits, where n is an implementation defined constant. For the maximum precision allowed by Open PL/I, see your Open PL/I User's Guide.
If the value and its sign cannot fit in w characters, the ERROR condition is signaled.
The following results are produced by both forms of the E-format.
| Value | Format | Field |
|---|---|---|
| 0 | E(10,3) | 0.000E+000 |
| -15 | E(10,3) | -1.500E+001 |
| 12345678 | E(10,3) | 1.234E+0 07 |
| 7.3E-10 | E(10,3) | 7.300E-010 |
| 0 | E(14) | 0.000000 E+000 |
| -25 | E(14) | -2.500000E+001 |
The last two examples assume that the precision of the value to be converted is 7, giving a default value of 6 for d.
The A-Format is used for character-string formats, as shown in the following:
A or A(w)
where w is an integer constant that specifies the width of a field.
For A-Format input conversion, w must be specified (unless the A-Format is used to read a variable-length line, as explained below). The result is a character string containing the next w characters from the input stream file.
The A-Format is used without a field width to read a variable-length line. The A-Format reads the content of the current line, starting with the current column and ending with the end of the line, then sets the column position so that the next operation will read a new line.
For A-Format output conversion, an arithmetic or string value given by the PUT statement's format list is converted to a character string using the normal rules for conversion to character string. If w is omitted, it is taken to be the length of the character string. The string is placed, left-justified, in a field of w blanks.
The B-Format is used for bit-string formats, as shown in the following:
B or B(w) B1 or B1(w) B2 or B2(w) B3 or B3(w) B4 or B4(w)
where w is an integer constant that specifies the width of a field.
For B-Format input conversion, w must be specified. The next w characters from the input stream are converted to a bit string, just as if they had appeared in a bit-string constant that was followed by B, B1, B2, B3, or B4. For a list of the valid characters and their translation to bits, see Table 7-2. If the field of w characters contains an invalid character (including blank), the ERROR condition is signaled.
For B-Format output conversion, an arithmetic or string value given by the PUT statement's format list is converted to a bit string using the normal rules for conversion to bit strings. The resulting bit string is then padded on the left with sufficient zero bits to make it a multiple of k bits in length, where kis the 1, 2, 3, or 4 following the B in the format code. The padded bit string is then converted to a character string of length n, where n is the length of the padded string divided by k. (All k bits are converted to one character, as shown in Table 7-2.) If w is omitted, w is the length of the character string. The character string is right-justified in a field of w blanks. w must be sufficient to hold all of the characters in the string.
The following results are produced by the various forms of the B-Format.
| Value | Format | Field |
|---|---|---|
| '00'B | B | 00 |
| '1'B | B(4) | 1 |
| "B | B(4) | |
| '1101'B | B2(2) | 31 |
| '110101'B | B3(2) | 65 |
| '10011101'B | B4(2) | 9D |
| '10111'B | B2(4) | 113 |
The P-Format is used for the input or output of data in a pictured format.
P 'picture'
where picture must be a valid picture as described in the section Picture Data.
For P-Format input, the next field of w characters is assigned as a pictured value to the variable in the GET statement's format list. The number of characters, w, is the number of characters in the picture, excluding any V characters.
For P-Format output conversion, an arithmetic or string value from the PUT statement's format list is converted to a fixed-point decimal value described by the picture. The decimal value is then edited into an output field of w characters as if an assignment had been made to the pictured field. For a discussion of picture controlled conversion, see the section Conversion to Pictured Data.
When a pictured value is converted to an arithmetic value, it is first converted to a fixed-point decimal value whose precision is determined by the picture, as described in the section Picture Data.
If the context that caused the conversion specified a different data type, the fixed-point value is converted to another value that conforms to the required data type using the normal rules for arithmetic to arithmetic conversion.
Pictured data is converted to bit-string data by first converting the pictured value to a fixed-point decimal value and then converting the decimal value to a bit string using the rules given previously in the section Arithmetic to Bit-String Conversion.
Pictured data is character-string data and is not converted when used in a context that expects character-string data.
When an arithmetic or string value is converted to a pictured value, it is first converted to a fixed-point decimal value described by the picture, as explained in the section Picture Data. The decimal value is then edited into a character string of length w, where w is the number of characters in the picture, excluding any 'V' characters.
If the fixed-point decimal value described by the picture is not sufficient to retain all digits to the left of the decimal point, the program may be in error and could produce unpredictable results. Excess fractional digits are truncated.
The fixed-point decimal value is formed into the pictured result value under control of the picture edit characters, as described in Picture Data.
If the fixed-point value is zero and the picture does not contain at least one '9' character, the result is a field of w blanks or w asterisks, depending on which zero-suppression picture characters were used.
Negative values cannot be edited unless the picture contains at least one sign picture character. If this rule is violated, the ERROR condition is signaled.
| Value | Picture | Result |
|---|---|---|
| 5.2 | ZZZVZZ | 520 |
| 0.01 | ZZZVZZ | 01 |
| 0 | ZZZ | |
| 1234 | ZZZZV | 1234 |
| 12345 | 99999 | 12345 |
| 123 | 99999 | 00123 |
| -105.02 | $**,***V.99 | invalid |
| -105.02 | $**,***V.99CR | $***105.02CR |
| -75 | ––––V–– | -7500 |
| 75 | ––––V–– | 7500 |
| -20 | -999 | -020 |
| 20 | -999 | 020 |
| -275.03 | $$$$$V.99- | $275.03- |
| 25.01 | $$$$$V.99- | $25.01 |
| -7.5 | $$,$$$V.99DB |
$7.50DB |
| 0 | -****V. ** | ******** |
| 5 | -****V.** | ****5.00 |
| -75 | -****V.** | -**75.00 |
| .75 | Z.VZZ | 75 |
| .75 | ZV.ZZ | .75 |
| 0 | ZZ$ | |
Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.