$Field List: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 4: Line 4:
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for <var>$Field_List</var> is the <var>Stringlist</var> <var>[[AppendFieldValues (Stringlist function)|AppendFieldValues]]</var> function.</p>
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for <var>$Field_List</var> is the <var>Stringlist</var> <var>[[AppendFieldValues (Stringlist function)|AppendFieldValues]]</var> function.</p>


This function retrieves field values from the current record into a $list. It provides an alternative to PAI INTO.  
This function retrieves field values from the current record into a $list. It provides an alternative to <var>PAI INTO</var>.  


The $Field_List function accepts four arguments and returns a number indicating the success of the function.  
<var>$Field_List</var> 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.
==Syntax==
<p class="syntax"><section begin="syntax" />%rc = $Field_List(olist, [fieldname_len], [fieldname], [options])
<section end="syntax" /></p>
 
===Syntax terms===
<table class="syntaxTable">
<tr><th>%rc</th>
<td>A number of items added to <var class="term">olist</var>, or it is or it is one of these (negative) status codes:
<table>
<tr><th><var>>= 0</var> </th>
<td>Number of field values extracted </td></tr>
<tr><th>&nbsp;&nbsp;&nbsp;&nbsp;<var>-3</var></th>
<td>CCATEMP full or $list full</td></tr>
</table>
All other errors result in request cancellation. </td></tr>


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.  
<tr><th>olist</th>
<td>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. </td></tr>


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.  
<tr><th>fieldname_len</th>
<td>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. </td></tr>


The fourth argument is a set of blank-delimited processing options:
<tr><th>fieldname</th>
<td>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 (<tt>*</tt>), which means to return all fields in the record. </td></tr>
 
<tr><th>options</th>
<td>A set of blank-delimited processing options that, starting with <var class="Product">Sirius Mods</var> Version 7.1, can be specified in any combination of uppercase and lowercase letters (prior to that, all-uppercase letters are required):
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>TruncLeft</th>
<tr><th><var>TruncLeft</var></th>
<td>Truncate fieldnames on the left. This is mutually exclusive with the TruncRight and CanTrunc options.</td></tr>
<td>Truncate fieldnames on the left. This is mutually exclusive with the <var>TruncRight</var> and <var>CanTrunc</var> options.</td></tr>
<tr><th>TruncRight</th>
 
<td>Truncate fieldnames on the right. This is mutually exclusive with the TruncLeft and CanTrunc options.</td></tr>
<tr><th><var>TruncRight</var></th>
<tr><th>CanTrunc</th>
<td>Truncate fieldnames on the right. This is mutually exclusive with the <var>TruncLeft</var> and <var>CanTrunc</var> options.</td></tr>
<td>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.</td></tr>
 
<tr><th>TrueLen</th>
<tr><th><var>CanTrunc</var></th>
<td>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.</td></tr>
<td>Cancel request on truncated fieldname, except when the <var class="term">fieldname_len</var> argument is 0. This is mutually exclusive with the <var>TruncRight</var> and <var>TruncLeft</var> options.</td></tr>
<tr><th>TruncLen</th>
 
<td>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.
<tr><th><var>TrueLen</var></th>
<td>Set true fieldname length rather than truncated fieldname length in the fieldname length byte in the output $list. This is mutually exclusive with the <var>TruncLen</var> option.</td></tr>
 
<tr><th><var>TruncLen</var></th>
<td>Set truncated fieldname length in the fieldname length byte in the output $list; this is the default. This is mutually exclusive with the <var>TrueLen</var> option.
</td></tr></table>
</td></tr></table>
</td></tr></table>


==Syntax==
===Output $list format===
<p class="syntax"><section begin="syntax" /> %RC = $Field_List(olist, fieldname_len, fieldname, options)
<table>
<section end="syntax" /></p>
<tr><th>Offset</th>
<p class="caption">$Field_List Function
<th>Contents</th>
</p>
<tr><th>0-3</th>
<p class="caption">%RC is a number of items added to '''olist''', or it is a negative error code.</p>
<td>A binary sequence number (same as the $list item number when item added). </td></tr>
<p class="code">  
<tr><th>4-4</th>
>= 0 - Number of fields values extracted
<td>Binary length of fieldname (true or truncated depending on TrueLen). </td></tr>
  -3 - $list full or out of CCATEMP
<tr><th>5-5+N-1</th>
<td>Blank padded or truncated field name where N is value of argument 2. </td></tr>
  All other errors result in request cancellation
<tr><th>5+N-5+N</th>
</p>
<td>Binary length of field value. </td></tr>
<p class="caption">$Field_List return codes
<tr><th>5+N+1-end</th>
</p>
<td>Field value in string format as it would be displayed in a PAI. </td></tr>
</table>


<p class="code">
==Usage notes==
Output $list format 
<ul>
<li>Most fieldnames are typically much shorter than 255 bytes so a large amount of $list space is wasted if the <var class="term">fieldname</var> argument is not specified.


Offset      Contents
<li>If neither <var>TruncLeft</var> nor <var>TruncRight</var> is specified as an option, a truncated fieldname causes request cancellation, except when the fieldname length is 0, in which case <var>TruncLeft</var>, <var>TruncRight</var>, and <var>CanTrunc</var> are meaningless.
  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.
</p>


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.  
<li>Note that you can (bizarrely) specify <var>TrueLen</var> and <var class="term">fieldname_len</var> 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:
<li>The name specified in the <var class="term">fieldname</var> argument can be an explicit name, or it can contain the following wildcard characters:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>*</th>
<tr><th>*</th>
Line 69: Line 90:


For example,  
For example,  
<ul>
<ul>
<li><tt>C*D</tt> matches "CUSTID", "COD" or "CLOD".</li>
<li><code>C*D</code> matches "CUSTID", "COD", or "CLOD".</li>
<li><tt>.S??T</tt> matches "SALT", "SLOT" or "SORT".</li>  
<li><code>.S??T</code> matches "SALT", "SLOT", or "SORT".</li>  
<li>.E"*CONCRETE</tt> matches "E*CONCRETE".</li>  
<li><code>.E"*CONCRETE</code> matches "E*CONCRETE".</li>  
</ul>
</ul>


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.  
<li>If a non-wildcard fieldname is specified for the <var class="term">fieldname</var> argument and the fieldname does not exist in the file, <var>$Field_List</var> simply returns a 0 without scanning the record. If a wildcard fieldname is specified for <var class="term">fieldname</var> 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.  
</ul>


==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.
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.
<p class="code"> IN FILE INFILE FRN %RECNO
<p class="code"> IN FILE INFILE FRN %RECNO
Line 86: Line 108:
</p>
</p>


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.


[[Category:$Functions|$Field_List]]
[[Category:$Functions|$Field_List]]

Revision as of 00:17, 8 July 2012

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 fieldname is specified for the fieldname argument 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 fieldname 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.

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