Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

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

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5933PRO_003.HTML