$ListSort and $ListSrt

$ListSort and $ListSrt : Sort $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListSort and $ListSrt function is the Sort subroutine.

Each of these functions sorts a $list and builds a new $list containing the sorted data from the input $list. The difference between $ListSort and $ListSrt is that, if the input $list is empty, $ListSort returns an empty $list while $ListSrt returns a -11 error code. Because of this, it is generally recommended that $ListSort be used, instead of $ListSrt. The $list can be sorted in ascending or descending EBCDIC order for specified ranges of columns.

The $ListSort and $ListSrt functions accept two arguments and return a numeric result.

Syntax

%result = $ListSort(list_identifier, sort_order) %result = $ListSrt(list_identifier, sort_order)

Syntax terms

%result	The identifier of the created $list, or an error code if the new $list was not created. $List identifiers are always positive integers and error codes are always negative integers.
list_identifier	The identifier of the input $list.
sort_order	A string that specifies the sort order. The sort order is a character string that contains blank separated triplets and/or quadruplets. The triplets are made up of a start column, length, and either the letter A for ascending or D for descending (see the example note below for information about sorting using an implied CENTSPAN of 1975). The quadruplets are made up of a start column, length, format, and either the letter A for ascending or D for descending (see the note below for information about sorting using an implied CENTSPAN of 1975).

Specifying the sort order

A format in the quadruplets can be one of these:

CH	Character format. The default.
FI	Fixed point format. Must have length 1, 2, 3 or 4.
FL	Floating point format. Must have length 4, 8 or 16.
PD	Packed decimal format. Must have length between 1 and 16, inclusive.
ZD	Zoned decimal format. Must have length between 1 and 16, inclusive.

The entities in a triplet or quadruplet must be separated by commas. For example, specifying a sort order of 1,10,A 18,4,FI,D would result in a $list being sorted in ascending order based on columns 1 through 10 and descending order based on a signed fixed point comparison of columns 18 through 21.

For $lists that have been associated with an image via $ListImg, the start column and length in any triplet and the start column, length, and format in any quadruplet can be replaced by the name of an image item in the associated image.

$ListSort and $ListSrt error codes

-3 — No room in CCATEMP -5 — Required argument not specified -6 — $List identifier invalid -10 — Invalid sort order -11 — Input $list is empty ($ListSrt only) -12 — Sort specification is too complex

Usage notes

• All invocations of a particular call to $ListSort or $ListSrt will always return the same $list identifier. Each time a call is executed, if the function is successful then any previous $list created by that call is deleted, and a new list is created. For example:

  REPEAT 4 TIMES %A = $ListSort(%LIST,'1,24,D 39,255,A') END REPEAT

  Would produce only one valid $list. On the other hand, the following

  %A = $ListSort(%LIST,'1,24,D 39,255,A') %A = $ListSort(%LIST,'1,24,D 39,255,A')

  would produce two $lists, though the identifier of the first $list would have been replaced in %A by the identifier of the second $list.

Example

The following is an example of using an image item name in a sort criterion:

IMAGE SURGERY PROCEDURE IS STRING LEN 16 DEPT IS STRING LEN 5 CODE IS STRING LEN 6 COST IS BINARY END IMAGE PREPARE IMAGE SURGERY %LIST = $ListNew %RC = $ListImg(%LIST, %SURGERY:CODE) . . . %OUTLIST = $ListSort(%LIST, 'DEPT,A COST,D')

Example notes:

• If the input $list was created by the invoked $ListSort or $ListSrt function, the input $list is not deleted if you get a -3 error code from LISTSORT or $ListSrt.
• If you are sorting 2-digit year dates, you can use a CENTSPAN of 1975 to sort the dates by appending the letter C to the third item (A or D) in the sort field specification. This could be used, for example, with output of $PRCLEX, based on the assumption that all procedures were created since 1974. However, a better approach is to use $PROC_LIST, which returns 4-digit year dates.
• $ListSrt and $ListSort use any specified image item's format for comparison. For example, if the image item WEIGHT is specified as part of the sort criteria and WEIGHT is defined as a FLOAT type image item, a floating point comparison of the values will be performed. Type specific comparison is done for FLOAT, BINARY, PACKED, and ZONED image items. Generally, the type specific comparisons produce the same results as a character comparison unless the some of the values are negative.
• $LISTSRT's and $LISTSORT's output $list identifiers are associated with the same image as their input $lists (as associated with $ListImg).

Products authorizing $ListSort and $ListSrt

• Sirius Functions
• Fast/Unload User Language Interface
• Janus Open Client
• Janus Open Server
• Janus Sockets
• Janus Web Server
• Japanese functions
• Sir2000 Field Migration Facility