Set Processing
This section describes Sets and their attributes, how the approval process works, and the Set scheduling system.
Set Overview and Attributes
What is a Set?
Sets are used to group together components for processing and to control the approval process. Task operations that need to be approved must be performed using a Set. Sets can also be used to carry out task operations asynchronously from the user’s online session. Code Pipeline’s optional Deploy feature also requires that Sets be used for the creation of Deploy Requests.
See the Code-Pipeline-User-Guide for details on creating and using Sets.
Set Attributes
Each set has a number of attributes to describe the status of phases of the set processing. The main statuses are:
- Task Status – whether tasks can be altered
- Approval Status – the state of approval
- Processing Status – describes the state of execution.
Task Status
This indicates whether the set has been Locked or Unlocked and represents the action that can be taken on tasks that are associated with the set. It can be specified on the set create.
The Task States are described in the following table.
Task States
State | Description |
|---|---|
Unlocked | Tasks can be added and removed from the set. No approval processing is possible. |
Analyze | Promote Analysis has been performed to check for related components, and it found that errors prevented the processing from continuing. The Set cannot be locked in this state. |
Review | Promote Analysis has been carried out and the Set is eligible to be Locked. Any promote analysis messages will be recorded against the Set. |
Locked | Tasks cannot be added to or removed from the set. Approval processing can begin. |
Unlock and Lock Commands
It is possible to toggle between the Task states by issuing the Unlock and Lock commands against the Set. See the Code-Pipeline-User-Guide for details.
If an unlocked Set is locked, the approval rules are used to build an approver list, which is attached to the Set. If a locked Set is unlocked, the approver list is discarded and any approvals that have been granted are lost.
Approval Status
The Approval status is maintained by Code Pipeline and indicates the approval state of the Set. It can be one of the values listed in the following table.
Approval States
State | Description |
|---|---|
Unknown | Set is unlocked. |
Required | One or more approvals are required before the Set can execute. |
Not Required | No approvals are required for this Set to execute. |
Approved | All the required approvals have been granted, and the Set is free to execute. |
Denied | One or more approvals have been denied. The Set cannot be executed. |
Processing Status
This shows the different states of execution for the Set. The user can specify when the execution will begin by choosing one of the two user-specified states. Code Pipeline maintains the Processing status once Set execution begins. All of the Processing states are described in the following sections.
Processing States – User-Specified
The processing states listed in the following table indicate how the execution of the Set will begin. It can be specified on Set creation or the Set Modify.
Processing States
State | Description |
|---|---|
Released | The Set will be executed once the Set is locked, approvals are granted (if required), and no other constraints exist to stop the Set executing (for example, time). |
Held | The Set will not be executed if the Set is locked and approvals are granted. The Set has to be manually updated to the Immediate state by releasing the set. |
Processing States – Code Pipeline Maintained
Code Pipeline maintains this status to show what stage the Set execution is in. The states are described in the following table.
Processing States - Code Pipeline Maintained
State | Description |
|---|---|
Waiting | The Set has now been passed over to the Code Pipeline Set Scheduling system and is waiting to be executed. It may be waiting for a number of reasons:
|
Executing | The Set is now executing under the control of the Set execution processor. During execution, the Set may pass through a number of phases:
|
Stopping | The Stop command has been entered against an executing Set. At the next available opportunity, the Set will be stopped and the Set state will be “Failed”. |
Failed | Set processing has failed. The Set log can be browsed for more details. If a task operation has failed, the task will be left In Process. The Restart command can be entered against the Set, and processing will resume from the point of failure. |
Complete | Set processing has successfully completed. All tasks are now available to perform further operations. No further processing can be performed by this Set. It can be closed. |
Terminated | The Terminate command has been entered against a failed Set. No further processing can be performed by this Set. It can be closed. |
Starting Sets on Other LPARs
Overview
By default, Sets are started on the same LPAR as the Code Pipeline CM Task. (The CM Task issues the START command.) Code Pipeline provides the capability to start Sets on other LPARs, if this is required.
How it Works
Special M.ER variables are recognized to map the Set Class to a SystemID.
If such a variable is defined, the START command for the Set is wrapped in a ROUTE command, targeted at the required system (LPAR).
M.ER Variable
The format of the M.ER variable name is SX$CLS$ followed by the class name (for example SX$CLS$D for Set Class D). The value assigned to this variable must be a valid CT name executing on the LPAR the Set is to run on.
Example
The following figure shows an example M.ER variable for class D.
M.ER Variable for Class D
Command ===>
Enter required details:
Type Code (KEY) ==> SX$CLS$D View Code (KEY) ==>
Description ==> Target system ID for sets of class D
Variable/Dsname ==> ISPWPCTD
(Fully qualified if data set name, no quotes)
Press ENTER to complete the change or END to terminate
Note: You can add a new entry by overtyping the keys with new unique values
In the above example, Sets that are started with a Code Pipeline class of “D”, will be routed to the system where ISPWPCTD is running.
Approval Process
Task operations can be controlled through an approval process. The approval process can only be used as part of Set processing.
Approval and Approval Rules
The authorization process is referred to as an approval. The rules that define which authorizations are required are called approval rules.
Approval Rules
These are the rules that control which Approvers must grant their approval before the operation can be processed on the components that are covered by the rule.
Approvers
The user or group of users who can grant approval are called Approvers. This is an eight-character name that is mapped to a resource controlled by the external security system (for example, RACF, ACF/2, etc.). Therefore, the actual UserIDs who are authorized to grant approvals are controlled by the external security system and not by Code Pipeline. See Security for details.
Is Approval Required?
Each approval in the approval list is marked as Required or Not Required. Required means that approval must be granted before the Set can be executed. Not Required means that the Set can be executed without the approval being granted, but the Set will still be listed as requiring approval. It can be useful where emergency fixes are necessary when some of the normal approvers, such as Audit, are not available to make the approval but want to be able to approve the Set after the event.
Quorums
Quorums are supported so that a specified number of distinct UserIDs must grant approval for a given approval rule.
Viewing Approval Information
The container list can be used to view Sets and their components. It can also be used to make approvals. The approver group name can be specified so that all the Sets that require approval by that approver will be displayed. See the Code-Pipeline-User-Guide for details.
Change Types
Change types relate to the type of change that a Set was created for and provide additional flexibility. They allow Sets to be grouped to specify different:
- approval rules
- scheduling priorities.
Code Pipeline places no inherent meaning in these types; it merely uses them to determine the processing to use for any given Set.
Default Change Types
Code Pipeline provides three default change types:
- Standard – normal changes
- Emergency – urgent fixes
- Incidental – a special non-urgent change.
A site may add additional user-defined changed types. See CH-Change-Types.
Set Exits
This section describes the sample Set exits provided for optional Set processing.
Set Exit PROCEXIT
This Process Exit can be used to do any processing that is required once the set has been created.
A Process Exit is invoked by initializing the variable PROCEXIT in a generate panel. The following panel example shows how a process exit might be defined in the panel )PROC section to implement the exit when variable WSXOPTN is set to DBUG:
&EXTNCLAS = 'WSXEXTN'
&EXTNVARS = 'WSXOPTN'
VPUT (EXTNVARS WSXOPTN)
IF (&WSXOPTN EQ 'DBUG')
&PROCEXIT = 'WSX@DBUG'
A Process Exit can be used to manipulate the extension variables (EXTNVARS) defined to an extension class (EXTNCLAS). The manipulated values are then passed into the remaining Set process.
Example Exits can be found in the CLIST members WSX@DBUG and WSX@DML.
Set Exit OPEREXIT
Similar to the Process Exit, the Operation Exit can be used to do any processing that is required for a specific operation once the Set has been created. It is executed immediately following any specified Process Exit.
An Operation Exit is invoked by initializing the variable OPEREXIT in a generate panel. The following panel example shows how a process exit might be defined in the panel )PROC section to implement the exit for operation UD (Update Deploy Component Details):
&OPEREXIT = 'WZU@UDS#'
&EXTNCLAS = 'WSXEXTN'
An Operation Exit can be used to manipulate the variables defined to an extension class (EXTNCLAS). The manipulated values are then passed into the remaining Set process.
An example Exit can be found in the CLIST member WZU@UDS#.
Set Pre-Exit for Operations
These exits are defined to M.EX (see EX-Exits) to run prior to the Set Create Panel being displayed.
These exits provide support for an Exit Validation point which would enable an interactive dialog with the user based on the Operation code for which the Set is being created. Other operation pre-exits defined in M.EX run in the background as part of the Set Processing, so they cannot provide the sort of end user interaction that is sometimes required.
To enable this feature in Code Pipeline, the M.ER (see ER-External-References) variable WZUOPVER must be set to 'Y'. This just enables support for the new exit point and ensures that the appropriate validation exits will be called for any operations that are defined with an exit key of @@@@.
A new Exit is activated to validate the operation if the M.EX table has an entry with an Exit Key of @@@@ for the applicable operation code and Member Environment. If the exit wants to fail the operation, it should return with a code of 4; otherwise it should return with code 0.
The operation code is presented in the shared pool variable OPCODE. See the sample exit WZUOPVER for a list of the other variables that are available. The Sample Exit provided shows how to limit validation to promote operations from the signout level. The sample will prevent any component with the name STOPME from being promoted.
Set Create Pre-Exit
This exit is similar to the Set Operation Pre-exit in that it is executed prior to the Set Create Panel being displayed, but this exit is executed regardless of the OPCODE being processed by the set and does not require M.EX table entries.
To enable this feature in Code Pipeline, the M.ER (see ER-External-References) variable WSETCRPX must be added to the table.
The following figure shows a sample definition of this variable which instructs Code Pipeline to execute CLIST WZUSETPX prior to displaying the Set Create Panel.
Set Create Pre-Exit
Command ===>
Enter required details:
Type Code (KEY) ==> WSETCRPX View Code (KEY) ==> $TAB
Description ==> USER SET CREATE PRE-EXIT
Variable/Dsname ==> ISPEXEC SELECT CMD(%WZUSETPX &DEBUG)
(Fully qualified if data set name, no quotes)
Press ENTER to complete the change or END to terminate
Note: You can add a new entry by overtyping the keys with new unique values
If the key value, View Code, is set to $TAB, the selected tasks being passed to the Set Create process will be made available in the table $WSETCRn, where n=current value assigned to variable ZSCREEN.
Sample Exits can be found in the CLIST members WZUSETPX (uses $TAB) and WZUSETPZ (does not use $TAB).
Set Lock Exit
Set Lock Exits are executed after the user has pressed Enter on the Set Create Panel or when the user enters the command to Lock the Set from the Modify/Approve Set Panel. See the Code-Pipeline-User-Guide for details.
To enable this feature in Code Pipeline, the M.ER (See ER-External-References) variable EXSTLOCK must be added to the table.
The following figure is a sample definition of this variable which instructs Code Pipeline to execute CLIST WZUAPPR prior to locking the Set.
Set Lock Exit
Command ===>
Enter required details:
Type Code (KEY) ==> EXSTLOCK View Code (KEY) ==>
Description ==> USER SET LOCK EXIT
Variable/Dsname ==> ISPEXEC SELECT CMD(%WZUAPPR &DEBUG)
(Fully qualified if data set name, no quotes)
Press ENTER to complete the change or END to terminate
Note: You can add a new entry by overtyping the keys with new unique values
Set Analyse Exit
Set analyse exits are executed before the set has finished the lock process. The purpose of the set analyse exit is to provide for a way to prevent a set from locking if it is deemed invalid by the exit.
To enable the set analyse exit, M.ER variable EXSTALYS must be added, and M.AD/L configuration must be updated.
The M.ER variable EXSTALYS should be defined with a value similar to the EXSTLOCK M.ER variable. For example, the following M.ER definition will run the WZUALYS CLIST immediately after locking a set:
Command ===>
Enter required details:
Type Code (KEY) ==> EXSTALYS View Code (KEY) ==>
Description ==> USER SET ANALYSE EXIT
Variable/Dsname ==> ISPEXEC SELECT CMD(%WZUALYS &DEBUG)
(Fully qualified if data set name, no quotes)
Press ENTER to complete the change or END to terminate
Note: You can add a new entry by overtyping the keys with new unique values
Additionally, each level in each application must have a "Set Analysis" value set to either C or A to run the set analyse exit at that level. See AD-S-L-Levels for an explanation of the options.
The M.ER variable EXSTLOCK with view code OPT must also be defined with a value of "A" to enable the Set Analyse Exit.
Command ===>
Enter required details:
Type Code (KEY) ==> EXSTLOCK View Code (KEY) ==> OPT
Description ==> ENABLE NEW USER SET ANALYSE EXIT
Variable/Dsname ==> A
(Fully qualified if data set name, no quotes)
Press ENTER to complete the change or END to terminate
Note: You can add a new entry by overtyping the keys with new unique values
Considerations for Writing the Set Analyse Exit
The Set Analyse Exit controls the execution of a set through return codes from the exit, and through the impact messages added to the running set.
As of PTF IWH108A, the Set Analyse Exit runs before the set is fully locked. This allows for set metadata to be changed within the exit.
Return Codes
Valid return codes for the set analyse exit are:
Return Code | Set Action |
|---|---|
0 | Indicates that no issues were detected during set analysis. The set continues on as normal. |
4 | Indicates that issues were detected during set analysis. The set is paused and put into a REVIEW status. |
Neither 0 or 4 | Indicates that set analysis failed when return code is other than 0 or 4. The set is put into an EXIT FAILED status. |
REVIEW Status and Impact Messages
When the set is in a REVIEW status, the set may be locked again to acknowledge any impact messages on the set. These messages would have been added by the set analyse exit. This is typically done using the #IMPTMSG WZZTSI calls.
If any impact messages have imsglvl 'E', then the set will not be able to be locked. In order to process the tasks in the set, they will need to be first removed from the set. Then, any error messages on the tasks will need to be addressed. After the user is sure the error messages are addressed, they can then process the previously rejected tasks in a new set.
As of IWH091A, sets in a REVIEW status can be unlocked, which allows them to be modified and locked again. Once locked again, the set analyse exit will run, which allows for a user to correct any mistakes discovered by the analyse exit.
To add messages to the set for the REVIEW status, the following WZZTSI calls can be used:
Object | Method | Input Variables | Description |
|---|---|---|---|
#IMPTMSG | ADDTASK | WTAPPLID, WTSUBAPL, WTSTRM, WTMTYPE, WTMNAME, WTCLVL, WTCDLNID, IMSGTEXT, IMSGACPT, IMSGLVL | Adds an impact message to an active task. |
#IMPTMSG | ADDCNTR | IPROJNO, ICNTYPE, IMSGTEXT, IMSGACPT, IMSGLVL | Adds an impact message to a container. |
The following input variables defines the message contents for the #IMPTMSG ADDTASK and #IMPTMSG ADDCNTR WZZTSI calls:
Variable | Description |
|---|---|
IMSGTEXT | The text of the impact message. |
IMSGACPT | If 'Y', then the impact message will require acknowledgement. |
IMSGLVL | The severity level of the impact message.
|
The following input variables uniquely selects a task to add an impact message for the #IMPTMSG ADDTASK WZZTSI call:
Variable | Description |
|---|---|
WTAPPLID | Application of the task |
WTSUBAPL | Subapplication of the task |
WTSTRM | Stream of the task |
WTMTYPE | Type of the task |
WTMNAME | Name of the task |
WTCLVL | Current level of the task |
WTCDLNID | Code line ID of the task, if applicable |
The following input variables uniquely selects a container to add an impact message for the #IMPTMSG ADDCNTR WZZTSI call:
Variable | Description |
|---|---|
IPROJNO | The ID of the container |
ICNTYPE | The type of the container |
Set Post Exit WZUSETX
This exit is provided with the Code Pipeline base code and is called when all standard set processing has been completed. The provided sample version of this exit sends email messages to the designated addressees for set completion notification and submits a batch job to perform any needed CICS NEWCOPY requests and/or LLA refresh requests via a provided skeleton.
You can locate the WZUSETX file in both the base product CLIST library (SPWMCLST) and the SKEL library (SPWMSKEL). These files serve as samples that can be copied to your SITE LIB. After adding them to the SITE LIB, you can modify these samples according to your specific post-set requirements.
Set Post Exit can be enabled for deploy requests by properly setting the values of M.ER variables, SXDPPOST and SXDPFAIL. Enabling this feature will cause another SX task to be run when a deploy request within a set fails, or when all deploy requests within a set complete.
The values of SXDPFAIL and SXDPPOST work together to control the behavior of the set post exit for deploys. The following table describes this behavior:
SXDPPOST value | SXDPFAIL value | Post exit runs for successful deploy? | Post exit runs for failed deploy? |
|---|---|---|---|
Y | blank, not defined, or * | Yes | Yes |
Y | A space delimited list of valid deploy environment names | Yes | Yes, only if deploy environment is listed in SXDPFAIL |
Y | An invalid deploy environment name | Yes | No |
blank or not defined | blank or not defined | No | No |
blank or not defined | * | No | Yes |
blank or not defined | A space delimited list of valid deploy environment names | No | Yes, only if deploy environment is listed in SXDPFAIL |
The WZUSETX exit contains the variables SXPARM and SXSTATUS. These variables provide details about the related deploy.
The possible values for SXPARM are:
- POST - The exit is running for a standard set Post Exit.
- DPLY - The exit is running for a set Post Exit which occurred after a deploy.
The possible values for SXSTATUS are:
- I - Set is ready for immediate execution.
- H - Set is held.
- W - Set is waiting for execution.
- E - Set is executing.
- P - Set is stopping after user issues stop command on modify set panel.
- F - Set has failed.
- C - Set is complete.
- T - Set is terminated.
The possible values for SXSTATUS during a deploy are:
- 0 - Deploy is confirmed.
- 1 - Deploy is staged.
- 2 - Deploy is implemented.
- 5 - Deploy is completed.
- 9 - Deploy is failed.
For a set which runs a non-deploy operation before an automatic deploy, with the SXDPPOST M.ER variable set to Y, you will see 2 runs of the set Post Exit. The first run will occur immediately before the deploy request runs with SXPARM = "POST", and the 2nd run will occur immediately after the deploy request succeeds or fails with SXPARM = "DPLY".