 |
OpenVMS RTL Library (LIB$) Manual
LIB$CVT_TO_INTERNAL_TIME
The Convert External Time to Internal Time routine converts an external
time interval into an OpenVMS internal format delta time.
Format
LIB$CVT_TO_INTERNAL_TIME operation ,input-time ,resultant-time
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
operation
| OpenVMS usage: |
function_code |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The conversion to be performed. The operation argument
is the address of an unsigned longword specifying the operation. Valid
values for operation are the following:
| Operation |
Interpretation |
|
LIB$K_DELTA_WEEKS
|
Whole weeks in delta time
|
|
LIB$K_DELTA_DAYS
|
Whole days in delta time
|
|
LIB$K_DELTA_HOURS
|
Whole hours in delta time
|
|
LIB$K_DELTA_MINUTES
|
Whole minutes in delta time
|
|
LIB$K_DELTA_SECONDS
|
Whole seconds in delta time
|
input-time
| OpenVMS usage: |
varying_arg |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Delta time to be converted. The input-time argument is
the address of this input time. The value you supply for
input-time must be greater than 0.
resultant-time
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
The OpenVMS internal format delta time that results from the
conversion. The resultant-time argument is the address
of an unsigned quadword containing the result.
Description
LIB$CVT_TO_INTERNAL_TIME converts an external time interval, such as
three weeks, into an OpenVMS internal format delta time. The
operation argument specifies the conversion.
LIB$_CVT_TO_INTERNAL_TIME converts the value of
input-time into one of the internal format delta times
listed in the operation argument description.
LIB$_CVT_TO_INTERNAL_TIME then places the result into
resultant-time.
See the OpenVMS Programming Concepts Manual for a description of system date and time
operations as well as a detailed description of the format mnemonics
used in these routines.
Condition Values Returned
|
LIB$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVOPER
|
Invalid operation.
|
|
LIB$_IVTIME
|
Invalid time.
|
|
LIB$_WRONUMARG
|
Incorrect number of arguments.
|
LIB$CVT_VECTIM
The Convert 7-Word Vector to Internal Time routine converts a 7-word
vector into an OpenVMS internal format delta or absolute time.
Format
LIB$CVT_VECTIM input-time ,resultant-time
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
input-time
| OpenVMS usage: |
vector_word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference, array reference |
Time to be converted. The input-time argument is the
address of a 7-word structure containing this time. This vector
directly corresponds to a $NUMTIM timbuf structure. The
following diagram depicts the fields in this structure:
The input-time argument can represent an absolute or a
delta time. In order for input-time to represent a
delta time, the year since 0 and month of
year fields must equal zero. If those fields do not equal
zero, an absolute time is returned.
resultant-time
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
The OpenVMS internal format delta or absolute time that results from
the conversion. The resultant-time argument is the
address of an unsigned quadword containing the result.
Description
LIB$CVT_VECTIM converts a 7-word vector (in the format output by the
$NUMTIM system service) into an OpenVMS internal format delta or
absolute time. LIB$CVT_VECTIM then places the result into
resultant-time.
See the OpenVMS System Services Reference Manual: GETUTC--Z for more information about $NUMTIM.
Condition Values Returned
|
LIB$_NORMAL
|
Routine successfully completed.
|
|
LIB$_IVTIME
|
Invalid time.
|
|
LIB$_WRONUMARG
|
Incorrect number of arguments.
|
LIB$CVT_xTB
The Convert Numeric Text to Binary routines return a binary
representation of the ASCII text string representation of a decimal,
hexadecimal, or octal number.
Format
LIB$CVT_DTB byte-count ,numeric-string ,result
LIB$CVT_HTB byte-count ,numeric-string ,result
LIB$CVT_OTB byte-count ,numeric-string ,result
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
byte-count
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by value |
Byte count of the input ASCII text string. The
byte-count argument is a signed longword integer
containing the byte count of the input string.
numeric-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by reference |
ASCII text string representation of a decimal, hexadecimal, or octal
number that LIB$CVT_xTB converts to binary representation. The
numeric-string argument is the address of a character
string containing this input string to be converted.
The syntax of a valid ASCII text input string is as follows:
[ + | - ] <radix-characters>
LIB$CVT_xTB allows only an optional plus (+) or minus - sign followed
by a string of decimal, hexadecimal, or octal characters appropriate to
the routine being called.
result
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
write only |
| mechanism: |
by reference |
Binary representation of the input string. The result
argument is the address of a signed longword integer containing the
converted string.
Description
LIB$CVT_DTB converts the ASCII text string representation of a decimal
number into binary representation. LIB$CVT_HTB converts the ASCII text
string representation of a hexadecimal number into binary
representation. LIB$CVT_OTB converts the ASCII text string
representation of an octal number into binary representation.
Note
LIB$CVT_DTB, LIB$CVT_HTB, and LIB$CVT_OTB are intended to be called
primarily from BLISS and MACRO programs. Therefore, the routines expect
input scalar arguments to be passed by value and strings by reference.
|
Condition Values Returned
|
1
|
Routine successfully completed.
|
|
0
|
Nonradix character in the input string or a sign in any position other
than the first character. An overflow from 32 bits (unsigned) causes an
error.
|
LIB$CVT_xTB_64 (Alpha Only)
The Convert Numeric Text to Binary routines return a binary
representation of the ASCII text string representation of a decimal,
hexadecimal, or octal number.
Format
LIB$CVT_DTB_64 byte-count ,numeric-string ,result
LIB$CVT_HTB_64 byte-count ,numeric-string ,result
LIB$CVT_OTB_64 byte-count ,numeric-string ,result
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
byte-count
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by value |
Byte count of the input ASCII text string. The
byte-count argument is a signed longword integer
containing the byte count of the input string.
numeric-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by reference |
ASCII text string representation of a decimal, hexadecimal, or octal
number that LIB$CVT_xTB_64 converts to binary representation. The
numeric-string argument is the address of a character
string containing this input string to be converted.
The syntax of a valid ASCII text input string is as follows:
[ + | - ] <radix-characters>
LIB$CVT_xTB_64 allows only an optional plus (+) or minus (-) sign
followed by a string of decimal, hexadecimal, or octal characters
appropriate to the routine being called.
result
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
write only |
| mechanism: |
by reference |
Binary representation of the input string. The result
argument is the address of a signed quadword integer containing the
converted string.
Description
LIB$CVT_DTB_64 converts the ASCII text string representation of a
decimal number into binary representation. LIB$CVT_HTB_64 converts the
ASCII text string representation of a hexadecimal number into binary
representation. LIB$CVT_OTB_64 converts the ASCII text string
representation of an octal number into binary representation.
Note
LIB$CVT_DTB_64, LIB$CVT_HTB_64, and LIB$CVT_OTB_64 are intended to be
called primarily from BLISS and MACRO programs. Therefore, the routines
expect input scalar arguments to be passed by value and strings by
reference.
|
Condition Values Returned
|
1
|
Routine successfully completed.
|
|
0
|
Nonradix character in the input string or a sign in any position other
than the first character. An overflow from 64 bits (unsigned) causes an
error.
|
LIB$DATE_TIME
The Date and Time Returned as a String routine returns the OpenVMS
system date and time in the semantics of a user-provided string.
Format
LIB$DATE_TIME date-time-string
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
date-time-string
| OpenVMS usage: |
time_name |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Destination string into which LIB$DATE_TIME writes the system date and
time. The date-time-string argument is the address of
a descriptor pointing to the destination string. This string is 23
characters long; its format is as follows:
See the OpenVMS Programming Concepts Manual for a description of system date and time
operations as well as a detailed description of the format mnemonics
used in these routines.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_STRTRU
|
Success, but destination string was truncated.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. Your program has exceeded the image quota
for virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
Example
|
10 !+
! This BASIC program demonstrates the use of LIB$DATE_TIME.
!-
CALL LIB$DATE_TIME(DSTSTR$)
PRINT DSTSTR$
99 END
|
This BASIC program uses LIB$DATE_TIME to display the current system
date and time. The output generated by one run of this program follows:
LIB$DAY
The Day Number Returned as a Longword Integer routine returns the
number of days since the system zero date of November 17, 1858, or the
number of days from November 17, 1858, to a user-supplied date.
Format
LIB$DAY number-of-days [,user-time] [,day-time]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
number-of-days
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
write only |
| mechanism: |
by reference |
Number of days since the system zero date. The
number-of-days argument is the address of a signed
longword integer containing the day number.
user-time
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User-supplied time, in 100-nanosecond units. The
user-time argument is the address of a signed quadword
integer containing the user time. A positive value indicates an
absolute time, while a negative value indicates a delta time. This is
an optional argument. If user-time is omitted, the
default is the current system time. This quadword time value is
obtained by calling the $BINTIM system service.
If time is passed as zero by value, the numeric value for the current
day is returned. If time is passed as a zero by reference, the number
returned represents the day of November 17, 1858, rather than the
current day.
day-time
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
write only |
| mechanism: |
by reference |
Number of 10-millisecond units since midnight of the
user-time argument. The day-time
argument is the address of a signed longword integer into which LIB$DAY
writes this number of units.
Description
LIB$DAY returns the number of days since the system zero date of
November 17, 1858. Optionally, the caller can supply a time in system
time format to be used instead of the current system time. In this
case, LIB$DAY returns the number of days from November 17, 1858, to the
user-supplied date.
The number of 10-millisecond units since midnight is an optional return
argument.
Note
If the caller supplies a quadword time, it is not verified. If it is
negative (bit 63 on), the number-of-days value
returned is negative.
|
The Run-Time Library provides the date/time utility routines for
languages that do not have built-in time and date functions and for
particular applications that require the time or date in a different
format from the one that the language supplies. In general, it is
simpler to call the Run-Time Library routines for the system date and
time than to call a system service.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_INTOVF
|
The optional argument
user-time is present and represents a date and time
well beyond the year 9999.
|
Example
|
PROGRAM DAY(INPUT, OUTPUT);
{+}
{ This is a VAX Pascal example program showing
{ the use of LIB$DAY.
{-}
VAR
DAYNUMBER : INTEGER;
routine LIB$DAY(VAR DAYNUM : INTEGER);
EXTERN;
BEGIN
LIB$DAY(DAYNUMBER);
WRITELN('The day number is ', DAYNUMBER);
END.
|
This Pascal program retrieves and prints the day number. A sample of
the output generated by this program is as follows.
LIB$DAY_OF_WEEK
The Show Numeric Day of Week routine returns the numeric day of the
week for an input time value. If 0 is the input time value, the current
day of the week is returned. The days are numbered 1 through 7, with
Monday as day 1 and Sunday as day 7.
Format
LIB$DAY_OF_WEEK [user-time,] day-number
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
user-time
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Time to be translated to a day of the week, or zero. The optional
user-time argument is the address of an unsigned
quadword containing the value of time. Time must be supplied as an
absolute system time. To obtain this time value in proper quadword
format, call the $BINTIM system service.
If time is passed as zero by value, the numeric value for the current
day is returned. If time is passed as a zero by reference, the number
returned represents the day of November 17, 1858. If the
user-time argument is omitted, it is equivalent to
passing a zero by value.
day-number
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Numeric day of week. The day-number argument is the
address of a longword into which LIB$DAY_OF_WEEK writes the integer
value representing the day of the week.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
Example
|
PROGRAM DAYOFWEEK(INPUT, OUTPUT);
{+}
{ This is an example showing
{ the use of LIB$DAY_OF_WEEK.
{-}
VAR
OUTDAT : INTEGER;
routine LIB$DAY_OF_WEEK(TIM : INTEGER; %REF OUTDA : INTEGER); EXTERN;
BEGIN
LIB$DAY_OF_WEEK(%IMMED 0, OUTDAT);
WRITELN(OUTDAT);
END.
|
This Pascal program shows the use of LIB$DAY_OF_WEEK. This example was
tested on a Monday, and the output generated was 1.
|
