View source for $ListUpd

{{DISPLAYTITLE:$ListUpd}}
<span class="pageSubtitle">Produce $list from input $list using $list of updates</span>

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

This function uses a first $list to update a second $list, producing a third $list containing data from the second $list as modified by the first $list. 

The <var>$ListUpd</var> function accepts three arguments and returns a numeric result. It is a [[Calling Sirius Mods $functions|callable]] $function. 

The first argument is the identifier of a $list containing data with 8 byte sequence numbers. This is a required argument. 

The second argument is the identifier of a $list containing update control statements and insertion or replacement lines. This is a required argument. 

The third argument is the identifier of the output $list. This is a required argument.

==Syntax==
<p class="syntax">[%RESULT =] $ListUpd(list_id1, list_id2, list_id3)
</p>

<p><var class="term">%result</var> is set either to the number of items in the output $list, or to a negative error code if an error has occurred.</p>

===Error codes===
<p class="code">-3 - No room to create $list items
        (if LISTFC <var>$SirParm</var> parameter not set)
-5 - Required argument not specified
-6 - $List identifier invalid
-8 - Input $list 1 has invalid format
</p>

==Usage notes==
<ul>
<li>The output $list produced by <var>$ListUpd</var> contains sequence numbers just as input $list 1. This makes it possible to use the output $list as input to another <var>$ListUpd</var> call. In this way it is possible to apply multiple updates to a single $list. 

<li>The first input $list to <var>$ListUpd</var> can be most easily created with the <var>$ProcDat</var> function using the fifth parameter to indicate a sequence number. The second input $list to <var>$ListUpd</var> can be most easily created with the <var>$ListCmp</var> function.

<li>The update $list (input $list 2) contains update control statements and insertion or replacement lines. The update $list must begin with an update control statement. All update control statements begin with the './ ' characters followed by a single character indicating the function and possible sequence numbers indicating the lines in input $list to which the updates apply. Any items in input $list 1 not updated by the update $list are simply copied into the output $list. The update control statements are:

<table class="syntaxTable">
<tr><th>./ * comment</th>
<td> This is a comment control statement and is ignored. This statement must be followed by another update control statement or it must be the last item in the update $list.</td></tr>
<tr><th>./ D seq1 { seq2 } { $ }</th>
<td> This is a deletion control statement indicating a range of input lines to be deleted. '''seq1''' and '''seq2''' indicate the range of sequence numbers in the input $list that are to be deleted. If '''seq2''' is not specified, it is assumed to equal '''seq1''', that is only the single line indicated by '''seq1''' will be deleted. This statement must be followed by another update control statement or it must be the last item in the update $list.</td></tr>
<tr><th>./ I seq1 { $ seq2 { seq3 } }</th>
<td> This is an insertion control statement and is followed by lines that are to be inserted in the output $list. '''seq1''' indicates the sequence number in the input $list after which the lines are to be inserted. '''seq2''' is the sequence number to be assigned to the first inserted line and '''seq3''' indicates the increment to be added to the current sequence number for subsequent inserted lines. The lines to be inserted are terminated by another update control statement.</td></tr>
<tr><th>./ R seq1 {seq2} { $ seq3 { seq4 } }</th>
<td> This is a replacement control statement and is followed by lines that are to replace lines from the input $list in the output $list. '''seq1''' and '''seq2''' indicate the range of sequence numbers in the input $list that are to be replaced. If '''seq2''' is not specified, it is assumed to equal '''seq1''', that is, only the single line indicated by '''seq1''' will be replaced. '''seq3''' is the sequence number to be assigned to the first replacement line and '''seq4''' indicates the increment to be added to the current sequence number for subsequent replacement lines. The replacement lines are terminated by another update control statement.</td></tr>
<tr><th>./ S seq1 { seq2 } { $ }</th>
<td> This is an resequence control statement and must be the first non-comment control statement in the update $list. This statement indicates that the output $list, after all subsequent updates have been applied, is to be given sequence numbers starting at '''seq1''' and incremented by '''seq2'''.
</td></tr>
</table>
</ul>

==Products authorizing {{PAGENAMEE}}== 
<ul class="smallAndTightList">
<li>[[SirLib]]
</ul>
 
[[Category:$Functions|$ListUpd]]