$ListIns

Insert string into a $list

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

This function inserts arbitrary string data to a $list. Generally, this $list would have been created with the $ListNew function.

The $ListIns 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 string is to be inserted. If this argument is equal to the number of items in the $list plus one, the string is added to the end of the $list and so is, in this case, identical to a $ListAdd. Because the string is inserted before the indicated item number, this item number is also the item number of the new $list item after $ListIns returns. This is a required argument.

The third argument is a string that is to be inserted into the $list. This is a required argument.

The fourth argument is a number that indicates the length of the new $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 third argument, the third argument is padded on the right with blanks. If this value is shorter than the length of the third argument, the third argument is truncated.

Syntax

[%RESULT =] $ListIns(list_identifier, item_num, - string, length)

%result is set either to the number of items in the indicated $list after the string has been inserted into the $list, or to a negative number if an error has occurred.

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 -9 - Invalid item number

Usage notes

• $ListAdd, $ListIns and $ListNew allow a User Language programmer to create arrays in CCATEMP. The following example demonstrates how such a mechanism might be used.

  %I = 1 REPEAT FOREVER IF %I GT $ListCnt(%LIST) THEN LOOP END END IF %SSN = $ListInf(%LIST, %I, 1, 9) F1: IN FILE CHILDREN FD PARENT = %SSN END FIND %I = %I + 1 FOR EACH RECORD IN F1 %STRING = SSN WITH 'C' WITH NAME WITH ' ' WITH AGE %COUNT = $ListIns(%LIST, %STRING, %I) %I = %I + 1 END FOR END REPEAT

• The length (fourth) argument makes it possible to create $list items that are longer than 255 bytes. This can be most easily accomplished in conjuction with the $ListOvl function. In the following example, several field values are placed into a $LIST item with a length of 512.

  FIND1: FIND ALL RECORDS FOR WHICH NAME = SONDHEIM END FIND FOR EACH RECORD IN FIND1 %RC = $ListIns(%LIST, %NUM, SSN, 512) %RC = $ListOvl(%LIST, %NUM, 10, LNAM) %RC = $ListOvl(%LIST, %NUM, 50, FNAM) %RC = $ListOvl(%LIST, %NUM, 90, MNAM) %RC = $ListOvl(%LIST, %NUM, 110, ADD1) %RC = $ListOvl(%LIST, %NUM, 170, ADD2) %RC = $ListOvl(%LIST, %NUM, 230, ADD3) %RC = $ListOvl(%LIST, %NUM, 290, CITY) %RC = $ListOvl(%LIST, %NUM, 310, ST) END FOR

• A $ListIns 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 makes this possible. Because of this, heavy use of $ListIns and $ListRem can result in "sparse&CQ. $lists which place an unnecessary burden on the buffer pool and CCATEMP. It can also result in an inability 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 does not result in any compression of the resultant $list. $List compression can be done using the $List_Copy_Items function.

Products authorizing $ListIns

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