$RdProc

From m204wiki
Revision as of 17:56, 11 June 2014 by Mlarocca (talk | contribs)
Jump to navigation Jump to search

The $RDPROC function sequentially retrieves the lines of a User Language procedure that is stored in a Model 204 file. The lines of the User Language procedure can reside in a file or in a group. A group can contain a single procedure file or multiple procedure files. Multiple procedure files are searched in the order in which they appear in the DEFINE GROUP command.

You can also read temporary procedures by specifying the procedure number, for example, 0, -1, or -2, in place of the procedure name. An input file is not required.

$RDPROC applies to local files only; it is not valid in remote context.

Options

The four options for $RDPROC are:

Option Action
OPEN Locates and locks a procedure
GET Reads a line from a procedure
CLOSE Explicitly unlocks the procedure at any time
LINEND Reads a line end character from a procedure

Single request

You must open and read a procedure within one request, without leaving the request. If the procedure is a permanent procedure, $RDPROC holds a share lock on the procedure while reading it, which prevents other users from modifying the procedure. $RDPROC unlocks the procedure automatically when it reads end-of-procedure.

The $RDPROC function uses 336 bytes of STBL and 8 bytes per $RDPROC level. You can nest $RDPROC up to the value of the MAXINCL parameter, plus one.

Syntax for locating and locking a procedure

The format for the $RDPROC function to locate and lock a procedure is:

ctlid = $RDPROC('OPEN', fgname, procname)

where:

  • ctlid is the integer ID of an internally maintained control field that is passed into $RDPROC for GET, LINEND, and CLOSE processing.
  • fgname is a name of the file or group that contains the procedure. The format of fgname is:
  • [[[TEMP | PERM] GROUP] | [FILE]] identifier

    where identifier is the name of the group or file.

  • procname is the name of a procedure.

Note: With $RDPROC, you can open up to six procedures concurrently.

Syntax for reading a line from a procedure

The format for the $RDPROC function to read a line from a procedure is:

text = $RDPROC('GET',ctlid)

where:

  • text is the next line of the procedure. (text is set to null when End-Of-Procedure is reached; however, since procedure lines can be null, always check $STATUS to determine EOP)
  • ctlid is the integer ID of an internally maintained control ID that is assigned during OPEN processing.

Syntax for closing and unlocking a procedure

The format for the $RDPROC function to close and unlock a procedure is:

text = $RDPROC('CLOSE',ctlid)

where:

  • text is set to the null string.
  • ctlid is the integer ID of an internally maintained control ID that is assigned during OPEN processing.

Syntax for reading a line end from a procedure

The format for the $RDPROC function to read a line-end character from a procedure is:

text = $RDPROC('LINEND',ctlid)

where:

  • text is the value of the line-end character parameter in effect when the procedure was saved. By default, this is a semicolon (;).
  • ctlid is the integer ID of an internally maintained control ID that is assigned during OPEN processing.

How $RDPROC works

Possible return status settings are summarized in this table:

Setting Meaning
0 Normal completion (a procedure line was read; more lines follow)
1 End-of-procedure reached (no more procedure lines exist)
2 Error occurred (see $STATUSD settings)

If the completion status is 2 and indicates that an error occurred or that the EOP was read, the procedure is automatically closed. A subsequent $RDPROC CLOSE call is unnecessary and returns this message:

$STATUS=2 / $STATUSD=11 (invalid ctlid value)

$STATUSD setting

The STATUSD setting can be one of the settings summarized in the following table:

Setting Meaning
1 Argument 1 is missing or null.
2 Argument 2 is missing or null.
3 Argument 3 is missing or null
4 Argument 1 must be OPEN, GET, CLOSE, or LINEND.
5 Invalid context specification in argument.
6 GROUP has no procedure file.
7 Could not lock on specified procedure.
8 Could not find procedure or access not allowed.
9 (unassigned)
10 Maximum number of procedures (five) are already open.
11 Ctlid contains an invalid value.

Example

BEGIN DECLARE %PROC IS STRING LEN 50 * USE LEN 19 BELOW TO ALLOW FOR 'TEMP GROUP XXXXXXXX' DECLARE %FILE IS STRING LEN 19 DECLARE %TEXT IS STRING LEN 255 DECLARE %CTLID IS FIXED * * FILE MUST BE PREVIOUSLY OPENED * %FILE = $READ('FILE/GROUP CONTEXT?') %PROC = $READ('PROCEDURE NAME?') * * OPEN THE PROCEDURE * %CTLID = $RDPROC ('OPEN', %FILE, %PROC) IF $STATUS > 0 THEN PRINT '$RDPROC OPEN ERROR, REASON CODE=' - AND $STATUSD STOP END IF * * DETERMINE THE LINEND CHARACTER * %TEXT = $RDPROC ('LINEND', %CTLID) IF $STATUS > 0 THEN PRINT '$RDPROC LINEND ERROR, REASON CODE=' - AND $STATUSD STOP END IF PRINT 'LINEND CHARACTER = ' WITH %TEXT PRINT * * DISPLAY THE PROCEDURE * REPEAT WHILE $STATUS = 0 %TEXT = $RDPROC ('GET', %CTLID) PRINT %TEXT END REPEAT * * SEE IF WE ENDED ABNORMALLY * IF $STATUS > 1 THEN PRINT 'GET ERROR, REASON CODE=' AND $STATUSD END IF * * CLOSE THE PROC (UNNECESSARY SINCE WE READ TO EOP) * %TEXT = $RDPROC ('CLOSE', %CTLID) END

Opening an empty temporary procedure

If you attempt to open an empty temporary procedure, $STATUS returns a zero and issues the following error:

M204.1172 PREVIOUS REQUEST NOT DEFINED

The current request continues as normal.

$RDPROC and temporary procedures

Using $RDPROC, create a temporary procedure named -1 and print procedure -1 to procedure -2. In this example, the place for the input file name is blank (, ,) or NULL.

USE PROC -2 MONITOR BEGIN %CTLID = $RDPROC('OPEN',,-1) IF $STATUS THEN JUMP TO BAILOUT END IF REPEAT WHILE NOT $STATUS PRINT $RDPROC('GET',%CTLID) END REPEAT BAILOUT: END