Operation-status-change exit (User Exit 7)
The operation-status-change exit (User Exit 7) is called whenever an operation in the current plan changes status. The exit is also called when a new operation is added to the current plan by a function other than by daily planning jobs, for example by PIF or the MCP dialog. The exit is called when the operation is added either to an existing occurrence or as a result of a new occurrence added to the current plan. The User Exit 7 is not called for operations that are added at daily planning. The exit can be used to modify the USERDAT field of the OPERAREA parameter. The exit cannot modify other parameters passed to it or other HCL Workload Automation for Z data or resources. It can examine the parameters and take some action external to HCL Workload Automation for Z based on the parameter information.
HCL Workload Automation for Z invokes the User Exit 7 in AMODE 31 and RMODE 24.
- Perform the functions described in Utility functions included in the user exits.
- Update the User Text field of the occurrence that triggers the user exit.
Editing the exit
exit7.h
, which contains the following routine: - void updateOperUsrdat(char *newUsrDat[], struct exit7struct *params)
- To update the User Text field of the occurrence with the string
newUsrDat
. ThenewUsrDat
input must end with the end-of-text character\0
, which corresponds to byte0
, and can be up to 16 characters excluding the end-of-text character. Theparams
input is the same as the input passed to the routineexit7do
.
struct exit7Struct
structure, which is
provided as an input to the routine exit7do
. Each string in the data structure
is expanded by 1 character to reserve space for the end-of-text character \0
,
which corresponds to byte 0
. User Exit 7 parameters
struct exit7Struct{
char newStat;
char oldStat;
short int opNum;
char caller[CALLER_LEN+1];
char errCode[ERRCODE_LEN+1];
char wsName[WSNAME_LEN+1];
char adName[ADNAME_LEN+1];
char owner[OWNER_LEN+1];
char group[GROUP_LEN+1];
struct jobAreaStruct jobArea;
struct operAreaStruct operArea;
void *mcaUserF;
char extStat;
void *occPtr;
void *oprPtr;
int usrFNr;
void *usrFArea;
} ;
#define OPNUM_LEN 5
#define CALLER_LEN 4
#define ERRCODE_LEN 4
#define WSNAME_LEN 4
#define ADNAME_LEN 16
#define OWNER_LEN 16
#define GROUP_LEN 8
where:- NEWSTAT
- New status of the current operation:
- *
- Ready for processing (predecessor at nonreporting workstation complete)
- A
- Arrived at the workstation
- C
- Complete
- E
- Ended with errors
- I
- Interrupted
- R
- Ready for processing
- S
- Active (started)
- W
- Waiting
- OLDSTAT
- Previous status of the current operation:
- blank
- The operation was added to the current plan by a function other than a daily-planning job. No call is made to User Exit 7 when operations are added to CP by daily-planning jobs.
- *
- Ready for processing (predecessor at nonreporting workstation complete)
- A
- Arrived at the workstation
- C
- Complete
- E
- Ended with errors
- I
- Interrupted
- R
- Ready for processing
- S
- Active (started)
- W
- Waiting
- OPNUM
- Number of the current operation.
- CALLER
- Function within HCL Workload Automation for Z that called the exit:
- AR
- Automatic-recovery task
- EM
- Event-manager task
- GS
- General-service task, but not modify-current-plan
- MCP
- Modify-current-plan function in the general-service task
- NMM
- Normal-mode-manager task
- WSA
- Workstation-analyzer task
- ERRCODE
- Error code of the current operation, if the new status is E.
- WSNAME
- Name of the workstation where the current operation is active or will become active.
- ADNAME
- Application name for the current operation.
- OWNER
- Name of the owner of the current application.
- GROUP
- Name of the authority group to which the current operation belongs.
- JOBAREA
- Sub-structure containing information about the status changes related to a specific job.
The job-related area is mapped as follows:
struct jobAreaStruct{ char jobName[JOBNAME_LEN+1]; //job name char jobNum[JOBNUM_LEN+1]; //job number char jobDate[JOBDATE_LEN+1]; //current date char jobStart[JOBSTART_LEN+1]; //start time char jobEnd[JOBEND_LEN+1]; //end time char jobStep[JOBSTEP_LEN+1]; //step name char jobAbSys[JOBABSYS_LEN+1]; //system abend code char jobAbUsr[JOBABUSR_LEN+1]; //user abend code char jobONJEN[JOBONJEN_LEN+1]; //origin nje node char jobPStep[JOBPSTEP_LEN+1]; //proc step name } ; #define JOBNAME_LEN 8 #define JOBNUM_LEN 8 #define JOBDATE_LEN 8 #define JOBSTART_LEN 8 #define JOBEND_LEN 8 #define JOBSTEP_LEN 8 #define JOBABSYS_LEN 8 #define JOBABUSR_LEN 8 #define JOBONJEN_LEN 8 #define JOBPSTEP_LEN 8
The JOBNAME and JOBDATE parameters are always present for status changes at automatically reporting computer and printer workstations. JOBNUM is present when an operation at automatically reporting computer and printer workstations changes its status from S to C. When the job is submitted by a fault-tolerant workstation, the first three characters of the JOBNUM value are set to UNX by HCL Workload Automation for Z.
The status is changed to S (Started). The JOBNUM value can change only if the operation is rerun. JOBSTART is present when the new status at automatically reporting computer and printer workstations is S (Started), C (Complete), E (Ended-in-error), or I (Interrupted). JOBEND is present when the new status at one of these workstations is C or E.
JOBSTEP, JOBPSTEP, JOBABSYS, and JOBABUSR are present only for jobs that have abended during running. JOBONJEN is present for processing operations when the new status is C or E. When the status of an operation is changed from C or E to S, C, E, or I, certain JOBAREA fields are set to their previous values for that operation. Fields in the job-related area are blank if information is not available when the exit is called.
- OPERAREA
- Sub-structure containing information about the operation whose status is being changed. It
is mapped as follows:
struct operAreaStruct{ char opText[OPTEXT_LEN+1]; //oper user data char opIA[OPIA_LEN+1]; //occ input arrival char opOpIA[OPOPIA_LEN+1]; //oper input arrival char opStartD[OPSTARTD_LEN+1]; //oper planned start date char opStartT[OPSTARTT_LEN+1]; //oper planned start HHMM char opEndD[OPENDD_LEN+1]; //oper planned end date char opEndT[OPENDT_LEN+1]; //oper planned end HHMM char opDl[OPDL_LEN+1]; //oper deadline char *opUsrDat; //oper user data pointer (16 bytes) char opRsPresent; //Y=reason exist char opRsErr[OPRSERR_LEN+1]; //err code set by user char opRsUsr[OPRSUSR_LEN+1]; //user data field from dialaog char opRsReason[OPRSREASON_LEN+1]; //reason char opRsPanel[OPRSPANEL_LEN+1]; //panel where set char opJName[OPJNAME_LEN+1]; //extended job name char opSaWS; //new automation ws } ; #define OPTEXT_LEN 24 #define OPIA_LEN 10 #define OPOPIA_LEN 10 #define OPSTARTD_LEN 6 #define OPSTARTT_LEN 4 #define OPENDD_LEN 6 #define OPENDT_LEN 4 #define OPDL_LEN 10 #define OPUSRDAT_LEN 16 #define OPRSERR_LEN 4 #define OPRSUSR_LEN 16 #define OPRSREASON_LEN 300 #define OPRSPANEL_LEN 8 #define OPJNAME_LEN 54
- MCAUSERF
- User field that is also passed to the User Exit 0. It contains valid data only if you have a User Exit 0 exit that places some data in it. HCL Workload Automation for Z does not use or update this field.
- EXSTAT
- Extended status code of the operation. For a list of the valid codes, see . For performance reasons, user exit 7 does not currently provide the extended status X (waiting for resource). A new value, Z, valid for all current status codes and types of workstation, has been added to signal that an error has occurred in the DOA updating process. In this case, message EQQE106I is issued in EQQMLOG.
- OCCPTR
- Address of the common data of record CPLREC3C.
- OPRPTR
- Address of the common data of record CPLREC3P.
- USRFNR
- Number of user field records in USRFAREA.
- USRFAREA
- Address of the user field area, in a format as in the following example: