Assignment of a computational value to a pictured variable is performed in the following two steps:

1. The value is converted to fixed decimal, with precision and scale as specified by the picture.
2. The resulting fixed decimal value is edited into the pictured variable.

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;

If the picture of CREDIT did not contain the DB characters, this assignment would signal the FIXEDOVERFLOW condition, because the sign would be lost. In some circumstances (for example, with the READ statement), it is possible to assign a value to a pictured variable that is not valid with respect to the variable's picture specification. In such cases, you can use the VALID built-in function to validate the contents of the variable.

3.2.5.3 Extracting Values from Pictured Data

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.

For example:

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

In the picture for CREDIT, the 9 character specifies the position of a decimal digit; because the picture contains seven of these, the fixed-point decimal precision of CREDIT is 7. The V character separates the integral and fractional digits; because there are two 9 characters to the right of the V, the scale factor of CREDIT is 2. Because the V character specifies only a numeric property, a period picture character (.) is included after the V to ensure that the output value has a decimal point in the correct place.

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.

3.2.5.4 Editing by Picture

Any computational value or expression can be assigned to a pictured variable, as long as it meets these two qualifications:

• The value either is a fixed-point decimal value or can be converted to a fixed-point decimal value.
• The fixed-point decimal value can be represented with the precision and scale factor of the picture specified for the target pictured variable.

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.

3.2.5.5 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:

• Characters that do not affect internal representation. The decimal place character (V) is the only one in this category.
• Characters that affect both the numeric interpretation and internal representation of the value. These characters indicate how the digits of the numeric value should be placed in the string and where to place a sign as follows:
  • The digit characters (9, Z, *, Y)
  • The encoded-sign characters (T, I, R)
  • The drifting characters ($, +, -, S)
• Characters that affect only the internal representation of the value. These characters appear in the internal characters string as follows:
  • The insertion characters (comma, period, slash, space)
  • The credit (CR) and debit (DB) characters

Section 3.2.5.1 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) */

3.3 Character-String Data

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:

• Constants
• Variables
  • Fixed-length character strings and their internal representation
  • Varying-length character strings and their internal representation
• Alignment of character strings

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 character constants.

3.3.1.1 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:

(4)'season '

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:

• For a static variable declaration, the length must be an integer constant.
• In the declaration of a parameter or returns descriptor, you can specify the length as an integer constant or as an asterisk (*). The resulting string is fixed length unless VARYING is also specified.
• For an automatic, based, or defined variable, you can specify the length as an integer constant or as an expression. In the case of automatic or defined variables, the expression must not contain any variables or functions that are declared in the same block, except for parameters.
• The maximum length in any declaration is 32,767.

If specified, n must immediately follow the keyword CHARACTER and must be enclosed in parentheses.

3.3.2.1 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:

• If the value is smaller than the length of the character string, PL/I pads the character string with spaces on the right. For example:

  DECLARE STRING CHARACTER (10); STRING = 'ABCDEF';

  
  The final value of the variable STRING is 'ABCDEF ', that is, the characters ABCDEF followed by four space characters.

• If the value is larger than the length of the variable, PL/I truncates the character string on the right. For example:

  DECLARE STRING CHARACTER (4); STRING = 'ABCDEF';

  
  Here, the final value of STRING is 'ABCD', that is, the first four characters of the value 'ABCDEF'.

PL/I stores fixed-length character string data in a contiguous sequence of bytes with the leftmost character occupying the lowest memory address.

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

3.3.2.4 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:

• Constants
• Variables
• Alignment
• Internal representation
• Bit strings and integers

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:

'character-string'Bn

n

Is 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:

• For B or B1, only the characters 0 and 1 are valid
• For B2, only the characters 0, 1, 2, and 3 are valid
• For B3, only the characters 0, 1, 2, 3, 4, 5, 6, and 7 are valid
• For B4, the characters 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, and F are valid (the letters A through F can be either upper- or lowercase)

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 9.2.4.2 for more information on the B format item.

3.4.1.1 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:

(r)'string'Bn

r

An unsigned integer that represents the number of times that the string is to be replicated.

string

A 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:

• If BIT is specified for a static variable declaration or in a returns descriptor, the length must be an integer constant.
• If BIT is specified in the declaration of a parameter or in a parameter descriptor, you can specify the length as an integer constant or as an asterisk (*).
• If BIT is specified for an automatic, based, or defined variable, you can specify the length as an integer constant or as an expression. In the case of automatic or defined variables, the expression must not contain any variables or functions that are declared in the same block, except for parameters.

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:

• If the assigned string is shorter than the defined length, PL/I pads the bit-string value with zeros in the direction of least significance. The less significant bits are on the right as the string is represented by PUT LIST.
• If the assigned string is longer, PL/I truncates the least significant bits from the bit-string value.

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.