| Previous | Contents | Index |
The PL/I embedded preprocessor provides four statements that permit user-generated diagnostic capability: %INFORM, %WARN, %ERROR, and %FATAL. Preprocessor diagnostic messages are compile-time messages, but you define the circumstances that invoke the message and the text displayed.
The action of each statement is to generate a diagnostic message of the appropriate severity level, with the preprocessor expression as the text of the message.
The first example shows how %INFORM can be used to return the value of VARIANT.
%IF VARIANT() = '' | VARIANT() = 'NORMAL'
%THEN
%INFORM 'NORMAL';
|
In this example, the %INFORM diagnostic message is used to let the programmer know that compilation is continuing according to a normal plan.
If the value of VARIANT is not specified at compile time or if the value is 'NORMAL', then the following informational message is issued:
%PLIG-I-USERDIAG, NORMAL |
In the following example, an unknown variant is included at compile time. The %WARN statement issues a compile-time warning diagnostic message and saves the message so that when the program is run, the appropriate text is output by the program.
DECLARE INIT_MESSAGE CHAR(40) VARYING INITIAL (T);
.
.
.
%IF VARIANT() = 'NONE';
%THEN %;
%ELSE
%DO;
%T = '''unknown variant''';
%WARN T;
INIT_MESSAGE = 'Compiled with '||T;
%END;
PUT SKIP LIST (INIT_MESSAGE);
|
The preprocessor built-in functions INFORM, WARN, and ERROR return the number of user-generated diagnostics issued at any specified point during compilation. Therefore, you can use user-generated diagnostics to control the course of compilation. For example:
%IF WARN() > 5
%THEN
%GOTO change_text;
%ELSE;
|
This example specifies that compilation take a different course if there are more than five warning messages at that point in program compilation. If there are fewer than five warnings, then compilation proceeds along the current path.
%IF ERROR() >= 1
%THEN
%FATAL 'Ending Compilation';
|
This example stops compilation if there is an error that would inhibit the production of an object file.
User-generated diagnostic messages increment the count displayed in the
diagnostic summary.
10.4 Preprocessor Built-In Functions
A number of PL/I built-in functions are available for use at compile time. Since preprocessor built-in functions work the same way as run-time PL/I built-in functions, refer to Chapter 11 for detailed descriptions of the functions.
The built-in functions are summarized in Table 10-2 according to the following functional categories:
| Category | Function Reference | Value Returned |
|---|---|---|
| Arithmetic | ABS(x) | Absolute value of x |
| MAX(x1,x2) | Larger of the values x1 and x2 | |
| MIN(x1,x2) | Smaller of the values x1 and x2 | |
| MOD(x,y) | Value of x modulo y | |
| SIGN(x) | -1, 0, or 1 to indicate the sign of x | |
| String-Handling | COPY(s,c) | c copies of specified string s |
| INDEX(s,c[,p]) | Position of the character string c within the string s, starting at position p | |
| LENGTH(s) | Number of characters or bits in the string s | |
| LTRIM(s,[b]) | Removes blanks from left of string s; or if b is supplied, removes string b from left of string s | |
| REVERSE(s) | Reverse of the source character string or bit string | |
| RTRIM(s,[e]) | Removes blanks from right of string s; or if e is supplied, removes string e from right of string s | |
| SEARCH(s,c[,p]) | Position of the first character in s, starting at position p, that is found in c | |
| SUBSTR(s,i[,j]) | Part of string s beginning at i for j characters | |
| TRANSLATE(s,c[,d]) | String s with substitutions defined in c and d | |
| TRIM(s[,e,f]) | String s with all characters in e removed from the left and all characters in f removed from the right | |
| VERIFY(s,c[,p]) | Position of the first character in s, starting at position p, which is not found in c | |
| Conversion | BYTE(x) | ASCII character represented by the integer x |
| DECODE(c,r) | Fixed binary value of the character string c converted to a base r number | |
| ENCODE(i,r) | Character string representing the base r number that is equivalent to the fixed binary expression i | |
| RANK(c) | Integer representation of the ASCII character c | |
| Timekeeping | DATE() | System date of compilation in the form YYMMDD |
| DATETIME() | System date and time of compilation in the form CCYYMMDDHHMMSSXX | |
| TIME() | System time of day of compilation in the form HHMMSSXX | |
| Miscellaneous | ERROR() | Count of user-generated diagnostic error message |
| INFORM() | Count of user-generated diagnostic informational message | |
| LINE() | Line number in source program that contains the end of a specified preprocessor statement | |
| VARIANT() | String result representing the value of the /VARIANT command qualifier | |
| WARN() | Count of user-generated diagnostic warning message |
PL/I provides a set of predefined functions, subroutines, and variables called built-in functions, built-in subroutines, and pseudovariables respectively.
This chapter describes the built-in functions, subroutines, and
pseudovariables that you can use in your PL/I programs.
11.1 Built-In Function Arguments
Built-in functions are similar to operators, and their arguments are similar to operands. Built-in function arguments, if arithmetic, are converted to their derived type before the function reference is evaluated. All evaluations of built-in functions are performed in the result type. The arguments are converted again from the derived type to the result type if necessary. The precision of the result is the greater of the precisions of the two arguments.
For instance, all the mathematical functions return floating-point values; their arguments are converted to floating point (binary or decimal, depending on the base of the argument) before the operation is performed. For example:
DCL J FIXED BINARY(8); FT = ATAN(J,2); |
Here the derived type of J and 2 is fixed-point binary. The converted precision of 2 is min(ceil(1/3.32)+1,31) , or 2. The result type is FLOAT BINARY(8). Both arguments are then converted to FLOAT BINARY(8), and the ATAN operation is performed.
Note the following restrictions on built-in function arguments:
Built-in functions, like other operations, can signal conditions. The
mathematical functions, which are computed in floating point, can
signal OVERFLOW and UNDERFLOW under the appropriate conditions.
Functions that are computed in fixed point can signal FIXEDOVERFLOW. In
general, string and other functions signal ERROR if a result cannot be
computed. Refer to Section 8.10.4 for more information about condition
handling.
11.3 Summary of Built-In Functions
The built-in functions are summarized in PL/I, according to the following categories:
Section 11.4 provides detailed descriptions of the functions listed in PL/I.
| Category | Function Reference | Value Returned |
|---|---|---|
| Arithmetic | ABS(x) | Absolute value of x |
| ADD(x,y,p[,q]) | Value of x+y, with precision p and scale factor q | |
| CEIL(x) | Smallest integer greater than or equal to x | |
| DIVIDE(x,y,p[,q]) | Value of x divided by y, with precision p and scale factor q | |
| FLOOR(x) | Largest integer that is less than or equal to x | |
| MAX(x,y) | Larger of the values x and y | |
| MIN(x,y) | Smaller of the values x and y | |
| MOD(x,y) | Value of x modulo y | |
| MULTIPLY(x,y,p[,q]) | Value of x*y, with precision p and scale factor q | |
| ROUND(x,k) | Value of x rounded to k digits | |
| SIGN(x) | -1, 0, or 1 to indicate the sign of x | |
| SUBTRACT(x,y,p[,q]) | Value of x-y, with precision p and scale factor q | |
| TRUNC(x) | Integer portion of x | |
| Mathematical | ACOS(x) | Arc cosine of x (angle, in radians, whose cosine is x) |
| ASIN(x) | Arc sine of x (angle, in radians, whose sine is x) | |
| ATAN(x) | Arc tangent of x (the angle, in radians, whose tangent is x) | |
| ATAN(x,y) | Arc tangent of x (the angle, in radians, whose sine is x and whose cosine is y) | |
| ATAND(x) | Arc tangent of x (the angle, in degrees, whose tangent is x) | |
| ATAND(x,y) | Arc tangent of x (the angle, in degrees, whose sine is x and whose cosine is y) | |
| ATANH(x) | Hyperbolic arc tangent of x | |
| COS(x) | Cosine of radian angle x | |
| COSD(x) | Cosine of degree angle x | |
| COSH(x) | Hyperbolic cosine of x | |
| EXP(x) | Base of the natural logarithm, e, to the power x | |
| LOG(x) | Logarithm of x to the base e | |
| LOG10(x) | Logarithm of x to the base 10 | |
| LOG2(x) | Logarithm of x to the base 2 | |
| SIN(x) | Sine of the radian angle x | |
| SIND(x) | Sine of the degree angle x | |
| SINH(x) | Hyperbolic sine of x | |
| SQRT(x) | Square root of x | |
| TAN(x) | Tangent of the radian angle x | |
| TAND(x) | Tangent of the degree angle x | |
| TANH(x) | Hyperbolic tangent of x | |
| String-Handling | BOOL(x,y,z) | Result of Boolean operation z performed on x and y |
| COLLATE() | ASCII character set | |
| COPY(s,c) | c copies of specified string, s | |
| EVERY(s) | Boolean value indicating whether every bit in bit string s is '1'B | |
| HIGH(c) | String of length c of repeated occurrences of the highest character in the collating sequence | |
| INDEX(s,c[,p]) | Position of the character string c within the string s, starting at position p | |
| LENGTH(s) | Number of characters or bits in the string s | |
| LOW(c) | String of length c of repeated occurrences of the lowest character in the collating sequence | |
| LTRIM(s,[b]) | Removes white space (form feeds, carriage returns, tabs, vertical tabs, line feeds, and spaces) from left of string s; or if b is supplied, removes string b from left of string s | |
| MAXLENGTH(s) | Maximum length of varying string s | |
| REVERSE(s) | Reverse of the source character string or bit string | |
| RTRIM(s,[e]) | Removes white space (form feeds, carriage returns, tabs, vertical tabs, line feeds, and spaces) from right of string s; or if e is supplied, removes string e from right of string s | |
| SEARCH(s,c[,p]) | Position of the first character in s, starting at position p, that is found in c | |
| SOME(s) | Boolean value indicating whether at least one bit in bit string s is '1'B | |
| STRING(s) | Concatenation of values in array or structure s | |
| SUBSTR(s,i[,j]) | Part of string s beginning at i for j characters | |
| TRANSLATE(s,c[,d]) | String s with substitutions defined in c and d | |
| TRIM(s[,e,f]) | String s with all characters in e removed from the left, and all characters in f removed from the right | |
| VERIFY(s,c[,p]) | Position of the first character in s, starting at position p, which is not found in c | |
| Conversion | BINARY(x[,p[,q]]) | Binary value of x with precision p and scale factor q |
| BIT(s[,l]) | Value of s converted to a bit string of length l | |
| BYTE(x) | ASCII character represented by the integer x | |
| CHARACTER(s[,l]) | Value of s converted to a character string of length l | |
| DECIMAL(x[,p[,q]]) | Decimal value of x | |
| DECODE(c,r) | Fixed binary value of the character string c converted to a base r number | |
| ENCODE(i,r) | Character string representing the base r number that is equivalent to the fixed binary expression i | |
| FIXED(x,p[,q]) | Fixed arithmetic value of x | |
| FLOAT(x,p) | Floating arithmetic value of x | |
| INT(x[,p[,l]]) | Signed integer value of variable x, located at position p with length l | |
| POSINT(x[,p[,l]]) | Unsigned integer value of variable x, located at position p with length l | |
| RANK(c) | Integer representation of the ASCII character c | |
| UNSPEC(x[,p[,l]]) | Internal coded form of x, located at position p with length l | |
| Condition-Handling | ONARGSLIST() | Pointer to argument lists of exception condition |
| ONCHAR() | Character that caused the CONVERSION condition to be raised | |
| ONCODE() | Error code of the most recent run-time error | |
| ONFILE() | Name of file constant for which the most recent ENDFILE, ENDPAGE, KEY, or UNDEFINEDFILE condition was signaled | |
| ONKEY() | Value of key that caused KEY condition | |
| ONSOURCE() | Field containing the ONCHAR character when the CONVERSION condition was raised | |
| Array-Handling | DIMENSION(x[,n]) | Extent of the nth dimension of x |
| HBOUND(x[,n]) | Higher bound of the nth dimension of x | |
| LBOUND(x[,n]) | Lower bound of the nth dimension of x | |
| PROD(x) | Arithmetic product of all the elements in x | |
| SUM(x) | Arithmetic sum of all the elements in x | |
| Storage | ADDR(x) | Pointer identifying the storage referenced by x |
| ADDREL(p,o) | Pointer which is the sum of pointer p and offset o | |
| ALLOCATION(x) | Number of existing generations for controlled variable x | |
| BYTESIZE(x) | Number of bytes allocated to variable x; same as SIZE function | |
| EMPTY() | An empty area value | |
| NULL() | A null pointer value | |
| OFFSET(p,a) | An offset into the location in area a pointed to by pointer p | |
| POINTER(o,a) | A pointer to the location at offset o within area a | |
| SIZE(x) | Number of bytes allocated to variable x | |
| Timekeeping | DATE() | System date in the form YYMMDD |
| DATETIME() | System date and time in the form CCYYMMDDHHMMSSXX | |
| TIME() | System time of day in the form HHMMSSXX | |
| File Control | LINENO(x) | Line number of the print file identified by x |
| PAGENO(x) | Page number of the print file identified by x | |
| Preprocessor | ABS(x) | Absolute value of x |
| BYTE(x) | ASCII character represented by integer x | |
| COPY(s,c) | c copies of specified string s | |
| DATE() | Compilation date in the form YYMMDD | |
| DATETIME() | System date and time in the form CCYYMMDDHHMMSSXX | |
| DECODE(c,r) | Fixed binary value of the character string c converted to a base r number | |
| ENCODE(i,r) | Character string representing the base r number that is equivalent to the fixed binary expression i | |
| ERROR() | Count of user-generated diagnostic error messages | |
| INDEX(s,c[,p]) | Position of the character string c within the string s, starting at position p | |
| INFORM() | Count of user-generated diagnostic informational messages | |
| LENGTH(s) | Number of characters or bits in the string s | |
| LINE() | Line number in source program that contains the end of the specified preprocessor statement | |
| LTRIM(s,[b]) | Removes white space (form feeds, carriage returns, tabs, vertical tabs, line feeds, and spaces) from left of string s; or if b is supplied, removes string b from left of string s | |
| MAX(x,y) | Larger of the values x and y | |
| MIN(x,y) | Smaller of the values x and y | |
| MOD(x,y) | Value of x modulo y | |
| RANK(c) | Integer representation of the ASCII character c | |
| REVERSE(s) | Reverse of the source character string or bit string | |
| RTRIM(s,[e]) | Removes white space (form feeds, carriage returns, tabs, vertical tabs, line feeds, and spaces) from right of string s; or if e is supplied, removes string e from right of string s | |
| SEARCH(s,c[,p]) | Position of the first character in s, starting at position p, that is found in c | |
| SIGN(x) | -1,0, or 1 to indicate the sign of x | |
| SUBSTR(s,i[,j]) | Part of string s beginning at i for j characters | |
| TIME() | Compilation time of the day in the form HHMMSSXX | |
| TRANSLATE(s,c[,d]) | String s with substitutions defined in c and d | |
| TRIM(s[,e,f]) | String s with all characters in e removed from the left and all characters in f removed from the right | |
| VARIANT() | String result representing the value of /VARIANT of the PLI command qualifier (for OpenVMS) or -variant command option (for RISC ULTRIX) | |
| VERIFY(s,c[,p]) | Position of the first character in s, starting at position p, which is not found in c | |
| WARN() | Count of user-generated diagnostic warning messages | |
| Argument-passing | ACTUALCOUNT() | Number of parameters the current procedure was called with |
| DESCRIPTOR(x) | Forces its argument to be passed by descriptor to a non-PL/I procedure | |
| PRESENT(p) | Boolean value indicating whether parameter p was specified in a call | |
| REFERENCE(x) | Forces its argument to be passed by reference to a non-PL/I procedure | |
| VALID(p) | Boolean value, indicating whether the pictured variable p has a value consistent with its picture specification | |
| VALUE(x) | Forces its argument to be passed by value to a non-PL/I procedure |
| Previous | Next | Contents | Index |