 |
HP OpenVMS RTL Library (LIB$) Manual
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:
- Scale is applied when indicated in the descriptor (descriptor
CLASS_SD only), and scaling is defined for the data type.
- No language-specific semantics are applied, such as BASIC scale for
DSC$K_DTYPE_D.
- Some conversions must use intermediate values to arrive at the
destination requested. Although some loss of speed is inevitable,
intermediate values will not cause a loss of precision.
- Results are always rounded instead of truncated, except for the
case described below. Note that loss of precision or range may be
inherent in the destination data type or in the NBDS destination size.
No errors are reported if there is a loss of precision or range as a
result of destination data type.
- When the destination is an NBDS and has fixed-string semantics,
then if the source does not fill the destination, the destination is
padded with blanks.
- When the source and destination are both NBDS and no scaling is
requested, then a straight copy is done without translation or
conversion, and truncation is possible. If scaling is requested, then a
conversion takes place as defined in Table lib-2.
- When the source is an NBDS and the destination is non-NBDS, if
there is an invalid character in the source or the value is outside the
range that can be represented by the destination, then LIB$_INVNBDS is
returned.
- Attempts to convert a negative value to an unsigned data type cause
the LIB$_INVCVT error to be returned.
- If the destination is an NBDS of descriptor CLASS_D, then a new
string of appropriate size is allocated for it, if necessary.
- Invalid conversions resulting in an error produce an unpredictable
result.
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
-
digits: Digits 0 through 9, and a decimal point
only if source descriptor specifies the value of the SCALE field as less
than 0.
-
w: Width of destination in bytes.
-
s: Sign. For positive numbers, the sign is implied.
-
min: Minimum of two values.
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.
|
|
