| Previous | Contents | Index |
The WARN preprocessor built-in function returns the number of diagnostic warning messages issued during compilation up to that particular point in the source program. The format for the WARN built-in function is:
WARN(); |
The function returns a fixed result representing the number of
compile-time warning messages that were issued up to the point at which
the WARN built-in function was encountered.
11.5 Built-In Subroutines
Built-in subroutines are specific routines for the platform that provide various added capabilities. These routines can be used in a CALL statement. All arguments are evaluated as for normal subroutines.
The built-in subroutines are summarized in Table 11-2, according to the following functional categories:
For more information on the PL/I subroutines in Table 11-2, see the Kednos PL/I for OpenVMS Systems User Manual.
| Category | Routine Reference | Action |
|---|---|---|
| Condition-handling | RESIGNAL() | Allows more processing of a signal. |
| File-control | DISPLAY(f,i) | Returns information on file f into i |
| EXTEND(f,b) | Extends file f by b blocks | |
| FLUSH(f) | Forces all buffers for file f to be flushed | |
| NEXT_VOLUME(f) | Performs magnetic tape volume processing on file f | |
| REWIND(f) | Resets file f to the beginning | |
| SPACE_BLOCK(f,b) | Positions file f forward or backward b blocks | |
| Record-locking | FREE(f) | Frees all locks for file f |
| RELEASE(f,r) | Releases locked record r in file f |
A pseudovariable can be used, in certain assignment contexts, in place of an ordinary variable reference. For example:
SUBSTR(S,2,1) = 'A'; |
A pseudovariable can be used wherever the following three conditions are true:
The principal contexts in which pseudovariables are used are:
Note that a pseudovariable cannot be used in preprocessor statements or in an argument list. In the following example, SUBSTR is not interpreted as a pseudovariable:
CALL P(SUBSTR(S,2,1)); |
Here, SUBSTR is interpreted as a built-in function reference, rather than as a pseudovariable. The actual argument passed to procedure P is a dummy argument containing the second character of string S.
The following are pseudovariables:
The next sections describe these pseudovariables in alphabetic order.
11.6.1 INT Pseudovariable
The INT pseudovariable assigns a signed integer value to specified storage. The format is:
INT(reference[,position[,length]]) = expression; |
reference
A reference to connected storage. This reference must not be an array, structure, or named constant. If position and length are not specified, the length of the referenced storage must not exceed 32 bits. If it exceeds 32 bits, a fatal run-time error results.position
A positive integer value that denotes the position of the first bit in the field. If omitted, position defaults to 1, signifying the first bit of the storage denoted by reference. If specified, position must satisfy the following condition:1 <= position <= size(reference)
where size(reference) is the length in bits of the storage denoted by reference. A position equal to size(reference) implies a zero-length field.
length
An integer value in the range 0 through 32 that specifies the length of the field. If omitted, length is the number of bits from the bit denoted by position through the end of the storage denoted by reference. If specified, length must satisfy the following condition:0 <= length <= size(reference) - position
where size(reference) is the length in bits of the storage denoted by reference.
The INT pseudovariable is valid only in an assignment statement. You cannot use it as the target of an input statement or in other instances where pseudovariables are normally acceptable.
The expression to be assigned to the pseudovariable is first converted to the data type FIXED BINARY (31). Then, the internal representation of the resulting integer value is assigned to the storage specified by the arguments to INT. If the representation of the value is too large for assignment to the storage, the most significant bits of the integer are removed and no error is signaled.
DECLARE F FLOAT INITIAL (123.45);
INT(F,8,8) = 25; /* Alter the exponent */
PUT SKIP LIST (F); /* New value */
|
In this example, the INT pseudovariable is used to modify the exponent field of a floating-point variable. This example prints the following value:
9.5102418E-32 |
Proper interpretation of this result requires understanding of the internal representation of floating-point numbers. As such, this example is only valid on the VAX hardware.
The next example demonstrates how the INT pseudovariable treats cases in which the value is too large for the specified storage:
INTOVER: PROCEDURE OPTIONS (MAIN);
DECLARE I15 FIXED BINARY (15),
I31 FIXED BINARY (31);
ON FIXEDOVERFLOW PUT SKIP LIST ('FIXEDOVERFLOW signaled');
I31 = -876543; /* Too big for I15 */
I15 = I31; /* Arithmetic assignment */
INT(I15) = I31; /* No error signaled */
PUT SKIP LIST (I15);
END;
|
This example produces the following output:
FIXEDOVERFLOW signaled -24575 |
The arithmetic assignment to I15 signals FIXEDOVERFLOW because the
value of I31 is outside the range of a FIXED BINARY (15) variable.
However, the assignment using the INT pseudovariable does not signal an
error; it just copies the low-order 16 bits of the value of I31 into
the storage for I15.
11.6.2 ONCHAR Pseudovariable
The ONCHAR pseudovariable can be used to replace the single character in the ONSOURCE value that caused a CONVERSION condition to be raised. An attempt to assign a value to the ONCHAR pseudovariable when there is no active CONVERSION condition causes the ERROR condition to be raised.
The format of the pseudovariable is:
ONCHAR() |
See Section 8.10.4.4 for more information about CONVERSION condition name.
11.6.3 ONSOURCE Pseudovariable
The ONSOURCE pseudovariable can be used to replace the entire ONSOURCE value that caused a CONVERSION condition to be raised. An attempt to assign a value to the ONSOURCE pseudovariable when there is no active CONVERSION condition causes the ERROR condition to be raised.
The format of the pseudovariable is:
ONSOURCE()
|
The ONSOURCE value is a fixed-length string value. An assignment of a longer string is truncated, and an assignment of a shorter string is padded with blanks on the right to the necessary length.
See Section 8.10.4.4 for more information about CONVERSION condition name.
11.6.4 PAGENO Pseudovariable
The PAGENO pseudovariable refers to the page number of the referenced print file. Assignment to the pseudovariable modifies the current page number. The format of the PAGENO pseudovariable in an assignment statement is:
PAGENO(reference) = expression; |
reference
A reference to a file for which the page number is to be set. The file must be open and must be a print file.
PAGENO(reference) is a FIXED BINARY(15) variable; however, values
assigned to it must not be negative.
11.6.5 POSINT Pseudovariable
The POSINT pseudovariable assigns an integer value to specified storage. The format is:
POSINT(expression1[,position[,length]]) = expression2; |
expression1
A reference to connected storage. This reference must not be an array, structure, or named constant. If position and length are not specified, the length of the referenced storage must not exceed 32 bits. (If it exceeds 32 bits, a fatal run-time error results.)position
A positive integer value that denotes the position of the first bit in the field. If omitted, position defaults to 1, signifying the first bit of the storage denoted by expression1. If specified, position must satisfy the following condition:1 <= position <= size(expression1)
Size(expression1) is the length in bits of the storage denoted by expression1. A position equal to size(expression1) implies a zero-length field.
length
An integer value in the range 0 through 32 that specifies the length of the field. If omitted, length is the number of bits from the bit denoted by position through the end of the storage denoted by expression1. If specified, length must satisfy the following condition:0 <= length <= size(expression1) - position
Size(expression1) is the length in bits of the storage denoted by expression1.
expression2
Any expression that evaluates to an integer.
The POSINT pseudovariable is valid only in an assignment statement. It cannot be used as the target of an input statement or in other instances where pseudovariables are normally acceptable.
The expression to be assigned to the pseudovariable is first converted to the data type FIXED BINARY (31). Then, the internal representation of the resulting integer value is assigned to the storage specified by the arguments to POSINT. If the representation of the value is too large for assignment to the storage, the most significant bits of the integer are removed and no error is signaled.
The POSINT pseudovariable is identical in operation and use to the INT
pseudovariable. For examples, see INT pseudovariable.
11.6.6 STRING Pseudovariable
The STRING pseudovariable interprets a suitable reference as a reference to a fixed-length string. By using it, you can modify an entire aggregate with a single string assignment or assign the aggregate to a pictured variable as if it were a character-string variable. The format of the pseudovariable (in an assignment statement) is:
STRING(reference) = expression; |
reference
A reference to a variable that is suitable for character-string (or bit-string) overlay defining (see Section 5.5.6.1 and Section 5.8.2). The length of the pseudovariable is equal to the total number of characters (or bits) in the scalar or aggregate denoted by the reference. This length must be less than or equal to the maximum length for character-string (or bit-string) data.
Assignment to the STRING pseudovariable modifies the entire storage denoted by the reference.
STRING_PSD_EXAMPLE: PROCEDURE;
DECLARE 1 NAME,
2 FIRST CHARACTER(10),
2 MIDDLE_INITIAL CHARACTER(3)
2 LAST CHARACTER(10);
STRING(NAME)='FRANKLIN D. ROOSEVELT';
/* NAME.FIRST - 'FRANKLIN D';
NAME.MIDDLE_INITIAL = '. R';
NAME.LAST = 'OOSEVELT '; */
END STRING_PSD_EXAMPLE;
.
.
.
DECLARE 1 FLAGS,
2 (A,B,C) BIT(1);
STRING(FLAGS) = '0'B; /* sets all three flags false */
.
.
.
DECLARE P PICTURE /Z.ZZZV,ZZDB';
GET EDIT (STRING(P)) (A(10));
/* assigns 10 characters from SYSIN to P,
without conversion */
|
The SUBSTR pseudovariable refers to a substring of a specified string variable reference. Assignment to the pseudovariable modifies only the substring. The format of the pseudovariable (in an assignment statement) is:
SUBSTR(reference,position[,length]) = expression; |
reference
A reference to a bit- or character-string variable. If the reference is to a varying-length character string, the substring defined by the position and length arguments must be within the current value of the string. Assignment to the SUBSTR pseudovariable does not change the length of a varying string.position
An integer expression indicating the position of the first bit or character in the substring. The length must satisfy the following condition:1 <= position <= LENGTH(reference) + 1
length
An integer expression that indicates the length of the substring. If not specified, length is:length = LENGTH(reference) - position + 1
In other words, if length is not specified, the substring begins at the indicated position and ends at the end of the string. The length must satisfy the following condition:
0 <= length <= LENGTH(reference) - position + 1
Note that the following two lines are equivalent:
SUBSTR(r,p,l) = v; r = SUBSTR(r,1,p-1)||SUBSTR(v||SUBSTR(r,p+length(v)),1,l)||SUBSTR(r,p+l); |
Assignment to the SUBSTR pseudovariable does not change the length of reference.
DECLARE (NAME,NEW_NAME) CHARACTER(20) VARYING; NAME = 'ISAK DINESEN'; NEW_NAME = NAME; SUBSTR(NEW_NAME,4) = 'AC NEWTON'; /* NEW_NAME = 'ISAAC NEWTON' */ |
The UNSPEC pseudovariable interprets a reference to a scalar or aggregate element variable as a reference to a bit string. The format of the pseudovariable (in an assignment statement) is:
UNSPEC(reference[,position[,length]]) = expression; |
reference
A reference to a scalar or aggregate variable. The length of its storage in bits must be less than or equal to the maximum length for bit-string data.
In an assignment of the form
UNSPEC(reference) = expression; |
the value of the expression is converted to a bit string if necessary and copied into the storage of the reference. The value is truncated or zero-extended as necessary to match the length of the storage.
To prevent zero-extending a value that is shorter than the variable, you can use the position parameter or both the position parameter and the length parameter. Then only the specified bits in the variable will be assigned a new value, and the other bits will remain as they were. Note that a position parameter of 1 refers to the low-order bit of the variable's storage, not the high-order bit.
DECLARE X FIXED BINARY (15); UNSPEC(X) = '110'B; |
UNSPEC(X,1,3) = '101'B; |
| Previous | Next | Contents | Index |