Digital PDFs

AA-LA73A-TE

December 1988

117 pages

Original

3.3MB

Document:	VMS 5.0 RTL General Purpose OTS$ Manual 198804
Order Number:	AA-LA73A-TE
Revision:
Pages:	117
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.0/AA-LA73A-TE_VMS_5.0_RTL_General_Purpose_OTS$_Manual_198804.pdf

OCR Text

VMS

digital

VMS RTL General Purpose (OTS$) Manual

Order Number AA-LA73A-TE

VMS RTL General Purpose
(OTS$) Manual
Order Number: AA-LA 73A-TE

April 1988
This manual documents the general purpose routines contained in the
OTS$ facility of the VMS Run-Time Library.

Revision/Update Information:

This document supersedes
the OTS$ section of the VAX/VMS
Run- Time Library Routines Reference
Manual, Version 4.4.

Software Version:

VMS Version 5.0

digital equipment corporation
maynard, massachusetts

April 1988
The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment
that is not supplied by Digital Equipment Corporation or its affiliated companies.
Copyright © 1988 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

~U~UIJ~DTM
ZK4611

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT MAIL ORDERS
USA & PUERTO Rico*

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire
03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digital~ local subsidiary
or approved distributor

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire, Alaska, and Hawaii call 603-884-6660.
In Canada call 800-267-6215.
*Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SDC), Digital Equipment
Corporation, Westminster, Massachusetts 01473.

Production Note
This book was produced with the VAX DOCUMENT electronic publishing
system, a software tool developed and sold by DIGITAL. In this system,
writers use an ASCII text editor to create source files containing text and
English-like code; this code labels the structural elements of the document,
such as chapters, paragraphs, and tables. The VAX DOCUMENT software,
which runs on the VMS operating system, interprets the code to format the
text, generate a table of contents and index, and paginate the entire document.
Writers can print the document on the terminal or line printer, or they can use
DIGITAL-supported devices, such as the LN03 laser printer and PostScript®
printers (PrintServer 40 or LN03R ScriptPrinter), to produce a typeset-quality
copy containing integrated graphics.

PostScript is a trademark of Adobe Systems, Inc.

Contents
PREFACE

vii

CHAPTER 1 OVERVIEW OF THE OTS$ FACILITY

1-1

OTS$ REFERENCE SECTION
OTS$CNVOUT
OTS$CVT_L_TB
OTS$CVT_L_Tl
OTS$CVT_L_TL
OTS$CVT_L_TQ
OTS$CVT_L_TU
OTS$CVT_L_TZ
OTS$CVT_TB_L
OTS$CVT_Tl_L
OTS$CVT_TL_L
OTS$CVT_TQ_L
OTS$CVT_TU_L
OTS$CVT_T_Z
OTS$CVT_T_Z
OTS$CVT_TZ_L
OTS$DIVCX
OTS$DIV_PK_LQNG
OTS$DIV_PK_SHORT
OTS$MOVE3
OTS$MOVE5
OTS$MULCX
OTS$POWCXCX
OTS$POWCXJ
OTS$POWDD
OTS$POWDR
OTS$POWDJ
OTS$POWGG
OTS$POWGJ
OTS$POWHH_R3
OTS$POWHJ_R3

OTS-3
OTS-5
OTS-7
OTS-9
OTS-11
OTS-13
OTS-15
OTS-17
OTS-20
OTS-22
OTS-24
OTS-27
OTS-29
OTS-33
OTS-36
OTS-39
OTS-42
OTS-46
OTS-49
OTS-51
OTS-53
OTS-55
OTS-58
OTS-61
OTS-63
OTS-65
OTS-67
OTS-70
OTS-72
OTS-74
v

Contents

OTS$POWll
OTS$POWJJ
OTS$POWLULU
OTS$POWXLU
OTS$POWRD
OTS$POWRJ
OTS$POWRR
OTS$SCOPV_DXDX
OTS$SCOPV_R_DX
OTS$SFREE1 _DD
OTS$SFREEN_DD
OTS$SGET1_DD

OTS-76
OTS-77
OTS-78
OTS-79
OTS-81
OTS-84
OTS-86
OTS-89
OTS-91
OTS-94
OTS-95
OTS-96

INDEX

TABLES
1-1

OTS$ Routines

1-1

Preface
This manual provides users of the VMS operating system with detailed usage
and reference information on general purpose routines supplied in the OTS$
facility of the Run-Time Library.
Run-Time Library routines can only be used in programs written in languages
that produce native code for the VAX hardware. At present, these languages
include VAX MACRO and the following compiled high-level languages:
VAX Ada
VAX BASIC
VAX BLISS-32
VAXC
VAX COBOL
VAX COBOL-7 4
VAX CORAL
VAX DIBOL
VAX FORTRAN
VAX Pascal
VAX PL/I
VAX RPG
VAX SCAN
Interpreted languages that can also access Run-Time Library routines include
VAX DSM and DATATRIEVE.

Intended Audience
This manual is intended for system and application programmers who want
to call Run-Time Library routines.

Document Structure
This manual is organized into two parts as follows:
•

Part I provides a brief overview of the OTS$ routines.

•

Part II provides detailed reference information on each routine contained
in the OTS$ facility of the Run-Time Library. This information is
presented using the documentation format described in the Introduction
to the VMS Run-Time Library. Routine descriptions appear in alphabetical
order by routine name.

vii

Preface

Associated Documents
The Run-Time Library routines are documented in a series of reference
manuals. A general overview of the Run-Time Library and a description
of how the Run-Time Library routines are accessed are presented in the
Introduction to the VMS Run-Time Library. Descriptions of the other RTL
facilities and their corresponding routines and usages are discussed in the
following books:
•

The VMS RTL DECtalk (DTK$) Manual

•

The VMS RTL Library (LIB$) Manual

•

The VMS RTL Mathematics (MTH$) Manual

•

The VMS RTL Parallel Processing (PPL$) Manual

•

The VMS RTL Screen Management (SMG$) Manual

•

The VMS RTL String Manipulation (STR$) Manual

The VAX Procedure Calling and Condition Handling Standard, which is
documented in the Introduction to System Routines, contains useful information
for anyone who wants to call Run-Time Library routines.
Application programmers of any language may refer to the Guide to Creating
VMS Modular Procedures for the Modular Programming Standard and other
guidelines.
High-level language programmers will find additional information on calling
Run-Time Library routines in their language reference manual. Additional
information may also be found in the language user's guide provided with
your VAX language.
The Guide to Using VMS Command Procedures may also be useful.
For a complete list and description of the manuals in the VMS documentation
set, see the Overview of VMS Documentation.

viii

Preface

Conventions

Convention

Meaning
In examples, a key name (usually abbreviated)
shown within a box indicates that you press
a key on the keyboard; in text, a key name is
not enclosed in a box. In this example, the key
is the RETURN key. (Note that the RETURN
key is not usually shown in syntax statements
or in all examples; however, assume that you
must press the RETURN key after entering a
command or responding to a prompt.)

CTRL/C

A key combination, shown in uppercase with a
slash separating two key names, indicates that
you hold down the first key while you press the
second key. For example, the key combination
CTRL/C indicates that you hold down the key
labeled CTRL while you press the key labeled C.
In examples, a key combination is enclosed in a
box.

$SHOW TIME
05-JUN-1988 11 :55:22

In examples, system output (what the system
displays) is shown in black. User input (what
you enter) is shown in red.

$TYPE MYFILE.DAT

In examples, a vertical series of periods, or
ellipsis, means either that not all the data that
the system would display in response to a
command is shown or that not all the data a
user would enter is shown.

input-file, ...

In examples, a horizontal ellipsis indicates
that additional parameters, values, or other
information can be entered, that preceding
items can be repeated one or more times, or
that optional arguments in a statement have
been omitted.

[logical-name]

Brackets indicate that the enclosed item is
optional. (Brackets are not, however, optional
in the syntax of a directory name in a file
specification or in the syntax of a substring
specification in an assignment statement.)

quotation marks
apostrophes

The term quotation marks is used to refer
to double quotation marks (" ). The term
apostrophe (' ) is used to refer to a single
quotation mark.

Other conventions used in the documentation of Run-Time Library routines
are described in the Introduction to the VMS Run-Time Library.

Overview of the OTS$ Facility

This manual discusses the Run-Time Library OTS$ routines that perform
general purpose functions. These functions include data type conversions as
part of a compiler's generated code, and some mathematical functions.
Most of the OTS$ routines were originally designed to support language
compilers. Because they provide useful functions, they were moved into the
language-independent facility, OTS$.
The OTS$ facility provides you with routines that perform seven main tasks:

•
•
•

Convert data types
Divide complex and packed decimal values
Move data to a specified destination address

•
•

Multiply complex values

•

Copy a source string to a destination string

•

Return a string area to free storage

Raise a base to an exp on en t

The following lists contain all of the OTS$ routines grouped according to
their functions.
Table 1-1

OTS$ Routines

Conversion Routine

Function

OTS$CNVOUT

Convert a D-floating, G-floating, or
H-floating value to a character string

OTS$CVT_L_TB
OTS$CVT_L _Tl

Convert an unsigned integer to binary text

OTS$CVT_L_TL
OTS$CVT_L_TO
OTS$CVT_L_TU
OTS$CVT_L_TZ
OTS$CVT_TB_L

Convert a signed integer to signed integer
text
Convert an integer to logical text
Convert an unsigned integer to octal text
Convert an unsigned integer to decimal text
Convert an integer to hexadecimal text
Convert binary text to an unsigned integer
value

OTS$CVT_Tl_L

Convert signed integer text to an integer
value

OTS$CVT_TL _L
OTS$CVT_TQ_L
OTS$CVT_TU_L

Convert logical text to an integer value
Convert octal text to an integer value
Convert unsigned decimal text to an integer
value

1-1

Overview of the OTS$ Facility

Table 1-1 {Cont.)

1-2

OTS$ Routines

Conversion Routine

Function

OTS$CVT_T_z

Convert numeric text to a D- or F-floating
value

OTS$CVT_T_x

Convert numeric text to a G- or H-floating
value

OTS$CVT_TZ_L

Convert hexadecimal text to an unsigned
longword integer value

Division Routine

Function

OTS$DIVCx

Perform complex division

OTS$DIV_PK_LONG

Perform packed decimal division with a long
divisor

OTS$DIV_PK_SHORT

Perform packed decimal division with a
short divisor

Move Data Routine

Function

OTS$MOVE3

Move data without fill

OTS$MOVE5

Move data with fill

Multiplication Routine

Function

OTS$MULCx

Perform complex multiplication

Exponentiation Routine

Function

OTS$POWCxCx

Raise a complex base to a complex floatingpoint exponent

OTS$POWCxJ

Raise a complex base to a signed longword
exponent

OTS$POWDD

Raise a D-floating base to a D-floating
exponent

OTS$POWDR

Raise a D-floating base to an F-floating
exponent

OTS$POWDJ

Raise a D-floating base to a longword
integer exponent

OTS$POWGx

Raise a G-floating base to a G-floating or
longword integer exponent

OTS$POWGJ

Raise a G-floating base to a longword
integer exponent

Overview of the OTS$ Facility

Table 1-1 (Cont.)

OTS$ Routines

Exponentiation Routine

Function

OTS$POWHx

Raise an H-floating base to a floating-point
exponent

OTS$POWHJ

Raise an H-floating base to a longword
integer exponent

OTS$POWll

Raise a word integer base to a word integer
exponent

OTS$POWHJJ

Raise a longword integer base to a
longword integer exponent

OTS$POWLULU

Raise an unsigned longword integer base to
an unsigned longword integer exponent

OTS$POWxLU

Raise a floating-point base to an unsigned
longword integer exponent

OTS$POWRO

Raise an F-floating base to a 0-floating
exponent

OTS$POWRJ

Raise an F-floating base to a longword
integer exponent

OTS$POWRR

Raise an F-floating base to an F-floating
exponent

Copy Source String Routine

Function

OTS$SCOPY_OXOX

Copy a source string passed by descriptor
to a destination string

OTS$SCOPY_R_OX

Copy a source string passed by reference
to a destination string

Return String Area Routine

Function

OTS$SFREE 1_00

Free one dynamic string

OTS$SFREEN_OO

Free n dynamic strings

OTS$SGET1_00

Get one dynamic string

1-3

OTS$ Reference Section
This section provides detailed descriptions of the routines provided by the
VMS RTL General Purpose (OTS$) Facility.

OTS$CNVOUT

Convert D-floating, G-floating or
H-floating Number to Character
String

The Convert Floating to Character String routines convert a D-floating,
G-floating or H-floating number to a character string in the FORTRAN E
format.

FORMAT

OTS$CNVOUT

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

0-G-or-H-float-pt-input-val
, fixed-length-resultant-string
, digits-in-fraction
OTS$CNVOUT_G 0-G-or-H-float-pt-input-val
, fixed-length-resultant-string
, digits-in-fraction
OTS$CNVOUT_H 0-G-or-H-float-pt-input-val
, fixed-length-resultant-string
, digits-in-fraction
cond_value
longword (unsigned)
write only
by value

D-G-or-H-float-pt-input-val
VMS usage:
type:
access:
mechanism:

floating_point
D_floating, G_floating, H_floating
read only
by reference

Value that OTS$CNVOUT converts to a character string. For OTS$CNVOUT,
the D-G-or-H-float-pt-input-val argument is the address of a D-floating
number containing the value. For OTS$CNVOUT_G, the D-G-or-H-floatpt-input-val argument is the address of a G-floating number containing the
value. For OTS$CNVOUT_H, the D-G-or-H-float-pt-input-val argument is
the address of an H-floating number containing the value.

fixed-length-resultant-string
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor, fixed length

Output string into which OTS$CNVOUT writes the character string result of
the conversion. The fixed-length-resultant-string argument is the address of
a descriptor pointing to the output string.

OTS-3

OTS$CNVOUT

digits-in-fraction
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by value

Number of digits in the fractional portion of the result. The digits-in-fraction
argument is an unsigned longword containing the number of digits to be
written to the fractional portion of the result.

CONDITION
VALUES
RETURNED

OTS-4

SS$_NORMAL

Normal successful completion.

SS$_ROPRAND

Floating reserved operand detected.

OTS$_QUTCONERR

Output conversion error. The result would have
exceeded the fixed-length string; the output string
is filled with asterisks.

OTS$CVT_L_TB

Convert an Unsigned Integer to
Binary Text

The Convert an Unsigned Integer to Binary Text routine converts an
unsigned integer value of arbitrary length to binary representation in an
ASCII text string. By default, a longword is converted.

FORMAT

OTS$CVT_L_TB

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

varying-input-value
, fixed-length-resultant-string
[,number-of-digits] [,input-value-size]

cond_value
longword (unsigned)
write only
by value

varying-input-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
read only
by reference

Unsigned byte, word, or longword that OTS$CVT_L_TB 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
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor, fixed-length

ASCII text string that OTS$CVT_L _TB creates when it converts the integer
value. 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 (DSC$K_CLASS_S).

number-of-digits
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Minimum number of digits in the binary representation to be generated. The
number-of-digits argument is a signed longword containing this minimum
number. This is an optional argument. If the minimum number of digits is
omitted, the default is 1. If the actual number of significant digits is less than
the minimum number of digits, leading zeros are produced. If the minimum

OTS-5

OTS$CVT_L_TB

number of digits is zero and the value of the integer to be converted is also
zero, OTS$CVT_L_TB creates a blank string.

input-value-size
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Size of the integer to be converted, in bytes. The input-value-size argument
is a signed longword containing the byte size. This is an optional argument.
If the size is omitted, the default is 4 (longword).

CONDITION
VALUES
RETURNED

SS$_NORMAL
OTS$_0UTCONERR

Normal successful completion.
Output conversion error. The result would have
exceeded the fixed-length string; the output string
is filled with asterisks.

EXAMPLE
o
I
1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FTTY

TTY

C* Initialize numeric value to be converted.

C
C

CVTLTB

Z-ADD13
VALUE
EXTRN'OTS$CVT_L_TB'

C* Convert the number to binary in a string.

C
C
C

CALL CVTLTB
PARM
PARMD

VALUE
RL
OUTSTR 4

C* Display on the terminal the converted string.

C
C

OUTSTR

DSPLYTTY
SETON

This RPG II program displays the string '1101' on the terminal.

OTS-6

OTS$CVT_L_Tl

OTS$CVT_L _Tl

Convert Signed Integer to
Decimal Text

The Convert Signed Integer to Decimal Text routine converts a signed
integer to a decimal ASCII text string. This routine supports FORTRAN lw
and lw.m output and BASIC output conversion.

FORMAT

OTS$CVT_L_Tl

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

varying-input-value
, fixed-length-resultant-string
[,number-of-digits} [,input-value-size}
[,flags-value]

cond_value
longword (unsigned)
write only
by value

varying-input-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
read only
by reference

Unsigned byte, word, or longword that OTS$CVT_L _TI 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
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor, fixed length

Decimal ASCII text string that OTS$CVT_L_TI creates when it converts the
signed integer. The fixed-length-resultant-string argument is the address of
a descriptor pointing to this text string. The string is assumed to be of fixed
length (DSC$K_CLASS_S).

number-of-digits
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Minimum number of digits to be generated when OTS$CVT_L _TI converts
the signed integer to a decimal ASCII text string. The number-of-digits
argument is a signed longword containing this number. This is an optional

OTS-7

OTS$CVT_L _Tl

argument. If the minimum number of digits is omitted, the default value
is 1. If the actual number of significant digits is smaller, OTS$CVT_L_TI
inserts leading zeros into the output string. If number-of-digits is zero and
varying-input-value is zero, OTS$CVT_L_TI writes a blank string to the
output string.

input-value-size
VMS usage: longword_signed
longword (signed)
access:
read only
mechanism: by value

type:

Size of the integer to be converted, in bytes. The input-value-size argument
is a signed longword containing this value size. The value size must be either
1, 2, or 4. If value size is 1 or 2, the value is sign-extended to a longword
before conversion. This is an optional argument. If the size is omitted, the
default is 4 (longword) .

.flags-value
VMS usage: mask_longword
longword (unsigned)
access:
read only
mechanism: by value

type:

Caller-supplied flags that you can use if you want OTS$CVT_L _TI to insert
a plus sign before the converted number. The flags-value argument is an
unsigned longword containing the flags.
The caller flags are defined as follows:
Bit 0

If set, a plus sign ( +) is inserted before the first non blank character in
the output string; otherwise, the plus sign is omitted.

This is an optional argument. If flags-value is omitted, all bits are clear and
the plus sign is not inserted.

CONDITION
VALUES
RETURNED

OTS-8

SS$_NORMAL

Normal successful completion.

OTS$_0UTCONERR

Output conversion error. The result would have
exceeded the fixed-length string; the output string
is filled with asterisks.

OTS$CVT_L_TL

OTS$CVT_L_TL Convert Integer to Logical Text
The Convert Integer to Logical Text routine converts an integer to an ASCII
text string representation using FORTRAN L (logical) format.

FORMAT

OTS$CVT_L_TL

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

longword-integer-value
, fixed-length-resultant-string

cond_value
longword (unsigned)
write only
by value

longword-integer-value
VMS usage: longword~signed
type:
longword (signed)
access:
read only
mechanism: by reference

Value that OTS$CVT_L _TL converts to an ASCII text string. The longwordinteger-value argument is the address of a signed longword containing this
integer value.

fixed-length-resultant-string
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor, fixed length

Output string that OTS$CVT_L_TL creates when it converts the integer
value to an ASCII text string. The fixed-length-resultant-string argument is
the address of a descriptor pointing to this ASCII text string.
The output string is assumed to be of fixed length (DSC$K_CLASS_S).
If length equals the fixed length of the output string, then the output string
consists of (length - 1) blanks followed by the letter T if bit 0 is set, or the
letter F if bit 0 is clear.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

OTS$_0UTCONERR

Output conversion error. The result would have
exceeded the fixed-length string; the output string
is of zero length (DSC$W_LENGTH= 0).

OTS-9

OTS$CVT_L_TL

EXAMPLE
5 !+
! This is an example program
! showing the use of OTS$CVT_L_TL.
!-

VALUE% = 10
OUTSTR$ = ' '
CALL OTS$CVT_L_TL(VALUE%, OUTSTR$)
PRINT OUTSTR$
9 END

This BASIC example illustrates the use of OTS$CVT_L_TL. The output
generated by this program is "F".

OTS-10

OTS$CVT_L_TQ

Convert Unsigned Integer to
Octal Text

The Convert Unsigned Integer to Octal Text routine converts an unsigned
integer to an octal ASCII text string. OTS$CVT_L_TO supports FORTRAN
Ow and Ow.m output conversion formats.

FORMAT

OTS$CVT_L_TQ

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

varying-input-value
, fixed-length-resultant-string
{,number-of-digits] {,input-value-size]

cond_value
longword (unsigned)
write only
by value

varying-input-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
read only
by reference

Unsigned byte, word, or longword that OTS$CVT_L_TO 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
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor, fixed length

Output string that OTS$CVT_L _TO creates when it converts the integer
value to an octal ASCII text string. The fixed-length-resultant-string
argument is the address of a descriptor pointing to the octal ASCII text
string. The string is assumed to be of fixed length (DSC$K_CLASS_S).

number-of-digits
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Minimum number of digits that OTS$CVT_L_TO generates when it converts
the integer value to an octal ASCII text string. The number-of-digits
argument is a signed longword containing the minimum number of digits.
This is an optional argument. If it is omitted, the default is 1. If the actual
number of significant digits in the octal ASCII text string is less than the

OTS-11

OTS$CVT_L_TO

minimum number of digits, OTS$CVT_L_TO inserts leading zeros into the
output string. If number-of-digits is zero and varying-input-value is zero,
OTS$CVT_L _TO writes a blank string to the output string.

input-value-size
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Size of the integer to be converted, in bytes. The input-value-size argument
is a signed longword containing the number of bytes in the integer to be
converted by OTS$CVT_L_TO. This is an optional argument. If it is omitted,
the default is 4 (longword).

CONDITION
VALUES
RETURNED

OTS-12

SS$_NORMAL

Normal successful completion.

OTS$_0UTCONERR

Output conversion error. The result would have
exceeded the fixed-length string; the output string
is filled with asterisks.

OTS$CVT_L_TU

Convert Unsigned Integer to
Decimal Text

The Convert Unsigned Integer to Decimal Text routine converts a byte,
word, or longword value to unsigned decimal representation in an ASCII
text string. By default, a longword is converted.

FORMAT

OTS$CVT_L_TU

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

varying-input-value
, fixed-length-resultant-string
{,number-of-digits} {,input-value-size}

cond_value
longword (unsigned)
write only
by value

varying-input-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
read only
by reference

Unsigned byte, word, or longword that OTS$CVT_L_TU 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
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor, fixed-length

Output string (fixed-length) 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
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
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. This is an optional argument. If the minimum number of
digits is omitted, the default is 1.

OTS-13

OTS$CVT_L_TU

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
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Size of the integer value to be converted, in bytes. The input-value-size
argument is a signed longword containing the size of the integer value. This
is an optional argument. If the size is omitted, the default is 4. The only
values that OTS$CVT_L_TU allows are l, 2 and 4. If any other value is
specified, OTS$CVT_L _TU uses the default value, 4 (longword).

CONDITION
VALUES
RETURNED

SS$_NORMAL
OTS$_0UTCONERR

Normal successful completion.
Output conversion error. The result would have
exceeded the fixed-length string; the output string
is filled with asterisks.

EXAMPLE
o
I
1
I
2
I
3
4
I
5
6
7
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FTTY
D F
7
TTY
C* Initialize numeric value to be converted.
C
Z-ADD32857
VALUE
90
C
Z-ADD7
DIGITS 90
C
CVTLTU
EXTRN'OTS$CVT_L_TU'
C* Convert the number to decimal in a string with 7 decimal digits.
C
CALL CVTLTU
RL
C
PARM
VALUE
C
PARMD
OUTSTR 7
C
PARMV
DIGITS
C* Display on the terminal the converted string.
C
OUTSTR
DSPLYTTY
C
SETON
LR
This RPG II program displays the string '0032857' on the terminal screen.

OTS-14

OTS$CVT_L_TZ

Convert Integer to Hexadecimal
Text

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

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

varying-input-value
, fixed-length-resultant-string
/,number-of-digits] [,input-value-size]

cond_value
longword (unsigned)
write only
by value

varying-input-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
read only
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
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
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 (DSC$K_CLASS_S).

number-of-digits
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
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. This is an optional
argument. 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

OTS-15

OTS$CVT_L_TZ

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
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Size of the integer that OTS$CVT_L_TZ converts, in bytes. The inputvalue-size argument is a signed longword containing the value size. This is
an optional argument. If the size is omitted, the default is 4 (longword).

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

OTS$_0UTCONERR

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-16

OTS$CVT_TB_L

OTS$CVT_TB_L Convert Binary Text to Unsigned
Integer
The Convert Binary Text to Unsigned Integer routine converts an ASCII
text string representation of an unsigned binary value to an unsigned
integer value of arbitrary length. By default, the result is a longword. Valid
input characters are the blank and the digits 0 and 1. No sign is permitted.

FORMAT

OTS$CVT_TB_L

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

input-string, varying-output-value
{,output-value-size]{, flags-value]

cond_value
longword (unsigned)
write only
by value

input-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Input string containing the string representation of an unsigned binary
value that OTS$CVT_TB_L converts to an integer value. The input-string
argument is the address of a descriptor pointing to the string.

varying-output-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
write only
by reference

Unsigned byte, word, or longword that OTS$CVT_TB_L creates when it
converts the ASCII text string. (The value of the output-value-size argument
determines whether varying-output-value is a byte, word, or longword.)
The varying-output-value argument is the address of the unsigned integer.

output-value-size
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Number of bytes to be occupied by the value created when OTS$CVT_TB_L
converts the ASCII text string to an integer value. The output-value-size
argument contains the value size. If output-value-size contains a zero or
a negative number, OTS$CVT_TB_L returns an error code as the condition
value. This is an optional argument. Valid values for the output-value-size
argument are 1, 2, and 4; the contents determine whether the integer value

OTS-17

OTS$CVT_TB_L

that OTS$CVT_TB_L creates is a byte, word, or longword. If the number of
bytes is omitted, the default is 4 (longword).

flags-value
VMS usage: mask_longword
type:
longword (unsigned)
access:
read only
mechanism: by value

User-supplied flags that OTS$CVT_TB_L uses to determine how to interpret
blanks and tabs. The flags-value argument contains the value of the usersupplied flags.
The flags are defined as follows:
Bit

Description

If set, OTS$CVT_TB_L ignores blanks. If clear, OTS$CVT_TB_L
interprets blanks as zeros.

If set, OTS$CVT_TB_L ignores tabs. If clear, OTS$CVT_TB_L
interprets tabs as invalid characters.

This is an optional argument. The default is that all bits are clear.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

OTS$_1NPCONERR

Input conversion error. An invalid character,
overflow, or invalid input-value-size occurred.

EXAMPLE
1

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
! 2AO + 2A4
EXTERNAL LONG FUNCTION OTS$CVT_TB_L (STRING, LONG, &
LONG BY VALUE, LONG BY VALUE)
!+

MAIN PROGRAM

OTS-18

OTS$CVT_TB_L

!+
!
!-

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-19

OTS$CVT_Tl_L

Convert Signed Integer Text to
Integer

The Convert Signed Integer Text to Integer routine converts an ASCII
text string representation of a decimal number to a signed byte, word, or
longword integer value. The result is a longword by default, but the calling
program can specify a byte or a word value instead.

FORMAT

OTS$CVT_Tl_L

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

fixed-or-dynamic-input-string
, varying-output-value
[,output-value-size][, flags-value}

cond_value
longword (unsigned)
write only
by value

fixed-or-dynamic-input-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor, fixed-length or dynamic string

Input ASCII text string that OTS$CVT_TI_L converts to a signed byte, word,
or longword. 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:
[+ or -]

<integer-digits>

OTS$CVT_TI_L always ignores leading blanks. A decimal point is assumed
at the right of the input string.

varying-output-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
write only
by reference

Unsigned byte, word, or longword that OTS$CVT_TI_L creates when it
converts the ASCII text string. (The value of the output-value-size argument
determines whether varying-output-value is a byte, word, or longword.)
The varying-output-value argument is the address of the unsigned integer.

output-value-size
VMS usage:
type:
access:
mechanism:

OTS-20

longword_signed
longword (signed)
read only
by value

OTS$CVT_Tl_L

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. If output-value-size contains a zero
or a negative number, OTS$CVT_TI_L returns an error code as the condition
value. This is an optional argument. Valid values for the output-value-size
argument are 1, 2, and 4; the contents determine whether the integer value
that OTS$CVT_TI_L creates is a byte, word, or longword. If the number of
bytes is omitted, the default is 4 (longword).

flags-value
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
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

Description

If set, OTS$CVT_Tl_L ignores all blanks. If clear, OTS$CVT_Tl_L
ignores leading blanks but interprets blanks after the first legal character
as zeros.

If set, OTS$CVT_Tl_L ignores tabs. If clear, OTS$CVT_Tl_L interprets
tabs as invalid characters.

This is an optional argument. If flags-value is omitted, the default is that all
bits are cleared.

CONDITION
VALUES
RETURNED

SS$_NQRMAL

Normal successful completion.

OTS$_1NPCONERR

Input conversion error: an invalid character in
the input string; or the value overflows byte,
word, or longword; or input-value-size is invalid.
Varying-input-value is set to zero.

OTS-21

OTS$CVT_TL_L

OTS$CVT_TL_L Convert Logical Text to Integer
The Convert Logical Text to Integer routine converts an ASCII text string
representation of a FORTRAN-77 L format to a byte, word, or longword
integer value. The result is a longword by default, but the calling program
can specify a byte or a word value instead.

FORMAT

OTS$CVT_TL_L

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

fixed-or-dynamic-input-string
, varying-output-value
[,output-value-size]

cond_value
longword (unsigned)
write only
by value

fixed-or-dynamic-input-string
VMS usage:
type:
access:
mechanism:

char-string
character string
read only
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 byte, word, or longword integer
value. 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 either of the following:
Blank (end of string)
Blank Period Letter Character (end of string)

The elements in the preceding input string are defined as follows:
Term

Description

Blank

Zero or more blanks

Period

. or nothing

Letter

T, t, F, or f

Character

Zero or more of any character

varying-output-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
write only
by reference

Unsigned byte, word, or longword that OTS$CVT_TL _L creates when it
converts the ASCII text string. (The value of the output-value-size argument

OTS-22

OTS$CVT_TL_L
determines whether varying-output-value is a byte, word, or longword.)
The varying-output-value argument is the address of the unsigned 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
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Number of bytes to be occupied by the value created when OTS$CVT_TL_L
converts the ASCII text string to an integer value. The output-value-size
argument contains the number of bytes. If output-value-size contains a
zero or a negative number, OTS$CVT_TL _L returns an error code as the
condition value. This is an optional argument. Valid values for the outputvalue-size argument are 1, 2, and 4; the contents determine whether the
integer value that OTS$CVT_TI_L creates is a byte, word, or longword. If it
is omitted, the default is 4 (longword).

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

OTS$_1NPCONERR

Invalid character in the input string or invalid
input-value-size; varying-input-value is set to
zero.

OTS-23

OTS$CVT_TQ_L

OTS$CVT_TQ_L Convert Octal Text to Signed
Integer
The Convert Octal Text to Signed Integer routine converts an ASCII text
string representation of an octal value to a signed integer of an arbitrary
length. The result is a longword by default, but the calling program can
specify a byte, word, or longword.

FORMAT

OTS$CVT_TQ_L

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

fixed-or-dynamic-input-string
, varying-output-value
[,output-value-size] [,flags-value]

cond_value
longword (unsigned)
write only
by value

fixed-or-dynamic-input-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor, fixed-length or dynamic string

Input string containing an ASCII text string representation of an octal value
that OTS$CVT_TQ_L converts to a signed integer. The fixed-or-dynamicinput-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
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
write only
by reference

Signed byte, word, or longword that OTS$CVT_TQ_L creates when it
converts the ASCII text string. (The value of the output-value-size argument
determines whether varying-output-value is a byte, word, or longword.)
The varying-output-value argument is the address of the signed integer.

output-value-size
VMS usage:
type:
access:
mechanism:

longword_signed
longword integer {signed)
read only
by value

Number of bytes occupied by the signed integer value. The output-valuesize argument contains the number of bytes. If the content of the outputvalue-size argument is zero or a negative number, OTS$CVT_TQ_L returns

OTS-24

OTS$CVT_TQ_L -

an error. This is an optional argument. If the number of bytes is omitted, the
default is 4 (longword).

flags-value
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by value

User-supplied flags that OTS$CVT_TQ_L uses to determine how blanks
within the input string are interpreted. The flags-value argument contains
the user-supplied flags.
Bit 0

If set, OTS$CVT_TQ_L ignores all blanks. If clear, OTS$CVT_TQ_L
interprets blanks as zeros.

This is an optional argument. If flags-value is omitted, the default is that all
bits are clear.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

OTS$_1NPCONERR

Input conversion error. An invalid character,
overflow, or invalid input-value-size occurred.

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,
I* 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(!) 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; simply press CTRL/Z to quit.

OTS-25

OTS$CVT_TO_L

$ RUN OCTOL
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-26

OTS$CVT_TU_L

OTS$CVT_TU_L Convert Unsigned Decimal Text
to Integer
The Convert Unsigned Decimal Text to Integer routine converts an ASCII
text string representation of an unsigned decimal value to an unsigned
byte, word, or longword value. By default, the result is a longword. Valid
input characters are the space and the digits 0 through 9. No sign is
permitted.

FORMAT

OTS$CVT_TU_L

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

fixed-length-input-string
, varying-output-value
[,output-value-size][, flags-value]

cond_value
longword (unsigned)
write only
by value

fixed-length-input-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor, fixed-length

Input string (fixed-length) containing an ASCII text string representation of
an unsigned decimal value that OTS$CVT_TU_L converts to a byte, word, or
longword value. The fixed-length-input-string argument is the address of a
descriptor pointing to the input string.

varying-output-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
write only
by reference

Unsigned byte, word, or longword that OTS$CVT_TU_L creates when it
converts the ASCII text string. (The value of the output-value-size argument
determines whether varying-output-value is a byte, word, or longword.)
The varying-output-value argument is the address of the unsigned integer.

output-value-size
VMS usage:
type:
access:
mechanism:

longword_signed
longword integer (signed)
read only
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. OTS$CVT_TU_L allows value sizes of 1, 2 and 4. If any

OTS-27

OTS$CVT_TU_L

other value is specified, or if output-value-size is omitted, OTS$CVT_TU_L
uses the default, 4.

flags-value
VMS usage: mask_longword
longword {unsigned)
access:
read only
mechanism: by value

type:

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

Description

If set, OTS$CVT_TU_L ignores blanks. If clear, OTS$CVT_TU_L
interprets blanks as zeros.

If set, OTS$CVT_TU_L ignores tabs. If clear, OTS$CVT_TU_L interprets
tabs as invalid characters.

Flags-value is an optional argument. If it is omitted, the default is that all
bits are clear.

CONDITION
VALUES
RETURNED

OTS-28

SS$_NORMAL

Normal successful completion.

OTS$_1NPCONERR

Input conversion error. An invalid character,
overflow or invalid input-value-size occurred.

OTS$CVT_T_z

Convert Numeric Text to D- or
F-Floating Value

The Convert Numeric Text to D- or F-Floating routines convert an ASCII
text string representation of a numeric value to a D-floating or F-floating
value.

FORMAT

OTS$CVT_T_D

OTS$CVT_T_f

RETURNS

ARGUMENTS

VMS usage:
type:
access:
mechanism:

fixed-or-dynamic-input-string
, floating-point-value[, digits-in-fraction]
[,scale-factor][, flags-value]
[,extension-bits]
fixed-or-dynamic-input-string
, floating-point-value[, digits-in-fraction]
[,scale-factor] [,flags-value]
[,extension-bits]

cond_value
longword (unsigned)
write only
by value

fixed-or-dynamic-input-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor, fixed-length or dynamic string

Input string containing an ASCII text string representation of a numeric value
that OTS$CVT_T_z converts to a D-floating or F-floating value. The fixedor-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:
Blank Sign Digit Period Digitletter blank sign OR sign digit

The elements in the preceding input string are defined as follows:
Term

Description

Blank

Zero or more blanks

Sign

+, -, or nothing

Digit

Zero or more decimal digits

Period

. or nothing

Letter

E, e, 0, d, 0, or q

OTS-29

OTS$CVT_T_z

There is no difference in semantics among any of the six valid exponent
letters (E, e, D, d, Q, q).

floating-point-value
VMS usage: floating_point
type:
D_floating, f _floating
access:
write only
mechanism: by reference

Floating-point value that OTS$CVT_T_z creates when it converts the input
string. The floating-point-value argument is the address of the floating-point
value. For OTS$CVT_T_D, floating-point-value is a D-floating number. For
OTS$CVT_T_F, floating-point-value is an F-floating number.

digits-in-fraction
VMS usage: longword_unsigned
longword (unsigned)
access:
read only
mechanism: by value

type:

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. This is
an optional argument. If the number of digits is omitted, the default is zero.

scale-factor
VMS 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
rnscale-factor unless the exponent is present. If bit 6 of flags-value is set, the
scale factor is always applied. This is an optional argument. If the scale factor
is omitted, the default is zero.

flags-value
VMS usage: mask_longword
type:
longword (unsigned)
access:
read only
mechanism: by value

User-supplied flags. The flags-value argument contains the user-supplied
flags.

OTS-30

Bit 0

If set, OTS$CVT_T_z ignores blanks. If clear, OTS$CVT_T_z
interprets blanks as zeros.

Bit 1

If set, OTS$CVT_T_z allows only E ore exponents. If clear,
OTS$CVT_T_z allows E, e, D, d, Q and q exponents. (Bit 1 is
clear for BASIC and set for FORTRAN.)

Bit 2

If set, OTS$CVT_T_z interprets an underflow as an error. If
clear, OTS$CVT_T_z does not interpret an underflow as an
error.

Bit 3

If set, OTS$CVT_T_z truncates the value. If clear, OTS$CVT_
T-z rounds the value.

OTS$CVT_T_z

Bit 4

If set, OTS$CVT_T_z ignores tabs. If clear, OTS$CVT_T_z
interprets tabs as invalid characters.

Bit 5

If set, an exponent must begin with a valid exponent letter. If
clear, the exponent letter can be omitted.

Bit 6

If set, OTS$CVT_ T_z always applies the scale factor. If clear,
OTS$CVT_T_z applies the scale factor only if there is no
exponent present in the string.

If flags-value is omitted, all bits are clear.

extension-bits
VMS usage:
type:
access:
mechanism:

byte_signed
byte (signed)
write only
by reference

Extra precision bits. The extension-bits argument is the address of a byte
containing the extra precision bits. If extension-bits is present, floatingpoint-value is not rounded, and the first n bits after truncation are returned
in this argument. For D-floating and F-floating values, n equals 8 and the bits
are returned as a byte.
These values are suitable for use as the extension operand in an EMOD
instruction.

DESCRIPTION

These routines support FORTRAN D, E, F, and G input type conversion as
well as similar types for other languages.
OTS$CVT_T_D and OTS$CVT_T_F provide run-time support for BASIC and
FORTRAN input statements.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

OTS$_1NPCONERR

Input conversion error; an invalid character in the
input string, or the value is outside the range that
can be represented. Floating-point-value is 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.

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)
FORMAT(' Input string ',!1,' is ',A10)

OTS-31

OTS$CVT_T_z

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

B = OTS$CVT_T_F(T(I),A,%VAL(5), ,)
TYPE*·' Output of OTSCVT_T_F is
TYPE *,'
CONTINUE
END

',A

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
Input string 2 is 8.786534+3
Output of OTSCVT_T_F is
Input string 3 is -983476E-3
Output of OTSCVT_T_F is
Input string 4 is -23.734532
Output of OTSCVT_T_F is
Input string 5 is 45
Output of OTSCVT_T_F is

OTS-32

1.2345669E+24
8786.534
-9.8347599E-03
-23.73453
45000.00

OTS$CVT_T_z

Convert Numeric Text to G- or ·
H-Floating Value

The Convert Numeric Text to G- or H-Floating routines convert an ASCII
text string representation of a numeric value to a G-floating or H-floating
value.

FORMAT

OTS$CVT_T_G

OTS$CVT_T_H

RETURNS

ARGUMENTS

VMS usage:
type:
access:
mechanism:

fixed-or-dynamic-input-string
, floating-point-value {,digits-in-fraction]
{,scale-factor]{, flags-value}
{,extension-bits]
fixed-or-dynamic-input-string
, floating-point-value{, digits-in-fraction]
{,scale-factor]{, flags-value]
{,extension-bits]

cond.......value
longword (unsigned)
write only
by value

fixed-or-dynamic-input-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor, fixed-length or dynamic string

Input string containing an ASCII text string representation of a numeric value
that OTS$CVT_T_z converts to a G-floating or H-floating value. The fixedor-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:
Blank Sign Digit Period Digitletter blank sign OR sign digit

The elements in the preceding input string are defined as follo'ws:
Term

Description

Blank

Zero or more blanks

Sign

+, -, or nothing

Digit

Zero or more decimal digits

Period

. or nothing

Letter

E, e, D, d, Q, or q

OTS-33

OTS$CVT_T_z

There is no difference in semantics among any of the six valid exponent
letters (E, e, D, d, Q, q).

floating-point-value
VMS usage:
type:
access:
mechanism:

floating_point
G_floating, H_floating
write only
by reference

Floating-point value that OTS$CVT_T_z creates when it converts the input
string. The floating-point-value argument is the address of the floating-point
value. For OTS$CVT_T_G, floating-point-value is a G-floating number. For
OTS$CVT_T_H, floating-point-value is an H-floating number.

digits-in-fraction
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by value

scale-factor
VMS 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
1oscale-factor unless the exponent is present. If bit 6 of flags-value is set, the
scale factor is always applied. This is an optional argument. If the scale factor

is omitted, the default is zero.

flags-value
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by value

User-supplied flags. The flags-value argument contains the user-supplied
flags.
·

OTS-34

Bit 0

If set, OTS$CVT_T_z ignores blanks. If clear, OTS$CVT_T_z interprets
blanks as zeros.

Bit 1

If set, OTS$CVT_T_z allows only E ore exponents. If clear, OTS$CVT_
T_z allows E, e, D, d, Q and q exponents. (Bit 1 is clear for BASIC and
set for FORTRAN.)

Bit 2

If set, OTS$CVT_ T_z interprets an underflow as an error. If clear,
OTS$CVT_ T_z does not interpret an underflow as an error.

Bit 3

If set, OTS$CVT_ T_z truncates the value. If clear, OTS$CVT_ T-z
rounds the value.

OTS$CVT_T_z

Bit 4

If set, OTS$CVT_T_z ignores tabs. If clear, OTS$CVT_T_z interprets
tabs as invalid characters.

Bit 5

If set, an exponent must begin with a valid exponent letter. If clear, the
exponent letter may be omitted.

Bit 6

If set, OTS$CVT_ T_z always applies the scale factor. If clear,
OTS$CVT_ T_z applies the scale factor only if there is no exponent
present in the string.

If flags-value is omitted, all bits are clear.

extension-bits
VMS usage: word_signed
type:
word (signed)
access:
write only
mechanism: by reference

Extra precision bits. The extension-bits argument is the address of a signed
word integer containing the extra precision bits. If present, floating-pointvalue is not rounded, and the first n bits after truncation are returned in this
argument. For G-floating and H-floating, n equals 11 and 15, respectively,
and the bits are returned as a word, left-justified.
These values are suitable for use as the extension operand in an EMOD
instruction.
The extra precision bits returned for H-floating may not be precise because
calculations are only carried to 128 bits. However, the error should be small.

DESCRIPTION

These routines support FORTRAN D, E, F, and G input type conversion as
well as similar types for other languages.
OTS$CVT_T_G and OTS$CVT_T_H provide run-time support for BASIC
and FORTRAN input statements.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

OTS$_1NPCONERR

Input conversion error; an invalid character in the
input string, or the value is outside the range that
can be represented. Floating-point-value is set to
+0.0 (not reserved operand -0.0).

OTS-35

OTS$CVT_TZ_L

Convert Hexadecimal Text to
Unsigned Integer

The Convert Hexadecimal Text to Unsigned Integer routine converts an
ASCII text string representation of an unsigned hexadecimal value to
an unsigned integer of an arbitrary length. The result is a longword by
default, but the calling program can specify a byte, word, or longword
value.

FORMAT

OTS$CVT_TZ_L

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

fixed-or-dynamic-input-string
, varying-output-value
{,output-value-size] {,flags-value]

cond_value
longword (unsigned)
write only
by value

fixed-or-dynamic-input-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor, fixed-length or dynamic string

Input string containing an ASCII text 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. Valid input characters are the space, the digits
0 through 9, and the letters A through F (lowercase letters a through f are
acceptable). No sign is permitted.

varying-output-value
VMS usage:
type:
access:
mechanism:

varying_arg
unspecified
write only
by reference

Unsigned byte, word, or longword that OTS$CVT_TZ_L creates when it
converts the ASCII text string. (The value of the output-value-size argument
determines whether varying-output-value is a byte, word, or longword.)
The varying-output-value argument is the address of the unsigned integer.

output-value-size
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Number of bytes occupied by the integer value. The output-value-size
argument contains the number of bytes. If the value size is zero or a negative

OTS-36

OTS$CVT_TZ_L

number, OTS$CVT_TZ_L returns an input conversion error. This is an
optional argument. If the number of bytes is omitted, the default is 4
(longword).

flags-value
VMS usage: mask_longword
longword (unsigned)
access:
read only
mechanism: by value

type:

User-supplied flags that OTS$CVT_TZ_L uses to determine how blanks are
interpreted. The flags-value argument is an unsigned longword containing
these user-supplied flags.
Bit 0

If set, OTS$CVT_TZ_L ignores blanks. If set, OTS$CVT_TZ_L
interprets blanks as zeros.

This is an optional argument. If flags-value is omitted, the default is that all
bits are clear.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

OTS$_1NPCONERR

Input conversion error. An invalid character,
overflow, or invalid output-value-size occurred.

EXAMPLES

!+
! 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 11 ;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

OTS-37

OTS$CVT_TZ_L

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 ASTS$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 types
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:

OTS-38

CTRL/Z

OTS$DIVCx

OTS$DIVCx Complex Division
The Complex Division routines return a complex result of a division on
complex numbers.

FORMAT

OTS$DIVC complex-dividend ,complex-divisor
OTS$DIVCD_R3 complex-dividend ,complex-divisor
OTS$DIVCG_R3 complex-dividend ,complex-divisor
Each of these three formats corresponds to one of the three floating-point
complex types.

RETURNS

VMS usage: complex_number
f _floating complex, D_floating complex, G_floating
type:
complex
access:
write only
mechanism: by value

Complex result of complex division. OTS$DIVC returns an F-floating
complex number. OTS$DIVCD_R3 returns a D-floating complex number.
OTS$DIVCG_R3 returns a G-floating complex number.

ARGUMENTS

complex-dividend
VMS usage: complex_number
type:
F_floating complex, D_floating complex, G_floating
complex
access:
read only
mechanism: by value

Complex dividend. The complex-dividend argument contains a floatingpoint complex value. For OTS$DIVC, complex-dividend is an F-floating
complex number. For OTS$DIVCD_R3, complex-dividend is a D-floating
complex number. For OTS$DIVCG_R3, complex-dividend is a G-floating
complex number.

complex-divisor
VMS usage: complex_number
type:
F_floating complex, D_floating complex, G_floating
complex
access:
read only
mechanism: by value

Complex divisor. The complex-divisor argument contains the value of the
divisor. For OTS$DIVC, complex-divisor is an F-floating complex number.
For OTS$DIVCD_R3, complex-divisor is a D-floating complex number. For
OTS$DIVCG_R3, complex-divisor is a G-floating complex number.

OTS-39

OTS$DIVCx

DESCRIPTION

These routines return a complex result of a division on complex numbers.
The complex result is computed as follows:
1

Let (a,b) represent the complex dividend.

Let (c,d) represent the complex divisor.

Let (r,i) represent the complex quotient.

The results of this computation are as follows:

r = (ac + bd)/(c 2 + d2 )
i =(be - ad)/(c 2 + d2 )

CONDITION
VALUES
SIGNALED

SS$_FLTDIV_F

Arithmetic fault. Floating-point division by zero.

SS$_FL TOV_F

Arithmetic fault. Floating-point overflow.

EXAMPLES

C+

c
c
c

c
c
c
c
c

This FORTRAN example forms the complex
quotient of two complex numbers using
OTS$DIVC and the FORTRAN random number
generator RAN.
Declare Z1, Z2, Z_Q, and OTS$DIVC as complex values.
OTS$DIVC will return the complex quotient of Z1 divided
by Z2: Z_Q = OTS$DIVC( %VAL(REAL(Z1)), %VAL(AIMAG(Z1),
%VAL(REAL(Z2)), %VAL(AIMAG(Z2))
COMPLEX Z1,Z2,Z_Q,OTS$DIVC

C+

Generate a complex number.
Z1 = (8.0,4.0)

C+

Generate another complex number.
Z2 = (1. 0 , 1. 0)

C+

Compute the complex quotient of Z1/Z2.

Z_Q = OTS$DIVC( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), %VAL(REAL(Z2)),
%VAL(AIMAG(Z2)))
TYPE*· 'The complex quotient of' ,Z1,' divided by ',Z2,' is'
TYPE*· '
',Z_Q
END

This FORTRAN program demonstrates how to call OTS$DIVC. The output
generated by this program is as follows:
The complex quotient of (8.000000,4.000000) divided by
(6.000000,-2.000000)

OTS-40

(1.000000,1.000000) is

OTS$DIVCx

C+

C
C
C
C

This FORTRAN example forms the complex
quotient of two complex numbers by using
OTS$DIVCG_R3 and the FORTRAN random number
generator RAN.

C
C
C

Declare Z1, Z2, and Z_Q as complex values. OTS$DIVCG_R3
will return the complex quotient of Z1 divided by Z2:
Z_Q = Z1/Z2

COMPLEX*16 Z1,Z2,Z_Q
C+

Generate a complex number.
Z1 = (8.0,4.0)

C+

Generate another complex number.
Z2 = (1. 0, 1. 0)

C+

Compute the complex quotient of Z1/Z2.
Z_Q = Z1/Z2
TYPE*· 'The complex quotient of',Z1,' divided by ',Z2,' is'
TYPE*· '
',Z_Q
END

This FORTRAN example uses the OTS$DIVCG_R3 entry point instead.
Notice the difference in the precision of the output generated:
The complex quotient of (8.000000000000000,4.000000000000000) divided by
(1.000000000000000,1.000000000000000) is
(6.000000000000000.~2.000000000000000)

OTS-41

OTS$DIV_PK_LQNG

OTS$DIV._PK_LONG

Packed Decimal Division
with Long Divisor

The Packed Decimal Division with Long Divisor routine divides fixed-point
decimal data, which is stored in packed decimal form, when precision and
scale requirements for the quotient call for multiple precision division. The
divisor must have a precision of thirty or thirty-one digits.

FORMAT

OTS$DIV_PK_LQNG

RETURNS

None.

ARGUMENTS

packed-decimal-dividend
,packed-decimal-divisor
, divisor-precision
,packed-decimal-quotient
, quotient-precision
,precision-data ,scale-data

packed-decimal-dividend
VMS usage:
type:
access:
mechanism:

varying_arg
packed decimal string
read only
by reference

Dividend. The packed-decimal-dividend argument is the address of a
packed decimal string that contains the shifted dividend.
Before being passed as input, the packed-decimal-dividend argument is
always multiplied by 10c where c is defined as follows:
c = 31 - prec(packed-decimal-dividend)

Mutiplying packed-decimal-dividend by 10c makes packed-decimaldividend a 31-digit number.

packed-decimal-divisor
VMS usage:
type:
access:
mechanism:

varying_arg
packed decimal string
read only
by reference

Divisor. The packed-decimal-divisor argument is the address of a packed
decimal string that contains the divisor.

divisor-precision
VMS usage:
type:
access:
mechanism:

OTS-42

word_signed
word (signed)
read only
by value

OTS$DIV_PK_LQNG

Precision of the divisor. The divisor-precision argument is a signed word
that contains the precision of the divisor. The high-order bits are filled with
zeros.

packed-decimal-quotient
VMS usage: varying_arg
packed decimal string
access:
write only
mechanism: by reference

type:

Quotient. The packed-decimal-quotient argument is the address of the
packed decimal string into which OTS$DIV_PK_LONG writes the quotient.

quotient-precision
VMS usage: word_signed
type:
word (signed)
access:
read only
mechanism: by value

Precision of the quotient. The quotient-precision argument is a signed word
that contains the precision of the quotient. The high-order bits are filled with
zeros.

precision-data
VMS usage: word_signed
word (signed)
access:
read only
mechanism: by value

type:

Additional digits of precision required. The precision-data argument is a
signed word that contains the value of the additional digits of precision
required.
OTS$DIV_PK_LONG computes the precision-data argument as follows:
precision-data = scale(packed-decimal-quotient)
+ scale(packed-decimal-divisor)
- scale(packed-decimal-dividend)
- 31 + prec(packed-decimal-dividend)

scale-data
VMS usage: word_signed
type:
word (signed)
access:
read only
mechanism: by value

Scale factor of the decimal point. The scale-data argument is a signed word
that contains the scale data.
OTS$DIV_PK_LONG defines the scale-data argument as follows:
scale-data = 31 - prec(packed-decimal-divisor)

OTS-43

OTS$DIV_PK_LQNG

DESCRIPTION

Before using this routine, you should determine whether it is best to use
OTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the VAX instruction DIVP.
To determine this, you must first calculate b, where b is defined as follows:
b = scale(packed-decimal-quotient)
+ scale(packed-decimal-divisor)
- scale(packed-decimal-dividend)
+ prec(packed-decimal-dividend)

If b is greater than 31, then OTS$DIV_PK_LONG can be used to perform the
division. If b is less than 31, you could use the instruction DIVP instead.

Once you have determined that you cannot use DIVP, you need to determine
whether you should use OTS$DIV_PK_LONG or OTS$DIV_PK_SHORT. To
determine this, you must examine the value of scale-data. If scale-data is less
than or equal to 1, then you should use OTS$DIV_PK_LONG. If scale-data
is greater than 1, you should use OTS$DIV_PK_SHORT instead.

CONDITION
VALUE
SIGNALED

SS$_FLTDIV

Fatal error. Division by zero.

EXAMPLE
1

OPTION
TYPE = EXPLICIT

This program uses OTS$DIV_PK_LONG to perform packed decimal
division.
!!+

DECLARATIONS

DECLARE DECIMAL (31, 2)
DECLARE DECIMAL (30, 3)
DECLARE DECIMAL (10, 5)

NATIONAL_DEBT
POPULATION
PER_CAPITA_DEBT

EXTERNAL SUB OTS$DIV_PK_LONG (DECIMAL(31,2), DECIMAL (30, 3), &
WORD BY VALUE, DECIMAL(10, 5), WORD BY VALUE, WORD BY VALUE, &
WORD BY VALUE)
!+

Prompt the user for the required input.

INPUT
INPUT

OTS-44

"Enter national debt: ";NATIONAL_DEBT
"Enter current population: ";POPULATION

OTS$DIV_PK_LONG

Perform the division and print the result.
scale(divd) = 2
scale(divr) = 3
scale(quot) = 5
prec(divd)
prec(divr)
prec(quot)

31
30
10

prec-data

scale(quot) + scale(divr) - scale(divd) - 31 +
prec(divd)
prec-data
5
+
3
2
- 31 +
31
prec-data = 6
b
b
b

scale(quot) + scale(divr) - scale(divd) + prec(divd)
5
+
3
2
+
31
37

c = 31 - prec(diyd)
c = 31 31
c =0
scale-data = 31 - prec(divr)
scale-data = 31 30
scale-data = 1
bis greater than 31, so either OTS$DIV_PK_LONG or
OTS$DIV_PK_SHORT may be used to perform the division.
If b is less than or equal to 31, then the DIVP
instruction may be used.
scale-data is less than or equal to 1, so OTS$DIV_PK_LONG
should be used instead of OTS$DIV_PK_SHORT.
!-

CALL OTS$DIV_PK_LONG( NATIONAL_DEBT, POPULATION, '30'W, PER_CAPITA_DEBT, &
, 10, w
I

PRINT
END

6, w
I

1 , W)

"The per capita debt is ";PER_CAPITA_DEBT

This BASIC example program uses OTS$DIV_PK_LONG to perform packed
decimal division. One example of the output generated by this program is as
follows:
$ RUN DEBT
Enter national debt: ? 12345678
Enter current population: ? 1212
The per capita debt is 10186.20297

OTS-45

OTS$DIV_PK_SHORT

OTS$DIV._PK_SHORT

Packed Decimal Division
with Short Divisor

The Packed Decimal Division with Short Divisor routine divides fixed-point
decimal data when precision and scale requirements for the quotient call
for multiple-precision division.

FORMAT

OTS$DIV_PK_SHORT packed-decimal-dividend
,packed-decimal-divisor
, divisor-precision
,packed-decimal-quotient
,quotient-precision
,precision-data

RETURNS
ARGUMENTS

None.

packed-decimal-dividend
VMS usage:
type:
access:
mechanism:

varying_arg
packed decimal string
read only
by reference

Multiplying packed-decimal-dividend by 10c makes packed-decimaldividend a 31-digit number.

packed-decimal-divisor
VMS usage:
type:
access:
mechanism:

varying_arg
packed decimal string
read only
by reference

Divisor. The packed-decimal-divisor argument is the address of a packed
decimal string that contains the divisor.

divisor-precision
VMS usage:
type:
access:
mechanism:

OTS-46

word_signed
word (signed)
read only
by value

OTS$DIV_PK_SHORT

Precision of the divisor. The divisor-precision argument is a signed word
integer that contains the precision of the divisor. The high-order bits are filled
with zeros.

packed-decimal-quotient
VMS usage: varying_arg
type:
packed decimal string
access:
write only
mechanism: by reference

Quotient. The packed-decimal-quotient argument is the address of a packed
decimal string into which OTS$DIV_PK_SHORT writes the quotient.

quotient-precision
VMS usage: word_signed
type:
word (signed)
access:
read only
mechanism: by value

Precision of the quotient. The quotient-precision argument is a signed word
that contains the precision of the quotient. The high-order bits are filled with
zeros.

precision-data
VMS usage: word_signed
type:
word (signed)
access:
read only
mechanism: by value

Additional digits of precision required. The precision-data argument is a
signed word that contains the value of the additional digits of precision
required.
OTS$DIV_PK_SHORT computes the precision-data argument as follows:
precision-data = scale(packed-decimal-quotient)
+ scale(packed-decimal-diviaor)
- scale(packed-decimal-dividend)
- 31 + prec(packed-decimal-dividend)

DESCRIPTION

Before using this routine, you should determine whether it is best to use
OTS$DIV_PK_LONG, OTS$DIV_pK_SHORT, or the VAX instruction DIVP.
To determine this, you must first calculate b, where b is defined as follows:
b = scale(packed-decimal-quotient) + scale(packed-decimal-diviaor) scale(packed-decimal-dividend) + prec(packed-decimal-dividend)

If b is greater than 31, then OTS$DIV_PK_SHORT can be used to perform
the division. If b is less than 31, you could use the VAX instruction DIVP
instead.

Once you have determined that you cannot use DIVP, you need to determine
whether you should use OTS$DIV_pK_LQNG or OTS$DIV_PK_SHORT. To
determine this, you must examine the value of scale-data. If scale-data is less
than or equal to 1, then you should use OTS$DIV_PK_LONG. If scale-data
is greater than 1, you should use OTS$DIV_PK_SHORT instead.

OTS-47

OTS$DIV_PK_SHORT

CONDITION
VALUE
SIGNALED

OTS-48

SS$_FLTDIV

Fatal error. Division by zero.

OTS$MOVE3

Move Data Without Fill

The Move Data Without Fill routine moves up to 2 31 -1 bytes
(2, 147,483 ,64 7 bytes) from a specified source address to a specified
destination address.

FORMAT

OTS$MOVE3

length-value ,source-array
, destination-array

corresponding jsb OTS$MOVE3_R5
entry point
RETURNS
ARGUMENTS

None.

length-value
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Number of bytes of data to move. The length-value argument is a signed
longword that contains the number of bytes to move. The value of lengthvalue may range from 0 to 2,147,483,647 bytes.

source-array
VMS usage:
type:
access:
mechanism:

vector_byte_unsigned
byte (unsigned)
read only
by reference, array reference

Data to be moved by OTS$MOVE3. The source-array argument contains the
address of an unsigned byte array that contains this data.

destination-array
VMS usage:
type:
access:
mechanism:

vector_byte_unsigned
byte (unsigned)
write only
by reference, array reference

Address into which source-array will be moved. The destination-array
argument is the address of an unsigned byte array into which OTS$MOVE3
writes the source data.

OTS-49

OTS$MOVE3

DESCRIPTION

OTS$MOVE3 performs the same function as the VAX MOVC3 instruction
except that the length-value is a longword integer rather than a word integer.
When called from the JSB entry point, the register outputs of OTS$MOVE3_
RS follow the same pattern as those of the MOVC3 instruction:
RO

Address of one byte beyond the source string

Address of one byte beyond the destination string

For more information, see the description of the MOVC3 instruction in the

VAX Architecture Manual. See also the routine LIB$MOVC3, which is a
callable version of the MOVC3 instruction.

CONDITION
VALUES
RETURNED

OTS-50

None.

OTS$MOVE5

Move Data with Fill

The Move Data with Fill routine moves up to 2 31 -1 bytes
(2, 147 ,483 ,64 7 bytes) from a specified source address to a specified
destination address, with separate source and destination lengths, and
with fill. Overlap of the source and destination arrays does not affect the
result.

FORMAT

OTS$MOVE5

longword-int-source-length ,source-array
, fill-value ,longword-int-dest-length
, destination-array

corresponding jsb OTS$MOVE5_R5
entry point
RETURNS
ARGUMENTS

None.

longword-int-source-length
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Number of bytes of data to move. The longword-int-source-length
argument is a signed longword that contains this number. The value of
longword-int-source-length may range from 0 to 2,147,483,647.

source-array
VMS usage:
type:
access:
mechanism:

vector_byte_unsigned
byte (unsigned)
read only
by reference, array reference

Data to be moved by OTS$MOVE5. The source-array argument contains the
address of an unsigned byte array that contains this data.

fill-value
VMS usage:
type:
access:
mechanism:

byte_unsigned
byte (unsigned)
read only
by value

Character used to pad the source data if longword-int-source-length is
less than longword-int-dest-length. The fill-value argument contains the
address of an unsigned byte that is this character.

OTS-51

OTS$MOVE5

longword-int-dest-length
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Size of the destination area in bytes. The longword-int-dest-length
argument is a signed longword containing this size. The value of longwordint-dest-length may range from 0 through 2,147,483,647.

destination-array
VMS usage:
type:
access:
mechanism:

vector_byte_unsigned
byte (unsigned)
write only
by reference, array reference

Address into which source-array is moved. The destination-array argument
is the address of an unsigned byte array into which OTS$MOVES writes the
source data.

DESCRIPTION

OTS$MOVES performs the same function as the VAX MOVCS instruction
except that the longword-int-source-length and longword-int-dest-length
arguments are longword integers rather than word integers. When called
from the JSB entry point, the register outputs of OTS$MOVES_R5 follow the
same pattern as those of the MOVCS instruction:
RO

Number of unmoved bytes remaining in source string

Address of one byte beyond the source string

Address of one byte beyond the destination string

For more information, see the description of the MOVCS instruction in the
VAX Architecture Manual. See also the routine LIB$MOVCS, which is a
callable version of the MOVCS instruction.

CONDITION
VALUES
RETURNED

OTS-52

None.

OTS$MULCx

Complex Multiplication

The Complex Multiplication routines calculate the complex product of two
complex values.

FORMAT

OTS$MULCD_R3

complex-multiplier
, complex-multiplicand
OTS$MULCG_R3 complex-multiplier
, complex-multiplicand
These formats correspond to the D-floating and G-floating complex types.

RETURNS

VMS usage:
type:
access:
mechanism:

complex_number
O_floating complex, G_floating complex
write only
by value

Complex result of multiplying two complex numbers. OTS$MULCD_R3
returns a D-floating complex number. OTS$MULCG_R3 returns a G-floating
complex number.

ARGUMENTS

complex-multiplier
VMS usage:
type:
access:
mechanism:

complex_number
O_floating complex, G_floating complex
read only
by value

Complex multiplier. The complex-multiplier argument contains the complex
multiplier. For OTS$MULCD_R3, complex-multiplier is a D-floating
complex number. For OTS$MULCG_R3, complex-multiplier is a G-floating
complex number.

complex-multiplicand
VMS usage:
type:
access:
mechanism:

complex_number
O_floating complex, G_floating complex
read only
by value

Complex multiplicand. The complex-multiplicand argument contains the
complex multiplicand. For OTS$MULCD_R3, complex-multiplicand is a
D-floating complex number. For OTS$MULCG_R3, complex-multiplicand
is an F-floating complex number.

DESCRIPTION

OTS$MULCD_R3 and OTS$MULCG_R3 calculate the complex product of
two complex values.
The complex product is computed as follows:
1

Let (a,b) represent the complex multiplier.

OTS-53

OTS$MULCx

Let (c,d) represent the complex multiplicand.

Let (r,i) represent the complex product.

The results of this computation are as follows:
(a, b) * (e, d) = (ae - bd) + J=I(ad +be)
There! ore: r = ae - bd
There! ore: i =ad+ be

CONDITION
VALUES
SIGNALED

MTH$_FLOOVEMA T

Floating-point overflow in math library.

SS$_ROPRAND

Reserved operand. OTS$MULCx encountered
a floating-point reserved operand because of
incorrect user input. A floating-point reserved
operand is a floating-point datum with a sign bit
of 1 and a biased exponent of zero. Floating-point
reserved operands are reserved for future use by
DIGITAL.

EXAMPLE
C+

C
C
C

This FORTRAN example forms the product of
two complex numbers using OTS$MULCD_R3
and the FORTRAN random number generator RAN.

C
C
C

Declare Z1, Z2, and Z_Q as complex values. OTS$MULCD_R3
returns the complex product of Z1 times Z2:
Z_Q = Z1 * Z2

COMPLEX*16 Z1,Z2,Z_Q
C+

Generate a complex number.
Z1 = (8.0,4.0)

C+

Generate another complex number.
Z2 = (2.0,3.0)

C+

Compute the complex product of Z1*Z2.
Z_Q = Z1 * Z2
TYPE*· 'The complex product of',Z1,' times ',Z2,' is'
TYPE*· '
',Z_Q
END

This FORTRAN example uses OTS$MULCD_R3 to multiply two complex
numbers. The output generated by this program is as follows:
The complex product of (8.000000000000000,4.000000000000000) times
(2.000000000000000,3.000000000000000) is
(4.000000000000000,32.00000000000000)

OTS-54

OTS$POWCxCx

Raise a Complex Base to
a Complex Floating-Point
Exponent

The Raise a Complex Base to a Complex Floating-Point Exponent routines
raise a complex base to a complex exponent.

FORMAT

OTS$POWCC complex-base ,complex-exponent-value
OTS$POWCDCD_R3 complex-base
,complex-exponent-value
OTS$POWCGCG_R3 complex-base
, complex-exponent-value
Each of these three formats corresponds to one of the three floating-point
complex types.

RETURNS

VMS usage: complex_number
F_floating complex, O_floating complex, G_floating
type:
complex
access:
write only
mechanism: by value

Result of raising a complex base to a complex exponent. OTS$POWCC
returns an F-floating complex number. OTS$POWCDCD_R3 returns a
D-floating complex number. OTS$POWCGCG_R3 returns a G-floating
complex number.

ARGUMENTS

complex-base
VMS usage: complex_number
type:
f _floating complex, O_floating complex, G_floating
complex
access:
read only
mechanism: by value

Complex base. The complex-base argument contains the value of the base.
For OTS$POWCC, complex-base is an F-floating complex number. For
OTS$POWCDCD_R3, complex-base is a D-floating complex number. For
OTS$POWCGCG_R3, complex-base is a G-floating complex number.

complex-exponent-value
VMS usage: complex_number
type:
f _floating complex, D_floating complex, G_floating
complex
access:
read only
mechanism: by value

Complex exponent. The complex-exponent-value argument contains the
value of the exponent. For OTS$POWCC, complex-exponent-value is an

OTS-55

OTS$POWCxCx

F-floating complex number. For OTS$POWCDCD_R3, complex-exponentvalue is a D-floating complex number. For OTS$POWCGCG_R3, complexexponent-value is a G-floating complex number.

DESCRIPTION

OTS$POWCC, OTS$POWCDCD_R3 and OTS$POWCGCG-R3 raise a
complex base to a complex exponent. The American National Standard
FORTRAN-77 (ANSI X3.9-1978) defines complex exponentiation as follows:
xY = exp(y * log(x))

In this example, x and y are type COMPLEX.

CONDITION
VALUES
SIGNALED

MTH$_1NV ARGMA T

Invalid argument in math library. Base is (0.,0.).

MTH$_FLOOVEMA T

Floating-point overflow in math library.

SS$_ROPRAND

Reserved operand.

EXAMPLES

C+

c
c
c

This FORTRAN example raises a complex base to a complex
power using OTS$POWCC.

c
c

Declare Z1, Z2, Z3, and OTS$POWCC as complex values. Then OTS$POWCC
returns the complex result of Z1**Z2:
Z3 = OTS$POWCC(Z1,Z2),
where Z1 and Z2 are passed by value.

COMPLEX Z1,Z2,Z3,0TS$POWCC
C+

Generate a complex base.
Z1 = (2.0,3.0)

C+

Generate a complex power.

Z2 = (1.0,2.0)

C+

Compute the complex value of Z1**Z2.
+

Z3 = OTS$POWCC( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)),
%VAL(REAL(Z2)), %VAL(AIMAG(Z2)))
TYPE*· 'The value of',Z1,'**' ,Z2,' is',Z3
END

This FORTRAN example uses OTS$POWCC to raise an F-floating complex
base to an F-floating complex exponent.
The output generated by this program is as follows:
The value of (2.000000,3.000000)** (1.000000,2.000000) is
(-0.4639565,-0.1995301)

OTS-56

OTS$POWCxCx

C+

C
C

This FORTRAN example raises a complex base to a complex
power using OTS$POWCGCG_R3.

C
C

Declare Z1, Z2, and Z3 as complex values. OTS$POWCGCG_R3
returns the complex result of Z1**Z2: Z3 = Z1**Z2.

COMPLEX*16 Z1,Z2,Z3
C+

Generate a complex base.

Z1 = (2.0,3.0)

C+

Generate a complex power.

Z2 = (1.0,2.0)

C+

Compute the complex value of Z1**Z2.

Z3 = Z1**Z2
TYPE 1,Z1,Z2,Z3
FORMAT(' The value of (',F11.8, ',',F11.8, ')**(',F11.8,
',',F11.8,') is (',F11.8,',',F11.8,').')
END

This FORTRAN example program shows how to use OTS$POWCGCG_R3.
Notice the high precision in the output generated by this program:
The value of ( 2.00000000, 3.00000000)**( 1.00000000, 2.00000000) is
(-0.46395650,-0.46395650).

OTS-57

OTS$POWCxJ

Raise a Complex Base to a
Signed Longword Integer
Exponent

The Raise a Complex Base to a Signed Longword Integer Exponent
routines return the complex result of raising a complex base to an integer
exponent.

FORMAT

OTS$POWCJ

complex-base
,longword-integer-exponent
OTS$POWCDJ_R3 complex-base
,longword-integer-exponent
OTS$POWCGJ_R3 complex--base
,longword-integer-exponent
Each of these three formats corresponds to one of the three floating-point
complex types.

RETURNS

VMS usage: complex_number
f _floating complex, D_floating complex, G_floating
type:
complex
write only
access:
mechanism: by value

Complex result of raising a complex base to an integer exponent.
OTS$POWCJ returns an F-floating complex number. OTS$POWCDJ_R3
returns a D-floating complex number. OTS$POWCGJ_R3 returns a
G-floating complex number. In each format, the result and base are of the
same data type.

ARGUMENTS

complex-base
VMS usage: complex_number
type:
f _floating complex, D_floating complex, G_floating
complex
access:
read only
mechanism: by value

Complex base. The complex-base argument contains the complex base.
For OTS$POWCJ, complex-base is an F-floating complex number. For
OTS$POWCDJ_R3, complex-base is a D-floating complex number. For
OTS$POWCGJ_R3, complex-base is a G-floating complex number.

OTS-58

OTS$POWCxJ

longword-integer-exponent
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Exponent. The longword-integer-exponent argument is a signed longword
containing the exponent.

DESCRIPTION

OTS$POWCJ, OTS$POWCDJ-R3, and OTS$POWCGJ_R3 return the
complex result of raising a complex base to an integer exponent. The complex
result is as follows:
Base

Exponent

Result

Any

The product of (base•2t where i is each nonzero bit in
longword-integer-exponent

(0.,0.)

::;:o
<O

Undefined exponentiation

(1.0,0.0)

Not
(0.,0.)
Not
(0.,0.)

CONDITION
VALUES
SIGNALED

The product of (base•2i), where i is each nonzero bit in
longword-integer-exponent

SS$_FLTDIV

Floating-point division by zero.

SS$_FLTOVF

Floating-point overflow.

MTH$_UNDEXP

Undefined exponentiation.

EXAMPLE
C+

C
C

This FORTRAN example raises a complex base to
a NONNEGATIVE integer power using OTS$POWCJ.

C
C
C
C

Declare Z1, Z2, Z3, and OTS$POWCJ as complex values.
Then OTS$POWCJ returns the complex result of
Z1**Z2:
Z3 = OTS$POWCJ(Z1,Z2),
where Z1 and Z2 are passed by value.

COMPLEX Z1,Z3,0TS$POWCJ
INTEGER Z2
C+

Generate a complex base.
Z1 = (2.0,3.0)

C+

Generate an integer power.
Z2 = 2

OTS-59

OTS$POWCxJ

C+

Compute the complex value of Z1**Z2.

Z3 = OTS$POWCJ( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), %VAL(Z2))
TYPE 1,Z1,Z2,Z3
FORMAT(' The value of (',F10.8, ',',F11.8, ')**',Ii,' is
(',F11.8,',',F12.8,').')

END

The output generated by this FORTRAN program is as follows:
The value of (2.00000000, 3.00000000)**2 is
(-5.00000000, 12.00000000).

OTS-60

OTS$POWDD

Raise a D-floating Base to a
D-floating Exponent

The Raise a D-floating Base to a D-floating Exponent routine raises a
D-floating base to a D-floating exponent.

FORMAT

OTS$POWDD

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

D-floating-point-base
, D-f/oating-point-exponent

floating_point
O_floating
write only
by value

D-floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
O_floating
read only
by value

Base. The D-floating-point-base argument is a D-floating number containing
the base.

D-floating-point-exponent
VMS usage:
type:
access:
mechanism:

floating_point
O_floating
read only
by value

Exponent. The D-floating-point-exponent argument is a D-floating number
that contains the exponent.

DESCRIPTION

OTS$POWDD raises a D-floating base to a D-floating exponent.
The internal calculations and the floating-point result have the same precision
as the base value.
The D-floating result for OTS$POWDD is given by the following:

OTS-61

OTS$POWDD

Base

Exponent

Result

=0
=0
=0
<0
>0
>0
>0

>0
=0
<0

0.0
Undefined exponentiation
Undefined exponentiation

Any

Undefined exponentiation

2[exponent*log2(base)]

=0
<0

1.0
2 [ exponent*log2(base)]

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative, or if the base is negative.

CONDITION
VALUES
SIGNALED

OTS-62

MTH$_FLOOVEMA T

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled
if 0-floating-point-base is zero and D-floatingpoint-exponent is zero or negative, or if the
D-floating-point-base is negative.

OTS$POWDR

Raise a D-floating Base to an
F-floating Exponent

The Raise a D-floating Base to an F-floating Exponent routine raises a
D-floating base to an F-floating exponent.

FORMAT

OTS$POWDR

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

0-floating-point-base
,F-floating-point-exponent

floating_point
D_floating
write only
by value

D-floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
D_floating
read only
by value

Base. The D-floating-point-base argument is a D-floating number containing
the base.

F-floating-point-exponent
VMS usage:
type:
access:
mechanism:

floating_point
f_floating
read only
by value

Exponent. The F-floating-point-exponent argument is an F-floating number
that contains the exponent.

DESCRIPTION

OTS$POWDR raises a D-floating base to an F-floating exponent.
The internal calculations and the floating-point result have the same precision
as the base value.
OTS$POWDR converts the F-floating exponent to a D-floating number. The
D-floating result for OTS$POWDR is given by the following:

OTS-63

OTS$POWDR

Base

Exponent

Result

0.0

=0
=0

=0
<0

Undefined exponentiation

<0
>0

Any

Undefined exponentiation

2 [exponent* log2 (base)]

>0
>0

=0
<0

2 [exponent*log2(base)]

Undefined exponentiation

1.0

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative, or if the base is negative.

CONDITION
VALUES
SIGNALED

OTS-64

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_FLOOVEMA T

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled
if 0-floating-point-base is zero and F-floatingpoint-exponent is zero or negative, or if the
0-floating-point-base is negative.

OTS$POWDJ

Raise a D-floating Base to a
Longword Exponent

The Raise a D-floating Base to a Longword Exponent routine raises a
D-floating base to a longword exponent.

FORMAT

OTS$POWDJ

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

D-floating-point-base
,longword-integer-exponent

floating_point
D_floating
write only
by value

D-floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
D_floating
read only
by value

Base. The D-floating-point-base argument is a D-floating number containing
the base.

longword-integer-exponent
VMS usage:
type:
access:
mechanism:

longword_signed
longword {signed)
read only
by value

Exponent. The longword-integer-exponent argument is a signed longword
that contains the signed longword integer exponent.

DESCRIPTION

OTS$POWDJ raises a D-floating base to a longword exponent.
The internal calculations and the floating-point result have the same precision
as the base value.
The floating-point result is as follows:

OTS-65

OTS$POWDJ

Base

Exponent

Result

Any

Product of (base*2i) where i is each nonzero bit position in
longword-integer-exponent

1.0

Undefined exponentiation

1.0

1.0/ (base*i), where i is each nonzero bit position in
longword-integer-exponent

Undefined exponentiation

1.0/ (base*2i) where i is each nonzero bit position in
longword-integer-exponent

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative.

CONDITION
VALUES
SIGNALED

OTS-66

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_FLOOVEMA T

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled
if D-floating-point-base is zero and longwordinteger-exponent is zero or negative, or if the
D-floating-point-base is negative.

OTS$POWGG

Raise a G-floating Base to a
G-floating Exponent

The Raise a G-floating Base to a G-floating Exponent routine raises a
G-floating base to a G-floating exponent.

FORMAT

OTS$POWGG

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

G-floating-point-base
, G-floating-point-exponent

floating_point
G_floating
write only
by value

G-floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
G_floating
read only
by value

Base that OTS$POWGG raises to a G-floating exponent. The G-floatingpoint-base argument is a G-floating number containing the base.

G-floating-point-exponent
VMS usage:
type:
access:
mechanism:

floating_point
G_floating
read only
by value

Exponent to which OTS$POWGG raises the base. The G-floating-pointexponent argument is a G-floating number containing the exponent.

DESCRIPTION

OTS$POWGG raises a G-floating base to a G-floating exponent.
The internal calculations and the floating-point result have the same precision
as the base value.
The G-floating result for OTS$POWGG is as follows:

OTS-67

OTS$POWGG

Base

Exponent

Result

0.0

Undefined exponentiation

Any

Undefined exponentiation

2 [exponent*log2(base)]

1.0

2 [exponent* log2 (base)]

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative, or if the base is negative.

CONDITION
VALUES
SIGNALED

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_FLOOVEMA T

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponent. This error is signaled if
G-floating-point-base is zero and G-floatingpoint-exponent is zero or negative, or if
G-floating-point-base is negative.

EXAMPLE
C+

C
C
C

This example demonstrates the use of OTS$POWGG,
which raises a G-f loating point base
to a G-floating point power.
REAL*8 X,Y,RESULT,OTS$POWGG

C+

C
C
C
C
C
C

The arguments of OTS$POWGG are passed by value. FORTRAN can
only pass INTEGER and REAL*4 expressions as VALUE. Since
INTEGER and REAL*4 values are one longword long, while REAL*8
values are two longwords long, equate the base (and power) to
two-dimensional INTEGER vectors. These vectors will be passed
by VALUE.
INTEGER N(2) ,M(2)
EQUIVALENCE (N(1) ,X), (M(1) ,Y)
x = 8.0
y = 2.0

C+

C To pass X by value, pass N(1) and N(2) by value. Similarly for Y.

RESULT = OTS$POWGG(%VAL(N(1)),%VAL(N(2)),%VAL(M(1)),%VAL(M(2)))
TYPE*·' 8.0**2.0 IS ',RESULT

x = 9.0

y = -0.5

C+

OTS-68

OTS$POWGG

C
C

In FORTRAN, OTS$POWWGG is indirectly called by simply using the
exponentiation operator.
RESULT = X**Y
TYPE*·' 9.0**-0.5 IS ',RESULT
END

This FORTRAN example uses OTS$POWGG to raise a G-floating base to a
G-floating exponent.
The output generated by this example is as follows:
8.0**2.0 IS
9.0**-0.5 IS

64.0000000000000
0.333333333333333

OTS-69

OTS$POWGJ

Raise a G-floating Base to a
Longvvord Exponent

The Raise a G-floating Base to a Longword Exponent routine raises a
G-floating base to a longword exponent.

FORMAT

OTS$POWGJ

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

G-floating-point-base
, longword-integer-exponent

floating_point
G_floating
write only
by value

G-floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
G_floating
read only
by value

Base that OTS$POWGJ raises to a longword exponent. The G-floating-point-

base argument is a G-floating number containing the base.

longword-integer-exponent
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Exponent to which OTS$POWGJ raises the base. The longword-integerexponent argument is a signed longword containing the exponent.

DESCRIPTION

OTS$POWGJ raises a G-floating base to a longword exponent.
The internal calculations and the floating-point result have the same precision
as the base value.
The floating-point result is as follows:

OTS-70

OTS$POWGJ

Base

Exponent

Result

Any

Product of (base•i) where i is each nonzero bit position in
longword-integer-exponent

1.0

Undefined exponentiation

1.0

1.0/ (base•i), where i is each nonzero bit position in
longword-integer-exponent

Undefined exponentiation

1.0/ (base*2i) where i is each nonzero bit position in
longword-integer-exponent

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative.

CONDITION
VALUES
SIGNALED

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_FLOOVEMA T

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponent. This error is signaled if
G-floating-point-base is zero and longwordinteger-exponent is zero or negative, or if
G-floating-point-base is negative.

OTS-71

OTS$POWHH_R3

Raise an H-floating Base to an
H-floating Exponent

The Raise an H-floating Base to an H-floating Exponent routine raises an
H-floating base to an H-floating exponent.

FORMAT

OTS$POWHH_R3

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

H-f/oating-point-base
,H-floating-point-exponent

floating_point
H_floating
write only
by value

H-f/oating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
H _floating
read only
by value

Base. The ff-floating-point-base argument is an H-floating number
containing the base.

H-floating-point-exponent
VMS usage:
type:
access:
mechanism:

floating_point
H_floating
read only
by value

Exponent. The ff-floating-point-exponent argument is an H-floating number
that contains the H-floating exponent.

DESCRIPTION

OTS$POWHH_R3 raises an H-floating base to an H-floating exponent.
The internal calculations and the floating-point result have the same precision
as the base value.
The H-floating result for OTS$POWHH_R3 is as follows:

OTS-72

OTS$POWHH_R3

Base

Exponent

Result

0.0

Undefined exponentiation

<0
Any

1.0

2[exponent*log2(base)]

Undefined exponentiation
2[exponent*log2(base)]

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative, or if the base is negative.

CONDITION
VALUES
SIGNALED

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_FLOOVEMA T

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled
if H-floating-point-base is zero and H-floatingpoint-exponent is zero or negative, or if the
H-floating-point-base is negative.

EXAMPLE
C+

C Example of OTS$POWHH, which raises an H_floating
C point base to an H_floating point power. In FORTRAN,
C it is not directly called.

REAL*16 X,Y,RESULT

x = 9877356535.0

y = -0.5837653
C+

C In FORTRAN, OTS$POWWHH is indirectly called by simply using the
C exponentiation operator.

RESULT = X**Y
TYPE*·' 9877356535.0**-0.5837653 IS ',RESULT
END

This FORTRAN example demonstrates how to call OTS$POWHH_R3 to
raise an H-floating base to an H-floating power.
The output generated by this program is as follows:
9877356535.0**-0.5837653 IS

1.463779145994628357482343598205427E-0006

OTS-73

OTS$POWHJ_R3

Raise an H-floating Base to a
Longword Exponent

The Raise an H-floating Base to a Longword Exponent routine raises an
H-floating base to a longword exponent.

FORMAT

OTS$POWHJ_R3

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

H-f/oating-point-base
,longword-integer-exponent

floating_point
H_floating
write only
by value

H-floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
H_floating
read only
by value

Base. The ff-floating-point-base argument is an H-floating number
containing the base.

longword-integer-exponent
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Exponent. The longword-integer-exponent argument is a signed longword
that contains the signed longword exponent.

DESCRIPTION

OTS$POWHJ_R3 raises an H-floating base to a longword exponent.
The internal calculations and the floating-point result have the same precision
as the base value.

OTS-74

OTS$POWHJ_R3

The floating-point result is as follows:
Base

Exponent

Result

Any

Product of (base*2i) where i is each nonzero bit position in
longword-integer-exponent

>0
=0
<0

=0
=0
=0

1.0

1.0/ (base*2i), where i is each nonzero bit position in
longword-integer-exponent

=0
<0

<0
<0

Undefined exponentiation

Undefined exponentiation
1.0

1.0/ (base*2i) where i is each nonzero bit position in
longword-integer-exponent

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative.

CONDITION
VALUES
SIGNALED

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_FLOOVEMA T

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled
if H-floating-point-base is zero and longwordinteger-exponent is zero or negative, or if the
H-floating-point-base is negative.

OTS-75

OTS$POWll

Raise a Word Base to a Word
Exponent
The Raise a Word Base to a Word Exponent routine raises a word base to
a word exponent.

FORMAT

OTS$POWI I

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

word-integer-base , word-integer-expopent

word_signed
word (signed)
write only
by value

word-integer-base
VMS usage:
type:
access:
mechanism:

word_signed
word (signed)
read only
by value

Base. The word-integer-base argument is a signed word containing the base.

word-integer-exponent
VMS usage:
type:
access:
mechanism:

word_signed
word (signed)
read only
by value

Exponent. The word-integer-exponent argument is a signed word containing
the exponent.

CONDITION
VALUES
SIGNALED

OTS-76

SS$_FLTDIV

Arithmetic trap. This error is signaled by the
hardware if a floating-point division by zero occurs.

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled
if word-integer-base is zero and word-integerexponent is zero or negative, or if word-integerbase is negative.

OTS$POWJJ

Raise a Longword Base to a
Longword Exponent

The Raise a Longword Base to a Longword Exponent routine raises a
signed longword base to a signed longword exponent.

FORMAT

OTS$POWJJ

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

longword-integer-base
,longword-integer-exponent

longword_signed
longword (signed)
write only
by value

longword-integer-base
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Base. The longword-integer-base argument is a signed longword containing
the base.

longword-integer-exponent
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Exponent. The longword-integer-exponent argument is a signed longword
containing the exponent.

CONDITION
VALUES
SIGNALED

SS$_FLTDIV

Arithmetic trap. This error is signaled by the
hardware if a floating-point division by zero occurs.

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled if
longword-integer-base is zero and longwordinteger-exponent is zero or negative, or if
longword-integer-base is negative.

OTS-77

OTS$POWLULU

Raise an Unsigned Longword
Base to an Unsigned Longword
Exponent

The Raise an Unsigned Longword Base to an Unsigned Longword
Exponent routine raises an unsigned longword integer base to an unsigned
longword integer exponent.

FORMAT

OTS$POWLULU

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

unsigned-lword-int-base,
unsigned-lword-int-exponent

longword_unsigned
longword (unsigned)
write only
by value

unsigned-lword-int-base
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by value

Unsigned longword integer base. The unsigned-lword-int-base argument
contains the value of the integer base.

unsigned-lword-int-exponent
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by value

Unsigned longword integer exponent. The unsigned-lword-int-exponent
argument contains the value of the integer exponent.

DESCRIPTION

CONDITION
VALUES
SIGNALED

OTS-78

OTS$POWLULU returns the unsigned longword integer result of raising an
unsigned longword integer base to an unsigned longword integer exponent.
Note that overflow cannot occur in this routine. If the result or intermediate
result is greater than 32 bits, the low-order 32 bits are used.

MTH$_UNDEXP

Both the base and exponent values are zero.

OTS$POWxLU

Raise a Floating-Point Base to
an Unsigned Longword Integer
Exponent

The Raise a Floating-Point Base to an Unsigned Longword Integer
Exponent routines raises a floating-point base to an unsigned longword
integer exponent.

FORMAT

floating-point-base
, unsigned-lword-int-exponent
OTS$POWDLU floating-point-base
, unsigned-lword-int-exponent
OTS$POWGLU floating-point-base
, unsigned-lword-int-exponent
OTS$POWHLU_R3 floating-point-base
, unsigned-lword-int-exponent

RETURNS

VMS usage:
type:
access:
mechanism:

OTS$POWRLU

floating_point
f _floating, O_floating, G_floating, H_floating
write only
by value

Result of raising a floating-point base to an unsigned longword integer
exponent. OTS$POWRLU returns an F-floating number. OTS$POWDLU
returns a D-floating number. OTS$POWGLU returns a G-floating number.
OTS$POWHLU_R3 returns an H-floating number.

ARGUMENTS

floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
f _floating, O_floating, G_floating, H_floating
read only
by value

Floating-point base. The floating-point-base argument contains the value
of the base. For OTS$POWRLU, floating-point-base is an F-floating
number. For OTS$POWDLU, floating-point-base is a D-floating number.
For OTS$POWGLU, floating-point-base is a G-floating number. For
OTS$POWHLU_R3, floating-point-base is an H-floating number.

unsigned-/word-int-exponent
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by value

Integer exponent. The unsigned-lword-int-exponent argument contains the
value of the unsigned longword integer exponent.

OTS-79

OTS$POWxLU

DESCRIPTION

CONDITION
VALUES
SIGNALED

OTS-80

OTS$POWRLU, OTS$POWDLU, OTS$POWGLU, and OTS$POWHLU_R3
return the result of raising a floating-point base to an unsigned longword
integer exponent. The floating-point result is as follows:
Base

Exponent

Result

Any

Product of (base*i) where i is each nonzero bit position in
longword-integer-exponent

1.0

= 0

Undefined exponentiation

1.0

MTH$_FLOOVEMA T

Floating-point overflow in math library

MTH$_FLOUNDMA T

Floating-point underflow in math library. This can
only occur if the caller has floating-point underflow
enabled.

MTH$_UNDEXP

Undefined exponentiation. This occurs if both
the floating-point-base and unsigned-longwordinteger-exponent arguments are zero.

OTS$POWRD

Raise an F-floating Base to a
D-floating Exponent

The Raise an F-floating Base to a D-floating Exponent routine raises an
F-floating base to a D-floating exponent.

FORMAT

OTS$POWRD

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

F-f/oating-point-base
, 0-f/oating-point-exponent

floating_point
O_floating
write only
by value

F-floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
f _floating
read only
by value

Base. The F-floating-point-base argument is an F-floating number containing
the base.

D-floating-point-exponent
VMS usage:
type:
access:
mechanism:

floating_point
O_floating
read only
by value

Exponent. The D-floating-point-exponent argument is a D-floating number
that contains the exponent.

DESCRIPTION

OTS$POWRD raises an F-floating base to a D-floating exponent.
The internal calculations and the floating-point result have the same precision
as the base value.
OTS$POWRD first converts the F-floating base to D-floating. The D-floating
result for OTS$POWRD is as follows:

OTS-81

OTS$POWRD

Exponent

Result

0.0

=0
=;: 0

Undefined exponentiation

Any

Undefined exponentiation

2[exponent*LOG2(base))

>0
>0

=0
<0

Base

1.0
2[exponent*LOG2(base))

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative, or if the base is negative.

CONDITION
VALUES
SIGNALED

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_FLOOVEMA T

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled
if F-floating-point-base is zero and 0-floatingpoint-exponent is zero or negative, or if
F-floating-point-base is negative.

EXAMPLE
C+

C
C
C
C

This FORTRAN example demonstrates the use
of OTS$POWRD, which raises an F-floating point
base to a D-floating point exponent. The result is a
D-floating value.

cREAL*4 X
REAL*8 Y,RESULT,OTS$POWRD
INTEGER M(2)
EQUIVALENCE (M(1) ,Y)
x = 9768.0
y = 9.0
C+

C The arguments of OTS$POWRD are passed by value.

cRESULT= OTS$POWRD(%VAL(X),%VAL(M(1)),%VAL(M(2)))
TYPE*·' 9768.0**9.0 IS ',RESULT
x = 7689.0
y = -0.587436654545
C+

C
C

In FORTRAN, OTS$POWRD is indirectly called by simply
using the exponenti~tion operator.

OTS-82

OTS$POWRD

RESULT = X**Y
TYPE*·' 7689.0**-0.587436654545 IS ',RESULT
END

This FORTRAN example uses OTS$POWRD to raise an F-floating base
to a D-floating exponent. Notice the difference in the precision of the
result produced by this routine in comparison to the result produced by
OTS$POWRR.
The output generated by this program is as follows:
9768.0**9.0 IS
8.0956338648832908E+35
7689.0**-0.587436654545 IS
5.2155199252836588E-03

OTS-83

OTS$POWRJ

Raise an F-floating Base to a
Longword Exponent

The Raise an F-floating Base to a Longword Exponent routine raises an
F-floating base to a longword exponent.

FORMAT

OTS$POWRJ

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

F-floating-point-base
,longword-integer-exponent

floating_point
F_floating
write only
by value

F-floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
F_floating
read only
by value

Base. The F-floating-point-base argument is an F-floating number containing
the base.

longword-integer-exponent
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by value

Exponent. The longword-integer-exponent argument is a signed longword
that contains the longword exponent.

DESCRIPTION

OTS$POWRJ raises an F-floating base to a longword exponent.
The internal calculations and the floating-point result have the same precision
as the base value.
The floating-point result is as follows:

OTS-84

OTS$POWRJ

Base

Exponent

Result

Any

Product of (base*i) where i is each nonzero bit position in
longword-integer-exponent

1.0

Undefined exponentiation

1.0

1.0/ (base*i), where i is each nonzero bit position in
longword-integer-exponent

Undefined exponentiation

1.0/ (base*2i) where i is each nonzero bit position in
longword-integer-exponent

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative.

CONDITION
VALUES
SIGNALED

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_FLOOVEMA T

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled
if F-floating-point-base is zero and longwordinteger-exponent is zero or negative, or if
F-floating-point-base is negative.

OTS-85

OTS$POWRR

Raise an F-floating Base to an
F-floating Exponent

The Raise an F-floating Base to an F-floating Exponent routine raises an
F-floating base to an F-floating exponent.

FORMAT

OTS$POWRR

RETURNS

VMS usage:
type:
access: ·
mechanism:

ARGUMENTS

F-floating-point-base
, F-f/oating-point-exponent

floating_point
F_floating
write only
by value

F-floating-point-base
VMS usage:
type:
access:
mechanism:

floating_point
f _floating
read only
by value

Base. The F-floating-point-base argument is an F-floating number containing
the base.

F-floating-point-exponent
VMS usage:
type:
access:
mechanism:

floating_point
f _floating
read only
by value

Exponent. The F-floating-point-exponent argument is an F-floating number
that contains the exponent.

DESCRIPTION

OTS$POWRR raises an F-floating base to an F-floating exponent.
The internal calculations and the floating-point result have the same precision
as the base value.
The F-floating result for OTS$POWRR is as follows:

OTS-86

OTS$POWRR

Base

Exponent

Result

0.0

Undefined exponentiation

Any

Undefined exponentiation

2[exponent*log2(base)]

1.0

2 [exponent* log2 (base)]

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero
or negative, or if the base is negative.

CONDITION
VALUES
SIGNALED

SS$_FLTOVF

Arithmetic trap. This error is signaled by the
hardware if a floating-point overflow occurs.

MTH$_FLOOVEMAT

Floating-point overflow in math library.

MTH$_FLOUNDMA T

Floating-point underflow in math library.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled
if F-floating-point-base is zero and F-floatingpoint-exponent is zero or negative, or if
F-floating-point-base is negative.

EXAMPLE
C+

C This FORTRAN example demonstrates the use
C of OTS$POWRR, which raises an F-floating
C point base to an F-floating point power.

REAL*4 X,Y,RESULT,OTS$POWRR

x = 8.0

y = 2.0

C+

C The arguments of OTS$POWRR are passed by value.

RESULT= OTS$POWRR(%VAL(X),%VAL(Y))
TYPE*·' 8.0**2.0 IS' ,RESULT
x = 9.0
y = -0.5
C+

C In FORTRAN, OTS$POWRR is indirectly called by simply
C using the exponentiation operator.

RESULT = X**Y
TYPE*·' 9.0**-0.5 IS' ,RESULT
END

OTS-87

OTS$POWRR

This FORTRAN example uses OTS$POWRR to raise an F-floating point base
to an F-floating point exponent. The output generated by this program is as
follows:
8.0**2.0 IS
9.0**-0.5 IS

OTS-88

64.00000
0.3333333

OTS$SCOPV_DXDX

Copy a Source String
Passed by Descriptor to a
Destination String

The Copy a Source String Passed by Descriptor to a Destination String
routine copies a source string to a destination string. Both strings are
passed by descriptor.

FORMAT

OTS$SCOPV_DXDX

source-string ,destination-string

corresponding jsb OTS$SCOPV_DXDX6
entry point
RETURNS

VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by value

If source-string contains more characters than destination-string, and the
JSB entry point is used, RO contains the number of characters that were not
copied.

ARGUMENTS

source-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Source string. The source-string argument is the address of a descriptor
pointing to the source string. The descriptor class can be unspecified, fixed
length, dynamic, scalar decimal, array, noncontiguous array, or varying.

destination-string
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

Destination string. The destination-string argument is the address of a
descriptor pointing to the destination string. The class field determines the
appropriate action.
See the Description section for further information.

OTS-89

OTS$SCOPY_DXDX

DESCRIPTION

OTS$SCOPY_DXDX copies a source string to a destination string. All error
conditions except truncation are signaled; truncation is ignored.
OTS$SCOPY_DXDX passes the source string by descriptor. In addition, an
equivalent JSB entry point is provided, with RO being the first argument (the
descriptor of the source string), and Rl the second (the descriptor of the
destination string).
For the CALL entry point, RO (return status) is as it would be after a MOVCS
instruction. For the JSB entry point, RO:RS and the PSL are as they would be
after a MOVCS instruction. RO:RS contain the following:
RO

Number of bytes of source string not moved to destination string

Address one byte beyond the last copied byte in the source string

Address one byte beyond the destination string

For further information, see the VAX Architecture Reference Manual.
Depending on the class of the destination string, the actions described below
occur:

CONDITION
VALUES
SIGNALED

OTS-90

Class Field

Action

DSC$K _CLASS_S ,Z,SD ,A ,NCA

Copy the source string. If needed, space fill
or truncate on the right.

DSC$K_CLASS_D

If the area specified by the destination
descriptor is large enough to contain the
source string, copy the source string and set
the new length in the destination descriptor.
If the area specified is not large enough,
return the previous space allocation (if any)
and then dynamically allocate the amount
of space needed. Copy the source string
and set the new length and address in the
destination descriptor.

DSC$K_CLASS_VS

Copy source string to destination string up
to the limit of DSC$W_MAXSTRLEN with no
padding. Adjust current length field to actual
number of bytes copied.

OTS$_FATINTERR

Fatal internal error.

OTS$_1NVSTRDES

Invalid string descriptor.

OTS$_1NSVIRMEM

Insufficient virtual memory.

OTS$SCOPV_R_DX

OTS$SCOPY_R_DX Copy a Source String
Passed by Reference to a
Destination String
The Copy a Source String Passed by Reference to a Destination String
routine copies a source string passed by reference to a destination string.

FORMAT

OTS$SCOPV_R _DX

word-int-source-length-val
, source-string-address
, destination-string

corresponding jsb OTS$SCOPV_R_DX6
entry point

RETURNS

VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by value

If source-string-address contains more characters than destination-string,
and the JSB entry point is used, RO contains the number of characters that
were not copied.

ARGUMENTS

word-int-source-length-val
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
read only
by value

Length of the source string. The word-int-source-length-val argument is an
unsigned word integer containing the length of the source string.

source-string-address
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by reference

Source string. The source-string-address argument is the address of the
source string.

destination-string
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

OTS-91

OTS$SCOPV_R_DX

Destination string. The destination-string argument is the address of a
descriptor pointing to the destination string. The class field determines the
appropriate action. The length field (DSC$W_LENGTH) alone or both the
address (DSC$A_POINTER) and length fields can be modified if the string is
dynamic. For varying strings, the current length is rewritten.

DESCRIPTION

OTS$SCOPY_R_DX copies a source string to a destination string. All
conditions except truncation are signaled; truncation is ignored. Input scalars
are passed by value.
OTS$SCOPY_R_DX passes the source string by reference preceded by a
length argument. In addition, an equivalent JSB entry point is provided, with
RO being the first argument, Rl the second, and R2 the third, if any. The
length argument is passed in bits 15:0 of the appropriate register.
For the CALL entry point, RO (return status) is as it would be after a MOVCS
instruction. For the JSB entry point, RO:RS and the PSL are as they would be
after a MOVCS instruction. RO:RS contain the following:
RO

Number of bytes of source string not moved to destination string

Address one byte beyond the last copied byte in the source string

Address one byte beyond the destination string

For additional information, see the VAX Architecture Reference Manual.
Depending on the class of the destination string, the actions described below
occur:

OTS-92

Class Field

Action

DSC$K_CLASS_S,Z,SD,A,NCA

Copy the source string. If needed, space fill
or truncate on the right.

DSC$K_CLASS_D

DSC$K_CLASS_ vs

Copy source string to destination string up
to the limit of DSC$W _MAXSTRLEN with no
padding. Adjust current length field to actual
number of bytes copied.

OTS$SCOPV_R_DX

CONDITION
VALUES
SIGNALED

OTS$_F A TINTERR

Fatal internal error.

OTS$_1NVSTRDES

Invalid string descriptor.

OTS$_1NSVIRMEM

Insufficient virtual memory.

EXAMPLE
A FORTRAN example demonstrating dynamic string manipulation appears
at the end of OTS$SGET1_DD. This example uses OTS$SCOPY_R_DX,
OTS$SGET1_DD, and OTS$SFREEl_DD.

OTS-93

OTS$SFREE1 _DD

Strings, Free One Dynamic

The Free One Dynamic String routine returns one dynamic string area to
free storage.

FORMAT

OTS$SFREE1_DD

dynamic-descriptor

corresponding jsb OTS$SFREE1 _DD6
entry point
RETURNS
ARGUMENTS

None.

dynamic-descriptor
VMS usage:
type:
access:
mechanism:

quadword_unsigned
quadword (unsigned)
modify
by reference

Dynamic string descriptor. The dynamic-descriptor argument is the address
of the dynamic string descriptor. The descriptor is assumed to be dynamic
and its class field is not checked.

DESCRIPTION

CONDITION
VALUE
SIGNALED

OTS$SFREEl_DD deallocates the described string space and flags the
descriptor as describing no string at all (DSC$A_POJNTER = 0 and
DSC$W_LENGTH = 0).

OTS$_FA TINTERR

Fatal internal error.

EXAMPLE
A FORTRAN example demonstrating dynamic string manipulation appears
at the end of OTS$SGET1_DD. This example uses OTS$SFREEl_DD,
OTS$SGET1_DD, and OTS$SCOPY_R_DX.

OTS-94

OTS$SFREEn_DD

Strings, Free n Dynamic

The Free n Dynamic Strings routine takes as input a vector of one or more
dynamic string areas and returns them to free storage.

FORMAT

OTS$SFREEN_DD

descriptor-count-value
, first-descriptor

corresponding jsb OTS$SFREEN_DD6
entry point
RETURNS
ARGUMENTS

None.

descriptor-count-value
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by value

Number of adjacent descriptors to be flagged as having no allocated
area (OSC$A_POINTER = 0 and OSC$W_LENGTH = 0) and to have
their allocated areas returned to free storage by OTS$SFREEN_OO. The
descriptor-count-value argument is an unsigned longword containing this
number.

first-descriptor
VMS usage:
type:
access:
mechanism:

quadword_unsigned
quadword (unsigned)
modify
by reference

First string descriptor of an array of string descriptors. The first-descriptor
argument is the address of the first string descriptor. The descriptors are
assumed to be dynamic, and their class fields are not checked.

DESCRIPTION

CONDITION
VALUES
SIGNALED

OTS$SFREEN _006 deallocates the described string space and flags each
descriptor as describing no string at all (OSC$A_POINTER = 0 and
OSC$W_LENGTH = 0).

OTS$_F A TINTERR

Fatal internal error.

OTS-95

OTS$SGET1_DD

Strings, Get One Dynamic

The Get One Dynamic String routine allocates a specified number of bytes
of dynamic virtual memory to a specified string descriptor.

FORMAT

OTS$SGET1 _DD

word-integer-length-value
, dynamic-descriptor

corresponding jsb OTS$SGET1 _DD_R6
entry point

RETURNS
ARGUMENTS

None.

word-integer-length-value
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
read only
by value

Number of bytes to be allocated. The word-integer-length-value
argument contains the number of bytes. The amount of storage allocated
is automatically rounded up. If the number of bytes is zero, a small number
of bytes is allocated.

dynamic-descriptor
VMS usage:
type:
access:
mechanism:

quadword_unsigned
quadword (unsigned)
modify
by reference

Dynamic string descriptor to which the area is to be allocated. The dyn-str
argument is the address of the dynamic string descriptor. The class field is
not checked but it is set to dynamic (DSC$B_CLASS = 2). The length field
(DSC$W_LENGTH) is set to word-integer-length-value and the address
field (DSC$A_PQINTER) is set to the string area allocated (first byte beyond
the header).

DESCRIPTION

OTS$SGET1_DD allocates a specified number of bytes of dynamic virtual
memory to a specified string descriptor. This routine is identical to
OTS$SCOPY_DXDX except that no source string is copied. You can write
anything you want in the allocated area.
If the specified string descriptor already has dynamic memory allocated to

it, but the amount allocated is either greater than or less than word-integerlength-value, that space is deallocated before OTS$SGET1_DD allocates new
space.

OTS-96

OTS$SGET1_DD

CONDITION
VALUES
SIGNALED

OTS$_F A TINT ERR

Fatal internal error.

OTS$_1NSVIRMEM

Insufficient virtual memory.

EXAMPLE
PROGRAM STRING_TEST
C+
C
C

This program demonstrates the use of some dynamic string
manipulation routines.

C+
C

DECLARATIONS

IMPLICIT NONE
CHARACTER*80
INTEGER*4
CHARACTER*2
C+
C

DATA_LINE
DATA_LEN, DSC(2), CRLF_DSC(2), TEMP_DSC(2)
CRLF

Initialize the output descriptor.

It should be empty.

CALL OTS$SGET1_DD(%VAL(O), DSC)
C+
C
C

Initialize a descriptor to the string CRLF and copy the
character CRLF to it.
CALL OTS$SGET1_DD(%VAL(2), CRLF_DSC)
CRLF = CHAR(13)//CHAR(10)
CALL OTS$SCOPY_R_DX( %VAL(2), %REF(CRLF(1:1)), CRLF_DSC)

C+

c
c-

Initialize a temporary descriptor.
CALL OTS$SGET1_DD(%VAL(O), TEMP_DSC)

C+

Prompt the user.

999

WRITE(6, 999)
FORMAT ( 1X, 'Enter your message, end with CTRL/Z. ')

cC+

c
c
c
c-

998

Read lines of text from the terminal until end-of-file.
Concatenate each line to the previous input. Include a
CRLF between each line.
DO WHILE (.TRUE.)
READ(5, 998, ERR= 10) DATA_LEN, DATA_LINE
FORMAT(Q,A)
CALL OTS$SCOPY_R_DX( %VAL(DATA_LEN),
%REF(DATA_LINE(1:1)),
1
TEMP_DSC)
2
CALL STR$CONCAT( DSC, DSC, TEMP_DSC, CRLF_DSC )
END DO

OTS-97

OTS$SGET1_DD

C+

The user has typed CTRL/Z.

CALL LIB$PUT_OUTPUT( DSC )

Output the data we read.

C+

Free the storage allocated to the dynamic strings.
CALL OTS$SFREE1_DD( DSC )
CALL OTS$SFREE1_DD( CRLF_DSC )
CALL OTS$SFREE1_DD( TEMP_DSC )

C+

End of program.

cSTOP
END

This FORTRAN example program demonstrates dynamic string manipulation
using OTS$SGET1_DD, OTS$SFREEl_DD, and OTS$SCOPY_R_DX.

OTS-98

Index

c
Complex number
division of• OTS-39
multiplication of• OTS-53
Conversion
binary text to unsigned integer• OTS-17
floating-point to character string• OTS-3
hexadecimal text to unsigned integer• OTS-36
integer to binary text• OTS-5
integer to FORTRAN L format• OTS-9
integer to hexadecimal • OTS-1 5
numeric text to floating-point• OTS-29,
OTS-33
unsigned decimal to integer• OTS-2 7
unsigned octal to signed integer• OTS-24
Copy string• OTS-89

D
Division
complex number• OTS-39
packed decimal• OTS-42, OTS-46
Dynamic string• OTS-95

E
Exponentiation
complex base to complex exponent• OTS-55
complex base to signed integer exponent•
OTS-58
D-floating base• OTS-61 , OTS-63, OTS-65
F-floating base• OTS-81, OTS-84, OTS-86
G-floating base• OTS-67, OTS-70
H-floating base• OTS-72, OTS-7 4
signed longword base• OTS-77
word base to word exponent• OTS-76

M
Multiplication
of complex number• OTS-53

0
OTS$CNVOUT•OTS-3
OTS$CNVOUT_G•OTS-3
OTS$CNVOUT_H•OTS-3
OTS$CVT_L_TB•OTS-5
OTS$CVT_L_Tl•OTS-7
OTS$CVT_L_TL•OTS-9
OTS$CVT_L_TO•OTS-11
OTS$CVT_L_TU•OTS-13
OTS$CVT_L_TZ•OTS-15
OTS$CVT_TB_L•OTS-17
OTS$CVT_Tl_L • OTS-20
OTS$CVT_TL_L•OTS-22
OTS$CVT_TQ_L•OTS-24
OTS$CVT_TU_L•OTS-27
OTS$CVT_TZ_L•OTS-36
OTS$CVT_T_z•OTS-29,0TS-33
OTS$DIVC • OTS-39
OTS$DIVCD_R3 • OTS-39
OTS$DIVCG_R3 • OTS-39
OTS$DIV_PK_LONG • OTS-42
OTS$DIV_PK_SHORT • OTS-46
OTS$MOVE3•0TS-49
OTS$MOVE5 • OTS-51
OTS$MULCD_R3 • OTS-53
OTS$MULCG_R3 • OTS-53
OTS$PO\NCxCx•OTS-55
OTS$PO\NCxJ•OTS-58
OTS$PO\NDD•OTS-61
OTS$PO\NDJ•OTS-65
OTS$PO\NDLU•OTS-79
OTS$PO\NDR•OTS-63
OTS$PO\NGG•OTS-67
OTS$PO\NGJ•OTS-70
OTS$PO\NGLU•OTS-79
OTS$PO\NHH_R3 • OTS-72
OTS$PO\NHJ_R3•0TS-74

lndex-1

Index

OTS$POVVHLU_R3•0TS-79
OTS$POVVll • OTS-76
OTS$POVV JJ • OTS-7 7
OTS$POVVLULU • OTS-78
OTS$POVVRD • OTS-81
OTS$POVVRJ•OTS-84
OTS$POVVRLU • OTS-79
OTS$POVVRR•OTS-86
OTS$SCOPY_DXDX•OTS-89
OTS$SCOPY_R_DX•OTS-91
OTS$SFREE1_DD•OTS-94
OTS$SFREEN_DD • OTS-95
OTS$SGET1_DD•OTS-96

R
Run-Time Library routine
general purpose• 1-1

s
String
allocating• OTS-96
copying by descriptor• OTS-89
copying by reference• OTS-91
freeing• OTS-94

lndex-2

Reader's Comments

VMS RTL General Purpose
(0TS$) Manual
AA-LA 73A-TE

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your
comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

I would like to see more /less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version _ _ _ of the software this manual describes.

Name/Title

Dept.

Company

Date

Mailing Address
Phone

I
I
I
I
I
I

-- Do Not Tear - Fold Here and Tape -------------------~lllr--------------
No Postage

mamaomn™

~:::i~=~y
in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POST AGE WILL BE PAID BY ADDRESSEE

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZK01-3/J35 110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

111 ..... 11.11 .... 11 .... 1.11.1 .. 1.1 .. 1•• 1.1 ••• 1.11 .. 1
-- Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

~
I

I•