$RdProc: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(4 intermediate revisions by 2 users not shown)
Line 2: Line 2:


<p>
<p>
The $RDPROC function sequentially retrieves the lines of a [[SOUL]] procedure that is stored in a <var class="product">Model&nbsp;204</var> file. The lines of the SOUL 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>[[DEFINE GROUP command|DEFINE GROUP]]</var> command.</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>
<p>
You can also read temporary procedures, which do not necessarily 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>
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>
<p>
<var>$RDPROC</var> applies to local files only; it is not valid in remote context.</p>
<var>$RDPROC</var> applies to local files only; it is not valid in remote context.</p>
Line 43: Line 43:
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>
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>


====Syntax for locating and locking a procedure====
===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>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 class="syntax"><span class="term">ctlid</span> = $RDPROC('OPEN', <span class="term">fgname</span>, <span class="term">procname</span>)  
Line 63: Line 63:
<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>


====Syntax for reading a line from a procedure====
====$RDPROC and temporary procedures====
<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>
<p>
The format for the <var>$RDPROC</var> function to read a line from a procedure is:</p>
The format for the <var>$RDPROC</var> function to read a line from a procedure is:</p>
Line 71: Line 97:
Where:</p>
Where:</p>
<ul>
<ul>
<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><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><var class="term">ctlid</var> 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>
</ul>
</ul>


====Syntax for closing and unlocking a procedure====
===Syntax for closing and unlocking a procedure===
<p>
<p>
The format for the <var>$RDPROC</var> function to close and unlock a procedure is:</p>
The format for the <var>$RDPROC</var> function to close and unlock a procedure is:</p>
Line 89: Line 115:
</ul>
</ul>


====Syntax for reading a line end from a procedure====
===Syntax for reading a line end from a procedure===
<p>
<p>
The format for the <var>$RDPROC</var> function to read a line-end character from a procedure is:</p>
The format for the <var>$RDPROC</var> function to read a line-end character from a procedure is:</p>
Line 104: Line 130:
==Status settings==
==Status settings==
<p>
<p>
Possible return (<var>$STATUS</var>) settings are summarized in this table: </p>
Possible return (<var>$Status</var>) settings are summarized in this table: </p>
<table>
<table>
<tr class="head">
<tr class="head">
Line 123: Line 149:
<tr>
<tr>
<td align="right">2</td>
<td align="right">2</td>
<td>Error occurred (see [[#$STATUSD setting|$STATUSD settings]])</td>
<td>Error occurred (see [[#$StatusD setting|$StatusD settings]])</td>
</tr>
</tr>
</table>
</table>
<p>
<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>
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 class="code">$Status=2 / $StatusD=11 (invalid ctlid value)     
</p>
</p>


====$STATUSD setting====
====$StatusD setting====
<p>
<p>
The <var>$STATUSD</var> setting can be one of the settings summarized in the following table:</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 195: Line 221:
</table>
</table>


==Examples==
==Example==
<p class="code">BEGIN
<p class="code">BEGIN
DECLARE %PROC  IS STRING LEN 50  
DECLARE %PROC  IS STRING LEN 50  
Line 246: Line 272:
END
END
</p>
</p>
===$RDPROC and temporary procedures===
<p>
Using <var>$RDPROC</var>, 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>
<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>


[[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