Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | 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.

### 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.

> 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.

> This Pascal program shows the use of LIB$DAY_OF_WEEK. This example was tested on a Monday, and the output generated was 1.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_009.HTML