| Previous | Contents | Index |
The PRESENT built-in function allows you to determine whether a given parameter was specified in a call. It can simplify the task of writing procedures with optional parameters.
The PRESENT built-in function takes one argument, the parameter name. It returns the bit value '1'B if the parameter was specified and '0'B if it was not.
The format of this function is:
PRESENT(parameter-name) |
Note that the result returned by the PRESENT built-in function for an
optional parameter passed by value is unpredictable (if a zero is
passed, '0'B is returned). A warning is generated for this use.
11.4.70 PROD
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.
11.4.71 RANK
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) |
character
Any expression yielding a 1-character value.
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. See Appendix B for a table of these
characters and their corresponding numeric codes.
11.4.72 REFERENCE
The REFERENCE built-in function is used to force a parameter to be passed by reference, rather than by whatever mechanism is specified by the declaration of the formal parameter.
The type of the argument specified with the REFERENCE built-in function is used for the parameter; thus, the type of the parameter declaration is ignored when the REFERENCE built-in function is used.
The format of the REFERENCE built-in function is:
(variable-reference)
variable-reference
The name of a scalar or aggregate variable.
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); |
string-expression
An expression that evaluates to a character string or a bit string.
DECLARE X CHARACTER(4) VARYING,
Y BIT(8);
X = REVERSE('abc')
Y = REVERSE('00010101'B)
|
The ROUND built-in function rounds a fixed-point binary expression, fixed-point decimal expression, or pictured value to a specified number of binary or decimal places respectively. The format is:
ROUND(expression,position) |
expression
An arithmetic expression that yields a fixed-point binary or decimal value; or a pictured value with fractional digits. A binary value can have a positive or negative non-zero scale factor, but a decimal value must have a positive non-zero scale factor.position
A nonnegative integer constant specifying the number of binary or decimal places in the rounded result.
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)*(2k)+1)
For a fixed decimal number, the rounded value is:
ROUND(x,k) = sign(x)*(10-k)*floor(abs(x)*(10k)+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 RTRIM built-in function accepts a character string as an argument and returns a character string that consists of the input string with the specified characters removed from the right. If you supply only one argument, white spaces (form feeds, carriage returns, tabs, vertical tabs, line feeds, and spaces) are removed from the end.
The format of the RTRIM built-in function is:
RTRIM (input-string, [end-chars]) |
input-string
A character-string variable or constant. This argument supplies the string from which blanks are to be trimmed.end-chars
A character-string variable or constant. This argument specifies characters to be trimmed from the right of the input string. If a character that is in the last position in the input string is also present anywhere in end-chars, that character is removed from the input string. This process is repeated until a character is encountered on the right of the input string that is not present in end-chars, or until the characters in the input string are exhausted. If no argument is supplied, all white spaces (form feeds, carriage returns, tabs, vertical tabs, line feeds, and spaces) are removed from the right of the input-string.
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]) |
string-1
A character-string expression. One character in the string is to be matched, if possible, in the second string.string-2
A character-string expression to be compared, character by character, with each character in the first string, in order, until one matching character is found.starting-position
A positive integer in the range 1 to n+1, where n is the length of the first string. It specifies the leftmost character in the first string from which the search is to begin. If starting-position is specified, any characters to the left of that position in the first string are ignored. (By default, the search begins with the leftmost character in the first string.)
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.
11.4.77 SIGN
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) |
reference
The name of a variable known to this block. The reference can be to a scalar variable, an array or structure, or a structure member. The reference cannot be to a constant or expression. Although references to individual array elements are allowed, the returned value in this instance is the size of the entire array, not the element.
The returned value is 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.
11.4.82 SOME
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.
11.4.83 SQRT
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 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) |
reference
A reference to a variable that is suitable for bit-string or character-string overlay defining. Briefly, a variable is suitable if it consists entirely of characters or bits, and these characters or bits are packed into adjacent storage locations, without gaps.
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]) |
string
A bit- or character-string expression.position
An integer expression that indicates the position of the first bit or character in the substring. The position must be greater than or equal to 1 and less than or equal to LENGTH(string) + 1.length
An integer expression that indicates the length of the substring to be extracted. If not specified, length is:LENGTH(string) - position + 1
In other words, if length is not specified, the substring is extracted beginning at the indicated position and ending at the end of the string.
The length must satisfy the following condition:
0 <= length <= LENGTH(string) - position + 1
If it does not, and the module was compiled with /CHECK=BOUNDS, the STRINGRANGE condition is raised.
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 ' */
|
| Previous | Next | Contents | Index |