Document revision date: 30 March 2001

## OpenVMS RTL General Purpose (OTS$) Manual

Previous | Contents | Index

## OTS$CVT_TL_L

> The Convert Logical Text to Integer routine converts an ASCII text string representation of a FORTRAN-77 L format to a signed integer.

### Format

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

### 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 representation of a FORTRAN-77 L format that OTS$CVT_TL_L converts to a signed integer value. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string.

> Common ASCII text representations of a FORTRAN-77 logical are .TRUE., .FALSE., T, t, F, and f. In practice, an OTS$CVT_TL_L input string is valid if it adheres to the following syntax:

One of the letters T, t, F, or f is required. Other elements in the preceding syntax are defined as follows:

Term | Description
--- | ---
blanks | One or more blanks
characters | One or more of any character

#### varying-output-value

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

Signed integer that OTS$CVT_TL_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 in bytes of the signed integer.

OTS$CVT_TL_L returns --1 as the contents of the varying-output-value argument if the character denoted by "letter" is T or t. Otherwise, OTS$CVT_TL_L sets varying-output-value to zero.

#### output-value-size

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

Number of bytes to be occupied by the signed integer created when OTS$CVT_TL_L converts the ASCII text string to an integer value. The output-value-size argument contains a value that equals the size in bytes of the output value. If output-value-size contains a zero or a negative number, OTS$CVT_TL_L returns an input conversion error.

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_TL_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. This value determines whether the integer value that OTS$CVT_TL_L creates is a byte, word, longword, or quadword.

For VAX and Alpha systems, if you omit the output-value-size argument, the default is 4 (longword).

### Condition Values Returned

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

## OTS$CVT_TO_L

> The Convert Octal Text to Unsigned Integer routine converts an ASCII text string representation of an unsigned octal value to an unsigned integer. 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_TO_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 string containing the string representation of an unsigned octal value that OTS$CVT_TO_L converts to an unsigned integer. 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 through 7. 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_TO_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the unsigned 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 integer (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_TO_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_TO_L uses to determine how to interpret blanks within the input string. The flags-value argument contains the user-supplied flag described in the following table:

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

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

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> OTS$_INPCONERR | Input conversion error. OTS$CVT_TO_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

    OCTAL_CONV: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31));

    %INCLUDE $STSDEF;       /* Include definition of return status values      */
    DECLARE OTS$CVT_TO_L ENTRY
            (CHARACTER (*),         /* Input string passed by descriptor       */
            FIXED BINARY (31),      /* Returned value passed by reference      */
            FIXED BINARY VALUE,     /* Size for returned value passed by value */
            FIXED BINARY VALUE)     /* Flags passed by value                   */
            RETURNS (FIXED BINARY (31))     /* Return status                   */
            OPTIONS (VARIABLE);     /* Arguments may be omitted                */

    DECLARE INPUT CHARACTER (10);
    DECLARE VALUE FIXED BINARY (31);
    DECLARE SIZE  FIXED BINARY(31) INITIAL(4) READONLY STATIC; /* Longword     */
    DECLARE FLAGS FIXED BINARY(31) INITIAL(1) READONLY STATIC; /* Ignore blanks*/

    ON ENDFILE (SYSIN) STOP;

    DO WHILE ('1'B);                /* Loop continuously, until end of file    */
            PUT SKIP (2);
            GET LIST (INPUT) OPTIONS (PROMPT ('Octal value: '));
            STS$VALUE = OTS$CVT_TO_L (INPUT, VALUE, SIZE, FLAGS);
            IF ^STS$SUCCESS THEN RETURN (STS$VALUE);
            PUT SKIP EDIT (INPUT, 'Octal equals', VALUE, 'Decimal')
                            (A,X,A,X,F(10),X,A);
            END;

    END OCTAL_CONV;

> This PL/I program translates an octal value in ASCII into a fixed binary value. The program is run interactively; press Ctrl/Z to quit.

>     $ RUN OCTAL
>     Octal value: 1
>     1  Octal equals 1 Decimal
>     Octal value: 11
>     11   Octal equals   9 Decimal
>     Octal value: 1017346
>     1017346 Octal equals 274150 Decimal
>     Octal value: Ctrl/Z

## OTS$CVT_TU_L

> The Convert Unsigned Decimal Text to Integer routine converts an ASCII text string representation of an unsigned decimal value to an unsigned integer value. By default, the size of the result is a longword.

### Format

> OTS$CVT_TU_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 an ASCII text string representation of an unsigned decimal value that OTS$CVT_TU_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. Valid input characters are the space and the digits 0 through 9. No sign is permitted.

> #### varying-output-value

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

> Unsigned integer that OTS$CVT_TU_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the unsigned 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 integer (signed)
> access: | read only
> mechanism: | by value

> Number of bytes occupied by the value created when OTS$CVT_TU_L converts the input string. 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_TU_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_TU_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_TU_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_TU_L uses to determine how blanks and tabs are interpreted. The flags-value argument contains the user-supplied flags as described in the following table:

> 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_TU_L defaults all flags to clear.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> OTS$_INPCONERR | Input conversion error. OTS$CVT_TU_L encountered an invalid character in the fixed-or-dynamic-input-string, 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.

## OTS$CVT_TZ_L

> The Convert Hexadecimal Text to Unsigned Integer routine converts an ASCII text string representation of an unsigned hexadecimal value to an unsigned integer. 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_TZ_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 string containing the string representation of an unsigned hexadecimal value that OTS$CVT_TZ_L converts to an unsigned integer. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string. The valid input characters are blanks, the digits 0 through 7, and the letters A through F. Letters can be uppercase or lowercase. 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_TZ_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the unsigned 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_TZ_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 flags that OTS$CVT_TZ_L uses to determine how to interpret blanks within the input string. The flags-value argument contains these user-supplied flags as described in the following table:

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

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

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> OTS$_INPCONERR | Input conversion error. OTS$CVT_TZ_L encountered an invalid character in the fixed-or-dynamic-input-string, 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.

###

#### Examples

#1
    10      !+
            ! This BASIC program converts a character string representing
            ! a hexadecimal value to a longword.
            !-

    100     !+
            ! Illustrate (and test) OTS convert hex-string to longword
            !-

            EXTERNAL LONG FUNCTION OTS$CVT_TZ_L
            EXTERNAL LONG CONSTANT OTS$_INPCONERR
            INPUT "Enter hex numeric";HEXVAL$
            RET_STAT% = OTS$CVT_TZ_L(HEXVAL$, HEX% )
            PRINT "Conversion error " IF RET_STAT% = OTS$_INPCONERR
            PRINT "Decimal value of ";HEXVAL$;" is";HEX%                &
                 IF RET_STAT% <> OTS$_INPCONERR

> This BASIC example accepts a hexadecimal numeric string, converts it to a decimal integer, and prints the result. One sample of the output generated by this program is as follows:

>     $ RUN HEX
>     Enter hex numeric?  A
>     Decimal value of A is 10

#2
    HEX_CONV: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31));

    %INCLUDE $STSDEF;       /* Include definition of return status values     */
    DECLARE OTS$CVT_TZ_L ENTRY
            (CHARACTER (*),         /* Input string passed by descriptor      */
            FIXED BINARY (31),      /* Returned value passed by reference     */
            FIXED BINARY VALUE,     /* Size for returned value passed by value*/
            FIXED BINARY VALUE)     /* Flags passed by value                  */
            RETURNS (FIXED BINARY (31))     /* Return status                  */
            OPTIONS (VARIABLE);     /* Arguments may be omitted               */

    DECLARE INPUT CHARACTER (10);
    DECLARE VALUE FIXED BINARY (31);
    DECLARE FLAGS FIXED BINARY(31) INITIAL(1) READONLY STATIC; /*Ignore blanks*/

    ON ENDFILE (SYSIN) STOP;

    DO WHILE ('1'B);                /* Loop continuously, until end of file   */
            PUT SKIP (2);
            GET LIST (INPUT) OPTIONS (PROMPT ('Hex value: '));
            STS$VALUE = OTS$CVT_TZ_L (INPUT, VALUE, , FLAGS);
            IF ^STS$SUCCESS THEN RETURN (STS$VALUE);
            PUT SKIP EDIT (INPUT, 'Hex equals', VALUE, 'Decimal')
                            (A,X,A,X,F(10),X,A);
            END;

    END HEX_CONV;

> This PL/I example translates a hexadecimal value in ASCII into a fixed binary value. This program continues to prompt for input values until the user presses Ctrl/Z.

> One sample of the output generated by this program is as follows:

>     $ RUN HEX
>     Hex value:  1A
>     1A      Hex equals       26 Decimal

>     Hex value:  C
>     C       Hex equals       12 Decimal

>     Hex value:  Ctrl/Z

Previous | Next | Contents | Index

| privacy and legal statement |
5933PRO_003.HTML