PreviousByte-stream File Handling FileshareNext"

Chapter 17: Callable Sort Module (Extsm)

The Callable Sort Module (Extsm) is a standalone sort routine that enables you to sort and re-order data files. The Callable Sort Module is faster than the default run-time system sort module and provides greater flexibility in sorting data. In addition, its call interface enables you to substitute alternative sort modules.

17.1 Overview

Using Extsm to sort your data files enables you to:

This chapter describes the call interface, how to use Extsm to sort your data files, and how to link Extsm into your application.

17.2 Operation

You can invoke Extsm, instead of the default run-time system sort module, for quicker execution of COBOL SORT and MERGE syntax in your program. To do this, compile your program with the CALLSORT"EXTSM" Compiler directive. This also enables you to use floating-point keys when performing SORT or MERGE operations.

You can also call Extsm explicitly using a CALL statement in your program instead of using COBOL syntax. See the section Call Interface for further details.

17.2.1 Ordering Duplicate Keys

16-bit:
On 16-bit systems, if you are using Extsm rather than the default run-time sort module, when your program performs a SORT operation on a data file, any duplicate keys in the file are returned in random order. You can force the SORT operation to return duplicate keys in the order in which they were written by:

32-bit:
On 32-bit systems, regardless of whether you are using Extsm or the default run-time sort module, when your program performs a SORT operation on a data file, any duplicate keys are returned in random order. You can force the SORT operation to return duplicate keys in the order in which they were written by using the +S run-time switch

17.2.2 Call Interface

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

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

where:

function-code is a 2-byte code indicating the type of operation to be performed. See the section Function Codes for details of valid codes.
sort-fcd is 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 for futher information about the Sort FCD.

17.2.2.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 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.

17.2.2.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 Callable File Handler.

Offset
Size
Description of the field
52 1 Number of USING files involved in the sort operation (this can be zero).
53 1 Number of GIVING files involved in the sort operation (this can be zero).
68 4 Pointer to the collating sequence (null if none used).
72 4 Pointer to the File Definition Block where you define the USING and GIVING files. See the section File Definition Block for further information.

17.2.2.3 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 the Sort FCD at offset 64.

See the section Key Definition Block in the chapter Callable File Handler 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. 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.

17.2.2.4 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. There is a pointer to this area in the Sort FCD at offset 72. Its length is four times the total of the contents of the fields at offsets 52 and 53.

17.2.3 Linking Extsm into your Application

To link Extsm into your application or executable program, you must include certain modules on the command line. There are also some modules that are optional. The following table lists the mandatory and the optional modules:

Mandatory
Optional
Extsm Xfhname (for filename mapping)
Extfh CBLDC001 and/or CBLDC003 (for compressed files)
COBFP87O (for OS/2)
COBFP87D (for DOS)
COBFP87W (for Windows)

See your Object COBOL User Guide for further information on linking a module into an application.

By default, Extsm calls the Callable File Handler (ExtFH) for all I/O on USING and GIVING files. If you want to call your own file handler to do this, use the CALLFH directive to specify the file handler to be called. See the chapter Callable File Handler for details on how to do this.


Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousByte-stream File Handling FileshareNext"