Register an environment method
|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall E_METHOD(method_option, method|library[, method_option, method|library] [, ...])
Arguments
method_option
One of the following environment method options:
Specify the application close method, which is the subroutine that is called when U_FINISH is called or when the application is closed using the System menu, close box, or Alt+F4.
Specify the application move method, which is the function that is called when the application window is moved.
Specify the application size method, which is the function that is called when the application window is resized.
Specify the application state method, which is the function that is called when the application window state is changed.
Specify the century method, which is the function that is called by U_DCDDAT whenever it needs to supply a default century. (Note that U_DCDDAT is called within the input processor to handle date defaulting.) If not specified, the default is the current century.
Specify the user field validation method, which is the subroutine that is called to validate the contents of the current user-defined input field.
Specify the user field display method, which is the subroutine that is called to display the contents of the current field if it is a user-defined input field.
Specify the user field edit display method, which is the subroutine that is called to display the editable contents of a user-defined field differently than both the way it is stored and the way the D_METH_DSPFLD method displays it.
Specify the input override method, which is the subroutine that is called when an input field is exited due to a menu entry.
Specify the key mapping method, which is the subroutine that is called whenever a function key or control character is entered by the user.
Specify the help method, which is the subroutine that is called when the user selects the menu entry with the internal name “O_HELP”.
Specify the library for in which Toolkit will search for methods for subsequent event method pairs. Used with library. See D_METH_LIBRARY in the Discussion.
Specify the script compilation error method, which is the subroutine to be called whenever the Script compiler external routine interface encounters a script compilation error.
Specify the utilities method, which is the subroutine that is called when the user selects a menu entry whose internal name begins with “U_”.
method
The name or integer address of the method to be used for the environment-level event specified with method_option, or a value of 0, which resets the method pair so that no method is associated with the specified method. Valid with all method_option options except D_METH_LIBRARY. (D_ADDR)
library
The ELB or shared image that contains the methods for subsequent event method pairs. Valid only with D_METH_LIBRARY. (a)
Discussion
E_METHOD registers method subroutine names for environment-level events. Use E_METHOD if you want to do additional processing when an environment-level event is initiated. When that event occurs, Toolkit will call method, which is a routine you write, and if library is specified prior to the method, Toolkit will look in the specified library for the method.
You may pass multiple environment method options in a call, each followed by a method or library. This is referred to as an event method pair. See the examples below.
If passed, method must be either the name or the address of a routine. If the integer address is specified, such as the return value from %XADDR, it must be of type D_ADDR (which is defined in dbl.def as either i4 or i8, depending on the system). Note that Toolkit immediately locates the method routine (unlike input field methods and list methods, which aren’t located until they need to be called).
If you omit method from an event method pair (any but a D_METH_LIBRARY pair), Toolkit resets the method pair, so that no method is associated with the specified event.
To enable the application to be closed with the System menu, the close box, or Alt+F4, you must either specify an application close method (D_METH_APPCLOSE) or use E_STATE to set the D_INTR state to allow interrupt characters.
If you don’t pass D_METH_LIBRARY, Toolkit uses the default mechanism for finding methods: it selects the first method it finds with the correct name in the program image or in a previously opened ELB or shared image. If you pass D_METH_LIBRARY without passing library, Toolkit ignores previously specified D_METH_LIBRARY pairs, and returns to the default mechanism for finding methods for subsequently specified event method pairs.
A library specification applies only to methods specified by name after the library specification in the same E_METHOD call. (Library is not used to look up method arguments passed as addresses, which represent routines that have already been located.) If there’s more than one library setting in a call, each one affects only the methods specified between it and the next library setting.
Library is passed on to %XADDR as the elb argument, which means that on Windows and Unix you can use an environment variable to specify the path—for example, “ELB_DIR:elb_name”. On OpenVMS, however, library can be either the filename of a shared image located in SYS$SHARE or a logical name that refers to a shared image, which may reside anywhere (so if library consists of a path and a name, similar to the example above, the path is ignored). For more information, see %XADDR.
See also
Examples
The following example registers “ap_close” as the application close method. Because no library is specified, Toolkit will look for that routine in the program image or in a previously opened ELB.
xcall e_method(D_METH_APPCLOSE, "ap_close")
The next example specifies the method by passing its address.
xcall e_method(D_METH_APPCLOSE, %xaddr("ap_close"))
The following example registers “mydspfld” as the user field display method subroutine. This subroutine is to be found in the userlib.elb executable library.
xcall e_method(D_METH_LIBRARY, "userlib.elb", D_METH_DSPFLD, "mydspfld")
