Invoking a multi-versioned application

Two or more versions of the same application can be installed, enabled and available on a platform at the same time. If multiple versions are available, callers can either access the highest available application version or use the EXEC CICS INVOKE APPLICATION command to invoke a specific or minimum version.

Before you begin

Before you can code your program, you should know:

The name of the application.
The name of the platform on which it is installed, or verify that it is installed on the current platform.
The name of the operation that corresponds to one of the program entry points for the application to be invoked.
The exact major version of the application you want to invoke.
The exact or minimum minor version of the application you want to invoke.

About this task

Although two or more versions of the same application can be installed, enabled and available on a platform at the same time, only one of those versions is visible to the EXEC CICS LINK command. This version is the highest major and minor version of the application, and its entry points are public. So an EXEC CICS LINK to an entry point program always invokes the highest version of the application. The entry points for lower levels of an application are private, and so are not visible to EXEC CICS LINK.

Note: Micro version is always hidden as it reflects an internal change; for example, a bug fix. The caller always gets the latest micro version.

You use the EXEC CICS INVOKE APPLICATION to invoke an application through one of its program entry points, without having to know the name of the entry point program and regardless of whether its entry points are public. If no version is specified, then the highest major and minor version (the public level) is invoked. This is the same behavior as using an EXEC CICS LINK command to the application entry point. However, a lower version that is enabled and available can be invoked by using EXEC CICS INVOKE APPLICATION and specifying an appropriate major and minor version. You can specify that either an exact match on the application major version number and minor version number is required, or that a minor version number is the minimum that is required, but if a higher minor version is available it is to be used. If multiple higher minor versions are available the highest is used. The major version number cannot be exceeded and must match exactly.

For the full syntax of the EXEC CICS INVOKE APPLICATION command, see INVOKE APPLICATION.

Procedure

In your program, use the EXEC CICS INVOKE APPLICATION command and specify the name of the application you want to invoke.
Add the OPERATION and, if required, the PLATFORM option to the command.
- The OPERATION option specifies the name of the application operation which the application entry point program implements.
- The PLATFORM option specifies the name of the platform on which the application is installed. If no platform name is specified, the current platform name is used.
Optional: Add the MAJORVERSION and MINORVERSION options, and either the EXACTMATCH or MINIMUM keyword to the command.
- The MAJORVERSION option specifies the major version number of the application as a fullword binary value. If MAJORVERSION is specified, then MINORVERSION must also be specified. If no version is specified, then the highest major and minor version of the application is invoked.
- The MINORVERSION option specifies the minor version number of the application as a fullword binary value.
- The EXACTMATCH keyword specifies that an exact match on the application major version number and minor version number is required.
- The MINIMUM keyword specifies that the specified minor version number is the minimum that is required, but to use a higher version if it is available. If multiple higher minor versions are available the highest is used. This applies to minor version numbers only. The major version number cannot be exceeded and must match exactly.
When you use either the EXACTMATCH or MINIMUM keyword, there is no match criteria for micro version. The highest micro version is always used.
Optional: Add the COMMAREA and LENGTH options to the command.
- The COMMAREA option specifies a communication area that is to be made available to the called program. In this option, the data area is passed, and you must give it the name DFHCOMMAREA in the receiving program.
- The LENGTH option specifies a halfword binary value that is the length in bytes of the COMMAREA. This value must not exceed 24 KB if the COMMAREA is to be passed between any two CICS® servers.
Optional: Add the CHANNEL option to the command.
The CHANNEL option specifies the 1 to 16 character name of a channel that is to be made available to the called entry point program. If the channel does not exist, it is created.

Results

When your program issues this command, CICS invokes the specified application at the appropriate entry point.

Examples of EXEC CICS INVOKE APPLICATION

Example 1

This example shows how to invoke an application that runs on the current platform, passing an exact match for the application major version number and minor version number:

EXEC CICS INVOKE APPLICATION(PAYROLL)
		OPERATION(APPLY_TAX_CHANGES)
		MAJORVERSION(2)
		MINORVERSION(3)
		EXACTMATCH

Where:

PAYROLL: Is the name of the application that is being invoked.
APPLY_TAX_CHANGES: Is the name of the application operation that is to be invoked.
2: Is the major version of application PAYROLL to be invoked.
3: Is the minor version of application PAYROLL to be invoked. This must match exactly.

When this code is run, the APPLY_TAX_CHANGES operation of version 2.3.x of application PAYROLL is invoked, where x is the highest microlevel.

Example 2

This example shows how to invoke an application that runs on a specified platform, and specifying a minimum minor version of the application:

EXEC CICS INVOKE APPLICATION(PENSIONS)
		OPERATION(UPDATE_PENSIONS)
		PLATFORM(TEST_PENSIONS_PLATFORM)
		MAJORVERSION(4)
		MINORVERSION(2)
		MINIMUM

Where:

PENSIONS: Is the name of the application that is being invoked.
UPDATE_PENSIONS: Is the name of the application operation that is to be invoked.
TEST_PENSIONS_PLATFORM: Is the name of the platform on which the application is installed.
4: Is the major version of application PENSIONS to be invoked.
2: Is the minimum minor version of application PENSIONS to be invoked. If higher minor versions exist, the highest minor version is invoked.

When this code is run, the UPDATE_PENSIONS operation of version 4.2 or higher of the PENSIONS application is invoked. If, for example, versions 4.2.4, 4.3.3, and 4.4.1 of PENSIONS were enabled and available, then the command would result in version 4.4.1 being invoked.