| Previous | Contents | Index |
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:
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.
11.4.27 DECODE
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 specifying the radix of the string 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) |
character-expression
A character-string constant or variable whose component characters can be any of the digits from '0' through '9', from 'a' through 'f', and from 'A' through 'F'. The digits must be within the range of digits valid for the base specified in the radix-expression.radix-expression
An expression evaluating to any integer from 2 through 16.
DECLARE (X,Y) FIXED BINARY;
X = DECODE('1010',2);
Y = DECODE('f0',16);
|
The DESCRIPTOR built-in function forces its argument to be passed by descriptor to a non-PL/I procedure. A reference to the built-in function must occur only as an argument in such a context and has no other use. The format of the function is:
expression
The argument to be passed by descriptor. Its data type must be computational but cannot be pictured. It can be an array variable.
The DIMENSION built-in function returns a fixed-point binary integer that is the number of elements in an array dimension. Its format is:
reference
A reference to an array variable.dimension
An integer constant specifying the dimension of the array for which the extent is to be determined. If the dimension is not specified, the dimension parameter defaults to 1. Thus, DIMENSION(A) is equivalent to DIMENSION(A,1).
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.)
11.4.30 DIVIDE
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. It is normally much faster than the FREE statement is in freeing all the variables in an area (freeing all the area's storage). 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) |
integer-expression
An expression evaluating to a fixed binary number representing a decimal integer. Whether signed or not, this integer is treated by the function as unsigned.radix-expression
An expression that evaluates to any integer from 2 through 16.
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.
11.4.33 ERROR
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.
11.4.34 EVERY
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.
11.4.35 EXP
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]) |
p
The number of bits used to represent the arithmetic value. The precision must be greater than zero and less than or equal to 31.q
An integer in the range 0 through 31 for decimal data, in the range -31 through 31 for binary data. If q is omitted, it is assumed to be zero. The scale factor q must be less than or equal to the specified precision.
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.
11.4.37 FLOAT
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:
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 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.
11.4.38 FLOOR
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]) |
reference
A reference to an array variable.dimension
An integer constant indicating a dimension of the specified array. If the dimension is not specified, the dimension parameter defaults to 1. Thus, HBOUND(A) is equivalent to HBOUND(A,1).
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) |
length
The specified length of the returned string. The (maximum length of the returned string is 32767 characters.
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
255.
11.4.41 INDEX
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]) |
string
The string to be searched for the given substring. It can be either a character-string or a bit-string expression.substring
The substring to be located. It must have the same string data type as the string argument.starting-position
A positive integer in the range 1 to n+1, where n is the length of the string. It specifies the leftmost position from which the search is to begin. (By default, the search begins at the left end of the string.)
| #1 |
|---|
DECLARE RESULT FIXED BINARY(31);
RESULT = INDEX ('ABCDEF','DEF');
|
RESULT is given the value 4 because the substring 'DEF' begins at the fourth position in 'ABCDEF'.
| #2 |
|---|
RESULT = INDEX('SHARP FORTUNE','R');
|
RESULT is given the value 4 because the leftmost occurrence of 'R' is at the fourth position in 'SHARP FORTUNE'.
| #3 |
|---|
RESULT = INDEX('SHARP FORTUNE','R',5);
|
The optional starting-position parameter specifies that the search begins at the fifth position of 'SHARP FORTUNE'. Thus, RESULT is given the value 9: the first R is ignored, so the first recognized occurrence of 'R' is found in the ninth position.
| #4 |
|---|
RESULT = INDEX('0000101100001011','1011');
|
RESULT is given the value 5 because the leftmost occurrence of '1011' is at the fifth position in '0000101100001011'.
| #5 |
|---|
NEW_STRING = '315-54-3159';
IF INDEX(NEW_STRING,'-')=4 THEN
PUT LIST('SOCIAL SECURITY NUMBER');
|
The INDEX function is used to determine whether or not a string is a Social Security number. The function finds the location of the first hyphen in the string.
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.
11.4.43 INT
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]]) |
expression
A scalar expression or reference to connected storage. This reference cannot be an array, structure, or named constant. If position and length are not specified, the length of the referenced storage must not exceed 32 bits. If it exceeds 32 bits, a fatal run-time error results.position
A positive integer value that denotes the position of the first bit in the field. If omitted, position defaults to 1, signifying the first bit of storage denoted by the expression. If specified, position must satisfy the following condition:1 <= position <= size(expression) Here, size(expression) is the length in bits of the storage denoted by expression. A position equal to size(expression) implies a zero-length field.
length
An integer value in the range 0 through 32 that specifies the length of the field. If omitted, length is the number of bits from the bit denoted by position through the end of the storage denoted by expression. If specified, length must satisfy the following condition:0 <= length <= size(expression) - position Here, size(expression) is the length in bits of the storage denoted by expression.
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]) |
reference
A reference to an array variable.dimension
An integer constant indicating the dimension of the specified array. If the dimension is not specified, the dimension parameter defaults to 1. Thus, LBOUND(A) is equivalent to LBOUND(A,1).
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) |
| Previous | Next | Contents | Index |