 |
OpenVMS RTL String Manipulation (STR$) Manual
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
|
|
