HELPLIB.HLB  —  RTL Routines, STR$

1  –  STR$ADD

    The Add Two Decimal Strings routine adds two decimal strings of
    digits.

    Format

      STR$ADD  asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign

               ,cexp ,cdigits

1.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

1.2  –  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 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 first operand. 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

    Text string of unsigned digits representing the absolute value of
    the first operand before aexp is applied. The adigits argument is
    the address of a descriptor pointing to this string. This 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 sign.
    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
    a signed longword containing the second operand's exponent.

 bdigits

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

    Text string of unsigned digits representing the absolute value of
    the second operand before bexp is applied. The bdigits argument
    is the address of a descriptor pointing to this string. This
    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

    Text string of unsigned digits representing the absolute value
    of the result before cexp is applied. The cdigits argument is the
    address of a descriptor pointing to this string. This string is
    an unsigned decimal number.

2  –  STR$ANALYZE_SDESC

    The Analyze String Descriptor routine extracts the length and
    starting address of the data for a variety of string descriptor
    classes.

    Format

      STR$ANALYZE_SDESC  input-descriptor ,integer-length

                         ,data-address

2.1  –  Corresponding JSB Entry Point

      STR$ANALYZE_SDESC_R1

2.2  –  Returns

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by value

    Length of the data. The return value is the same value returned
    to the integer-length argument.

2.3  –  Arguments

 input-descriptor

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

    Input descriptor from which STR$ANALYZE_SDESC extracts the length
    of the data and the address at which the data starts. The input-
    descriptor argument is the address of a descriptor pointing to
    the input data.

 integer-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Length of the data; this length is extracted from the descriptor
    by STR$ANALYZE_SDESC. The integer-length argument is the address
    of an unsigned word integer into which STR$ANALYZE_SDESC writes
    the data length.

 data-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Address of the data; this address is extracted from the
    descriptor by STR$ANALYZE_SDESC. The data-address argument is an
    unsigned longword into which STR$ANALYZE_SDESC writes the address
    of the data.

3  –  STR$ANALYZE_SDESC_64

    (Alpha only.) The Analyze String Descriptor routine extracts the
    length and starting address of the data for a variety of string
    descriptor classes.

    Format

      STR$ANALYZE_SDESC_64  input-descriptor ,integer-length

                            ,data-address [,descriptor-type]

3.1  –  Corresponding JSB Entry Point

      STR$ANALYZE_SDESC_R1

                            Refer to the STR$ANALYZE_SDESC routine

                            for information about the JSB entry

                            point, STR$ANALYZE_SDESC_R1. This JSB

                            entry point returns 64-bit results on

                            Alpha systems.

3.2  –  Returns

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by value

    Length of the data. The return value is the same value returned
    to the integer-length argument.

3.3  –  Arguments

 input-descriptor

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

    Input descriptor from which STR$ANALYZE_SDESC_64 extracts the
    length of the data and the address at which the data starts. The
    input-descriptor argument is the address of a descriptor pointing
    to the input data. The input descriptor can be a longword
    (unsigned) or a quadword (unsigned).

 integer-length

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Length of the data; this length is extracted from the descriptor
    by STR$ANALYZE_SDESC_64. The integer-length argument is the
    address of an unsigned quadword integer into which STR$ANALYZE_
    SDESC_64 writes the data length.

 data-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Address of the data; this address is extracted from the
    descriptor by STR$ANALYZE_SDESC_64. The data-address argument
    is an unsigned quadword into which STR$ANALYZE_SDESC_64 writes
    the address of the data.

 descriptor-type

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Flag value indicating the type of input descriptor. The
    descriptor-type argument contains the address of an unsigned
    word integer to which STR$ANALYZE_SDESC_64 writes a zero (0) for
    a 32-bit input descriptor or a one (1) for a 64-bit descriptor.

    This argument is optional.

4  –  STR$APPEND

    The Append String routine appends a source string to the end of a
    destination string.

    Format

      STR$APPEND  destination-string ,source-string

4.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

4.2  –  Arguments

 destination-string

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

    Destination string to which STR$APPEND appends the source string.
    The destination-string argument is the address of a descriptor
    pointing to the destination string. This destination string
    must be dynamic or varying length. The maximum length of the
    destination string for a 32-bit descriptor is 2**16-1, or 65,535,
    bytes.

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

 source-string

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

    Source string that STR$APPEND appends to the end of the
    destination string. The source-string argument is the address
    of a descriptor pointing to this source string.

5  –  STR$CASE_BLIND_COMPARE

    The Compare Strings Without Regard to Case routine compares two
    input strings of any supported class and data type without regard
    to whether the alphabetic characters are uppercase or lowercase.

    Format

      STR$CASE_BLIND_COMPARE  first-source-string

                              ,second-source-string

5.1  –  Returns

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

    The values returned by STR$CASE_BLIND_COMPARE and the conditions
    to which they translate are as follows:

    Returned
    Value         Condition

                  first-source-string is less than second-source-
                  string.
    0             Both are the same (with blank fill for shorter
                  string).
    1             first-source-string is greater than second-source-
                  string.

5.2  –  Arguments

 first-source-string

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

    First string. The first-source-string argument is the address of
    a descriptor pointing to the first string.

 second-source-string

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

    Second string. The second-source-string argument is the address
    of a descriptor pointing to the second string.

6  –  STR$COMPARE

    The Compare Two Strings routine compares the contents of two
    strings.

    Format

      STR$COMPARE  first-source-string ,second-source-string

6.1  –  Returns

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

    The values returned by STR$COMPARE and the conditions to which
    they translate are as follows:

    Returned
    Value         Condition

                  first-source-string is less than second-source-
                  string.
    0             first-source-string is equal to second-source-
                  string.
    1             first-source-string is greater than second-source-
                  string.

6.2  –  Arguments

 first-source-string

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

    First string. The first-source-string argument is the address of
    a descriptor pointing to the first string.

 second-source-string

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

    Second string. The second-source-string argument is the address
    of a descriptor pointing to the second string.

7  –  STR$COMPARE_EQL

    The Compare Two Strings for Equality routine compares two strings
    to see if they have the same length and contents. Uppercase and
    lowercase characters are not considered equal.

    Format

      STR$COMPARE_EQL  first-source-string ,second-source-string

7.1  –  Returns

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    The values returned by STR$COMPARE and the conditions to which
    they translate are as follows:

    Returned
    Value         Condition

    0             The length and the contents of first-source-string
                  are equal to the length and contents of second-
                  source-string.
    1             Either the length of first-source-string is not
                  equal to the length of second-source-string, or the
                  contents of first-source-string are not equal to
                  the contents of second-source-string, or both.

7.2  –  Arguments

 first-source-string

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

    First source string. The first-source-string argument is the
    address of a descriptor pointing to the first source string.

 second-source-string

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

    Second source string. The second-source-string argument is the
    address of a descriptor pointing to the second source string.

8  –  STR$COMPARE_MULTI

    The Compare Two Strings for Equality Using Multinational
    Character Set routine compares two character strings for equality
    using the DEC Multinational Character Set.

    Format

      STR$COMPARE_MULTI  first-source-string ,second-source-string

                         [,flags-value] [,foreign-language]

8.1  –  Returns

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

    The values returned by STR$COMPARE_MULTI and the conditions to
    which they translate are as follows:

    Returned
    Value         Condition

                  first-source-string is less than second-source-
                  string.
    0             Both strings are the same; the shorter string is
                  blank filled.
    1             first-source-string is greater than second-source-
                  string.

8.2  –  Arguments

 first-source-string

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

    First string in the comparison. The first-source-string argument
    is the address of a descriptor pointing to the first string.

 second-source-string

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

    Second string in the comparison. The second-source-string
    argument is the address of a descriptor pointing to the second
    string.

 flags-value

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

    A single flag bit. The flags-value argument is a signed longword
    integer that contains this flag bit. The flags-value argument
    indicates whether the comparison is to be case sensitive or case
    blind. The default value of flags-value is 0, indicating a case
    sensitive comparison. The following table lists the meaning of
    the bit values:

    Value Meaning

    0     Uppercase and lowercase characters are not equivalent. (The
          comparison is case sensitive.)
    1     Uppercase and lowercase characters are equivalent. (The
          comparison is case blind.)

 foreign-language

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    Indicator that determines the foreign language table to be
    used. The foreign-language argument is an unsigned longword that
    contains this foreign language table indicator. The default value
    of foreign-language is 1. The following table lists the value
    of the foreign-language argument associated with each language
    table:

    Value Language

    1     Multinational table
    2     Danish table
    3     Finnish/Swedish table
    4     German table
    5     Norwegian table
    6     Spanish table

9  –  STR$CONCAT

    The Concatenate Two or More Strings routine concatenates all
    specified source strings into a single destination string.

    Format

      STR$CONCAT  destination-string ,source-string

                  [,source-string...]

9.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

9.2  –  Arguments

 destination-string

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

    Destination string into which STR$CONCAT concatenates all
    specified source strings. The destination-string argument is
    the address of a descriptor pointing to this destination string.

 source-string

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

    First source string; STR$CONCAT requires at least one source
    string. The source-string argument is the address of a descriptor
    pointing to the first source string. The maximum number of source
    strings that STR$CONCAT allows is 254.

 source-string

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

    Additional source strings; STR$CONCAT requires at least one
    source string. The source-string argument is the address of a
    descriptor pointing to the additional source string. The maximum
    number of source strings that STR$CONCAT allows is 254.

10  –  STR$COPY_DX

    The Copy a Source String Passed by Descriptor to a Destination
    String routine copies a source string to a destination string.
    Both strings are passed by descriptor.

    Format

      STR$COPY_DX  destination-string ,source-string

10.1  –  Corresponding JSB Entry Point

      STR$COPY_DX_R8

10.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

10.3  –  Arguments

 destination-string

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

    Destination string into which STR$COPY_DX writes the source
    string. Depending on the class of the destination string, the
    following actions occur:

    Descriptor
    Class          Action

    S, Z, SD, A,   Copy the source string. If needed, fill space or
    NCA            truncate on the right.
    D              If the area specified by the destination
                   descriptor is large enough to contain the source
                   string, copy the source string and set the new
                   length in the destination descriptor. If the area
                   specified is not large enough, return the previous
                   space allocation (if any) and then dynamically
                   allocate the amount of space needed. Copy the
                   source string and set the new length and address
                   in the destination descriptor.
    VS             Copy the source string to the destination string
                   up to the limit of the descriptor's MAXSTRLEN
                   field with no padding. Adjust the string's current
                   length (CURLEN) field to the actual number of
                   bytes copied.

    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$COPY_DX copies into the destination
    string; the descriptor class of the source string can be
    unspecified, fixed length, dynamic length, scalar decimal,
    array, noncontiguous array, or varying length. The source-string
    argument is the address of a descriptor pointing to this source
    string. (See the description of LIB$ANALYZE_SDESC for possible
    restrictions.)

11  –  STR$COPY_R

    The Copy a Source String Passed by Reference to a Destination
    String routine copies a source string passed by reference to a
    destination string passed by descriptor.

    Format

      STR$COPY_R  destination-string ,word-integer-source-length

                  ,source-string-address

11.1  –  Corresponding JSB Entry Point

      STR$COPY_R_R8

11.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

11.3  –  Arguments

 destination-string

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

    Destination string into which STR$COPY_R copies the source
    string. The destination-string argument is the address of a
    descriptor pointing to the destination string.

    The class field determines the appropriate action.

    See the description of LIB$ANALYZE_SDESC for restrictions
    associated with specific descriptor classes.

 word-integer-source-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Length of the source string. The word-integer-source-length
    argument is the address of an unsigned word containing the length
    of the source string.

 source-string-address

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

    Source string that STR$COPY_R copies into the destination string.
    The source-string-address argument is the address of the source
    string.

12  –  STR$COPY_R_64

    (Alpha only.) The Copy a Source String Passed by Reference to
    a Destination String routine copies a source string passed by
    reference to a destination string passed by descriptor.

    Format

      STR$COPY_R_64  destination-string ,quad-integer-source-length

                     ,source-string-address

12.1  –  Corresponding JSB Entry Point

      STR$COPY_R_R8

12.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

12.3  –  Arguments

 destination-string

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

    Destination string into which STR$COPY_R_64 copies the source
    string. The destination-string argument is the address of a
    descriptor pointing to the destination string.

    The class field determines the appropriate action.

    See the description of LIB$ANALYZE_SDESC for restrictions
    associated with specific descriptor classes.

 quad-integer-source-length

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Length of the source string. The quad-integer-source-length
    argument is the address of an unsigned quadword containing the
    length of the source string.

 source-string-address

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

    Source string that STR$COPY_R_64 copies into the destination
    string. The source-string-address argument is the address of the
    source string.

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

13.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

13.2  –  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.

14  –  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]

14.1  –  Corresponding JSB Entry Point

      STR$DUPL_CHAR_R8

14.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

14.3  –  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**16-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**64-1 bytes. The maximum length of a varying-length string is
    2**16-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.

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

15.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

15.2  –  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.

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

16.1  –  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**32-1, assign the return value to a quadword to ensure
    that you retrieve the correct relative position.

16.2  –  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.

17  –  STR$FIND_FIRST_NOT_IN_SET

    The Find First Character That Does Not Occur in Set 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_NOT_IN_SET
    returns the position of the first character in the string that
    does not match any of the characters in the selected set of
    characters.

    Format

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

17.1  –  Returns

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

    Position in source-string where a nonmatch was found.

    On Alpha systems, if the relative position of the substring can
    exceed 2**32-1, assign the return value to a quadword to ensure
    that you retrieve the correct relative position.

    Returned
    Value         Condition

    0             Either all characters in source-string match some
                  characters in set-of-characters, or there were no
                  characters in set-of-characters.
    1             Either the first nonmatching character in source-
                  string was found in position 1, or there were no
                  characters in source-string.
    N             The first nonmatching character was found in
                  position N within source-string.

17.2  –  Arguments

 source-string

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

    String that STR$FIND_FIRST_NOT_IN_SET searches. The source-string
    argument is the address of a descriptor pointing to the string.

 set-of-characters

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

    The set of characters that STR$FIND_FIRST_NOT_IN_SET compares
    to the string, looking for a nonmatch. The set-of-characters
    argument is the address of a descriptor pointing to this set of
    characters.

18  –  STR$FIND_FIRST_SUBSTRING

    The Find First Substring in Input String routine finds the first
    substring (in a provided list of substrings) occurring in a given
    string.

    Format

      STR$FIND_FIRST_SUBSTRING  source-string ,index ,substring-index

                                ,substring [,substring...]

18.1  –  Returns

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    The values returned by STR$FIND_FIRST_SUBSTRING and the
    conditions to which they translate are as follows:

    Returned
    Value          Condition

    0              source-string did not contain any of the specified
                   substrings.
    1              STR$FIND_FIRST_SUBSTRING found at least one of the
                   specified substrings in source-string.

18.2  –  Arguments

 source-string

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

    String that STR$FIND_FIRST_SUBSTRING searches. The source-string
    argument is the address of a descriptor pointing to the string.

 index

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

    Earliest position within source-string at which STR$FIND_FIRST_
    SUBSTRING found a matching substring; zero if no matching
    substring was found. The index argument is the address of a
    signed longword containing this position.

 substring-index

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

    Ordinal number of the substring that matched (1 for the first, 2
    for the second, and so on), or zero if STR$FIND_FIRST_SUBSTRING
    found no substrings that matched. The substring-index argument is
    the address of a signed longword containing this ordinal number.

 substring

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

    Specified substring for which STR$FIND_FIRST_SUBSTRING searches
    in source-string. The substring argument is the address of a
    descriptor pointing to the first substring. You can specify
    multiple substrings to search for.

 substring

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

    Additional specified substring for which STR$FIND_FIRST_SUBSTRING
    searches in source-string. The substring argument is the address
    of a descriptor pointing to the substring. You can specify
    multiple substrings to search for.

19  –  STR$FREE1_DX

    The Free One Dynamic String routine deallocates one dynamic
    string.

    Format

      STR$FREE1_DX  string-descriptor

19.1  –  Corresponding JSB Entry Point

      STR$FREE1_DX_R4

19.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

19.3  –  Argument

 string-descriptor

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor

    Dynamic string descriptor of the dynamic string that STR$FREE1_
    DX deallocates. The string-descriptor argument is the address
    of a descriptor pointing to the string to be deallocated. The
    descriptor's CLASS field is checked.

20  –  STR$GET1_DX

    The Allocate One Dynamic String routine allocates a specified
    number of bytes of virtual memory to a specified dynamic string
    descriptor.

    Format

      STR$GET1_DX  word-integer-length ,character-string

20.1  –  Corresponding JSB Entry Point

      STR$GET1_DX_R4

20.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

20.3  –  Arguments

 word-integer-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Number of bytes that STR$GET1_DX allocates. The word-integer-
    length argument is the address of an unsigned word containing
    this number.

 character-string

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor

    Dynamic string descriptor to which STR$GET1_DX allocates the
    area. The character-string argument is the address of the
    descriptor. The descriptor's CLASS field is checked.

21  –  STR$GET1_DX_64

    (Alpha only.) The Allocate One Dynamic String routine allocates
    a specified number of bytes of virtual memory to a specified
    dynamic string descriptor.

    Format

      STR$GET1_DX_64  quad-integer-length ,character-string

21.1  –  Corresponding JSB Entry Point

      STR$GET1_DX_R4

21.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

21.3  –  Arguments

 quad-integer-length

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Number of bytes that STR$GET1_DX_64 allocates. The quad-integer-
    length argument is the address of an unsigned quadword containing
    this number.

 character-string

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor

    Dynamic string descriptor to which STR$GET1_DX_64 allocates
    the area. The character-string argument is the address of the
    descriptor. The descriptor's CLASS field is checked.

22  –  STR$LEFT

    The Extract a Substring of a String routine copies a substring
    beginning at the first character of a source string into a
    destination string.

    Format

      STR$LEFT  destination-string ,source-string ,end-position

22.1  –  Corresponding JSB Entry Point

      STR$LEFT_R8

22.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

22.3  –  Arguments

 destination-string

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

    Destination string into which STR$LEFT 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$LEFT 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.

 end-position

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

    Relative position in the source string at which the substring
    ends. The end-position argument is the address of a signed
    longword containing the ending position.

    STR$LEFT copies all characters in the source string from position
    1 (the leftmost position) to the position number specified in
    this end-position argument.

23  –  STR$LEN_EXTR

    The Extract a Substring of a String routine copies a substring of
    a source string into a destination string.

    Format

      STR$LEN_EXTR  destination-string ,source-string ,start-position

                    ,longword-integer-length

23.1  –  Corresponding JSB Entry Point

      STR$LEN_EXTR_R8

23.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

23.3  –  Arguments

 destination-string

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

    Destination string into which STR$LEN_EXTR 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$LEN_EXTR 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

    Relative position in the source string at which STR$LEN_EXTR
    begins copying the substring. The start-position argument is the
    address of a signed longword containing the starting position.

 longword-integer-length

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

    Number of characters in the substring that STR$LEN_EXTR copies
    to the destination string. The longword-integer-length argument
    is the address of a signed longword containing the length of the
    substring.

24  –  STR$MATCH_WILD

    The Match Wildcard Specification routine compares a pattern
    string that includes wildcard characters with a candidate string.

    Format

      STR$MATCH_WILD  candidate-string ,pattern-string

24.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Returns a condition value of STR$_MATCH if the strings match and
    STR$_NOMATCH if they do not match.

24.2  –  Arguments

 candidate-string

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

    String that is compared to the pattern string. The candidate-
    string argument is the address of a descriptor pointing to the
    candidate string.

 pattern-string

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

    String containing wildcard characters. The pattern-string
    argument is the address of a descriptor pointing to the pattern
    string. The wildcards in the pattern string are translated when
    STR$MATCH_WILD searches the candidate string to determine if it
    matches the pattern string.

25  –  STR$MUL

    The Multiply Two Decimal Strings routine multiplies two decimal
    strings.

    Format

      STR$MUL  asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign

               ,cexp ,cdigits

25.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

25.2  –  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 first operand's 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 first operand. 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

    First operand's numeric text string. The adigits argument is the
    address of a descriptor pointing to the numeric string of the
    first operand. 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 sign of the second operand.
    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
    a signed longword containing this 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 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 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 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 the numeric string of the result. The
    string is an unsigned decimal number.

26  –  STR$POSITION

    The Return Relative Position of Substring routine searches for
    the first occurrence of a single substring within a source
    string. If STR$POSITION finds the substring, it returns the
    relative position of that substring. If the substring is not
    found, STR$POSITION returns a zero.

    Format

      STR$POSITION  source-string ,substring [,start-position]

26.1  –  Corresponding JSB Entry Point

      STR$POSITION_R6

26.2  –  Returns

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Relative position of the first character of the substring. Zero
    is the value returned if STR$POSITION did not find the substring.

    On Alpha systems, if the relative position of the substring can
    exceed 2**32-1, assign the return value to a quadword to ensure
    that you retrieve the correct relative position.

26.3  –  Arguments

 source-string

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

    Source string within which STR$POSITION searches for the
    substring. The source-string argument is the address of a
    descriptor pointing to the source string.

 substring

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

    Substring for which STR$POSITION searches. The substring argument
    is the address of a descriptor pointing to the substring.

 start-position

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

    Relative position in the source string at which STR$POSITION
    begins the search. The start-position argument is the address of
    a signed longword containing the starting position. Although this
    is an optional argument, it is required if you are using the JSB
    entry point.

    If start-position is not supplied, STR$POSITION starts the search
    at the first character position of source-string.

27  –  STR$POS_EXTR

    The Extract a Substring of a String routine copies a substring of
    a source string into a destination string.

    Format

      STR$POS_EXTR  destination-string ,source-string ,start-position

                    ,end-position

27.1  –  Corresponding JSB Entry Point

      STR$POS_EXTR_R8

27.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

27.3  –  Arguments

 destination-string

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

    Destination string into which STR$POS_EXTR 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$POS_EXTR 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 STR$POS_EXTR
    begins copying the substring. The start-position argument is the
    address of a signed longword containing the starting position.

 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

    Relative position in the source string at which STR$POS_EXTR
    stops copying the substring. The end-position argument is the
    address of a signed longword containing the ending position.

28  –  STR$PREFIX

    The Prefix a String routine inserts a source string at the
    beginning of a destination string. The destination string must
    be dynamic or varying length.

    Format

      STR$PREFIX  destination-string ,source-string

28.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

28.2  –  Arguments

 destination-string

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

    Destination string (dynamic or varying length). STR$PREFIX copies
    the source string into the beginning of this 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 that STR$PREFIX copies into the beginning of the
    destination string. The source-string argument is the address of
    a descriptor pointing to the source string.

29  –  STR$RECIP

    The Reciprocal of a Decimal String routine takes the reciprocal
    of the first decimal string to the precision limit specified by
    the second decimal string and returns the result as a decimal
    string.

    Format

      STR$RECIP  asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign

                 ,cexp ,cdigits

29.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

29.2  –  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 first operand's 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 first operand. 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

    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 sign of the second operand.
    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
    a signed longword containing this 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 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 the result's numeric string. The
    string is an unsigned decimal number.

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

30.1  –  Corresponding JSB Entry Point

      STR$REPLACE_R8

30.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

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.

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

31.1  –  Corresponding JSB Entry Point

      STR$RIGHT_R8

31.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

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.

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

32.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

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.

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

33.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

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.

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]

34.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

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.

35  –  STR$UPCASE

    The Convert String to All Uppercase Characters routine converts a
    source string to uppercase.

    Format

      STR$UPCASE  destination-string ,source-string

35.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

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.
Close Help