Document revision date: 30 March 2001

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

Previous | Next | Contents | Index

| privacy and legal statement |
5936PRO_009.HTML