$ProcOpn: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
No edit summary
 
(23 intermediate revisions by 4 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Open procedure for $ProcDat, $ProcGet, $ProcLoc</span>
<span class="pageSubtitle">Open procedure for $ProcDat, $ProcGet, $ProcLoc</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $ProcOpn function.</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $ProcOpn function.</p>


The <var>$ProcOpn</var> function is used to "open" a procedure as input to a <var class="product">User Language</var> procedure via [[$ProcGet]], [[$ProcDat]] and [[$ProcLoc]].  
The <var>$ProcOpn</var> function is used to "open" a procedure as input to a <var class="product">SOUL</var> procedure via <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedure]]</var> (or the deprecated <var>[[$ProcGet]]</var> and <var>[[$ProcDat]]</var>) or via <var>[[$ProcLoc]]</var>.  


<var>$ProcOpn</var> accepts three arguments and returns a numeric code. As of <var class="product">[[Sirius Mods]]</var> Version 6.8, it is a callable $function.
<var>$ProcOpn</var> accepts three arguments and returns a numeric code. It is also a [[Calling Sirius Mods $functions|callable]] $function.


The first argument is required and identifies the <var class="product">User Language</var> procedure to be opened.  
==Syntax==
<p class="syntax"><span class="term">%result</span> = <span class="literal">$ProcOpn</span>(<span class="term">proc_name</span>, [<span class="term">file_name</span>], <span class="term">inc_string</span>)
</p>
 
===Syntax terms===
<table>
<tr><th>%result</th>
<td>A numeric return code that indicates the success of the function.  (Return codes are [[#retCodes|listed below]].)</td></tr>
 
<tr><th>proc_name</th>
<td>This argument is required; it identifies the <var class="product">SOUL</var> procedure to be opened. </td></tr>


The second argument is an optional file name. If the second argument is not provided, or is a null string, the current file is used.
<tr><th>file_name</th>
<td>An optional file name. If this argument is not provided or is a null string, the current file is used. </td></tr>


The third argument is a string that is used by [[$ProcGet]] for dummy string substitution just as if this argument had been placed on an INCLUDE statement. Note that [[$ProcDat]] does no dummy string substitution.
<tr><th>inc_string</th>
<td>A string that is used by <var>$ProcGet</var> for dummy string substitution, just as if this argument had been placed on an <var>Include</var> statement.  
<p class="note"><b>Note:</b> <var>$ProcDat</var> does no dummy string substitution. </p>
</table>


For example, suppose procedure TIS_PITY in procedure file HOHO contains the line
===<b id="retCodes"></b>Return codes===
<p class="code"> FIND1: IN ?? FIND ALL RECORDS FOR WHICH
<p class="code">-1 - Current include level not opened by $ProcOpn
0 - Procedure opened without errors
1 - Procedure is locked for edit or delete
2 - Procedure does not exist or the current user does not have access privilege
3 - Specified procedure name is invalid (null)
4 - File name invalid, or no current file, or caller does not have sufficient
    privilege to display/include procedures
5 - The maximum number of open procedures ([[MAXINCL parameter|MAXINCL]]) has already been reached
6 - Insufficient space in ITBL to hold third argument; increase the size of ITBL
</p>
</p>


the sequence
==Usage notes==
<p class="code"> %RESULT = $ProcOpn('TIS_PITY', 'HOHO', -
<ul>
            ' THESE ARE ARGUMENTS')
<li>After <var>$ProcOpn</var> has successfully opened a procedure, <var>$ProcGet</var> and <var>$ProcDat</var> may be used to retrieve the procedure source lines, and <var>$ProcLoc</var> may be used to scan the lines. </li>
  %LINE = $ProcGet
 
<li>If a "temporary request" (a negative number or zero) is
specified for <var class="term">proc_name</var> that does not exist (this includes numbers
outside the range of the <var>[[NORQS parameter|NORQS]]</var> parameter), an error condition may result. For example:
   
<p class="code">$procOpn(-9999)
</p>
</p>
When the above fragment is executed, the following error occurs
(but the request continues to run):
<p class="code">M204.1186: Bad previous request number</p>
The value <code>0</code> is returned by <var>$ProcOpn</var>, and
the procedure is treated as an empty procedure. This probably
works properly for most applications.
<p class="note"><b>Beware:</b> If your application
passes such non-existing temporary request numbers to <var>$ProcOpn</var>,
your request may be subject to request cancellation due to
exceeding <var>[[ERMX parameter|ERMX]]</var>.</p></li>
</ul>


would result in %LINE being set to
==Examples==
<p class="code"> FIND1: IN THESE FIND ALL RECORDS FOR WHICH
Suppose procedure <code>TIS_PITY</code> in procedure file <code>HOHO</code> contains this line:
<p class="code">FIND1: IN ?? FIND ALL RECORDS FOR WHICH
</p>
</p>


==Syntax==
Then this sequence:
<p class="syntax"><section begin="syntax" />%result = $ProcOpn(proc_name, file_name, inc_string)
<p class="code">%result = $ProcOpn('TIS_PITY', 'HOHO', ' THESE ARE ARGUMENTS')    
<section end="syntax" /></p>
%line = $ProcGet
<p>
</p>
</p>
<p>%result is set to indicate the success of the function.</p>


<p class="code">  
Results in <code>%line</code> being set to:
-1 - Current include level not opened by $ProcOpn
<p class="code">FIND1: IN THESE FIND ALL RECORDS FOR WHICH
  0 - Procedure opened without errors
  1 - Procedure is locked for edit or delete
  2 - Procedure does not exist or the current user does not
          have access privilege
  3 - Specified procedure name is invalid (null)
  4 - File name invalid, or no current file, or caller
          does not have sufficient privilege to
          display/include procedures
  5 - The maximum number of open procedures (5)
          has already been reached
  6 - Insufficient space in ITBL to hold third
          argument; increase the size of ITBL
</p>
<p class="caption">$ProcOpn return codes
</p>
</p>


After <var>$ProcOpn</var> has successfully opened a procedure, [[$ProcGet]] and [[$ProcDat]] may be used to retrieve the procedure source lines and [[$ProcLoc]] may be used to scan them.
==Products authorizing {{PAGENAMEE}}==
 
<ul class="smallAndTightList">
<h2>Products authorizing {{PAGENAMEE}}</h2><ul class="smallAndTightList">
<li>[[Sirius Functions]]
<li>[[Sirius functions]]
<li>[[Fast/Unload SOUL Interface]]
<li>[[Fast/Unload User Language Interface]]
<li>[[Janus Web Server]]
<li>[[Janus Web Server]]
</ul>
</ul>
<p>
</p>


[[Category:$Functions|$ProcOpn]]
[[Category:$Functions|$ProcOpn]]

Latest revision as of 00:43, 10 May 2022

Open procedure for $ProcDat, $ProcGet, $ProcLoc

Note: Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $ProcOpn function.

The $ProcOpn function is used to "open" a procedure as input to a SOUL procedure via AppendOpenProcedure (or the deprecated $ProcGet and $ProcDat) or via $ProcLoc.

$ProcOpn accepts three arguments and returns a numeric code. It is also a callable $function.

Syntax

%result = $ProcOpn(proc_name, [file_name], inc_string)

Syntax terms

%result A numeric return code that indicates the success of the function. (Return codes are listed below.)
proc_name This argument is required; it identifies the SOUL procedure to be opened.
file_name An optional file name. If this argument is not provided or is a null string, the current file is used.
inc_string A string that is used by $ProcGet for dummy string substitution, just as if this argument had been placed on an Include statement.

Note: $ProcDat does no dummy string substitution.

Return codes

-1 - Current include level not opened by $ProcOpn 0 - Procedure opened without errors 1 - Procedure is locked for edit or delete 2 - Procedure does not exist or the current user does not have access privilege 3 - Specified procedure name is invalid (null) 4 - File name invalid, or no current file, or caller does not have sufficient privilege to display/include procedures 5 - The maximum number of open procedures (MAXINCL) has already been reached 6 - Insufficient space in ITBL to hold third argument; increase the size of ITBL

Usage notes

  • After $ProcOpn has successfully opened a procedure, $ProcGet and $ProcDat may be used to retrieve the procedure source lines, and $ProcLoc may be used to scan the lines.
  • If a "temporary request" (a negative number or zero) is specified for proc_name that does not exist (this includes numbers outside the range of the NORQS parameter), an error condition may result. For example:

    $procOpn(-9999)

    When the above fragment is executed, the following error occurs (but the request continues to run):

    M204.1186: Bad previous request number

    The value 0 is returned by $ProcOpn, and the procedure is treated as an empty procedure. This probably works properly for most applications.

    Beware: If your application passes such non-existing temporary request numbers to $ProcOpn, your request may be subject to request cancellation due to exceeding ERMX.

Examples

Suppose procedure TIS_PITY in procedure file HOHO contains this line:

FIND1: IN ?? FIND ALL RECORDS FOR WHICH

Then this sequence:

%result = $ProcOpn('TIS_PITY', 'HOHO', ' THESE ARE ARGUMENTS') %line = $ProcGet

Results in %line being set to:

FIND1: IN THESE FIND ALL RECORDS FOR WHICH

Products authorizing $ProcOpn