JCL provides a facility known as the JCL Subsystem Exit (SUBSYS), which allows an installation to customize the behavior required by a subsystem by monitoring events and controlling the resultant actions performed by the system.
SUBSYS can be specified as a keyword on a DD statement and as a Text Unit (TU) on SVC 99. In call cases, the syntax is equivalent to:
SUBSYS=(subsystem-name[,subsystem-subparameter]...)
Where :
For example, on the DD statement:
//someddn DD SUBSYS=(OODA,A,DKP39CPM,’PPP3’,STD,,USER),
// DSN=MFIDSA.SUBSYS1B.NEW.OODA.NOTUSED,
// OUTPUT=(*.OUTSJ,*.OUTHORSE)
If the DD statement has the SUBSYS keyword and the subsystem-subparameter string contains DDNAME=x anywhere in the string, it is processed as if DDNAME=x was coded on the DD statement. This applies only to the JCL DD statement regardless of the subsystem-name. It does not apply to SVC99 Text Units (TUs).
For each DD with SUBSYS, the exit is given control once just before resource allocation. It is not given control during execution for other events such as OPEN, CLOSE and WRITE.
The user exit, which must be named MFJYssss, and where ssss is the subsystem-name, is optional and is invoked as follows:
CALL ‘MFJYssss’ USING SXIT
Where SXIT is the user exit interface block (mfjdsxit.cpy). It contains
mfjdsxit.cpy describes in detail all of the event codes, actions codes, and the data associated with each event. When looking at mfjdsxit.cpy, note the following:
The subsystem exit is called as events occur.
If the user exit fails for any reason, it is disabled in the failing process for all subsequent events.
Notes:
For each event, this section defines the key (but not all) inputs and outputs and the actions that can be requested for the event. The following action applies to all events:
The event names listed below correspond in part to the level-78 name assigned to the event code. Similarly, action code names listed correspond in part to the level-78 name assigned to the action code. Having access to mfjdsxit.cpy, mfjyooda.cbl and subsys1b.jcl files will help your understanding of the facilities being described here.
This event indicates that the source for the DD is about to be allocated. The purpose of this event is to allow the subsystem exit to verify and/or modify the DD that is being processed.
This event and Event-before-PGM-call occur in the child process. All other events occur in the parent process. You exit cannot remember any events that occurred in the parent process.
Data available for this event includes:
The exit can view or change the information and request that the system use the changed information. The information that can be changed includes:
Actions that can be requested:
If the exit changes the DD to a SYSOUT, the printer exit is, in addition to accessing normal sysout related information such as OUTPUT statements, able to access subsystem-subparameter string information allowing further customization of the produced sysout output.
This section presents a listing of the mfjdsxit.cpy copybook used by SXIT.
For the most up-to-date information refer to the source for this copybook in install-dir\base\source.
*>==============================================================
*> Copyright ©) 1997-2008 Micro Focus (IP) Ltd.
*> All rights reserved.
*>
*> This sample source code is provided for use by users of
*> Micro Focus products (the "Software") and may be used,
*> modified and distributed as part of your application provided
*> that you properly acknowledge the copyright of Micro Focus in
*> this material.
*>
*> All conditions, warranties and undertakings, express or implied,
*> statutory or otherwise, on the part of Micro Focus are excluded,
*> including without limitation those of merchantability or fitness
*> for purpose. This shall not, however, purport to exclude or
*> restrict the liability of Micro Focus to any extent not
*> permitted by law.
*>
*> IN NO EVENT WILL MICRO FOCUS BE LIABLE FOR ANY INDIRECT,
*> INCIDENTAL, SPECIAL, CONSEQUENTIAL OR OTHER DAMAGES ARISING OUT
*> OF THE USE OF THE DEMONSTRATION PROGRAM DISTRIBUTED WITH THE
*> SOFTWARE, WHETHER OR NOT INFORMED OF THE POSSIBILITIES OF
*> DAMAGES IN ADVANCE. THESE LIMITATIONS APPLY TO ALL CAUSES OF
*> ACTION, INCLUDING BREACH OF CONTRACT, BREACH OF WARRANTY, STRICT
*> LIABILITY, AND ANY ACTIONS IN TORTS.
*>==============================================================
*>==============================================================
*> mfjdsxit - Micro Focus Subsystem user exit parameter block
*> Contains interface information and is passed as a parameter
*> to the subsystem exit which is ivoked as:
*> call subsys-exit using sxit
*>
*> Notes:
*> 1. It should be included as follows (e.g.)
*> copy mfjdsxit replacing ==()== by ==sxit==.
*> 2. Fields beginning with sxit-I- ( ()-I- ) are Input
*> to the subsystem exit and must not be modified
*> e.g. sxit-I-size
*> 3. Fields beginning with sxit-U- ( ()-U- ) are Input and
*> Output. On entry to the subsystem exit, they are set as
*> appropriate and may be changed by the subsystem exit to
*> an acceptable value upon return.
*> e.g. ()-U-ds-type
*> 4. All data is ASCII(ANSI). Null values are those appropriate
*> for the data type. i.e. blanks for character data,
*> zeros for numeric and binary data
*>==============================================================
1 ().
3 ()-header.
5 ()-I-size pic x(2) comp-x. *>Size of this blk
5 ()-I-event pic x(2) comp-x. *> event code
*> this event occurs before DD is allocated
78 ()-I-event-dd-alloc-pre value 1.
5 ()-U-action pic x(2) comp-x. *>action requested
*> The system should continue as if the exit were
*> never invoked. Do not modify any data.
78 ()-U-action-continue value 0.
*> The system should use updated data and continue.
78 ()-U-action-use-updated-data value 4.
*> Others - TBD
5 pic x(2) comp-x.
3 ()-data.
5 ()-I-jseb-ptr pointer.
5 ()-U-ds-name-ptr pointer.
5 ()-U-ds-type pic x(1).
78 ()-U-ds-type-perm value x'00'.
78 ()-U-ds-type-temp value x'80'.
78 ()-U-ds-type-dummy value x'40'.
78 ()-U-ds-type-sysout value x'20'.
78 ()-U-ds-type-terminal value x'10'.
78 ()-U-ds-type-pc value x'08'.
5 pic x(3).
*> DD statement SUBSYS= value length
5 ()-U-subsys-len pic x(4) comp-x.
*> if SUBSYS= value length (previous field) is non-zero,
*> a ptr to entire (including subsystem name, the 1st
*> subparameter) DD SUBSYS= string
5 ()-U-subsys-ptr pointer.
5 pic x(20).
*>==============================================================
This exit, for event-dd-alloc-pre, changes the following listed items and requests, with action-use-updated-data, that the changed information be used to allocate the DD, thus allocating it as a SYSOUT.
It also verifies that it received the expected subsystem-subparameter string.
For the most up-to-date information refer to the source for this copybook in install-dir\base\source.
*>==============================================================
*> Use directives at least: /CHARSET"ASCII"
*> /DIALECT"MF" /DEFAULTBYTE"00"
*>==============================================================
*> Copyright ©) 1997-2008 Micro Focus (IP) Ltd.
*> All rights reserved.
*>
*> This sample source code is provided for use by users of
*> Micro Focus products (the "Software") and may be used,
*> modified and distributed as part of your application provided
*> that you properly acknowledge the copyright of Micro Focus in
*> this material.
*>
*> All conditions, warranties and undertakings, express or implied,
*> statutory or otherwise, on the part of Micro Focus are excluded,
*> including without limitation those of merchantability or fitness
*> for purpose. This shall not, however, purport to exclude or
*> restrict the liability of Micro Focus to any extent not
*> permitted by law.
*>
*> IN NO EVENT WILL MICRO FOCUS BE LIABLE FOR ANY INDIRECT,
*> INCIDENTAL, SPECIAL, CONSEQUENTIAL OR OTHER DAMAGES ARISING OUT
*> OF THE USE OF THE DEMONSTRATION PROGRAM DISTRIBUTED WITH THE
*> SOFTWARE, WHETHER OR NOT INFORMED OF THE POSSIBILITIES OF
*> DAMAGES IN ADVANCE. THESE LIMITATIONS APPLY TO ALL CAUSES OF
*> ACTION, INCLUDING BREACH OF CONTRACT, BREACH OF WARRANTY, STRICT
*> LIABILITY, AND ANY ACTIONS IN TORTS.
*>==============================================================
*>==============================================================
*> Note that subsystem exit is ways named as MFJYssss, where
*> ssss is the subssystem name (1st sub-parameter of SUBSYS=)
*>==============================================================
*>==============================================================
*> SUBSYS Subsystem exit for OODA subsystem
*>==============================================================
identification division.
program-id. MFJYOODA.
environment division.
file-control.
data division.
*>=============================================================
working-storage section.
77 subsys-val-expected pic x(30) value
'OODA,A,DKP39CPM,PPP3,STD,,USER'.
77 msg-dest-both pic 9(8) comp value 0.
77 msg-len pic 9(8) comp value 80.
77 msg-txt pic x(80).
77 w-len pic 99999.
linkage section.
copy "mfjdsxit.cpy" replacing ==()== by ==sxit==.
01 subsys-val pic x(32000).
*>=============================================================
procedure division using by reference sxit.
* Dsa temp >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
* call 'CBL_DEBUGBREAK'
* Dsa temp <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
evaluate sxit-I-event
when sxit-I-event-dd-alloc-pre
*>=======================================================
*> DD is about to be allocated. Change to SYSOUT=*
*>=======================================================
move sxit-U-ds-type-sysout to sxit-U-ds-type
set sxit-U-ds-name-ptr to null
move sxit-U-action-use-updated-data to sxit-U-action
*>=======================================================
*> The code below is informational only. Note that
*> - sxit-U-subsys-ptr points to the the entire
*> SUBSYS string with syntactic quotes removed.
*> - sxit-U-subsys-len is the length of the string
set address of subsys-val to sxit-U-subsys-ptr
if sxit-U-subsys-len <> length subsys-val-expected
move sxit-U-subsys-len to w-len
move ' ' to msg-txt
string 'MFJYOODA - Length should be 30 but is '
delimited by size
w-len delimited by size
into msg-txt
call 'MFJZLOG' using msg-dest-both msg-len msg-txt
end-if
if subsys-val(1:length subsys-val-expected) <>
subsys-val-expected
move ' ' to msg-txt
string 'MFJYOODA - Value incorrect. It is '
delimited by size
subsys-val(1:length subsys-val-expected)
delimited by size
into msg-txt
call 'MFJZLOG' using msg-dest-both msg-len msg-txt
end-if
*> move subsys-val(1:sxit-U-subsys-len) to ...
*>=======================================================
goback
when other
*>=======================================================
*> Ignore all other events
*>=======================================================
continue
end-evaluate
goback.
*>===========================================================
For the most up-to-date information refer to the source in install-dir\base\source.
//MFIDSA1B JOB 'SUBSYS TESTS - VIA JCL',CLASS=A,MSGCLASS=A
//OUTSJ OUTPUT CLASS=X,DEST=SANJOSE.DAVINDER,DEFAULT=YES
//OUTNWB OUTPUT CLASS=Y,DEST=GARDEN.CLIVE,DEFAULT=YES
//OUTHORSE OUTPUT CLASS=M,DEST=HORSES.THAIUSER,DEFAULT=NO
//*-------------------------------------------------------------------
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSUTX DD *
REC1
REC2
//SYSIN DD *
REPRO IFILE(SYSUTX) OFILE(OODA )
REPRO IFILE(SYSUTX) OFILE(NONE )
//OODA DD SUBSYS=(OODA,A,DKP39CPM,PPP3,STD,,USER),
// DSN=MFIDSA.SUBSYS1B.NEW.OODA.NOTUSED,
// OUTPUT=(*.OUTSJ,*.OUTHORSE)
//NONE DD SUBSYS=(NONE,A,DKP39CPM,PPP3,STD,,USER),
// DSN=MFIDSA.SUBSYS1B.NEW.NONE.DELETED,
// OUTPUT=(*.OUTSJ,*.OUTHORSE)
//
Copyright © 2008 Micro Focus (IP) Ltd. All rights reserved.