Chapter 13: Callable Sort API

When your COBOL program uses the SORT or MERGE verbs, the Compiler automatically translates these statements into calls to the Callable Sort Module (Extsm). This chapter describes how your program can perform sorts by making explicit calls to the Callable Sort Module.

13.1 Call Interface

You can call the Callable Sort Module explicitly to sort or merge your files, by including the following call statement in your program:

call "EXTSM" using function-code, sort-fcd

where the parameters are:

`function-code`	A two-byte code indicating the type of operation to be performed. See the section Function Codes for details of valid codes.
`sort-fcd`	The Sort File Control Description (FCD). This is an area in the Data Division that describes a file. This contains pointers to the record area, filename, collating sequence, Key Definition Block and File Definition Block. See the section Sort File Control Description for futher information about the Sort FCD.

13.1.1 Function Codes

Possible values for the function-code parameter are:

x"FA01"	Initiates a sort operation. If the number of USING files is other than zero, the sort starts immediately, using the specified files as input. If the number of GIVING files is other than zero, the sort operation processes the GIVING files before returning control to the calling program.
x"FA40"	Initiates a merge operation. For this operation the number of USING files must be other than zero. It is assumed that the records in each of the USING files are already sorted.
x"FAF3"	Releases a record to the sort operation. This function is only used when the number of USING files is zero.
x"FA10"	Terminates the input stage of a sort operation. This function is only used when the number of USING files is zero. It indicates that no more release operations are to be performed. If the number of GIVING files is other than zero, the sort operation writes the sorted data to the GIVING file and terminates.
x"FAF5"	Returns a record from the sort or merge operation. This function is only used when the number of GIVING files is zero.
x"FA88"	Terminates the sort or merge operation, releasing all memory allocated for the operation and deleting any temporary files. This function is only used when the number of GIVING files is zero. It indicates that no more return operations are to be performed.

13.1.2 Sort File Control Description

The Sort FCD used has the following fields in addition to, or overriding, the fields in the FCD described in the chapter File Handler API.

Field Name	Size	Description of the Field
fcd-use-files	1	Number of USING files involved in the sort operation (this can be zero).
fcd-give-files	1	Number of GIVING files involved in the sort operation (this can be zero).
fcd-col-seq-address	4	Pointer to the collating sequence (null if none used).
fcd-fildef-address	4	Pointer to the File Definition Block where you define the USING and GIVING files. See the section File Definition Block for further information.

13.1.2.1 Key Definition Block

The Key Definition Block is used to describe the structure of the key to be used in the sort operation. There is a pointer to this block in fcd-key-def-address in the Sort FCD.

See the section Key Definition Block in the chapter File Handler API for full details of the Key Definition Block.

For sort operations, only one key is allowed, although this key can have many components. Each of these components can be either ascending or descending and can have one of many different numeric formats. Records with duplicate key values are always returned in the order in which they are presented to the sort operation. The first two bytes of the component definition are used as follows:

Offset 0 - 1 byte:
    bit 6 (value x"40") indicates DESCENDING key
    bit 0 (value x"01") indicates that the data is in EBCDIC format
    bit 1 (value x"02" indicates that SIGN is in EBCDIC format

Offset 1 - 1 byte:
    bit 7 (value x"80") indicates that the field is NUMERIC
      If bit 7 is set (numeric):
        bit 6 (value x"40") indicates that the field is SIGNED NUMERIC
        bit 5 (value x"20") indicates that the field is a non-display field
          If bit 5 is set (non-DISPLAY field):
            bits 0 and 1 are used as follows:
            0    indicates that the field is BINARY
            1    indicates that the field is PACKED-DECIMAL
            2    indicates that the field is COMP-X format
            3    indicates that the field is COMP-5 format
            bit 2 (value x"04") indicates floating point
          If bit 5 is not set, (DISPLAY field)
          but bit 6 is set (SIGNED field):
            bits 0 and 1 are used as follows:
            0    indicates SIGN TRAILING INCLUDED
            1    indicates SIGN TRAILING SEPARATE
            2    indicates SIGN LEADING INCLUDED
            3    indicates SIGN LEADING SEPARATE
      If bit 7 is not set (non-numeric):
        Bit 1 is set if the collating sequence specified in the FCD is
        to be applied to this field.

13.1.2.2 File Definition Block

A File Definition Block is a table of pointers that point to the file control descriptions for each of the USING and GIVING files involved in the sort operation. The fcd-fildef-address field in the Sort FCD is a pointer to this area. Its length is four times the total of the contents of the two fields fcd-use-files and fcd-give-files.

Byte-stream File Handling

File Structures