Using the enterprise service discovery wizard, you create an import
based on an IMS™ application.
You are taken step by step through the generation of the import as well as
shown how to test the import using the integration test client.
Prerequisite: This example uses IVTNO, one of the transactions
used in IMS installation
verification. Most IMS systems will include this transaction. If this transaction
is not installed on your IMS system, and you wish to test the import component
you create, contact your IMS system administrator and have it installed. In this
example, a module already existed called PhoneBook though you could alternately
create the module in the final page of the wizard.
You will follow the pattern you see in these steps when
you create an import component for IMS. You can find a similar step-by-step
example but with multiple outputs in the samples
section.
For more information on the IMS resource adapter, see What is the IMS resource adapter?. However, remember
that you are looking at this information from the Rational® Application Developer perspective.
While in the WebSphere® Integration
Developer, you are using different tools. Nevertheless, for reference material
on IMS,
the Rational Application
Developer material can be helpful.
- Right-click the PhoneBook module and from the pop-up menu
select New > Enterprise Service Discovery. The enterprise
service discovery wizard opens. If you have not added the IMS resource adapter,
- Click Import Resource Adapter. The Connector
Import wizard opens.
- Browse to the appropriate resource adapter from the file system
and path. All resource adapters that come with the product are found in this
path: <installdir>\Resource Adapters. In the case of IMS,
only the JCA 1.5 IMS resource
adapter is supported for use in the creation of import components, so you
must select the RAR file in <installdir>\Resource Adapters\ims15.
- At this time, you may also select a particular name for the
connector project, a specific target server, and specify that your selection
be added to a particular EAR project. Deploying or not deploying the resource adapter in the module discusses
why you might want to add and later deploy your resource adapter with a module.
For this example, do not select Add module to an EAR project.
Click Finish. If asked to change perspectives, select No.

- With your resource adapter added, return to the Select
an Enterprise Service Resource Adapter page, select your resource
adapter and click Next. You may occasionally need to
wait a minute as your workspace is rebuilding in the background following
the import. If you do not see your resource adapter, close the wizard, wait
until the workspace has rebuilt, and then return to the enterprise service
discovery wizard.

- The Resource Adapter Connection Properties page
opens. You can choose between two types of managed connections. The differences
are discussed in Using connection properties specified on a server or specifying them.
For this example, select the Use connection properties specified
on server radio button and specify eis/imsTarget for
the JNDI Lookup Name and widNode/myAlias for the J2C
Authentication Data Entry (the JAAS alias name). The connection factory
with JNDI lookup name eis/imsTarget and the J2C authentication data entry
with name widNode/myAlias may or may not exist on the target server at this
time. For this example, they will be created in a later step.

If you
select Use the following connection properties, then
you will need to provide, at a minimum, the TCP/IP Host name and Port Number
and the IMS Data
store name. This option is illustrated in Creating an import to retrieve undelivered IMS transaction output. Descriptions of these IMS connection properties can be found in Connection properties. As mentioned previously,
remember that you are looking at this information from the Rational Application
Developer perspective. Complete the information and click Next.
- The Add Operations page opens. It is initially
empty.

- Click Add to define an operation and its
input and output types. The Add operation wizard opens.
In our example, we are creating an import component for the IMS transaction,
IVTNO. This transaction processes an IMS database containing phone book data using
commands DISPLAY, ADD, DELETE, and UPDATE. For this example we will define
a single operation called runPhoneBook, which contains the
command to be executed as part of its input message. You will need to specify
an input and an output for your operation.

This page also requests
the input and output types for the operation. The first time you use this
page, there will not be any input types to choose from. Click New next
to the Input type field. The Data Import page
opens.
- The Data Import wizard requests the type of
mapping you want and the source file. Select the mapping you want for the Choose
mapping field, in our case COBOL To Business Object.

Click Browse beside the COBOL
file field and navigate to your COBOL file. Click Next. We used the following COBOL code for our particular example: 01 INPUT-MSG.
02 IN-LL PICTURE S9(3) COMP.
02 IN-ZZ PICTURE S9(3) COMP.
02 IN-TRCD PICTURE X(10).
02 IN-CMD PICTURE X(8).
02 IN-NAME1 PICTURE X(10).
02 IN-NAME2 PICTURE X(10).
02 IN-EXTN PICTURE X(10).
02 IN-ZIP PICTURE X(7).
01 OUTPUT-MSG.
02 OUT-LL PICTURE S9(3) COMP VALUE +0.
02 OUT-ZZ PICTURE S9(3) COMP VALUE +0.
02 OUT-MSG PICTURE X(40) VALUE SPACES.
02 OUT-CMD PICTURE X(8) VALUE SPACES.
02 OUT-NAME1 PICTURE X(10) VALUE SPACES.
02 OUT-NAME2 PICTURE X(10) VALUE SPACES.
02 OUT-EXTN PICTURE X(10) VALUE SPACES.
02 OUT-ZIP PICTURE X(7) VALUE SPACES.
02 OUT-SEGNO PICTURE X(4) VALUE SPACES.
Click Next
- The Importer page opens where you specify
the data structure you will use. Platform and code page are already completed
for you, but you can change them. For an import component that runs an IMS transaction,
you must select z/OS® from
the Platform drop-down list. Click Show Advanced to
reveal the default settings for the z/OS platform. Most of the values can be
accepted without change. However, because most IMS programs are compiled with the TRUNC(BIN)
option, it is recommended that you change the value of the Trunc field
from STD to BIN. Other values might differ
for your environment. For example, you might need to specify a different value
for the Code page field if your IMS data is in a code page other than U.S.
English (037). The value for the Quote field might also differ, depending
on your COBOL source. Click Apply beside the Data
structures field. The wizard analyzes the data structures in the COBOL
file and returns them to the pane. Select the one you want. In our example,
we selected INPUT-MSG for the input. Click Next

- The Saving Properties page opens specifying
the names, styles and folder for the properties. Note that you can choose
to change or create a new module at this point. Remember, at this point nothing
has been generated. The name will be the data structure name if you do not
change it, which in our case is INPUTMSG. Specifying
a folder is recommended since otherwise all generated files will be put in
the root module folder and it will be difficult to manage them. In this sample,
use sample/ims. Generation style lets you specify a variation
of generated names, as indicated by the hover help. Click Finish to
complete the specification of your operation.

- The wizard returns to the Add operation window.
In this IMS example
we will add an output type by selecting Specify an output type radio
button and clicking New. We return to the Import page.
Select the COBOL to Business Object mapping for the Choose
mapping field. Click Browse beside the COBOL file
field and navigate to the same COBOL file used above for the input message.
Note that for output type multiple outputs are possible. Click Next.

- The Importer page opens. Select z/OS from
the Platform drop-down list. Optionally, provide advanced properties.
Click Apply beside the Data structures pane,
then select OUTPUT-MSG and click Next.

- The Saving Properties page opens specifying
the names, styles and folder for the properties. Provide the same values for Module, Folder,
and Generation Style as you provided for the input message. Click Finish to
complete the specification of your operation.

- The wizard returns to the Add operation wizard
page. At this point you could add more output types but for the IMS transaction
IVTNO one input and one output is sufficient. Click Finish.

- The Add Operations page opens. You could at
this point add some more operations. For this example, we will only use one
operation, runPhoneBook. The InteractionSpec class is shown as well
as the InteractionSpec properties. Clicking Show Advanced provides
other properties you may want to specify.

For a complete description
of the properties of IMSInteractionSpec, see IMSInteractionSpec properties. As mentioned
previously, remember that you are looking at this information from the Rational Application
Developer perspective. For this example, we will accept all the default values.
Click Next. Note: Depending on the maintenance
level of the IMS resource
adapter you are using you may have difficulty in entering values for the properties: Reroute
name, LTERM name, and Map name. Ensure that you remove the
blanks from these fields before entering your values.
- The Generate Artifacts page opens. You can
specify a folder to contain the generated files, in our case sample/ims.
You must enter a name in the Name field. In our case, enter PhoneBookService.
At this point you can deploy the resource adapter with the module if you wish. Deploying or not deploying the resource adapter in the module discusses why you
might want to deploy your resource adapter. In our case, do not deploy the IMS resource
adapter with this module. Click Finish.

- Your service is created and added to the module. Select your business
object beneath Data Types. The relationship of this business object
to others appears in the references view. Right-click a business object. From
the pop-up menu select Open With > Business Object Editor.
It opens in the editor. Selecting an item from the business object results
in seeing lower level information in the properties view. Business objects from data structures provides
more details on the properties view of business objects created by the wizard.
- Right-click your interface beneath Interfaces. From the
pop-up menu, select Open With > Interface Editor. The
interface opens in the interface editor. The relationship between the interface
and the service is shown in the references view.
- Right-click the name of service you created, PhoneBookService,
from the pop-up menu select Open. The assembly editor
opens with an import component icon. EIS indicates that it is created from
an application on an EIS system.

- Select the import component. In the properties view, more details
are provided. You can add or change the names and description provided. Select Details.
More details are specified including the interface name, preferred interaction
style - synchronous, asynchronous, or any - and the operations. Qualifiers tab
may let you add a qualifier to the interface. A qualifier is a quality of
service (QoS) addition you may be able to add to the interface; for example,
a security level. However, it is determined by the creation of the service
whether one or more are present and if you are permitted to add any yourself.
The Event Monitor tab lets you monitor events at run
time using the Common Event Infrastructure (CEI) property. For example, you
might want to monitor how many times a transaction involving this service
occurred. Event monitoring can be helpful in fine tuning an application. For
example, if you monitored the transactions occurring it might point to a bottleneck
at run time.

- Select the Binding tab. The type of binding,
the resource adapter, the managed connection factory class, data type and
binding description are listed. Since a JNDI lookup name was specified in
this example, the Connection section is empty as the
server will contain the connection values. If the JNDI name was not specified
then this example would contain the managed connection factory class and its
properties, the Connection Spec class and its properties, the authentication
and administration properties. The Resource Adapter section contains
the resource adapter name and type. The Method Bindings section
contains the interaction information. You can set IMSInteractionSpec values
such as IMS request
type and commit mode. Binding information fields are discussed in detail in Data bindings, function selector and generated properties.
- If you wish to test your component using the WebSphere test
environment, see WebSphere test environment setup.
You have created an IMS service as an import component. You can find a similar
step-by-step example but with multiple outputs in the
samples
section. Compare it with creating an import component using a PeopleSoft
system.