REUS: Reusability options

The REUS option allows you to specify how a program can be reused. (Reusability means that the same copy of a program module can be used by more than one task either concurrently or one after another.)

Note that the value of the REUS option always overrides the reusability of any included load modules or program objects.

The syntax of the REUS option is as follows:

REUS={NONE | SERIAL | RENT | REFR}

The reusability values are:

NONE

The module cannot be reused. A new copy must be brought into virtual storage for each use. NONE is the default value.

SERIAL

The module is serially reusable. It can only be executed by one task at a time; when one task has finished executing it another task can begin. A serially reusable module can modify its own code, but when it is reexecuted it must initialize itself or restore any instructions or data that have been altered.

RENT

The module is reenterable. It can be executed by more than one task at a time. A task can begin executing it before a previous task has completed execution. A reenterable module is ordinarily expected not to modify its own code. In some cases, MVS™ protects the reentrant module's virtual storage so that it cannot be modified except by a program running in key 0. These cases include programs which the system treats as having been loaded from an authorized library, and also programs running under UNIX unless a debugging environment has been specified.

Reenterable modules are also serially reusable.

REFR

The module is refreshable. It can be replaced by a new copy during execution without changing the sequence or results of processing. A refreshable module cannot be modified during execution.

A module can only be refreshable if all the control sections within it are refreshable. The refreshable attribute is negated if any input modules are not refreshable. Refreshable modules are also reenterable and serially reusable.

The refreshable attribute can be specified for any nonmodifiable module.

If REFRPROT has been specified on the SETPROG command or in parmlib member PROGxx, the module is protected from modification by placing it in key 0, non-fetch protected storage, and page protecting the whole pages. Note that debuggers, such as TSO TEST and UNIX debugging environments, will override REFRPROT protection for particular TCBs so that they can modify module storage in order to set breakpoints.

Alternatively, you can code a REUS option as a single keyword without a value (REUS, NOREUS, RENT, NORENT, REFR, NOREFR). For example:

//LKED  EXEC PGM=IEWBLINK,PARM='RENT,…'

REUS used as a single keyword is equivalent to REUS=SERIAL. NOREUS used as a single keyword is equivalent to REUS=NONE. This alternative form is supported only for backward compatibility. The most restrictive positive specification is used to set the reusability attribute. For example, specifying REFR has the same effect as specifying REUS (REFR) and the module is marked as refreshable, reenterable, and (serially) reusable.

If the PARM string contains both formats, the REUS(value) instance will override any reusability options specified without values.

The binder only stores the attribute in the directory entry. It does not check whether the module is actually reenterable or serially reusable. If the module is incorrectly marked as reenterable or reusable, execution results are unpredictable; for example, a protection exception might occur or the program might use another task's data.