Updated: 11 December 1998

OpenVMS RTL String Manipulation (STR$) Manual

The Compare Two Strings for Equality Using Multinational Character Set routine compares two character strings for equality using the DEC Multinational Character Set.

Format

STR$COMPARE_MULTI first-source-string ,second-source-string [,flags-value] [,foreign-language]

RETURNS

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

The values returned by STR$COMPARE_MULTI 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 strings are the same; the shorter string is blank filled.
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 in the comparison. 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 in the comparison. The second-source-string argument is the address of a descriptor pointing to the second string.

flags-value

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

A single flag bit. The flags-value argument is a signed longword integer that contains this flag bit. The flags-value argument indicates whether the comparison is to be case sensitive or case blind. The default value of flags-value is 0, indicating a case sensitive comparison. The following table lists the meaning of the bit values:

Value	Meaning
0	Uppercase and lowercase characters are not equivalent. (The comparison is case sensitive.)
1	Uppercase and lowercase characters are equivalent. (The comparison is case blind.)

foreign-language

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

Indicator that determines the foreign language table to be used. The foreign-language argument is an unsigned longword that contains this foreign language table indicator. The default value of foreign-language is 1. The following table lists the value of the foreign-language argument associated with each language table:

Value	Language
1	Multinational table
2	Danish table
3	Finnish/Swedish table
4	German table
5	Norwegian table
6	Spanish table

Description

STR$COMPARE_MULTI compares two character strings to see whether they have the same contents. Two strings are "equal" if they contain the same characters in the same sequence, even if one of them is blank filled to a longer length than the other. The DEC Multinational Character Set, or foreign language variations of the DEC Multinational Character Set, are used in the comparison.

See the OpenVMS I/O User's Reference Manual for more information about the DEC Multinational Character Set.

Condition Values Signaled

STR$_ILLSTRCLA	Illegal string class. Severe error. The descriptor of first-source-string and/or second-source-string contains a class code that is not supported by the OpenVMS calling standard.
LIB$_INVARG	Invalid argument. Severe error.

The Concatenate Two or More Strings routine concatenates all specified source strings into a single destination string.

Format

STR$CONCAT destination-string ,source-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 into which STR$CONCAT concatenates all specified source strings. The destination-string argument is the address of a descriptor pointing to this destination string.

source-string

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

First source string; STR$CONCAT requires at least one source string. The source-string argument is the address of a descriptor pointing to the first source string. The maximum number of source strings that STR$CONCAT allows is 254.

source-string

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

Additional source strings; STR$CONCAT requires at least one source string. The source-string argument is the address of a descriptor pointing to the additional source string. The maximum number of source strings that STR$CONCAT allows is 254.

Description

STR$CONCAT concatenates all specified source strings into a single destination string. The strings can be of any class and data type, provided that the length fields of the descriptors indicate the lengths of the strings in bytes. You must specify at least one source string, and you can specify up to 254 source strings. The maximum length of a concatenated 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.

A warning status is returned if one or more input characters are not copied to the destination string.

Condition Values Returned

SS$_NORMAL	Normal successful completion. All characters in the input strings were copied into the destination string.
STR$_TRU	String truncation warning. One or more input characters were not copied into the destination 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$CONCAT could not allocate heap storage for a dynamic or temporary string.
STR$_STRTOOLON	The combined length of all the source strings exceeded the maximum allowed for the destination-string descriptor.
STR$_WRONUMARG	Wrong number of arguments. You tried to pass fewer than two or more than 255 arguments to STR$CONCAT.

Example

10 !+ 
   !  This example program uses STR$CONCAT 
   !  to concatenate four source strings into a 
   !  single destination string. 
   !- 
 
   EXTERNAL INTEGER FUNCTION STR$CONCAT 
   STATUS% = STR$CONCAT (X$, 'A', 'B', 'C', 'D') 
   PRINT "X$ = ";X$ 
   END 
 
 
      

The output generated by this BASIC program is as follows:

X$ = ABCD

The Copy a Source String Passed by Descriptor to a Destination String routine copies a source string to a destination string. Both strings are passed by descriptor.

Format

STR$COPY_DX destination-string ,source-string

Corresponding JSB Entry Point

STR$COPY_DX_R8

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 into which STR$COPY_DX writes the source string. Depending on the class of the destination string, the following actions occur:

Descriptor Class	Action
S, Z, SD, A, NCA	Copy the source string. If needed, fill space or truncate on the right.
D	If the area specified by the destination descriptor is large enough to contain the source string, copy the source string and set the new length in the destination descriptor. If the area specified is not large enough, return the previous space allocation (if any) and then dynamically allocate the amount of space needed. Copy the source string and set the new length and address in the destination descriptor.
VS	Copy the source string to the destination string up to the limit of the descriptor's MAXSTRLEN field with no padding. Adjust the string's current length (CURLEN) field to the actual number of bytes copied.

The destination-string argument is the address of a descriptor pointing to the destination string.

source-string

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

Source string that STR$COPY_DX copies into the destination string; the descriptor class of the source string can be unspecified, fixed length, dynamic length, scalar decimal, array, noncontiguous array, or varying length. The source-string argument is the address of a descriptor pointing to this source string. (See the description of LIB$ANALYZE_SDESC for possible restrictions.)

Description

STR$COPY_DX copies a source string to a destination string, where both strings are passed by descriptor. All conditions except success and truncation are signaled; truncation is returned as a warning condition value.

STR$COPY_DX passes the source string by descriptor. In addition, an equivalent JSB entry point is provided, with R0 being the first argument (the descriptor of the destination string), and R1 the second (the descriptor of the source string).

Condition Values Returned

SS$_NORMAL	Normal successful completion. All characters in the input string were copied to the destination string.
STR$_TRU	String truncation warning. The destination string could not contain all of the characters copied from the source 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$COPY_DX could not allocate heap storage for a dynamic or temporary string.

The Copy a Source String Passed by Reference to a Destination String routine copies a source string passed by reference to a destination string passed by descriptor.

Format

STR$COPY_R destination-string ,word-integer-source-length ,source-string-address

Corresponding JSB Entry Point

STR$COPY_R_R8

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 into which STR$COPY_R copies the source string. The destination-string argument is the address of a descriptor pointing to the destination string.

The class field determines the appropriate action.

See the description of LIB$ANALYZE_SDESC for restrictions associated with specific descriptor classes.

word-integer-source-length

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

Length of the source string. The word-integer-source-length argument is the address of an unsigned word containing the length of the source string.

source-string-address

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

Source string that STR$COPY_R copies into the destination string. The source-string-address argument is the address of the source string.

Description

STR$COPY_R copies a source string passed by reference to a destination string passed by descriptor. All conditions except success and truncation are signaled; truncation is returned as a warning condition value.

A JSB entry point is provided, with R0 being the first argument, R1 the second, and R2 the third. The length argument is passed in bits 15:0 of R1.

The actions taken by STR$COPY_R depend on the descriptor class of the destination string. The following table describes these actions for each appropriate descriptor class:

Descriptor Class	Action
S, Z, SD, A, NCA	Copy the source string. If needed, space fill or truncate on the right.
D	If the area specified by the destination descriptor is large enough to contain the source string, copy the source string and set the new length in the destination descriptor.
	If the area specified is not large enough, return the previous space allocation, if any, and then dynamically allocate the amount of space needed. Copy the source string and set the new length and address in the destination descriptor.
VS	Copy source string to destination string up to the limit of the descriptor's MAXSTRLEN field with no padding. Readjust the string's current length (CURLEN) field to the actual number of bytes copied.

Condition Values Returned

SS$_NORMAL	Normal successful completion. All characters in the input string were copied to the destination string.
STR$_TRU	String truncation warning. The destination string could not contain all of the characters copied from the source 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$COPY_R could not allocate heap storage for a dynamic or temporary string.

The Copy a Source String Passed by Reference to a Destination String routine copies a source string passed by reference to a destination string passed by descriptor.

Format

STR$COPY_R_64 destination-string ,quad-integer-source-length ,source-string-address

Corresponding JSB Entry Point

STR$COPY_R_R8

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 into which STR$COPY_R_64 copies the source string. The destination-string argument is the address of a descriptor pointing to the destination string.

The class field determines the appropriate action.

See the description of LIB$ANALYZE_SDESC for restrictions associated with specific descriptor classes.

quad-integer-source-length

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

Length of the source string. The quad-integer-source-length argument is the address of an unsigned quadword containing the length of the source string.

source-string-address

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

Source string that STR$COPY_R_64 copies into the destination string. The source-string-address argument is the address of the source string.

Description

STR$COPY_R_64 copies a source string passed by reference to a destination string passed by descriptor. All conditions except success and truncation are signaled; truncation is returned as a warning condition value.

A JSB entry point is provided, with R0 being the first argument, R1 the second, and R2 the third. The length argument is passed in bits 15:0 of R1.

The actions taken by STR$COPY_R_64 depend on the descriptor class of the destination string. The following table describes these actions for each appropriate descriptor class:

Descriptor Class	Action
S, Z, SD, A, NCA	Copy the source string. If needed, space fill or truncate on the right.
D	If the area specified by the destination descriptor is large enough to contain the source string, copy the source string and set the new length in the destination descriptor.
	If the area specified is not large enough, return the previous space allocation, if any, and then dynamically allocate the amount of space needed. Copy the source string and set the new length and address in the destination descriptor.
VS	Copy source string to destination string up to the limit of the descriptor's MAXSTRLEN field with no padding. Readjust the string's current length (CURLEN) field to the actual number of bytes copied.

Condition Values Returned

SS$_NORMAL	Normal successful completion. All characters in the input string were copied to the destination string.
STR$_TRU	String truncation warning. The destination string could not contain all of the characters copied from the source 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$COPY_R_64 could not allocate heap storage for a dynamic or temporary string.

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

5936PRO_004.HTML