$ListAdd: 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" />Add string as new $list item<section end="desc" /></span>
<span class="pageSubtitle"><section begin="desc" />Add string as new $list item<section end="desc" /></span>


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


The $ListAdd function accepts three arguments and returns a numeric result. It is a callable $function (:hdref refid=callfun.).  
The $ListAdd function accepts three 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.  
Line 21: Line 21:
<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 31: Line 31:


$ListAdd and $ListNew allow a User Language programmer to create arrays in CCATEMP. The following example demonstrates how such a mechanism might be used.
$ListAdd 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"> FIND1: FIND ALL RECORDS FOR WHICH
<p class="code"> FIND1: FIND ALL RECORDS FOR WHICH
  NAME = SMITH
  NAME = SMITH
Line 38: Line 39:
   
   
  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.


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.
<p class="code"> FIND1: FIND ALL RECORDS FOR WHICH
<p class="code"> FIND1: FIND ALL RECORDS FOR WHICH
  NAME = SIMPSON
  NAME = SIMPSON
Line 52: Line 53:
   
   
  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>
Line 82: Line 83:
<p class="caption">Products authorizing $ListAdd
<p class="caption">Products authorizing $ListAdd
</p>
</p>


[[Category:$Functions|$ListAdd]]
[[Category:$Functions|$ListAdd]]

Revision as of 13:06, 9 February 2011

<section begin="desc" />Add string as new $list item<section end="desc" />

Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListAdd function is Add (Stringlist 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 (see Calling Sirius Mods $functions).

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

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

$ListAdd Function

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

-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

$ListAdd Error Codes


$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