$ProcOpn

From m204wiki
Revision as of 16:53, 23 November 2016 by Dme (talk | contribs) (→‎Usage notes)
Jump to navigation Jump to search

Open procedure for $ProcDat, $ProcGet, $ProcLoc

Note: Most Sirius $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 User Language procedure via $ProcGet, $ProcDat and $ProcLoc.

$ProcOpn accepts three arguments and returns a numeric code, and it is a callable $function.

The first argument is required and identifies the User Language procedure to be opened.

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.

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.

Syntax

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

%result is set to indicate the success of the function.

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 them.
  • If a 'temporary request' (a negative number or zero) is specified which does not exist (this includes numbers outside the range of the NORQS parameter) can produce an error condition. For example:

    $procOpn(-9999)

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

    M204.1186: Bad previous request number

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

    Beware, however, that 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