Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS RTL String Manipulation (STR$) Manual


Previous Contents Index


STR$DIVIDE

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:

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


STR$DUPL_CHAR

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 216 - 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 264 - 1 bytes. The maximum length of a varying-length string is 216 - 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 


STR$ELEMENT

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.

STR$FIND_FIRST_IN_SET

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

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 


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5936PRO_005.HTML