S 274

8174ch04.
fm
Draft Document for Review October 22, 2013 7:07 pm
pulling from a centralized repository that is delivered through the SMP/E process. The
configurable server architecture allows parts of the server architecture to remain in read-only
mode. More disk space can be added with increasing web service demands without
impacting the server operations. Advanced Installation Support by using the IBM Installation
Manager for z/OS
Advanced installation support by using the IBM Installation Manager for

z/OS
The IBM Installation Manager is a tool that you can use to install and maintain your software
packages. On z/OS, the IBM Installation Manager runs as a UNIX System Services
application, and can be invoked from the UNIX System Services shell, shell scripts, or from
MVS batch jobs.
The IBM Installation Manager allows you to simplify installation and maintenance and achieve
faster value through a simplified product installation, update, and uninstallation with
integrated prerequisite and interdependency checking. This installation occurs after the
SMP/E installation.
Note: If you already have IBM Installation Manager for z/OS processed by SMP/E on the
driving system, ensure that you have at least applied PTF UK79476 to upgrade the
Installation Manager installation kit to V 1.5.3.
If you already have the Installation Manager for z/OS installed you may verify if you are at
least at V1.5.3 APAR PM834465 updates the IBM Installation Manager install kit to Version
1.6.2. After this APAR is applied, new Installation Managers are created at Version 1.6.2. To
upgrade existing Installation Managers, re-run the command to create the Installation
Manager (installc, userinstc, or groupinstc) from the updated install kit. In Addition, APAR
PM83465 updates the sample install job instructions to provide more detailed information
about user ID and group requirements for IBM Installation Manager.
Example 5-3 Mount point of the IM default to
/usr/lpp/InstallationManager/V1R4
5.4.2 The new installation architecture in IMS Enterprise Suite V2.2

Prior to version 2.2 of the IMS Enterprise Suite, SOAP Gateway is installed under one
directory. Everything from the program's executable binary files, to server properties file, log
files, and users' web service artifacts, is installed together under one mount point. See
Figure 5-4. Installation of multiple copies of the SOAP Gateway server typically requires the
use of MVS DUMP, copytree, or PAX, and it is difficult to install from one managed copy.
170
IMS Integration and Connectivity Across the Enterprise
8174ch04.fm
Figure 5-4 Prior to Enterprise Suite 2.2
1. The directory where SOAP Gateway is installed must be writeable because users need to
add web services, and the server log file is updated. Crucial server files therefore cannot
be mounted in READ only mode to prevent alterations.
2. As more web services are deployed and the server continues to run, user files and log files
could consume critical server space, and therefore slow down the server.
3. Installation of multiple copies of the SOAP Gateway server typically requires the use of
MVS DUMP, copytree, or PAX, and it is difficult to install from one managed copy.
In Version 2.2, the SOAP Gateway installation is divided into three components: imsserver,
imsbase, and imssoap. imsserver contains the server executable code, tools, and scripts.
Files in this component should never be altered. imsbase contains the server configuration
information, default log directory, and scratch directories. imssoap contains users' service
artifacts, such as web service WSDL files, correlator files, connection bundles, and
WS-Security configurations. See Figure 5-5.
Chapter 5. SOAP application technology
171
8174ch04.fm
Figure 5-5 The new architecture
Components of SOAP Gateway:

imsserver
It contains the server executable code, tools, and scripts. Files in this component should
never be altered.
imsbase
It contains the server configuration information, default log directory, and scratch
directories.
imssoap
It contains users' service artifacts, such as web service WSDL files, correlator files,
connection bundles, and WS-Security configurations.
Each of the three components can be mounted separately, which means that the imsserver
component can be mounted on a READ only data set for added security.
The imsbase and imssoap components must be mounted on a READ and WRITE data set.
The data set volume would depend on the number of services you plan to deploy and if
logging is enabled. Should more disk space is needed later, you can add more volume and
remount the imsbase and imssoap components without impacting the server component.
This 3-part installation architecture enhances the server's security and its ability to grow with
the increasing demands for web services.
This solves the first two issues with previous versions of SOAP Gateway, but the third issue of
installing multiple copies of SOAP Gateway from a managed copy remains. Next, well explain
the use of IBM Installation Manager for z/OS as the solution.
What is IBM Installation Manager for z/OS?

IBM Installation Manager has been used on distributed platforms for many years for installing
IBM products and applying updates.
It installs from a repository.
172
8174ch04.fm
A repository contains a repository.config file that stores the metadata on how to install and lay
out the selected packages on the system.
More and more IBM z/OS products are using IBM Installation Manager for z/OS, including
WebSphere Application Server for z/OS.
See videos of the installation process starting at:
http://www.youtube.com/watch?v=uiOZKtyXJ8c
5.4.3 Installing multiple copies of SOAP Gateway

Before you can install multiple copies of SOAP Gateway you need to run the SMPE
installation of it see Figure 5-6.
For SOAP Gateway installation on z/OS, the SOAP Gateway repository file is a compressed
ZIP file that is SMP/E managed in one location. The Installation Manager for z/OS can
connect to a repository through HTTP, FTP, or a shared disk. You then use the Installation
Manager to install SOAP Gateway by pointing to the repository file.
You can install multiple copies of SOAP Gateway from the same copy of SMP/E-managed
repository. You can use the same instance of the Installation Manager to install SOAP
Gateway on different LPARs if they are in the same Sysplex. If not, you need to install the
Installation Manager on that LPAR first.
First, from the tape or your Custom-built Product Delivery Option (CBPDO), you receive the
Base Services and SOAP Gateway FMIDs. The IBM Installation Manager FMID is also
included. Use the SMP/E installation process to obtain the sample jobs needed to install
SOAP Gateway, the IBM Java SDK, and the SOAP Gateway repository. If you don't have IBM
Installation Manager installed already, use the SMP/E installation process to obtain the
installation kit for the Installation Manager.
The new installation process
Figure 5-6 SMP/E installation process

173
8174ch04.fm
After you RECEIVE, APPLY, and ACCEPT the FMIDs, the second step is to install the
Installation Manager.
Before the installation, you need to apply PTF UK79476 to upgrade to V 1.5.3 of
the.Installation Manager. The version of the Installation Manager included in your order is an
older version and it must be upgraded. Then you can install the Installation Manager by
editing and submitting the provided sample jobs.
After the Installation Manager is installed, you can use the Installation Manager Command
Line imcl command to install SOAP Gateway by pointing to the SOAP Gateway repository.
See Figure 5-7
Figure 5-7 Multiple copies of SOAP Gateway
Remember that there are three installation components, imsserver, imsbase, and imssoap.
For each of these components, its installation directory or mount point must be specified.
Example 5-4 shows part of the AEWTSGCF sample job provided in the Base Services that
you can edit and submit to configure the installation directory. Instructions are provided in the
sample job for parameters that you must customize.
Example 5-4 AEWTSGCF sample
AEWTSGCF
//* 1) If you are installing SOAP Gateway on multiple mount
//*
points:
//*
a) Replace -ServerPathPrefix- with the path to install
//*
the imsserver component
174
*/
*/
*/
*/
8174ch04.fm
//*
b) Replace -BasePathPrefix- with the path to install
//*
the imsbase component
//*
c) Replace -SoapPathPrefix- with the path to install
//*
the imssoap component
//*
These directories are created and mounted in sample job
//*
AEWTSGAL.
ServerPathPrefix=-ServerPathPrefixBasePathPrefix=-BasePathPrefixSoapPathPrefix=-SoapPathPrefixIMPathPrefix=-IMPathPrefixRepoPath=ftp://driving.site.com/-RepoPathPrefixSharedResource=-SharedDirPath-
*/
*/
*/
*/
*/
*/
The Base Services include various sample jobs for SOAP Gateway installation for different
installation scenarios, and they are documented in the SOAP Gateway documentation in the
information center.
There are a few configuration steps you need to follow before you can start SOAP Gateway:
AEWPARMF
Sample job to copy the Java load module into the partitioned data set extended (PDSE)
used by SOAP Gateway.
AEWIOGBP
Sample job to specify the IBM Java SDK location and view the SOAP Gateway server
properties by using the SOAP Gateway management utility commands from BPXBATCH.
AEWIOGCF
Configuration member to configure SOAP Gateway runtime settings.
AEWIOGPR
JCL procedure for starting and stopping SOAP Gateway.
On the distributed platform you use the Installation Manager like always, only the deployment
utility has changed to Management Utility as shown in Figure 5-2 on page 167. Also the
directory is the same as described previously.
If you are a Unix person and dont like JCL, you may use the OMVS go to the imsserver
mount point to deploy. from here you are able to do the same as you do on the Windows
Management Utility. See Example 5-5 by using ./iogmgmt.
Example 5-5 mount point imsserver/deploy on OMVS
deploy>./iogmgmt -view -sgp

A few notes to the iogmgmt commands.
To use the SOAP Gateway management utility, from the installation directory where the
SOAP Gateway is installed (SOAP_Gateway_install_directory\imsserver\deploy), type
iogmgmt (for Windows) or ./iogmgmt (for z/OS and Linux on System z). See Figure 5-8 on
page 176
On Windows 7 systems, depending on the SOAP Gateway installation directory, you might
need to open a command prompt as an administrator and change directories to the SOAP
Gateway management utility directory (install_dir/imsserver/deploy) before you can issue any
command.
175
8174ch04.fm
An iogmgmt command consists of the iogmgmt statement followed by arguments to specify

the command and associated options.
Issuing a command with more than one instance of a parameter will override all but the last
instance of the parameter. For example, issuing the command iogmgmt -corr -u -r MyCorr.xml
-p MyService -i MyOperation -n NewBundleName1 -n NewBundleName2 will set the
connection bundle name for the specified correlator entry to NewBundleName2.
SOAP Gateway management utility commands are case sensitive and must be entered in all
lower case or as shown in the command reference topic. For SOAP Gateway servers running
on z/OS, the SOAP Gateway management utility must run on the same LPAR as the target
server.
cicsts
ing
pdxt
wsrrPB3
IMSR2 SC63:/Z1DRB1/usr/lpp>cd ims
IMSR2 SC63:/Z1DRB1/usr/lpp/ims>ls
ims13q imsb imses soap
IMSR2 SC63:/Z1DRB1/usr/lpp/ims>cd soap
IMSR2 SC63:/pp/imssoap/v2r2>ls
imsbase imsserver imssoap
IMSR2 SC63:/pp/imssoap/v2r2>cd imsserver
IMSR2 SC63:/pp/imssoap/v2r2/imsserver>ls
bin
icons
native.ais.properties
deploy
imsserverBackup_20130717_2205 server
docs
install
tools
IMSR2 SC63:/pp/imssoap/v2r2/imsserver>dir deploy
dir: FSUM7351 not found
IMSR2 SC63:/pp/imssoap/v2r2/imsserver>cd deploy
IMSR2 SC63:/pp/imssoap/v2r2/imsserver/deploy>ls
commons-cli-1.2.jar
iogmgmt
log4j.deploy.properties
ims.esv2.2.1.iog.mgmt_20130314.jar iogmgmt.bat
IMSR2 SC63:/pp/imssoap/v2r2/imsserver/deploy>./iogmgmt -view -sgp
IOG00018E: The command failed because the specified /pp/imssoap/v2r2/imsserver/java/bin
directory does not exist. The directory must
already exist. Specify the full path to the java directory, for example, C:Program
filesIBMIMS Enterprise Suite V2.2SOAP Gatewa
yjava.
IMSR2 SC63:/pp/imssoap/v2r2/imsserver/deploy>
===>
INPUT
ESC=
8=Scroll
1=Help
2=SubCmd
3=HlpRetrn
9=NextSess 10=Refresh
11=FwdRetr 12=Retrieve
4=Top
5=Bottom
6=TSO
7=BackScr
Figure 5-8 Screen shot for deploy>./iogmgmt -view -sgp
In Table 5-1, we see the different paths after migration from a previous SOAP Gateway to V22
Table 5-1 the different paths
176
ES V2.1 SOAP Gateway
server/webapps/imssoap/WEB-INF/classes/log4
j.properties
imsbase/conf/log4j.properties
8174ch04.fm
server/webapps/imssoap/imssoap.properties
imsbase/conf/imssoap.properties
N/A
imsbase/conf/native.env.propeties
env.properties
N/A
server/conf/server.xml
imsbase/conf/master/server.xml
server/webapps/imssoap/xml/(correlators)
imssoap/xml/(correlators)
server/webapps/imssoap/wsdl/(wsdls)
Callout and business event:

imssoap/wsdl/(wsdls)
server/webapps/imssoap/WEB-INF/conf/
wsjaas.conf binary copy
Provider: not copy, but to be embedded in service

file
server/webapps/imssoap/WS-SECURITY/
policy/bindings Binary Copy
imssoap/WEB-INF/wsjaas.conf
policy/bindings
server/webapps/imssoap/xml/connbundle
- >Binary Copy
imssoap/xml/connbundle.xml
5.4.4 Monitoring, tracking, and logging

In this part we describe the new IMS Transaction Tracking and monitoring support. We have
heard from our customers that they really need their enterprise system to be transparent,
such that when a request is sent from a distributed client to IMS, the path can be tracked.
So when a response takes longer than usually to come back, what was the cause? To figure
out the problem, first is to figure out where. Where is the bottle-neck? This is one of the
challenge we try to tackle, the lack of end-to-end tracking capability for distributed requests to
and from IMS.
Another requirement in this area came from SOAP Gateway customer. As more customers go
into production with SOAP Gateway, system administrators needs to periodically monitor the
health of SOAP Gateway. Simple metrics such as when running a load of thousands of
transactions / second, is SOAP Gateway responding well at certain point in time? What are
the available services and their usage? Are the soap faults growing out of control? Is SOAP
Gateway managing connections to IMS Connect well, or connections growing out of control?
We provided a public interface to publish such monitoring metrics.
Furthermore we worked on a related requirement to assist support user to do problem
determination of a particular transaction. For example, IRS asks to find a specific record sent
on a particular day and time. This record better be there. Thus the requirement is for SOAP
Gateway to provide a transaction log, recording the basic information for every
request/response with minimal impact to performance.
Right now the following restrictions apply
Monitoring, tracking and logging is supported only for provider scenarios.
The callout support comes in later release
Monitoring SOAP Gateway transactions is only enabled over a non secure JMX port.
The JMX port you listen to cannot be secured by SSL
Tracking is only supported with IMS V12 and up
We find the following Solution highlights in SOAP Gateway 2.2, we
177
8174ch04.fm
Publish SOAP Gateway monitoring statistics (Monitoring)

Enable transaction tracking from SOAP Gateway to IMS and back (Tracking)
Support problem determination via transaction log (Logging).
Enable ITCAM to process transaction event data.
Lets talk about monitoring:

SOAP Gateway Monitoring keeps statistics for requests by operation, noting operation details
as successful, active, failed, total successful, and total failed.
It does this by implementing a JAVA JMX MBean interface.
Jconsole or client written applications can listen over the JMX port to get the data via the
operations specified in the JMX interface
Example 5-6 shows the command to enable SOAP Gateway monitoring from the
Management Utility to be send to port 7176.
Example 5-6 monitoring deployed to specific port
iogmgmt mbeans on port 7176
Transaction tracking
SOAP Gateway sends a tracking ID (up to 40 bytes) to IMS Connect on request and receives
the tracking ID back on response.
The unique tracking ID is generated by SOAP Gateway unless a user-defined tracking ID is
provided by the user as shown in Figure 5-7.
Configure SOAP Gateway to enable or disable tracking, as well as configure the tracking ID
type.
Example 5-7 Sample commands for trackingID
iogmgmt tracking on|-off (-off by default) id messageID|generated|custom

messageID by default) -element e (element name only needs be specified for custom)
-nameSpace ns (ns is optional, can only be specified with custom)
i.e.
iogmgmt tracking on id mesageID
In Figure 5-9 you see a IMS Transaction Tracking Provider Scenario where the correlation is
based on Tracking ID
When it takes longer than usual for SOAP gateway to send a response to a request message,
what could be the problem, It can be a performance bottleneck and the tracking id feature can
be used to pinpoint the problem and hence be used for performance analysis.
178
8174ch04.fm
IMS Transaction Tracking Provider Scenario

(correlation based on Tracking ID)
Tracking ID
segment +
request
Tracking ID
segment +
(XML) respons e
data + CSM
response
New
In
ES2.2
Logs (message ID) +

Tracki ngID and more
SOAP
G ateway
Transa cti on log
Tracking ID
In OTMA header
(user data secti on) +
bytes data
me ssage
ex it*
SOAP
Gateway
Request wi th
optional mess age ID
IMS
Connect
O
T
M
A
IMS
IMS App
Tracking ID
In OTMA header
(us er data secti on) +
T rack ing ID
bytes data
publi c
(JMX)
i nterface
R out e /
gen era te
T rackin g ID
ev ent
e xit *
Trac king ID
records events wi th
Tracking ID
picks up
Tracking ID
Moni toring
data*
IMS
Log record
moni tors
Monitoring and analyzer tools/client application

* new/modified
components
Figure 5-9 IMS Transaction tracking Provider scenario
SOAP Gateway sends the tracking ID with the request to IMS Connect, which makes the ID
visible through the event exit. The id is also recorded into IMS log record as it is placed in
OTMA prefix user data section. On response, the data in OTMA user data section is echoed
back out. IMS Connect returns the tracking id on response back to SOAP Gateway. The
inbound and outbound tracking id is logged if the transaction log feature is enabled.
Tracking transactions from SOAP Gateway to IMS and back using logs
Now that we saw how the tracking propagated from the request to response, we can view
some logs to see how the logs have propagated lets start as seen in Figure 5-10 with the
SOAP Gateway Log first
179
8174ch04.fm
SOAP Log Input Message
Figure 5-10 SOAP Gateway Log of a Input Message
In the ICON BPE TRACE you find the following entries if:
ICONTR <-Message received from a TCP/IP client
ICONIS <-Message to be sent to IMS OTMA
ICONIR <-Message received from IMS OTMA
ICONTS <-Message sent to TCP/IP client
In Figure 5-11 you can see the ICONTR Entry of a BPE trace showing the trace and tracking
ID.
180
8174ch04.fm
Figure 5-11 ICONTR Entry in a BPE Trace
In the IMS input output logrecord you see an increase of x34 bytes which means the ICON
User Data in the type01 type03 record has been increased from the usual x'100' bytes to
x'134' bytes where the new/extra x'34' bytes is the *TRCKID* section
Transaction logging
SOAP Gateway creates and versions the transaction log.
The SOAP Gateway transaction log records information about every request made to a web
service provider and the associated response messages from IMS.
With the commands shown in Example 5-8, you can configure SOAP Gateway to enable or
disable transaction file logging, as well as configuring the file properties.
Example 5-8 Configure and enabling transaction file logging
iogmgmt tranLog on|-off

(-off by default) filePath fp (fp is optional logging file path)
fileNamePrefix fnp (fnp is optional logging file name prefix, default is
tranLog) fileMaxAge fa (fa is optional, exclusive with fileMaxSize, default is
24) fileMaxSize fs (fs is optional, exclusive with fileMaxAge, default is 1)
iogmgmt tranLog on filePath C:\SOAPGateway\logs
tranLog fileMaxAge 24 fileMaxSize 2
fileNamePrefix
In SOAP Gateway we are using either a Vertical or Horizontal ID

Horizontal ID
It is available if you have tracking enabled.
It is propagated to IMS Connect, so you can use them to trace a specific request
through SOAP Gateway, IMS Connect, IMS, and back.
Vertical ID
It is always unique
It is automatically generated and is not configurable.
181
8174ch04.fm
5.4.5 SOAP Gateway Message Processing Events

Uniquely identified message events are generated. Inbound request message records the
following events:
Event type 0: The server received a request from the client.
Event type 10: The server validated the request message.
Event type 12: SOAP Gateway sent the request message to IMS Connect.
The response message is associated with two event types:
Event type 11: SOAP Gateway retrieved the response message from IMS Connect.
Event type 17: the SOAP response message was sent to the client application.
Each request message sent to SOAP Gateway web service provider generates Uniquely
identified message events.
After IMS processes the request message, it sends a response message back to the client
application. The response message is associated with two additional event types:
The response can be a normal message response, a SOAP fault, an IMS Connect error
response, an IMS error response, or an error from the target IMS application program.
Errors during message processing might cause a message to fail before all event types are
recorded for the message. To determine why an error occurred, search the SOAP Gateway
server log, IMS Connect log records, or IMS log records for the horizontal ID associated with
the failed message.
In the screen shot of a transaction log shown in Figure 5-12, we collected event types 0, 10,
12, 11, and 17.
182
8174ch04.fm
Transaction Log
Figure 5-12 Transaction log
Each transaction record uses approximately 300 bytes of disk space, and each successful
transaction generates five transaction records in the active log file
the SOAP Gateway transaction logger creates a record for every incoming request and
outgoing response message that passes through the SOAP Gateway server
5.4.6 COBOL Top Down and Multiple hosts

In the previous versions of SOAP Gateway we used the bottom up or meet in the middle
approach, now with V22 of SOAP Gateway we want to introduce to Top Down or WSDL first
approach. Why do we need it:
Need to quickly get synchronous callout running with SOAP Gateway.
SOAP customers who want to have multi-operation support for synchronous callout.
Remove the need of COBOL copybook to generate artifacts for synchronous callout
Remove requirement to manual map between XSD data types and COBOL data types
The solution to this item is that the parts needed for synchronous callout can be generated
from a single WSDL file.
Also multiple operations defined in a WSDL file are now supported within the callout
correlators.
183
8174ch04.fm
It eases the setup of synchronous callout for SOAP Gateway and reduce errors that may
occur in a manually created COBOL copy book needed for callout. See Figure 5-13 depicting
an overview of the flow.
Figure 5-13 Design flow
1. Identify the WSDL service, port, and operation(s) that your IMS application needs to
invoke.
2. Create top-down Batch Processor options files (e.g., ServiceSpecification.xml) citing the
WSDL service, port, [and a subset of the operations if so desired].
3. 3. Run the Batch Processor once to generate the following for all (or a subset of)
operations:
COBOL Copybook containing 01-level structures for each input or output message.
COBOL XML converter for each operation.
SOAP Gateway correlator containing information for each operation.
Mapping session file for each input or output message
The solution highlights are, we create artifacts needed for synchronous callout from a single
WSDL file, multiple operations are supported for callout. Converters are generated for each
operation defined in WSDL and data types in XSD are associated accordingly to COBOL data
type. The correlator is populated with multiple operations if needed and multiple connection
bundle support is built into RDz 8.5.1.
In Figure 5-14 you see the operational specs you need to specify like serviceName, port, and
other attributes in the ServiceSpecification.xml file
184
8174ch04.fm
Define ServiceSpecification.xml
xsebatch -f C:\Hello\xsebatch_input\Container.xml -d C:\Hello\xsebatch_output -c verbose

Figure 5-14 operational considerations
Output will be generated in the correlator, converter and copybook by using the xsebatch as
shown in Example 5-9.
Example 5-9 xsebatch you need
xsebatch -s languageFile [-c | -w serviceName] | [-c -w serviceName] -f

containerFile [-d workspace] [-e WS_installdir] [-verbose] [-version]
[-overwrite=yes|no]
xsebatch -f C:\Hello\xsebatch_input\Container.xml -d C:\Hello\xsebatch_output -c
verbose
-s languageFile:
This parameter is required unless the same information is specified in the importFile
element. Here languageFile is the language source file that contains the message
definition. You can override this name by specifying values for the elements
importDirectory and inputFile in the MessageSpec element in the
ServiceSpecification.xml file.
-w serviceName
It causes the service definition files to be generated using the specified name for the Web
service. You can override this option by using the generateWSDL option in the
Container.xml file and in the ServiceSpecification.xml file. The value of this parameter can
be overridden by the value attribute of the EISService element in the
ServiceSpecification.xml file. The default value is set to esvc.
-f containerFile:
In Format (2) this parameter is required. It specifies the name of the Container.xml file that
contains the generation options. Most of the elements in this file are optional, but a few are
required and must be specified.
Most of the elements in this file are optional, but a few are required and must be specified.
-d workspace:
185
8174ch04.fm
This parameter specifies the fully qualified path of the workspace to be used for the
import. If this path is not specified on the command line then the default is taken from the
environment variable workspace. If that environment variable is not set then the default is
set to the following:
$eclipse_root/workspace
%eclipse_root%\workspace
-e WS_installdir:
This parameter specifies is the Eclipse subdirectory of the directory in which IBM Rational
Developer for System z is installed. If not specified, the default is taken from an
environment variable eclipse_root. If that environment variable is not set then the default is
set to the default installation directory for IBM Rational Developer for System z. That
directory is recorded during installation by the install process and is set in the environment
variable
WDZ71INSTDIR.
-verbose:
This parameter causes the diagnostic messages to be printed to the console.
-version:
This parameter causes the version, release, and modification information to be printed to
the console.
-novalidation:
This parameter turns off the validation of generation property files against an XML
Schema.
-overwrite=yes|no:
If set to yes then this parameter causes newly generated files to overwrite existing files of
the same
Compile and link IMS Connect XML converters
SFEKLOAD data set required for compiling
Setup ICON proc with FEK.SFEKLOAD for STEPLIB.
5.4.7 SOAP Gateway support for multiple hosts for callout

This function addresses SOAP Gateway customers who want to distribute workload between
multiple hosts for callout web services. by reduce the need for multiple SOAP Gateway
services. It also removes the need to deploy duplicate IMS Connect XML converters over
several hosts.
We enable SOAP Gateway services to talk to multiple IMS Connect hosts or datastores. The
distributed workload of callout over multiple hosts gives us the ability to share services and
converters. Figure 5-15 on page 187 samples the amount of:
1 SOAP Gateway
1 WSDL
1 correlator
2 connbundles
2 datastore or ICON.
1 descriptor.
1 converter.
186
8174ch04.fm
SOAP Gateway multiple hosts

HelloService
SOAP Gateways
Hello.xml
Hello.wsdl
cb_host_ims1
cb_host_imsa
IMS1
HWS1
Resume
Tpipes
Super
Member
IMSA
Hello.xml
Hello.wsdl
cb_host_ims1
cb_host_imsa
Figure 5-15 Multiple hosts
What we need to do to get this to run, is to create a descriptor in DFSYTDx member for
TMEMBER and XML Adapter, as shown in Example 5-10.
Example 5-10 DFSYTDx sample
D HELLO1
D HELLO1
TYPE=IMSCON TMEMBER=SM01 SMEM=YES TPIPE=SGPSING9

ADAPTER=HWSXMLA0 CONVERTR=HELLOD
Than we need to Compile and link a single converter. Next we need to do is to Create 2
connection bundles as Example 5-11 shows, by using the SOAP Gateway Management
Utility.
Example 5-11 connection bundles
iogmgmt conn c n cb_host_ims1 d IMS1 p 9999 h myhost.com i SGPSING9

iogmgmt conn c n cb_host_ims1 d IMSA p 9999 h myhost.com I SGPSING9
Next we want to do is Update the correlator to point to the 2 connection bundles
Example 5-12 shows how this is done.
Example 5-12 update the correlator
iogmgmt u r HELLO.xml p HelloOperation i HELLOService d

cb_host_ims1,cb_host_imsa
What would be next, yes deploy it by doing the command as in Example 5-13.
Example 5-13 Deploy
iogmgmt deploy w HELLO.wsdl r HELLO.xml
187
8174ch04.fm
Now we should be able to run the service, but what to do or look for in case we get into a
problem because we did something wrong
We may start with the IMS job log to verify DFSYDTx data set is loaded upon IMS restart
READ SUCCESSFUL FOR DDNAME PROCLIB
MEMBER = DFSYDTx
We Verify MPP job log for ICAL if it has a return and reason codes of 0
If the external web service is not available SOAP log will have the message:
IOGS0077E:
AN ERROR OCCURRED DURING THE INVOCATION OF THE EXTERNAL WEB SERVICE: THE
SERVICE CANNOT BE FOUND FOR THE ENDPOINT REFERENCE
If the external web service times out the SOAP log will have the message:
IOGS0077E:
AN ERROR OCCURRED DURING THE INVOCATION OF THE EXTERNAL WEB SERVICE: READ TIMED
OUT
In that case you should increase the Callout WS timeout value in the callout correlator. You
may have to also increase the timeout value for ICAL in the IMS Application.
A no tpipes specified case will give you a warning
IOGX0019W
skipping the callout connection bundle
If the Connection Bundle is missing that gives you a
IOGX0008W:
The correlator file entries cannot processed
5.4.8 WS-Security for synchronous callout and migration

The next step we need to address is to apply security into SOAP Gateway for Synchronous
Callout. With the previous Versions of SG the authentication and authorization assertions
didnt get propagated across web service transactions for callout.
We are using the Originating Userid (PSTUSID) for IMS Synchronous callout application
which is passed to the external Web service for further authentication and authorization. This
provides the message-level security for synchronous callout.
188
8174ch04.fm
Design Overview
Figure 5-16 Run time of a synchronous callout processing
Figure 5-16 shows the run time of a synchronous callout processing.

1. A callout application (in this sample, SYCALOUT.cbl) starts. The ICAL call in
SYCALOUT.cbl specifies the name of the OTMA destination descriptor, which defines the
name of the hold queue (or tpipe) the callout message will be placed.
2. Upon the Hello callout web service deployment, IMS Enterprise Suite SOAP Gateway
polls the hold queue for callout messages.
3. IMS Connect converts the callout message from binary data to XML and sends it to SOAP
Gateway.
4. SOAP Gateway sends the callout message to the external target server.
5. The target server sends a response.
6. SOAP Gateway sends the response back to the waiting IMS application.
For the synchronous callout scenarios, in addition to transport-level security through basic
authentication, server authentication, or mutual authentication, SOAP Gateway now supports
message-level security with SAML 1.1 and SAML 2.0 sender-vouches unsigned tokens.
SAML is an XML-based standard developed by Security Services Technical Committee
(SSTC) of Organization for the Advancement of Structured Information Standards (OASIS).
This standard facilitates:
189
8174ch04.fm
The exchange of user identity and security attributes information between communicating
parties at the SOAP message level.
The exchange of authentication and authorization assertions across web service
transactions.
WS-Security SAML confirmation method is supported for synchronous callout applications by
extracting the user ID (the user that initiates the synchronous callout application) from the
correlation token and passing it to the external web service.
SOAP Gateway also supports custom authentication modules for accessing the security
header for validation before the SOAP request messages are sent out to the external web
service server.
Like always we have some restrictions to consider, these are:
Only support WS-Security for Synchronous callout
Only support for SAML1.1 or SAML2.0 unsigned assertion
Use different TPIPEs for security and non-security connections
If you use RDz 8.0.3.2 generated correlator files
Then you need to run migration tool first to update correlator files to the latest schema
Keystores/truststores for both provider and callout
Cannot co-exist in the same SOAP Gateway instance
All operations in a service must be the same security type
A few words on how to configure client authentication between SOAP Gateway (client) and
external web services server
Use Java key tool command to create key store, trust store for both client and server,
exchange certificate, import the other side certificate to trust store. e.g. Importing client side
certificate to server side trust store.
Use management utility tool, (Example 5-14) to update client side (SOAP Gateway) keystore,
truststore and passwords information to the connection bundle file.
Example 5-14 update client side
iogmgmt -conn -c -n MyCalloutConnBundle -h ICONHOST -p 9998 -d IMSSTOR1 -i tpipe1

-l /path/to/MyCalloutClientKeystore.ks -y MyCalloutclientKeystorePwd -v
/path/to/MyCalloutClientTruststore.ks -q MyCalloutClientTruststorePwd
Deploy call out web service with token type either SAML11Token (Example 5-15) or
SAML20Token
Example 5-15 deploy SAML11 token
iogmgmt -deploy w hello.wsdl r hello.xml t SAML11Token

Callout message will be encrypted and decrypted during the transportation socket security;
there will be some performance impact
What kind of documentation you may need to collect to diagnose a problem?
Turn on soap log to debug mode by changing to level 5 using the property command in
Example 5-16.
190
8174ch04.fm
Example 5-16 debug mode
iogmgmt prop u l 5
Error scenarios and possible causes you can see in Figure 5-17 and Figure 5-18 on
page 191.
CWWSS6521E: The Login failed because of an exception:
javax.security.auth.login.LoginException:
unable to find valid certification path to requested target
org.apache.axis2.AxisFault: CWWSS6521E: The Login failed because of an exception:

javax.security.auth.login.LoginException:
at org.apache.axis2.util.Utils.getInboundFaultFromMessageContext(Utils.java:517)
at org.apache.axis2.description.OutInAxisOperationClient.handleResponse(OutInAxisOperation.java:370)
at org.apache.axis2.description.OutInAxisOperationClient.send(OutInAxisOperation.java:416)
at org.apache.axis2.description.OutInAxisOperationClient.executeImpl(OutInAxisOperation.java:228)
at org.apache.axis2.client.OperationClient.execute(OperationClient.java:163)
at target.files.PL1TYPEServiceStub.emptyInRandomOutOperation(PL1TYPEServiceStub.java:816)
at PL1TYPE_ADB_Security.main(PL1TYPE_ADB_Security.java:39)
CWWSS6521E: The Login failed because of an exception: javax.security.auth.login.LoginException:
Figure 5-17 Error scenario #1
Possible Causes might be:

Didn't import client side certificate to the server side truststore correctly.
If the trust store does not contain the root cert, you see this kind of exception.
Use Keytool tool to check certification command as seen in Example 5-17.
Example 5-17 Check certificate
keytool -printcert -file absolute path to cert

Scenario #2 is showing a token problem, see Figure 5-18
<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope
xmln s:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Head er
xmln s:wsa="http://www.w3.org/2005/08/addressing"><wsa:Action>http://www.w3.org/2005/08
/addressing/soap/fault</wsa:Action><wsa:RelatesTo>urn:uuid:DCA3E8B163DADDA0EB1309
983 896543</wsa:Rel atesTo></soapenv:Header><soapenv:Body><soapenv:Fault><faultcode
>soapenv:Server</faultcode><faultstring>security.wssecurity.WSSContextImpl.s02:
org.apache.axis2.AxisFault: CWWS S5502E: The target element: saml2:Assertion w as not
expected.</faul tstring><detail /></soapenv:Fault></soapenv:Body></soapenv:Envelope>
Figure 5-18 Error scenario #2
Usually, the policyset is configured to require the token type; the received message does not
have the token in it or it could be that you have SAML20Token configured, but SAML20Token
is not being sent, instead you received SAML11Token.
191
8174ch04.fm
5.4.9 IMS Enterprise Suite V3.1 features

IMS Enterprise Suite Version 3.1SOAP Gateway adds the following support:
64-bit support for z/OS

Send-only with ACK support for synchronous callout
SOAP Gateway management utility batch mode support
Enhanced security cipher suite support
5.4.10 64-bit support for z/OS

IMS Enterprise Suite Version 3.1SOAP Gateway adds the support for 64-bit z/OS
operating environments, send-only with acknowledge for synchronous callout, and SOAP
Gateway management utility batch mode.
SOAP Gateway now runs on 64-bit on the z/OS platform, allowing organizations to take
advantage of their 64-bit operating environment for extended memory usage.
5.4.11 Send-only with ACK support for synchronous callout

Send-only with acknowledgement protocol support for synchronous callout allows SOAP
Gateway to receive a final confirmation that the response message was delivered to the
original IMS application that issued the callout request. This confirmation provides SOAP
Gateway users additional information about whether a callout response message was sent to
IMS and whether IMS received the message.
Send-only with acknowledgement protocol for web service consumer

applications
The send-only with acknowledgement protocol allows your application to receive a final
confirmation that the response message was delivered to the original IMS application that
issued the callout request.
Restriction: Only synchronous callout applications can use the send-only with
acknowledgement protocol.
By default, SOAP Gateway uses the send-only protocol without acknowledgement to send
callout response messages to IMS. The send-only with acknowledgement protocol provides
an alternative approach that offers an extra level of confirmation that the response message
was received. After the callout response message is sent to IMS, IMS sends either an ACK
(positive acknowledgement) or NACK (negative acknowledgement) response to SOAP
Gateway. The ACK or NACK is not sent to the external callout target application, but SOAP
Gateway logs the response.
For NACK responses, SOAP Gateway logs an IOGS0082E message if the trace level is set to
error or higher. For ACK responses, SOAP Gateway logs an IOGS0081I message if the trace
level is set to informational or higher. If no ACK or NACK is received, SOAP Gateway logs an
IOGS0083E message.
The main advantage of the send-only with ACK protocol is that you can easily identify if a
callout response message was sent to IMS, whether IMS received the message, and how
long it took the message to reach IMS. The main disadvantage is that the ACK or NACK reply
adds an extra network communication event for each callout response message.
192
8174ch04.fm
You can enable the send-only with acknowledgement protocol for a web service consumer
application with the SOAP Gateway management utility when you create or update a
correlator. Set the value for the -k property to true. The send-only with acknowledgement
protocol is configured at the operation level and can be enabled or disabled without restarting
the SOAP Gateway server.
5.4.12 SOAP Gateway management utility batch mode support

Administrators can now use the batch mode of the management utility to facilitate web
service deployment and server management for better performance. Instead of issuing one
command at a time, each with its own JVM instance, a file with a list of commands can be
passed to the SOAP Gateway management utility batch command for execution in one JVM
instance.
5.4.13 Enhanced security cipher suite support

SOAP Gateway is enhanced to use the FIPS 140-2 approved cryptographic provider(s);
IBMJCEFIPS (certificate 376) and/or IBMJSSEFIPS (certificate 409) for cryptography. The
certificates are listed on the NIST web site at
http://csrc.nist.gov/cryptval/140-1/1401val2004.htm. SOAP Gateway also adds the
support for Transport Layer Security (TLS) V1.2 and for cipher suites with key length of 2048
and key strength of 112 bit, as required by NIST SP800-131A.
5.5 Asynchronous Callout with SOAP Gateway

In the recent years, there is an increasing need for core IMS business functions to access
new business logic and data running outside the IMS environment. There is interest in
transforming IMS applications into a Business-to-Business (B2B) clients, not just components
within a B2B server.
IMS Version 10 adds application asynchronous callout support to a Web Service through IMS
SOAP Gateway. IMS Callout refers to the ability of an IMS application to act as a client to
invoke an application that is external to the IMS environment (for example, an application
running in the distributed platform).
To support IMS Asynchronous Callout to Web Services, IMS SOAP Gateway implements the
IMS Resume TPIPE protocol internally and manages a resume TPIPE loop inside the IMS
SOAP Gateway server to continually retrieve asynchronous messages that were inserted
from an alternate TPPCB by the IMS application. After the callout request message is
received, IMS SOAP Gateway processes the request, finds the Web Service identifier in the
callout request message and matches it with the deployed Web Services to locate and invoke
the desired Web Service. The invoked Web Service either performs the task and ends or
sends the callout response message back to IMS to start a new IMS transaction, as shown in
Figure 5-19.
193
8174ch04.fm
Figure 5-19 Asynchronous Callout flow
The advantage of using asynchronous callout is that it does not hold up the region, but it does
require the IMS application to be designed in a way that is able to handle the output from the
external application (if any) in a different IMS application instance.
5.5.1 Invoking the Web Service operation

There are two types of Web Service operations for asynchronous callout: the one-way
invocation and the request-response invocation. The one-way invocation corresponds to the
one-way port type and the request-response invocation corresponds to the request-response
port type of the Web Service operation. In the one-way invocation, no response is expected
from the Web Service. In the request-response invocation, a response message is
synchronously returned back to the caller.
If the operation is a one-way, it sends out the request message by taking the XML message
as the payload data but does not wait for the response to come back. If the operation is a
request-response, IMS SOAP Gateway waits for the response data to synchronously come
back from the same SOAP/HTTP connection.
After the request message is sent successfully, IMS SOAP Gateway sends an ACK (positive
acknowledgement) internally to IMS Connect to indicate the callout request message is
received and processed such that it can be removed from the TPIPE. In the case of the
request-response request, the ACK is sent back to IMS Connect after the request is sent
successfully to the Web Service but before IMS SOAP Gateway starts waiting for the
response message from the Web Service.
If the send fails or a processing error occurred before invoking the Web Service, a NAK
(negative acknowledgement) with reroute command is sent to IMS Connect such that the
callout request message is removed from the callout TPIPE and be rerouted to an error
queue.
5.5.2 Returning the callout response message to IMS

In a request-response invocation, a callout response message is returned by the Web Service
to IMS SOAP Gateway. For asynchronous callout, this response message is sent back to the
IMS system by invoking a new IMS transaction, which we call Appl2.
194
8174ch04.fm
When IMS SOAP Gateway receives the response message, it first extracts the response
payload data from the SOAP message. Then, an IMS Connect message is built to send the
response message back to the IMS Appl2. The IMS Connect message has the format,
LLLLIRM<Response data>. The IRM contains the transaction code for the IMS Appl2. It also
contains the XML Adapter name and the converter name if the user chooses to use the XML
adapter function to transform the callout response message. The transaction code, XML
adapter, and converter name are all obtained from the correlator file specified by the user
during the deployment step. If the user chooses not to use the XML adapter, IMS SOAP
Gateway adds LL ZZ and trancode in front of the response data.
After the response message is built, it is sent to IMS Connect using Commit Mode 0 with
Send Only protocol.
When IMS Connect receives the XML response message from the IMS SOAP Gateway, the
XML conversion function converts the XML response data into the IMS application data
format if the user chooses the XML adapter function. Upon receiving the converted
application data bytes from the converter, the XML Adapter computes the new LL value. It
also sets the transaction code value (obtained from the IRM that IMS SOAP Gateway sends)
within the message. The resulting response data message is then sent to IMS Appl2.
Note: If the callout response needs to go back to the initial client, a synchronous callout
solution is recommended. However, a pseudo synchronous solution can be achieved with
appropriate application design, for example, the initial IMS application can wait in the
dependent region and continue to check for the output data (updated by a second
transaction) through a database.
5.5.3 Web Services callout scenarios for Asynchronous Callout

In this section, we describe three common scenarios. All of these scenarios use the IMS
Connect XML Adapter function for XML transformation and the OTMA descriptor function.
Scenario 1: Callout to one-way Web Service with no response to IMS

In this scenario, presented in Figure 5-20, the IMS application calls out to an one-way
operation on the Web Service. Neither response or error is expected from the Web Service.
An example of this type of processing is when an IMS application needs to invoke a Web
Service to perform a task, such as callout to a printer.
195
8174ch04.fm
Figure 5-20 SOAP Callout to a one-way Web Service invocation with no response
The stages that are associated with this type of asynchronous callout flow are:
1. A client starts IMS Appl1.
2. A one-way callout message is inserted into the ALTPCB by the IMS application App1
using the destination routing descriptor DESTSG1. The descriptor contains the
TMEMBER name, TPIPE name, XML Adapter name, and the associated Converter name.
As part of the destination routing descriptor processing, OTMA reads the descriptor
DESTSG1, which contains a TPIPE name of SGTP1, and sends the callout message to
the asynchronous hold queue SGTP1 TPIPE. The adapter name (HWSXMLA0) and
converter name (XMLCNV1D) specified in the DESTSG1 descriptor are copied to the
OTMA headers of the callout message. The callout message looks like Figure 5-21, after
descriptor processing.
Figure 5-21 Callout message after OMTA descriptor processing
3. IMS SOAP Gateway establishes a sharable persistent TCP/IP connection with IMS
Connect and sends a RESUME TPIPE using an option of No Auto to retrieve messages
from the SGTP1 TPIPE. The TPIPE is obtained from the connection bundle file when IMS
SOAP Gateway starts up.
4. IMS Connect retrieves the existing callout message from SGTP1 as part of the RESUME
TPIPE request processing for IMS SOAP Gateway. It reads the OTMA headers for the
196
8174ch04.fm
adapter name and converter name. It calls the adapter HWSXMLA0 and passes the
converter name XMLCNV1D to it.
After the activity completes the XML Adapter calls the converter XMLCNV1D to perform
the data transformation from COBOL application data to XML. The converter adds the
service data prefix to the message so that IMS SOAP Gateway can use/read the
appropriate correlator file and direct the request to the appropriate Web Service operation.
5. After the converter converts the callout message successfully, XML Adapter wraps the
callout message in a <XMLAdapterOutput> tag and then IMS Connect adds a 4-byte
length LLLL at the beginning of the message and sends the callout request message back
to IMS SOAP Gateway. The resulting callout message appears in Figure 5-22.
Figure 5-22 Callout message with XML Adapter Output tag
6. After IMS SOAP Gateway receives the callout request message, it reads the LLLL portion
of the message and determines the length of the message to be read. It also parses the
message to retrieve the WSID from the service data prefix. Based on the WSID value
WS1, it loads the corresponding correlator file, which is WS1.xml, and retrieves the Web
Service information and properties for invoking the Web Service. The request message for
Web Service is built.
7. After the callout message is processed successfully and the request message for the Web
Service is built, IMS SOAP Gateway internally sends a positive acknowledgement (ACK)
to IMS Connect such that the callout message can be removed from the corresponding
TPIPE.
8. IMS SOAP Gateway sends the one-way callout request message to the Web Service
using SOAP/HTTP. The callout message using SOAP/HTTP appears in Figure 5-23.
.
Figure 5-23 Callout message with SOAP tag
Scenario 2: Callout to one-way Web Service with a response returned to

IMS by invoking a second Web Service on IMS SOAP Gateway
In this scenario, presented in Figure 5-24 on page 198, IMS application App1 calls out as a
one-way operation to Web Service 1 which invokes another one-way operation on Web
Service 2.
The first seven steps are similar to the previous scenario in that they provide details of how a
Web Service is invoked. The additional steps show the details of a Web Service invoking
another pre-deployed Web Service, which calls an existing IMS application.
197
8174ch04.fm
Figure 5-24 SOAP Callout to a one-way Web Service invocation with a response
1. A client starts IMS application App1.

2. A one-way callout message is inserted into the ALTPCB by the IMS application App1
using the destination routing descriptor DESTSG1. The descriptor contains the
TMEMBER name, TPIPE name, XML Adapter name, and the associated Converter name.
As part of the destination routing descriptor processing, OTMA reads descriptor
DESTSG1, which contains a TPIPE name of SGTP1, and sends the callout message to
the asynchronous hold queue SGTP1 TPIPE. The adapter name (HWSXMLA0) and
converter name (XMLCNV1D) specified in the DESTSG1 descriptor are copied to the
OTMA headers of the callout message. The callout message looks like Figure 5-21 on
page 196 after descriptor processing.
Connect and sends a RESUME TPIPE to retrieve messages from the SGTP1 TPIPE. The
TPIPE is obtained from the connection bundle file when IMS SOAP Gateway starts up.
The XML Adapter calls the converter XMLCNV1D to perform the data transformation from
COBOL application data to XML. The converter adds the WSID and the operation name
information to the message so that IMS SOAP Gateway can use/read the appropriate
correlator file and direct the request to the appropriate Web Service operation.
5. After the converter converts the callout message successfully, the XML Adapter wraps the
callout message in a <XMLAdapterOutput> tag and then IMS Connect adds a 4-byte
length LLLL at the beginning of the message and sends the callout request message back
to IMS SOAP Gateway. The resulting callout message looks like Figure 5-22 on page 197.
198
8174ch04.fm
message to retrieve the service data. Based on the WSID value WS1 from the service
data, it loads the corresponding correlator file, which is WS1.xml, and retrieves the Web
Service information and properties for invoking the Web Service. The request message for
Web Service is built.
TPIPE.
8. IMS SOAP Gateway sends the one-way callout request message to the Web Service 1
using SOAP/HTTP. No response is expected from the Web Service 1. The callout
message using SOAP/HTTP appears as in Figure 5-23 on page 197.
9. Web Service 1 executes, generates output, and calls Web Service 2. It is the responsibility
of Web Service 1 to create and transform output in such a manner that it maps to the input
request of Web Service 2.
10.IMS SOAP Gateway receives the Web Service 2 request and it loads the correlator 2
(WS2.xml) to obtain the information for IMS Appl2 and sends the data to IMS Connect. In
this scenario, the IMS transaction code is supplied by the Web Service 2.
11.IMS Connect receives the input message and loads converter 2 (XMLCNV2D) for XML to
bytes conversion. Then, it invokes the IMS application Appl2 to process the data.
Scenario 3: Callout to a request-response Web Service

In this scenario, presented in Figure 5-25 on page 200, the IMS application calls out to a
request-response operation on the Web Service, and a response is sent back to IMS SOAP
Gateway, which invokes a new IMS application (IMS application App2) for processing the
output.
199
8174ch04.fm
Figure 5-25 Message flow of SOAP Callout to a request-response Web Service invocation
1. A client starts IMS application App1.

2. A one-way callout message is inserted into the ALTPCB by IMS application App1 using
the destination routing descriptor DESTSG1. The descriptor contains the TMEMBER
name, TPIPE name, XML Adapter name, and the associated Converter name. The callout
message looks like Figure 5-22 on page 197 after descriptor processing.
As part of the destination routing descriptor processing, OTMA reads the descriptor
DESTSG1, that has a TPIPE name of SGTP1, and sends the callout message to the
asynchronous hold queue SGTP1 TPIPE. The adapter name (HWSXMLA0) and converter
name (XMLCNV1D) specified in the DESTSG1 descriptor are copied to the OTMA
headers of the callout message.
Connect and sends a RESUME TPIPE using an option of No Auto to retrieve messages
from the SGTP1 TPIPE. The TPIPE is obtained from the connection bundle file when IMS
SOAP Gateway starts up.
The XML Adapter calls the converter XMLCNV1D to perform the data transformation from
COBOL application data to XML. The converter adds the WSID and the operation name
information to the message so that IMS SOAP Gateway can use/read the appropriate
correlator file and direct the request to the appropriate Web Service operation.
5. After the converter converts the callout message successfully, XML Adapter wraps the
callout message in <XMLAdapterOutput> tag and then IMS Connect adds a 4-byte length
200
8174ch04.fm
LLLL at the beginning of the message and sends the callout request message back to IMS
SOAP Gateway. The resulting callout message appears as in Figure 5-22 on page 197.
message to retrieve the service data prefix. Based on the WSID value WS1 from the
service data prefix, it loads the corresponding correlator file, which is WS1.xml, and
retrieves the Web Service information and properties for invoking the Web Service. The
request message for Web Service is built.
TPIPE.
8. IMS SOAP Gateway sends the request to the Web Service 1 using SOAP/HTTP and waits
for the response synchronously on the same HTTP connection. The callout message
using SOAP/HTTP appears as in Figure 5-23 on page 197.
9. The Web Service 1 runs and generates output response and sends back to IMS SOAP
Gateway.
10.IMS SOAP Gateway adds the transaction code App2, the adapter name, HWSXMLA0;
and the converter name, XMLCNV2D (all retrieved from the correlator file in step 6) to the
IRM and sends the response message to IMS Connect.
11.IMS Connect receives the response message and loads the response converter
XMLCNV2D for XML to bytes conversion. IMS Connect takes the transaction code value
and adds it to the appropriate place (LLZZTRCDDATA) in the message.
12.IMS invokes the IMS application App2 to process the output data.
RDz can be used to import the SOAP Client WSDL, generate the correlator file, create the
XML Converter routine to be called by IMS Connect to do the XML transformation for the
callout message, and the COBOL copy member that represents the output message.
Considerations for Callout usage

When you use the callout function, to restart or gracefully shut down the IMS SOAP Gateway
server:
1. Stop all the callout threads by using the IMS SOAP Gateway Management Utility. Give
sufficient time for the threads to stop completely. The time it takes to stop the threads is
based on the callout poll interval property that is defined in the imssoap.properties file. At
a minimum, wait as long as the callout poll interval time.
2. Stop the IMS SOAP Gateway server.
3. When you are ready, start the IMS SOAP Gateway server. If the callout function is not
disabled, the callout threads would start automatically.
5.6 Synchronous Callout with IMS SOAP Gateway

IMS SOAP Gateway 10.1 with the latest iFix supports synchronous callout. With this new
feature your IMS applications are enabled to synchronously invoke external applications
With Synchronous Callout support, IMS applications callout synchronously and wait for the
response to come back. Using this programming style, the IMS application program can
initiate direct communication with other external application programs and receive the
response in the same IMS transaction instance.
201
8174ch04.fm
5.6.1 Detailing Synchronous Callout with IMS SOAP Gateway

Figure 5-26 is an overview of IMS Synchronous Callout support.
Figure 5-26 IMS Synchronous Callout support
The IMS Synchronous Callout support enhancements are:

A new DL/I call, the ICAL SENDRECV call, for an IMS application to send out a
synchronous callout request and receive the response back. The ICAL synchronous call
function introduces a new IMS application programming style. The traditional IMS
application programming style is an asynchronous programming model supported by the
IMS message queue.
The ICAL synchronous call function is only supported using the AIBTDLI interface in IMS
TM runtime environments for IFP, MPP, BMP, JMP, and JBP regions. ICAL is used to
support IMS Synchronous Callout.
Synchronous invocation to Web Services.
Communication topology to enable an external application to process the callout request
and to return the response to the same IMS application program instance. The
IMS-dependent region is in a wait state when waiting for the response.
Time-out capability to allow the IMS application to specify how long it can wait for the
response message to come back, which can help to terminate the callout request and free
up the dependent region if the external service does not respond in a timely manner.
Enhanced OTMA Resume TPIPE and Send-Only message processing functions for
external application to pull synchronous callout request messages and return the
response back.
Relief of the 32K segmentation limitation for synchronous callout messages because the
IMS message queue is not used. The maximum XML message size for both the request
and response for synchronous callout messages is 32 MB for COBOL applications and 16
MB for PL/I applications, which enables IMS applications to send out and receive large
messages.
Concurrent processing with a correlation mechanism to allow callout requests to be sent
out and response messages to be received in different connections and threads.
Updated IMS commands to view synchronous callout request status.
202
8174ch04.fm
Figure 5-27 shows an overview of the synchronous callout flow.
Figure 5-27 Overview of IMS Synchronous Callout flow
The flow of the synchronous callout flow is:

1. The external application or server does not listen for callout messages because of the use
of the IMS OTMA Resume TPIPE function.
2. The IMS application program issues an ICAL SENDRECV synchronous callout request
through an OTMA descriptor name, which defines the destination for the call.
3. The OTMA descriptor allows IMS to route the callout request through IMS Connect to the
outbound destination, for example, a EJB/MDB running in WebSphere Application Server
using the IMS TM Resource Adapter, a RYO IMS Connect TCP/IP application, or a Web
Service provider through IMS SOAP Gateway.
4. After the callout request is processed, the response data is returned back to the same IMS
transaction instance.
In summary, after the synchronous callout request message is received, IMS SOAP Gateway
processes the request, finds the Web Service identifier in the callout request message and
matches it with the deployed Web Services to locate and invoke the desired Web Service.
The invoked Web Service, after processing, sends the callout response message back to the
IMS application that is waiting synchronously for a response.
Invoking the Web Service operation

For Synchronous Callout, only one type of Web Service operation is supported. It is the
request-response invocation where a response message is returned synchronously back to
the caller. IMS SOAP Gateway waits for the response data to come back synchronously from
the same SOAP/HTTP connection.
The invocation of the Web Service is performed by a worker thread. Any errors that occur in
the worker thread during the invocation of the Web Service is sent back with an error
response to IMS Connect which, in-turn, passes the error to the waiting IMS application.
203
8174ch04.fm
5.6.2 Synchronous Callout User Scenarios

In this section, we describe the various topologies where you can use synchronous Callout.
Scenario 1: Multiple IMS applications

Figure 5-28 illustrates that multiple IMS applications can make callout requests at the same
time. In this example, each IMS application uses a different descriptor for the target callout
destination.
Figure 5-28 Callout flow with multiple IMS applications
Scenario 2: Multiple IMS Connects

Figure 5-29 on page 205 represents the scenario that different IMS Connect instances are
used to send the request and to receive the response messages. The correlation token sent
inside the request and response message allows IMS to ensure that the response message
goes to the same IMS transaction instance that initiates the synchronous callout request.
This scenario is common if Sysplex Distributor is configured and used in front of a number of
IMS Connects. All the IMS Connects would share a single external IP address that is
managed by the Sysplex Distributor. When the response is returned, the sysplex distributor
might route the response to any of the IMS Connect if the external server uses a different
connection to return the callout response message.
204
8174ch04.fm
Figure 5-29 Callout flow with multiple IMS Connects
Scenario 3: IMS Shared Queues

Figure 5-30 illustrates that the Synchronous Callout support can be used in a shared queue
environment if the IMS is both the front-end and back-end system.
The Send Only response must be routed back to the same IMS that initiated the request;
otherwise, the response message is rejected.
Figure 5-30 Callout flow with IMS Shared Queues
205
8174ch04.fm
Scenario 4: Multiple Servers for High Availability

Figure 5-31 illustrates that multiple servers can be configured to achieve high availability and
redundancy.
Server 1 can be a WebSphere Application Server, IMS SOAP Gateway, or RYO application.
Server 2 can be connected to the same IMS Connect as Server 1 or a different IMS Connect
instance. If IMS Connect attempts to deliver the callout request message to Server 1 and
fails, IMS Connect sends the message back to OTMA, which allows the message to remain
on the TPIPE and be retrieved by Server 2 to complete the processing.
Figure 5-31 Callout flow with multiple servers
Requirements and restrictions for synchronous callout

In this section, we provide the requirements and restrictions for synchronous callout.
The requirements for synchronous callout are:
IMS SOAP Gateway Version 10.1 with the latest iFix
Rational Developer for System z Version 7.1.1.3 or later
The restrictions for synchronous callout are:
Two-phase commit is not supported.
Shared queue environments with different front end and back end IMS systems is not
supported. The response message of a synchronous callout request must flow back to the
originating IMS to be processed correctly.
BMP or JBP applications running in a DBCTL environment are not supported.
The callout processing inside the IMS application must be single-threaded, that is, the IMS
application can only issue one synchronous callout call at a time. It must wait for the
response (or time-out) before it can issue the next callout request.
The maximum XML message size for both the request and response for synchronous
callout messages, is 32 MB for COBOL applications and 16 MB for PL/I applications.
206
8174ch04.fm
5.7 Multi-segment support

IMS SOAP Gateway 10.2 introduces multi-segment support. The significance of this support
is that IMS multi-segment applications can now participate in SOA using IMS SOAP Gateway.
This support is provided for the XML adapter scenario in IMS Connect and IMS SOAP
Gateway, with tooling support from Rational Developer for System z Version 7.5.
Multi-segment support is provided only for the provider (inbound both request / response)
scenario and not for the consumer (callout) scenario.
As with current single segment handling, the bulk of the multi-segment handling is performed
by the RD/z generated XML converters, which are deployed into IMS Connect. The IMS
Connect XML Adapter function utilizes the XML converters for the XML-to-bytes conversion
on the way in and bytes-to-XML conversion on the way out of IMS. This approach still applies
for multi-segment support. IMS SOAP Gateway utilizes the RD/z tooling to support the
generation of Web Services artifacts for multi-segment message processing programs
(MPPs).
Multi-segment handling in SOAP Gateway is achieved in two steps:
1. Artifact generation using Rational Developer for System z (RD/z) Version 7.5.
2. Runtime handling in IMS Connect by the XML Adapter and the generated XML converters.
The pre-requisites for multi-segment support are:
IMS Connect 10 SPE APAR PK69366
IMS SOAP Gateway 10.2
Tooling support: Rational Developer for System z 7.5
5.8 Security enhancements

SSL and HTTPS security allow data to be transferred in a secure manner between the Web
Service and IMS SOAP Gateway and between IMS SOAP Gateway and IMS Connect.
IMS SOAP Gateway processes a SOAP request by stripping off the SOAP headers and
passing the XML payload to IMS Connect. This can be sent in plain format or over a SSL
connection to protect the message.
The security properties between IMS SOAP Gateway, IMS Connect, and IMS are specified in
the connection bundle. The security properties that must be specified and that are passed to
IMS Connect are: User Id, Password, and Groupname.
In addition, there are SSL parameters that are required for the IMS SOAP Gateway to
communicate with the IMS Connect through TCP/IP SSL Sockets. These parameters are
listed in 5.2, IMS SOAP Gateway overview on page 164. To specify this data you must open
the Connection Bundle file, which can be accessed through the IMS SOAP Gateway
Management Utility.
If RACF=Y is specified in the HWSCFGxx member, IMS Connect issues a RACF call to verify
these parameters. If the call is not successful, an error message is returned to IMS SOAP
Gateway. If the call is successful, the UserID and Group is passed to OTMA.
The IMSLSECX exit is also invoked if it exists, but this exit does not does not verify the
password. Figure 5-32 on page 208 maps out the message flow under security controls.
207
8174ch04.fm
Figure 5-32 SSL/HTTP message flow
5.9 IMS SOAP Gateway features and compatibilities

Table 5-2 maps what features of IMS SOAP Gateway are compatible to which tools and
versions of IMS and IMS Connect.
Table 5-2 Summary of IMS SOAP Gateway features and compatibilities
208
Feature
Minimum SOAP
Gateway
version
Minimum IMS
version
Minimum IMS
Connect version
Minimum
Rational Tooling
version
Accessibility
Enablement
v 9.2
v9
v9
7.0
IMS Connect
XML Adapter
Support
v9.2
v9
v9
7.0
Security
Enhancements:
SSL/HTTPS
v 9.2
v9
v9
7.0
Platform Support:
z/OS and zLinux
zLinux: v9.2
z/OS: v10
v9
v10
v9
v10
v7.0
v7.1.1
Asynchronous
Callout
v10.1
v10
v10
7.1.1
8174ch04.fm
Feature
Minimum SOAP
Gateway
version
Minimum IMS
version
Minimum IMS
Connect version
Minimum
Rational Tooling
version
Synchronous
Callout
v10.1 +iFIX2
v10
v10
7.1.1.3
Multiple Segment
v10.2
v10
v10
v 7.5
Refer to the following Web site for the current SOAP Gateway compatibility table:
http://www-01.ibm.com/support/docview.wss?uid=swg27036162
Multiple segment support in IMS SOAP Gateway is announced in the IMS Version 11 QPP
(Quality Partnership Program) announcement number 208-258 found in URL:
http://www.ibm.com/common/ssi/index.wss?DocURL=http://www.ibm.com/common/ssi/rep_c
a/8/897/ENUS208-258/index.html&InfoType=AN&InfoSubType=CA&InfoDesc=Announcement+Le
tters&panelurl=index.wss%3Fbuttonpressed%3DNAV002PT090&paneltext=Announcement+lett
er+search
This concludes our discussion about SOAP Gateway.
209
8174ch04.fm
210
8174ch05.fm
Chapter 6.
JEE application technology

In this chapter we provide an overview about the JAVA Enterprise Edition and the tooling we
are using such as Rational Developer for z (RDz) and WebSphere Application Server (WAS)
The Java 2 Platform, Enterprise Edition (J2EE platform) provides containers for client
applications, web components based on servlets and Java Server Pages (JSP), and
Enterprise JavaBeans (EJB) components. These containers provide deployment and
runtime support for application components. They provide a federated view of the services
provided by the underlying application server for the application components.
Containers can run on existing systems; for example, web servers for the web containers;
application servers, TP monitors, and database systems for EJB containers. This enables
enterprises to leverage both the advantages of their existing systems and those of J2EE.
This chapter contains the following:
JAVA Enterprise Edition

Key features of the IMS TM Resource Adapter
Installing the IMS TM Resource Adapter
Callin request support
Callout request support
Copyright IBM Corp. 2013. All rights reserved.
211
8174ch05.fm
6.1 JAVA Enterprise Edition

Java Platform, Enterprise Edition or Java EE is Oracle's enterprise Java computing platform.
The platform provides an API and runtime environment for developing and running enterprise
software, including network and web services, and other large-scale, multi-tiered, scalable,
reliable, and secure network applications. Java EE extends the Java Platform, Standard
Edition. Besides Enterprise Edition (EE) we know Standard Edition (SE) and Micro Edition
(ME)
Enterprises can write, or rewrite, new applications using J2EE capabilities and can also
encapsulate parts of existing applications in Enterprise JavaBeans, Java Server Pages or
servlets. Enterprise applications access functions and data associated with applications
running on Enterprise Information Systems (EIS).
Application servers extend their containers and support connectivity to heterogeneous EISs.
Enterprise tools and Enterprise Application Integration (EAI) vendors add value by providing
tools and frameworks to simplify the EIS integration task. For enterprise application
integration, bi-directional connectivity between enterprise applications and EIS is essential.
The J2EE Connector architecture defines standard contracts that allow bi-directional
connectivity between enterprise applications and EISs. It also formalizes the relationships,
interactions, and the packaging of the integration layer, thus enabling enterprise application
integration.
The Java Runtime Environment (JRE) and Java Development Kit (JDK) are the actual files
downloaded and installed on a computer to run or develop Java programs.
6.1.1 Developing Java applications

The Java development tools (JDT) project provides the tool plug-ins that implement a Java
IDE supporting the development of any Java application, including Eclipse plug-ins. It adds a
Java project nature and Java perspective to the Eclipse Workbench as well as a number of
views, editors, wizards, builders, and code merging and refactoring tools. The JDT project
allows Eclipse to be a development environment for itself. The Java visual editor is a tool
which allows you to visually construct Graphical User Interfaces based on Swing, SWT or
Abstract Windows Toolkit (AWT). The Session Initiation Protocol (SIP) Tools Feature provides
a development environment for the creation of new SIP-based services. The feature
enhances the existing Java EE Platform, Enterprise Edition development perspective to allow
for the creation of SIP and converged HTTP/SIP applications. The enhanced Java EE
perspective also includes support for the Servlet ARchive (SAR) archive format and includes
a wizard for editing SIP deployment descriptors. You can bundle SAR archive files within a
Java EE application archive, just like other Java EE components.
Java EE 5 did already provide simplified packaging rules for enterprise applications:
212
Web applications us .WAR files

Resource adapters use .RAR files
Enterprise applications use .EAR files
The lib directory contains shared .JAR files
A .JAR file with Main-Class implies an application client
A .JAR file with @Stateless annotation implies an EJB application
Many simple applications no longer require deployment descriptors, including
EJB applications (.JAR files)
Web applications that use JSP technology only
Application clients
Enterprise applications (.EAR files)
8174ch05.fm
For additional information about Java EE, see the official specification:
Java EE 5: JSR 244: Java Platform, Enterprise Edition 5 (Java EE 5) Specification
Java EE 6: JSR 316: JavaTM Platform, Enterprise Edition 6 (Java EE 6) Specification
Java EE 7 JSR 342: JavaTM Platform, Enterprise Edition 7 (Java EE 7) Specification
A history of the mentioned Java Versions:
Java EE 5 (May 11, 2006)
Java EE 6 (Dec 10, 2009)
Java EE 7 (May 28, 2013
Here are some Java EE 7 Platform Highlights.The most important goal of the Java EE 7
platform is to simplify development by providing a common foundation for the various kinds of
components in the Java EE platform. Developers benefit from productivity improvements with
more annotations and less XML configuration, more Plain Old Java Objects (POJOs), and
simplified packaging. The Java EE 7 platform includes the following new features:
Batch Applications for the Java Platform

Concurrency Utilities for Java EE
Java API for JSON Processing (JSON-P)
Java API for WebSocket
Enables developers to deliver HTML5 dynamic scalable applications.
If you are a beginner with Java you would like to start with JUNO Eclipse Version The JDT
project provides the tool plug-ins that implement a Java IDE supporting the development of
any Java application, including Eclipse plug-ins. It adds a Java project nature and Java
perspective to the Eclipse Workbench as well as a number of views, editors, wizards,
builders, and code merging and refactoring tools. The JDT project allows Eclipse to be a
development environment for itself.
Web service development scenarios: Service flow projects

There are three possibilities to develop a application project. this are bottom-up,
meet-in-middle, and top-down development of web services in the context of developing a
comprehensive web service that is capable of collecting and processing data from multiple
IMS applications, or from other web services, or from both.
Service flow projects support the following development approaches:
Bottom-up development
You use a service flow project in a bottom-up approach when your objective is to create a
service from an existing application.
Meet-in-middle development
You use a service flow project in a meet-in-middle approach when you already have both the
WSDL file and the implementation component (application) and you need to create the
additional support code that maps between the two.
Top-down development
You use a service flow project in a top-down development approach when you already have
the definition of a particular web service specified in a web service definition file (WSDL
format) and you want to generate high-level language source files (in this case, COBOL
source files) containing: COBOL versions of the XML schema definitions that are specified in
the WSDL file for the inbound message and the outbound message of the web service; and
COBOL program modules that copy ("map") the contents of the COBOL versions of the
inbound message and outbound message to the XML schema definition versions of the
Chapter 6. JEE application technology
213
8174ch05.fm
inbound message and the outbound message, and vice versa.This application development
approaches are solved or imbedded into the rational development products or better in the
Eclipse IDE
After you have installed the Eclipse Workbench IDE you may start with the first Java projects
HelloWorld and HelloWorld SWT to find the distingtion between SWT and non SWT see
Figure 6-1. In the IDE you also find the Cheat sheets very useful.
Figure 6-1 HelloWorld
Java Editor
The Java Editor example Figure 6-2 on page 215demonstrates the standard features
available for custom text editors. It also shows how to register an editor for a file extension (in
this case .jav) and how to define a custom Document provider for use by that editor. This
example is only for demonstration purposes. Java editing support is provided by the Eclipse
Java Tooling.
What you can do with the sample

Browse the source code in the workspace.When ready, run the sample and follow instructions
in the help document. Later on, you can re-run the sample by pressing the Run icon on the
tool bar. If you place breakpoints in the code, you can debug it. Later on, you can debug the
sample by pressing the Debug icon on the tool bar.
214
8174ch05.fm
Figure 6-2 Java Editor Sample
In the Help section tryout the cheat sheets as you see in Figure 6-3.
Figure 6-3 cheat sheets

215
8174ch05.fm
Ok so far for the basics of Java Application development it can only be a short introduction
and overview since the topic would fill to many books. lets see what is in from the IMS side.
}
6.1.2 IBM Rational Developer for System z

IBM Rational Developer for System z consists of a mainframe system component and a
workstation client component see Figure 6-4 on page 216.
Remote system
The mainframe system component is also referred to as the remote system component. It is
the part of the product that is installed on the System z mainframe. The remote system
component is the System z mainframe to which you connect to access your data. This portion
of the product is installed into a z/OS logical partition (LPAR) by the site system programmer.
The remote system component provides the interface between the workstation client and
traditional development components, such as JES and the file system.
During setup, you create a connection between the workstation client and remote system
components. The remote system component provides transaction management system
functions to communicate with IMS and CICS. Problem determination tools, such as the IBM
Debug Tool are included.
Workstation client
The workstation client is the portion that is installed on a personal computer operating
environment. It must be installed on each developer's computer. Throughout the product
documentation, the term IBM Rational Developer for System z refers to the workstation
component. The client software can be installed on a Microsoft Windows operating system or
a Linux operating system. The two components communicate by using TCP/IP.
Figure 6-4 RDz architecture
216
8174ch05.fm
The user interface contains a set of development tools that support the development,
maintenance, and web service enablement of enterprise applications.
Access z/OS assets.
You can organize, allocate, manage, and edit z/OS data sets and tools.
Develop, maintain, compile, and assemble source files by using integrated
language-sensitive editors for
COBOL, PL/I, IBM High Level Assembler (HLASM), C/C++, Java, job control language
(JCL), basic mapping support (BMS), and Message Format Service (MFS).
You can access source directly from MVS data sets or through a number of source
control management (SCM) systems.
Manage and edit data, such as
Queued sequential access method (QSAM) or sequential data sets
Virtual Storage Access Method (VSAM) or indexed data sets
Relative and entry sequenced data sets
DB2 tables and views
Information Management System (IMS) databases
Access to your z/OS Job Entry Subsystem (JES) to submit
jobs and JES spool files to organize and manage batch jobs.
Access other tools such as wizards and declarative development tools that replace low-level
coding to create, deploy and test DB2 stored procedures, web services, and Service
Component Architecture (SCA); transform Unified Modeling Language (UML) models to
COBOL; and use Enterprise Generation Language (EGL) to develop web 2.0 and Java 2
Platform and Enterprise Edition (J2EE) applications.
IMS snippets categories in IBM Rational Developer for System z

IBM Rational Developer for System z supports IMS categories among the categories
in the Snippets view.
The categories for IMS snippets are as follows:
IMS Transaction Management for COBOL

IMS Database Management for COBOL
IMS DB System Services for COBOL
IMS TM System Services for COBOL
IMS Application Interface Masks for COBOL
IMS DL/I Function Codes for COBOL
Management and services categories

You can use the first four snippets categories to add IMS DL/I calls to your COBOL program.
Each snippet in these categories corresponds to an individual DL/I function. Invoking one of
these snippets brings ups a dialog that prompts you for details of the specific DL/I function
call. At the top of the dialog you specify the interface type to use in the DL/I call from the list of
interfaces compatible with the selected DL/I function call. The remaining fields correspond to
the parameters of the corresponding DL/I call, with the following exceptions:
When you use the language-independent interface (CEETDLI), you may need to fill in the
Type of Control Block field to specify whether you are using an AIB parameter.
The CIMS, DPSB, GMSG, and INQY snippets have a field for you to enter in the
subfunction code.
217
8174ch05.fm
When you use these snippets in conjunction with the System z LPEX Editor or COBOL Editor,
references to nested fields of the AIB or PCB control blocks in the snippet code are replaced
automatically with the actual fields present in the referenced AIB or control block. For
example, when generating the line of code MOVE LENGTH OF AIB TO AIBRLEN OF AIB, the
snippet generator looks up the field defined at offset 8 of the AIB control block selected in the
dialog and uses that as the name for the AIBRLEN field. If the AIB block cannot be parsed out
of the code, a default value for the field is used.
When generating the DL/I call, the snippet code generator tries to look up a level 77 field
whose VALUE clause equals the DL/I function and use that in the call. For example, when
creating the code for the GHN snippet, the generator parses the code and may find the
declaration in Example 6-1.
Example 6-1 GET-HOLD-NEXT snippet
77
GET-HOLD-NEXT
PICTURE X(4)
VALUE 'GHN '.
At that point, GET-HOLD-NEXT is substituted into the function call. If no match is found, the
snippet name (GHN in this case) is used in the function call.
These snippets add the DL/I function names as level 77 data structures.
IMS template generation

IMS PL/I top-down MPP template generation features separation of protocol-level logic
from user-written business logic. The protocol-level logic is generated to be used as-is and
effectively shields the user-written business logic from the details of interacting with the IMS
Message Queue and the IRZPWSIO API. Enhanced separation also allows for easier
integration of existing business logic and increases the portability of new code for any future
migrations.
Using the enhanced templates, IMS application programmers may immediately focus on
writing or integrating business logic to process or create the input, output, or fault structures
respective to each operation implemented by the MPP. The following Figure 6-5 illustrates
how the separation of protocol-level logic from business logic is implemented in the enhanced
templates.
218
8174ch05.fm
Figure 6-5 Enhanced Provider MPP template overview
As shown in the above figure, protocol-level logic exists in code-complete procedures named
OperationNameHandler that are dedicated to handling interactions with the IMS Message
Queue and IRZPWSIO APIs on behalf of the respective user-written business logic in
procedures named OperationNameImpl. All of the user-written business logic must be
entered into the OperationNameImpl procedures. At execution time, OperationNameImpl
procedures are invoked by their respective OperationNameHandler procedure.
Appendix A.9, Enhanced Provider MPP template sample on page 437 shows an example of
an enhanced template for a WSDL file that includes three operations:
getteam_1_0
setteam_1_0
ping_1_0
The operations getteam_1_0 and setteam_1_0 may issue a SOAP fault.
6.1.3 The IMS TM Resource Adapter

The IBM IMS TM Resource Adapter (previously known as IMS Connector for Java (IC4J)) is
used by Java applications, Java Platform, Enterprise Edition (Java EE) applications, or Web
Services to access IMS transactions that are running on host IMS systems.
It is also used by IMS applications that run in IMS dependent regions to make asynchronous
and synchronous (supported through IMS Version 10 maintenance and Version 11) callout
requests to external Web Services.
219
8174ch05.fm
In addition, the IMS TM Resource Adapter implements the J2C Common Client Interface
(CCI), which is a programming interface that allows your application to communicate with the
IMS Transaction Manager.
The IMS TM Resource Adapter is used with a Java EE server, such as IBM WebSphere
Application Server, when Java applications (Java EE artifacts in the WebSphere Application
Server) access an IMS transaction that is running on a host IMS system. The IMS TM
Resource Adapter also enables an IMS application to act as a client to invoke applications in
a Java EE server.
Submitting commands to IMS

Although the IMS TM resource adapter is intended primarily for you to run transactions on a
host IMS system through a Java EE application, you can also issue IMS commands that
are supported by IMS OTMA from your Java applications.
The IMS TM resource adapter uses the host product, IMS Connect, to access IMS. IMS
Connect uses the cross-system coupling facility (XCF) to access IMS through OTMA.
Only certain IMS commands can to be submitted through the IMS OTMA interface. Because
the IMS TM resource adapter accesses IMS through OTMA, IMS commands supported by
OTMA are the only commands that can be submitted to IMS by an application that uses the
IMS TM resource adapter.
The output of an IMS command is a message that consists of one or more segments of data.
The output of some IMS commands is a DFS message. For example, the output of most
/START commands is usually the message DFS058I START COMMAND COMPLETED.
Other IMS commands do not return DFS messages. For example, /DISPLAY commands
return multiple segments of data representing lines of display information. To treat both types
of output the same, you must set the imsRequestType property of the IMSInteractionSpec
class to 2 (IMS_REQUEST_TYPE_IMS_COMMAND). This value indicates to the IMS TM
resource adapter that the interaction is an IMS command, and to treat DFS messages as
normal output and not as Java exceptions.
Commands that can be submitted to IMS by an application that uses the IMS TM resource
adapter can be found in the IMS commands reference.
To have the full benefit of the adapter code, the adapter must be installed in the WebSphere
Application Server and used from Java EE artifacts, but RYO Java client programs can also
utilize the code.
6.2 Key features of the IMS TM Resource Adapter

Support is based on Sun's Java EE Connector Architecture (JCA) 1.5 for the IMS TM
Resource Adapter version levels of 10, 11 and 12 provides the following support:
Supports development of applications that can submit transactions to IMS Transaction
Manager through IMS Connect.
Provides tooling support for development of Java EE applications, Web Services, and
business processes that access IMS transactions in various Rational and WebSphere
integrated development environments.
Provides a JCA Resource Adapter (RAR) for deployment to the WebSphere Application
Server and WebSphere Process Server (WPS) runtime environment on many platforms
including z/OS and Linux on System z.
220
8174ch05.fm
Supports connection pooling and reuse.

Supports global transaction processing and two-phase commit.
Supports component-managed and container-managed security, including support for
run-as thread identity.
Supports SSL communication between the IMS TM Resource Adapter and IMS Connect,
including support for SSL null encryption.
Supports most types of interactions with IMS application programs including the retrieval
of asynchronous output messages.
Supports for IMS applications to invoke Java EE applications asynchronously, and
synchronously in callout mode.
IMS Transaction Manager Resource Adapter (TMRA) components

There are two key components that make up TMRA:
A runtime component that needs to be deployed on the WebSphere Application Server. A
deployed TM resource adapter in WebSphere Application Server fulfills all rules of the
JCA 1.5 contract.
A development component that lets you create your application by using an integrated
development environment (IDE), such as IBM Rational Application Developer for
WebSphere Software, IBM Rational Software Architect, IBM WebSphere Integration
Developer, and IBM WebSphere Transformation Extender, as part of the optional J2C
feature.
The J2C wizards in these IDEs enables you to create IMS connector code to be used from
Enterprise JavaBeans (EJB) components, Web Services, or from standalone programs.
Supported platforms
The IMS TMRA runtime component supports WebSphere Application Server on the following
platforms:
AIX
HP-UX
Linux
Linux for System z
Solaris
Windows
z/OS and OS/390
6.2.1 Features introduced in Version 10.2

IMS TM Resource Adapter Version 10.2 provides the following new features:
Support for the invocation of IMS applications by using complex data types from
distributed platforms
With the WebSphere Transformation Extender Design Studio, you can build applications
that send complex data formats to and from IMS applications. WebSphere Transformation
Extender is a transaction-oriented, data integration solution that automates the
transformation of high-volume, complex transactions across the enterprise. You can use
its Type Designer to generate a type tree from your COBOL copybook and then specify
rules for transforming and routing the data in the Map Designer.
Support for reestablishing any stale connection in a connection pool when the connection
encounters a communication failure. Using this enhancement you can recycle IMS
221
8174ch05.fm
Connect during system maintenance without resubmitting any IMS TM Resource Adapter
interactions from the client application.
IMS MFS SOA support
IMS MFS SOA support is integrated with the Enterprise Metadata Discovery (EMD)
framework in Rational Application Developer Version 7.5 or later to transform existing
MFS-based IMS applications into J2C Java beans and J2C Java Data Binding classes.
After you create a J2C Java bean, you can create Java EE artifacts, such as JSPs, EJBs,
or Web Services, to deploy the generated J2C Java bean.
IMS MFS SOA support is supported in the following WebSphere Application Server V6.1
runtime environments:
Windows
z/OS
Rerouting undeliverable output messages to a specified destination for commit mode 0,
SYNC_SEND interactions on sharable persistent sockets
The reroute function allows undeliverable output messages to be rerouted to a specified
destination. Previously, the reroute function was supported for only commit mode 0 (CM0),
SYNC_SEND_RECEIVE interactions on sharable persistent sockets. This enhancement
supports the reroute function on CM0, SYNC_SEND interactions on sharable persistent
sockets.
6.2.2 Features introduced in Version 11

IMS TM Resource Adapter Version 11 provides the following new features:
Support for WebSphere Transformation Extender:
WebSphere Transformation Extender (WTX) is the new name for the WebSphere
DataStage TX (formerly Ascential DataStage TX) product. WTX performs
transformation and routing of data from source systems to target systems in batch and
real-time environments. The sources can include files, relational databases, MOMs
(message-oriented middleware), packaged applications, or other external sources. After
retrieving the data from its sources, the WebSphere Transformation Extender product
transforms it and routes it to any number of targets where it is needed, providing the
appropriate content and format for each target system. Figure 6-6 on page 223 positions
WTX with respect to IMS TMRA.
222
8174ch05.fm
Figure 6-6 WTX support
The software requirements for WTX are:

IMS and IMS Connect Version 10 or later
IMS TM Resource Adapter Version 10.2 (APAR PK64663 provides this support for IMS
TMRA V10.1.1)
WTX 8.2.0.2
IMS TMRA socket reconnect support
Socket reconnect support provides a retry and reconnect capability to re-establish a
connection when encountering communication failures in sending / receiving and request /
response through IMS Connect from a WebSphere Application Server, without user
intervention. This retry function is implemented for Sync Level Confirm interactions to
avoid duplicate interactions.
During system maintenance previously, customers would recycle IMS Connect, which
caused WebSphere Application Server applications to fail due to persistent connections
and connection pooling. This solution avoids unnecessary errors and quickly
re-establishes connections, thus enhancing IMS availability and operational
characteristics to allow these applications to seamlessly recover from connection errors.
IMS TMRA send only reroute support
Send only reroute support reroutes current Sync-Send (Send-Only) interactions for CM0.
With the reroute flag set to True and the reroute TPIPE name specified, any IOPCB output
message resulting from the Send-Only transaction is queued to the reroute TPIPE.
223
8174ch05.fm
Message Format Services (MFS) Business Process Execution Language (BPEL) support
MFS BPEL support for the WebSphere Integration Developer assists integration
developers with business-to-business transformation. This support creates Web
Services/EJB/JSPs out of existing MFS-based IMS applications, and provides support for
Service Component Architecture (SCA), Enterprise Metadata Discovery (EMD) 1.1, and
BPEL. It includes a GUI wizard that allows you to parse the MFS source files and generate
the service definition and artifacts. The generated application can be deployed to run on
WebSphere Process Server for business orchestration and choreography.
Synchronous Callout support
Synchronous callout (also available through an IMS Version 10 SPE) for IMS TMRA
manages the correlation of a callout request. This enables IMS applications to invoke
external applications and synchronously receive a response in the same IMS transaction
instance. External applications and servers include Java EE applications (EJB/MDB).
6.2.3 New features in IMS TM Resource Adapter Version 12

Version 12 adds the support for WebSphere Application Server Version 8 and its resource
workload routing function, the support for multiple data stores per IMS activation
specification for callout messages, and takes advantage of various enhancements in IMS.
Support for WebSphere Application Server Version 8 and its resource

workload routing function
WebSphere Application Server Version 8 introduces a new resource workload routing
function that offers data source and connection factory failover and subsequent failback from
a predefined alternate or backup resource. This function enables applications to easily
recover from resource outages, such as database failures, without having to embed alternate
resource and configuration information.
You can specify two connection factories for the IMS TM resource adapter, and then specify
the second connection factory to be the alternate resource for the first connection factory.
Support for multiple data stores per IMS activation specification for
callout messages
This enhancement enables a single message-driven bean (MDB) to pull callout messages
from more than one IMS data store. For a shared-queues environment, this enhancement
removes the requirement to duplicate the MDB application to connect to each IMS member in
the shared queue.
Data store connection failure recovery for callout messages

When the backend IMS is not available, in addition to the attempt to reconnect to IMS
Connect, the resource adapter will also attempt to reconnect to the IMS data store. A new -1
value is added to the IMSActivationSpec retryLimit property to support indefinite retry for
connection to IMS Connect and the IMS data store. When the retry is successful and the
connection is restored, informational messages are provided to indicate the successful
re-connection.
IMSActivationSpec property configuration for message-driven beans

The values of the properties of the IMSActivationSpec object describe the inbound
communication from IMS to be used by message-driven beans.
224
8174ch05.fm
You must configure an instance of the IMSActivationSpec object when you deploy a
message-drive bean in order for the IMS TM resource adapter to communicate with IMS
Connect for retrieving and responding to synchronous callout messages.
The following Table 6-1 describes the properties for the IMSActivationSpec object, the
implementation of the J2C activation specification in IMS TM resource adapter. The values for
these properties are to be specified and configured by using the administrative console in
WebSphere Application Server.
Table 6-1 Properties for the IMSActivationSpec object
Properties
Description
dataStoreName
IMS data store name. The name must match the ID parameter of the Datastore statement
that is specified in the IMS Connect configuration member when IMS Connect is installed. It
also serves as the XCF member name for IMS during cross-system coupling facility (XCF)
communications between IMS Connect and OTMA.
With Version 12 and later, the data store name can be a comma-separated list of data store
names, enabling one instance of the IMSActivationSpec class to pull callout messages from
more than one IMS data store.
groupName
The security authorization facility (SAF) group name.
hostName
IMS Connect host name.
password
SAF password
portNumber
IMS Connect port number
queueNames
A comma-delimited list of IMS OTMA tpipe names for the callout (synchronous or
asynchronous) messages. Queue names must be 1 to 8 alphanumeric characters (A-Z, 0-9,
@, #, $).
retryInterval
The time delay in milliseconds before the IMS TM resource adapter tries to check on the
availability of the data store.
retryLimit
The maximum number of times the IMS TM resource adapter will attempt to reconnect to IMS
Connect if a connection is lost due to IMS Connect or IMS data store availability issues.
For Version 10.5.1, Version 11.3.1, and Version 12 and later, when the retryLimit value is set
to -1, the IMS TM resource adapter will retry indefinitely to reconnect to IMS Connect if the
backend IMS Connect or IMS data store is restarted.
SSLEnabled
Instructs the IMS TM resource adapter to create a Secure Sockets Layer (SSL) socket
connection to IMS Connect by using the specified host name and port number in the
IMSActivationSpec object. This property is valid for TCP/IP connections only.
SSLEncryptionType
Specifies the SSL encryption type. Valid values are strong and week.
SSLKeyStoreName
The name, including the full file path, of the keystore for TCP/IP SSL communications.
Private keys and their associated public key certificates are stored in password-protected
databases called keystores. Trusted certificates can also be stored in the keystore, and the
truststore property can either be empty or could point to the keystore file. An example of a
keystore name is c:\keystore\MyKeystore.ks. The file can have other file extensions.
SSLKeyStorePassword
The password for the keystore for TCP/IP SSL communications.
SSLTrustStoreName
The name, including the full path, of the keystore file that contains security credentials
(certificates) for TCP/IP SSL communications. A value for the SSLTrustStoreName property
is not mandatory if a keystore is used. A truststore file is a key database file that contains
public keys or certificates. Private keys can also be stored in the truststore, and the keystore
property can either be empty or could point to the truststore file. An example of a truststore
name is c:\keystore\MyTruststore.ks. The file can have other file extensions.
SSLTrustStorePassword
The password for the truststore for TCP/IP SSL communications.
225
8174ch05.fm
Properties
Description
userName
SAF user name.
Properties in the J2C activation specification that are not listed in the Table 6-1 are not
supported by the IMS TM resource adapter.
Support for IMS V12 OTMA DFS2082 messages for commit-then-send

CM0 transactions
With this IMS V12 enhancement, for CM0 transactions, if the IMS application does not reply
to the IOPCB or complete a message switch to another transaction, OTMA issues a DFS2082
message to the client to indicate the transaction terminated with no reply.
This enhancement enables you to convert send-then-commit (CM1) transactions into CM0
transactions without having to modify your applications.
Send/receive programming model

Use the send/receive programming model to run an IMS response mode transaction.
To run a transaction in IMS, a Java application executes a SYNC_SEND_RECEIVE
interaction. In your application, provide the following values for the IMSInteractionSpec object
that is used by the execute method of the Interaction object.
A value of SYNC_SEND_RECEIVE for the interactionVerb property
A value of 0 or 1 for the commitMode property
However, the SYNC_SEND_RECEIVE interaction processing is different for shareable and
dedicated persistent socket connections. Depending on the type of socket connections, the
processing model is different in either a normal processing of the transaction, or when an
error or an execution timeout occurs.
With IMS TM Resource Adapter Version 12 and later, if you convert an IMS Version 12
send-then-commit (CM1) application that expects a response to a commit-then-send (CM0)
application that does not, set the IMSInteractionSpec CM0Response property to true. When
this property is set for a CM0 transaction, if the IMS application does not reply to the IOPCB
or complete a message switch to another transaction, IMS OTMA issues a DFS2082
message to the client, regardless of the transaction response mode.
Shareable persistent socket processing model

Shareable persistent socket connections are connections that can be used for commit mode
1 and commit mode 0 interactions. The following scenarios describe the
SYNC_SEND_RECEIVE interaction on a shareable persistent socket during normal
processing, error processing, and execution timeout.
Normal processing scenario

The IMS TM resource adapter, with the application server, obtains either an available
connection from the connection pool or creates a new connection. The IMS TM resource
adapter, as part of initializing a new connection, generates a client ID for the connection. The
generated client ID identifies the socket connection, and for commit mode 0 interactions, the
tpipe and associated OTMA asynchronous hold queue.
The IMS TM resource adapter ensures that a socket is associated with the connection and
sends the request with input data to IMS Connect by using that socket. IMS Connect then
sends the message to IMS, where IMS runs the transaction and returns the output message.
226
8174ch05.fm
For commit mode 0 interactions, when it receives the output message, the IMS TM resource
adapter sends an ACK message to IMS, which signals IMS to discard the output from the IMS
queue. When the client application closes the connection or terminates, the connection is
returned to the connection pool for reuse by other commit mode 0 or commit mode 1
interactions.
Error processing scenario

All errors result in a resource exception being thrown to the client application. In addition,
some errors result in the socket being disconnected by IMS Connect. For commit mode 0
interactions, an exception means that the output message cannot be delivered to the client
application. However, following the exceptions, undelivered output messages for commit
mode 0 interactions on shareable persistent socket connections can be retrieved if the
SYNC_SEND_RECEIVE interaction specifies that undelivered output is to be rerouted to a
specific destination. To have an undelivered output message rerouted to a specific
destination, the following additional properties must be specified in the IMSInteractionSpec
object that is passed on the SYNC_SEND_RECEIVE interaction:
Set the purgeAsyncOutput property to false so that undelivered output is not purged.
Set the reRoute property to true, and specify a reroute destination in the RouteName
property.
To retrieve undelivered output from a reroute destination, a separate client application issues
a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT or
SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction on a dedicated persistent
socket connection. The client application provides the reroute destination as the client ID of
the interaction.
Alternatively, to retrieve undelivered output from a reroute destination, a separate client
application issues a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, or
SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction on a shareable persistent
socket connection by specifying the alternate client ID. Using the alternate client ID, a client
application can retrieve undelivered asynchronous output messages from any tpipe.
The default value of the purgeAsyncOutput property is true. When the value of the
purgeAsyncOutput property is true, the following output messages are purged:
Undelivered output message inserted to the I/O Program Communications Block (I/O
PCB) by the primary IMS application program
Output messages inserted to the I/O PCB by secondary IMS application programs invoked
by program-to-program switches
When the purgeAsyncOutput property is set to false, the reroute destination must be
specified.
Execution timeout scenario

If an execution timeout occurs, the socket connection remains open but the output message is
not delivered to the client application. However, following an execution timeout exception,
undelivered output messages for commit mode 0 interactions on shareable persistent socket
connections can be retrieved in either of the following two ways:
The same client application that issued the SYNC_SEND_RECEIVE interaction can issue
a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT or
SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction.
227
8174ch05.fm
The undelivered output message can be rerouted to a specific destination as described in the
error processing scenario.
When the client application closes the connection or terminates, the connection is returned to
the connection pool so it can be reused by other commit mode 0 or commit mode 1
interactions.
Support for IMS Version 12 RACF return codes

In IMS V12, if a RACF security failure occurs, IMS Connect includes a 2-byte return code
from the RACF RACROUTE REQUEST=VERIFY command. This version of the IMS TM
resource adapter is enhanced to take advantage of the enhancement so the RACF security
failure reason code is available to IMS TM resource adapter to assist troubleshooting.
WebSphere Application Server Version 8 resource workload routing:

WebSphere Application Server V8 information center
6.3 Installing the IMS TM Resource Adapter

The latest version of the TM Resource Adapter is at:
http://www.ibm.com/software/data/ims/ims/components/tm-resource-adapter.html
Restriction: Synchronous callout support requires IMS TM Resource Adapter 11, 10.3
Documentation is available from IMS TM Resource Adapter User's Guide and Reference,
SC19-1211-02.
Use the WebSphere Application Server administrative console to deploy the IMS TM
resource adapter RAR file.
To access the administrative console see Figure 6-7 on page 229:
1. Start the WebSphere Application Server.
2. In the Servers view, right-click the server, and then select Administration > Run
administrative console. The Administrative Client logon window opens in the Web Browser
view.
3. If the server is secured, specify the user ID and password to access the administration
console.
4. Click the Log in button.
Note: With RDz there is no WAS installed. You need to install a WAS which comes with the
RAD product first before you install RDz.
228
8174ch05.fm
Figure 6-7 Run Administrative Console
Important steps you need to consider if installing the TM Resource Adapter are:
1. If you are installing the IMS TM resource adapter archive (RAR) on a generic application
server, additional class libraries might be needed for use with the IMS TM resource
adapter. For class libraries that are not included in the IMS TM resource adapter
installation archive, contact your product representative for the development environment
of your choice for information regarding the licensing and location of any needed JAR files.
2. When you use the Install RAR dialog to install a RAR file, the scope you define on the
Resource Adapters page has no effect on where the RAR file is installed. You can install
RAR files only at the node level, which you specify on the Install RAR page. To set the
scope of an RAR file to a specific cluster, or server, after you install the RAR file at each
node level, create a copy of the RAR file with the appropriate cluster or server scope
You must have installed the IMS TM resource adapter RAR to a file system that is accessible
to your WebSphere Application Server.
229
8174ch05.fm
Figure 6-8 Resource adapter configuration in WebSphere Application Server
Start the WebSphere Application Server and log in to the administrative console to deploy the
RAR on a WebSphere Application Server:
1. In the navigation pane in the administrative console (also known as the Integrated
Solutions Console), click Resources > Resource Adapters > Resource adapters.
2. If a RAR that you no longer want to use is already installed, delete it first. Stop and restart
the WebSphere Application Server. Repeat the previous step to return to the resource
adapter configuration page.
3. In the content pane, click Install RAR. You might need to scroll down in the pane to locate
the button. The Install RAR File page displays.
4. Click Local file system or Remote file system, depending on the location of the RAR file.
5. If you choose Local file system, click Browser to locate and specify the IMS TM resource
adapter RAR file that is installed, for example,
install_path/IBM/IMS/ICOxx/Vxxxx/JCA15/imsxxxx.rar.
6. Click Next.
7. On the Configuration page, type a name for the RAR, for example, imstmravxxxx. Click
OK.
8. Optionally, create a copy of the RAR file with a different scope level. After you install the
RAR file at each node level, you can create another copy of the file that has a specific
server or cluster as the scope for that file. See the Installing a resource adapter archive
topic in WebSphere Application Server information center.
9. To save your results in the master configuration, click Save at the top of the panel.
6.4 Callin request support

Support for external clients to request services from IMS was available for many years. This
functionality can be requested from all Java EE artifacts, Servlets, EJBs, Business
Processes, and Mediation Modules. The non conversational transaction type is the most
230
8174ch05.fm
simple and most frequently used. Conversational transactional flow is also supported, but
does not always fit well in SOA scenarios.
When a Java application submits a transaction request to IMS through IMS TMRA, IMS
Connect sends the transaction request to OTMA by using cross-system coupling facility
(XCF) communications, and the transaction runs in an IMS dependent region. The response
is returned to the Java application using the same path.
If access is engaged through a deployed TM Resource Adapter in the WebSphere Application
Server Java EE container, the Common Client Interface (CCI) contract is honored. Figure 6-9
on page 231 shows the container component contract with respect to the other components
within the container.
Figure 6-9 Common Client Interface contract
The CCI contract is responsible for three processing components:

Connection management (including connection pooling). This implies that to establish the
connection with IMS, a Managed Connection Factory is used.
Security management through the passing of UserIDs.
Transaction management through the control over processing units of work.
The interaction with IMS Connect and IMS is based on four Java objects:
Connection
This object represents the connection. It is obtained from the Connection Factory that
resides in a WebSphere Application Server. Figure 6-10 on page 232 presents the
properties that can be defined in the Connection Factory
231
8174ch05.fm
Figure 6-10 Custom properties of IMS Connection Factory
Define the factory with the WebSphere Application Server Administration Console, and
label it with a JNDIName for look-up.
Note: The factory can also be instantiated at runtime if no container (WebSphere
Application Server) is available, which is also true for Java Batch, stand alone
programs.
In that case, the factory must be instantiated at runtime.
ConnectionSpec
This object provides some additional connection properties for the connection, mainly
related to security and identification. See Figure 6-11 on page 233 for details.
Interaction
This object is the coordinator of the interaction executed with IMS. Its execute method
triggers the interaction.
InteractionSpec
This object specifies the details of the interaction. See Figure 6-11 on page 233 for details.
232
8174ch05.fm
Figure 6-11 ConnectionSpec and InteractionSpec
The InteractionVerb is probably the most important parameter, which indicates what action
IMS Connect must take. We remind you that the TM Resource client is always the contacting
partner, even if IMS must send output.
The available verbs are:
SYNC_SEND (value 0)
Sends a request to IMS when a response is not expected, in another words, perform a
send only interaction.
SYNC_SEND_RECEIVE (value 1)
Used for the single iteration of a non-conversational IMS transaction and for each iteration
of a conversational IMS transaction.
Note: SYNC_RECEIVE (value 2) is currently not supported by IMS Connector for Java.
SYNC_END_CONVERSATION (value 3)
Forces the end of an IMS conversational transaction.
SYNC_RECEIVE_ASYNCOUTPUT (value 4)
Retrieves asynchronous output messages. With this type of interaction, the Java client can
only receive a single message. If there are no messages in the IMS OTMA Asynchronous
Queue for the clientID when the request is made, no further attempts are made to retrieve
the message. No message is returned and a time-out occurs after the length of time
specified in the executionTimeout property of the SYNC_RECEIVE_ASYNCOUTPUT
interaction.
233
8174ch05.fm
SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT (value 5)
Queue for the clientID when the request is made, no further attempts are made to retrieve
the message. No message is returned and a time-out occurs after the length of time that is
specified in the executionTimeout property of the
SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT interaction.
SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT (value 6)
Queue for the clientID when the request is made, IMS Connect waits for OTMA to return a
message. IMS Connect waits the length of time specified in the executionTimeout property
of the SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction before returning an
exception.
The Generated Client ID function: In IMS Version11, the TM Resource Adapter is
enhanced to take advantage of a new function in IMS Connect: the Generated Client ID
function, which ensures the uniqueness of each socket.
This enhancement eliminates the requirement for IMS TM Resource Adapter to use
different IMS Connect ports for instances of distributed WebSphere Application Server.
IMS Connect can use the Generated Client ID function to ensure the uniqueness of each
socket and allow all instances of WebSphere Application Server to specify the same IMS
Connect TCP/IP port.
6.5 Callout request support

Although we call this pattern callout, in reality it starts with a callin invitation
(SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT) from the TM Resource Adapter
partner, a Java EE application.
Asynchronous callout is already available with IMS Version 10. IMS Version 11 and a SPE on
IMS Version 10 (APAR PK74168) add the synchronous capability. Synchronous callout
support requires the latest fix pack on WebSphere Application Server v6.1.
At least two data flows exist in a callout pattern with the WebSphere Application Server. A
third inbound data flow to TMRA is required if IMS expects a response:
1. SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT
2. Receive callout request
3. SYNC_SEND (send response) optional
Figure 6-12 on page 235 illustrates this callout data flow.
234
8174ch05.fm
Figure 6-12 Callout data flow
OTMA destination routing descriptors are used by customers who implement this callout
function or who implement message switches from OTMA to non-OTMA destinations and do
not want to code the OTMA routing exits (DFSYPRX0 and DFSYDRU0). If an OTMA
descriptor is used with the callout function, Destination Routing Descriptors in the DFSYDTx
member of IMS.PROCLIB must be created specifying the appropriate properties for the
callout destination. The properties depend on the type of callout.
We distinguish two types of callout requests:
Asynchronous: The request is sent, but the sending IMS program does not wait for the
response, which is returned as a separate IMS transaction invocation if necessary. This
happens through an ISRT call to an ALTPCB destination.
Synchronous: The sending IMS program waits for the response from the send / receive
call flow. Also a time-out value needs to be provided. The request is performed through the
new ICAL call function to an alternate destination, which is described through an OTMA
descriptor.
A new optional keyword SYNTIMER is introduced to the OTMA descriptor so that the user
can specify a time value to wait in hundredths of seconds, which can range from 1 to
900000, for synchronous call process to complete. See Example 6-2.
Example 6-2 OTMA descriptor keyword SYNTIMER
D WASDEST1 TYPE=IMSCON TMEMBER=HWS1 TPIPE=WASTP1 SYNTIMER=5000
6.5.1 Destinations for callouts through TM Resource Adapter

Two types of Enterprise Java Beans (EJBs) can be solicited for serving the callout request.
They take the initiative to pull the callout message from an hold queue with a
SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction.
The types of EJB that we can use are:
StateLess Session Bean (SLSB)
Stateless Session Beans are distributed objects, server-side Java EE components, that do
not have state associated with them thus allowing concurrent access to the bean.
Stateless session EJBs display the following behavior:
Provide a relatively short lived single use service.
Do not maintain state on behalf of the client and do not survive EJB server crashes.
235
8174ch05.fm
Any two instances of the same stateless session EJB type are always identical, and
each instance can be shared by multiple clients.
For more information about this subject refer to the WebSphere InfoCenter at URL:
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.
websphere.base.doc/info/welcome_base.html
Message Driven Bean (MDB)
Message-driven beans (MDBs) are stateless, server-side Java EE components for
processing asynchronous messages. A MDB bean is an asynchronous bean activated by
message deliveries and can consume and process messages concurrently.
A MDB can be used as a listener to receive callout requests that are retrieved by IMS
TMRA. Then the MDB can route the message to the appropriate EJB or other application
within the WebSphere Application Server for further processing.
6.5.2 Asynchronous callout requests

IMS application programs that are running in IMS-dependent regions can send outbound
messages to request services from a WebSphere Application Server Enterprise Java Bean.
The request for services or data is referred to as a callout request. When an IMS application
program makes a callout request, IMS can be viewed as a client in a client-server relationship
where the server is the external application to which IMS is making the callout request. If the
request is treated as an asynchronous request, there will be no answer (send only), or a
response is sent back as a new transaction.
An IMS configuration that supports callout includes these functions and components:
The IMS application program that issues the callout request and If necessary, the IMS
application program that processes the callout response.
Optionally, an IMS database to store the data necessary to correlate the callout response
to the initiating IMS client.
An OTMA instance containing:
Asynchronous hold queue

OTMA ALTPCB destination descriptor
OTMA routing exits
OTMA asynchronous hold queue security
Optionally an OTMA Resume TPIPE Security exit routine (DFSYRTUX)
IMS Connect instance

WebSphere Application Server:
IMS TM Resource Adapter running on WebSphere Application Server
WebSphere Application Server EJBs
The external application program
Optionally the use of RACF
Each Java application using IMS TMRA that processes a callout request externally can be
configured to "listen" to the OTMA asynchronous hold queue by issuing a looping RESUME
TPIPE call with an appropriate wait time. The Java application program might also be
designed to preserve the correlation data and send it back with the callout response.
OTMA routing of callout requests is required to route the ISRT alternate_pcb call to the
appropriate tpipe. The OTMA routing is performed by the OTMA ALTPCB destination
descriptor, or the OTMA Destination Resolution exit routine (DFSYPRX0) and the OTMA User
Data Formatting exit routine (DFSYDRU0).
236
8174ch05.fm
In the WebSphere Application Server, the listening Java (EJB) code can be a Stateless
Session Bean (SLSB) or the listener of a Message Driven Bean (MDB).
Securing the retrieval of asynchronous output and callout messages

The asynchronous output and the asynchronous callout programming models of the IMS TM
Resource Adapter allow you to retrieve asynchronous output or callout request messages
from the hold queue. To ensure that only an authorized user can retrieve an asynchronous
output message or a callout request from the hold queue, you can optionally specify the user
ID, together with the tpipe name that is contained in the
SYNC_RECEIVE_ASYNCOUTPUT_* command message. Authorization is performed by
IMS OTMA when the message is retrieved from the hold queue.
The user ID and password information can be specified in the IMSConnectionSpec object, in
the authentication alias that the IMS ConnectionFactory uses, or the applications deployment
descriptor. For more information about OTMA security, see the Specifying OTMA security
and Securing messages on the asynchronous hold queue topics in IMS Version 10
Communications and Connections Guide, SC18-9703.
Asynchronous callout to a SLSB

Figure 6-13 shows the interaction with a Stateless Session EJB. Because the activity that is
associated with the setup within the SLSB and IMS application are not directly tied together,
we begin the flow not with the initiating Client, but within the SLSB running in WebSphere
Application Server. This is opposite to the examples in 5.6, Synchronous Callout with IMS
SOAP Gateway on page 201. If a callout request did not arrive to the waiting SLSB, it waits
for the next available callout message or until a time-out occurs.
Figure 6-13 Message flow of Asynchronous Callout to SLSB using IMS TM Resource Adapter
The message flow of asynchronous callout to SLSB using the IMS TM Resource Adapter is:
237
8174ch05.fm
1. In preparation for the flow, the EJB application in a WebSphere Application Server starts
and obtains a shareable persistent connection to IMS Connect through the IMS TM
Resource Adapter. It issues a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT
interaction, specifying the tpipe name as the value for the alternate client ID, and sets a
large time-out value. TMRA in turn issues a RESUME TPIPE request to the tpipe and
waits for the callout request from IMS Connect.
2. An initiating client, such as a terminal or an IMS Connect or OTMA client, causes an IMS
application to start.
3. The IMS application issues an ISRT ALTPCB call to an OTMA destination routing
descriptor, which contains the destination tpipe name. The callout request message is
queued on this tpipe.
4. As soon as the callout request is available in the tpipe, IMS Connect delivers the callout
message to TMRA.
5. TMRA receives the callout request message and presents the callout request to the EJB.
6. The EJB processes the callout request.
7. If the EJB has response data to be sent back to IMS, the EJB issues a normal IMS
send_only transaction request through IMS TMRA and IMS Connect to IMS.
8. A second IMS application is scheduled to handle the asynchronous reply.
To prepare a Java application for inbound requests from an IMS application program, you
must specify the appropriate interaction verb and the asynchronous hold queue name in the
Java application. Also, specify a time-out value.
Specify the asynchronous hold queue name.
InteractionSpec.setAltClientID(calloutQueueName);
Set the interactionVerb property to SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT.
interactionSpec.setInteractionVerb(com.ibm.connector2.ims.ico.
IMSInteractionSpec.SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT);
Specify an execution time-out value (in milliseconds) that you want to wait for a callout
request message in the hold queue.
interactionSpec.setExecutionTimeout(3600000);
In this example, we specify a large execution time-out value. A large execution time-out value
helps to minimize the looping required in a callout EJB when there might be long periods of
time when no callout requests occur.
Sample code related to the asynchronous callout to a SLSB can be found in ICAL
Synchronous Program Switch COBOL program on page 416.
Asynchronous callout to an MDB

Message Driven Beans (MDB) allow your application to asynchronously receive messages
delivered to a JMS destination. Figure 6-14 on page 239 presents the interaction with a
Message Driven Bean.
238
8174ch05.fm
Figure 6-14 Message flow of asynchronous callout to MDB using TMRA
The message flow of an asynchronous callout to MDB using TMRA is:

1. When the Java EE application containing the deployed MDB is started in the WebSphere
Application Server through the ActivationSpec and the underlaying listening software, a
shareable persistent connection to IMS Connect through TMRA is obtained. The Java EE
application issues a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction,
which specifies the tpipe name as the value for the alternate client ID and sets a large
time-out value. TMRA, in turn, issues a RESUME TPIPE request to the tpipe and waits for
the callout request from IMS Connect. The addressing information is pulled from
properties in the EJB(MDB) deployment descriptor.
2. An initiating client, such as a terminal, an IMS Connect, or OTMA client, provokes the
scheduling of an IMS application.
3. The IMS application issues an ISRT ALTPCB call to an OTMA destination routing
descriptor, which contains the destination tpipe name. The callout request message is
queued in this tpipe.
message to TMRA.
5. TMRA receives the callout request message and passes the request to the MDB in the
onNotification() method.
6. The MDB processes the callout request.
7. If response data must be sent back to IMS, the MDB issues a normal IMS transaction with
a SYNC_SEND request to the appropriate IMS application with the trancode and
response data.
8. In this case, IMS App2 is initiated by the receipt of the response from the MDB.
Sample MDB code is in Appendix A.3, Asynchronous callout to a Message Driven Bean on
page 423.
239
8174ch05.fm
6.5.3 Synchronous callout requests

Figure 6-15 shows that with the IMS callout support, IMS applications can be a client and
server. IMS provides bi-directional access between IMS applications and external application
and servers. The IMS application program can:
Callout to user-written IMS Connect client
Callout to WebSphere EJB/MDB using IMS TM Resource Adapter
Callout to Web Service Provider using IMS SOAP Gateway
Figure 6-15 Synchronous Callout interfaces
A new DLI call, the ICAL SENDRECV synchronous call function, allows an IMS application
program to communicate with other external applications synchronously. An IMS Call (ICAL)
sends a synchronous request for data or services from an IMS application program running in
the IMS TM environment to a non-IMS application program or service running in a distributed
environment. ICAL processing does not use the IMS message queue.
Here is the format of this new DLI call:
CALL 'AIBTDLI' USING function, aib,i/o area
The parameters are:
function: set to ICAL
aib
Specifies the application interface block (AIB) to be used for this call.
AIBID
Eyecatcher. This 8-byte field must contain DFSAIBbb.
AIBLEN
240
8174ch05.fm
AIB length. This field must contain the actual length of the AIB that the application
program obtained.
AIBSFUNC
This sub function code field must contain one of the listed 8 byte sub function codes:
SENDRECV. The IMS application program uses this sub function for synchronous
program to program communication.
AIBRSNM1
This resource name field contains the OTMA descriptor name. AIBRSNM1 is an 8 byte
alphanumeric left-justified field padded with blanks.
AIBRSFLD
This 4 byte field is used by the IMS application program to specify a time value to wait
in 100th of a second for the synchronous call process to complete. This value overrides
the value specified in the OTMA descriptor. The minimum value is 0 and the maximum
value is 999999. The system default is 10 seconds.
AIBOALEN
This request area length is an input and an output parameter. As an input parameter
this 4-byte field must contain the length of the input request area that is specified in the
call list. As an output parameter this field is only updated when partial data is returned
(AIB return code x'100', AIB reason code x'00C'). In the case of partial data returned,
this field contains the actual length of the response message. For any return code
other than partial data, this field is unchanged.
i/o area
The ICAL synchronous call function provides the ability for an IMS application program to
communicate with other application programs in a synchronous manner using the new OTMA
message processing function. Because the IMS message queue is not used, the 32K
message segment restriction was removed.
The ICAL synchronous call function is only supported using the AIBTDLI interface in IMS TM
runtime environments for IFP, MPP, BMP, JMP, and JBP regions.
Attention: Coordinated two phase commit between the IMS application program and the
external application program is not supported in the IMS Version 10 SPE. Also a Shared
Queues back-end IMS which is not connected to IMS Connect, cannot issue this ICAL.
The functions that OTMA provides as part of its support for the IMS synchronous callout
Version 10 SPE are:
Flow the synchronous callout request and receive the response
Enhance the OTMA output descriptor
Provide the time-out function for the ICAL call
Provide the OTMA protocol updates so that the synchronous callout request and the
response can be recognized by both IMS Connect and OTMA
Provide a simplified OTMA TPIPE log record to track input and output flow of a
synchronous callout message
Provide the OTMA command updates
OTMA connects the ICAL call to the IMS Connect client applications so that a synchronous
callout request can be delivered to them and the response can be given back to the IMS
application. This synchronous callout request is delivered through the OTMA Resume TPIPE
241
8174ch05.fm
method. If the request is larger than 32K, it is delivered to IMS Connect using a multi-segment
flow. The size of each message segment is equal or less than 32K. IMS Connect assembles
the segments and deliver them as one complete message to IMS Connect client applications,
such as IMS TM Resource Adapter.
Synchronous callout to an SLSB

Figure 6-16 shows the interaction with a Stateless Session EJB.
Figure 6-16 Message flow of synchronous callout to SLSB using TMRA
The message flow of a synchronous callout to SLSB using TMRA is:

1. The SLB application in WebSphere Application Server starts and obtains a sharable
persistent connection to IMS Connect through TMRA. It issues a
SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction, specifying the tpipe
name as the value for the alternate client ID, and sets a large time-out value. TMRA in turn
issues a RESUME TPIPE request to the tpipe and waits for the callout request from IMS
Connect.
2. An initiating client, such as a terminal, an IMS Connect, or an OTMA client, starts an IMS
application.
3. The IMS application issues an ICAL call to an OTMA destination routing descriptor, which
contains the destination tpipe name. The callout request message is queued in this tpipe.
4. As soon as the callout request is available in the Tpipe, IMS Connect delivers the callout
message to the IMS TM Resource Adapter.
5. TMRA receives the callout request message and returns the callout request to the SLSB.
6. The EJB processes the callout request.
7. A response message for a synchronous callout request return to OTMA as a special form
of SYNC_SEND message. This type of Send-Only message has no trancode and can be
a regular response data or error information to be passed back to the ICAL call. The
242
8174ch05.fm
response message can also be a multi-segment message. OTMA assembles the

multi-segment messages into a single message to be returned back to the IMS
application.
The correlation between request from IMS and response to IMS, is assumed by the
correlation token in interactionSpec of the
SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT. and SYNC_SEND interaction.
8. The waiting IMS App1 is presented the response.
Sample code for the SLSB is located inSynchronous callout to a StateLess Session Bean
on page 426.
Synchronous callout to an MDB

Message Driven Beans allow your application to synchronously receive messages delivered
to a JMS destination. Figure 6-17 presents the interaction with a MDB.
Figure 6-17 Message flow of Synchronous Callout to MDB using IMS TM Resource Adapter
The message flow of a synchronous callout to MDB using IMS TM Resource Adapter is:
1. When the Java EE application that contains the deployed MDB is started in the
WebSphere Application Server through the ActivationSpec and the underlaying listening
software, a sharable persistent connection to IMS Connect is obtained through TMRA. It
issues a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction, specifying the
tpipe name as the value for the alternate client ID, and sets a large time-out value. TMRA
issues a RESUME TPIPE request to the tpipe and waits for the callout request from IMS
Connect. The addressing information is pulled from properties in the MDB deployment
descriptor.
2. An initiating client, such as a terminal, an IMS Connect, or an OTMA client provokes the
scheduling of an IMS application.
3. The IMS application issues an ICAL call to an OTMA destination routing descriptor, which
contains the destination tpipe name.
4. The callout request message is queued in this tpipe.
message to TMRA.
243
8174ch05.fm
6. TMRA receives the callout request message and passes the callout request to the MDB in
the onMessage() method.
7. The MDB processes the callout request.
8. Response data are returned as an object of type Javax.resource.cci.Record with the
output data.
9. The waiting IMS App1 is presented the response.
Sample code for the MDB is located in A.5, Synchronous callout to a Message Driven Bean
on page 428.
Orphaned IMS conversation

When a conversation is not ended explicitly, it continues to exist in the system as an orphaned
conversation, and the associated IMS storage continues to be allocated to that
conversation.
An IMS conversation is usually ended explicitly in one of two ways:
The IMS application inserts blanks to the SPA before returning a response to the client.
The client application program submits a SYNC_END_CONVERSATION request.
If the browser was closed before the conversation ends properly, for example, the IMS
conversation is not ended explicitly and continues to exist in the system. When an IMS
conversation becomes orphaned, you have no way of programmatically continuing or ending
that conversation. One measure that you can take to avoid orphaned conversations would be
to use timeouts, such as the EJB session timeout, to force the end of a conversation that does
not complete in a reasonable amount of time by submitting a SYNC_END_CONVERSATION
request in the EJB session timeout cleanup code.
If a client application is terminated and a conversation becomes orphaned, the orphaned IMS
conversation can be ended only by an IMS restart. You can check for orphaned IMS
conversations in the system by issuing an IMS /DISPLAY CONV command through an
IMS_REQUEST_TYPE_IMS_COMMAND interaction. For a list of IMS commands supported by OTMA,
see the "Commands Supported from LU 6.2 Devices and OTMA" section in IMS Version 12
Commands, Volume 2: IMS Commands N-V, SC19-3010 or in "IMS Commands using OTMA"
in IMS Version 12 Communications and Connections, SC19-3012.
Restrictions for the IMS TM resource adapter

IMS TM Resource Adapter has some restrictions with their support of JCA 1.5
implementations.
IMS TM Resource Adapter do not provide the JCA 1.5 Kerberos support.
For a complete description of the restrictions for building composite business applications
that invoke IMS conversational transactions, see the IMS Connect conversational support
topic in IMS Communications and Connections information.
New features that are added after IMS TM Resource Adapter Version 10 and later require
TCP/IP connections (no Local Option).
For generic Java EE application servers, including WebSphere Application Server
Community Edition, two-phase commit (2PC), MFS functions, and conversational and
global transactions (XA) are not supported. These features are supported only when the
IMS TM resource adapter runs in IBM WebSphere Application Server.
244
8174ch05.fm
Important: The information provided in this set of IMS TM resource adapter

documentation is mainly based on the use of WebSphere Application Server. IMS TM
resource adapter functions that are not supported in WebSphere Application Server
Community Edition are not supported in other generic Java EE application servers.
A Class Summary for the IMS TM Resource Adapter Version 12 Package
com.ibm.connector2.ims.ico is in Table 6-2
Table 6-2 com.ibm.connector2.ims.ico
Class
Description
IMSConnection
An IMSConnection instance is an application-level handle that is used by a

component to access an underlying physical connection to IMS Connect.
IMSConnectionFactory
The IMSConnectionFactory class provides an interface for getting connections

to IMS Connect and, in turn, IMS OTMA.
IMSConnectionMetaData
Provides information about the Enterprise Information System (EIS) instance

associated with a particular IMSConnection instance.
IMSConnectionSpec
An IMSConnectionSpec instance is used by an application component to pass

information to the getConnection method.
IMSDFSMessageException
IMS TM Resource Adapter throws an IMSDFSMessageException when IMS

returns a "DFS" message and the value of the imsRequestType property in the
IMSInteractionSpec instance of the interaction is 1.
IMSInteraction
A component uses an instance of this class to perform an interaction with IMS

via IMS Connect.
IMSInteractionSpec
An instance of this class contains properties that are used in an interaction with
IMS via IMS Connect.
IMSManagedConnection
An IMSManagedConnection is an abstract class for the IMS managed

connection that represents a physical connection to IMS via IMS Connect
IMSManagedConnectionFactory
An IMSManagedConnectionFactory instance is a factory for

IMSConnectionFactory instances and IMSManagedConnection instances.
IMSManagedConnectionMetaData
The IMSManagedConnectionMetaData class provides information about a

ManagedConnection instance and the associated Enterprise Information
System (EIS).
IMSResourceAdapterMetaData
The IMSResourceAdapterMetaData class Contains meta information about the

resource adapter, IMS TM Resource Adapter.
Developing an application for use with the IMS TM resource adapter

To interact with IMS Transaction Manager (IMS TM) through the IMS TM resource adapter,
you can develop your application by using a Rational or WebSphere integrated
development environment (IDE), or by coding your application outside of an IDE by using the
J2EE Connector Architecture Common Client Interface (CCI).
An application uses the IMS TM resource adapter to run an IMS transaction in IMS
Transaction Manager. The IMS TM resource adapter also supports other types of interactions
with IMS TM, such as executing the IMS commands that are supported by IMS OTMA.
Consider the type of interaction with IMS TM when you develop your application. In addition,
the IMS TM resource adapter implements the J2EE Connector Architecture Common Client
Interface (CCI) API, an application programming interface that you can use in your
245
8174ch05.fm
applications to communicate with an Enterprise Information System (EIS), IMS TM in this

case, through the IMS TM resource adapter.
Recommendation: When you develop your application by using an IDE, you can use the
provided wizards and file importers to generate a Java EE application that will run on
WebSphere Application Server. When you use an IDE to generate your code, you do not
need to write the quality of service (QOS) code or the CCI code that is needed by your
Java application. Instead, you can concentrate on writing code to implement your business
logic and function.
Preparing to use the IMS TM resource adapter

Before you use the IMS TM resource adapter, you must first determine the version of the
IMS TM resource adapter and the development environment you need to use.
1. Determine which version of the IMS TM resource adapter you want to use. The version of
the IMS TM resource adapter that you use depends on whether you need the new
features that are added to IMS TM Resource Adapter and the version of your IMS.
For supported versions and software configurations, see Figure 6-18.
2. Determine which integrated development environment (IDE) you will use.
3. If you plan to deploy the IMS TM resource adapter to an application server other than
IBM WebSphere Application Server, you must download International Components for
Unicode (ICU) Version 4.4.2 or later from the ICU website at
http://icu-project.org/download and deploy it to your application server.
4. Review the potential migration issues and decide if the issues apply to you.
5. Download the runtime component for the version that you choose. The runtime component
is available for downloads from the IMS TM resource adapter website. It is also available
for installation on z/OS by using SMP/E.
6. If you are upgrading from an older version of the IMS TM resource adapter, follow the
steps in Installing IMS TM resource adapter service and updates.
246
8174ch05.fm
Figure 6-18 Supported software configurations by version of the IMS TM resource adapter
The numbers in Figure 6-18 have this meanings:

1. For the version of the IMS TM resource adapter that you choose, see the requirements
and restrictions topics on supported configurations for specific functionality.
2. The integrated IMS Connect function can coexist with earlier or newer versions of IMS.
See the Release Planning Guide for the version of IMS that you are using for IMS Connect
coexistence considerations and coexistence APARs.
3. Generic Java EE 1.4 or later certified application servers, including WebSphere
Application Server Community Edition, are supported if the IMS TM resource adapter
installation verification program (IVP) can run successfully. Only a subset of IMS TM
resource adapter functions are supported. See the restrictions topic for usage restrictions.
For generic Java EE 1.4 or later certified application servers, IBM support is provided for
specific functions if:
a. The problem can be recreated in the supported versions of WebSphere Application
Server or WebSphere Application Server Community Edition, or
b. The problem is confirmed to be caused by the IMS TM resource adapter through
diagnostic traces.
For a more detailed description of the compatibility of supported architecture, development
environments, and runtime environments, including the use of WebSphere Process Server
and WebSphere Message Broker, see the IMS TM resource adapter supported development
environments and runtime environments technote.
This concludes our discussion about the IMS Transaction Manager Resource Adapter.
247
8174ch05.fm
6.5.4 Issuing synchronous callout requests from a Java dependent region

IMS provides support for synchronous callout functionality from Java message processing
(JMP) or Java batch processing (JBP) applications through an IMS implementation of the
Java Message Service (JMS).
To use the JMP and JBP support for synchronous callout, the IMS Enterprise Suite JMS API
jms.jar file must be on your classpath. To download the IMS Enterprise Suite JMS API, go to
the following web URL:
http://www-01.ibm.com/software/data/ims/soa-integration-suite/enterprise-suite/
The IMS implementation of JMS is limited to supporting the Point-to-Point (PTP) messaging
domain only. In addition, support is only provided for non-transacted QueueSession objects
with Session.AUTO_ACKNOWLEDGE mode.
If the JMP or JBP application attempts to call any JMS method not supported by IMS or pass
any unsupported argument to JMS method calls, a JMSException exception is thrown.
1. To send a message using the JMP and JBP support for synchronous callout and
synchronously receive a response:
2. Create a com.ibm.ims.jms.IMSQueueConnectionFactory object.
3. Create a JMS QueueConnection instance by calling the createQueueConnection method
on the IMSQueueConnectionFactory object.
4. Create a JMS QueueSession instance by calling the createQueueSession method on the
QueueConnection instance.
In the method call, you must set the input parameter values to false and
Session.AUTO_ACKNOWLEDGE to specify that the generated QueueSession instance is
non-transacted and runs in AUTO_ACKNOWLEDGE mode.
5. Create a queue identity by calling the createQueue method on the QueueSession
instance. In the method call, you must set the input parameter value to the OTMA
descriptor name for the synchronous callout operation.
6. Create a JMS QueueRequestor instance and pass in the QueueSession instance from
step 3 and the Queue instance from step 4 as input parameters to the QueueRequestor
constructor method.
7. Create a TextMessage instance by calling the createTextMessage method on the
QueueSession instance from step 3. Set the string containing the message data.
8. To send the message and retrieve a response, call the request method on the
QueueRequestor object from step 5. In the method call, pass in the TextMessage instance
from step 6. You need to cast the return value from the request method call to a
TextMessage instance. If the call is successful, the return value is the response to the
synchronous callout request.
The code in Example 6-3shows how to write a simple JMP or JBP application that sends a
message to an external application and synchronously receive a response message. In the
example, an IMSQueueConnectionFactory instance is created with a timeout value of 10
seconds and with 128 KB of space allocated to hold response messages.
Example 6-3 Sample IMSQueueConnectionFactory
import
import
import
import
import
248
javax.jms.JMSException;
javax.jms.Queue;
javax.jms.QueueConnection;
javax.jms.QueueRequestor;
javax.jms.QueueSession;
8174ch05.fm
import javax.jms.Session ;
import javax.jms.TextMessage;
import com.ibm.ims.jms.IMSQueueConnectionFactory;
public class IMS_Sample
{
public static void main(String argv[])
{
IMSQueueConnectionFactory jmsConnectionFactory
= new IMSQueueConnectionFactory();
QueueConnection jmsConnection = null;
QueueSession jmsQueueSession = null;
Queue jmsQueue = null;
QueueRequestor jmsQueueRequestor = null;
try {
jmsConnectionFactory.setTimeout(1000);
// set the timeout to 10 seconds
jmsConnectionFactory.setResponseAreaLength(128000);
// allocate 128k to hold the response message
jmsConnection = jmsConnectionFactory.createQueueConnection();
jmsQueueSession
= jmsConnection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
// set session to be non-transacted and in AUTO_ACKNOWLEDGE mode
jmsQueue = jmsQueueSession.createQueue("OTMDEST1");
// pass in the OTMA descriptor name
jmsQueueRequestor
= new QueueRequestor(jmsQueueSession, jmsQueue);
TextMessage sendMsg = jmsQueueSession.createTextMessage();
sendMsg.setText("MyMessage");
System.out.println("Sending message: "+sendMsg.getText());
TextMessage replyMsg
= (TextMessage)jmsQueueRequestor.request(sendMsg);
System.out.println("\nReceived message: "+replyMsg.getText());
} catch (JMSException e) {
e.printStackTrace();
}
}
6.5.5 IMS Enterprise Suite Connect APIs

The Connect APIs provide application programming interfaces for custom IMS Connect
TCP/IP client applications to specify and configure connections and interactions with IMS
Connect.
The Connect APIs are available in two languages:
Connect API for C
Connect API for Java
249
8174ch05.fm
IMS Enterprise Suite Connect API for Java overview

The IMS Enterprise Suite Connect API for Java provides a simple interface for
developing custom IMS Connect TCP/IP client applications that are written in Java.
IMS Connect is an optional IMS Transaction Manager (TM) network component that provides
high performance communication between one or more TCP/IP clients and one or more IMS
systems. The Connect API for Java simplifies the process of developing Java applications that
interact with IMS through IMS Connect.
The key features of the Connect API for Java include:
Opens connections to IMS connect on behalf of the client application
Provides client applications with programmatic control of connections
Assembles messages to send to IMS Connect, including the IMS request message (IRM)
header
Manages the IMS Connect message protocol by sending and receiving the appropriate
messages for interactions with IMS Connect
The Connect API for Java manages the communication between the Java application and
IMS Connect. The client application provides property values that describe the type of
connection to establish with IMS Connect. The Connect API for Java establishes a connection
for the application and maintains that connection for as long as it is needed.
The Connect API for Java provides methods which encapsulate the creation of an input
request message to be sent to IMS Connect and the retrieval of the resulting response from
IMS Connect. The creation of the request message is based on properties which are
specified in the application or loaded from a reusable properties file. The properties
determine the type of interaction to be executed. By completing these steps on behalf of the
application, the API reduces the programming overhead associated with the IMS Connect
protocol headers.
For a synchronous callout message, the Connect API for Java stores the output message and
associated correlator token for the client application in the corresponding interaction object.
When the client is finished processing the message, it can return the synchronous callout
response (or an error response) to the waiting IMS application program.
The Connect API for Java also provides Java application developers with flexible ways to use
IMS Connect. For example, you can either acknowledge responses from IMS Connect
manually in your application or have the Connect API for Java internally acknowledge
responses from IMS Connect automatically.
You can use the Connect API for Java to drive IMS transactions, OTMA-supported IMS
commands, CSL OM-supported IMS type-2 commands, and IMS Connect-supported
commands (such as PING and RACF Password Change) from your Java client application.
The Connect API for Java supports Secure Sockets Layer (SSL) for securing TCP/IP
communications between client applications and IMS Connect.
The Connect API for Java supports the HWSSMPL0 and HWSSMPL1 IMS Connect user
message exits. The default user exit is HWSSMPL1.
6.5.6 IBM IMS DB Resource Adapter (DB Universal Driver)

Here are the highlights of what have been added to the Universal DB resource adapter for
IMS V12:
Catalog support
250
8174ch05.fm
The Universal DB resource adapters can now leverage the IMS catalog that was released
in IMS V12. This provides a trusted source of database and application metadata. By
providing a central source for metadata we are also improving the ease of scaling
applications as there is no file system dependency for application metadata
Qualify by Position Support
IMS DB has enhanced its SSA qualifications to take an offset and a length for a chunk of
data in a segment instead of a field name. This completely removes the notion of "search"
fields (fields defined directly in the IMS DBD source) as all fields can now be searched.
This removes any IMS specific knowledge in forming SQL qualifications and speeds up
application development and improves tool integration.
Support for scalars
This was added for analytic purposes. Suppose you have a value that is stored as 0 based
but you know it's actually 1 based. You can adjust it using 'SELECT COLUMN + 1 FROM
TABLE' and get it adjusted for you in the query itself instead of having to do application
manipulation of the ResultSet
Enhanced SQL support for OLAP function
We also added support for numeric functions such as SIN, COS, LOG, and EXP. Similar to
above this will help users write queries that produced results they want instead of having
to massage data afterwards in an application. This is very important for reporting and
analytic tools such as Cognos.
WebLogic support
We enhanced our drivers to work with WebLogic. You're able to leverage everything you
get from using the Java EE architecture like connection pooling. More importantly for many
customers, this also provides the capabilities of doing two phase commit
Performance enhancements
We have a lot of performance enhancements to the resource adapters such as better
caching. These same technologies apply to our other Universal Drivers which have been
benchmarked at over 19000 transaction per second in a JMP region.
6.5.7 IMS Universal drivers: configuring connections to IMS

The IMS Universal drivers can run in z/OS and distributed environments, including,
WebSphere Application Server for z/OS, and WebSphere Application Server for distributed
platforms.
The IMS Universal drivers include the following adapters and drivers:
The IMS Universal Database resource adapters, which take advantage of Java
Platform, Enterprise Edition (Java EE) services.
The IMS Universal JDBC driver, which support SQL calls that directly access your IMS
data.
The IMS Universal DL/I driver, which provides calls that are similar to DL/I in a Java
programming interface.
When running in a distributed environment on a server such as WebSphere Application
Server for distributed platforms, or in a remote z/OS environments on a server such as
WebSphere Application Server for z/OS, the IMS Universal drivers connect to IMS using a
type-4 connection architecture, which supports TCP/IP communications and socket
management.
251
8174ch05.fm
When running locally on the same logical partition (LPAR) as IMS, the IMS Universal drivers
connect to IMS by using a type-2 connection architecture, which supports direct
communication with IMS through the IMS Open Database Access (ODBA) and IMS database
resource adapter (DRA) interfaces.
WebSphere Application Server supports all of the IMS Universal drivers in both distributed
and z/OS environments.
IMS Universal drivers: WebSphere Application Server type-4 connections
Java applications that run on WebSphere Application Server can access IMS databases
by using the type-4 connectivity provided by the IMS Universal drivers. The type-4
connectivity of the IMS Universal drivers enables Java application programs to access IMS
databases from a wide variety of distributed and mainframe environments, either in
stand-alone mode or under an application server, with or without XA support for global
transactions.
IMS Universal drivers: WebSphere Application Server for z/OS type-2 connections
When WebSphere Application Server for z/OS and IMS are on the same logical partition
(LPAR), Java applications running in WebSphere Application Server for z/OS can access
IMS databases by using the type-2 connectivity provided by the IMS Universal Database
resource adapters.
The IMS Universal drivers: CICS connections
Java applications that run on IBM CICS Transaction Server for z/OS can access IMS
databases by using the type-2 connectivity provided by the IMS Universal drivers. Other
than the Java layer, access to IMS from a Java application is the same as for a non-Java
application.
Figure 6-19 zOS unix mount point sample
In Table 6-3 you find the comparison where to use the different IMS Universal Database
resource adapters you need. In your z/OS Unix file system on the IMS mount point usually
under usr lpp ims. See Figure 6-19 for details where your mount point might be slightly
different.
252
8174ch05.fm
Table 6-3 IMS Universal resource adapter comparison

Application platform
Data access method
Transaction
processing required
Recommended approach
WebSphere
Application Server for
distributed platforms or
WebSphere
Application Server for
z/OS
JDBC programming
interface to perform
SQL data operations.
Local transaction
processing only.
Use the IMS Universal JCA/JDBC driver

version of the IMS Universal Database
resource adapter with local transaction
support (imsudbJLocal.rar), and make
SQL calls with the JDBC API.
JDBC programming
Two-phase (XA)
commit processing (1)
or local transaction
processing.
Use the IMS Universal JCA/JDBC driver

version of the IMS Universal Database
resource adapter with XA transaction
support (imsudbJXA.rar), and make SQL
calls with the JDBC API.
JDBC programming
Two-phase (XA)
processing.
Use the IMS Universal JDBC driver

(imsudb.jar), and make SQL calls with the
JDBC API.
CCI programming
SQL or DL/I data
operations.
Local transaction
processing only.
Use the IMS Universal Database

resource adapter with local transaction
support (imsudbLocal.rar), and make
SQL calls with the SQLInteractionSpec
class or DL/I calls with the
DLIInteractionSpec class.
CCI programming
SQL or DL/I data
operations.
Two-phase (XA)
processing.
Use the IMS Universal Database

resource adapter with XA transaction
support (imsudbXA.rar), and make SQL
calls with the SQLInteractionSpec class
or DL/I calls with the DLIInteractionSpec
class.
Standalone Java
application (outside a
Java EE application
server) that resides on
a distributed platform
or a z/OS platform
Traditional DL/I
programming
semantics to perform
data operations.
Two-phase (XA)
processing.
Use the IMS Universal DL/I driver

(imsudb.jar), and make DL/I calls with the
PCB class.
Standalone non-Java
application that
resides on a
distributed platform or
a z/OS platform
Data access using

DRDA protocol.
Two-phase (XA)
commit processing or
local transaction
processing.
Use a programming language of your

choice to issue DDM commands to IMS
Connect. The application programmer is
responsible for implementing the
two-phase commit mechanism.
Note:
1. XA transaction support is available only with type-4 connectivity.
2. The driver is enabled for local and XA transactions, but the application programmer is
responsible for implementing the two-phase commit mechanism. XA transaction
support is available only with type-4 connectivity.
We also support Type 2 and Type 4 connection with the Universal DB resource adapters.
Distributed access
253
8174ch05.fm
Universal drivers support type 4 connectivity to IMS databases from TCP/IP enabled
platforms and runtimes
Windows
zLinux
z/OS
WebSphere Application Server
Standalone Java SE
Resource Recovery Services (RRS) is NOT required if applications do not require distributed
two phase commit.
The Universal drivers have a framework capable of processing any of the three main
programming models: J2EE, JDBC, DLI. The Universal drivers are able to connect to any IMS
subsystem on any mainframe system. The same application can have active connections to
any number of IMS systems on any number of mainframe installations.
We are also providing type 2 access (IMS access from the same LPAR in WAS z/OS, IMS
JDR, CICS, DB2 for z /OS stored procedures) using these same Universal drivers. See
Figure 6-20. Again, the same framework is capable of handling both type 2 and type 4
connectivity so the applications themselves do not change. Only the connection properties.
IMS Open Database Environment (Type 2 and 4 Connectivity)

z/OS
LPAR A
z/OS WAS
IMS
DB
Resource
Distributed
Adapter
WAS on Any Platform
Type-2
Universal
DB
Resource
Adapter
1. 5
JDBC
PC CTL
O
D
B
A
PC
LPAR C
TCP/IP
TCP/IP
P
I
CTL
IMS DB
IMS
IMS Connect
T
DLI
IMS DB
IMS
Traditional ODBA
S
C
I
DLI
IMS Universal Drivers
O
D
B
A
S
C
I
ODBM
JDBC
1.5
ODBM
PC
XCF
IMS Universal Drivers
O
D S
B C
A I
LPAR B
Traditional ODBA
Univer sal
ODBM
S
C
I
S
C
I
O
D
B
A
PC
CTL
IMS DB
RYO DRDA Appl.
Type-4
Figure 6-20 Type 2 and Type 4 Connectivity
For more details and programming info follow this link to the IMS Info Center
http://pic.dhe.ibm.com/infocenter/dzichelp/v2r2/index.jsp?topic=%2Fcom.ibm.ims12.d
oc%2Fimshome_v12.htm.
254
8174p02.fm
Part 2
Part
Extended architecture
and application
technology of IMS
IMS connectivity enables clients to easily integrate IMS across the enterprise: trusted IMS
applications and transactions may become web services. New points of integration for IMS
across the enterprise offer capabilities such as database visualization, query tooling support,
data insight, open access, SQL and .NET support, analytics, etc., contributing to the
modernization of IMS IT infrastructures.
In this part we discuss sample of the enhanced application technologies which allow the
repurposing of IMS data assets as web services, mobile apps, and so on, thus preserving
and extending the ROI of the original investment.
In this part we discuss the following chapters:
Chapter 7, COBOL dynamic SQL access to IMS databases on page 257

Chapter 8, The IMS catalog on page 267
Chapter 9, IMS Explorer and Open Database on page 337
Chapter 10, IMS Data Provider for Microsoft .NET on page 357
Chapter 11, IMS mobile enablement solutions on page 373
Chapter 12, WebSphere DataPower and IMS integration on page 383
255
8174p02.fm
256
8174ch06.fm
Chapter 7.
COBOL dynamic SQL access to

IMS databases
Native SQL support for COBOL enables SQL in COBOL programs to access IMS databases
and provides for SQL processing natively in IMS. This support, available in IMS 13, is in
addition to the Java-based SQL IMS application support.
Native SQL support for COBOL allows SQL programmers to access IMS databases using
SQL statements like those issued when dealing with a relational databases. This
enhancement expands IMS database usage to a wider group of application and database
developers and can take advantage of SQL skills without requiring in-depth IMS database
knowledge.
This function requires IBM Enterprise COBOL for z/OS 5.1 and APAR PM92523.
In this chapter we briefly describe an example of SQL support for COBOL by referencing a
simple COBOL program.
This chapter contains the following:
Overview
SQL statements supported by IMS
Sample IMS COBOL SQL program
257
8174ch06.fm
7.1 Overview
Over recent releases, the information in your IMS databases has been made accessible
through an increasing number of avenues. Initially, the only access was through host
applications running on z/OS, using Data Language 1. More recently, distributed access to
IMS data has been possible through Java applications using the JDBC interface.
IMS 13 has added a new dimension to access and update the information in your IMS
databases. The existing Data Language 1 (DL/I) interface continues to be available and
supported for all your applications. When using Enterprise COBOL Version 5, applications
can now access and update information in these same IMS databases using the Structured
Query Language (SQL).
Using the extended database descriptions made possible through the catalog function in IMS
12, these COBOL SQL programs are able to access IMS databases using the relational
column and table paradigm. The SQL supported by IMS is a subset of the full SQL language,
so application programming skills gained through use of DB2 for z/OS and other relational
database management systems are immediately usable in the IMS SQL environment. In this
release, IMS provides support for dynamic SQL.
IMS makes no distinction between applications accessing IMS databases through DL/I, and
applications accessing IMS databases through SQL. These IMS SQL applications are able to
enquire, and update, the same set of IMS databases in the same manner as all existing IMS
application. The DL/I and SQL interfaces can be used in the same program, and can even
access the same databases in the program. These applications can run as Message
Processing Programs (MPPs), Interactive Fast Path (IFP) programs, or Batch Message
Processing (BMP) programs. The IMS databases are accessible through a full IMS TM/DB
system, or through IMS DBCTL. At this time, IMS SQL access is not possible with CICS
applications or DL/I Batch applications.
IMS SQL uses the same environment to access IMS databases as native DL/I applications.
That is, the database is defined through the standard data base description (DBD), and
program access is provided through the standard program specification block (PSB). The
DBD and PSB are used to produce the standard access control block (ACB). The IMS catalog
needs to be populated, either by using the combined ACB Generation and Catalog Populate
utility (DFS3UACB), or the two utilities separately: that is, the ACBGEN utility and the IMS
Catalog Populate utility (DFS3PU00).
IMS SQL applications require the IMS catalog for the definition of all tables (segments) and
columns (fields). The catalog is accessed at runtime for these definitions.
7.2 SQL statements supported by IMS

Listed here are the SQL statements currently supported by IMS:
CLOSE
The CLOSE statement closes a cursor.
DECLARE CURSOR The DECLARE CURSOR statement defines a cursor.

DECLARE STATEMENT
The DECLARE STATEMENT statement is used for application
program documentation. It declares names that are used to identify
prepared SQL statements.
DELETE
258
The DELETE statement deletes rows from a table.
8174ch06.fm
DESCRIBE OUTPUT The DESCRIBE OUTPUT statement obtains information about a

prepared statement.
EXECUTE
The EXECUTE statement executes a prepared SQL statement.
FETCH
The FETCH statement positions a cursor on a row of its result table. It

can return zero or one and assigns the values of the rows to host
variables if there is a target specification.
INCLUDE
The INCLUDE statement inserts application code, including

declarations and statements, into a source program.
INSERT
The INSERT statement inserts rows into a table.
OPEN
The OPEN statement opens a cursor so that it can be used to process

rows from its result table.
PREPARE
The PREPARE statement creates an executable SQL statement from

a string form of the statement. The character-string form is called a
statement string. The executable form is called a prepared statement.
SELECT
The SELECT statement is used to retrieve data from one or more

tables. The result is returned in a tabular result set.
UPDATE
The UPDATE statement updates the values of specified columns in

rows of a table.
WHENEVER
The WHENEVER statement specifies the host language statement to

be executed when a specified exception condition occurs.
7.3 Sample IMS COBOL SQL program

In Example 7-1 we show a sample IMS COBOL SQL program. The program is also available
for download as described in Appendix B, Additional material on page 445.
Example 7-1 Sample IMS COBOL SQL program
CBL SIZE(4000K) SOURCE XREF

CBL SQLIMS
IDENTIFICATION DIVISION.
PROGRAM-ID. 'sqla12'.
************************************************************
*
*
* Read information from the LGI (IMS) database using SQL *
*
*
* Program
SQLA12
*
* PSB:
S2U1PSB
*
* Databases: S2U1DBD
*
* Access:
SQLIMS
*
*
*
************************************************************
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. IBM-zSeries.
OBJECT-COMPUTER. IBM-zSeries.
DATA DIVISION.
Chapter 7. COBOL dynamic SQL access to IMS databases
259
8174ch06.fm
WORKING-STORAGE SECTION.
************************************************************
*
These are the SSAs used to retrieve the database
*
*
and PSB information from the catalog
*
*
This is done with the show-catalog procedure
*
************************************************************
01 dbd-ssa.
02 filler
pic x(8) value 'HEADER '.
02 filler
pic x(1) value '('.
02 ssa-field-name pic x(8) value 'RHDRSEQ '.
02 ssa-boolean
pic x(2) value '= '.
02 ssa-field-value pic x(8) value 'DBD
'.
02 ssa-dbd-name
pic x(8).
02 filler
pic x(1) value ')'.
01 psb-ssa.
02 filler
02 filler
pic x(1) value '('.
02 ssa-boolean
02 ssa-field-value pic x(8) value 'PSB
'.
02 ssa-psb-name
pic x(8).
02 filler
pic x(1) value ')'.
77 gur-call
pic x(4) value 'GUR '.
77 sync-call
pic x(4) value 'SYNC'.
01 gur-returned-data.
03 gur-header
pic x(56).
03 gur-information
pic x(15000).
***********************************************************
* This program uses the AIB interface, since the GUR call
* to retrieve information from the catalog requires the
* use of the AIB interface. The program could also use
* CBLTDLI calls if desired, when accessing IMS databases
***********************************************************
01 AIB.
02 AIBRID
PIC x(8).
02 AIBRLEN
PIC 9(9) USAGE BINARY.
02 AIBRSFUNC
PIC x(8).
02 AIBRSNM1
PIC x(8).
02 AIBRSNM2
PIC x(8).
02 AIBRESV1
PIC x(8).
02 AIBOALEN
02 AIBOAUSE
02 AIBRESV2
PIC x(12).
02 AIBRETRN
02 AIBREASN
02 AIBERRXT
260
8174ch06.fm
02 AIBRESA1
USAGE POINTER.
02 AIBRESA2
USAGE POINTER.
02 AIBRESA3
USAGE POINTER.
02 AIBRESV4
PIC x(40).
02 AIBRSAVE
OCCURS 18 TIMES USAGE POINTER.
02 AIBRTOKN
02 AIBRTOKC
PIC x(16).
02 AIBRTOKV
PIC x(16).
02 AIBRTOKA
OCCURS 2 TIMES PIC 9(9) USAGE BINARY.
* Data Input Area from the terminal
* (not used in this program).
01 INPUT-MESSAGE.
PIC S9(4) COMP.
03 IN-LL
03 IN-ZZ
PIC S9(4) COMP.
03 IN-TRANCODE PIC X(8).
03 IN-DATA.
04 IN-LINE1 PIC X(80).
* Data Output Area from the terminal
* (not used in this program).
01 OUTPUT-AREA.
02 OUT-LL
PICTURE S9(3) COMP VALUE +100.
02 OUT-ZZ
PICTURE S9(3) COMP VALUE +0.
02 OUT-LINE
PICTURE X(96) VALUE SPACES.
02 OUT-DATA REDEFINES OUT-LINE.
04 OUT-TEXT
PIC X(32).
04 OUT-MSG1
PIC X(32).
04 OUT-MSG2
PIC X(32).
*********************************************************
* SQL STRING
*
* In this program, the SQL statement is passed to IMS
* via a working storage text variable. The first two
* bytes are the length of the SQL statement, and the
* rest is the statement itself.
*********************************************************
01 FULL-STATEMENT.
05 SELECT-STATEMENT.
49 SELECT-STATEMENT-LEN PIC S9(4) COMP VALUE +200.
49 STATEMENT-TXT
PIC X(200).
* Miscellaneous fields for this program
77 row-count
PIC 9(6) VALUE 0.
77 loop-count
PIC 9(6) VALUE 0.
*****************************************************
* SQL INCLUDE FOR SQLCA
*
*
IMS SQL Communications Area
*
*****************************************************
EXEC SQLIMS
261
8174ch06.fm
INCLUDE SQLIMSCA
END-EXEC.
*****************************************************
* SQL INCLUDE FOR SQLCA
*
*
IMS SQL Descriptor Area
*
*****************************************************
*
* it is retrieved, and displayed for your interest,
* but not used in this program
EXEC SQLIMS
INCLUDE SQLIMSDA
END-EXEC.
*********************************************************
* SQLCODE TEMPLATE TO REMOVE SIGN BIT.
*
*********************************************************
77 SQLIMSCODE-DISP PIC S9(9) DISPLAY SIGN LEADING SEPARATE.
*****************************************************
* district SEGMENT
*
*****************************************************
01 sql-district.
03 sql-distnum
pic x(6).
03 sql-distname
pic x(30).
03 sql-currdate
pic x(6).
03 sql-currtime
pic x(8).
03 sql-custno
pic x(6).
03 sql-distrest
pic x(5).
*****************************************************
LINKAGE SECTION.
01 IOPCB.
02 IO-LTERM
PIC X(8).
02 IO-RESV
PIC X(2).
02 IO-STATUS
PIC X(2).
02 IO-PREF
PIC X(12).
02 IO-MODN
PIC X(8).
02 IO-USERID
PIC X(8).
02 IO-GROUPID
PIC X(8).
01 DBPCB.
02 DBNAME
PICTURE X(8).
02 SEG-LEVEL-NO PICTURE X(2).
02 DBSTATUS
PICTURE XX.
02 FILLER
PICTURE X(2000).
PROCEDURE DIVISION USING IOPCB, DBPCB.
MAIN-Routine.
DISPLAY "COBOL Program sqla12 Execution begins... ".
EXEC SQLIMS
WHENEVER SQLERROR GOTO 100-DBERROR
262
8174ch06.fm
END-EXEC.
EXEC SQLIMS
WHENEVER SQLWARNING GOTO 200-DBERROR
END-EXEC.
EXEC SQLIMS
WHENEVER NOT FOUND CONTINUE
END-EXEC.
perform show-catalog through show-catalog-end .
display "about to process DECLARE TELE1 CURSOR FOR DYSQL".
EXEC SQLIMS
DECLARE TELE1 CURSOR FOR DYSQL
END-EXEC.
MOVE ZERO to LOOP-COUNT.
MOVE "SELECT distnum, distname, currdate, currtime,
"custno, distrest FROM district
"where distnum = '000010'"
TO STATEMENT-TXT.
move 198 to SELECT-STATEMENT-LEN.
display "about to process PREPARE DYSQL FROM :SELECT-".
EXEC SQLIMS
PREPARE DYSQL FROM :FULL-STATEMENT
END-EXEC.
move 6 to SQLIMSn.
exec SQLIMS
describe output dysql into :sqlimsda
end-exec.
perform display-sqlda.
display "about to process OPEN TELE1".
EXEC SQLIMS
OPEN TELE1
END-EXEC.
PERFORM FETCH-DISTRICT
UNTIL SQLIMSCODE NOT EQUAL 0
display "about to perform CLOSE TELE1".
EXEC SQLIMS
CLOSE TELE1
END-EXEC.
PERFORM sync-and-return.
FETCH-DISTRICT.
EXEC SQLIMS
FETCH TELE1 INTO :sql-distnum, :sql-distname,
:sql-currdate,
:sql-currtime,
:sql-custno,
:sql-distrest
END-EXEC.
IF SQLIMSCODE EQUAL 0
ADD 1 TO row-count
263
8174ch06.fm
display " count ", row-count,

"| sql-distnum |", sql-distnum,
"| sql-distname |", sql-distname,
'|', sql-currdate,
'|', sql-currtime,
'|', sql-custno,
'|', sql-distrest
end-if.
************************************************************
*
Display 'Data Not Found' Message when data not found.
************************************************************
DATA-NOT-FOUND.
DISPLAY " ----------------------------------------".
DISPLAY " ".
DISPLAY "******NO MORE DATA FOUND******".
*
MOVE SQLIMSCODE TO SQLIMSCODE-DISP.
*
DISPLAY "SQLIMSCODE = " SQLIMSCODE-DISP.
*
************************************************************
*
Display error message
************************************************************
100-DBERROR.
DISPLAY "ERROR OCCURRED IN WHENEVER SQLIMSERROR".
DISPLAY "SQLIMSERRMC= " SQLIMSERRMC.
DISPLAY "SQLIMSSTATE= " SQLIMSSTATE.
perform sync-and-return.
************************************************************
*
Display warning message
************************************************************
200-DBERROR.
DISPLAY "ERROR OCCURRED IN WHENEVER SQLWARNING".
DISPLAY "SQLIMSERRMC= " SQLIMSERRMC.
DISPLAY "SQLIMSSTATE= " SQLIMSSTATE.
perform sync-and-return.
************************************************************
*
Time to go home again...
************************************************************
sync-and-return.
DISPLAY "Returning ...".
call 'CBLTDLI' using sync-call iopcb.
GOBACK.
************************************************************
264
8174ch06.fm
*
*
This routine accesses the IMS catalog information with
*
the Get Unique Record (GUR) call through an
*
Application Interface Block (AIB)
*
*
Applications can use the CBLTDLI, AIB and now the
*
SQL interface to IMS databases in the same program,
*
even to the same database (PCB) if needed.
*
************************************************************
show-catalog.
move "C1CSTP "
to ssa-dbd-name.
move "C1ACSTLD"
to ssa-psb-name.
*
Retrieve the DBD information from the catalog
move "DFSAIB "
to AIBRID.
move length of aib to AIBRLEN.
move length of gur-returned-data to AIBOALEN.
move spaces
to AIBRSFUNC.
MOVE "DFSCAT00"
TO AIBRSNM1.
call 'AIBTDLI' using gur-call
aib
gur-returned-data
dbd-ssa.
set address of dbpcb to aibresa1.
if dbstatus not equal space
display '|' dbstatus '|,' 'aib return is ', AIBRETRN,
',aib reason is ' AIBREASN
else
display "------------ D B D --------------------".
display gur-information .
*
Now retrieve the PSB information from the catalog
call 'AIBTDLI' using gur-call aib
gur-returned-data psb-ssa.
if dbstatus not equal space
display '|' dbstatus '|,' 'aib return is ', AIBRETRN,
',aib reason is ' AIBREASN
else
display " ".
display "------------ P S B --------------------".
display gur-information .
show-catalog-end.
exit.
************************************************************
*
*
This routine displays the information returned
*
from the DESCRIBE STATEMENT request into the
265
8174ch06.fm
*
SQL IMS Descriptor Area (SQLIMSDA).
*
************************************************************
display-sqlda.
display "SQLIMSDAID|" SQLIMSdaid
"|SQLIMSDABC|" SQLIMSdabc
"|SQLIMSN|" SQLIMSn
"|SQLIMSD|" SQLIMSd.
perform with test after
varying LOOP-COUNT from 1 by 1
until loop-count > SQLIMSd
display
" ",
loop-count,
" type=", SQLIMSTYPE(loop-count),
" len=" , SQLIMSLEN(LOOP-COUNT),
" namel=", SQLIMSNAMEL(loop-count),
" namec=" SQLIMSNAMEC(LOOP-COUNT),
"|"
end-perform.
END PROGRAM "sqla12".
266
8174ch07.fm
Chapter 8.
The IMS catalog

This chapter provides a description of the IBM IMS catalog and the way it can be used to
expand and consolidate the information about IMS databases and their metadata.
The IMS catalog is an optional system database, available since IMS 12, that stores metadata
about your databases and applications. Its comprehensive view of IMS database metadata,
fully managed by IMS, allows IMS to participate in solutions that require the exchange of
metadata. A type of solution that requires such an exchange is business impact analysis.
The IMS Universal drivers have been enhanced to take advantage of the IMS catalog.
In this chapter, the following topics are described:
Overview and objectives of the catalog

Physical structure of the catalog database
IMS catalog database installation and management
Application use of the catalog
The role of the IMS Enterprise Suite Explorer for Development
Using IMS Explorer to capture IMS metadata
Enhancements to the IMS Universal drivers
This chapter describes the IMS catalog, a trusted online source for both IBM IMS database
and application metadata information, and its use by IMS Open Database and IMS Explorer.
This chapter targets application developers who can benefit from these simplification and
integration functions when they are facing any large-scale deployment of the IMS Open
Database solution.
267
8174ch07.fm
8.1 Overview and objectives of the catalog

Before the introduction of the IMS catalog, information about the structure of the
Data Language/I (DL/I) databases was spread across the following different data structures:
The database description
The database description (DBD) defines the characteristics of a database. For example,
the DBD defines characteristics such as its organization and access method, the
segments and fields in a database record, and the relationship between the types of
segments. Most of the time, information for the segments was limited to the few fields
required to identify and search for segments across the hierarchical structures. That is,
limited to the fields used as search arguments in the segment search argument (SSA),
and the fields required to define logical relationships and secondary indexes.
The COBOL copybooks and PL/I or C include members
The details of the fields in each segment of the database are often defined in a
Common Business Oriented Language (COBOL) copybook and in PL/I or C include
members. These members detail all the fields in each database segment (not just the
fields used in SSAs), and are included into the source program when the program is
compiled.
The program specification block
A program specification block (PSB) is used to define two things: The view of the
databases to be used by a program, and any logical message destinations. These views
are called program communication blocks (PCBs), because they are the means of
communicating between the application program and IMS. There can be many PCBs in a
PSB (as shown in Figure 8-1), allowing a program to communicate with (access) multiple
IMS databases. For each database the program is able to access, a PCB is needed which
describes the segments and the hierarchical structure that the program can access. The
description can also indicate the sensitivity a program has to the information. That is,
whether the program can see only a subset of the segment types in the database, and a
subset of the fields in these segments.
A PCB can also allow a program to use different access paths through a database. It can
allow the program to access a database through a secondary index or a logical
268
8174ch07.fm
relationship. The program view of the hierarchical structure of the database can be
different from the hierarchical structure defined in the DBD. See Figure 8-1.
PSB
PCB
PCB
PCB
PCB
DBD
DBD
DBD
DBD
Figure 8-1 A PSB with multiple PCBs
For online IMS systems, application control block (ACB) libraries contain the metadata used
by IMS, created by performing an ACB generation from the DBD and PSB libraries. The
current system that uses DBD, PSB, and ACB libraries is proprietary. Typically, a DBD defines
only a subset of the fields in a database record, such as the sequence (key) fields and any
fields needed by a secondary index. Other fields in a record are typically defined only in a
COBOL copybook or in a PL/I or C include file used by an application program.
The introduction of Java access to IMS data from JBP or JMP regions, or from remote
systems or clients, required easily accessible metadata. To provide this access, the contents
of ACBLIB are offered as a Java class.
With the move to making IMS data more widely and easily accessible outside of the
mainframe, application programmers need to have easy and consistent access to the
metadata. Since IMS V8, this data has been provided by using the DLIMODEL utility. This
utility generates Java class files, containing a static definition of the database design at the
point when the DLIMODEL utility is run.
The drawback when using the DLIMODEL utility is that it can be a challenge to manage. Also,
change control is needed when the underlying database definition changes. This method
potentially allows the creation of multiple copies of the database metadata, each one of which
must be updated with any database structure change.
There is a requirement for a source of metadata that is easier to manage and can be trusted
to reflect the possible changes of the design of IMS databases. The metadata can also be
defined in an open format.
IMS 12 introduced the IMS catalog. The IMS catalog contains the metadata for databases
and PSBs. It is accessed by using the Java Database Connectivity (JDBC) drivers and is also
available to any tool or application. IMS metadata is available in an Extensible Markup
Language (XML) format, and also available to standard DL/I applications in a traditional IMS
segment format.
When the metadata is updated, the catalog is also updated to reflect the change; therefore,
the data is always current. The data is current because the metadata is accessed dynamically
Chapter 8. The IMS catalog
269
8174ch07.fm
from the active IMS catalog high availability large database (HALDB), rather than from static
class files.
The catalog in IMS also includes a versioning system. This system allows the current version
of the metadata, and a user-specified number of previous versions, to be kept and available
for the applications.
The IMS catalog is a partitioned hierarchical indexed direct access method (PHIDAM)
database that contains trusted metadata for IMS databases and applications. The
IMS Catalog Populate utility (DFS3PU00) can optionally be used to initially populate the
catalog by reading an existing ACBLIB and loading the available metadata into the catalog. All
the information that is contained in the runtime ACBLIB (which was derived from the DBDs
and PSBs) is available to the users in the IMS catalog. Enhancements to the existing
DBDGEN, PSBGEN, and ACBGEN processes allow database and application metadata to
be defined to IMS. The new ACB Generation and Catalog Populate utility (DFS3UACB)
automatically updates the IMS catalog when the ACB members are generated. This update
keeps the catalog in a trusted state at all times after initialization. The IMS catalog is the
single, authoritative source of database and application metadata for all client applications.
The catalog can also contain application metadata such as decimal data specifications (scale
and precision), data structure definitions, and mapping information.
The IMS catalog uses timestamps to identify the version of the metadata for each database,
and can store multiple versions of metadata for each database. IMS provides the facility to
keep a number of generations of this metadata, and remove old metadata, according to a
maximum number of generations or longevity that you specify. By default, the IMS catalog
contains information for each DBD and PSB in the active IMS system ACBLIB. The
IMS Catalog Record Purge utility (DFS3PU10) must be run to remove the extra definitions in
the catalog.
8.2 Physical structure of the catalog database

The IMS catalog is a HALDB database: a partitioned, IMS full-function database type. Before
loading records into an IMS catalog, you must define the partitions to IMS. The IMS catalog is
composed of the following objects:
Primary database DFSCD000
The access method is overflow sequential access method (OSAM), comprising the
following database data sets:
Primary index data set
Indirect list data set (ILDS)
Four data set groups for the segments of the IMS catalog records
Secondary index DFSCX000
This index provides a cross-reference between the PSB segment and the DBD it is used
to access: The data set for the secondary index database is a partitioned secondary index
(PSINDEX).
The data stored in the IMS catalog includes all the metadata that has been traditionally held
in the DBD and PSB libraries. The IMS catalog also includes extra metadata information not
available in the earlier releases of the DBD and PSB libraries. The IMS Explorer for
Development is used to extend the metadata in the DBD, to be stored in the catalog. See 8.5,
The role of the IMS Enterprise Suite Explorer for Development on page 299 for details on
the process to include the extended metadata into the DBD and the IMS catalog.
270
8174ch07.fm
Segments of the catalog database

The following segments are part of the catalog:
Resource header (item name and type) for each DBD and PSB
DBD resources:
Database structure definitions (ACCESS, RMNAME, and so on)

Data capture parameters
Physical database data set (DATASET) or area (AREA) definitions
Segment definitions (SEGM)
Field definitions (FIELD)
Marshaller definitions (DFSMARSH)
Logical children (LCHILD)
Indexed field (XDFLD)
Map definitions (DFSMAP)
Case definitions (DFSCASE)
Case field definition
Case marshaller definition
PSB resources:
Program Communication Block (PCB)

Sensitive segments (SENSEG)
Sensitive fields (SENFLD)
DBD cross-reference
There are a number of new macros in a DBD which allow IMS to better map the application
data structures. They are all an extension of the field macro.
For each macro used in a DBD or PSB, there is an equivalent segment in the IMS catalog
database.
The segments in the DBD of the IMS catalog database are shown in Example 8-1.
Example 8-1 Segments in the IMS catalog database (DFSCD000)
DDDD
D
D
D
D
D
D
D
D
D
D
DDDD
ID=
1* N/A
ID=
2+ N/A
ID=
3" N/A
ID=
4. N/A
SEG-NAME
SC# LV
HEADER
DBD
CAPXDBD .
3 3
DBDRMK
FFFFF SSS
CCC
F
S
S C
C
F
S
C
FFF
SSS C
F
S C
F
S
S C
C
F
SSS
CCC
DDDD
D
D
D
D
D
D
D
D
D
D
DDDD
000
0
0
0 00
0 0 0
00 0
0
0
000
000
0
0
0 00
0 0 0
00 0
0
0
000
000
0
0
0 00
0 0 0
00 0
0
0
000
VERSION=04/18/12 11.49
LEVELS=
8
SEGMENTS= 62
DATA SET GROUPS=
4
PRIME DS LOG. RCD. LEN=
0, BLOCKSIZE= 32752
SEGMENT LENGTH MAX=
614,
OFLW DS LOG. RCD. LEN=
0, BLOCKSIZE= 32752
KEY LENGTH MAX=
17,
0, BLOCKSIZE= 32752
SEGMENT LENGTH MAX=
934,
0, BLOCKSIZE= 32752
KEY LENGTH MAX=
2,
0, BLOCKSIZE= 32752
SEGMENT LENGTH MAX=
934,
0, BLOCKSIZE= 32752
KEY LENGTH MAX=
2,
0, BLOCKSIZE= 32752
SEGMENT LENGTH MAX= 4022,
0, BLOCKSIZE= 32752
KEY LENGTH MAX=
17,
C P P L L P
P P L L E RULES PHYS.
SEG-NAME D-B-NAME
PAR -LEN- ---FREQ--- T T P T P H
C C C C P
N-SEQ
OR
OR
R FB
FB
FB .F .L .F .L S I D R INSRT
FLD-NAME LEN STRT
0
56
0.00
XX
13
P P P LAST
*PFX* LEN= 70 MAX=
56
MIN=
24
1
552
0.00
XX X
10
P P P LAST
*PFX* LEN= 62 MAX=
552
MIN=
505
2
32
0.00
X X
P P P LAST
*PFX* LEN= 18 MAX=
32
MIN=
28
2
264
0.00
XX X
P P P LAST
MIN=
126
MIN=
16
NUMBSEG=
MIN=
66
MIN=
2
NUMBSEG=
MIN=
326
MIN=
2
NUMBSEG=
MIN=
46
MIN=
2
NUMBSEG=
FORM LOG CHLD
OR
INSRT
PNTR RULES
VAR LEN
PFX+MAX=
126
PFX+MIN=
94
VAR LEN
PFX+MAX=
614
PFX+MIN=
567
VAR LEN
PFX+MAX=
50
PFX+MIN=
46
VAR LEN
3
11
3
45
271
8174ch07.fm
DSET
DSETRMK .
AREA
AREARMK .
SEGM
CAPXSEGM.
SEGMRMK .
FLD
FLDRMK
MAR
MARRMK
PROP
LCHILD
LCHRMK
"
"
"
LCH2IDX .
XDFLD
XDFLDRMK.
MAP
MAPRMK
CASE
CASERMK .
CFLD
CFLDRMK .
CMAR
CMARRMK .
CPROP
DBDVEND .
272
6 4
8 4
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
12
12
14
14
17
17
17
20
22
22
24
24
26
26
28
28
96
264
40
264
376
32
264
904
264
704
264
304
72
264
24
200
264
520
264
656
264
904
264
704
264
304
4000
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
XX X
XX X
XX X
P P P
XX X
XX X
P P P
XX X
P P P
XX X
P P P
XX X
XX X
XX X
XX X
P P P
P P P
XX X
XX X
P P P
P P P
XX X
XX X
P P P
P P P
XX X
XX X
P P P
P P P
XX X
XX X
P P P
P P P
XX X
XX X
P P P
P P P
XX X
XX X
P P P
P P P
XX X
XX X
P P P
P P P
XX X
P P P
P P P
P P P
P P P
P P P
P P P
P P P
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
26 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
26 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
42 MAX=
MIN=
*PFX*
LEN=
18 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
30 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
30 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
34 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
26 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
30 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
30 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
30 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
30 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
96 PFX+MAX=
70 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
40 PFX+MAX=
26 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
376 PFX+MAX=
341 PFX+MIN=
VAR LEN
32 PFX+MAX=
28 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
904 PFX+MAX=
836 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
704 PFX+MAX=
640 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
304 PFX+MAX=
264 PFX+MIN=
VAR LEN
72 PFX+MAX=
56 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
24 PFX+MAX=
20 PFX+MIN=
VAR LEN
200 PFX+MAX=
184 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
520 PFX+MAX=
264 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
656 PFX+MAX=
400 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
904 PFX+MAX=
836 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
704 PFX+MAX=
640 PFX+MIN=
VAR LEN
264 PFX+MAX=
20 PFX+MIN=
VAR LEN
304 PFX+MAX=
264 PFX+MIN=
VAR LEN
4000 PFX+MAX=
64 PFX+MIN=
286
42
122
96
286
42
66
52
286
42
418
383
50
46
286
42
934
866
286
42
734
670
286
42
326
286
106
90
286
42
46
42
226
210
286
42
550
294
286
42
686
430
286
42
934
866
286
42
734
670
286
42
326
286
4022
86
8174ch07.fm
DBDSXXX .
32
135
0.00
XX X
P P P
LAST
VAR LEN
135 PFX+MAX=
157
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 22 MAX=
135 PFX+MAX=
157
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 22 MAX=
135 PFX+MAX=
157
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 22 MAX=
135 PFX+MAX=
157
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 22 MAX=
128 PFX+MAX=
150
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 50 MAX=
88 PFX+MAX=
138
MIN=
72 PFX+MIN=
122
VAR LEN
*PFX* LEN= 22 MAX=
264 PFX+MAX=
286
MIN=
20 PFX+MIN=
42
VAR LEN
*PFX* LEN= 30 MAX=
288 PFX+MAX=
318
MIN=
208 PFX+MIN=
238
VAR LEN
*PFX* LEN= 22 MAX=
264 PFX+MAX=
286
MIN=
20 PFX+MIN=
42
VAR LEN
*PFX* LEN= 30 MAX=
328 PFX+MAX=
358
MIN=
320 PFX+MIN=
350
VAR LEN
*PFX* LEN= 22 MAX=
264 PFX+MAX=
286
MIN=
20 PFX+MIN=
42
VAR LEN
*PFX* LEN= 26 MAX=
40 PFX+MAX=
66
MIN=
20 PFX+MIN=
46
VAR LEN
*PFX* LEN= 22 MAX=
264 PFX+MAX=
286
MIN=
20 PFX+MIN=
42
SNDIXD
VAR LEN
*PFX* LEN= 22 MAX=
48 PFX+MAX=
70
MIN=
36 PFX+MIN=
58
*LC** DBDPSB
DFSCX000 INDX LAST
*XFD* DBD2PSB SECONDARY INDEXED FIELD
**SRCSEG** **SAME**
**SEARCH** IMSNAME
8
29
PSBNAME
8
37
TSVERS
13
13
**SUBSEQ** /SX1
8
1
VAR LEN
*PFX* LEN= 22 MAX= 4000 PFX+MAX=
4022
MIN=
64 PFX+MIN=
86
VAR LEN
*PFX* LEN= 22 MAX=
135 PFX+MAX=
157
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 22 MAX=
135 PFX+MAX=
157
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 22 MAX=
135 PFX+MAX=
157
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 22 MAX=
128 PFX+MAX=
150
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 26 MAX=
135 PFX+MAX=
161
MIN=
32 PFX+MIN=
58
VAR LEN
*PFX* LEN= 22 MAX= 4000 PFX+MAX=
4022
MIN=
64 PFX+MIN=
86
VAR LEN
*PFX* LEN= 26 MAX=
128 PFX+MAX=
154
MIN=
32 PFX+MIN=
58
VAR LEN
*PFX* LEN= 22 MAX=
128 PFX+MAX=
150
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 22 MAX=
128 PFX+MAX=
150
MIN=
32 PFX+MIN=
54
VAR LEN
*PFX* LEN= 26 MAX=
128 PFX+MAX=
154
MIN=
32 PFX+MIN=
58
VAR LEN
*PFX*
DBDPXXX .
33
135
0.00
XX X
P P P
LAST
DBDRES1 .
34
135
0.00
XX X
P P P
LAST
DBDRES2 .
35
135
0.00
XX X
P P P
LAST
DBDHXXX .
36
128
0.00
XX X
P P P
LAST
PSB
37
88
0.00
XX X
P P P
LAST
PSBRMK
38
37
264
0.00
XX X
P P P
LAST
PCB
39
37
288
0.00
XX X
P P P
LAST
PCBRMK
40
39
264
0.00
XX X
P P P
LAST
SS
41
39
328
0.00
XX X
P P P
LAST
SSRMK
42
41
264
0.00
XX X
P P P
LAST
SF
43
41
40
0.00
XX X
P P P
LAST
SFRMK
44
43
264
0.00
XX X
P P P
LAST
DBDXREF .
45
37
48
0.00
XX X
P P P
LAST
SUBSEQUENCE
PSBVEND .
46
37
4000
0.00
XX X
P P P
LAST
PSBSXXX .
47
37
135
0.00
XX X
P P P
LAST
PSBRES1 .
48
37
135
0.00
XX X
P P P
LAST
PSBRES2 .
49
37
135
0.00
XX X
P P P
LAST
PSBHXXX .
50
128
0.00
XX X
P P P
LAST
DBEXXXX .
51
135
0.00
XX X
P P P
LAST
DBESXXX .
52
51
4000
0.00
XX X
P P P
LAST
UXX
53
128
0.00
XX X
P P P
LAST
UXXOXXX .
54
53
128
0.00
XX X
P P P
LAST
UXXHXXX .
55
128
0.00
XX X
P P P
LAST
SXX
56
128
0.00
XX X
P P P
LAST
SXXOXXX .
57
56
128
0.00
XX X
P P P
LAST
LEN=
22 MAX=
MIN=
273
8174ch07.fm
SXXHXXX .
RESERVE1.
RESERVE2.
RESERVE3.
RESERVE4.
58
59
60
61
62
128
0.00
128
0.00
128
0.00
128
0.00
128
0.00
XX X
P P P
XX X
P P P
XX X
P P P
XX X
P P P
XX X
P P P
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
*PFX*
LEN=
22 MAX=
MIN=
LAST
LAST
LAST
LAST
LAST
128 PFX+MAX=
32 PFX+MIN=
VAR LEN
128 PFX+MAX=
32 PFX+MIN=
VAR LEN
128 PFX+MAX=
32 PFX+MIN=
VAR LEN
128 PFX+MAX=
32 PFX+MIN=
VAR LEN
128 PFX+MAX=
32 PFX+MIN=
VAR LEN
128 PFX+MAX=
32 PFX+MIN=
150
54
150
54
150
54
150
54
150
54
150
54
The hierarchical structure of the IMS catalog database is shown in Figure 8-2. Some segment
types were omitted for display reasons, but most of the important ones are shown.
Example 8-1 shows the complete list. To see the complete picture of the catalog database,
import the catalog database DBD (DFSCD001) into IMS Explorer. The source of this DBD is
available in the SDFSSRC data set delivered with IMS since version 12. Instructions for
importing DBDs into IMS Explorer are in 8.6, Using IMS Explorer to capture IMS metadata
on page 302.
Figure 8-2 shows the database structure for the IMS catalog database.
HEADER
(RESOURCE HE ADER)
DBDHXXX
DBD
CAPX
DBD
DBD
RMK
DSETRMK
(REMARK S)
DSET
AREA
FLDRMK
MAR
(DFSMA RSH)
(REMARKS)
PROP
(PROPERTIES)
PSB
PSBRMK
DBDVEND
AR EARMK CAPXSEGM SEGMRMK

(REMARKS)
(REMA RKS)
(REMARKS)
MARRMK
SEGM
RESERVED
FLD
(FIELD)
LCHRMK
LCH2ID X
(REMARK S)
(INDEX NAME)
LCHILD
XDFLD
DBDXREF
PCBRMK
SS
(REMARKS )
(SE NSEG)
MAPRMK
CASE
SSR MK
SF
(REMARKS)
(DFSCASE)
(REMAKRS )
(SENFLD)
CASERMK
CFLD
SFRMK
(REMARKS)
(REMARKS)
(FIELD)
(REMARKS )
(REMARKS)
CMARRMK
(REMARKS)
PSBVEND
MAP
XDFLDRMK
Figure 8-2 Database structure for the catalog database, DFSCD000
(DFSMAP)
CFLDRMK
274
PCB
(REMARKS)
RESERVED
CMAR
(DFSMARSH)
CPROP
(PROPERTIES)
8174ch07.fm
There are five PSBs supplied for access and update to the catalog database:
DFSCPL00
It is used for an initial load of the database (PROCOPT=L).
DFSCP000
It has read-only access (PROCOPT=G) for all segments. This PSB can be used for
Assembler and COBOL programs for direct read-only access to the catalog database.
DFSCP001
It has update access (PROCOPT=A) for all segments. This PSB can be used for
Assembler and COBOL programs for direct update access to the catalog database.
DFSCP002
It has read-only access (PROCOPT=G) for all segments. This PSB is used for PL/I
programs for direct read-only access to the catalog database.
DFSCP003
It has read-only access (PROCOPT=G) for all segments. This PSB is used for PASCAL
programs for direct read-only access to the catalog database.
There are several segments in the catalog database, including DBDVEND and PSBVEND, in
the database definition for IBM tools and vendor products to store additional information.
There are also several reserved segments in the database to allow for future expansion.
Most of the segment types (including DBD, DSET, AREA, SEGM, FLD, LCHILD, XFLD)
contain metadata about the specific element that they represent. The data also includes the
name of the segment corresponding to the metadata stored.
Other segments (DBDRMK, DSETRMK, AREARMK, SEGMRMK, MAPRMK, CASERMK)
contain remarks about the element definition.
The CAPXDBD and CAPXSEGM segments contain information about Data Capture exit
routines used.
8.3 IMS catalog database installation and management

The IMS catalog is implemented as a HALDB database. IMS normally requires each HALDB
database to be registered in the Database Recovery Control (DBRC). There are companies
who choose not to use DBRC in some of their environments. Therefore, a method is provided
to define the IMS catalog without the need to register the database in the RECON.
In this section, we describe the following steps for installation and management of the IMS
catalog:
Installation
IMS catalog initial data population
ACB generation and changes
IMS Catalog Copy utility
Keeping multiple versions of metadata in the catalog
IMS Catalog Record Purge utility
Automatically creating the IMS catalog database data sets
Using the IMS catalog without DBRC
Aliases and sharing
Definitions needed for the IMS catalog
275
8174ch07.fm
IMS provides a number of new utilities to maintain the catalog database when databases or
PSB definitions are changed as part of your normal application development lifecycle.
8.3.1 Installation
The first step of the installation of the IMS catalog is to copy the supplied catalog DBD and
PSB members from the SDFSRESL data set to your own DBD and PSB libraries. See
Example 8-2 for JCL to perform this copy.
The source for the catalog DBD and PSBs is shipped for reference in the IMS source library
SDFSSRC. However, the object code in SDFSRESL must be used for execution.
Example 8-2 Copy the supplied DBD and PSB members to your own libraries
//CPYCMEM EXEC PGM=IEBCOPY
//SDFSRESL DD DSN=IMS12.SDFSRESL,DISP=SHR
//DBDLIB
DD DSN=IMS12.IMS12X.DBDLIB,DISP=SHR
//PSBLIB
DD DSN=IMS12.IMS12X.PSBLIB,DISP=SHR
//SYSIN
DD *
COPY OUTDD=DBDLIB,INDD=((SDFSRESL,R))
SELECT MEMBER=(DFSCD000,DFSCX000)
COPY OUTDD=PSBLIB,INDD=((SDFSRESL,R))
SELECT MEMBER=(DFSCPL00,DFSCP000,DFSCP001,DFSCP002,DFSCP003)
After the DBDs and PSBs are copied to your libraries, you need to build them as ACBs by
using the traditional ACB process as shown in Example 8-3.
Example 8-3 ACBGEN for IMS catalog
// JCLLIB ORDER=IMS12.PROCLIB
// EXEC ACBGEN
//SYSIN
DD *
BUILD PSB=(DFSCPL00)
BUILD PSB=(DFSCP001)
Next, create the catalog database data sets. The space allocated for the catalog database
needs to be sufficient to store the number of DBD and PSB definitions for your environment.
This creation can be done in three ways:
The database data sets can be allocated with the job control language (JCL) similar to
what is shown in Example 8-4.
The IMS Catalog Partition Definition Data Set utility (DFS3UCD0) can be used to create
the catalog partition definition database data set if DBRC is not in use. It also creates the
database data sets for the catalog database.
The IMS Catalog Populate utility (DFS3PU00) is used to load or insert records into the
catalog database, whether DBRC is used for the catalog database or not. If any of the
database data sets do not exist, the utility creates them. The size parameters used for
automatic creation are specified in the catalog section of the DFSDFxxx procedure library
(PROCLIB) member.
Example 8-4 shows the process of defining the database data sets and indexes.
Example 8-4 Define the HALDB data sets, the ILDS, and the primary and secondary indexes
//PHIDAM EXEC PGM=IDCAMS
276
8174ch07.fm
//SYSPRINT DD SYSOUT=*
ALLOCATE DSNAME('IMS12.IMS12X.DFSCDI2D.A00001') FILE(A00001) RECFM(F,B,S) DSORG(PS) NEW CATALOG SPACE(2,2) CYLINDERS VOLUME(SBOXI5) UNIT(SYSALLDA)
ALLOCATE DSNAME('IMS12.IMS12X.DFSCDI2D.B00001') FILE(B00001) RECFM(F,B,S) DSORG(PS) NEW CATALOG SPACE(2,2) CYLINDERS VOLUME(SBOXI5) UNIT(SYSALLDA)
ALLOCATE DSNAME('IMS12.IMS12X.DFSCDI2D.C00001') FILE(C00001) RECFM(F,B,S) DSORG(PS) NEW CATALOG SPACE(2,2) CYLINDERS VOLUME(SBOXI5) UNIT(SYSALLDA)
ALLOCATE DSNAME('IMS12.IMS12X.DFSCDI2D.D00001') FILE(D00001) RECFM(F,B,S) DSORG(PS) NEW CATALOG SPACE(2,2) CYLINDERS VOLUME(SBOXI5) UNIT(SYSALLDA)
DEFINE CLUSTER(NAME('IMS12.IMS12X.DFSCDI2D.L00001') FREESPACE(80 10) SHAREOPTIONS(3 3) KEYS(9 0) RECORDSIZE(50 50) SPEED CYLINDERS(1,1) VOLUMES(SBOXI5)) DATA(CONTROLINTERVALSIZE(4096)) INDEX(CONTROLINTERVALSIZE(2048))
DEFINE CLUSTER(NAME('IMS12.IMS12X.DFSCDI2D.X00001') INDEXED KEYS(16,5) VOL(SBOXI5) REUSE RECORDSIZE (22,22)) DATA(CONTROLINTERVALSIZE(4096))
//PSINDEX EXEC PGM=IDCAMS
DEFINE CLUSTER (NAME('IMS12Q.IMS12X.DFSCXI2D.A00001') INDEXED SHAREOPTIONS(3 3) KEYS(37,45) REUSE RECORDS(5,5) VOL(SBOXI5) RECORDSIZE(82,82)) DATA(CONTROLINTERVALSIZE(4096))
After the database data sets are created, you need to update the IMS.PROCLIB(DFSDFxxx)
member to define the catalog parameters for your IMS system. There are two sections to be
added to the member, depending on which of the following configurations you choose to use:
A unique IMS catalog for each system.

A unique DFSDFxxx member for each system.
A shared IMS catalog.
A shared DFSDFxxx member.
Example 8-5 shows the simplest environment: a single IMS with a single catalog prefixed with
the default name DFSC.
Example 8-5 IMS.PROCLIB(DFSDFxxx) for a single IMS system
*--------------------------------------------------------------------*
* IMS CATALOG SECTION
*
*--------------------------------------------------------------------*
<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
Example 8-6 shows a shared DFSDFxxx member with a separate IMS catalog for each IMS
system (defined with an ALIAS that matches the IMSID). We explain the use of aliases for the
IMS catalog in 8.3.9, Aliases and sharing on page 284.
277
8174ch07.fm
Example 8-6 IMS.PROCLIB(DFSDFxxx) for multiple IMS systems

*--------------------------------------------------------------------*
* IMS CATALOG SECTION for IMS I12B *
*--------------------------------------------------------------------*
<SECTION=CATALOGI12B>
CATALOG=Y
ALIAS=I12B
*--------------------------------------------------------------------*
* IMS CATALOG SECTION for IMS I12D *
*--------------------------------------------------------------------*
<SECTION=CATALOGI12D>
CATALOG=Y
ALIAS=I12D
The catalog can be activated, by using the new DFSDFxxx member, with a cold start, warm
start, or even an emergency restart of the IMS system. The restart is required because IMS
only reads the DFSDF member during initialization.
8.3.2 IMS catalog initial data population

After you define the IMS catalog database data sets, you need to run a new utility to read the
IMS ACBLIB to initially load (populate) the IMS catalog database. As is usual for all new
releases of IMS, the ACBLIB needs to be rebuilt from the DBD and PSB libraries. This rebuild
is done by using the type-1 ACB generation utility for the new release before the ACBLIB is
used, including populating the catalog. The catalog populate process might need to be done
only one time for each system using that IMS catalog.
You start by defining the IMS catalog database either to DBRC, or with the non-DBRC utility.
When using DBRC, this process can be done with the batch DBRC utility (DSPURX00), by
using the INIT.DB and INIT.PART commands for the catalog database. Or, the catalog
populate process can be done by using the IMS
Partition Definition Utility (PDU) application in the Time Sharing Option (TSO).
DBRC registration is optional. For more information when DBRC is not used, see 8.3.8,
Using the IMS catalog without DBRC on page 283.
The initial data population of the IMS catalog is done by using a new utility, the
IMS Catalog Populate utility (DFS3PU00), as shown in Figure 8-3.
278
8174ch07.fm
DFSDFxxx member
in IMS.PROCLIB
Catalog Definition
DBRC comman ds
ACBLIB
Catalog
DBDLIB
Populate
Cata log
Utility
PS BLIB
Figure 8-3 IMS Catalog Populate utility (DFS3PU00)
The utility reads the IMS.PROCLIB(DFSDFxxx) member, then builds the IMS catalog from the
ACB libraries referenced in the JCL. The utility also reads the DBD and PSB libraries to
capture the information about any generalized sequential access method (GSAM) DBDs. This
method is used because they are not built as ACB library members.
After execution, a HALDB REORG record is recorded in the RECON.
The IMS Explorer allows us to add application metadata to these database definitions. This
process is needed because, at this stage, the IMS catalog holds only the rudimentary
information that is available from the DBD and PSB definitions. For details about this process,
see 8.5, The role of the IMS Enterprise Suite Explorer for Development on page 299.
Example 8-7 shows the JCL used to populate an IMS catalog from the current
ACB libraries.
Example 8-7 Running the IMS Catalog Populate utility (DFS3PU00)
//LOADCAT EXEC PGM=DFS3PU00,
// PARM=(DLI,DFS3PU00,DFSCPL00,,,,,,,,,,,Y,N,,,,,,,,,,,,'DFSDF=12D')
//STEPLIB DD DSN=IMS12.SDFSRESL,DISP=SHR
//DFSRESLB DD DSN=IMS12.SDFSRESL,DISP=SHR
//IMS
DD DSN=IMS12.IMS12X.PSBLIB,DISP=SHR
//
DD DSN=IMS12.IMS12X.DBDLIB,DISP=SHR
//PROCLIB DD DSN=IMS12.PROCLIB,DISP=SHR
//SYSABEND DD SYSOUT=*
//IEFRDER DD DISP=(,CATLG),DSN=IMS12.IMS12X.PU000.LOG(+1),
// SPACE=(TRK,(5,5),RLSE),UNIT=SYSALLDA
//DFSVSAMP DD DSN=IMS12.PROCLIB(DFSVSMDB),DISP=SHR
//IMSACB01 DD DSN=IMS12.IMS12D.ACBLIBA,DISP=SHR
//IMSACB02 DD DSN=IMS12.IMS12D.ACBLIB.DOPT,DISP=SHR
279
8174ch07.fm
8.3.3 ACB generation and changes

After you migrate to an IMS system that is using an IMS catalog, you need to keep the ACB
libraries and the catalog synchronized. IMS uses time stamps to ensure consistency. With
timestamps, you can ensure that the catalog data can always be trusted as an accurate
equivalent of the metadata that is held in the DBD, PSB, and ACB libraries.
There is a new ACB Generation and IMS Catalog Populate utility (DFS3UACB). This utility is
used to perform both the generation of ACB members in an IMS.ACBLIB data set and the
creation of the corresponding metadata records in the IMS catalog in a single job step. This
process is shown in Figure 8-4. The DFS3UACB utility can be used in load mode to initially
populate the catalog, or in update mode to add a version of the new or changed definitions. In
update mode, a new version of any changed definitions are created in the catalog, rather than
altering the existing definitions in the catalog.
When the utility is run in load mode, all existing records in the IMS catalog are discarded.
Figure 8-4 shows the ACB Generation and IMS Catalog Populate utility.
PSBLIB
DBDLIB
ACBGEN
and
Catalog
Populate
ACBLIB
Catalog
DFSDFxxx
Figure 8-4 ACB Generation and IMS Catalog Populate utility
The new ACB Generation utility writes logs. If the IMS catalog is defined in DBRC, it updates
the RECON. It can run as a batch message program (BMP) or DLIBATCH utility. If it is run as
a BMP, ensure that the catalog database is opened by IMS for update access. Usually, IMS
opens the catalog database in read-only mode.
8.3.4 IMS Catalog Copy utility

Once you migrate to an IMS catalog, you need to ensure that the IMS catalog is updated
every time you update the IMS ACB library. When you migrate applications from one
environment to another, from the test through to production for example, the new IMS Catalog
Copy utility can be used to keep the metadata synchronized. This utility allows the export and
import of metadata information between catalogs:
The utility DFS3CCE0 exports from a catalog and the ACBLIB, DBDLIB, or PSBLIB
libraries.
280
8174ch07.fm
This utility copies an IMS catalog and any included ACB, DBD, and PSB libraries to export
data sets in the same job step.
The utility DFS3CCI0 imports from the export data set into another catalog, ACBLIB,
DBDLIB, and PSBLIB libraries.
At the destination environment, the import module DFS3CCI0 loads or updates an IMS
catalog. The module also copies any included ACB, DBD, and PSB libraries from the export
data sets into their destination data sets.
For the import function of the IMS Catalog Copy utility, the primary input to the utility is a data
set that contains the new copy of the IMS catalog. A CCUCATIM data definition (DD)
statement is required to identify this data set.
If the ACB libraries, DBD libraries, and PSB libraries were copied during the export function,
they are identified in the import JCL by the following DD statements:
CCUACBIM DD statement for the ACB library export data set
CCUDBDIM DD statement for the DBD library export data set
CCUPSBIM DD statement for the PSB library export data set
The new utilities ensure that the updates to the ACB libraries result in parallel updates to the
IMS catalog.
Optionally, the IMS Catalog Copy utility can also create copies of the ACB, DBD, and PSB
library members that correspond to the IMS catalog records that are copied.
The IMS Catalog Copy utility creates an import statistics report for the record segments to be
loaded or updated in the IMS catalog. When the Catalog Copy utility runs in analysis-only
mode, the report reflects only certain statistics. The report reflects only the potential statistics
if the IMS catalog were loaded or updated from the ACB libraries that are currently used as
input to the utility.
The IMS Catalog Copy utility can be run as either a batch job or as an online BMP.
8.3.5 Keeping multiple versions of metadata in the catalog

The catalog is designed to hold multiple versions of the DBD and PSB metadata. The
information in the IMS catalog is timestamped. IMS uses these timestamps to allow multiple
versions of the metadata to be kept.
The catalog section of the DFSDFxxx PROCLIB member specifies the IMS-wide default
values for the retention of metadata in the catalog. The parameters define the maximum
number of generations and the minimum retention period for which information is to be kept in
the catalog. This specification is similar to the way that information is stored by DBRC in the
RECON to keep records of a number of Image Copy sets. However, the information is not
automatically purged, as it is with DBRC. The DBDs and PSBs are only deleted by the
IMS Catalog Record Purge utility (DFS3PU10). The retention parameters for specific
databases can be specified with DFS3PU10.
The following two parameters are used to control the optional RETENTION statement in the
DFSDFxxx catalog section: VERSIONS=nnn and DAYS=ddd:
VERSIONS defines the maximum number of versions of a DBD or PSB to be kept in the
IMS catalog database. The value can be from 1 to 65535; the default value is 2. When the
maximum value is reached, the oldest version (based on the ACBGEN time stamp) is
replaced by the newest.
281
8174ch07.fm
DAYS defines the minimum number of days a version remains in the catalog. The value
can be from 0 to 65535; the default value is 0 (function disabled). When a version of the
catalog metadata is older that the specified version, it becomes a candidate for removal. It
might be removed when new versions of the same DBD or PSB are added to the
IMS catalog.
These parameters work in the same way that GENMAX and RECOVPD work with DBRC: If
the maximum number of versions is reached but the retention period has not expired, a new
catalog record is kept. The oldest record is not removed.
Example 8-8 shows the specification in the IMS.PROCLIB(DFSDFxxx) member, where at
least five generations of metadata is kept, for a minimum of 30 days.
Example 8-8 Setting default maximum generations and retention periods for catalog metadata
<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
RETENTION=(VERSIONS=5,DAYS=30)
With multiple versions stored in the catalog, if an online change is reversed, the catalog might
still have the previous version available.
For logically related databases, where in the past the DBD information is kept only in the
DBDLIB and not the ACBLIB, the Catalog Populate utility sets the timestamp to zero. The
timestamp is set to zero until the combined ACBGEN/Populate utility runs for those
databases.
Metadata information in the catalog can be removed by the IMS Catalog Record Purge utility
(DFS3PU10) if it is outdated or if the version exceeds the specified retention value. When
using DFS3PU10, the default of two versions applies. If no retention value is specified, each
execution of ACBGEN or Populate Utility adds a version.
8.3.6 IMS Catalog Record Purge utility

The IMS Catalog Record Purge utility (DFS3PU10) provides several functions:
Sets the record retention criteria for specific DBD and PSB records in the catalog
database.
Produces a list of DBDs and PSBs with versions that are no longer needed according to
the current retention criteria for each record.
Purges specific versions (based on the ACB time stamp) of a record for a DBD or PSB
resource from the IMS catalog database.
Purges unnecessary versions of IMS catalog records from the catalog database based on
criteria that you specify.
8.3.7 Automatically creating the IMS catalog database data sets

Use the DFSDFxxx member of the IMS PROCLIB data set to specify processing options for
the IMS catalog. The DFSDFxxx member contains parameters organized into sections.
Example 8-9 shows the specify options for the IMS catalog. In a data sharing environment,
this section defines the IMS catalog for all IMS systems that are not individually configured
with a CATALOGxxxx section.
282
8174ch07.fm
Example 8-9 IMS catalog parameters in DFSDFxxx

<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
/* IXVOLSER=vvvvvv if DFSMS is not used */
DATACLAS=IMSDATA
MGMTCLAS=EXTRABAK
STORCLAS=IMS
SPACEALLOC=500
The additional parameters allow us to define the DFSMS DATALCLAS, MGMTCLAS,

STORCLAS, or volume serial number if DFSMS is not used.
Parameter SPACEALLOC=nnnn (with a range of 0 to 9999; the default is 500) also allows us
to define the space as a percentage of the predefined IMS value.
8.3.8 Using the IMS catalog without DBRC

The IMS catalog database is a standard PHIDAM database. Usually, that requires registration
to DBRC. DBRC tracks the logs used when the database is updated. DBRC can also be used
to generate jobs to perform image copies and accumulate changes with the
IMS Change Accumulation utility.
You might be running your IMS system with non-HALDB databases that are not registered to
DBRC (which is a common configuration for test systems). If the databases are not
registered, IMS does not insist that the catalog HALDB database (and index) is registered in
RECON. If the HALDB is not registered, IMS does not track logs, change accumulations, or
image copies.
The backup, logging, and recovery of the IMS catalog is the responsibility of the user. This
process can be done by running stand-alone IBM MVS utilities or by DFSMShsm backup
and recovery. In some cases, the use of the IMS Catalog Populate utility to rebuild the
database might be the best choice.
To overcome the need for IMS to have the IMS catalog PHIDAM database metadata (normally
stored in the DBRC RECON), IMS has special handling for the IMS catalog. Instead of having
database, partition, and database data set records defined in the RECON, IMS uses dynamic
allocation, the DFSMDA macro, with the TYPE=CATDBDEF statement. This statement
defines the dynamic allocation parameter list for the IMS catalog partition definition data set.
This data set contains the definitions for the catalog HALDBs that are not defined in the
DBRC RECON data set. The DD name of the catalog partition definition data set is
DFSHDBSC.
A new utility DFS3UCD0 is used to create the HALDB partition definition data set. You need
to supply a system input stream (SYSIN) data set to define the data that would normally be
used on the INIT.DB and INIT.PART statements when a database is registered in DBRC.
Example 8-10 shows an example. The structure information is stored in the definition data set
(DFSHDBSC).
Example 8-10 Example SYSIN for DFS3UCD0
HALDB=(NAME=DFSCD000,HIKEY=YES)
PART=(NAME=DFSCD000,
PART=DFSCD01,
DSNPREFX=IMSTESTS.DFSCD000,
283
8174ch07.fm
KEYSTHEX=FFFFFFFFFFFFFFFFFFFFFFFFFFFF)
HALDB=(NAME=DFSCX000,HIKEY=YES)
PART=(NAME=DFSCX000,
PART=DFSCX01,
DSNPREFX(IMSTESTS.DFSCX000)
KEYSTHEX=FFFFFFFFFFFFFFFFFFFFFFFFFFFF)
The next thing you need to add is a statement in the IMS.PROCLIB(DFSDFxxx) member to
define the IMS catalog that is not registered in DBRC (Example 8-11).
Example 8-11 IMS.PROCLIB(DFSDFxxx) definition for a non-DBRC IMS catalog
<SECTION=DATABASE>
UNREGCATLG=DFSCD000
Optionally, to avoid making JCL changes, you can also build a DFSMDA dynamic allocation
macro to define the DFSHDBSC to IMS, as shown in Example 8-12. TYPE=CATDBDEF is a
new specification just for an unregistered IMS catalog database.
Example 8-12 DFSMDA definition
DFSMDA TYPE=INITIAL
DFSMDA TYPE=CATDBDEF,DSNAME=IMS12.IMS12D.CATALOG.DEFDS
DFSMDA TYPE=FINAL
END
8.3.9 Aliases and sharing

In an IMSplex, you have a number of options for how to set up the ACBLIB and the IMS
catalog. You can share or clone the ACB libraries ACBLIBA or ACBLIBB. Similarly, the IMS
catalog can be shared, or it can use a separate IMS catalog for each IMS system.
The way that ACB libraries in IMS 10 or IMS 11 are used depends on whether you are using
local, global, and member online changes. IMS 12 and later supports these configuration
options, and you can configure the IMS catalog to participate with your existing shared or
discrete ACB libraries. The IMS catalog can be shared between multiple IMS systems.
Tip: Convert your systems to use global online change, which dynamically allocates ACB
libraries and the use of member online change.
284
8174ch07.fm
Figure 8-5 shows the migration of a system from an IMSplex where each IMS has its own
cloned ACB library pair. However, we also introduce a single shared IMS catalog populated
from all the existing ACB libraries.
IMS1
ACBLIBA
DFSDF member
<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
ACBLIBB
ACBLIBA
Catalog
IMS2
ACBLIBA
ACBLIBB
ACBLIBB
DFSDF member
<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
DFSDF member
<SECTION=CATAL OG>
CATALOG=Y
AL IAS=DFSC
D FSDF memb er
<SECTION=CATALOG>
C ATALOG=Y
ALIAS=DFSC
IMS3
ACBLIBA
IMS4
ACBLIBB
Figure 8-5 Multiple IMS, cloned ACBLIB, and shared IMS catalog
Figure 8-6 shows a system where we are starting from separate (cloned)
ACB libraries. We chose to create a unique aliased IMS catalog for each IMS system.
285
8174ch07.fm
IMS1
ACBLIBA
DFSDF member
<SECTION=CATALOG>
CATALOG=Y
ALIAS=IMS1
ACBLIBB
Catalog
(IMS1)
ACBLIBA
IMS2
Catalog
(IMS3)
Catalog
(IMS2)
IMS3
ACBLIBA
ACBLIBB
ACBLIBB
DFSDF membe r
<SECTION=CATALOG>
CATAL OG=Y
ALIAS=IMS2
DFSDF member
<SECTION=CATALOG>
CATALOG=Y
ALIAS=IMS3
Catalog
(IMS4)
DFSDF member
<SECTION=CATALOG>
CATALOG=Y
ALIAS=IMS4
ACBLIBA
IMS4
ACBLIBB
Figure 8-6 Multiple IMS, cloned ACBLIB, and one IMS catalog for each IMS
Figure 8-7 shows the integrated system, where there is one pair of ACB libraries for the
IMSplex and a single shared IMS catalog (registered in DBRC with SHARELVL=3). In this
system, global online change and member online change are used.
IMS1
DFSDF member
<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
ACBLIBA
IMS2
Catalog
ACBLIBA
DFSDF member
<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
DFSDF member
<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
IMS4
Figure 8-7 Multiple IMS, shared ACBLIBs, and shared IMS catalog
286
IMS3
DFSDF member
<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
8174ch07.fm
IMS handles loading the DBDs (DFSCD000 and DFSCX000(, and the PSBs (DFSCP000,
DFSCP001, DFSCP002, and DFSCP003). IMS also makes the internal changes needed
when aliased names. are used.
8.3.10 Definitions needed for the IMS catalog

Before you can have the IMS catalog created and initially loaded with the populate utility, you
need to update the IMS system to use it. The definition is done by adding statements to the
IMS.PROCLIB(DFSDFxxx) member.
You have some flexibility in how to define the CATALOG section in the DFSDFxxx member. A
simple single IMS is shown in Example 8-13 with its suggested ALIAS name.
Example 8-13 Single IMS system
<SECTION=CATALOG>
CATALOG=Y
ALIAS=DFSC
Alternatively, if you have two or more IMS systems that use shared queues, you might want
them to share a single IMS catalog and the same DFSDFxxx proclib member. In this case,
you can define different section suffixes in the CATALOG statement by using the IMS ID. And
you can define the catalog database with a single shared ALIAS name. See Example 8-14.
Example 8-14 Multiple IMS systems
<SECTION=CATALOGI12A>
CATALOG=Y
ALIAS=I12Q
<SECTION=CATALOGI12C>
CATALOG=Y
ALIAS=I12Q
8.4 Application use of the catalog

IMS 12 and later can access the IMS catalog when IMS metadata is required. IMS also
provides a user interface to the IMS catalog data and a new DL/I call to access the IMS
catalog. One source of metadata for populating the catalog is the DBDs and PSBs. The
extensions of the metadata information and the additional data manipulation possibilities that
are introduced require additional information than was possible with the DBD and PSB
sources prior to IMS 12. As a result, several DBDGEN and PSBGEN macros were enhanced
with IMS 12.
We provide details about using the IMS catalog in the following sections:
DBD and PSB source changes

Get Unique Record DL/I call
IMS catalog access
SSA enhancements
287
8174ch07.fm
8.4.1 DBD and PSB source changes

There were new DBDGEN statements in IMS 12 and changes to existing ones. The new and
changed statements extend the metadata information available to the catalog. Much of this
metadata information is the basis for the extended Object exploitation by the Java language.
DFSMARSH statement in the DBD

The DFSMARSH statement in a DBD defines the marshalling attributes for field data. The
DFSMARSH statement must immediately follow the FIELD statement to which it applies. You
can use the DFSMARSH statement to specify the following data marshalling attributes for the
data contained in a field:
You can specify the code page or character encoding that defines the character data in a
field.
You can specify a data-conversion routine for IMS to use when converting field data. For
example, use it when converting field data from the data type that IMS uses to physically
store data, to a data type expected by an application program.
You can specify whether a numeric data type is signed or not with the ISSIGNED
parameter.
The pattern to use for dates and times can be specified with the PATTERN parameter.
You can specify the properties that are used with a user-provided data-conversion routine.
The MAR segment type in the catalog database contains information about a field marshaller
definition in an IMS database. Each FLD segment can have a MAR child segment that
contains data marshalling properties for that field. The following information in this segment
type is generated from the input parameters of the DFSMARSH statement of the
DBDGEN utility:
ENCODING
Specifies the default encoding of all character data in the database defined by this DBD.
Default ENCODING is CP1047 (EBCDIC). This default value can be overridden for
individual segments and fields.
USERTYPECONVERTER
Specifies the fully-qualified Java class name of the user-provided Java class to be used for
type conversion.
INTERNALTYPECONVERTER
Specifies the internal conversion routine that IMS uses to convert the IMS data into Java
objects for Java application programs. IMS requires the specification of either
INTERNALTYPECONVERTER or USERTYPECONVERTER, but not both. Valid values for
the INTERNALTYPECONVERTER parameter include:
ARRAY, BINARY, BIT, BLOB, BYTE, CHAR, CLOB, DOUBLE, FLOAT, INT, LONG,
PACKEDDECIMAL, SHORT, STRUCT, UBYTE, USHORT, UINT, ULONG, XML_CLOB,
and ZONEDDECIMAL.
ISSIGNED
Valid only for DATATYPE=DECIMAL. Valid values are Y (default) or N.
PROPERTIES
Specifies properties for user type converter names with the USERTYPECONVERTER
parameter. These properties are passed to the user type converter.
288
8174ch07.fm
PATTERN
An optional field that specifies the pattern to use for the date, time, and timestamp Java
data types.
The PATTERN parameter applies only when the DATE, TIME, or TIMESTAMP is specified
on the DATATYPE keyword in the FIELD statement. Also, CHAR must be specified on the
INTERNALTYPECONVERTER keyword in the DFSMARSH statement.
DFSMAP statement
The DFSMAP statement enables the alternate mapping of fields within a segment.
The DFSMAP statement defines a group of one or more map cases and relates the cases to
a control field. The control field identifies which map case is used in a particular segment
instance, as shown in Figure 8-8.
Figure 8-8 Several mappings for the same segment
NAME
Defines the name of this map.
DEPENDING ON
External name of the control field within this segment that contains the value that
determines which map case is used for a particular segment instance. If the control field
does not contain a value that corresponds to a CASEID in a DFSCASE statement for this
map, the map is not used for this segment instance.
If the FIELD statement that defines the control field does not explicitly code the
EXTERNALNAME parameter, specify the value of the NAME parameter in the
DEPENDING ON field.
REMARKS
Allow for a comment up to 256 characters long to be recorded in the DBD and the IMS
catalog database.
DFSCASE statement
Many applications allow for several different layouts for the same segment type in an IMS
database. Typically, this configuration is done in COBOL with the REDEFINES statement, and
in PL/I with the DEFINED statement. The corresponding facility in IMS is the DFSCASE
statement, which defines a map case: A conditional mapping of a set of fields in a segment.
Each map case has a name and an identifier (ID). A single segment can be defined with
multiple map cases. The map cases within a segment are grouped by the DFSMAP
statement, which also associates the map cases with their control field.
289
8174ch07.fm
Each map case is defined with a case ID. The case ID is stored in the control field to identify
which case map is used for a particular segment instance. Typically, the control field is
defined at the beginning of the segment, before the DFSMAP statement.
The fields that make up a map case identify the map case that they belong to by the name on
the CASENAME parameter in the FIELD statement. CASENAME is valid and required only to
associate a FIELD statement with the preceding DFSCASE statement that defines the map
case to which this field belongs. The value of CASENAME must match the value specified on
the NAME parameter of the DFSCASE statement.
The ID of a map case is specified on the CASEID parameter. In a segment instance, the ID is
inserted in a control field to indicate which map case is in use:
NAME
Defines the name of this case.
CASEIDTYPE
Defines the data type of the value specified in the CASEID parameter.
MAPNAME
The name of the map that this case belongs to, as specified on the NAME parameter in
the DFSMAP statement.
CASEID
Defines a unique identifier for the case. A segment instance specifies the CASEID value in
a user-defined control field when part or all of the field structure of the segment is mapped
by this case. The CASEID must be unique within the map to which the case belongs.
REMARKS
Allow for a comment of up 256 characters to be recorded in the DBD and the IMS catalog
database.
Enhancements to DBD definition statements

There are a number of enhancements to the statements that are used to describe a database
definition with IMS 12:
Changes to the DBD statement

ENCODING
Specifies the default encoding of all character data in the database that is defined by this
DBD otherwise default ENCODING is CP1047 (EBCDIC). The value can be overridden in
individual segments or fields.
Changes to the SEGM statement

ENCODING
Specifies the default encoding of all character data in the database that is defined by this
DBD otherwise default ENCODING is CP1047 (EBCDIC). The value can be overridden in
individual fields.
EXTERNALNAME
This parameter is used to give a segment an extended (1 - 128 byte) name.
Changes to the FIELD statement

NAME
290
8174ch07.fm
Specifies the name of this field within a segment type. The name must be provided to be
able to search on the field.
For key-sequenced field types and field types that are referenced by an XDFLD statement,
the NAME parameter is required.
For other field types, you can optionally omit the NAME parameter when the
EXTERNALNAME parameter is specified.
PARENT
Specifies the name of a field that is defined as a structure or array in which this field is
contained. Must be the value of the EXTERNALNAME parameter in the definition of the
referenced field.
The referenced field must be defined with either DATATYPE=ARRAY or
DATATYPE=STRUCT.
CASENAME
The name of the map case to which this field belongs.
This parameter is required only to associate a field statement with the preceding
DFSCASE statement that defines the map case.
This parameter must match the value specified on the NAME parameter of the DFSCASE
statement.
DATATYPE
This parameter is an optional value that specifies one of the following external data types
for the field:
ARRAY, BINARY, BIT, BYTE, CHAR, DATE, DECIMAL (with precision and scale),
DOUBLE, FLOAT, INT, LONG, OTHER, SHORT, STRUCT, TIME, TIMESTAMP, and XML.
REDEFINES
This is a field that specifies the name of another field in the segment. The field must be the
same length as the field that is redefined.
The field cannot be an ARRAY or contain an ARRAY.
EXTERNALNAME
This parameter is an optional alias for the NAME= parameter. Java application programs
use the external name to refer to the field.
The EXTERNALNAME parameter is required only when the NAME parameter is not
specified. If the NAME parameter is not specified, you cannot search on this field.
DEPENDSON
This parameter specifies the name of a field that defines the number of elements in a
dynamic array. Referenced fields must precede the field statement that specifies this
parameter.
The name specified must be the value, whether explicitly defined or accepted by default, of
the EXTERNALNAME parameter in the definition of the referenced field.
The DEPENDSON parameter is valid only when DATATYPE=ARRAY is also specified.
The field referenced by the DEPENDSON parameter must be defined with one of the
following DATATYPE values: INT, SHORT, LONG, DECIMAL.
MINOCCURS
Valid for the DATATYPE=ARRAY only, a MINOCCURS is a required numeric value that
specifies the minimum number of elements in an ARRAY. MINOCCURS is invalid for all
other data types.
291
8174ch07.fm
MAXOCCURS
Valid for the DATATYPE=ARRAY only, a MAXOCCURS is a required numeric value that
specifies the maximum number of elements in an ARRAY.
MAXOCCURS must be greater than or equal to MINOCCURS, but not zero.
MAXBYTES
This parameter specifies the maximum size of a field in bytes when the byte-length of the
field instance can vary based on the number of elements in a dynamic array. MAXBYTES
and BYTES are mutually exclusive.
The value of MAXBYTES must be greater than or equal to the maximum total of the byte
values of all fields nested under this field.
The MAXBYTES parameter is required and valid only in the following cases:
The field is defined as a dynamic array.
For a field defined as a static array or for a structure that contains a nested field that is
defined as a dynamic array.
STARTAFTER
This parameter specifies the name of the field that directly precedes this field in the
segment. The name specified must be the value of the EXTERNALNAME parameter in
the definition of the referenced field.
STARTAFTER is required and valid only when the starting position of a field cannot be
calculated. The starting position cannot be calculated because the field is preceded at a
prior offset by a field defined as a dynamic array.
The STARTAFTER parameter cannot be specified on fields that define an array field as a
parent.
RELSTART
This parameter specifies the starting position of a field that is defined as an element of an
array or a structure:
For fields that specify an array field as a parent, RELSTART is required.
For fields that specify a structure as a parent, RELSTART is required only when a
dynamic array precedes the structure at any prior offset in the segment.
RELSTART is the starting byte offset of the field relative to the start of the array or
structure.
Changes to remarks for DBDs and PSBs

The following existing IMS macros are updated to allow up to 256 characters to be stored as a
remark for a DBD or PSB. This update allows the user to specify comments that are stored in
the DBDLIB, PSBLIB, ACBLIB, and IMS catalog. This notation helps to ensure that comments
are not lost if the source is lost:
PSB remarks
PCB, SENFLD, SENSEG
DBD remarks
DBD, SEGM, FIELD, XDFLD, LCHILD, DATASET, AREA
292
8174ch07.fm
8.4.2 Get Unique Record DL/I call

IMS 12 provided a new DL/I call specifically for the IMS catalog. The Get Unique Record
(GUR) call retrieves the metadata for an IMS database description (DBD) or PSB from the
catalog database. To read all the segments in this database record, the GUR call functions
similarly to a Get Unique (GU) call followed by a series of Get Next within Parent (GNP) calls.
This call can only be used to retrieve the metadata definition of an IMS DBD or PSB from the
catalog database.
The GUR call reads an entire database record from the catalog database and returns an XML
document that contains the metadata definition for the requested IMS resource (DBD or
PSB). If the XML document is larger than the IOAREA provided by the application,
subsequent GUR calls can be issued to retrieve the balance of the XML document. This
process is done by passing back a token that was returned by the initial GUR call. The data is
buffered by IMS. This buffering is based on the assumption that the entire XML document is
needed to minimize the processor usage when you ask for subsequent blocks of data to be
returned. The advantage is that you do not need to over-estimate the size of the IOAREA. If
the IOAREA is too small, the call still succeeds and the balance of the data can be requested
without having to reread the catalog database. This new call is designed to simplify access to
the database definition metadata and minimize the processor usage when retrieving it.
If you pass a token with a value of zero, IMS assumes that it is a new GUR call and starts
from the beginning.
DFSDDLT0 and IMS Restructured Extended Executor (REXX) were updated to add special
processing for the IMS catalog and the XML that is returned from a GUR call.
The GUR call builds an entire XML instance document from the information in the catalog
database. Internally, each GUR call with a zero AIBRTKN executes a GU and multiple GNP
calls to read the IMS catalog. When the I/O area is too small for output, the output buffer is
kept. A token is returned in the application interface block (AIB) to allow the application to
resume copying data from the buffer to I/O area on subsequent calls.
GUR reads an entire record. SSAs can be coded starting with the HEADER and then the
DBD or PSB. GUR does not function like GU calls in which you can read a segment with one
qualified SSA, then get a lower level segment with a different SSA.
The GUR call can only be used to access an IMS catalog database, and the call requires the
AIB interface. If an attempt is made to use the GUR call through the ASMTDLI, CBLTDLI, or
PLITDLI interfaces, IMS returns a DE status code.
During initialization, IMS reads the timestamps from the ACBLIB and stores them into the
database control blocks. The GUR call uses the timestamp to find the currently active
member that is used by IMS. Or, the call finds the first record only, when IMS does not have a
timestamp. IMS does not have a timestamp for resources that are not defined to this IMS.
Segment search arguments used with the GUR call

Typically, segment search arguments (SSAs) are needed when using the GUR call, to identify
the database or PSB definition to be retrieved. SSAs are specified on the GUR call in the
same way as other GU calls to IMS, that is, field <relational operator> field-value.
Example 8-15 shows an application program that is using the GUR call to retrieve the
metadata for the S2U1DBD database.
293
8174ch07.fm
Example 8-15 Sample application that uses the GUR DL/I call
Identification division.
program-id. gur.
Environment division.
Data division.
Working-storage section.
01 dli-insert pic x(4) value 'ISRT'.
01 dli-gur
pic x(4) value 'GUR'.
01 dli-gu
pic x(4) value 'GU'.
01 header-ssa.
02 filler
02 filler
pic x(1) value '('.
02 ssa-boolean
02 ssa-field-value pic x(16) value 'DBD
S2U1DBD '.
02 filler
pic x(1) value ')'.
01 AIB.
02 AIBRID
PIC x(8).
02 AIBRLEN
02 AIBRSFUNC
PIC x(8).
02 AIBRSNM1
PIC x(8).
02 AIBRSNM2
PIC x(8).
02 AIBRESV1
PIC x(8).
02 AIBOALEN
02 AIBOAUSE
02 AIBRESV2
PIC x(12).
02 AIBRETRN
02 AIBREASN
02 AIBERRXT
02 AIBRESA1
USAGE POINTER.
02 AIBRESA2
USAGE POINTER.
02 AIBRESA3
USAGE POINTER.
02 AIBRESV4
PIC x(40).
02 AIBRSAVE
02 AIBRTOKN
02 AIBRTOKC
PIC x(16).
02 AIBRTOKV
PIC x(16).
02 AIBRTOKA
OCCURS 2 TIMES PIC 9(9) USAGE BINARY.
01 gur-returned-data pic x(32000).
Linkage section.
1 io-pcb.
3 filler
pic x(60).
1 db-pcb.
3 filler
pic x(10).
3 status-code
pic x(2).
3 filler
pic x(20).
Procedure division using io-pcb db-pcb.
move "DFSAIB "
to AIBRID.
move length of aib to AIBRLEN.
move length of gur-returned-data to AIBOALEN.
move spaces
to AIBRSFUNC.
MOVE "DFSCAT00"
TO AIBRSNM1.
call 'AIBTDLI' using dli-gur aib
gur-returned-data header-ssa.
294
8174ch07.fm
set address of db-pcb to aibresa1.

display '|' status-code '|' db-pcb.
display 'aib return is ' AIBRETRN .
display 'aib reason is ' AIBREASN .
display gur-returned-data.
goback .
End program gur.
The first few lines of the data returned by the GUR call from the program (shown in
Example 8-15), are shown in Example 8-16. The first 56 characters in the IOAREA are not
part of the XML document.
Example 8-16 Sample data returned by a GUR call
_%
?>
> ? >
/> /%?>
`
<ns2:dbd xmlns:ns2="http://www.ibm.com/ims/DBD" dbdName="S2U1DBD
" timestamp="1215015125765" version="02/10/1114.51" xmlSchemaVersion="1"><access dbType="HIDAM"><hidam datxexit="N" pass
word="N" osAccess="VSAM"><dataSetContainer><dataSet ddname="S2U1DB" label="DSG1" searchA="0" scan="3"><block size="0"/>
<size size="0"/><frspc fspf="0" fbff="0"/></dataSet></dataSetContainer></hidam></access><segment imsName="CUSTROOT" name
="CUSTROOT" encoding="Cp1047"><hidam label="DSG1"><bytes maxBytes="76"/><rules insertionRule="L" deletionRule="L" replac
ementRule="L" insertionLocation="LAST"/><pointer physicalPointer="TWINBWD" lparnt="N" ctr="N" paired="N"/></hidam><field
imsDatatype="C" imsName="CUSTNO" name="CUSTOMERNUMBER" seqType="U"><startPos>1</startPos><bytes>4</bytes><marshaller><t
ypeConverter>BINARY</typeConverter></marshaller><applicationDatatype datatype="BINARY"/></field><field imsDatatype="C" n
ame="FIRSTNAME"><startPos>5</startPos><bytes>10</bytes><marshaller encoding="Cp1047"><typeConverter>CHAR</typeConverter>
</marshaller><applicationDatatype datatype="CHAR"/></field><field imsDatatype="C" name="LASTNAME"><startPos>15</startPos
><bytes>20</bytes><marshaller encoding="Cp1047"><typeConverter>CHAR</typeConverter></marshaller><applicationDatatype dat
atype="CHAR"/></field><field imsDatatype="C" name="DATEOFBIRTH"><startPos>35</startPos><bytes>10</bytes><marshaller enco
ding="Cp1047"><typeConverter>CHAR</typeConverter></marshaller><applicationDatatype datatype="CHAR"/></field><field imsDa
tatype="C" name="HOUSENAME"><startPos>45</startPos><bytes>20</bytes><marshaller encoding="Cp1047"><typeConverter>CHAR</t
ypeConverter></marshaller><applicationDatatype datatype="CHAR"/></field><field imsDatatype="C" name="HOUSENUMBER"><start
A better way to display this XML information is through a browser. Example 8-17 shows the
same information as displayed by Microsoft Internet Explorer.
Example 8-17 Sample data returned by a browser
<ns2:dbd xmlns:ns2="http://www.ibm.com/ims/DBD" dbdName="S2U1DBD" timestamp="1215015125765"
version="02/10/1114.51" xmlSchemaVersion="1">
<access dbType="HIDAM">
<hidam datxexit="N" password="N" osAccess="VSAM">
<dataSetContainer>
<dataSet ddname="S2U1DB" label="DSG1" searchA="0" scan="3">
<block size="0" />
<size size="0" />
<frspc fspf="0" fbff="0" />
</dataSet>
</dataSetContainer>
</hidam>
</access>
<segment imsName="CUSTROOT" name="CUSTROOT" encoding="Cp1047">
<hidam label="DSG1">
<bytes maxBytes="76" />
<rules insertionRule="L" deletionRule="L" replacementRule="L" insertionLocation="LAST" />
<pointer physicalPointer="TWINBWD" lparnt="N" ctr="N" paired="N" />
</hidam>
295
8174ch07.fm
<field imsDatatype="C" imsName="CUSTNO" name="CUSTOMERNUMBER" seqType="U">

<startPos>1</startPos>
<bytes>4</bytes>
<marshaller>
<typeConverter>BINARY</typeConverter>
</marshaller>
<applicationDatatype datatype="BINARY" />
</field>
<field imsDatatype="C" name="FIRSTNAME">
<startPos>5</startPos>
<bytes>10</bytes>
<marshaller encoding="Cp1047">
<typeConverter>CHAR</typeConverter>
</marshaller>
<applicationDatatype datatype="CHAR" />
</field>
The XML schemas for the documents returned as responses to this call, are included in the
IMS.ADFSSMPL data set:
DFS3XDBD.xsd (for DBD records)
DFS3XPSB.xsd (for PSB records)
SSAs can be specified only up to the DBD or PSB level in the catalog database
No more than two SSAs can be specified:
One for the root HEADER segment
One for the DBD or PSB segment
Example 8-18 shows the IMS Test Program (DFSDDLT0) statements that are needed to
process a GUR call. The DATA statement is needed to provide sufficient IO-AREA for the
XML document that contains the database definition to be returned to DSFSDDLT0.
Example 8-18 DFSDDLT0 statements for GUR
S 1 1 1 1 1
DFSCD000
AIB
L
GUR HEADER (RHDRSEQ ==DBD
L Z9999 DATA
S2U1DBD )
8.4.3 IMS catalog access

When an IMS application program requires access to the metadata in the catalog, a PSB to
access the catalog database is automatically attached to the PSB that is loaded for the
application. IMS can then use that PSB to access the metadata in the IMS catalog. There is
no need to specifically define the catalog database in your PSB.
Direct catalog interface

An application user can issue a DL/I call by using the PCB that directly references the IMS
catalog DBD if they need to access the metadata.
The application operates as a normal DL/I application. It can, for example, use the new
GUR DL/I call to read the entire record (root and all the child segments) from the IMS catalog.
296
8174ch07.fm
Indirect catalog interface

The indirect catalog interface is used when a process needs access to the metadata, but is
not accessing the IMS catalog directly. The application processes as usual and can issue DL/I
calls with a PSB that does not reference with the catalog DBD. When a process needs access
to the metadata (in the past, the Java class from the DLIMODEL utility was used), IMS
dynamically attaches a PSB with a catalog PCB. Figure 8-9 shows this access.
ACBLIB
Users
Direct
access
DLI
Distributed
Access
(Ja va)
Type 4
PSB
pool
DMB
pool
Catalog PSB
DF SCP001
4 attach
Ims
connect
Catalog PSB
DF SCP001
ODBM
Type 2
Catalog PSB
DF SCP001
MYD
MYDATBAS
Catalog DBD
DF SCD000
Appl DBD
MYDATBAS
Catalog
User PSB
MYPCB
Type 2
WAS
DB2 StoredProc
CICS
Attached PSB
Indirect
access
Figure 8-9 IMS catalog access
The catalog PCB is used by the DL/I engine without any external effects on the calling
application. The normal mode of operation is that you are only reading the IMS catalog with a
PROCOPT=G (read with integrity). The name of the main catalog PCB is DFSCAT00.
For message processing program (MPP) applications (running in an online IMS), the dynamic
attach of a PSB that contains the IMS catalog PCB occurs at the first reference, that is during
the first DL/I call. The database is accessed with deferred scheduling, so the scheduling only
occurs when the first call is made that needs access to the IMS catalog. The IMS catalog
database availability does not affect application availability. If the IMS catalog is offline, you
can get an abend (U3303), but that does not cause the application to terminate.
In a DL/I batch environment, the dynamic attach of the IMS catalog PCB occurs during the
batch initialization. Scheduling is only done once for the batch when the region starts. A batch
job loads the IMS catalog PSB for later reference if the catalog is enabled in the DFSDFxxx
PROCLIB member.
297
8174ch07.fm
8.4.4 SSA enhancements

The new SSA format, get by offset, allows a new search function by offset and length, instead
of field name. Fields are no longer required to be defined in the DBD:
Support is added for DFSDDLT0 and IMS REXX.

Performance is the same as a non-key field search.
IMS scans the database to look for matches.
SSA contains offset and length followed by operator and value.
In Figure 8-10, an SSA search on the field is issued, although the type is not known by the
DBD.
DBD
Field
Labname
Street
State
Offset
1
10
30
Len
5
20
2
Segment name
SSA qualification(s)
Offset
Length
Operator Compare data
COBOL Copybook
Field
Labname
Type
Street
State
Offset
1
6
10
30
Len
5
3
20
2
GU IBMLABS (00000030 00000002=CA)

GU IBMLABS (00000006 0000003=DEV)
Segment
Offset
Length
Figure 8-10 Using get by offset
Field level sensitivity allows the user to change the layout of the segment that is returned in
the I/O area. The fields can be reordered, omitted, or spaces can be added between, as
shown in Figure 8-11. The new SSA qualifications can be used in combination with the
existing SSA qualification format. For example, the following SSA combination is valid for the
fields: labname and type.
GU IBMLABS*O (LABNAME =SVL
&00000006 00000003=DEV)
Segment physically stored on DASD

Employee #
Name
Birthday
Salary
Address
Phone
Segment returned in I/O area

Name
Address
Phone
Figure 8-11 Field sensitivity
In this request, the SSA offset is relative to the physical starting position in the segment that is
visible to your program. If you attempt to search for fields that are outside of the sensitive area
(that is, past the end of the segment), IMS returns an AK status code. If a segment is not
found that matches the SSA qualifications, a GE or GB status code is returned.
298
8174ch07.fm
8.5 The role of the IMS Enterprise Suite Explorer for

Development
The IMS Enterprise Suite Explorer for Development (IMS Explorer) is an Eclipse-based
graphical tool that simplifies many IMS application development tasks. The tool simplifies
tasks such as updating IMS database and program definitions, and by using standard
Structured Query Language (SQL) to manipulate the IMS data.
You can use the IMS Explorer graphical editors to import, visualize, and edit IMS database
and program definitions. You can also use the IMS Explorer to easily access and manipulate
data that is stored in IMS, by using standard SQL.
The IMS Explorer can also directly import DBDs and PSBs, or can obtain existing catalog
information from the IMS catalog via a type 4 connection.
The population of the IMS catalog is mainly done from the PSB and DBD sources. Additional
DBDGEN statements and additional attributes on the FIELD macro can provide more
complete metadata information.
Additional metadata can be collected from COBOL copybooks and PL/I or C include
members. After updating the metadata information in the PSBs and DBDs in the Explorer,
those sources can be sent to the host for the GEN process. This process causes the
metadata to be populated into the IMS catalog.
Figure 8-12 shows how the Explorer is able to interact with the IMS catalog directly, via a type
4 driver connection. Figure 8-12 also shows an interaction with the catalog indirectly, via a
File Transfer Protocol (FTP) import and export.
DBD/PSB/ACB Reversal utility
PSB/DBD
sources
ftp export
EXPLORER
PSB/DBD
sources
ftp import
type4
D BD GEN
PS BGEN
DBDLIB
PSBLIB
ACBLIB
A CB GEN
Populate
utility
Populate
utility
catalog
Cobol/PLI
Copybooks
includes
Distributed z/OS
Figure 8-12 IMS Explorer and catalog
A direct update from the explorer is not available. An intermediate application control block
generation (ACBGEN) with population of the catalog is required.
299
8174ch07.fm
The DLIModel utility is a helpful tool for visualizing the structure of an IMS database. The tool
documents the details of the DBD and PSB sources. The DLIModel utility is required to
produce the com.ibm.ims.db.DLIDatabaseView class for accessing the IMS databases from
Java applications on the remote and local locations. This access is through the type 4 and
type 2 drivers. Both the traditional DL/I SSA and JDBC access can be used.
The DLIModel utility was not changed in Enterprise Suite V2, but its functions were integrated
into the IMS Enterprise Suite Explorer for Development. The IMS Explorer uses the
centralized IMS catalog on IBM z/OS. The metadata that is currently available in the
DatabaseView class is integrated in the IMS catalog. The concept of the IMS catalog makes
the metadata more dynamic and shared. Its implementation avoids the need for distributing
the class to all sites where it might be used in Java programs with DL/I (or JDBC) access. The
access is through the IMS database type 2 and type 4 Universal drivers. The drivers were
adapted to provide this function.
The following features summarize the IBM Enterprise Explorer:
Incorporates DLIModel functionality
Support for migration of DLIModel projects is provided
Provides the following graphical editors for development and visualization:
Data Base Description (DBD)
Program Specification Block (PSB)
Shows a relational view of IMS data with graphical assistance to build SQL statements
The IMS Universal JDBC type 4 connectivity extracts DBD and PSB information for local
enhancement.
Input for the IMS Explorer

The section, 8.5, The role of the IMS Enterprise Suite Explorer for Development on
page 299, explains how the input for the IMS Explorer is taken from local PSB and DBD
sources.
The IMS Explorer can also take input from other sources:
Import of the DLIModel utility project
Remote import
From the IMS catalog
All information about the PSBs and DBDs is consolidated into the IMS catalog. The
Explorer, using the new type 4 driver, can extract PSB and DBD information from the
catalog to be updated locally. After the update, this information is sent back to the
consolidating host by FTP. Figure 8-13 shows the Export panel.
300
8174ch07.fm
Figure 8-13 Export to the z/OS host with FTP
An ACBGEN of the changed PSB or DBD is needed to update the ACBLIB and populate this
updated information to the catalog.
IMS Enterprise Suite Explorer and the IMS catalog

The IMS catalog is a PHIDAM database that contains trusted metadata for IMS databases
and applications. All the information contained in the runtime ACBLIB (from the DBDLIB and
PSBLIB) is available to users in the IMS catalog.
The IMS Explorer is an important tool for using and updating the information in the catalog.
The IMS Explorer can access information from the catalog database, work with it, update it,
and send it back to the IMS on z/OS for consolidation in the catalog.
The following data connections can be used between the Explorer and catalog information:
From z/OS:
FTP import from the DBD and PSB sources
Via type-4 driver direct access to the catalog
To z/OS:
FTP export to the DBD and PSB sources
8.5.1 Extending IMS database definitions with the IMS Explorer

This section describes the extension of an IMS DBD with the IMS Explorer for Development.
Using the IMS Explorer, you can quickly and easily add metadata to the IMS databases. You
can do this from the COBOL copybooks or PL/I include members that are used by application
programs.
301
8174ch07.fm
8.6 Using IMS Explorer to capture IMS metadata

The IMS Explorer facilitates the capture of more metadata for an IMS database than was
previously stored in the IMS DBD. With Explorer, the layout of the data in the database
segments can be captured and added to the DBD. The enhanced DBD can then be
generated back on the host system and included in the catalog. This section details how to
use the IMS Explorer for Development to capture the extra metadata information from the
COBOL copybooks. This section also describes how the enhanced DBD is ready for
generation on the host system.
Before starting, you need to install the IMS Explorer for Development. The code is available
as part of the IMS Enterprise Suite Version 2, freely downloadable from the IMS home page
(http://www.ibm.com/ims). There are several runtime versions of this code. The code needed
for this task is the shell-sharing version. This version installs with the
IBM Installation Manager as an extension to IBM Rational Developer for zSeries or
IBM Rational Developer for zEnterprise.
To begin the process, run Rational Developer for zEnterprise (or Rational Developer for
zSeries), and open the IMS Explorer perspective, as shown in Figure 8-14.
302
8174ch07.fm
Figure 8-14 IMS Explorer perspective in Rational Developer for zEnterprise
To create an IMS Explorer Project, right-click in the Project Explorer window (upper left), and
select New Project to start the Create a New Project wizard (Figure 8-15).
303
8174ch07.fm
Figure 8-15 Create a New Project wizard
The wizard is the IMS Explorer Project wizard. Select this one, and click Next. See
Figure 8-16.
Figure 8-16 IMS Explorer Project
304
8174ch07.fm
Enter a name for the IMS Explorer Project in the pane of Figure 8-17.
Figure 8-17 Name the IMS Explorer Project
When the wizard completes, Rational Developer for IBM System z (RDz) shows the named
project in the Project Explorer window (see Figure 8-18).
305
8174ch07.fm
Figure 8-18 The LGI Application IMS Explorer Project
Next, you must import the DBD for the databases for which you are going to capture the
metadata. To import the DBD, right-click the Explorer Project (in this case, the
LGI Application), and select Import (Figure 8-19).
306
8174ch07.fm
Figure 8-19 Options for an IMS Explorer Project
Select the IMS Resources option, and click Next. See Figure 8-20.
Figure 8-20 Select an import source
307
8174ch07.fm
Enter the name of the project in Figure 8-21.
Figure 8-21 Provide a name for the IMS Resources to be imported
In Figure 8-22, select a location from which the resources are to be imported. The location
can be a file on your local workstation, a file on a host in which you are connected, or an IMS
catalog. Then click Next.
308
8174ch07.fm
Figure 8-22 Select the Import Source of the source to be imported
You can now select the files from the source that you want imported into your project.
Although there are separate radio buttons on this window for DBDs and PSBs, IMS Explorer
can identify the resources in the source file selected. It then lists them in the appropriate list in
this window. IMS Explorer also understands a file of JCL containing multiple DBDs, PSBs, or
a mixture of both, which simplifies the import process.
The first resources to be imported here are DBDs. Click Add DBD, shown in Figure 8-23.
309
8174ch07.fm
Figure 8-23 Select resources from the local file system
Select the file that contains the DBDs to be imported. See Figure 8-24. In this example,
multiple DBDs are in a JCL file which was previously downloaded to the local workstation.
IMS automatically filters out the JCL and imports each of the DBDs in the file.
Figure 8-24 Select the file that contains the resources to be imported
310
8174ch07.fm
The Import IMS Resources window shows the two DBDs (S2U1DBD and S2U1DXD) which
were in the single JCL file that was imported. Any of these DBDs can now be deleted from the
import list if wanted.
To add PSBs to this import, click Add PSB. See Figure 8-25.
Figure 8-25 Keep selecting more files until you are done
As with the DBDs, a single file can contain multiple PSBs, and possibly the JCL used to
generate them. IMS looks for each of the PSBs and DBDs in the file selected and adds each
of them to the import selection.
Select the file that contains the PSBs that you want to import, and click Open. See
Example 8-26.
311
8174ch07.fm
Figure 8-26 Selecting the PSB source to be imported
The Import IMS Resources window shows the two PSBs imported from the single file that
was selected. Any of these DBDs and PSBs can now be removed from the import list by
selecting Delete DBD and then by selecting Delete PSB.
The IMS Explorer also shows any DBDs that still need to be imported to satisfy the databases
referenced in the PSBs to be imported. In this example, the two PSBs reference only the
databases to be imported.
You are now ready to import these DBDs and PSBs into your project. As Figure 8-27 shows,
click Finish.
312
8174ch07.fm
Figure 8-27 Lists of the DBD and PSB resources to be imported
The LGI Databases project now includes the DBDs and PSBs that you imported and several
other artifacts that are needed later. At any time, you can refer to this project to see the DBD
or PSB source which was imported. The project also includes the generated source for the
DBDs and PSBs. At this stage, however, the generated source is the same as the imported
source. The sources are the same because you did not yet add any of the metadata from the
COBOL copybooks or PL/I include members. You do that soon.
To see the current layout of a database, click the arrow at the left of the DBD, to expand the
list of DBDs in your project. See Figure 8-28.
313
8174ch07.fm
Figure 8-28 LGI Databases project, showing the DBD and PSB resources which are imported
You can now see the two DBDs which are imported into your project, S2U1DBD.dbd and
S2U1DXD.dbd. Double-click the S2U1DBD.dbd option, as shown in Figure 8-29, to see the
view of this database.
Figure 8-29 Expanding the DBD Resources view
You can now see the graphical layout of the database, shown in Figure 8-30. The segments in
the S2U1DBD database are shown. The relationships between these segments, and the
fields defined to each of the segments, are also shown.
314
8174ch07.fm
Figure 8-30 The Explorer view of an IMS database
From this window, you can import the rest of the metadata for this database into this IMS
Explorer project. To do this import, right-click the CUSTROOT segment in the graphical view,
and select Import COBOL or PL/I Data Structures. This action opens the window shown in
Figure 8-31.
315
8174ch07.fm
Figure 8-31 Importing database metadata from COBOL or PL/I
To select the file that contains the COBOL or PL/I definition for the segment, click Browse, as
shown in Figure 8-31.
Select the file that contains the COBOL or PL/I definition for the custroot (client) segment, and
click Open, as shown in Figure 8-32.
316
8174ch07.fm
Figure 8-32 Select the file that contains the Copybook or Include member
Figure 8-33 shows the window that displays when you select Open (see Figure 8-32).
Figure 8-33 shows the Import Data Structures window. This panel is where you identify the
data structure to be imported for a database segment.
Figure 8-33 Identify the data structure to be imported for a database segment
In the COBOL copybook you selected, there is only one definition layout. Click Add, as shown
in Figure 8-34, to add this structure as the metadata for the CUSTROOT segment.
317
8174ch07.fm
Figure 8-34 Importing the metadata for a database segment
From here, click Finish to import this segment layout into the database definition for the
CUSTROOT segment. Figure 8-35 shows the expanded definition for this segment in the
database.
Figure 8-35 Explorer database view, with imported metadata for one segment
The same process (right-click the segment, import the COBOL or PL/I copybook, click Add,
then Finish) is used to import the metadata for each of the other segments in the database.
Figure 8-36 shows the database layout with definitions for each of the segments in the
database. The asterisk at the left of the database name (*S2U1DBD.dbd), indicates that the
318
8174ch07.fm
database definition is not yet saved. Select File Save to save the enhanced database
definition to the LGI Database Project.
Figure 8-36 Explorer database view, with imported metadata for all segments
You captured the metadata for the layout of each of the segments in your database. If you
click the expand arrow for DBD Source and Generated Source in your project, the IMS
catalog-enabled DBD source files heading opens. Figure 8-37 shows the enhanced
definitions for the databases in your project.
319
8174ch07.fm
Figure 8-37 The catalog-enabled DBD source
You captured the expanded metadata for these databases. A snippet of the expanded DBD
definition for this database is shown in Figure 8-38.
320

S 274

Uploaded by

Document Informationclick to expand document informationplacas base multiprocesador

Document Informationclick to expand document information

Copyright:

Available Formats

S 274

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

S 274

Uploaded by

Copyright:

Available Formats

8174ch04.

Draft Document for Review October 22, 2013 7:07 pm

Advanced installation support by using the IBM Installation Manager for

5.4.2 The new installation architecture in IMS Enterprise Suite V2.2

IMS Integration and Connectivity Across the Enterprise

Draft Document for Review October 22, 2013 7:07 pm

Figure 5-4 Prior to Enterprise Suite 2.2

Chapter 5. SOAP application technology

Draft Document for Review October 22, 2013 7:07 pm

Figure 5-5 The new architecture

Components of SOAP Gateway:

What is IBM Installation Manager for z/OS?

IMS Integration and Connectivity Across the Enterprise

Draft Document for Review October 22, 2013 7:07 pm

5.4.3 Installing multiple copies of SOAP Gateway

The new installation process

Figure 5-6 SMP/E installation process

Draft Document for Review October 22, 2013 7:07 pm

Figure 5-7 Multiple copies of SOAP Gateway

IMS Integration and Connectivity Across the Enterprise

Draft Document for Review October 22, 2013 7:07 pm

deploy>./iogmgmt -view -sgp

Chapter 5. SOAP application technology

Draft Document for Review October 22, 2013 7:07 pm

An iogmgmt command consists of the iogmgmt statement followed by arguments to specify

Figure 5-8 Screen shot for deploy>./iogmgmt -view -sgp

ES V2.1 SOAP Gateway

ES V2.2 SOAP Gateway

IMS Integration and Connectivity Across the Enterprise

Draft Document for Review October 22, 2013 7:07 pm

ES V2.1 SOAP Gateway

ES V2.2 SOAP Gateway

Callout and business event:

Provider: not copy, but to be embedded in service

5.4.4 Monitoring, tracking, and logging

Draft Document for Review October 22, 2013 7:07 pm

Publish SOAP Gateway monitoring statistics (Monitoring)

Lets talk about monitoring:

iogmgmt mbeans on port 7176

iogmgmt tracking on|-off (-off by default) id messageID|generated|custom

IMS Integration and Connectivity Across the Enterprise

Draft Document for Review October 22, 2013 7:07 pm

IMS Transaction Tracking Provider Scenario

Logs (message ID) +

Monitoring and analyzer tools/client application

Figure 5-9 IMS Transaction tracking Provider scenario

Chapter 5. SOAP application technology

Draft Document for Review October 22, 2013 7:07 pm

SOAP Log Input Message

Figure 5-10 SOAP Gateway Log of a Input Message

IMS Integration and Connectivity Across the Enterprise

Draft Document for Review October 22, 2013 7:07 pm

Figure 5-11 ICONTR Entry in a BPE Trace

iogmgmt tranLog on|-off

In SOAP Gateway we are using either a Vertical or Horizontal ID

Chapter 5. SOAP application technology

Draft Document for Review October 22, 2013 7:07 pm