PASCAL, Predeclared Routines
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help PASCAL, Predeclared Routines *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
Compaq Pascal supplies predeclared procedures and functions that perform various commonly used operations. You do not have to declare these routines in order to call them from your code.
| 1 - Allocation |
The allocation size routines provide information about the amount of storage allocated for variables and components of various types. The parameters may be in the form of variable or type identifiers. Each routine returns an integer value that represents the allocation size of the given parameter.
1.1 - BITNEXT
The BITNEXT function returns an integer value that indicates the
number of bits that would be allocated for one component of the
specified type in a packed array or if the specified variable
appeared as a cell in a packed array.
Syntax:
BITNEXT( x )
The parameter 'x' can be a variable or any type identifier.
1.2 - BITSIZE
The BITSIZE function returns an integer value that indicates the number of bits that would be allocated for one field of the specified type in a packed record or if the specified variable appeared as a field in a packed record. Syntax: BITSIZE( x ) The parameter 'x' can be a variable or any type identifier.
1.3 - BIT_OFFSET
The BIT_OFFSET function returns an integer value that represents
the bit position of a field in a record.
Syntax:
BIT_OFFSET( t,f )
The parameter 't' can be of any record type or variable, and the
parameter 'f' can be any field contained in that record.
1.4 - BYTE_OFFSET
The BYTE_OFFSET function returns an integer value that
represents the byte position of a field in a record.
Syntax:
BYTE_OFFSET( t,f )
The parameter 't' can be of any record type or variable, and the
parameter 'f' can be any field contained in that record.
1.5 - NEXT
The NEXT function returns an integer value that indicates the
number of bytes that would be allocated for one component of the
specified type in an unpacked array or if the specified variable
appeared as the cell in an unpacked array.
Syntax:
NEXT( x )
The parameter 'x' can be a type identifier or variable.
Cells in an unpacked array are affected by alignment attributes
and, by default, are byte or naturally aligned. Therefore, the
size returned includes the actual size of the type or variable,
in addition to trailing space required to ensure proper
alignment.
1.6 - SIZE
The SIZE function returns an integer value that indicates the
possible or actual number of bytes that are allocated for a
specified data type or variable.
Syntax:
SIZE( x[[,t1,...,tn]] )
The parameter 'x' can be a type identifier or a variable. If
'x' is a type identifier, then SIZE returns an integer value
which indicates the number of bytes that would be allocated for
a variable or record field of type 'x'.
If 'x' is a variable, then SIZE returns an integer value that
indicates the number of bytes that are allocated for that
variable.
In the case where the parameter 'x' is a variant record variable
or variant type identifier, SIZE returns an integer value that
indicates the number of bytes that are allocated (for a variant
record variable) or would be allocated (for a variant type
identifier) for both the fixed portion of the record and the
largest variant. In addition you can supply additional
parameters t1 through tn that correspond to the case labels of
the record. The SIZE routine returns an integer value that
indicates the number of bytes that would be allocated by the NEW
procedure for a dynamic variable of the specified variant.
| 2 - Arithmetic |
Arithmetic routines perform mathematical computations. Actual parameters to the arithmetic functions can be of any arithmetic type.
2.1 - ABS
The ABS function returns a value (of the same data type as the
specified parameter) that is the absolute value of the
parameter.
Syntax:
ABS( x )
The parameter 'x' can be of any arithmetic type.
2.2 - ARCTAN
The ARCTAN function returns a real value that expresses in
radians the arctangent of the specified parameter.
Syntax:
ARCTAN( x )
The parameter 'x' can be an integer or REAL type.
2.3 - COS
The COS function returns a real value that represents the cosine
of the specified parameter.
Syntax:
COS( x )
The parameter 'x' can be an integer or REAL type, and is
expressed in radians.
2.4 - EXP
The EXP function returns a real value that represents the
exponent of the specified parameter (it represents e**x).
Syntax:
EXP( x )
The parameter 'x' can be an integer or REAL type.
2.5 - LN
The LN function returns a real value that represents the natural
logarithm of the specified parameter.
Syntax:
LN( x )
The parameter 'x' can be an integer or REAL type. The value of
'x' must be greater than zero.
2.6 - LSHIFT_LSHFT
The LSHIFT and LSHFT predeclared functions return a value of the
same type as its first parameter. The return value represents
the value of the first parameter after the bits have been
shifted to the left.
Syntax:
LSHIFT(expression,expression)
LSHFT(expression,expression)
The parameters are two integer or unsigned values. The first
parameter represents a value to shift. The second parameter
represents the number of bits to shift the first value to the
left. LSHIFT and LSHFT insert zero bits on the right as the
bits shift left.
Note that shifting integers is not equivalent to multiplying or
dividing by a power of two when the value of the integer is
negative.
If the number of bits shifted is larger than the natural integer
size of the target platform, the result is undefined.
2.7 - MAX
The MAX function returns a value (the same type as that of the
parameters) that is the maximum value of a specified list of
parameters.
Syntax:
MAX( x1,...,xn )
The parameters can be any arithmetic type, but must all be of
the same type.
2.8 - MIN
The MIN function returns a value (of the same type as that of
the parameters) that is the minimum value of a specified list of
parameters.
Syntax:
MIN( x1,...,xn )
The parameters can be any arithmetic type, but must all be of
the same type.
2.9 - RSHIFT_RSHFT
The RSHIFT and RSHFT predeclared functions return a value of the
same type as its first parameter. The value represents the
value of the first parameter after the bits have been shifted to
the right.
Syntax:
RSHIFT(expression,expression)
RSHFT(expression,expression)
The parameters are two integer or unsigned values. The first
parameter represents a value to shift; the second represents the
number of bits to shift the first value. The RSHIFT and RSHFT
functions insert zero bits on the left as the bits shift right.
Note that shifting integers is not equivalent to multiplying or
dividing by a power of two when the value of the integer is
negative.
If the number of bits shifted is larger than the natural integer
size of the target platform, the result is undefined.
2.10 - SIN
The SIN function returns a real value that represents the sine
of the specified parameter.
Syntax:
SIN( x )
The parameter 'x' can be an integer or REAL type, and is
expressed in radians.
2.11 - SQR
The SQR function returns a value (of the same type of the
parameter) that represents the square of the specified
parameter.
Syntax:
SQR( x )
The parameter 'x' can be of any arithmetic type.
2.12 - SQRT
The SQRT function returns a real value that represents the
square root of the specified parameter.
Syntax:
SQRT( x )
The parameter 'x' can be of an integer, unsigned, or REAL type.
If the value of 'x' is less than zero, an error occurs.
2.13 - UAND
The UAND function returns an unsigned value that represents a
binary logical AND operation on each corresponding pair of bits
of the specified parameters.
Syntax:
UAND( u1,u2 )
The parameters 'u1' and 'u2' must be unsigned.
2.14 - UNOT
The UNOT function returns an unsigned value that represents a
binary logical NOT operation on each bit of the specified
parameter.
Syntax:
UNOT( u1 )
The parameter 'u' must be unsigned.
2.15 - UOR
The UOR function returns an unsigned value of a binary logical
OR operation on the corresponding pair of bits of two specified
parameters.
Syntax:
UOR( u1,u2 )
The parameters 'u1' and 'u2' must be unsigned.
2.16 - UXOR
The UXOR function returns an unsigned value of a binary logical
exclusive-OR operation on the corresponding pair of bits of two
specified parameters.
Syntax:
UXOR( u1,u2 )
The parameters 'u1' and 'u2' must be unsigned.
2.17 - XOR
The XOR function returns a value (of the same type as the
parameters) of a binary logical exclusive-OR operation on two
specified parameters.
Syntax:
XOR( p1,p2 )
The 'p1' and 'p2' parameters must be of the same type and must
be of either the BOOLEAN or SET types.
| 3 - Char Strng |
Compaq Pascal supplies predeclared routines that manipulate character strings.
3.1 - BIN
The BIN function returns a character-string value that is the
binary equivalent of the specified parameter. The return value
is compatible with all other string types.
Syntax:
BIN( x [[, length[[, digits]]]] )
The parameter 'x' is the expression to be converted. This
parameter must have a size that is known at compile time; it
cannot be VARYING OF CHAR, a conformant parameter, or a schema
type.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left.
If you omit the optional parameters, the bit width of the
converted parameter value determines the string length and the
number of significant digits. By default, the number of
significant digits is the minimum number of characters necessary
to express all the bits of the converted parameter. This
default length is one character more than the default number of
digits, which causes a leading blank to be included in the
resulting string when both parameters are omitted.
3.2 - DEC
The DEC function returns character-string value that is the
decimal equivalent of the specified parameter. The return value
is compatible with all other string types.
Syntax:
DEC( x [[, length[[, digits]]]] )
The parameter 'x' is the expression to be converted. The DEC
function can take a parameter of any type except VARYING OF
CHAR, conformant parameters, or schema types. The DEC function
requires the size of 'x' to be less than or equal to the size of
INTEGER64 (if supported), or less than or equal to the size of
INTEGER32.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left. If you do not specify values for the optional parameters,
a default length and a default minimum number of significant
digits is used.
If the size of 'x' is greater than 32, the defaults are 20
characters for the length and 19 characters for the minimum
number of digits. Otherwise, the defaults are 11 characters for
the length and 10 characters for the minimum number of digits.
Because the default length is 1 greater than the number of
significant digits, positive numbers will be preceded by a blank
and negative numbers will be preceded by a minus sign.
3.3 - EQ
The EQ function returns a Boolean value that specifies if the
parameters are equal according to the ASCII values of the
strings' characters.
Syntax:
EQ( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. If the EQ function detects unequal string lengths,
it stops comparison and returns FALSE.
3.4 - FIND_MEMBER
The FIND_MEMBER function locates the first character in a string
that is a member of a specified set and returns an integer value
indicating the position of the character in the string; the
function returns 0 if the characters in the string were not
members of the set.
Syntax:
FIND_MEMBER( string, char-set )
The 'string' parameter is a string value, and the 'char-set' is
a value of type SET OF CHAR.
3.5 - FIND_NONMEMBER
The FIND_NONMEMBER function locates the first character in a
string that is not a member of a specified set and returns an
integer value indicating the position of the character in the
string; the function returns 0 if the characters in the string
were all members of the set.
Syntax:
FIND_NONMEMBER( string, char-set )
The 'string' parameter is a string value, and the 'char-set' is
a value of type SET OF CHAR.
3.6 - GE
The GE function returns a Boolean value that specifies if the
first parameter is greater than or equal to the second
parameter, according to the ASCII values of the strings'
characters.
Syntax:
GE( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. Compaq Pascal does not pad shorter strings with
blanks.
3.7 - GT
The GT function returns a BOOLEAN value that specifies if the
first parameter is greater than the second parameter, according
to the ASCII values of the strings' characters.
Syntax:
GT( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. Compaq Pascal does not pad shorter strings with
blanks.
3.8 - HEX
The HEX function returns a character-string value that is the
hexadecimal equivalent of the specified parameter. The return
value is compatible with all other string types.
Syntax:
HEX( x [[, length[[, digits]]]] )
The parameter 'x' is the expression to be converted. This
parameter must have a size that is known at compile time; it
cannot be VARYING OF CHAR, a conformant parameter, or a schema
type.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left. If you do not specify values for the optional parameters,
a default length and a default number of significant digits is
used.
By default, the number of significant digits is the minimum
number of characters necessary to express all the bits of the
converted parameter. This default length is one character more
than the default number of digits, which causes a leading blank
to be included in the resulting string when both parameters are
omitted.
3.9 - INDEX
The INDEX function searches a string for a specified substring
and returns an integer value that either indicates the location
of the substring or the status of the search.
Syntax:
INDEX( string, substring )
INDEX requires two character-string expressions as parameters:
a string to be searched and a substring to be found.
The search ends as soon as the first occurrence of the substring
is located. If the substring is found, INDEX returns the string
component that contains the first letter of the substring. If
the substring is not found, INDEX returns the value 0. If the
substring is an empty string, INDEX returns the value 1. If the
string to be searched is an empty string, INDEX returns the
value 0 unless the substring is also empty; in which case, INDEX
returns the value 1.
3.10 - LE
The LE function returns a Boolean value that specifies if the
first parameter is less than or equal to the second parameter,
according to the ASCII values of the strings' characters.
Syntax:
LE( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. Compaq Pascal does not pad shorter strings with
blanks.
3.11 - LENGTH
The LENGTH function returns an integer value that is the length
of a specified string expression.
Syntax:
LENGTH( str )
The parameter 'str' must be a character-string expression.
3.12 - LT
This function returns a Boolean value that specifies if the
first parameter is less than the second parameter, according to
the ASCII values of the strings' characters.
Syntax:
LT( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. Compaq Pascal does not pad shorter strings with
blanks.
3.13 - NE
The NE function returns a Boolean value that specifies if the
parameters are not equal according to the ASCII values of the
strings' characters.
Syntax:
NE( str1,str2 )
The parameters 'str1' and 'str2' must be character-string
expressions. Compaq Pascal does not pad shorter strings with
blanks.
3.14 - OCT
The OCT function returns character-string value that is the
octal equivalent of the specified parameter. The return value
is compatible with all other string types.
Syntax:
OCT( x [[, length[[, digits]]]] )
The parameter 'x' is the expression to be converted. This
parameter must have a size that is known at compile time; it
cannot be VARYING OF CHAR, a conformant parameter, or a schema
type.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left.
By default, the number of significant digits is the minimum
number of characters necessary to express all the bits of the
converted parameter. This default length is one character more
than the default number of digits, which causes a leading blank
to be included in the resulting string when both parameters are
omitted.
3.15 - PAD
The PAD function returns a character-string value, of the
specified size, that contains padded fill characters. The
return value is compatible with all other string types.
Syntax:
PAD( str,fill,size )
The parameter 'str' is a character-string value to be padded;
the parameter fill is a value of type CHAR to be used as the
fill character; and, the parameter 'size' is an integer value
indicating the size of the final string.
This string is composed of the original string followed by the
fill character, which is repeated as many times as is necessary
to extend the string to its specified size. The final size must
be greater than or equal to the length of the string to be
padded.
3.16 - READV
The READV procedure reads characters from a character-string
expression and assigns them to parameters in the READV call.
The behavior of READV is analogous to that of READLN; the
character string is analogous to a one-line file.
Syntax:
READV( str, {variable-id[[ : radix-specifier ]]},...
[[, ERROR := error-recovery ]])
The parameter 'str' is the string to be read. The
variable-identifier is the variable to be assigned a value from
'str'. The parameter 'radix-specifier' can be BIN, OCT, or HEX.
You can read a variable of any type by using a radix specifier
except a type that contains a file component. The
'error-recovery' indicates the action to be taken in case of an
error.
An error occurs at run time if values have not been assigned to
all the parameters listed in the READV procedure call before the
end of the character string is reached.
3.17 - STATUSV
The STATUSV function returns an integer value that specifies the status of the last READV or WRITEV completed. It does not have any parameters. Note that if you have an asynchronous trap (AST) routine condition handler written in your program that uses READV and WRITEV, the call of STATUSV in your main program may not return the results you expected if an AST occurred between the READV/WRITEV and STATUS.
3.18 - SUBSTR
The SUBSTR function returns a substring (from a string specified
as a parameter) that is of the specified starting point and
length. The return value is compatible with all other string
types.
Syntax:
SUBSTR( str,start,length )
The parameter 'str' is a character string value; the parameter
'start' is an integer value that indicates the starting position
of the substring. The parameter 'length' is an integer value
that indicates the length of the substring.
When you use the SUBSTR function, the value of the starting
position must be greater than 0, the value of the length must be
greater than or equal to 0, and there must be enough characters
following the starting position to construct a substring of the
specified length.
3.19 - UDEC
The UDEC function returns a character-string value that is the
unsigned decimal equivalent of the specified parameter. The
return value is compatible with all other string types.
Syntax:
UDEC(x [[,length[[,digits]]]])
The parameter 'x' is the expression to be converted. The UDEC
function can take a parameter of any type except VARYING OF
CHAR, conformant parameters, or schema types. This function
requires the size of 'x' to be less than or equal to the size of
INTEGER64 (if supported) on your system. If your system does
not support INTEGER64, then the UDEC function requires that 'x'
be less than or equal to the size of INTEGER32.
Two optional integer parameters specify the length of the
resulting string and the minimum number of significant digits to
be returned. If you specify a length that is too short to hold
the converted value, the resulting string is truncated on the
left.
If you do not specify values for the optional parameters, a
default length and a default minimum number of significant
digits is used. If the size of 'x' is greater than 32, the
defaults are 21 characters for the length and 20 characters for
the minimum number of digits. Otherwise, the defaults are 11
characters for the length and 10 characters for the minimum
number of digits.
3.20 - WRITEV
The WRITEV procedure writes characters to a character-string
variable of type VARYING OF CHAR or discriminated STRING, by
converting the values of the parameters in the procedure call to
textual representations. The behavior of WRITEV is analogous to
that of the WRITELN function; the character-string parameter is
analogous to a one-line file.
Syntax:
WRITEV( str, parameter-list
[[,ERROR := error-recovery]] )
The parameter 'str' cannot appear within the parameter-list; if
you attempt to do this, unexpected results may occur. An error
occurs if WRITEV reaches the maximum length of the character
string before the values of all the parameters in the procedure
call have been written into the string. The parameter
'error-recovery' indicates the action to be taken if an error
occurs while the WRITEV procedure is executing.
| 4 - Dyn Alloc |
Compaq Pascal provides dynamic allocation routines for the creation and use of pointer variables. Use pointer variables and dynamic allocation routines to create linked data structures.
4.1 - ADDRESS
The ADDRESS function returns a pointer value that is the address
of the parameter.
Syntax:
ADDRESS( x )
The parameter 'x' can be a variable of any type except a
component of a packed structured type. A compile-time warning
results if 'x' is a formal VAR parameter, a component of a
formal VAR parameter, or a variable that does not have the
READONLY or VOLATILE attribute.
A pointer can only refer to a VOLATILE variable or a variable
allocated by the NEW procedure.
4.2 - DISPOSE
The DISPOSE procedure deallocates memory for a dynamic variable.
Syntax:
DISPOSE( p )
The parameter 'p' is a pointer variable. The 't' parameters are
constant expressions that match the corresponding 't' parameter
used in the call to the NEW procedure that allocated the memory.
If you use 't' parameters in a call to NEW, you must specify the
same 't' parameters in the call to DISPOSE. If you allocated
memory using d parameters, just specify the pointer variable to
the corresponding DISPOSE call.
The DISPOSE procedure deallocates the object to which the
pointer variable points. You cannot call DISPOSE more than once
for the same dynamic variable.
4.3 - IADDRESS
The IADDRESS function returns an INTEGER_ADDRESS value that
refers to a the address of either a VOLATILE parameter or a
routine, and does not generate compile-time warnings (as does
the ADDRESS function). The IADDRESS function is commonly used
for constructing arguments for system services of the VMS
operating system.
Syntax:
IADDRESS( x )
The parameter 'x' can be of any type except a component of a
packed structured type or a routine name. The parameter 'x' can
be a variable, parameter, routine, or constant-expression. When
IADDRESS is used on constant-expressions, the returned address
is valid for the remainder of the program. Two calls to
IADDRESS with the same constant may not return the same address.
Note that the Compaq Pascal compiler automatically assumes that
all pointers refer either to dynamic variables allocated by the
NEW procedure or to variables that have the VOLATILE attribute;
therefore, you should use utmost caution when using the IADDRESS
function. This function does not generate compile-time
warnings.
4.4 - NEW
The NEW procedure allocates memory for the dynamic variable to
which a pointer variable refers. The value of the newly
allocated variable is set to the initial value of the base type
if defined; otherwise, the value of the variable is undefined.
Syntax:
NEW( p [[, {t1,...,tn | d1,...,dn} ]] )
The parameter 'p' is a pointer variable.
The parameters 't1,...,tn' are constant expressions of an
ordinal type that represent nested tag-field values, where 't1'
is the outermost variant.
If the object of the pointer is a non-schema record type with
variants, then you have two ways of allocating memory. If you
do not specify 't' parameters, Compaq Pascal allocates enough
memory to hold any of the variants of the record. If you do
specify 't' parameters, then Compaq Pascal allocates enough
memory to hold only the variant or variants that you specify.
Since the 't' parameters cause Compaq Pascal to allocate memory
for the variant alone and not for the whole record, you cannot
assign or evaluate the record as a whole; you can assign and
evaluate only the individual fields. Also, a call to NEW does
not set the tag fields of a variant record.
The paramters 'd1,...,dn' are compile-time or run-time ordinal
values that must be the same type as the formal discriminants of
the object.
If the object of the pointer is of an undiscriminated schema
type, you must specify a 'd' parameter for each of the formal
discriminants of the schema type. The 'd' parameters
discriminate the schema type in much the same way as actual
discriminants in a discriminated schema. Compaq Pascal bases
the size of the allocation on the value of the 'd' parameters.
If the object is a schema record type, then you must use 'd'
parameters; you cannot use 't' parameters or a combination of
the syntaxes. If the schema record type contains a variant
(which depends on one of the formal discriminants) then the 'd'
parameter discriminates the schema, determines the variant, and
allows Compaq Pascal to compute the necessary size of the
allocation.
Note that if you specify 't' parameters to the NEW procedure,
you must specify the same 't' parameters to the DISPOSE
procedure that deallocates memory for the corresponding
variable.
| 5 - Low Level |
The low-level routines allow for parallel processes and asynchronous routines to operate in a real-time or multi-tasking environment.
5.1 - ADD_ATOMIC
The ADD_ATOMIC function adds the value of an expression to the
value of a variable, stores the newly computed value, and
returns the previous value.
Syntax:
ADD_ATOMIC(e,v)
The type of the expression 'e' must be assignment compatbile
with that of the variable 'v'. The variable 'v' must be an
INTEGER, UNSIGNED, INTEGER64, or UNSIGNED64 variable and must be
allocated on a natural boundary (ie, longword for INTEGER and
UNSIGNED and quadword for INTEGER64 and UNSIGNED64). The result
of ADD_ATOMIC is the same type as the variable 'v'.
Overflow and subrange checking are never performed on the
ADD_ATOMIC operation, even if these options are in effect for
the rest of the function or compilation unit.
5.2 - ADD_INTERLOCKED
The ADD_INTERLOCKED function adds the value of an expression to
the value of a variable, stores the newly computed value in the
variable, and returns an integer value: -1 if the new value is
negative, 0 if it is zero, and 1 if it is positive.
Syntax:
ADD_INTERLOCKED( e, v )
The type of the expression 'e' must be assignment compatible
with that of the variable 'v'. The variable 'v' must be an
integer or an unsigned subrange; 'v' must have an allocation
size of two bytes and must be aligned on a word boundary. The
type of 'e' must be assignment compatible with that of 'v'.
5.3 - AND_ATOMIC
The AND_ATOMIC function logically ANDs the value of an
expression to the value of a variable, stores the newly computed
value, and returns the previous value.
Syntax:
AND_ATOMIC(e,v)
The type of the expression 'e' must be assignment compatbile
with that of the variable 'v'. The variable v must be an
INTEGER, UNSIGNED, INTEGER64, or UNSIGNED64 variable and must be
allocated on a natural boundary (ie, longword for INTEGER and
UNSIGNED and quadword for INTEGER64 and UNSIGNED64). The result
of AND_ATOMIC is the same type as the variable 'v'.
5.4 - BARRIER
The BARRIER procedure causes a memory barrier instruction to be
emitted to synchronize pending memory updates in a
multi-processor environment.
Syntax:
BARRIER
The BARRIER procedure has no parameters.
5.5 - CLEAR_INTERLOCKED
The CLEAR_INTERLOCKED function assigns the value FALSE to the
parameter and returns the original Boolean value of the
parameter.
Syntax:
CLEAR_INTERLOCKED( b )
The variable 'b' must be a variable of type Boolean. The
variable does not have to be aligned; therefore, it can be a
field of a packed record.
5.6 - OR_ATOMIC
The OR_ATOMIC function logically ORs the value of an expression
to the value of a variable, stores the newly computed value, and
returns the previous value.
Syntax:
OR_ATOMIC(e,v)
The type of the expression 'e' must be assignment compatbile
with that of the variable 'v'. The variable v must be an
INTEGER, UNSIGNED, INTEGER64, or UNSIGNED64 variable and must be
allocated on a natural boundary (ie, longword for INTEGER and
UNSIGNED and quadword for INTEGER64 and UNSIGNED64). The result
of OR_ATOMIC is the same type as the variable 'v'.
5.7 - SET_INTERLOCKED
The SET_INTERLOCKED function assigns the value TRUE to the
parameter and returns its original Boolean value.
Syntax:
SET_INTERLOCKED( b )
The variable 'b' must be a variable of type Boolean. The
variable does not have to be aligned; therefore, it can be a
field of a packed record.
| 6 - Ordinal |
Ordinal routines provide information on the ordered sequence of values.
6.1 - LOWER
This function returns the lower bound for ordinal types, SET
base types, and array indexes.
Syntax:
LOWER( x [[, n]] )
The parameter 'x' is a type identifier or variable of an
ordinal, SET, or ARRAY type. The parameter 'n' is an integer
constant that denotes a dimension of 'x', if 'x' is an array.
If 'x' is an array and if you omit the 'n', Compaq Pascal uses
the default value 1. If 'x' is an array, LOWER returns the
lower bound of the nth dimension of 'x'. If 'x' is an ordinal
type, LOWER returns the lower bound or smallest value. If 'x'
is a SET, LOWER returns the lower bound of the SET base type.
6.2 - PRED
The PRED function returns the value preceding the parameter
according to the parameter's data type.
Syntax:
PRED( x )
The parameter 'x' can be of any ordinal type; however, there
must be a predecessor value for 'x' in the type.
6.3 - SUCC
The SUCC function returns the value that succeeds the parameter
according to the parameter's data type.
Syntax:
SUCC( x )
The parameter 'x' can be of any ordinal type; however, there
must be a successor value for 'x' in the type.
6.4 - UPPER
The UPPER function returns the upper bound for ordinal types,
SET base types, and array indexes.
Syntax:
UPPER( x [[, n]] )
The parameter 'x' is a type identifier or variable of an
ordinal, SET, or ARRAY type. The parameter 'n' is an integer
constant that denotes a dimension of 'x', if 'x' is an array.
If 'x' is an array and if you omit the 'n', Compaq Pascal uses
the default value 1. If 'x' is an array, UPPER returns the
upper bound of the nth dimension of 'x'. If 'x' is an ordinal
type, UPPER returns the upper bound or largest value. If 'x' is
a SET, UPPER returns the upper bound of the SET base type.
| 7 - Null String |
Compaq Pascal provides routines for manipulating null-terminated strings. These routines use the predeclared type C_STR_T as a pointer to a null-terminated character string. The compiler assumes that buffers are large enough to hold their values and null-terminated strings are actually terminated by a null character.
7.1 - C_STR
The C_STR function takes a compile-time string expression and
returns a C_STR_T pointer to a static string literal with a
terminating null character.
Syntax:
C_STR(e)
The C_STR function can also accept a Pascal variable of either
PACKED ARRAY OF CHAR, VARYING OF CHAR, or STRING.
Syntax:
C_STR(v)
In this form, it will return a C_STR_T value that represents the
first character in the string variable. It does not ensure a
terminating null byte. The programmer must handle the
null-termination to treat a Pascal string variable as a
null-terminated string.
7.2 - MALLOC_C_STR
The MALLOC_C_STR function takes a Pascal string expression,
calls the C routine malloc() to allocate memory, initializes the
memory with the string expression, and then terminates the
string with a null-charcter.
Syntax:
MALLOC_C_STR(e)
The type of the expression e must be a Pascal string expression.
The function result is a C_STR_T pointer to the null-terminted
string. The amount of memory allocated with malloc() is equal
to the length of the string expression plus one. The memory
allocated with MALLOC_C_STR must be deallocated with the C
free() routine. The compiler will not allow C_STR_T parameters
with the NEW and DISPOSE routines.
7.3 - PAS_STR
The PAS_STR function returns a Pascal string value from a
C_STR_T value.
Syntax:
PAS_STR(e)
The type of the expression e must be C_STR_T. It is an error if
the expression is NIL.
7.4 - PAS_STRCPY
The PAS_STRCPY function copies a Pascal string expression into
memory pointed to by C_STR_T.
Syntax:
PAS_STRCPY(v, e)
The type of the variable v must be C_STR_T. The type of the
expression e must be a Pascal string expression. The Pascal
string is copied into the memory pointed to by the variable v.
The memory is then terminated with a null character. The
function returns a C_STR_T value representing the destination
(such as, the same value as contained by the variable v).
The behavior of PAS_STRCPY is undefined if the length of the
Pascal string expression is greater than or equal to the amount
of memory pointed to by the variable v. It is an error if the
variable v is NIL.
| 8 - Parameter |
Compaq Pascal provides routines that give information about variable-length parameter lists.
8.1 - ARGUMENT
The ARGUMENT function specifies an argument in a variable-length
parameter list that was created using the LIST attribute.
Syntax:
ARGUMENT( parameter-name, n )
The 'parameter-name' argument specifies the name of a parameter
declared with the LIST attribute. The 'n' specifies a positive
integer value that identifies the argument. The first argument
in a list is always 1. An error occurs if the value supplied
for 'n' is less than 1, or exceeds the ARGUMENT_LIST_LENGTH
parameter (which indicates the total number of arguments).
If the LIST parameter is a value parameter, ARGUMENT indicates
the corresponding value in the argument list. If the LIST
parameter is a VAR parameter, ARGUMENT is a reference to the
corresponding variable in the argument list.
8.2 - ARGUMENT_LIST_LENGTH
The ARGUMENT_LIST_LENGTH function returns an integer value
representing the number of arguments in a variable-length
parameter list that was created using the LIST attribute.
Syntax:
ARGUMENT_LIST_LENGTH( parameter-name )
The 'parameter-name' argument specifies the name of the
parameter declared with the LIST attribute.
When creating a variable-length parameter list, you can place
the LIST attribute on only the last formal parameter. When you
call the routine, you can specify any number of actual
parameters, or arguments, that correspond to the last formal
parameter declared with LIST.
8.3 - PRESENT
The PRESENT function returns a Boolean value that indicates
whether the actual argument list of a routine contains an
argument that corresponds to a formal parameter. (The PRESENT
function is usually used to supply a default value or to take a
default action when the argument for a parameter is omitted.)
Syntax:
PRESENT (parameter-name)
The 'parameter-name' parameter is the name of a formal parameter
with the TRUNCATE attribute. The 'parameter-name' must be the
name of a formal parameter of the function from which PRESENT is
called, or from a subroutine of that function. The function
result indicates whether the argument list of the containing
routine specifies an actual argument corresponding to an
optional parameter.
Parameters that do not have the TRUNCATE attribute and also do
not follow a parameter with the TRUNCATE attribute in the formal
parameter list, are allowed; in their case, the PRESENT function
always returns TRUE.
Default parameters are considered to be present in the argument
list, and the PRESENT function returns TRUE when passed the name
of a parameter with a default value.
| 9 - Transfer |
Transfer routines convert an actual parameter to data of another type.
9.1 - CHR
The CHR function returns a char value whose ordinal value in the
ASCII character set is the parameter, provided such a character
exists.
Syntax:
CHR( x )
The parameter 'x' must be integer or unsigned and have a value
from 0 to 255.
9.2 - DBLE
The DBLE function converts the parameter and returns its DOUBLE
equivalent.
Syntax:
DBLE( x )
The parameter 'x' must be of an arithmetic type. The value of
'x' must not be too large to be represented by a
double-precision number.
9.3 - INT64
The INT64 function converts the parameter and returns its
INTEGER64 equivalent.
Syntax:
INT64(x)
Overflow can occur and is detected at runtime if overflow
checking is enabled and the value of 'x' is outside the range of
INTEGER64.
9.4 - INT
The INT function converts the parameter and returns its INTEGER
equivalent.
Syntax:
INT(x)
Overflow can occur and is detected at runtime if overflow
checking is enabled and the value of 'x' is outside the range of
INTEGER.
9.5 - ORD
The ORD function returns an integer value that is the position
of the parameter in the ordered sequence of values of the
parameter's type.
Syntax:
ORD( x )
The parameter 'x' must be of an ordinal type. Note that the
ordinal value of an INTEGER object is the integer itself. If
'x' is of type UNSIGNED, its value must not be greater than
MAXINT.
9.6 - PACK
The PACK procedure copies components of an unpacked array
variable to a packed array variable.
Syntax:
PACK( a,i,z )
The parameter 'a' is an unpacked array. The parameter 'i' is a
value to indicate the starting value of the index of 'a'. The
parameter 'z' is a packed array of the same component type as
'a'.
The number of components in parameter a must be greater than or
equal to the number of components in 'z'. The PACK procedure
assigns the components of 'a', starting with a[i], to the array
'z', starting with z[lower bound], until all the components in
'z' are filled.
In general, when specifying 'i', keep in mind that the upper
bound of a (that is, n) must be greater than or equal to i + v -
u, where 'v' is the upper bound of 'z' and 'u' is the lower
bound of 'z'. That is, ORD(n) must be greater than or equal to
ORD(i) + ORD(v) - ORD(u).
9.7 - QUAD
The QUAD function converts the parameter and returns its
QUADRUPLE equivalent.
Syntax:
QUAD( x )
The parameter 'x' must be of an arithmetic type.
9.8 - ROUND
The ROUND function converts the value of the parameter by
rounding the fractional part of the value, and returns its
integer equivalent.
Syntax:
ROUND( x )
The parameter 'x' must be of type REAL, SINGLE, DOUBLE, or
QUADRUPLE. The value of 'x' must not be too large to be
represented by an integer.
9.9 - SNGL
The SNGL function converts the parameter and returns its real
equivalent.
Syntax:
SNGL( x )
The parameter 'x' must be of an arithmetic type. The value of
'x' must not be too large to be represented by a
single-precision number.
9.10 - TRUNC
The TRUNC function converts the value of the parameter by
truncating the fractional part of the value and returns its
integer equivalent.
Syntax:
TRUNC( x )
The parameter 'x' must be of type REAL, SINGLE, DOUBLE, or
QUADRUPLE. The value of 'x' must not be too large to be
represented by an integer.
9.11 - UINT
The UINT function converts the value of the parameter and
returns its unsigned equivalent.
Syntax:
UINT( x )
The parameter 'x' must be of an ordinal type.
No error results if 'x' is an integer and has a negative value.
The value returned is x MOD 2**32.
9.12 - UINT64
The UINT64 function converts the value of the parameter and
return its UNSIGNED64 equivalent.
Syntax:
UINT64(x)
The parameter 'x' must be of an ordinal type.
No error results if 'x' is an integer and has a negative value.
The value returned is x MOD 2**64.
9.13 - UNPACK
The UNPACK procedure copies components of a packed array to an
unpacked array variable.
Syntax:
UNPACK( z,a,i )
The parameter 'z' is a packed array. The parameter 'a' is an
unpacked array variable. The parameter 'i' is the starting
value of the index of 'a'.
The number of components in 'a' must be greater than or equal to
the number of components in 'z'. The UNPACK procedure assigns
the components of 'z', starting with z[lower bound], to the
array 'a', starting with a[i], until all the components in 'z'
are used.
In general, when specifying 'i', keep in mind that the upper
bound of 'a' (that is, n) must be greater than or equal to i + v
- u, where 'v' is the upper bound of 'a' and 'u' is the lower
bound of 'a'. That is, ORD(n) must be greater than or equal to
ORD(i) + ORD(v) - ORD(u).
Normally, you cannot pass the individual components of a packed
array to formal VAR parameters; you must unpack the array first.
9.14 - UROUND
The UROUND function converts the value of the parameter and
returns its unsigned equivalent by rounding the fractional part
of the value.
Syntax:
UROUND( x )
The parameter 'x' must be of type REAL, SINGLE, DOUBLE, or
QUADRUPLE.
No error results if the value of 'x' is negative or greater than
4,294,967,295. In that case, the unsigned result is the rounded
parameter value MOD 4,294,967,296.
9.15 - UTRUNC
The UTRUNC function converts the parameter and returns its
unsigned equivalent by truncating the fractional part of the
value.
Syntax:
UTRUNC( x )
The parameter 'x' must be of type REAL, SINGLE, DOUBLE, or
QUADRUPLE.
No error results if the value of 'x' is negative or greater than
4,294,967,295. In that case, the unsigned result is the
truncated parameter value MOD 4,294,967,296.
| 10 - Privileged |
Privileged routines manipulate privileged hardware registers.
10.1 - MFPR
The MFPR function returns an unsigned value that is the value of
a VAX internal processor register.
Syntax:
MFPR( ipr_register_expression )
The 'ipr_register_expression' parameter is an expression
compatible with the UNSIGNED type.
The Compaq Pascal compiler generates user-mode code. Compaq
Pascal does not explicitly support the running of Compaq Pascal
generated code in kernel mode. However, if the following rules
are observed, then the generated code has a good chance of
working as expected in elevated access modes:
o All code must be compiled with the /NOCHECK qualifier or
[CHECK(NONE)] attribute. The Compaq Pascal on OpenVMS VAX
run-time signaling method relies on trying to execute the
HALT instruction. In user-mode, this causes an exception
that is a signal to the Compaq Pascal run-time library. In
kernel-mode on an OpenVMS VAX system, this simply HALTs the
machine.
o Avoid all routine calls which translate into Run-Time
Library calls. These include all I/O routines, several
arithmetic routines, several string routines, etc.
10.2 - MTPR
The MTPR procedure assigns a value into a VAX internal processor
register.
Syntax:
MTPR( ipr_register_expression, source_expression );
The 'ipr_register_expression' and 'source_expression' parameters
are expressions compatible with the unsigned type. Compaq
Pascal stores the value specified by 'source-expression' into
the internal processor register specified by
'ipr-register-expression'.
The Compaq Pascal compiler generates user-mode code. Compaq
Pascal does not explicitly support the running of Compaq Pascal
generated code in kernel mode. However, if the following rules
are observed, then the generated code has a good chance of
working as expected in elevated access modes:
o All code must be compiled with the /NOCHECK qualifier or
[CHECK(NONE)] attribute. The Compaq Pascal for OpenVMS VAX
systems run-time signaling method relies on trying to
execute the HALT instruction. In user-mode, this causes an
exception which is a signal to the Compaq Pascal run-time
library. In kernel-mode on an OpenVMS VAX system, this
simply HALTs the machine.
o Avoid all routine calls which translate into Run-Time
Library calls. These include all I/O routines, several
arithmetic routines, several string routines, etc.
| 11 - Misc |
The miscellaneous routines include routines that determine the amount of time a process uses, routines that record the system date and time, routines that control error handling of a program, and routines that perform miscellaneous calculations.
11.1 - ARGC
The ARGC function returns an integer values representing the number of arguments that were typed on the command line used to invoke the program (including the progam name).
11.2 - ARGV
The ARGV function returns a string value containing the
indicated argument.
Syntax:
ARGV(argument-number)
11.3 - ASSERT
The ASSERT procedure signals a run-time error if the value of
its parameter is FALSE.
Syntax:
ASSERT(expression [[, string]])
The 'expression' is a Boolean expression that is normally true.
If ASSERT evaluates the expression as false, it signals a
run-time error, indicating that the assertion failed.
The optional string parameter is output as part of the error
message.
11.4 - CARD
The CARD function returns an integer value indicating the number
of components that are currently elements of the set expression.
Syntax:
CARD( s )
The parameter 's' must be a set expression.
11.5 - CLOCK
The CLOCK function returns an integer value indicating the amount of central processor time, in milliseconds, used by the current process. This function does not have a parameter list. The result of CLOCK includes the amount of central processor time allocated to all previously executed images.
11.6 - CREATE_DIRECTORY
The CREATE_DIRECTORY procedure creates a new directory or
subdirectory.
Syntax:
CREATE_DIRECTORY( file_name [, error_return] )
The 'file_name' parameter must be a directory name and
optionally can contain a device name. The 'error_return'
parameter is optional, and will return an error recovery code if
specified.
11.7 - STANDARD_DATE_AND_TIME
These functions provide a standard way of returning a
character-string value that indicates the calender date and
time. The return value is compatible with all string types.
Syntax:
DATE( t )
TIME( t )
The parameter 't' is a variable of the predeclared type
TIMESTAMP. You can either call the GETTIMESTAMP procedure to
initialize 't' before you pass 't' to either DATE or TIME, or
you can construct your own TIMESTAMP object.
The size of the function's return value depends on the string
length that is normally returned by your system for either date
or time data.
Example:
VAR
Time_Var : TIMESTAMP;
The_Time, The_Date : STRING(23);
{In the executable section:}
GETTIMESTAMP( Time_Var );
The_Date := DATE( Time_Var );
The_Time := TIME( Time_Var );
WRITELN( The_Date, The_Time ); {Writes: 1-FEB-1989
14:20:25.98 }
11.8 - NONSTANDARD_DATE_AND_TIME
These procedures write the date and the time to their
parameters. These procedures are Compaq Pascal extensions, and
have the forms:
DATE( str )
TIME( str )
The parameter 'str' must be of type PACKED ARRAY[1..11] OF CHAR.
After execution of the procedure, the 'str' contains either the
date or the time. If the day of the month is a 1-digit number,
the leading zero does not appear in the result; that is, a space
appears before the date string. The time is returned in 24-hour
format.
11.9 - DELETE_FILE
The DELETE_FILE procedure deletes one or more files.
Syntax:
DELETE_FILE( file_name [, error_return] )
The 'file-name' specification can contain an explicit device and
directory name, plus it must contain a file name, a file type or
extension, and a version number. If you omit either the
directory or device name, Compaq Pascal uses the directory you
are working in at the time of program execution. The
'error_return' parameter returns an error recovery code if
specified.
11.10 - ESTABLISH
The ESTABLISH procedure specifies a condition handler that
executes if your program generates operating-system events.
Syntax:
ESTABLISH( function-identifier )
The 'function-identifier' parameter must be the name of a
function that has the ASYNCHRONOUS attribute. The function
passed to ESTABLISH must have two formal array parameters.
11.11 - EXPO
The EXPO function returns the integer exponent of the
floating-point representation of its parameter.
Syntax:
EXPO( x )
The parameter 'x' can be of any real type.
11.12 - FIND_FIRST_BIT_CLEAR
The FIND_FIRST_BIT_CLEAR function locates the first bit in a
Boolean array whose value is 0 and returns an integer value that
specifies the index into the array.
Syntax:
FIND_FIRST_BIT_CLEAR( vector [[, start_index]] )
The 'vector' parameter is a variable of type PACKED ARRAY OF
BOOLEAN with an INTEGER index type. The optional 'start-index'
parameter must be an INTEGER expression that indexes the element
at the point at which the search starts. The 'starting index'
must be greater than or equal to the vector's lower bound, and
less than or equal to 1 plus the vector's upper bound;
otherwise, a range violation occurs. If omitted, the starting
index defaults to the vector's first element.
The FIND_FIRST_BIT_CLEAR function returns a value indexing the
first element containing the value 0. If no bit is 0, the
result is 1 plus the vector's upper bound. If the vector or the
indexed part of the vector has a size of 0, the result is
start-index.
11.13 - FIND_FIRST_BIT_SET
The FIND_FIRST_BIT_SET function locates the first bit in a
Boolean array whose value is 1 and returns an integer value that
specifies the index into the array.
Syntax:
FIND_FIRST_BIT_SET( vector [[, start_index]] )
The 'vector' parameter is a variable of type PACKED ARRAY OF
BOOLEAN with an INTEGER index type. The optional 'start-index'
parameter must be an expression of an integer type that indexes
the element at the point at which the search starts. The
'starting index' must be greater than or equal to the vector's
lower bound, and less than or equal to 1 plus the vector's upper
bound; otherwise, a range violation occurs. If omitted, the
starting index defaults to the vector's first element.
The FIND_FIRST_BIT_SET function returns an integer value
indexing the first element containing the value 1. If no bit is
1, the result is 1 plus the vector's upper bound. If the vector
or the indexed part of the vector has a size of 0, the result is
start-index.
11.14 - GETTIMESTAMP
The GETTIMESTAMP procedure initializes its parameter for use
with the DATE and TIME functions.
Syntax:
GETTIMESTAMP( t [[, str]] )
The parameter 't' is a variable of the TIMESTAMP type, which is
a predeclared record type. The TIMESTAMP data type is as
follows:
TIMESTAMP = PACKED RECORD
Datevalid, Timevalid : BOOLEAN;
Year : INTEGER;
Month : 1..12;
Day : 1..31;
Hour : 0..23;
Minute : 0..59;
Second : 0..59;
Hundredth : 0..99;
{64-bit OpenVMS binary time:}
BINARY_TIME : [QUAD] RECORD L1,L2 : INTEGER END;
DAY_OF_WEEK : 1..7; {1 is Monday, 7 is Sunday}
END;
The parameter 'str' is a string type that represents a date or
both a date and time. The following rules apply to the
specification of the 'str' parameter:
o If you do not specify the 'str', the GETTIMESTAMP procedure
initializes the variable to be the date and time at
execution of your program.
o If you specify an invalid date, the GETTIMESTAMP procedure
sets the date to be January 1, 1; if you specify an invalid
time, it sets the time to be midnight.
11.15 - HALT
The HALT procedure uses operating system resources to stop execution of your program unless you have written a condition handler (using the ESTABLISH procedure) that enables continued execution.
11.16 - IN_RANGE
The IN_RANGE function determines whether a value is in the
defined subrange.
Syntax:
IN_RANGE(expression,lower-expression,upper-expression)
This function returns TRUE if the contents of the variable is in
the range specified by the lower-expression and upper-expression
values.
11.17 - ODD
The ODD function returns a Boolean value that indicates if the
parameter is odd.
Syntax:
ODD( x )
The parameter 'x' must be of type INTEGER or UNSIGNED. The
function returns TRUE if the value of 'x' is odd and FALSE if
the value of 'x' is even.
11.18 - RANDOM
The RANDOM function returns a randomly computed real value in the range [0.0,1.0). RANDOM[[(expression)]] If present, the optional integer parameter is ignored.
11.19 - RENAME_FILE
The RENAME_FILE procedure renames a file.
Syntax:
RENAME_FILE( old-file-name, new-file-name [, error-return] )
The parameter 'old-file-name' specifies the names of one or more
files whose specifications are to be changed. The parameter
'new-file-name' provides the new file specification to be
applied. The 'error-return' parameter contains an error
recovery code if specified.
11.20 - REVERT
The REVERT procedure cancels a condition handler activated by the ESTABLISH procedure. This procedure does not have a parameter list.
11.21 - SEED
The SEED function has a single integer parameter that sets the random number generator seed for the RANDOM function. The function returns an integer that represents the previous seed value. SEED(expression) The parameter is of type integer.
11.22 - SYSCLOCK
The SYSCLOCK function returns an integer value for the number of
milliseconds of system time used by the current process. On
OpenVMS systems, the result is the same as that returned by the
CLOCK function.
Syntax:
SYSCLOCK
11.23 - UNDEFINED
The UNDEFINED function returns a Boolean value that specifies
whether the parameter contains a reserved operand.
Syntax:
UNDEFINED( x )
The parameter 'x' must be a variable of type REAL, SINGLE,
DOUBLE, or QUADRUPLE. The function returns TRUE if 'x' contains
a value that has been reserved by the system or machine
architecture. If 'x' does not contain a reserved value, the
function returns FALSE. If 'x' contains a reserved operand and
if you attempt to use 'x' in arithmetic computations, an error
occurs. 4 WALLCLOCK
On OpenVMS systems, the WALLCLOCK function returns an integer
value representing the number of seconds since the boot time for
the system.
Syntax:
WALLCLOCK
11.24 - ZERO
The ZERO function returns data, whose type depends on the context of the function call, that sets any variable (except a file variable) to its binary zero. If you attempt to use the ZERO function to initialize a file variable, an error occurs. Do not specify a parameter list when you call the ZERO function.
|
|
