Updated: 11 December 1998

OpenVMS RTL String Manipulation (STR$) Manual

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.
LIB$_INVARG	Invalid argument.
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$REPLACE could not allocate heap storage for a dynamic or temporary string.

Example

10 !+ 
   !  This example uses STR$REPLACE to 
   !  replace all characters from the starting 
   !  position (2%) to the ending position (3%) 
   !  with characters from the replacement string 
   !  ('XYZ'). 
   !- 
 
   EXTERNAL INTEGER FUNCTION STR$REPLACE 
   D$ = 'ABCD' 
   STATUS% = STR$REPLACE (D$, D$, 2%, 3%, 'XYZ') 
   PRINT D$ 
   END 
 
      

These BASIC statements set D$ equal to 'AXYZD'.

The Extract a Substring of a String routine copies a substring ending at the last character of a source string into a destination string.

Format

STR$RIGHT destination-string ,source-string ,start-position

Corresponding JSB Entry Point

STR$RIGHT_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$RIGHT copies the substring. 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 from which STR$RIGHT extracts the substring that it copies into the destination string. The source-string argument is the address of a descriptor pointing to the source string.

start-position

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference for CALL entry point, by value for JSB entry point

Relative position in the source string at which the substring that STR$RIGHT copies starts. The start-position argument is the address of a signed longword containing the starting position.

Description

STR$RIGHT extracts a substring from a source string and copies that substring into a destination string. STR$RIGHT defines the substring by specifying the relative starting position. The relative ending position is equal to the length of the source string. The source string is unchanged, unless it is also the destination string.

If the starting position is less than 2, the entire source string is copied. If the starting position is greater than the length of the source string, a null string is copied.

This is a variation of STR$POS_EXTR. Other routines that can be used to extract and copy a substring are STR$LEFT and STR$LEN_EXTR.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
STR$_ILLSTRPOS	Alternate success. An argument referenced a character position outside the specified string. A default value was used.
STR$_TRU	String truncation warning. The destination string could not contain all 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.
LIB$_INVARG	Invalid argument.
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$RIGHT could not allocate heap storage for a dynamic or temporary string.

Example

PROGRAM RIGHT(INPUT, OUTPUT); 
 
{+} 
{  This example uses STR$RIGHT to extract a substring 
{  from a specified starting position (START_POS) to 
{  the end (right side) of a source string (SRC_STR) 
{  and write the result in a destination string (DST_STR). 
{ 
{  First, declare the external procedure. 
{-} 
 
PROCEDURE STR$RIGHT(%DESCR DSTSTR: VARYING 
          [A] OF CHAR; SRCSTR  : VARYING [B] OF CHAR; 
          STARTPOS : INTEGER); EXTERN; 
{+} 
{  Declare the variables used in the main program. 
{-} 
 
VAR 
  SRC_STR       : VARYING [256] OF CHAR; 
  DST_STR       : VARYING [256] OF CHAR; 
  START_POS     : INTEGER; 
 
{+} 
{  Begin the main program.  Read the source string 
{  and starting position. Call STR$RIGHT to extract 
{  the substring.  Print the result. 
{-} 
 
BEGIN 
  WRITELN('ENTER THE SOURCE STRING: '); 
  READLN(SRC_STR); 
  WRITELN('ENTER THE STARTING POSITION'); 
  WRITELN('OF THE SUBSTRING: '); 
  READLN(START_POS); 
  STR$RIGHT(DST_STR, SRC_STR, START_POS); 
  WRITELN; 
  WRITELN('THE SUBSTRING IS: ',DST_STR); 
END. 
 
      

This Pascal program uses STR$RIGHT to extract a substring from a specified starting position (START_POS) to the end of the source string. One sample of the output is as follows:

$ RUN RIGHT ENTER THE SOURCE STRING: BLUE PLANETS ALWAYS HAVE PURPLE PLANTS ENTER THE STARTING POSITION OF THE SUBSTRING: 27 THE SUBSTRING IS: URPLE PLANTS

The Round or Truncate a Decimal String routine rounds or truncates a decimal string to a specified number of significant digits and places the result in another decimal string.

Format

STR$ROUND places ,flags ,asign ,aexp ,adigits ,csign ,cexp ,cdigits

RETURNS

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

Arguments

places

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

Maximum number of decimal digits that STR$ROUND retains in the result. The places argument is the address of a signed longword containing the number of decimal digits.

flags

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

Function flag. A value of 0 indicates that the decimal string is rounded; a value of 1 indicates that it is truncated. The flags argument is the address of an unsigned longword containing this function flag.

asign

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

Sign of the decimal input string to be rounded or truncated. The asign argument is the address of an unsigned longword string containing this sign. A value of 0 is considered positive; a value of 1 is considered negative.

aexp

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

Power of 10 by which adigits is multiplied to get the absolute value of the decimal input string. The aexp argument is the address of a signed longword containing this exponent.

adigits

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

Decimal input string. This is the string of digits to which asign and aexp are applied. The adigits argument is the address of a descriptor pointing to this numeric string. The string must be an unsigned decimal number.

csign

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

Sign of the result. The csign argument is the address of an unsigned longword containing the result's sign. A value of 0 is considered positive; a value of 1 is considered negative.

cexp

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

Power of 10 by which cdigits is multiplied to get the absolute value of the result. The cexp argument is the address of a signed longword containing this exponent.

cdigits

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

Result's numeric text string. The cdigits argument is the address of a descriptor pointing to this numeric string. The string is an unsigned decimal number.

Description

The Round or Truncate a Decimal String routine rounds or truncates a decimal string to a specified number of significant digits and places the result in another decimal string.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
STR$_TRU	String truncation warning. The destination string could not contain all of the characters.

Condition Values Signaled

LIB$_INVARG	Invalid argument.
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$ROUND could not allocate heap storage for a dynamic or temporary string.
STR$_WRONUMARG	Wrong number of arguments.

Example

100 !+ 
    !  This example shows the difference between the values obtained 
    !  when rounding or truncating a decimal string. 
    !- 
    ASIGN% = 0% 
    AEXP% = -4% 
    ADIGITS$ = '9999998' 
    CSIGN% = 0% 
    CEXP% = 0% 
    CDIGITS$ = '0' 
    PRINT "A = "; ASIGN%; AEXP%; ADIGITS$ 
    !+ 
    !  First, call STR$ROUND to round the value of A. 
    !- 
    CALL STR$ROUND      (3%, 0%, ASIGN%, AEXP%, ADIGITS$, & 
                        CSIGN%, CEXP%, CDIGITS$) 
    PRINT "ROUNDED:  C = "; CSIGN%; CEXP%; CDIGITS$ 
    !+ 
    !  Now, call STR$ROUND to truncate the value of A. 
    !- 
    CALL STR$ROUND     (3%, 1%, ASIGN%, AEXP%, ADIGITS$, & 
                        CSIGN%, CEXP%, CDIGITS$) 
    PRINT "TRUNCATED:  C = "; CSIGN%; CEXP%; CDIGITS$ 
999 END 
 
 
      

This BASIC example uses STR$ROUND to round and truncate the value of A to the number of decimal places specified by places. The following values apply:

A = 999.9998 (ASIGN = 0, AEXP = -4, ADIGITS = '9999998')

The output generated by this program is as follows; note that the decimal value of C equals 1000 when rounded and 999 when truncated.

A = 0 -4 9999998 ROUNDED: C = 0 1 100 TRUNCATED: C = 0 0 999

The Translate Matched Characters routine successively compares each character in a source string to all characters in a match string. If a source character has a match, the destination character is taken from the translate string. Otherwise, STR$TRANSLATE moves the source character to the destination string.

Format

STR$TRANSLATE destination-string ,source-string ,translation-string ,match-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. 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. The source-string argument is the address of a descriptor pointing to the source string.

translation-string

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

Translate string. The translation-string argument is the address of a descriptor pointing to the translate string.

match-string

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

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

Description

STR$TRANSLATE successively compares each character in a source string to all characters in a match string. If a source character matches any of the characters in the match string, STR$TRANSLATE moves a character from the translate string to the destination string. Otherwise, STR$TRANSLATE moves the character from the source string to the destination string.

The character taken from the translate string has the same relative position as the matching character had in the match string. When a character appears more than once in the match string, the position of the leftmost occurrence of the multiply-defined character is used to select the translate string character. If the translate string is shorter than the match string and the matched character position is greater than the translate string length, the destination character is a space.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
STR$_TRU	String truncation warning. The destination string could not contain all of the characters.

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$TRANSLATE could not allocate heap storage for a dynamic or temporary string.

Example

10      !+ 
        !  This example program uses STR$TRANSLATE to 
        !  translate all characters of a source string 
        !  from uppercase to lowercase characters. 
        !- 
 
        EXTERNAL INTEGER FUNCTION STR$TRANSLATE(STRING,STRING,STRING,STRING) 
        TO$='abcdefghijklmnopqrstuvwxyz' 
        FROM$='ABCDEFGHIJKLMNOPQRSTUVWXYZ' 
        X% = STR$TRANSLATE(OUT$,'TEST',TO$,FROM$) 
        PRINT 'Status = ';x% 
        PRINT 'Resulting string = ';out$ 
32767   END 
 
      

This BASIC example translates uppercase letters to lowercase letters, thus performing a function similar to but the opposite of STR$UPCASE.

The output generated by this example is as follows:

$ RUN TRANSLATE Status = 1 Resulting string = test

A more practical although more complicated use for STR$TRANSLATE is to encrypt data by translating the characters to obscure combinations of numbers and alphabetic characters.

The Trim Trailing Blanks and Tabs routine copies a source string to a destination string and deletes the trailing blank and tab characters.

Format

STR$TRIM destination-string ,source-string [,resultant-length]

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

resultant-length

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

Number of bytes that STR$TRIM writes into destination-string, not counting padding in the case of a fixed-length string. The resultant-length argument is the address of an unsigned word into which STR$TRIM writes the length of the output string. If the input string is truncated to the size specified in the destination-string description, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of destination-string.

Description

STR$TRIM copies a source string to a destination string and deletes the trailing blank and tab characters.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
STR$_TRU	String truncation warning. The destination string could not contain all the characters.

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$TRIM could not allocate heap storage for a dynamic or temporary string.

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

5936PRO_009.HTML