Document revision date: 30 March 2001

## OpenVMS RTL General Purpose (OTS$) Manual

Previous | Contents | Index

## OTS$CVT_L_TZ

> The Convert Integer to Hexadecimal Text routine converts an unsigned integer to a hexadecimal ASCII text string. OTS$CVT_L_TZ supports Fortran Zw and Zw.m output conversion formats.

### Format

> OTS$CVT_L_TZ varying-input-value ,fixed-length-resultant-string [,number-of-digits] [,input-value-size]

### RETURNS

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

### Arguments

> #### varying-input-value

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

> Unsigned byte, word, or longword that OTS$CVT_L_TZ converts to an unsigned decimal representation in an ASCII text string. (The value of the input-value-size argument determines whether varying-input-value is a byte, word, or longword.) The varying-input-value argument is the address of the unsigned integer.

> #### fixed-length-resultant-string

> OpenVMS usage: | char_string
> type: | character string
> access: | write only
> mechanism: | by descriptor, fixed length

> Output string that OTS$CVT_L_TZ creates when it converts the integer value to a hexadecimal ASCII text string. The fixed-length-resultant-string argument is the address of a descriptor pointing to this ASCII text string. The string is assumed to be of fixed length (CLASS_S descriptor).

> #### number-of-digits

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by value

> Minimum number of digits in the ASCII text string that OTS$CVT_L_TZ creates when it converts the integer. The number-of-digits argument is a signed longword containing this minimum number. If it is omitted, the default is 1. If the actual number of significant digits in the text string that OTS$CVT_L_TZ creates is less than this minimum number, OTS$CVT_L_TZ inserts leading zeros in the output string. If the minimum number of digits is zero and the integer value to be converted is also zero, OTS$CVT_L_TZ writes a blank string to the output string.

> #### input-value-size

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by value

> Size of the integer that OTS$CVT_L_TZ converts, in bytes. The input-value-size argument is a signed longword containing the value size. If the size is omitted, the default is 4 (longword).

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> OTS$_OUTCONERR | Output conversion error. The result would have exceeded the fixed-length string; the output string is filled with asterisks (*).

### Example

    with TEXT_IO; use TEXT_IO;
    procedure SHOW_CONVERT is

       type INPUT_INT is new INTEGER range 0..INTEGER'LAST;

       INTVALUE : INPUT_INT := 256;
       HEXSTRING : STRING(1..11);

       procedure CONVERT_TO_HEX (I : in INPUT_INT; HS : out STRING);
       pragma INTERFACE (RTL, CONVERT_TO_HEX);
       pragma IMPORT_routine (INTERNAL => CONVERT_TO_HEX,
                                EXTERNAL => "OTS$CVT_L_TZ",
                                MECHANISM =>(REFERENCE,
                                             DESCRIPTOR (CLASS => S)));

    begin
       CONVERT_TO_HEX (INTVALUE, HEXSTRING);
       PUT_LINE("This is the value of HEXSTRING");
       PUT_LINE(HEXSTRING);
    end;

> This Ada example uses OTS$CVT_L_TZ to convert a longword integer to hexadecimal text.

## OTS$CVT_T_x

> The Convert Numeric Text to D-, F-, G-, or H-Floating routines convert an ASCII text string representation of a numeric value to a D-floating, F-floating, G-floating, or H-floating value.

### Format

> OTS$CVT_T_D fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits]

> OTS$CVT_T_F fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits]

> OTS$CVT_T_G fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits]

> OTS$CVT_T_H fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits]

### RETURNS

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

### Arguments

> #### fixed-or-dynamic-input-string

> OpenVMS usage: | char_string
> type: | character string
> access: | read only
> mechanism: | by descriptor, fixed-length or dynamic string

> Input string containing an ASCII text string representation of a numeric value that OTS$CVT_T_x converts to a D-floating, F-floating, G-floating, or H-floating value. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string.

> The syntax of a valid input string is as follows:

E, e, D, d, Q, and q are the possible exponent letters. They are semantically equivalent. Other elements in the preceding syntax are defined as follows:

Term | Description
--- | ---
blanks | One or more blanks
digits | One or more decimal digits

#### floating-point-value

OpenVMS usage: | floating_point
type: | D_floating, F_floating, G_floating, H_floating
access: | write only
mechanism: | by reference

Floating-point value that OTS$CVT_T_x creates when it converts the input string. The floating-point-value argument is the address of the floating-point value. The data type of floating-point-value depends on the called routine as shown in the following table:

Routine | floating-point-value Data Type
--- | ---
OTS$CVT_T_D | D-floating
OTS$CVT_T_F | F-floating
OTS$CVT_T_G | G-floating
OTS$CVT_T_H | H-floating

#### digits-in-fraction

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

Number of digits in the fraction if no decimal point is included in the input string. The digits-in-fraction argument contains the number of digits. If the number of digits is omitted, the default is zero.

#### scale-factor

OpenVMS usage: | longword_signed
type: | longword (signed)
access: | read only
mechanism: | by value

Scale factor. The scale-factor argument contains the value of the scale factor. If bit 6 of the flags-value argument is clear, the resultant value is divided by 10scale-factor unless the exponent is present. If bit 6 of flags-value is set, the scale factor is always applied. If the scale factor is omitted, the default is zero.

#### flags-value

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

User-supplied flags. The flags-value argument contains the user-supplied flags described in the following table:

Bit | Action if Set | Action if Clear
--- | --- | ---
0 | Ignore blanks. | Interpret blanks as zeros.
1 | Allow only E or e exponents. (This is consistent with Fortran semantics.) | Allow E, e, D, d, Q and q exponents. (This is consistent with BASIC semantics.)
2 | Interpret an underflow as an error. | Do not interpret an underflow as an error.
3 | Truncate the value. | Round the value.
4 | Ignore tabs. | Interpret tabs as invalid characters.
5 | An exponent must begin with a valid exponent letter. | The exponent letter can be omitted.
6 | Always apply the scale factor. | Apply the scale factor only if there is no exponent present in the string.

If you omit the flags-value argument, OTS$CVT_T_x defaults all flags to clear.

#### extension-bits (D-, F-floating)

OpenVMS usage: | byte_unsigned
type: | byte (unsigned)
access: | write only
mechanism: | by reference

#### extension-bits (G-, H-floating)

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

Extra precision bits. The extension-bits argument is the address of a word containing the extra precision bits. If extension-bits is present, floating-point-value is not rounded, and the first n bits after truncation are returned left-justified in this argument, as follows:

Routine | Number of Bits Returned | Data Type
--- | --- | ---
OTS$CVT_T_D | 8 | Byte (unsigned)
OTS$CVT_T_F | 8 | Byte (unsigned)
OTS$CVT_T_G | 11 | Word (unsigned)
OTS$CVT_T_H | 15 | Word (unsigned)

A value represented by extension bits is suitable for use as the extension operand in an EMOD instruction.

The extra precision bits returned for H-floating may not be precise because OTS$CVT_T_H carries its calculations to only 128 bits. However the error should be small.

### Description

> The OTS$CVT_T_D, OTS$CVT_T_F, OTS$CVT_T_G, and OTS$CVT_T_H routines support Fortran D, E, F, and G input type conversion as well as similar types for other languages.

> These routines provide run-time support for BASIC and Fortran input statements.

> Although Alpha systems do not generally support H-floating operations, you can use OTS$CVT_T_H to convert a text string to an H-floating value on an Alpha system.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> OTS$_INPCONERR | Input conversion error; an invalid character in the input string, or the value is outside the range that can be represented. The floating-point-value and extension-bits arguments, if present, are set to +0.0 (not reserved operand --0.0).

### Example

    C+
    C This is a Fortran program demonstrating the use of
    C OTS$CVT_T_F.
    C-

            REAL*4 A
            CHARACTER*10 T(5)
            DATA T/'1234567+23','8.786534+3','-983476E-3','-23.734532','45'/
            DO 2 I = 1, 5
            TYPE 1,I,T(I)
     1      FORMAT(' Input string ',I1,' is ',A10)

    C+
    C B is the return status.
    C T(I) is the string to be converted to an
    C F-floating point value.  A is the F-floating
    C point conversion of T(I).  %VAL(5) means 5 digits
    C are in the fraction if no decimal point is in
    C the input string T(I).
    C-
            B = OTS$CVT_T_F(T(I),A,%VAL(5),,)
            TYPE *,' Output of OTSCVT_T_F is     ',A
            TYPE *,'  '
     2      CONTINUE
            END

> This Fortran example demonstrates the use of OTS$CVT_T_F. The output generated by this program is as follows:

>     Input string 1 is 1234567+23
>      Output of OTSCVT_T_F is       1.2345669E+24
>     Input string 2 is 8.786534+3
>      Output of OTSCVT_T_F is        8786.534
>     Input string 3 is -983476E-3
>      Output of OTSCVT_T_F is      -9.8347599E-03
>     Input string 4 is -23.734532
>      Output of OTSCVT_T_F is       -23.73453
>     Input string 5 is 45
>      Output of OTSCVT_T_F is        45000.00

## OTS$CVT_TB_L

> The Convert Binary Text to Unsigned Integer routine converts an ASCII text string representation of an unsigned binary value to an unsigned integer value. The integer value can be of arbitrary length but is typically a byte, word, longword, or quadword. The default size of the result is a longword.

### Format

> OTS$CVT_TB_L fixed-or-dynamic-input-string ,varying-output-value [,output-value-size] [,flags-value]

### RETURNS

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

### Arguments

> #### fixed-or-dynamic-input-string

> OpenVMS usage: | char_string
> type: | character string
> access: | read only
> mechanism: | by descriptor

> Input string containing the string representation of an unsigned binary value that OTS$CVT_TB_L converts to an unsigned integer value. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string. The valid input characters are blanks and the digits 0 and 1. No sign is permitted.

> #### varying-output-value

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

> Unsigned integer of specified size that OTS$CVT_TB_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the integer. The value of the output-value-size argument determines the size in bytes of the output value.

> #### output-value-size

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by value

> Arbitrary number of bytes to be occupied by the unsigned integer output value. The output-value-size argument contains a value that equals the size in bytes of the output value. If the value of output-value-size is zero or a negative number, OTS$CVT_TB_L returns an input conversion error. If you omit the output-value-size argument, the default is 4 (longword).

> #### flags-value

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

> User-supplied flag that OTS$CVT_TB_L uses to determine how to interpret blanks within the input string. The flags-value argument contains this user-supplied flag.

> OTS$CVT_TB_L defines the flag as follows:

> Bit | Action if Set | Action if Clear
> --- | --- | ---
> 0 | Ignore blanks. | Interpret blanks as zeros.

> If you omit the flags-value argument, OTS$CVT_TB_L defaults all flags to clear.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> OTS$_INPCONERR | Input conversion error. OTS$CVT_TB_L encountered an invalid character in the fixed-or-dynamic-input-string, an overflow of varying-output-value, or an invalid output-value-size. In the case of an invalid character or of an overflow, varying-output-value is set to zero.

### Example

        OPTION                              &
            TYPE = EXPLICIT

        !+
        !   This program demonstrates the use of OTS$CVT_TB_L from BASIC.
        !   Several binary numbers are read and then converted to their
        !   integer equivalents.
        !-

        !+
        !   DECLARATIONS
        !-

        DECLARE STRING BIN_STR
        DECLARE LONG BIN_VAL, I, RET_STATUS
        DECLARE LONG CONSTANT FLAGS = 17        ! 2^0 + 2^4
        EXTERNAL LONG FUNCTION OTS$CVT_TB_L (STRING, LONG, &
            LONG BY VALUE, LONG BY VALUE)

        !+
        !   MAIN PROGRAM
        !-

        !+
        !   Read the data, convert it to binary, and print the result.
        !-

        FOR I = 1 TO 5
            READ BIN_STR
            RET_STATUS = OTS$CVT_TB_L( BIN_STR, BIN_VAL, '4'L, FLAGS)
            PRINT BIN_STR;" treated as a binary number equals";BIN_VAL
        NEXT I

        !+
        !   Done, end the program.
        !-

        GOTO 32767

    999 Data    "1111", "1 111", "1011011", "11111111", "00000000"

    32767 END

> This BASIC example program demonstrates how to call OTS$CVT_TB_L to convert binary text to a longword integer.

> The output generated by this BASIC program is as follows:

>     1111 treated as a binary number equals 15
>     1 111 treated as a binary number equals 15
>     1011011 treated as a binary number equals 91
>     11111111 treated as a binary number equals 255
>     00000000 treated as a binary number equals 0

## OTS$CVT_TI_L

> The Convert Signed Integer Text to Integer routine converts an ASCII text string representation of a signed decimal number to a signed integer value. The default size of the result is a longword.

### Format

> OTS$CVT_TI_L fixed-or-dynamic-input-string ,varying-output-value [,output-value-size] [,flags-value]

### RETURNS

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

### Arguments

> #### fixed-or-dynamic-input-string

> OpenVMS usage: | char_string
> type: | character string
> access: | read only
> mechanism: | by descriptor, fixed-length or dynamic string

> Input ASCII text string that OTS$CVT_TI_L converts to a signed integer. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string.

> The syntax of a valid ASCII text input string is as follows:

> [ + | - ] <integer-digits>

> OTS$CVT_TI_L always ignores leading blanks.

> #### varying-output-value

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

> Signed integer that OTS$CVT_TI_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the signed integer. The value of the output-value-size argument determines the size of varying-output-value.

> #### output-value-size

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by value

> Number of bytes to be occupied by the value created when OTS$CVT_TI_L converts the ASCII text string to an integer value. The output-value-size argument contains the number of bytes in varying-output-value.

> On VAX systems, valid values for the output-value-size argument are 1, 2, and 4. The value determines whether the integer value that OTS$CVT_TI_L creates is a byte, word, or longword.

> On Alpha systems, valid values for the output-value-size argument are 1, 2, 4, and 8. The value determines whether the integer value that OTS$CVT_TI_L creates is a byte, word, longword, or quadword.

> For VAX and Alpha systems, if you specify a 0 (zero) or omit the output-value-size argument, the size of the output value defaults to 4 (longword). If you specify any other value, OTS$CVT_TI_L returns an input conversion error.

> #### flags-value

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

> User-supplied flags that OTS$CVT_TI_L uses to determine how blanks and tabs are interpreted. The flags-value argument is an unsigned longword containing the value of the flags.

> Bit | Action if Set | Action if Clear
> --- | --- | ---
> 0 | Ignore all blanks. | Ignore leading blanks but interpret blanks after the first legal character as zeros.
> 4 | Ignore tabs. | Interpret tabs as invalid characters.

> If you omit the flags-value argument, OTS$CVT_TI_L defaults all flags to clear.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> OTS$_INPCONERR | Input conversion error. OTS$CVT_TI_L encountered an invalid character in the fixed-or-dynamic-input-string, an overflow of varying-output-value, or an invalid output-value-size. In the case of an invalid character or of an overflow, varying-output-value is set to zero.

Previous | Next | Contents | Index

| privacy and legal statement |
5933PRO_002.HTML