$Field_List
Return field values into a $list
Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $Field_List is the Stringlist AppendFieldValues function.
This function retrieves field values from the current record into a $list. It provides an alternative to PAI INTO.
$Field_List accepts four arguments and returns a number indicating the success of the function.
Syntax
<section begin="syntax" />%rc = $Field_List(olist, [fieldname_len], [fieldname], [options]) <section end="syntax" />
Syntax terms
| %rc | A number of items added to olist, or it is or it is one of these (negative) status codes:
| ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| olist | The output $list identifier. If the output $list is not empty data is added to the end of the output $list. This is a required argument. | ||||||||||
| fieldname_len | The length of the output fieldname in the output $list items and can be any numeric value from 0 to 255. This is an optional argument and defaults to 255. | ||||||||||
| fieldname | The name of the field to be returned. This argument can contain a single specific fieldname or it can contain a wildcard string that matches a number of fields in the file. This is an optional argument and defaults to asterisk (*), which means to return all fields in the record. | ||||||||||
| options | A set of blank-delimited processing options that, starting with Sirius Mods Version 7.1, can be specified in any combination of uppercase and lowercase letters (prior to that, all-uppercase letters are required):
|
Output $list format
| Offset | Contents |
|---|---|
| 0-3 | A binary sequence number (same as the $list item number when item added). |
| 4-4 | Binary length of fieldname (true or truncated depending on TrueLen). |
| 5-5+N-1 | Blank padded or truncated field name where N is value of argument 2. |
| 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. |
Usage notes
- Most fieldnames are typically much shorter than 255 bytes so a large amount of $list space is wasted if the fieldname argument is not specified.
- If neither TruncLeft nor TruncRight is specified as an option, a truncated fieldname causes request cancellation, except when the fieldname length is 0, in which case TruncLeft, TruncRight, and CanTrunc are meaningless.
- Note that you can (bizarrely) specify TrueLen and fieldname_len of 0, which means that while the fieldname 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. For example,
C*Dmatches "CUSTID", "COD", or "CLOD"..S??Tmatches "SALT", "SLOT", or "SORT"..E"*CONCRETEmatches "E*CONCRETE".
- If a non-wildcard fieldname is specified for the fieldname argument and the fieldname does not exist in the file, $Field_List simply returns a 0 without scanning the record. If a wildcard fieldname is specified for fieldname and the wildcard string does not match any fieldnames in the file, the record is still scanned. Except in the case of a non-wildcard fieldname that does not exist in the file or a request cancellation because of a truncated fieldname, or $list or CCATEMP full, the entire record is always scanned.
Examples
The following code fragment retrieves all fields in a record where the fieldname begins with the letters "CHILD_" into a $list and sorts the $list by fieldname.
IN FILE INFILE FRN %RECNO %RC = $Field_List(%OLIST, 'CHILD_*', 20) END FOR %SLIST = $ListSort(%OLIST, '6,20,A')