VMS Help NCS Routines, NCS$COMPARE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The NCS$COMPARE routine compares two strings using a specified
    collating sequence as a comparison basis.

    Format

      NCS$COMPARE  cs_id ,string_1 ,string_2

1 - Returns

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

    Longword condition value. Most routines return a condition value
    in R0, but the NCS$COMPARE routine uses R0 to return the result
    of the comparison, as shown in the following table:

    Returned
    Value         Comparison Result

    -1            string_1 is less than string_2
    0             string_1 is equal to string_2
    1             string_1 is greater than string_2

    The NCS$COMPARE routine uses the Signaling Mechanism to indicate
    completion status as described under Condition Value Signaled.

2 - Arguments

 cs_id

    OpenVMS usage:identifier
    type:         longword integer (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword that NCS uses to identify a collating
    sequence. The cs_id argument is required and can be obtained
    by a call to the NCS$GET_CS routine.

    All calls to the NCS$COMPARE routine and the call to the NCS$END_
    CS routine that terminates the comparison must pass this longword
    identifier. Upon completion, the NCS$END_CS routine releases the
    memory used to store the collating sequence and sets the value of
    the longword identifier to 0.

 string_1

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Descriptor (length and address) of the first string.

 string_2

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Descriptor of the second string.

3 - Description

    The NCS$COMPARE routine compares two strings using the specified
    collating sequence as the comparison basis. The routine indicates
    whether the value of the first string is greater than, less than,
    or equal to the value of the second string.

4 - Condition Value Signaled

    STR$_ILLSTRCLA     Illegal string class. Severe error. The
                       descriptor of string_1 or string_2, or both,
                       contains a class code not supported by the
                       OpenVMS Calling Standard.