This is a typical modernization project story. Migrating CICS from z/VSE to z/OS meant analyzing tens of thousands of system and application definitions across multiple regions. Doing this manually would have required checking every definition for z/OS compatibility and tracing countless dependencies, a process that could easily have taken months. Instead, we developed a custom dashboard to pinpoint areas requiring expert review, significantly reducing the effort while giving both CROZ and the client a transparent, measurable view of the migration’s progress. To tackle this challenge, we turned to Carbon.modernize, our methodology built on CROZ’s hands-on experience.
Understand, before you touch them
We applied Carbon.modernize principle: analyze every definition first, then make decisions based on facts. To support this migration, we built a CSD dashboard. The dashboard reads every definition, maps its dependencies, automatically rewrites cases covered by clear rules, and presents the remaining exceptions together with the relevant IBM documentation. The dashboard provides a real-time view of completed and outstanding work, giving both CROZ and the client a single, agreed measure of migration progress.
Why resource definitions make CICS migration complex
A CSD contains the CICS system and application object definitions that a region needs to run: transactions, programs, files, map sets, terminals, connections, and the groups and lists that organize them. In this environment, there was no application documentation and no system documentation clearly describing the purpose of each definition or providing a reference against which it could be validated. The CSD and the application source code were the only reliable records.
CICS uses the same DEFINE syntax for most attributes on both z/VSE and z/OS, making migration issues deceptively difficult to spot. Some keywords supported on z/VSE simply do not exist on z/OS. Others have different names, different value formats, or map to multiple attributes. In addition, CICS TS on z/OS requires attributes that were never needed on z/VSE. None of these differences is particularly difficult to handle when analyzing a single definition. The real challenge emerges when the same checks must be performed across tens of thousands of definitions.
How to make migration progress measurable
Everything starts with reading. The CSD extracts are parsed as text into a model of every resource type with its groups and lists, and each attribute is checked against a description of which parameters each platform accepts and with which values. That gives a complete inventory in minutes. It also gives the first thing my colleagues looked at every day: a progress bar per region showing how many definitions CICS on z/OS would already accept and how many it would not.
Every attribute CICS on z/OS would not accept as written is classified by what has to happen to it: dropped, renamed, kept as obsolete, transformed to a new value, or split into two attributes. Next to each finding sit the label, the reason and a link to the IBM documentation page for that parameter.
The first three are applied automatically during conversion, because there is one correct answer and no judgement involved. Transforms and splits stay flagged, because a value change depends on how the client wants its CICS regions on z/OS to behave.
For each of those the dashboard opens a guide for the resource type: what changes between the platforms, why, the migration considerations IBM lists, and the documentation link. My colleagues read that, decided, and marked the item done. Asked afterwards what had helped most, they named this part first: the side by side comparison of CICS on VSE and CICS on z/OS, the deprecated parameters found for them, and the list of what had to be transformed.
Alongside the syntax work, dependencies between the definitions are mapped. A transaction names a program, a terminal refers to a terminal type, a file to a buffer pool. Not all of those references stay inside their own region: a remote file definition points at something defined elsewhere, and until you can follow a reference across regions you cannot tell whether it resolves at all. The graph draws resolved references as solid lines and unresolved ones as dashed, and clicking a node shows what refers to it and what it refers to. On this estate that came to thousands of dependencies.
The last part is the cross-region comparison. Each conflict is listed with every version side by side, and for each one my colleagues chose the version that would go forward or marked it irrelevant. A second scoreboard on that tab counts resolved, irrelevant and unresolved, and the z/OS output is generated only once nothing is left unresolved.
[SCREENSHOT: cross CSD tab, one conflict in several regions side by side, names redacted]
Not every question could be answered from the CSD alone. The client’s teams decided which applications and resources belonged in each z/OS CICS region, while the dashboard handled the heavy lifting of assembling the final CSDs.
Finally, the generated CSD was loaded into the CICS development region on z/OS and the region was monitored, then the same for system test and acceptance. Production went in last.
Where automation needed human judgement
There are some examples of tasks which cannot be automatically done with CSD dashboard. In these cases, there was a need for human evaluation. CSD Dashboard flagged those cases for engineer to have a closer look. For example, one keyword form VSE CSD definition doen’t exist on z/OS CICS, instead it’s definition is a combination of CSD keywords on z/OS. In that case, user get’s the workspace to seamlessly resolve those transformation cases.
Carbon.modernize approach to mainframe modernization
Carbon.modernize is most often used to support application modernization initiatives, but this project shows that its principles can be equally valuable for system-level migrations. It is a perfect example of Carbon.modernize applied to a focused and well-defined target:
- We built a custom “CSD dashboard” specifically for this project
- We used deterministic preprocessing first, so every finding could be traced back to a line in the source. Human judgement came in only once the facts were clear: CSD attributes were the evidence, and the decision was which definition should move forward.
- AI-assisted development enabled incremental modernization with continuous verification. At each stage, the generated CSD was loaded and tested in a working CICS region before the migration moved to the next environment.
- Building a CSD dashboard reduced manual analysis effort through knowledge reuse. We built a custom CICS migration dashboard for this project, reducing manual analysis through reusable rules, dependency mapping, and a clear view of unresolved work.
Lessons learnt
One thing I would definitely keep is the scoreboard. A progress bar for each region, combined with a count of resolved versus unresolved conflicts, contributed more to productive discussions with the client than any report could. Everyone was looking at the same metrics and watching them move in real time.
I would also keep the IBM documentation attached to each finding. That simple addition allowed my colleagues to focus on making decisions rather than spending time searching for information.
Don’t try to automate everything!
At the beginning of the project, I wanted to automate every transformation. Over time, I realized that the definitions contain too much business logic to be converted reliably without human input. In this type of migration, human review remains the most dependable form of validation.
Ultimately, the migration cannot be completed without testing the transformed CSD on z/OS. No amount of automation can replace final verification in the target environment.
One Final Thought
If you have a CSD extract and a tight deadline, count how many times your most important file is defined. If the answer is more than one, go with Carbon.modernize
