Document revision date: 30 March 2001

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 2³² - 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

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.

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

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

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.

	privacy and legal statement
5936PRO_008.HTML