Application Deployment Manager - Release Notes

Who should read this information
Customization
   ADM workstation setup and customization
      ADM preferences
      Export/Import Systems Registry
      Defining CICS primary connection regions
      Providing the CICSPlex name
   z/OS server customization
      Modifying the ADM PIPELINE definition
      Security for CRD client API Web services
CICS resource definition editor
   Supported environments
   CICS resource definition language restrictions
   CICS region deployment scope
   CRD editor-supported CICS resource definitions
   Launching the CICS Resource Definition editor
   Using the CRD editor
   CRD editor function for the system programmer
   CRD editor function for the application developer

Who should read this information

ADM is intended for Rational Developer for System z developers who deploy Developer for System z or generated artifacts to z/OS. It is also intended for developers who will define CICS resource definitions, and z/OS system programmers who will use Developer for System z to supply CICS resource definition defaults.

Customization

Customization of the ADM workstation and z/OS server are covered in this section.

ADM workstation setup and customization

ADM has two levels of workstation setup and customization. ADM preferences are system values, and target system definitions define and provide connection information for target systems. This section describes the necessary workstation customization.

ADM preferences

Use the ADM preferences window to do the following:

Figure 1. ADM Preferences
Artwork for image009

Export/Import Systems Registry

The current systems registry can be exported to an external file or an external systems registry file can be imported and merged with the current systems registry. To export the current systems registry:

  1. Click File->Export->ADM Export Systems Registry.
  2. Click Next.
  3. Select the file path that you want to export.
  4. Click Finish.

Figure 2. Export window
Artwork for image010

The process for importing an external registry into the current systems registry is similar. Click File->Import->ADM Import Systems Registry, choose an existing registry file, and click Finish .

Defining CICS primary connection regions

The ADM CRD client implements a Web service connection to the CICS primary connection region. CICS primary connection regions must be configured using ADM. First, launch the CICS resource definition editor by right clicking on on the root folder of a Service Flow project (refer to Launching the CICS Resource Definition editor for more information). The Systems/Regions tab is used to add or edit CICS primary connection regions. A user error is indicated by a red "X" next to the appropriate field along with a tool tip describing the error. The required information includes:

Figure 3. Defining CICS primary connection regions

Providing the CICSPlex name

To provide the CICSPlex name, use the CICS Interactive tab and do the following:

  1. Select CICSPlex from the Resource type pull down.
  2. Select Provide CICSPlex name from the Action pull down.
  3. Enter the CICSPlex name in the ResourceName field.

z/OS server customization

The ADM host component is made up of the CRD server, associated CICS resource definitions, Web service bind files, and a sample pipeline message handler. The Developer for System z program directory contains instructions to install the ADM host component. However, certain customization might be necessary. This section describes that customization.

Modifying the ADM PIPELINE definition

The Web service binding directory contains a Web service binding (WSBind) file that is associated with a pipeline. The WSBind file is installed automatically by the CICS pipeline scanning mechanism.

At run time, CICS uses information in the Web service binding file to provide the mapping between application data structures and SOAP messages.

ADM provides WSBind files for each of its Web services. The installation process, described in the Developer for System z program directory, installs these supplied WSBind files in the UNIX system services HFS in a Web service binding directory (also known as the pickup directory).

If the directory paths specified in the supplied ADM pipeline definition do not conform to your shops naming conventions then you will need to use the CICS CEDA transaction to modify the supplied PIPELINE definition. This definition contains the WSDIR attribute, which specifies the name of the Web Services pickup directory containing the ADM WSBind files. The following figure contains a sample PIPELINE definition.

PIpeline       : ADMPIPE1                                       
Group          : ADMGROUP                                       
Description    :                                                
STatus         : Enabled            Enabled | Disabled          
Configfile     : /u/adm/pipeline/wssecurityprovider.xml
(Mixed Case)   :                                                
               :                                                
               :                                                
               :                                                
SHelf          : /u/adm/wsshelf                          
(Mixed Case)   :                                                
               :                                                
               :                                                
               :                                                
Wsdir          : /u/adm/wspickup                         

Security for CRD client API Web services

Some, or all, of these requests should be secured. At a minimum, the update CRD client API commands (update default Web service parameters, default descriptor parameters, and file name to data set name binding) should be secured to prevent all but CICS system programmers from issuing these commands used to set global resource defaults.

The CRD server repository file should be installed with resource-level security that requires update authority. An external security manager (for example, RACF) should be used to define the CICS user IDs that have the proper level of update authorization.

When the SOAP message is received by CICS it is processed by a pipeline. A pipeline is a set of message handlers that are executed in sequence. CICS reads the pipeline configuration file to determine which message handlers should be invoked in the pipeline.

A message handler is a program in which you can perform special processing of Web service requests and responses.

ADM provides a sample pipeline configuration file that specifies the invocation of a message handler and a SOAP header processing program.

CPIH is the default transaction ID under which an application invoked by a pipeline will run. Typically, CPIH is set for a minimal level of authorization. ADNSMSGH is a sample message handler used to set a new CICS transaction ID as follows:

When the transaction is attached, CICS resource security checking insures that the user ID is authorized to run the transaction ID.

Resource checking is controlled by the RESSEC option in the transaction that is running, the RESSEC system initialization parameter, and for the CRD server, the XPCT system initialization parameter.

Resource checking occurs only if the XPCT system initialization system initialization parameter has a value other than NO and either the RESSEC option in the TRANSACTION definition is YES or the RESSEC system initialization parameter is ALWAYS.

ADNSMSGH can be modified, and must be compiled by the customer. The compilation job must name the module ADNTMSGH in the link edit step.

In addition the TCPIPSERVICE definition can optionally specify an HTTPS connection to provide encryption for the entire SOAP message.

CICS resource definition editor

The Developer for System z CICS Resource Definition editor provides support for defining CICS resources. It is a Developer for System z component and is a consumer of ADM deployment services for deployment of defined CICS resources.

Traditionally, the role of defining resources to CICS has been the domain of the CICS system programmer. There has been a reluctance to allow the application developer the to define CICS resources for the following reasons:

The Developer for System z CRD editor addresses these issues by allowing the CICS system programmers to control CICS resource definition defaults, and to control the display properties of a CICS resource definition parameter. For example, the CICS system programmer can supply certain CICS resource definition parameters that might not be updated by the application developer. Other CICS resource definition parameters may be updateable, with or without supplied defaults, or the CICS resource definition parameter can be hidden to avoid unnecessary complexity.

Supported environments

The CRD editor supports definition of CICS resources in CICS TS 3.1 systems, with or without CPSM.

When CPSM is not installed, the CRD server uses the CICS CREATE SPI command to define and install (and enable) CICS resources. In this case, the CSD is not updated. Therefore, CEDA cannot be used to view the resource definitions. However, CEMT INQUIRE can be used, although it does not display all definition parameters.

When CPSM is installed, the CPSM Business Application Services (BAS) interface is used to define and install CICS resources. In this case, the CSD is not updated. Therefore, CEDA cannot be used to view the resource definitions. However, both the CEMT INQUIRE and the CPSM BAS interface can be used to view CICS resources. The CPSM BAS interface will list all definition parameters.

CICS resource definition language restrictions

CICS resource names and other alphanumeric resource attributes are usually limited to the characters that are common in all variants of EBCDIC. This does not include bi-directional or DBCS characters. See the CICS TS Resource Definition Guide (SC34-6430) for precise information about the valid characters for each resource type and attribute.

CICS region deployment scope

Developer for System z ADM uses a Web service to connect to a CICS TS 3.1 region running the CRD server. CICS resources may be installed in the CRD server region and in other regions according to the following scenarios.

CRD editor-supported CICS resource definitions

The following CICS resource definitions are supported by the CRD editor:

Launching the CICS Resource Definition editor

Perform the following steps to launch the CICS Resource Definition editor. If you already have a Service Flow Project, skip to step 4.

  1. Open the Enterprise Service Tools perspective.
  2. Click the Enterprise Service Tools Menu icon and select Service Flow Project.
  3. In the New Service Flow Project wizard, do the following:
  4. Right-click on the root project folder and select CICS Resource Definition.

Using the CRD editor

The CRD editor function is implemented as a Developer for System z component. It has applicability to both the application developer and the system programmer roles.

The system programmer uses the CRD editor to supply z/OS-based parameter defaults for all CRD editor supported CICS resource definitions, CICS resource definition parameter display properties, supply binding information for VSAM files, and when CPSM is installed to provide the CICSPlex name.

The application developer uses the CRD editor to retrieve existing resource definitions (these can be used as models), with a list of CICS region IDs (SYSID) available for deployment, and define and deploy CICS resource definitions.

Figure 4 shows the CRD editor being used to retrieve an existing program definition.

Figure 4. CICS Resource Definition Editor

CRD editor function for the system programmer

The CRD editor implements the following functions intended for use by the CICS system programmer:

Retrieve/update CICS resource definition defaults
The user selects a specific CICS resource type. The default parameters for this resource type are retrieved from z/OS by the CRD server. For the initial provisioning for a specific resource type the CRD server supplies suggested resource parameter defaults.

The resource is displayed as it typically appears when creating a new resource definition of this type. Entries in the parameter fields are used to update defaults on the CRD server repository file on z/OS. These defaults are then used for subsequent creation of resource definitions of the same type.

In addition, the display properties can be set for most resource parameters. Valid display properties are updateable, protected, and hidden.

Each supported resource type will also have a setting to indicate if the resource type is allowed to be defined using the CRD editor.

Retrieve/update CICS VSAM file logical to physical binding
A logical VSAM file name is supplied by the user. If a binding has been previously supplied, the physical dataset name is displayed.

The physical dataset name can then be initially supplied or updated.

The logical to physical binding information is stored in the CRD server repository on z/OS.

The logical to physical VSAM file binding is then used for a subsequent creation of a VSAM file definition using the logical file name.

CRD editor function for the application developer

The CRD editor implements the following functions intended for use by the CICS application developer:

Retrieve/create CICS resource definition
The user selects a specific CICS resource type. The default parameters for this resource type are retrieved from z/OS by the CRD server. If default parameters for this resource type are not found in the CRD server repository, the CRD server supplies suggested resource parameter defaults.

The resource parameters for a particular resource type are displayed according to display values supplied with the resource defaults from the CRD server repository. Resource parameters are displayed as updateable, protected, or hidden.

By default, a created resource is installed in the CICS TS 3.1 region running the CRD server. However, the user may instead indicate that the resource should be installed in another target CICS region. This is accomplished according to the installed environment.

If CICSPlex SM is not installed then a resource can be installed in a target that has an active MRO connection to the primary connection region. This can be done in one of the following ways:

If CICSPLex SM is installed, the resource can be installed in any CICS region in the same CICSPlex as the primary connection region. This can be done in one of the following three ways:

  1. By supplying a 4 character CICS SYSID in the Sysid field of the DestinationInfo section.
  2. By supplying the VTAM Application ID (APPLID), by which the target region is know to VTAM, in the Applid field of the DestinationInfo section.
  3. By supplying a CICS region name by which the target region is known to CICSPlex SM, in the Applid field of the DestinationInfo section.

There are two additional benefits to operating in a CICSPlex SM environment, as follows:

  1. Some CICS resources can be created where a single resource definition can be used for both local and remote definitions. This applies to Program, Transaction, File, and TDQ definitions. In these types of definitions both local and remote attributes are defined in the same definition. When the definition is installed the remote definition attributes are installed in the target region as described above. The local definition attributes are installed in the region specified by the Related Applid field of the DestinationInfo section. The Related Applid field may contain either a VTAM Applid or a CICSPlex SM CICS region name.
  2. Resource groups can be created. After a resource group has been created, you can specify that resource group when creating other resource definitions by supplying the resource group name in the Resource Group field of the DestinationInfo section. The resource group is now associated with the specified group.

CICS resource parameter values are governed by rules as specified in the CICS Resource Definition Guide (SC34-6430).

(C) Copyright IBM Corporation 2006, 2007. All Rights Reserved.