Defining application entry points

If your CICS® bundle project is part of a CICS application, declare suitable application entry points in the bundle manifest. An application entry point identifies a resource that is an access point to an application. Application entry points are used to control users' access to different versions of an application that is deployed on a platform.

Before you begin

You must have a CICS bundle project in the Project Explorer view.

About this task

PROGRAM and URIMAP resources can be identified as application entry points.

For applications that are deployed on a platform, application entry points control users' access to the different versions of the application. Application entry points can be set as available or unavailable to users. You can install the application and its resources in the CICS regions in the platform at any convenient time, then enable the CICS bundles to verify the installation. When you choose to provide the application version to users, you make the application entry points, and therefore the resources that they control for the application, available to callers.

Each application entry point is declared on a resource and also names an operation. For example, you could declare application entry points for create, read, update, or delete operations in the application.

A resource for an application can only be declared once as an application entry point, naming one operation. You cannot declare multiple application entry points on the same resource.
An operation name must be unique within an application.
Operation names are case sensitive, so you may use operation names that are differentiated only by case.

The resource for an application entry point does not have to be defined in the same CICS bundle as the application entry point. CICS adds the application operation to the specified resource when the application is installed. For PROGRAM resources that are declared as application entry points, the application entry point controls users' access to the program regardless of the location of the PROGRAM resource. However, for URIMAP resources that are declared as application entry points, the application entry point only controls access to the URIMAP resource if it is declared in the same CICS bundle where the URIMAP resource is defined.

You can declare an application entry point for a resource that is not defined in any CICS bundle, but already exists in the CICS regions where the bundle will be deployed. You can also declare an application entry point for a PROGRAM resource that can be autoinstalled in the CICS regions where the bundle will be deployed. When you install an application, if the resource targeted by an application entry point is not present and cannot be autoinstalled, the CICS bundle containing the declaration of the application entry point does not install and is marked with a warning.

CICS bundles that are installed as part of platform bundles, or added to a running platform, must not contain declarations of application entry points in the bundle manifest. Application entry points are not supported for CICS bundles installed directly on platforms, and CICS does not enable the application entry points in this situation, although the CICS bundle and its resources are installed. Standalone CICS bundles that are installed directly in CICS regions can contain declarations of application entry points to enable scoping of region level policies.

Application entry points only control users' access to the resources that are specified in the application entry points. If an application includes any public resources that are not named as application entry points, when the application is installed and enabled, these resources can be accessed by other applications installed on the platform or in the CICS region regardless of the availability status of the application. Private resources for an application version cannot be accessed by other applications.

Programs that are defined as an application entry point must have a unique PROGRAM resource name in your environment. To enable these programs to be called from outside the application, they must be public resources. When you enable an application that contains an application entry point for a private PROGRAM resource, the PROGRAM resource that is named as the application entry point changes from a private resource to a public resource. The PROGRAM resource therefore can have the same name as a public program that is installed in the CICS region, or the same name as a public program that is defined as an application entry point by another installed application. Multiple versions of the same program that is defined as an application entry point can be loaded for multiple versions of the same application.

When you define a URIMAP resource in a CICS bundle, you can use an application entry point declaration to control users' access to the service provided by the URIMAP resource. For this function, declare the application entry point and define the URIMAP resource in the same CICS bundle. In this case, when you install and enable the application, the service provided by the URIMAP resource is not yet available to callers. When you choose to provide the service to users, you make the CICS bundle containing the application entry point and the URIMAP resource available using the CICS Explorer® or the EXEC CICS SET BUNDLE command. This action makes the application entry point, and therefore the service provided by the URIMAP resource, available to callers.

If you do not want the application entry point to control access to the service provided by the URIMAP resource, declare the application entry point and define the URIMAP resource in different CICS bundles. You can also declare as an application entry point a URIMAP resource that is defined outside the application and declared as a dependency, or import, for the application. In either of these cases, the service becomes available to users as soon as you install and enable the URIMAP resource.

Procedure

Expand the CICS bundle project and META-INF folder.
Open the cics.xml file to view the CICS bundle manifest editor.
Click the Entry Points tab to open the list of application entry points for the bundle.
Click Add to define an application entry point for the application. The Create Application Entry Point dialog is displayed.
1. Enter the name of the application operation. The operation name is case sensitive. It can include the characters a-z, A-Z, 0-9._#@-, and has a maximum length of 64 characters. Ensure that the operation name is unique within your application. If an application contains duplicate operation names, it cannot be made available.
2. Select the resource type.
3. Enter the name of the CICS resource.
Click OK to save the application entry point.

Results

As well as controlling users' access to the different versions of an application, application entry points are used to create an application context for tasks. When the application is deployed, the operation name is added to the specified resource, and application context data is produced for tasks that use the resource.

When a task calls a resource that has an application entry point, CICS creates an application context that becomes the initial application context associated with the task, and with any subsequent programs that it calls and tasks that it starts. The application context identifies the platform, the application, the application version, and the operation. If a task already has an application context, this becomes the current application context although the application context of the invoking task can be used for monitoring and scoping of policies. You can use the application context data for the following purposes:

The initial application context is used for monitoring and measuring how much resource an application or a particular application operation is using across CICS regions and multiple tasks.
The initial application context is used for applying a policy to tasks that are part of an application, to define threshold conditions to manage the behavior of the tasks.
The initial or current application context can be used with the transaction tracking capability in the CICS Explorer to quickly identify and diagnose application-related problems.