IFSRTV (HLI function)

From m204wiki
Revision as of 22:59, 11 July 2016 by ELowell (talk | contribs)
Jump to navigation Jump to search

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

Summary

Description
The IFSRTV call (SORT VALUES) sorts the values in a found set in the specified order and creates a sorted value set.
Thread type
multiple cursor IFSTRT, single cursor IFSTRT
IFCALL function number
80

Syntax

IFSRTV(RETCODE,SORT_SPEC,SRTV_NAME)

Compile-only form
IFCALL function number: 81

IFSTVC(RETCODE,SORT_SPEC,SRTV_NAME)

Execute-only form
IFCALL function number: 82

IFSTVE(RETCODE,SRTV_NAME)

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 and is valid for an unsorted or a sorted value set. To indicate default ordering for the value set, specify a semicolon (;). Specify the ordering clause using the following format line with an IN ORDER clause:

[set qualifier] [IN [ASCENDING | DESCENDING] [NUMERICAL | CHARACTER | RIGHT-ADJUSTED] ORDER]

where:

set qualifier is available only for use with a multiple cursor IFSTRT thread and it is required for specifying the value set whose values 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 the IN label clause, where label is the name of a saved IFFDV or IFSRTV compilation from a previously compiled call that established the value set.

ASCENDING and DESCENDING are mutually exclusive keywords that indicate the order in which the value set is processed. ASCENDING order is the default.

CHARACTER, RIGHT-ADJUSTED and NUMERIC are mutually exclusive keywords.

  • CHARACTER specifies values sorted in standard EBCDIC collating sequence.
  • RIGHT-ADJUSTED specifies that values are temporarily right-justified before s
  • NUMERICAL specifies a sort of number values with the usual numeric order relationships.

Note: The sort specification is required for a value set. To specify default sorted order (ASCENDING) on a multiple cursor IFSTRT thread, specify the IN label clause followed by a semicolon (;). On a single cursor IFSTRT thread, specify a semicolon for default ordering.

See Sorting for more information.

SRTV_NAME [I,s,r/o] The name of the IFSRTV 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 (IFSTVC and IFSTVE). 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 may 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.

Usage notes

Use the IFSRTV call to sort a value set. On a single cursor IFSTRT thread, the sorted set replaces the IFFDV or IFSRTV set and becomes the current set. On a multiple cursor IFSTRT thread, the IFFDV or IFSRTV set is not replaced and may be accessed again.

You can issue more than one IFSRTV call and you can sort a value set that is already sorted. Note that if you issue IFSRTV after some values have been extracted using IFGETV on a single cursor IFSTRT thread, Model 204 sorts the values that are remaining in the set.

The IFSRTV call is valid on all types of IFSTRT threads. You must specify the found value set that is to be sorted on a multiple cursor IFSTRT thread. On a single cursor IFSTRT thread, IFSRTV sorts values using the current IFFDV or IFSRTV set.

If the value set does not exist, Model 204 does not perform the sort and returns an error completion code.

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 ARGS-FOR-CALL. 05 RETCODE PIC 9(5) COMP SYNC. 05 SORT-SPEC PIC X(26) VALUE "IN FDV IN ASCENDING ORDER;". 05 NAME PIC X(8) VALUE "SAVEVAL;". . . . PROCEDURE DIVISION. . . . CALL "IFSRTV" USING RETCODE, SORT-SPEC.