Document revision date: 30 March 2001

## OpenVMS RTL String Manipulation (STR$) Manual

Previous | Contents | Index

## STR$ANALYZE_SDESC

> The Analyze String Descriptor routine extracts the length and starting address of the data for a variety of string descriptor classes.

### Format

> STR$ANALYZE_SDESC input-descriptor ,integer-length ,data-address

> ### Corresponding JSB Entry Point

> STR$ANALYZE_SDESC_R1

### RETURNS

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | write only
> mechanism: | by value

> Length of the data. The return value is the same value returned to the integer-length argument.

### Arguments

> #### input-descriptor

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

> Input descriptor from which STR$ANALYZE_SDESC extracts the length of the data and the address at which the data starts. The input-descriptor argument is the address of a descriptor pointing to the input data.

> #### integer-length

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | write only
> mechanism: | by reference for CALL entry point, by value for JSB entry point

> Length of the data; this length is extracted from the descriptor by STR$ANALYZE_SDESC. The integer-length argument is the address of an unsigned word integer into which STR$ANALYZE_SDESC writes the data length.

> #### data-address

> OpenVMS usage: | address
> type: | longword (unsigned)
> access: | write only
> mechanism: | by reference for CALL entry point, by value for JSB entry point

> Address of the data; this address is extracted from the descriptor by STR$ANALYZE_SDESC. The data-address argument is an unsigned longword into which STR$ANALYZE_SDESC writes the address of the data.

### Description

> STR$ANALYZE_SDESC takes as input a 32-bit descriptor argument and extracts from the descriptor the length of the data and the address at which the data starts for a variety of string descriptor classes. See LIB$ANALYZE_SDESC for a list of classes.

> STR$ANALYZE_SDESC returns the length of the data in the integer-length argument and the starting address of the data in the data-address argument.

> STR$ANALYZE_SDESC signals an error if an invalid descriptor class is found.

### 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$ANALYZE_SDESC_64 (Alpha only)

> The Analyze String Descriptor routine extracts the length and starting address of the data for a variety of string descriptor classes.

### Format

> STR$ANALYZE_SDESC_64 input-descriptor ,integer-length ,data-address [,descriptor-type]

> ### Corresponding JSB Entry Point

> STR$ANALYZE_SDESC_R1

> Refer to the STR$ANALYZE_SDESC routine for information about the JSB entry point, STR$ANALYZE_SDESC_R1. This JSB entry point returns 64-bit results on Alpha systems.

### RETURNS

> OpenVMS usage: | quadword_unsigned
> type: | quadword (unsigned)
> access: | write only
> mechanism: | by value

> Length of the data. The return value is the same value returned to the integer-length argument.

### Arguments

> #### input-descriptor

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

> Input descriptor from which STR$ANALYZE_SDESC_64 extracts the length of the data and the address at which the data starts. The input-descriptor argument is the address of a descriptor pointing to the input data. The input descriptor can be a longword (unsigned) or a quadword (unsigned).

> #### integer-length

> OpenVMS usage: | quadword_unsigned
> type: | quadword (unsigned)
> access: | write only
> mechanism: | by reference for CALL entry point, by value for JSB entry point

> Length of the data; this length is extracted from the descriptor by STR$ANALYZE_SDESC_64. The integer-length argument is the address of an unsigned quadword integer into which STR$ANALYZE_SDESC_64 writes the data length.

> #### data-address

> OpenVMS usage: | address
> type: | quadword (unsigned)
> access: | write only
> mechanism: | by reference for CALL entry point, by value for JSB entry point

> Address of the data; this address is extracted from the descriptor by STR$ANALYZE_SDESC_64. The data-address argument is an unsigned quadword into which STR$ANALYZE_SDESC_64 writes the address of the data.

> #### descriptor-type

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | write only
> mechanism: | by reference

> Flag value indicating the type of input descriptor. The descriptor-type argument contains the address of an unsigned word integer to which STR$ANALYZE_SDESC_64 writes a zero (0) for a 32-bit input descriptor or a one (1) for a 64-bit descriptor.

> This argument is optional.

### Description

> STR$ANALYZE_SDESC_64 takes as input a descriptor argument and extracts from the descriptor the length of the data and the address at which the data starts for a variety of string descriptor classes. See LIB$ANALYZE_SDESC_64 for a list of classes.

> STR$ANALYZE_SDESC_64 returns the length of the data in the integer-length argument and the starting address of the data in the data-address argument.

> STR$ANALYZE_SDESC_64 signals an error if an invalid descriptor class is found.

### 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$APPEND

> The Append String routine appends a source string to the end of a destination string.

### Format

> STR$APPEND destination-string ,source-string

### RETURNS

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

### Arguments

> #### destination-string

> OpenVMS usage: | char_string
> type: | character string
> access: | write only
> mechanism: | by descriptor

> Destination string to which STR$APPEND appends the source string. The destination-string argument is the address of a descriptor pointing to the destination string. This destination string must be dynamic or varying length. The maximum length of the destination string for a 32-bit descriptor is 216 - 1, or 65,535, bytes.

> On Alpha systems, the maximum length of the destination string for all 64-bit descriptor classes, except varying-length strings, is 264 - 1 bytes. The maximum length of a varying-length string is 216 - 1 for both 32-bit and 64-bit descriptors.

> #### source-string

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

> Source string that STR$APPEND appends to the end of the destination string. The source-string argument is the address of a descriptor pointing to this source string.

### Description

> STR$APPEND appends a source string to the end of the destination string. The destination string must be a dynamic string or a varying-length string.

### Condition Values Returned

> SS$_NORMAL | Routine successfully completed.
> STR$_TRU | String truncation warning. The destination string could not contain all of the characters from the concatinated string.

### 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$APPEND could not allocate heap storage for a dynamic or temporary string.
> STR$_STRTOOLON | The combined lengths of the source and destination strings exceeded the maximum allowed for the destination-string descriptor.

### Example

    10 !+
       !  This example program uses
       !  STR$APPEND to append a source
       !  string to a destination string.
       !-

       DST$ = 'DOG/'
       SRC$ = 'CAT'
       CALL STR$APPEND (DST$, SRC$)
       PRINT "DST$ = ";DST$
       END

> This BASIC example uses STR$APPEND to append a source string 'CAT', to a destination string 'DOG/'.

> The output generated by this program is as follows:

>     DST$ = DOG/CAT

## STR$CASE_BLIND_COMPARE

> The Compare Strings Without Regard to Case routine compares two input strings of any supported class and data type without regard to whether the alphabetic characters are uppercase or lowercase.

### Format

> STR$CASE_BLIND_COMPARE first-source-string ,second-source-string

### RETURNS

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

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

> Returned Value | Condition
> --- | ---
> -1 | first-source-string is less than second-source-string.
> 0 | Both are the same (with blank fill for shorter string).
> 1 | first-source-string is greater than second-source-string.

### Arguments

> #### first-source-string

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

> First string. The first-source-string argument is the address of a descriptor pointing to the first string.

> #### second-source-string

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

> Second string. The second-source-string argument is the address of a descriptor pointing to the second string.

### Description

> STR$CASE_BLIND_COMPARE does not distinguish between uppercase and lowercase characters. The contents of both strings are converted to uppercase before the strings are compared, but the source strings themselves are not changed. STR$CASE_BLIND_COMPARE uses the DEC Multinational Character Set.

### 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 CASE_BLIND(INPUT, OUTPUT);

    {+}
    {  This program demonstrates the use of
    {  STR$CASE_BLIND_COMPARE.
    {
    {  First, declare the external function.
    {-}

    FUNCTION STR$CASE_BLIND_COMPARE(STR1 : VARYING
             [A] OF CHAR; STR2 : VARYING [B] OF
             CHAR) : INTEGER; EXTERN;

    {+}
    {  Declare the variables to be used in the
    {  main program.
    {-}

    VAR
      STRING1       : VARYING [256] OF CHAR;
      STRING2       : VARYING [256] OF CHAR;
      RET_STATUS    : INTEGER;

    {+}
    {  Begin the main program.  Read values for
    {  the strings to be compared.  Call
    {  STR$CASE_BLIND_COMPARE.  Print the
    {  result.
    {-}

    BEGIN
      WRITELN('ENTER THE FIRST STRING: ');
      READLN(STRING1);
      WRITELN('ENTER THE SECOND STRING: ');
      READLN(STRING2);
      RET_STATUS := STR$CASE_BLIND_COMPARE(STRING1, STRING2);
      WRITELN(RET_STATUS);
    END.

> This Pascal example shows how to call STR$CASE_BLIND_COMPARE to determine whether two strings are equal regardless of case. One example of the output of this program is as follows:

>     $ RUN CASE_BLIND
>     ENTER THE FIRST STRING:  KITTEN
>     ENTER THE SECOND STRING:  kItTeN
>         0

## STR$COMPARE

> The Compare Two Strings routine compares the contents of two strings.

### Format

> STR$COMPARE first-source-string ,second-source-string

### RETURNS

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

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

> Returned Value | Condition
> --- | ---
> -1 | first-source-string is less than second-source-string.
> 0 | first-source-string is equal to second-source-string.
> 1 | first-source-string is greater than second-source-string.

### Arguments

> #### first-source-string

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

> First string. The first-source-string argument is the address of a descriptor pointing to the first string.

> #### second-source-string

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

> Second string. The second-source-string argument is the address of a descriptor pointing to the second string.

### Description

> STR$COMPARE compares two strings for the same contents. If the strings are unequal in length, the shorter string is considered to be filled with blanks to the length of the longer string before the comparison is made. This routine distinguishes between uppercase and lowercase alphabetic characters.

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

    100 EXTERNAL INTEGER FUNCTION STR$COMPARE
        SRC1$ = 'ABC'
        SRC2$ = 'BCD     '

        !+
        !  Note that STR$COMPARE will treat SRC1$ as if it were the same
        !  length as SRC2$ for the purpose of the comparison.  Thus, it
        !  will treat the contents of SRC1$ as 'ABC     '.  However, it
        !  will only 'treat' the contents as longer; the contents of
        !  the source string are not actually changed.
        !-

        I% = STR$COMPARE(SRC1$, SRC2$)
        IF I% = 1 THEN RESULT$ = ' IS GREATER THAN '
        IF I% = 0 THEN RESULT$ = ' IS EQUAL TO '
        IF I% = -1 THEN RESULT$ = ' IS LESS THAN '
        PRINT SRC1$; RESULT$; SRC2$
    999 END

> This BASIC program uses STR$COMPARE to compare two strings. The output generated by this program is as follows:

>     ABC IS LESS THAN BCD

## STR$COMPARE_EQL

> The Compare Two Strings for Equality routine compares two strings to see if they have the same length and contents. Uppercase and lowercase characters are not considered equal.

### Format

> STR$COMPARE_EQL first-source-string ,second-source-string

### RETURNS

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

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

> Returned Value | Condition
> --- | ---
> 0 | The length and the contents of first-source-string are equal to the length and contents of second-source-string.
> 1 | Either the length of first-source-string is not equal to the length of second-source-string, or the contents of first-source-string are not equal to the contents of second-source-string, or both.

### Arguments

> #### first-source-string

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

> First source string. The first-source-string argument is the address of a descriptor pointing to the first source string.

> #### second-source-string

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

> Second source string. The second-source-string argument is the address of a descriptor pointing to the second source 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.

### Example

    PROGRAM COMPARE_EQL(INPUT, OUTPUT);

    {+}
    {  This program demonstrates the use of
    {  STR$COMPARE_EQL to compare two strings.
    {  Strings are considered equal only if they
    {  have the same contents and the same length.
    {
    {  First, declare the external function.
    {-}

    FUNCTION STR$COMPARE_EQL(SRC1STR : VARYING
             [A] OF CHAR; SRC2STR : VARYING [B]
             OF CHAR) : INTEGER; EXTERN;

    {+}
    {  Declare the variables used in the main program.
    {-}

    VAR
      STRING1       : VARYING [256] OF CHAR;
      STRING2       : VARYING [256] OF CHAR;
      RET_STATUS    : INTEGER;

    {+}
    {  Begin the main program.  Read the strings
    {  to be compared.  Call STR$COMARE_EQL to compare
    {  the strings.  Print the result.
    {-}

    BEGIN
      WRITELN('ENTER THE FIRST STRING: ');
      READLN(STRING1);
      WRITELN('ENTER THE SECOND STRING: ');
      READLN(STRING2);
      RET_STATUS := STR$COMPARE_EQL(STRING1, STRING2);
      WRITELN(RET_STATUS);
    END.

> This Pascal example demonstrates the use of STR$COMPARE_EQL. A sample of the output generated by this program is as follows:

>     $ RUN COMPARE_EQL
>     ENTER THE FIRST STRING:  frog
>     ENTER THE SECOND STRING:  Frogs
>          1

Previous | Next | Contents | Index

| privacy and legal statement |
5936PRO_003.HTML