$ListSort and $ListSrt

From m204wiki
Revision as of 21:13, 8 July 2012 by JAL2 (talk | contribs)
Jump to navigation Jump to search

$ListSort and $ListSrt : Sort $list

Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListSort and $ListSrt function is the Sort (Stringlist 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

<section begin="syntax" /> %RESULT = $ListSort(list_identifier, sort_order) %RESULT = $ListSrt(list_identifier, sort_order) <section end="syntax" />

$ListSort and $ListSrt Functions

%RESULT is the identifier of the created $list or is an error code if the new $list was not created. $List identifiers are always positive integers and error codes are always negative integers.

  • The first argument is the identifier of the input $list. This is a required argument.
  • The second argument is 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 the letterA for ascending or D for descending (see below for note about sorting using an implied CENTSPAN of 1975). The quadruplets are made up of a start column, length, format, and the letterA for ascending or D for descending (see below for note about sorting using an implied CENTSPAN of 1975).
  • th 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 (:hdref refid=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.

-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

$LISTSRT/$LISTSORT Error Codes

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 : .SK

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

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

%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.

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')


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

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$ListSort_and_$ListSrt&oldid=34696"