Document revision date: 30 March 2001

## OpenVMS RTL String Manipulation (STR$) Manual

Previous | Contents | Index

## STR$FIND_FIRST_NOT_IN_SET

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

## STR$FIND_FIRST_SUBSTRING

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

## STR$FREE1_DX

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

## STR$GET1_DX

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

## STR$GET1_DX_64 (Alpha Only)

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

Previous | Next | Contents | Index

| privacy and legal statement |
5936PRO_006.HTML