6.30 – 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
6.30.1 – Corresponding JSB Entry Point
STR$REPLACE_R8
6.30.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.30.3 – 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.
6.31 – STR$RIGHT
The Extract a Substring of a String routine copies a substring
ending at the last character of a source string into a
destination string.
Format
STR$RIGHT destination-string ,source-string ,start-position
6.31.1 – Corresponding JSB Entry Point
STR$RIGHT_R8
6.31.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.31.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$RIGHT 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$RIGHT 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 the substring
that STR$RIGHT copies starts. The start-position argument is the
address of a signed longword containing the starting position.
6.32 – STR$ROUND
The Round or Truncate a Decimal String routine rounds or
truncates a decimal string to a specified number of significant
digits and places the result in another decimal string.
Format
STR$ROUND places ,flags ,asign ,aexp ,adigits ,csign ,cexp
,cdigits
6.32.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.32.2 – Arguments
places
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Maximum number of decimal digits that STR$ROUND retains in the
result. The places argument is the address of a signed longword
containing the number of decimal digits.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Function flag. A value of 0 indicates that the decimal string is
rounded; a value of 1 indicates that it is truncated. The flags
argument is the address of an unsigned longword containing this
function flag.
asign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the decimal input string to be rounded or truncated.
The asign argument is the address of an unsigned longword string
containing this 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 decimal input string. 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
Decimal input string. This is the string of digits to which asign
and aexp are applied. The adigits argument is the address of a
descriptor pointing to this 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 this numeric string. The string is an
unsigned decimal number.
6.33 – STR$TRANSLATE
The Translate Matched Characters routine successively compares
each character in a source string to all characters in a match
string. If a source character has a match, the destination
character is taken from the translate string. Otherwise,
STR$TRANSLATE moves the source character to the destination
string.
Format
STR$TRANSLATE destination-string ,source-string
,translation-string ,match-string
6.33.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.33.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
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. The source-string argument is the address of a
descriptor pointing to the source string.
translation-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Translate string. The translation-string argument is the address
of a descriptor pointing to the translate string.
match-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Match string. The match-string argument is the address of a
descriptor pointing to the match string.
6.34 – STR$TRIM
The Trim Trailing Blanks and Tabs routine copies a source string
to a destination string and deletes the trailing blank and tab
characters.
Format
STR$TRIM destination-string ,source-string [,resultant-length]
6.34.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.34.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$TRIM copies the trimmed 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 which STR$TRIM trims and then copies into the
destination string. The source-string argument is the address
of a descriptor pointing to the source string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes that STR$TRIM writes into destination-string,
not counting padding in the case of a fixed-length string. The
resultant-length argument is the address of an unsigned word
into which STR$TRIM writes the length of the output string.
If the input string is truncated to the size specified in the
destination-string description, resultant-length is set to
this size. Therefore, resultant-length can always be used by
the calling program to access a valid substring of destination-
string.
6.35 – STR$UPCASE
The Convert String to All Uppercase Characters routine converts a
source string to uppercase.
Format
STR$UPCASE destination-string ,source-string
6.35.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.35.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$UPCASE writes the string it has
converted to uppercase. 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$UPCASE converts to uppercase. The source-
string argument is the address of a descriptor pointing to the
source string.