OpenVMS AXP 1.5 VAX 6.0

This document, the "OpenVMS RTL String Manipulation (STR$) Manual," serves as a detailed guide for system and application programmers utilizing string manipulation routines within the OpenVMS Run-Time Library (RTL).

Key Contents:

1. Overview of STR$ Facility: Introduces the STR$ routines and categorizes their functions, including:

   • Mathematical Operations: Adding, dividing, multiplying, reciprocating, and rounding decimal strings (e.g., STR$ADD, STR$DIVIDE, STR$MUL, STR$RECIP, STR$ROUND).
   • String Comparison: Routines for comparing strings with or without regard to case, and using multinational character sets (e.g., STR$COMPARE, STR$CASE_BLIND_COMPARE).
   • Substring Manipulation: Extracting, replacing, appending, and concatenating substrings (e.g., STR$LEFT, STR$REPLACE, STR$APPEND, STR$CONCAT).
   • String Copying: Copying strings passed by descriptor or by reference (e.g., STR$COPY_DX, STR$COPY_R).
   • Searching: Finding specific characters or substrings within a string (e.g., STR$FIND_FIRST_IN_SET, STR$FIND_FIRST_SUBSTRING).
   • Dynamic String Management: Allocating and deallocating dynamic string memory (e.g., STR$GET1_DX, STR$FREE1_DX).
   • Miscellaneous Functions: Analyzing string descriptors, duplicating characters, matching wildcards, translating, trimming, and converting to uppercase (e.g., STR$ANALYZE_SDESC, STR$DUPL_CHAR, STR$TRIM, STR$UPCASE).

2. Introduction to String Manipulation (STR$) Routines: Provides in-depth information on:

   • String Semantics: Explains the three types of strings recognized by OpenVMS (fixed-length, varying-length, and dynamic-length strings) and their attributes.
   • Descriptor Classes: Details how strings are passed to RTL routines via descriptors, including various descriptor classes (e.g., fixed, varying, dynamic, array) and how routines interpret them for input and output.
   • Routine Selection: Discusses factors for choosing among different string manipulation routines, such as efficiency (comparing LIB$, OTS$, and STR$ facilities), argument passing mechanisms (CALL vs. JSB), and error handling conventions.
   • Dynamic String Resources: Explains the allocation and deallocation of memory for dynamic strings from the Run-Time Library's "string zone," highlighting efficiency benefits and important considerations for programmers.

3. STR$ Reference Section: This part contains detailed, alphabetical descriptions of each individual STR$ routine, outlining their format, arguments, return values, and condition values (errors/warnings) signaled.

The manual emphasizes that STR$ routines are the primary facility for string manipulation in OpenVMS, providing robust and efficient methods for handling various string types and operations.