$RdProc
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:
- procname is the name of a procedure.
[[[TEMP | PERM] GROUP] | [FILE]] identifier
where identifier is the name of the group or file.
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 (null if end-of-procedure is reached).
- 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