Defining subsystems

You must define the name of every new agent for z/OS subsystem in the active subsystem-name-table member of SYS1.PARMLIB.

Consider the following when you define the subsystem name:
  • The subsystem and the started task names for the agent for z/OS must be the same.
  • Agent for z/OS instances connected to the same dynamic workload broker cannot have the same system-STC name identification.
  • Because subsystem names on a given LPAR must be unique, and because all agent for z/OS started tasks must have the same name as their associated subsystems, all started tasks on any given LPAR must have unique names (that is, every agent for z/OS instance inside a z/OS® image must have a unique Subsystem/STC name).
To define the subsystems, update the active IEFSSNnn member in SYS1.PARMLIB. Include records as in the following example:
Subsystem definition record
SUBSYS SUBNAME(subsystem name) INITRTN(module name) INITPARM ('maxecsa,suffix')
where:
subsystem name
The name assigned to an agent for z/OS subsystem. The name must be from 2 to 4 characters. All the subsystem names, as defined in the SYS1.PARMLIB member IEFSSNnn, must be unique within a GRS complex. Also, the subsystem names must be unique within your SYSPLEX, both local and remote systems. The started task name used for an agent for z/OS address space must exactly match the name of the associated subsystem.
module name
The name of the subsystem initialization module, EELINITN.
maxecsa
Defines the maximum amount of extended common service area (ECSA) that is used to queue job tracking events. The value is expressed in kilobytes (1 KB equals 1024 bytes). The default is 4, which means that a maximum of 4 KB (4096 bytes) of ECSA storage is needed to queue job tracking events. The maximum value allowed for MAXECSA is 2816.
suffix
The module name suffix for the EELSSCM module that EELINIT loads into common storage. EELSSCM is the subsystem communication module. The suffix must be a single character. Because the name of the module shipped with the agent for z/OS is EELINITN, specify N as the suffix value. If you do not provide a suffix, EELINITN attempts to load module name EELSSCMN. You can also specify a subsystem communication module name in the SSCMNAME keyword of the TWSOPTS initialization statement to load an updated version of the module before a scheduled IPL.

Updating the z/OS link-library definition provides more information about EELSSCM modules.

The next example illustrates a record you can include in the SYS1.PARMLIB IEFSSNnn member:
/*Subsystem definition example*/
SUBSYS SUBNAME(ZAG3) INITRTN(EELINITN) INITPARM ('100,N')

The record defines an agent for z/OS subsystem called ZAG3. Its initialization module is EELINITN. The amount of ECSA that is allocated, 101104 bytes, is enough for 1136 job tracking events. Because suffix value N is specified, EELINITN loads module EELSSCMN.

Calculating MAXECSA values

The agent for z/OS allocates ECSA storage for job tracking events in blocks of 1424 bytes. Each block is equivalent to 16 events. Every job creates a minimum of six events.Examples of MAXECSA storage values gives examples of the storage needed for, the storage actually allocated, and the events accommodated for several MAXECSA values.

If you want to calculate values that are not shown in the table for a given MAXECSA value, use this method:
  • Space requested = MAXECSA * 1024
  • Blocks = space requested / 1424 (round down to a whole number)
  • Space allocated = blocks * 1424
  • Events accommodated = blocks * 16
Table 1. Examples of MAXECSA storage values
MAXECSA value Amount of MAXECSA space requested Blocks of ECSA space allocated (bytes) Number of events accommodated
0 0 0 (0) 0
4 4096 2 (2848) 32
8 8192 5 (7120) 80
16 16384 11 (15664) 176
36 36864 25 (35600) 400
72 73728 51 (72624) 816
100 102400 71 (101104) 1136
200 204800 143 (203632) 2288
400 409600 287 (408688) 4592
500 512000 359 (511216) 5744
Important:
  • Allocate enough ECSA storage so that job tracking events are not lost when the event writer subtask of the agent for z/OS is not active. When the event writer is active, the number of queued events in ECSA is almost always 0. Allocate enough ECSA for the maximum amount of time you expect the event writer to be inactive.

    For example, after the IPL of a z/OS® system, job tracking events can occur before the agent for z/OS address space has become active. If you expect a maximum of 50 events to occur during this time, you should set a MAXECSA value of 8, as shown in the table. When the event writer becomes active, the queued events are processed and removed from ECSA.

    If events are lost, message EELZ035E is written in the message log.

  • All ECSA storage is allocated above the 16MB line.