View source for $RdProc

<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $RDPROC, recommended for manipulating procedure text, is <var>[[AppendOpenProcedure (Stringlist function)|appendOpenProcedure]]</var>.</p>

<p>The $RDPROC function sequentially retrieves the lines of a User Language procedure that is stored in a <var class="product">Model&nbsp;204</var> 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.</p>
<p>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.</p>
<p>$RDPROC applies to local files only; it is not valid in remote context.</p>
<b>Options</b>
<p>The four options for $RDPROC are: </p>
<table>
<tr class="head">
<th>Option</th>
<th>Action</th>
</tr>
<tr>
<td>OPEN</td>
<td>Locates and locks a procedure</td>
</tr>
<tr>
<td>GET</td>
<td>Reads a line from a procedure</td>
</tr>
<tr>
<td>CLOSE</td>
<td>Explicitly unlocks the procedure at any time</td>
</tr>
<tr>
<td>LINEND</td>
<td>Reads a line end character from a procedure </td>
</tr>
</table>
<b>Single request</b>
<p>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. </p>
<p>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.</p>
<b>Syntax for locating and locking a procedure</b>
<p>The format for the $RDPROC function to locate and lock a procedure is:</p>
<p class="code">ctlid = $RDPROC('OPEN', fgname, procname) 
</p>
<p>where:</p>
<ul>
<li>ctlid is the integer ID of an internally maintained control field that is passed into $RDPROC for GET, LINEND, and CLOSE processing.</li>
</li>
<li>fgname is a name of the file or group that contains the procedure. The format of fgname is:</li>
<p class="code">[[[TEMP | PERM] GROUP] | [FILE]] identifier
</p>
<p>where identifier is the name of the group or file.</p>
</li>
<li>procname is the name of a procedure. </li>
</li>
</ul>
<p class="note"><b>Note:</b> With $RDPROC, you can open up to six procedures concurrently. </p>
<b>Syntax for reading a line from a procedure</b>
<p>The format for the $RDPROC function to read a line from a procedure is:</p>
<p class="code">text = $RDPROC('GET',ctlid) 
</p>
<p>where:</p>
<ul>
<li>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)</li>
</li>
<li>ctlid is the integer ID of an internally maintained control ID that is assigned during OPEN processing.</li>
</li>
</ul>
<b>Syntax for closing and unlocking a procedure</b>
<p>The format for the $RDPROC function to close and unlock a procedure is:</p>
<p class="code">text = $RDPROC('CLOSE',ctlid) 
</p>
<p>where:</p>
<ul>
<li>text is set to the null string. </li>
</li>
<li>ctlid is the integer ID of an internally maintained control ID that is assigned during OPEN processing.</li>
</li>
</ul>
<b>Syntax for reading a line end from a procedure</b>
<p>The format for the $RDPROC function to read a line-end character from a procedure is:</p>
<p class="code">text = $RDPROC('LINEND',ctlid) 
</p>
<p>where:</p>
<ul>
<li>text is the value of the line-end character parameter in effect when the procedure was saved. By default, this is a semicolon (;). </li>
</li>
<li>ctlid is the integer ID of an internally maintained control ID that is assigned during OPEN processing.</li>
</li>
</ul>
<b>How $RDPROC works</b>
<p>Possible return status settings are summarized in this table: </p>
<table>
<tr class="head">
<th>Setting</th>
<th>Meaning</th>
</tr>
<tr>
<td align="right">0</td>
<td>Normal completion (a procedure line was read; more lines follow)</td>
</tr>
<tr>
<td align="right">1</td>
<td>End-of-procedure reached (no more procedure lines exist)</td>
</tr>
<tr>
<td align="right">2</td>
<td>Error occurred (see $STATUSD settings)</td>
</tr>
</table>
<p>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: </p>
<p class="code">$STATUS=2 / $STATUSD=11 (invalid ctlid value)    
</p>
<b>$STATUSD setting</b>
<p>The STATUSD setting can be one of the settings summarized in the following table:</p>
<table>
<tr class="head">
<th>Setting</th>
<th>Meaning</th>
</tr>
<tr>
<td align="right">1</td>
<td>Argument 1 is missing or null.</td>
</tr>
<tr>
<td align="right">2</td>
<td>Argument 2 is missing or null.</td>
</tr>
<tr>
<td align="right">3</td>
<td>Argument 3 is missing or null</td>
</tr>
<tr>
<td align="right">4</td>
<td>Argument 1 must be OPEN, GET, CLOSE, or LINEND.</td>
</tr>
<tr>
<td align="right">5</td>
<td>Invalid context specification in argument.</td>
</tr>
<tr>
<td align="right">6</td>
<td>GROUP has no procedure file.</td>
</tr>
<tr>
<td align="right">7</td>
<td>Could not lock on specified procedure.</td>
</tr>
<tr>
<td align="right">8</td>
<td>Could not find procedure or access not allowed.</td>
</tr>
<tr>
<td align="right">9</td>
<td>(unassigned)</td>
</tr>
<tr>
<td align="right">10</td>
<td>Maximum number of procedures (five) are already open.</td>
</tr>
<tr>
<td align="right">11</td>
<td>Ctlid contains an invalid value.</td>
</tr>
</table>
<b>Example</b>
<p class="code">BEGIN
DECLARE %PROC   IS STRING LEN 50 
<b></b>* 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 
<b></b>*
<b></b>* FILE MUST BE PREVIOUSLY OPENED
<b></b>*
            %FILE = $READ('FILE/GROUP CONTEXT?')
            %PROC = $READ('PROCEDURE NAME?') 
<b></b>*
<b></b>* OPEN THE PROCEDURE 
<b></b>*
            %CTLID = $RDPROC ('OPEN', %FILE, %PROC)
            IF $STATUS > 0 THEN
               PRINT '$RDPROC OPEN ERROR, REASON CODE=' -
               AND $STATUSD
               STOP
            END IF 
<b></b>*
<b></b>* DETERMINE THE LINEND CHARACTER 
<b></b>*
            %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 
<b></b>*
<b></b>* DISPLAY THE PROCEDURE 
<b></b>*
            REPEAT WHILE $STATUS = 0
            %TEXT = $RDPROC ('GET', %CTLID)
            PRINT %TEXT
            END REPEAT  
<b></b>*
<b></b>* SEE IF WE ENDED ABNORMALLY 
<b></b>*
            IF $STATUS > 1 THEN 
              PRINT 'GET ERROR, REASON CODE=' AND $STATUSD
            END IF 
<b></b>*
<b></b>* CLOSE THE PROC (UNNECESSARY SINCE WE READ TO EOP) 
<b></b>*
            %TEXT = $RDPROC ('CLOSE', %CTLID)
END
</p>
<b>Opening an empty temporary procedure</b>
<p>If you attempt to open an empty temporary procedure, $STATUS returns a zero and issues the following error:</p>
<p class="code">M204.1172 PREVIOUS REQUEST NOT DEFINED
</p>
<p>The current request continues as normal. </p>
<b>$RDPROC and temporary procedures</b>
<p>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.</p>
<p class="code">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
</p>
[[Category:SOUL $functions]]