$LstProc: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 102: Line 102:
<li>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. </li>
<li>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. </li>
</ul>
</ul>
<p>You must <b>not modify</b> the loop variable once it is initially set to 0; modifications might result in snaps. A loop variable <b>must</b> be specified if one of the following conditions exist:
<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>
<ul>
<p>A procname argument is not specified.</p>
<li>A procname argument is not specified.</li>
<p>The alias flag argument has a value of 1 (aliases is retrieved). </p>
<li>The alias flag argument has a value of 1 (aliases is retrieved). </li>
</ul>
</p>


<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>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>
Line 116: Line 113:
</li>
</li>
</ul>
</ul>
<b>Status codes</b>
===Status codes===
<p>In addition to storing procedure information in an image, $LSTPROC returns a status code that has one of these values: </p>
<p>In addition to storing procedure information in an image, $LSTPROC returns a status code that has one of these values: </p>
<table>
<table>
Line 140: Line 137:
</tr>
</tr>
</table>
</table>
==Usage notes==
<b>Usage notes</b>
<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>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>
Line 149: Line 146:
</li>
</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>

Revision as of 18:03, 18 August 2013

$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 (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.
  • 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 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.
  • 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:
    • 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).

  • 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.
  • 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.
  • pattern (optional) 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

  • 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 Defining an image.
  • $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 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