Deactivate subsystem
Component: | DSSM |
Functional area: | Subsystem management |
Domain: | SYSTEM-MANAGEMENT |
Privileges: | OPERATING |
Routing code: | R |
Function
This command enables systems support staff to deactivate a subsystem. The command functions in the following sequence:
The subsystem in question is locked for all new callers.
The subsystem is deactivated as soon as all jobs connected to it have terminated normally.
When the FORCED=*YES operand is specified, the subsystem is unloaded without waiting any further for the connected jobs. Any attempt of these jobs to obtain access later results in an error. In the case of privileged subsystems it leads either to a user dump or, if defined, to the corresponding STXIT contingency being called and the reaction programmed there.
However, FORCED=*YES will be accepted only if the STOP-SUBSYSTEM command has already been issued with FORCED=*NO and failed to terminate the tasks.The subsystem is unloaded.
All occupied resources are released.
The STOP-SUBSYSTEM command is rejected if:
the subsystem cannot be found in the dynamic subsystem catalog
subsystems that have already been activated or are in the process of being activated are dependent on the subsystem to be deactivated
subsystems that have already been activated or are in the process of being activated are linked to the subsystem to be deactivated.
FORCED=*YES is used without a previous attempt to terminate using FORCED=*NO.
Format
STOP-SUBSYSTEM |
SUBSYSTEM-NAME = <structured-name 1..8> ,VERSION = *STD / <product-version mandatory-man-corr> / <product-version without-man-corr> / *HIGHEST ,SUBSYSTEM-PARAMETER = *NONE / <c-string 1..254> ,FORCED = *NO / *YES ,SYNCHRONOUS = *NO / *YES |
Operands
SUBSYSTEM-NAME = <structured-name 1..8>
Name of the subsystem to be deactivated.
VERSION = *STD / <product-version mandatory-man-corr> /
<product-version without-man-corr> / *HIGHEST
Specifies the version number.
If a version number is specified, the format specified here must be identical to the format used when the subsystem was defined (release and correction status mandatory or not allowed; see also the description of the data type "SDF syntax representation").
VERSION = *STD
If only one version of the loaded subsystem exists, this version is selected. If more than one matching version exists, the version must be specified.
VERSION = *HIGHEST
Selects the highest version of the subsystem entered in the static subsystem catalog.
SUBSYSTEM-PARAMETER = *NONE / <c-string 1..254>
Specifies whether special parameters which can be interpreted only by the specified subsystem may be processed.
FORCED =
Determines the behavior and urgency of command processing.
FORCED = *NO
The system waits for all tasks connected to the subsystem to be disconnected. When a task releases its connection depends on the subsystem. A connection to a nonprivileged subsystem (e.g. EDT) is released as soon as the program terminates.
The system waits for all tasks that access the subsystem to be processed and terminated normally.
FORCED = *YES
Immediate unloading of the subsystem is forced.
In the case of a privileged subsystem, this can lead to system dumps of the tasks which are still connected; in the case of a nonprivileged subsystem, this can lead to user dumps or to the execution of the STXIT error handling routine which is offered by DSSM.
SYNCHRONOUS =
Permits a choice between synchronous and asynchronous processing.
SYNCHRONOUS = *NO
The command is to be processed asynchronously, i.e. without waiting for its execution before further input. Once the syntax of the command has been checked, the calling task is sent message ESM0216. No error messages relating to the execution of the command are output.
SYNCHRONOUS = *YES
Execution of the command must be awaited.
Accompanying error messages are output.
In the event of a version change, this specification applies only to the new version. Deactivation of the other, “old” version always runs asynchronously.
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | No error | |
1 | 0 | CMD0001 | No action necessary; subsystem is no longer active |
1 | ESM0414 | Syntax error: invalid version specified | |
32 | ESM0224 | Command not processed | |
32 | ESM0228 | Command terminated abnormally |
Notes
In order to ensure a high degree of parallelism and data integrity, time-consuming administrative jobs are not executed under the control of the calling task but are transferred to a DSSM task.
As a rule only the check of the requested function is performed synchronously (i.e. in conjunction with a wait state for the calling task). However, DSSM performs the actual processing asynchronously and independently of the calling task.STOP-SUBSYSTEM with the FORCED=*YES operand is accepted only if the command has previously been issued with FORCED=*NO and the subsystem only has to wait for the deactivation of the occupying tasks.
The FORCED function cannot guarantee the “normal” behavior of tasks connected to a privileged subsystem.
Tasks connected to a nonprivileged subsystem can initiate an error routine that permits resumption of the program.
However, since DSSM does not wait for completion of this routine, a START-SUBSYSTEM command issued in the meantime may result in these tasks being reported as still linked to the subsystem.