$RdProc: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<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 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>
<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>
The $RDPROC function sequentially retrieves the lines of a procedure that is stored in a <var class="product">Model&nbsp;204</var> 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 <var>[[Managing file groups#CREATE GROUP command and the types of groups|CREATE GROUP]]</var> command.</p>
<p>$RDPROC applies to local files only; it is not valid in remote context.</p>
<p>
<b>Options</b>
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. </p>
<p>The four options for $RDPROC are: </p>
<p>
<var>$RDPROC</var> applies to local files only; it is not valid in remote context.</p>
 
==Syntax==
<p>
The four options for <var>$RDPROC</var> are: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 11: Line 16:
<th>Action</th>
<th>Action</th>
</tr>
</tr>
<tr>
<tr>
<td>OPEN</td>
<td>OPEN</td>
<td>Locates and locks a procedure</td>
<td>Locates and locks a procedure</td>
</tr>
</tr>
<tr>
<tr>
<td>GET</td>
<td>GET</td>
<td>Reads a line from a procedure</td>
<td>Reads a line from a procedure</td>
</tr>
</tr>
<tr>
<tr>
<td>CLOSE</td>
<td>CLOSE</td>
<td>Explicitly unlocks the procedure at any time</td>
<td>Explicitly unlocks the procedure at any time</td>
</tr>
</tr>
<tr>
<tr>
<td>LINEND</td>
<td>LINEND</td>
Line 29: Line 38:
</table>
</table>
<b>Single request</b>
<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>
<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>
You must open and read a procedure within one request, without leaving the request. If the procedure is a permanent procedure, <var>$RDPROC</var> holds a share lock on the procedure while reading it, which prevents other users from modifying the procedure. <var>$RDPROC</var> unlocks the procedure automatically when it reads end-of-procedure. </p>
<b>Syntax for locating and locking a procedure</b>
<p>
<p>The format for the $RDPROC function to locate and lock a procedure is:</p>
The <var>$RDPROC</var> function uses 336 bytes of STBL and 8 bytes per <var>$RDPROC</var> level. You can nest <var>$RDPROC</var> up to the value of the MAXINCL parameter, plus one.</p>
<p class="code">ctlid = $RDPROC('OPEN', fgname, procname)  
 
===Syntax for locating and locking a procedure===
<p>The format for the <var>$RDPROC</var> function to locate and lock a procedure is:</p>
<p class="syntax"><span class="term">ctlid</span> = $RDPROC('OPEN', <span class="term">fgname</span>, <span class="term">procname</span>)  
</p>
</p>
<p>where:</p>
<p>Where:</p>
<ul>
<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><var class="term">ctlid</var> 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>
<li><var class="term">fgname</var> is a name of the file or group that contains the procedure. The format of <var class="term">fgname</var> is:
<p class="code">[[[TEMP | PERM] GROUP] | [FILE]] identifier
<p class="syntax">[[[TEMP | PERM] GROUP] | [FILE]] <span class="term">identifier</span>
</p>
</p>
<p>where identifier is the name of the group or file.</p>
<p>
</li>
where <var class="term">identifier</var> is the name of the group or file.</p>
<li>procname is the name of a procedure. </li>
</li>
</li>
<li><var class="term">procname</var> is the name of a procedure. </li>
</ul>
</ul>
<p class="note"><b>Note:</b> With $RDPROC, you can open up to six procedures concurrently. </p>
<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>
====$RDPROC and temporary procedures====
<p class="code">text = $RDPROC('GET',ctlid)  
<p>
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:</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>
 
<blockquote class="note">
<p><b>Note:</b>
If you attempt to open an empty temporary procedure, <code>$STATUS</code> 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>
</blockquote>
 
===Syntax for reading a line from a procedure===
<p>
The format for the <var>$RDPROC</var> function to read a line from a procedure is:</p>
<p class="code"><span class="term">text</span> = $RDPROC('GET', <span class="term">ctlid</span>)  
</p>
</p>
<p>where:</p>
<p>
Where:</p>
<ul>
<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><var class="term">text</var> is the next line of the procedure.  (<var class="term">text</var> is set to null when end-of-procedure is reached; however, since procedure lines can be null, always check <var>[[$Status]]</var> to determine end-of-procedure.)</li>
</li>
<li>ctlid is the integer ID of an internally maintained control ID that is assigned during OPEN processing.</li>
<li><var class="term">ctlid</var> is the integer ID of an internally maintained control ID that is assigned during OPEN processing.</li>
</li>
</ul>
</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>
===Syntax for closing and unlocking a procedure===
<p class="code">text = $RDPROC('CLOSE',ctlid)  
<p>
The format for the <var>$RDPROC</var> function to close and unlock a procedure is:</p>
<p class="syntax"><span class="term">text</span> = $RDPROC('CLOSE', <span class="term">ctlid</span>)  
</p>
</p>
<p>where:</p>
<p>
Where:</p>
<ul>
<ul>
<li>text is set to the null string. </li>
<li><var class="term">text</var> 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><var class="term">ctlid</var> is the integer ID of an internally maintained control ID that is assigned during OPEN processing.</li>
</li>
</ul>
</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>
===Syntax for reading a line end from a procedure===
<p class="code">text = $RDPROC('LINEND',ctlid)  
<p>
The format for the <var>$RDPROC</var> function to read a line-end character from a procedure is:</p>
<p class="syntax"><span class="term">text</span> = $RDPROC('LINEND', <span class="term">ctlid</span>)  
</p>
</p>
<p>where:</p>
<p>
Where:</p>
<ul>
<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><var class="term">text</var> is the value of the line-end character parameter in effect when the procedure was saved. By default, this is a semicolon (<tt>;</tt>). </li>
</li>
 
<li>ctlid is the integer ID of an internally maintained control ID that is assigned during OPEN processing.</li>
<li><var class="term">ctlid</var> is the integer ID of an internally maintained control ID that is assigned during OPEN processing.</li>
</li>
</ul>
</ul>
<b>How $RDPROC works</b>
 
<p>Possible return status settings are summarized in this table: </p>
==Status settings==
<p>
Possible return (<var>$Status</var>) settings are summarized in this table: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 88: Line 136:
<th>Meaning</th>
<th>Meaning</th>
</tr>
</tr>
<tr>
<tr>
<td align="right">0</td>
<td align="right">0</td>
<td>Normal completion (a procedure line was read; more lines follow)</td>
<td>Normal completion (a procedure line was read; more lines follow)</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">1</td>
<td align="right">1</td>
<td>End-of-procedure reached (no more procedure lines exist)</td>
<td>End-of-procedure reached (no more procedure lines exist)</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">2</td>
<td align="right">2</td>
<td>Error occurred (see $STATUSD settings)</td>
<td>Error occurred (see [[#$StatusD setting|$StatusD settings]])</td>
</tr>
</tr>
</table>
</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>
<p class="code">$STATUS=2 / $STATUSD=11 (invalid ctlid value)     
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>
</p>
<b>$STATUSD setting</b>
 
<p>The STATUSD setting can be one of the settings summarized in the following table:</p>
====$StatusD setting====
<p>
The <var>$StatusD</var> setting can be one of the settings summarized in the following table:</p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 115: Line 169:
<td>Argument 1 is missing or null.</td>
<td>Argument 1 is missing or null.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">2</td>
<td align="right">2</td>
<td>Argument 2 is missing or null.</td>
<td>Argument 2 is missing or null.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">3</td>
<td align="right">3</td>
<td>Argument 3 is missing or null</td>
<td>Argument 3 is missing or null</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">4</td>
<td align="right">4</td>
<td>Argument 1 must be OPEN, GET, CLOSE, or LINEND.</td>
<td>Argument 1 must be OPEN, GET, CLOSE, or LINEND.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">5</td>
<td align="right">5</td>
<td>Invalid context specification in argument.</td>
<td>Invalid context specification in argument.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">6</td>
<td align="right">6</td>
<td>GROUP has no procedure file.</td>
<td>GROUP has no procedure file.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">7</td>
<td align="right">7</td>
<td>Could not lock on specified procedure.</td>
<td>Could not lock on specified procedure.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">8</td>
<td align="right">8</td>
<td>Could not find procedure or access not allowed.</td>
<td>Could not find procedure or access not allowed.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">9</td>
<td align="right">9</td>
<td>(unassigned)</td>
<td>(unassigned)</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">10</td>
<td align="right">10</td>
<td>Maximum number of procedures (five) are already open.</td>
<td>Maximum number of procedures (five) are already open.</td>
</tr>
</tr>
<tr>
<tr>
<td align="right">11</td>
<td align="right">11</td>
Line 156: Line 220:
</tr>
</tr>
</table>
</table>
<b>Example</b>
 
==Example==
<p class="code">BEGIN
<p class="code">BEGIN
DECLARE %PROC  IS STRING LEN 50  
DECLARE %PROC  IS STRING LEN 50  
Line 207: Line 272:
END
END
</p>
</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]]
[[Category:SOUL $functions]]

Latest revision as of 19:21, 29 July 2014

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