vsi openvms rtl general purpose (ots$) manual_18-june-2019.pdf · 2019. 6. 18. · purpose (ots$)...

VSI OpenVMS

VSI OpenVMS RTL General Purpose(OTS$) Manual

Document Number: DO–RTLOTS–01A

Publication Date: June 2019

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

Revision Update Information: This is a new manual.

Operating System and Version: HPE OpenVMS I64 Version 8.2HPE OpenVMS Alpha Version 8.2

VMS Software, Inc. (VSI)Bolton, Massachusetts, USA

VSI OpenVMS RTL General Purpose (OTS$) Manual:

Copyright © 2019 VMS Software, Inc. (VSI), Bolton, Massachusetts, USA

Legal Notice

Confidential computer software. Valid license from VSI 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 VSI products and services are set forth in theexpress warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additionalwarranty. VSI shall not be liable for technical or editorial errors or omissions contained herein.

HPE, HPE Integrity, HPE Alpha, and HPE Proliant are trademarks or registered trademarks of Hewlett Packard Enterprise.

The VSI OpenVMS documentation set is available on DVD.

ii

VSI OpenVMS RTL General Purpose (OTS$) Manual

Preface ..................................................................................................................................... v1. About VSI ...................................................................................................................... v2. Intended Audience .......................................................................................................... v3. Document Structure ........................................................................................................ v4. Related Documents ......................................................................................................... v5. VSI Encourages Your Comments .................................................................................... vi6. How to Order Additional Documentation ........................................................................ vi7. Typographical Conventions ............................................................................................ vi

Chapter 1. Run-Time Library General Purpose (OTS$) Facility ..................................... 11.1. 1.1 Overview ............................................................................................................... 11.2. Linking OTS$ Routines on Alpha and I64 Systems ........................................................ 3

1.2.1. 64-Bit Addressing Support (Alpha and I64 Only) ................................................ 4Chapter 2. General-Purpose (OTS$) Routines ................................................................... 7

OTS$CALL_PROC (Alpha and I64 Only) ........................................................................... 7OTS$CNVOUT .................................................................................................................. 8OTS$CVT_L_TB ................................................................................................................ 9OTS$CVT_L_TI ............................................................................................................... 11OTS$CVT_L_TL .............................................................................................................. 13OTS$CVT_L_TO .............................................................................................................. 14OTS$CVT_L_TU .............................................................................................................. 16OTS$CVT_L_TZ .............................................................................................................. 18OTS$CVT_T_x ................................................................................................................. 20OTS$CVT_TB_L .............................................................................................................. 24OTS$CVT_TI_L ............................................................................................................... 27OTS$CVT_TL_L .............................................................................................................. 29OTS$CVT_TO_L .............................................................................................................. 31OTS$CVT_TU_L .............................................................................................................. 33OTS$CVT_TZ_L .............................................................................................................. 35OTS$DIVCx ..................................................................................................................... 38OTS$DIV_PK_LONG ....................................................................................................... 41OTS$DIV_PK_SHORT ..................................................................................................... 45OTS$JUMP_TO_BPV (I64 Only) ...................................................................................... 48OTS$MOVE3 ................................................................................................................... 49OTS$MOVE5 ................................................................................................................... 50OTS$MULCx ................................................................................................................... 52OTS$POWCxCx ............................................................................................................... 55OTS$POWCxJ .................................................................................................................. 57OTS$POWDD .................................................................................................................. 60OTS$POWDJ ................................................................................................................... 61OTS$POWDR .................................................................................................................. 63OTS$POWGG .................................................................................................................. 64OTS$POWGJ ................................................................................................................... 67OTS$POWHH_R3 (VAX Only) ........................................................................................ 68OTS$POWHJ_R3 (VAX Only) .......................................................................................... 70OTS$POWII ..................................................................................................................... 72OTS$POWJJ ..................................................................................................................... 73OTS$POWLULU .............................................................................................................. 74OTS$POWRD .................................................................................................................. 75OTS$POWRJ .................................................................................................................... 77OTS$POWRR ................................................................................................................... 79OTS$POWSJ .................................................................................................................... 81

iii

VSI OpenVMS RTL General Purpose (OTS$) Manual

OTS$POWSS ................................................................................................................... 83OTS$POWTJ .................................................................................................................... 85OTS$POWTT ................................................................................................................... 86OTS$POWxLU ................................................................................................................. 89OTS$SCOPY_DXDX ....................................................................................................... 90OTS$SCOPY_R_DX ........................................................................................................ 92OTS$SFREE1_DD ............................................................................................................ 95OTS$SFREEN_DD ........................................................................................................... 96OTS$SGET1_DD .............................................................................................................. 97

iv

Preface

1. About VSIVMS Software, Inc. (VSI) is an independent software company licensed by Hewlett PackardEnterprise to develop and support the OpenVMS operating system.

VSI seeks to continue the legendary development prowess and customer-first priorities that are soclosely associated with the OpenVMS operating system and its original author, Digital EquipmentCorporation.

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

3. Document StructureThis manual is organized into two parts as follows:

• Chapter 1 contains a brief overview of the OTS$ routines.

• Chapter 2 provides detailed reference information on each routine contained in the OTS$ facilityof the Run-Time Library. This information is presented using the documentation format describedin VSI OpenVMS Programming Concepts Manual. Routine descriptions appear in alphabeticalorder by routine name.

4. Related DocumentsThe Run-Time Library routines are documented in a series of reference manuals. A descriptionof how the Run-Time Library routines are accessed and of OpenVMS features and functionalityavailable through calls to the OTS$ Run-Time Library appears in the VSI OpenVMS ProgrammingConcepts Manual. Descriptions of other RTL facilities and their corresponding routines and usagesare discussed in the following books:

• Compaq Portable Mathematics Library

• VSI OpenVMS RTL Library (LIB$) Manual

• VSI OpenVMS RTL Screen Management (SMG$) Manual

• VSI OpenVMS RTL String Manipulation (STR$) Manual

The Guide to the POSIX Threads Library contains guidelines and reference information for POSIXThreads, the Multithreading Run-Time Library.

Application programmers using any programming language can refer to the Guide to CreatingOpenVMS Modular Procedures for writing modular and reentrant code.

v

Preface

High-level language programmers will find additional information on calling Run-Time Libraryroutines in their language reference manual. Additional information may also be found in thelanguage user's guide provided with your OpenVMS language software.

For additional information about OpenVMS products and services, access the VSI website at thefollowing location: https://www.vmssoftware.com/

5. VSI Encourages Your CommentsYou may send comments or suggestions regarding this manual or any VSI document by sending emailto the following Internet address: <[email protected]>.

6. How to Order Additional DocumentationFor information about how to order additional documentation, email the VSI OpenVMS informationaccount: <[email protected]>. We will be posting links to documentation on ourcorporate website soon.

7. Typographical ConventionsThe following conventions are used in this manual:

Convention MeaningCtrl/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 (x) or a pointingdevice button.

... A horizontal ellipsis in examples indicates one of the followingpossibilities:

• 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 orcommand format; the items are omitted because they are not important tothe topic being discussed.

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

[ ] In command format descriptions, brackets indicate optional choices. Youcan choose one or more items or no items. Do not type the brackets on thecommand line. However, you must include the brackets in the syntax fordirectory specifications and for a substring specification in an assignmentstatement.

| In command format descriptions, vertical bars separate choices withinbrackets or braces. Within brackets, the choices are optional; withinbraces, at least one choice is required. Do not type the vertical bars on thecommand line.

vi

https://www.vmssoftware.com/

Preface

Convention Meaning{ } In command format descriptions, braces indicate required choices; you

must choose at least one of the items listed. Do not type the braces on thecommand line.

bold type Bold type represents the name of an argument, an attribute, or a reason.Bold type also represents the introduction of a new term.

italic type Italic type 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 incommand parameters in text (where dd represents the predefined code forthe device type).

UPPERCASE TYPE Uppercase type indicates a command, the name of a routine, the name of afile, or the abbreviation for a system privilege.

Example This typeface indicates code examples, command examples, and interactivescreen displays. In text, this type also identifies website addresses, UNIXcommands and pathnames, PC-based commands and folders, and certainelements of the C programming language.

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

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

vii

Preface

viii

Chapter 1. Run-Time Library GeneralPurpose (OTS$) FacilityThis chapter describes the OpenVMS Run-Time Library General Purpose (OTS$) Facility. See theChapter 2 for a detailed description of each routine within the OTS$ facility.

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

1.1. 1.1 OverviewThe Run-Time Library General Purpose (OTS$) Facility provides routines to perform general-purposefunctions. These functions include data type conversions as part of a compiler's generated code, andsome 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 I64 system. SeeSection 1.2 for more information about these restrictions.

Table 1.1. OTS$ Conversion Routines

Routine Name FunctionOTS$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.

1

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

Routine Name FunctionOTS$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 inthe VSI OpenVMS RTL Library (LIB$) Manual.

Table 1.2. OTS$ Division Routines

Routine Name FunctionOTS$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.

Table 1.3. OTS$ Move Data Routines

Routine Name FunctionOTS$MOVE3 Move data without fill.OTS$MOVE5 Move data with fill.

Table 1.4. OTS$ Multiplication Routine

Routine Name FunctionOTS$MULCx Perform complex multiplication.

Table 1.5. OTS$ Exponentiation Routines

Routine Name FunctionOTS$POWCxCx Raise a complex base to a complex floating-point 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$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_R31 Raise an H-floating base to an H-floating exponent.OTS$POWHJ_R31 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$POWxLU Raise a floating-point base to an unsigned longword integer exponent.

2


Routine Name FunctionOTS$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.1VAX specific

Table 1.6. OTS$ Copy Source String Routines

Routine Name FunctionOTS$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 FunctionOTS$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 FunctionOTS$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 I64SystemsOn Alpha and I64 systems, if you use the OTS$ entry points for certain mathematics routines, youmust link against the DPML$SHR.EXE library. Alternately, you can use the equivalent math$ entrypoint 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 theCompaq Portable Mathematics Library for information about the math$ entry points.

Table 1.9. OTS$ and Equivalent Math$ Entry Points

OTS$ Entry Point Math$ Entry PointOTS$DIVC math$cdiv_fOTS$DIVCG_R3 math$cdiv_g

3


OTS$ Entry Point Math$ Entry PointOTS$DIVCS math$cdiv_sOTS$DIVCT_R3 math$cdiv_tOTS$MULCS math$cmul_sOTS$MULCT_R3 math$cmul_tOTS$MULCG_R3 math$cmul_gOTS$POWCC math$cpow_fOTS$POWCGCG_R3 math$cpow_gOTS$POWCJ math$cpow_fqOTS$POWCSCS math$cpow_sOTS$POWCSJ math$cpow_sqOTS$POWCTCT_R3 math$cpow_tOTS$POWCTJ_R3 math$cpow_tqOTS$POWGG math$pow_ggOTS$POWGJ math$pow_gqOTS$POWGLU math$pow_gqOTS$POWII math$pow_qqOTS$POWJJ math$pow_qqOTS$POWLULU math$pow_qqOTS$POWRJ math$pow_fqOTS$POWRLU math$pow_fqOTS$POWRR math$pow_ffOTS$POWSS math$pow_ssOTS$POWSJ math$pow_sqOTS$POWSLU math$pow_sqOTS$POWTJ math$pow_tqOTS$POWTLU math$pow_tqOTS$POWTT math$pow_tt

1.2.1. 64-Bit Addressing Support (Alpha and I64 Only)On Alpha and I64 systems, the General Purpose (OTS$) routines provide 64-bit virtual addressingcapabilities as follows:

• All OTS$ RTL routines accept 64-bit addresses for arguments passed by reference.

• All OTS$ RTL routines also accept either 32-bit or 64-bit descriptors for arguments passed bydescriptor.

Note

The OTS$ routines declared in ots$routines.h do not include prototypes for 64-bit data. You mustprovide your own generic prototypes for any OTS$ functions you use.

4


See the VSI OpenVMS Programming Concepts Manual for more information about 64-bit virtualaddressing capabilities.

5


6

Chapter 2. General-Purpose (OTS$)RoutinesThis chapter provides detailed descriptions of the routines provided by the OpenVMS RTL GeneralPurpose (OTS$) Facility.

OTS$CALL_PROC (Alpha and I64 Only)OTS$CALL_PROC (Alpha and I64 Only) — The Call Special Procedure routine performs a call to aprocedure that may be either in native code or in a translated image.

FormatOTS$CALL_PROC target-func-value ,target-sig-info ,standard-args ,...

ReturnsNone.

Argumentstarget-func-value

OpenVMS usage: function valuetype: quadword addressaccess: read onlymechanism: by value in register R23 (Alpha); by value in register R17 (I64)

Function value for the procedure to be called.

target-sig-info

OpenVMS usage: TIE signature informationtype: TIE signature blockaccess: read onlymechanism: by reference in register R24 (Alpha); by value in register R17 (I64)

Signature information is used to transform the standard arguments into the form required bya translated image (if needed). The representation of signature information is described in theOpenVMS Calling Standard.

standard-args

Zero or more arguments to be passed to the called routine, passed using standard conventions(including the AI register).

7

Chapter 2. General-Purpose (OTS$) Routines

DescriptionWhen translated code support is requested, the compiled code must call the special service routine,OTS$CALL_PROC. The actual parameters to the target function are passed to OTS$CALL_PROC asthough the target routine is native code that is being invoked directly.

OTS$CALL_PROC first determines whether the target routine is part of a translated image.

If the target is in native code, then OTS$CALL_PROC completes the call in a way that makesits mediation transparent (that is, control need not pass back through it for the return). The nativeparameters are used without modification.

If the target is in translated code, then OTS$CALL_PROC passes control to the Translated ImageEnvironment (TIE). For additional information, see the VSI OpenVMS Calling Standard.

Condition Values ReturnedNone.

OTS$CNVOUTOTS$CNVOUT — The Convert Floating to Character String routines convert a D-floating, G-floating, H-floating, IEEE S-floating, or IEEE T-floating number to a character string in the Fortran Eformat.

FormatOTS$CNVOUT D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction

OTS$CNVOUT_G D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction

OTS$CNVOUT_H D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction (VAX only)

OTS$CNVOUT_S D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction (VAX only)

OTS$CNVOUT_T D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction (VAX only)

ReturnsOpenVMS usage: cond_valuetype: longword (unsigned)access: write onlymechanism: by value

8


ArgumentsD-G-H-S-or-T-float-pt-input-val

OpenVMS usage: floating_pointtype: D_floating, G_floating, H_floating, IEEE S_floating, IEEE T_floatingaccess: read onlymechanism: by reference

Value that OTS$CNVOUT converts to a character string. For OTS$CNVOUT, the D-G-H-S-or-T-float-pt-input-val argument is the address of a D-floating number containing the value. ForOTS$CNVOUT_G, the D-G-H-S-or-T-float-pt-input-val argument is the address of a G-floatingnumber containing the value. For OTS$CNVOUT_S, the D-G-H-S-or-T-float-pt-input-val argumentis the address of an IEEE S-floating number containing the value. For OTS$CNVOUT_T, the D-G-H-S-or-T-float-pt-input-val argument is the address of an IEEE T-floating number containing thevalue.

fixed-length-resultant-string

OpenVMS usage: char_stringtype: character stringaccess: write onlymechanism: by descriptor, fixed length

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

digits-in-fraction

OpenVMS usage: longword_unsignedtype: longword (unsigned)access: read onlymechanism: by value

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

Condition Values ReturnedSS$_NORMAL Normal successful completion.SS$_ROPRAND Floating reserved operand detected.OTS$_OUTCONERR Output conversion error. The result would have exceeded the fixed-

length string; the output string is filled with asterisks (*).

OTS$CVT_L_TBOTS$CVT_L_TB — The Convert an Unsigned Integer to Binary Text routine converts an unsignedinteger value of arbitrary length to binary representation in an ASCII text string. By default, alongword is converted.

9


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


Argumentsvarying-input-value

OpenVMS usage: varying_argtype: unspecifiedaccess: read onlymechanism: by reference

Unsigned byte, word, or longword that OTS$CVT_L_TB converts to an unsigned decimalrepresentation in an ASCII text string. (The value of the input-value-size argument determineswhether varying-input-value is a byte, word, or longword.) The varying-input-value argument isthe address of the unsigned integer.



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 stringis assumed to be of fixed length (CLASS_S descriptor).

number-of-digits

OpenVMS usage: longword_signedtype: longword (signed)access: read onlymechanism: by value

Minimum number of digits in the binary representation to be generated. The number-of-digitsargument is a signed longword containing this minimum number. If the minimum number of digits isomitted, the default is 1. If the actual number of significant digits is less than the minimum number

10


of digits, leading zeros are produced. If the minimum number of digits is zero and the value of theinteger to be converted is also zero, OTS$CVT_L_TB creates a blank string.

input-value-size


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

Condition Values ReturnedSS$_NORMAL Normal successful completion.OTS$_OUTCONERR Output conversion error. The result would have exceeded the fixed-


OTS$CVT_L_TIOTS$CVT_L_TI — The Convert Signed Integer to Decimal Text routine converts a signed integer toits decimal representation in an ASCII text string. This routine supports Fortran Iw and Iw.m outputand BASIC output conversion.

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



OpenVMS usage: varying_argtype: unspecifiedaccess: read onlymechanism: by reference, fixed length

11


A signed integer that OTS$CVT_L_TI converts to a signed decimal representation in an ASCII textstring. The varying-input-value argument is the address of the signed integer.

On VAX systems, the integer can be a signed byte, word, or longword. The value of the input-value-size argument determines whether varying-input-value is a byte, word, or longword.

On Alpha and I64 systems, the integer can be a signed byte, word, longword, or quadword. The valueof the input-value-size argument determines whether varying-input-value is a byte, word, longword,or quadword.


OpenVMS usage: char_stringtype: character stringaccess: write onlymechanism: by descriptor

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

number-of-digits


Minimum number of digits to be generated when OTS$CVT_L_TI converts the signed integer toa decimal ASCII text string. The number-of-digits argument is a signed longword containing thisnumber. If the minimum number of digits is omitted, the default value is 1. If the actual number ofsignificant 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 outputstring.

input-value-size


Size of the integer to be converted, in bytes. The input-value-size argument is a signed longwordcontaining this value size. If the size is omitted, the default is 4 (longword).

On VAX systems, the value size must be 1, 2, or 4. If value size is 1 or 2, the value is sign-extended toa longword before conversion.

On Alpha and I64 systems, the value size must be 1, 2, 4, or 8. If the value is 1, 2, or 4, the value issign-extended to a quadword before conversion.

12


flags-value

OpenVMS usage: mask_longwordtype: longword (unsigned)access: read onlymechanism: by value

Caller-supplied flags that you can use if you want OTS$CVT_L_TI to insert a plus sign before theconverted number. The flags-value argument is an unsigned longword containing the flags.

The caller flags are described in the following table:

Bit Action if Set Action if Clear0 Insert a plus sign (+) before the first

nonblank character in the output string.Omit the plus sign.

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

Condition Values ReturnedSS$_NORMAL Normal successful completion.OTS$_OUTCONERR Output conversion error. Either the result would have exceeded the

fixed-length string or the input-value-size is not a valid value. Theoutput string is filled with asterisks (*).

OTS$CVT_L_TLOTS$CVT_L_TL — The Convert Integer to Logical Text routine converts an integer to an ASCII textstring representation using Fortran L (logical) format.

FormatOTS$CVT_L_TL longword-integer-value ,fixed-length-resultant-string


Argumentslongword-integer-value

OpenVMS usage: longword_signedtype: longword (signed)

13


access: read onlymechanism: by reference

Value that OTS$CVT_L_TL converts to an ASCII text string. The longword-integer-value argumentis the address of a signed longword containing this integer value.



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

The output string is assumed to be of fixed length (CLASS_S descriptor).

If bit 0 of longword-integer-value is set, OTS$CVT_L_TL stores the character T in the rightmostcharacter of fixed-length-resultant-string. If bit 0 is clear, it stores the character F. In either case, itfills the remaining characters of fixed-length-resultant-string with blanks.


length string; the output string is of zero length (descriptor LENGTHfield contains 0).

Example5 !+ ! 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$CVT_L_TOOTS$CVT_L_TO — The Convert Unsigned Integer to Octal Text routine converts an unsignedinteger to an octal ASCII text string. OTS$CVT_L_TO supports Fortran Ow and Ow.m outputconversion formats.

14


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

Returns

OpenVMS usage: cond_valuetype: longword (unsigned)access: write onlymechanism: by value



Unsigned byte, word, or longword that OTS$CVT_L_TO converts to an unsigned decimalrepresentation in an ASCII text string. (The value of the input-value-size argument determineswhether varying-input-value is a byte, word, or longword.) The varying-input-value argument isthe address of the unsigned integer.



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

number-of-digits


Minimum number of digits that OTS$CVT_L_TO generates when it converts the integer valueto an octal ASCII text string. The number-of-digits argument is a signed longword containing

15


the minimum number of digits. If it is omitted, the default is 1. If the actual number of significantdigits in the octal ASCII text string is less than the minimum number of digits, OTS$CVT_L_TOinserts leading zeros into the output string. If number-of-digits is 0 and varying-input-value is 0,OTS$CVT_L_TO writes a blank string to the output string.

input-value-size


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



OTS$CVT_L_TUOTS$CVT_L_TU — The Convert Unsigned Integer to Decimal Text routine converts an unsignedinteger value to its unsigned decimal representation in an ASCII text string.

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



OpenVMS usage: varying_argtype: unspecifiedaccess: read only

16


mechanism: by reference

An unsigned integer that OTS$CVT_L_TU converts to an unsigned decimal representation in anASCII text string. The varying-input-value argument is the address of the unsigned integer.

On VAX systems, the integer can be an unsigned byte, word, or longword. (The value of the input-value-size argument determines whether varying-input-value is a byte, word, or longword.)

On Alpha and I64 systems, the integer can be an unsigned byte, word, longword, or quadword. (Thevalue of the input-value-size argument determines whether varying-input-value is a byte, word,longword, or quadword.)



Output string that OTS$CVT_L_TU creates when it converts the integer value to unsigned decimalrepresentation in an ASCII text string. The fixed-length-resultant-string argument is the address of adescriptor pointing to this ASCII text string.

number-of-digits


Minimum number of digits in the ASCII text string that OTS$CVT_L_TU creates. The number-of-digits argument is a signed longword containing the minimum number. If the minimum number ofdigits is omitted, the default is 1.

If the actual number of significant digits in the output string created is less than the minimum number,OTS$CVT_L_TU inserts leading zeros into the output string. If the minimum number of digits is zeroand the integer value to be converted is also zero, OTS$CVT_L_TU writes a blank string to the outputstring.

input-value-size


Size of the integer to be converted, in bytes. The input-value-size argument is a signed longwordcontaining this value size. If the size is omitted, the default is 4 (longword).

On VAX systems, the value size must be 1, 2, or 4.

17


On Alpha and I64 systems, the value size must be 1, 2, 4, or 8.

Condition Values ReturnedSS$_NORMAL Normal successful completion.OTS$_OUTCONERR Output conversion error. Either the result would have exceeded the

fixed-length string or the input-value-size is not a valid value. Theoutput string is filled with asterisks (*).

OTS$CVT_L_TZOTS$CVT_L_TZ — The Convert Integer to Hexadecimal Text routine converts an unsignedinteger to a hexadecimal ASCII text string. OTS$CVT_L_TZ supports Fortran Zw and Zw.m outputconversion formats.

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




Unsigned byte, word, or longword that OTS$CVT_L_TZ converts to an unsigned decimalrepresentation in an ASCII text string. (The value of the input-value-size argument determineswhether varying-input-value is a byte, word, or longword.) The varying-input-value argument isthe address of the unsigned integer.


OpenVMS usage: char_stringtype: character stringaccess: write only

18


mechanism: by descriptor, fixed length

Output string that OTS$CVT_L_TZ creates when it converts the integer value to a hexadecimalASCII text string. The fixed-length-resultant-string argument is the address of a descriptor pointingto this ASCII text string. The string is assumed to be of fixed length (CLASS_S descriptor).

number-of-digits


Minimum number of digits in the ASCII text string that OTS$CVT_L_TZ creates when it convertsthe integer. The number-of-digits argument is a signed longword containing this minimum number.If it is omitted, the default is 1. If the actual number of significant digits in the text string thatOTS$CVT_L_TZ creates is less than this minimum number, OTS$CVT_L_TZ inserts leading zerosin the output string. If the minimum number of digits is zero and the integer value to be converted isalso zero, OTS$CVT_L_TZ writes a blank string to the output string.

input-value-size


Size of the integer that OTS$CVT_L_TZ converts, in bytes. The input-value-size argument is asigned longword containing the value size. If the size is omitted, the default is 4 (longword).



Examplewith 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,

19


DESCRIPTOR (CLASS => S)));

begin CONVERT_TO_HEX (INTVALUE, HEXSTRING); PUT_LINE("This is the value of HEXSTRING"); PUT_LINE(HEXSTRING);end;

This Ada example uses OTS$CVT_L_TZ to convert a longword integer to hexadecimal text.

OTS$CVT_T_xOTS$CVT_T_x — The Convert Numeric Text to D-, F-, G-, H-, IEEE S-, or IEEE T-Floatingroutines convert an ASCII text string representation of a numeric value to a D-floating, F-floating, G-floating, H-floating, IEEE S-floating, or IEEE T-floating value.

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

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

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

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

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

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


Argumentsfixed-or-dynamic-input-string

OpenVMS usage: char_string

20


type: character stringaccess: read onlymechanism: by descriptor, fixed-length or dynamic string

Input string containing an ASCII text string representation of a numeric value thatOTS$CVT_T_xconverts to a D-floating, F-floating, G-floating, H-floating, IEEE S-floating, or IEEET-floating value. The fixed-or-dynamic-input-string argument is the address of a descriptor pointingto the input string.

The syntax of a valid input string is as follows:

E, e, D, d, Q, and q are the possible exponent letters. They are semantically equivalent. Otherelements in the preceding syntax are defined as follows:

Term Descriptionblanks One or more blanksdigits One or more decimal digits

floating-point-value

OpenVMS usage: floating_pointtype: D_floating, F_floating, G_floating, H_floating, IEEE S_floating, IEEE

T_floatingaccess: write onlymechanism: by reference

Floating-point value that OTS$CVT_T_x creates when it converts the input string. The floating-point-value argument is the address of the floating-point value. The data type of floating-point-valuedepends on the called routine as shown in the following table:

Routine Floating-Point-Value Data TypeOTS$CVT_T_D D-floatingOTS$CVT_T_F F-floatingOTS$CVT_T_G G-floatingOTS$CVT_T_H H-floatingOTS$CVT_T_S IEEE S-floating

21


Routine Floating-Point-Value Data TypeOTS$CVT_T_T IEEE T-floating

digits-in-fraction


Number of digits in the fraction if no decimal point is included in the input string. The digits-in-fraction argument contains the number of digits. If the number of digits is omitted, the default is zero.

scale-factor


Scale factor. The scale-factor argument contains the value of the scale factor. If bit 6 of the flags-value argument is clear, the resultant value is divided by 10scale-factor unless the exponent is present. Ifbit 6 of flags-value is set, the scale factor is always applied. If the scale factor is omitted, the defaultis zero.

flags-value


User-supplied flags. The flags-value argument contains the user-supplied flags described in thefollowing table:

Bit Action if Set Action if Clear0 Ignore blanks. Interpret blanks as zeros.1 Allow only E or e exponents. (This is

consistent with Fortran semantics.)Allow E, e, D, d, Q and q exponents. (This isconsistent with BASIC semantics.)

2 Interpret an underflow as an error. Do not interpret an underflow as an error.3 Truncate the value. Round the value.4 Ignore tabs. Interpret tabs as invalid characters.5 An exponent must begin with a valid

exponent letter.The exponent letter can be omitted.

6 Always apply the scale factor. Apply the scale factor only if there is noexponent present in the string.

If you omit the flags-value argument, OTS$CVT_T_x defaults all flags to clear.

22


extension-bits (D-, F-floating, IEEE S-floating)

OpenVMS usage: byte_unsignedtype: byte (unsigned)access: write onlymechanism: by reference

extension-bits (G-, H-floating, IEEE T-floating)

OpenVMS usage: word_unsignedtype: word (unsigned)access: write onlymechanism: by reference

Extra precision bits. The extension-bits argument is the address of a word containing the extraprecision bits. Ifextension-bits is present, floating-point-value is not rounded, and the first n bitsafter truncation are returned left-justified in this argument, as follows:

Routine Number of BitsReturned

Data Type

OTS$CVT_T_D 8 Byte (unsigned)OTS$CVT_T_F 8 Byte (unsigned)OTS$CVT_T_G 11 Word (unsigned)OTS$CVT_T_H 15 Word (unsigned)OTS$CVT_T_S 8 Byte (unsigned)OTS$CVT_T_T 11 Word (unsigned)

A value represented by extension bits is suitable for use as the extension operand in an EMODinstruction.

The extra precision bits returned for H-floating may not be precise because OTS$CVT_T_H carriesits calculations to only 128 bits. However the error should be small.

DescriptionThe OTS$CVT_T_D, OTS$CVT_T_F, OTS$CVT_T_G, OTS$CVT_T_H, OTS$CVT_T_S, andOTS$CVT_T_T routines support Fortran D, E, F, and G input type conversion as well as similar typesfor other languages.

These routines provide run-time support for BASIC and Fortran input statements.

Although Alpha and I64 systems do not generally support H-floating operations, you can useOTS$CVT_T_H to convert a text string to an H-floating value on an Alpha or I64 system.

Condition Values ReturnedSS$_NORMAL Normal successful completion.OTS$_INPCONERR Input conversion error; an invalid character in the input string, or the

value is outside the range that can be represented. The floating-point-

23


value and extension-bits arguments, if present, are set to +0.0 (notreserved operand –0.0).

ExampleC+C This is a Fortran program demonstrating the use ofC OTS$CVT_T_F.C-

REAL*4 A CHARACTER*10 T(5) DATA T/'1234567+23','8.786534+3','-983476E-3','-23.734532','45'/ DO 2 I = 1, 5 TYPE 1,I,T(I) 1 FORMAT(' Input string ',I1,' is ',A10)

C+C B is the return status.C T(I) is the string to be converted to anC F-floating point value. A is the F-floatingC point conversion of T(I). %VAL(5) means 5 digitsC are in the fraction if no decimal point is inC the input string T(I).C- B = OTS$CVT_T_F(T(I),A,%VAL(5),,) TYPE *,' Output of OTSCVT_T_F is ',A TYPE *,' ' 2 CONTINUE END

This Fortran example demonstrates the use of OTS$CVT_T_F. The output generated by this programis as follows:

Input string 1 is 1234567+23 Output of OTSCVT_T_F is 1.2345669E+24Input string 2 is 8.786534+3 Output of OTSCVT_T_F is 8786.534Input string 3 is -983476E-3 Output of OTSCVT_T_F is -9.8347599E-03Input string 4 is -23.734532 Output of OTSCVT_T_F is -23.73453Input string 5 is 45 Output of OTSCVT_T_F is 45000.00

OTS$CVT_TB_LOTS$CVT_TB_L — The Convert Binary Text to Unsigned Integer routine converts an ASCII textstring representation of an unsigned binary value to an unsigned integer value. The integer value canbe of arbitrary length but is typically a byte, word, longword, or quadword. The default size of theresult is a longword.

FormatOTS$CVT_TB_L

24


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

Returns



OpenVMS usage: char_stringtype: character stringaccess: read onlymechanism: by descriptor

Input string containing the string representation of an unsigned binary value that OTS$CVT_TB_Lconverts to an unsigned integer value. The fixed-or-dynamic-input-string argument is the address ofa descriptor pointing to the input string. The valid input characters are blanks and the digits 0 and 1.No sign is permitted.

varying-output-value

OpenVMS usage: varying_argtype: unspecifiedaccess: write onlymechanism: by reference

Unsigned integer of specified size that OTS$CVT_TB_L creates when it converts the ASCII textstring. The varying-output-value argument is the address of the integer. The value of the output-value-size argument determines the size in bytes of the output value.

output-value-size


Arbitrary number of bytes to be occupied by the unsigned integer output value. The output-value-size argument contains a value that equals the size in bytes of the output value. If the value ofoutput-value-size is zero or a negative number, OTS$CVT_TB_L returns an input conversion error. If youomit the output-value-size argument, the default is 4 (longword).

flags-value

25



User-supplied flag that OTS$CVT_TB_L uses to determine how to interpret blanks within the inputstring. The flags-value argument contains this user-supplied flag.

OTS$CVT_TB_L defines the flag as follows:

Bit Action if Set Action if Clear0 Ignore blanks. Interpret blanks as zeros.

If you omit the flags-value argument, OTS$CVT_TB_L defaults all flags to clear.

Condition Values ReturnedSS$_NORMAL Normal successful completion.OTS$_INPCONERR Input conversion error. OTS$CVT_TB_L encountered an invalid

character in the fixed-or-dynamic-input-string, an overflow ofvarying-output-value, or an invalid output-value-size. In the case ofan invalid character or of an overflow, varying-output-value is set tozero.

Example OPTION & TYPE = EXPLICIT

!+ ! This program demonstrates the use of OTS$CVT_TB_L from BASIC. ! Several binary numbers are read and then converted to their ! integer equivalents. !-

!+ ! DECLARATIONS !-

DECLARE STRING BIN_STR DECLARE LONG BIN_VAL, I, RET_STATUS DECLARE LONG CONSTANT FLAGS = 17 ! 2^0 + 2^4 EXTERNAL LONG FUNCTION OTS$CVT_TB_L (STRING, LONG, & LONG BY VALUE, LONG BY VALUE)

!+ ! MAIN PROGRAM !-

!+ ! Read the data, convert it to binary, and print the result. !-

26


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 alongword integer.

The output generated by this BASIC program is as follows:

1111 treated as a binary number equals 151 111 treated as a binary number equals 151011011 treated as a binary number equals 9111111111 treated as a binary number equals 25500000000 treated as a binary number equals 0

OTS$CVT_TI_LOTS$CVT_TI_L — The Convert Signed Integer Text to Integer routine converts an ASCII text stringrepresentation of a signed decimal number to a signed integer value. The default size of the result is alongword.

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



OpenVMS usage: char_string

27


type: character stringaccess: read onlymechanism: by descriptor, fixed-length or dynamic string

Input ASCII text string that OTS$CVT_TI_L converts to a signed integer. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string.

The syntax of a valid ASCII text input string is as follows:

OTS$CVT_TI_L always ignores leading blanks.



Signed integer that OTS$CVT_TI_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the signed integer. The value of the output-value-sizeargument determines the size of varying-output-value.

output-value-size


Number of bytes to be occupied by the value created when OTS$CVT_TI_L converts the ASCII textstring to an integer value. The output-value-size argument contains the number of bytes in varying-output-value.

On VAX systems, valid values for the output-value-size argument are 1, 2, and 4. The valuedetermines whether the integer value that OTS$CVT_TI_L creates is a byte, word, or longword.

On Alpha and I64 systems, valid values for the output-value-size argument are 1, 2, 4, and 8. Thevalue determines whether the integer value that OTS$CVT_TI_L creates is a byte, word, longword, orquadword.

For VAX and Alpha systems, if you specify a 0 (zero) or omit the output-value-size argument, thesize of the output value defaults to 4 (longword). If you specify any other value, OTS$CVT_TI_Lreturns an input conversion error.

flags-value

OpenVMS usage: mask_longword

28


type: longword (unsigned)access: read onlymechanism: by value

User-supplied flags that OTS$CVT_TI_L uses to determine how blanks and tabs are interpreted. Theflags-value argument is an unsigned longword containing the value of the flags.

Bit Action if Set Action if Clear0 Ignore all blanks. Ignore leading blanks but interpret blanks after the first legal

character as zeros.4 Ignore tabs. Interpret tabs as invalid characters.

If you omit the flags-value argument, OTS$CVT_TI_L defaults all flags to clear.

Condition Values Returned

SS$_NORMAL Normal successful completion.OTS$_INPCONERR Input conversion error. OTS$CVT_TI_L encountered an invalid

character in the fixed-or-dynamic-input-string, an overflow ofvarying-output-value, or an invalid output-value-size. In the case ofan invalid character or of an overflow, varying-output-value is set tozero.

OTS$CVT_TL_LOTS$CVT_TL_L — The Convert Logical Text to Integer routine converts an ASCII text stringrepresentation of a FORTRAN-77 L format to a signed integer.

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

Returns



OpenVMS usage: char_stringtype: character string

29


access: read onlymechanism: by descriptor, fixed-length or dynamic string

Input string containing an ASCII text representation of a FORTRAN-77 L format thatOTS$CVT_TL_L converts to a signed integer value. The fixed-or-dynamic-input-string argument isthe address of a descriptor pointing to the input string.

Common ASCII text representations of a FORTRAN-77 logical are .TRUE., .FALSE., T, t, F, and f. Inpractice, an OTS$CVT_TL_L input string is valid if it adheres to the following syntax:

One of the letters T, t, F, or f is required. Other elements in the preceding syntax are defined asfollows:

Term Descriptionblanks One or more blankscharacters One or more of any character



Signed integer that OTS$CVT_TL_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the signed integer. The value of the output-value-sizeargument determines the size in bytes of the signed integer.

OTS$CVT_TL_L returns –1 as the contents of the varying-output-value argument if the characterdenoted by "letter" is T or t. Otherwise, OTS$CVT_TL_L sets varying-output-value to zero.

output-value-size


Number of bytes to be occupied by the signed integer created when OTS$CVT_TL_L converts theASCII text string to an integer value. The output-value-size argument contains a value that equals

30


the size in bytes of the output value. If output-value-size contains a zero or a negative number,OTS$CVT_TL_L returns an input conversion error.

On VAX systems, valid values for the output-value-size argument are 1, 2, and 4. The valuedetermines whether the integer value that OTS$CVT_TL_L creates is a byte, word, or longword.

On Alpha and I64 systems, valid values for the output-value-size argument are 1, 2, 4, and 8. Thisvalue determines whether the integer value that OTS$CVT_TL_L creates is a byte, word, longword,or quadword.

For VAX, Alpha, and I64 systems, if you omit the output-value-size argument, the default is 4(longword).


SS$_NORMAL Normal successful completion.OTS$_INPCONERR Input conversion error. OTS$CVT_TL_L encountered an invalid

character in the fixed-or-dynamic-input-string or an invalid output-value-size. In the case of an invalid character varying-output-valueis set to zero.

OTS$CVT_TO_LOTS$CVT_TO_L — The Convert Octal Text to Unsigned Integer routine converts an ASCII textstring representation of an unsigned octal value to an unsigned integer. The integer value can be ofarbitrary length but is typically a byte, word, longword, or quadword. The default size of the result is alongword.

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

Returns



OpenVMS usage: char_stringtype: character stringaccess: read only

31


mechanism: by descriptor, fixed-length or dynamic string

Input string containing the string representation of an unsigned octal value that OTS$CVT_TO_Lconverts to an unsigned integer. The fixed-or-dynamic-input-string argument is the address of adescriptor pointing to the input string. The valid input characters are blanks and the digits 0 through 7.No sign is permitted.



Unsigned integer of specified size that OTS$CVT_TO_L creates when it converts the ASCII textstring. The varying-output-value argument is the address of the unsigned integer. The value of theoutput-value-size argument determines the size in bytes of the output value.

output-value-size

OpenVMS usage: longword_signedtype: longword integer (signed)access: read onlymechanism: by value

Arbitrary number of bytes to be occupied by the unsigned integer output value. The output-value-size argument contains a value that equals the size in bytes of the output value. If the value ofoutput-value-size is zero or a negative number, OTS$CVT_TO_L returns an input conversion error. If youomit the output-value-size argument, the default is 4 (longword).

flags-value


User-supplied flag that OTS$CVT_TO_L uses to determine how to interpret blanks within the inputstring. The flags-value argument contains the user-supplied flag described in the following table:

Bit Action if Set Action if Clear0 Ignore all blanks. Interpret blanks as zeros.

If you omit the flags-value argument, OTS$CVT_TO_L defaults the flag to clear.


SS$_NORMAL Normal successful completion.

32


OTS$_INPCONERR Input conversion error. OTS$CVT_TO_L encountered an invalidcharacter in the fixed-or-dynamic-input-string, an overflow ofvarying-output-value, or an invalid output-value-size. In the case ofan invalid character or of an overflow, varying-output-value is set tozero.

ExampleOCTAL_CONV: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31));

%INCLUDE $STSDEF; /* Include definition of return status values */DECLARE OTS$CVT_TO_L ENTRY (CHARACTER (*), /* Input string passed by descriptor */ FIXED BINARY (31), /* Returned value passed by reference */ FIXED BINARY VALUE, /* Size for returned value passed by value */ FIXED BINARY VALUE) /* Flags passed by value */ RETURNS (FIXED BINARY (31)) /* Return status */ OPTIONS (VARIABLE); /* Arguments may be omitted */

DECLARE INPUT CHARACTER (10);DECLARE VALUE FIXED BINARY (31);DECLARE SIZE FIXED BINARY(31) INITIAL(4) READONLY STATIC; /* Longword */DECLARE FLAGS FIXED BINARY(31) INITIAL(1) READONLY STATIC; /* Ignore blanks */

ON ENDFILE (SYSIN) STOP;

DO WHILE ('1'B); /* Loop continuously, until end of file */ PUT SKIP (2); GET LIST (INPUT) OPTIONS (PROMPT ('Octal value: ')); STS$VALUE = OTS$CVT_TO_L (INPUT, VALUE, SIZE, FLAGS); IF ^STS$SUCCESS THEN RETURN (STS$VALUE); PUT SKIP EDIT (INPUT, 'Octal equals', VALUE, 'Decimal') (A,X,A,X,F(10),X,A); END;

END OCTAL_CONV;

This PL/I program translates an octal value in ASCII into a fixed binary value. The program is runinteractively; press Ctrl/Z to quit.

$ RUN OCTALOctal value: 11 Octal equals 1 DecimalOctal value: 1111 Octal equals 9 DecimalOctal value: 10173461017346 Octal equals 274150 DecimalOctal value: Ctrl/Z

OTS$CVT_TU_LOTS$CVT_TU_L — The Convert Unsigned Decimal Text to Integer routine converts an ASCII textstring representation of an unsigned decimal value to an unsigned integer value. By default, the size ofthe result is a longword.

33


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

Returns




Input string containing an ASCII text string representation of an unsigned decimal value thatOTS$CVT_TU_L converts to an unsigned integer value. The fixed-or-dynamic-input-stringargument is the address of a descriptor pointing to the input string. Valid input characters are the spaceand the digits 0 through 9. No sign is permitted.



Unsigned integer that OTS$CVT_TU_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the unsigned integer. The value of the output-value-sizeargument determines the size of varying-output-value.

output-value-size

OpenVMS usage: longword_signedtype: longword integer (signed)access: read onlymechanism: by value

Number of bytes occupied by the value created when OTS$CVT_TU_L converts the input string. Theoutput-value-size argument contains the number of bytes in varying-output-value.

34


On VAX systems, valid values for the output-value-size argument are 1, 2, and 4. The valuedetermines whether the integer value that OTS$CVT_TU_L creates is a byte, word, or longword.

On Alpha and I64 systems, valid values for the output-value-size argument are 1, 2, 4, and 8. Thevalue determines whether the integer value that OTS$CVT_TU_L creates is a byte, word, longword,or quadword.

For VAX, Alpha, and I64 systems, if you specify a 0 (zero) or omit the output-value-size argument,the size of the output value defaults to 4 (longword). If you specify any other value, OTS$CVT_TU_Lreturns an input conversion error.

flags-value


User-supplied flags that OTS$CVT_TU_L uses to determine how blanks and tabs are interpreted. Theflags-value argument contains the user-supplied flags as described in the following table:

Bit Action if Set Action if Clear0 Ignore all blanks. Ignore leading blanks but interpret blanks after the first legal

character as zeros.4 Ignore tabs. Interpret tabs as invalid characters.

If you omit the flags-value argument, OTS$CVT_TU_L defaults all flags to clear.


SS$_NORMAL Normal successful completion.OTS$_INPCONERR Input conversion error. OTS$CVT_TU_L encountered an invalid

character in the fixed-or-dynamic-input-string, overflow of varying-output-value, or an invalid output-value-size. In the case of aninvalid character or of an overflow, varying-output-value is set tozero.

OTS$CVT_TZ_LOTS$CVT_TZ_L — The Convert Hexadecimal Text to Unsigned Integer routine converts an ASCIItext string representation of an unsigned hexadecimal value to an unsigned integer. The integer valuecan be of arbitrary length but is typically a byte, word, longword, or quadword. The default size of theresult is a longword.

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

35


Returns



OpenVMS usage: char_stringtype: character stringaccess: read onlymechanism: by descriptor, fixed-length or dynamic string

Input string containing the string representation of an unsigned hexadecimal value thatOTS$CVT_TZ_L converts to an unsigned integer. The fixed-or-dynamic-input-string argument isthe address of a descriptor pointing to the input string. The valid input characters are blanks, the digits0 through 7, and the letters A through F. Letters can be uppercase or lowercase. No sign is permitted.



Unsigned integer of specified size that OTS$CVT_TZ_L creates when it converts the ASCII textstring. The varying-output-value argument is the address of the unsigned integer. The value of theoutput-value-size argument determines the size in bytes of the output value.

output-value-size


Arbitrary number of bytes to be occupied by the unsigned integer output value. The output-value-size argument contains a value that equals the size in bytes of the output value. If the value ofoutput-value-size is zero or a negative number, OTS$CVT_TZ_L returns an input conversion error. If youomit the output-value-size argument, the default is 4 (longword).

flags-value

OpenVMS usage: mask_longword

36


type: longword (unsigned)access: read onlymechanism: by value

User-supplied flags that OTS$CVT_TZ_L uses to determine how to interpret blanks within the inputstring. The flags-value argument contains these user-supplied flags as described in the followingtable:

Bit Action if Set Action if Clear0 Ignore all blanks. Interpret blanks as zeros.

If you omit the flags-value argument, OTS$CVT_TZ_L defaults the flag to clear.

Condition Values ReturnedSS$_NORMAL Normal successful completion.OTS$_INPCONERR Input conversion error. OTS$CVT_TZ_L encountered an invalid

character in the fixed-or-dynamic-input-string, overflow of varying-output-value, or an invalid output-value-size. In the case of aninvalid character or of an overflow, varying-output-value is set tozero.

Examples1. 10 !+

! This BASIC program converts a character string representing ! a hexadecimal value to a longword. !-

100 !+ ! Illustrate (and test) OTS convert hex-string to longword !-

EXTERNAL LONG FUNCTION OTS$CVT_TZ_L EXTERNAL LONG CONSTANT OTS$_INPCONERR INPUT "Enter hex numeric";HEXVAL$ RET_STAT% = OTS$CVT_TZ_L(HEXVAL$, HEX% ) PRINT "Conversion error " IF RET_STAT% = OTS$_INPCONERR PRINT "Decimal value of ";HEXVAL$;" is";HEX% & IF RET_STAT% <> OTS$_INPCONERR

This BASIC example accepts a hexadecimal numeric string, converts it to a decimal integer, andprints the result. One sample of the output generated by this program is as follows:

$ RUN HEXEnter hex numeric? ADecimal value of A is 10

2. HEX_CONV: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31));

%INCLUDE $STSDEF; /* Include definition of return status values */DECLARE OTS$CVT_TZ_L ENTRY (CHARACTER (*), /* Input string passed by descriptor */

37


FIXED BINARY (31), /* Returned value passed by reference */ FIXED BINARY VALUE, /* Size for returned value passed by value */ FIXED BINARY VALUE) /* Flags passed by value */ RETURNS (FIXED BINARY (31)) /* Return status */ OPTIONS (VARIABLE); /* Arguments may be omitted */

DECLARE INPUT CHARACTER (10);DECLARE VALUE FIXED BINARY (31);DECLARE FLAGS FIXED BINARY(31) INITIAL(1) READONLY STATIC; /* Ignore blanks */

ON ENDFILE (SYSIN) STOP;

DO WHILE ('1'B); /* Loop continuously, until end of file */ PUT SKIP (2); GET LIST (INPUT) OPTIONS (PROMPT ('Hex value: ')); STS$VALUE = OTS$CVT_TZ_L (INPUT, VALUE, , FLAGS); IF ^STS$SUCCESS THEN RETURN (STS$VALUE); PUT SKIP EDIT (INPUT, 'Hex equals', VALUE, 'Decimal') (A,X,A,X,F(10),X,A); END;

END HEX_CONV;

This PL/I example translates a hexadecimal value in ASCII into a fixed binary value. Thisprogram continues to prompt for input values until the user presses Ctrl/Z.

One sample of the output generated by this program is as follows:

$ RUN HEXHex value: 1A1A Hex equals 26 Decimal

Hex value: CC Hex equals 12 Decimal

Hex value: Ctrl/Z

OTS$DIVCxOTS$DIVCx — The Complex Division routines return a complex result of a division on complexnumbers.

FormatOTS$DIVC complex-dividend ,complex-divisor

OTS$DIVCD_R3 complex-dividend ,complex-divisor (VAX only)

OTS$DIVCG_R3 complex-dividend ,complex-divisor

OTS$DIVCS complex-dividend ,complex-divisor

OTS$DIVCT_R3 complex-dividend ,complex-divisor

Each of these formats corresponds to one of the floating-point complex types.

38


Returns

OpenVMS usage: complex_numbertype: F_floating complex, D_floating complex, G_floating complex, IEEE

S_floating complex, IEEE T_floating complex,access: write onlymechanism: 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-floatingcomplex number. OST$DIVCS returns an IEEE S-floating complex number. OTS$DIVCT_R3 returnsan IEEE T-floating complex number.

Argumentscomplex-dividend


S_floating complex, IEEE T_floating complexaccess: read onlymechanism: by value

Complex dividend. The complex-dividend argument contains a floating-point complex value. ForOTS$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-floatingcomplex number. For OTS$DIVCT_R3, complex-dividend is an IEEE T-floating complex number.

complex-divisor



Complex divisor. The complex-divisor argument contains the value of the divisor. ForOTS$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-floatingcomplex number. For OTS$DIVCS, complex-divisor is an IEEE S-floating complex number. ForOTS$DIVCS, complex-dividend is an IEEE S-floating complex number. For OTS$DIVCT_R3,complex-divisoris an IEEE T-floating complex number.

DescriptionThese routines return a complex result of a division on complex numbers.

The complex result is computed as follows:

39


1. Let (a,b) represent the complex dividend.

2. Let (c,d) represent the complex divisor.

3. Let (r,i) represent the complex quotient.

The results of this computation are as follows:

r = (ac + bd)/(c2 + d2)i = (bc - ad)/(c2 + d2)

On Alpha and I64 systems, some restrictions apply when linking OTS$DIVC or OTS$DIVCG_R3.See Chapter 1 for more information about these restrictions.

Condition Values SignaledSS$_FLTDIV_F Arithmetic fault. Floating-point division by zero.SS$_FLTOVF_F Arithmetic fault. Floating-point overflow.

Examples1.

C+C This Fortran example forms the complexC quotient of two complex numbers usingC OTS$DIVC and the Fortran random numberC generator RAN.CC Declare Z1, Z2, Z_Q, and OTS$DIVC as complex values.C OTS$DIVC will return the complex quotient of Z1 dividedC by Z2: Z_Q = OTS$DIVC( %VAL(REAL(Z1)), %VAL(AIMAG(Z1),C %VAL(REAL(Z2)), %VAL(AIMAG(Z2))C-

COMPLEX Z1,Z2,Z_Q,OTS$DIVCC+C Generate a complex number.C- Z1 = (8.0,4.0)C+C Generate another complex number.C- Z2 = (1.0,1.0)C+C Compute the complex quotient of Z1/Z2.C- 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 programis as follows:

The complex quotient of (8.000000,4.000000) divided by (1.000000,1.000000)

40


is (6.000000,-2.000000)

2. C+C This Fortran example forms the complexC quotient of two complex numbers by usingC OTS$DIVCG_R3 and the Fortran random numberC generator RAN.CC Declare Z1, Z2, and Z_Q as complex values. OTS$DIVCG_R3C will return the complex quotient of Z1 divided by Z2:C Z_Q = Z1/Z2C-

COMPLEX*16 Z1,Z2,Z_QC+C Generate a complex number.C- Z1 = (8.0,4.0)C+C Generate another complex number.C- Z2 = (1.0,1.0)C+C Compute the complex quotient of Z1/Z2.C- 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 theprecision of the output generated:

The complex quotient of (8.000000000000000,4.000000000000000) divided by(1.000000000000000,1.000000000000000) is (6.000000000000000,-2.000000000000000)

OTS$DIV_PK_LONGOTS$DIV_PK_LONG — The Packed Decimal Division with Long Divisor routine divides fixed-point decimal data, which is stored in packed decimal form, when precision and scale requirementsfor the quotient call for multiple precision division. The divisor must have a precision of 30 or 31digits.

FormatOTS$DIV_PK_LONG packed-decimal-dividend ,packed-decimal-divisor ,divisor-precision ,packed-decimal-quotient ,quotient-precision ,precision-data ,scale-data

ReturnsOpenVMS usage: cond_valuetype: longword (unsigned)

41


access: write onlymechanism: by value

Argumentspacked-decimal-dividend

OpenVMS usage: varying_argtype: packed decimal stringaccess: read onlymechanism: by reference

Dividend. The packed-decimal-dividend argument is the address of a packed decimal string thatcontains 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)

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

packed-decimal-divisor


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

divisor-precision

OpenVMS usage: word_signedtype: word (signed)access: read onlymechanism: by value

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

packed-decimal-quotient

OpenVMS usage: varying_argtype: packed decimal stringaccess: write onlymechanism: by reference

42


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

quotient-precision


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

precision-data


Additional digits of precision required. The precision-data argument is a signed word that containsthe 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


Scale factor of the decimal point. The scale-data argument is a signed word that contains the scaledata.

OTS$DIV_PK_LONG defines the scale-data argument as follows:

scale-data = 31 - prec(packed-decimal-divisor)

DescriptionOn VAX systems, before using this routine, you should determine whether it is best to useOTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the VAX instruction DIVP. To determine this, youmust first calculate b, where b is defined as follows:

b = scale(packed-decimal-quotient)+ scale(packed-decimal-divisor)- scale(packed-decimal-dividend)

43


+ 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 lessthan 31, you could use the instruction DIVP instead.

When using this routine on an OpenVMS Alpha system, an I64 system, or on an OpenVMSVAX system and you have determined that you cannot use DIVP, you need to determine whetheryou should use OTS$DIV_PK_LONG or OTS$DIV_PK_SHORT. To determine this, you mustexamine the value of scale-data. If scale-data is less than or equal to 1, then you should useOTS$DIV_PK_LONG. If scale-data is greater than 1, you should use OTS$DIV_PK_SHORTinstead.

Condition Values ReturnedSS$_FLTDIV Fatal error. Division by zero.

Example1

OPTION & TYPE = EXPLICIT

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

!+ ! DECLARATIONS !-

DECLARE DECIMAL (31, 2) NATIONAL_DEBT DECLARE DECIMAL (30, 3) POPULATION DECLARE DECIMAL (10, 5) 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 "Enter national debt: ";NATIONAL_DEBT INPUT "Enter current population: ";POPULATION

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

44


! prec(divd) = 31 ! prec(divr) = 30 ! prec(quot) = 10 ! ! prec-data = scale(quot) + scale(divr) - scale(divd) - 31 + ! prec(divd) ! prec-data = 5 + 3 - 2 - 31 + 31 ! prec-data = 6 ! ! b = scale(quot) + scale(divr) - scale(divd) + prec(divd) ! b = 5 + 3 - 2 + 31 ! b = 37 ! ! c = 31 - prec(divd) ! c = 31 - 31 ! c = 0 ! ! scale-data = 31 - prec(divr) ! scale-data = 31 - 30 ! scale-data = 1 ! ! b is 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, '6'W, '1'W)

PRINT "The per capita debt is ";PER_CAPITA_DEBT END

This BASIC example program uses OTS$DIV_PK_LONG to perform packed decimal division. Oneexample of the output generated by this program is as follows:

$ RUN DEBTEnter national debt: ? 12345678Enter current population: ? 1212The per capita debt is 10186.20297

OTS$DIV_PK_SHORTOTS$DIV_PK_SHORT — The Packed Decimal Division with Short Divisor routine divides fixed-point decimal data when precision and scale requirements for the quotient call for multiple-precisiondivision.

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

45



Argumentspacked-decimal-dividend


Dividend. The packed-decimal-dividend argument is the address of a packed decimal string thatcontains 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)

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

packed-decimal-divisor


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

divisor-precision


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

packed-decimal-quotient

OpenVMS usage: varying_arg

46


type: packed decimal stringaccess: write onlymechanism: by reference

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

quotient-precision


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

precision-data


Additional digits of precision required. The precision-data argument is a signed word that containsthe 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-divisor)- scale(packed-decimal-dividend)- 31 + prec(packed-decimal-dividend)

DescriptionOn VAX systems, before using this routine, you should determine whether it is best to useOTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the VAX instruction DIVP. To determine this, youmust 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_SHORT can be used to perform the division. If b is lessthan 31, you could use the VAX instruction DIVP instead.

When using this routine on an OpenVMS Alpha system, an I64 system, or on an OpenVMSVAX system and you have determined that you cannot use DIVP, you need to determine whetheryou should use OTS$DIV_PK_LONG or OTS$DIV_PK_SHORT. To determine this, you mustexamine the value of scale-data. If scale-data is less than or equal to 1, then you should useOTS$DIV_PK_LONG. If scale-data is greater than 1, you should use OTS$DIV_PK_SHORTinstead.

47


Condition Values ReturnedSS$_FLTDIV Fatal error. Division by zero.

OTS$JUMP_TO_BPV (I64 Only)OTS$JUMP_TO_BPV (I64 Only) — The Jump to Bound Procedure Value routine transfers control toa bound procedure.

FormatOTS$JUMP_TO_BPV bound-func-value ,standard-args ,...

ReturnsNone.

Argumentsbound-func-value

OpenVMS usage: quadword addresstype: addressaccess: read onlymechanism: by value in register R1 (GP)

Function value for the procedure being called.

standard-args

Zero or more arguments to be passed to the called routine, passed using standard conventions(including the AI register).

DescriptionWhen a procedure value that refers to a bound procedure descriptor is used to make a call, the routinedesignated in the OTS_ENTRY field (typically OTS$JUMP_TO_BPV) receives control with theGP register pointing to the bound procedure descriptor (instead of a global offset table). This routineperforms the following steps:

1. Load the "real" target entry address into a volatile branch register, for example, B6.

2. Load the dynamic environment value into the appropriate uplevel-addressing register for the targetfunction, for example, OTS$JUMP_TO_BPV uses R9.

3. Load the "real" target GP address into the GP register.

4. Transfer control (branch, not call) to the target entry address.

Control arrives at the real target procedure address with both the GP and environment register valuesestablished appropriately.

48


Support routine OTS$JUMP_TO_BPV is included as a standard library routine. The operation ofOTS$JUMP_TO_BPV is logically equivalent to the following code:

OTS$JUMP_TO_BPV:: add gp=gp,24 ; Adjust GP to point to entry address ld8 r9=[gp],16 ; Load target entry address mov b6=r9 ld8 r9=[gp],-8 ; Load target environment value ld8 gp=[gp] ; Load target GP br b6 ; Transfer to target

Note that there can be multiple OTS$JUMP_TO_BPV-like support routines, corresponding todifferent target registers where the environment value should be placed. The code that creates thebound function descriptor is also necessarily compiled by the same compiler that compiles the targetprocedure, thus can correctly select an appropriate support routine.


OTS$MOVE3OTS$MOVE3 — The Move Data Without Fill routine moves up to 232 - 1 bytes (2,147,483,647bytes) from a specified source address to a specified destination address.

FormatOTS$MOVE3 length-value ,source-array ,destination-array

Corresponding JSB Entry PointOTS$MOVE3_R5

ReturnsNone.

Argumentslength-value


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

source-array

OpenVMS usage: vector_byte_unsigned

49


type: byte (unsigned)access: read onlymechanism: by reference, array reference

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

destination-array

OpenVMS usage: vector_byte_unsignedtype: byte (unsigned)access: write onlymechanism: by reference, array reference

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

DescriptionOTS$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, theregister outputs of OTS$MOVE3_R5 follow the same pattern as those of the MOVC3 instruction:

R0 0R1 Address of one byte beyond the source stringR2 0R3 Address of one byte beyond the destination stringR4 0R5 0

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


OTS$MOVE5OTS$MOVE5 — The Move Data with Fill routine moves up to 232 - 1 bytes (2,147,483,647bytes) from a specified source address to a specified destination address, with separate source anddestination lengths, and with fill. Overlap of the source and destination arrays does not affect theresult.

FormatOTS$MOVE5

50


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

Corresponding JSB Entry PointOTS$MOVE5_R5

ReturnsNone.

Argumentslongword-int-source-length


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

source-array

OpenVMS usage: vector_byte_unsignedtype: byte (unsigned)access: read onlymechanism: by reference, array reference

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

fill-value

OpenVMS usage: byte_unsignedtype: byte (unsigned)access: read onlymechanism: 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.

longword-int-dest-length

OpenVMS usage: longword_signedtype: longword (signed)access: read only

51


mechanism: by value

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

destination-array

OpenVMS usage: vector_byte_unsignedtype: byte (unsigned)access: write onlymechanism: by reference, array reference

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

DescriptionOTS$MOVE5 performs the same function as the VAX MOVC5 instruction except that the longword-int-source-length and longword-int-dest-length arguments are longword integers rather than wordintegers. When called from the JSB entry point, the register outputs of OTS$MOVE5_R5 follow thesame pattern as those of the MOVC5 instruction:

R0 Number of unmoved bytes remaining in source stringR1 Address of one byte beyond the source stringR2 0R3 Address of one byte beyond the destination stringR4 0R5 0

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


OTS$MULCxOTS$MULCx — The Complex Multiplication routines calculate the complex product of two complexvalues.

FormatOTS$MULCD_R3 complex-multiplier ,complex-multiplicand (VAX only)

OTS$MULCG_R3 complex-multiplier ,complex-multiplicand

OTS$MULCT_R3 complex-multiplier ,complex-multiplicand

52


OTS$MULCS complex-multiplier ,complex-multiplicand

These formats correspond to the D-floating, G-floating, IEEE S-floating, and IEEE T-floatingcomplex types.

ReturnsOpenVMS usage: complex_numbertype: D_floating complex, G_floating complex, IEEE S_floating complex, IEEE

T_floating complex,access: write onlymechanism: by value

Complex result of multiplying two complex numbers. OTS$MULCD_R3 returns a D-floatingcomplex number. OTS$MULCG_R3 returns a G-floating complex number. OTS$MULCS returns anIEEE S-Floating complex number. OTS$MULCT_R3 returns an IEEE T-floating complex number.

Argumentscomplex-multiplier

OpenVMS usage: complex_numbertype: D_floating complex, G_floating complex, S_floating complex, S_floating

complexaccess: read onlymechanism: by value

Complex multiplier. The complex-multiplier argument contains the complex multiplier. ForOTS$MULCD_R3, complex-multiplier is a D-floating complex number. For OTS$MULCG_R3,complex-multiplier is a G-floating complex number. For OTS$MULCS, complex-multiplier is aIEEE S-Floating complex number. For OTS$MULCT_R3, complex-multiplier is an IEEE T-floatingcomplex number.

complex-multiplicand

OpenVMS usage: complex_numbertype: D_floating complex, G_floating complex, IEEE S_floating complex, IEEE

T_floating complexaccess: read onlymechanism: by value

Complex multiplicand. The complex-multiplicand argument contains the complex multiplicand. ForOTS$MULCD_R3, complex-multiplicand is a D-floating complex number. For OTS$MULCG_R3,complex-multiplicand is a G-floating complex number. For OTS$MULCS, complex-multiplicandisan IEEE S-floating complex number. For OTS$MULCT_R3, complex-multiplicand is an IEEE T-floating complex number.

DescriptionOTS$MULCx calculates the complex product of two complex values.

53


The complex product is computed as follows:

1. Let (a,b) represent the complex multiplier.

2. Let (c,d) represent the complex multiplicand.

3. Let (r,i) represent the complex product.

The results of this computation are as follows:

(a,b) * (c,d) = (ac-bd) + (ad+bc)

Therefore: r = ac - bd Therefore: i = ad + bc

On Alpha and I64 systems, some restrictions apply when linking OTS$MULCG_R3, OTS$MULCS,and OTS$MULCT_R3. See Chapter 1 for more information about these restrictions.

Condition Values Signaled

SS$_FLTOVF_F Floating value overflow can occur.SS$_ROPRAND Reserved operand. OTS$MULCx encountered a floating-point

reserved operand because of incorrect user input. A floating-pointreserved operand is a floating-point datum with a sign bit of 1 and abiased exponent of zero. Floating-point reserved operands are reservedfor future OpenVMS use.

ExampleC+C This Fortran example forms the product ofC two complex numbers using OTS$MULCD_R3C and the Fortran random number generator RAN.CC Declare Z1, Z2, and Z_Q as complex values. OTS$MULCD_R3C returns the complex product of Z1 times Z2:C Z_Q = Z1 * Z2C-

COMPLEX*16 Z1,Z2,Z_QC+C Generate a complex number.C- Z1 = (8.0,4.0)C+C Generate another complex number.C- Z2 = (2.0,3.0)C+C Compute the complex product of Z1*Z2.C- Z_Q = Z1 * Z2 TYPE *, ' The complex product of',Z1,' times ',Z2,' is' TYPE *, ' ',Z_Q END

54


This Fortran example uses OTS$MULCD_R3 to multiply two complex numbers. The outputgenerated 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$POWCxCxOTS$POWCxCx — The Raise a Complex Base to a Complex Floating-Point Exponent routines raisea complex base to a complex exponent.

FormatOTS$POWCC complex-base ,complex-exponent-value

OTS$POWCDCD_R3 complex-base ,complex-exponent-value (VAX only)

OTS$POWCGCG_R3 complex-base ,complex-exponent-value

OTS$POWCSCS complex-base ,complex-exponent-value

OTS$POWCTCT_R3 complex-base ,complex-exponent-value


ReturnsOpenVMS usage: complex_numbertype: F_floating complex, D_floating complex, G_floating complex, IEEE

S_floating complex, IEEE T_floating complexaccess: write onlymechanism: by value

Result of raising a complex base to a complex exponent. OTS$POWCC returns an F-floating complexnumber. OTS$POWCDCD_R3 returns a D-floating complex number. OTS$POWCGCG_R3 returnsa G-floating complex number. OTS$POWCSCS returns an IEEE S-floating complex number.OTS$POWCTCT_R3 returns an IEEE T-floating complex number.

Argumentscomplex-base



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 aD-floating complex number. For OTS$POWCGCG_R3, complex-base is a G-floating complex

55


number. For OTS$POWCSCS, complex-base is an IEEE S-floating complex number. ForOTS$POWCTCT_R3, complex-base is an IEEE T-floating complex number.

complex-exponent-value



Complex exponent. The complex-exponent-value argument contains the value of theexponent. For OTS$POWCC, complex-exponent-value is an F-floating complex number.For OTS$POWCDCD_R3, complex-exponent-value is a D-floating complex number. ForOTS$POWCGCG_R3, complex-exponent-value is a G-floating complex number. ForOTS$POWCSCS, complex-exponent-value is an IEEE S-floating complex number. ForOTS$POWCTCT_R3, complex-exponent-value is an IEEE T-floating complex number.

DescriptionOTS$POWCC, OTS$POWCDCD_R3, OTS$POWCGCG_R3, OTS$POWCSCS, andOTS$POWCSCT_R3 raise a complex base to a complex exponent. The American National StandardFORTRAN-77 (ANSI X3.9—1978) defines complex exponentiation as follows:

xy = exp(y * log(x))

In this example, x and y are of type COMPLEX.

On Alpha and I64 systems, some restrictions apply when linking OTS$POWCC orOTS$POWCGCG_R3. See Chapter 1 for more information about these restrictions.

Condition Values SignaledMTH$_INVARGMAT Invalid argument in math library. Base is (0.,0.).MTH$_FLOOVEMAT Floating-point overflow in math library.SS$_ROPRAND Reserved operand.

Examples1. C+

C This Fortran example raises a complex base to a complexC power using OTS$POWCC.CC Declare Z1, Z2, Z3, and OTS$POWCC as complex values. Then OTS$POWCCC returns the complex result of Z1**Z2: Z3 = OTS$POWCC(Z1,Z2),C where Z1 and Z2 are passed by value.C-

COMPLEX Z1,Z2,Z3,OTS$POWCCC+C Generate a complex base.C-

56


Z1 = (2.0,3.0)C+C Generate a complex power.C- Z2 = (1.0,2.0)C+C Compute the complex value of Z1**Z2.C- 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-floatingcomplex 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)

2. C+C This Fortran example raises a complex base to a complexC power using OTS$POWCGCG_R3.CC Declare Z1, Z2, and Z3 as complex values. OTS$POWCGCG_R3C returns the complex result of Z1**Z2: Z3 = Z1**Z2.C-

COMPLEX*16 Z1,Z2,Z3C+C Generate a complex base.C- Z1 = (2.0,3.0)C+C Generate a complex power.C- Z2 = (1.0,2.0)C+C Compute the complex value of Z1**Z2.C- Z3 = Z1**Z2 TYPE 1,Z1,Z2,Z3 1 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 precisionin the output generated by this program:

The value of ( 2.00000000, 3.00000000)**( 1.00000000, 2.00000000) is(-0.46395650,-0.46395650).

OTS$POWCxJOTS$POWCxJ — The Raise a Complex Base to a Signed Longword Integer Exponent routines returnthe complex result of raising a complex base to an integer exponent.

57


FormatOTS$POWCJ complex-base ,longword-integer-exponent

OTS$POWCDJ_R3 complex-base ,longword-integer-exponent (VAX only)

OTS$POWCGJ_R3 complex-base ,longword-integer-exponent (VAX only)

OTS$POWCSJ complex-base ,longword-integer-exponent

OTS$POWCTJ_R3 complex-base ,longword-integer-exponent


Returns


S_floating complex, IEEE T_floating complexaccess: write onlymechanism: by value

Complex result of raising a complex base to an integer exponent. OTS$POWCJ returns an F-floatingcomplex number. OTS$POWCDJ_R3 returns a D-floating complex number. OTS$POWCGJ_R3returns a G-floating complex number. OTS$POWCGS_R3 returns an IEEE S-floating complexnumber. OTS$POWCGT_R3 returns an IEEE T-floating complex number. In each format, the resultand base are of the same data type.

Argumentscomplex-base

OpenVMS usage: complex_numbertype: F_floating complex, D_floating complex, G_floating complex, S_floating

complex, T_floating complex,access: read onlymechanism: 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 aD-floating complex number. For OTS$POWCGJ_R3, complex-base is a G-floating complexnumber. For OTS$POWCSJ, complex-base is an IEEE S-floating complex number. ForOTS$POWCTJ_R3,complex-base is an IEEE T-floating complex number.

longword-integer-exponent

OpenVMS usage: longword_signedtype: longword (signed)access: read only

58


mechanism: by value

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

DescriptionThe OTS$POWCxJ routines return the complex result of raising a complex base to an integerexponent. The complex result is as follows:

Base Exponent ResultAny > 0 The product of (base**2 i), where i is each nonzero bit in longword-

integer-exponent.(0.,0.) <= 0 Undefined exponentiation.Not(0.,0.)

< 0 The product of (base**2 i), where i is each nonzero bit in longword-integer-exponent.

Not(0.,0.)

0 (1.0,0.0)

On Alpha and I64 systems, some restrictions apply when linking OTS$POWCJ, OTS$POWCSJ, andOTS$POWCTJ_R3. See Chapter 1 for more information about these restrictions.


SS$_FLTDIV Floating-point division by zero.SS$_FLTOVF Floating-point overflow.MTH$_UNDEXP Undefined exponentiation.

Example+C This Fortran example raises a complex base toC a NONNEGATIVE integer power using OTS$POWCJ.CC Declare Z1, Z2, Z3, and OTS$POWCJ as complex values.C Then OTS$POWCJ returns the complex result ofC Z1**Z2: Z3 = OTS$POWCJ(Z1,Z2),C where Z1 and Z2 are passed by value.C- COMPLEX Z1,Z3,OTS$POWCJ INTEGER Z2C+C Generate a complex base.C- Z1 = (2.0,3.0)C+C Generate an integer power.C- Z2 = 2

C+

59


C Compute the complex value of Z1**Z2.C- Z3 = OTS$POWCJ( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), %VAL(Z2)) TYPE 1,Z1,Z2,Z3 1 FORMAT(' The value of (',F10.8,',',F11.8,')**',I1,' 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$POWDDOTS$POWDD — The Raise a D-Floating Base to a D-Floating Exponent routine raises a D-floatingbase to a D-floating exponent.

FormatOTS$POWDD D-floating-point-base ,D-floating-point-exponent

Returns

OpenVMS usage: floating_pointtype: D_floatingaccess: write onlymechanism: by value

Result of raising a D-floating base to a D-floating exponent.

ArgumentsD-floating-point-base

OpenVMS usage: floating_pointtype: D_floatingaccess: read onlymechanism: by value

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

D-floating-point-exponent


60


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

DescriptionOTS$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:

Base Exponent Result= 0 > 0 0.0= 0 = 0 Undefined exponentiation= 0 < 0 Undefined exponentiation< 0 Any Undefined exponentiation> 0 > 0 2 [exponent*log2(base)]

> 0 = 0 1.0> 0 < 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 baseis negative.


MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponentiation. This error is signaled if D-floating-point-

base is zero and D-floating-point-exponent is zero or negative, or ifthe D-floating-point-base is negative.

OTS$POWDJOTS$POWDJ — The Raise a D-Floating Base to a Longword Exponent routine raises a D-floatingbase to a longword exponent.

FormatOTS$POWDJ D-floating-point-base ,longword-integer-exponent

Returns

OpenVMS usage: floating_pointtype: D_floating

61



Result of raising a D-floating base to a longword exponent.






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

DescriptionOTS$POWDJ raises a D-floating base to a longword exponent.


The floating-point result is as follows:

Base Exponent ResultAny > 0 Product of ( base**2 i ), where i is each nonzero bit position in longword-

integer-exponent.> 0 = 0 1.0= 0 = 0 Undefined exponentiation.< 0 = 0 1.0> 0 < 0 1.0/( base**2 i ), where i is each nonzero bit position in longword-integer-

exponent.= 0 < 0 Undefined exponentiation.< 0 < 0 1.0/( base**2 i ), where i is each nonzero bit position in longword-integer-

exponent.


62


Undefined exponentiation occurs if the base is zero and the exponent is zero or negative.


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


base is zero and longword-integer-exponent is zero or negative, or ifthe D-floating-point-base is negative.

OTS$POWDROTS$POWDR — The Raise a D-Floating Base to an F-Floating Exponent routine raises a D-floatingbase to an F-floating exponent.

FormatOTS$POWDR D-floating-point-base ,F-floating-point-exponent

Returns

OpenVMS usage: floating_pointtype: D_floatingaccess: write onlymechanism: by value

Result of raising a D-floating base to an F-floating exponent.




F-floating-point-exponent

OpenVMS usage: floating_pointtype: F_floatingaccess: read only

63


mechanism: by value

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

DescriptionOTS$POWDR raises a D-floating base to an F-floating exponent.


OTS$POWDR converts the F-floating exponent to a D-floating number. The D-floating result forOTS$POWDR is given by the following:

Base Exponent Result= 0 > 0 0.0= 0 = 0 Undefined exponentiation= 0 < 0 Undefined exponentiation< 0 Any Undefined exponentiation> 0 > 0 2 [exponent*log2 (base)]

> 0 = 0 1.0> 0 < 0 2 [exponent*log2 (base)]






base is zero and F-floating-point-exponent is zero or negative, or ifthe D-floating-point-base is negative.

OTS$POWGGOTS$POWGG — The Raise a G-Floating Base to a G-Floating Exponent routine raises a G-floatingbase to a G-floating exponent.

FormatOTS$POWGG G-floating-point-base ,G-floating-point-exponent

64


ReturnsOpenVMS usage: floating_pointtype: G_floatingaccess: write onlymechanism: by value

Result of raising a G-floating base to a G-floating exponent.

ArgumentsG-floating-point-base

OpenVMS usage: floating_pointtype: G_floatingaccess: read onlymechanism: by value

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

G-floating-point-exponent


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

DescriptionOTS$POWGG raises a G-floating base to a G-floating exponent.


The G-floating result for OTS$POWGG is as follows:



65




On Alpha and I64 systems, some restrictions apply when linking OTS$POWGG. See Chapter 1 formore information about these restrictions.



MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponent. This error is signaled if G-floating-point-base

is zero and G-floating-point-exponent is zero or negative, or if G-floating-point-base is negative.

ExampleC+C This example demonstrates the use of OTS$POWGG,C which raises a G-floating point baseC to a G-floating point power.C- REAL*8 X,Y,RESULT,OTS$POWGGC+C The arguments of OTS$POWGG are passed by value. Fortran canC only pass INTEGER and REAL*4 expressions as VALUE. SinceC INTEGER and REAL*4 values are one longword long, while REAL*8C values are two longwords long, equate the base (and power) toC two-dimensional INTEGER vectors. These vectors will be passedC by VALUE.C- INTEGER N(2),M(2) EQUIVALENCE (N(1),X), (M(1),Y) X = 8.0 Y = 2.0C+C To pass X by value, pass N(1) and N(2) by value. Similarly for Y.C- 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.5C+C In Fortran, OTS$POWWGG is indirectly called by simply using theC exponentiation operator.C- 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.

66


The output generated by this example is as follows:

8.0**2.0 IS 64.00000000000009.0**-0.5 IS 0.333333333333333

OTS$POWGJOTS$POWGJ — The Raise a G-Floating Base to a Longword Exponent routine raises a G-floatingbase to a longword exponent.

FormatOTS$POWGJ G-floating-point-base ,longword-integer-exponent

ReturnsOpenVMS usage: floating_pointtype: G_floatingaccess: write onlymechanism: by value

Result of raising a G-floating base to a longword exponent.

ArgumentsG-floating-point-base


Base that OTS$POWGJ raises to a longword exponent. The G-floating-point-base argument is a G-floating number containing the base.



Exponent to which OTS$POWGJ raises the base. The longword-integer-exponent argument is asigned longword containing the exponent.

DescriptionOTS$POWGJ raises a G-floating base to a longword exponent.

67







exponent.



On Alpha and I64 systems, some restrictions apply when linking OTS$POWGJ. See Chapter 1 formore information about these restrictions.

Condition Values SignaledSS$_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$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponent. This error is signaled if G-floating-point-base

is zero and longword-integer-exponent is zero or negative, or if G-floating-point-base is negative.

OTS$POWHH_R3 (VAX Only)OTS$POWHH_R3 (VAX Only) — On VAX systems, the Raise an H-Floating Base to an H-FloatingExponent routine raises an H-floating base to an H-floating exponent.

FormatOTS$POWHH_R3 H-floating-point-base ,H-floating-point-exponent

ReturnsOpenVMS usage: floating_pointtype: H_floating

68



Result of raising an H-floating base to an H-floating exponent.

ArgumentsH-floating-point-base

OpenVMS usage: floating_pointtype: H_floatingaccess: read onlymechanism: by value

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

H-floating-point-exponent


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

DescriptionOTS$POWHH_R3 raises an H-floating base to an H-floating exponent.


The H-floating result for OTS$POWHH_R3 is as follows:





69



point overflow occurs.MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponentiation. This error is signaled if H-floating-point-

base is zero and H-floating-point-exponent is zero or negative, or ifthe H-floating-point-base is negative.

ExampleC+C Example of OTS$POWHH, which raises an H_floatingC point base to an H_floating point power. In Fortran,C it is not directly called.C- REAL*16 X,Y,RESULT X = 9877356535.0 Y = -0.5837653C+C In Fortran, OTS$POWWHH is indirectly called by simply using theC exponentiation operator.C- 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 anH-floating power.

The output generated by this program is as follows:

9877356535.0**-0.5837653 IS 1.463779145994628357482343598205427E-0006

OTS$POWHJ_R3 (VAX Only)OTS$POWHJ_R3 (VAX Only) — On VAX systems, the Raise an H-Floating Base to a LongwordExponent routine raises an H-floating base to a longword exponent.

FormatOTS$POWHJ_R3 H-floating-point-base ,longword-integer-exponent

ReturnsOpenVMS usage: floating_pointtype: H_floatingaccess: write only

70


mechanism: by value

Result of raising an H-floating base to a longword exponent.

ArgumentsH-floating-point-base


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



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

DescriptionOTS$POWHJ_R3 raises an H-floating base to a longword exponent.






exponent.



71



point overflow occurs.MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponentiation. This error is signaled if H-floating-point-

base is zero and longword-integer-exponent is zero or negative, or ifthe H-floating-point-base is negative.

OTS$POWIIOTS$POWII — The Raise a Word Base to a Word Exponent routine raises a word base to a wordexponent.

FormatOTS$POWII word-integer-base ,word-integer-exponent

ReturnsOpenVMS usage: word_signedtype: word (signed)access: write onlymechanism: by value

Result of raising a word base to a word exponent.

Argumentsword-integer-base


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

word-integer-exponent


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

72


DescriptionThe OTS$POWII routine raises a word base to a word exponent.

On Alpha and I64 systems, some restrictions apply when linking OTS$POWII. See Chapter 1 formore information about these restrictions.

Condition Values SignaledSS$_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-integer-exponent is zero or negative, or if word-integer-base is negative.

OTS$POWJJOTS$POWJJ — The Raise a Longword Base to a Longword Exponent routine raises a signedlongword base to a signed longword exponent.

FormatOTS$POWJJ longword-integer-base ,longword-integer-exponent

ReturnsOpenVMS usage: longword_signedtype: longword (signed)access: write onlymechanism: by value

Result of raising a signed longword base to a signed longword exponent.

Argumentslongword-integer-base


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


OpenVMS usage: longword_signed

73


type: longword (signed)access: read onlymechanism: by value

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

DescriptionThe OTS$POWJJ routine raises a signed longword base to a signed longword exponent.

On Alpha and I64 systems, some restrictions apply when linking OTS$POWJJ. See Chapter 1 formore information about these restrictions.

Condition Values SignaledSS$_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 longword-integer-exponent is zero or negative, or iflongword-integer-base is negative.

OTS$POWLULUOTS$POWLULU — The Raise an Unsigned Longword Base to an Unsigned Longword Exponentroutine raises an unsigned longword integer base to an unsigned longword integer exponent.

FormatOTS$POWLULU unsigned-lword-int-base, unsigned-lword-int-exponent

ReturnsOpenVMS usage: longword_unsignedtype: longword (unsigned)access: write onlymechanism: by value

Result of raising an unsigned longword integer base to an unsigned longword integer exponent.

Argumentsunsigned-lword-int-base

OpenVMS usage: longword_unsignedtype: longword (unsigned)access: read only

74


mechanism: by value

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

unsigned-lword-int-exponent


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

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

On Alpha and I64 systems, some restrictions apply when linking OTS$POWLULU. See Chapter 1 formore information about these restrictions.

Condition Values SignaledMTH$_UNDEXP Both the base and exponent values are zero.

OTS$POWRDOTS$POWRD — The Raise an F-Floating Base to a D-Floating Exponent routine raises an F-floatingbase to a D-floating exponent.

FormatOTS$POWRD F-floating-point-base ,D-floating-point-exponent

ReturnsOpenVMS usage: floating_pointtype: D_floatingaccess: write onlymechanism: by value

Result of raising an F-floating base to a D-floating exponent.

ArgumentsF-floating-point-base

75


OpenVMS usage: floating_pointtype: F_floatingaccess: read onlymechanism: by value

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

D-floating-point-exponent


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

DescriptionOTS$POWRD raises an F-floating base to a D-floating exponent.


OTS$POWRD first converts the F-floating base to D-floating. The D-floating result forOTS$POWRD is as follows:

Base Exponent Result= 0 > 0 0.0= 0 = 0 Undefined exponentiation= 0 < 0 Undefined exponentiation< 0 Any Undefined exponentiation> 0 > 0 2 [exponent*LOG2(base)]

> 0 = 0 1.0> 0 < 0 2 [exponent*LOG2(base)]





MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.

76


MTH$_UNDEXP Undefined exponentiation. This error is signaled if F-floating-point-baseis zero and D-floating-point-exponent is zero or negative, or ifF-floating-point-base is negative.

ExampleC+C This Fortran example uses OTS$POWRD, to raise an F-floating pointC base to a D-floating point exponent. The result is a D-floating value.C- REAL*4 X REAL*8 Y,RESULT,OTS$POWRD INTEGER M(2) EQUIVALENCE (M(1),Y) X = 9768.0 Y = 9.0C+C The arguments of OTS$POWRD are passed by value.C- RESULT = OTS$POWRD(%VAL(X),%VAL(M(1)),%VAL(M(2))) TYPE *,' 9768.0**9.0 IS ',RESULT X = 7689.0 Y = -0.587436654545C+C In Fortran, OTS$POWRD is indirectly called by the exponentiationC operator.C- 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. Noticethe difference in the precision of the result produced by this routine in comparison to the resultproduced by OTS$POWRR. The output generated by this program is as follows:

9768.0**9.0 IS 8.0956338648832908E+357689.0**-0.587436654545 IS 5.2155199252836588E-03

OTS$POWRJOTS$POWRJ — The Raise an F-Floating Base to a Longword Exponent routine raises an F-floatingbase to a longword exponent.

FormatOTS$POWRJ F-floating-point-base ,longword-integer-exponent

ReturnsOpenVMS usage: floating_pointtype: F_floating

77



Result of raising an F-floating base to a longword exponent.






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

DescriptionOTS$POWRJ raises an F-floating base to a longword exponent.






exponent.



78


On Alpha and I64 systems, some restrictions apply when linking OTS$POWRJ. See Chapter 1 formore information about these restrictions.


point overflow occurs.MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponentiation. This error is signaled if F-floating-point-

baseis zero and longword-integer-exponent is zero or negative, or ifF-floating-point-base is negative.

OTS$POWRROTS$POWRR — The Raise an F-Floating Base to an F-Floating Exponent routine raises an F-floating base to an F-floating exponent.

FormatOTS$POWRR F-floating-point-base ,F-floating-point-exponent

ReturnsOpenVMS usage: floating_pointtype: F_floatingaccess: write onlymechanism: by value

Result of raising an F-floating base to an F-floating exponent.




F-floating-point-exponent

OpenVMS usage: floating_pointtype: F_floatingaccess: read only

79


mechanism: by value

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

DescriptionOTS$POWRR raises an F-floating base to an F-floating exponent.


The F-floating result for OTS$POWRR is as follows:

Base Exponent Result= 0 > 0 0.0= 0 = 0 Undefined exponentiation= 0 < 0 Undefined exponentiation< 0 Any Undefined exponentiation> 0 > 0 2 [exponent*log2( base)]

> 0 = 0 1.0> 0 < 0 2 [exponent*log2( base)]



On Alpha and i64 systems, some restrictions apply when linking OTS$POWRR. See Chapter 1 formore information about these restrictions.


point overflow occurs.MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponentiation. This error is signaled if F-floating-point-

baseis zero and F-floating-point-exponent is zero or negative, or ifF-floating-point-base is negative.

ExampleC+C This Fortran example demonstrates the useC of OTS$POWRR, which raises an F-floatingC point base to an F-floating point power.C-

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

80


Y = 2.0

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

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 simplyC using the exponentiation operator.C-

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

This Fortran example uses OTS$POWRR to raise an F-floating point base to an F-floating pointexponent. The output generated by this program is as follows:

8.0**2.0 IS 64.000009.0**-0.5 IS 0.3333333

OTS$POWSJOTS$POWSJ — The Raise an IEEE S-Floating Base to a Longword Exponent routine raises an IEEES-floating base to a longword exponent.

FormatOTS$POWSJ S-floating-point-base ,longword-integer-exponent

ReturnsOpenVMS usage: floating_pointtype: S_floatingaccess: write onlymechanism: by value

Result of raising an IEEE S-floating base to a longword exponent.

ArgumentsS-floating-point-base

OpenVMS usage: floating_pointtype: S_floating

81


access: read onlymechanism: by value

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




DescriptionOTS$POWSJ raises an IEEE S-floating base to a longword exponent.



Base Exponent ResultAny > 0 Product of (base**2 i), where i is each nonzero bit position in longword-

integer-exponent.> 0 = 0 1.0= 0 = 0 Undefined exponentiation.< 0 = 0 1.0> 0 < 0 1.0/(base**2 i), where i is each nonzero bit position in longword-integer-

exponent.= 0 < 0 Undefined exponentiation.< 0 < 0 1.0/(base**2 i), where i is each nonzero bit position in longword-integer-

exponent.



On Alpha and I64 systems, some restrictions apply when linking OTS$POWSJ. See Chapter 1 formore information about these restrictions.


point overflow occurs.MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.

82


MTH$_UNDEXP Undefined exponentiation. This error is signaled if S-floating-point-baseis zero and longword-integer-exponent is zero or negative, or ifS-floating-point-base is negative.

OTS$POWSSOTS$POWSS — The Raise an IEEE S-Floating Base to an IEEE S-Floating Exponent routine raises aIEEE S-floating base to an IEEE S-floating exponent.

FormatOTS$POWSS S-floating-point-base ,S-floating-point-exponent

ReturnsOpenVMS usage: floating_pointtype: IEEE S_floatingaccess: write onlymechanism: by value

Result of raising an IEEE S-floating base to an IEEE S-floating exponent.

ArgumentsS-floating-point-base

OpenVMS usage: floating_pointtype: IEEE S_floatingaccess: read onlymechanism: by value

Base that OTS$POWSS raises to an IEEE S-floating exponent. The S-floating-point-base argumentis an IEEE S-floating number containing the base.

S-floating-point-exponent

OpenVMS usage: floating_pointtype: IEEE S_floatingaccess: read onlymechanism: by value

Exponent to which OTS$POWSS raises the base. The S-floating-point-exponent argument is anIEEE S-floating number containing the exponent.

DescriptionOTS$POWSS raises an IEEE S-floating base to an IEEE S-floating exponent.


83


The S-floating result for OTS$POWSS is as follows:





On Alpha and I64 systems, some restrictions apply when linking OTS$POWSS. See Chapter 1 formore information about these restrictions.


point overflow occurs.MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponent. This error is signaled if S-floating-point-base

is zero and S-floating-point-exponent is zero or negative, or if S-floating-point-base is negative.

ExampleThe following example demonstrates the use of OTS$POWSS.

C+C This Fortran example demonstrates the use ofC OTS$POWSS, which raises an IEEE S-floatingC point base to an IEEE S-floating point power.C-

OPTIONS /FLOAT=IEEE_FLOAT

REAL*4 X,Y,RESULT,OTS$POWSS X = 10.0 Y = 3.0

C+C The arguments of OTS$POWSS are passed by value.C-

RESULT = OTS$POWSS(%VAL(X),%VAL(Y)) TYPE *,' 10.0**3.0 IS ',RESULT

84


X = 9.0 Y = -0.5

C+C In Fortran, OTS$POWSS is indirectly called byC simply using the exponentiation operator.C-


This Fortran example uses OTS$POWSS to raise an IEEE S-floating point base to an IEEE S-floatingpoint exponent. The output generated by this program is as follows:

10.0**3.0 IS 1000.000 9.0**-0.5 IS 0.3333333

OTS$POWTJOTS$POWTJ — The Raise a T-Floating base to a Longword Exponent routine raises an IEEE T-floating base to a longword exponent.

FormatOTS$POWTJ T-floating-point-base ,longword-integer-exponent

ReturnsOpenVMS usage: floating_pointtype: IEEE T_floatingaccess: write onlymechanism: by value

Result of raising an IEEE T-floating base to a longword exponent.

ArgumentsT-floating-point-base

OpenVMS usage: floating_pointtype: IEEE T_floatingaccess: read onlymechanism: by value

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


OpenVMS usage: longword_signedtype: longword (signed)

85




DescriptionOTS$POWTJ raises an IEEE T-floating base to a longword exponent.






exponent.



On Alpha and I64 systems, some restrictions apply when linking OTS$POWTJ. See Chapter 1 formore information about these restrictions.


point overflow occurs.MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponentiation. This error is signaled if T-floating-point-

base is zero and longword-integer-exponent is zero or negative, or ifT-floating-point-base is negative.

OTS$POWTTOTS$POWTT — The Raise an IEEE T-Floating Base to an IEEE T-Floating Exponent routine raisesan IEEE T-floating base to an IEEE T-floating exponent.

86


FormatOTS$POWTT T-floating-point-base ,T-floating-point-exponent

ReturnsOpenVMS usage: floating_pointtype: IEEE T_floatingaccess: write onlymechanism: by value

Result of raising an IEEE T-floating base to an IEEE T-floating exponent.

ArgumentsT-floating-point-base


Base that OTS$POWTT raises to an IEEE T-floating exponent. The T-floating-point-base argumentis an IEEE T-floating number containing the base.

T-floating-point-exponent


Exponent to which OTS$POWTT raises the base. The T-floating-point-exponent argument is anIEEE T-floating number containing the exponent.

DescriptionOTS$POWTT raises an IEEE T-floating base to an IEEE T-floating exponent.


The T-floating result for OTS$POWTT is as follows:

Base Exponent Result= 0 > 0 0.0= 0 = 0 Undefined exponentiation= 0 < 0 Undefined exponentiation< 0 Any Undefined exponentiation

87


Base Exponent Result> 0 > 0 2 [exponent*log2(base)]




On Alpha and I64 systems, some restrictions apply when linking OTS$POWTT. See Chapter 1 formore information about these restrictions.


point overflow occurs.MTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT Floating-point underflow in math library.MTH$_UNDEXP Undefined exponent. This error is signaled if T-floating-point-base

is zero and T-floating-point-exponent is zero or negative, or if T-floating-point-base is negative.

ExampleThe following example demonstrates the use of OTS$POWTT.

C+C This Fortran example demonstrates the use ofC OTS$POWTT, which raises an IEEE T-floatingC point base to an IEEE T-floating point power.C-

OPTIONS /FLOAT=IEEE_FLOAT

REAL*8 X,Y,RESULT,OTS$POWTT X = 10.0 Y = 3.0

C+C The arguments of OTS$POWTT are passed by value.C-

RESULT = OTS$POWTT(%VAL(X),%VAL(Y)) TYPE *,' 10.0**3.0 IS ',RESULT X = 9.0 Y = -0.5

C+C In Fortran, OTS$POWTT is indirectly called byC simply using the exponentiation operator.C-

88



This Fortran example uses OTS$POWTT to raise an IEEE T-floating point base to an IEEE T-floatingpoint exponent. The output generated by this program is as follows:

10.0**3.0 IS 1000.00000000000 9.0**-0.5 IS 0.333333333333333

OTS$POWxLUOTS$POWxLU — The Raise a Floating-Point Base to an Unsigned Longword Integer Exponentroutines raise a floating-point base to an unsigned longword integer exponent.

FormatOTS$POWRLU 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$POWSLU floating-point-base ,unsigned-lword-int-exponent

OTS$POWTLU floating-point-base ,unsigned-lword-int-exponent

OTS$POWHLU_R3 floating-point-base ,unsigned-lword-int-exponent (VAX only)

ReturnsOpenVMS usage: floating_pointtype: F_floating, D_floating, G_floating, H_floating, IEEE S_floating, IEEE

T_floatingaccess: write onlymechanism: by value

Result of raising a floating-point base to an unsigned longword integer exponent. OTS$POWRLUreturns an F-floating number. OTS$POWDLU returns a D-floating number. OTS$POWGLU returnsa G-floating number. OTS$POWSLU returns an IEEE S-floating number. OTS$POWTLU returns anIEEE T-floating number.

On VAX systems, OTS$POWHLU_R3 returns an H-floating number.

Argumentsfloating-point-base

OpenVMS usage: floating_pointtype: F_floating, D_floating, G_floating, H_floating, IEEE S_floating, IEEE

T_floating

89



Floating-point base. The floating-point-base argument contains the value of the base. ForOTS$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. ForOTS$POWHLU_R3, floating-point-base is an H-floating number. For OTS$POWSLU, floating-point-base is an IEE S-floating number. For OTS$POWTLU, floating-point-base is an IEEE T-floating number.

unsigned-lword-int-exponent


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

DescriptionThe OTS$POWxLU routines return the result of raising a floating-point base to an unsigned longwordinteger exponent. The floating-point result is as follows:

Base Exponent ResultAny > 0 Product of ( base*2 i ), where i is each nonzero bit position in longword-

integer-exponent.> 0 = 0 1.0= 0 = 0 Undefined exponentiation.< 0 = 0 1.0

On Alpha and I64 systems, some restrictions apply when linking OTS$POWRLU, OTS$POWGLU,OTS$POWSLU, and OTS$POWTLU. See Chapter 1 for more information about these restrictions.

Condition Values SignaledMTH$_FLOOVEMAT Floating-point overflow in math library.MTH$_FLOUNDMAT 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

andunsigned-longword-integer-exponent arguments are zero.

OTS$SCOPY_DXDXOTS$SCOPY_DXDX — The Copy a Source String Passed by Descriptor to a Destination Stringroutine copies a source string to a destination string. Both strings are passed by descriptor.

90


FormatOTS$SCOPY_DXDX source-string ,destination-string

Corresponding JSB Entry PointOTS$SCOPY_DXDX6

Returns

OpenVMS usage: word_unsignedtype: word (unsigned)access: write onlymechanism: by value

Number of bytes not moved to the destination string if the length of source-string is greater than thelength of destination-string. The value is 0 (zero) otherwise.

Argumentssource-string


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, noncontiguousarray, or varying.

destination-string


Destination string. The destination-string argument is the address of a descriptor pointing to thedestination string. The class field determines the appropriate action.

See the Description section for further information.

DescriptionOTS$SCOPY_DXDX copies a source string to a destination string. It passes the source stringby descriptor. If the length of the source string is greater than the length of the destination string,OTS$SCOPY_DXDX returns the number of bytes not moved to the destination string. If the length

91


of the source string is less than or equal to the length of the destination string, it returns 0 (zero). Allerror conditions except truncation are signaled; truncation is ignored.

An equivalent JSB entry point is provided, with R0 being the first argument (the descriptor of thesource string), and R1 the second (the descriptor of the destination string). On return, R0 throughR5 and the PSL are as they would be after a VAX MOVC5 instruction. R0 through R5 contain thefollowing:

R0 Number of bytes of source string not moved to destination stringR1 Address one byte beyond the last copied byte in the source stringR2 0R3 Address one byte beyond the destination stringR4 0R5 0

For further information, see the VAX Architecture Reference Manual.

The actions taken by OTS$SCOPY_DXDX depend on the descriptor class of the destination string.The following table describes these actions for each descriptor class:

DescriptorClass

Action

S, Z, SD, A,NCA

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

D If the area specified by the destination descriptor is large enough to contain the sourcestring, 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 stringand set the new length and address in the destination descriptor.

VS Copy source string to destination string up to the limit of the destination descriptor'sMAXSTRLEN field with no padding. Adjust the string's current length field(CURLEN) to the actual number of bytes copied.

Condition Values SignaledOTS$_FATINTERR Fatal internal error.OTS$_INVSTRDES Invalid string descriptor.OTS$_INSVIRMEM Insufficient virtual memory.

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

FormatOTS$SCOPY_R_DX

92


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

Corresponding JSB Entry PointOTS$SCOPY_R_DX6

Returns

OpenVMS usage: word_unsignedtype: word (unsigned)access: write onlymechanism: by value

Number of bytes not moved to the destination string if the length of the source string pointed to bysource-string-address is greater than the length of destination-string. Otherwise, the value is 0(zero).

Argumentsword-int-source-length-val

OpenVMS usage: word_unsignedtype: word (unsigned)access: read onlymechanism: by value

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

source-string-address

OpenVMS usage: char_stringtype: character stringaccess: read onlymechanism: by reference

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

destination-string


Destination string. The destination-string argument is the address of a descriptor pointing to thedestination string. OTS$SCOPY_R_DX determines the appropriate action based on the descriptor'sCLASS field. The descriptor's LENGTH field alone or both the POINTER and LENGTH fields can

93


be modified if the string is dynamic. For varying strings, the string's current length (CURLEN) isrewritten.

DescriptionOTS$SCOPY_R_DX copies a source string to a destination string. It passes the source string byreference preceded by a length argument. The length argument, word-int-source-length-val, ispassed by value.

If the length of the source string is greater than the length of the destination string,OTS$SCOPY_R_DX returns the number of bytes not moved to the destination string. If the lengthof the source string is less than or equal to the length of the destination string, it returns 0 (zero). Allconditions except truncation are signaled; truncation is ignored.

An equivalent JSB entry point is provided, with R0 being the first argument, R1 the second, and R2the third, if any. The length argument is passed in bits 15:0 of the appropriate register. On return,R0 through R5 and the PSL are as they would be after a VAX MOVC5 instruction. R0 through R5contain the following:

R0 Number of bytes of source string not moved to destination stringR1 Address one byte beyond the last copied byte in the source stringR2 0R3 Address one byte beyond the destination stringR4 0R5 0

For additional information, see the VAX Architecture Reference Manual.

The actions taken by OTS$SCOPY_R_DX depend on the descriptor class of the destination string.The following table describes these actions for each descriptor class:

DescriptorClass

Action

S, Z, SD, A,NCA

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

D If the area specified by the destination descriptor is large enough to contain the sourcestring, 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 stringand set the new length and address in the destination descriptor.

VS Copy source string to destination string up to the limit of the descriptor'sMAXSTRLEN field with no padding. Adjust the string's current length (CURLEN)field to the actual number of bytes copied.

Condition Values SignaledOTS$_FATINTERR Fatal internal error.OTS$_INVSTRDES Invalid string descriptor.OTS$_INSVIRMEM Insufficient virtual memory.

94


ExampleA Fortran example that demonstrates the manipulation of dynamic strings appears at theend of OTS$SGET1_DD. This example uses OTS$SCOPY_R_DX, OTS$SGET1_DD, andOTS$SFREE1_DD.

OTS$SFREE1_DDOTS$SFREE1_DD — The Strings, Free One Dynamic routine returns one dynamic string area to freestorage.

FormatOTS$SFREE1_DD dynamic-descriptor

Corresponding JSB Entry PointOTS$SFREE1_DD6

ReturnsNone.

Argumentsdynamic-descriptor

OpenVMS usage: quadword_unsignedtype: quadword (unsigned)access: modifymechanism: by reference

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

DescriptionOTS$SFREE1_DD deallocates the described string space and flags the descriptor as describing nostring at all. The descriptor's POINTER and LENGTH fields contain 0.

Condition Values SignaledOTS$_FATINTERR Fatal internal error.

ExampleA Fortran example that demonstrates the manipulation of dynamic strings appears at theend of OTS$SGET1_DD. This example uses OTS$SFREE1_DD, OTS$SGET1_DD, andOTS$SCOPY_R_DX.

95


OTS$SFREEN_DDOTS$SFREEN_DD — The Free n Dynamic Strings routine takes as input a vector of one or moredynamic string areas and returns them to free storage.

FormatOTS$SFREEN_DD descriptor-count-value ,first-descriptor

Corresponding JSB Entry PointOTS$SFREEN_DD6

ReturnsNone.

Argumentsdescriptor-count-value


Number of adjacent descriptors to be flagged as having no allocated area (the descriptor's POINTERand LENGTH fields contain 0) and to have their allocated areas returned to free storage byOTS$SFREEN_DD. The descriptor-count-value argument is an unsigned longword containing thisnumber.

first-descriptor


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

DescriptionOTS$SFREEN_DD6 deallocates the described string space and flags each descriptor as describing nostring at all. The descriptor's POINTER and LENGTH fields contain 0.

Condition Values SignaledOTS$_FATINTERR Fatal internal error.

96


OTS$SGET1_DDOTS$SGET1_DD — The Get One Dynamic String routine allocates a specified number of bytes ofdynamic virtual memory to a specified string descriptor.

FormatOTS$SGET1_DD word-integer-length-value ,dynamic-descriptor

Corresponding JSB Entry PointOTS$SGET1_DD_R6

ReturnsNone.

Argumentsword-integer-length-value

OpenVMS usage: word_unsignedtype: word (unsigned)access: read onlymechanism: by value

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

dynamic-descriptor


Dynamic string descriptor to which the area is to be allocated. The dyn-str argument is the address ofthe dynamic string descriptor. The CLASS field is not checked but it is set to dynamic (CLASS = 2).The LENGTH field is set to word-integer-length-value and the POINTER field is set to the stringarea allocated (first byte beyond the header).

DescriptionOTS$SGET1_DD allocates a specified number of bytes of dynamic virtual memory to a specifiedstring descriptor. This routine is identical to OTS$SCOPY_DXDX except that no source string iscopied. 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 allocatedis either greater than or less than word-integer-length-value, that space is deallocated beforeOTS$SGET1_DD allocates new space.

97


Condition Values SignaledOTS$_FATINTERR Fatal internal error.OTS$_INSVIRMEM Insufficient virtual memory.

Example PROGRAM STRING_TEST

C+C This program demonstrates the use of some dynamic stringC manipulation routines.C-

C+C DECLARATIONSC-

IMPLICIT NONE CHARACTER*80 DATA_LINE INTEGER*4 DATA_LEN, DSC(2), CRLF_DSC(2), TEMP_DSC(2) CHARACTER*2 CRLF

C+C Initialize the output descriptor. It should be empty.C-

CALL OTS$SGET1_DD(%VAL(0), DSC)

C+C Initialize a descriptor to the string CRLF and copy theC character CRLF to it.C-

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 Initialize a temporary descriptor.C-

CALL OTS$SGET1_DD(%VAL(0), TEMP_DSC)

C+C Prompt the user.C-

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

C+C Read lines of text from the terminal until end-of-file.C Concatenate each line to the previous input. Include aC CRLF between each line.C-

98


DO WHILE (.TRUE.) READ(5, 998, ERR = 10) DATA_LEN, DATA_LINE998 FORMAT(Q,A) CALL OTS$SCOPY_R_DX( %VAL(DATA_LEN), 1 %REF(DATA_LINE(1:1)), 2 TEMP_DSC) CALL STR$CONCAT( DSC, DSC, TEMP_DSC, CRLF_DSC ) END DO

C+C The user has typed Ctrl/Z. Output the data we read.C-

10 CALL LIB$PUT_OUTPUT( DSC )C+C Free the storage allocated to the dynamic strings.C-

CALL OTS$SFREE1_DD( DSC ) CALL OTS$SFREE1_DD( CRLF_DSC ) CALL OTS$SFREE1_DD( TEMP_DSC )

C+C End of program.C-

STOP END

This Fortran example program demonstrates the manipulation of dynamic strings usingOTS$SGET1_DD, OTS$SFREE1_DD, and OTS$SCOPY_R_DX.

99


100