AppendFieldValues (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
No edit summary
 
(7 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:Stringlist:AppendFieldValues subtitle}}
{{Template:Stringlist:AppendFieldValues subtitle}}
This [[Notation conventions for methods#Callable functions|callable]] function retrieves retrieves field values from the current record into <var>Stringlist</var> items.
This [[Notation conventions for methods#Callable functions|callable]] function retrieves retrieves field values from the current record into <var>Stringlist</var> items.


Line 24: Line 23:


<tr><th><var>NameLength</var></th>
<tr><th><var>NameLength</var></th>
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a string containing the length of the output fieldname in the output <var>Stringlist</var> items. It can be any numeric value from 0 to 255; the default is 255.</td></tr>
<td>This optional, [[Notation conventions for methods#Named parameters|name required]], argument is a string containing the length of the output field name in the [[#Output Stringlist item format|output Stringlist items]]. It can be any numeric value from 0 to 255; the default is 255.</td></tr>


<tr><th><var>Fieldname</var></th>
<tr><th><var>Fieldname</var></th>
<td>An optional, name required, string that 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. The default is an asterisk (<tt>*</tt>), which means to return all fields in the record.</td></tr>
<td>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 (<tt>*</tt>), which means to return all fields in the record.</td></tr>


<tr><th><var>Options</var></th>
<tr><th><var>Options</var></th>
Line 33: Line 32:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th><var>TruncLeft</var></th>
<tr><th><var>TruncLeft</var></th>
<td>Truncate fieldnames on the left. This is mutually exclusive with the <var>TruncRight</var> and <var>CanTrunc</var> options.</td></tr>
<td>Truncate field names on the left. This is mutually exclusive with the <var>TruncRight</var> and <var>CanTrunc</var> options.</td></tr>


<tr><th><var>TruncRight</var></th>
<tr><th><var>TruncRight</var></th>
<td>Truncate fieldnames on the right. This is mutually exclusive with the <var>TruncLeft</var> and <var>CanTrunc</var> options.</td></tr>
<td>Truncate field names on the right. This is mutually exclusive with the <var>TruncLeft</var> and <var>CanTrunc</var> options.</td></tr>


<tr><th><var>CanTrunc</var></th>
<tr><th><var>CanTrunc</var></th>
<td>Cancel request on truncated fieldname, except when the <var>NameLength</var> argument is 0. This is mutually exclusive with the <var>TruncRight</var> and <var>TruncLeft</var> options.</td></tr>
<td>Cancel request on truncated field name, except when the <var>NameLength</var> argument is 0. This is mutually exclusive with the <var>TruncRight</var> and <var>TruncLeft</var> options.</td></tr>


<tr><th><var>TrueLen</var></th>
<tr><th><var>TrueLen</var></th>
<td>Set true fieldname length rather than truncated fieldname length in the fieldname length byte in the output <var>Stringlist</var>. This is mutually exclusive with the <var>TruncLen</var> option.</td></tr>
<td>Set true field-name length rather than truncated field-name length in the field-name length byte in the output <var>Stringlist</var>. This is mutually exclusive with the <var>TruncLen</var> option.</td></tr>


<tr><th><var>TruncLen</var></th>
<tr><th><var>TruncLen</var></th>
<td>Set truncated fieldname length in the fieldname length byte in the output <var>Stringlist</var>; this is the default. This is mutually exclusive with the <var>TrueLen</var> option.
<td>Set truncated field-name length in the field-name length byte in the output <var>Stringlist</var>; this is the default. This is mutually exclusive with the <var>TrueLen</var> option.
</td></tr></table>
</td></tr></table>
</td></tr>
</td></tr>
Line 51: Line 50:


===Output Stringlist item format===
===Output Stringlist item format===
<table>
<table class="thJustBold">
<tr><th>Offset</th>
<tr class="head"><th>Offset</th>
<th>Contents</th>
<th>Contents</th>
<tr><th>0-3</th>
<tr><th>0-3</th>
<td>A binary sequence number (same as the $list item number when item added). </td></tr>
<td>A binary sequence number (same as the $list item number when item added). </td></tr>
<tr><th>4-4</th>
<tr><th>4-4</th>
<td>Binary length of fieldname (true or truncated depending on TrueLen). </td></tr>
<td>Binary length of field name (true or truncated depending on <var>TrueLen</var>). </td></tr>
 
<tr><th>5-(5+N-1)</th>
<tr><th>5-(5+N-1)</th>
<td>Blank padded or truncated field name where N is value of argument 2. </td></tr>
<td>Blank padded or truncated field name, where N is value of the <var>NameLength</var> argument. </td></tr>
 
<tr><th>5+N-(5+N)</th>
<tr><th>5+N-(5+N)</th>
<td>Binary length of field value. </td></tr>
<td>Binary length of field value. </td></tr>
<tr><th>(5+N+1)-end</th>
<tr><th>(5+N+1)-end</th>
<td>Field value in string format as it would be displayed in a PAI. </td></tr>
<td>Field value in string format as it would be displayed in a <var>PAI</var>. </td></tr>
</table>
</table>


Line 75: Line 79:


<li>The name specified in the <var>Fieldname</var> argument can be an explicit name, or it can contain the following wildcard characters:
<li>The name specified in the <var>Fieldname</var> argument can be an explicit name, or it can contain the following wildcard characters:
<table class="syntaxTable">
<table class="thJustBold">
<tr><th>*</th>
<tr><th>*</th>
<td>Matches any number of characters including none</td></tr>
<td>Matches any number of characters including none</td></tr>
<tr><th>?</th>
<tr><th>?</th>
<td>Matches any single character</td></tr>
<td>Matches any single character</td></tr>
<tr><th>"</th>
<tr><th>"</th>
<td>Indicates that the next character must be treated literally even if it is a wildcard character.
<td>Indicates that the next character must be treated literally even if it is a wildcard character.
Line 92: Line 98:
</ul>
</ul>


<li>If a non-wildcard <var>Fieldname</var> value is specified, and the field name does not exist in the file, <var>AppendFieldValues</var> simply returns a 0 without scanning the record. If a wildcard <var>Fieldname</var> 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 <var>Fieldname</var> value that does not exist in the file, or a request cancellation because of a truncated field name, or <var>Stringlist</var> or CCATEMP full, the entire record is always scanned.  
<li>If a non-wildcard <var>Fieldname</var> value is specified, and the field name does not exist in the file, <var>AppendFieldValues</var> simply returns a 0 without scanning the record. If a wildcard <var>Fieldname</var> 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 <var>Fieldname</var> value that does not exist in the file, or a request cancellation because of a truncated field name, or <var>Stringlist</var> or CCATEMP full, the entire record is always scanned.
 
<li><var>AppendFieldValues</var> is not recommended for use with <var>FILEORG</var> X'100' files. For example, <var>AppendFieldValues</var> will not create a <var>Stringlist</var> item for an <var>EXACTLY-ONE</var> field that was not explicitly stored. For <var>FILEORG</var> X'100' files, <var>[[AppendFieldImages (Stringlist function)|AppendFieldImages]]</var> is recommended.
 
</ul>
</ul>


==Examples==
==Examples==
The following code fragment retrieves all fields in a record where the field name begins with the letters "CHILD_" into  <var>Stringlist</var> <code>%sl</code> and sorts the <var>Stringlist</var> by field name:
The following code fragment retrieves all fields in a record where the field name begins with the letters "CHILD_" into  <var>Stringlist</var> <code>%sl</code> and sorts the <var>Stringlist</var> <code>%sl</code> by field name into <var>Stringlist</var> <code>%outlist</code>:
<p class="code">In File INFILE Frn %recno
<p class="code">In File INFILE Frn %recno
%rc = %sl:AppendFieldValues('CHILD_*', 20)
%rc = %sl:AppendFieldValues('CHILD_*', 20)
End For
End For
   
   
%outlist = %sl:Sort('6,20,A')
%outlist = %sl:Sortnew('6,20,A')
</p>
</p>


==See also==
==See also==
<ul>
<li><var>[[AppendFieldImages (Stringlist function)|AppendFieldImages]]</var> retrieves fields that are in repeating groups into <var>Stringlist</var> items mapped to a <var class="product">SOUL</var> image.
</ul>
{{Template:Stringlist:AppendFieldValues footer}}
{{Template:Stringlist:AppendFieldValues footer}}

Latest revision as of 22:48, 2 September 2015

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.