 |
HP OpenVMS RTL General Purpose (OTS$) Manual
HP OpenVMS RTL General Purpose (OTS$) Manual
OTS$CVT_L_TU
The Convert Unsigned Integer to Decimal Text routine converts an
unsigned integer value to its unsigned decimal representation in an
ASCII text string.
Format
OTS$CVT_L_TU 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 |
An unsigned integer that OTS$CVT_L_TU converts to an unsigned decimal
representation in an ASCII text string. The
varying-input-value argument is the address of the
unsigned integer.
On VAX systems, the integer can be an unsigned byte, word, or longword.
(The value of the input-value-size argument determines
whether varying-input-value is a byte, word, or
longword.)
On Alpha and I64 systems, the integer can be an unsigned byte, word,
longword, or quadword. (The value of the
input-value-size argument determines whether
varying-input-value is a byte, word, longword, or
quadword.)
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_TU creates when it converts the integer
value to unsigned decimal representation in an ASCII text string. The
fixed-length-resultant-string argument is the address
of a descriptor pointing to this ASCII text string.
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_TU
creates. The number-of-digits argument is a signed
longword containing the minimum number. If the minimum number of digits
is omitted, the default is 1.
If the actual number of significant digits in the output string created
is less than the minimum number, OTS$CVT_L_TU inserts leading zeros
into the output string. If the minimum number of digits is zero and the
integer value to be converted is also zero, OTS$CVT_L_TU 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 to be converted, in bytes. The
input-value-size argument is a signed longword
containing this value size. If the size is omitted, the default is 4
(longword).
On VAX systems, the value size must be 1, 2, or 4.
On Alpha and I64 systems, the value size must be 1, 2, 4, or 8.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
OTS$_OUTCONERR
|
Output conversion error. Either the result would have exceeded the
fixed-length string or the
input-value-size is not a valid value. The output
string is filled with asterisks (*).
|
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-, H-, IEEE S-, or IEEE T-Floating
routines convert an ASCII text string representation of a numeric value
to a D-floating, F-floating, G-floating, H-floating, IEEE S-floating,
or IEEE T-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]
OTS$CVT_T_S fixed-or-dynamic-input-string ,floating-point-value
[,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits]
OTS$CVT_T_T 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, H-floating, IEEE S-floating, or IEEE T-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, IEEE
S_floating, IEEE T_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
|
|
OTS$CVT_T_S
|
IEEE S-floating
|
|
OTS$CVT_T_T
|
IEEE T-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, IEEE S-floating)
| OpenVMS usage: |
byte_unsigned |
| type: |
byte (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
extension-bits (G-, H-floating, IEEE T-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)
|
|
OTS$CVT_T_S
|
8
|
Byte (unsigned)
|
|
OTS$CVT_T_T
|
11
|
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, OTS$CVT_T_H, OTS$CVT_T_S,
and OTS$CVT_T_T 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 and I64 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 or I64 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
|
