OpenVMS RTL General Purpose (OTS$) Manual

Updated: 11 December 1998

OpenVMS RTL General Purpose (OTS$) Manual

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:
{<blanks> [<blanks>][.] {T | t | F | f} [<characters>}
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).

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

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.

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

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;

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.

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.

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.

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

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

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;

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

Contents

Index

Legal

 
5933PRO_003.HTML

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

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

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

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

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.

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