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.
1 – 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.
2 – 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.
3 – 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.
4 – 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.
5 – 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 }
6 – NONSTANDARD_DATE_AND_TIME
These procedures write the date and the time to their
parameters. These procedures are VSI 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.
7 – 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, VSI 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.
8 – 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.
9 – 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.
10 – 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 – 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.
12 – 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.
13 – 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.
14 – 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.
15 – 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.
16 – 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.
17 – 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.
18 – REVERT
The REVERT procedure cancels a condition handler activated by the ESTABLISH procedure. This procedure does not have a parameter list.
19 – 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.
20 – 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
21 – 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.
22 – 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
23 – 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.