Document revision date: 30 March 2001

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

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

| privacy and legal statement |
5936PRO_005.HTML