$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.
The $Field_List function accepts four arguments and returns a number indicating the success of the function.
The first argument is 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.
The second argument is 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.
The third argument is 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 "*" which means to return all fields in the record.
The fourth argument is a set of blank-delimited processing options:
| TruncLeft | Truncate fieldnames on the left. This is mutually exclusive with the TruncRight and CanTrunc options. |
|---|---|
| TruncRight | Truncate fieldnames on the right. This is mutually exclusive with the TruncLeft and CanTrunc options. |
| CanTrunc | Cancel request on truncated fieldname, except when argument 2 (the output fieldname length) is 0. This is mutually exclusive with the TruncRight and TruncLeft options. |
| TrueLen | Set true fieldname length rather than truncated fieldname length in the fieldname length byte in the output $list. This is mutually exclusive with the TruncLen option. |
| TruncLen | Set truncated fieldname length in the fieldname length byte in the output $list; this is the default. This is mutually exclusive with the TrueLen option. |
Syntax
<section begin="syntax" /> %RC = $Field_List(olist, fieldname_len, fieldname, options) <section end="syntax" />
$Field_List Function
%RC is a number of items added to olist, or it is a negative error code.
>= 0 - Number of fields values extracted -3 - $list full or out of CCATEMP All other errors result in request cancellation
$Field_List return codes
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.
Most fieldnames are typically much shorter than 255 bytes so a large amount of $list space is wasted if the third 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 length of 0 which means that while the fieldname will not be returned its length will.
The name specified in the third 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*D matches "CUSTID", "COD" or "CLOD".
- .S??T matches "SALT", "SLOT" or "SORT".
- .E"*CONCRETE matches "E*CONCRETE".
If a non-wildcard fieldname is specified for argument three 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 argument three 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.
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')
$Field_List is only available in Version 6.0 and later of the Sirius Mods.
Starting with Version 7.1, the options argument can be specified in any combination of uppercase and lowercase letters; prior to that, it must be specified in all uppercase letters.