Updated: 11 December 1998

OpenVMS RTL String Manipulation (STR$) Manual

The Divide Two Decimal Strings routine divides two decimal strings.

Format

STR$DIVIDE asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,total-digits ,round-truncate-indicator ,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 sign of the first operand. 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 the first operand's 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 second operand's string. 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 the second operand's 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 number string. The string must be an unsigned decimal number.

total-digits

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Number of digits to the right of the decimal point. The total-digits argument is the address of a signed longword containing the number of total digits. STR$DIVIDE uses this number to carry out the division.

round-truncate-indicator

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Indicator of whether STR$DIVIDE is to round or truncate the result; a value of 0 means truncate; a value of 1 means round. The round-truncate-indicator argument is the address of a longword bit mask containing this indicator.

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 the 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. This string is an unsigned decimal number.

Description

STR$DIVIDE divides two decimal strings. The divisor and dividend are passed to STR$DIVIDE 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 division 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 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 Digital 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$DIVIDE could not allocate heap storage for a dynamic or temporary string.
STR$_WRONUMARG	Wrong number of arguments.

Example

100 !+ 
    !  This BASIC example program uses STR$DIVIDE 
    !  to divide two decimal strings and truncates 
    !  the result. 
    !- 
 
    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$DIVIDE     (ASIGN%, AEXP%, ADIGITS$, & 
                        BSIGN%, BEXP%, BDIGITS$,  & 
                        3%, 0%, CSIGN%, CEXP%, CDIGITS$) 
     PRINT "C = "; CSIGN%; CEXP%; CDIGITS$ 
1500 END 
 
 
      

This BASIC program uses STR$DIVIDE to divide two decimal strings, A divided by B, 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:

A = 1 3 1 B = 0 -4 2 C = 1 -3 5000000000

Thus, the decimal value of C equals -5000000 (CSIGN = 1, CEXP = -3, CDIGITS = 5000000000).

The Duplicate Character n Times routine generates a string containing n duplicates of the input character. If the destination string is an "empty" dynamic-length string descriptor, STR$DUPL_CHAR allocates and initializes the string.

Format

STR$DUPL_CHAR destination-string [,repetition-count] [,ASCII-character]

Corresponding JSB Entry Point

STR$DUPL_CHAR_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$DUPL_CHAR writes repetition-count copies of the input character. The destination-string argument is the address of a descriptor pointing to the destination string. The maximum length of the destination string for a 32-bit descriptor is 2¹⁶ - 1, or 65,535, bytes.

On Alpha systems, the maximum length of the destination string for all 64-bit descriptor classes, except varying strings, is 2⁶⁴ - 1 bytes. The maximum length of a varying-length string is 2¹⁶ - 1 for both 32-bit and 64-bit descriptors.

repetition-count

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Number of times ASCII-character is duplicated; this is an optional argument (if omitted, the default is 1). The repetition-count argument is the address of a signed longword containing the number.

ASCII-character

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by reference

ASCII character that STR$DUPL_CHAR writes repetition-count times into the destination string. The ASCII-character argument is the address of a character string containing this character. This is an optional argument; if omitted, the default is a space.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
STR$_NEGSTRLEN	Alternate success. The length argument contained a negative value; zero was used.
STR$_TRU	String truncation warning. The destination string could not contain all of the characters.

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 Digital 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$DUPL_CHAR could not allocate heap storage for a dynamic or temporary string.
STR$_STRTOOLON	String length exceeds the maximum allowed for the destination-string descriptor.

Example

10  !+ 
    !  This example uses STR$DUPL_CHAR to 
    !  duplicate the character 'A' four times. 
    !- 
 
    EXTERNAL INTEGER FUNCTION STR$DUPL_CHAR 
    STATUS% = STR$DUPL_CHAR (X$, 4%, 'A' BY REF) 
    PRINT X$ 
    END 
 
 
      

These BASIC statements set X$ equal to 'AAAA'.

The output generated by this program is as follows:

AAAA

The Extract Delimited Element Substring routine extracts an element from a string in which the elements are separated by a specified delimiter.

Format

STR$ELEMENT destination-string ,element-number ,delimiter-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 into which STR$ELEMENT copies the selected substring. The destination-string argument is the address of a descriptor pointing to the destination string.

element-number

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Element number of the delimited element substring to be returned. The element-number argument is the address of a signed longword containing the desired element number. Zero is used to represent the first delimited element substring, one is used to represent the second, and so forth.

delimiter-string

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Delimiter string used to separate element substrings. The delimiter-string argument is the address of a descriptor pointing to the delimiter string. The delimiter-string argument must be exactly one character long.

source-string

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Source string from which STR$ELEMENT extracts the requested delimited substring. The source-string argument is the address of a descriptor pointing to the source string.

Description

STR$ELEMENT extracts an element from a string in which the elements are separated by a specified delimiter.

For example, if source-string is MON^TUE^WED^THU^FRI^SAT^SUN, delimiter-string is ^, and element-number is 2, then STR$ELEMENT returns the string WED.

Once the specified element is located, all the characters in that delimited element are returned. That is, all characters between the element-number and the element-number + 1 delimiters are written to destination-string. At least element-number delimiters must be found. If exactly element-number delimiters are found, then all values from the element-number delimiter to the end of the string are returned. If element-number equals 0 and no delimiters are found, the entire input string is returned.

STR$ELEMENT duplicates the functions of the DCL lexical function F$ELEMENT.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
STR$_INVDELIM	Delimiter string is not exactly one character long (warning).
STR$_NOELEM	Not enough delimited characters found to satisfy requested element number (warning).
STR$_TRU	String truncation. The destination string could not contain all the characters in the delimited substring (warning).

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 Digital 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$ELEMENT could not allocate heap storage for a dynamic or temporary string.

The Find First Character in a Set of Characters routine searches a string, comparing each character to the characters in a specified set of characters. The string is searched character by character, from left to right. STR$FIND_FIRST_IN_SET returns the position of the first character in the string that matches any of the characters in the selected set of characters.

Format

STR$FIND_FIRST_IN_SET source-string ,set-of-characters

RETURNS

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write only
mechanism:	by value

Position in source-string where the first match is found; zero if no match is found.

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

String that STR$FIND_FIRST_IN_SET compares to the set of characters, looking for the first match. The source-string argument is the address of a descriptor pointing to the character string.

set-of-characters

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Set of characters that STR$FIND_FIRST_IN_SET is searching for in the string. The source-string argument is the address of a descriptor pointing to the set of characters.

Description

STR$FIND_FIRST_IN_SET compares each character in the string to every character in the specified set of characters. As soon as the first match is found, STR$FIND_FIRST_IN_SET returns the position in the string where the matching character was found. If no match is found, 0 is returned. If either source-string or set-of-characters is of zero length, 0 is returned.

Condition Value Signaled

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.

Example

PROGRAM FIND_FIRST(INPUT, OUTPUT); 
 
{+} 
{  This example uses STR$FIND_FIRST_IN_SET 
{  to find the first character in the source 
{  string (STRING1) that matches a character 
{  in the set of characters being searched for 
{  (CHARS). 
{ 
{  First, declare the external function. 
{-} 
 
FUNCTION STR$FIND_FIRST_IN_SET(STRING : 
          VARYING [A] OF CHAR; SETOFCHARS : 
          VARYING [B] OF CHAR) : INTEGER; 
          EXTERN; 
 
{+} 
{  Declare the variables used in the main program. 
{-} 
 
VAR 
  STRING1       : VARYING [256] OF CHAR; 
  CHARS         : VARYING [256] OF CHAR; 
  RET_STATUS    : INTEGER; 
 
{+} 
{  Begin the main program.  Read the source string 
{  and the set of characters being searched for.  Call 
{  STR$FIND_FIRST_IN_SET to find the first match. 
{  Print the result. 
{-} 
 
BEGIN 
  WRITELN('ENTER THE STRING: '); 
  READLN(STRING1); 
  WRITELN('ENTER THE SET OF CHARACTERS: '); 
  READLN(CHARS); 
  RET_STATUS := STR$FIND_FIRST_IN_SET(STRING1, CHARS); 
  WRITELN(RET_STATUS); 
END. 
 
 
      

This Pascal program demonstrates the use of STR$FIND_FIRST_IN_SET. If you run this program and set STRING1 equal to ABCDEFGHIJK and CHARS equal to XYZA, the value of RET_STATUS is 1. The output generated by this program is as follows:

ENTER THE STRING: ABCDEFGHIJK ENTER THE SET OF CHARACTERS: XYZA 1

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5936PRO_005.HTML