Updated: 11 December 1998

OpenVMS RTL String Manipulation (STR$) Manual

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.

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.

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 2¹⁶ - 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 2⁶⁴ - 1 bytes. The maximum length of a varying-length string is 2¹⁶ - 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 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$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

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

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

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

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

5936PRO_003.HTML