$ProcOpn: Difference between revisions
(→Syntax) |
|||
| Line 15: | Line 15: | ||
<table> | <table> | ||
<tr><th>%result</th> | <tr><th>%result</th> | ||
<td>A numeric [[#retCodes|return code]] that indicates the success of the function. (Return codes are [[#retCodes|listed below]]) | <td>A numeric [[#retCodes|return code]] that indicates the success of the function. (Return codes are [[#retCodes|listed below]].)</td></tr> | ||
<tr><th>proc_name</th> | <tr><th>proc_name</th> | ||
Revision as of 23:11, 11 November 2017
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 (5) 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
0is 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 var>$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