OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

Contents

Index

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.

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

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:

dd-mmm-yyyy hh:mm:ss.hh

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:

26-JUL-2000 13:41:22.67

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.

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.
The day number is 46738

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.

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.

Contents

Index

privacy and legal statement

5932PRO_009.HTML

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	function_code
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	varying_arg
type:	longword (signed)
access:	read only
mechanism:	by reference

LIB$_NORMAL	Routine successfully completed.
LIB$_INVOPER	Invalid operation.
LIB$_IVTIME	Invalid time.
LIB$_WRONUMARG	Incorrect number of arguments.

OpenVMS usage:	vector_word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference, array reference

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by value

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by reference

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.

OpenVMS usage:	quadword_signed
type:	quadword integer (signed)
access:	write only
mechanism:	by reference

OpenVMS usage:	time_name
type:	character string
access:	write only
mechanism:	by descriptor

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.

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.

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by reference