![[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)
| Document revision date: 30 March 2001 | |
|
|
|
|
|
|
| Previous | Contents | Index |
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. LIB$_INVARG Invalid argument. 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$REPLACE could not allocate heap storage for a dynamic or temporary string.
10 !+
! This example uses STR$REPLACE to
! replace all characters from the starting
! position (2%) to the ending position (3%)
! with characters from the replacement string
! ('XYZ').
!-
EXTERNAL INTEGER FUNCTION STR$REPLACE
D$ = 'ABCD'
STATUS% = STR$REPLACE (D$, D$, 2%, 3%, 'XYZ')
PRINT D$
END
|
These BASIC statements set D$ equal to 'AXYZD'.
The Extract a Substring of a String routine copies a substring ending at the last character of a source string into a destination string.
STR$RIGHT destination-string ,source-string ,start-position
Corresponding JSB Entry Point
STR$RIGHT_R8
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
STR$RIGHT extracts a substring from a source string and copies that substring into a destination string. STR$RIGHT defines the substring by specifying the relative starting position. The relative ending position is equal to the length of the source string. The source string is unchanged, unless it is also the destination string.If the starting position is less than 2, the entire source string is copied. If the starting position is greater than the length of the source string, a null string is copied.
This is a variation of STR$POS_EXTR. Other routines that can be used to extract and copy a substring are STR$LEFT and STR$LEN_EXTR.
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$_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 Compaq support representative. LIB$_INVARG Invalid argument. 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$RIGHT could not allocate heap storage for a dynamic or temporary string.
PROGRAM RIGHT(INPUT, OUTPUT);
{+}
{ This example uses STR$RIGHT to extract a substring
{ from a specified starting position (START_POS) to
{ the end (right side) of a source string (SRC_STR)
{ and write the result in a destination string (DST_STR).
{
{ First, declare the external procedure.
{-}
PROCEDURE STR$RIGHT(%DESCR DSTSTR: VARYING
[A] OF CHAR; SRCSTR : VARYING [B] OF CHAR;
STARTPOS : INTEGER); EXTERN;
{+}
{ Declare the variables used in the main program.
{-}
VAR
SRC_STR : VARYING [256] OF CHAR;
DST_STR : VARYING [256] OF CHAR;
START_POS : INTEGER;
{+}
{ Begin the main program. Read the source string
{ and starting position. Call STR$RIGHT to extract
{ the substring. Print the result.
{-}
BEGIN
WRITELN('ENTER THE SOURCE STRING: ');
READLN(SRC_STR);
WRITELN('ENTER THE STARTING POSITION');
WRITELN('OF THE SUBSTRING: ');
READLN(START_POS);
STR$RIGHT(DST_STR, SRC_STR, START_POS);
WRITELN;
WRITELN('THE SUBSTRING IS: ',DST_STR);
END.
|
This Pascal program uses STR$RIGHT to extract a substring from a specified starting position (START_POS) to the end of the source string. One sample of the output is as follows:
$ RUN RIGHT ENTER THE SOURCE STRING: BLUE PLANETS ALWAYS HAVE PURPLE PLANTS ENTER THE STARTING POSITION OF THE SUBSTRING: 27 THE SUBSTRING IS: URPLE PLANTS
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.
STR$ROUND places ,flags ,asign ,aexp ,adigits ,csign ,cexp ,cdigits
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
SS$_NORMAL Normal successful completion. STR$_TRU String truncation warning. The destination string could not contain all of the characters.
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$ROUND could not allocate heap storage for a dynamic or temporary string. STR$_WRONUMARG Wrong number of arguments.
100 !+
! This example shows the difference between the values obtained
! when rounding or truncating a decimal string.
!-
ASIGN% = 0%
AEXP% = -4%
ADIGITS$ = '9999998'
CSIGN% = 0%
CEXP% = 0%
CDIGITS$ = '0'
PRINT "A = "; ASIGN%; AEXP%; ADIGITS$
!+
! First, call STR$ROUND to round the value of A.
!-
CALL STR$ROUND (3%, 0%, ASIGN%, AEXP%, ADIGITS$, &
CSIGN%, CEXP%, CDIGITS$)
PRINT "ROUNDED: C = "; CSIGN%; CEXP%; CDIGITS$
!+
! Now, call STR$ROUND to truncate the value of A.
!-
CALL STR$ROUND (3%, 1%, ASIGN%, AEXP%, ADIGITS$, &
CSIGN%, CEXP%, CDIGITS$)
PRINT "TRUNCATED: C = "; CSIGN%; CEXP%; CDIGITS$
999 END
|
This BASIC example uses STR$ROUND to round and truncate the value of A to the number of decimal places specified by places. The following values apply:
A = 999.9998 (ASIGN = 0, AEXP = -4, ADIGITS = '9999998')The output generated by this program is as follows; note that the decimal value of C equals 1000 when rounded and 999 when truncated.
A = 0 -4 9999998 ROUNDED: C = 0 1 100 TRUNCATED: C = 0 0 999
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.
STR$TRANSLATE destination-string ,source-string ,translation-string ,match-string
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
STR$TRANSLATE successively compares each character in a source string to all characters in a match string. If a source character matches any of the characters in the match string, STR$TRANSLATE moves a character from the translate string to the destination string. Otherwise, STR$TRANSLATE moves the character from the source string to the destination string.The character taken from the translate string has the same relative position as the matching character had in the match string. When a character appears more than once in the match string, the position of the leftmost occurrence of the multiply-defined character is used to select the translate string character. If the translate string is shorter than the match string and the matched character position is greater than the translate string length, the destination character is a space.
SS$_NORMAL Normal successful completion. STR$_TRU String truncation warning. The destination string could not contain all of the characters.
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$TRANSLATE could not allocate heap storage for a dynamic or temporary string.
10 !+
! This example program uses STR$TRANSLATE to
! translate all characters of a source string
! from uppercase to lowercase characters.
!-
EXTERNAL INTEGER FUNCTION STR$TRANSLATE(STRING,STRING,STRING,STRING)
TO$='abcdefghijklmnopqrstuvwxyz'
FROM$='ABCDEFGHIJKLMNOPQRSTUVWXYZ'
X% = STR$TRANSLATE(OUT$,'TEST',TO$,FROM$)
PRINT 'Status = ';x%
PRINT 'Resulting string = ';out$
32767 END
|
This BASIC example translates uppercase letters to lowercase letters, thus performing a function similar to but the opposite of STR$UPCASE.
The output generated by this example is as follows:
$ RUN TRANSLATE Status = 1 Resulting string = testA more practical although more complicated use for STR$TRANSLATE is to encrypt data by translating the characters to obscure combinations of numbers and alphabetic characters.
The Trim Trailing Blanks and Tabs routine copies a source string to a destination string and deletes the trailing blank and tab characters.
STR$TRIM destination-string ,source-string [,resultant-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
STR$TRIM copies a source string to a destination string and deletes the trailing blank and tab characters.
SS$_NORMAL Normal successful completion. STR$_TRU String truncation warning. The destination string could not contain all the characters.
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$TRIM could not allocate heap storage for a dynamic or temporary string.
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 5936PRO_009.HTML | ||