Progress
Language Reference
ADD-SUPER-PROCEDURE( ) Method
Associates a super procedure file with a procedure file or with the current Progress session. When a procedure file invokes an internal procedure or a user-defined function, Progress searches for it, among other places, in the super procedures (if any) of the procedure file and of the current Progress session. The procedure-search option determines which procedures are searched.
For more information on the rules that Progress uses to search for internal procedures and user-defined functions, see the "Search Rules" section of this entry. For information on super procedures, see the Progress Programming Handbook . For a sample program that uses the ADD-SUPER-PROCEDURE method, see the reference entry for the RUN SUPER Statement in this book.
Return Type: LOGICAL Applies To: SESSION System Handle, THIS-PROCEDURE System Handle and all procedure handles
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 Progress session.
ADD-SUPER-PROCEDURE returns FALSE if super-proc-hdl is not a valid handle, or if Progress 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 attribute. In addition, the warning message can be avoided by creating two instances ofsuper-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:
The following example:
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 Progress Session
The following example associates a super procedure with the current Progress session:
When you do this, Progress 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:
in individual procedures with a single occurrence of the following:
Super Procedure Stacking
You can associate multiple super procedures with a single local procedure or with the current Progress session. When you do this, Progress 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 Progress 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, Progress 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:
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 Progress 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:
The following events occur:
- Progress searches A 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, Progress runs it. If B does not contain add-record, Progress does not search for add-record in C.- If and only if A’s add-record exists and says RUN SUPER, Progress searches B for add-record and runs it if found.
- If and only if B’s add-record exists and says RUN SUPER, Progress searches C for add-record and runs it if found.
In this way, Progress avoids excessive and possibly circular searching.
Search Rules
Progress 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 Progress encounters a statement like the following:
Progress searches for add-record as follows:
Case 2: When Progress encounters a statement like the following:
Progress searches for add-record as follows:
Case 3: When Progress encounters a statement like the following:
Progress searches for add-record as follows:
NOTE: The rules of Case 3 apply whether or not the user-defined function’s declaration (function prototype) includes the IN proc-hdloption. In Case 3, proc-hdl represents the local procedure. For more information on function prototypes of user-defined functions, see the Progress Programming Handbook .
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 Progress encounters a statement like the following:
It searches for the add-record procedure:
If add-record was added with no proc-search
value or with a
proc-search value of SEARCH-SELF, when RUN SUPER is executed within add-record in S2:
If add-record was added with a proc-search value of SEARCH-TARGET, when RUN SUPER is executed within add-record in S2:
NOTE: The search commences with the super procedure following super-proc-hdlin the local procedure’s chain.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |