Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS RTL String Manipulation (STR$) Manual


Previous Contents Index


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


STR$RIGHT

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 


STR$ROUND

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 


STR$TRANSLATE

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.


STR$TRIM

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.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5936PRO_009.HTML