How to maintain different versions of a COBOL copybook for use in Dev, QA and Prod.

[Wayne Murray]

I am new to Endevor and this community.  

I support a COBOL CICS appllcation that runs on the mainframe.

We are putting our current CICS application into Endevor and I understand the basic functionality of Endevor, but I cannot figure out how to handle the following situation.

We have three environments - Dev, QA and PROD, each associated with its own CICS region.

Some of our COBOL copybooks are unique to each environment.  Let's assume one is named 'MYCBTAB1'.

There is a unique version of 'MYCBTAB1' for Dev, another for QA and another for PROD.  They all share the same purpose and have the same structure, but the contents are different by environment.  One possible use might be to define a list of privileged users for each environment.

Endevor does not appear to provide a means for supporting a copybook like this that is different for each environment in the lifecycle.

So, we have the standard 4 levels of libraries; DEV, QA, EMER and PROD.

The normal progression is to Add/Update in DEV, then Move to QA, and then Move to PROD.  EMER allows elements to be pulled from PROD and then Moved back to PROD bypassing DEV and QA for quick fixes.

As is, Endevor does not allow me to Add/Update an element directly to QA or PROD.  I can only Add/Update to DEV and EMER.

So, by using EMER I can effectively maintain a different version of 'MYCBTAB1' in PROD.  And since I can do Add/Update in DEV I can also maintain a different version of 'MYCBTAB1' in DEV.  The problem is with QA.  Since I cannot Add/Update straight to QA the only way to get 'MYCBTAB1' into QA is to move it from DEV in which case it will be the same version as in DEV.

Is it possible to define an "EMER" like set of libraries for QA such as EMERQA that would act the same as the EMER libraries for PROD?

Then I could maintain a different version of 'MYCBTAB1' in QA by doing an Add/Update to EMERQA and then moving it to QA.

'MYCBTAB1' would never be moved from DEV to QA, or from QA to PROD.

Is something like this possible? 

Is there some other method provided by Endevor that would allow us to maintain different variations of 'MYCBTAB1' between DEV, QA and PROD?

I am sure this need to maintain different versions of a copybook across environments is not unique to us.  How do other folks address this situation with Endevor?  Or is this something to be avoided?

Thanks,

Wayne Murray

[Dave Harding]

You have 4 versions of MYCBTAB1 in 4 different copybook datasets; one per stage. It's painful to modify the intermediate versions; i.e. you have overlay DEV to update QA, then you have to put the original DEV back in place.  There’s no good way to perform a direct update to an intermediate stage; doing so (via the transfer action) would cause issues and be confusing to maintain. Instead, I would consider a special process for these special copybooks.

   I like Dana’s recommendation; if you can use a rexx to transform a single version of the element into whatever’s needed for a given stage, that sounds like the way to go. If not, read on.

   In order to have multiple versions of MYCBTAB1, Endevor needs them in either a different system, different subsystem, or different type.  Or… it needs 4 different element names.

   This would be my first suggestion; using different names. Using a new type copybook processor group, let’s call is CICSCPY, you can build a special generate processor; GCICSCPY, and let it sort out where to put the copybook.  Example; the QA version of MYCBTAB1 is added to Endevor with an element name of MYCBTABQ and using processor group CICSCPY. The GCICSCPY processor is nothing more than IF/THEN/ELSE statements around a BSTCOPY step:  

//STEP EXEC PGM=BSTCOPY

// IF &C1ELEMENT(8,1) = ‘D’ THEN

//OUTDD     DD DISP=SHR,DSN=NDV.DEV.COPYBOOK,FOOTPRNT=CREATE,MONITOR=COMPONENTS

// ENDIF

// IF &C1ELEMENT(8,1) = ‘Q’ THEN

//OUTDD     DD DISP=SHR,DSN=NDV.QA.COPYBOOK,FOOTPRNT=CREATE,MONITOR=COMPONENTS

// ENDIF

…etc…

//SYSIN

 S M=((&C1ELEMENT,MYCBTAB1))         <-- rename to the 'real' copybook name

//*

   If this needs to be protected from unauthorized updates, add another IF/THEN/ELSE to only do the BSTCOPY on a move to PROD.

// IF ((&C1ST EQ DEV)     OR

//       (&C1ST EQ QA)      OR

//       (&C1ST EQ EMER)) THEN

//* DO NOTHING

// ELSE

//STEP EXEC PGM=BSTCOPY….

// ENDIF

   Now you can change each of the four versions independent of the others and still get the correct name; MYCBTAB1, into each of the four different copybook datasets. Note, if using this method, you need to be mindful of the BASE dataset used by the type. If your GCICSCPY processor updates the BASELIB, it’ll corrupt the element. This can easily be avoided by creating 4 new datasets, one for each stage and adding these to the top of your COBOL generate processor’s SYSLIB concat for IGYCRCTL;

//STEP EXEC PGM=IGYCRCTL

//SYSLIB DD DISP=SHR,DSN=NDV.&C1ST..COPYBOOK       <-- new libs just for MYCBTAB1

//             DD DISP=SHR,DSN=regular copybook concat here

 

   Another approach, similar to the above but using unique types (each with their own stage specific BASELIB or source output lib – these new libs would also need to be added to the top of the IGYCRCTL SYSLIB concat). Using this approach, you’d be able to add each version of MYCBTAB1 to each of the four new types and Endevor would put them each in a separate source output lib.

 

   Again, if you wanted to protect from unauthorized updates, only define source output libs at stage PROD. For example:

Env DEV, type CICSCPYQ, BASELIB (whatever generic baselib you pick), SOLIB: blank

Env QA, type CICSCPYQ, BASELIB (whatever generic baselib you pick), SOLIB: blank

Env EMER, type CICSCPYQ, BASELIB (whatever generic baselib you pick), SOLIB: blank

 

Env PROD, type CICSCPYD, BASELIB (whatever generic baselib you pick), SOLIB: NDV.DEV.COPYBOOK

Env PROD, type CICSCPYQ, BASELIB (whatever generic baselib you pick), SOLIB: NDV.QA.COPYBOOK

Env PROD, type CICSCPYE, BASELIB (whatever generic baselib you pick), SOLIB: NDV.EMER.COPYBOOK

Env PROD, type CICSCPYP, BASELIB (whatever generic baselib you pick), SOLIB: NDV.PROD.COPYBOOK

[Lenn Thompson]

Welcome to the community, Wayne!

I'm sure one of our Endevor experts will chime in with help soon (I not one of those people).

Stay tuned!
​​

[Joseph Walther]

One Endevor site maintains a copybook like the one you described and updates the content of the copybook outside of Endevor. Each COBOL program references a constant copybook name, but the content of the copybook differs, depending upon input libraries that match the life cycle  - DEV, QA, EMER, and PROD for example.  The approach is simple, but it provides no Endevor control of the copybook itself.

A better approach would be one that might put an additional step into the COBOL Generate processor, but also place Endevor control onto the copybook and make the overall result more compatible with the use of Dynamic Environments and/or Sandboxes.  If nobody has one to offer, I will offer one.

[Dana Crawford]

I would recommend keeping the Production version of the copybook in Endevor and Transform it for each run-time environment below Prod. The transformed version is written to the output lib. The COBOL processor picks up the latest copybook from the Endevor-written output lib. We transform bind cards using a REXX routine.

[Eoin OCleirigh]

Welcome to the community Wayne,

It's great to see you already have plenty of feedback on this, and I'd second Dana, if there is any way to use a "transform" on the content to build each stage specific version, this is likely the best option.  Many sites use a similar process for tailoring JCL, PROCs or PARMs to build run-time versions of these libraries ready to go at each stage, (sometimes even more than one instance per stage) - and ideally yes the source content should be the production version with a transform replacing the 'prod' values with the stage specific values - but this leads you to the next important factor - what sort of edits are required, and where will THAT code be.  Its easy to get into a chicken and egg situation where the "code" for the Edits is held in PARM members, and you need different versions for each stage... but it may be easier to have environment specific names for these members.  As to the transform tool, all you need is something that can perform 'global' edits, any maybe also understand the syntax of the output (so that extended lines are wrapped appropriately). ICEMAN (Sort) can search and replace content, but Endevor also ships a utility used for tailoring Endevor's libraries (SCMUPDTE) that can also be used in a processor and has a fairly simple string/replacement string syntax.  If the requirement is a bit more complex (like replacing a single line in the source element with multiple lines in the transformed one, then maybe you will need to roll your own Rexx.

Oh and don't forget that for these types you probably do NOT want to delete behind as the source element is promoted through the life-cycle so you'll need a custom delete processor. [and it can get more complex if you have multiple, converging life-cycles where you might need to 'copy back' when promoting above the merge point(s)].

All that said, given your example use case of '...define a list of privileged users for each environment...' I suspect that Dave's suggestion starts to make more sense (although in the first case I'd try to keep security separate from code - a program should reach out to the security system (RACF, TopSecret, ACF2, or even Active Directory to determine a users access, Any hard coding of values in a copy book, would also require you to keep compiled versions of the code at each stage, and generate on every move (instead of using a move processor). 

If the 'stage specific' content is very different at each stage and not a more generic like HLQ differences- then having an ELEMENT with a stage specific name per stage makes more sense - Endevor would perform the 'rename' when it outputs to the stage specific library. Without knowing more about the specific values you want to look-up it's hard to make a final recommendation, but in general the principle would be to use an appropriate 'data source' per environment and read that at run-time.  In the long run this will probably be more flexible and more reflective of best practice.  Copybooks should describe the data structure(s) rather than define the data itself. 

Hope this helps, but if you can share a couple of the 'stage specific' versions of your copybook so we can all SEE the potential transform challenges or help you identify it this has crossed the line to 'run-time data', then please share.

[John Scott]

Hello Wayne,

You mentioned having 3 environments DEV QA PROD each with their own CICS regions so likely 3 sets of Endevor output libraries for each of these.

You also mentioned being able to add to EMER and move to PROD bypassing DEV and QA but you did not say much about "stages" which are important for this question.

You can check the Environment mapping by looking at the set up of stages from the Display option Menu - option STAGES.

Each Endevor Environment has 2 stages.

When you display the stages for each Environment you can work out the map to production from any stage in Endevor.

Depending on the Endevor Admin both stages may be used or not used and may be an entry stage (where you can add into the Environment) or not an entry stage.

Display stages shows you the NEXT ENV / stage ID for the Environment stages being displayed:

This tells you the target stage for the move action.

Looking at this for your Environments you can quickly draw an Environment mapping with stage ids showing a root to PROD from any given stage.

Endevor Admin will probably have set up the concatenations for copybooks to match the builds at stages on this same map on the route to live.

It sounds like there is a fairly static version of MYCBTAB1 in PROD and variations that cater for differences in the Environment the program runs in.

I am assuming the variations at lower stages are for environmental reasons and should not be moved up to prod.

This implies the programs using MYCBTAB1 are recompiled with the environmental copybook as its moved through the lifecycle to pick up the relevant version of MYCBTAB1

Depending on your Endevor Admin the MOVE action can trigger a GENERATE (compile) of the program each time it moves or it may be necessary to request a GENERATE of programs using MYCBTAB1 at each stage.

The simplest answer to your question

Without changing the Endevor lifecycle it sounds like you can already update the PROD version via EMER

You can also display stages to see if an equivalent stage to "EMERQA" exists already as an entry point to that environment but you mentioned you cannot currently add to QA.

Without changing the lifecycle you could simply add the version for QA to DEV and move it to QA then add the DEV version to DEV.

This will achieve what you want.

You probably just want to then cast a package to generate the version of each version of MYCBTAB1 at each stage required so the element is locked and is not moved by mistake.

Write once copybook solution:

Others have mentioned having a processor to automatically translate a source and make substitutions as it is moved up the lifecycle which you may or may not be able to do depending on the changes required.

This is worth considering but requires a bit more admin work to set up and is not required to get you up and running.

Another solution for environmental elements

Again this is more elaborate work for Endevor admin but assuming the environmental versions of MYCBTAB1 for DEV QA PROD are required on an ongoing basis and exist really to support the environments rather than to be promoted to production it may be worth considering a special Environment for these sorts of elements if it is not just one.

This Environment would not be mapped to production but of to the side for reference in processors and other processes to support the development environment.

e.g. you could have a new 2 stage environment separate from the regular lifecyle map and set the stage so you cannot move further.

stages may be called TEST and LIVE

System names would be QA DEV matching whatever non PROD environments require special versions of copybooks

You would define type copybook and add a version of MYCBTAB1 to the system name matching the Environment where its to be used.

The processor for this copybook when moved to LIVE will put it in a copybook library e.g. .SPECIAL.DEV.COPYBOOK or SPECIAL.QA.COPYBOOK

Hope this helps, it may be that the simplest solution is all you need here - move up the version of the copybook needed for each environment and lock it in a package. Move to QA then add the DEV version !

[Wayne Murray]

Hi Everyone,

I am blown away by the quality of all your responses.  Very detailed and thorough.  Wow!

I truly appreciate the time each of you took to compose such great ideas and suggestions in such detail.

I must confess that much of what you shared went over my head a bit, but I get the gist of what each of you are saying.  So, while there are several possible ways to handle this situation, they all pretty much involve a degree of change to the existing environment I am working in and will require that I get the Endevor Admin involved.  She is aware of my issue and does not see a solution based on how our environment is currently configured.  But she is willing to look at possible solutions and I will share your input with her.

For now though, due to project deadlines that I need to meet, I don't have time to deal with this right now and have decided for the moment to keep these "variable" copybooks, as I call them, outside of the control of Endevor.  I will circle back later when we have more time.  I can tell that I have a bit more to learn about Endevor before I can evaluate and pursue your suggestions further. 

With regards to how our Endevor environment is setup, here is some info on that.

We have two environments: DEV and PROD.  Each is made up of two stages.

In the DEV environment stage 1 is named 'DEV' and is defined as an entry stage; and stage 2 is named 'QA' and is not defined as an entry stage.  DEV then moves to QA.  And QA moves to the 'PROD' stage in the PROD environment.

In the PROD environment stage 1 is named 'EMER" and is defined as an entry stage; and stage 2 is named 'PROD' and is not defined as an entry stage.  EMER moves to PROD, and PROD is the end of the line.

All of our existing applications in Endevor use this structure.

It would be nice if we could simply define the QA stage in the DEV environment to be an entry stage in which case I could directly add a unique version of MYCBTAB1 to it.

I will update this thread when I circle back to this issue, but I cannot say for sure how long that might be.  At least a few weeks.

Again, I truly appreciate the time each of you took to provide guidance on this to me.

Regards,

Wayne

[June Abercrombie]

Hi Wayne,

   This can be done too:

It would be nice if we could simply define the QA stage in the DEV environment to be an entry stage in which case I could directly add a unique version of MYCBTAB1 to it.

You can move the QA stage to Stage 2 of a new QA Environment and move the DEV stage to stage 2 of the DEV Environment.  Then you make the DEV and QA stages the Entry stages of their respective Environments.

It is a bit of work but doable.  

We have complete instructions on how to set up a new Environment in the doc:

https://techdocs.broadcom.com/us/en/ca-mainframe-software/devops/ca-endevor-software-change-manager/19-0/installing/implementation-and-customization/defining-maps-and-inventory-structures/defining-inventory-structures/add-an-environment-to-an-existing-inventory-structure.html

If you want to pursue this, please do not hesitate to open an Endevor Support case and we will be happy to assist you.

June Abercrombie

Broadcom Endevor Support Engineer

[Joseph Stein]

Hi Wayne,

There is no ideal solution to this requirement.

I like Dave's second solution with some small modification.

1. Define a unique type for the special elements all residing in one BASE library by enabling the encrypt parm on the TYPE definition.
2. Define a subsystem for each stage (e.g. DEV, QA, EMER,PROD)
3. Define an output lib of the form: hlq.2lq.&C1SU
4. Allocate the necessary output libraries specified in step 3.
5. Place the generic output library specified in step 3 at the appropriate place in your compile step SYSLIB.
   1. 1. 1. You may want to consider replicating this to a second stage to allow for TEST and PROD versions of the COPY member

[Mathew Goldstein]

Ideally, program elements added to ENDEVOR are coded for production and rely on conditionals and variables to automatically and fully "environmentalize" for pre-production testing with no changes to the source code. This may not always be feasible for all types of program elements. I read that IBM Enterprise COBOL V6 supports conditional compilation which makes it possible to code "adaptive" COPYBOOKs:

• conditional compilation variables are valued in the source code of the COBOL program; some are through DEFINE compiler options

• these compilation variables condition a first level of COPYBOOKs inclusion

• these COPYBOOKs in turn reference other COPYBOOKs, always conditionally, and this on several levels of inclusion

• COPYBOOKS modify the values of conditional compilation variables, and for some delete conditional compilation variables, (variables local to a group of COPYBOOKs

[Eoin OCleirigh]

Mathew's mention of DEFINE compiler directives, which while another interesting method of building code differently still has the common shortcoming that Wayne will still end up with and have to maintain multiple versions of essentially the same code, and control (in CICS, probably by RPL) which one he loads to see the results he expects. So now in addition to the 'special copybooks' or 'define' code, he's got to also maintain multiple load modules, presumably all with the same name. 

To me it still makes more sense to have a single program, with common code, that loads different data.  The program should be behave differently at RUN-TIME depending on the environment it's running in. That's what most programs do after all, read a file or database or something that tells 'em what to do in this specific environment.

Specifically in a CICS environment, perhaps using the APPLID/SYSID, if you have appropriate naming standards for the SYSID (that won't change in the future) you could use something like:

EXEC CICS ASSIGN
    SYSID(WS-SYSID)
END_EXEC

and then an evaluate that sets up all the 'life-cycle-stage-specific' values which could come from copybooks or just be hard coded in place.
Potentially a more 'proper' solution would use a value passed in the INITPARM (allowing the admins to set the value (test/Qa/Prod) irrespective of the CICS Region name, applid, etc.  Of course the data could equally come from a file, or database  - as they could also have regions specific values.

This, to me, seems the simplest answer. No need to have multiple compile time values, multiple loads - just one program that reads some run-time data to set processing.

[Mathew Goldstein]

I agree 100% with EOIN. The goal should be to arrange a run time read of any data that changes for each lifecycle stage and avoid relying on generating and retaining different load modules (via different copybooks for each lifecycle stage). Furthermore, if there is a different CICS region for each lifecycle stage then you can leverage that to read in different data with SYSIN DD INITPARM.