[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual


Previous Contents Index

Guidelines for Using LIB$CVT_DX_DX

The data type and descriptor class of the source and destination arguments determine how LIB$CVT_DX_DX performs the conversion, according to the following rules:

Use of Numeric Byte Data Strings (NBDS)

For simplicity, and to define a generic numeric string that LIB$CVT_DX_DX understands to be a numeric string, the set Numeric Byte Data String (NBDS) is defined to be the set of NBDS descriptors shown in Table lib-1.

The combination of data type and descriptor class determines whether an argument is an NBDS. For example, LIB$CVT_DX_DX treats the combination DSC$K_DTYPE_B/DSC$K_CLASS_S (unsigned byte scalar) as an atomic data type. However, the routine considers DSC$K_DTYPE_BU/DSC$K_CLASS_NCA (noncontiguous array of unsigned bytes) to be an NBDS.

A destination NBDS is always left-justified.

If a destination NBDS requires more than 50 digits for its format (including the sign, if any), then it is expressed in exponential format.

For a conversion of NBDS to NBDS, this format is used if scaling is requested. Otherwise, a straight copy is done. The format of a source NBDS is the same as the format defined for the input argument inp in OTS$_CVT_T_z, with bits 0, 2, and 4 set in the flags argument. That is, blanks are ignored, underflow causes an error, and tabs are ignored.

Table lib-2 defines the format of a destination NBDS.

Table lib-2 LIB$CVT_DX_DX Destination NBDS Formats
Source Data Type Destination NBDS Format
Byte integer (signed) sdigits
Byte (unsigned) digits
Word integer (signed) sdigits
Word (unsigned) digits
Longword integer (signed) sdigits
Longword (unsigned) digits
Quadword integer (signed) sdigits
D_floating s0.min(16,w-7)E+ or - nn
F_floating s0.min( 7,w-7)E+ or - nn
G_floating s0.min(15,w-8)E+ or - nnn
H_floating s0.min(33,w-9)E+ or - nnnn
FS_floating (IEEE) s0.min(7,w-7)E+ or - nn
FT_floating (IEEE) s0.min(15,w-8)E+ or - nnn
NBDS s0.min(33,w-9)E+ or - nnnn
Decimal string sdigits (as defined by VAX architecture)


Key to Destination NBDS Formats

The A and NCA array descriptor classes are supported with the following restrictions:
An array is written with the semantics of a fixed string.
DIMCT = 1 Only one-dimensional arrays are recognized.
LENGTH = 1 The length of each array element must be a byte.
ARSIZE <= 65,535 The total size of the array must be less than 65,535 bytes. If ARSIZE = 0, the array has a length of zero.
S1 = 1 The stride of an array passed by a noncontiguous array descriptor must be 1. That is, even if the class of the array's descriptor is noncontiguous array (NCA), the array itself must be contiguous.

For more information about the semantics of writing output strings, see the OpenVMS RTL String Manipulation (STR$) Manual.

If the calling program passes a descriptor to LIB$CVT_DX_DX that does not comply with Table lib-1, one of the following error messages is returned:


Condition Values Returned

SS$_NORMAL Routine successfully completed.
LIB$_DECOVF Packed decimal overflow error. Severe error.
LIB$_FLTOVF Floating overflow error. Severe error.
LIB$_FLTUND Floating underflow error. Severe error.
LIB$_INTOVF Integer overflow error. Severe error.
LIB$_INVCLADSC Invalid class in descriptor. This class of descriptor is not supported. Severe error.
LIB$_INVCLADTY Invalid class and data type in descriptor. This class and data type combination is not supported. Severe error.
LIB$_INVCVT If the source value is negative and the destination data type is unsigned, this error is returned.
LIB$_INVDTYDSC Invalid data type in descriptor. This data type is not supported. Severe error.
LIB$_INVNBDS Invalid NBDS. There is an invalid character in the input, or the value is outside the range that can be represented by the destination, or the NMDS descriptor is invalid. This error is also signaled when the array size of an NBDS is larger than 65,535 bytes or the array is multi-dimensional.
LIB$_OUTSTRTRU Output string truncated. This is returned only when NBDS is both source and destination and no scaling is requested. The result is truncated.
LIB$_ROPRAND Reserved operand error. Severe error.

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 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 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 for more information about $NUMTIM.


Condition Values Returned

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


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5932PRO_008.HTML