$ListAdd: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(38 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Add string as new $list item</span>
<span class="pageSubtitle">Add string 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 $ListAdd function is [[Add (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 $ListAdd function is the <var>[[Add (Stringlist function)|Add]]</var> function.</p>


This function adds arbitrary string data to a $list. Generally, this $list would have been created with the $ListNew function.  
This function adds arbitrary string data to a $list. Generally, this $list would have been created with the <var>$ListNew</var> function.  


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


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RESULT =] $ListAdd(list_identifier, string, length)
<p class="syntax">[%RESULT =] $ListAdd(list_identifier, string, length)
<section end="syntax" /></p>
<p class="caption">$ListAdd 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 <var>$SirParm</var> 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
</p>
-6 - $List identifier invalid
<p class="caption">$ListAdd Error Codes
-7 - Invalid length specified
</p>
</p>




<var>$ListAdd</var> and $ListNew 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.
==Usage notes==
<ul>
<li><var>$ListAdd</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:


<p class="code"> FIND1: FIND ALL RECORDS FOR WHICH
<p class="code">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
    %STRING = NAME WITH ' ' WITH SSN WITH ' ' WITH AGE
  %STRING = NAME WITH ' ' WITH SSN WITH ' ' WITH AGE
    %COUNT = $ListAdd(%LIST, %STRING)
  %COUNT = $ListAdd(%LIST, %STRING)
END FOR
END FOR
</p>
</p>


The length (third) 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.
<li>The length (third) argument makes it possible to create $list items that are longer than 255 bytes. This can be most easily accomplished in conjuction with the <var>$ListOvl</var> 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 = SIMPSON
NAME = SIMPSON
END FIND
END FIND
   
   
%LIST = $ListNew
%LIST = $ListNew
   
   
FOR EACH RECORD IN FIND1
FOR EACH RECORD IN FIND1
    %NUM = $ListAdd(%LIST, SSN, 512)
  %NUM = $ListAdd(%LIST, 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)
    %RC = $ListOvl(%LIST, %NUM, 312, COMMENT1)
  %RC = $ListOvl(%LIST, %NUM, 312, COMMENT1)
    %RC = $ListOvl(%LIST, %NUM, 412, COMMENT2)
  %RC = $ListOvl(%LIST, %NUM, 412, COMMENT2)
END FOR
END FOR
</p>
</p>
<p class="code">


==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 $ListAdd
</p>
[[Category:$Functions|$ListAdd]]
[[Category:$Functions|$ListAdd]]

Latest revision as of 22:51, 20 September 2018

Add string as new $list item

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

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

The $ListAdd 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 is a string that is to be added to the $list. This 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 before. If this value is longer than the length of the second argument, the second argument is padded on the right with blanks. If this value is shorter than the length of the second argument, the second argument is truncated.

Syntax

[%RESULT =] $ListAdd(list_identifier, string, 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


Usage notes

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

    FIND1: FIND ALL RECORDS FOR WHICH NAME = SMITH END FIND %LIST = $ListNew FOR EACH RECORD IN FIND1 %STRING = NAME WITH ' ' WITH SSN WITH ' ' WITH AGE %COUNT = $ListAdd(%LIST, %STRING) END FOR

  • The length (third) 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 = SIMPSON END FIND %LIST = $ListNew FOR EACH RECORD IN FIND1 %NUM = $ListAdd(%LIST, 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) %RC = $ListOvl(%LIST, %NUM, 312, COMMENT1) %RC = $ListOvl(%LIST, %NUM, 412, COMMENT2) END FOR

    Products authorizing $ListAdd