Defining application entry points

Edit online

If your CICS® bundle project is part of a CICS application, you can declare suitable application entry points by using the CICS bundle manifest editor. 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.

Application entry points can also be defined in bundles that are deployed into single CICS regions. In this case, if application entry points are defined together with a policy scope, they can be used to restrict the scope of a policy that defines task rules to specific user tasks. See Restricting a task rule policy to specific user tasks in a single CICS region.

Before you begin

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

About this task

PROGRAM, TRANSACTION 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 should be unique in an application.
  • Operation names are case sensitive, so you can 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. When a resource for an application entry point and the entry point are both defined as part of an application, the entry point controls access to the service provided by the resource. For example, a TRANSACTION defined as an application entry point cannot be invoked until the application is made available.

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 that an application entry point targets is not present and cannot be autoinstalled, the CICS bundle that contains the declaration of the application entry point cannot be enabled, and the entry point bundle part remains disabled.

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. Stand-alone 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 cannot have the same name as a public program that is installed in the CICS region, or a public program that is defined as an application entry point by another installed application. However, multiple versions of the same PROGRAM resource that is defined as an application entry point can be installed for multiple versions of the same application.

When you define a URIMAP or TRANSACTION resource in a CICS application bundle, you can use an application entry point declaration to control users' access to the service provided by the URIMAP or TRANSACTION resource. In this situation, when you install and enable the application, the service provided by the URIMAP or TRANSACTION 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 or TRANSACTION resource available by using the Bundles view in CICS Explorer® or the EXEC CICS SET BUNDLE command. This action makes the application entry point, and therefore the service provided by the URIMAP or TRANSACTION resource, available to callers.

You can also declare as an application entry point a URIMAP or TRANSACTION resource that is defined outside the application. In this situation, the service becomes available to users as soon as you install and enable the URIMAP or TRANSACTION resource.

CICS system transactions must not be defined as application entry points.

For more information about application entry points, see Application entry points.

Procedure

  1. Expand the CICS bundle project and META-INF folder.
  2. Open the cics.xml file to view the CICS bundle manifest editor.
  3. Click the Entry Points tab to open the list of application entry points for the bundle.
  4. 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 in 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.
  5. 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 to measure how much resource an application, or a specific application operation, is using across CICS regions and multiple tasks.
  • The initial application context is used to apply 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 CICS Explorer to identify and diagnose application-related problems.