$ListInsI

Insert image into a $list

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

This function inserts data from an image into a $list. Generally, this $list would have been created with the $ListNew function.

The $ListInsI function accepts four arguments and returns a numeric result. It is a callable $function.

The first argument is a $list identifier. This is a required argument.

The second argument is the item number before which the image is to be inserted. If this argument is 1, the image is inserted before the first item in the $list. If this argument equals the number of items in the $list plus one, the image is added after the last $list item and so is identical to a $ListAddI. This is a required argument and must have a value between 1 and the number of items in the $list plus 1, inclusive.

The third argument can either be a string containing the name of an image or any image item from the required image. This is an optional argument if a image has been associated with the $list with a $ListImg function. Otherwise, it is a required argument.

The fourth argument is a number that indicates the length of the inserted $list item. This is an optional argument. Its minimum valid value is 0 and the maximum is 6124 under Sirius Mods Version 6.2 and later and 4096 before. If this value is longer than the length of the image, the image is padded on the right with blanks. If this value is shorter than the length of the image, the image is truncated.

Syntax

[%RESULT =] $ListInsI(list_id, item_num, image_id, length)

%result is set either to the number of items in the indicated $list after the image has been inserted into the $list, or to a negative number if an error has occurred. Note that in the former case, %result is also the item number associated with the added string in the $list.

Error codes

-3 - No room to add item (if LISTFC $SirParm parameter not set) -5 - Required argument not specified -6 - $List identifier invalid -7 - Invalid length specified -8 - Image not active or not found -9 - Invalid item number

Usage notes

• One application of $ListInsI is to create a large sorted array, although this can also be achieved (usually more efficiently) with $ListSrt. The following example demonstrates how such a mechanism might be used, with the $list items in order by SSN:

  IMAGE CUST SSN IS STRING LEN 10 NAME IS STRING LEN 20 BDATE IS STRING LEN 8 END IMAGE FIND1: FIND ALL RECORDS FOR WHICH NAME = SMITH END FIND FOR EACH RECORD IN FIND1 %CUST:SSN = SSN %CUST:NAME = NAME %CUST:BDATE = BDATE FOR %I FROM 1 TO $ListCnt(%LIST) IF %CUST:SSN LT $ListInf(%LIST, %I, 1, 10) THEN LOOP END END IF END FOR %COUNT = $ListInsI(%LIST, %I, 'CUST') END FOR

  The above example can be made more efficient by coding the $ListInsI as follows:

  %COUNT = $ListInsI(%LIST, %I, %CUST:NAME)

  The specific image item is irrelevant in this call but is more efficient than specifying the image name in quotes because in the first example, the image name must be hashed and looked up (in NTBL) in each invocation of $ListInsI while in the second example, the hashing of the image name and lookup happens only once; at compile time.

  Here is an even neater and equally efficient way of coding this:

  %RC = $ListImg(%LIST, %CUST:BDATE) FOR EACH RECORD IN FIND1 . . . %COUNT = $ListInsI(%LIST, %I) END FOR

  In this last example, $ListImg associates the image with the $list, eliminating the need to specify the image name on the $ListInsI. This association is also useful in many other function calls in that it provides a structure to be associated with the $list that is useful for column oriented functions such as $ListFindI and $ListSrt.

• A $ListInsI can result in the splitting of a $list leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent $ListRems make this possible. Because of this, heavy use of $ListIns and $ListRem can result in "sparse&CQ. $lists, which places an unnecessary burden on the buffer pool and CCATEMP. It can also result in not being able to add an item to the end of the $list (via $ListAdd) because of a full pointer page, even though the $list is nowhere near the theoretical capacity for a $list. To make matters worse, $ListCpy does a page-for-page copy of a $list, so it results in no compression of the resultant $list. $List compression can be done using the $List_Copy_Items function.

Products authorizing $ListInsI

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