IFSKEY (HLI function)

The conventions used on this page are described in Function call notation conventions.

Summary

Description

The IFSKEY call (SORT KEYS) sorts the records in a found set or list in the specified order, using the record keys.

Thread type

multiple cursor IFSTRT, single cursor IFSTRT

IFCALL function number

83

Syntax

IFSKEY(RETCODE,SORT_SPEC,SKEY_NAME,%VARBUF,%VARSPEC)

Compile-only form

IFCALL function number: 84

IFSKYC(RETCODE,SORT_SPEC,SKEY_NAME)

Execute-only form

IFCALL function number: 85

IFSKYE(RETCODE,SKEY_NAME,%VARBUF,%VARSPEC)

Specify the parameters in the syntax order shown above.

Parameter	Description
RETCODE	[O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value.
SORT_SPEC	[I,c,r] The sort specification is required to specify ordering criteria for a found record set. Specify the ordering clause as a character string. See the detailed description of the sort specification used with IFSORT that is also valid for IFSKEY. Note: The SORT_SPEC options that are available in an IFSKEY call are similar to the sort options available in a SOUL SORT RECORD KEYS statement. For IFSKEY, the EACH term is not supported. For more information, see Sorting.
SKEY_NAME	[I,s,r/o] The name of the IFSKEY compilation is an input parameter that is required for use with a multiple cursor IFSTRT thread, and is only required for a single cursor IFSTRT thread if using the Compiled IFAM facility (IFSKYC and IFSKYE). Model 204 saves the compilation using this name. Specify the name as unique, and as a short character string (maximum 32 characters). On a single cursor IFSTRT thread, any characters except the following are valid in the name: blank, comma, parenthesis, equal sign, or semicolon. On a multiple cursor IFSTRT thread, the first character in the name must be alphanumeric, and the name must begin with a letter (A-Z or a-z) which can be followed by a letter, a digit (0-9), a period (.), or underscore (_). Note: A null value is equivalent to omitting the name parameter, and is not valid for a multiple cursor thread.
%VARBUF	[I,c,o] The variable buffer is an optional input parameter that addresses a data area that accommodates up to 255 bytes of data per value. The buffer contains values that are defined by the %VARSPEC parameter to be assigned to %variables. Specify a character string.
%VARSPEC	[I,c,o] The variable specification describes the format of the data that is contained in the %variable parameter and lists the names of %variables to be assigned. %VARSPEC specifies the contents of the variable buffer. Specify a character string that follows LIST, DATA, or EDIT syntax. %VARSPEC is a required input parameter if %VARBUF is specified.

Usage notes

Use the IFSKEY call to sort a found set; the record number of the Model 204 record is added to the temporary sort record. On a single cursor IFSTRT thread, the sorted set replaces the IFFIND or IFFAC set and becomes the current set.

The sorted records contain only the keys and the Table B record numbers, so the records are very small. The sorted set acts as an index into Table B. Any reference to the sorted record directly accesses the Table B record.

IFSKEY conserves the amount of CCATEMP space that is used and provides relatively fast sort processing. In comparison to IFSORT, IFSKEY processing is faster and more efficient. See the IFSORT call.

The IFSKEY call is valid on all types of IFSTRT threads. You must specify the found set of records that are to be sorted on a multiple cursor IFSTRT thread. On a single cursor IFSTRT thread, IFSKEY sorts records using the current IFFIND or IFFAC set.

Record enqueuing

IFSKEY does not lock the original Table B records. Another Model 204 user can update them while the sorted records are being processed.

Completion return code (RETCODE)

If the IFSKEY call is unsuccessful, Model 204 returns an error code of 4 for either of the following error conditions:

• General syntax error
• Attempt to sort an already sorted set

Processing sorted records

Once records are sorted, you can issue subsequent retrieval calls, such as IFGET on a single cursor IFSTRT thread or IFFTCH on a multiple cursor thread, to retrieve fields from the sorted records. On a single cursor IFSTRT thread, you can also use the IFMORE call or the IFCTO call after IFSKEY, and you can use IFOCC on a multiple cursor IFSTRT thread.

On either a single cursor or multiple cursor IFSTRT thread, you can use IFPROL or IFRRFL to update a list with records from a sorted set. Because lists are named sets of record numbers that exist as bit patterns, lists that contain records from sorted sets are not maintained in sorted order. However, you can explicitly sort any list.

Restrictions on processing sorted records

You cannot use IFSKEY with a record set that is already sorted. On a single cursor IFSTRT thread, a sorted set cannot be resorted without an intervening call to IFFIND or IFFAC to rebuild the original set.

On a single cursor IFSTRT thread, any call to IFFIND replaces the sorted set and discards any unprocessed sorted records. This means that an HLI program that uses single cursor IFSTRT threads and finds new records within a loop on sorted records must use one thread for the sorted records and another thread for the inner IFFINDs.

You cannot use updating calls, such as IFPUT on a single cursor IFSTRT thread or IFUPDT on a multiple cursor thread, with sorted records. You cannot use IFLIST, IFDSET, and IFFILE to process a sorted set.

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 ARGS-FOR-CALL. 05 RETCODE PIC 9(5) COMP SYNC. 05 SORT-SPEC PIC X(53) VALUE "CUSTOMER NAME AND PRODUCT CODE VALUE DESCENDING;". 05 SKYNAME PIC X(8) VALUE 'SAVSORT;'. . . . PROCEDURE DIVISION. . . . CALL "IFSKEY" USING RETCODE, SORT-SPEC, SKYNAME.

This example operates similarly to the example shown for IFSORT.