Application entry points

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. They are also used to create an application context to monitor the resource usage for applications and to identify an application being run. PROGRAM and URIMAP resources can be declared 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.

You can declare one or more application entry points in the bundle manifest for a CICS bundle that is to be packaged and deployed as part of an application. Each application entry point is declared on a resource and also names the operation performed by the resource, such as a create, read, update, or delete operation.

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.

Start of change 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. End of change

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.

Application entry points are also used to create an application context for tasks. When a task calls a resource that has an application entry point, CICS creates an application context and associates it with the task. The application context is used to identify, load, and browse private resources for applications deployed on platforms, to apply policies to tasks, and to monitor the resources used by applications across multiple CICS regions and tasks. For information on the application context, see Application context.

PROGRAM resources as application entry points

Programs that are declared 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 make an application available 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. Only one instance of a public resource with a particular name can exist in a CICS region. The private PROGRAM resource therefore cannot 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 a different installed application. However, multiple versions of the same private PROGRAM resource defined as an application entry point can be installed for multiple versions of the same application, because CICS manages the promotion of private PROGRAM resources to public status for the versions of an application.

When you enable an application that contains an application entry point for a PROGRAM resource, CICS carries out the following checks to ensure that the resource is valid for use by the application:

If the PROGRAM resource that you name as an application entry point is a private PROGRAM resource that is defined in one of the CICS bundles packaged with the application, CICS checks that the PROGRAM resource does not have the same name as a public program that is installed in the CICS region, or as a public program that is defined as an application entry point by another installed and enabled application.
If the PROGRAM resource that you name as an application entry point is not defined in one of the CICS bundles packaged with the application, but is not yet installed as a public program, CICS attempts to autoinstall the program, then to reserve it for the application and enable an application entry point for it. If this action takes place, the autoinstalled program becomes a private program when you make the application version unavailable, so the same action can be taken for future versions of the application.
If the PROGRAM resource that you name as an application entry point is already installed as a public program, CICS checks that the PROGRAM resource has not already been defined as an application entry point by another installed and enabled application, then reserves the public program for the application, and enables an application entry point for it. If this action takes place, CICS cannot automatically manage the application entry points for future versions of the application, because a public program that was installed before the application cannot become a private program. To update the application to a new version, you will need to disable and discard the existing version. To avoid this situation, you can arrange that the public program is autoinstalled by the application installation process, in which case it can become a private program and allow future application versions to be installed at the same time. Alternatively, you can define the program in one of the CICS bundles deployed with the application version, ensuring that it has a unique name, and so make it a private program.

When the enabling process has completed successfully, the application entry point is in an ENABLED state, but the program is not yet available to callers through its application entry points. When you make the application available using the CICS Explorer®, CICS allows callers to access the application through its application entry points, and makes the private PROGRAM resources for application entry points into public resources. Callers can either use the EXEC CICS LINK command to access the highest available application version, or use the EXEC CICS INVOKE APPLICATION command to specify any available application version. Where multiple versions of the same application are available, the PROGRAM resource for the highest application version is public, and the others are private.

When you make an application version unavailable, the PROGRAM resources for the application entry points remain reserved for the application, but they are no longer available to callers. Any PROGRAM resources that began as private resources defined as part of the application, or were autoinstalled during the enabling process, are changed back from public to private programs. When you disable an application version, the PROGRAM resources for the application entry points are no longer reserved for the application. Any PROGRAM resources that began as public resources are made available to other applications and to callers.

Programs that are declared as application entry points are identified and reported in both the public and private resource statistics for program definitions and JVM programs produced by CICS, because, while the entry point is publicly accessible, it is also part of the application. For the program statistics that are produced by the loader domain, application entry points are not identified, and only one private program statistics record is written.

Start of change If you apply security measures to individual PROGRAM resources, for applications that are deployed on platforms, secure the programs that are declared as application entry points, but do not secure other programs in the applications. The security settings that you specify for a program that is part of an application deployed on a platform apply to both public and private programs, and do not take into account the version of the application. Programs that are declared as an application entry point must have a unique PROGRAM resource name in your environment. However, if you secure programs that run at a lower level in the application, programs with the same names might be running in different applications, which can lead to unforeseen consequences. In this situation, a user might have permission to access a program that is declared as an application entry point, but not have permission to access a program that runs at a lower level in the application, because the security settings from another instance of the program name are in effect. Consider the security measures that you apply to a program that is declared as an application entry point program, as applying to the whole application. End of change

Use the CICS Explorer to declare application entry points for your applications, and to make available or unavailable, enable or disable, and install or discard applications. For instructions to set up application entry points, see Working with applications in the CICS Explorer product documentation and Working with bundles in the CICS Explorer product documentation. To define an application entry point directly on a PROGRAM resource, see SET PROGRAM.

URIMAP resources as application entry points

The following usage scenarios are supported when using the URIMAP resource as an application entry point:

URIMAP resource with USAGE(JVMSERVER) using Liberty: If the URIMAP resource located by the Liberty JVM server is defined with an application entry point, the application context data is set for the JVM server request processor task, or its alias as specified by the transaction attribute.
URIMAP resource with USAGE(SERVER), or USAGE(PIPELINE) that does not use WebSphere® MQ: If the URIMAP resource located by CWXN is defined with an application entry point, the application context data is set for the CWXN task. Then, because CWXN is a user task, the application context data can be automatically propagated to the alias transactions started by CWXN; for example, CPIH for USAGE(PIPELINE), CWBA for USAGE(SERVER), or the transaction specified by the TRANSACTION field.

The following usage scenarios are not supported when using the URIMAP resource as an application entry point:

URIMAP resource with USAGE(PIPELINE) using WebSphere MQ: This scenario is not supported.
URIMAP resource with USAGE(CLIENT), or USAGE(ATOM): These scenarios are not supported. A bundle with URIMAP and USAGE(CLIENT) or a bundle with URIMAP and USAGE(ATOM) have the status DISABLED if the URIMAP is defined as an application entry point. If the bundle is installed and you attempt to enable the bundle, the ENTRYPOINT bundle part within the bundle has the status DISABLED and as a result the bundle has the status DISABLED.

URIMAP resources that are declared as an application entry point must have a unique name in your environment. A URIMAP resource can be defined in a CICS bundle and packaged as part of an application, but it is not supported as a private resource for the application, so it cannot be installed in multiple versions. When you update applications that include URIMAP resources defined in CICS bundles, you must rename the URIMAP resources for each version of the 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. 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.