$RdProc

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $RDPROC, recommended for manipulating procedure text, is AppendOpenProcedure.

The $RDPROC function sequentially retrieves the lines of a procedure that is stored in a Model 204 file. The lines of the procedure can reside in a file or in a group (one or multiple procedure files). Multiple procedure files are searched in the order in which they appear in the CREATE GROUP command.

You can also read temporary procedures, which do not reside in an input file. In this case, you specify the procedure number, for example, 0, -1, or -2, in place of the procedure name.

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

Syntax

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.

$RDPROC and temporary procedures

For a temporary procedure, you specify a blank (, ,) or null for the file name, and you specify the procedure number in place of the procedure name. For example, to create a temporary procedure named -1, and print procedure -1 to procedure -2:

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

Note: 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.

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 end-of-procedure.)
• 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.

Status settings

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