Document revision date: 30 March 2001

## OpenVMS RTL String Manipulation (STR$) Manual

Previous | Contents | Index

## STR$LEFT

> The Extract a Substring of a String routine copies a substring beginning at the first character of a source string into a destination string.

### Format

> STR$LEFT destination-string ,source-string ,end-position

> ### Corresponding JSB Entry Point

> STR$LEFT_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$LEFT 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$LEFT 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.

> #### end-position

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

> Relative position in the source string at which the substring ends. The end-position argument is the address of a signed longword containing the ending position.

> STR$LEFT copies all characters in the source string from position 1 (the leftmost position) to the position number specified in this end-position argument.

### Description

> STR$LEFT extracts a substring from a source string and copies that substring into a destination string. STR$LEFT defines the substring by specifying the relative ending position in the source string. The relative starting position in the source string is 1. The source string is unchanged, unless it is also the destination string.

> This is a variation of STR$POS_EXTR. Other routines that may be used to extract and copy a substring are STR$RIGHT 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$_ILLSTRSPE | Alternate success. The length of the substring was too long for the specified destination string. Default values were 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.
> 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$LEFT could not allocate heap storage for a dynamic or temporary string.

### Example

    PROGRAM LEFT(INPUT, OUTPUT);

    {+}
    { This Pascal program demonstrates the use of
    { STR$LEFT.  This program reads in a source string
    { and the ending position of a substring.
    { It returns a substring consisting of all
    { characters from the beginning (left) of the
    { source string to the ending position entered.
    {-}

    {+}
    { Declare the external procedure, STR$LEFT.
    {-}

    PROCEDURE STR$LEFT(%DESCR DSTSTR: VARYING
              [A] OF CHAR; SRCSTR  :
              VARYING [B] OF CHAR; ENDPOS :
              INTEGER); EXTERN;

    {+}
    { Declare the variables used by this program.
    {-}

    VAR
      SRC_STR : VARYING [256] OF CHAR;
      DST_STR : VARYING [256] OF CHAR;
      END_POS : INTEGER;

    {+}
    { Begin the main program.  Read the source string
    { and ending position.  Call STR$LEFT.  Print the
    { results.
    {-}

    BEGIN
      WRITELN('ENTER THE SOURCE STRING: ');
      READLN(SRC_STR);
      WRITELN('ENTER THE ENDING POSITION');
      WRITELN('OF THE SUBSTRING: ');
      READLN(END_POS);
      STR$LEFT(DST_STR, SRC_STR, END_POS);
      WRITELN;
      WRITELN('THE SUBSTRING IS: ',DST_STR);
    END.

> This Pascal example shows the use of STR$LEFT. One sample of the output of this program is as follows:

>     $ PASCAL LEFT
>     $ LINK LEFT
>     $ RUN LEFT
>     ENTER THE SOURCE STRING:  MAGIC CARPET
>     ENTER THE ENDING POSITION OF
>     THE SUBSTRING:  9

>     THE SUBSTRING IS:  MAGIC CAR

## STR$LEN_EXTR

> The Extract a Substring of a String routine copies a substring of a source string into a destination string.

### Format

> STR$LEN_EXTR destination-string ,source-string ,start-position ,longword-integer-length

> ### Corresponding JSB Entry Point

> STR$LEN_EXTR_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$LEN_EXTR 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$LEN_EXTR 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

> Relative position in the source string at which STR$LEN_EXTR begins copying the substring. The start-position argument is the address of a signed longword containing the starting position.

> #### longword-integer-length

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

> Number of characters in the substring that STR$LEN_EXTR copies to the destination string. The longword-integer-length argument is the address of a signed longword containing the length of the substring.

### Description

> STR$LEN_EXTR extracts a substring from a source string and copies that substring into a destination string.

> STR$LEN_EXTR defines the substring by specifying the relative starting position in the source string and the number of characters to be copied. The source string is unchanged, unless it is also the destination string.

> If the starting position is less than 1, 1 is used. If the starting position is greater than the length of the source string, the null string is returned. If the length is less than 1, the null string is also returned.

> Other substring routines are STR$RIGHT, STR$LEFT, and STR$POS_EXTR.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> STR$_ILLSTRPOS | STR$LEN_EXTR completed successfully, but an argument referenced a character position outside the specified string. A default value was used.
> STR$_ILLSTRSPE | STR$LEN_EXTR completed successfully, except that the length was too long for the specified string. Default values were used.
> STR$_NEGSTRLEN | STR$LEN_EXTR completed successfully, except that longword-integer-length contained a negative value. Zero 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.
> 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$LEN_EXTR could not allocate heap storage for a dynamic or temporary string.

### Example

            CHARACTER*131    IN_STRING
            CHARACTER*1      FRONT_CHAR
            CHARACTER*1      TAIL_CHAR
            INTEGER STR$LEN_EXTR, STR$REPLACE, STR$TRIM
            INTEGER FRONT_POSITION, TAIL_POSITION
    10      WRITE (6, 800)
    800     FORMAT (' Enter a string, 131 characters or less:',$)
            READ (5, 900, END=200) IN_STRING
    900     FORMAT (A)
            ISTATUS = STR$TRIM (IN_STRING, IN_STRING, LENGTH)

            DO 100 I = 1, LENGTH/2
            FRONT_POSITION = I
            TAIL_POSITION = LENGTH + 1 - I
            ISTATUS = STR$LEN_EXTR ( FRONT_CHAR, IN_STRING, FRONT_POSITION,
         A                           %REF(1))

            ISTATUS = STR$LEN_EXTR ( TAIL_CHAR, IN_STRING, TAIL_POSITION,
         A                           %REF(1))

            ISTATUS = STR$REPLACE ( IN_STRING, IN_STRING, FRONT_POSITION,
         A                          FRONT_POSITION, TAIL_CHAR)

            ISTATUS = STR$REPLACE ( IN_STRING, IN_STRING, TAIL_POSITION,
         A                          TAIL_POSITION, FRONT_CHAR)
    100     CONTINUE
            WRITE (6, 901) IN_STRING
    901     FORMAT (' Reversed string is : ',/,1X,A)
            GOTO 10
    200     CONTINUE
            END

> This Fortran program accepts a string as input and writes the string in reverse order as output. This program continues to prompt for input until Ctrl/Z is pressed. One sample of the output generated by this program is as follows:

>     $ FORTRAN REVERSE
>     $ LINK REVERSE
>     $ RUN REVERSE
>     Enter a string, 131 characters or less:  Elephants often have
>     flat feet.
>      Reversed string is :
>      .teef talf evah netfo stnahpelE
>     Enter a string, 131 characters or less: CTRL/Z
>     $

## STR$MATCH_WILD

> The Match Wildcard Specification routine compares a pattern string that includes wildcard characters with a candidate string.

### Format

> STR$MATCH_WILD candidate-string ,pattern-string

### RETURNS

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

> Returns a condition value of STR$_MATCH if the strings match and STR$_NOMATCH if they do not match.

### Arguments

> #### candidate-string

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

> String that is compared to the pattern string. The candidate-string argument is the address of a descriptor pointing to the candidate string.

> #### pattern-string

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

> String containing wildcard characters. The pattern-string argument is the address of a descriptor pointing to the pattern string. The wildcards in the pattern string are translated when STR$MATCH_WILD searches the candidate string to determine if it matches the pattern string.

### Description

> STR$MATCH_WILD translates wildcard characters and searches the candidate string to determine if it matches the pattern string. The pattern string may contain either one or both of the two wildcard characters, asterisk (*) and percent (%). The asterisk character is mapped to zero or more characters. The percent character is mapped to only one character.

> The two wildcard characters that may be used in the pattern string may be used only as wildcards. If the candidate string contains an asterisk or percent character, the condition STR$_MATCH is returned. Wildcard characters are translated literally. There is no restriction on whether either wildcard character in the pattern string can match a percent or asterisk that is translated literally in the candidate string.

### Condition Values Returned

> STR$_MATCH | The candidate string and the pattern string match.
> STR$_NOMATCH | The candidate string and the pattern string do not match.

### Condition Value Signaled

> STR$_ILLSTRCLA | Illegal string class. Severe error. The descriptor of candidate-string and/or pattern-string contains a class code that is not supported by the OpenVMS calling standard.

### Example

    /*
     *  Example program using STR$MATCH_WILD.
     *
     *  The following program reads in a master pattern string and then
     *  compares that to input strings until it reaches the end of the
     *  input file.  For each string comparison done, it prints
     *  either 'Matches pattern string' or 'Doesn't match pattern string'.
     */

    declare str$match_wild
        external entry (character(*) varying, character(*) varying)
        returns (bit(1));

    example: procedure options(main);

        dcl pattern_string character(80) varying;
        dcl test_string character(80) varying;

        on endfile(sysin) stop;

        put skip;

        get list(pattern_string) options(prompt('Pattern string> '));

        do while( '1'b );
            get skip list(test_string) options(prompt('Test string> '));
            if str$match_wild(test_string,pattern_string)
                then put skip list('Matches pattern string');
                else put skip list('Doesn''t match pattern string');
            end;

        end;

> This PL/I program demonstrates the use of STR$MATCH_WILD. The output generated by this program is as follows:

>     $ PLI MATCH
>     $ LINK MATCH
>     $ RUN MATCH
>     Pattern string>  'Must match me exactly.'
>     Test string>  'Will this work? Must match me exactly.'
>     Doesn't match pattern string
>     Test string> 'must match me exactly'
>     Doesn't match pattern string
>     Test string>  'must match me exactly.'
>     Doesn't match pattern string
>     Test string>  'Must match me exactly'
>     Doesn't match pattern string
>     Test String>  'Must match me exactly.'
>     Matches pattern string

## STR$MUL

> The Multiply Two Decimal Strings routine multiplies two decimal strings.

### Format

> STR$MUL asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign ,cexp ,cdigits

### RETURNS

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

### Arguments

> #### asign

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

> Sign of the first operand. The asign argument is the address of an unsigned longword containing the first operand's 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 first operand. 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

> First operand's numeric text string. The adigits argument is the address of a descriptor pointing to the numeric string of the first operand. The string must be an unsigned decimal number.

> #### bsign

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

> Sign of the second operand. The bsign argument is the address of an unsigned longword containing the sign of the second operand. A value of 0 is considered positive; a value of 1 is considered negative.

> #### bexp

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

> Power of 10 by which bdigits is multiplied to get the absolute value of the second operand. The bexp argument is the address of a signed longword containing this exponent.

> #### bdigits

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

> Second operand's numeric text string. The bdigits argument is the address of a descriptor pointing to the second operand's 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 sign of the result. 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 the numeric string of the result. The string is an unsigned decimal number.

### Description

> STR$MUL multiplies two decimal strings. The numbers to be multiplied are passed to STR$MUL in three parts: (1) the sign of the decimal number, (2) the power of 10 needed to obtain the absolute value, and (3) the numeric string. The result of the multiplication is also returned in those three parts.

### Condition Values Returned

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

### 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$MUL could not allocate heap storage for a dynamic or temporary string.
> STR$_WRONUMARG | Wrong number of arguments.

### Example

    100 !+
        !  This example program uses
        !  STR$MUL to multiply two decimal
        !  strings (A and B) and place the
        !  results in a third decimal string,
        !  (C)
        !-

        ASIGN% = 1%
        AEXP% = 3%
        ADIGITS$ = '1'
        BSIGN% = 0%
        BEXP% = -4%
        BDIGITS$ = '2'
        CSIGN% = 0%
        CEXP% = 0%
        CDIGITS$ = '0'
        PRINT "A = "; ASIGN%; AEXP%; ADIGITS$
        PRINT "B = "; BSIGN%; BEXP%; BDIGITS$
        CALL STR$MUL        (ASIGN%, AEXP%, ADIGITS$, &
                            BSIGN%, BEXP%, BDIGITS$,  &
                            CSIGN%, CEXP%, CDIGITS$)
        PRINT "C = "; CSIGN%; CEXP%; CDIGITS$
    999 END

> This BASIC example uses STR$MUL to multiply two decimal strings, where the following values apply:

> > A = -1000 (ASIGN = 1, AEXP = 3, ADIGITS = '1')
> > B = .0002 (BSIGN = 0, BEXP = -4, BDIGITS = '2')

> The output generated by this program is as follows; note that the decimal value C equals -.2 (CSIGN = 1, CEXP = -1, CDIGITS = 2).

>     A = 1  3 1
>     B = 0 -4 2
>     C = 1 -1 2

Previous | Next | Contents | Index

| privacy and legal statement |
5936PRO_007.HTML