$LstProc

$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).

• alias_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	$LstProcC 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