Byte-stream File Handling | Fileshare |
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.
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.
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.
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
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. |
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. |
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. |
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.
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.
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.
Byte-stream File Handling | Fileshare |