$ListAdd: Difference between revisions
m (1 revision) |
(Automatically generated page update) |
||
| (44 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=" | <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 | 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 12: | Line 12: | ||
The second argument is a string that is to be added to the $list. 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 | 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 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== | ==Syntax== | ||
<p class="syntax" | <p class="syntax">[%RESULT =] $ListAdd(list_identifier, string, length) | ||
</p> | </p> | ||
<p class=" | |||
<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> | ||
===Error Codes=== | |||
<p class="code"> -3 - No room to add item | |||
(if LISTFC <var>$SirParm</var> parameter not set) | |||
-5 - Required argument not specified | |||
-6 - $List identifier invalid | |||
-7 - Invalid length specified | |||
</p> | </p> | ||
$ListAdd and $ListNew allow a User Language 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 | |||
END FIND | |||
%LIST = $ListNew | |||
FOR EACH RECORD IN FIND1 | |||
%STRING = NAME WITH ' ' WITH SSN WITH ' ' WITH AGE | |||
%COUNT = $ListAdd(%LIST, %STRING) | |||
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 | |||
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 | |||
</p> | </p> | ||
==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> | <li>Japanese functions</li> | ||
<li>[[Sir2000 Field Migration Facility]]</li> | <li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li> | ||
</ul> | </ul> | ||
[[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