| Previous | Contents | Index |
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.
11.4.48 LOG
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) |
length
The specified length of the returned string. The maximum length permitted is 32767 characters.
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 0.
11.4.52 LTRIM
The LTRIM 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 left. If you supply only one argument, white spaces (form feeds, carriage returns, tabs, vertical tabs, line feeds, and spaces) are removed from the left.
The format of the LTRIM built-in function is:
LTRIM (input-string, [beginning-chars]) |
input-string
A character-string variable or constant. This argument supplies the string from which the characters or blanks are to be trimmed.beginning-chars
A character-string variable or constant. This argument specifies characters to be trimmed from the left of the input string. If a character that is in the first position in the input string is also present anywhere in beginning-chars, that character is removed from the input string. This process is repeated until a character is encountered on the left of the input string that is not present in beginning-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 left of the input-string.
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. 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.
11.4.54 MAXLENGTH
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) |
string
A reference to a character string or a bit string. If it is anything other than a varying-length character string, the MAXLENGTH function returns a result identical to the result that would be returned by the LENGTH built-in function.
For example:
MAXLENGTH_EXAMPLE: PROCEDURE OPTIONS(MAIN); DCL CHAR_VAR CHARACTER(10) VARYING; CHAR_VAR = 'String'; CALL SAMPLE(CHAR_VAR); END MAXLENGTH_EXAMPLE; SAMPLE: PROCEDURE(STRING); DCL STRING CHAR(*) VARYING; PUT LIST(LENGTH(STRING),MAXLENGTH(STRING)); END SAMPLE; |
The program prints the following:
6 10 |
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. 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.
11.4.56 MOD
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 8
|
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.)
11.4.57 MULTIPLY
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]) |
p
An integer constant greater than zero and less than or equal to the maximum precision of the result type, which is:
- For OpenVMS Alpha systems: 31for 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 in the range -31 through p when used with fixed-point binary multiplication. The scale factor for fixed-point decimal multiplication has a range 0 through p. A scale factor is not to be used with floating-point arithmetic. If no scale factor is designated, q defaults to zero.
Expressions x and y are converted to their derived type before the multiplication is performed.
For example:
MULT: PROCEDURE OPTIONS (MAIN);
DECLARE I_RATE FIXED DECIMAL(31,4),
PRINCIPAL FIXED DECIMAL(31,2),
OWED FIXED DECIMAL(31,6);
I_RATE = .1514;
PRINCIPAL = 27688.25;
OWED = MULTIPLY (I_RATE,PRINCIPAL,31,6);
PUT SKIP LIST ('INTEREST OWED =',OWED);
END;
|
Interest rates are calculated to six decimal places and the following string is printed:
INTEREST OWED = 4192.001050 |
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.
11.4.59 OFFSET
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) |
pointer
A reference to a pointer variable whose current value either represents the location of a based variable within the specified area or is null.area
A reference to a variable declared with the AREA attribute. If the specified pointer is not null, it must designate a storage location within this 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.
11.4.60 ONARGSLIST
The ONARGSLIST built-in function returns a pointer to the location in memory of the argument list for an exception condition. If the ONARGSLIST built-in function is referenced in any context outside of an ON-unit, it returns a null pointer. The format is:
ONARGSLIST() |
What the return pointer points to depends on the host system. See the
Kednos PL/I for OpenVMS Systems User Manual.
11.4.61 ONCHAR
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.
11.4.62 ONCODE
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.
11.4.64 ONKEY
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.
11.4.65 ONSOURCE
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 PAGENO built-in function returns a FIXED BINARY(15) integer that is the current page number in the referenced print file. The print file must be open. The format of the function is:
PAGENO(reference) |
The POINTER built-in function returns a pointer to the location identified by the referenced offset and area. The format is:
offset
A reference to an offset variable whose current value either represents the offset of a based variable within the specified area or is null.area
A reference to a variable that is declared with the AREA attribute and with which the specified offset value is associated.
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.
11.4.68 POSINT
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]]) |
expression
A scalar expression or reference to connected storage. This reference must not 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 the storage denoted by the expression. If specified, position must satisfy the following condition:1 <= position <= size(expression) 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 Size(expression) is the length in bits of the storage denoted by expression.
The value returned by POSINT is of the type FIXED BINARY (31) for OpenVMS VAX and RISC ULTRIX, or FIXED BINARY (63) for OpenVMS Alpha. 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 largest possible FIXED BIN (15) value, 32767. An attempt to assign the same value to a FIXED BIN (15) variable results in PL/I signaling an ERROR condition.
| Previous | Next | Contents | Index |