@USE - Define external statement routines

The @USE statement is used to define user statements by specifying a user statement symbol and an associated statement routine (see Subroutine Interfaces User Guide [1]).

Operation	Operands	F mode, L mode
@USE	C OMMAND='[spec]' [ { , E NTRY={entry | *} [, M ODLIB=modlib]   ( {name | *} [,modlib] ) } ]

spec	Special character which is used as the user statement symbol for an external statement routine. The user statement symbol must be different from the current EDT statement symbol. In the specific case that an external statement routine is to be used as a statement filter then an empty string must be specified instead of a user statement symbol. However, this is only possible when EDT is called as a subroutine (see the section “Special application as a statement filter” in [1]).
entry	Entry point for the external statement routine: The module which contains the entry point is loaded immediately.
name	Entry point for the external statement routine: The operand syntax with parentheses is now only supported for reasons of compatibility.
*	The name of the statement routine's entry point is specified as the statement name when the user-defined statement is entered. The module which contains the entry point is not loaded until the user-defined statement is executed for the first time. Similarly, the UNIT name which is used to unload the load unit again (see below) is not formed until this point.
modlib	Name of the library containing the module which contains the entry point. The library must exist. Otherwise, the statement is rejected with the error message EDT5372. If the module containing the entry point is not found in the specified library, the system first searches in the alternative libraries BLSLIBnn then in the private task library and system task library $TASKLIB.

If no library is specified, the system first searches in the private task library and then in the system task library $TASKLIB.

If the search fails, the error message EDT5372 is issued.

A maximum of 5 different user statement symbols can be declared. The attempt to declare a sixth user statement symbol is rejected with the message EDT5373.

If no other operands are specified apart from the user statement symbol then the statement routine previously defined using the user statement symbol is deactivated.

If the execution of the @USE statement results in a separate load operation then a UNIT name which is the same as the entry point specified in entry or name is notified to the dynamic binder loader.

This UNIT name can be specified in the @UNLOAD statement in order to unload all the load units that were loaded together with the entry point. If the entry point is found inside another load unit, @USE does not therefore result in a separate load operation and the entry point can only be unloaded together with this load unit.

If the value * is specified instead of entry or name then this mechanism is not applied until a user-defined statement is entered. This means that the names of all the entry points which have resulted in a load operation are notified to the dynamic binder loader as UNIT names.

EDT only dynamically loads an entry point if this has not already been found in a previously loaded load unit. If EDT itself has been loaded as a subroutine in a user program, this also applies to entry points in this user program.

It is not therefore possible to use entry points of the same name in different load units in parallel. It is nevertheless possible that the dynamic binder loader may identify duplicate names when loading a statement routine. In this case, the @USE statement or user statement that caused dynamic loading is rejected with the message EDT4208. If EDT is not running in F mode then the error message from the dynamic binder loader is also output. This message makes it possible to identify the name of the duplicate symbol.

This situation can be avoided by using the @UNLOAD statement to unload the load unit loaded with a previous @USE statement before issuing any further @USE statements. The associated user statement symbol is then also canceled.

In contrast, if the user statement symbol is simply canceled using @USE
COMMAND='spec' or if a user statement symbol is assigned twice then the originally assigned load unit is not implicitly unloaded.

If EDT-specific entry points or module names are specified in the @USE statement then it is rejected with the message EDT4933.

If the ENTRY=* or (*,modlib) operand is specified then conversion to uppercase characters is always performed when the name of the entry point is formed from the first part of the user statement. The remainder of the user statement may or may not be converted to uppercase depending on the @PAR LOW setting.
If (*,modlib) is specified then (for reasons of compatibility) only a maximum of 8 characters are taken into account during the formation of the entry point name. Otherwise, a maximum of 32 characters are taken into account.

For details on the implementation of external statement routines or statement filters and for information on passing parameters to these, see the section “Calling a user-defined statement” in [1].

The @USE statement is one of the EDT statements with security implications (see also section “Access protection”). Under certain privileged IDs, the @USE statement is rejected. This also applies to uninterruptible system procedures in interactive mode (read from SYSDTA with RDATA, execute EDT start procedure) unless the @USE statement is issued by the protected procedure itself (SYSDTA=SYSCMD).

Note

Names of up to 32 characters in length are permitted in the entry specification and the name is case-sensitive. Only 8 characters are permitted for name and any lowercase characters that are entered are converted into uppercase.

Example 1

The module which contains the entry point JOBVAR in the library PRIVLIB can be called with the parameters CATJV <name>, ERAJV <name>, GETJV <name>,<ln> or SETJV
<name>,<ln>. The name of the entry point JOBVAR is specified directly in the @USE statement.

@USE COMMAND = '*',ENTRY=JOBVAR,MODLIB=PRIVLIB ---------------------------(1)
*CATJV JV.TEST ---------------------------------------------------------- (2)
*SETJV JV.TEST,3 -------------------------------------------------------- (3)

(1) The user statement symbol * is declared and the module JOBVAR is loaded.

(2) The module JOBVAR is called with the parameter 'CATJV JV.TEST'.

(3) The module JOBVAR is called with the parameter 'SETJV JV.TEST,3'.

Example 2

The library PRIVLIB contains the two modules SORT and HELP. The name of the entry point is not defined until the user-defined statement is actually called.

@USE COMMAND = '*',ENTRY=*,MODLIB=MODLIB -------------------------------- (1)
*SORT 20-100 ------------------------------------------------------------ (2)
*HELP EDT5100 ----------------------------------------------------------- (3)

(1) * is declared as the user statement symbol. However, no module is loaded as yet.

(2) The module SORT is loaded and called with the parameter '20-100'.

(3) The module HELP is loaded and called with the parameter 'EDT5100'.