| Previous | Contents | Index |
The SUBTRACT built-in function returns the difference of two arithmetic expressions x and y, with a specified precision p and an optionally specified scale factor q. The format of the function is:
SUBTRACT(x,y,p[,q]) |
p
An unsigned integer constant greater than zero and less than or equal to the maximum precision of the result type, which is:
- For OpenVMS Alpha systems: 31for fixed-point data, 15 for floating-point decimal data, and 53 for floating-point binary data
- For OpenVMS VAX systems: 31 for fixed-point data, 34 for floating-point decimal data, and 113 for floating-point binary data
q
An integer constant less than or equal to the specified precision. The scale factor can be optionally signed when used in fixed-point binary subtraction. The scale factor for fixed-point binary must be in the range -31 through p. The scale factor for fixed-point decimal data must be in the range 0 through p. If you omit q, the default value is zero. Do not use a scale factor for floating-point arithmetic.
Expressions x and y are converted to their derived type before the subtraction is performed.
For example:
SUBTRACTBIF: PROCEDURE OPTIONS (MAIN);
DECLARE X FIXED DECIMAL (8,3),
Y FIXED DECIMAL (8,3),
Z FIXED DECIMAL (9,3);
X=9500.374;
Y=2278.897;
Z = SUBTRACT (X,Y,9,3);
PUT SKIP LIST ('DIFFERENCE =',Z);
END;
|
This program prints:
DIFFERENCE = 7221.477 |
The SUM built-in function takes an array as an argument and returns the arithmetic sum of all the elements in the array. The array must have the FIXED or the FLOAT attribute. The format of the SUM built-in function is:
SUM(array-variable) |
If the array has the attributes FIXED(p,q), the result will have the attributes FIXED(p,q). If the array has the attributes FLOAT(p), the result will also have the attributes FLOAT(p).
The result will have the same base attribute as the array, either
DECIMAL or BINARY.
11.4.88 TAN
The TAN built-in function returns a floating-point value that is the tangent of an arithmetic expression x, where x represents an angle in radians. The tangent is computed in floating point. After its conversion to floating point, x must not be an odd multiple of Pi sign/2 .
The format of the function is:
TAN(x) |
The TAND built-in function returns a floating-point value that is the tangent of an arithmetic expression x, where x represents an angle in degrees. The tangent is computed in floating point. After its conversion to floating point, x must not be an odd multiple of 90.
The format of the function is:
TAND(x) |
The TANH built-in function returns a floating-point value that is the hyperbolic tangent of an arithmetic expression x. The hyperbolic tangent is computed in floating point. The format of the function is:
TANH(x) |
The TIME built-in function returns an 8-character string representing the current time of day in the following form:
hhmmssxx |
hh
The current hour (00-23)mm
The minutes (00-59)ss
The seconds (00-59)xx
Hundredths of seconds (00-99)
The format of the TIME built-in function is:
TIME() |
If TIME is used as a preprocessor built-in function, the time returned
is the time when the program was compiled; otherwise the function
returns the time at run time.
11.4.92 TRANSLATE
Given a character-string argument, the TRANSLATE built-in function replaces occurrences of an old character with a corresponding translation character and returns the resulting string. The format is:
TRANSLATE(original,translation[,old-chars]) |
original
A character-string expression in which specific characters are to be translated.translation
A character-string expression giving replacement characters for corresponding characters in old-chars.old-chars
A character-string expression indicating which characters in the original are to be replaced. If old-chars is not specified, the default is COLLATE().If the translation is shorter than old-chars, the translation is padded on the right with spaces to the length of old-chars before any translation occurs. If the translation is longer than old-chars, its excess characters (on the right) are ignored.
The following steps are performed for each character (beginning at the left) in the original:
The string returned is of type CHARACTER(length), where length is the length of the original string. If the original string is a null string, the returned value is a null string.
TRANSLATE_XM: PROCEDURE OPTIONS(MAIN);
DECLARE NEWSTRING CHARACTER(80) VARYING;
DECLARE TRANSLATION CHARACTER(128);
DECLARE I FIXED;
DECLARE COLLATE BUILTIN;
/* translate space to '0': */
NEWSTRING = TRANSLATE('1 2','0',' ');
PUT SKIP LIST(NEWSTRING);
/* translate letter 'F' to 'E': */
NEWSTRING = TRANSLATE('BFFLZFBUB','E','F');
PUT SKIP LIST(NEWSTRING);
/* change case of letters in sentence */
TRANSLATION = COLLATE;
DO I=66 TO 91; /* replace upper with lower */
SUBSTR(TRANSLATION,I,1) = SUBSTR(COLLATE,I+32,1);
END;
DO I=98 TO 123; /* replace lower with upper */
SUBSTR(TRANSLATION,I,1) = SUBSTR(COLLATE,I-32,1);
END;
NEWSTRING =
TRANSLATE('THE QUICK BROWN fox JUMPS OVER THE LAZY dog',TRANSLATION);
PUT SKIP LIST(NEWSTRING);
END TRANSLATE_XM;
|
The first reference translates the string <BIT_STRING>(1 2) to <BIT_STRING>(102). The second reference translates <BIT_STRING>(BFFLZFBUB) to <BIT_STRING>(BEELZEBUB). The third reference produces the following new sentence:
'the quick brown FOX jumps over the lazy DOG' |
The TRIM built-in function accepts a character string as an argument and returns a character string that consists of the input string with specified characters removed from the left and right. If you supply only one argument, TRIM removes blanks from the left and right of the argument. If you supply second and third arguments, TRIM removes characters specified by those arguments from the left and right of the string, respectively.
The format of the TRIM built-in function is:
TRIM (input-string,[beginning-chars,end-chars]) |
input-string
A character-string variable or constant. This argument supplies the string from which characters are to be trimmed.beginning-chars
A character-string variable or constant. This argument specifies characters to be trimmed from the left of the input string. If a character that is in the first position in the input string is also present anywhere in beginning-chars, that character is removed from the input string. This process is repeated until a character is encountered on the left of the input string that is not present in beginning-chars, or until the characters in the input string are exhausted.end-chars
A character-string variable or constant. This argument specifies characters to be trimmed from the right of the input string. The process of removing characters from the right is identical to that of removing characters from the left, except that the character in the last position is examined.
The TRIM built-in function accepts either one or three arguments. Any of the arguments can consist of a null string; specifically, if beginning-chars or end-chars is null, no characters are removed from the corresponding end of the input string.
When only one argument is supplied, TRIM removes blanks from both ends of that argument. In other words, the following two expressions are equivalent:
TRIM(S) TRIM(S,' ',' ') |
The returned value is a character string with characters removed from the ends.
The following examples illustrate the use of the TRIM built-in function.
| Text | Returned String |
|---|---|
| TRIM ('ABC') | 'ABC' |
| TRIM(' ABC') | 'ABC' |
| TRIM(' ABC ') | 'ABC' |
| TRIM('ABC ') | 'ABC' |
| TRIM(' ABCDEF','','E') | ' ABCDEF' |
| TRIM(' ABCDEF','','FE') | ' ABCD' |
| TRIM(' ABCDEF ','ABC','EDF') | ' ABCDEF ' |
| TRIM('ABCDEF','CADB','FE') | '' |
| TRIM(' ABCDEF ','ABC ',' EDF') | '' |
| TRIM('AAAABCCXCCDDDDEFFFF','AC','DF') | 'BCCXCCDDDDE' |
The TRUNC built-in function changes all fractional digits in an arithmetic expression x to zeros and returns the resulting integer value. Its format is:
TRUNC(x) |
If x is a floating-point expression, the returned value is a floating-point value. If x is a fixed-point expression, the returned value is a fixed-point value with the same base as x. The value has the following attributes:
precision = min(31,p-q+1)
scale factor = 0
scale factor = 0
Here, p and q are the precision and scale factor of x.
11.4.95 UNSPEC
The UNSPEC built-in function returns a bit string representing the internal coded value of the referenced variable, or a specified part of that variable. The variable can be an aggregate or a scalar variable of any type. The format of the function is:
UNSPEC(reference[,position[,length]]) |
The returned value is a bit string whose length is the number of bits occupied by the referenced variable or by that part of the variable specified by the optional parameters, position and length. The length of the bit string must be less than or equal to the maximum length for bit-string data. The returned bit string contains the contents of the storage of the referenced variable (or the specified part of the variable), the first bit in storage being the first bit in the returned value. The actual value is specific to VAX hardware systems and Alpha hardware systems, and may differ from other PL/I implementations. Note that if the referenced variable is a binary integer (FIXED BINARY), the first bit in the returned value is the lowest binary digit.
DECLARE X CHARACTER(2), Y BIT(16);
X = 'AB';
Y = UNSPEC(X);
.
.
.
DECLARE I FIXED BINARY(15);
I = 2;
PUT LIST(UNSPEC(I));
|
As a result of the first UNSPEC reference, Y contains the ASCII codes of <BIT_STRING>(A) and <BIT_STRING>(B). The PUT LIST statement containing UNSPEC(I) prints the following string:
'0100000000000000'B |
The VALID built-in function determines whether the argument x, a pictured variable, has a value that is valid with respect to its picture specification. A value is valid if it is any of the character strings that can be created by the picture specification. The function returns <BIT_STRING>(0)B if x has an invalid value and <BIT_STRING>(1)B if it has a valid value. The function can be used whenever a data item is read in with a record input (READ) statement, to ensure that the input data is valid. The format of the function is:
VALID(x) |
x
A reference to a variable declared with the PICTURE attribute.
Note that pictured data is always validated (and thus, the VALID function is unnecessary) when it is read in with the GET EDIT statement and the P format item; the CONVERSION condition is signaled if the data does not conform to the picture given in the P format item. If GET LIST is used (or GET EDIT with a format item other than P), the input value is converted to conform to the pictured input target.
VALP: PROCEDURE OPTIONS(MAIN);
DECLARE INCOME PICTURE '$$$$$$V.$$';
DECLARE MASTER RECORD FILE;
DECLARE I FIXED;
DO I = 1 TO 2;
READ FILE(MASTER) INTO(INCOME);
IF VALID(INCOME) THEN;
ELSE PUT SKIP LIST('Invalid input:',INCOME);
END;
END VALP;
|
Asume that the file MASTER.DAT contains the following data:
$15000.50 50000.50 |
Invalid input: 50000.50 |
The picture <BIT_STRING>($$$$$$V.$$) specifies a fixed-point
decimal number of up to seven digits, two of which are fractional. To
be valid, a pictured value must consist of nine characters: the first
digit must be immediately preceded by a dollar sign, the number must
contain a period before the fractional digits, and each position
specified by a dollar sign must contain either that sign, a digit, or a
space. The second record in MASTER.DAT can be assigned by the READ
statement because it has the correct size; however, the pictured value
is invalid because it does not contain a dollar sign.
11.4.97 VALUE
The VALUE built-in function is used to force a parameter to be passed by immediate value, rather than by whatever mechanism is specified by the declaration of the formal parameter.
The syntax of the function is:
(expression)
expression
An expression or scalar variable that is valid to be passed by value. It must fit into a longword (32 bits). The valid data types are:
- FIXED BINARY (m) where m is less than or equal to 31
- FLOAT BINARY (n) where n is less than or equal to 24
- BIT (o) ALIGNED where o is less than or equal to 32
- ENTRY
- OFFSET
- POINTER
DECLARE FOO ENTRY (ANY) EXTERNAL; DECLARE X FIXED BINARY (31); X = 15; . . . CALL FOO(VALUE(X)); |
As with the REFERENCE and DESCRIPTOR built-in functions, VALUE is not
designed for use with other PL/I procedures; it is intended for use
only with routines written in languages other than PL/I.
11.4.98 VARIANT
The VARIANT preprocessor built-in function returns a string representing the value of the variant qualifier in the command that invoked the compilation.
The format in a preprocessor expression is:
VARIANT() |
The /VARIANT qualifier permits specification of compilation variants. The value specified is available to the VARIANT preprocessor built-in function at compile time. The format of compilation variants is:
For example, if a program is to be compiled with one of three different INCLUDE files, you can use the /VARIANT command qualifier to specify which file is to be included. In the following example, the file SPECIAL.SRC is included in the program only if /VARIANT=SPECIAL appears in the pli command line.
For example:
%IF VARIANT() = 'SPECIAL'
%THEN
%INCLUDE 'SPECIAL.SRC';
%IF VARIANT() = 'NONE'
%THEN;
|
No action is taken if /VARIANT=NONE appears on the pli command line.
If /VARIANT is not specified, or if it is specified without a value,
the default value is /VARIANT ="".
11.4.99 VERIFY
The VERIFY built-in function compares a string with a character-set string and verifies that all characters appearing in the string also appear in the character-set string. The function returns the value zero if they all appear. If not, the function returns a fixed-point binary integer that indicates the position of the first character in the string that is not present in the character-set string. The comparison is done character by character and left to right, and as soon as one nonmatching character is found in the first string, no more characters are compared. The function is case sensitive.
The format of the function is:
VERIFY(string,character-set-string[,starting-position]) |
string
A character-string expression representing the string to be checked.character-set-string
A character-string expression containing the set of characters with which the characters in the first string are to be compared.starting-position
A positive integer in the range 1 to n+1, where n is the length of the first string. It specifies the leftmost position in the first string to be compared with the character-set-string. (By default, the comparison starts at the left end of the first string.)
| #1 |
|---|
STRING = 'HOW MUCH IS 1 PLUS 2';
ALPHABET = 'abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ ';
A = VERIFY(STRING,ALPHABET);
|
The value of the variable ALPHABET is a string containing the 26 lowercase letters, the 26 uppercase letters, and the space character. The function returns a value of 13, indicating the position of the character '1', which is the first nonalphabetic and nonspace character in STRING.
| #2 |
|---|
A = VERIFY(STRING,' ');
|
This example finds the first nonspace character in a string by using the space character as a test string. Note that constants can be used as the string parameters.
| #3 |
|---|
NEWSTRING = 'ALL LETTERS';
A = VERIFY(NEWSTRING,ALPHABET);
|
VERIFY returns a value of zero because all characters in the string NEWSTRING are present in the string ALPHABET.
| #4 |
|---|
NEWSTRING = '9 LETTERS';
A = VERIFY (NEWSTRING,ALPHABET,2);
|
The optional starting-position parameter specifies that the comparison begins at position 2 in NEWSTRING. VERIFY returns a value of zero because all characters beginning with the second character in the string NEWSTRING are present in the string ALPHABET. If the starting-position parameter had not been specified, VERIFY would have returned a value of 1, because the first character ('9') in NEWSTRING is not present in ALPHABET.
| Previous | Next | Contents | Index |