hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


Previous Contents Index


LIB$CVTF_TO_INTERNAL_TIME

The Convert External Time to Internal Time (F-Floating-Point Value) routine converts an external time interval into an OpenVMS internal format F-floating delta time.

Format

LIB$CVTF_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_F Fractional weeks
LIB$K_DELTA_DAYS_F Fractional days
LIB$K_DELTA_HOURS_F Fractional hours
LIB$K_DELTA_MINUTES_F Fractional minutes
LIB$K_DELTA_SECONDS_F Fractional seconds

input-time


OpenVMS usage: varying_arg
type: F_floating
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$CVTF_TO_INTERNAL_TIME converts an external time interval, such as 3.5 weeks, into an OpenVMS internal format F-floating delta time. The operation argument specifies the conversion. LIB$CVTF_TO_INTERNAL_TIME converts the value of input-time into one of the internal format delta times listed in the operation argument description. LIB$CVTF_TO_INTERNAL_TIME then places the result into resultant-time.

Condition Values Returned

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

LIB$CVTS_TO_INTERNAL_TIME (Alpha and I64 Only)

The Convert External Time to Internal Time (IEEE S-Floating-Point Value) routine converts an external time interval into an OpenVMS internal format IEEE S-floating delta time.

Format

LIB$CVTS_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_F Fractional weeks
LIB$K_DELTA_DAYS_F Fractional days
LIB$K_DELTA_HOURS_F Fractional hours
LIB$K_DELTA_MINUTES_F Fractional minutes
LIB$K_DELTA_SECONDS_F Fractional seconds

input-time


OpenVMS usage: varying_arg
type: IEEE S_floating
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$CVTS_TO_INTERNAL_TIME converts an external time interval, such as 3.5 weeks, into an OpenVMS internal format IEEE S-floating delta time. The operation argument specifies the conversion. LIB$CVTS_TO_INTERNAL_TIME converts the value of input-time into one of the internal format delta times listed in the operation argument description. LIB$CVTS_TO_INTERNAL_TIME then places the result into resultant-time.

Condition Values Returned

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

LIB$CVT_DX_DX

The General Data Type Conversion routine converts OpenVMS standard atomic or string data described by a source descriptor to OpenVMS standard atomic or string data described by a destination descriptor. This conversion is supported over a subset of the OpenVMS standard data types.

Format

LIB$CVT_DX_DX source-item ,destination-item [,word-integer-dest-length]


RETURNS


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


Arguments

source-item


OpenVMS usage: unspecified
type: unspecified
access: read only
mechanism: by descriptor

Source item to be converted by LIB$CVT_DX_DX. The source-item argument is the address of a descriptor pointing to the source item to be converted. The type of the item to be converted is contained in the descriptor.

The combination of source descriptor class and data type is restricted as described in Table lib-1 and Table lib-2.

destination-item


OpenVMS usage: unspecified
type: unspecified
access: write only
mechanism: by descriptor

Destination of the conversion. The destination-item argument is the address of a descriptor pointing to the destination item. The destination descriptor specifies the data type to which the source item is converted.

The combination of destination descriptor class and data type is restricted as described in Table lib-1 and Table lib-2.

word-integer-dest-length


OpenVMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference

Length in bytes of the destination item (when that item is a string) that has been converted by LIB$CVT_DX_DX, not including any space filling. The word-integer-dest-length argument contains the address of an unsigned word containing this length.

If the destination string is truncated, the returned length reflects the truncation. This word can be used by the calling program to determine if truncation has occurred or to extract the exact length of the string when the string contains space filling.


Description

LIB$CVT_DX_DX is a universal conversion utility routine. Table lib-1 shows the complete matrix of data type and descriptor class combinations (as specified in the fields of the descriptor) supported by LIB$CVT_DX_DX.

Conversion is defined over three sets of data types: atomic, string, and numeric byte data strings. Although some of the functions of this routine may be found in other Run-Time Library routines, LIB$CVT_DX_DX packages the conversion functions with a general interface. Because of this general interface, the calling program does not have to specify what conversion should be done for which data type.

Refer to LIB$CVT_xTB if you want to convert the ASCII text string representation of a decimal, hexadecimal, or octal number into a binary representation.

The description of this routine has been divided into the following parts:

For more information about numeric byte data strings, see the section called Use of Numeric Byte Data Strings (NBDS). Although the set of data types in NBDS is actually a subset of the atomic and string data types, the three sets are mutually exclusive in this routine. For more information on the OpenVMS atomic and string data types and the argument descriptor classes supported by this routine, see the HP OpenVMS Calling Standard manual.

Table lib-1 OpenVMS Descriptor Class and Data Type Combinations Accepted by LIB$CVT_DX_DX
  Descriptor Class
DSC$K_DTYPE_yyy A D NCA S SD VS
B       Non-NBDS Non-NBDS  
BU NBDS   NBDS Non-NBDS    
D       Non-NBDS Non-NBDS  
F       Non-NBDS Non-NBDS  
FS       Non-NBDS Non-NBDS  
FT       Non-NBDS Non-NBDS  
G       Non-NBDS Non-NBDS  
H       Non-NBDS Non-NBDS  
L       Non-NBDS Non-NBDS  
LU       Non-NBDS    
NL       Non-NBDS Non-NBDS  
NLO       Non-NBDS Non-NBDS  
NR       Non-NBDS Non-NBDS  
NRO       Non-NBDS Non-NBDS  
NU       Non-NBDS Non-NBDS  
NZ       Non-NBDS Non-NBDS  
P       Non-NBDS Non-NBDS  
Q       Non-NBDS Non-NBDS  
T NBDS NBDS NBDS NBDS NBDS  
VT           NBDS
W       Non-NBDS Non-NBDS  
WU       Non-NBDS    


Invalid combinations are blank. Any source data can be converted into any other destination data as long as they are both represented by one of the valid combinations.


Note: LIB $CVT _DX _DX treats an array, described by a CLASS _A or CLASS _NCA descriptor, as a character string. NBDS must have the format defined in Table lib-2 .


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:

LIB$_INVDTYDSC
LIB$_INVCLADSC
LIB$_INVCLADTY
LIB$_INVNBDS

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.


Previous Next Contents Index