HELPLIB.HLB  —  RTL Routines, CVT$

1  –  CVT$CONVERT_FLOAT

    The Convert Floating-Point Data Type routine provides a
    simplified options-interface for converting a floating-point
    data type to another supported floating-point data type.

    Format

      CVT$CONVERT_FLOAT  input_value, input_type_code, output_value,

                         output_type_code, options

1.1  –  Returns

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

1.2  –  Arguments

 input_value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       read only
    mechanism:    by reference

    The address of a data area containing a floating-point number
    that is to be converted. The input_value argument may contain
    floating-point data in F_Floating, D_Floating, G_Floating, H_
    Floating, IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, IBM_
    Long_Floating, IBM_Short_Floating, or CRAY_Floating format. The
    value of the input_type_code argument determines the format and
    size of the input_value argument.

 input_type_code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    The value of a longword bit mask specifying the type of floating-
    point data being passed in the input_value argument. Valid type
    codes are:

                                                          Size in
    input_type_code          Format                       Bytes

    CVT$K_VAX_F              F_Floating                   4
    CVT$K_VAX_D              D_Floating                   8
    CVT$K_VAX_G              G_Floating                   8
    CVT$K_VAX_H              H_Floating                   16
    CVT$K_IEEE_S             IEEE_S_Floating              4
    CVT$K_IEEE_T             IEEE_T_Floating              8
    CVT$K_IEEE_X             IEEE_X_Floating              16
    CVT$K_IBM_LONG           IBM_Long_Floating            8
    CVT$K_IBM_SHORT          IBM_Short_Floating           4
    CVT$K_CRAY               CRAY_Floating                8

    Declarations for the input_type_code argument are in the $CVTDEF
    module found in the system symbol libraries.

 output_value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    The address of a data area that receives the converted floating-
    point number. The output_value argument can contain floating-
    point data in F_Floating, D_Floating, G_Floating, H_Floating,
    IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, IBM_Long_
    Floating, IBM_Short_Floating, or CRAY_Floating format. The value
    of the output_type_code argument determines the size and format
    of the data placed into the output_value argument.

 output_type_code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    The value of a longword bit mask specifying the type of floating-
    point data that the input_value argument will be converted into
    and returned in the output_value argument. Valid type codes are:

                                                          Size in
    output_type_code         Format                       Bytes

    CVT$K_VAX_F              F_Floating                   4
    CVT$K_VAX_D              D_Floating                   8
    CVT$K_VAX_G              G_Floating                   8
    CVT$K_VAX_H              H_Floating                   16
    CVT$K_IEEE_S             IEEE_S_Floating              4
    CVT$K_IEEE_T             IEEE_T_Floating              8
    CVT$K_IEEE_X             IEEE_X_Floating              16
    CVT$K_IBM_LONG           IBM_Long_Floating            8
    CVT$K_IBM_SHORT          IBM_Short_Floating           4
    CVT$K_CRAY               CRAY_Floating                8

    Declarations for the output_type_code argument are in the $CVTDEF
    module found in the system symbol libraries.

 options

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    Conversion option specifier. The options argument is the address
    of a longword bit mask in which each option bit set causes the
    corresponding option to be used during the conversion.

    The following options can be specified using the options
    argument:

    Option                 Description

    CVT$M_ROUND_TO_        The default rounding option for
    NEAREST                conversions to IEEE data types. This
                           IEEE Std. 754 rounding mode results in
                           the representable output value nearest to
                           the infinitely precise result. If the two
                           nearest representable values are equally
                           near, the one whose least significant bit
                           is 0 is the result.
    CVT$M_VAX_ROUNDING     The default rounding option for
                           conversions to non-IEEE data types.
                           Performs "traditional" style rounding.
                           This mode results in the representable
                           output value nearest to the infinitely
                           precise result. If the two nearest
                           representable values are equally near,
                           the output value is the closest to either
                           positive infinity or negative infinity,
                           depending on the sign of the input value.
    CVT$M_TRUNCATE         Round the output value toward zero
                           (truncate).
    CVT$M_ROUND_TO_POS     Round the output value toward positive
                           infinity.
    CVT$M_ROUND_TO_NEG     Round the output value toward negative
                           infinity.
    CVT$M_BIG_ENDIAN       Interprets IEEE data types as Big Endian.
    CVT$M_ERR_UNDERFLOW    Report underflow conditions as errors.

    Declarations for the options argument are in the $CVTDEF module
    found in the system symbol libraries.

2  –  CVT$FTOF

    The Convert Floating-Point Data Type routine converts floating-
    point data types to other supported floating-point data types and
    allows additional control over the converted results.

    Format

      status = CVT$FTOF  input_value, input_type_code, output_value,

                         output_type_code, options

2.1  –  Returns

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

    The status return value is an unsigned longword bit mask
    containing the condition codes raised by the function. CVT$FTOF
    returns CVT$K_NORMAL; otherwise, it sets one or more recoverable
    and unrecoverable conditions.

    Return status values are in the $CVTDEF module in the system
    symbol libraries.

2.2  –  Arguments

 input_value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       read only
    mechanism:    by reference

    The address of a data area containing a floating-point number to
    be converted. The number can be floating-point data in one of the
    following formats:

    F_Floating         Big_Endian_IEEE_S_Floating
    D_Floating         Big_Endian_IEEE_T_Floating
    G_Floating         Big_Endian_IEEE_X_Floating
    H_Floating         IBM_Long_Floating
    IEEE_S_Floating    IBM_Short_Floating
    IEEE_T_Floating    CRAY_Floating_Single
    IEEE_X_Floating

    The value of the input_type_code argument determines the format
    and size of the input_value argument.

 input_type_code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    The value of a longword bit mask specifying the type of floating-
    point data being passed in the input_value argument. Valid type
    codes are:

                                                          Size in
    Input_type_code          Format                       Bytes

    CVT$K_VAX_F              F_Floating                   4
    CVT$K_VAX_D              D_Floating                   8
    CVT$K_VAX_G              G_Floating                   8
    CVT$K_VAX_H              H_Floating                   16
    CVT$K_IEEE_S             IEEE_S_Floating              4
    CVT$K_IEEE_T             IEEE_T_Floating              8
    CVT$K_IEEE_X             IEEE_X_Floating              16
    CVT$K_BIG_ENDIAN_IEEE_S  Big_Endian_IEEE_S_Floating   4
    CVT$K_BIG_ENDIAN_IEEE_T  Big_Endian_IEEE_T_Floating   8
    CVT$K_BIG_ENDIAN_IEEE_X  Big_Endian_IEEE_X_Floating   16
    CVT$K_IBM_LONG           IBM_Long_Floating            8
    CVT$K_IBM_SHORT          IBM_Short_Floating           4
    CVT$K_CRAY_SINGLE        CRAY_Floating                8

    Declarations for the input_type_code argument are in the $CVTDEF
    module found in the system symbol libraries.

 output_value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    The address of a data area that receives the converted floating-
    point number. The number can be floating-point data in F_
    Floating, D_Floating, G_Floating, H_Floating, IEEE_S_Floating,
    IEEE_T_Floating, IEEE_X_Floating, Big_Endian_IEEE_S_Floating,
    Big_Endian_IEEE_T_Floating, Big_Endian_IEEE_X_Floating, IBM_Long_
    Floating, IBM_Short_Floating, or CRAY_Floating_Single format. The
    value of the output_type_code argument determines the size and
    format of the converted floating-point number.

 output_type_code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    The value of a longword bit mask specifying the type of floating-
    point data that the input_value argument will be converted into
    and returned in the output_value argument. Valid type codes are:

                                                          Size in
    Output_type_code         Format                       Bytes

    CVT$K_VAX_F              F_Floating                   4
    CVT$K_VAX_D              D_Floating                   8
    CVT$K_VAX_G              G_Floating                   8
    CVT$K_VAX_H              H_Floating                   16
    CVT$K_IEEE_S             IEEE_S_Floating              4
    CVT$K_IEEE_T             IEEE_T_Floating              8
    CVT$K_IEEE_X             IEEE_X_Floating              16
    CVT$K_BIG_ENDIAN_IEEE_S  Big_Endian_IEEE_S_Floating   4
    CVT$K_BIG_ENDIAN_IEEE_T  Big_Endian_IEEE_T_Floating   8
    CVT$K_BIG_ENDIAN_IEEE_X  Big_Endian_IEEE_X_Floating   16
    CVT$K_IBM_LONG           IBM_Long_Floating            8
    CVT$K_IBM_SHORT          IBM_Short_Floating           4
    CVT$K_CRAY_SINGLE        CRAY_Floating                8

    Declarations for the output_type_code argument are in the $CVTDEF
    module found in the system symbol libraries.

 options

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    Conversion option specifier. The options argument is the address
    of a longword bit mask in which each option bit set causes the
    corresponding option to be used during the conversion. Provide
    a zero (0) value to the options argument to select default
    behavior or choose one or more options (status condition option,
    rounding options, "FORCE" options, CRAY and IBM options) from
    the following tables. Specify only the options that apply to your
    conversion. A conflicting or incompatible options argument is
    reported as an error (CVT$M_INVALID_OPTION).

    Applicable
    ConversioOption                Description

                              Status Condition Option

    All      CVT$M_REPORT_ALL      Report all applicable status
                                   conditions as the default. The
                                   reporting of recoverable status
                                   conditions is disabled by default
                                   when this option is not used.

                                 Rounding Options

    All      CVT$M_ROUND_TO_       The default rounding option for
             NEAREST               conversions to IEEE data types.
                                   This IEEE Std. 754 rounding mode
                                   results in the representable
                                   output value nearest to the
                                   infinitely precise result. If the
                                   two nearest representable values
                                   are equally near, the one whose
                                   least significant bit is 0 is the
                                   result.
    All      CVT$M_BIASED_         The default rounding option for
             ROUNDING              conversions to non-IEEE data
                                   types. Performs "traditional"
                                   style rounding. This mode results
                                   in the representable output
                                   value nearest to the infinitely
                                   precise result. If the two nearest
                                   representable values are equally
                                   near, the output value is the
                                   closest to either positive
                                   infinity or negative infinity
                                   depending on the sign of the input
                                   value.
    All      CVT$M_ROUND_TO_ZERO   Round the output value toward zero
                                   (truncate).
    All      CVT$M_ROUND_TO_POS    Round the output value toward
                                   positive infinity.
    All      CVT$M_ROUND_TO_NEG    Round the output value toward
                                   negative infinity.

                                  "FORCE" Options

    All      CVT$M_FORCE_ALL_      Apply all applicable "FORCE"
             SPECIAL_VALUES        options for the current
                                   conversion.
    IEEE     CVT$M_FORCE_DENORM_   Force a denormalized IEEE output
             TO_ZERO               value to zero.
    IEEE     CVT$M_FORCE_INF_TO_   Force a positive IEEE infinite
             MAX_FLOAT             output value to +max_float and
                                   force a negative IEEE infinite
                                   output value to -max_float.
    IEEE     CVT$M_FORCE_          Force an invalid IEEE NaN (not a
    or VAX   INVALID_TO_ZERO       number) output value or a VAX ROP
                                   (reserved operand) output value to
                                   zero.

                          CRAY Format Conversion Options

    CRAY     CVT$M_ALLOW_OVRFLW_   Allow an input/output exponent
             RANGE_VALUES          value > 60000 (8).
    CRAY     CVT$M_ALLOW_UDRFLW_   Allow an input/output exponent
             RANGE_VALUES          value < 20000 (8).

                       IBM Format Conversion Option

    IBM      CVT$M_ALLOW_          Allow unnormalized input
             UNNORMALIZED_VALUES   arguments. Allow an unnormalized
                                   output value for a small value
                                   that would normalize to zero.

    The maximum representable floating-point values (max_float) for
    the IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, Big_
    Endian_IEEE_S_Floating, Big_Endian_IEEE_T_Floating, and Big_
    Endian_IEEE_X_Floating formats are:

    Data
    Type Value for: max_float

    S    Decimal: 3.402823e38
    T    Decimal: 1.797693134862316e308
    X    Decimal: 1.189731495357231765085759326628007016196477e4932

    Declarations for the options argument are in the $CVTDEF module
    found in the system symbol libraries.
Close Help