OpenVMS RTL String Manipulation (STR$) Manual

Updated: 11 December 1998

Order Number: AA--PV6MB--TK

November 1996

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.0 and OpenVMS VAX Version 7.0.

Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1

Digital Equipment Corporation Maynard, Massachusetts

November 1996

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Digital Equipment Corporation: AXP, Bookreader, DEC, DECdirect, DECtalk, DECthreads, DECwindows, Digital, OpenVMS, OpenVMS Cluster, VAX, VAX DOCUMENT, VAXcluster, VMS, VMScluster, and the DIGITAL logo.

The following are third-party trademarks:

Motif, OSF, OSF/1, OSF/Motif, and Open Software Foundation are registered trademarks of the Open Software Foundation, Inc.

All other trademarks and registered trademarks are the property of their respective holders.

ZK5936

The OpenVMS documentation set is available on CD-ROM.

Contents Index

Preface

This manual provides users of the OpenVMS operating system with detailed usage and reference information 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 Interfaces: Calling a System Routine. Routine descriptions appear in alphabetical order by routine name.

Reader's Comments

Digital welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08

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

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also 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 or
GOLD x A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button.
GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.

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

... Horizontal ellipsis points in examples indicate 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.

.
.
. Vertical ellipsis points indicate 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, if you choose more than one option, you must enclose the choices in parentheses.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

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

text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual.

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 device-name contains up to five alphanumeric characters).

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

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

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

Part 1
STR$ Tutorial Section

This part of the OpenVMS RTL String Manipulation (STR$) Manual contains a tutorial for the OpenVMS RTL String Manipulation (STR$) facility.

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.

Chapter 1
Run-Time Library String Manipulation (STR$) Facility

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

++Alpha specific.

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

++Alpha specific.

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

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

++Alpha specific.

1.1.1 64-Bit Addressing Support (Alpha Only)

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 Alpha Guide to 64-Bit Addressing and VLM Features for more information about 64-bit virtual addressing capabilities.

Contents

Index

Legal

 
5936PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x or GOLD x	A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button. GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.
`[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.)
...	Horizontal ellipsis points in examples indicate 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.
. . .	Vertical ellipsis points indicate 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, if you choose more than one option, you must enclose the choices in parentheses.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
{ }	In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.
text style	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. This style is also used to show user input in Bookreader versions of the manual.
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 device-name contains up to five alphanumeric characters).
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 type	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.