Update (Stringlist function)

Produce Stringlist from input Stringlist using Stringlist of updates (Stringlist class)

This method uses an input Stringlist to update the method Stringlist, producing an output Stringlist that contains data from the method Stringlist as modified by the first argument Stringlist. The Update method accepts two arguments and returns a Stringlist. The method Stringlist must contain items with 8-byte sequence numbers.

Syntax

%outList = sl:Update( updList, [%status])

Syntax terms

%outlist	The output Stringlist.
sl	A Stringlist object that must contain items with 8-byte sequence numbers.
updlist	A Stringlist that contains update control statements and insertion or replacement lines.
status	A numeric variable that is set to 0 if the method is successful, or it is set to the item number of the invalid update command if updlist contains an invalid item. This is an optional output argument.

Usage notes

• All errors in Update other than an invalid update item cause request cancellation.
• The output Stringlist produced by Update contains sequence numbers just as the input Stringlist in the first argument. This makes it possible to use the output Stringlist as input to another Update call. In this way it is possible to apply multiple updates to a single Stringlist.
• The method Stringlist for Update can be most easily created with the AppendOpenProcedure method (:hdref reftxt=AppendOpenProcedure refid=appopen.) using its fourth parameter to indicate a sequence number. The input argument Stringlist to Update can be most easily created with the Compare method (:hdref reftxt=Compare refid=slcomp.).
• The update Stringlist contains update control statements and insertion or replacement lines. The update Stringlist must begin with an update control statement. All update control statements begin with the period-slash character sequence (./); this is followed by a single character indicating the function, and then possibly by sequence numbers indicating the lines in the input Stringlist to which the updates apply. Any items in the method Stringlist that are not updated by the update Stringlist are simply copied into the output Stringlist. The update control statements are:

  ./ * comment

  This is a comment control statement and it is ignored. It must be followed by another update control statement, or it must be the last item in the update Stringlist.

  ./ D seq1 { seq2 } { $ }

  This is a deletion control statement that indicates a range of input lines to be deleted. seq1 and seq2 indicate the range of sequence numbers in the method Stringlist that are to be deleted. If seq2 is not specified, it is assumed to equal seq1, so 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 Stringlist.

  ./ I seq1 { $ seq2 { seq3 } }

  This is an insertion control statement, and it is followed by lines that are to be inserted in the output Stringlist. seq1 indicates the sequence number in the method Stringlist 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.

  ./ R seq1 {seq2} { $ seq3 { seq4 } }

  This is a replacement control statement, and it is followed by lines that are to replace lines from the method Stringlist in the output Stringlist. seq1 and seq2 indicate the range of sequence numbers in the input Stringlist that are to be replaced. If seq2 is not specified, it is assumed to equal seq1, so 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.

  ./ S seq1 { seq2 } { $ }

  This is a resequence control statement, and it must be the first non-comment control statement in the update Stringlist. This statement indicates that the output Stringlist, after all subsequent updates have been applied, is to be given sequence numbers starting at seq1 and incremented by seq2.