|
Document revision date: 30 March 2001
|
![[Compaq]](../../images/compaq.gif) |
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
|
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
|
OpenVMS RTL String Manipulation (STR$) Manual
STR$POSITION
The Return Relative Position of Substring routine searches for the
first occurrence of a single substring within a source string. If
STR$POSITION finds the substring, it returns the relative position of
that substring. If the substring is not found, STR$POSITION returns a
zero.
Format
STR$POSITION source-string ,substring [,start-position]
Corresponding JSB Entry Point
STR$POSITION_R6
RETURNS
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Relative position of the first character of the substring. Zero is the
value returned if STR$POSITION did not find the substring.
On Alpha systems, if the relative position of the substring can exceed
232 - 1, assign the return value to a quadword to ensure
that you retrieve the correct relative position.
Arguments
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Source string within which STR$POSITION searches for the substring. The
source-string argument is the address of a descriptor
pointing to the source string.
substring
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Substring for which STR$POSITION searches. The
substring argument is the address of a descriptor
pointing to the substring.
start-position
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Relative position in the source string at which STR$POSITION begins the
search. The start-position argument is the address of
a signed longword containing the starting position. Although this is an
optional argument, it is required if you are using the JSB entry point.
If start-position is not supplied, STR$POSITION starts
the search at the first character position of
source-string.
Description
STR$POSITION returns the relative position of the first occurrence of a
substring in the source string. The value returned is an unsigned
longword. The relative character positions are numbered 1, 2, 3, and so
on. A value of 0 indicates that the substring was not found.
If the substring has a zero length, the minimum value of
start-position (and the length of
source-string plus one) is returned by STR$POSITION.
If the source string has a zero length and the substring has a nonzero
length, zero is returned, indicating that the substring was not found.
Condition Values Signaled
|
STR$_ILLSTRCLA
|
Illegal string class. The class code found in the string class field of
a descriptor is not a string class code allowed by the OpenVMS calling
standard.
|
Example
|
PROGRAM POSITION(INPUT,OUTPUT);
{+}
{ This example uses STR$POSITION to determine
{ the position of the first occurrence of
{ a substring (SUBSTRING) within a source
{ string (STRING1) after the starting
{ position (START).
{
{ First, declare the external function.
{-}
FUNCTION STR$POSITION(SRCSTR : VARYING [A]
OF CHAR; SUBSTR : VARYING [B] OF CHAR;
STARTPOS : INTEGER) : INTEGER; EXTERN;
{+}
{ Declare the variables used in the main program.
{-}
VAR
STRING1 : VARYING [256] OF CHAR;
SUBSTRING : VARYING [256] OF CHAR;
START : INTEGER;
RET_STATUS : INTEGER;
{+}
{ Begin the main program. Read the string and substring.
{ Set START equal to 1 to begin looking for the substring
{ at the beginning of the source string. Call STR$POSITION
{ and print the result.
{-}
BEGIN
WRITELN('ENTER THE STRING: ');
READLN(STRING1);
WRITELN('ENTER THE SUBSTRING: ');
READLN(SUBSTRING);
START := 1;
RET_STATUS := STR$POSITION(STRING1, SUBSTRING, START);
WRITELN(RET_STATUS);
END.
|
This Pascal program demonstrates the use of STR$POSITION. If you run
this program and set STRING1 equal to KITTEN and substring equal to
TEN, the value of RET_STATUS is 4.
The output generated by this program is as follows:
ENTER THE STRING:
KITTEN
ENTER THE SUBSTRING:
TEN
4
|
STR$POS_EXTR
The Extract a Substring of a String routine copies a substring of a
source string into a destination string.
Format
STR$POS_EXTR destination-string ,source-string ,start-position
,end-position
Corresponding JSB Entry Point
STR$POS_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$POS_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$POS_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 for CALL entry point, by value for JSB entry
point |
Relative position in the source string at which STR$POS_EXTR begins
copying the substring. The start-position argument is
the address of a signed longword containing the starting position.
end-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 STR$POS_EXTR stops
copying the substring. The end-position argument is
the address of a signed longword containing the ending position.
Description
STR$POS_EXTR extracts a substring from a source string and copies the
substring into a destination string. STR$POS_EXTR defines the substring
by specifying the relative starting and ending positions in the source
string. 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 ending position is greater than the length
of the source string, the length of the source string is used.
Other routines that can be used to extract and copy a substring are
STR$LEFT, 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.
End-position was less than
start-position. 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$POS_EXTR could not allocate heap
storage for a dynamic or temporary string.
|
STR$PREFIX
The Prefix a String routine inserts a source string at the beginning of
a destination string. The destination string must be dynamic or varying
length.
Format
STR$PREFIX destination-string ,source-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 (dynamic or varying length). STR$PREFIX copies the
source string into the beginning of this 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 that STR$PREFIX copies into the beginning of the
destination string. The source-string argument is the
address of a descriptor pointing to the source string.
Description
STR$PREFIX inserts the source string at the beginning of the
destination string. The destination string must be dynamic or varying
length.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
STR$_TRU
|
String truncation warning. The destination string could not contain all
of the characters in the result.
|
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$PREFIX could not allocate heap storage
for a dynamic or temporary string.
|
Example
|
10 !+
! This example uses STR$PREFIX to
! prefix a destination string (D$)
! with a source string ('ABCD').
!-
EXTERNAL INTEGER FUNCTION STR$PREFIX
D$ = 'EFG'
STATUS% = STR$PREFIX (D$, 'ABCD')
PRINT D$
END
|
These BASIC statements set D$ equal to 'ABCDEFG'.
STR$RECIP
The Reciprocal of a Decimal String routine takes the reciprocal of the
first decimal string to the precision limit specified by the second
decimal string and returns the result as a decimal string.
Format
STR$RECIP 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 first operand's
numeric string. 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 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 the result's numeric string.
The string is an unsigned decimal number.
Description
STR$RECIP takes the reciprocal of the first decimal string to the
precision limit specified by the second decimal string and returns the
result as a decimal string.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
STR$_TRU
|
String truncation warning. The destination string could not contain all
of the characters in the result.
|
Condition Values Signaled
|
LIB$_INVARG
|
Invalid argument.
|
|
STR$_DIVBY_ZER
|
Division by zero.
|
|
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$RECIP could not allocate heap storage
for a dynamic or temporary string.
|
|
STR$_WRONUMARG
|
Wrong number of arguments.
|
Example
|
100 !+
! This example program uses STR$RECIP to find the reciprocal of the
! first decimal string (A) to the precision specified in the second
! decimal string (B), and place the result 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$RECIP (ASIGN%, AEXP%, ADIGITS$, &
BSIGN%, BEXP%, BDIGITS$, &
CSIGN%, CEXP%, CDIGITS$)
PRINT "C = "; CSIGN%; CEXP%; CDIGITS$
999 END
|
This BASIC example uses STR$RECIP to find the reciprocal of A to the
precision level specified in B, using the following values:
A = -1000 (ASIGN = 1, AEXP = 3, ADIGITS = '1')
B = .0002 (BSIGN = 0, BEXP = -4, BDIGITS = '2')
The output generated is as follows, yielding a decimal value of C equal
to -.001:
A = 1 3 1
B = 0 -4 2
C = 1 -3 1
|
STR$REPLACE
The Replace a Substring routine copies a source string to a destination
string, replacing part of the string with another string. The substring
to be replaced is specified by its starting and ending positions.
Format
STR$REPLACE destination-string ,source-string ,start-position
,end-position ,replacement-string
Corresponding JSB Entry Point
STR$REPLACE_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$REPLACE writes the new string created
when it replaces 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. 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 |
Position in the source string at which the substring that STR$REPLACE
replaces begins. The start-position argument is the
address of a signed longword containing the starting position. The
position is relative to the start of the source string.
end-position
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference for CALL entry point, by value for JSB entry
point |
Position in the source string at which the substring that STR$REPLACE
replaces ends. The end-position argument is the
address of a signed longword containing the ending position. The
position is relative to the start of the source string.
replacement-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Replacement string with which STR$REPLACE replaces the substring. The
replacement-string argument is the address of a
descriptor pointing to this replacement string. The value of
replacement-string must be equal to
end-position minus start-position.
Description
STR$REPLACE copies a source string to a destination string, replacing
part of the string with another string. The substring to be replaced is
specified by its starting and ending positions.
If the starting position is less than 1, 1 is used. If the ending
position is greater than the length of the source string, the length of
the source string is used. If the starting position is greater than the
ending position, the overlapping portion of the source string will be
copied twice.
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 value of
end-position was less than the value of
start-position or the length of the substring was too
long for the specified string. Default values were used.
|
|
STR$_TRU
|
String truncation warning. The destination string could not contain all
of the characters.
|