ADD-SUPER-PROCEDURE( ) method

Associates a super procedure file with a procedure file or with the current ABL session. When a procedure file invokes an internal procedure or a user-defined function, ABL searches for it, among other places, in the super procedures (if any) of the procedure file and of the current ABL session. The procedure-search option determines which procedures are searched.

For more information on the rules that ABL uses to search for internal procedures and user-defined functions, see Search rules.

For a sample program that uses the ADD-SUPER-PROCEDURE method, see the reference entry for the RUN SUPER statement.

Returns FALSE for a Web service procedure.

Return type: LOGICAL

Applies to: Procedure object handle, SESSION system handle

Syntax

ADD-SUPER-PROCEDURE ( super-proc-hdl[ , proc-search ] )

super-proc-handle

The handle of a running persistent procedure that you want to make a super procedure of the local procedure or of the current ABL session.

ADD-SUPER-PROCEDURE returns FALSE if super-proc-hdl is not a valid handle, or if the AVM detects that the method was not successful. Otherwise, the method returns TRUE.

proc-search

Optional expression that determines which super procedures are searched when super-proc-hdl invokes RUN SUPER or the SUPER function. Valid values are SEARCH-SELF (or 1) or SEARCH-TARGET (or 2). The default, if there is no entry, is SEARCH-SELF. The search commences in the super procedure stack of super-proc-hdl.

Consider the following:

• SEARCH-SELF starts searching in the procedure file that initiated the current internal procedure or user-defined function.
• SEARCH-TARGET starts searching the super procedures of the procedure file that originally invoked the current internal procedure or user-defined function (the procedure with the original RUN statement). If the procedure was RUN . . . IN procedure-handle, SEARCH-TARGET searches the super procedures of procedure-handle.
• A given super-proc-hdl can be added as either SEARCH-TARGET or SEARCH-SELF, but cannot be added as both. If proc-search is set for a super-proc-hdl, then any attempt to change its value generates a run-time warning, but the ADD-SUPER-PROCEDURE( ) method succeeds. The warning message "Changing proc-search-string for procedure <.p-name> from <string> to <string>" is presented to indicate that the application is using an instance of a given super procedure in an inconsistent manner. This warning message can be suppressed by using the SESSION:SUPPRESS-WARNINGS-LIST attribute. In addition, the warning message can be avoided by creating two instances of super-proc-hdl, one identified as SEARCH-TARGET and the other identified as SEARCH-SELF.

Associating a super procedure with a procedure

The following example associates a super procedure with the current procedure:

THIS-PROCEDURE:ADD-SUPER-PROCEDURE(my-super-proc-hdl,SEARCH-SELF).

The following example:

• Associates a super procedure with a procedure that the current procedure is working for.
• Requests that the super procedure stack associated with local-proc-hdl be searched rather than the stack associated with my-super-proc-hdl when RUN SUPER is invoked in super-proc-hdl.

local-proc-hdl:ADD-SUPER-PROCEDURE(my-super-proc-hdl,SEARCH-TARGET).

The procedure to which you add a super procedure is called the local procedure of the super procedure.

Associating a super procedure with the current ABL session

The following example associates a super procedure with the current ABL session:

SESSION:ADD-SUPER-PROCEDURE(my-super-proc-hdl).

When you do this, the AVM automatically associates the super procedure with all the session's procedures—persistent and nonpersistent—without your having to change their code in any way. This technique lets you replace occurrences of the following:

THIS-PROCEDURE:ADD-SUPER-PROCEDURE(super-proc-hdl).

In individual procedures with a single occurrence of the following:

SESSION:ADD-SUPER-PROCEDURE(super-proc-hdl).

Super procedure stacking

You can associate multiple super procedures with a single local procedure or with the current ABL session. When you do this, the AVM stores (and later on, searches) the corresponding procedure handles in last in first out (LIFO) order—the handle of the most recently added super procedure first, the handle of the next most recently added super procedure second, etc.

A collection of super procedure handles associated with a local procedure or with the current ABL session is called a super procedure stack. The handle of the most recently added super procedure occupies the top of the stack.

If you add a super procedure that is already in the stack, the AVM removes the previous occurrence of the super procedure handle from the stack and adds the new occurrence to the top of the stack—all without reporting an error.

Super procedure chaining

You can add a super procedure to a super procedure. For example, imagine the following scenario:

1. A, B, and C are procedure files running persistently.
2. B is a super procedure of A.
3. C is a super procedure of B.

B is a super procedure (of A) and has a super procedure (C).

When you add a super procedure to a super procedure, the result is a super procedure chain, each link of which consists of two elements: a local procedure and its super procedure. When the AVM searches a super procedure chain, it does not proceed to the next link unless the current link's super procedure element explicitly invokes its super version (by using the RUN SUPER statement or the SUPER function).

For example, imagine the following scenario:

1. A, B, and C, and X are procedure files running persistently.
2. add-record is an internal procedure different versions of which reside in A, B, and C.
3. B is a super procedure of A.
4. C is a super procedure of B.
5. X says RUN add-record IN A.

The following events occur:

1. The AVM searches A for add-record and runs it if found.
2. If and only if A's add-record exists and says RUN SUPER, the AVM searches B for add-record and runs it if found.
   Note: If A does not contain add-record, the following events occur: If B contains add-record, the AVM runs it. If B does not contain add-record, the AVM does not search for add-record in C.
3. If and only if B's add-record exists and says RUN SUPER, the AVM searches C for add-record and runs it if found.

In this way, the AVM avoids excessive and possibly circular searching.

Search rules

The AVM searches for internal procedures and user-defined functions depending on how the internal procedure or user-defined function is invoked. The search rules illustrated in the first three cases assume that all the super procedures were added with no proc-search value or with a proc-search value of SEARCH-SELF. The fourth case illustrates the search process when a super procedure is added with a proc-search value of SEARCH-TARGET.

Case 1: When the AVM encounters a statement like the following:

RUN add-record('Customer').

The AVM searches for add-record as follows:

1. As an internal procedure in the local procedure
2. As an internal procedure in a super procedure of the local procedure
3. As an internal procedure in a super procedure of the ABL session
4. As an external procedure file add-record.p or add-record.r

Case 2: When the AVM encounters a statement like the following:

RUN add-record IN my-proc-hdl('Customer').

The AVM searches for add-record as follows:

1. As an internal procedure in my-proc-hdl
2. As an internal procedure in a super procedure of my-proc-hdl
3. As an internal procedure in a super procedure of the ABL session

Case 3: When the AVM encounters a statement like the following:

add-record('Customer').

The AVM searches for add-record as follows:

1. As a user-defined function in the local procedure
2. As a user-defined function in a super procedure of the local procedure
3. As a user-defined function in a super procedure of the ABL session

Search rules for SEARCH-TARGET

Case 4: A procedure, main.p, has added three super procedures, S1, S2, and S3 (in that order). Each of these super procedures has added its own super procedures, S1A, S1B, S2A, S2B, S3A, S3B. The procedure, add-record, exists in three places: in S1, in S2 where it contains a RUN SUPER statement, and in S2A.

When the AVM encounters a statement like "RUN add-record('customer').", it searches for the add-record procedure:

1. As an internal procedure in the local procedure, main.p
2. Then as an internal procedure in S3, and then in S2 where it is found

The following code for main.p shows the differences in the initial setup of this case, which compares the use of no proc-search value (Instance 1) with the use of a value of SEARCH-TARGET (Instance 2):

/* main.p */
DEFINE VARIABLE h AS HANDLE NO-UNDO.

RUN s1.p PERSISTENT SET h.
THIS-PROCEDURE:ADD-SUPER-PROC(h).

RUN s2.p PERSISTENT SET h.
/* Instance 1
THIS-PROCEDURE:ADD-SUPER-PROC(h). */
/* Instance 2 */
THIS-PROCEDURE:ADD-SUPER-PROC(h, SEARCH-TARGET).

RUN s3.p PERSISTENT SET h.
THIS-PROCEDURE:ADD-SUPER-PROC(h).

RUN add-record.

If S2 was added with no proc-search value (Instance 1, commented out) or with a proc-search value of SEARCH-SELF, when RUN SUPER is executed within add-record in S2, the AVM starts searching in S2A, which is next in the search stack of the super procedure, S2.

If S2 was added with a proc-search value of SEARCH-TARGET (Instance 2, as executed), when RUN SUPER is executed within add-record in S2, the AVM starts searching in S1, which is next in the search stack of the local procedure, main.p.