HP OpenVMS RTL General Purpose (OTS$) Manual

Order Number: AA--PV6HE--TK

January 2005

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

Revision/Update Information: This manual supersedes the HP OpenVMS RTL General Purpose (OTS$) Manual for OpenVMS Alpha Version 7.3.

Software Version: OpenVMS I64 Version 8.2 OpenVMS Alpha Version 8.2

Hewlett-Packard Company
Palo Alto, California

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Printed in the US

ZK5933

The HP OpenVMS documentation set is available on CD-ROM.

Contents Index

Preface

This manual provides users of the OpenVMS operating system with detailed usage and reference information on general-purpose routines supplied in the OTS$ facility of the Run-Time Library.

Intended Audience

This manual is intended for system and application programmers who write programs that call OTS$ Run-Time Library routines.

Document Structure

This manual is organized into two parts as follows:

Part I contains a brief overview of the OTS$ routines in Chapter 1.
Part 2, the OTS$ Reference Section, 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 OpenVMS Programming Concepts Manual. Routine descriptions appear in alphabetical order by routine name.

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet openvmsdoc@hp.com

Mail Hewlett-Packard Company
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

For information on how to order additional documentation, visit the following World Wide Web address:

http://www.hp.com/go/openvms/doc/order

Conventions

The following conventions are used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as brackets, rather than a box.

... A horizontal ellipsis in examples indicates one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.

[ ] In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.

{ } In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed. Do not type the braces on the command line.

bold text This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text

Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Part 1
OTS$ Overview

This part of the HP OpenVMS RTL General Purpose (OTS$) Manual contains a general overview of the routines provided by the OpenVMS RTL General Purpose (OTS$) Facility, and lists them by function.

Chapter 1
Run-Time Library General Purpose (OTS$) Facility

This chapter describes the OpenVMS Run-Time Library General Purpose (OTS$) Facility. See the OTS$ Reference Section for a detailed description of each routine within the OTS$ facility.

Most of the OTS$ routines were originally designed to support language compilers. Because they perform general-purpose functions, the routines were moved into the language-independent facility, OTS$.

1.1 Overview

The Run-Time Library General Purpose (OTS$) Facility provides routines to perform general-purpose functions. These functions include data type conversions as part of a compiler's generated code, and some mathematical functions.

The OTS$ facility contains routines to perform the following main tasks:

Convert data types (see Table 1-1)
Divide complex and packed decimal values (see Table 1-2)
Move data to a specified destination address (see Table 1-3)
Multiply complex values (see Table 1-4)
Raise a base to an exponent (see Table 1-5)
Copy a source string to a destination string (see Table 1-6)
Return a string area to free storage (see Table 1-7)
Use convenience routines related to the OpenVMS Calling Standard (see Table 1-8)

Some restrictions apply if you link certain OTS$ routines on an Alpha system or HP OpenVMS Industry Standard 64 for Integrity Servers (I64) system. See Section 1.2 for more information about these restrictions.

Table 1-1 OTS$ Conversion Routines
Routine Name Function

OTS$CNVOUT Convert a D-floating, G-floating, H-floating, IEEE S-floating or IEEE T-floating value to a character string.

OTS$CVT_L_TB Convert an unsigned integer to binary text.

OTS$CVT_L_TI Convert a signed integer to signed integer text.

OTS$CVT_L_TL Convert an integer to logical text.

OTS$CVT_L_TO Convert an unsigned integer to octal text.

OTS$CVT_L_TU Convert an unsigned integer to decimal text.

OTS$CVT_L_TZ Convert an integer to hexadecimal text.

OTS$CVT_TB_L Convert binary text to an unsigned integer value.

OTS$CVT_TI_L Convert signed integer text to an integer value.

OTS$CVT_TL_L Convert logical text to an integer value.

OTS$CVT_TO_L Convert octal text to an unsigned integer value.

OTS$CVT_TU_L Convert unsigned decimal text to an integer value.

OTS$CVT_T_ x Convert numeric text to a D-, F-, G-, H-, IEEE S-, or IEEE T-floating value.

OTS$CVT_TZ_L Convert hexadecimal text to an unsigned integer value.

**Table 1-1 OTS$ Conversion Routines**
Routine Name	Function
OTS$CNVOUT	Convert a D-floating, G-floating, H-floating, IEEE S-floating or IEEE T-floating value to a character string.
OTS$CVT_L_TB	Convert an unsigned integer to binary text.
OTS$CVT_L_TI	Convert a signed integer to signed integer text.
OTS$CVT_L_TL	Convert an integer to logical text.
OTS$CVT_L_TO	Convert an unsigned integer to octal text.
OTS$CVT_L_TU	Convert an unsigned integer to decimal text.
OTS$CVT_L_TZ	Convert an integer to hexadecimal text.
OTS$CVT_TB_L	Convert binary text to an unsigned integer value.
OTS$CVT_TI_L	Convert signed integer text to an integer value.
OTS$CVT_TL_L	Convert logical text to an integer value.
OTS$CVT_TO_L	Convert octal text to an unsigned integer value.
OTS$CVT_TU_L	Convert unsigned decimal text to an integer value.
OTS$CVT_T_ x	Convert numeric text to a D-, F-, G-, H-, IEEE S-, or IEEE T-floating value.
OTS$CVT_TZ_L	Convert hexadecimal text to an unsigned integer value.

For more information on Run-Time Library conversion routines, see the CVT$ reference section in the HP OpenVMS RTL Library (LIB$) Manual.

Table 1-2 OTS$ Division Routines
Routine Name Function

OTS$DIVC x 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.

**Table 1-2 OTS$ Division Routines**
Routine Name	Function
OTS$DIVC x	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.

Table 1-3 OTS$ Move Data Routines
Routine Name Function

OTS$MOVE3 Move data without fill.

OTS$MOVE5 Move data with fill.

**Table 1-3 OTS$ Move Data Routines**
Routine Name	Function
OTS$MOVE3	Move data without fill.
OTS$MOVE5	Move data with fill.

Table 1-4 OTS$ Multiplication Routine
Routine Name Function

OTS$MULC x Perform complex multiplication.

**Table 1-4 OTS$ Multiplication Routine**
Routine Name	Function
OTS$MULC x	Perform complex multiplication.

Table 1-5 OTS$ Exponentiation Routines
Routine Name Function

OTS$POWC xC x Raise a complex base to a complex floating-point exponent.

OTS$POWC xJ 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$POWGG 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.

+OTS$POWHH_R3 Raise an H-floating base to an H-floating exponent.

+OTS$POWHJ_R3 Raise an H-floating base to a longword integer exponent.

OTS$POWII Raise a word integer base to a word integer exponent.

OTS$POWJJ 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$POW xLU Raise a floating-point base to an unsigned longword integer exponent.

OTS$POWRD Raise an F-floating base to a D-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.

OTS$POWSJ Raise an IEEE S-floating base to a longword integer exponent.

OTS$POWSS Raise an IEEE S-floating base to an S-floating or longword integer exponent.

OTS$POWTJ Raise an IEEE T-floating base to a longword integer exponent.

OTS$POWTT Raise an IEEE T-floating base to a T-floating or longword integer exponent.

**Table 1-5 OTS$ Exponentiation Routines**
Routine Name	Function
OTS$POWC xC x	Raise a complex base to a complex floating-point exponent.
OTS$POWC xJ	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$POWGG	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.
+OTS$POWHH_R3	Raise an H-floating base to an H-floating exponent.
+OTS$POWHJ_R3	Raise an H-floating base to a longword integer exponent.
OTS$POWII	Raise a word integer base to a word integer exponent.
OTS$POWJJ	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$POW xLU	Raise a floating-point base to an unsigned longword integer exponent.
OTS$POWRD	Raise an F-floating base to a D-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.
OTS$POWSJ	Raise an IEEE S-floating base to a longword integer exponent.
OTS$POWSS	Raise an IEEE S-floating base to an S-floating or longword integer exponent.
OTS$POWTJ	Raise an IEEE T-floating base to a longword integer exponent.
OTS$POWTT	Raise an IEEE T-floating base to a T-floating or longword integer exponent.

+VAX specific.

Table 1-6 OTS$ Copy Source String Routines
Routine Name Function

OTS$SCOPY_DXDX Copy a source string passed by descriptor to a destination string.

OTS$SCOPY_R_DX Copy a source string passed by reference to a destination string.

**Table 1-6 OTS$ Copy Source String Routines**
Routine Name	Function
OTS$SCOPY_DXDX	Copy a source string passed by descriptor to a destination string.
OTS$SCOPY_R_DX	Copy a source string passed by reference to a destination string.

Table 1-7 OTS$ Return String Area Routines
Routine Name Function

OTS$SFREE1_DD Free one dynamic string.

OTS$SFREEN_DD Free n dynamic strings.

OTS$SGET1_DD Get one dynamic string.

**Table 1-7 OTS$ Return String Area Routines**
Routine Name	Function
OTS$SFREE1_DD	Free one dynamic string.
OTS$SFREEN_DD	Free n dynamic strings.
OTS$SGET1_DD	Get one dynamic string.

Table 1-8 OTS$ Convenience Routines
Routine Name Function

OTS$CALL_PROC Perform a call to a procedure that may be either in native code or in a translated image.

OTS$JUMP_TO_BPV Transfer control to a bound procedure.

**Table 1-8 OTS$ Convenience Routines**
Routine Name	Function
OTS$CALL_PROC	Perform a call to a procedure that may be either in native code or in a translated image.
OTS$JUMP_TO_BPV	Transfer control to a bound procedure.

1.2 Linking OTS$ Routines on Alpha and I64 Systems

On Alpha and I64 systems, if you use the OTS$ entry points for certain mathematics routines, you must link against the DPML$SHR.EXE library. Alternately, you can use the equivalent math$ entry point for the routine and link against either STARLET.OLB or the DPML$SHR.EXE library. Math$ entry points are available only on Alpha and I64 systems.

Table 1-9 lists the affected OTS$ entry points with their equivalent math$ entry points. Refer to the Compaq Portable Mathematics Library for information about the math$ entry points.

Table 1-9 OTS$ and Equivalent Math$ Entry Points
OTS$ Entry Point Math$ Entry Point

OTS$DIVC math$cdiv_f

OTS$DIVCG_R3 math$cdiv_g

OTS$DIVCS math$cdiv_s

OTS$DIVCT_R3 math$cdiv_t

OTS$MULCS math$cmul_s

OTS$MULCT_R3 math$cmul_t

OTS$MULCG_R3 math$cmul_g

OTS$POWCC math$cpow_f

OTS$POWCGCG_R3 math$cpow_g

OTS$POWCJ math$cpow_fq

OTS$POWCSCS math$cpow_s

OTS$POWCSJ math$cpow_sq

OTS$POWCTCT_R3 math$cpow_t

OTS$POWCTJ_R3 math$cpow_tq

OTS$POWGG math$pow_gg

OTS$POWGJ math$pow_gq

OTS$POWGLU math$pow_gq

OTS$POWII math$pow_qq

OTS$POWJJ math$pow_qq

OTS$POWLULU math$pow_qq

OTS$POWRJ math$pow_fq

OTS$POWRLU math$pow_fq

OTS$POWRR math$pow_ff

OTS$POWSS math$pow_ss

OTS$POWSJ math$pow_sq

OTS$POWSLU math$pow_sq

OTS$POWTJ math$pow_tq

OTS$POWTLU math$pow_tq

OTS$POWTT math$pow_tt

**Table 1-9 OTS$ and Equivalent Math$ Entry Points**
OTS$ Entry Point	Math$ Entry Point
OTS$DIVC	math$cdiv_f
OTS$DIVCG_R3	math$cdiv_g
OTS$DIVCS	math$cdiv_s
OTS$DIVCT_R3	math$cdiv_t
OTS$MULCS	math$cmul_s
OTS$MULCT_R3	math$cmul_t
OTS$MULCG_R3	math$cmul_g
OTS$POWCC	math$cpow_f
OTS$POWCGCG_R3	math$cpow_g
OTS$POWCJ	math$cpow_fq
OTS$POWCSCS	math$cpow_s
OTS$POWCSJ	math$cpow_sq
OTS$POWCTCT_R3	math$cpow_t
OTS$POWCTJ_R3	math$cpow_tq
OTS$POWGG	math$pow_gg
OTS$POWGJ	math$pow_gq
OTS$POWGLU	math$pow_gq
OTS$POWII	math$pow_qq
OTS$POWJJ	math$pow_qq
OTS$POWLULU	math$pow_qq
OTS$POWRJ	math$pow_fq
OTS$POWRLU	math$pow_fq
OTS$POWRR	math$pow_ff
OTS$POWSS	math$pow_ss
OTS$POWSJ	math$pow_sq
OTS$POWSLU	math$pow_sq
OTS$POWTJ	math$pow_tq
OTS$POWTLU	math$pow_tq
OTS$POWTT	math$pow_tt

Contents

Index

HP OpenVMS RTL General Purpose (OTS$) Manual

January 2005

Preface

Intended Audience

Document Structure

Related Documents

¹ This manual has been archived but is available on the OpenVMS Documentation CD-ROM.

² HP POSIX Threads was formerly called DECthreads.

Reader's Comments

How To Order Additional Documentation

Conventions

Part 1
OTS$ Overview

Chapter 1
Run-Time Library General Purpose (OTS$) Facility

1.1 Overview

1.2 Linking OTS$ Routines on Alpha and I64 Systems

Internet	openvmsdoc@hp.com
Mail	Hewlett-Packard Company OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
{ }	In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed. Do not type the braces on the command line.
bold text	This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace text	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

HP OpenVMS RTL General Purpose (OTS$) Manual

January 2005

Preface

Intended Audience

Document Structure

Related Documents

1 This manual has been archived but is available on the OpenVMS Documentation CD-ROM.

2 HP POSIX Threads was formerly called DECthreads.

Reader's Comments

How To Order Additional Documentation

Conventions

Part 1OTS$ Overview

Chapter 1Run-Time Library General Purpose (OTS$) Facility

1.1 Overview

1.2 Linking OTS$ Routines on Alpha and I64 Systems

¹ This manual has been archived but is available on the OpenVMS Documentation CD-ROM.

² HP POSIX Threads was formerly called DECthreads.

Part 1
OTS$ Overview

Chapter 1
Run-Time Library General Purpose (OTS$) Facility