47.7. $searchCallChain

$searchCallChain searches the PROCEDURE call chain of the current coroutine (i.e., the current PROCEDURE's caller, its caller, and so on back to the initializing PROCEDURE of the coroutine) for a PROCEDURE invocation associated with the MODULE named moduleName. If such a PROCEDURE invocation is found, $searchCallChain returns a POINTER to the data section from which the most recent such call was made; otherwise, $searchCallChain returns NULLPOINTER. The only valid ctrlBits bit is errorOK, which suppresses an error message if no call from moduleName is found.

For example, consider two nonbound MODULEs A and B. If A knows it was created by B, and that B is therefore in the call chain of A's INITIAL PROCEDURE, and B contains some interface fields to which A needs access, A may find B's data section with:

$searchCallChain("B")

Without $searchCallChain, it would be necessary for B to make a POINTER to itself available in a known place before allocating A, or to provide a special initialization PROCEDURE in A to which B could pass a POINTER to itself.

Note that it is generally advisable to use one of the alternative strategies rather than using $searchCallChain. If constraints on program design permit B to make itself available to A in a known place, such as through a bound MODULE's interface PROCEDURE, that is usually preferable to calling $searchCallChain, since a bound MODULE declaration makes the structure of the program clearer to the human reader.