OpenVMS RTL General Purpose (OTS$) Manual

Updated: 11 December 1998

OpenVMS RTL General Purpose (OTS$) Manual

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;

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:
[<blanks>] [+ | --] [<digits>][.][<digits>] [ {+ | --} {E | e | D | d | Q |q} [<blanks>] [+ | --]] [<digits>]
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 10^scale-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.

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

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

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.

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)

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- REAL4 A CHARACTER10 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

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.

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

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

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.

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_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.

Contents

Index

Legal

 
5933PRO_002.HTML

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

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

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

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

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 (*).

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

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

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

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

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

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).