IFSORT (HLI function)
The conventions used on this page are described in Function call notation conventions.
Summary
- Description
- The IFSORT call (SORT) sorts the records in a found set in the specified order and creates a record set.
- Thread type
- multiple cursor IFSTRT, single cursor IFSTRT
- IFCALL function number
- 68
Syntax
IFSORT(RETCODE,SORT_SPEC,SORT_NAME,%VARBUF,%VARSPEC)
- Compile-only form
- IFCALL function number: 69
IFSRTC(RETCODE,SORT_SPEC,SORT_NAME)
- Execute-only form
- IFCALL function number: 70
IFSRTE(RETCODE,SORT_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 using the following format line:
[set qualifier] BY key1 [AND key2 ... AND keyn] [VALUE [ASCENDING | DESCENDING]] where: set qualifier is available only for use with a multiple cursor IFSTRT thread and it is required for specifying the record set or list whose records will be sorted. Note: The set qualifier is not a valid parameter for use with a single cursor IFSTRT thread. Specify the set qualifier as a character string using one of the following formats: [IN label | ON [LIST} listname] where:
The BY clause specifies the key, or keys, for ordering records. Each key is the name of a field to be used for ordering the records: key1 is the highest order for the sort, key2 is next highest, and so on; keyn is the lowest sort level. Separate the keys with the keyword AND. ASCENDING and DESCENDING are mutually exclusive keywords that indicate the order in which the record set will be processed. ASCENDING order is the default. Note: The sort specification is required for a record set. To specify default sorted order (ASCENDING) on a multiple cursor IFSTRT thread, specify the IN label or ON listname clause followed by a semicolon (;). On a single cursor IFSTRT thread, specify a semicolon for default ordering. The SORT_SPEC options that are available in an IFSORT call are similar to the sort options available in a SORT statement in SOUL. |
| SORT_NAME | [I,s,r/o] The name of the IFSORT 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 (IFSRTC and IFSRTE). 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 an 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, which 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 IFSORT call to sort a found set of records. The sorted records are temporary copies of the original records. 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. On a multiple cursor IFSTRT thread, the IFFIND or IFFAC set is not replaced and may be accessed again.
IFSORT makes a copy of the original Table B record in CCATEMP and sorts the copies. All references to fields on the sorted records are references to CCATEMP.
Because of the space limitations of CCATEMP and the performance characteristics of Model 204 sort processing, Rocket does not recommend using IFSORT to sort very large numbers of records. The IFSKEY call provides an efficient alternative to IFSORT processing. See the IFSKEY call.
The IFSORT 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, IFSORT sorts records using the current IFFIND or IFFAC set.
Completion return code (RETCODE)
If the IFSORT 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
Record enqueuing
On a single cursor IFSTRT thread, enqueuing on the found set is released when the sort is performed. IFSORT does not lock the original Table B records. Another Model 204 user can update the original records while the sorted records are being processed, but the sorted records are not updated.
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 IFSTRT 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 IFSORT, and you can use IFOCC on a multiple cursor IFSTRT thread.
On either a single cursor or a multiple cursor thread, you can use IFPROL or IFRRFL to update a list with records from a sorted set. Since 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 may explicitly sort any list.
Restrictions on processing sorted records
Note that on a single cursor IFSTRT thread, you cannot use IFSORT 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.
Therefore, a host language 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 IFSTRT thread, with sorted records. You cannot use the 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;". . . . PROCEDURE DIVISION. . . . CALL "IFSORT" USING RETCODE, SORT-SPEC.
This example takes the found record set and generates a sorted set of temporary records. Each element of the sorted set contains a customer name and a product code, and the records are ordered alphabetically by customer name. When there are multiple product codes for a given customer name, the record with the higher product code precedes the one with the lower code.