$ListAddI: 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">Add image as new $list item</span>
<span class="pageSubtitle">Add image as new $list item</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListAddI function is the [[AddImage (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 $ListAddI function is <var>[[AddImage (Stringlist function)|AddImage]]</var>.</p>


This function copies data from an image to a $list. Generally, this $list would have been created with the [[$ListNew]] function.  
This function copies data from an image to a $list. Generally, this $list would have been created with the [[$ListNew]] function.  


The $ListAddI function accepts three arguments and returns a numeric result. It is a callable $function (see [[Calling Sirius Mods $functions]]).  
The <var>$ListAddI</var> function accepts three 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.  


The second 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 an image has been associated with the $list with a $ListImg (:hdref refid=listimg.) function. Otherwise, it is a required argument.  
The second 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 an image has been associated with the $list with a <var>[[$ListImg]]</var> function. Otherwise, it is a required argument.  


The third 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 <var class="product">[[Sirius Mods]]</var> Version 6.2 and later, and 4096 in Versions before 6.2. 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 third 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 <var class="product">[[Sirius Mods]]</var> Version 6.2 and later, and 4096 in Versions before 6.2. 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 =] $ListAddI(list_identifier, image_id, length)
<p class="syntax">[%RESULT =] $ListAddI(list_identifier, image_id, length)
<section end="syntax" /></p>
<p class="caption">$ListAddI Function
</p>
</p>
<p class="caption">%RESULT is set either to the number of items in the indicated $list after the string has been added to 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 string has been added to 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
</p>
-7 - Invalid length specified
<p class="caption">$ListAddI Error Codes
-8 - Image not active or not found
</p>
</p>


==Usage notes==
<ul>
<li><var>$ListAddI</var> and <var>$ListNew</var> allow a <var class="product">User Language</var> programmer to create arrays in CCATEMP. The following example demonstrates how such a mechanism might be used:


$ListAddI 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">IMAGE CUST
 
NAME IS STRING LEN 20
<p class="code">  
SSN IS STRING LEN 10
IMAGE CUST
BDATE IS STRING LEN 8
NAME IS STRING LEN 20
END IMAGE
SSN IS STRING LEN 10
BDATE IS STRING LEN 8
END IMAGE
   
   
FIND1: FIND ALL RECORDS FOR WHICH
FIND1: FIND ALL RECORDS FOR WHICH
        NAME = SMITH
        NAME = SMITH
END FIND
END FIND
   
   
%LIST = $ListNew
%LIST = $ListNew
   
   
FOR EACH RECORD IN FIND1
FOR EACH RECORD IN FIND1
    %CUST:NAME = NAME
  %CUST:NAME = NAME
    %CUST:SSN = SSN
  %CUST:SSN = SSN
    %CUST:BDATE = BDATE
  %CUST:BDATE = BDATE
    %COUNT = $ListAddI(%LIST, 'CUST')
  %COUNT = $ListAddI(%LIST, 'CUST')
END FOR
END FOR
</p>
</p>


 
The above example can be made more efficient by coding the <var>$ListAddI</var> as follows:
The above example can be made more efficient by coding the $ListAddI as follows.
<p class="code">%COUNT = $ListAddI(%LIST, %CUST:NAME)
<p class="code"> %COUNT = $ListAddI(%LIST, %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 $LISTADDI, 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 $LISTADDI, while in the second example, the hashing of the image name and lookup happens only once: at compile time.  
Line 64: Line 60:
Here is an even neater and equally efficient way of coding this:
Here is an even neater and equally efficient way of coding this:


<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
  %CUST:NAME = NAME
    %CUST:NAME = NAME
  %CUST:SSN = SSN
    %CUST:SSN = SSN
  %CUST:BDATE = BDATE
    %CUST:BDATE = BDATE
  %COUNT = $ListAddI(%LIST)
    %COUNT = $ListAddI(%LIST)
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 $ListAddI. This association is also useful in many other function calls, because it provides a structure to be associated with the $list that is useful for column-oriented functions such as $ListLoc and $ListSrt.<p>
In this last example, <var>$ListImg</var> associates the image with the $list, eliminating the need to specify the image name on the <var>$ListAddI</var>. This association is also useful in many other function calls, because it provides a structure to be associated with the $list that is useful for column-oriented functions such as <var>$ListLoc</var> and <var>$ListSrt</var>.
</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 $ListAddI
</p>
[[Category:$Functions|$ListAddI]]
[[Category:$Functions|$ListAddI]]

Latest revision as of 22:51, 20 September 2018

Add image as new $list item

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

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

The $ListAddI function accepts three 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 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 an image has been associated with the $list with a $ListImg function. Otherwise, it is a required argument.

The third 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 in Versions before 6.2. 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 =] $ListAddI(list_identifier, image_id, length)

%result is set either to the number of items in the indicated $list after the string has been added to 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

Usage notes

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

    IMAGE CUST NAME IS STRING LEN 20 SSN IS STRING LEN 10 BDATE IS STRING LEN 8 END IMAGE FIND1: FIND ALL RECORDS FOR WHICH NAME = SMITH END FIND %LIST = $ListNew FOR EACH RECORD IN FIND1 %CUST:NAME = NAME %CUST:SSN = SSN %CUST:BDATE = BDATE %COUNT = $ListAddI(%LIST, 'CUST') END FOR

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

    %COUNT = $ListAddI(%LIST, %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 $LISTADDI, 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 %CUST:NAME = NAME %CUST:SSN = SSN %CUST:BDATE = BDATE %COUNT = $ListAddI(%LIST) END FOR

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

Products authorizing $ListAddI

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