E_METHOD

xcall E_METHOD(method_option, method|library[, method_option, method|library] [, ...])

Arguments

method_option

One of the following environment method options:

D_METH_APPCLOSE

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.

D_METH_APPMOVE

Specify the application move method, which is the function that is called when the application window is moved.

D_METH_APPSIZE

Specify the application size method, which is the function that is called when the application window is resized.

D_METH_APPSTATE

Specify the application state method, which is the function that is called when the application window state is changed.

D_METH_CENTURY

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.

D_METH_CHKFLD

Specify the user field validation method, which is the subroutine that is called to validate the contents of the current user-defined input field.

D_METH_DSPFLD

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.

D_METH_EDTDSP

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.

D_METH_ENTRST

Specify the input override method, which is the subroutine that is called when an input field is exited due to a menu entry.

D_METH_FKEY

Specify the key mapping method, which is the subroutine that is called whenever a function key or control character is entered by the user.

D_METH_HELP

Specify the help method, which is the subroutine that is called when the user selects the menu entry with the internal name “O_HELP”.

D_METH_LIBRARY

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.

D_METH_SCRIPTERR

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.

D_METH_UTILS

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.

D_METH_LIBRARY

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.