OpenVMS RTL String Manipulation (STR$) Manual

Updated: 11 December 1998

OpenVMS RTL String Manipulation (STR$) Manual

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

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

Example


CHARACTER131 IN_STRING CHARACTER1 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

        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;

    
/* 
 *  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 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$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

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

Contents

Index

Legal

 
5936PRO_007.HTML

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

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

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

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.

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

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

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

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