$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: >= 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 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): 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 the fieldname_len argument 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.

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*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.

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')