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 of the ADM workstation and z/OS server are covered in this section.
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.
Use the ADM preferences window to do the following:
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:
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 .
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:
To provide the CICSPlex name, use the CICS Interactive tab and do the following:
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.
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.
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.
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.
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 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.
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.
The following CICS resource definitions are supported by the CRD editor:
Perform the following steps to launch the CICS Resource Definition editor. If you already have a Service Flow Project, skip to step 4.
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.
The CRD editor implements the following functions intended for use by the CICS system programmer:
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.
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.
The CRD editor implements the following functions intended for use by the CICS application developer:
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:
There are two additional benefits to operating in a CICSPlex SM environment, as follows:
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.