ProcedureInfo class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (misc formatting)
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The <var>ProcedureInfo</var> class provides information about the procedures in a procedure file or group. The class is an object-oriented alternative to  
The <var>ProcedureInfo</var> class provides information about the procedures in a procedure file or group. The class is an object-oriented alternative to  
<var>$LSTPROC</var>, <var>[[$Proc_List]]</var>, <var>[[$Proc_ListG]]</var>, <var>[[$PrcLEx]]</var>, and <var>[[$PrcLExG]]</var>, and it is a more structured alternative to the <var>Stringlist</var> class <var>[[AppendProcedureList (Stringlist function)|AppendProcedureList]]</var> method.                     
<var>[[$LstProc]]</var>, <var>[[$Proc_List]]</var>, <var>[[$Proc_ListG]]</var>, <var>[[$PrcLEx]]</var>, and <var>[[$PrcLExG]]</var>, and it is a more structured alternative to the <var>Stringlist</var> class <var>[[AppendProcedureList (Stringlist function)|AppendProcedureList]]</var> method.                     
   
   
<var>ProcedureInfo</var>
A <var>ProcedureInfo</var> object provides information such as the size of a   
procedure and the date and user ID of its last update. <var>ProcedureInfo</var>
objects are easily gathered into an <var>ArrayList</var>, so they offer the advantage of the sorting, finding, and subsetting facilities of collections.
objects are easily gathered into an <var>ArrayList</var>, so they offer the advantage of the sorting, finding, and subsetting facilities of collections.
   
   
The <var>ProcedureInfo</var> class is available as of <var class="product">Sirius Mods</var> Version 7.8.
The <var>ProcedureInfo</var> class is available as of <var class="product">Sirius Mods</var> Version 7.8.
==The information accessing methods==
These pieces of information (provided by class functions named as follows) are available for an object in the <var>ProcedureInfo</var> class:
<table class="syntaxTable">


<tr><td><var>[[Bytes (ProcedureInfo function)|Bytes]]</var></td>
==Creating ProcedureInfo objects==
<td>The length of the procedure in bytes. </td></tr>
 
<tr><td><var>[[Filename (ProcedureInfo function)|Filename]]</var></td>
<td>The the name of the file that contains the procedure. </td></tr>
 
<tr><td><var>[[FirstPageNumber (ProcedureInfo function)|FirstPageNumber]]</var></td>
<td>The internal page number of the first page of the procedure; intended for debugging. </td></tr>
 
<tr><td><var>[[Name (ProcedureInfo function)|Name]]</var></td>
<td>The global/session name associated with the object.</td></tr>
 
<tr><td><var>[[LastUpdateTime (ProcedureInfo function)|LastUpdateTime]]</var></td>
<td>The time the procedure was last updated (YYYYMMDDHHMISSXXX format).
 
<tr><td><var>[[LastUpdateTimeMilliseconds (ProcedureInfo function)|LastUpdateTimeMilliseconds]]</var></td>
<td>The time the procedure was last updated in  milliseconds since Jan 1, 1900 00:00:00.


<tr><td><var>[[LastUpdateUser (ProcedureInfo function)|LastUpdateUser]]</var></td>
<td>The ID of the user that last updated the procedure.
</td></tr></table>
==Creating ProcedureInfo objects==
===Using New===
===Using New===
One way of creating a <var>ProcedureInfo</var> object is with the <var>[[New (ProcedureInfo function)|New]]</var> method. <var>New</var> takes two named input parameters that indicate the name of the procedure and of its procedure file or group:
One way of creating a <var>ProcedureInfo</var> object is with the <var>[[New (ProcedureInfo constructor)|New]]</var> method. <var>New</var> takes two named input parameters that indicate the name of the procedure and of its procedure file or group:
<p class="code">%procInfo    is object procedureInfo
<p class="code">%procInfo    is object procedureInfo
  ...
  ...
Line 43: Line 19:
   
   
<var>New</var> returns a <var>Null</var> object if the procedure is not found.
<var>New</var> returns a <var>Null</var> object if the procedure is not found.
 
===Using List===
===Using List===
Probably the most common way of creating <var>ProcedureInfo</var> objects is using
Probably the most common way of creating <var>ProcedureInfo</var> objects is using
the <var>[[List (ProcedureInfo function)|List]]</var> method. This is a [[Notation conventions for methods#Shared methods|shared]] method that returns an <var>Arraylist of Object ProcedureInfo</var>.
the <var>[[List (ProcedureInfo function)|List]]</var> method. This is a [[Notation conventions for methods#Shared methods|shared]] method that returns an <var>Arraylist of Object ProcedureInfo</var>.
   
   
The <var>List</var> method has one required named parameter (<var>In</var> for the containing procedure file or group, and one optional named parameter (<var>Name</var>) to identify the procedures to be returned, with wildcards allowed.
The <var>List</var> method has one required, named parameter (<var>In</var> for the containing procedure file or group, and one optional, named parameter (<var>Name</var>) to identify the procedures to be returned, with wildcards allowed.
These wildcards are the <var class="product">User Language</var> standard, non-regex, wildcards.
These wildcards are the <var class="product">SOUL</var> standard, non-regex, wildcards.
Specifying no <var>Name</var> value is the same as specifying an asterisk (<tt>*</tt>) for the procedure name pattern: the information is returned for all the procedures.
   
   
For example:
For example:
Line 57: Line 32:
%procInfoList = %(procedureInfo):List(In='MYPROCFILE', Name='MY*')
%procInfoList = %(procedureInfo):List(In='MYPROCFILE', Name='MY*')
for %i from 1 to %procInfoList:count
for %i from 1 to %procInfoList:count
  printText {%procInfoList(%i):name} {%procInfoList(%i):bytes} {%procInfoList(%i):lastUpdateTime}
  printText {%procInfoList(%i):name} {%procInfoList(%i):bytes} {%procInfoList(%i):lastUpdateTime}
end for
end for
</p>
</p>


'''Note:''' The <var>List</var> method does not have parameters to select procedures based on last update time or last updating user ID. You can accomplish the same thing by using the <var>Arraylist</var> subsetting methods though, this approach would be significantly more expensive if a large list were built only to select a small subset. 
==The ProcedureInfoList type==
==The ProcedureInfoList type==
As a coding convenience, the <var>ProcedureInfoList</var>
As a coding convenience, the <var>ProcedureInfoList</var>
Line 68: Line 41:
<p class="code">%procInfoList is type procedureInfoList</p>
<p class="code">%procInfoList is type procedureInfoList</p>
   
   
'''Note:''' The keyword <var>Type</var> is required.
<p class="note">'''Note:''' The keyword <var>Type</var> is required. </p>
   
   
==Example==
==Example==
The following example uses may of the <var>ProcedureInfo</var> methods:
The following example uses many of the <var>ProcedureInfo</var> methods:
<p class="code">OPENC SIRIUS                                                    
<p class="code">OPENC SIRIUS  
b  
b  
%procInfo  is object procedureInfo  
%procInfo  is object procedureInfo  
Line 78: Line 51:
%i          is float  
%i          is float  


%procList = %(procedureInfo):list(name='*SS*', in='GROUP SIRIUS')
%procList = %(procedureInfo):list(name='SSL*', in='GROUP SIRIUS')
                                                                 
printText {~} = {%procList:count}
printText {~} = {%procList:count}
%procList:sort(descending(lastUpdateTimeMilliseconds))
%procList:sort(descending(lastUpdateTimeMilliseconds))
for %i from 1 to %procList:count
for %i from 1 to %procList:count
    %procInfo = %procList(%i)
  %procInfo = %procList(%i)   
    %procInfo = %procList(%i)   
  printText {%procInfo:filename:left(8)} {%procInfo:name:left(16)} {%procInfo:bytes:left(8)} -
    printText {%procInfo:filename:left(8)} {%procInfo:firstPageNumber:left(10)} {%procInfo:name:left(34)} -
              {%procInfo:lastUpdateUser:left(10)} {%procInfo:lastUpdateTime}  
              {%procInfo:bytes:left(8)} {%procInfo:lastUpdateUser:left(10)} {%procInfo:lastUpdateTime}    
end for  
end for  
end  
end  
</p>
</p>
This is a sample result:
This is a sample result:
<p class="code">%procList:count = 7                                                                      
<p class="code">%procList:count = 7  
SIRIUS   04000773   SSLP-REQ                           30846    ALAN      2011071509461684
SIRIUS  SSLP-REQ         30846    ALAN      2011071509461684
SIRIUS   0400076E   SSLP-PROCS                         25888    ALAN      2011071509461681
SIRIUS  SSLP-PROCS       25888    ALAN      2011071509461681
SIRIUS   04000593   SSLP-SIGN                         22908    ALAN      2008062010244706
SIRIUS  SSLP-SIGN       22908    ALAN      2008062010244706
SIRIUS   04000259   SSLP-RECV                         25827    ALAN      2008062010244218
SIRIUS  SSLP-RECV       25827    ALAN      2008062010244218
SIRIUS   040002AB   SSLP-FILES                         7201    ALAN      2008062010243551
SIRIUS  SSLP-FILES       7201    ALAN      2008062010243551
SIRIUS   04000237   SSLN-START                         10115    ALAN      2008062010243273
SIRIUS  SSLN-START       10115    ALAN      2008062010243273
SIRIUS   04000566   SSLN-END                           3632    ALAN      2008062010242969
SIRIUS  SSLN-END         3632    ALAN      2008062010242969
</p>
</p>


Line 112: Line 83:
$list equivalents. If fewer than 10% of the procedures are selected, a <var>ProcedureInfoList</var>       
$list equivalents. If fewer than 10% of the procedures are selected, a <var>ProcedureInfoList</var>       
would be faster than the $list equivalent. If 5% are selected, then the <var>ProcedureInfoList</var> approach would be twice as fast. The reasons for the speed improvement are for internal technical reasons.  
would be faster than the $list equivalent. If 5% are selected, then the <var>ProcedureInfoList</var> approach would be twice as fast. The reasons for the speed improvement are for internal technical reasons.  
<blockquote class="note">
<p>'''Note:''' Because the object-oriented infrastructure is a considerably "heavier weight" than a simple unstructured $list containing procedure information, using a <var>ProcedureInfoList</var> can be a factor of 3 to 5 times slower than  equivalent $list (or <var>Stringlist</var>) processing. This includes procedure list extraction and possibly sorting. </p>     
<p>
<p>
'''Note:''' Because the object-oriented infrastructure is a considerably "heavier weight" than a simple unstructured $list containing procedure information, using a <var>ProcedureInfoList</var> can be a factor of 3 to 5 times slower than  equivalent $list (or <var>Stringlist</var>)
However, except for extremely large lists (more than 100,000 procedures), this is likely to be a minor cost (along the order of a few hundred milliseconds or less on a fast processor).
processing. This includes procedure list extraction and possibly sorting.       
And, for such large lists, it is quite likely that the I/O time for reading the procedure dictionary (which will be quite large and so likely to not all be in the buffer pool) will dominate.</p>
However, except for extremely large lists (>100,000 procedures), this is likely to be a minor cost (along the order of a few hundred milliseconds or less on a fast processor).
</blockquote>
And, for such large lists, it is quite likely that the I/O time for reading      
</li>
the procedure dictionary (which will be quite large and so likely to not        
all be in the buffer pool) will dominate.</p>
</ul>
</ul>


==List of ProcedureInfo methods==
==List of ProcedureInfo methods==
The [[List of ProcedureInfo methods|"List of ProcedureInfo methods"]] contains a complete list of the class methods.
The [[List of ProcedureInfo methods]] contains a complete list of the class methods.
   
   
[[Category:System classes]]
[[Category:System classes]]

Latest revision as of 19:24, 20 June 2017

The ProcedureInfo class provides information about the procedures in a procedure file or group. The class is an object-oriented alternative to $LstProc, $Proc_List, $Proc_ListG, $PrcLEx, and $PrcLExG, and it is a more structured alternative to the Stringlist class AppendProcedureList method.

A ProcedureInfo object provides information such as the size of a procedure and the date and user ID of its last update. ProcedureInfo objects are easily gathered into an ArrayList, so they offer the advantage of the sorting, finding, and subsetting facilities of collections.

The ProcedureInfo class is available as of Sirius Mods Version 7.8.

Creating ProcedureInfo objects

Using New

One way of creating a ProcedureInfo object is with the New method. New takes two named input parameters that indicate the name of the procedure and of its procedure file or group:

%procInfo is object procedureInfo ... %procInfo = new(In='MYPROCFILE', Name='MYPROC') printText {%procInfo:name} {%procInfo:bytes} {%procInfo:lastUpdateTime}

New returns a Null object if the procedure is not found.

Using List

Probably the most common way of creating ProcedureInfo objects is using the List method. This is a shared method that returns an Arraylist of Object ProcedureInfo.

The List method has one required, named parameter (In for the containing procedure file or group, and one optional, named parameter (Name) to identify the procedures to be returned, with wildcards allowed. These wildcards are the SOUL standard, non-regex, wildcards.

For example:

%procInfoList is arraylist of object procedureInfo ... %procInfoList = %(procedureInfo):List(In='MYPROCFILE', Name='MY*') for %i from 1 to %procInfoList:count printText {%procInfoList(%i):name} {%procInfoList(%i):bytes} {%procInfoList(%i):lastUpdateTime} end for

The ProcedureInfoList type

As a coding convenience, the ProcedureInfoList type is defined as an "Arraylist of Object ProcedureInfo". Consequently, you can specify a declaration like the one in the preceding example for %procInfoList more simply as:

%procInfoList is type procedureInfoList

Note: The keyword Type is required.

Example

The following example uses many of the ProcedureInfo methods:

OPENC SIRIUS b %procInfo is object procedureInfo %procList is type procedureInfoList %i is float %procList = %(procedureInfo):list(name='SSL*', in='GROUP SIRIUS') printText {~} = {%procList:count} %procList:sort(descending(lastUpdateTimeMilliseconds)) for %i from 1 to %procList:count %procInfo = %procList(%i) printText {%procInfo:filename:left(8)} {%procInfo:name:left(16)} {%procInfo:bytes:left(8)} - {%procInfo:lastUpdateUser:left(10)} {%procInfo:lastUpdateTime} end for end

This is a sample result:

%procList:count = 7 SIRIUS SSLP-REQ 30846 ALAN 2011071509461684 SIRIUS SSLP-PROCS 25888 ALAN 2011071509461681 SIRIUS SSLP-SIGN 22908 ALAN 2008062010244706 SIRIUS SSLP-RECV 25827 ALAN 2008062010244218 SIRIUS SSLP-FILES 7201 ALAN 2008062010243551 SIRIUS SSLN-START 10115 ALAN 2008062010243273 SIRIUS SSLN-END 3632 ALAN 2008062010242969

ProcedureInfo advantages

The ProcedureInfo processing has several advantages over $list processing:

  • It is more structured and robust than the comparable $list technology, and it uses the superior object-oriented syntax. Except in extreme cases, this alone is sufficient to justify using the ProcedureInfo class instead of the $list equivalents ($Proc_List, $Proc_ListG, $PrcLEx, and $PrcLExG).
  • The ProcedureInfo New method does not scan the entire procedure dictionary, unlike the $list $functions. This can make the New method hundreds or even thousands of times more efficient than the comparable $list approach. And the List method is comparably efficient if the requested name contains no wildcards.
  • If the List method specifies a wildcard that excludes a significant percentage of the procedures in the context file, it becomes more efficient than the $list equivalents. If fewer than 10% of the procedures are selected, a ProcedureInfoList would be faster than the $list equivalent. If 5% are selected, then the ProcedureInfoList approach would be twice as fast. The reasons for the speed improvement are for internal technical reasons.

    Note: Because the object-oriented infrastructure is a considerably "heavier weight" than a simple unstructured $list containing procedure information, using a ProcedureInfoList can be a factor of 3 to 5 times slower than equivalent $list (or Stringlist) processing. This includes procedure list extraction and possibly sorting.

    However, except for extremely large lists (more than 100,000 procedures), this is likely to be a minor cost (along the order of a few hundred milliseconds or less on a fast processor). And, for such large lists, it is quite likely that the I/O time for reading the procedure dictionary (which will be quite large and so likely to not all be in the buffer pool) will dominate.

List of ProcedureInfo methods

The List of ProcedureInfo methods contains a complete list of the class methods.