HELPLIB.HLB  —  SOR Routines
    The Sort/Merge (SOR) routines allow you to integrate a sort or
    merge operation into a program application. Using these callable
    routines, you can process records, sort or merge them, and then
    process them again.

1  –  SOR$BEGIN_MERGE

    The SOR$BEGIN_MERGE routine initializes the merge operation by
    opening the input and output files and by providing the number of
    input files, the key specifications, and the merge options.

    Format

      SOR$BEGIN_MERGE  [key-buffer] [,lrl] [,options] [,merge_order]

                       [,user_compare] [,user_equal] [,user_input]

                       [,context]

1.1  –  Returns

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

    Longword condition value. Most Sort/Merge utility routines return
    a condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

1.2  –  Arguments

 key_buffer

    OpenVMS usage:vector_word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Array of words describing the keys on which you plan to merge.
    The key_buffer argument is the address of an array containing the
    key descriptions.

    The first word of this array contains the number of keys
    described (up to 255). Following the first word, each key is
    described (in order of priority) in blocks of four words. The
    four words specify the key's data type, order, offset, and
    length, respectively.

    The first word of the block specifies the key's data type. The
    following data types are accepted:

    DSC$K_DTYPE_Z          Unspecified (uninfluenced by collating
                           sequence)
    DSC$K_DTYPE_B          Byte integer (signed)
    DSC$K_DTYPE_BU         Byte (unsigned)
    DSC$K_DTYPE_W          Word integer (signed)
    DSC$K_DTYPE_WU         Word (unsigned)
    DSC$K_DTYPE_L          Longword integer (signed)
    DSC$K_DTYPE_LU         Longword (unsigned)
    DSC$K_DTYPE_Q          Quadword integer (signed)
    DSC$K_DTYPE_QU         Quadword (unsigned)
    DSC$K_DTYPE_O(1)       Octaword integer (signed)
    DSC$K_DTYPE_OU(1)      Octaword (unsigned)
    DSC$K_DTYPE_F          Single-precision floating
    DSC$K_DTYPE_D          Double-precision floating
    DSC$K_DTYPE_G          G-format floating
    DSC$K_DTYPE_H(1)       H-format floating
    DSC$K_DTYPE_FS(2)      IEEE single-precision S floating
    DSC$K_DTYPE_FT(2)      IEEE double-precision T floating
    DSC$K_DTYPE_T          Text (may be influenced by collating
                           sequence)
    DSC$K_DTYPE_NU         Numeric string, unsigned
    DSC$K_DTYPE_NL         Numeric string, left separate sign
    DSC$K_DTYPE_NLO        Numeric string, left overpunched sign
    DSC$K_DTYPE_NR         Numeric string, right separate sign
    DSC$K_DTYPE_NRO        Numeric string, right overpunched sign
    DSC$K_DTYPE_NZ(1)      Numeric string, zoned sign
    DSC$K_DTYPE_P          Packed decimal string

    Footnotes:

    1. Data type is not currently supported by the high-performance
       Sort/Merge utility.

    2. Data type is Alpha specific.

    The VSI OpenVMS Programming Concepts Manual manual describes each
    of these data types.

    The second word of the block specifies the key order: 0 for
    ascending order, 1 for descending order. The third word of the
    block specifies the relative offset of the key in the record.
    (Note that the first byte in the record is at position 0.) The
    fourth word of the block specifies the key length in bytes (in
    digits for packed decimal-DSC$K_DTYPE_P).

    If you do not specify the key_buffer argument, you must pass
    either a key comparison routine or use a specification file to
    define the key.

 lrl

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Length of the longest record that will be released for merging.
    The lrl (longest record length) argument is the address of a
    word containing the length. If the input file is on a disk,
    this argument is not required. It is required when you use the
    record interface. For Vertical Format Control (VFC) records, this
    length must include the length of the fixed-length portion of the
    record.

 options

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Flags that identify merge options. The options argument is the
    address of a longword bit mask whose settings determine the merge
    options selected.

    The following table lists and describes the bit mask values
    available:

    Flag            Description

    SOR$M_STABLE    Keeps records with equal keys in the same order
                    as they appeared on input.
    SOR$M_EBCDIC    Orders ASCII character keys according to EBCDIC
                    collating sequence. No translation takes place.
    SOR$M_MULTI     Orders character keys according to the
                    multinational collating sequence, which collates
                    the international character set.
    SOR$M_          Returns a status code instead of signaling
    NOSIGNAL        errors.
    SOR$M_NODUPS    Omits records with duplicate keys. You cannot
                    use this option if you specify your own equal-key
                    routine.
    SOR$M_SEQ_      Requests an "out of order" error return if
    CHECK           an input file is not already in sequence. By
                    default, this check is not done. You must request
                    sequence checking if you specify an equal-key
                    routine.

    All other bits in the longword are reserved and must be zero.

 merge_order

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    Number of input streams to be merged. The merge_order argument is
    the address of a byte containing the number of files (1 through
    10) to be merged. (The high-performance Sort/Merge utility allows
    you to specify 1 through 12 files.) When you use the record
    interface on input, this argument is required.

 user_compare

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call
    mechanism:    by reference
    Routine that compares records to determine their merge order.
    (This routine is not currently supported by the high-performance
    Sort/Merge utility.) The user_compare argument is the address of
    the procedure value for this user-written routine. If you do not
    specify the key_buffer argument or if you define key information
    in a specification file, this argument is required.

    MERGE calls the comparison routine with five reference arguments-
    ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to the addresses
    of the two records to be compared, the lengths of these two
    records, and the context longword.

    The comparison routine must return a 32-bit integer value:

    o  -1 if the first record collates before the second

    o  0 if the records collate as equal

    o  1 if the first record collates after the second

 user_equal

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call
    mechanism:    by reference
    Routine that resolves the merge order when records have duplicate
    keys. (This routine is not currently supported by the high-
    performance Sort/Merge utility.) The user_equal argument is the
    address of the procedure value for this user-written routine. If
    you specify SOR$M_STABLE or SOR$M_NODUPS in the options argument,
    do not use this argument.

    MERGE calls the duplicate key routine with five reference
    arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to the
    addresses of the two records that compare equally, the lengths of
    the two records that compare equally, and the context longword.

    The routine must return one of the following 32-bit condition
    codes:

    Code         Description

    SOR$_        Delete the first record from the merge.
    DELETE1
    SOR$_        Delete the second record from the merge.
    DELETE2
    SOR$_        Delete both records from the merge.
    DELBOTH
    SS$_NORMAL   Keep both records in the merge.

    Any other failure value causes the error to be signaled or
    returned. Any other success value causes an undefined result.

 user_input

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call
    mechanism:    by reference
    Routine that releases records to the merge operation. The user_
    input argument is the address of the procedure value for this
    user-written routine. SOR$BEGIN_MERGE and SOR$RETURN_REC call
    this routine until all records have been passed.

    This input routine must read (or construct) a record, place it in
    a record buffer, store its length in an output argument, and then
    return control to MERGE.

    The input routine must accept the following four arguments:

    o  A descriptor of the buffer where the routine must place the
       record

    o  A longword, passed by reference, containing the stream number
       from which to input a record (the first file is 1, the second
       2, and so on)

    o  A word, passed by reference, where the routine must return the
       actual length of the record

    o  The context longword, passed by reference

    The input routine must also return one of the following status
    values:

    o  SS$_NORMAL or any other success status causes the merge
       operation to continue.

    o  SS$_ENDOFFILE indicates that no more records are in the file.
       The contents of the buffer are ignored.

    o  Any other error status terminates the merge operation and
       passes the status value back to the caller of SOR$BEGIN_MERGE
       or SOR$RETURN_REC.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE then
    stores a value in the longword to identify the operation just
    initiated. When you make subsequent routine calls for the same
    operation, you must pass the context value that was supplied by
    SORT/MERGE.

1.3  –  Description

    The SOR$BEGIN_MERGE routine initializes the merge process by
    passing arguments that provide the number of input streams, the
    key specifications, and any merge options.

    You must define the key by passing either the key buffer address
    argument or your own comparison routine address. (You can also
    define the key in a specification file and call the SOR$SPEC_FILE
    routine.)

    The SOR$BEGIN_MERGE routine initializes the merge process in
    the file, record, and mixed interfaces. For record interface
    on input, you must also pass the merge order, the input routine
    address, and the longest record length. For files not on disk,
    you must pass the longest record length.

    Some of the following condition values are used with different
    severities, depending on whether SORT/MERGE can recover. Thus,
    you should use LIB$MATCH_COND if you want to check for a specific
    status.

1.4  –  Condition Values Returned

    SS$_NORMAL         Success.
    SOR$_BADDTYPE      Invalid or unsupported CDD data type.
    SOR$_BADLENOFF     Length and offset must be multiples of 8 bits.
    SOR$_BADLOGIC      Internal logic error detected.
    SOR$_BADOCCURS     Invalid OCCURS clause.
    SOR$_BADOVRLAY     Invalid overlay structure.
    SOR$_BADPROTCL     Node is an invalid CDD object.
    SOR$_BAD_KEY       Invalid key specification.
    SOR$_BAD_LRL       Record length n greater than specified longest
                       record length.
    SOR$_BAD_MERGE     Number of input files must be between 0 and
                       10. (For the high-performance Sort/Merge
                       utility, the maximum number is 12.)
    SOR$_BAD_ORDER     Merge input is out of order.
    SOR$_BAD_SRL       Record length n is too short to contain keys.
    SOR$_BAD_TYPE      Invalid sort process specified.
    SOR$_CDDERROR      CDD error at node name.
    SOR$_CLOSEIN       Error closing file as input.
    SOR$_CLOSEOUT      Error closing file.
    SOR$_COL_CHAR      Invalid character definition.
    SOR$_COL_CMPLX     Collating sequence is too complex.
    SOR$_COL_PAD       Invalid pad character.
    SOR$_COL_THREE     Cannot define 3-byte collating values.
    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_ILLBASE       Nondecimal base is invalid.
    SOR$_ILLLITERL     Record containing symbolic literals is
                       unsupported.
    SOR$_ILLSCALE      Nonzero scale invalid for floating-point data
                       item.
    SOR$_INCDIGITS     Number of digits is not consistent with the
                       type or length of item.
    SOR$_INCNODATA     Include specification references no data, at
                       line n.
    SOR$_INCNOKEY      Include specification references no keys, at
                       line n.
    SOR$_IND_OVR       Indexed output file must already exist.
    SOR$_KEYAMBINC     Key specification is ambiguous or
                       inconsistent.
    SOR$_KEYED         Mismatch between SORT/MERGE keys and primary
                       file key.
    SOR$_KEY_LEN       Invalid key length, key number n, length n.
    SOR$_LRL_MISS      Longest record length must be specified.
    SOR$_MISLENOFF     Length and offset required.
    SOR$_MISS_PARAM    A required subroutine argument is missing.
    SOR$_MULTIDIM      Invalid multidimensional OCCURS.
    SOR$_NODUPEXC      Equal-key routine and no-duplicates option
                       cannot both be specified.
    SOR$_NOTRECORD     Node name is a name, not a record definition.
    SOR$_NUM_KEY       Too many keys specified.
    SOR$_NYI           Not yet implemented.
    SOR$_OPENIN        Error opening file as input.
    SOR$_OPENOUT       Error opening file as output.
    SOR$_READERR       Error reading file.
    SOR$_RTNERROR      Unexpected error status from user-written
                       routine.
    SOR$_SIGNCOMPQ     Absolute Date and Time data type represented
                       in 1-second units.
    SOR$_SORT_ON       Sort or merge routines called in incorrect
                       order.
    SOR$_SPCIVC        Invalid collating sequence specification at
                       line n.
    SOR$_SPCIVD        Invalid data type at line n.
    SOR$_SPCIVF        Invalid field specification at line n.
    SOR$_SPCIVI        Invalid include or omit specification at line
                       n.
    SOR$_SPCIVK        Invalid key or data specification at line n.
    SOR$_SPCIVP        Invalid sort process at line n.
    SOR$_SPCIVS        Invalid specification at line n.
    SOR$_SPCIVX        Invalid condition specification at line n.
    SOR$_SPCMIS        Invalid merge specification at line n.
    SOR$_SPCOVR        Overridden specification at line n.
    SOR$_SPCSIS        Invalid sort specification at line n.
    SOR$_SRTIWA        Insufficient space. The specification file is
                       too complex.
    SOR$_STABLEEX      Equal-key routine and stable option cannot
                       both be specified.
    SOR$_SYSERROR      System service error.
    SOR$_UNDOPTION     Undefined option flag was set.
    SOR$_UNSUPLEVL     Unsupported core level for record name.
    SOR$_WRITEERR      Error writing file.

2  –  SOR$BEGIN_SORT

    The SOR$BEGIN_SORT routine initializes a sort operation by
    opening input and output files and by passing the key information
    and any sort options.

    Format

      SOR$BEGIN_SORT  [key_buffer] [,lrl] [,options] [,file_alloc]

                      [,user_compare] [,user_equal] [,sort_process]

                      [,work_files] [,context]

2.1  –  Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

2.2  –  Arguments

 key_buffer

    OpenVMS usage:vector_word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Array of words describing the keys on which you plan to sort. The
    key_buffer argument is the address of an array containing the key
    descriptions.

    The first word of this array contains the number of keys
    described (up to 255). Following the first word, each key is
    described (in order of priority) in blocks of four words. The
    four words specify the key's data type, order, offset, and
    length, respectively.

    The first word of the block specifies the data type of the key.
    The following data types are accepted:

    DSC$K_DTYPE_Z          Unspecified (uninfluenced by collating
                           sequence)
    DSC$K_DTYPE_B          Byte integer (signed)
    DSC$K_DTYPE_BU         Byte (unsigned)
    DSC$K_DTYPE_W          Word integer (signed)
    DSC$K_DTYPE_WU         Word (unsigned)
    DSC$K_DTYPE_L          Longword integer (signed)
    DSC$K_DTYPE_LU         Longword (unsigned)
    DSC$K_DTYPE_Q          Quadword integer (signed)
    DSC$K_DTYPE_QU         Quadword (unsigned)
    DSC$K_DTYPE_O(1)       Octaword integer (signed)
    DSC$K_DTYPE_OU(1)      Octaword (unsigned)
    DSC$K_DTYPE_F          Single-precision floating
    DSC$K_DTYPE_D          Double-precision floating
    DSC$K_DTYPE_G          G-format floating
    DSC$K_DTYPE_H(1)       H-format floating
    DSC$K_DTYPE_FS(2)      IEEE single-precision S floating
    DSC$K_DTYPE_FT(2)      IEEE double-precision T floating
    DSC$K_DTYPE_T          Text (may be influenced by collating
                           sequence)
    DSC$K_DTYPE_NU         Numeric string, unsigned
    DSC$K_DTYPE_NL         Numeric string, left separate sign
    DSC$K_DTYPE_NLO        Numeric string, left overpunched sign
    DSC$K_DTYPE_NR         Numeric string, right separate sign
    DSC$K_DTYPE_NRO        Numeric string, right overpunched sign
    DSC$K_DTYPE_NZ(1)      Numeric string, zoned sign
    DSC$K_DTYPE_P          Packed decimal string

    Footnotes:

    1. Data type is not currently supported by the high-performance
       Sort/Merge utility.

    2. Data type is Alpha specific.

    The VSI OpenVMS Programming Concepts Manual describes each of
    these data types.

    The second word of the block specifies the key order: 0 for
    ascending order, 1 for descending order. The third word of the
    block specifies the relative offset of the key in the record.
    Note that the first byte in the record is at position 0. The
    fourth word of the block specifies the key length in bytes (in
    digits for packed decimal-DSC$K_DTYPE_P).

    The key_buffer argument specifies the address of the key buffer
    in the data area. If you do not specify this argument, you must
    either pass a key comparison routine or use a specification file
    to define the key.

 lrl

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Length of the longest record that will be released for sorting.
    The lrl argument is the address of a word containing the length.
    This argument is not required if the input files are on disk but
    is required when you use the record interface. For VFC records,
    this length must include the length of the fixed-length portion
    of the record.

 options

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Flags that identify sort options. The options argument is the
    address of a longword bit mask whose settings determine the merge
    options selected. The following table lists and describes the bit
    mask values available.

    Flags          Description

    SOR$M_STABLE   Keeps records with equal keys in the same order in
                   which they appeared on input. With multiple input
                   files that have records that collate as equal,
                   records from the first input file are placed
                   before the records from the second input file,
                   and so on.
    SOR$M_EBCDIC   Orders ASCII character keys according to EBCDIC
                   collating sequence. No translation takes place.
    SOR$M_MULTI    Orders character keys according to the
                   multinational collating sequence, which collates
                   the international character set.
    SOR$M_         Returns a status code instead of signaling errors.
    NOSIGNAL
    SOR$M_NODUPS   Omits records with duplicate keys. You cannot
                   use this option if you specify your own equal-key
                   routine.

    All other bits in the longword are reserved and must be zero.

 file_alloc

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Input file size in blocks. The file_alloc argument is the
    address of a longword containing the size of the input file.
    This argument is optional because, by default, SORT uses the
    allocation of the input files. If you are using the record
    interface, or if the input files are not on disk, the default is
    1000 blocks.(The high-performance Sort/Merge utility determines
    the default based on the size of the input file, or if input is
    not from files, on available memory.) When you specify the input
    size with this argument, it overrides the default size.

    This optional argument is useful when you are using the record
    interface and you have a good idea of the total input size. You
    can use this argument to improve the efficiency of the sort by
    adjusting the amount of resources the sort process allocates to
    match the input size.

 user_compare

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call
    mechanism:    by reference
    User-written routine that compares records to determine their
    sort order. (This argument is not currently supported by the
    high-performance Sort/Merge utility.) The user_compare argument
    is the address of the procedure value for this user-written
    routine. If you do not specify the key_buffer argument or if
    you define key information in a specification file, this argument
    is required.

    SORT/MERGE calls the comparison routine with five reference
    arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to
    the addresses of the two records to be compared, the lengths of
    these two records, and the context longword. The LENG1 and LENG2
    arguments are addresses that point to 16-bit word structures that
    contain the length information.

    The comparison routine must return a 32-bit integer value:

    o  -1 if the first record collates before the second

    o  0 if the records collate as equal

    o  1 if the first record collates after the second

 user_equal

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call
    mechanism:    by reference
    User-written routine that resolves the sort order when records
    have duplicate keys. (This argument is not currently supported
    by the high-performance Sort/Merge utility.) The user_equal
    argument is the address of the procedure value for this user-
    written routine. If you specify SOR$M_STABLE or SOR$M_NODUPS in
    the options argument, do not use this argument.

    SORT/MERGE calls the duplicate key routine with five reference
    arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to the
    addresses of the two records that compare equally, the lengths of
    the two records that compare equally, and the context longword.
    The LENG1 and LENG2 arguments are addresses that point to 16-bit
    word structures that contain the length information.

    The routine must return one of the following 32-bit integer
    condition codes:

    Code         Description

    SOR$_        Delete the first record from the sort.
    DELETE1
    SOR$_        Delete the second record from the sort.
    DELETE2
    SOR$_        Delete both records from the sort.
    DELBOTH
    SS$_NORMAL   Keep both records in the sort.

    Any other failure value causes the error to be signaled or
    returned. Any other success value causes an undefined result.

 sort_process

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    Code indicating the type of sort process. The sort_process
    argument is the address of a byte whose value indicates whether
    the sort type is record, tag, index, or address. (The high-
    performance Sort/Merge utility supports only the record process.
    Implementation of the tag, address, and index processes is
    deferred to a future OpenVMS Alpha release.) The default is
    record. If you select the record interface on input, you can
    use only a record sort process.

    To specify a byte containing the value for the type of sort
    process you want, enter one of the following:

    o  SOR$GK_RECORD (record sort)

    o  SOR$GK_TAG (tag sort)

    o  SOR$GK_ADDRESS (address sort)

    o  SOR$GK_INDEX (index sort)

 work_files

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    Number of work files to be used in the sorting process. The work_
    files argument is the address of a byte containing the number of
    work files; permissible values for SORT range from 0 through 10.
    (For the high-performance Sort/Merge utility, you can specify
    from 1 through 255 work files. The default is 2.)

    By default, SORT creates two temporary work files when it needs
    them and determines their size from the size of your input files.
    By increasing the number of work files, you can reduce their
    individual size so that each fits into less disk space. You can
    also assign each of them to different disk-structured devices
    (highly recommended).

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

2.3  –  Description

    The SOR$BEGIN_SORT routine initializes the sort process by
    setting up sort work areas and provides key specification and
    sort options.

    Specify the key information with the key_buffer argument, with
    the user_compare argument, or in a specification file. If no key
    information is specified, the default (character for the entire
    record) is used.

    You must use the SOR$BEGIN_SORT routine to initialize the sort
    process for the file, record, and mixed interfaces. For record
    interface on input, you must use the lrl (longest record length)
    argument.

    Some of the following condition values are used with different
    severities, depending on whether SORT/MERGE can recover. Thus,
    if you want to check for a specific status, you should use
    LIB$MATCH_COND.

2.4  –  Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SOR$_BADLOGIC      Internal logic error detected.
    SOR$_BAD_KEY       Invalid key specification.
    SOR$_BAD_LRL       Record length n greater than specified longest
                       record length.
    SOR$_BAD_MERGE     Number of work files must be between 0 and 10.
                       (For the high-performance Sort/Merge utility,
                       the maximum number is 255.)
    SOR$_BAD_TYPE      Invalid sort process specified.
    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_INSVIRMEM     Insufficient virtual memory.
    SOR$_KEYAMBINC     Key specification is ambiguous or
                       inconsistent.
    SOR$_KEY_LEN       Invalid key length, key number n, length n.
    SOR$_LRL_MISS      Longest record length must be specified.
    SOR$_NODUPEXC      Equal-key routine and no-duplicates option
                       cannot both be specified.
    SOR$_NUM_KEY       Too many keys specified.
    SOR$_NYI           Not yet implemented.
    SOR$_RTNERROR      Unexpected error status from user-written
                       routine.
    SOR$_SORT_ON       Sort or merge routine called in incorrect
                       order.
    SOR$_STABLEEXC     Equal-key routine and stable option cannot
                       both be specified.
    SOR$_SYSERROR      System service error.
    SOR$_UNDOPTION     Undefined option flag was set.

3  –  SOR$DTYPE

    The SOR$DTYPE routine defines a key data type that is not
    normally supported by SORT/MERGE. (This routine is not currently
    supported by the high-performance Sort/Merge utility.) This
    routine returns a key data type code that can be used in the key_
    buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_MERGE to describe
    special key data types (such as extended data types and National
    character set (NCS) collating sequences).

    Format

      SOR$DTYPE  [context] ,dtype_code ,usage ,p1

3.1  –  Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

3.2  –  Arguments

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

 dtype_code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Returned key data type code. The dtype_code argument is the
    address of a word into which SORT/MERGE writes the key data type
    code that can be used in the key_buffer argument to SOR$BEGIN_
    SORT or SOR$BEGIN_MERGE.

 usage

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing a code that indicates the
    interpretation of the p1 argument. The following table lists
    and describes the valid usage codes:

    Flag             Description

    SOR$K_ROUTINE    The p1 argument should be interpreted as the
                     address of the procedure value of a routine
                     that SORT/MERGE will call to compare keys
                     described by the dtype_code returned by the
                     call to SOR$DTYPE.
    SOR$K_NCS_TABLE  The p1 argument should be interpreted as the
                     address of a collating sequence identification
                     returned by a call to NCS$GET_CS. SORT/MERGE
                     will use this collating sequence to compare keys
                     described by the dtype_code returned by the call
                     to SOR$DTYPE.

    If SOR$K_ROUTINE is returned, SORT/MERGE will call this routine
    with five reference arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-
    corresponding to the addresses of the two keys to be compared,
    the lengths of the two keys, and the context longword.

    The comparison routine must return a 32-bit integer value:

    o  -1 if the first key collates before the second

    o  0 if the keys collate as equal

    o  +1 if the first key collates after the second

 p1

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of the procedure value of a routine or the address of
    a collating sequence identification, depending on the usage
    argument.

3.3  –  Description

    Call SOR$DTYPE to define a key data type not normally supported
    by SORT/MERGE.

    If your SORT/MERGE application needs to compare dates (for
    example) that are stored in text form and that is the only key
    in the records, then use the user_compare argument to SOR$BEGIN_
    SORT or SOR$BEGIN_MERGE. However, if the records contain several
    keys besides the dates in text form, it may be easier to call
    SOR$DTYPE to allocate a key data type code that can then be used
    in the the key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_
    MERGE.

    If your SORT/MERGE application has a string key that should be
    collated by a collating sequence defined by the NCS utility, the
    NCS$GET_CS routine can be used to fetch the collating sequence
    definition, and SOR$DTYPE can be called to allocate a key data
    type code for the collating sequence. This key data type code
    can then be used to describe keys that should be compared by this
    collating sequence.

3.4  –  Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SOR$_NYI           Not yet implemented.
    SOR$_SORT_ON       Sort or merge routine called in incorrect
                       order.

4  –  SOR$END_SORT

    The SOR$END_SORT routine performs cleanup functions, such as
    closing files and releasing memory.

    Format

      SOR$END_SORT  [context]

4.1  –  Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

4.2  –  Argument

 context

    OpenVMS usage:context
    type:         longword
    access:       write only
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

4.3  –  Description

    The SOR$END_SORT routine ends a sort or merge operation, either
    at the end of a successful process or between calls because of an
    error. If an error status is returned, you must call SOR$END_SORT
    to release all allocated resources. In addition, this routine can
    be called at any time to close files and release memory.

    The value of the optional context argument is cleared when the
    SOR$END_SORT routine completes its operation.

    Some of the following condition values are used with different
    severities, depending on whether SORT/MERGE can recover. Thus,
    if you want to check for a specific status, you should use
    LIB$MATCH_COND.

4.4  –  Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SOR$_CLOSEIN       Error closing file as input.
    SOR$_CLOSEOUT      Error closing file as output.
    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_END_SORT      SORT/MERGE terminated, context = context.
    SOR$_SYSERROR      System service error.

5  –  SOR$PASS_FILES

    The SOR$PASS_FILES routine passes the names of input and output
    files and output file characteristics to SORT or MERGE.

    Format

      SOR$PASS_FILES  [inp_desc] [,out_desc] [,org] [,rfm] [,bks]

                      [,bls] [,mrs] [,alq] [,fop] [,fsz] [,context]

5.1  –  Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

5.2  –  Arguments

 inp_desc

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Input file specification. The inp_desc argument is the address
    of a descriptor pointing to the file specification. In the
    file interface, you must call SOR$PASS_FILES to pass SORT
    the input file specifications. For multiple input files, call
    SOR$PASS_FILES once for each input file, passing one input file
    specification descriptor each time.

    In the mixed interface, if you are using the record interface on
    input, pass only the output file specification; do not pass any
    input file specifications. If you are using the record interface
    on output, pass only the input file specifications; do not pass
    an output file specification or any of the optional output file
    arguments.

 out_desc

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Output file specification. The out_desc argument is the address
    of a descriptor pointing to the file specification. In the file
    interface, when you call SOR$PASS_FILES, you must pass the output
    file specification. Specify the output file specification and
    characteristics only once, as part of the first call, as in the
    following:

    Call SOR$PASS_FILES(Input1,Output)
    Call SOR$PASS_FILES(Input2)
    Call SOR$PASS_FILES(Input3)

    In the mixed interface, if you are using the record interface on
    input, pass only the output file specification; do not pass any
    input file specifications. If you are using the record interface
    on output, pass only the input file specifications; do not pass
    an output file specification or any of the optional output file
    arguments.

 org

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    File organization of the output file, if different from the
    input file. The org argument is the address of a byte whose value
    specifies the organization of the output file; permissible values
    include the following:

    FAB$C_SEQ
    FAB$C_REL
    FAB$C_IDX

    For the record interface on input, the default value is
    sequential. For the file interface, the default value is the
    file organization of the first input file for record or tag sort
    and sequential for address and index sort.

    For more information about OpenVMS RMS file organizations, see
    the OpenVMS Record Management Services Reference Manual.

 rfm

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    Record format of the output file, if different from the input
    file. The rfm argument is the address of a byte whose value
    specifies the record format of the output file; permissible
    values include the following:

    FAB$C_FIX
    FAB$C_VAR
    FAB$C_VFC

    For the record interface on input, the default value is variable.
    For the file interface, the default value is the record format
    of the first input file for record or tag sort and fixed format
    for address or index sort. For the mixed interface with record
    interface on input, the default value is variable format.

    For more information about OpenVMS RMS record formats, see the
    OpenVMS Record Management Services Reference Manual.

 bks

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    Bucket size of the output file, if different from the first input
    file. The bks argument is the address of a byte containing this
    size. Use this argument with relative and indexed-sequential
    files only. If the bucket size of the output file is to differ
    from that of the first input file, specify a byte to indicate the
    bucket size. Acceptable values are from 1 to 32. If you do not
    pass this argument-and the output file organization is the same
    as that of the first input file-the bucket size defaults to the
    value of the first input file. If the file organizations differ
    or if the record interface is used on input, the default value is
    1 block.

 bls

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Block size of a magnetic tape output file. The bls argument is
    the address of a word containing this size. Use this argument
    with magnetic tapes only. Permissible values range from 20 to
    65,532. However, to ensure compatibility with non-VMS systems,
    ANSI standards require that the block size be less than or equal
    to 2048.

    The block size defaults to the block size of the input file
    magnetic tape. If the input file is not on magnetic tape,
    the output file block size defaults to the size used when the
    magnetic tape was mounted.

 mrs

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Maximum record size for the output file. The mrs argument is the
    address of a word specifying this size. Following are acceptable
    values for each type of file:

    File
    Organization     Acceptable Value

    Sequential       0 to 32,767
    Relative         0 to 16,383
    Indexed          0 to 16,362
    sequential

    If you omit this argument or if you specify a value of 0, SORT
    does not check maximum record size.

    If you do not specify this argument, the default is based on the
    output file organization and format, unless the organization is
    relative or the format is fixed. The longest output record length
    is based on the longest calculated input record length, the type
    of sort, and the record format.

 alq

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Number of preallocated output file blocks. The alq argument is
    the address of a longword specifying the number of blocks you
    want to preallocate to the output file. Acceptable values range
    from 1 to 4,294,967,295.

    Pass this argument if you know your output file allocation will
    be larger or smaller than that of your input files. The default
    value is the total allocation of all the input files. If the
    allocation cannot be obtained for any of the input files or
    if the record interface is used on input, the file allocation
    defaults to 1000 blocks.

 fop

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    File-handling options. The fop argument is the address of a
    longword whose bit settings determine the options selected. For
    a list of valid file-handling options, see the description of
    the FAB$L_FOP field in the OpenVMS Record Management Services
    Reference Manual. By default, only the DFW (deferred write)
    option is set. If your output file is indexed, you should set
    the CIF (create if) option.

 fsz

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    Size of the fixed portion of VFC records. The fsz argument is the
    address of a byte containing this size. If you do not pass this
    argument, the default is the size of the fixed portion of the
    first input file. If you specify the VFC size as 0, RMS defaults
    the value to 2 bytes.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Value that distinguishes between multiple concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

5.3  –  Description

    The SOR$PASS_FILES routine passes input and output file
    specifications to SORT. The SOR$PASS_FILES routine must be
    repeated for multiple input files. The output file name string
    and characteristics should be specified only in the first call to
    SOR$PASS_FILES.

    This routine also accepts optional arguments that specify
    characteristics for the output file. By default, the output file
    characteristics are the same as the first input file; specified
    output file characteristics are used to change these defaults.

    Some of the following condition values are used with different
    severities, depending on whether SORT/MERGE can recover. Thus,
    if you want to check for a specific status, you should use
    LIB$MATCH_COND.

5.4  –  Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SOR$_DUP_OUTPUT    Output file has already been specified.
    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_INP_FILES     Too many input files specified.
    SOR$_NYI           Not yet implemented.
    SOR$_SORT_ON       Sort or merge routine called in incorrect
                       order.
    SOR$_SYSERROR      System service error.

6  –  SOR$RELEASE_REC

    The SOR$RELEASE_REC routine is used with the record interface to
    pass one input record to SORT or MERGE.

    Format

      SOR$RELEASE_REC  desc [,context]

6.1  –  Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

6.2  –  Arguments

 desc

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Input record buffer. The desc argument is the address of a
    descriptor pointing to the buffer containing the record to
    be sorted. If you use the record interface, this argument is
    required.

 context

    OpenVMS usage:context
    type:         longword
    access:       modify
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

6.3  –  Description

    Call SOR$RELEASE_REC to pass records to SORT or MERGE with the
    record interface. SOR$RELEASE_REC must be called once for each
    record to be sorted.

    Some of the following condition values are used with different
    severities, depending on whether SORT/MERGE can recover. Thus,
    if you want to check for a specific status, you should use
    LIB$MATCH_COND.

6.4  –  Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SOR$_BADLOGIC      Internal logic error detected.
    SOR$_BAD_LRL       Record length n greater than longest specified
                       record length.
    SOR$_BAD_SRL       Record length n too short to contain keys.
    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_EXTEND        Unable to extend work file for needed space.
    SOR$_MISS_PARAM    The desc argument is missing.
    SOR$_NO_WRK        Work files required; cannot do sort in memory
                       as requested.
    SOR$_OPENOUT       Error opening file as output.
    SOR$_OPERFAIL      Error requesting operator service.
    SOR$_READERR       Error reading file.
    SOR$_REQ_ALT       Specify alternate name file (or nothing to try
                       again).
    SOR$_RTNERROR      Unexpected error status from user-written
                       routine.
    SOR$_SORT_ON       Sort or merge routines called in incorrect
                       order.
    SOR$_SYSERROR      System service error.
    SOR$_USE_ALT       Using alternate file name.
    SOR$_WORK_DEV      Work file name must be on random access local
                       device.

7  –  SOR$RETURN_REC

    The SOR$RETURN_REC routine is used with the record interface to
    return one sorted or merged record to a program.

    Format

      SOR$RETURN_REC  desc [,length] [,context]

7.1  –  Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

7.2  –  Arguments

 desc

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor
    Output record buffer. The desc argument is the address of a
    descriptor pointing to the buffer that receives the sorted or
    merged record.

 length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Length of the output record. The length argument is the address
    of a word receiving the length of the record returned from
    SORT/MERGE.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

7.3  –  Description

    Call the SOR$RETURN_REC routine to release the sorted or merged
    records to a program. Call this routine once for each record to
    be returned.

    SOR$RETURN_REC places the record into a record buffer that you
    set up in the program's data area. After SORT has successfully
    returned all the records to the program, it returns the status
    code SS$_ENDOFFILE, which indicates that there are no more
    records to return.

    Some of the following condition values are used with different
    severities, depending on whether SORT/MERGE can recover. Thus,
    if you want to check for a specific status, you should use
    LIB$MATCH_COND.

7.4  –  Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SOR$_BADLOGIC      Internal logic error detected.
    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_EXTEND        Unable to extend work file for needed space.
    SOR$_MISS_PARAM    A required subroutine argument is missing.
    SOR$_OPERFAIL      Error requesting operator service.
    SOR$_READERR       Error reading file.
    SOR$_REQ_ALT       Specify alternate name file (or specify
                       nothing to simply try again).
    SOR$_RTNERROR      Unexpected error status from user-written
                       routine.
    SOR$_SORT_ON       Sort or merge routines called in incorrect
                       order.
    SOR$_SYSERROR      System service error.
    SOR$_USE_ALT       Using alternate file name.
    SOR$_WORK_DEV      Work file name must be on random access local
                       device.

8  –  SOR$SORT_MERGE

    The SOR$SORT_MERGE routine sorts the input records.

    Format

      SOR$SORT_MERGE  [context]

8.1  –  Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

8.2  –  Argument

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

8.3  –  Description

    After you have passed either the file names or the records to
    SORT, call the SOR$SORT_MERGE routine to sort the records. For
    file interface on input, the input files are opened and the
    records are released to the sort. For the record interface on
    input, the record must have already been released (by calls
    to SOR$RELEASE_REC). For file interface on output, the output
    records are reformatted and directed to the output file. For the
    record interface on output, SOR$RETURN_REC must be called to get
    the sorted records.

    Some of the return values are used with different severities
    depending on whether SORT/MERGE can recover. Thus, if you want to
    check for a specific status, you should use LIB$MATCH_COND.

8.4  –  Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SOR$_BADDTYPE      Invalid or unsupported CDD data type.
    SOR$_BADLENOFF     Length and offset must be multiples of 8 bits.
    SOR$_BADLOGIC      Internal logic error detected.
    SOR$_BADOCCURS     Invalid OCCURS clause.
    SOR$_BADOVRLAY     Invalid overlay structure.
    SOR$_BADPROTCL     Node is an invalid CDD object.
    SOR$_BAD_LRL       Record length n greater than longest specified
                       record length.
    SOR$_BAD_TYPE      Invalid sort process specified.
    SOR$_CDDERROR      CDD error at node name.
    SOR$_CLOSEIN       Error closing file as input.
    SOR$_CLOSEOUT      Error closing file as output.
    SOR$_COL_CHAR      Invalid character definition.
    SOR$_COL_CMPLX     Collating sequence is too complex.
    SOR$_COL_PAD       Invalid pad character.
    SOR$_COL_THREE     Cannot define 3-byte collating values.
    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_EXTEND        Unable to extend work file for needed space.
    SOR$_ILLBASE       Nondecimal base is invalid.
    SOR$_ILLLITERL     Record containing symbolic literals is
                       unsupported.
    SOR$_ILLSCALE      Nonzero scale invalid for floating-point data
                       item.
    SOR$_INCDIGITS     Number of digits is inconsistent with the type
                       or length of item.
    SOR$_INCNODATA     Include specification references no data
                       keyword, at line n.
    SOR$_INCNOKEY      Include specification references no keys
                       keyword, at line n.
    SOR$_IND_OVR       Indexed output file must already exist.
    SOR$_KEYED         Mismatch between SORT/MERGE keys and primary
                       file key.
    SOR$_LRL_MISS      Longest record length must be specified.
    SOR$_MISLENOFF     Length and offset required.
    SOR$_MULTIDIM      Invalid multidimensional OCCURS.
    SOR$_NOTRECORD     Node name is a name, not a record definition.
    SOR$_NO_WRK        Work files required, cannot do sort in memory
                       as requested.
    SOR$_OPENIN        Error opening file as input.
    SOR$_OPENOUT       Error opening file as output.
    SOR$_OPERFAIL      Error requesting operator service.
    SOR$_READERR       Error reading file.
    SOR$_REQ_ALT       Specify alternate name file (or nothing to try
                       again).
    SOR$_RTNERROR      Unexpected error status from user-written
                       routine.
    SOR$_SIGNCOMPQ     Absolute Date and Time data type represented
                       in 1-second units.
    SOR$_SORT_ON       Sort or merge routines called in incorrect
                       order.
    SOR$_SPCIVC        Invalid collating sequence specification, at
                       line n.
    SOR$_SPCIVD        Invalid data type, at line n.
    SOR$_SPCIVF        Invalid field specification, at line n.
    SOR$_SPCIVI        Invalid include or omit specification, at line
                       n.
    SOR$_SPCIVK        Invalid key or data specification, at line n.
    SOR$_SPCIVP        Invalid sort process, at line n.
    SOR$_SPCIVS        Invalid specification, at line n.
    SOR$_SPCIVX        Invalid condition specification, at line n.
    SOR$_SPCMIS        Invalid merge specification, at line n.
    SOR$_SPCOVR        Overridden specification, at line n.
    SOR$_SPCSIS        Invalid sort specification, at line n.
    SOR$_SRTIWA        Insufficient space. Specification file is too
                       complex.
    SOR$_SYSERROR      System service error.
    SOR$_UNSUPLEVL     Unsupported core level for record name.
    SOR$_USE_ALT       Using alternate file name.
    SOR$_WORK_DEV      Work file name must be on random access local
                       device.
    SOR$_WRITEERR      Error writing file.

9  –  SOR$SPEC_FILE

    The SOR$SPEC_FILE routine is used to pass a specification file
    or specification text to a sort or merge operation. (This routine
    is not currently supported by the high-performance Sort/Merge
    utility.)

    Format

      SOR$SPEC_FILE  [spec_file] [,spec_buffer] [,context]

9.1  –  Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

9.2  –  Arguments

 spec_file

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read-only
    mechanism:    by descriptor
    Specification file name. The spec_file argument is the address
    of a descriptor pointing to the name of a file that contains
    the text of the options requested for the sort or merge. The
    specification file name string and the specification file buffer
    arguments are mutually exclusive.

 spec_buffer

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read-only
    mechanism:    by descriptor
    Specification text buffer. The spec_buffer argument is the
    address of a descriptor pointing to a buffer containing
    specification text. This text has the same format as the text
    within the specification file. The specification file name
    string and the specification file buffer arguments are mutually
    exclusive.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

9.3  –  Description

    Call SOR$SPEC_FILE to pass a specification file name or a buffer
    with specification text to a sort or merge operation. Through
    the use of a specification file, you can selectively omit or
    include particular records from the sort or merge operation and
    specify the reformatting of the output records. (See the Sort
    Utility in the OpenVMS User's Manual for a complete description
    of specification files.)

    If you call the SOR$SPEC_FILE routine, you must do so before you
    call any other routines. You must pass either the spec_file or
    spec_buffer argument, but not both.

    Some of the return condition values are used with different
    severities, depending on whether SORT/MERGE can recover. Thus,
    if you want to check for a specific status, you should use
    LIB$MATCH_COND.

9.4  –  Condition Values Returned

    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_NYI           Not yet implemented.
    SOR$_SORT_ON       Sort or merge routine called in incorrect
                       order.
    SOR$_SYSERROR      System service error.

10  –  SOR$STAT

    The SOR$STAT routine returns one statistic about the sort or
    merge operation to the user program.

    Format

      SOR$STAT  code ,result [,context]

10.1  –  Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

10.2  –  Arguments

 code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    SORT/MERGE statistic code. The code argument is the address of
    a longword containing the code that identifies the statistic
    you want returned in the result argument. The following table
    describes the values that are accepted.

    Note: The high-performance Sort/Merge utility currently supports
    only the following subset of these values: SOR$K_REC_INP, SOR$K_
    REC_SOR, SOR$K_REC_OUT, SOR$K_LRL_INP.

    Code             Description

    SOR$K_IDENT      Address of ASCII string for version number
    SOR$K_REC_INP    Number of records input
    SOR$K_REC_SOR    Records sorted
    SOR$K_REC_OUT    Records output
    SOR$K_LRL_INP    Longest record length (LRL) for input
    SOR$K_LRL_INT    Internal LRL
    SOR$K_LRL_OUT    LRL for output
    SOR$K_NODES      Nodes in sort tree
    SOR$K_INI_RUNS   Initial dispersion runs
    SOR$K_MRG_       Maximum merge order
    ORDER
    SOR$K_MRG_       Number of merge passes
    PASSES
    SOR$K_WRK_ALQ    Work file allocation
    SOR$K_MBC_INP    Multiblock count for input
    SOR$K_MBC_OUT    Multiblock count for output
    SOR$K_MBF_INP    Multibuffer count for input
    SOR$K_MBF_OUT    Multibuffer count for output

    Note that performance statistics (such as direct I/O, buffered
    I/O, and elapsed and CPU times) are not available because user-
    written routines may affect those values. However, they are
    available if you call LIB$GETJPI.

 result

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    SORT/MERGE statistic value. The result argument is the address
    of a longword into which SORT/MERGE writes the value of the
    statistic identified by the code argument.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

10.3  –  Description

    The SOR$STAT routine returns one statistic about the sort or
    merge operation to your program. You can call the SOR$STAT
    routine at any time while the sort or merge is active.

    Some of the following condition values are used with different
    severities, depending on whether SORT/MERGE can recover. Thus,
    if you want to check for a specific status, you should use
    LIB$MATCH_COND.

10.4  –  Condition Values Returned

    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_MISS_PARAM    A required subroutine argument is missing.
    SOR$_NYI           Functionality is not yet implemented.
    SOR$_SYSERROR      System service error.
Close Help