| Previous | Contents | Index |
This section presents the built-in functions in alphabetical order.
11.4.1 ABS
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.
11.4.2 ACOS
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 <= Pi sign
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 ACTUALCOUNT built-in function allows you to determine how many parameters the current procedure was called with. The function returns a FIXED BINARY(31) result.
The format of the function is:
ACTUALCOUNT(); |
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]) |
p
An unsigned integer constant greater than zero and less than or equal to the maximum precision of the result type, which is:
- For OpenVMS Alpha systems: 31 for fixed-point data, 15 for floating-point decimal data, and 53 for floating-point binary data
- >For OpenVMS VAX systems: 31 for fixed-point data, 34 for floating-point decimal data, and 113 for floating-point binary data
q
An integer constant less than or equal to the specified precision. The scale factor can be optionally signed when used in fixed-point binary addition. The scale factor for fixed-point binary must be in the range -31 to p. The scale factor for fixed-point decimal data must be in the range 0 to p. If you omit q, the default value is zero. You should not use a scale factor for floating-point arithmetic.
Expressions x and y are converted to their derived type before the addition is performed.
For example:
ADDBIF: PROCEDURE OPTIONS (MAIN);
DECLARE X FIXED DECIMAL (8,3),
Y FIXED DECIMAL (8,3),
Z FIXED DECIMAL (9,3);
X=9500.374;
Y=2278.897;
Z = ADD (X,Y,9,3);
PUT SKIP LIST ('TOTAL =',Z);
END;
|
This program prints the following:
TOTAL = 11779.271 |
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.)
11.4.6 ADDREL
The ADDREL built-in function adds an offset value to a pointer and returns a pointer which is the sum of the two arguments. The format of the function is:
ADDREL(pointer,offset) |
pointer
A reference to a pointer variable whose current value represents the location of a based variable.offset
Any integer expression.
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:
reference
The name of a controlled variable.
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.
ALLO: PROCEDURE OPTIONS (MAIN);
DECLARE STR CHARACTER (10) CONTROLLED;
ALLOCATE STR;
STR='FIRST';
ALLOCATE STR;
STR='SECOND';
ALLOCATE STR;
STR='THIRD';
DO WHILE (ALLOCATION(STR)^=0);
PUT SKIP LIST (STR);
FREE STR;
END;
END;
|
This example shows how the ALLOCATION built-in function can be used to
count generations of controlled variables and therefore control the
loop. Strings are freed while generations still exist, but when all
generations have been freed, the value of ALLOCATION is zero and the
process ends, thus avoiding a fatal run-time error.
11.4.8 ASIN
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:
-Pi sign/2 <= w <= Pi sign/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:
-Pi sign/2 < v < Pi sign/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 <= Pi sign , and if s < 0 , then -Pi sign
< v < 0 , where s and r are, respectively, the values of expressions y
and x after their conversion to floating point.
11.4.10 ATAND
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/Pi sign
11.4.11 ATANH
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:
p
The precision p, if specified, must be an integer constant greater than zero and less than or equal to the maximum precision of the result type:
- For OpenVMS Alpha: 63 if fixed-point binary and 53 if floating-point binary
- For OpenVMS VAX: 31 if fixed-point binary and 113 if floating-point binary
The precision p must be specified if x is a fixed-point value with fractional digits.
q
The scale factor q, if specified, must be an integer constant less than or equal to the specified precision and in the range -31 to 31.
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.
11.4.13 BIT
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) |
string-1
A bit-string expression of any length.string-2
A bit-string expression of any length.operation-string
A bit-string expression that is converted to length 4. Each bit in the operation string specifies the result of comparing two corresponding bits in string-1 and string-2. Specify bit positions in the operation string from left to right to define the operation, as in the following truth table:
| String-1 Bit | String-2 Bit | Result of Boolean Operation |
|---|---|---|
| 0 | 0 | Bit 1 of operation string |
| 0 | 1 | Bit 2 of operation string |
| 1 | 0 | Bit 3 of operation string |
| 1 | 1 | Bit 4 of operation string |
Thus, an AND operation, for instance, would be specified by the operation-string '0001'B.
If string-1 and string-2 are of different lengths, the shorter is extended on the right with zeros to the length of the longer.
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 <BIT_STRING>(011001)B.
Figure 11-1 illustrates this example.
Figure 11-1 Example of the BOOL Built-In Function
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.
11.4.17 CEIL
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:
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
<BIT_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'.
11.4.19 COLLATE
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) |
string
Any bit- or character-string expression. If the expression is a bit string, the result is a bit string. Otherwise, the result is a character string.count
Any expression that yields a nonnegative integer. The specified count controls the number of copies of the string that are concatenated, as follows:
| Value of Count | String Returned |
|---|---|
| 0 | A null string |
| 1 | The string argument |
| n | Concatenated copies of the string argument |
COPY('12',3)
|
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 DATE built-in function returns a 6-character string in the form yymmdd, where:
| yy | Is the current year (00-99) |
| mm | Is the current month (01-12) |
| dd | Is the current day of the month (01-31) |
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.
11.4.25 DATETIME
The DATETIME built-in function returns a 16-character string in the form ccyymmddhhmmssxx, where:
| cc | Is the current century (00-99) |
| yy | Is the current year (00-99) |
| mm | Is the current month (01-12) |
| dd | Is the current day of the month (01-31) |
| hh | Is the current hour (00-23) |
| mm | Is the minutes (00-59) |
| ss | Is the seconds (00-59) |
| xx | Is the hundredths of seconds (00-99) |
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().
| Previous | Next | Contents | Index |