Job card user exits
This exit allows you to indicate when to begin a new job. However, do not use this exit with workload balancing. We recommend using syntax options to control job splitting.
Types of calls
The following table describes the user exit includes the types of calls.
Type of call | Description |
|---|---|
Initialization | called once for user-required resource allocation |
Job | called for each object selected; job name and other job card parameters might be changed |
Termination | called once to release resources acquired during initialization |
Number of jobs generated
The following BMCTRIG options determine the number of jobs generated:
- NUMJOBS or MINJOBS is the number of jobs to generate.
- MAXOBJECTS is the maximum number of objects per job.
- MAXSTEPS is the maximum number of steps per job (not available in the exit).
The sample user exit generates new jobs, at least until the MINJOBS value is reached. If the user exit generates enough jobs to process all objects with exceptions before reaching the NUMJOBS value, null IEFBR14 jobs are generated for the remaining jobs. For example, if you specify NUMJOBS=4 and the first three jobs include all selected objects, a fourth job is still generated. The fourth job contains only an IEFBR14 step.
If you are not doing workload balancing and BMCTRIG finds more exceptions than the specified minimum number of jobs can contain, it continues to produce jobs until all objects with exceptions have been placed in jobs. If you are performing workload balancing, after BMCTRIG generates the number of jobs, BMCTRIG does not add work, and exceptions remain active.
Job name changes
The default code for the job card exit returns the job card that is passed to it.
The job card that is passed is usually the job card image of the first job card specified when you define the BMCTRIG utility in DASD MANAGER PLUS. To change the job name or other job card parameters specified in the BMCTRIG utility, you must edit the job card user exit. .
The product generates a separate job step for each object and utility that you select. If the generated job exceeds 255 steps (the maximum number per job), the product generates a new job and job name, regardless of whether or not the maximum number of objects per job was reached.
Job names consist of the following parts:
- Basic job name, composed of a variable or literals
- Job sequence variable (see the following table)
Keep the following items in mind:
- When specifying the STDJCL Y option and using job name variables, avoid placing the numbers after &JOBSEQ unless you want to specify &JOBSEQ1 or &JOBSEQ2 and so on. Also, avoid using the variable &WKID8.
- JCLGEN increments the job sequence number by 1 for each BMCTRIG-generated standard job to a maximum count of 999 (for &JOBSEQ).
- This column indicates the first job name generated unless you specify a different beginning sequence number by using the Beginning Seq Num option.
JCL Generation increments the job sequence number by 1 each time it generates a new job. The maximum number of jobs one BMCTRIG utility can generate in Standard JCL format is 999. However, if you select Job Sequence Type A (for alphanumeric; 0 to 9 and A to Z) in the JCL Generation options, the BMCTRIG utility can generate up to 46,655 jobs.
The resolved job name cannot contain more than eight characters, whether the name is resolved through the job card user exit or through variable substitution.
Source code
This topic describes the Assembler source for the job card user exit.
The following figure shows the Assembler source for the job card user exit.
The source is located in the HLQ.CNTL library member ASUXJBCD. The exit parameter list (see below), including input data should not be altered by the exit routine.
Assembler job card user exit
SPACE 1
***********************************************************************
* *
* ENTRY POINT: ASUXJBCD *
* *
* PURPOSE: CHANGE JOBNAME AND OPTIONALLY ANY OTHER JOBCARD *
* PARAMETER *
* *
* STATE: PROBLEM STATE, USER KEY, AMODE 31 *
* *
* REGISTER-USAGE: *
* *
* R12 - BASE ADDRESS *
* R13 - ADDRESS SAVE AREA *
* R14 - RETURN ADDRESS/WORK *
* R15 - ENTRY POINT/WORK *
* *
* INPUT: ADDRESS XPL (EXIT PARAMETER LIST) *
* *
* OUTPUT: R15 - RETURN CODE *
* *
* 0 - (XPLRCNRM) NORMAL *
* 4 - (XPLRCNEW) CREATE NEW JOB *
* 8 - (XPLRCERR) ERROR *
* *
* NOTE: ASUXJBCD IS CALLED BY DASD MANAGER (JCL OPTION ONLY) *
* DURING JOB GENERATION. THERE ARE THREE TYPES OF CALLS *
* (PARAMETER XPLTYPE); INITIALIZATION, JOB, AND *
* TERMINATION. *
* *
* 1. INITIALIZATION - CALLED ONCE FOR USER REQUIRED *
* RESOURCE ACQUISITION. *
* *
* 2. JOB - CALLED FOR EACH OBJECT SELECTED. THE JOB NAME *
* AND OTHER JOB CARD PARAMETERS MAY BE CHANGED. THE *
* JOB SEQUENCE COUNTER (XPLJBSEQ) STARTS WITH A VALUE *
* OF ZERO AND IS INCREMENTED BY ONE WHEN THE EXIT *
* RETURNS WITH R15 SET TO 4 (XPLRCNEW). A RETURN CODE *
* OF 4 INDICATES THAT A NEW JOB IS TO BE CREATED. *
* *
* 3. TERMINATION - CALLED ONCE TO RELEASE RESOURCES *
* ACQUIRED DURING INITIALZATION. *
* *
***********************************************************************
SPACE 1
ASUXJBCD CSECT
ASUXJBCD AMODE 31
ASUXJBCD RMODE ANY
SPACE 1
USING *,R12
SPACE 1
SAVE (14,12),,* SAVE REGISTERS
SPACE 1
LR R12,R15 BASE REGISTER
L R1,0(,R1) GET ADDR XPL
ST R13,4(,R1) BACKWARD SAVE AREA CHAIN
ST R1,8(,R13) FORWARD SAVE AREA CHAIN
LR R13,R1 SAVE AREA
SPACE 1
USING XPL,R13 ADDRESSABILITY TO EXIT PARAMETERS
SPACE 1
CLC XPLTYPE,=AL2(XPLJOB) JOBNAME REQUEST?
BE JBCDJOB YES, BRANCH
CLC XPLTYPE,=AL2(XPLTERM) TERMINATION REQUEST?
BE JBCDTERM YES, BRANCH
LA R15,XPLRCERR ERROR RETURN CODE
CLC XPLTYPE,=AL2(XPLINIT) INITIALIZATION REQUEST?
BNE JBCDEXIT NO, BRANCH
SPACE 1
*---------------------------------------------------------------------*
* INITIALIZATION REQUEST *
*---------------------------------------------------------------------*
SPACE 1
* ADD ANY RESOURCE INITIALIZATION CODE
B JBCDRET BRANCH TO RETURN
SPACE 1
*---------------------------------------------------------------------*
* CHANGE JOBNAME AND OPTIONALLY OTHER JOB CARD PARMS *
*---------------------------------------------------------------------*
SPACE 1
JBCDJOB DS 0H
ICM R0,B'1111',XPLJBSEQ VALID JOB SEQUENCE NUMBER?
BZ JBCDNEWJ NO, BRANCH
CLC XPLSTSEQ,=F'255' TOO MANY STEPS FOR THIS JOB? V18850
BNL JBCDNEWJ YES, BRANCH
*****************************************************************
*** ***
*** THE FOLLOWING BLOCK OF CODE FORCES A NEW JOB FOR REBINDS ***
*** ***
*****************************************************************
* CLC XPLUTIL,=CL8'REBIND' DOING REBINDS ?
* BE JBCDNEWJ YES, THEN DO THEM IN A NEW JOB
*******************************************************************
*** ***
*** THE FOLLOWING BLOCK OF CODE CAN BE USED TO CONTROL THE ***
*** NUMBER OF STEPS IN EACH JOB WITH A USER SPECIFIED AMOUNT ***
*** OF STEPS. THE NUMBER OF REQUESTED STEPS PER JOB IS ***
*** CURRENTLY SET TO 90, BUT CAN BE CHANGED TO ANY NUMBER ***
*** BETWEEN 1 AND 254. ***
*** ***
*** THE FOLLOWING BLOCK OF CODE ALSO ATTEMPTS TO MAINTAIN THE ***
*** CONSISTENCY OF EACH UTILITY/OBJECT UNIT OF WORK. THIS ***
*** IMPLIES THAT FOR EACH OBJECT SELECTED, BMCTRIG WILL TRY ***
*** TO GENERATE EACH UTILITY SPECIFIED IN THE SKELETON BEFORE ***
*** STARTING A NEW JOB. ***
*** ***
*******************************************************************
* CLC XPLSTSEQ,=F'90' NUMBER OF STEPS PER JOB > 90 ***
* BL JBCDRET NO, RETURN (IGNORE MAXOBJS) ***
* CLI XPLLUWI,C'N' LUW IN PROGRESS ***
* BE JBCDNEWJ NO, OK TO BUILD NEW JOB ***
* B JBCDRET RETURN (IGNORE MAXOBJS) ***
*******************************************************************
* CLC XPLOBSEQ,XPLMXOBJ OBJECTS EXCEEDS MAX PER JOB?
* BH JBCDRET YES - GET OUT, BRANCH
SPACE 1
JBCDNEWJ DS 0H
CLI XPLOBJT,C' ' END OF OBJECTS?
BE JBCDBR14 YES, BRANCH FOR BR14 JOBS
SPACE 1
* ADD SPECIFIC JOB NAME AND OTHER JOB CARD CHANGES
SPACE 1
* FINE MODIFICHE
SPACE 1
JBCDBR14 DS 0H
* ADD SPECIFIC JOB NAME AND OTHER JOB CARD CHANGES FOR IEFBR14 JOBS
* LA R15,XPLRCNEW CHANGED JOBNAME/JOBCARD
B JBCDEXIT BRANCH TO RETURN
SPACE 1
*---------------------------------------------------------------------*
* TERMINATION REQUEST *
*---------------------------------------------------------------------*
SPACE 1
JBCDTERM DS 0H
* ADD ANY RESOURCE TERMINATION CODE
SPACE 1
*---------------------------------------------------------------------*
* EXIT *
*---------------------------------------------------------------------*
SPACE 1
JBCDRET DS 0H NORMAL RETURN
SLR R15,R15 ZERO RETURN CODE
SPACE 1
JBCDEXIT DS 0H
L R13,4(,R13) RESTORE CALLER'S SAVEAREA
SPACE 1
RETURN (14,12),RC=(15)
SPACE 1
*---------------------------------------------------------------------*
* CONSTANTS AND LITERALS *
*---------------------------------------------------------------------*
SPACE 1
LTORG
SPACE 1
*---------------------------------------------------------------------*
* REGISTER EQUATES *
*---------------------------------------------------------------------*
SPACE 1
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
SPACE 1
*---------------------------------------------------------------------*
* EXIT PARAMETER LIST *
*---------------------------------------------------------------------*
SPACE 1
XPL DSECT
XPLSAVE DS 18F SAVE AREA FOR EXIT
* *
* INPUT DATA THAT SHOULD NOT BE ALTERED BY THE EXIT ROUTINE *
* *
XPLTYPE DS H TYPE
XPLINIT EQU X'00' INITIAL
XPLJOB EQU X'01' JOBNAME/JOBCARD
XPLTERM EQU X'02' TERMINATION
SPACE 1
DS XL2 RESERVED
XPLMXOBJ DS F OBJECTS PER JOB
XPLMNJOB DS F MINIMUM NUMBER OF JOBS
XPLOBSEQ DS F OBJECT SEQUENCE NUMBER
XPLJBSEQ DS F JOB SEQUENCE NUMBER
XPLSTSEQ DS F STEP SEQUENCE NUMBER
SPACE 1
* *
XPLSSID DS CL4 SUBSYSTEM ID
XPLWKID DS CL20 WORK ID V428019
XPLUSRID DS CL8 USER ID
XPLSKEL DS CL20 TRIGGER SKELETON NAME V428019
XPLUTIL DS CL8 UTILITY
XPLDB DS CL8 DATABASE NAME
XPLCR DS CL128 CREATOR NAME V527034 F44256
*PLCR EQU XPLDB,L'XPLDB,C'C' CREATOR NAME F44256
XPLIX DS CL128 INDEX NAME V527034V513868
XPLTS DS CL8 TABLESPACE NAME F44256
*PLTS EQU XPLIX,8,C'C' TABLESPACE NAME F44256
XPLOBJT DS CL2 OBJECT TYPE (IX OR TS)
XPLPART DS H PARTITION NUMBER
SPACE 1
XPLJDSN DS CL56 JCL DSN
XPLLUWI DS CL1 LOGICAL UNIT OF WORK INDICATOR
DS 10F RESERVED
XPLIDATA EQU XPL,*-XPL,C'C' INPUT DATA AREA
* *
* WORK AREA FOR EXIT ROUTINE PRESERVED ACROSS CALLS *
* *
* ON FIRST CALL, XPLJBCD IS INITIALIZED TO THE FIRST JOB CARD *
* FROM THE JOB CARDS FOR TRIGGERED JOB(S) ON PANEL ASUJSPR9. *
* ON SUBSEQUENT CALLS, XPLJBCD WILL CONTAIN THE JOB CARD *
* AS ALTERED BY THE PREVIOUS CALL. *
* *
XPLJBCD DS CL80 JOB CARD
XPLJBNM EQU XPLJBCD+2,8,C'C' JOB NAME
* *
DS 0D
XPLDATA DS CL256 USER DEFINED DATA AREA
SPACE 1
XPLUDATA EQU XPLJBCD,*-XPLJBCD,C'C' USER DATA AREA
XPLTDATA EQU XPL,*-XPL,C'C' TOTAL DATA AREA
SPACE 1
* RETURN CODES *
XPLRCNRM EQU 0 NORMAL
XPLRCNEW EQU 4 CREATE NEW JOB
XPLRCERR EQU 8 ERROR - TERMINATE PROCESS
SPACE 2
END
Sample JCL for assembling and linking the job card user exit
If you need to edit the job card user exit, use the following sample JCL to assemble and link the exit into the product load library.
Assemble step for job card user exit
// class="A",MSGCLASS=X,MSGLEVEL=(1,1)
//*
//ASMSLIB PROC SLIBNAME=, SLIB BEING PROCESSED
// HLQ=, HIGH LEVEL DSN OF BMC LIBRARIES
// ASMSTEPL=SYS1.LINKLIB CAN BE SYS1.LINKLIB IF IN LPA
//*-------------------------------------------------
//* ASSEMBLE THE MODULE
//*-------------------------------------------------
//ASM EXEC PGM=ASMA90,COND=(4,LT),
// PARM=('DECK,NOOBJ,LIST,TEST,TERM,RENT',
// 'LINECOUNT(75)','XREF(SHORT)','SYSPARM(DEV)')
//STEPLIB DD DISP=SHR,DSN=&ASMSTEPL
//SYSPUNCH DD DSN=&&OBJ(&SLIBNAME),DISP=(NEW,PASS),
// DCB=(LRECL=80,RECFM=FB,BLKSIZE=6160),
// SPACE=(CYL,(1,1,1)),UNIT=WORK
//SYSPRINT DD SYSOUT=*
//SYSTERM DD DUMMY
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(15,5))
//SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(15,5))
//*
//SYSIN DD DISP=SHR,DSN=YOUR.DASDMANAGER.CNTL(ASUXJBCD)
//SYSLIB DD DISP=SHR,DSN=&HLQ..CNTL
// DD DISP=SHR,DSN=SYS1.MACLIB
// DD DISP=SHR,DSN=SYS1.AMODGEN
//*------------------------------------------------------
//* LINK THE MODULE
//*------------------------------------------------------
//LINK EXEC PGM=IEWL,COND=(4,LT),
// PARM=('SIZE=(962560,86016),LIST(ALL)',
// 'RENT,AC(1),LIST,MAP,XREF,LET,AMODE(31),RMODE(ANY)')
//SYSPUNCH DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSTERM DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(10,5))
//*
//SYSLIB DD DSN=&&OBJ,DISP=(OLD,DELETE,DELETE)
//SYSLMOD DD DISP=SHR,DSN=&HLQ..LOAD
// PEND
//*
//ASMIT EXEC ASMSLIB, NAME OF INSTREAM PROC DEFINED
// SLIBNAME=ASUXJBCD, SLIB TO PROCESS
// HLQ=YOUR.DASDMANAGER.HLQ, HIGH LEVEL DSN OF BMC LIBS
// ASMSTEPL=SYS1.LINKLIB DEFAULTS SYS1.LINKLIB
//LINK.SYSLIN DD *
INCLUDE SYSLIB(ASUXJBCD)
ENTRY ASUXJBCD
NAME ASUXJBCD(R)
/*