Updated: 11 December 1998

OpenVMS RTL String Manipulation (STR$) Manual

The Find First Character That Does Not Occur in Set routine searches a string, comparing each character to the characters in a specified set of characters. The string is searched character by character, from left to right. STR$FIND_FIRST_NOT_IN_SET returns the position of the first character in the string that does not match any of the characters in the selected set of characters.

Format

STR$FIND_FIRST_NOT_IN_SET source-string ,set-of-characters

RETURNS

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write only
mechanism:	by value

Position in source-string where a nonmatch was found.

On Alpha systems, if the relative position of the substring can exceed 2³² - 1, assign the return value to a quadword to ensure that you retrieve the correct relative position.

Returned Value	Condition
0	Either all characters in source-string match some characters in set-of-characters, or there were no characters in set-of-characters.
1	Either the first nonmatching character in source-string was found in position 1, or there were no characters in source-string.
N	The first nonmatching character was found in position N within source-string.

Arguments

source-string

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

String that STR$FIND_FIRST_NOT_IN_SET searches. The source-string argument is the address of a descriptor pointing to the string.

set-of-characters

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

The set of characters that STR$FIND_FIRST_NOT_IN_SET compares to the string, looking for a nonmatch. The set-of-characters argument is the address of a descriptor pointing to this set of characters.

Description

STR$FIND_FIRST_NOT_IN_SET searches a string, comparing each character to the characters in a specified set of characters. The string is searched character by character, from left to right. When STR$FIND_FIRST_NOT_IN_SET finds a character from the string that is not in set-of-characters, it stops searching and returns, as the value of STR$FIND_FIRST_NOT_IN_SET, the position in source-string where it found the nonmatching character. If all characters in the string match some character in the set of characters, STR$FIND_FIRST_NOT_IN_SET returns 0. If the string is of zero length, the position returned is 1 since none of the elements in the set of characters (particularly the first element) can be found in the string. If there are no characters in the set of characters, 0 is returned since "nothing" can always be found.

Condition Value Signaled

STR$_ILLSTRCLA

Illegal string class. The class code found in the class field of a descriptor is not a string class code allowed by the OpenVMS calling standard.

Example

PROGRAM NOT_IN_SET(INPUT, OUTPUT); 
 
{+} 
{  This example uses STR$FIND_FIRST_NOT_IN_SET 
{  to find the position of the first nonmatching 
{  character from a set of characters (CHARS) 
{  in a source string (STRING1). 
{ 
{  First, declare the external function. 
{-} 
 
FUNCTION STR$FIND_FIRST_NOT_IN_SET(STRING : 
          VARYING [A] OF CHAR; SETOFCHARS : 
          VARYING [B] OF CHAR) : INTEGER; 
          EXTERN; 
{+} 
{  Declare the variables used in the main program. 
{-} 
 
VAR 
  STRING1       : VARYING [256] OF CHAR; 
  CHARS         : VARYING [256] OF CHAR; 
  RET_STATUS    : INTEGER; 
 
{+} 
{  Begin the main program.  Read the source string 
{  and set of characters.  Call STR$FIND_FIRST_NOT_IN_SET. 
{  Print the result. 
{-} 
 
BEGIN 
  WRITELN('ENTER THE STRING: '); 
  READLN(STRING1); 
  WRITELN('ENTER THE SET OF CHARACTERS: '); 
  READLN(CHARS); 
  RET_STATUS := STR$FIND_FIRST_NOT_IN_SET(STRING1, CHARS); 
  WRITELN(RET_STATUS); 
END. 
 
 
      

This Pascal program demonstrates the use of STR$FIND_FIRST_NOT_IN_SET. If you run this program and set STRING1 equal to FORTUNATE and CHARS equal to FORT, the value of RET_STATUS is 5.

The output generated by this program is as follows:

ENTER THE STRING: FORTUNATE ENTER THE SET OF CHARACTERS: FORT 5

The Find First Substring in Input String routine finds the first substring (in a provided list of substrings) occurring in a given string.

Format

STR$FIND_FIRST_SUBSTRING source-string ,index ,substring-index ,substring [,substring...]

RETURNS

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by value

The values returned by STR$FIND_FIRST_SUBSTRING and the conditions to which they translate are as follows:

Returned Value	Condition
0	source-string did not contain any of the specified substrings.
1	STR$FIND_FIRST_SUBSTRING found at least one of the specified substrings in source-string.

Arguments

source-string

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

String that STR$FIND_FIRST_SUBSTRING searches. The source-string argument is the address of a descriptor pointing to the string.

index

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write only
mechanism:	by reference

Earliest position within source-string at which STR$FIND_FIRST_SUBSTRING found a matching substring; zero if no matching substring was found. The index argument is the address of a signed longword containing this position.

substring-index

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write only
mechanism:	by reference

Ordinal number of the substring that matched (1 for the first, 2 for the second, and so on), or zero if STR$FIND_FIRST_SUBSTRING found no substrings that matched. The substring-index argument is the address of a signed longword containing this ordinal number.

substring

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Specified substring for which STR$FIND_FIRST_SUBSTRING searches in source-string. The substring argument is the address of a descriptor pointing to the first substring. You can specify multiple substrings to search for.

substring

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Additional specified substring for which STR$FIND_FIRST_SUBSTRING searches in source-string. The substring argument is the address of a descriptor pointing to the substring. You can specify multiple substrings to search for.

Description

STR$FIND_FIRST_SUBSTRING takes as input a string to be searched and an unspecified number of substrings for which to search. It searches the specified string and returns the position of the substring that is found earliest in the string. This is not necessarily the position of the first substring specified. That is, STR$FIND_FIRST_SUBSTRING returns the position of the leftmost matching substring. The order in which the substrings are searched for is irrelevant.

Unlike many of the compare and search routines, STR$FIND_FIRST_SUBSTRING does not return the position in a return value. The position of the substring which is found earliest in the string is returned in the index argument. If none of the specified substrings is found in the string, the value of index is 0.

Zero-length strings, or null arguments, produce unexpected results. Any time the routine is called with a null substring as an argument, STR$FIND_FIRST_SUBSTRING always returns the position of the null substring as the first substring found. All other substrings are interpreted as appearing in the string after the null string.

Condition Values Signaled

STR$_ILLSTRCLA	Illegal string class. The class code found in the class field of a descriptor is not a string class code allowed by the OpenVMS calling standard.
STR$_WRONUMARG	Wrong number of arguments. You must supply at least one substring.

Example

1   !+ 
    ! This is a BASIC program demonstrating the use of 
    ! STR$FIND_FIRST_SUBSTRING.  This program takes as input 
    ! four strings that are listed in a data statement 
    ! at the end of the program.  STR$FIND_FIRST_SUBSTRING 
    ! is called four times (once for each string) 
    ! to find the first substring occurring in the given 
    ! string.  
    !- 
 
    OPTION TYPE = EXPLICIT 
 
    DECLARE STRING      MATCH_STRING 
    DECLARE LONG        RET_STATUS, & 
                        INDEX, & 
                        I, & 
                        SUB_STRING_NUM 
     EXTERNAL LONG FUNCTION STR$FIND_FIRST_SUBSTRING 
 
     FOR I = 1 TO 4 
        READ MATCH_STRING 
        RET_STATUS = STR$FIND_FIRST_SUBSTRING( MATCH_STRING, & 
            INDEX, SUB_STRING_NUM, 'ING', 'CK', 'TH') 
        IF RET_STATUS = 0% THEN 
            PRINT MATCH_STRING;" did not contain any of the substrings" 
        ELSE 
            SELECT SUB_STRING_NUM 
                CASE 1 
                    PRINT MATCH_STRING;" contains ING at position";INDEX 
                CASE 2 
                    PRINT MATCH_STRING;" contains CK at position";INDEX 
                CASE 3 
                    PRINT MATCH_STRING;" contains TH at position";INDEX 
            END SELECT 
        END IF 
     NEXT I 
 
2    DATA CHUCKLE, RAINING, FOURTH, THICK 
 
3    END 
 
 
 
      

This BASIC program demonstrates the use of STR$FIND_FIRST_SUBSTRING. The output generated by this program is as follows:

$ BASIC FINDSUB $ LINK FINDSUB $ RUN FINDSUB CHUCKLE contains CK at position 4 RAINING contains ING at position 5 FOURTH contains TH at position 5 THICK contains TH at position 1

Note that "THICK" contains both the substrings "TH" and "CK". STR$FIND_FIRST_SUBSTRING locates the "CK" substring in "THICK", and then locates the "TH" substring. However, since the "TH" substring is the earliest, or leftmost matching substring, its ordinal number is returned in substring-index, and the point at which "TH" occurs is returned in index.

The Free One Dynamic String routine deallocates one dynamic string.

Format

STR$FREE1_DX string-descriptor

Corresponding JSB Entry Point

STR$FREE1_DX_R4

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Argument

string-descriptor

OpenVMS usage:	char_string
type:	character string
access:	modify
mechanism:	by descriptor

Dynamic string descriptor of the dynamic string that STR$FREE1_DX deallocates. The string-descriptor argument is the address of a descriptor pointing to the string to be deallocated. The descriptor's CLASS field is checked.

Description

STR$FREE1_DX deallocates the described string space and flags the descriptor as describing no string at all. The descriptor's POINTER and LENGTH fields contain 0.

Condition Values Returned

SS$_NORMAL

Normal successful completion.

Condition Values Signaled

STR$_FATINTERR	Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Digital support representative.
STR$ERRFREDYN	Error freeing dynamic string descriptor. LIB$FREE_VM OR LIB$FREE_VM_64 failed to free the descriptor.
STR$_ILLSTRCLA	Illegal string class. The class code found in the class field of a descriptor is not a string class code allowed by the OpenVMS calling standard.

The Allocate One Dynamic String routine allocates a specified number of bytes of virtual memory to a specified dynamic string descriptor.

Format

STR$GET1_DX word-integer-length ,character-string

Corresponding JSB Entry Point

STR$GET1_DX_R4

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

word-integer-length

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference

Number of bytes that STR$GET1_DX allocates. The word-integer-length argument is the address of an unsigned word containing this number.

character-string

OpenVMS usage:	char_string
type:	character string
access:	modify
mechanism:	by descriptor

Dynamic string descriptor to which STR$GET1_DX allocates the area. The character-string argument is the address of the descriptor. The descriptor's CLASS field is checked.

Description

STR$GET1_DX allocates a specified number of bytes of dynamic virtual memory to a specified string descriptor. The descriptor must be dynamic.

If the string descriptor already has dynamic memory allocated to it, but the amount allocated is less than word-integer-length, STR$GET1_DX deallocates that space before it allocates new space.

Note Digital recommends use of the STR$GET1_DX or STR$GET1_DX_64 (Alpha only) routine for allocating a string to a dynamic-length string descriptor. Simply filling in the length and pointer fields of a dynamic-length string descriptor can cause serious and unexpected problems with string management.

Use STR$FREE1_DX to deallocate a string allocated by STR$GET1_DX.

Condition Values Returned

SS$_NORMAL	Normal successful completion.

Condition Values Signaled

STR$_FATINTERR	Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Digital support representative.
STR$_ILLSTRCLA	Illegal string class. The class code found in the class field of a descriptor is not a string class code allowed by the OpenVMS calling standard.
STR$_INSVIRMEM	Insufficient virtual memory. STR$GET1_DX could not allocate heap storage for a dynamic or temporary string.

The Allocate One Dynamic String routine allocates a specified number of bytes of virtual memory to a specified dynamic string descriptor.

Format

STR$GET1_DX_64 quad-integer-length ,character-string

Corresponding JSB Entry Point

STR$GET1_DX_R4

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

quad-integer-length

OpenVMS usage:	quadword_unsigned
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Number of bytes that STR$GET1_DX_64 allocates. The quad-integer-length argument is the address of an unsigned quadword containing this number.

character-string

OpenVMS usage:	char_string
type:	character string
access:	modify
mechanism:	by descriptor

Dynamic string descriptor to which STR$GET1_DX_64 allocates the area. The character-string argument is the address of the descriptor. The descriptor's CLASS field is checked.

Description

STR$GET1_DX_64 allocates a specified number of bytes of dynamic virtual memory to a specified 64-bit string descriptor. The descriptor must be dynamic.

If the string descriptor already has dynamic memory allocated to it, but the amount allocated is less than quad-integer-length, STR$GET1_DX_64 deallocates that space before it allocates new space.

Note Digital recommends use of the STR$GET1_DX or STR$GET1_DX_64 (Alpha only) routine for allocating a string to a dynamic-length string descriptor. Simply filling in the length and pointer fields of a dynamic-length string descriptor can cause serious and unexpected problems with string management.

Use STR$FREE1_DX to deallocate a string allocated by STR$GET1_DX_64.

Condition Values Returned

SS$_NORMAL	Normal successful completion.

Condition Values Signaled

STR$_FATINTERR	Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Digital support representative.
STR$_ILLSTRCLA	Illegal string class. The class code found in the class field of a descriptor is not a string class code allowed by the OpenVMS calling standard.
STR$_INSVIRMEM	Insufficient virtual memory. STR$GET1_DX_64 could not allocate heap storage for a dynamic or temporary string.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5936PRO_006.HTML