Document revision date: 30 March 2001

Order Number: AA--PV6MD--TK

This manual documents the string manipulation routines contained in the STR$ facility of the OpenVMS Run-Time Library.

Revision/Update Information: This manual supersedes the OpenVMS RTL String Manipulation (STR$) Manual, OpenVMS Alpha Version 7.1 and OpenVMS VAX Version 7.1.

Software Version: OpenVMS Alpha Version 7.3 OpenVMS VAX Version 7.3

Compaq Computer Corporation
Houston, Texas

© 2001 Compaq Computer Corporation

Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.

OpenVMS is a trademark of Compaq Information Technologies Group, L.P. in the United States and other countries.

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq 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.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK5936

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

Contents

Index

This manual provides users of the OpenVMS operating system with detailed usage and reference information about the string manipulation routines supplied in the STR$ facility of the Run-Time Library.

Intended Audience

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

Document Structure

This manual is organized into two parts as follows:

• Part 1 is a tutorial, structured as follows:
  • Chapter 1 provides a brief overview of the STR$ routines and lists the routines and their functions.
  • Chapter 2 discusses in detail how to use the Run-Time Library STR$ routines.
• Part 2 provides detailed reference information on each routine contained in the STR$ facility of the Run-Time Library. This information is presented using the documentation format described in OpenVMS Programming Concepts Manual. Routine descriptions appear in alphabetical order by routine name.

Related Documents

The Run-Time Library routines are documented in a series of reference manuals. A description of how the Run-Time Library routines are accessed and of the OpenVMS features and functionality available through calls to the STR$ Run-Time Library appear in the OpenVMS Programming Concepts Manual. Descriptions of other RTL facilities and their corresponding routines and usages are discussed in the following books:

• Compaq Portable Mathematics Library
• OpenVMS VAX RTL Mathematics (MTH$) Manual
• OpenVMS RTL DECtalk (DTK$) Manual¹
• OpenVMS RTL Library (LIB$) Manual
• OpenVMS RTL General Purpose (OTS$) Manual
• OpenVMS RTL Parallel Processing (PPL$) Manual¹
• OpenVMS RTL Screen Management (SMG$) Manual

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

The OpenVMS Calling Standard contains useful information for anyone who needs to call Run-Time Library routines.

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

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

For a complete list and description of the manuals in the OpenVMS documentation set, see the OpenVMS Version 7.3 New Features and Documentation Overview.

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:

http://www.openvms.compaq.com/

Reader's Comments

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

Internet	openvmsdoc@compaq.com
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

Conventions

The following conventions are used in this manual:

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

The material is structured as follows:

• Chapter 1 provides a brief overview of the STR$ routines and lists the routines and their functions.
• Chapter 2 discusses in detail how to use the Run-Time Library STR$ routines.

This chapter contains an overview of the STR$ facility and lists the routines and their functions. Chapter 2 explains in detail how the STR$ facility handles strings. The STR$ Reference Section describes all the STR$ routines.

1.1 Overview

The STR$ facility provides routines to perform the following functions:

• Perform mathematical operations on strings (see Table 1-1)
• Compare strings (see Table 1-2)
• Extract and replace substrings (see Table 1-3)
• Append and concatenate strings (see Table 1-4)
• Copy strings (see Table 1-5)
• Search for characters and substrings (see Table 1-6)
• Free and allocate dynamic strings (see Table 1-7)
• Perform miscellaneous functions on strings (see Table 1-8)

Table 1-1 STR$ Mathematical Operation Routines

Routine Name	Function
STR$ADD	Add two decimal strings
STR$DIVIDE	Divide two decimal strings
STR$MUL	Multiply two decimal strings
STR$RECIP	Return the reciprocal of a decimal string
STR$ROUND	Round or truncate a decimal string

Table 1-2 STR$ Compare Routines

Routine Name	Function
STR$CASE_BLIND_COMPARE	Compare strings without regard to case
STR$COMPARE	Compare two strings
STR$COMPARE_EQL	Compare two strings for equality
STR$COMPARE_MULTI	Compare two strings for equality using the DEC Multinational Character Set

Table 1-3 STR$ Extract and Replace Routines

Routine Name	Function
STR$ELEMENT	Extract delimited element substring
STR$LEFT	Extract a substring of a string
STR$LEN_EXTR	Extract a substring of a string
STR$POS_EXTR	Extract a substring of a string
STR$REPLACE	Replace a substring
STR$RIGHT	Extract a substring of a string

Table 1-4 STR$ Append and Concatenate Routines

Routine Name	Function
STR$APPEND	Append a string
STR$CONCAT	Concatenate two or more strings
STR$PREFIX	Prefix a string

Table 1-5 STR$ Copy Routines

Routine Name	Function
STR$COPY_DX	Copy a source string passed by descriptor to a destination string
STR$COPY_R	Copy a source string passed by reference to a destination string
++STR$COPY_R_64	Copy a source string passed by reference to a destination string

Table 1-6 STR$ Search Routines

Routine Name	Function
STR$FIND_FIRST_IN_SET	Find the first character in a set of characters
STR$FIND_FIRST_NOT_IN_SET	Find the first character that does not occur in the set
STR$FIND_FIRST_SUBSTRING	Find the first substring in the input string

Table 1-7 STR$ Allocate and Deallocate Routines

Routine Name	Function
STR$FREE1_DX	Free one dynamic string
STR$GET1_DX	Allocate one dynamic string
++STR$GET1_DX_64	Allocate one dynamic string

Table 1-8 STR$ Miscellaneous Routines

Routine Name	Function
STR$ANALYZE_SDESC	Analyze a string descriptor
++STR$ANALYZE_SDESC_64	Analyze a string descriptor
STR$DUPL_CHAR	Duplicate character n times
STR$MATCH_WILD	Match a wildcard specification
STR$POSITION	Return relative position of a substring
STR$TRANSLATE	Translate matched characters
STR$TRIM	Trim trailing blanks and tabs
STR$UPCASE	Convert string to all uppercase

On Alpha systems, the String Manipulation (STR$) routines provide 64-bit virtual addressing capabilities as follows:

• All STR$ RTL routines now accept 64-bit addresses for arguments passed by reference.
• All STR$ RTL routines also accept either 32-bit or 64-bit descriptors for arguments passed by descriptor.
• In some cases a new routine was added to support a 64-bit addressing or data capability. These routines carry the same name as the original routine but with a _64 suffix. In general, both versions of the routine support 64-bit addressing but the routine with the _64 suffix also supports additional 64-bit capability. The 32-bit capabilities of the original routine are unchanged.

See the OpenVMS Programming Concepts Manual for more information about 64-bit virtual addressing capabilities.

	privacy and legal statement
5936PRO.HTML