$ListSub

Create $list that is subset of input $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListSub function is Subset.

This function creates a $list that is a subset of an input $list. The subset is created by selecting all entries that contain a specified search string.

The $ListSub function accepts five arguments and returns a numeric result.

The first argument is the identifier of the $list for which a subset is to be built. This is a required argument.

The second argument is the string to be located. This argument is called the search string. If this argument is not specified, all $list items are considered to contain the search string. The subset $list consists of all items in the source list that contain the search string in the specified columns.

The third argument is the starting column number of a range of columns in which the search string must be located or a string containing the name of an image item in the image associated with the $list using $ListImg. In the latter case, the start column for the search is the position of the image item in the image. This is an optional argument and defaults to 1.

The fourth argument is the ending column number of a range of columns in which the search string must be located. This is an optional argument and defaults to one of the following values:

• if the third argument specifies an image item name, the position of the end of the image item in the image
• otherwise, 6124

If the fifth argument is a non-zero integer, then the width of the column range is reduced to a maximum of 256.

The fifth argument is an indicator for case-insensitive comparisons. If this argument is a non-zero integer, the string comparisons use $list item data translated to uppercase (hence your search string should be passed as an uppercase value). This is an optional argument and defaults to zero. If the fifth argument is 1, then the width of the column range is reduced to a maximum of 256.

Syntax

%result = $ListSub(list_id, [search_string], [start_col], - [end_col], [case_ignore])

%result is set either to the identifier of the newly created subset $list, or to a negative number if an error has occurred.

Error codes

-3 - No room in CCATEMP -5 - Required argument not specified -6 - $List identifier invalid -8 - String not found -9 - Invalid column range

Usage notes

• All invocations of a particular call to $ListSub will always return the same $list identifier. Each time that 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 = $ListSub(%LIST,'SUBSET-DATA',20,50) END REPEAT

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

  %A = $ListSub(%LIST,'SUBSET-DATA',20,50) %A = $ListSub(%LIST,'SUBSET-DATA',20,50)

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

  Note that if the input $list was created by the invoked $ListSub function, the input $list is not deleted if you get a -3 or -8 error code from $ListSub.

Example

In the following example, a $list is loaded from the contents of an image and a subset list is created of all items that had been loaded with a specific value in the source image.

IMAGE PART ITEMNO IS STRING LEN 6 NAME IS STRING LEN 30 COST IS BINARY END IMAGE PREPARE IMAGE PART %LIST = $ListNew %RC = $ListImg(%LIST, %PART:NAME) . . . FOR EACH RECORD IN PARTS . . . %RC = $ListAddI(%LIST) . . . END FOR %LIST2 = $ListSub(%LIST, 'LUG NUT', 'NAME')

$ListSub's output $list identifier is associated with the same image as the input $list (as associated with $ListImg).

Products authorizing $ListSub

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