previous next top complete contents complete index framed top this page unframed
Figure 31–4. bind (GENERIC)
| SPECIAL POINTER # classified to be of m's CLASS PROCEDURE bind (MODULE m; OPTIONAL BITS ctrlBits; OPTIONAL POINTER($area) area; PRODUCES OPTIONAL STRING msg); POINTER PROCEDURE bind (STRING moduleName; OPTIONAL BITS ctrlBits; OPTIONAL POINTER($area) area; PRODUCES OPTIONAL STRING msg); |
If a bound data section is not already allocated for the MODULE indicated by its argument, bind allocates a bound data section for it. If there is already a bound data section, bind does not change it or allocate a new data section. In any case, bind returns a POINTER to the bound data section. The control section is brought into memory, if necessary; it is found as described in Section 14.2.
The POINTER returned is of the CLASS associated with the MODULE m.
In the STRING form of bind, moduleName is the name of the MODULE to be bound. This allows for those cases in which the name of the MODULE to be bound has not been declared in the program (e.g., it may be obtained from the user). The returned POINTER is unclassified since the compiler does not know the CLASS of the anonymous MODULE.
area is the area in which the bound data section is allocated.
Inaccessible bound data sections are not reclaimed by the garbage collector; bound data sections must be explicitly disposed. (Inaccessible nonbound data sections, by contrast, are collected.)
The predefined valid bits constants for ctrlBits are shown in Table 31–5.
Table 31–5. Valid Bits for bind ctrlBits
| Bit | Meaning |
|---|---|
| $programInterface | Cause the BOOLEAN macro $useProgramInterface, if called in the bound MODULE's INITIAL PROCEDURE before any other PROCEDURE is called, to return TRUE (see Section 49.10). |
| errorOK | Return NULLPOINTER if the MODULE's control section cannot be bound; never issue an error message or prompt for whether to try again. |
If the specified MODULE cannot be bound, bind issues an error message (unless errorOK is set in ctrlBits). If errorOK is not set, then for some kinds of errors, it then prompts for whether to try binding the MODULE again; for other kinds of errors, it returns NULLPOINTER without prompting. In any case, when bind fails, its return value is NULLPOINTER and msg is set to a description of the error.
NB: A call to bind with errorOK set can return NULLPOINTER, so you should always check bind's return value if there is a chance it might fail.
The PROCEDURE new (see Section 42.1) may be used to allocate nonbound data sections.
A related PROCEDURE, unBind, is described in Section 49.1.
The PROCEDURE $invokeModule (see Section 38.14) binds and then unbinds a MODULE, thereby invoking the MODULE's INITIAL PROCEDURE.
31.5.1. Handling Errors from bind
It is possible to handle errors encountered by
bind and have the PROCEDURE
try to allocate the MODULE again.
To do this, call $raiseReturn at the end of the handler for the
$systemExcpt raised by bind.
For example, to handle a call to bind that cannot find a MODULE
FOO by opening the library where FOO is supposed to reside and
retrying the bind:
$HANDLE bind("FOO")
$WITH
IF $exceptionName = $systemExcpt THENB
openLibrary("libWithFoo.olb");
$raiseReturn; # bind will try FOO again
END
EL $raise;
MAINSAIL Language Manual, Section 31.5