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.

AppendFieldValues is a Stringlist variant of $Field_List. AppendFieldValues has the same parameters as $Field_list, except they are name required parameters.

Syntax

[%count =] sl:AppendFieldValues[( [NameLength= number], [Fieldname= string], - [Options= string])]

Syntax terms

%count	This numeric variable is the number of values added to Stringlist sl, or it is one of these (negative) status codes: >= 0 Number of field values extracted.     -3 CCATEMP full. All other errors result in request cancellation.
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): 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 NameLength 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 Stringlist. This is mutually exclusive with the TruncLen option. TruncLen Set truncated field-name length in the field-name length byte in the output Stringlist; this is the default. This is mutually exclusive with the TrueLen option.

Output Stringlist item 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 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.

Usage notes

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

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

Examples

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 %outlist:

In File INFILE Frn %recno %rc = %sl:AppendFieldValues('CHILD_*', 20) End For %outlist = %sl:Sortnew('6,20,A')

See also

• AppendFieldImages retrieves fields that are in repeating groups into Stringlist items mapped to a SOUL image.

Stringlist class	List of Stringlist methods	Stringlist methods syntax
Notation conventions for methods