$Field List

Return field values into a $list

Note: Many $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

%rc = $Field_List(olist, [fieldname_len], [fieldname], [options])

Syntax terms

%rc	A number of items added to olist, or it is one of these (negative) status codes: >= 0 Number of field values extracted     -3 CCATEMP full or $list full All other errors result in request cancellation.
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 field name in the output $list items; it 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 field name 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): TruncLeft Truncate field names on the left. This is mutually exclusive with the TruncRight and CanTrunc options. TruncRight Truncate field names on the right. This is mutually exclusive with the TruncLeft and CanTrunc options. CanTrunc Cancel request on truncated field name, except when the fieldname_len argument is 0. This is mutually exclusive with the TruncRight and TruncLeft options. TrueLen Set true field-name length rather than truncated field name length in the field-name length byte in the output $list. This is mutually exclusive with the TruncLen option. TruncLen Set truncated field-name length in the field-name length byte in the output $list; this is the default. This is mutually exclusive with the TrueLen option.

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 field name (true or truncated depending on TrueLen).
5-(5+N-1)	Blank padded or truncated field name where N is value of the fieldname_len 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.

Usage notes

• Most field names 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 field name causes request cancellation, except when the fieldname_len argument 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 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.

  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 field name is specified for the fieldname argument and the field name does not exist in the file, $Field_List simply returns a 0 without scanning the record. If a wildcard field name is specified for fieldname 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 field name that does not exist in the file or a request cancellation because of a truncated field name, or $list or CCATEMP full, the entire record is always scanned.
• $Field_List is not recommended for use with FILEORG X'100' files. For example, $Field_List will not create a $list item for an EXACTLY-ONE field that was not explicitly stored. For FILEORG X'100' files, AppendFieldImages (or the non-OO $Field_ListI) is recommended.

Examples

The following code fragment retrieves all fields in a record where the field name begins with the letters "CHILD_" into a $list and sorts the $list by field name.

In File INFILE Frn %recno %rc = $Field_List(%olist, 'CHILD_*', 20) End For %slist = $ListSort(%olist, '6,20,A')