HP 3000 Manuals HP 3000 Manuals
Operation
You can invokeExtsm, instead of the default run-time system Sort module,
for quicker execution of COBOL SORT and MERGE verbs in your program.
You invoke Extsm in either of two ways:
* Compile your program with the CALLSORT"EXTSM"directive either
specified on the command line or included in the $SET statement of
your program. This method of invoking Extsm enables you to use
floating-point keys when performing SORT or MERGE operations.
* Call Extsm explicitly using a call statement in your program. See
the section Call Interface for further details.
When you perform a SORT operation on a data file, any duplicate keys
within the file are returned in random order. Setting the S
run-timeswitch forces all SORT statements within your file to be treated
at run-time as though you had specified the SORT...WITH DUPLICATES IN
ORDER statement. This means that duplicate keys are returned in the
order they were written.
NOTE The S Switch is only applicable to Sort operations using Extsm.
Setting the S switch is the only available method of ensuring that
duplicate keys in a SORT statement are returned in order, as although you
can explicitly specify the WITH DUPLICATES IN ORDER phrase in your
program, it has no effect at run-time.
By default, this switch is set off (COBSW=-S). If no other switch is set
in COBSW, you can set it on as follows:
COBSW=+S
For UNIX systems, export this setting to the shell.(UNIX)
If COBSW already has other switches set, you need to add +S to it.
Call Interface
You can call Extsmexplicitly 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 later in this
chapter 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, file-name,
collating sequence, key definition block (see the section
Key Definition Block) and file definition block (see the
section File Definition Block) of a file. See the
section Sort File Control Description for further
information about the Sort FCD.
When using this command line, the normal COBOL syntax for SORT and MERGE
is not used. You therefore need to create a definition for each file in
the Data Division of your program which is involved in the SORT.
Function Codes.
Possible values for the function code parameter are:
x"FA01" Initiates the 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 returns from this call.
x"FA40" Initiates the MERGE operation. For this operation the
number of USING files MUST be other than zero. It is
assumed that each of these USING files already has records
sorted into order.
x"FAF3" Releases a record to the Sort operation. This function is
used only when the number of USING files is zero.
x"FA10" Terminates the input stage of the Sort operation. This
function is used only 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 used only 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 created. This function is used only when
the number of GIVING files is zero. It indicates that no
more Return operations are to be performed.
Sort File Control Description.
Set up the Sort File Control Description (FCD) in the same way as the FCD
used by the Callable File Handler.
The Sort FCD used to interface to Extsm has the following fields in
addition to, or overriding, the fields in the FCD described in the
chapter Callable File Handler earlier in this manual:
Offset Size Description
-----------------------------------------------
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.
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 earlier in this manual.
In the case of 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.
File Definition Block.
A File Definition Block is a table of pointers which 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.
Linking Extsm into your Application
To link Extsm into your application or executable program, there are
certain modules you must include certain modules on the command line.
There are also some modules which are optional. The following table
lists the mandatory and optional modules:
Mandatory Optional
-------------------------------------------------------
Extfh Xfhname (for file-name mapping)
COBFP87O (for CBLDC001 (for compressed files)
OS/2)
COBFP87D (for DOS)
COBFP87W (for
Windows)
See your COBOL System Reference for further information on linking a
module into an application.
By default, Extsm will call the Callable File Handler (Extfh) for all I/O
on USING and GIVING files. If you want to call your own file handler to
this, use the CALLFH directive to specify the file handler to be called.
See the chapter Callable File Handler for details of how to do this.