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

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 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:

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:

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:

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

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:

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 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:

  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 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:

  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. Progress searches A for add-record and runs it if found.
  2. If and only if A’s add-record exists and says RUN SUPER, Progress searches B for add-record and runs it if found.
  3. 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.

  4. 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:

RUN add-record(’customer’). 

Progress 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 Progress session
  4. As an external procedure file add-record.p or add-record.r.

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

RUN add-record(’customer’) IN my-proc-hdl. 

Progress 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 Progress session

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

add-record(’customer’). 

Progress 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 Progress session
NOTE: The rules of Case 3 apply whether or not the user-defined function’s declaration (function prototype) includes the IN proc-hdl option. 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:

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.

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:

  1. Progress will start searching in S2A which is next in the search stack of the super procedure, S2.

If add-record was added with a proc-search value of SEARCH-TARGET, when RUN SUPER is executed within add-record in S2:

  1. Progress will start searching in S1 which is next in the search stack of the local procedure, main.p.
NOTE: The search commences with the super procedure following super-proc-hdl in the local procedure’s chain.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095