$ListInsI: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(46 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Insert image into a $list</span>
<span class="pageSubtitle">Insert image into a $list</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListInsI function is the [[InsertImage (Stringlist function)]].</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListInsI function is <var>[[InsertImage (Stringlist function)|InsertImage]]</var>.</p>


This function inserts data from an image into a $list. Generally, this $list would have been created with the [[$ListNew]] function.  
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 (see [[Calling Sirius Mods $functions]]).  
The <var>$ListInsI</var> function accepts four arguments and returns a numeric result. It is a [[Calling Sirius Mods $functions|callable]] $function.  


The first argument is a $list identifier. This is a required argument.  
The first argument is a $list identifier. This is a required argument.  
Line 14: Line 14:
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 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.
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 <var class="product">[[Sirius Mods]]</var> 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==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RESULT =] $ListInsI(list_id, item_num, image_id, length)
<p class="syntax">[%RESULT =] $ListInsI(list_id, item_num, image_id, length)
<section end="syntax" /></p>
<p class="caption">$ListInsI Function
</p>
</p>
<p class="caption">%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.</p>


<p class="code">  
<p><var class="term">%result</var> 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.</p>
-3 - No room to add item
 
          (if LISTFC $SirParm parameter not set)
===Error codes===
-5 - Required argument not specified
<p class="code">-3 - No room to add item
-6 - $List identifier invalid
        (if LISTFC <var>$SirParm</var> parameter not set)
-7 - Invalid length specified
-5 - Required argument not specified
-8 - Image not active or not found
-6 - $List identifier invalid
-9 - Invalid item number
-7 - Invalid length specified
</p>
-8 - Image not active or not found
<p class="caption">$ListInsI Error Codes
-9 - Invalid item number
</p>
</p>


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:
==Usage notes==
<ul>
<li>One application of <var>$ListInsI</var> is to create a large sorted array, although this can also be achieved (usually more efficiently) with <var>$ListSrt</var>. The following example demonstrates how such a mechanism might be used, with the $list items in order by SSN:


<p class="code">  
<p class="code">IMAGE CUST
IMAGE CUST
  SSN IS STRING LEN 10
    SSN IS STRING LEN 10
  NAME IS STRING LEN 20
    NAME IS STRING LEN 20
  BDATE IS STRING LEN 8
    BDATE IS STRING LEN 8
END IMAGE
END IMAGE
   
   
FIND1:
FIND1:
FIND ALL RECORDS FOR WHICH
FIND ALL RECORDS FOR WHICH
NAME = SMITH
NAME = SMITH
END FIND
END FIND
   
   
FOR EACH RECORD IN FIND1
FOR EACH RECORD IN FIND1
    %CUST:SSN = SSN
  %CUST:SSN = SSN
    %CUST:NAME = NAME
  %CUST:NAME = NAME
    %CUST:BDATE = BDATE
  %CUST:BDATE = BDATE
    FOR %I FROM 1 TO $ListCnt(%LIST)
  FOR %I FROM 1 TO $ListCnt(%LIST)
      IF %CUST:SSN LT $ListInf(%LIST, %I, 1, 10) THEN
      IF %CUST:SSN LT $ListInf(%LIST, %I, 1, 10) THEN
          LOOP END
        LOOP END
      END IF
      END IF
    END FOR
  END FOR
    %COUNT = $ListInsI(%LIST, %I, 'CUST')
  %COUNT = $ListInsI(%LIST, %I, 'CUST')
END FOR
END FOR
</p>
</p>
<p>
The above example can be made more efficient by coding the <var>$ListInsI</var> as follows:</p>


The above example can be made more efficient by coding the $ListInsI as follows.
<p class="code">%COUNT = $ListInsI(%LIST, %I, %CUST:NAME)
 
<p class="code"> %COUNT = $ListInsI(%LIST, %I, %CUST:NAME)
</p>
</p>


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.  
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 <var>$ListInsI</var> while in the second example, the hashing of the image name and lookup happens only once; at compile time.  
 
<p>
An even neater and equally efficient way of coding this would be
Here is an even neater and equally efficient way of coding this:</p>


<p class="code">  
<p class="code">%RC = $ListImg(%LIST, %CUST:BDATE)
%RC = $ListImg(%LIST, %CUST:BDATE)
FOR EACH RECORD IN FIND1
FOR EACH RECORD IN FIND1
  . . .  
  . . . . . .
%COUNT = $ListInsI(%LIST, %I)
%COUNT = $ListInsI(%LIST, %I)
END FOR
END FOR
</p>
</p>


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]].  
In this last example, [[$ListImg]] associates the image with the $list, eliminating the need to specify the image name on the <var>$ListInsI</var>. 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 $ListFindI_Up|$ListFindI]] and [[$ListSort and $ListSrt|$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 [[$ListRem]]s make this possible. Because of this, heavy use of $ListIns and $ListRem can result in "sparse&amp;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.<p>
<li>A <var>$ListInsI</var> 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 make this possible. Because of this, heavy use of <var>$ListIns</var> and <var>$ListRem</var> can result in "sparse&amp;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.
</ul>


==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[List of $functions|Sirius functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Janus Open Client]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Janus Open Server]]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Japanese functions]]</li>
<li>Japanese functions</li>
<li>[[Sir2000 Field Migration Facility]]</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
</ul>
</ul>
</p>
 
<p class="caption">Products authorizing $ListInsI
</p>


[[Category:$Functions|$ListInsI]]
[[Category:$Functions|$ListInsI]]

Latest revision as of 22:51, 20 September 2018

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