$LstProc: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (misc formatting)
 
(One intermediate revision by one other user not shown)
Line 18: Line 18:
<p>
<p>
The format of the <var>$LstProc</var> function is:</p>
The format of the <var>$LstProc</var> function is:</p>
<p class="code">$LstProc(<span class="term">imagename</span>, [<span class="term">procname</span>] [, <span class="term">loop_variable</span>]
<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>])  
        [, <span class="term">alias_flag</span>] [, <span class="term">filename</span>] [, <span class="term">pattern</span>])  
</p>
</p>


===Syntax terms===
===Syntax terms===
<ul>
<table>
<li><var class="term">imagename</var> (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 <var>AT</var> clause where applicable.   
<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 36: Line 37:
<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>


Line 43: Line 44:
<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>


Line 50: Line 51:
<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>


Line 57: Line 58:
<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>


Line 64: Line 65:
<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>


Line 71: Line 72:
<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>


Line 78: Line 79:
<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>
Line 85: Line 86:
<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>
Line 105: Line 106:
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>
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, <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></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><var class="term">procname</var> is 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.</li>
<tr><th>procname</th>
<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>


<li><var class="term">loop_variable</var> is 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:
<tr><th>loop_variable</th>
<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:
<ul>
<ul>
<li>A null value, if a procedure name is specified.</li>
<li>A null value, if a procedure name is specified.</li>
Line 120: Line 123:
A <var class="term">procname</var> argument is not specified.</p>
A <var class="term">procname</var> argument is not specified.</p>
<p>
<p>
The <var class="term">alias_flag</var> argument has a value of 1 (aliases is retrieved). </p>
The <var class="term">alias_flag</var> argument has a value of 1 (aliases is retrieved). </p></td></tr>


<li><var class="term">alias_flag</var> (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 <var>$LstProc</var> execution. </li>
<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>


<li><var class="term">filename</var> (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>
<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>


<li><var class="term">pattern</var> (optional) lets you retrieve procedures that match <var class="term">pattern</var>, conforming to the syntax of [[Is Like pattern matching|Is Like patterns]].
<tr><th>pattern</th>
</li>
<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>
</ul>
</table>


===Status codes===
===Status codes===
Line 139: Line 144:


<tr>
<tr>
<td align="right">0</td>
<td>0</td>
<td><var>$LstProc</var>C 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 <var>$LstProc</var> processing. </td>
<td>An error was encountered during <var>$LstProc</var> processing. </td>
</tr>
</tr>
Line 161: Line 166:
==Usage notes==
==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 <var>$LstProc</var>. 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><var>$LstProc</var> 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><var>$LstProc</var> applies to local files only; it is not valid in remote context. </li>


<li>For a file with a procedure stored in it that was created using Model 204 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 &mdash; in this example, 100001, in the cyyddd format.</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>



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