ADD-SUBSYSTEM

Extend dynamic subsystem catalog

Component:	DSSM
Functional area:	Subsystem management
Domain:	SYSTEM-MANAGEMENT
Privileges:	SUBSYSTEM-MANAGEMENT

Function

Using this command, the system administration can extend the current subsystem configuration during a session (maximum number: 1000 subsystems and 16000 CALL entries). The catalog specified may either be a completely new one, which includes all the entries in the previous one, or it may contain only the new subsystems which are to be added into the current catalog.

In either case, the subsystem catalog specified must have been generated using SSCM. The (‘old’) subsystem catalog used during system initialization is not automatically updated. For the next session, the system administration can either

• use the catalog generated for ADD-SUBSYSTEM during system initialization, or

• generate a completely new and updated subsystem catalog and use this for system initialization. This new catalog need not build up quantitatively on an old predecessor catalog nor qualitatively support its references and attributes.

The ADD-SUBSYSTEM command is rejected if the class 5 memory reserved for the subsystem is insufficient (on system initialization, DSSM reserves class 5 memory for subsystems defined with MEMORY-CLASS=*LOCAL-PRIVILEGED, *LOCAL-UNPRIVILEGED or *BY-SLICE).

Format

ADD-SUBSYSTEM                                                                                                                                         

CATALOG = <filename 1..54 without-gen-vers>

,TYPE = *EXTENDED-ACTIVE-CONFIGURATION / *NEW-SUBSYSTEMS

Operands

CATALOG = <filename 1..54 without-gen-vers>
Name of the new subsystem catalog.

TYPE =
Specifies whether the current catalog is to be extended or replaced.

TYPE = *EXTENDED-ACTIVE-CONFIGURATION
A completely new catalog is to be activated, containing not only the entries from its predecessor, but also the new subsystems.

TYPE = *NEW-SUBSYSTEMS
The specified catalog contains only new subsystems, which are to be added to the old catalog. DSSM will check the catalog to ensure that the subsystems which it contains really are new. If any subsystem is found which is also listed in the catalog which is being extended, the command will be rejected.

Restrictions

• The subsystems specified for generation using SSCM with RELATED-SUBSYSTEM and REFERENCED-SUBSYSTEM must be cycle-free, i.e. free of mutual dependency.

• It is not permitted to define different versions of a subsystem with the start attributes AT-SUBSYSTEM-CALL, BEFORE-SYSTEM-READY, AFTER-SYSTEM-READY, BEFORE-DSSM-LOAD, AT-DSSM-LOAD and MANDATORY-AT-STARTUP (exception: AT-SUBSYSTEM-CALL is permitted if coexistence is defined for all versions involved).

Return codes

(SC2)	SC1	Maincode	Meaning
	0	CMD0001	No errors
	32	ESM0296	Abnormal termination (REQM error)
	32	ESM0350	Internal DSSM problem during processing
	64	ESM0260	File not found
	64	ESM0261	Storage space limit reached in DSSM catalog
	64	ESM0262	File is not a catalog
	64	ESM0322	Maximum number of relations exceeded
	64	ESM0325	Inconsistent with old catalog
	64	ESM0332	Incompatible version of catalog
	64	ESM0340	Reserved address-space exhausted for subsystems with MEMORY-CLASS=*BY-SLICE

Notes

There is a problem with relations which refer to subsystems that are not defined in the current catalog (put there using the SSCM statement SAVE-CATALOG FORCED=*YES). This problem can be circumvented during a session by using SSCM to define the relation in a new catalog and then using ADD-SUBSYSTEM to define this new catalog.

Example for TYPE=*EXTENDED-ACTIVE-CONFIGURATION

Old catalog		New catalog
//START-CATALOG-CREATION old-cat //SET-SUBSYSTEM-ATTRIBUTES // SUBSYSTEM-NAME=ss1, // RELATED-SUBSYSTEM=ss2 //SAVE-CATALOG FORCED= // *FOR-ADD-SUBSYSTEM	====>	//START-CATALOG-CREATION new-cat //SET-SUBSYSTEM-ATTRIBUTES - // SUBSYSTEM-NAME=ss1, - // RELATED-SUBSYSTEM=ss2 //SET-SUBSYSTEM-ATTRIBUTES - // SUBSYSTEM-NAME=ss2 //SAVE-CATALOG

Restrictions on the operand TYPE=*EXTENDED-ACTIVE-CONFIGURATION

• Subsystems with the attribute MEMORY-CLASS=*LOCAL-PRIVILEGED, which are being added to the newly created catalog, must not exceed the size of the address space strip in user or system address space, nor may their location in the address space overlap with subsystems from the old catalog.

• The CREATION-TIME operand for any new subsystem must be chosen to be compatible with versions of the same subsystem which are already defined in the old catalog. In making this choice, the values BEFORE-SYSTEM-READY, AFTER-SYSTEM-READY, BEFORE-DSSM-LOAD, AT-DSSM-LOAD and MANDATORY-AT-STARTUP could be used, but would have no effect since the system startup time for a session which has started will already have been passed; i.e. the system administration will be given an appropriate warning, but the subsystem will not be loaded.

• In distributing subsystems to holder tasks (ASSIGN-HOLDER-TASK statement), the “stand alone” principle must be observed, i.e. subsystems from different catalogs may not be assigned to the same holder task.

  Example

  Subsystems in the old catalog: Subsystems in the new catalog:	A, B, C A, B, C, D, E
  Then:
  //ASSIGN-HOLDER-TASK *SHARE-HOLDER(BY-SUB=(A,B)) //ASSIGN-HOLDER-TASK *SHARE-HOLDER(BY-SUB=(D,E))		is permissible is permissible
  but:
  //ASSIGN-HOLDER-TASK *SHARE-HOLDER(BY-SUB=(A,D,C))		not permissible

• The new catalog must be larger than its predecessor, because it not only contains the old subsystems with their attributes (relations, dependencies, loading instructions), but must also maintain details of the new subsystems.

• Linkage and dependence relations (REFERENCED-SUBSYSTEM / RELATED-SUBSYSTEM) must not go outside the bounds of the catalog: for a subsystem defined in catalog A there must be no relations in that catalog which refer to a subsystem defined in catalog B.

• Once REMOVE-SUBSYSTEM has been used to delete a subsystem from the catalog, TYPE=*EXTENDED-ACTIVE-CONFIGURATION can no longer be specified.

It is not permissible to define different

• subsystems with an identical combination of the attributes: SVC-NUMBER / FUNCTION-NUMBER / FUNCTION-VERSION.

• subsystems with an identical combination of the attributes: FUNCTION-NUMBER / FUNCTION-VERSION (if the value *ALLOWED is set for VERSION-COEXISTENCE or VERSION-EXCHANGE) for subsystems which are indirectly linked via System Procedure Linkage (ISL).

• versions of a subsystem with an identical combination of the attributes: SVC-NUMBER / FUNCTION-NUMBER / FUNCTION-VERSION if the value *ALLOWED is set for VERSION-COEXISTENCE or VERSION-EXCHANGE.

• versions of a subsystem with an identical combination of the attributes: FUNCTION-NUMBER / FUNCTION-VERSION / VERSION-COEXISTENCE or VERSION-EXCHANGE for subsystems which are indirectly linked via System Procedure Linkage (ISL).

Overlaps of subsystems must be avoided. To prevent this, DSSM compares the values of the SIZE and START-ADDRESS operands in the SET-SUBSYSTEM-ATTRIBUTES statements.

The assignment of a holder task (by an SSCM statement) for an “old” and a new subsystem has no effect on holder task distribution.

Table of incompatibilities for relations between subsystems in the old and new catalog:

x:	this combination is not possible: neither link relations (REFERENCED-SUBSYSTEM) nor any other dependencies (RELATED-SUBSYSTEM) are permitted
r:	link relations (REFERENCED-SUBSYSTEM) are not permitted

Subsystem in the new catalog	Subsystem in the old catalog
	MAS	BSR	ASR	ACR1)	ASC1)	BDL	ADL	STY1)	SAL1)	SAH1)	MCP1)	MCU1)	MCS
MAS: MANDATORY-AT-STARTUP		x	x	x	x
BSR: BEFORE-SYSTEM-READY			x	x	x
ASR: AFTER-SYSTEM-READY				x	x
BDL: BEFORE-DSSM-LOAD	x	x	x	x	x		x
ADL: AT-DSSM-LOAD	x	x	x	x	x
STN: STOP-AT-SHUTDOWN=*NO								r
SAS: SUBSYSTEM-ACCESS=*SYSTEM									x	x			x
MCG: MEMORY-CLASS=*SYSTEM-GLOBAL											x	x
MCS: MEMORY-CLASS=*BY-SLICE											r	r	r

Table 24: Incompatibilities in relations between subsystems

1)	ACR: AT-CREATION-REQUEST ASC: AT-SUBSYSTEM-CALL STY: STOP-AT-SHUTDOWN=*YES SAL: SUBSYSTEM-ACCESS=*LOW SAH: SUBSYSTEM-ACCESS=*HIGH MCP: MEMORY-CLASS=*LOCAL-PRIVILEGED MCU: MEMORY-CLASS=*LOCAL-UNPRIVILEGED