Built-In Functions, Subroutines, and Pseudovariables

The ABS built-in function returns the absolute value of an arithmetic expression x. Its format is:

ABS(x)

A = 3.567;
Y = ABS(A); /* Y = +3.567 */
A = -3.567;
Y = ABS(A); /* Y = +3.567 */
ROOT = SQRT (ABS(TEMP));

The last example shows a common use for the ABS built-in function: to ensure that an expression has a positive value before it is used as an argument to the square root (SQRT) built-in function.

The ACOS built-in function returns a floating-point value that is the arc (inverse) cosine of an arithmetic expression x. The arc cosine is computed in floating point. The returned value is an angle w such that:

0 < = w <=p

The absolute value of x, after its conversion to floating point, must be less than or equal to 1. The format of the function is:

ACOS(x)

The ADD built-in function returns the sum of two arithmetic expressions x and y, with a specified precision p and an optionally specified scale factor q. The format of the function is:

ADD(x,y,p[,q])

The ADDR built-in function returns a pointer to storage denoted by a specified variable. The variable reference must be addressable. The format of the function is:

ADDR(reference)

If the reference is to a parameter (or any element or member of a parameter), the pointer value obtained must not be used after return from the parameter's procedure invocation. (This could occur, for example, if the pointer were saved in a static variable or returned as a function value.)

The ALL built-in function takes an array as an argument and returns a bit string the length of the longest element of the referenced array. The returned string contains a one in every position where the equivalent positions in all the elements of the array exist and are ones. The format of the ALL built-in function is:

ALL(array-variable)

The ALLOCATION built-in function returns a fixed-point binary integer that is the number of existing generations of a specified controlled variable. If no generations of the specified variable exist, the function returns zero. The format of the function is:

{ ALLOCATION } (reference)
{ ALLOCN     }

DECLARE INPUT CHARACTER(10) CONTROLLED,
       A CHARACTER(3) VARYING;
               ⋮

               DO UNTIL (INPUT = 'QUIT');
                       ALLOCATE INPUT;
                       GET LIST(INPUT);
                               ⋮
                       END;
               A = ALLOCATION(INPUT);
               PUT SKIP LIST('Generations = ';A);

This example uses the ALLOCATION built-in function to return the number of generations of the controlled variable INPUT. The example illustrates how input in an interactive program can be stored on a stack for future use.

The ANY built-in function takes an array as an argument and returns a bit string the length of the longest element of the referenced array. The returned string contains a one in every position where the equivalent positions in any of the elements of the array exist and is a one. The format of the ANY built-in function is:

ANY(array-variable)

The ASIN built-in function returns a floating-point value that is the arc (inverse) sine of an arithmetic expression x. The arc sine is computed in floating point. The returned value is an angle w such that:

-p/2 < = w<= p/2

The absolute value of x, after its conversion to floating point, must be less than or equal to 1. The format of the function is:

ASIN(x)

The ATAN built-in function returns a floating-point value that is the arc tangent of an arithmetic expression y or an arc tangent computed from two arithmetic expressions y and x. The arc tangent is computed in floating point. If two arguments are supplied, they must both have nonzero values after they have been converted to floating point.

The format of the function is:

ATAN(y[,x])

The returned value represents an angle in radians.

If x is omitted, the returned value v equals arc tangent(s), such that:

-p/2 < v< p/2

Here, s is the value of expression y after its conversion to floating point.

If x is present, the returned value v equals arc tangent(s/r), such that if s >= 0 then 0 <= v <= p and if s < 0 then -p < v < 0, where s and r are, respectively, the values of expressions y and x after their conversion to floating point.

The ATAND built-in function returns a floating-point value that is the arc tangent of a single arithmetic expression y or an arc tangent computed from two arithmetic expressions y and x. The arc tangent is computed in floating point. If two arguments are supplied, they must both have nonzero values after their conversion to floating point.

The format of the function is:

ATAND(y[,x])

The floating-point value returned (which represents an angle in degrees) equals:

ATAN(y,x)*180/p

The ATANH built-in function returns a floating-point value that is the inverse hyperbolic tangent of an arithmetic expression x. After its conversion to floating point, the absolute value of the argument x must be less than 1.

The format of the function is:

ATANH(x)

The BINARY built-in function converts an arithmetic or string expression x to its binary representation, with an optionally specified precision p and scale factor q. The returned value is either fixed- or floating-point binary, depending on whether x is a fixed- or floating-point expression.

The format of the function is:

{ BINARY }(x[,p[,q]])
{ BIN    }

The result type is fixed- or floating-point binary, depending on whether the argument x is a fixed- or floating-point expression. (If the argument is a bit- or character-string expression, the result type is fixed-point binary.)

The argument x is converted to the result type, giving a value v, following the PL/I rules for conversion.

The returned value is the value v, with precision p, and scale factor q. If p is omitted (integer and floating-point arguments only), the precision of the returned value is the converted precision of x. FIXEDOVERFLOW, OVERFLOW, or UNDERFLOW is signaled if appropriate.

The BIT built-in function converts an arithmetic or string expression x to a bit string of an optionally specified length. If x is a string expression, it must consist of 0s and 1s. If the length is specified, it must be a nonnegative integer. If the length is omitted, the returned value has a length determined by the PL/I rules for conversion to bit strings.

The format of the function is:

BIT(x[,length])

The BOOL built-in function performs a Boolean operation on two bit-string arguments and returns the result as a bit string with the length of the longer argument.

The format of the function is:

BOOL(string-1,string-2,operation-string)

X = '101010'B;
Y = '110011'B;
CHECK = BOOL (X,Y,'0110'B);

The operation string is '0110'B, which defines an EXCLUSIVE OR operation. The operation is performed as follows on the corresponding bits in the strings X and Y: The leftmost bit in X is 1 and the leftmost bit in Y is 1. The truth table above specifies that when the two corresponding bits in the two strings are both 1, then bit 4 of the operation string will be the result; in this case, bit 4 of the operation string '0110'B is 0. Thus, 0 is the first bit of the value to be returned. The second bit of X is 0 and of Y is 1. The truth table specifies that when the bit in the first string is 0 and in the second string is 1, the result will be bit 2 of the operation string. Here, bit 2 of the operation string '0110'B is 1, and so 1 is the second bit of the value to be returned. The operation continues in this manner with each two corresponding bits in the strings. The value returned is '011001'B.

Figure 11.1, “Example of the BOOL Built-In Function” illustrates this example.

The BYTE built-in function returns the ASCII character whose ASCII code is the integer x; x must not be negative. The returned value is a character equivalent to BYTE(y), where y equals x modulo 256. The format of the function is:

BYTE(x)

DECLARE CHAR CHARACTER(1);
CHAR = BYTE(65);       /* CHAR = 'A' */
CHAR = BYTE(32);       /* CHAR = ' ' (space) */

This function is the same as the SIZE function. See Section 11.4.81, “SIZE”.

The CEIL function returns the smallest integer that is greater than or equal to an arithmetic expression x. Its format is:

CEIL(x)

If x is a floating-point expression, a floating-point value is returned with the same precision as x. If x is a fixed-point expression, the returned value is a fixed-point value of the same base as x and with:

precision = min(31,p -q + 1)

scale factor = 0

Here, p and q are the precision and scale factor of x.

A = 4.3;
Y = CEIL(A);   /* Y = 5 */
A = -4.3;
Y = CEIL(A);   /* Y = -4 */

The CHARACTER built-in function converts an arithmetic or string expression x to a character string of an optionally specified length. If the length is specified, it must be a nonnegative integer. If the length is omitted, the length of the returned value is determined by the PL/I rules for conversion to character strings. The format of the function is:

{ CHARACTER } (x[,length])
{ CHAR      }

CHAR: PROCEDURE OPTIONS(MAIN);

DECLARE EXPRES FIXED DECIMAL(7,5);
DECLARE OUTPUT PRINT FILE;

EXPRES = 12.34567;

OPEN FILE(OUTPUT) TITLE('CHAR2.OUT');

PUT SKIP FILE(OUTPUT)
       LIST('No length argument: ',CHARACTER(EXPRES));
PUT SKIP FILE(OUTPUT)
       LIST('Length = 4: ',CHARACTER(EXPRES,4));

END CHAR;

The program CHAR produces the following output:

No length argument:    12.34567
Length = 4:    12

In the first PUT LIST statement, CHARACTER has only one argument, so the entire string is written out. The string '12.34567' is actually preceded by two spaces; this is the case with any nonnegative number converted to a character string. In the second PUT LIST statement, CHARACTER has a length argument of 4, so the first four characters of the converted string are written out as ' 12'.

The COLLATE built-in function returns a 256-character string consisting of the ASCII character set in ascending order. Its format is:

COLLATE()

The COPY built-in function copies a given string a specified number of times and concatenates the result into a single string. Its format is:

COPY(string,count)

COPY('12',3)

This function reference returns the character-string value '121212'.

The COS function returns a floating-point value that is the cosine of an arithmetic expression x, where x represents an angle in radians. The cosine is computed in floating point. The format of the function is:

COS(x)

The COSD built-in function returns a floating-point value that is the cosine of an arithmetic expression x, where x is an angle in degrees. The cosine is computed in floating point. The format of the function is:

COSD(x)

The COSH built-in function returns a floating-point value that is the hyperbolic cosine of an arithmetic expression x. The hyperbolic cosine is computed in floating point. The format of the function is:

COSH(x)

The CURRENTSTORAGE built-in function returns a fixed binary (15) value that is the implementation-defined storage, in bytes, required by the specified variable. The format of the function is:

CURRENTSTORAGE(reference)

The returned value is a fixed bin(15) value containing the variable's actual storage size in bytes. This is the number of bytes that would be transmitted if you wrote the variable to a record file defined with the ENVIRONMENT(SCALARVARYING) option.

Some variables can have varying sizes. If the referenced variable is a varying-length string, the returned value includes the two bytes of storage allocated by PL/I to contain the current length of the string (the length-prefix) and the currently-used bytes. It does not include any unused bytes at the end of the string.

If the referenced variable is a scalar area, the returned value includes the storage used by the area control bytes and the current extent. It does not include any unused bytes at the end of the area.

However, if the referenced variable is an aggregate that contains areas or varying-length strings, the returned value includes the storage used by any control bytes and length prefixes plus the maximum lengths of the strings and the maximum sizes of the areas. This rule has one exception. If the referenced variable is a structure and the last element is a non-dimensioned area, the returned value contains only the current extent of that area, not the unused bytes at the end of the area.

The DATE built-in function returns a 6-character string in the form yymmdd, where:

Its format is:

DATE()

The date returned is the run-time date. However, if DATE is used as a preprocessor built-in function, the date returned is the compile-time date.

The DATETIME built-in function returns a 16-character string in the form ccyymmddhhmmssxx, where:

The format of the function is:

DATETIME()

The date and time returned is the run-time date and time. However, if DATETIME is used as a preprocessor built-in function, the date and time returned is the compile-time date and time.

Note that the DATETIME function is identical to the century concatenated with DATE() and TIME().

The DECIMAL built-in function converts an arithmetic or string expression x to a decimal value of an optionally specified precision p and scale factor q.

P and q, if specified, must be integer constants. P must be greater than zero and less than or equal to the maximum precision for the result type (31 for fixed-point, 34 for floating- point). If q is specified, x must be a fixed-point expression and p must also be specified; if q is omitted or has a negative value, the scale factor of the result is zero.

The format of the function is:

{ DECIMAL }(x[,p[,q]])
{ DEC     }

The result type is fixed-point or floating-point decimal, depending on whether x is a fixed- or floating-point expression. (If x is a bit- or character-string expression, the result type is fixed-point decimal.)

The expression x is converted to a value v of the result type, following the PL/I rules for conversion. The returned value is v with precision p and scale factor q. If p and q are omitted, they are the converted precision and scale factor of x. FIXEDOVERFLOW, UNDERFLOW, or OVERFLOW is signaled if appropriate.

The DECODE built-in function converts a character string representing a number to a fixed binary number. It takes two arguments: a character string and an integer expression It converts the string to an unsigned, base r integer, where r is the specified radix. The function returns a FIXED BINARY(31,0) number representing the base ten equivalent of the string.

The format of the function is:

DECODE(character-expression,radix-expression)

DECLARE (X,Y) FIXED BINARY;
X = DECODE('1010',2);
Y = DECODE('f0',16);

The fixed binary variables X and Y are given the values 10 and 240, respectively.

The DIMENSION built-in function returns a fixed-point binary integer that is the number of elements in an array dimension. Its format is:

{ DIMENSION } (reference [,dimension])
{ DIM       }

INIT: PROCEDURE (ARRAY);
DECLARE ARRAY(*) FIXED,
       I FIXED;

       DO I = 1 TO DIM(ARRAY);
               ARRAY(I) = I;
               END;

This procedure is passed a one-dimensional array of an unknown extent. The DIMENSION built-in function is used as the end value in a controlled DO statement. This DO-group assigns integral values to each element of the array ARRAY so that the first element has the value 1, the second element has the value 2, and so on to the last element of the array. (Because the array is one-dimensional, the optional second parameter is omitted and defaults to 1.)

The DIVIDE built-in function divides an arithmetic expression x by an arithmetic expression y and returns the quotient with a specified precision p and an optionally specified scale factor q. The scale factor q must be an integer following these rules:

The expressions x and y are converted to their derived types before the division is performed. If y is zero after this conversion, the ZERODIVIDE condition is signaled. The quotient has the derived type of the two arguments.

The format of the function is:

DIVIDE(x,y,p[,q])

The EMPTY built-in function returns an empty area value for use in initializing areas. Its format is:

EMPTY()

The EMPTY built-in function is useful in initializing the contents of an area. Note that an area value must be assigned to an area before the area is used.

The following is an example of its use in a declaration:

DECLARE A AREA(1024) STATIC INITIAL(EMPTY());

The ENCODE built-in function converts a decimal integer to a character string. It converts the decimal integer (stored as a FIXED BINARY(31,0) number) to a base r number, where r is the radix you specify, and returns the resulting number as a character string. The function takes two arguments: a decimal integer and a radix; the radix is an integer in the range 2 through 16.

The format of the function is:

ENCODE(integer-expression,radix-expression)

DECLARE (X,Y) CHARACTER(5) VARYING;
X = ENCODE(53,8);
Y = ENCODE(10,2);

The character-string variable X is assigned the value '65', which is the character equivalent of the octal number 65, which is the equivalent of the decimal number 53. The character-string variable Y is assigned the value '1010', which is the character equivalent of the binary number 1010, which is the equivalent of the decimal number 10.

The ERF built-in function returns a floating-point value that is an approximation of the error function of x. The format of the function is:

ERF(real-expression)

The returned value has the base and precision of the real-expression, and the following value:

The ERFC built-in function returns a floating-point value that is an approximation of the complement of the error function of x. The format of the function is:

ERFC(real-expression)

The returned value has the base and precision of the real-expression, and the following value:

1 - ERF(real-expression)

The ERROR preprocessor built-in function returns the number of preprocessor diagnostic error messages issued during compilation up to that particular point in the source program. The format for the ERROR built-in function is:

ERROR();

The function returns a fixed-point result representing the number of compile-time warning messages that were issued up until the point at which the built-in function was encountered.

The EVERY built-in function determines whether every bit in a bit string is '1'B. In other words, it performs a logical AND operation on the elements of the bit string. The format of the function is:

EVERY(bit-string)

The function returns the value '1'B if all bits in the bit-string argument are '1'B. It returns '0'B if one or more bits in the argument are '0'B or if the argument is the null bit string.

The EXP built-in function returns a floating-point value that is the base e to the power of an arithmetic expression x. The computation is performed in floating point. The format of the function is:

EXP(x)

The FIXED built-in function converts an arithmetic or string expression x to a fixed-point arithmetic value with a specified precision p and, optionally, a scale factor q.

The format of the function is:

FIXED(x,p[,q])

The result type is fixed-point binary or decimal, depending on whether x is binary or decimal. (If x is a bit string, the result type is fixed-point binary; if x is a character string, the result type is fixed-point decimal.)

The expression x is converted to a value v of the result type, following the PL/I rules. The returned value is v with precision p and scale factor q. If q is omitted, the returned value has the converted precision of x and a scale factor of zero. FIXEDOVERFLOW is signaled if appropriate.

The FLOAT built-in function converts a string or arithmetic expression x to floating point, with a specified precision p. The precision p must be an integer constant that is greater than zero and less than or equal to the maximum precision of the result type, which is 15 for floating-point decimal data and 53 for floating-point binary data

If x is a character string, it can contain any series of characters that describes a valid arithmetic constant. That is, the character string can contain any of the numeric digits 0 through 9, a plus (+) or minus (-) sign, a decimal point (.), and the letter E. If the character string contains any invalid characters, the CONVERSION condition is signaled. The format of the FLOAT function is:

FLOAT(x,p)

The result type is floating-point binary or decimal, depending on whether x is a binary or decimal expression. (If x is a bit-string expression, the result type is floating-point binary; if x is a character-string expression, the result type is floating-point decimal.)

The expression x is converted to a value of the result type, following the PL/I conversion rules, and of the specified precision. UNDERFLOW or OVERFLOW is signaled if appropriate.

The FLOOR built-in function returns the largest integer that is less than or equal to an arithmetic expression x. The format is:

FLOOR(x)

If x is a floating-point expression, the returned value is a floating-point value. If x is a fixed-point expression, the returned value is a fixed-point value with the same base as x and with the following attributes:

precision = min(31,p - q + 1)

scale factor = 0

Here, p and q are the precision and scale factor of x.

For example:

FLOOR_DEMO: PROC OPTIONS(MAIN);
       PUT LIST (FLOOR(3));
       PUT LIST (FLOOR(-3.323));
       PUT LIST (FLOOR(3.456E9));
END;

This program prints the following values:

3      -4      3.456E+09

The HBOUND built-in function returns a fixed-point binary integer that is the upper bound of an array dimension. The format is:

HBOUND(reference[,dimension])

The HIGH built-in function returns a string of specified length that consists of repeated appearances of the highest character in the collating sequence. The format is:

HIGH(length)

The string returned is of the length specified. The rank of the highest character that can appear in the collating sequence for PL/I is ASCII DEL (value 255).

The INDEX built-in function returns a fixed-point binary integer that indicates the position of the leftmost occurrence of a specified substring within a string. If the substring is not found, or if the length of either argument is zero, the INDEX function returns zero. This function is case-sensitive.

The format of the function is:

INDEX(string,substring[,starting-position])

The INFORM preprocessor built-in function returns the number of diagnostic informational messages issued during compilation up to that point in the source program. The format for the INFORM built-in function is:

INFORM();

The function returns a FIXED result representing the number of compile-time warning messages that were issued up until the INFORM built-in function was encountered.

The INT built-in function treats specified storage as a signed integer, and returns the value of the integer. The format is:

INT(expression[,position[,length]])

The value returned by INT is of the type FIXED BINARY (31). If the field has a length of zero, INT returns zero.

The following example shows the use of the INT built-in function to interpret the storage occupied by a bit string as an integer:

B16 = '0000000000001101'B;     /* 16-bit string */

I = BIN(B16);                                  /* I = 13 */
I = INT(B16);                                  /* I = -20480 */

B64 = '5076ABCD00000000'B4;    /* 64-bit string */



I = INT(B64,1,32);                                     /* First 32 bits; I = -1277858294 */
I = INT(B64,33);                                       /* Second 32 bits; I = 0 */
I = INT(B64);                                  /* Field too large, run-time error */

Notice that, unlike the BIN built-in function, the INT built-in function performs no conversion. It simply treats the contents of the designated storage as a signed integer. Therefore, the value returned by INT depends on the data type (and therefore the internal representation) of the variable occupying the storage. For example:

INTEXM: PROCEDURE OPTIONS (MAIN);

DECLARE D FIXED DECIMAL (3,2),
               C CHARACTER (4),
       F FLOAT;


       D = 2.54;
       C = '2.54';
       F = 2.54;

       PUT SKIP LIST ( INT(D),
                       INT(C),
                       INT (F) );

       END;

The output of this example is:

19493                  875900466                       -1889779422

The LBOUND built-in function returns a fixed-point binary integer that is the lower bound of an array dimension. The format is:

LBOUND(reference[,dimension])

The LENGTH built-in function returns a fixed-point binary integer that is the number of characters or the number of bits in a specified character- or bit-string expression. If the string is a varying-length character string, the function returns its current length. (To determine the maximum length of a varying-length character string, use the MAXLENGTH built-in function.)

The format of the function is:

LENGTH(string)

The LINE preprocessor built-in function returns the line number of the source program text containing the end of the preprocessor statement that calls the LINE built-in function.

The format of the function within a preprocessor expression is:

LINE()

The LINENO built-in function returns a FIXED BINARY(15) integer that is the current line number of the referenced print file. The format is:

LINENO(reference)

If the referenced print file is closed, the returned value is the last value from the previous opening. If the file was never opened, the returned value is zero.

The LOG built-in function returns a floating-point value that is the base e (natural) logarithm of an arithmetic expression x. The computation is performed in floating point. The expression x must be greater than zero after its conversion to floating point.

The format of the function is:

LOG(x)

The LOG10 built-in function returns a floating-point value that is the base 10 logarithm of arithmetic expression x. The computation is performed in floating point. The expression x must be greater than zero after its conversion to floating point.

The format of the function is:

LOG10(x)

The LOG2 built-in function returns a floating-point value that is the base 2 logarithm of an arithmetic expression x. The computation is performed in floating point. The expression x must be greater than zero after its conversion to floating point.

The format of the function is:

LOG2(x)

The LOW built-in function returns a string of specified length that consists of repeated appearances of the lowest character in the collating sequence. The format is:

LOW(length)

The string returned is of the length specified. The rank of the lowest character that can appear in the collating sequence for PL/I is ASCII NUL (value 0).

The MAX built-in function returns the larger of two arithmetic expressions x and y. The format of the function is:

MAX(x,y)

The expressions x and y are converted to their derived type before the operation is performed (for a discussion of derived types see Section 6.4.2, “Derived Data Types for Arithmetic Operations”. If the derived type is floating point, the value returned is also floating point, with the larger precision of the two converted arguments. If the derived type is fixed point, the returned value is a fixed-point value with the base of the derived type. The value has the following attributes:

precision = min(31,max(px - qx,py - qy) + max(qx,qy))

scale factor = max(qx,qy)

Here, px,qx and py,qy are the converted precisions and scale factors of x and y, respectively.

The MAX built-in function is also a preprocessor built-in function; however, the preprocessor does not permit scale factors.

The MAXLENGTH built-in function returns a fixed binary number representing the maximum possible length of a varying-length character string. The format is:

MAXLENGTH (string)

The MIN built-in function returns the smaller of two arithmetic expressions x and y. The format is:

MIN(x,y)

The expressions x and y are converted to their derived type before the operation is performed (for a discussion of derived types see Section 6.4.2, “Derived Data Types for Arithmetic Operations”. If the derived type is floating point, the value returned is also floating point, with the larger precision of the two converted arguments. If the derived type is fixed point, the returned value is a fixed-point value with the base of derived type. The value has the following attributes:

precision = min(31,max(px - qx,py - qy) + max(qx,qy))

scale factor = max(qx,qy)

Here, px,qx and py,qy are the converted precisions and scale factors of x and y.

The MIN built-in function is also a preprocessor built-in function; however, the preprocessor does not permit scale factors.

The MOD built-in function returns, for an arithmetic expression x and nonnegative arithmetic expression y, the value r that equals x modulo y. That is, r is the smallest positive value that must be subtracted from x to make the remainder of x divided by y exactly 0.

The format of the function is:

MOD(x,y)

The expressions x and y are converted to their derived type before the operation is performed.

If the derived type is unscaled fixed point, then the precision of the result is the precision of the second operand.

If the derived type is floating point, the returned value is an approximation in floating point, with the larger of the precisions of the two converted arguments.

The value returned is:

u - w * floor(u / w)

The arguments u and w become the arguments x and y, respectively, after conversion to their derived type. If w is zero, u is converted to the precision described below, which can signal FIXEDOVERFLOW.

If x and y are fixed-point expressions, a fixed-point value is returned. The value has the following attributes:

precision = min(31,pw - qw + max(qu,qw))

scale factor = max(qu,qw)

Here, qu is the scale factor of u, pw is the precision of w, and qw is the scale factor of w. The FIXEDOVERFLOW condition is signaled if the following is true:

pw - qw + max(qu,qw) > 31

The MOD built-in function is also a preprocessor built-in function; however, the preprocessor does not permit scale factors.

MODEX: PROCEDURE OPTIONS(MAIN);

DECLARE OUTMOD PRINT FILE;

ON FIXEDOVERFLOW PUT FILE(OUTMOD)
                       SKIP LIST('FIXEDOVERFLOW signaled');

PUT FILE(OUTMOD) SKIP LIST(MOD(28,128));
PUT FILE(OUTMOD) SKIP LIST(MOD(130,128));
PUT FILE(OUTMOD) SKIP LIST(MOD(-28,128));
PUT FILE(OUTMOD) SKIP LIST(MOD(4.5,.758));
PUT FILE(OUTMOD) SKIP LIST(MOD(-4.5,.758));
PUT FILE(OUTMOD) SKIP LIST(MOD(1.5E-3,-1.4E-3));
PUT FILE(OUTMOD) SKIP LIST(MOD(28,0));

END MODEX;

The program MODEX writes the following output to OUTMOD.DAT:

       28
       2
       100
       0.710
       0.048
       -1.3E-03

FIXEDOVERFLOW signaled

The last PUT statement attempts to take MOD(28,0). The constants 28 and 0 are both fixed-point decimal expressions, with precisions (2,0) and (1,0), respectively. Therefore, the attributes of the returned value are determined to be FIXED DECIMAL. The value has the following attributes:

precision = min(31,1 - 0 + max(0,0)) = 1

scale factor = max(0,0) = 0

Although 28 modulo 0 is 28, MOD(28,0) signals FIXEDOVERFLOW because 28 cannot be represented in the result precision. (The value of the function is therefore undefined.)

The MULTIPLY built-in function multiplies two arithmetic expressions x and y, and returns the product of the two values with a specified precision p and an optionally specified scale factor q.

The format of the function is:

MULTIPLY(x,y,p[,q])

The NULL built-in function returns a null pointer value. The format is:

NULL()

IF NEXT_POINTER = NULL() THEN CALL FINISH;

The IF statement checks whether the pointer variable NEXT_POINTER is null; if so, the CALL statement is executed.

The NULL built-in function can be used for offset variables as well as pointer variables, because the compiler automatically performs conversions between pointer and offset values.

The OFFSET built-in function converts a pointer to an offset relative to a designated area. If the pointer is null, the result is null. The format of the function is:

OFFSET(pointer,area)

DECLARE MAP_SPACE AREA (2048),
       START OFFSET (MAP_SPACE),
       QUEUE_HEAD POINTER;
               ⋮
START = OFFSET (QUEUE_HEAD,MAP_SPACE);

The offset variable START is associated with the area MAP_SPACE. The OFFSET built-in function converts the value of the pointer to an offset value.

The ONCHAR built-in function returns the character that caused a CONVERSION condition to be raised. If there is no active CONVERSION condition, the return value is a single space.

The format of the function is:

ONCHAR()

The ONCHAR value is actually a single character substring of the ONSOURCE built-in function value, unless there is no active CONVERSION condition.

The ONCODE built-in function returns a fixed-point binary integer that is the status value of the most recent run-time error that signaled the current ON condition. You can use the function in any ON-unit to determine the specific error that caused the condition. If the function is used within any context outside an ON-unit, it returns a zero. The format is:

ONCODE()

The ONFILE built-in function returns the name of the file constant for which the current file-related condition was signaled. The format is:

ONFILE()

This built-in function can be used in an ON-unit established for any of the following conditions:

The returned value is a varying-length character string. The ONFILE function returns a null string if referenced outside an ON-unit, within an ON-unit that is executed as a result of a SIGNAL statement, or within a CONVERSION ON-unit that was not entered because of a conversion in a GET statement.

The ONKEY built-in function returns the key value that caused the KEY condition to be signaled during an I/O operation to a file that is being accessed by key. Its format is:

ONKEY()

This built-in function can be used in an ON-unit established for these conditions:

The returned key value is a varying-length character string. The ONKEY built-in function returns a null string if referenced outside an ON-unit or within an ON-unit executed as a result of the SIGNAL statement.

The ONLOC built-in function returns the hexadecimal address of the entry point used for the current invocation of the procedure in which a condition was raised. Its format is:

ONLOC

This built-in function can be used in any ON-unit or any of the dynamic descendants of an ON-unit.

The returned key value is a varying-length character string. The ONKEY built-in function returns a null string if referenced outside an ON-unit or within an ON-unit executed as a result of the SIGNAL statement.

The ONSOURCE built-in function returns the source string that was being converted when the CONVERSION condition was raised. If no CONVERSION condition is active, the return value is a null string.

The format of the function is:

ONSOURCE()

The PLIRETV built-in function returns the PL/I return code, a fixed binary (15) value. The PL/I return code is set by the PLIRETC built-in subroutine: it is zero when the program starts, and keeps the value of the most recent call to PLIRETC, in any procedure. The Sort program also sets it, to 4 before passing the first record to an output routine.

PLIRETC and PLIRETV are used chiefly with the Sort program, by the input and output routines a program passes to PLISRTB, PLISRTC and PLISRTD. A program can also use them for its own purposes, to pass a value from one procedure to another. The PL/I return code is not the program's exit status: it is not passed to the operating system when the program ends. See the Endless PL/I for POSIX Systems User's Manual for the Sort program and PLIRETC.

The format of the function is:

PLIRETV

For example, the following statements set the PL/I return code and test it:

CALL PLIRETC(8);
IF PLIRETV = 8 THEN PUT SKIP LIST ('No more records.');

The POINTER built-in function returns a pointer to the location identified by the referenced offset and area. The format is:

{ POINTER } (offset,area)
{ PTR     }

The returned value is of type POINTER. If the offset value is null, the result is null.

DECLARE MAP_SPACE AREA (2048),
       START OFFSET (MAP_SPACE),
       P POINTER;
               ⋮
P = POINTER (START,MAP_SPACE);

The POINTER built-in function converts the value of the offset variable START (in the area MAP_SPACE) to a pointer value.

The POSINT built-in function treats specified storage as an unsigned integer, and returns the value of the integer. The format is:

POSINT(expression[,position[,length]])

The value returned by POSINT is of the type FIXED BINARY (31). If the field has a length of zero, POSINT returns zero.

Because the POSINT built-in function treats storage as if it contained an unsigned integer, the value returned can be larger than the maximum positive value that can be contained in the signed integer that is stored in the same number of bits. For example, if the argument to POSINT is 32 bits long and has the high-order (sign) bit set, then the resulting value is too large for assignment to a FIXED BIN (31) variable. The result of such an operation is undefined.

The use of the POSINT built-in function is identical to the use of the INT built-in function, except that POSINT treats its argument as an unsigned integer. The following example illustrates this difference.

DECLARE (X15,Y15,I15,P15) FIXED BIN (15),
               P31 FIXED BIN (31);

       X15 = 585;
       Y15 = -585;
       I15 = INT(X15);         /* I15 = 585    */
       I15 = INT(Y15);         /* I15 = -585   */
       P15 = POSINT(X15);              /* P15 = 585    */
       P31 = POSINT(Y15);              /* P31 = 64951  */
       P15 = POSINT(Y15);              /* ERROR signaled */

In this example, POSINT first assigns the storage referenced by X15 to P15. Because this storage is occupied by a positive integer and therefore has the sign bit clear, POSINT behaves exactly like INT. However, when POSINT is applied to storage occupied by a negative integer, it interprets the set sign bit as representing part of the integer. When the resulting value is assigned to a FIXED BIN (31) variable, it is seen to be larger than the FIXED BIN (15) variable results in PL/I signaling an ERROR condition.

The PRECISION built-in function takes an input expression and returns the value converted to the specified precision. The format of the PRECISION built-in function is:

PRECISION(expression, digits [,scale]);

Any valid arithmetic expression.

An integer specifying the number of digits of precision to which the expression will be converted. It must not exceed the dialect-defined limit for the data type of the expression.

An optional integer constant less than or equal to the specified precision. The scale factor can be optionally signed. It must not exceed the dialect-defined limit for the data type of the expression. The default scale factor is zero.

Do not use a scale factor with floating point expressions.

The PROD built-in function takes an array as an argument and returns the arithmetic product of all the elements in the array. The array must have the FIXED or the FLOAT attribute. The format of the PROD built-in function is:

PROD(array-variable);

If the array has the attributes FIXED(p,0), the result will have the attributes FIXED(p,0). If the array has the attributes FLOAT(p), the result will also have the attributes FLOAT(p). If the array has the attributes FIXED(p,q) with q not equal to 0, the result will have the attributes FLOAT(p).

The result will have the same base attribute as the array, either DECIMAL or BINARY.

Note that the PROD built-in function does not perform matrix multiplication of two arrays.

The RANK built-in function returns a fixed-point binary integer that is the ASCII code for the designated character. The precision of the returned value is 15. The format of the function is:

RANK(character)

CODE = RANK('A');      /* CODE = 65 */
CODE = RANK('a');      /* CODE = 97 */
CODE = RANK('$');      /* CODE = 36 */

The ASCII characters are the first 128 characters of the DEC Multinational Character Set.

The REPEAT built-in function copies a given string a specified number of times and concatenates the result into a single string. Its format is:

REPEAT(string,count)

The REPEAT built-in function is similar to the COPY built-in function, but not exactly the same. Compare the value returned by this example to the one returned by the example for the COPY built-in function:

REPEAT('12',3)

This function reference returns the character-string value '12121212'.

The REVERSE built-in function reverses the characters or bits in a string. It takes one argument, which is either a character string (fixed or varying) or a bit string. It returns a string of the same type and size as its argument, with all the characters (bytes) or bits reversed.

The format of the function is:

REVERSE(string-expression);

DECLARE X CHARACTER(4) VARYING,
       Y BIT(8);
X = REVERSE('abc')
Y = REVERSE('00010101'B)

The character-string variable X is assigned the value `cba'. The bit-string variable Y is assigned the value '10101000'B.

The ROUND built-in function rounds a fixed-point binary decimal expression to a specified number of binary or decimal places respectively. The format is:

ROUND(expression,position)

Where the arguments are an expression of type FIXED BINARY(p,q) or type FIXED DECIMAL(p,q) and position k, the returned value is the rounded value with the following attributes:

precision = max(1,min(p - q + k + 1,31))

scale factor = k

For a fixed binary number, the rounded value is:

ROUND(x,k) = sign(x)*(2 ^-k+1 )*floor(abs(x)*(2 ^k ) + 1)

For a fixed decimal number, the rounded value is:

ROUND(x,k) = sign(x)*(10 ^-k )*floor(abs(x)*10 ^k ) + 0.5)

The following sample program shows rounding of scaled fixed binary numbers:

r: procedure options(main);

declare
       fb1 fixed binary(31, 8),
       fb2 fixed binary(31, 4),
       fb3 fixed binary(31, 2),
       fb4 fixed binary(31, 2),
       fb5 fixed binary(31, 2);

       fb1 = 16.8750; /* 7/8 */
       fb2 = 15.4375; /* 7/16 */
       fb3 = 128.25; /* 128 1/4 */
       fb4 = 128.75; /* 128 3/4 */
       fb5 = -128.75; /* -128 3/4 */

       put skip edit ('round(16.8750, 2)=',round(fb1,2))
                       (a,col(20),f(15,5));
       put skip edit ('round(16.8750, 3)=',round(fb1,3))
                       (a,col(20),f(15,5));
       put skip edit ('round(15.4375, 1)=',round(fb2,1))
                       (a,col(20),f(15,5));
       put skip edit ('round(128.25,0)=',round(fb3,0))
                       (a,col(20),f(15,5));
       put skip edit ('round(128.75,0)=',round(fb4,0))
                       (a,col(20),f(15,5));
       put skip edit ('round(-128.75,0)=',round(fb5,0))
                       (a,col(20),f(15,5));
end r;

This program produces the following output. Note that 16.87500 equals 16 7/8 in fractional notation and that 15.50000 equals 15 1/2 in fractional notation.

round(16.8750, 2)=     17.00000
round(16.8750, 3)=     16.87500
round(15.4375, 1)=     15.50000
round(128.25,0)=       128.00000
round(128.75,0)=       129.00000
round(-128.75,0)=      -129.00000

The following example shows rounding of scaled fixed decimal numbers:

A = 1234.567;
Y = ROUND(A,1);        /* Y = 1234.6   */

Y = ROUND(A,0);        /* Y = 1235     */

A = -1234.567;
Y = ROUND(A,2);        /* Y = -1234.57 */

The SEARCH built-in function takes two character-string arguments and attempts to locate the first character in the first string that is also present in the second string. The search for a match is carried out from left to right. If one character is matched, the function returns the position of that character in the first string. This function is case sensitive.

The format is:

SEARCH(string-1,string-2[,starting-position])

The returned value is a positive integer representing the position in string-1 of the first character that is also found in string-2. If no match is found, the returned value is zero.

DECLARE STR1 CHARACTER(20) VARYING,
       STR2 CHARACTER(10) INITIAL ('ABCDEFGHIJ'),
       X FIXED DECIMAL(2);
STR1 = 'BARBARA';
X = SEARCH (STR1,STR2);

In this example, X is given the value 1 because the first character (`B') in STR1 (`BARBARA') is found in STR2 (`ABCDEFGHIJ').

STR1 = '12-GEORGE';
X = SEARCH (STR1,STR2);

Here, X is given the value 4. `G' is in the fourth position in `12-GEORGE' and is the first character in STR1 that is also present in STR2 (`ABCDEFGHIJ').

X = SEARCH (STR1,STR2,6);

X is given the value 8. The starting-position parameter, 6, causes the search to begin with the sixth character in `12-GEORGE', and thus the first matching character is the second `G', which is in the eighth position.

PUT LIST (SEARCH('ZZZBAD','ABCD'));

The function returns the value 4 because the position of `B' in `ZZZBAD' is 4, and `B' is the leftmost matching character. Here, constants are used instead of variables.

PUT LIST (SEARCH('ABCD','ZZZBAD'));

This statement is the same as the preceding one except that the parameters are reversed. Now the value returned is 1 instead of 4 because `A', the first character in `ABCD', is matched. Note that the order in which the parameters are given is crucial. Note also that duplicate characters in the second string never change the result.

PUT LIST (SEARCH (' TEST 123','0123456789'));

The function returns the value 9 because `1', which is in the ninth position, is the first character matched in the second string.

The SIGN built-in function returns 1, -1, or 0, indicating whether an arithmetic expression is positive, negative, or zero, respectively. The returned value is a fixed-point binary integer.

The format of the function is:

SIGN(expression)

The SIN built-in function returns a floating-point value that is the sine of an arithmetic expression x, where x is an angle in radians. The sine is computed in floating point. The format of the function is:

SIN(x)

The SIND built-in function returns a floating-point value that is the sine of an arithmetic expression x, where x represents an angle in degrees. The sine is computed in floating point. The format of the function is:

SIND(x)

The SINH built-in function returns a floating-point value that is the hyperbolic sine of an arithmetic expression x. The hyperbolic sine is computed in floating point. The format of the function is:

SINH(x)

The SIZE built-in function returns a fixed-point binary integer that is the number of bytes allocated to a referenced variable. The format is:

SIZE (reference)

The returned value is a fixed bin(31) value containing the variable's allocated size in bytes. For bit strings that do not exactly fill an integral number of bytes, the value is rounded up to the next byte.

For varying character-string variables, note that the returned value is two bytes greater than the declared length of the string. These extra two bytes are allocated by PL/I to contain the current length of the string. (If you want the value of the maximum length of a varying character string, use the MAXLENGTH built-in function. If you want the value of the current length of a varying character string, use the LENGTH built-in function.)

The following example illustrates the use of the SIZE built-in function on some scalar variables.

DECLARE S FIXED BINARY(31),
               INT FIXED BINARY(15),
               CHAR1 CHARACTER(5),
               CHAR2 CHARACTER(5) VARYING,
               BITSTRING BIT(10),
               P POINTER;

       S = SIZE(INT);  /* S = 2 */
       S = SIZE(CHAR1);        /* S = 5 */
       S = SIZE(CHAR2);        /* S = 7 */
       S = SIZE(BITSTRING);    /* S = 2 */
       S = SIZE(P);    /* S = 4 */

Note the difference between the allocated size for the fixed-length and varying character strings. Note also that the returned value for the bit string is rounded up to 2 bytes, the integral number of bytes required to contain 10 bits.

DECLARE 1 STRUC,
                       2 CHARSTR CHARACTER(5),
                       2 BITSTR BIT(10),
               ARRAY(5) FIXED BINARY(31),
       S FIXED BINARY(31);
       S = SIZE(STRUC);        /* S = 7 */
       S = SIZE(CHRSTR);       /* S = 5 */
       S = SIZE(ARRAY);        /* S = 20 */
       S = SIZE(ARRAY(2));     /* S = 20 */

In this example, the SIZE built-in function is applied to a structure, to one of its members, to an array, and to an element of the array. Note that a reference to an array element returns the same value as a reference to the entire array.

DECLARE 1 TARGET,
                       2 A BIT(9),
                       2 B BIT(10),
                       2 C BIT(1),
               1 ALIGNED_TARGET,
                       2 A BIT(9) ALIGNED,
                       2 B BIT(10) ALIGNED,
                       2 C BIT(1) ALIGNED,
               S FIXED BINARY(31);

       S = SIZE(TARGET);                                                       /* S = 3 */
       S = SIZE(ALIGNED_TARGET);                                                       /* S = 5 */

This example illustrates the difference in PL/I's storage of unaligned and aligned bit strings. The structure TARGET consists of three bit strings that are unaligned (the default storage mechanism). The three bit strings occupy 20 consecutive bits in memory. Therefore, only three bytes are required to hold the structure. The structure ALIGNED_TARGET consists of the same three strings, except each is declared with the ALIGNED attribute, forcing the structure to start on a byte boundary. In this structure, A and B each require two bytes while C requires one byte, for a total of five bytes. A similar situation exists with arrays of bit strings.

T: PROC OPTIONS(MAIN);

DCL P PTR;
DCL 1 S BASED(P),
               2 I FIXED,
               2 A(10 REFER(I)) FIXED;

ALLOCATE S;
PUT SKIP LIST(SIZE(S));                                                        /* Returns 44 */
I = 5;
PUT SKIP LIST(SIZE(S));                                                        /* Returns 24 */
END;

This example shows how the SIZE built-in function works on a structure containing the REFER option. SIZE returns the current size.

DECLARE STR CHARACTER(10) VARYING;
       ⋮
       CALL SUB(STR);
       ⋮
SUB: PROCEDURE(X);
DECLARE X CHARACTER(*) VARYING;

               PUT SKIP LIST (SIZE(X));

Here, the SIZE built-in function is used to determine the size of a parameter that is passed to a procedure. This PUT statement prints the value 12.

CALL MACRO_ROUTINE(
        ADDR(OUTSTRING),SIZE(OUTSTRING) );

Here, the SIZE built-in function is used to supply an argument to a procedure (possibly one written in another language) that requires the size in bytes of a data structure.

The SOME built-in function allows you to determine whether at least one bit in a bit string is '1'B. In other words, it performs a logical OR operation on the elements of the bit string. The format of the SOME built-in function is:

SOME(bit-string)

The function returns the value '1'B if one or more bits in the bit-string argument are '1'B. It returns '0'B if every bit in the argument is '0'B or if the argument is the null bit string.

The SQRT built-in function returns a floating-point value that is the square root of an arithmetic expression x. The square root is computed in floating point. After its conversion to floating point, x must be greater than or equal to zero.

The format of the function is:

SQRT(x)

The STORAGE built-in function returns a fixed binary (31) value that is the implementation-defined storage, in bytes, required by the specified variable. The format of the function is:

STORAGE(reference)

The returned value is a fixed bin(31) value containing the variable's maximum storage size in bytes. This is the maximum number of bytes that could be transmitted if you wrote the variable to a record file defined with the ENVIRONMENT(SCALARVARYING) option.

Some variables can have varying sizes. If the referenced variable is a varying-length string, a scalar area, or an aggregate that contains areas or varying-length strings, the returned value includes the storage used by any control bytes and length prefixes plus the maximum lengths of the strings and the maximum sizes of the areas.

The STRING built-in function concatenates the elements of an array or structure and returns the result. Elements of a string array are concatenated in row-major order. Members of a structure are concatenated in the order in which they were declared.

The format of the STRING built-in function is:

STRING(reference)

The string returned is of type CHARACTER or BIT, depending on whether the reference is suitable for character- or bit-string overlay defining. The length of the string is the total number of characters or bits in the base reference.

STRING_BIF_EXAMPLE: PROCEDURE;
DECLARE NEW_NAME CHARACTER(40);
DECLARE 1 FULL_NAME,
                       2 FIRST_NAME CHARACTER(10),
                       2 MIDDLE_INITIAL CHARACTER(3),
                       2 LAST_NAME CHARACTER(27);
FIRST_NAME = 'MABEL';
MIDDLE_INITIAL = 'S.';
LAST_NAME = 'MERCER';
NEW_NAME = STRING(FULL_NAME);
                               /* NEW_NAME =
                               'MABEL     S. MERCER                     '
                                where   is a space                                             */
END STRING_BIF_EXAMPLE;

The SUBSTR built-in function returns a specified substring from a string. The format is:

SUBSTR(string,position[,length])

The returned substring is of type BIT(length) or CHARACTER(length), depending on the type of the string argument. If the length argument is zero, the result is a null string.

DECLARE (NAME,LAST_NAME) CHARACTER(20),
       START FIXED BINARY(31);

NAME = 'ISAK DINESEN';
       /* NAME = 'ISAK#DINESEN        ' */

START = INDEX(NAME,' ') + 1;
       /* START = 6 */

LAST_NAME = SUBSTR(NAME,START);
       /* default length = LENGTH(NAME) - START + 1 = 15 */
       /* LAST_NAME = 'DINESEN             ' */

The SUBTRACT built-in function returns the difference of two arithmetic expressions x and y, with a specified precision p and an optionally specified scale factor q. The format of the function is:

SUBTRACT(x,y,p[,q])

The SUM built-in function takes an array as an argument and returns the arithmetic sum of all the elements in the array. The array must have the FIXED or the FLOAT attribute. The format of the SUM built-in function is:

SUM(array-variable)

If the array has the attributes FIXED(p,q), the result will have the attributes FIXED(p,q). If the array has the attributes FLOAT(p), the result will also have the attributes FLOAT(p).

The result will have the same base attribute as the array, either DECIMAL or BINARY.

The TAN built-in function returns a floating-point value that is the tangent of an arithmetic expression x, where x represents an angle in radians. The tangent is computed in floating point. After its conversion to floating point, x must not be an odd multiple of /2

The format of the function is:

TAN(x)

The TAND built-in function returns a floating-point value that is the tangent of an arithmetic expression x, where x represents an angle in degrees. The tangent is computed in floating point. After its conversion to floating point, x must not be an odd multiple of 90.

The format of the function is:

TAND(x)

The TANH built-in function returns a floating-point value that is the hyperbolic tangent of an arithmetic expression x. The hyperbolic tangent is computed in floating point. The format of the function is:

TANH(x)

The TIME built-in function returns an 8-character string representing the current time of day in the following form:

hhmmssxx

The current hour (00-23)

The minutes (00-59)

The seconds (00-59)

Hundredths of seconds (00-99)

The format of the TIME built-in function is:

TIME()

If TIME is used as a preprocessor built-in function, the time returned is the time when the program was compiled; otherwise the function returns the time at run time.

Given a character-string argument, the TRANSLATE built-in function replaces occurrences of an old character with a corresponding translation character and returns the resulting string. The format is:

TRANSLATE(original,translation[,old-chars])

The string returned is of type CHARACTER(length), where length is the length of the original string. If the original string is a null string, the returned value is a null string.

TRANSLATE_XM: PROCEDURE OPTIONS(MAIN);

DECLARE NEWSTRING CHARACTER(80) VARYING;
DECLARE TRANSLATION CHARACTER(128);
DECLARE I FIXED;
DECLARE COLLATE BUILTIN;

       /* translate space to '0': */
NEWSTRING = TRANSLATE('1 2','0',' ');
PUT SKIP LIST(NEWSTRING);

       /* translate letter 'F' to 'E': */
NEWSTRING = TRANSLATE('BFFLZFBUB','E','F');
PUT SKIP LIST(NEWSTRING);

/* change case of letters in sentence */
TRANSLATION = COLLATE;
DO I=RANK('A') TO RANK('Z'); /* replace upper with lower */
SUBSTR(TRANSLATION,I,1) = SUBSTR(COLLATE,I+32,1);
END;

DO I=RANK('a') TO RANK('z'); /* replace lower with upper */
SUBSTR(TRANSLATION,I,1) = SUBSTR(COLLATE,I-32,1);
END;
NEWSTRING =
TRANSLATE('THE QUICK BROWN fox JUMPS OVER THE LAZY dog',TRANSLATION);
PUT SKIP LIST(NEWSTRING);

END TRANSLATE_XM;

The first reference translates the string `1 2' to `102' The second reference translates `BFFLZFBUB' to `BEELZEBUB'. The third reference produces the following new sentence:

'the quick brown FOX jumps over the lazy DOG'

The TRIM built-in function accepts a character string as an argument and returns a character string that consists of the input string with specified characters removed from the left and right. If you supply only one argument, TRIM removes blanks from the left and right of the argument. If you supply only the second argument, TRIM removes the specified characters from the left of the string and blanks from the right. If you supply both the second and third arguments, TRIM removes characters specified by those arguments from the left and right of the string, respectively.

The format of the TRIM built-in function is:

TRIM (input-string,[beginning-chars,end-chars])

The returned value is a character string with characters removed from the ends.

The following examples illustrate the use of the TRIM built-in function.

The TRUNC built-in function changes all fractional digits in an arithmetic expression x to zeros and returns the resulting integer value. Its format is:

TRUNC(x)

If x is a floating-point expression, the returned value is a floating-point value. If x is a fixed-point expression, the returned value is a fixed-point value with the same base as x. The value has the following attributes:

precision = min(31,p - q + 1)

scale factor = 0

Here, p and q are the precision and scale factor of x.

The UNSPEC built-in function returns a bit string representing the internal coded value of the referenced variable, or a specified part of that variable. The variable can be an aggregate or a scalar variable of any type. The format of the function is:

UNSPEC(reference)

The returned value is a bit string whose length is the number of bits occupied by the referenced variable. The length of the bit string must be less than or equal to the maximum length for bit-string data. The returned bit string contains the contents of the storage of the referenced variable , the first bit in storage being the first bit in the returned value. The actual value may differ depending on the architecture of your platform. For example, the VAX and Alpha architecture store integers differently than the IBM architecture. Therefore, use the UNSPEC built-in function with caution when developing cross-platform software.

Note that if the referenced variable is a binary integer (FIXED BINARY), the first bit in the returned value is the lowest binary digit.

DECLARE X CHARACTER(2), Y BIT(16);

X = 'AB';
Y = UNSPEC(X);
       ⋮
DECLARE I FIXED BINARY(15);
I = 2;
PUT LIST(UNSPEC(I));

As a result of the first UNSPEC reference, Y contains the ASCII codes of 'A' and 'B'. The PUT LIST statement containing UNSPEC(I) prints the following string:

'0100000000000000'B

The VARIANT preprocessor built-in function returns a string representing the value of the variant qualifier in the command that invoked the compilation.

The format in a preprocessor expression is:

VARIANT()

The -T variant option permits specification of compilation variants. The value specified is available to the VARIANT preprocessor built-in function at compile time. The format of compilation variants is:

-T variant { [alphanumeric-string]   }
           { ["alphanumeric-string"] }
           { ['alphanumeric-string'] }

For example, if you want to compile a program with one of three different INCLUDE files, you can use the -T variant command qualifier to specify which file to include.

In the following example, the file SPECIAL.SRC is included in the program only if -T SPECIAL appears in the pl1 command line:

%IF VARIANT() = 'SPECIAL'
%THEN
       %INCLUDE 'SPECIAL.SRC';
%IF VARIANT() = 'NONE'
%THEN;

No action is taken if -T NONE appears on the pli command line.

To specify a null variant, omit the -T option from the pli command line.

The VERIFY built-in function compares a string with a character-set string and verifies that all characters appearing in the string also appear in the character-set string. The function returns the value zero if they all appear. If not, the function returns a fixed-point binary integer that indicates the position of the first character in the string that is not present in the character-set string. The comparison is done character by character and left to right, and as soon as one nonmatching character is found in the first string, no more characters are compared. The function is case sensitive.

The format of the function is:

VERIFY(string,character-set-string[,starting-position])

The WARN preprocessor built-in function returns the number of diagnostic warning messages issued during compilation up to that particular point in the source program. The format for the WARN built-in function is:

WARN();

The function returns a fixed result representing the number of compile-time warning messages that were issued up to the point at which the WARN built-in function was encountered.

The INT pseudovariable assigns a signed integer value to specified storage. The format is:

INT(reference[,position[,length]]) = expression;

DECLARE F FLOAT INITIAL (123.45);
               INT(F,8,8) = 25;        /* Alter the exponent */
               PUT SKIP LIST (F);      /* New value */

In this example, the INT pseudovariable is used to modify the exponent field of a floating-point variable. This example prints the following value:

9.5102418E-32

Proper interpretation of this result requires understanding of the internal representation of floating-point numbers. As such, this example is only valid on the Alpha hardware.

The next example demonstrates how the INT pseudovariable treats cases in which the value is too large for the specified storage:

INTOVER: PROCEDURE OPTIONS (MAIN);

DECLARE I15 FIXED BINARY (15),
                       I31 FIXED BINARY (31);

ON FIXEDOVERFLOW PUT SKIP LIST ('FIXEDOVERFLOW signaled');
       I31 = -876543;                                  /* Too big for I15 */
       I15 = I31;                                      /* Arithmetic assignment */
       INT(I15) = I31;                                 /* No error signaled */
       PUT SKIP LIST (I15);
       END;

This example produces the following output:

FIXEDOVERFLOW signaled
       -24575

The arithmetic assignment to I15 signals FIXEDOVERFLOW because the value of I31 is outside the range of a FIXED BINARY (15) variable. However, the assignment using the INT pseudovariable does not signal an error; it just copies the low-order 16 bits of the value of I31 into the storage for I15.

The ONCHAR pseudovariable can be used to replace the single character in the ONSOURCE value that caused a CONVERSION condition to be raised. An attempt to assign a value to the ONCHAR pseudovariable when there is no active CONVERSION condition causes the ERROR condition to be raised.

The format of the pseudovariable is:

ONCHAR()

See Section 8.10.4.6, “CONVERSION Condition” for more information about CONVERSION condition name.

The ONSOURCE pseudovariable can be used to replace the entire ONSOURCE value that caused a CONVERSION condition to be raised. An attempt to assign a value to the ONSOURCE pseudovariable when there is no active CONVERSION condition causes the ERROR condition to be raised.

The format of the pseudovariable is:

ONSOURCE()

The ONSOURCE value is a fixed-length string value. An assignment of a longer string is truncated, and an assignment of a shorter string is padded with blanks on the right to the necessary length.

See Section 8.10.4.6, “CONVERSION Condition” for more information about CONVERSION condition name.

The PAGENO pseudovariable refers to the page number of the referenced print file. Assignment to the pseudovariable modifies the current page number. The format of the PAGENO pseudovariable in an assignment statement is:

PAGENO(reference) = expression;

The POSINT pseudovariable assigns an integer value to specified storage. The format is:

POSINT(expression1[,position[,length]]) = expression2;

The STRING pseudovariable interprets a suitable reference as a reference to a fixed-length string. By using it, you can modify an entire aggregate with a single string assignment or assign the aggregate to a pictured variable as if it were a character-string variable. The format of the pseudovariable (in an assignment statement) is:

STRING(reference) = expression;

STRING_PSD_EXAMPLE: PROCEDURE;

DECLARE 1 NAME,
                       2 FIRST CHARACTER(10),
                       2 MIDDLE_INITIAL CHARACTER(3)
                       2 LAST CHARACTER(10);

STRING(NAME)='FRANKLIN D. ROOSEVELT';
               /* NAME.FIRST - 'FRANKLIN D';
               NAME.MIDDLE_INITIAL = '. R';
               NAME.LAST = 'OOSEVELT '; */

END STRING_PSD_EXAMPLE;
       ⋮
DECLARE 1 FLAGS,
2 (A,B,C) BIT(1);
STRING(FLAGS) = '0'B; /* sets all three flags false */
       ⋮
DECLARE P PICTURE /Z.ZZZV,ZZDB';

GET EDIT (STRING(P)) (A(10));
       /* assigns 10 characters from SYSIN to P,
       without conversion */

The SUBSTR pseudovariable refers to a substring of a specified string variable reference. Assignment to the pseudovariable modifies only the substring. The format of the pseudovariable (in an assignment statement) is:

SUBSTR(reference,position[,length]) = expression;

DECLARE (NAME,NEW_NAME) CHARACTER(20) VARYING;
NAME = 'ISAK DINESEN';
NEW_NAME = NAME;
SUBSTR(NEW_NAME,4) = 'AC NEWTON';
/* NEW_NAME = 'ISAAC NEWTON' */

The UNSPEC pseudovariable interprets a reference to a scalar or aggregate element variable as a reference to a bit string. The format of the pseudovariable (in an assignment statement) is:

UNSPEC(reference) = expression;

DECLARE X FIXED BINARY (15);
UNSPEC(X) = '110'B;

The use of the constant '110'b, which appears to be 6 in binary, actually assigns 3 to X. The two low-order bits of X (that is, X's first two bits of storage) are set; all other bits of X are cleared.

UNSPEC(X,1,3) = '101'B;

The optional parameters position and length are specified, causing the first three, low-order bits of the variable X to be assigned the value '101'B; the other bits are unaffected.