$ListIns: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
Line 2: Line 2:
<span class="pageSubtitle"><section begin="desc" />Insert string into a $list<section end="desc" /></span>
<span class="pageSubtitle"><section begin="desc" />Insert string into a $list<section end="desc" /></span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListIns function is [[to be entered]].</p>
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListIns function is the [[Insert (Stringlist function)]].</p>


This function inserts arbitrary string data to a $list. Generally, this $list would have been created with the $ListNew function.  
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 (:hdref refid=callfun.).  
The $ListIns function accepts four arguments and returns a numeric result. It is a callable $function (see [[Calling Sirius Mods $functions]]).  


The first argument is a $list identifier. This is a required argument.  
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 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 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.
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==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RESULT =] $ListIns(list_identifier, item_num, -
<p class="syntax"><section begin="syntax" /> [%RESULT =] $ListIns(list_identifier, item_num, -
Line 22: Line 23:
</p>
</p>
<p class="caption">%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.</p>
<p class="caption">%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.</p>
<p class="code">  
<p class="code">  
  -3 - No room to add item
  -3 - No room to add item
(if LISTFC $SirParm parameter not set)
        (if LISTFC $SirParm parameter not set)
  -5 - Required argument not specified
  -5 - Required argument not specified
  -6 - $List identifier invalid
  -6 - $List identifier invalid
Line 33: Line 35:
</p>
</p>


[[$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.


$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.
<p class="code"> %I = 1
<p class="code"> %I = 1
  REPEAT FOREVER
  REPEAT FOREVER
IF %I GT $ListCnt(%LIST) THEN
    IF %I GT $ListCnt(%LIST) THEN
LOOP END
      LOOP END
END IF
    END IF
%SSN = $ListInf(%LIST, %I, 1, 9)
    %SSN = $ListInf(%LIST, %I, 1, 9)
F1: IN FILE CHILDREN FD
    F1: IN FILE CHILDREN FD
PARENT = %SSN
      PARENT = %SSN
END FIND
    END FIND
   
   
%I = %I + 1
    %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
   
   
    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
  END REPEAT
</p>
</p>


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.


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.
<p class="code"> FIND1: FIND ALL RECORDS FOR WHICH
<p class="code"> FIND1: FIND ALL RECORDS FOR WHICH
  NAME = SONDHEIM
  NAME = SONDHEIM
Line 63: Line 64:
   
   
  FOR EACH RECORD IN FIND1
  FOR EACH RECORD IN FIND1
%RC = $ListIns(%LIST, %NUM, SSN, 512)
    %RC = $ListIns(%LIST, %NUM, SSN, 512)
%RC = $ListOvl(%LIST, %NUM, 10, LNAM)
    %RC = $ListOvl(%LIST, %NUM, 10, LNAM)
%RC = $ListOvl(%LIST, %NUM, 50, FNAM)
    %RC = $ListOvl(%LIST, %NUM, 50, FNAM)
%RC = $ListOvl(%LIST, %NUM, 90, MNAM)
    %RC = $ListOvl(%LIST, %NUM, 90, MNAM)
%RC = $ListOvl(%LIST, %NUM, 110, ADD1)
    %RC = $ListOvl(%LIST, %NUM, 110, ADD1)
%RC = $ListOvl(%LIST, %NUM, 170, ADD2)
    %RC = $ListOvl(%LIST, %NUM, 170, ADD2)
%RC = $ListOvl(%LIST, %NUM, 230, ADD3)
    %RC = $ListOvl(%LIST, %NUM, 230, ADD3)
%RC = $ListOvl(%LIST, %NUM, 290, CITY)
    %RC = $ListOvl(%LIST, %NUM, 290, CITY)
%RC = $ListOvl(%LIST, %NUM, 310, ST)
    %RC = $ListOvl(%LIST, %NUM, 310, ST)
  END FOR
  END FOR
</p>
</p>


 
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 [[$ListRem]]s 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.<p>
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, documented in :hdref refid=listcit..<p>


<ul class="smallAndTightList">
<ul class="smallAndTightList">
Line 87: Line 87:
<li>[[Japanese functions]]</li>
<li>[[Japanese functions]]</li>
<li>[[Sir2000 Field Migration Facility]]</li>
<li>[[Sir2000 Field Migration Facility]]</li>
</ul>
</ul>
   
   
Line 93: Line 92:
<p class="caption">Products authorizing $ListIns
<p class="caption">Products authorizing $ListIns
</p>
</p>


[[Category:$Functions|$ListIns]]
[[Category:$Functions|$ListIns]]

Revision as of 15:08, 10 February 2011

<section begin="desc" />Insert string into a $list<section end="desc" />

Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListIns function is the Insert (Stringlist function).

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 (see Calling Sirius Mods $functions).

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

<section begin="syntax" /> [%RESULT =] $ListIns(list_identifier, item_num, - string, length) <section end="syntax" />

$ListIns Function

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

-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

$ListIns Error Codes

$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

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$ListIns&oldid=34078"