Assignment of a computational value to a pictured variable is performed in the following two steps:
If PL/I cannot perform one of these steps in a meaningful fashion, an error occurs. The following examples show two programming errors that are common in assignments to pictured variables.
CREDIT = '$12443.00';
This example signals the CONVERSION condition, because the character string contains a dollar sign and cannot be converted to fixed-point decimal. The value assigned to CREDIT should be either '12443.00' or 12443.00, both of which result in the same value assigned to CREDIT.
If a negative value is assigned to a pictured variable, the picture must include one of the sign picture characters (such as DB). For example:
CREDIT = -12443.00;
When you use a pictured value in an arithmetic context (such as an assignment to an arithmetic variable), the picture is used to extract the fixed-point decimal number from the character string that internally represents the pictured value. Extraction also occurs when you input a pictured value with the GET EDIT statement and the P format item. If the contents of the pictured variable or input item do not conform to the picture, an error occurs.
DECLARE CREDIT PICTURE '$99999V.99DB';
The period and dollar sign are always inserted in the internal representation and the output value regardless of CREDIT's numeric value.
The picture character DB appears only when the value of CREDIT is less
than 0; otherwise, two spaces appear in the indicated positions. The DB
character also indicates that CREDIT's value is numerically negative,
so that if CREDIT is later assigned to an arithmetic variable the
variable will be given a negative value.
22.214.171.124 Editing by Picture
Any computational value or expression can be assigned to a pictured variable, as long as it meets these two qualifications:
When a value is assigned to a pictured variable, the value is edited to construct a character string that meets the picture specification. Editing also occurs when a value is output with the PUT EDIT statement and the P format item. Editing was performed in the previous examples in which fixed-point decimal values were assigned to the pictured variable CREDIT.
Because a picture specifies a fixed-point decimal value, the
FIXEDOVERFLOW condition is signaled in the same circumstances as for
assignment of an expression to a FIXED DECIMAL variable.
126.96.36.199 The Internal Representation of Pictured Variables
A pictured variable has the attributes of a fixed-point decimal variable, but values assigned to it are stored internally as character strings. Such a character string contains digits describing the variable's numeric value as well as special symbols. An individual picture character and its position in the picture indicate the interpretation of an associated position in the pictured value.
The picture characters fall into three categories:
Section 188.8.131.52 describes each picture character in more detail. The assignment CREDIT = 12443.00; stores data internally, as shown in Figure 3-6, as a character string where delta (<bigtriangleup symbol>) represents a space.
Figure 3-6 Internal Representation of a Pictured Variable
The assignment CREDIT = -12443.00; stores data internally as shown in Figure 3-7.
Figure 3-7 Internal Representation of a Pictured Variable
In situations that call for a character representation of a pictured data item (such as output with PUT LIST), this internal representation is used, including the nonnumeric characters. On output, the values assigned to CREDIT would look like this:
$12443.00 /* a positive value (credit) */ $12443.00DB /* a negative value (debit) */
A character string is a sequence of zero or more characters. The value of a character-string variable can consist of any DEC Multinational Character to a maximum length of 32,767 characters. The first 128 characters of the DEC Multinational Character Set are the ASCII characters. See Appendix B for the entire character set.
Every character-string variable has a length attribute that specifies either the length of all values of the variable (fixed-length strings) or the maximum length of a value of the variable (varying-length strings).
This discussion of character-string data is divided into the following parts:
A character-string constant can consist of any characters in the DEC Multinational Character Set (see Appendix B). When you use character-string constants in a program, you must enclose the strings in apostrophes, as shown in the following examples:
'Total is:' 'Enter your name and age' 'Error - value is out of range'
To specify a string containing a literal apostrophe, use two apostrophes within the string. For example:
'Life isn''t fair'
When a character string that has embedded apostrophes is specified as previously shown, the final result contains only a single apostrophe.
Note that the quotation mark (") is not a legal delimiter for PL/I
184.108.40.206 Replication of String Constants
You can use a replication factor to replicate character-string and bit-string constants in any context of the program. A replication factor is an unsigned integer constant that specifies the number of times a simple string constant is replicated to produce a resulting string constant. For example:
In this example, the string is repeated four times. The character constant resulting from this specification is equivalent to:
'season season season season '
You can use a replication factor in combination with the iteration factor in INITIAL. For example, the following two statements are equivalent:
INITIAL ((10)('ABCABC')) INITIAL ((10)((2)'ABC'))
The first example uses an iteration factor exclusively, but the second
example combines an iteration factor of 10 with a replication factor of
2. Note that an extra set of parentheses is required to separate the
iteration factor from the replication factor and the character string.
3.3.2 Character-String Variables
The CHARACTER keyword identifies a variable as a character-string variable in a declaration. The format for specifying a character-string variable is:
The CHARACTER keyword identifies a character-string variable in a declaration.
The addition of the VARYING attribute indicates a varying-length character-string variable.
An optional number in parentheses specifies the length of the variable, that is, the number of bytes needed to contain its value (maximum is 32,767). This length attribute specifies either the length of all values of the variable (fixed-length strings) or the maximum length of a value of the variable (varying-length strings). If the length is not specified, PL/I uses the default length of one character, or byte. The rules for specifying the length are:
If specified, n must immediately follow the keyword CHARACTER and must
be enclosed in parentheses.
220.127.116.11 Fixed-Length Character-String Variables
A fixed-length character string is one that does not have the VARYING attribute. For a particular allocation of a fixed-length character-string variable, all its values have the same length. When a program assigns a value to a fixed-length character-string variable, however, the value does not need to have the same length defined for the variable. Depending on the size of the value, PL/I adjusts the assignment length according to the following rules:
DECLARE STRING CHARACTER (10); STRING = 'ABCDEF';
DECLARE STRING CHARACTER (4); STRING = 'ABCDEF';
PL/I stores fixed-length character string data in a contiguous sequence
of bytes with the leftmost character occupying the lowest memory
18.104.22.168 Varying-Length Character-String Variables
When you define a character-string variable, you can also specify the VARYING attribute. In a varying character-string variable, the length is not fixed. The length specified in the declaration of the variable defines the maximum length of any value that can be assigned to the variable. Each time a value is assigned, the current length changes. For example:
DECLARE NAME CHARACTER (20) VARYING; NAME = 'COOPER'; NAME = 'RANDOM FACTOR';
The declaration of the variable NAME indicates that the maximum length of any character-string value it can have is 20. The current length becomes 6 when NAME is assigned the value 'COOPER'; the length becomes 13 when NAME is assigned the value 'RANDOM FACTOR'; and so on.
When a varying character string is assigned a value with a length greater than the maximum defined, the value is truncated on the right.
The initial length of an automatic varying-length character-string variable is undefined unless the variable is initialized.
You can use the LENGTH built-in function to determine the current
length of any string, and the MAXLENGTH built-in function to determine
the maximum length.
22.214.171.124 Internal Representation of Varying Character Data
A varying-length character string consists of a word specifying the
string's current length, followed by a sequence of bytes in
sequentially higher memory addresses.
3.3.3 Alignment of Character Strings
The PL/I language makes a distinction between aligned and unaligned (fixed-length) character-string variables. (No such distinction is made for varying character strings or for character-string constants.) A character-string variable is aligned if it is declared with the ALIGNED attribute.
This distinction affects only argument passing. If a procedure declares a parameter as ALIGNED CHARACTER, and if the corresponding argument is an unaligned character-string variable or vice versa, the actual argument will be a dummy variable. For example:
DECLARE GETSTRING ENTRY (CHARACTER (*) ALIGNED); DECLARE STRING CHARACTER (8); CALL GETSTRING (STRING);
PL/I constructs a dummy variable here to pass the unaligned string variable STRING to the called procedure GETSTRING, rather than passing the actual argument by reference.
All character strings on the VAX and Alpha hardware
are aligned on byte boundaries. You should not use the ALIGNED
attribute to declare character-string variables.
3.4 Bit-String Data
A bit string consists of a sequence of binary digits, or bits. It can be used as a Boolean value, which has one of two states: true (if any bit is non-zero) or false (if all bits are 0).
Like a fixed-length character string, a bit string has a fixed length defined in the declaration or specified by the number of bits in a bit-string constant. The maximum length of any bit string is 32,767 bits. However, bit-string variables cannot be declared with the VARYING attribute.
The rest of this section discusses bit-string constants and variables, alignment of bit-string data, and the use of bit strings to represent integers.
This discussion of bit-string data is divided into the following parts:
To specify a bit-string constant, enclose the string in apostrophes and follow the closing apostrophe with the letter B. For example:
'0101'B '10101010'B '1'B
The length of a bit-string constant is always the number of binary digits specified; the B does not count in the length of the string. You can specify a bit-string constant with a maximum of 1000 characters between the apostrophes.
You can also specify a bit-string constant using the following syntax:
nIs the number of bits to be represented by each digit in the string. n can have the value 1 through 4, and if not specified defaults to 1.
This format allows you to specify bit-string constants with bases other than 2. You can use base 4, 8, and 16, where n equals 2, 3, and 4 respectively. For example:
'EF8'B4 '117'B3 '223'B2
These constants specify the hexadecimal value EF8, the octal value 117, and the base 4 value 223. All such constants are stored internally as bit strings, not as integer representations of the value.
The valid characters for each type of bit-string constant are as follows:
Using the B format items, you can also acquire or output (with the GET
EDIT and PUT EDIT statements) bit-string data in binary, base 4, octal,
or hexadecimal format. See Section 126.96.36.199 for more information on the B
188.8.131.52 Replication Factor for Bit-String Constants
A replication factor is an unsigned integer constant that specifies the number of times a simple bit-string constant is replicated. A replication factor permits repetition of bit strings in any context where a simple string constant is permissible, including format items and assignment, string, and arithmetic operations. The format of a replication factor is as follows:
rAn unsigned integer that represents the number of times that the string is to be replicated.
stringA simple bit string constant to be replicated. The bit string is enclosed in apostrophes.
An example of replication is:
DECLARE (A) BIT (800); A = (400) '2'B2; PUT SKIP LIST ((A)); END;
In this example, A will be replicated to its maximum specified length of 800 characters.
The resulting character constant looks like this:
'10101010101010101010101010101010 . . . 10101010101010101010101010'B
You can use the replication factor in combination with the iteration factor in INITIAL. For example, the following two statements are equivalent:
INITIAL ((10)('ABCABC'B4)) INITIAL ((10)((2)'ABC'B4))
The first statement uses an iteration factor exclusively; the second
statement combines an iteration factor of 10 with a replication factor
of 2. An extra set of parentheses is required to separate the iteration
factor from the replication factor and the bit string.
3.4.2 Bit-String Variables
Use the BIT attribute to declare a bit-string variable. The format is:
DECLARE variable-name BIT [(length)];
You can optionally specify the length of the variable in parentheses. The length can be from 0 to 32,767; the default length is one bit. The rules for specifying the length are as follows:
A program can assign to a bit-string variable a value larger or smaller than the variable's defined length. In such cases, PL/I does the following:
You can convert bit-string variables to other data types; however,
there are some precautions you must observe if you do so. Section 6.4
describes how to convert bit-string variables.
3.4.3 Alignment of Bit-String Data
PL/I distinguishes between aligned and unaligned bit-string variables. (Bit-string constants are always unaligned.) A bit-string variable is aligned only if it is declared with the ALIGNED attribute, as shown in the following example:
DECLARE FLAGS BIT (8) ALIGNED;
If the default packed alignment is in effect, PL/I allocates storage for an aligned bit-string variable on a byte boundary and reserves an integral number of bytes to contain the variable. If natural alignment is in effect, PL/I allocates storage for an aligned bit-string variable on a longword boundary and reserves an integral number of longwords to contain the variable. See the PL/I for OpenVMS Systems User Manual for more information on the /ALIGN and /DATA command line qualifiers, which affect what type of alignment is in effect.
Unaligned bit-string variables always occupy only as many bits as are needed to contain them. They need not be on byte boundaries. You can optionally specify the UNALIGNED attribute in a declaration; UNALIGNED is the default for bit strings.
In general, operations involving unaligned bit-string variables are less efficient than those involving aligned bit-string variables. Unaligned bit-string variables are also invalid as the targets of the FROM and INTO options of record I/O statements, and as the argument of the ADDR built-in function. Moreover, most non-PL/I programs that accept bit-string arguments require the strings to be aligned.
In most cases, you should declare bit-string variables with the ALIGNED attribute. Use unaligned bit-string variables when bit strings must be packed as tightly as possible, for example, in arrays and in structures. See Section 2.2.1 for a description of the ALIGNED attribute.