 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$CVT_FROM_INTERNAL_TIME
The Convert Internal Time to External Time routine converts an internal
OpenVMS system time (either absolute or delta) into an external time.
Format
LIB$CVT_FROM_INTERNAL_TIME operation ,resultant-time [,input-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 containing the operation. The
following table shows valid values for operation:
| Operation |
Type |
Return Range |
|
LIB$K_MONTH_OF_YEAR
|
Absolute
|
1 to 12
|
|
LIB$K_DAY_OF_YEAR
|
Absolute
|
1 to 366
|
|
LIB$K_HOUR_OF_YEAR
|
Absolute
|
1 to 8784
|
|
LIB$K_MINUTE_OF_YEAR
|
Absolute
|
1 to 527,040
|
|
LIB$K_SECOND_OF_YEAR
|
Absolute
|
1 to 31,622,400
|
|
LIB$K_DAY_OF_MONTH
|
Absolute
|
1 to 31
|
|
LIB$K_HOUR_OF_MONTH
|
Absolute
|
1 to 744
|
|
LIB$K_MINUTE_OF_MONTH
|
Absolute
|
1 to 44,640
|
|
LIB$K_SECOND_OF_MONTH
|
Absolute
|
1 to 2,678,400
|
|
LIB$K_DAY_OF_WEEK
|
Absolute
1
|
1 to 7
|
|
LIB$K_HOUR_OF_WEEK
|
Absolute
2
|
1 to 168
|
|
LIB$K_MINUTE_OF_WEEK
|
Absolute
3
|
1 to 10,080
|
|
LIB$K_SECOND_OF_WEEK
|
Absolute
4
|
1 to 604,800
|
|
LIB$K_HOUR_OF_DAY
|
Absolute
|
0 to 23
|
|
LIB$K_MINUTE_OF_DAY
|
Absolute
|
0 to 1439
|
|
LIB$K_SECOND_OF_DAY
|
Absolute
|
0 to 86,399
|
|
LIB$K_MINUTE_OF_HOUR
|
Absolute
|
0 to 59
|
|
LIB$K_SECOND_OF_HOUR
|
Absolute
|
0 to 3599
|
|
LIB$K_SECOND_OF_MINUTE
|
Absolute
|
0 to 59
|
|
LIB$K_JULIAN_DATE
|
Absolute
5
|
Julian date
|
|
LIB$K_DELTA_WEEKS
|
Delta
6
|
|
|
LIB$K_DELTA_DAYS
|
Delta
7
|
|
|
LIB$K_DELTA_HOURS
|
Delta
8
|
|
|
LIB$K_DELTA_MINUTES
|
Delta
9
|
|
|
LIB$K_DELTA_SECONDS
|
Delta
10
|
|
1Day 1 is Monday.
2Hours since midnight on previous Monday.
3Minutes since midnight on previous Monday.
4Seconds since midnight on previous Monday.
5Number of days since system zero time (17--Nov--1858).
6Whole weeks.
7Whole days.
8Whole hours.
9Whole minutes.
10Whole seconds.
resultant-time
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
The external time that results from the conversion. The
resultant-time argument is the address of an unsigned
longword containing the result.
input-time
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Optional absolute or delta time to be converted. The
input-time argument is the address of an unsigned
quadword containing the time. If you do not supply a value for
input-time, the current system time is used.
Description
LIB$CVT_FROM_INTERNAL_TIME converts an internal OpenVMS system time
(either absolute or delta) into an external time. The
operation argument specifies the conversion.
LIB$CVT_FROM_INTERNAL_TIME converts the value of
input-time (or the current system time if
input-time is not supplied) into one of the external
formats listed in the operation argument description.
LIB$CVT_FROM_INTERNAL_TIME then places the result into
resultant-time.
See the HP 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$_ABSTIMREQ
|
Absolute time required but delta time supplied.
|
|
LIB$_DELTIMREQ
|
Delta time required but absolute time supplied.
|
|
LIB$_INVOPER
|
Invalid operation.
|
|
LIB$_IVTIME
|
Invalid time.
|
|
LIB$_WRONUMARG
|
Incorrect number of arguments.
|
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 HP 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 HP 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 and I64 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 HP 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:
|
