AppendProcedureList (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (add usage note and See also link)
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:Stringlist:AppendProcedureList subtitle}}
{{Template:Stringlist:AppendProcedureList subtitle}}


This callable function returns information about procedures in a procedure file or group into a <var>Stringlist</var>.
This [[Notation conventions for methods#Callable functions|callable]] function returns information about procedures in a procedure file or group into a <var>Stringlist</var>.
 
The <var>AppendProcedureList</var> function accepts three arguments and returns a numeric result.


==Syntax==
==Syntax==
{{Template:Stringlist:AppendProcedureList syntax}}
{{Template:Stringlist:AppendProcedureList syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
Line 12: Line 11:
<td>A numeric variable that is set to zero if the function is a success; otherwise, it is set to one of these negative error codes:.
<td>A numeric variable that is set to zero if the function is a success; otherwise, it is set to one of these negative error codes:.
<table>
<table>
<tr><th>-1</th>
<tr><th><var>-1</var></th>
<td>File/group not found</td></tr>
<td>File/group not found</td></tr>
<tr><th>-2</th>
 
<tr><th><var>-2</var></th>
<td>No procedures match search criteria</td></tr>
<td>No procedures match search criteria</td></tr>
</table>
</table>
All other errors result in request cancellation.
All other errors result in request cancellation.
<tr><th>sl</th>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object.</td></tr>
<td>A <var>Stringlist</var> object.</td></tr>
<tr><th>file</th>
<tr><th>file</th>
<td>The name of the file or group for which information is to be returned. This is an optional argument, and it defaults to the default file/group at <b><i>compile</i></b> time.</td></tr>
<td>The name of the file or group for which information is to be returned. This is an optional argument, and it defaults to the default file/group at <b><i>compile</i></b> time.</td></tr>
<tr><th>pname</th>
<tr><th>pname</th>
<td>The procedure name that is to be selected. The procedure name may contain asterisk (*) characters to indicate wildcard matches. This is an optional parameter, and it defaults to all procedures.</td></tr>
<td>The procedure name that is to be selected. The procedure name may contain asterisk (*) characters to indicate wildcard matches. This is an optional parameter, and it defaults to all procedures.</td></tr>
<tr><th>accnt</th>
<tr><th>accnt</th>
<td>The account ID of the last modifying user for the procedures to be selected. The account ID may contain asterisk (*) characters to indicate wildcard matches. This is an optional parameter, and it defaults to all account IDs.</td></tr>
<td>The account ID of the last modifying user for the procedures to be selected. The account ID may contain asterisk (*) characters to indicate wildcard matches. This is an optional parameter, and it defaults to all account IDs.</td></tr>
<tr><th>date</th>
<tr><th>date</th>
<td>A string indicating the last modification date for the procedures to be selected. If specified, this parameter must be six bytes long and begin with an equal sign (<code>=</code>), a less-than sign (<code><</code>), or a greater-than sign (<code>></code>) to indicate whether the date should be equal to, less than, or greater than, respectively, the Julian date that follows, which is the last five characters.  For example: the value <code>>03200</code> selects procedures last modified after day 200 of 2003.
<td>A string indicating the last modification date for the procedures to be selected. If specified, this parameter must be six bytes long and begin with an equals sign (<code>=</code>), a less-than sign (<code><</code>), or a greater-than sign (<code>></code>) to indicate whether the date should be equal to, less than, or greater than, respectively, the Julian date that follows, which is the last five characters.  For example: the value <code>>03200</code> selects procedures last modified after day 200 of 2003.
This is an optional parameter, and it defaults to all modification dates.
This is an optional parameter, and it defaults to all modification dates.
This two-digit year date is interpreted with a <code>CENTSPAN</code> of <code>1975</code>, so values between <code>00000</code> and <code>74365</code> are considered to be in the year range 2000-2074.</td></tr>
This two-digit year date is interpreted with a <code>CENTSPAN</code> of <code>1975</code>, so values between <code>00000</code> and <code>74365</code> are considered to be in the year range 2000-2074.</td></tr>
Line 33: Line 37:


==Usage notes==
==Usage notes==
<ul><li><var class="term">sl</var>, the output <var>Stringlist</var> produced by <var>AppendProcedureList</var>, has the following format:<dl>
<ul>
<dt>Col 1-10<dd>Account ID of last updater.<dt>Col 12-19<dd>Size of procedure in bytes.<dt>Col 21-30<dd>Date of last update (YYYY/MM/DD).<dt>Col 32-39<dd>Time of last update (BH:MI:SS).<dt>Col 41-48<dd>File containing the procedure.<dt>Col 49-<dd>Procedure name.</dl></ul>
<li><var class="term">sl</var>, the output <var>Stringlist</var> produced by <var>AppendProcedureList</var>, has the following format:<dl>
<dt>Col 1-10<dd>Account ID of last updater.<dt>Col 12-19<dd>Size of procedure in bytes.<dt>Col 21-30<dd>Date of last update (YYYY/MM/DD).<dt>Col 32-39<dd>Time of last update (BH:MI:SS).<dt>Col 41-48<dd>File containing the procedure.<dt>Col 49-<dd>Procedure name.</dl>
 
<li>Each file in the file or group context specified by <var class="term">sl</var> is processed in turn, in the order of the files in that context.
<p>
Within each file, the procedures are added in the order in which they occur in the procedure dictionary, which, since the procedure dictionary is a hashed structure, can essentially be a random order. </p>
</li>
</ul>


==Examples==
==Examples==
<ol><li>The following program displays information for all procedures in group <code>HOMER</code> beginning with the letter <code>S</code>, last updated by a user whose account ID begins with the letter <code>A</code>.
The following program displays information for all procedures in group <code>HOMER</code> beginning with the letter <code>S</code>, last updated by a user whose account ID begins with the letter <code>A</code>.


<p class="code">begin
<p class="code">begin
Line 43: Line 54:
  %list = new
  %list = new
  %list:appendProcedureList('HOMER', 'S*', 'A*')
  %list:appendProcedureList('HOMER', 'S*', 'A*')
  %list:print
  %list:print
end
end
</p></ol>
</p>


==See also==
==See also==
<ul>
<li>The <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedure]]</var> function appends procedure lines to a <var>Stringlist</var>.
<li>The <var>[[ProcedureInfo class|ProcedureInfo]]</var> class can provide comparable functionality to <var>AppendProcedureList</var>. </ul>
{{Template:Stringlist:AppendProcedureList footer}}
{{Template:Stringlist:AppendProcedureList footer}}

Latest revision as of 23:37, 25 January 2016

Add information about procedures to a Stringlist (Stringlist class)


This callable function returns information about procedures in a procedure file or group into a Stringlist.

Syntax

[%rc =] sl:AppendProcedureList( file, [pname], [accnt], [date])

Syntax terms

%rc A numeric variable that is set to zero if the function is a success; otherwise, it is set to one of these negative error codes:.
-1 File/group not found
-2 No procedures match search criteria

All other errors result in request cancellation.

sl A Stringlist object.
file The name of the file or group for which information is to be returned. This is an optional argument, and it defaults to the default file/group at compile time.
pname The procedure name that is to be selected. The procedure name may contain asterisk (*) characters to indicate wildcard matches. This is an optional parameter, and it defaults to all procedures.
accnt The account ID of the last modifying user for the procedures to be selected. The account ID may contain asterisk (*) characters to indicate wildcard matches. This is an optional parameter, and it defaults to all account IDs.
date A string indicating the last modification date for the procedures to be selected. If specified, this parameter must be six bytes long and begin with an equals sign (=), a less-than sign (<), or a greater-than sign (>) to indicate whether the date should be equal to, less than, or greater than, respectively, the Julian date that follows, which is the last five characters. For example: the value >03200 selects procedures last modified after day 200 of 2003.

This is an optional parameter, and it defaults to all modification dates.

This two-digit year date is interpreted with a CENTSPAN of 1975, so values between 00000 and 74365 are considered to be in the year range 2000-2074.

Usage notes

  • sl, the output Stringlist produced by AppendProcedureList, has the following format:
    Col 1-10
    Account ID of last updater.
    Col 12-19
    Size of procedure in bytes.
    Col 21-30
    Date of last update (YYYY/MM/DD).
    Col 32-39
    Time of last update (BH:MI:SS).
    Col 41-48
    File containing the procedure.
    Col 49-
    Procedure name.
  • Each file in the file or group context specified by sl is processed in turn, in the order of the files in that context.

    Within each file, the procedures are added in the order in which they occur in the procedure dictionary, which, since the procedure dictionary is a hashed structure, can essentially be a random order.

Examples

The following program displays information for all procedures in group HOMER beginning with the letter S, last updated by a user whose account ID begins with the letter A.

begin %list is object stringList %list = new %list:appendProcedureList('HOMER', 'S*', 'A*') %list:print end

See also

  • The AppendOpenProcedure function appends procedure lines to a Stringlist.
  • The ProcedureInfo class can provide comparable functionality to AppendProcedureList.