In the past couple of years, it's become much easier to develop Java applications in CICS TS because we've been uploading libraries to Maven Central. Now, if you have a dependency on JCICS, for example, you can simply pull that into your application's Maven or Gradle build and it'll be downloaded from Maven Central or from your internal artifact repository. It's much easier than finding JCICS in your CICS TS installation, and it's easier to share than the target platforms in CICS Explorer.

It does raise some questions, though. With all those versions in Maven Central, which version of JCICS should you use? Or which version of the new JCICSX API, or the annotations or annotation processor for making linkable programs? Here's a screenshot of the available versions of JCICS today:

Where to start?

Understanding the version numbers

The first thing to know is how those version numbers are constructed. It's described in the documentation, but in summary, it has up to three parts:

1. For an OSGi bundle like JCICS, the first part is the OSGi bundle version. We use semantic versioning for our OSGi bundle versions, so this major.minor.micro structure tells you about API changes and compatibility.
2. Next comes the CICS TS version.
3. Finally comes the APAR version. This is optional, because when a CICS TS version is first released, there's no APAR. However, during the course of that version's life, there may be API additions or bug fixes, so we'll release new artifacts. You can search for the APAR number to discover what was included in that fix.

That's the background on the version numbers. But how should you choose the right version so that you can be sure your application is compatible?

Choosing the right version for your needs

Really there are just two steps to work out which version you need:

1. The first step is to narrow the choice down to versions that apply to the correct CICS TS version. For example, at the moment, if you're developing for CICS TS V5.5 then there's a choice of just 3 versions of JCICS out of the full 13 options.
2. Next, choose the version that indicates the APAR level you're at. If your CICS TS has PH25409 applied, or PH11872, or PH10453, pick the one of those that is most recently applied to CICS TS.

But what if you're not entirely sure which maintenance level you're at? Sometimes it can be tricky to find that information.

Well, here's the secret. To some extent, it doesn't matter.

The reason I say this is that JCICS should never get packaged into your application and installed into CICS TS anyway. CICS TS provides JCICS as part of its own runtime. In fact, if you do package JCICS into your application, you run the risk of more than API compatibility - strange and hard-to-debug things can happen! Always make sure you're using Gradle's compileOnly configuration or Maven's provided scope to ensure it doesn't get packaged into your application. It bears repeating: Never package JCICS into your application.

With runtime compatibility out of the question, then all we need to be concerned by is API compatibility, and that's much easier to reason about, because of the semantic versioning scheme we use. Remember, a major.minor.micro semantic versioning scheme has these parts:

• Major: only changes when API is removed. These are breaking changes.
• Minor: only changes when API is added. These are compatible changes.
• Micro: changes when there's a bugfix. There are no API changes involved.

Keeping that in mind, let's look at three examples of how you would choose the right version.

Scenario 1: I need the version of JCICS for my CICS TS V5.5 installation

Looking on Maven Central, I can see that none of the V5.5 versions of the artifact changed the major or minor version number (they're all 1.700), so no API has been added or removed during that release - not that we would remove API mid-release anyway! In the absence of knowing the maintenance level, any of the available V5.5 versions will be fine to use.

Scenario 2: I'm mid-upgrade and am deploying the same application to both CICS TS V5.3 and CICS TS V5.5

Looking at Maven Central, I can see that the CICS TS V5.3 artifacts and the CICS TS V5.5 have the same major version ('1'), so there are no API removals, but their minor version has incremented from '606' to '700', indicating that there have been API additions. If I want to be sure that I don't accidentally try to use those new CICS TS V5.5 APIs in a CICS TS V5.3 region, I should choose a V5.3 version to use, but any of them would be fine to use.

Scenario 3: Imagine that some API has been added during the course of CICS TS V5.6, that I specifically want to use

In this case I could look up the APAR that the API was introduced with. I could also look at the list of package versions of JCICS and the APIs they introduce on the com.ibm.cics.server package description. Either of those sources would show me the precise APAR version I would want to depend on, to get the right version for my needs.

Managing all versions at once with the BOM

If you start pulling in multiple CICS TS libraries such as JCICS, the CICS TS annotation processor, and JCICSX, then you'll want to manage those versions as one to avoid any incompatibility between them.

Any time we release an update to any of the libraries, we also release what's known as a Bill of Materials, or BOM. This special artifact controls the versions of the libraries unless you override them. That means that if you import the BOM, you can omit specifying the individual versions of the libraries. In Maven, you can even stop specifying the scope of the artifacts, as that's defined by the BOM too. You can see examples of how to use the BOM in the documentation.

It's worth noting that the versioning system for the BOM is slightly different - it contains the CICS TS version, then the timestamp of release, then (optionally) the APAR. This timestamp allows you to sort the BOM versions and understand what order the BOMs within a release come in, so the process of upgrading becomes a little clearer.

In many respects, it's worth applying the BOM even when you're only using one library as its version is easier to reason about, and as soon as you start using another library, you'll already be benefiting from it choosing the version from you.

Then once you've applied the BOM, that's the only version you need to be interested in! Omit the versions of CICS TS libraries and they'll be controlled by the BOM.

What about when I upgrade CICS TS?

If you upgrade CICS TS, either by applying maintenance or doing a full release upgrade, will your applications still be compatible? Will they need recompiling?

In general, there is no need to worry. Within the scope of a release we won't remove API. And in fact, between releases, we only very rarely do so, and with plenty of warning of deprecation! We document all new, deprecated, and removed API. You'll be able to rely on the semantic versioning of the package, looking for changes in the major version, to know whether breaking changes have taken place and your application may need alteration. Otherwise, your application will still be compatible.

There's also no need to recompile your application. The Java bytecode will continue to be compatible with upgraded versions of CICS, even if the version of Java has been upgraded too.

In summary

Don't be afraid of the version numbers! Above, I've shown you how to understand the version numbers and choose the artifact you need to get the job done. If you remember nothing else, remember these points:

• Use the CICS version, APAR number, and semantic version embedded in the artifact version to help you make the choice.
• Use the BOM so you only need manage one version number.
• If you make sure you don't package JCICS into your application, getting the exact right version number isn't that important anyway.