$LstProc: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
m (misc formatting)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<p>$LSTPROC returns the following procedure information, which is stored in the procedure dictionary:</p>
<p>
<var>$LstProc</var> returns the following procedure information, which is stored in the procedure dictionary:</p>
<ul>
<ul>
<li>Procedure name</li>
<li>Procedure name</li>
</li>
 
<li>Date and time of last update</li>
<li>Date and time of last update</li>
</li>
 
<li>ID of last user to update the procedure</li>
<li>ID of last user to update the procedure</li>
</li>
 
<li>Length of the procedure (in bytes)</li>
<li>Length of the procedure (in bytes)</li>
</li>
 
<li>Procedure security class (if available)</li>
<li>Procedure security class (if available)</li>
</li>
 
<li>Procedure file (if in multiple procedure file group context) </li>
<li>Procedure file (if in multiple procedure file group context) </li>
</li>
</ul><br/>
</ul>
<b>Syntax</b>
<p>The format of the $LSTPROC function is:</p>
<p class="code">$LSTPROC(imagename, <var>[</var>procname<var>] [</var>,loop variable<var>]</var>


        <var>[</var>,alias flag<var>] [</var>,filename<var>] [</var>,pattern<var>])</var>
==Syntax==
<p>
The format of the <var>$LstProc</var> function is:</p>
<p class="syntax">$LstProc(<span class="term">imagename</span>, [<span class="term">procname</span>] [, <span class="term">loop_variable</span>]
        [, <span class="term">alias_flag</span>] [, <span class="term">filename</span>] [, <span class="term">pattern</span>])  
</p>
</p>
<p>where:</p>
 
<ul>
===Syntax terms===
<li>imagename (required) specifies the name of the image into which the information should be returned. The items that must be defined in the image are listed below along with the data type and length of each item. In addition, the position of each item is provided for use with the AT clause where applicable.  </li>
<table>
<tr><th>imagename</th>
<td>This required argument specifies the name of the image into which the information should be returned. The items that must be defined in the image are listed below, along with the data type and length of each item. In addition, the position of each item is provided for use with the <var>AT</var> clause where applicable.   
<table>
<table>
<tr class="head">
<tr class="head">
Line 30: Line 33:
<th>Position</th>
<th>Position</th>
</tr>
</tr>
<tr>
<tr>
<td>Loop variable </td>
<td>loop_variable </td>
<td>BINARY </td>
<td>BINARY </td>
<td align="right">4</td>
<td>4</td>
<td align="right">1</td>
<td>1</td>
</tr>
</tr>
<tr>
<tr>
<td>Date </td>
<td>Date </td>
<td>PACKED </td>
<td>PACKED </td>
<td align="right">4</td>
<td>4</td>
<td align="right">5</td>
<td>5</td>
</tr>
</tr>
<tr>
<tr>
<td>Time </td>
<td>Time </td>
<td>STRING </td>
<td>STRING </td>
<td align="right">8</td>
<td>8</td>
<td align="right">9</td>
<td>9</td>
</tr>
</tr>
<tr>
<tr>
<td>Length </td>
<td>Length </td>
<td>BINARY </td>
<td>BINARY </td>
<td align="right">4</td>
<td>4</td>
<td align="right">17</td>
<td>17</td>
</tr>
</tr>
<tr>
<tr>
<td>Security class </td>
<td>Security class </td>
<td>BINARY </td>
<td>BINARY </td>
<td align="right">1</td>
<td>1</td>
<td align="right">21</td>
<td>21</td>
</tr>
</tr>
<tr>
<tr>
<td>Procedure name </td>
<td>Procedure name </td>
<td>STRING </td>
<td>STRING </td>
<td align="right">209</td>
<td>209</td>
<td align="right">22</td>
<td>22</td>
</tr>
</tr>
<tr>
<tr>
<td>Procedure file name</td>
<td>Procedure file name</td>
<td>STRING</td>
<td>STRING</td>
<td align="right">8</td>
<td>8</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tr>
<tr>
<tr>
<td>User ID </td>
<td>User ID </td>
<td>STRING</td>
<td>STRING</td>
<td align="right">10</td>
<td>10</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tr>
</table>
</table>
<p>For example:</p>
<p>
For example:</p>
<p class="code">IMAGE PROCS
<p class="code">IMAGE PROCS
     LOOPVAR IS BINARY LEN 4
     LOOPVAR IS BINARY LEN 4
Line 91: Line 103:
END IMAGE  
END IMAGE  
</p>
</p>
<p>The procedure file name and the user ID are both optional. If they are not specified, they are not filled in by default values. If the user ID is included, however, the file name must also be included.</p>
<p>
<p>If the image length is not increased, $LSTPROC executes when multiple procedure files have been specified, but does not return file information for each procedure or the user ID.</p>
The procedure file name and the user ID are both optional. If they are not specified, they are not filled in by default values. If the user ID is included, however, the file name must also be included.</p>
</li>
<p>
<li>procname is the procedure for which information should be obtained. The value of procname must be the name of a permanent procedure. If this argument is omitted or null, information about the next procedure is returned. You must specify this argument if the alias flag argument has a value of 1.</li>
If the image length is not increased, <var>$LstProc</var> executes when multiple procedure files have been specified, but does not return file information for each procedure or the user ID.</p></td></tr>
</li>
 
<li>loop variable is an image item that specifies where to begin the search in the procedure dictionary. Because each invocation of $LSTPROC returns information for only one procedure, this variable is used to control repeated $LSTPROC calls. The loop variable must be the first item in the image. The variable can have one of the following values:</li>
<tr><th>procname</th>
</li>
<td>The procedure for which information should be obtained. The value of <var class="term">procname</var> must be the name of a permanent procedure. If this argument is omitted or null, information about the next procedure is returned. You must specify this argument if the <var class="term">alias_flag</var> argument has a value of 1. </td></tr>
</ul>
 
<p>A null value, if a procedure name is specified.</p>
<tr><th>loop_variable</th>
<p>0, for the first iteration of a loop extracting data on all procedures.</p>
<td>An image item that specifies where to begin the search in the procedure dictionary. Because each invocation of <var>$LstProc</var> returns information for only one procedure, this variable is used to control repeated <var>$LstProc</var> calls. The loop variable must be the first item in the image. The variable can have one of the following values:
<p>The value of loop variable returned by the previous iteration through the loop, if data for the next procedure in the procedure dictionary is being requested. </p>
<p>You must not modify loop variable once it is initially set to 0; modifications might result in snaps. A loop variable must be specified if one of the following conditions exist:</p>
<p>A procname argument is not specified.</p>
<p>The alias flag argument has a value of 1 (aliases is retrieved). </p>
<ul>
<ul>
<li>flag (optional) specifies that alias names should be obtained for the specified procedure. The value for the alias flag is 1 to obtain aliases. One alias is returned for each $LSTPROC execution. </li>
<li>A null value, if a procedure name is specified.</li>
</li>
<li>0, for the first iteration of a loop extracting data on all procedures.</li>
<li>filename (optional) specifies the name of the file or group that contains the procedure dictionary. If this argument is omitted, the current file at the time that the request was compiled is used. </li>
<li>The value of <var class="term">loop_variable</var> returned by the previous iteration through the loop, if data for the next procedure in the procedure dictionary is being requested. </li>
</li>
<li>pattern (optional) lets you retrieve procedures that match <var class="term">pattern</var>, conforming to the syntax of [[Is Like pattern matching|Is Like patterns]].</li>
</li>
</ul>
</ul>
<b>Status codes</b>
<p>
<p>In addition to storing procedure information in an image, $LSTPROC returns a status code that has one of these values: </p>
You must not modify <var class="term">loop_variable</var> once it is initially set to 0; modifications might result in snaps. A loop variable must be specified if one of the following conditions exist:</p>
<p>
A <var class="term">procname</var> argument is not specified.</p>
<p>
The <var class="term">alias_flag</var> argument has a value of 1 (aliases is retrieved). </p></td></tr>
 
<tr><th>alias_flag</th>
<td>This optional argument specifies that alias names should be obtained for the specified procedure. The value for the alias flag is 1 to obtain aliases. One alias is returned for each <var>$LstProc</var> execution. </td></tr>
 
<tr><th>filename</th>
<td>This optional argument specifies the name of the file or group that contains the procedure dictionary. If this argument is omitted, the current file at the time that the request was compiled is used. </td></tr>
 
<tr><th>pattern</th>
<td>This optional argument lets you retrieve procedures that match <var class="term">pattern</var>, conforming to the syntax of [[Is Like pattern matching|Is Like patterns]]. </td></tr>
</table>
 
===Status codes===
<p>In addition to storing procedure information in an image, <var>$LstProc</var> returns a status code that has one of these values: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 120: Line 142:
<th>Meaning</th>
<th>Meaning</th>
</tr>
</tr>
<tr>
<tr>
<td align="right">0</td>
<td>0</td>
<td>$LSTPROC executed successfully.</td>
<td><var>$LstProc</var> executed successfully. </td>
</tr>
</tr>
<tr>
<tr>
<td align="right">1</td>
<td>1</td>
<td>The end of the procedure dictionary has been reached (there are no more procedure names to process).</td>
<td>The end of the procedure dictionary has been reached (there are no more procedure names to process). </td>
</tr>
</tr>
<tr>
<tr>
<td align="right">2</td>
<td>2</td>
<td>The specified procedure is not available.</td>
<td>The specified procedure is not available. </td>
</tr>
</tr>
<tr>
<tr>
<td align="right">4</td>
<td>4</td>
<td>An error was encountered during $LSTPROC processing. </td>
<td>An error was encountered during <var>$LstProc</var> processing. </td>
</tr>
</tr>
</table>
</table>
<b>Usage notes</b>
 
==Usage notes==
<ul>
<ul>
<li>For files created prior to Release 8.1, only the procedure name and security class are provided. An image must be defined earlier in the request in order to receive the information returned by $LSTPROC. For more information on image definition, refer to [[Images#Defining an image|Defining an image]].</li>
<li>An image must be defined earlier in the request in order to receive the information returned by <var>$LstProc</var>. For more information on image definition, refer to [[Images#Defining an image|Defining an image]].</li>
</li>
 
<li>$LSTPROC applies to local files only; it is not valid in remote context.</li>
<li>For files with a <var>FICREATE</var> value of 2 or less, only the procedure name and security class are provided.</li>
</li>
<li>For a file with a procedure stored in it that was created using Model V3R2.1 or later, then opened under <var class="product">Model&nbsp;204</var> V4R1.0 or later with $SYSDATE set to January 1, 2000 (or later), and the procedure is changed, the date returned includes the century--in this example, 100001, in the cyyddd format.</li>
<li><var>$LstProc</var> applies to local files only; it is not valid in remote context. </li>
</li>
 
<li>For a file with a procedure stored in it that was created using Model&nbsp;204 V3R2.1 or later, then opened under <var class="product">Model&nbsp;204</var> V4R1.0 or later with <var>$SysDate</var> set to January 1, 2000 (or later), and the procedure is changed, the date returned includes the century &mdash; in this example, 100001, in the cyyddd format. </li>
</ul>
</ul>
==Examples==
<b>Example 1</b>
<b>Example 1</b>
<p>This request retrieves and prints all procedure names in the current file:</p>
<p>
This request retrieves and prints all procedure names in the current file:</p>
<p class="code">BEGIN
<p class="code">BEGIN
     IMAGE PROC
     IMAGE PROC
Line 166: Line 197:
</p>
</p>
<b>Example 2</b>
<b>Example 2</b>
<p>This request retrieves alias names for a specified procedure:</p>
<p>
This request retrieves alias names for a specified procedure:</p>
<p class="code">IMAGE PROCINFO
<p class="code">IMAGE PROCINFO
     LOOPVAR IS BINARY LEN 4
     LOOPVAR IS BINARY LEN 4
Line 191: Line 223:
</p>
</p>
<b>Example 3</b>
<b>Example 3</b>
<p>This request retrieves procedures in a multiple procfile group that match a pattern specified by the user:</p>
<p>
This request retrieves procedures in a multiple procfile group that match a pattern specified by the user:</p>
<p class="code">BEGIN
<p class="code">BEGIN
IMAGE PROCS
IMAGE PROCS
Line 221: Line 254:
END PROCEDURE   
END PROCEDURE   
</p>
</p>
[[Category:SOUL $functions]]
[[Category:SOUL $functions]]

Latest revision as of 18:27, 15 June 2018

$LstProc returns the following procedure information, which is stored in the procedure dictionary:

  • Procedure name
  • Date and time of last update
  • ID of last user to update the procedure
  • Length of the procedure (in bytes)
  • Procedure security class (if available)
  • Procedure file (if in multiple procedure file group context)


Syntax

The format of the $LstProc function is:

$LstProc(imagename, [procname] [, loop_variable] [, alias_flag] [, filename] [, pattern])

Syntax terms

imagename This required argument specifies the name of the image into which the information should be returned. The items that must be defined in the image are listed below, along with the data type and length of each item. In addition, the position of each item is provided for use with the AT clause where applicable.
Item Type Length Position
loop_variable BINARY 4 1
Date PACKED 4 5
Time STRING 8 9
Length BINARY 4 17
Security class BINARY 1 21
Procedure name STRING 209 22
Procedure file name STRING 8  
User ID STRING 10  

For example:

IMAGE PROCS LOOPVAR IS BINARY LEN 4 DATE IS PACKED LEN 4 TIME IS STRING LEN 8 LENGTH IS BINARY LEN 4 CLASS IS BINARY LEN 1 NAME IS STRING LEN 255 FILE IS STRING LEN 8 USERID IS STRING LEN 10 END IMAGE

The procedure file name and the user ID are both optional. If they are not specified, they are not filled in by default values. If the user ID is included, however, the file name must also be included.

If the image length is not increased, $LstProc executes when multiple procedure files have been specified, but does not return file information for each procedure or the user ID.

procname The procedure for which information should be obtained. The value of procname must be the name of a permanent procedure. If this argument is omitted or null, information about the next procedure is returned. You must specify this argument if the alias_flag argument has a value of 1.
loop_variable An image item that specifies where to begin the search in the procedure dictionary. Because each invocation of $LstProc returns information for only one procedure, this variable is used to control repeated $LstProc calls. The loop variable must be the first item in the image. The variable can have one of the following values:
  • A null value, if a procedure name is specified.
  • 0, for the first iteration of a loop extracting data on all procedures.
  • The value of loop_variable returned by the previous iteration through the loop, if data for the next procedure in the procedure dictionary is being requested.

You must not modify loop_variable once it is initially set to 0; modifications might result in snaps. A loop variable must be specified if one of the following conditions exist:

A procname argument is not specified.

The alias_flag argument has a value of 1 (aliases is retrieved).

alias_flag This optional argument specifies that alias names should be obtained for the specified procedure. The value for the alias flag is 1 to obtain aliases. One alias is returned for each $LstProc execution.
filename This optional argument specifies the name of the file or group that contains the procedure dictionary. If this argument is omitted, the current file at the time that the request was compiled is used.
pattern This optional argument lets you retrieve procedures that match pattern, conforming to the syntax of Is Like patterns.

Status codes

In addition to storing procedure information in an image, $LstProc returns a status code that has one of these values:

Status code Meaning
0 $LstProc executed successfully.
1 The end of the procedure dictionary has been reached (there are no more procedure names to process).
2 The specified procedure is not available.
4 An error was encountered during $LstProc processing.

Usage notes

  • An image must be defined earlier in the request in order to receive the information returned by $LstProc. For more information on image definition, refer to Defining an image.
  • For files with a FICREATE value of 2 or less, only the procedure name and security class are provided.
  • $LstProc applies to local files only; it is not valid in remote context.
  • For a file with a procedure stored in it that was created using Model 204 V3R2.1 or later, then opened under Model 204 V4R1.0 or later with $SysDate set to January 1, 2000 (or later), and the procedure is changed, the date returned includes the century — in this example, 100001, in the cyyddd format.

Examples

Example 1

This request retrieves and prints all procedure names in the current file:

BEGIN IMAGE PROC LOOPVAR IS BINARY LEN 4 DATE IS PACKED LEN 4 TIME IS STRING LEN 8 LENGTH IS BINARY LEN 4 CLASS IS BINARY LEN 1 NAME IS STRING LEN 255 FILE IS STRING LEN 8 USERID IS STRING LEN 10 END IMAGE PREPARE PROC REPEAT WHILE $LSTPROC('PROC',,%PROC:LOOPVAR) = 0 PRINT %PROC:NAME END REPEAT END

Example 2

This request retrieves alias names for a specified procedure:

IMAGE PROCINFO LOOPVAR IS BINARY LEN 4 DATE IS PACKED LEN 4 TIME IS STRING LEN 8 LENGTH IS BINARY LEN 4 CLASS IS BINARY LEN 1 NAME IS STRING LEN 255 FILE IS STRING LEN 8 USERID IS STRING LEN 10 END IMAGE . . . %PROCINFO:LOOPVAR = 0 GETALIAS: IF $LSTPROC('PROCINFO','MYPROC',%PROCINFO:LOOPVAR,1) = 0 THEN PRINT %PROCINFO:NAME END IF . . .

Example 3

This request retrieves procedures in a multiple procfile group that match a pattern specified by the user:

BEGIN IMAGE PROCS LOOPVAR IS BINARY LEN 4 DATE IS PACKED LEN 4 TIME IS STRING LEN 8 LENGTH IS BINARY LEN 4 CLASS IS BINARY LEN 1 NAME IS STRING LEN 255 FILE IS STRING LEN 8 USERID IS STRING LEN 10 END IMAGE %PAT = '??PAT' NEW PAGE PREPARE PROCS PRINT ' PROCEDURE NAME DATE TIME LENGTH - USERID CLASS' WITH ' FILE' REPEAT WHILE $LSTPROC('PROCS',,%PROCS:LOOPVAR) = 0 IF %PROCS:NAME IS LIKE %PAT THEN %DATE = $DATECNV('YYDDD','MM/DD/YY',%PROCS:DATE) PRINT %PROCS:NAME AND %DATE AT 25 AND %PROCS:TIME - AND %PROCS:LENGTH TO 50 AND %PROCS:USERID AT 52 - AND %PROCS:CLASS AT 68 - AND %PROCS:FILE AT 63 END IF END REPEAT PRINT '-- END OF LIST FOR PATTERN = ' %PAT END END PROCEDURE