AppendFieldValues (Stringlist function)
Add fields names and values to a Stringlist (Stringlist class)
[Introduced in Sirius Mods 7.8]
This callable function retrieves retrieves field values from the current record into Stringlist items.
[%count =] sl:AppendFieldValues[( [NameLength= number], [Fieldname= string], - [Options= string])]
|%count||This numeric variable is the number of values added to Stringlist sl, or it is one of these (negative) status codes:
|sl||A Stringlist object. If empty, data is added to the end of the Stringlist.|
|NameLength||This optional, name required, argument is a string containing the length of the output field name in the output Stringlist items. It can be any numeric value from 0 to 255; the default is 255.|
|Fieldname||An optional, name required, string that is the name of the field to be returned. This argument can contain a single specific field name or it can contain a wildcard string that matches a number of fields in the file. The default is an asterisk (*), which means to return all fields in the record.|
|Options||An optional, name required, string that is a set of blank-delimited processing options. As of Sirius Mods Version 7.1, these options may be specified in any combination of uppercase and lowercase letters (prior to that, all-uppercase letters are required):
Output Stringlist item format
|0-3||A binary sequence number (same as the $list item number when item added).|
|4-4||Binary length of field name (true or truncated depending on TrueLen).|
|5-(5+N-1)||Blank padded or truncated field name, where N is value of the NameLength argument.|
|5+N-(5+N)||Binary length of field value.|
|(5+N+1)-end||Field value in string format as it would be displayed in a PAI.|
- Most field names are typically much shorter than 255 bytes, so a large amount of Stringlist space is wasted if the Fieldname argument is not specified.
- If neither TruncLeft nor TruncRight is specified in the Options string, a truncated Fieldname value causes request cancellation, except when the value's length is 0, in which case TruncLeft, TruncRight, and CanTrunc are meaningless.
- Note that you can (bizarrely) specify TrueLen and NameLength values of 0, which means that while the field name will not be returned, its length will.
- The name specified in the Fieldname argument can be an explicit name, or it can contain the following wildcard characters:
* Matches any number of characters including none ? Matches any single character " Indicates that the next character must be treated literally even if it is a wildcard character.
C*Dmatches "CUSTID", "COD", or "CLOD".
.S??Tmatches "SALT", "SLOT", or "SORT".
- If a non-wildcard Fieldname value is specified, and the field name does not exist in the file, AppendFieldValues simply returns a 0 without scanning the record. If a wildcard Fieldname value is specified and the wildcard string does not match any field names in the file, the record is still scanned. Except in the case of a non-wildcard Fieldname value that does not exist in the file, or a request cancellation because of a truncated field name, or Stringlist or CCATEMP full, the entire record is always scanned.
- AppendFieldValues is not recommended for use with FILEORG X'100' files. For example, AppendFieldValues will not create a Stringlist item for an EXACTLY-ONE field that was not explicitly stored. For FILEORG X'100' files, AppendFieldImages is recommended.
The following code fragment retrieves all fields in a record where the field name begins with the letters "CHILD_" into Stringlist
%sl and sorts the Stringlist
%sl by field name into Stringlist
In File INFILE Frn %recno %rc = %sl:AppendFieldValues('CHILD_*', 20) End For %outlist = %sl:Sortnew('6,20,A')
- AppendFieldImages retrieves fields that are in repeating groups into Stringlist items mapped to a SOUL image.