SORTFIELDS=(pos,len,type,seq,[,posj,lenj,typej,seqj]...)
[,options-list]'This chapter defines the built-in functions and subroutines provided by Open PL/I.
Built-in functions and subroutines are procedures provided by the Open PL/I language. They can be used wherever an expression is valid.
The built-in functions and subroutines provided by Open PL/I can be grouped into the following classes:
| ABS | EXP | LOG10 | MOD | SIGN |
| ADD | FLOOR | LOG2 | MULTIPLY | SORT |
| CEIL | INT | MAX | POSINT | TRUNC |
| DIVIDE | LOG | MIN | ROUND |
| ACOS | ATAND | COSD | SIND | TAND |
| ASIN | ATANH | COSH | SINH | TANH |
| ATAN | COS | SIN | TAN |
| BOOL | HIGH | LOW | SUBSTR | VALID |
| COLLATE | INDEX | REPEAT | TRANSLATE | VERIFY |
| COPY | LENGTH | STRING | TRIM |
| BINARY | BYTE | DECIMAL | FLOAT | RANK |
| BIT | CHARACTER | FIXED |
| ONCHAR | ONFILE | ONKEY | ONLOC | ONSOURCE |
| ONCODE |
| ALL | DIMENSION | LBOUND | PROD | SUM |
| ANY | HBOUND |
| ADDR | CURRENTSTORAGE | OFFSET | SIZE | STORAGE |
| ALLOCATION | NULL | POINTER |
| DATE | LINENO | PLIRETC | PLISRTx | TIME |
| DATETIME | PAGENO | PLIRETV | RESIGNAL | UNSPEC |
| FLUSH |
This chapter describes each built-in. The built-ins are presented in alphabetical order by name. Each built-in definition consists of the following subsections: syntax, description (the effect of the built-in), examples (one or more examples of the built-in usage and results) and restrictions (any restrictions in the use of the built-in).
Arguments to built-ins are effectively passed by value, that is, no alteration of the arguments is done.
Returns the absolute value of an arithmetic value.
ABS(x)
x is an arithmetic expression.
ABS(x) returns the absolute value of x.
The result has the same data type and precision as x.
ABS(-132) /* returns 132 */ ABS(12.5) /* returns 12.5 */
The ABS function may produce unexpected results when x is fixed binary and has the maximum negative value for its precision. For example, if x is Fixed Binary(15) and has the value -32768, ABS(x) is -32768.
Returns the arc cosine of a floating-point value.
ACOS(x)
x is a floating-point value such that -1 ≤ x ≤ 1, or is an expression that can be converted to such a value.
ACOS(x) returns the arc cosine of x expressed in radians, such that 0 ≤ ACOS(x) ≤ Π. The result is a floating-point value.
ACOS(1.0) /* returns 0.0 */
An ACOS operation on Float Decimal data is actually performed using its Float Binary equivalent. Thus, the ranges of the operands and the result are limited to the range of Float Binary data.
Returns the sum of two arithmetic values.
ADD(x,y,p,[q])
x and y are arithmetic values, and p and q are integer constants that represent precision and scale factor, respectively.
ADD(x,y,p) returns the arithmetic value x+y with precision and scale (p,0). ADD(x,y,p,q) returns x+y with precision and scale (p,q). The result has the common data type of x and y. If the arguments differ, they are converted as described in the section Arithmetic to Arithmetic Conversion.
The ADD function can also be used for subtraction. To subtract, precede the operand to be subtracted with a minus sign.
DECLARE (PRICE, TAX) DECIMAL(5,2);
.
.
.
PUT LIST ('TOTAL COST IS' ||
ADD (PRICE, TAX, 6,2));
The parameter q must not be specified unless the result type is decimal.
Returns a pointer to the storage referenced by the specified variable.
ADDR(x)
x is a specified variable.
The ADDR function returns a pointer to the storage referenced by a specified variable x. If x is an unconnected array cross-section, ADDR returns the address of the first element of the first element of the cross-section.
x must not be a reference to a parameter whose corresponding argument was passed by value.
DECLARE ELEMENT FIXED BINARY BASED; DECLARE A(10) FIXED BINARY; DECLARE P POINTER; P = ADDR (A(5)); /* ADDRESS OF 5TH ELEMENT */ P -> ELEMENT = -1;
On many implementations, x must not be an unaligned bit string or a structure consisting entirely of unaligned bit strings. (For information on this implementation, see your Open PL/I User's Guide.)
Returns a bit string that is the logical AND of the elements of a bit string array.
ALL(x)
x is an array expression. If x is not a bit string array, it is converted to one.
The ALL function returns a bit string whose length is equal to the length of the longest bit string value in the array. Each bit of the result is 1 if and only if the corresponding bit exists and has the value 1 in every element of the array.
DCL BIT_TEST(3) BIT(5) INITIAL ('10011'B, '10111'B, 10110'B);
DCL BIT_RES BIT(5);
BIT_RES = ALL(BIT_TEST); /* returns '10010'B */
Returns a fixed-point binary integer that is the number of existing generations of a controlled variable.
ALLOCATION (x)
Abbreviation(s): ALLOCN for ALLOCATION.
x is a controlled variable.
The ALLOCATION function returns a fixed-point binary integer that is the number of existing generations of a specified controlled variable. If x is not currently allocated, the result is zero.
DECLARE INPUT CHAR(10) CONTROLLED,
A CHAR(3) VARYING;
.
.
.
DO UNTIL (INPUT = 'STOP');
ALLOCATE INPUT;
GET LIST (INPUT);
.
.
.
END;
A = ALLOCATION(INPUT);
PUT SKIP LIST('Generations = ', A);
None.
Returns a bit string that is the logical OR of the elements of a bit string array.
ANY(x)
x is an array expression. If x is not a bit string array, it is converted to one.
The ANY function returns a bit string whose length is equal to the length of the longest bit string value in the array. Each bit of the result is 1 if the corresponding bit exists and has the value 1 in any element of the array.
DECLARE BIT_TEST(3) BIT(5) INITIAL ('10011'B, '10111'B, 10110'B);
DECLARE BIT_RES BIT(5);
BIT_RES = ANY(BIT_TEST); /* returns '10111'B */
None.
Returns the arc sine of a floating-point value.
ASIN(x)
x is a floating-point value such that -1 ≤ x ≤ 1, or is an expression that can be converted to such a value.
ASIN(x) returns the arc sine of x expressed in radians, such that -Π/2 ≤ ASIN(x) ≤ Π/2. The result is a floating-point value.
ASIN(0.0) /* returns 0.0. */
An ASIN operation on Float Decimal data is actually performed using its Float Binary equivalent. Thus, the ranges of the operands and the result are limited to the range of Float Binary data.
Returns the arc tangent of an arithmetic expression.
ATAN(x,[y])
x and y are floating-point values such that y is not zero, or are expressions that can be converted to such values.
ATAN(x) returns the arc tangent of x. The result is such that -Π/2 ≤ ATAN(x) ≤ Π/2. The result is expressed in radians and has the same data type as x.
ATAN(x,y) returns the arc tangent of x/y. The result is such that if x/y ≥ 0, then 0 ≤ ATAN(x,y) ≤ Π; and, if x/y < 0, then -Π ≤ ATAN(x,y) ≤ 0. The result is expressed in radians and has the same data type as x/y, and has the maximum precision of xand y.
X = 3.14157; Y = 2.0; RADIANS = ATAN(X); /* 1.26 */
or
RADIANS ATAN(X,Y); /* 1.00 */
An ATAN operation on Float Decimal data is actually performed using its Float Binary equivalent. Thus, the ranges of the operands and the result are limited to the range of Float Binary data.
Returns the arc tangent of an arithmetic expression expressed in degrees.
ATAND(x)
or
ATAND(x,y)
x is a single floating-point value (syntax 1) or both x and y are floating-point values (syntax 2).
The ATAND function returns a floating-point value that is the arc tangent of a single arithmetic expression x or an arc tangent computed from two arithmetic expressions x and y. If two arguments are supplied, they must not both be zero.
ATAND(x) returns the arctangent of x. The result is expressed in degrees and has the same data type as x such that -90 ≤ ATAND(x) ≤ 90.
ATAND(x,y) returns the angle in degrees whose tangent is x/y. The result is the common type and maximum precision of x and y such that if x/y ≥ 0, then 0 ≤ ATAND(x,y) ≤ 180, and if x/y < 0, then -180 ≤ ATAND(x,y) ≤ 0.
ATAND(1.0) /* returns 45.0. */ ATAND(-1.0,1.0) /* returns -45.0. */ ATAND(1.0,0.0) /* returns 45.0. */ X = 3.14157; Y = 2.0; DEGREES = ATAND(X); /* 7.2343E+01 */
or
DEGREES = ATAND(X,Y) /* 5.7518E+01 */
An ATAND operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns the hyperbolic arc tangent of an arithmetic expression.
ATANH(x)
x is a floating-point value such that -1 < x < 1.
The ATANH(x) function returns the hyperbolic arc tangent of x. The result has the same data type as x.
ATANH(0.5) /* returns 0.54930 */
An ATANH operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Converts an arithmetic or string value to a binary number with an optionally specified precision.
BINARY(x[,p])
Abbreviation(s): BIN for BINARY.
x is an arithmetic or string value, and p is an integer constant specifying an optional precision.
The BINARY function converts an arithmetic or string value x to binary radix (Float Binary or Fixed Binary data type), with an optionally specified precision p.
If x is a Fixed Decimal value with a non-zero scale factor, p must be given.
If x is a Float Decimal value, the result is a Float Binary value; otherwise, the result is a Fixed Binary value. A non-zero scale factor is not allowed with a Float Decimal. If p is omitted, the result has a precision that is determined by the rules for data type conversion given in the chapter Data Type Conversions.
BINARY('2000',31);
In fixed–point context, this example returns the value 2000 as a Fixed Bin(31) integer.
None.
Returns a fixed binary integer that is the converted value of a pointer, offset, or ordinal.
BINARYVALUE(x)
Abbreviation: BINVALUE for BINARYVALUE.
x is an expression.
None.
Converts an arithmetic or string value to a bit string.
BIT(s)
or
BIT(s,l)
s is an arithmetic or string value of an optionally specified length l, and l is a positive integer.
The BIT function converts an arithmetic or string value to a bit string of an optionally specified length.
s is first converted to a bit string whose length is determined by the rules for data type conversion given in the chapter Data Type Conversions. Then, if the length l is specified, the bit string is truncated on the right or padded on the right with zero bits to the specified length.
DECLARE INTEGER FIXED BINARY(15); DECLARE BIT_STRING BIT(15); INTEGER = 20; BIT_STRING = BIT(INTEGER); /* BIT_STRING NOW EQUALS '000000000010100'B */
None.
Performs a Boolean operation on two bit-string arguments.
BOOL(x,y,z)
x and y are bit-string arguments, and z is a bit string.
The BOOL function performs a Boolean operation on two bit-string arguments, x and y, and returns the result as a bit string with the length of the longer argument.
z should be a bit string 4 bits long. If not, it is converted to Bit (4).
If x and y are null strings, the result is a null string. If x is not the same length as y, the shorter string is extended on the right with zero bits until x and y are the same length. The bit values within z are m1, m2, m3, m4 from left-to-right, respectively.
The Ith bit value of the result is set to one of the values m1, m2, m3, m4 depending on the Ith bit value of x and y according to Table 9-2.
Table 9-2: Bit value of the Result
| X(I) | Y(I) | RESULT(I) |
|---|---|---|
| 0 | 0 | m1 |
| 0 | 1 | m2 |
| 1 | 0 | m3 |
| 1 | 1 | m4 |
In other words, bit string z defines the result of some Boolean function. For instance, to define the function OR, the value of bit string z is given as '0111'b. To define the function AND, bit string z is '0001'b. The result is a bit string of the same length as x and y, obtained by applying the function rule described by z to each bit position of string x and string y.
BOOL('1100110'b,'0101'b,'0110'b) /*returns '1001110'b */
In this example, the second argument is extended to '0101000'b. For bit 1, x is 1 and y is 0. Therefore, the resulting bit is the value m3or 1. For bit 2, x is 1 and y is 1, therefore the resulting bit is the value of m4 or 0. A comparison of bits 3, 0, and 0 produces the value m1 or 0.
None.
Returns a single character whose ASCII code corresponds to the specified value.
BYTE(x)
x is a fixed-point binary integer value.
The BYTE function returns a single character whose ASCII code corresponds to the value x. The index into COLLATE() is taken by considering only the rightmost bits of x (one byte). The BYTE function uses a 256-byte collating string.
CHAR=BYTE(66) /* returns 'B' for the American English ASCII collating sequence */
None.
Returns the smallest integer greater than or equal to the specified arithmetic expression.
CEIL(x)
x is an arithmetic expression.
The CEIL function returns the smallest integer greater than or equal to x with precision (p,q). The result has the same data type as x.
If x is a floating-point value, the precision of the result is the precision of x. If x is a fixed-point value, the precision of the result is (MIN(n,MAX(p-q+1,1)),0). n is the maximum precision allowed for a fixed-point value of the result type. (For details, see your Open PL/I User's Guide.)
CEIL(-3.1) /* returns -3.0 */ CEIL(3.1) /* returns 4.0 */ CEIL(0) /* returns 0 */
None.
Converts an arithmetic or string value to a character string.
CHARACTER(s)
or
CHARACTER(sl)
Abbreviation(s): CHAR for CHARACTER.
s is an arithmetic or string value, and l is a positive integer value.
The CHARACTER function converts an arithmetic or string value s to a character string of an optionally specified length l. s is first converted to a character string whose length is determined by the rules for data type conversion given in the chapter Data Type Conversions. Then, if l is given, s is either truncated on the right or extended on the right with blanks to be l characters long.
DECLARE X FIXED BINARY (15);
DECLARE Y CHARACTER(14) VARYING;
X = 2;
Y = CHARACTER(X);
PUT LIST ('$'||Y); /* $ 2 */
The CHARACTER function does not support unaligned BIT(n) parameters.
Returns a string consisting of the character set of the National Language being used, in ascending order.
COLLATE()
or
COLLATE
The second syntax form can be used only when the BUILTIN attribute is specified.
The COLLATE function returns a character string, of a length determined for the National Language support being used (128 characters for American English), that consists of the set of characters in the computer's character set in ascending order.
In Open PL/I, COLLATE returns a string consisting of the number of characters of the character set as determined by the National Language support.
The COLLATE function uses a 256-byte collating string.
DECLARE X CHARACTER(5); X = SUBSTR(COLLATE(), 100, 5); /* returns X = 'cdefg' */
This example assumes American English National Language support.
None.
Returns the complex value x + yI.
COMPLEX(x,y)
Abbreviation: CPLX for COMPLEX.
x and y are real expressions.
If x and y differ in base, the decimal argument is converted to binary.
If x and y differ in scale, the fixed-point argument is converted to floating-point. The result has the common base and scale.
If fixed-point, the precision of the result is given by the following:
(min(N,max(p1-q1,p2-q2)+max(q1,q2)),max(q1,q2))
where (p1,q1) and (p2,q2) are the precisions of x and y, respectively, and N is the maximum number of digits allowed. After any necessary conversions have been performed, if the arguments are floating-point, the result has the precision of the longer argument
None.
Returns the conjugate of the specified expression; that is, the value of the expression with the sign of the imaginary part reversed.
CONJG(x)x is an expression.
If x is real, it is converted to complex. The result has the base, scale, mode, and precision of x.
None.
Copies a particular string a certain number of times and concatenates the result into a single string.
COPY(x,y)
x is a character-string, bit-string, or picture value, and y is a positive integer expression. If x is an arithmetic value, it is converted to a bit string if it is binary, or to a character string if it is decimal.
The COPY function copies a particular string, x, a certain number of times, y, and concatenates the result into a single string. COPY effectively returns a string containing y occurrences of the string argument, with length y* length (x).
The result is obtained by concatenating y occurrences of x together.
DECLARE X CHAR(6);
X = COPY('AB',3) /* returns X = 'ABABAB' */
Note that the same result could be produced by using a string repetition factor, as illustrated below:
X = (3) 'AB';
None.
Returns a value that is the cosine of the specified angle expressed in radians.
COS(X)
x is a floating-point value.
The COS function returns a value that is the cosine of the angle x expressed in radians. The result has the same data type as x such that -1 ≤ COS(x) ≤ 1.
COS(0.0) /* returns 1.0 */
A COS operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns a value that is the cosine of the specified angle expressed in degrees.
COSD(x)
x is a floating-point value.
The COSD function returns a value that is the cosine of the angle x expressed in degrees. The result has the same value type as x such that -1 ≤ COSD(x) ≤ 1.
COSD(60.0) /* returns 0.5 */
A COSD operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns a value that is the hyperbolic cosine of the specified arithmetic value.
COSH(x)
x is a floating-point value.
The COSH function returns a value that is the hyperbolic cosine of the angle x expressed in radians.
The result has the same data type as x such that COSH(x) ≥ 1.
COSH(0.0) /* returns 1.0 */
A COSH operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns an unscaled real fixed binary value specifying the number of data items transmitted during the last GET or PUT operation on the specified file-reference.
COUNT(x)x is a file-reference. The file must be open and have the STREAM attribute.
The count of transmitted items for a GET or PUT operation on x is initialized to zero before the first data item is transmitted, and is incremented by one after the transmission of each data item in the list. If x is not open in the current program, a value of zero is returned.
If an ON-unit or procedure is entered during a GET or PUT operation, and within that ON-unit or procedure, a GET or PUT operation is executed for x, the value of COUNT is reset for the new operation. It is restored when the original GET or PUT is continued.
None.
Returns a Fixed Bin(15) value that is the number of bytes of storage used by the current value of the referenced variable.
CURRENTSTORAGE(reference)
Abbreviation(s): CSTG for CURRENTSTORAGE.
reference is a variable.
For constant-length strings and other fixed-size variables, the CURRENTSTORAGE function returns a Fixed Bin(15) integer that is the number of bytes allocated for the referenced variable.
A variable-length string consists of two parts: the text field and the length field. CURRENTSTORAGE returns the number of bytes of the text field currently in use plus two, since the length field always uses two bytes.
For a scalar area or an element of an array of areas, the CURRENTSTORAGE function returns the sum of the current extent of the area plus the size of the area header. Any bytes at the end of the area that have not been allocated are not included in the area extent value. Note, however, that the extent does include the size of any holes in the area that have developed as a result of ALLOCATE and FREE operations. For an array of areas, the CURRENTSTORAGE function returns the maximum size of the array, including the header bytes for each area element of the array.
DCL A FIXED BIN(15) INIT (1); /* CSTG (A) = 2 */
DCL B CHAR(5) INIT ('XY'); /* CSTG (B) = 5 */
DCL C CHAR(5) VARYING INIT ('XY'); /* CSTG ©) = 4 */
DCL D BIT(4) INIT ('1010'B); /* CSTG (D) = 1 */
None.
In a NAME condition ON-unit (or any of its dynamic descendants), or an ON-unit (or any of its dynamic descendants) for an ERROR or FINISH condition raised as part of the implicit action for the NAME condition, returns a character string whose value is the contents of the field that raised the condition.
DATAFIELD[()]
None.
If the string that raised the condition contains DBCS identifiers, GRAPHIC data, or mixed character data, DATAFIELD returns a mixed character string. If DATAFIELD is used out of context, a null string is returned.
None.
Returns a character string that represents the system date.
DATE()
or
DATE
The second form can be used only when the BUILTIN attribute is specified.
The DATE function returns a character string of length 6 that represents the system date in the form yymmdd, where yy, mm, and dd are in the ranges 00–99, 01–12, and 01–31, respectively, and represent year, month, and day, respectively.
You may also define the LPI_YEAR environment variable to return any year value you want (such as 2009).
If you are using Bourne shell, do this:
LPI_YEAR=2009; export LPI_YEAR
If you are using C-shell, do this:
setenv LPI_YEAR 2009;
DATE() /* returned '891017' on October 17, 1989 */
Returns a character string that represents the system date and time of day.
DATETIME()
or
DATETIME
The second form can be used only when DATETIME has been declared with the BUILTIN attribute.
The DATE function returns a character string of length 17 that represents the system date in the form yyyymmddhhmmssttt, where:
| String | Range | Represents |
|---|---|---|
| yyyy | 0000–9999 | year |
| mm | 01–12 | month |
| dd | 01–31 | day |
| hh | 00–23 | hour |
| mm | 00–59 | minute |
| ss | 00–59 | second |
| ttt | 000–999 | millisecond |
You may also define the LPI_YEAR environment variable to return any year value you want (such as 2009).
If you are using Bourne shell, do this:
LPI_YEAR=2009; export LPI_YEAR
If you are using C-shell, do this:
setenv LPI_YEAR 2009;
DATETIME() /* returned '19940526163111585' on May 26,
1994 at 11.585 seconds after 4:31 PM */
None.
Converts an arithmetic or string value to a DECIMAL number.
DECIMAL(x)
or
DECIMAL(x,p)
or
DECIMAL(x,p,q)
Abbreviation(s): DEC for DECIMAL.
x is an arithmetic or string value, and p and q are integer constants representing precision and scale factor, respectively.
The DECIMAL function converts an arithmetic or string value x to a DECIMAL number of an optionally specified precision p and scale factor q. p indicates the precision of the result. q indicates the scale of the result. If p alone is given, q is assumed to be zero.
If x is a floating-point value, the result is a float decimal value, and q must be omitted; otherwise, the result is a fixed decimal value, and if q is omitted, the result is an integer of precision p.
If p is omitted, the result has a precision determined by the rules for type conversion given in the chapter Data Type Conversions.
DECIMAL('3.14') /* returns 3 */
Returns a fixed binary integer that is the number of elements in the specified dimension of an array.
DIMENSION(x[,n])
Abbreviation(s): DIM for DIMENSION.
x is an array and n is an integer constant greater than zero that indicates the dimension of the array.
The DIMENSION function returns an integer that is the number of elements in the specified dimension of an array x. This is useful for arrays with * extents.
n is an optional integer constant indicating the nth dimension of x. If n is not specified, the first dimension is assumed. The resulting binary integer gives the number of elements in the nth dimension of x.
The type of the result is Fixed Binary(31). x must have at least n dimensions.
DECLARE R FIXED BINARY; DECLARE A(3:5,1:2,10:10,4:7); . . . R=DIMENSION(A,1); /*R=3*/ . . .
The DIMENSION function is not supported with expression arguments.
Divides an arithmetic value by an arithmetic value and returns the quotient with a specified precision and an optionally specified scale factor.
DIVIDE(x,y,p)
or
DIVIDE(x,y,p,q)
x and y are arithmetic values, and p and q are integer constants that represent precision and scale factor, respectively.
The DIVIDE function divides an arithmetic value, x, by an arithmetic value, y, and returns the quotient with a specified precision p and an optionally specified scale factor q.
The result is xly, having the common data type of x and y.
The precision of the result is (p,q) or (p). In the latter case, q equals zero.
If y equals zero, the program is in error and the ZERODIVIDE condition is raised.
DECLARE SUM FIXED BINARY(15);
.
.
.
PUT LIST ('HALF PRICE IS'||DIVIDE (SUM, 2, 15));
The parameter q must not occur unless the result type is decimal.
Returns an area whose extent is zero. This can be used to free all allocations in an area.
EMPTY()
or
EMPTY
The second syntax form can be used only if EMPTY has been declared with the BUILTIN attribute.
The value returned by this function is the same as the one used by the Compiler to initialize an area when it is allocated.
DECLARE A AREA,
0 OFFSET(A),
X FIXED EASED(0);
ALLOCATE X IN(A) SET(0);
A = EMPTY(); /* Frees all allocations in A. */
None.
Returns a pointer value that is the address of the first executed instruction if the specified entry is invoked.
ENTRYADDR(x)x is an entry reference.
x must represent a non-nested procedure. If x is a fetchable entry constant, it must be fetched before ENTRYADDR is executed.
None.
Initializes an entry variable with the address of the entry to be invoked.
ENTRYADDR(x)x is an entry reference.
If the address supplied to the ENTRYADDR variable is the address of an internal procedure, results are unpredictable.
None.
Returns a real floating point value that is an approximation of the error function of x.
ERF(x)x is a real expression.
The result has the base and precision of x, and a value given by (2/ &sqrt.(&pi.) ) &integral.(x)[0] EXP(-(t(2) ))dt.
None.
Returns a real floating point value that is an approximation of the complement of the error function of x.
ERFC(x)x is a real expression.
The result has the base and precision of x, and a value given by: 1 - ERF(x).
None.
Returns the base of the natural logarithm raised to the specified power.
EXP(x)
x is an arithmetic expression.
The EXP function returns the value of the base of the natural logarithm e raised to the power of x or e**x.
The result has the same data type as x.
EXP(2.0) /* returns approximately 7.389056 */
An EXP operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Converts an arithmetic or string value to a fixed-point arithmetic value with a specified precision and, optionally, a scale factor.
FIXED(x,p)
or
FIXED(x,p,q)
x is an arithmetic or string value, and p and q are integer constants representing precision and scale factor, respectively.
The FIXED function converts an arithmetic or string value x to a fixed-point arithmetic value with a specified precision p and, optionally, a scale factor q. If q is omitted, q equals zero. The resulting fixed-point arithmetic value is converted according to the rules for type conversion given in the chapter Data Type Conversions.
FIXED(9.8614E+01,15,2) /* returns 98.61 */
None.
Converts a string or arithmetic value to a floating-point arithmetic value, with a specified precision.
FLOAT(x,p)
x is a string or arithmetic value, and p is an integer representing precision.
The FLOAT function converts a string or arithmetic value x to a floating-point arithmetic value, with a specified precision p. The resulting floating-point arithmetic value is converted according to the rules for type conversion given in the chapter Data Type Conversions.
FLOAT(98.614,8) /* returns 9.8614 E+01 */
Ensures that all disk I/O on a specified file has been written to disk, as opposed to remaining in I/O buffers.
FLUSH(f);
f is a filename.
The FLUSH subroutine is used to ensure that all disk I/O on file f has been written to disk. This subroutine might be called in order to ensure some sort of synchronization, such as during critical I/O, or if there is a concern of a system crash or some other serious problem such that you may to want to make sure that the last I/O was in fact written out to disk.
DECLARE MYFILE FILE; WRITE FILE(MYFILE) FROM(RECORD); CALL FLUSH(MYFILE);
None.
Returns the largest integer that is less than or equal to the specified arithmetic expression.
FLOOR(x)
x is an arithmetic expression.
The FLOOR function returns the largest integer that is less than or equal to an arithmetic expression x.
If x is a floating-point value, the precision of the result is the precision of x. If x is a fixed-point value, the precision of the result is (MIN(n,MAX(p-q+1,1)),0). n is the maximum precision allowed for fixed-point values of the result type. (For details on maximum precisions, see your Open PL/I User's Guide.)
FLOOR(3.125) /* returns 3.000 */ FLOOR(-3.125) /* returns -4.000 */ FLOOR(0) /* returns 0 */
None.
Can be use to explicitly convert character (or mixed character) data to GRAPHIC data. All other data first converts to character, and then to the GRAPHIC data type.
Returns the graphic value of x, with a length in graphic symbols specified by y.
Characters convert to graphics. The content of x is checked for validity during conversion, using the same rules as for checking graphic and mixed character constants.
GRAPHIC(x[,y])
x and y are expressions.
When x is GRAPHIC it is subject to a length change, with appropriate padding or truncation. When x is nongraphic it is converted to character, if necessary. SBCS characters are converted to equivalent DBCS characters.
When necessary, y is converted to a real fixed-point binary value. If y is omitted, the length is determined by the rules for type conversion. y must not be negative.
If y = 0, the result is the null graphic string.
The following rules apply:
None.
Returns a fixed-point binary integer that is the upper bound of a specified dimension of an array.
HBOUND(x[,n])
x is an array variable and n is an integer constant indicating the nth dimension of x.
The HBOUND function returns a fixed-point binary integer that is the upper bound of a specified dimension of an array x. This allows you to determine the upper bound of an array with * extents.
n is the specified dimension of the array. If n is not present, 1 is assumed. When present, n must be greater than zero and less than or equal to the number of dimensions declared.
The precision of the result is Fixed Binary(31).
DECLARE R FIXED BINARY; DECLARE A(3:5,2,-10:10,4:7); . . . R = HBOUND(A,1); /*R = 5*/ . . . R = HBOUND(A,2); /*R = 2*/ . . .
The HBOUND function is now supported with expression arguments.
Returns a character string made up of the highest character in the collating sequence.
HIGH(x)
x is an expression whose value is a non-negative integer.
The HIGH function returns a character string of length x, in which each character is the highest character in the collating sequence (ASCII = hex 7F).
The HIGH function uses a 256-byte collating string.
The value of x must be non-negative. If x = 0, the result is the null character string.
HIGH(3) /* Returns a character string whose length
is equal to 3 characters and in which
each character is hexadecimal 7F. */None.
Returns the imaginary part of x. The mode of the result is real and has the base, scale, and precision of x.
IMAG(x)x is an expression.
If x is real it is converted to complex and an appropriate zero value is returned.
None.
Assigns a real value or the real part of a complex value to the coefficient of the imaginary part of the specified reference.
IMAG(x)x is a complex reference.
None.
Searches a string for a specified substring and returns a fixed binary integer value indicating its position.
INDEX(s,c)
s and c are both either character or bit strings, and c may be a substring of s.
The INDEX function searches a string, s, for a specified substring, c, and returns an integer value indicating the position of c within s.
If either s or c is a null string, the result is zero. If the substring c is not contained within s, the result is zero; otherwise, the result is an integer indicating the position within s of the leftmost character or bit (if s and c are bit strings) of the substring c. The result precision is Fixed Binary(15).
INDEX('abcdefg','def') /* returns 4 */
INDEX('AAA', 'A') /* returns 1 */
INDEX('A', 'AA') /* returns 0 */None.
Interprets specified storage as a signed integer and returns the value of that integer.
INT(expression[,position[,length]])
expression is a scalar expression or reference to connected storage. expression cannot be an array, structure, or named constant. position is a positive integer value specifying the position of the first bit in the field; length is a positive integer value in the range 0–32 specifying the length of the field.
The INT function interprets the storage specified as a signed integer and returns the value of that integer. the INT function does not perform conversion, so that the value returned depends on the data type of the variable contained in the specified storage.
If position is specified, its minimum value is 1 and its maximum value is the length in bits of the storage specified by expression. If position is omitted, the default value is 1.
If length is specified, its minimum value is 0 and its maximum value is the length in bits of the storage specified by expression, less the value of position. If length is omitted, the default value is equal to the number of bits from the bit indicated by position to the end of the storage specified by expression.
If position and length are not specified, the length of the storage referenced by expression cannot exceed 32 bits.
INT returns a value of type Fixed Bin(31). If the field has a length of zero, INT returns zero.
INT and POSINT are identical functions, except that POSINT returns an unsigned integer.
The result of this function is dependent on the native byte ordering of the hardware you are using. For this reason, the use of this function may not be portable across different platforms.
DCL A BIT(32); A = '12345678'B4; PUT SKIP LIST(INT(A,5,4)); END TEST;
None.
Returns a fixed binary integer value giving the lower bound of the specified dimension of an array.
LBOUND(x[,n])
x is an array variable, and n is an integer constant indicating the dimension of x.
The LBOUND function returns an integer value that gives the lower bound of the nth dimension of x. This is useful for arrays with * extents.
n is the specified dimension of the array. If n is not present, 1 is assumed. When present, n must be greater than zero and less than or equal to the number of dimensions declared.
DECLARE R FIXED BINARY; DECLARE A(3:5,2,-10:10,4:7); . . . R = LBOUND(A,1); /*R = 3*/ . . . R = LBOUND(A,2); /*R = 1*/ . . .
The LBOUND function is not supported with expression arguments.
Returns a Fixed Binary integer that gives the number of characters or bits in the specified string.
LENGTH(s)
s is a Character, Bit String, or Picture value. If s is a binary value, it is converted to a Bit string. If it is a decimal value, it is converted to a character string.
The LENGTH function returns an integer that gives the number of characters or bits in the string s, where s is either a character string or a bit string. For character varying strings, this is the length of the string currently stored in the variable.
The precision of the result is Fixed Binary(15). A null string has length zero.
TEST: PROCEDURE(A);
DCL A CHARACTER(20) VARYING STATIC INITIAL ('ABC');
DCL X FIXED BINARY(15);
X = LENGTH(A); /* GET CORRECT LENGTH = 3 */
END TEST;
None.
Returns a Fixed Binary integer that gives the line number of an open file control block with the specified PRINT attribute.
LINENO(x)
x is a file value representing a file control block.
The LINENO function returns an integer that gives the line number of an open file control block identified by x.
The precision of the result is Fixed Binary(15).
x must identify an open file control block with the PRINT attribute.
DECLARE X FILE; . . . CURRENT = LINENO(X); /* GET CORRECT LINE # */
None.
Returns the natural logarithm of an arithmetic expression.
LOG(x)
x is a floating-point value greater than zero.
The LOG function returns the natural logarithm of x. Note that LOG(x) is the inverse of EXP(x), that is, LOG(EXP(x)) = x = EXP(LOG(x)).
The result has the same data type as x.
LOG(7.389056) /* returns 2 */
An LOG operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns the logarithm of an arithmetic expression to the base 10.
LOG10(x)
x is a floating-point value greater than zero.
The LOG10 function returns the logarithm of x to the base 10. Note that LOG10(x) is the inverse of 10**x, that is, 10**LOG10(x) = x = LOG10(10**x).
The result has the same data type as x.
LOG10(100.0) /* returns 2 */
A LOG10 operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns the logarithm of an arithmetic expression to the base 2.
LOG2(x)
x is a floating-point value greater than zero.
The LOG2 function returns the logarithm of x to the base 2. Note that LOG2(x) is the inverse of 2**x, that is, 2**LOG2(x) = x = LOG2(2**x).
The result has the same data type as x.
LOG2(0.5) /* returns -1 */
An LOG2 operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns a character string made up of the lowest character in the collating sequence.
LOW(x)
x is an expression whose value is a non-negative integer.
The LOW function returns a character string of length x, in which each character is the lowest character in the collating sequence (hex 00).
The LOW function uses a 256-byte collating string.
The value of x must be non-negative. If x = 0, the result is the null character string.
LOW(3) /* Returns a character string whose length
is equal to 3 characters and in which
each character is hexadecimal 00. */None.
Returns a fixed binary(15) integer that represents the number of parameters passed to a PL/I subroutine.
LPIPARAMCOUNT()
or
LPIPARAMCOUNT
?
The LPIPARAMCOUNT built-in function returns the number of parametes passed to an Open PL/I procedure from another PL/I procedure. To be able to use this function, the calling procedure has to be compiled with the -paramount compile time option, or that procedure has to have an entry name attribute OPTIONS(LPIPARAMCOUNT).
main: procedure options(main);
declare subr entry;
...
call subr();
...
call subr(x,y,z);
end main;
subr: procedure(p1,p2,p3,p4);
...
declare no_of_args fixed bin(15);
no_of_args = lpiparamcount();
put skip list ('Number of arguments passed to SUBR: ',
no_of_args);
end subr;
If the main program is compiled with the -paramcount option, the above example will print:
Number of arguments passed to SUBR: 0 Number of arguments passed to SUBR: 3
None.
Returns the greatest of one or more values.
MAX(x,…)
x and any subsequent values are arithmetic values.
The MAX function returns the largest of a set of arithmetic values. x and any subsequent values are converted to a common arithmetic data type (using the conversion rules for arithmetic infix operators) before the operation is performed. x and any subsequent values cannot be string values. The result is the largest of these converted values and has the common arithmetic data type.
MAX(5, -118, 1) /* returns 5 */ MAX(12.3, 13, 9.68) /* returns 13.0 */
None.
Returns the smallest of one or more values.
MIN(x,...)
x and any subsequent values are arithmetic values.
The MIN function returns the smallest of a set of arithmetic values. x and any subsequent values are converted to a common arithmetic data type (using the conversion rules for arithmetic infix operators) before the operation is performed. x and any subsequent values cannot be string values. The result is the smallest of these converted values and has the common arithmetic data type.
MIN(5,-118, 1) /* returns -118 */ MIN(12.3, 11, 9.68) /* returns 9.68 */
None.
Returns the truncated remainder of x divided by y.
MOD(x,y)
x and y are arithmetic values.
The MOD function returns the truncated remainder of x divided by y. The result is x-y*FLOOR(x/y) and has the common data type of x and y.
To determine the precision of the result, let (px,qx) and (py,qy) represent the precision of x and y, respectively. If the common type of x and y is fixed point, the precision of the result is:
(MIN(n,py-qy+MAX(qx,qy)),MAX(qx,qy))
Otherwise, the precision of the result is MAX(px,py). n is the maximum precision allowed for the common type of x and y. For details on maximum precisions, see your Open PL/I User's Guide.
MOD(15,2) /* returns 1 */
The value of y must not be 0.
An MOD operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Truncates a string at a logical boundary and returns a mixed character string. It does not truncate a double-byte character between bytes. The length of the returned string is equal to the length of the expression x, or to the value specified by y.
MPSTR(x,r[,y])
x, y, and r are expressions.
x yields the character string result. The value of x is converted to character if necessary.
r yields a character result. The expression cannot be GRAPHIC and is converted to character if necessary. r specifies the rules to be used for processing the string.
The characters that can be used in r and the rules for them are as follows:
| V or v | Validates the mixed string x and returns a mixed string. | |
| S or s | Removes any null DBCS strings, creates a new string, and returns a mixed string. |
If both V and S are specified, V takes precedence over S, regardless of the order in which they were specified. If S is specified without V, the string x is assumed to be a valid string. If the string is not valid, results are undefined.
y, if necessary, is converted to a real fixed point binary value. If y is omitted the length is determined by the rules for type conversion. The value of y cannot be negative.
If y = 0, the result is the null character string. If y is greater than the length needed to contain x, the result is padded with blanks. If y is less than the length needed to contain x, the result is truncated by discarding excess characters from the right (if they are SBCS characters), or by discarding as many DBCS characters (2-byte pairs) as needed.
r is ignored on Intel and AIX.
Multiplies an arithmetic value by an arithmetic value and returns the product with a specified precision and an optionally specified scale factor.
MULTIPLY(x,y,p)
or
MULTIPLY(x,y,p,q)
x and y are arithmetic values, and p and q are integer constants that represent precision and scale factor, respectively.
The MULTIPLY function multiplies an arithmetic value, x, by an arithmetic value, y, and returns the sum with a specified precision p and an optionally specified scale factor q.
The result is x*y, having the common data type of x and y.
The precision of the result is (p,q) or (p). In the latter case, q equals zero.
DECLARE (LENGTH, WIDTH) FIXED BINARY(15);
.
.
.
PUT LIST ('TOTAL AREA IS'||MULTIPLY (LENGTH, WIDTH, 31));
The parameter q must not occur unless the result type is decimal.
Returns a null pointer value.
NULL()
or
NULL
The second syntax form can be used only when the BUILTIN attribute is specified.
The NULL function returns a null pointer value.
In Open PL/I, the value of the NULL built-in function is a fictitious address, which is distinct from any valid pointer address.
The -setnull compiler option allows you to designate a particular null pointer value at compile time. The default NULL value is -1 (all 1 bits). For a description of the -setnull compiler option, see your Open PL/I User's Guide.
IF LAST_POINTER = NULL() THEN CALL FINISH;
In this example, the IF statement determines whether the pointer variable LAST_POINTER is null; if so, the CALL statement executes.
None.
Returns an offset value relative to an area and derived from a pointer.
OFFSET(p,a)
p is a pointer reference identifying a based variable; a is the area containing the based variable.
The OFFSET function returns an offset value that is the relative byte offset of a based variable stored within an area variable.
If p is the null pointer value, the OFFSET function returns the null offset value.
DECLARE (A, B) AREA;
DECLARE (A1, A2) CHAR(20) BASED;
DECLARE (P1, P2) POINTER;
DECLARE (01, 02) OFFSET(A);
DECLARE (03, 04) OFFSET(B);
ALLOCATE A1 IN(A) SET(01);
ALLOCATE A2 IN(A) SET(02);
B = A; /* assign area */
P1 = ADDR(01->A1); /* address of A1 in A */
P2 = POINTER(02, B); /* address of A2 in B */
03 = OFFSET(P1, A); /* offset value of A1 -
same in A and B */
04 = OFFSET(P2, B); /* offset value of A2 -
same in A and B */
None.
Returns a character string of length 1, containing the character that caused the CONVERSION condition to be signaled.
ONCHAR()
or
ONCHAR
The second syntax form can be used only when ONCHAR has been explicitly declared with the BUILTIN attribute.
The ONCHAR function returns a character string of length 1, containing the character that caused the CONVERSION condition to be signaled.
The ONCHAR function can be used in an ON-unit established for a CONVERSION condition. It can also be used for an ERROR ON-unit that obtains control as the result of unsuccessful error correction in the CONVERSION ON-unit.
DCL I FIXED BIN(15);
ON CONVERSION BEGIN;
PUT LIST ('Incorrect character is:',ONCHAR());
END;
I = '34Z9';
In the above example, the program will display the character "Z" that caused the conversion error to occur.
None.
Returns a fixed-point binary integer that is the status value of the most recent run-time error that signaled the current ON condition.
ONCODE()
or
ONCODE
The second syntax form can be used only when the BUILTIN attribute is specified.
The ONCODE function returns a binary integer that is the status value of the most recent run-time error that signaled the current ON condition. The result has an implementation-defined precision. (For details on precisions, see your Open PL/I User's Guide.) The ONCODE function can be used in any ON-unit to ascertain the exact error that caused the condition. Used within any context other than an ON-unit, the ONCODE function returns a zero.
For the values of the run-time errors that signal particular ON conditions, see your Open PL/I User's Guide.
ON ERROR BEGIN;
PUT EDIT ('ERROR NUMBER', ONCODE()) (SKIP, A, F(10));
END;
None.
ONCOUNT returns an unscaled real fixed binary value specifying the number of conditions that remain to be handled when an ON-unit is entered.
ONCOUNT[()]
None.
ONCOUNT can be used in any ON-unit, or any dynamic descendant of an ON-unit. If ONCOUNT is used elsewhere, zero is returned.
None.
Returns the name of a file constant for which the most recent ENDPAGE, ENDFILE, KEY, or UNDEFINEDFILE condition was signaled.
ONFILE()
The ONFILE function returns the name of a file constant for which the most recent ENDPAGE, ENDFILE, KEY, or UNDEFINEDFILE condition was signaled. The ONFILE function can also be used in an ERROR ON-unit that gets control as a consequence of the default Open PL/I action for file-related errors. (The default action for file-related errors is to signal the ERROR condition.)
The returned value is a varying length character string.
On some systems, you may need to specify the -defext compile-time option for ONFILE to return the correct value. For specific information, see your Open PL/I User's Guide.
If referenced outside an ON-unit or within an ON-unit that is executed as a result of a SIGNAL statement, the ONFILE function returns a null string.
If used outside an ON-unit or within an ON-unit that has been invoked as the result of a condition unrelated to any file, the ONFILE function returns a null string.
All other uses of such files must be in other modules compiled without the -defext compile-time option or declared with the GLOBALREF attribute.
For more information on the -defext option, see your Open PL/I User's Guide. For more information on the GLOBALREF attribute, see the section GLOBALREF
Returns the key value that precipitated the signaling of the condition during an input/output operation to a file that is being accessed.
ONKEY()
The ONKEY function returns the key value that precipitated the signaling of the KEY condition during an input/output operation to a file that is being accessed by key.
The ONKEY function can be used in an ON-unit established for the ENDFILE, KEY, RECORD, and UNDEFINEDFILE conditions. It can also be used for an ERROR ON-unit that obtains control as a result of the default Open PL/I action for the KEY condition. (The default action is to signal the ERROR condition.)
The returned value is a varying length character string.
ON KEY(DFILE) BEGIN;
PUTEDIT ('DFILE KEY',ONKEY(),'NOT FOUND')(SKIP,3 A);
END;
If the ONKEY function is referenced outside an ON-unit or within an ON-unit executed as a consequence of a condition not related to a file being accessed by key, it will return the null string.
Returns the name of an entry in which a condition was raised.
ONLOC()
When the ONLOC function is called under the control of an ON-unit (that is, from the ON-unit or any procedure called by the ON-unit), it returns a character string whose value is the name of the entry in which the condition was raised that caused the ON-unit to be invoked. If a call to the ONLOC function is made not under the control of an ON-unit, ONLOC() returns the null string.
SUBPROG: PROCEDURE(X) RETURNS(FLOAT BIN(23));
DECLARE X FLOAT BIN(23);
ON ERROR BEGIN;
PUT LIST('Error at ', ONLOC());
PUT SKIP;
GOTO HIGHER_LEVEL_EXIT;
END;
X = X / (X-X);
RETURN(X);
END SUBPROG;
Execution of this subprogram causes the following text to be displayed:
Error at SUBPROG
This feature is currently available only on HP-UX and Sun SPARC Solaris 2 systems.
Returns a character string whose value is the context of the field that was being processed when the CONVERSION condition was signaled.
ONSOURCE()
or
ONSOURCE
The second syntax form can be used only when ONSOURCE has been explicitly declared with the BUILTIN attribute.
The ONSOURCE function returns a character string whose value is the context of the field that was being processed when the CONVERSION condition was signaled.
The ONSOURCE function can be used in an ON-unit established for a CONVERSION condition. It can also be used for an ERROR ON-unit that obtains control as the result of unsuccessful error correction in the CONVERSION ON-unit.
The returned value is a varying-length character string.
DCL BT BIT(4);
ON CONVERSION BEGIN;
PUT LIST ('Incorrect string is:',ONSOURCE());
END;
T = '1021';
In the above example, the program will display the string "1021" that caused the conversion error to occur because only characters 0 and 1 are valid for a bit data type.
None.
Returns a fixed binary integer that gives the current page number in the specified file.
PAGENO(x)
x is a file value that identifies a file control block.
The PAGENO function returns an integer that gives the current page number in the file control block identified by x.
The precision of the result is Fixed Binary(15).
If x does not identify an open file control block with the PRINT attribute, the program is in error. This implementation of PL/I may not diagnose all violations of this restriction.
For a description of the PAGENO function's use as a pseudovariable, see the section ASSIGNMENT Statement.
DECLARE X FILE; . . . CURRENT = PAGENO(X); /* GET CURRENT PAGE # */
None.
Sets the Open PL/I return code.
CALL PLIRETC(x);
x is an arithmetic value.
The PLIRETC built-in subroutine sets a return code that can be examined using the PLIRETV built-in function. When the program ends, the last value used in a call to PLIRETC is returned to the system as the program's exit status.
The argument to PLIRETC is converted to a Fixed Binary (31) value, but the actual precision of the value that is stored and returned to the system may be lower, depending on the implementation. For details on precisions, see your Open PL/I User's Guide.
For more information on the PLIRETV function, see the section PLIRETV Function.
ON ERROR CALL PLIRETC (1);
None.
Returns a fixed binary integer that is the Open PL/I return code.
PLIRETV()
or
PLIRETV
The PLIRETV function returns the most recent value specified by a CALL PLIRETC statement. Note that the precision of the returned value may be smaller than that of the value passed to PLIRETC, and the precision of the value returned to the system at program termination may be even smaller than that returned by PLIRETV, depending on the implementation. (For more information on this implementation, see your Open PL/I User's Guide.) For example, the PLIRETC and PLIRETV routines may preserve their fixed binary (31) value, but the value may be truncated (using the MOD function) to only the rightmost byte of that value when the program exits.
For more information on the PLIRETC function, see the section PLIRETC Function.
CALL READ_LINE (BUFFER);
IF PLIRETV ()
THEN PUT LIST ("ERROR ON INPUT");
None.
These routines enable data to be sorted, with source and destination as indicated by the following table:
| Input Data From | Output Data To | |
| PLISRTA | Input file | Output file |
| PLISRTB | Procedure | Output file |
| PLISRTC | Input file | Procedure |
| PLISRTD | Procedure | Procedure |
RECORD | Input file | ?? |
Note:
You may substitute sort routines supplied by SyncSort for these sort routines. For details, see the section Using Open PL/I with Other Software Products of your Open PL/I User's Guide.
CALL PLISRTA(fields–spec, records-spec, storage, ret-code [,prefix][,msg-level] [,algorithm]);
CALL PLISRTB(fields-spec, records-spec, storage, ret-code, input-proc[,prefix][msg-level][,algorithm]);
CALL PLISRTC(fields-spec, records-spec, storage, ret-code, output-proc [,prefix][,msg-level] [,algorithm]);
CALL PLISRTD(fields-spec, records-spec, storage, ret-code, input-proc, output-proc [,prefix] [,msg-level][,algorithm]);
fields-spec is a character-string having the following format:
`SORTFIELDS=(pos,len,type,seq,[,posj,lenj,typej,seqj]...)
[,options-list]'
, in each of the three
instances, represents one or more space characters. These are the only spaces
that may occur in the string.
| CH | character string |
| ZD | pictured |
| PD | fixed decimal |
| Fl | fixed binary |
| BI | bit string |
| FL | float binary |
Open PL/I requires the key type to be CH.
The following items can be specified in the options-list:
| FILSZ=n | Specifies the number of records in the sort. This option is ignored. |
| SKIPREC=n | Specifies that n records at the beginning of the input file are to be skipped. |
| CKPT or CHKPT | Specifies that checkpoints are to be taken. This option is ignored. |
| EQUALS | Specifies a stable sort algorithm (that is, that records with identical key values are to be kept in the same order they have in the input file or were given by the input procedure. |
| NOEQUALS | Specifies that a stable sort algorithm will not be used. This is the default. |
| DYNALLOC=(d,n) | Specifies the intermediate storage. This option is ignored. |
records–spec is a character-string having the following format:
`RECORDTYPE=rectype,LENGTH=(len)[,ftype]'
,
in each of the three instances, represents one or more space characters. These
are the only spaces that may occur in the string.
storage: This argument is ignored. Use the environment variable SORTMEM to specify the amount of memory to make available. For example,
setenv SORTMEM 6
The units for SORTMEM are megabytes, and the default is 3.
algorithm: this argument is ignored. Use the environment variable SORTALG to specify the sort algorithm to be used. For example,
setenv SORTALG 1
The choices for SORTALG are:
The input records are sorted as specified by the parameters and written to the output file or passed to the output procedure, as appropriate.
If an input or output procedure is used, it is called repeatedly by the sort subroutine, once for each record involved in the sort. Hence, the procedure must be written so as to process one record at a time. These procedures are ordinary PL/I procedures, and all PL/I language rules apply. Any contained AUTOMATIC variables are reinitialized at each invocation of the procedure and any allocated BASED or CONTROLLED variables are freed when the procedure returns.
An input procedure must have the form:
IN_PROC: PROCEDURE RETURNS(CHAR(len)); DECLARE S CHAR(len); IF LAST_REC THEN DO; CALL PLIRETC(8); /* must tell the sort routine all records have been sent */ RETURN(S); END; ELSE DO; /* code to produce the record goes here */ CALL PLIRETC(12); /* tell the sort routine this is not the last record */ RETURN(S); END; END IN_PROC;
An output procedure must have the form:
OUT_PROC: PROCEDURE(S); DECLARE S CHAR(*); /* code to process the sorted record goes here */ CALL PLIRETC(4); /* tell the sort routine to continue sending records */ END OUT_PROC;
In the output procedure, use CALL PLI RETC(16); to tell the sort routine to terminate unsuccessfully.
test: proc options(main);
/* Examples of SORT Bifs */
/* Uses a data file of name 'SRT1_IN', which must exist.
/* The contents of 'SRT1_IN' are shown below. */
dcl (plisrta, plisrtb, plisrtc, plisrtd) builtin;
declare ret_code fixed bin(31);
declare (input_proc,output_proc) entry;
declare eof bit(1);
declare x file;
declare rec char(20);
put skip list('Calling srta -----------------------------');
call plisrta(' sort fields=(1,10,ch,a),equals',
' record type=f,length(20) ',
0 , /* strg */
ret_code,
'SRT1_', /* data name prefix */
'AP', /* msg level */
'xxxx' /* sort method */);
put skip list('result code is ', ret_code);
/* display output file of above */
open file(x) record title('SRT1_OUT');
eof = '0'b;
on endfile(x) eof='1'b;
read file(x) into(rec);
do while(eof = '0'b);
put skip list(rec);
read file(x) into(rec);
end;
close file(x);
revert endfile(x);
put skip(2) list('Calling srtb --------------------------------');
call plisrtb(' sort fields=(1,10,ch,a)',
' record type=f,length(20) ',
0 , /* strg */
ret_code,
input_proc,
, /* data name prefix */
'AP', /* msg level */
'xxxx' /* sort method */);
put skip list('result code is ',ret_code);
/* display output file of above */
open file(x) stream title('SORTOUT');
eof = '0'b1;
on endfile(x) eof='1'b1;
read file(x) into(rec);
do while(^eof);
put skip list(rec);
read file(x) into(rec);
end;
close file(x);
revert endfile(x);
put skip(2) list('Calling srtc --------------------------------');
call plisrtc(' sort fields=(1,10,ch,a) ',
' record type=f,length(20) ',
0 , /* strg */
ret_code,
output_proc,
'SRT1_', /* data name prefix */
'AP', /* msg level */
'xxxx' /* sort method */);
put skip list('result code is ',ret_code);
put skip(2) list('Calling srtd --------------------------------');
call plisrtd(' sort fields=(1,10,ch,a),skiprec=3 ',
' record type=f,length(20) ',
0 , /* strg */
ret_code,
input_proc,
output_proc,
, /* data name prefix */
'AP', /* msg level */
'xxxx' /* sort method */);
put skip list('result code is ',ret_code);
end test;
input_proc: procedure returns(char(20));
dcl x char(20);
dcl cnt fixed bin(31) static internal initial(0);
dcl rec(1:5) char(20) static internal initial (
'abc2', 'abc4', 'abc1', 'abc6', 'abc3');
cnt = cnt + 1;
if cnt <= 5 then do;
x=rec(cnt);
call pliretc(12);
end;
else do;
x = '';
call pliretc(8); /* no more */
cnt = 0;
end;
return(x);
end input_proc;
output_proc: procedure(x);
dcl x char(*);
put skip list(x);
call pliretc(4); /* ready for more */
end output_proc;test: proc options(main);
/* Test of SORT Bif using a indexed file as input.
/* The input file is 1st created by this program prior to the sort. */
/*
/* How to compile/link
/*
/* mfplx srt2.pl1 -defext -cisam
*/
/* Output of this program:
/*
/* Creating a indexed file with following records:
/*
/* Calling plisrtc ---------------------------------------
/* Sorting on 2nd column ASCENDING, 1st column DECENDING
/* Boston abc
/* Albany ccc
/* Westboro xyz
/* Milford xyz
/* Acton xyz
/*
/**/
dcl plisrtd builtin;
declare ret_code fixed bin(31);
declare (input_proc,output_proc) entry;
dcl SORTIN direct env(vsam keylength(8) keyloc (5) recsize(50));
dcl rec char(50);
%replace KEY2 by 40; /* be sure to change other references */
%replace KEY2_LEN by 3; /* be sure to change other references */
put skip list('Creating a indexed file with following records:');
open file(SORTIN) output;
rec = ' ';
substr(rec,KEY2,KEY2_LEN) = 'ccc';
write file(SORTIN) from(rec) keyfrom('Albany');
rec = ' ';
substr(rec,KEY2,KEY2_LEN) = 'xyz';
write file(SORTIN) from(rec) keyfrom('Acton');
rec = ' ';
substr(rec,KEY2,KEY2_LEN) = 'abc';
write file(SORTIN) from(rec) keyfrom('Boston');
rec = ' ';
substr(rec,KEY2,KEY2_LEN) = 'xyz';
write file(SORTIN) from(rec) keyfrom('Westboro');
rec = ' ';
substr(rec,KEY2,KEY2_LEN) = 'xyz';
write file(SORTIN) from(rec) keyfrom('Milford');
close file(SORTIN);
put skip;
put skip list('Calling plisrtc ---------------------------------------');
put skip list('Sorting on 2nd column ASCENDING, 1st column DECENDING');
call plisrtc(' sort fields=(40,3,ch,a,5,8,ch,d) ',
' record type=f,length(50),indexed ',
0 , /* strg */
ret_code, /* result status */
output_proc,
, /* data name prefix */
'AP', /* msg level */
'xxxx' /* sort method */);
put skip list('result code is ',ret_code);
end test;
output_proc: procedure(x);
dcl x char(*);
put skip list(x);
call pliretc(4); /* ready for more */
end output_proc;
None.
Returns a pointer value specifying the generation of a based variable in an area.
POINTER(o,a)
Abbreviation(s): PTR for POINTER.
o is an offset reference that specifies the generation of a based variable in the area identified by a.
If o is the null offset value, the POINTER function returns the null pointer value; otherwise, the value of o must be the offset of some based variable's allocation in an area, but not necessarily in a.
The result returned by the POINTER function is the sum of the offset value, o, plus the address of the beginning of the area, a.
DECLARE (A, B) AREA; DECLARE (A1, A2) CHAR(20) BASED; DECLARE (P1, P2) POINTER; DECLARE (01, 02) OFFSET; ALLOCATE A1 IN(A) SET(01); ALLOCATE A2 IN(A) SET(02); B = A; /* assign area */ P1 = POINTER(01, B); /* address of A1 in B */ P2 = POINTER(02, B); /* address of A2 in B */
None.
Increments (or decrements) a pointer value by an integer value.
POINTERADD(x,y)
Abbreviation(s): PTRADD for POINTERADD.
x is a pointer expression. y is a fixed binary(31) value or a value that can be converted to a fixed binary(31) value.
The POINTERADD function returns a pointer value that is the pointer value x incremented by y bytes (or decremented by y bytes if y is negative).
DECLARE A CHAR(10) BASED INIT('0123456789');
DECLARE B CHAR(3);
DECLARE P POINTER;
ALLOCATE A SET(P);
B = POINTERADD(P,3)->A; /* This yields B = '345'. */
None.
Returns a pointer value that is the converted value of the specified expression.
POINTERVALUE(x)
Abbreviation: PTRVALUE for POINTERVALUE.
x is an expression. It must have either the HANDLE attribute, or have a computational type. If x has a computational type, it is converted to fixed binary.
You can use POINTERVALUE(x) to initialize static pointer variables if x is a constant.
None.
Returns a floating point value that is an approximation of a polynomial formed from the specified one-dimensional array expression. The returned value has the same attributes as the first argument.
POLY(x,y)
x is an array expression, and y is an element expression.
x must be real float and y is converted to the attributes of x, if necessary.
If x has lower bound 0 and upper bound n, the result is a classic polynomial of degree n in y with coefficients given by x: x(0) + x(1)*y + x(2)*y**2 + ... + x(n)*y**n.
In the general case, where x has lower bound m and upper bound n, the result is the polynomial x(m) + x(m+1)*y + x(m+2)*y**2 + ... + x(n)*y**(n-m)
None.
Interprets specified storage as an unsigned integer and returns the value of that integer.
POSINT(expression[,position[,length]])
expression is a scalar expression or reference to connected storage. expression cannot be an array, structure, or named constant. position is a positive integer value specifying the position of the first bit in the field; length is a positive integer value in the range 0 – 32 specifying the length of the field.
The POSINT function interprets the storage specified as an unsigned integer and returns the value of that integer. The POSINT function does not perform conversion, so that the value returned depends on the data type of the variable contained in the specified storage.
If position is specified, its minimum value is 1 and its maximum value is the length in bits of the storage specified by expression. If position is omitted, the default value is 1.
If length is specified, its minimum value is 0 and its maximum value is the length in bits of the storage specified by expression, less the value of position. If length is omitted, the default value is equal to the number of bits from the bit indicated by position to the end of the storage specified by expression.
If position and length are not specified, the length of the storage referenced by expression cannot exceed 32 bits.
POSINT returns a value of type Fixed Bin(31). If the field has a length of zero, POSINT returns zero. Because POSINT returns an unsigned integer, it is possible for the value returned to be too large for assignment to Fixed Bin(31). The result of such an operation is undefined.
POSINT and INT are identical functions, except that INT returns a signed integer.
The result of this function is dependent on the native byte ordering of the hardware you are using. For this reason, the use of this function may not be portable across different platforms.
DCL A BIT(32); A = '12345678'B4; PUT SKIP LIST(POSINT(A,5,4)); END TEST;
None.
Returns the value of the specified expression using specified precsion.
PRECISION(x,p[,q])
Abbreviation: PREC for PRECISION.
x is an expression, and p and q are restricted expressions.
p specifies the number of digits that the value of the expression x is to have after conversion.
q specifies the scaling factor of the result. For a fixed-point result, if q is omitted a scaling factor of zero is assumed. For a floating-point result, q must be omitted.
The base, mode, and scale of the returned value are the same as that of x.
None.
Returns the product of all the elements of an array.
PROD(x)
x is an array expression.
The PROD function returns the product of all the elements of the array.
If the elements of x are strings, they are converted to fixed-point values. If they are neither fixed-point values nor strings, they are converted to floating-point values. In the latter case, the result is a floating-point value; otherwise, it is a fixed-point value.
DECLARE (A(4), I) FIXED BIN (15); DO I = 1 to 4; A(I) = I; END I = PROD(A); /* returns 24 */
None.
Returns a fixed binary integer that is the position of the character x within the collating sequence.
RANK(x)
x is a character string of length one.
The RANK function returns a fixed binary integer that is the position of the character x within the collating sequence.
The result is defined as RANK(x) = INDEX(COLLATE(),x)-1 and has an implementation-defined precision. For details on precisions, see your Open PL/I User's Guide.
The RANK function uses a 256-byte collating string.
DECLARE X FIXED BINARY(15);
X = RANK('2'); /* X IS SET TO 50 */
None.
Returns the real part of the specified expression.
REAL(x)x is an expression. If it is real it is converted to complex.
The result has the base, scale, and precision of x.
None.
Returns a string consisting of the source string concatenated to itself the number of times specified by the second argument.
REPEAT(x,y)
xis a character-string, bit-string, or picture value, and y is a positive integer expression. If x is an arithmetic value, it is converted to a bit string if it is binary, or to a character string if it is decimal.
The REPEAT function copies a particular string, x, a certain number of times, y, and concatenates the result to the original string x. REPEAT effectively returns a string containing (y+1) occurrences of the string argument with length (y+1) * length (x).
DECLARE X CHAR(8);
X = REPEAT('AB',3); /* returns X = 'ABABABAB' *
Note that the same result could be produced by using a string repetition factor, as illustrated below:
X = (4) 'AB';
Here is an example of using the REPEAT function for bit–strings:
DECLARE B_STRING BIT(4) STATIC INIT('1110'B);
DECLARE B_RESULT BIT(8);
B_RESULT = REPEAT(B_STRING,1);
The above example will produce B_RESULT equal to '11101110'B.
None.
Continues to search for another ON-unit to handle a condition.
CALL RESIGNAL();
In Open PL/I, an ON-unit can determine that it does not want to handle a condition and can subsequently request that, instead of returning control to the point of interruption, Open PL/I continue to search for another ON-unit to handle the condition. The RESIGNAL built-in subroutine is available for this purpose.
CALL RESIGNAL() is used in an ON-unit to pass the signaled condition back to the run-time system so that it can look for another ON-unit to handle the condition. The condition is passed at the end of the current ON-unit, that is, execution of the RESIGNAL does not immediately cause a return to the run-time system, but merely sets up the conditions so that when the ON-unit completes its execution and returns, the run-time system will continue searching for another ON-unit that matches the signaled condition.
ON ERROR BEGIN;
PUT SKIP LIST('AN UNIDENTIFIED ERROR OCCURRED IN GETREC');
CALL RESIGNAL();
END;
None.
Rounds a given value at a specified digit and pads spare digit positions with zeros.
ROUND(x,k)
x is a fixed-point arithmetic or decimal picture value to be rounded, and k is an integer constant that specifies the digit at which the value x is to be rounded.
The ROUND function rounds a given value x at a specified digit and pads positions k+1 to q (q is the scale factor) with zeros. The result is the value of x rounded such that the kth position of x is expressed to its nearest integer. For example, if the argument is 8.77 and it is desired to round to the first fractional digit, the result would be 8.80.
The first argument, x, may be an element expression or array name representing the value (or values, in the case of an array). If the value to be rounded is negative, its absolute value is rounded, but its sign remains unchanged.
The second argument, k, may be unsigned or signed. If k is positive, rounding occurs at the kth digit to the right of the decimal (or binary) point in the first argument; if k is zero, rounding occurs at the first digit to the left of the decimal (or binary) point in the first argument; if k is negative, rounding occurs at the (1 - k) digit to the left of the decimal (or binary) point in the first argument.
DCL (X,K) DECIMAL FIXED (7,4); X = 123.7261; K = ROUND(X,3); /* K IS NOW 123.7260 */ K = ROUND(X,2); /* K IS NOW 123.7300 */ K = ROUND(X,1); /* K IS NOW 123.7000 */ K = ROUND(X,0); /* K IS NOW 124.0000 */ X = -123.7261; K = ROUND(X,2); /* K IS NOW -123.7300 */ K = ROUND(X,0); /* K IS NOW -124.0000 */ K = ROUND(X,-1); /* KIS NOW -120.0000 */ X = 9.9999; K = ROUND(X,0); /* K IS NOW 10.0000 */
None.
Returns a bit string of length 1 indicating whether a record that has been accessed is followed by another with the same key.
SAMEKEY(x)x is a file reference. The file must have the RECORD attribute.
Upon successful completion of an input/output operation on file x, or immediately before the RECORD condition is raised, the value accessed by SAMEKEY is set to '1'B if the record processed is followed by another record with the same key, and set to '0'B if it is not.
The value accessed by SAMEKEY is also set to '0'B if:
None.
Returns a 1, -1, or 0, indicating whether the specified value is positive, negative, or zero, respectively.
SIGN(x)
x is an arithmetic expression.
The SIGN function returns a 1, -1, or 0, indicating whether x is positive, negative, or zero, respectively. The precision of the result is Fixed Binary(15).
IF SIGN(X) = 1 THEN
PUT LIST ('SIGN OF X IS POSITIVE');
None.
Returns a floating-point value that is the sine of an arithmetic expression.
SIN(x)
x is an arithmetic expression.
The SIN function returns a floating-point value that is the sine of an arithmetic expression x, where x is an angle in radians such that -1 ≤ SIN(x) ≤ 1.
The sine is computed in floating-point, and the result has the same data type as x.
SIN(0.0) /* returns 0.0 */
An SIN operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns a floating-point value that is the sine of the specified angle expressed in degrees.
SIND(x)
x is a floating-point value representing the sine of an angle.
The SIND function returns the sine of the angle x expressed in degrees. The result has the same data type as x such that -1 ≤ SIND(x) ≤ 1.
SIND(30.0) /* returns 0.5 */
An SIND operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns a floating-point value that is the hyperbolic sine of the arithmetic value x.
SINH(x)
x is a floating-point value representing the sine of an angle.
The SINH function returns the hyperbolic sine of the angle x expressed in radians. The result has the same data type as x.
SINH(0.0) /* returns 0.0 */
An SINH operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns a Fixed Bin(31) value that is the number of bytes allocated for the referenced variable.
SIZE(reference)
reference is a variable of any data type and storage class.
This function is identical to the STORAGE function and is provided for compatibility with earlier versions of Open PL/I (formerly called LPI-PL/I).
The SIZE function returns a Fixed Bin(31) integer that is the number of bytes allocated for the referenced variable. The variable can be a scalar, an array, an array element, a structure, or a member of a structure. The reference cannot be made to a constant or an expression.
When a reference is made to an individual array element, the value returned is the size of the element of the array and not the size of the entire array. The SIZE function can be used with an unconnected array argument.
If the variable is a bit string that does not fill an integral number of bytes, the value returned is rounded up to the next byte. If the variable is of the type character varying, the value returned is the declared length of the string plus two, where the extra two bytes are the bytes needed to store the current length of the string.
In the following example, the returned values are shown in the comment.
Note: The sizes in the example are accurate for Open PL/I, but may not be correct for different implementations of PL/I that have different precision, alignment, boundaries, or datatype representations. For information on this implementation, see your Open PL/I User's Guide.
DECLARE
S FIXED BIN(31),
A FIXED BIN(15),
B FIXED BIN(31),
C FLOAT BIN(23),
D CHAR(5),
E CHAR(5) VARYING,
F BIT(11),
G POINTER;
S = SIZE(A); /* S = 2 */
S = SIZE(B); /* S = 4 */
S = SIZE©); /* S = 4 */
S = SIZE(D); /* S = 5 */
S = SIZE(E); /* S = 7 */
S = SIZE(F); /* S = 2 */
S = SIZE(G); /* S = 4 */
DECLARE
S FIXED BIN(31),
1 A_STRUCT
2 A FIXED BIN(31),
2 B CHAR (2),
C(20) FIXED BIN(15);
S = SIZE(A_STRUCT); /* S = 6 */
S = SIZE(A STRUCT.A); /* S = 4 */
S = SIZE(A_STRUCT.B); /* S = 2 */
S = SIZE©); /* S = 40 */
S = SIZE©(13)); /* S = 2 */
DECLARE
S FIXED BIN(31),
1 STRUC1,
2 A BIT(1),
2 B BIT(3);
DECLARE
1 STRUC2,
2 C BIT(1) ALIGNED,
2 D BIT(3) ALIGNED;
S = SIZE(STRUC1); /* S = 1 */
S = SIZE(STRUC2); /* S = 2 */
None.
Returns the positive square root of the specified value.
SQRT(x)
x is a positive or zero floating-point value.
The SORT function returns the positive square root of x. The result has the same data type as x.
SQRT(4.0) /* returns 2.0 */
An SQRT operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns a Fixed Bin(31) value that is the number of bytes allocated for the referenced variable.
STORAGE(reference)
Abbreviation(s): STG for STORAGE.
reference is a variable.
The STORAGE function returns a Fixed Bin(31) integer that is the number of bytes allocated for the referenced variable. The variable can be a scalar, an array, an array element, a structure, or a member of a structure.
When a reference is made to an individual array element, the value returned is the size of the element of the array and not the size of the entire array. If the variable is a bit string that does not fill an integral number of bytes, the value returned is rounded up to the next byte.
If the variable is of the type character varying it consists of two parts: the text field and the length field. STORAGE returns the declared length of the text field plus two, since the length field always uses two bytes.
If the variable is an area, STORAGE returns the maximum size of the area plus the size of the area header.
For more information on data storage, see your Open PL/I User's Guide.
DCL A FIXED BIN(15);
DCL 1 FOO,
2 AB FIXED BIN(15),
2 F001,
5 A0 CHAR(12),
5 A2 FIXED BIN(31),
5 A1 CHAR(5) VARYING,
2 ABC CHAR(4);
PUT SKIP LIST('Should see 2 ->',SIZE (A));
PUT SKIP LIST('Should see 2 ->',STG (A));
PUT SKIP LIST('Should see 23 ->',STG (F001));
PUT SKIP;None.
Concatenates the elements of an array or a structure and returns the results.
STRING(s)
s is an arithmetic value, string value, picture value, or an array or structure containing all nonvarying string or picture values.
The STRING function concatenates the elements of an array s or a structure s and returns the results. If s is scalar, it is converted to a string.
If s is an array or structure, it must be suitable for storage sharing, as defined in the section Storage Sharing. s must be a reference to a variable whose storage is connected. The STRING function can be used with an unconnected array argument.
The result is converted to a string according to the rules for data type conversion given in the chapter Data Type Conversions.
For a description of the STRING function's use as a pseudovariable, see the section ASSIGNMENT Statement.
DECLARE S(4) CHAR(1); S(1) = 'A'; S(2) = 'B'; S(3) = 'C'; S(4) = 'D'; STR = STRING(S); /* 'ABCD' */
None.
Returns a string that is a copy of a specified part of the specified string.
SUBSTR(s,i,j)
or
SUBSTR(s,i)
s is a bit string, character string, or picture value. If s is not a string, it is converted to a bit string if it is binary or to a character string if it is decimal. I is an integer value indicating the first bit (if s is a bit string) or character of a substring within s; and j is an integer value indicating the length of the substring within s.
The SUBSTR function returns a string that is a copy of a part of the string s starting at the Ith character for a length j. If j is not given, j = LENGTH(s)-I+1, that is, the remainder of the string s.
The program is in error if I < 1 or (I + j -1) > LENGTH(s) or j < 0. If the program is compiled with subscript checking enabled, these errors result in the ERROR condition; otherwise, these errors produce unpredictable results.
For a description of the SUBSTR function's use as a pseudovariable, and for the description of the ASSIGNMENT statement, see the section ASSIGNMENT Statement.
SUBSTR('ABCDE',2,2) /* returns 'BC' */
SUBSTR('ABCDE',2) /* returns 'BCDE' */
None.
Returns the sum of all the elements in an array.
SUM(x)
x is an array expression.
The SUM function returns the sum of all the elements in the array.
If the elements of the array are strings, they are converted to fixed-point values. If they are neither fixed-point values nor strings, they are converted to floating-point values. In the latter case, the result is a floating-point value; otherwise, it is a fixed-point value.
DECLARE (A(4), I) FIXED BIN (15); DO I = 1 to 4; A(I) = 4; END I = SUM(A); /* returns 10 */
None.
Returns the system null pointer value.
SYSNULL[()]
None.
You can assign SYSNULL to handles and compare it with handles. You can use it to initialize static pointer and offset variables.
NULL and SYSNULL may compare equal. However, we recommend that you do not write code that depends on their equality.
None.
Returns the tangent of the specified angle expressed in radians.
TAN(x)
x is a floating-point value representing an angle and cannot be an odd multiple of Π/2.
The TAN function returns the tangent of the angle x expressed in radians. The result has the same data type as x.
TAN(0.0) /* returns 0.0 */
A TAN operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns the tangent of the specified angle expressed in degrees.
TAND(x)
x is a floating-point value representing an angle and cannot be an odd multiple of 90.
The TAND function returns the tangent of the angle x expressed in degrees. The result has the same data type as x.
TAND(45.0) /* returns 1.0 */
A TAND operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns the hyperbolic tangent of the specified arithmetic value.
TANH(x)
x is a floating-point value representing an angle.
The TANH function returns the hyperbolic tangent of the angle x expressed in radians such that -1 ≤ TANH(x) ≤ 1.
The result has the same data type as x.
TANH(0.0) /* returns 0.0 */
A TANH operation on floating-point decimal data is actually performed using the floating-point binary operation. Thus, the range of the operands and the result of the operation are limited to the ranges for floating-point binary numbers.
Returns a character string that represents the time of day.
TIME()
or
TIME
The second syntax form can be used only if the BUILTIN attribute was specified.
The TIME function returns a character string of the form hhmmssttt that represents the time of day, where hh, mm, and ss are in the ranges 00 – 23, 00 – 59, and 00 – 59, respectively, and represent hours, minutes, and seconds, respectively. ttt represents thousandths of a second. If your system is not capable of supplying ttt, zeros are returned in these positions. (Releases of Open PL/I prior to release 5.0 returned only two fractional digits, that is, hundredths, instead of three. To retain that behavior, compile with the -pl1g option. (See your Open PL/I User's Guide.)
The value of TIME at 6 seconds after 11:15 P.M. is '231506000 '.
None.
Replaces occurrences of a character in a string with a corresponding translation character and returns the resulting string.
TRANSLATE(s,t)
or
TRANSLATE(s,t,x)
s, t, and x are all character strings.
Given a character string argument, the TRANSLATE function replaces occurrences of a character with a corresponding translation character and returns the resulting string. If x is not given, it is assumed to be COLLATE().
If t is shorter than x, t is padded on the right with blanks until the length of t is equal to the length of x. If t is longer than x, the rightmost extra characters of t are ignored.
The occurrence of an element of x in the string s is replaced by the corresponding element in the string t.
If s is the null string, the result is the null string. If s is not the null string, for each character of s, s(k), the value I is calculated to be equal to INDEX(x,s(k)). If the value of I is 0, the corresponding character of the result is s(k); otherwise, the corresponding character of the result is t(I).
TRANSLATE('TEXT','abcdefghijklmnopqrstuvwxyz',
'ABCDEFGHIJKLMNOPQRSTUVWXYZ') /*returns 'text'*/
None.
Strips blanks or specified characters from the beginning and end of a character string value and returns the resulting string.
TRIM(string[,a,b])
string is a character string value (variable or constant). a, if present, is a string consisting of the set of characters to be trimmed from the beginning of string. b, if present, is a string consisting of the set of characters to be trimmed from the end of string.
The TRIM built-in function strips the characters specified in a from the beginning of string and the characters specified in b from the end of string and returns the resulting string.
If the second and third arguments are not present, blanks are trimmed from the beginning and end of the first argument.
The following example returns the values shown in the comment.
DECLARE
S CHAR(25)VARYING,
A CHAR(5);
A = 'ABC';
S = TRIM(A); /* S = 'ABC' */
S = TRIM(' HELLO'); /* S = 'HELLO' */
S = TRIM(' GOODBYE '); /* S = 'GOODBYE' */
S = TRIM(''); /* S = '' null string */
S = TRIM('abcdefghi','cba', 'high'); /* S = 'def' */
S = TRIM('abc','abc','abc') /* S = '' null string */
None.
Returns the integer part of a specified value.
TRUNC(x)
x is an arithmetic expression.
The TRUNC function returns the integer part of x. If x is floating-point, the precision of the result is the precision of x.
If x is fixed-point, the precision of the result is (MIN(n,MAX(p-q+1,1)),0). n is the maximum precision allowed for values of the result type. For details on maximum precisions, see your Open PL/I User's Guide.
For x < 0, the result is CEIL(x). For x ≥ 0, the result is FLOOR(x).
TRUNC(3.125) /* returns 3 */
TRUNC(-3.125) /* returns -3 */
None.
Returns a bit string containing the internal representation of the specified value.
UNSPEC(x)
or
UNSPEC(SUBSTR(char_string,i,j))
x is a reference to a scalar variable.
?
The UNSPEC function returns a bit string containing the internal representation of x.
The length and content of the result value depend on the data type and value of x and are implementation-defined. For details, see your Open PL/I User's Guide.
For a description of the UNSPEC function's use as a pseudovariable, see the section ASSIGNMENT Statement.
DECLARE CH CHAR(1); DECLARE MINUS_ONE FIXED BIN; MINUS_ONE = -1; UNSPEC(CH) = UNSPEC(MINUS_ONE); BIT(8) = UNSPEC(CH); /* '11111111'B */
Determines whether a reference to a scalar pictured value has a value that is valid with respect to its picture specification.
VALID(x)
x is a reference to a scalar pictured value.
The VALID function determines whether x, a reference to a scalar pictured value, has a value that is valid with respect to its picture specification. The result is a bit string of length one that indicates if the character-string value of x can be edited into the picture declared for x.
If the character-string value of x can be edited into the picture declared for x, the result value is '1' B; otherwise, the result is '0' B.
The VALID function can be used when a pictured data item or a pictured item that is a member of a structure is read using the READ statement. Record input done with READ does not perform the validation that is normally done when a value is assigned to a pictured data item.
VALIDATE_FILE: PROCEDURE (BALANCES, REC_COUNT);
DECLARE BALANCES FILE RECORD;
DECLARE REC_COUNT FIXED BIN(31);
DECLARE TOTAL PICTURE '999V.99';
DO I = 1 TO REC_COUNT;
READ FILE(BALANCES) INTO (TOTAL);
IF ^VALID(TOTAL) THEN
DO;
PUT LIST('Invalid total value:', TOTAL);
PUT SKIP;
END;
END;
END VALIDATE_FILE;
None.
Compares a string with a test string and verifies that all characters appearing in the string also appear in the test string.
VERIFY(s,c)
s and c are both either character-string or picture values.
The VERIFY function compares a string s with a test string c and verifies that all characters appearing in the string also appear in the test string. If each of the characters in s occurs in c, the result is 0. If all of the characters in s do not occur in c, the result is a fixed-point binary integer that indicates the leftmost character in s that is not found in c. If only s is null, a 0 is returned. If only c is null, a 1 is returned. If both s and c are null, a 0 is returned.
VERIFY('2a56b','0123456789')
/* returns the value 2 to indicate the first */
/* non-numeric character in the string '2a56b' */
None.
Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.