Skip Headers
Oracle® Application Server Adapter for IMS/DB User's Guide
10g Release 2 (10.1.2)
B15806-01
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

2 Installing and Configuring the OracleAS Adapter for IMS/DB

This chapter describes how to install Oracle Connect and Oracle Studio from the CD-ROM, and how to configure Oracle Connect using Oracle Studio.


Note:

In addition to the installation procedures described in this chapter, the J2CA 1.0 IMS/DB adapter must be installed with Oracle Application Server. Installing the J2CA 1.0 IMS/DB adapter is described in Oracle Application Server Adapter Installation Guide.

This chapter includes the following sections:

Preinstallation Tasks

Before installing OracleAS Adapter for IMS/DB, ensure that your computer meets the following requirements:

IBM OS/390 or z/OS Hardware and Software Requirements

This section describes the following requirements for installing Oracle Connect on an IBM OS/390 or z/OS platform:

Hardware Requirements

The following table summarizes the hardware requirements for Oracle Connect.

Hardware Component Requirements
Processor An IBM S/390 computer
Memory The minimum requirement is 4MBfor each connection. A connection is defined as a connection to a server process or daemon. The actual memory requirement depends on such things as the size of the database and the number of databases accessed.
CD-ROM Drive An internal or external CD-ROM drive
Disk Space (3380 and 3390 disks) 150 cylinders

Software Requirements

The following table summarizes the software requirements for Oracle Connect.

Software Component Requirements
Operating System IBM OS/390 V2R5 or higher

Or

IBM z/OS Series V1R0 or higher

CICS TP Monitor (if accessing IMS/DB data under CICS) V4R1 or higher (recommended to use CICS V6R1 or higher)

CICS EXCI support must be installed and IRCSTRT=YES must be specified in the CICS initialization parameters, so that the IRC (Inter Region Communication) starts.

You can also set the IRC to open by issuing the following command: CEMT SET IRC OPEN. Also the IBM group DFH$EXCI (or an equivalent user-defined group) must be installed in the CICS region: using the CEDA RDO facility.

Oracle Application Server Oracle Application Server 10g (10.1.2.0.1)

Windows Hardware and Software Requirements

This section describes the following requirements for installing Oracle Studio:

Hardware Requirements

The following table summarizes the hardware requirements for Oracle Studio.

Hardware Component Requirements
Processor An Intel or 100% compatible personal computer (PC), based on a Pentium processor
Memory 256 MB of RAM
CD-ROM Drive An internal or external CD-ROM drive
Disk Space for Oracle Studio 100MB of free disk space

Software Requirements

The following table summarizes the software requirements for Oracle Studio.

Software Component Requirements
Operating System Microsoft Windows 2000 with service pack 2 or higher, or Microsoft Windows XP, or Microsoft Windows 2003
Microsoft Network transport protocol software, TCP/IP, included with Microsoft Windows

Installing Oracle Connect on an IBM OS/390 or z/OS Series Platform

This section explains how to install Oracle Connect from the CD-ROM. This section includes the following:


Note:

If you have an Oracle Connect back-end adapter already installed on the IBM OS/390 or z/OS platform, follow the instructions described in "Updating an Existing Oracle Connect Installation with IMS/DB".

The other back-end adapters that run on an IBM OS/390 or z/OS platform include:

  • OracleAS Adapter for CICS

  • OracleAS Adapter for IMS/TM

  • OracleAS Adapter for VSAM


Installation Worksheet

Verify that you have all the information detailed in the following installation worksheets, so you can refer to it during the configuration process.

Table 2-1 Preinstallation Information

Topic Required Information Default Comment
General Operating system - OS/390 V2R5 or higher, or z/OS Series V1R0 or higher
- Disk space - 150 cylinders
- Memory - The minimum requirement is 4MBfor each connection. A connection is defined as a connection to a server process or daemon. The actual memory requirement depends on such things as the size of the database and the number of databases accessed.
- Installation high-level qualifier OCL1012 -
- Volume - -
- Unit 3390 SMS only: unit where SMS resides.
- Output class A -
- JCL job card - An optional card (up to 6 lines) to replace the prefix job (entered as it will appear in the job)
- ISPF load library name ISP.SISPLOAD -
CICS CICS EXCI load library name CICS.CICS.SDFHEXCL To access IMS/DB data under CICS

Table 2-2 Required Permissions

Permission
Permission to define an APF-authorized library
Permission to write to an active proclib, such as user.proclib
Permission to read the CICS EXCI library (when accessing IMS/DB data under CICS)
Permission to update the security manager, such as RACF
Optionally, permission to specify an output class for Oracle Connect output

Table 2-3 Installation Checklist

Step Comment/Outputs
tso profile prefix Ensures that the user name is not used as part of the dataset name allocated in the next steps
Allocate dataset: {HLQ}.TRANSMIT.KIT 130 tracks (3390), format=FB, record length=80, block size=3120
Allocate dataset: {HLQ}.TRANSMIT.LOAD 420 tracks (3390), format=FB, record length=80, block size=3120
FTP files to OS/390 (or z/OS) FTP using binary mode
RECEIVE INDSNAME('{HLQ}.TRANSMIT.KIT') -
da('{HLQ}.TRANSMIT.LIB') UNIT(unit) VOLUME(volume) -
EX {HLQ}.TRANSMIT.LIB(PREPARE) Successful MAXCC is 0, 4 or 8

BUILDKIT.SRC and BUILDKIT.LOAD created

EX {HLQ}.BUILDKIT.SRC(NAVINST) Successful MAXCC is 0 or 4

Preinstallation Tasks

Before starting the installation, ensure that you have the following information available:

  • The output class for the installation output if you do not want to use the default value, which is A

  • If you use SMS to manage all datasets (you cannot provide unit and volume information), then the unit where SMS resides

Before starting the installation, ensure that you have the following permissions:

  • Permission to define an APF-authorized library

  • Permission to write to an active proclib, such as user.proclib

  • Permission to read the CICS EXCI library, when accessing IMS/DB data under CICS.

  • Permission to update the security manager, such as RACF.


    Note:

    Optionally, ensure that you have permission to specify an output class for Oracle Connect output. Assigning a device which is set on HOLD prevents the loss of log information when Oracle Connect started tasks finish.

Oracle Connect software for the IBM OS/390 or z/OS platform is contained in the following datasets:

  • OCL1012.TRANSMIT.KIT

  • OCL1012.TRANSMIT.LOAD

These datasets are provided on a CD-ROM in the directory Oracle_Connect\IMS/DB_Legacy_Adapter.

Importing the Installation Kit

Perform the following steps on the mainframe to import Oracle Connect installation kit to the mainframe:

  1. Run the following command:

    tso profile noprefix
    
    

    The user name will not be used as part of the dataset name. On some systems this is the default.

  2. Allocate datasets with the following space for each of these files:

    • OCL1012.TRANSMIT.KIT = 130 tracks (3380 and 3390 disks)

    • OCL1012.TRANSMIT.LOAD = 420 tracks (3380 and 3390 disks)

    For each dataset: RECFM=FB and LRECL=80. The block size is 3120.

  3. Using FTP, copy OCL1012.TRANSMIT.KIT and OCL1012.TRANSMIT.LOAD in binary mode from the installation CD to the mainframe. You can replace the OCL1012 high-level qualifier to any qualifier you want.

Installation Instructions

Perform the following steps to install Oracle Connect:

  1. Run the following command at the TSO prompt:

    RECEIVE INDSNAME('nnn.TRANSMIT.KIT')
    
    

    Where nnn represents the high-level qualifier you want to assign for the Oracle Connect installation. Assign the high-level qualifier you specified in step 7 of the preinstallation. The default value is OCL1012.


    Note:

    You can use more than one high-level qualifier (such as ACME.DEV.OCL1012) with the following conditions:
    • The total length must be less than or equal to twenty characters

    • The words transmit and buildkit cannot be used as high-level qualifiers


  2. Enter the following command when prompted for the restore parameters:

    da('nnn.TRANSMIT.LIB') [UNIT(unit) VOLUME(volume)]
    
    

    This extracts the nnn.TRANSMIT.LIB library from the nnn.TRANSMIT.KIT kit to the specified unit and volume. If a unit and volume are not specified the library is extracted to the current unit and volume.

  3. Execute the PREPARE member of the nn.TRANSMIT.LIB library:

    ex PREPARE
    
    

    Follow the instructions in the Response column in Table 2-4 for each entry in the Screen column.

    Table 2-4 Installation Prepare Job Prompts and Responses

    Screen Response
    DO YOU WANT TO USE SMS MANAGED STORAGE FOR THIS INSTALLATION Y/N [N] : If you want to manage the storage using SMS, then answer Y, otherwise answer N.
    ENTER THE STORCLASS FOR INSTALLATION TEMP DATASETS [ ] : This prompt is displayed only if SMS is used to manage the installation (you answered Y to the first prompt).

    Enter the storage class

    ENTER THE UNIT NAME FOR INSTALLATION TEMP DATASETS [3390] : If a storage class is not specified, then enter the unit name for temporary datasets used during the installation procedure
    ENTER THE VOLUME NAME FOR INSTALLATION TEMP DATASETS : This prompt is displayed only if SMS is not used to manage the installation (you answered N to the first prompt).

    The volume name for temporary datasets used during the installation procedure

    ENTER THE OUTPUT CLASS FOR INSTALLATION OUTPUT [A] : Enter the output class only if you do not want the default class used (the default is A)
    DO YOU WANT TO USE THE DEFAULT JOB CARD Y/N [Y] A job card is displayed. If you want to use a replacement card, then it must be entered as it will appear in the job. You can enter up to six lines. Enter a blank card to end input.

    If you do not enter a card, then the Oracle Connect default card is used.

    DO YOU WANT TO PERFORM A MANUAL (M) OR AUTOMATIC (A) INSTALLATION [A] : If you want to review the JCL used to install Oracle Connect, before it is submitted, then respond M for a manual installation.
    PLEASE REVIEW AND SUBMIT FOR EXECUTION THE HLQ.TRANSMIT.LIB(INSTJO) This prompt is displayed only if a manual installation is requested (you answered M to the previous prompt).

    The following libraries are generated:

    nnn.BUILDKIT.LOAD
    nnn.BUILDKIT.SRC
    nnn.BUILDKIT.GENDEMO
    
    

    Where nnn is the high-level qualifiers you assigned in step 0.

  4. In the nnn.BUILDKIT.SRC library, execute the NAVINST member:

    ex NAVINST
    
    

    Follow the instructions in the Response column in Table 2-5 for each entry in the Screen column.

    Table 2-5 Installation Prompts and Responses

    Screen Response
    DO YOU WANT TO USE SMS MANAGED STORAGE FOR THIS INSTALLATION Y/N [N] : If you want to manage the storage using SMS, then answer Y, otherwise answer N.
    THE SOFTWARE WILL BE INSTALLED UNDER THE HIGH LEVEL QUALIFIER THAT YOU WILL CHOOSE.

    ENTER THE HIGH LEVEL QUALIFIER ["QUALIFIER"] :

    The high-level qualifier for the installation (referred to as INSTROOT throughout this guide)

    You can use more than one high-level qualifier (such as ACME.DEV.VA10). The total length must be less than or equal to twenty characters. The qualifiers can be the same as the ones used for the installation (step 0).

    The words transmit and buildkit cannot be used as high-level qualifiers.

    ENTER THE STORCLASS FOR TEMP DATASETS ['STORCLASS'] : This prompt is displayed only if SMS is used to manage the installation (you answered Y to the first prompt).

    Enter the storage class

    ENTER THE UNIT NAME FOR INSTALLATION TEMP DATASETS [3390] : The unit name for temporary datasets used during the installation procedure.
    ENTER THE VOLUME NAME FOR INSTALLATION TEMP DATASETS : This prompt is displayed only if SMS is not used to manage the installation (you answered N to the first prompt).

    The volume name for temporary datasets used during the installation procedure

    PLEASE CONFIRM (YES/NO/QUIT) [YES] : Confirm the entered details
    ENTER THE OUTPUT CLASS FOR INSTALLATION OUTPUT [A] : Enter the output class for Oracle Connect output. Assigning a device which is set on HOLD prevents the loss of log information when the Oracle Connect started tasks finish (the default is A).
    DO YOU WANT TO USE THE DEFAULT JOB CARD Y/N [Y] A job card is displayed. If you want to use a replacement card, then it must be entered as it will appear in the job. You can enter up to six lines. Enter a blank card to end input.

    If you do not enter a card, then the Oracle Connect default card is used.

    ADDING AND UPDATING ORACLE CONNECT FOR IMS/DB CONFIGURATION ON THIS MACHINE, FROM A REMOTE ORACLE ADMINISTRATION CONSOLE, CAN ONLY BE DONE BY SOMEONE DEFINED AS AN ADMINISTRATOR FOR ORACLE CONNECT ON THIS MACHINE.

    ENTER A VALID USER NAME FOR AN ORACLE CONNECT ADMINISTRATOR [ALL]:

    To manage Oracle Connect on this computer from Oracle Studio, you need to enter a user account of a user who will have administrative authorization, or press Enter to enable any user to administer Oracle Connect on this computer. The administrative rights can be changed from within Oracle Studio after the installation.
    DO YOU WANT TO PERFORM A MANUAL (M) OR AUTOMATIC (A) INSTALLATION [A]: If you want to review the JCL used to install Oracle Connect, before it is submitted, then respond M for a manual installation.
    PLEASE REVIEW AND SUBMIT FOR EXECUTION THE DSN1 (INSTJBOR) This prompt is displayed only if a manual installation is requested (you answered M to the previous prompt).

    DSN1 is the dataset name where INSTJBOR is located.


  5. In the nnn.BUILDKIT.SRC library, execute the IMS/DB member:

    ex IMS/DB
    
    

    Follow the instructions in the Response column in Table 2-6 for each entry in the Screen column.

    Table 2-6 IMS/DB Adapter-Specific Installation Prompts and Responses

    Screen Response
    DO YOU WANT ORACLE CONNECT FOR LEGACY ADAPTER TO WORK WITH IMS/DB UNDER CICS (YES/NO) [NO] : Answer YES to this prompt if you want to access IMS/DB data under CICS.
    ENTER THE CICS EXCI LOAD LIBRARY NAME [CICSTS13.CICS.SDFHEXCI] : If you responded YES to working with IMS/DB under CICS, then enter the CICS EXCI load library name only if you do not want the default.
    PLEASE CONFIRM (YES/NO/QUIT) [YES] : If you responded YES to working with IMS/DB under CICS, then confirm the entered details.
    ENTER THE ISPF LOAD LIBRARY NAME [ISP.SISPLOAD] : Enter the ISPF load library name only if you do not want the default.
    PLEASE CONFIRM (YES/NO/QUIT) [YES] : Confirm the entered details
    ENTER THE OUTPUT CLASS FOR INSTALLATION OUTPUT [A] : Enter the output class for Oracle Connect output. Assigning a device which is set on HOLD prevents the loss of log information when the Oracle Connect started tasks finish (the default is A).
    DO YOU WANT TO USE THE DEFAULT JOB CARD Y/N [Y] A job card is displayed. If you want to use a replacement card, then it must be entered as it will appear in the job. You can enter up to six lines. Enter a blank card to end input.

    If you do not enter a card, then the Oracle Connect default card is used.


The installation is completed. All JCL jobs and REXX procedures are written to the INSTROOT.USERLIB library. INSTROOT is the high-level qualifier for the installation.

Postinstallation Instructions

The following postinstallation tasks must be done to work with Oracle Connect:

Postinstallation Procedures

Perform the following procedures after completing the installation to configure Oracle Connect.

  • Allocate a dataset for INSTROOT.DEF.BRANDBIN, using 1 track and with RECFM=VB and LRECL=256. The block size is 6233.

    INSTROOT is the high-level qualifier where Oracle Connect is installed.

    Using FTP, copy the BRANDBIN file, in binary mode, from the Oracle Connect\IMS/DB Legacy Adapter directory in the installation CD to the mainframe, to INSTROOT.DEF.BRANDBIN.

  • Define the LOADAUT library as an APF-authorized library


    Note:

    To define a DSN as APF-authorized, in the SDSF screen enter the command:
    "/setprog apf,add,dsn=INSTROOT.loadaut,volume=vol002"
    
    

    where vol002 is the volume where you installed Oracle Connect and INSTROOT is the high-level qualifier where Oracle Connect is installed.

    If the site uses SMS, then when defining APF-authorization in the SDSF screen, enter the following command:

    "/setprog apf,add,dsn=INSTROOT.loadaut,SMS"
    
    

    Ensure that the library is APF-authorized, even after an IPL (reboot) of the computer.


  • Move the INSTROOT.USERLIB(ATTDAEMN) and INSTROOT.USERLIB(ATTSRVR) members to any active proclib, such as user.proclib, ATTDAEMN and ATTSRVR are run as started tasks.

    If you decide to change the name of the ATTSRVR member when you move it to a general high-level qualifier, then change the name specified in the StartupScript parameter in the daemon configuration to the new name:

    • Run INSTROOT.USERLIB(NAVCMD) and enter EDIT DAEMON IRPCDINI at the prompt.

    • Change the startupScript parameter from ATTSRVR to the new name for the server:

      <Workspace name="Navigator"
                 startupScript="NEW_NAME"
                 serverMode="reusable"
                 ... />
      
      
    • Exit and save the change.

  • Change the following line in the ATTDAEMN script to include the IP address and port of the IBM OS/390 or z/OS platform.

    For example, before:

    // PARM='-B START IRPCDINI'
    
    

    After:

    // PARM='-B -L ip_address:2252 START IRPCDINI'
    
    

    Where ip_address specifies the IP address of the computer, 2552 is the default port for starting the daemon and IRPCDINI is the default daemon configuration.

  • The ATTDAEMN and ATTSRVR started tasks need permission to use an Open Edition TCP/IP stack. The owner must be a user with OMVS segment defined and OMVS UID= 0000000000.

  • In the security manager, such as RACF, define ATTDAEMN and ATTSRVR with a started task class and a general profile that enables the following:

    • Permission to issue master console commands.

    • START authority for the ATTSRVR job.

    • Access to an Open OS/390 segment (that defines access to TCP/IP OA sockets).

    • ALTER authority on datasets under INSTROOT (to access to read, write, allocate and delete datasets under INSTROOT).

  • The installation includes a PS, INSTROOT.DEF.GBLPARMS, that contains global environment information. This PS is read at startup and the correct software version is used, based on the details provided in the startup task.

    If you change the location of this member, you must also change the relevant cards in the following jobs to the new locations:

    • ATTSRVR: located in an active proclib, such as user.proclib

    • ATTDAEMN: located in an active proclib, such as user.proclib

    • NAVSQL: located in INSTROOT.USERLIB

  • The input during the installation procedure is written to nnn.BUILDKIT.SRC(PARS). You can use this file to provide the same inputs if you rerun the installation, where nnn is the high-level qualifier you assign for the installation.

  • For information about specifying Oracle Connect as the service using port 2552 in the TCP/IP network services file, consult TCP/IP documentation.

Starting the Daemon

Activate INSTROOT.USERLIB(ATTDAEMN) as a started task to invoke the daemon. For example, in the SDSF screen enter the following:

'/s ATTDAEMN'

Where INSTROOT is the high-level qualifier where Oracle Connect is installed.

To submit the daemon as a job, uncomment the first two lines of the ATTDAEMN JCL, change the PARM line as described earlier, and run the job using the subcommand. The ATTDAEMN JCL is similar to the following:

//*ATTDAEMN JOB 'RR','TTT',MSGLEVEL=(1,1),CLASS=A,
//* MSGCLASS=A,NOTIFY=&SYSUID,REGION=8M
//STEP1 EXEC PGM=IRPCD,
// PARM='-B  START IRPCDINI'
//* PARM='-B -L :8883 START'
//STEPLIB DD DSN=INSTROOT.LOADAUT,DISP=SHR
//SYSPRINT DD SYSOUT=A
//GBLPARMS DD DSN=INSTROOT.DEF.GBLPARMS,DISP=SHR
// EXEC PGM=IRPCD,COND=((1,EQ,STEP1),(2,EQ,STEP1)),
// PARM='-KATTDAEMN START ''INSTROOT.DEF.IRPCDINI'''
//STEPLIB DD DSN=INSTROOT.LOADAUT,DISP=SHR
//SYSPRINT DD SYSOUT=A
//GBLPARMS DD DSN=INSTROOT.DEF.GBLPARMS,DISP=SHR
//SYSDUMP DD DUMMY

Setting Up Oracle Connect for Reentrancy

All Oracle Connect load modules are reentrant to enable sub-tasking. Therefore, move INSTROOT.LOAD to the Link Pack Area (LPA).

WhereINSTROOT is the high-level qualifier where Oracle Connect is installed.

Using the LPA reduces real storage usage (because everyone shares the LPA copy) and fetch time.


Note:

If you intend on using impersonation, so that you can run in a security context that is different than the context of the process that owns the server, then do the following:
  • Place the INSTROOT.LOAD(ATYSVCW) member in an APF-authorized library outside the LPA.

  • Change the ATTSRVR member (located in the active proclib), by adding the following to the STEPLIB list:

// DD DSN=apf_library,DISP=SHR

Where apf_library is the APF-authorized library outside the LPA where the ATYSCVW member was moved.


Setting Up Oracle Connect to Update IMS/DB Data

Perform the following to set up Oracle Connect so that you can update IMS/DB data.

IMS/DB Running Under CICS

To set up Oracle Connect so that you can update IMS/DB data from a CICS transaction, copy the UPDTRNS load module from INSTROOT.LOAD to a CICS DFHRPL library (such as CICS.USER.LOAD) and then define the UPDTRNS program under CICS using any available group such as ORA group:

CEDA DEF PROG(UPDTRNS) G(ORA) LANG(C) DA(ANY) DE(ORACLE IMS/DB UPDATE PROG)

Where INSTROOT is the high-level qualifier where Oracle Connect is installed.

After defining the UPDTRNS program to a group, install it as follows:

CEDA IN G(ORA)
IMS/DB Not Running Under CICS

To enable Oracle Connect to create and delete IMS/DB data, run the following JCL:

// IDCSYSIN DD DSN=&&IMS/DB,DISP=(NEW,DELETE,DELETE),
// SPACE=(TRK,(1)),UNIT=SYSDA,
// DCB=(BLKSIZE=3200,LRECL=80,RECFM=FB)

Updating an Existing Oracle Connect Installation with IMS/DB

Verify that you have all the information detailed in the following installation worksheets, so you can refer to it during the configuration process.

Table 2-7 Preinstallation Information

Topic Required Information Default Comment
CICS CICS EXCI load library name CICS.CICS.SDFHEXCL -

Table 2-8 Required Permissions

Permission
Permission to read the CICS EXCI library

In the nnn.BUILDKIT.SRC library, execute the CUSTOCL member:

ex CUSTOCL

Follow the instructions in the Response column in Table 2-9 for each entry in the Screen column.

Table 2-9 IMS/DB Adapter Installation Prompts and Responses

Screen Response
DO YOU WANT ORACLE CONNECT FOR LEGACY ADAPTER TO WORK WITH IMS/DB (YES/NO) [YES]: Answer YES to this prompt if you have Oracle Connect for IMS/DB already installed.
ENTER DBD LIBRARY NAME [IMS.DBDLIB]: If you responded YES to working with IMS/DB, then enter the library where database definition (DBD) files are located.
ENTER PSB LIBRARY NAME [IMS.PSBLIB]: If you responded YES to working with IMS/DB, then enter the library where Program Specification Blocks (PSBs) are located.
ENTER YOUR PSB NAME [HOSPPSB]: If you responded YES to working with IMS/DB, then enter the name of the PSB file to use.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: If you responded YES to working with IMS/DB, then confirm the entered details.
DO YOU WANT ORACLE CONNECT FOR LEGACY ADAPTER TO WORK WITH IMS/DB UNDER CICS (YES/NO) [NO]: If you want to access IMS/DB data under CICS, using the OracleAS Adapter for IMS/DB, then respond YES.
ENTER THE CICS EXCI LOAD LIBRARY NAME [CICSTS13.CICS.SDFHEXCI]: If you responded YES to working with IMS/DB under CICS, then enter the CICS EXCI load library name only if you do not want the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: If you responded YES to working with IMS/DB under CICS, then confirm the entered details.
DO YOU WANT ORACLE CONNECT FOR LEGACY ADAPTER TO WORK WITH CICS APP ADAPTER (YES/NO) [YES]: Answer YES to this prompt
ENTER THE CICS EXCI LOAD LIBRARY NAME [CICSTS13.CICS.SDFHEXCI] : Enter the CICS EXCI load library name only if you do not want the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: Confirm the entered details.
THE IMS/DB DRIVER IS INSTALLED AUTOMATICALLY. DO YOU ALSO WANT ORACLE CONNECT FOR LEGACY ADAPTER TO WORK WITH IMS/DB UNDER CICS (YES/NO) [NO]: Answer YES to this prompt if you have Oracle Connect for IMS/DB already installed and you want to access IMS/DB data under CICS.
ENTER THE CICS EXCI LOAD LIBRARY NAME [CICSTS13.CICS.SDFHEXCI]: If you responded YES to working with IMS/DB under CICS, then enter the CICS EXCI load library name only if you do not want the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: If you responded YES to working with IMS/DB under CICS, then confirm the entered details.
ENTER THE ISPF LOAD LIBRARY NAME [ISP.SISPLOAD]: Enter the ISPF load library name only if you do not want the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES] : Confirm the entered details
ENTER THE OUTPUT CLASS FOR INSTALLATION OUTPUT [A]: Enter the output class for Oracle Connect output. Assigning a device which is set on HOLD prevents the loss of log information when the Oracle Connect started tasks finish (the default is A).
DO YOU WANT TO USE THE DEFAULT JOB CARD Y/N [Y] A job card is displayed. If you want to use a replacement card, then it must be entered as it will appear in the job. You can enter up to six lines. Enter a blank card to end input.

If you do not enter a card, then the Oracle Connect default card is used.


The installation is completed. All JCL jobs and REXX procedures are written to the INSTROOT.USERLIB library. INSTROOT is the high-level qualifier for the installation.

After completing the installation, perform postinstallation tasks, as described in "Postinstallation Instructions", as required.

Installing Oracle Studio

This section explains how to install Oracle Studio from the distribution CD-ROM.


Note:

If you have Oracle Studio already installed because you are also using another legacy adapter, then you do not need to reinstall it.

The other legacy adapters are:

  • OracleAS Adapter for CICS

  • OracleAS Adapter for VSAM

  • OracleAS Adapter for IMS/TM

  • OracleAS Adapter for Tuxedo


Installing Oracle Studio from the CD-ROM

Assuming that the CD-ROM drive is D:, the installation file is located in the D:\Oracle_Studio directory. Install Oracle Studio from the CD-ROM by running the self-extracting executable installation file, OSL904-win32.exe.


Note:

If you are installing Oracle Studio on a Windows XP computer, then you cannot specify a logical drive as the Destination folder for the installation.

Configuring Oracle Connect

All modeling of Oracle Connect is performed using Oracle Studio. To use Oracle Studio, you first configure it to enable access to the IBM OS/390 or z/OS platform where the IMS/DB data resides.

To configure Oracle Connect, refer to the following sections:


Note:

The following tasks assume you have permission to access the IBM OS/390 or z/OS platform and that the Oracle Connect daemon is running on this computer.

Check with the system administrator to ensure these requirements are fulfilled.


Setting Up the IBM OS/390 or z/OS Platform in Oracle Studio

Using Oracle Studio, perform the following steps to configure the IBM OS/390 or z/OS platform:

  1. From the Start menu, select Start, Programs, Oracle, and then select Studio. Oracle Studio opens, displaying the Design perspective.

  2. Right-click Machines in the Configuration Explorer and select Add Machine. The Add Machine screen is displayed.

  3. Enter the name of the computer you want to connect to, or click Browse to select the computer from the list of computers that is displayed and which use the default port (2552).

  4. Specify the username and password of the user who was specified as the administrator when Oracle Connect was installed.


    Note:

    Selecting Anonymous connection enables anyone having access to the computer to be an administrator, if this was defined for the computer.

    The Add Machine screen is shown in the following figure:

    Add Machine
    Description of the illustration addmach.gif

  5. Click Finish.

    The computer is displayed in the Configuration Explorer.

Securing Access to Oracle Connect

Oracle Studio includes mechanisms to secure access to Oracle Connect both during modeling and at run time.

During modeling, the following security mechanisms can be applied:

At run time client access to Oracle Connect is provided by the user profile:

Setting Password Access to Oracle Studio

Initially, any operation performed using Oracle Studio does not require a password. You can set a password so that the first operation that involves accessing the server from Oracle Studio requires a password to be entered.

Perform the following steps to set password access to Oracle Studio:

  1. From the Start menu, select Start, Programs, Oracle, and then select Studio. Oracle Studio opens.

  2. Select Window, from the menu bar, and then select Preferences. The Preferences screen is displayed.

  3. Select the Studio node as shown in the following figure:

    Oracle Studio Preferences
    Description of the illustration prefer.gif

  4. Click Change Master Password. The Change Master Password screen is displayed as shown in the following figure:

    Description of mastpass.gif follows
    Description of the illustration mastpass.gif

  5. Leave the Enter Current Master Password field blank and type a new master password.

  6. Confirm the password.

  7. Click OK.

Specifying Users with Administrative Rights

By default, only the user who was specified during the installation as an administrator has the authorization to modify settings on that computer from Oracle Studio. This user can then authorize other users to make changes or to view the definitions for a selected computer. Adding a computer to Oracle Studio is described in "Setting Up the IBM OS/390 or z/OS Platform in Oracle Studio".


Note:

The default during installation is to enable all users to be administrators.

  1. From the Start menu, select Start, Programs, Oracle, and then select Studio. Oracle Studio opens.

  2. Right-click the computer in the Configuration Explorer and select Administration Authorization.

    The Administration Authorization screen is displayed as shown in the following figure:

    Oracle Studio
    Description of the illustration admin.gif

  3. Add users or groups of users by clicking Add User or Add Group for the relevant sections.

    The user or group that is added must be recognized as a valid user or group for the computer. Once a name has been added to a section, only the user or group who logs on with that user name has the relevant authorization.

Setting Up Run-Time User Access to the IBM OS/390 or z/OS Platform

During run time, client access to Oracle Connect is provided by the user profile. A user profile contains name and password pairs that are used to access a computer, data source or application at run time, when anonymous access is not allowed.

  1. In the Configuration Explorer, expand the node of the computer for which you want to set the user name and password.

  2. Expand the Users node.

  3. Right-click the NAV user profile and select Edit User. The NAV user profile editor is displayed as shown in the following figure:

    Description of user.gif follows
    Description of the illustration user.gif

  4. In the User editor, click Add. The Add Authenticator screen is displayed as shown in the following figure:

    The Add Authenticator window
    Description of the illustration adduser.gif

  5. Select Remote Machine from the Resource Type list.

  6. Enter the name of the IBM OS/390 or z/OS computer defined in Oracle Studio.

  7. Enter the name and password used to access the computer and confirm the password.

  8. Click OK.

Modeling Interactions for OracleAS Adapter for IMS/DB

Modeling interactions for OracleAS Adapter for IMS/DB involves defining an Oracle Connect back-end adapter using Oracle Studio. All the definitions specified in Oracle Studio are written to the IBM OS/390 or z/OS platform.

This section contains the following:

Setting Up the IMS/DB Data Source

Oracle Connect requires you to specify the IMS/DB data source as the first step in setting up the adapter.

Perform the following steps to setup the IMS/DB data source:

  1. From the Start menu, select Start, Programs, Oracle, and then select Studio.

  2. In the Configuration Explorer, expand the node of the computer defined in "Setting Up the IBM OS/390 or z/OS Platform in Oracle Studio".

  3. Expand the Bindings node. The binding configurations available on this computer are listed.

  4. Expand the NAV binding node. The NAV binding configuration includes branches for data sources and adapters that are located on the computer.

  5. Right-click Data sources and select New data source, to open the New data source wizard.

  6. In the New dialog box, enter a name for the IMS/DB data source. The name can contain letters and numbers and the underscore character only.

  7. Select the data source type from the Type list, as follows:

    • If you are accessing IMS/DB data under CICS, then select IMS-DBCTL

    • If you are accessing IMS/DB data under IMS/TM, then select IMS-DBDC

    • If you are accessing IMS/DB data directly, then select IMS-DLI


      Note:

      Only use the IMS-DLI option to connect directly to the IMS/DB data in the following circumstances:
      • The IMS/DB records are not managed by CICS or by IMS/TM.

      • The IMS/DB records are required for read-only purposes and changes to the data buffered by CICS or IMS/TM while reading the data, are not expected.


    The New Data Source screen is shown in the following figure:

    Adding an IMS/DB
    Description of the illustration new_import.gif

  8. Click Next. The Data Source Connect String screen for the selected data source type is displayed.

  9. Enter the connect string for the selected data source, as follows:

    If you select IMS-DBCTL, then the following screen is displayed:

    Required information
    Description of the illustration adcnstr1.gif

    Where:

    • CICS Application ID: The VTAM applid of the CICS target system. The default value is CICS. This parameter is used when updating IMS/DB data. You can determine this value by activating the CEMT transaction on the target CICS system. On the bottom right corner of the screen appears the legend APPLID=target_system.

    • Transaction ID: The mirror transaction within CICS that receives control through MRO, which transfers the transaction from the Oracle Connect for IMS/DB environment to CICS. The default value is EXCI.

    • VTAM NetName: The VTAM netname of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system. For example, if you issue to CEMT the following command:

      CEMT INQ CONN
      
      

      Then, you will see on the display screen that the netname is BATCHCLI (this is the default connection supplied by IBM upon the installation of CICS). The default value is ATYCLIEN.

    • Program Name: The UPDTRNS program that is supplied by Oracle Connect for IMS/DB to enable updating IMS/DB data.


      See Also:

      "IMS/DB Running Under CICS" for details about the adapter metadata

    • Trace Queue: The name of queue for output which is defined under CICS when tracing the output of the UPDTRNS program. When not defined, the default CICS queue is used.

    If you select IMS-DBDC, then the following screen is displayed:

    The connect string.
    Description of the illustration new_ds_underIMS.gif

    Where:

    • XCF group: The Cross System Coupling Facility collection of XFC members the connection belongs to. A group may consist of up to eight characters, and may span between multiple systems.

    • XCF server: The Cross System Coupling Facility group member.

    • Tpipe prefix: The transaction pipe prefix used to associate between the transaction and the transaction pipe it is using. The default value is ATTU.

    • User name: The security facility user identification.

    • Group name: The security facility group identification.

    If you select IMS-DLI, then the following screen is displayed:

    The Data source connect string.
    Description of the illustration adcnstr2.gif

    Where:

    • Data HLQ: The high-level qualifier where the data files are located. If a value is not specified in this field, the data files are written to the DEF high-level qualifier where Oracle Connect for IMS/DB is installed.

    • Disk Volume name: The high-level qualifier (volume) where the data resides.

  10. Click Finish. The new data source is displayed in the Configuration Explorer.

Configuring the Data Source Driver

After setting up the data source, you can set its driver properties according to specific requirements, as follows:

  1. Right-click the required data source in the Configuration Explorer and select Edit Data source.

  2. Click the Properties tab.

    For IMS/DB under CICS, the following configuration properties are available:

    • cicsProgname=string: The UPDTRNS program that is supplied with Oracle Server to enable updating VSAM data. To use the UPDTRNS program, copy the program from NAVROOT.LOAD to a CICS DFHRPL library (such as CICS.USER.LOAD) and then define the UPDTRNS program under CICS using any available group such as ATY group:

      CEDA DEF PROG (UPDTRNS) G(ATY) LANG(C) DA(ANY) DE(ATTUNIT VSAM UPDATE PROG)

      After defining the UPDTRNS program to a group, install it as follows:

      CEDA IN G(ATY)

    • cicsTraceQueue=string: The name of queue for output which is defined under CICS when tracing the output of the UPDTRNS program. When not defined, the default CICS queue is used.

    • disableExplicitSelect=true | false: Set to true to disable the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement.

    • exciTransid=string: The CICS TRANSID. This value must be EXCI or a copy of this transaction.

    • psbName=string: (PSB Name parameter in the connect string) The name of the PSB file that contains details of all the IMS/DB databases that you want to access.

    • targetSystemApplid=string: (Target system parameter in the connect string) The VTAM applid of the CICS target system. The default value is CICS. This parameter is used when updating VSAM data. You can determine this value by activating the CEMT transaction on the target CICS system. On the bottom-right corner of the screen appears the legend APPLID=target_system.

    • vtamNetname=string: (VTAM NetName parameter in the connect string) The VTAM netname of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system. The default value is ATYCLIEN.

    For IMS/DB under IMS/TM, the following configuration properties are available:

    • disableExplicitSelect=true | false: Set to true to disable the ExplicitSelect ADD attribute; every field is returned by a "SELECT * FROM..." statement.

    • imsTransname=string: The name of the IMS transaction that points to the program that is used to access the PSB used to access the IMS/DB data. The default name of the transaction is ATYIMSTM.

    • maxSessions=n: The maximum number of sessions allowed. The default value is 5.

    • racfGroupId=string – The security facility group identification (for example, the RACF group identification).

    • racfUserId=string: The security resource user name.

    • tpipePrefix=string: (TPipe prefix parameter in the connect string) The transaction pipe prefix used to associate between the transaction and the transaction pipe it is using. The default is ATTU.

    • xcfClient=string: The client name for the Cross System Coupling Facility the connection belongs to.

    • xcfGroup=string: (XCF group parameter in the connect string) The Cross System Coupling Facility collection of XCF members the connection belongs to. A group may consist of up to eight characters, and may span between multiple systems.

    • xcfImsMember=string: The Cross System Coupling Facility group member.

    • xcfServer=string: (XCF server parameter in the connect string) The Cross System Coupling Facility group member.

    • userName=string: (User name in the connect string) The security facility user identification (for example, the RACF user identification).

    For IMS/DB direct, the following configuration property is available:

    • disableExplicitSelect=true | false: Set to true to disable the ExplicitSelect ADD attribute; every field is returned by a SELECT statement.

  3. Click Save to save the changes you made to the configuration properties.

Importing Metadata for the IMS/DB Data Source

Oracle Connect requires metadata describing the IMS/DB data source records and the fields in these records. Use the Import Metadata procedure in Oracle Studio Design perspective to import metadata for the IMS/DB data source from DBD, COBOL copybooks and PSB files, which describe the data.

The following information is needed during the import procedure:

  • DBD files: These files are copied to the computer running Oracle Studio as part of the import procedure.

  • COBOL copybooks: These copybooks are copied to the computer running Oracle Studio as part of the import procedure.

  • PSB file: This file is copied to the computer running Oracle Studio as part of the import procedure.

Perform the following steps to import metadata for the IMS/DB data source:

  1. From the Start menu, select Start, Programs, Oracle, and then select Studio.

  2. In the Configuration Explorer, expand the node of the computer defined in "Setting Up the IBM OS/390 or z/OS Platform in Oracle Studio".

  3. Expand the Bindings node. The binding configurations available on this computer are listed.

  4. Expand the NAV binding node.

  5. Expand the Data sources node.

  6. Right-click the IMS/DB data source defined in "Setting Up the IMS/DB Data Source".

  7. Select Edit Metadata, to open the Metadata tab, with the IMS/DB data source displayed under the data sources list.

  8. Right-click the IMS/DB data source and select New Import.

    The New Import screen is displayed.

  9. Enter a name for the import. The name can contain letters and numbers and the underscore character only.

  10. Select the import type from the Import Type list as shown in the following figure:

    The selected IMS/DB
    Description of the illustration import1.gif


    Note:

    The New import screen is the same for both the IMS/DB imports (IMS/DB under CICS, IMS/DB under IMS/TM and direct), with the exception of the Import Type value: either IMS/DB Import Manager or IMS/DB Under CICS Import Manager or IMS/DB under IMS/TM Import Manager, respectively).

  11. Click Finish. The Metadata Import wizard opens.

  12. Click Add.

    The Select Resources screen is displayed, which provides the option to select files from the local computer or copy the files from another computer.

  13. If the files are on another computer, right-click My FTP Sites and select Add. Optionally, double-click Add FTP site. The Add FTP Site screen is displayed.

  14. Enter the server name or IP address where the COBOL copybooks reside and enter a valid username and password to access the computer (if anonymous access is used, select Anonymous Connection) then click OK. The FTP site is added to the list of available sites.


    Note:

    The selected server is accessed using the username as the high-level qualifier, enabling you to browse and transfer files.

    The Select Resources screen is shown in the following figure:

    The added machine.
    Description of the illustration import3.gif

  15. Right-click the computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) and click OK.

  16. Expand the node of the added site and locate the necessary DBD/COBOL and PSB files. To change the high-level qualifier, right-click the computer and select Change Root Directory. Enter the high-level qualifier enclosed in quotes, and click OK.

  17. Select the file or files and click Finish. The selected file or files are displayed in the Metadata Import wizard as shown in the following figure:

    The selected files.
    Description of the illustration new_IMSImp1.gif


    Note:

    You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import procedure using different COBOL copybooks.

    The format of the COBOL copybooks must be identical. That is, you cannot import a COBOL copybook that uses the first six columns with a COBOL copybook that ignores the first six columns. In this type of case you must repeat the import procedure.


  18. Click Next.

    The Apply Filters screen is displayed as shown in the following figure:

    The image shows the Appy filters screen.
  19. Apply filters to the copybooks if required.

    The following COBOL filters are available:

    Filter Description
    COMP_6 switch The MicroFocus COMP-6 compiler directive. Specify either COMP-6'1' to treat COMP-6 as a COMP data type or COMP-6'2' to treat COMP-6 as a COMP-3 data type.
    Compiler source The compiler vendor.
    Storage mode The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP is for word storage mode.
    Ignore after column 72 Ignores columns 73 to 80 in the COBOL copybook.
    IgnoreFirst6 Ignores the first six columns in the COBOL copybook.
    Replace hyphens (-) in record and field names with underscores (_) Replace all hyphens in either the record or field names in the metadata generated from the COBOL with underscore characters.
    Prefix nested columns Prefix all nested columns with the previous level heading.

    In addition, you can specify a search string and the string that will replace this search string in the generated metadata, and whether the replacement is dependent on the case of the found string.

    Case sensitive Specifies whether to be sensitive to the search string case.
    Find Searches for the specified value.
    Replace with Replaces the value specified for Find with the value specified here.
    The following DBD filters are available:
    Ignore after column 72 Ignores columns 73 to 80 in the DBD file.
    Ignore first 6 columns Ignores the first 6 columns in the DBD file.
    Ignore labels Ignores labels in the DBD file.
    The following PSB filters are available:
    Ignore after column 72 Ignores columns 73 to 80 in the PSB file.
    Ignore first 6 columns Ignores the first 6 columns in the PSB file.

  20. Click Next.

    The Select Tables screen is displayed, showing the identified records as shown in the following figure:

    The Select Tables screen.
    Description of the illustration new_import6.gif

  21. Select the required tables or click Select All, then click Next.

    The Match DBD to COBOL screen is displayed as shown in the following figure:

    Description of new_import7.gif follows
    Description of the illustration new_import7.gif

  22. Select the required COBOL files and tables from the COBOL Files and the COBOL Tables columns respectively, that match the DBD tables, listed in the DBD Tables column.

  23. Click Next. The Import Manipulation screen is displayed as shown in the following figure:

    Description of new_import8.gif follows
    Description of the illustration new_import8.gif

    This screen enables you to perform the following operations:

    • Resolve table names, where tables with identical names are generated from different COBOL copybooks specified during the import.

    • Specify the physical location for the data.

    • Specify table attributes.

    • Manipulate the fields generated from the COBOL, as follows:

      • Merge sequential fields into one for simple fields.

      • Resolve variants by either marking a selector field or specifying that only one case of the variant is relevant.

      • Add, delete, hide, or rename fields.

      • Change a data type.

      • Set a field size and scale.

      • Change the order of the fields.

      • Set a field as nullable.

      • Select a counter field for fields with dimensions (arrays). You can select the counter for the array from a list of potential fields.

      • Set column wise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension.

      • Create arrays and set the array dimensions.

      The Validation tab at the lower area of the screen displays information about what needs to be resolved in order to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location).

  24. To manipulate table metadata, right-click the table record, and select the necessary operation. The following table lists the available options:

    Option Description
    Fields manipulation Customizing the fields definitions, using the Fields Manipulation screen. You can also access this screen by double-clicking the required table record.
    Rename Renaming a table. This option is used especially when more than one table is generated from the COBOL with the same name.
    Set data location Setting the physical location of the data file for the table.
    Set table attributes Setting the table attributes.
    XSL manipulation Specifying an XSL transformation or JDOM document that is used to transform the table definitions.

  25. Once all the validation error issues have been resolved, the Import Manipulation screen is displayed with no error indicators.

  26. Click Next to generate the metadata.

  27. Specify that you want to transfer the metadata from the Windows computer to the IBM OS/390 or z/OS platform and click Finish.

The metadata is imported based on the options specified and it is stored on the IBM OS/390 or z/OS platform. An XML representation of the metadata is generated. This XML file can be viewed by expanding the Output node.

After performing the import, you can view the metadata in the Metadata tab in Oracle Studio Design perspective. You can also make any fine adjustments to the metadata and maintain it, as necessary.


See Also:

"Metadata for the IMS/DB Data Source" for details about the data source metadata

Setting Up an Oracle Connect Adapter

To work with the Oracle Connect against the IMS/DB data source from Oracle Application Server, you need to set up an adapter definition on the IBM OS/390 or z/OS platform to handle the interactions to and from the IMS/DB data.

Perform the following steps to setup the adapter:

  1. From the Start menu, select Start, Programs, Oracle, and then select Studio.

  2. In the Configuration Explorer, expand the node of the computer defined in "Setting Up the IBM OS/390 or z/OS Platform in Oracle Studio".

  3. Expand the Bindings node.

  4. Expand the NAV binding node.

  5. Right-click Adapters and select New Adapter to open the New Adapter wizard.

  6. Enter a name for the back-end adapter.


    Note:

    The word event is a reserved word and cannot be used when naming an adapter.

  7. Select Database as the back-end adapter type from the Type list. The Database adapter enables accessing the IMS/DB data source from Oracle Application Server.

  8. Select Events.

  9. Click Finish. The back-end adapter is added to the Configuration Explorer and the definition opens for editing.


    Note:

    Other adapters that are displayed in the Type list are not supported with the version of Oracle Connect installed at the site.

  10. Click the Properties tab and change any of the properties for the adapter, as required.

    The Properties tab is shown in the following figure:

    The Database adapter properties tab.
    Description of the illustration adprop.gif

    The following properties are available:

    Property Description
    connectString Leave this value blank
    defaultDatasource The name of the data source defined in Oracle Studio that you want to access with the Database adapter

    For example, Legacy

    multipleResults Leave this value as true


    Note:

    You must specify the IMS/DB data source name for the default Datasoure property.

Generating Outbound Interactions

Oracle Connect requires metadata describing the adapter interactions, including the structures used to pass information to and from the adapter.

Use the Metadata Import procedure in Oracle Studio to generate interaction metadata.

Use the Metadata Import wizard in Oracle Studio to generate interaction metadata, as follows:

  1. From the Start menu, select Start, Programs, Oracle, and then select Studio.

  2. In the Configuration Explorer, expand the node of the computer defined in "Setting Up the IBM OS/390 or z/OS Platform in Oracle Studio".

  3. Expand the Bindings node. The binding configurations available on this computer are listed.

  4. Expand the NAV binding node.

  5. Expand the Adapters node.

  6. Right-click the Database back-end adapter defined in "Setting Up an Oracle Connect Adapter".

  7. Select Edit metadata to open the Metadata tab, with the database back-end adapter displayed under the Adapters list.

  8. Right-click the Interactions node and select New to open the New Interaction wizard. The wizard opens with the following options displayed:

    • Automatic: Four interactions are generated for each IMS/DB table, enabling to execute the SELECT, INSERT, UPDATE, DELETE command.

    • Manual: One interaction is generated, based on the type of SQL selected such as database query (a SELECT statement) or Database Modification (an INSERT, UPDATE, or DELETE statement).


      Note:

      IMS/DB does not support the stored procedure option.

  9. Select how you want to generate interactions (Automatic or Manual).

    If you select Automatic generation, perform the following steps:

    1. Click Next. The Select Tables screen opens, enabling you to add tables from the IMS/DB data source that you want to access with the interaction.

    2. Click Add to include tables.

      The data sources that have been defined and all the tables, for each data source, that have had metadata defined for them are displayed.

      Select the tables that you want to access with the interaction and click the right-pointing arrow to move these tables to the right-hand pane.

    3. Click Finish. The selected tables are displayed.

    4. Click Finish. Four interactions are generated for each table selected (SELECT, INSERT, UPDATE, DELETE), together with the record structures to support the interactions and the responses from the IMS/DB data source.

    5. Click Yes to complete the task. The interactions and the record structures that relate to the interactions are displayed in the Metadata tab.

    If you select Manual generation, perform the following steps:

    1. Select the type of SQL (query or modification) for the interaction and click Next. The Interaction Name screen is displayed.

    2. Enter a name for the interaction, and select Create new query.


      Note:

      The option to use a previously saved query is not applicable.

    3. Click Next. The Define Interaction screen is displayed enabling you to build the query.


      Note:

      If the database query option was selected in step a, then the Define Interaction screen is displayed, enabling you to build a SELECT statement only, as indicated in the Query type field. If the database modification option was selected, then this field enables you to select the required SQL modification statement from a list (INSERT, UPDATE, or DELETE).

    4. Click Next. The Interaction Properties screen is displayed, enabling you to define the interaction parameters. You can set the following interaction prameters:

      Parameter Description
      passThrough Defines whether the query is passed directly to the back-end database for processing or processed by the Query Processor.
      Reuse compiled query Defines whether the query is saved in cache for reuse.
      Encoding Sets the encoding method used to return binary data in text format. You can select between the base 64 and the hexadecimal encoding methods.
      Event Defines whether the interaction mode is sync-send or sync-receive.
      Fail on no rows return Defines whether an error is returned in case no data is returned
      Root element Defines the root element name for records returned by the query, using the <root> \ <record> format.
      Record element Defines the record element name for records returned by the query, using the <root> \ <record> format.
      Max. records Sets the maximum number of record returned by the query.
      Null string Sets the string returned in place of a null value. If not specified, the column is skipped.

    5. Click Next. The Interaction Parameters screen is displayed, where you specify input parameters for the interaction. The following parameters are specified:

      Parameter Description
      Name The name of the parameter.
      Type The type of parameter (such as string, number, binary).
      Nullable The nullable value (true or false).
      Default The default value for the parameter.
      Context Field This field is not applicable.
      Bind to Sqls This field is not applicable.

    6. Click Finish to generate the interaction, including the record schema required to support the interaction input and output.


See Also:

"Metadata for the Back-end Adapter" for details about the data source metadata

Generating Inbound Interactions

Inbound interactions are defined as events in Oracle Studio. When you defined the Oracle Connect for VSAM back-end adapter with Create event queue for the adapter selected, as described in "Setting Up an Oracle Connect Adapter", an event adapter was defined automatically. The event adapter is defined with the same name as the back-end adapter with the word Event appended to it.

The back-end adapter and the event adapter are linked by Oracle Studio. You can jump from the adapter definition to the event definition by right-clicking the adapter or event in the Configuration Explorer list and choosing the Linked Event or Linked Adapter, respectively.

The event adapter requires metadata describing the inbound interactions, including the structure used to pass information.


Note:

The generation of inbound interactions involves similar steps to the steps described to generate outbound interactions. For details, see "Generating Outbound Interactions".

Perform the following steps to generate inbound interaction metadata

  1. In the Configuration Explorer, right-click the IMS/DB back-end adapter defined in "Setting Up an Oracle Connect Adapter".

  2. Select Linked Event, to skip to the event adapter.

  3. Right-click the event adapter and select Edit Event.

  4. Click the Properties tab to add the names of Oracle Application Server users who can retrieve inbound interactions and OS/390 users who can send inbound interactions.

  5. To add Oracle Application Server users, expand the Routers node, right-click Users, and then select Add Item as shown in the following figure:

    The IMS/DB events adpater Properties tab
    Description of the illustration new_eveAdapProp.gif

  6. Enter the name of the Oracle Application Server user in the Value column for the item added.

  7. To add OS/390 users, expand the Senders node and right-click the Users property to add the user.

  8. Enter the name of the OS/390 user in the Value column for the item added.

  9. Click Save to save the changes.

  10. Right-click the event adapter in the Configuration Explorer and select Edit metadata, to display the Metadata tab, with the event adapter displayed under the Events list.

  11. Right-click the Imports node and select New Import, to open the Metadata Import wizard.

  12. Enter a name for the import. The name can contain letters and numbers and the underscore character only.

  13. Click Finish. After defining an import, the Metadata Import wizard opens in Oracle Studio. COBOL copybooks are used to create the metadata. The import wizard generates record structures, which are used for the record structures for inbound interactions.

  14. Click Add in the Metadata Import wizard. The Select Resources screen is displayed, which provides the option to select files from the local computer or copy the files from another computer.

  15. If the files are on another computer, right-click My FTP Sites and select Add. Optionally, double-click Add FTP Site.

  16. Enter the server name or IP address where the COBOL copybooks reside and enter a valid username and password to access the computer (if anonymous access is used, select Anonymous Connection) then click OK.


    Note:

    The selected server is accessed using the username as the high-level qualifier, enabling you to browse and transfer files.

    The FTP site is added to the list of available sites as shown in the following figure:

    Description of import3.gif follows
    Description of the illustration import3.gif

  17. Right-click the computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) and click OK.

  18. Expand the node of the added site and locate the necessary COBOL files. To change the high-level qualifier, right-click the computer and select Change Root Directory. Enter a high-level qualifier enclosed in quotes, and click OK.

  19. Select the file or files and click Finish. The selected file or files are displayed in the Metadata Import wizard as shown in the following figure:

    Description of new_import1_in.gif follows
    Description of the illustration new_import1_in.gif

  20. Click Next.

  21. The Apply Filters screen is displayed as shown in the following figure:

    Setting the properties.
    Description of the illustration import5.gif

  22. Apply filters to the copybooks, as needed.

    The following filters are available:

    Filter Description
    COMP_6 switch The MicroFocus COMP-6 compiler directive. Specify either COMP-6'1' to treat COMP-6 as a COMP data type or COMP-6'2' to treat COMP-6 as a COMP-3 data type.
    Compiler source The compiler vendor.
    Storage mode The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP is for word storage mode.
    Ignore after column 72 Ignores columns 73 to 80 in the COBOL copybook.
    IgnoreFirst6 Ignores the first six columns in the COBOL copybook.
    Replace hyphens (-) in record and field names with underscores (_) Replace all hyphens in either the record or field names in the metadata generated from the COBOL with underscore characters.
    Prefix nested columns Prefix all nested columns with the previous level heading.

    In addition, you can specify a search string and the string that will replace this search string in the generated metadata, and whether the replacement is dependent on the case of the found string.

    Case sensitive Specifies whether to be sensitive to the search string case.
    Find Searches for the specified value.
    Replace with Replaces the value specified for Find with the value specified here.

  23. Click Next. The Add Events screen is displayed.

  24. Click Add to add an event for the IMS/DB adapter. Provide the following information:

    • Name: The name of the interaction. You can change the default name specified.

    • Mode: The interaction mode. You can select the async-send mode, which sends a request and processing then continues asynchronously, without regard to the request.

    • Input: Identifies an input record. The input record is the data structure for the interaction. The records generated from the COBOL files specified at the beginning of the procedure are listed. Select the relevant record for the interaction.


      Note:

      You must specify an input record for each interaction before you can click Next.

    • Description: Free text describing the interaction. The Add Events screen is shown in the following figure:

      Description of new_import1_in.gif follows
      Description of the illustration new_import1_in.gif

  25. Add as many interactions as necessary.

  26. Click Next to generate the metadata definitions for the adapter.

  27. Specify that you want to transfer the data from the Windows computer to the IBM OS/390 or z/OS platform, and click Finish.

The event is generated, including the record schema required to support the interaction input and output. Both the event and the schema are displayed in the Metadata tab under the Event adapter node.


See Also:

"Metadata for the Back-end Adapter" for details about the adapter metadata

Modifying Existing Interactions

You can modify the interaction definitions to the exact requirements of the application, in the Design perspective Metadata tab.

The following example uses the DELETE interaction, generated in the previous task, to describe how the interactions can be modified:


Note:

The interaction modification procedure is the same for all types of SQL statements (INSERT and UPDATE) as described, using a DELETE SQL statement.

  1. In the Metadata tab, right-click the interaction to modify and select Edit Metadata.

    The adapter metadata editor opens, displaying the Interaction General tab.

    The Interaction General tab displays general information about the way the interaction is executed. You can add a description of the interaction and define the mode of operation for the interaction. The following modes are available:

    • sync-send-receive: The interaction sends a request and expects to receive a response.

    • sync-send: The interaction sends a request and does not expect to receive a response.

    • sync-receive: The interaction expects to receive a response.

    The information for a request is passed in the input record. The information for the response from the IMS/DB data source is passed in the output record.

  2. Click the Interaction Advanced tab to display specific information about the interaction.

    As required, change the SQL and the parameters associated with the SQL.

    Parameters are specified in a SET clause or in a WHERE clause with the following format:

    :parameter_name
    
    
  3. Depending on the changes made to the SQL, when you close the editor, or when clicking Save, the Context Selection screen is displayed.

    Select the required adapter from the Adapters list and select Update interaction-related records. Any changes that need making to the record structures in the schema part of the metadata are done automatically.

    The Context Selection screen is shown in the following figure:

    Description of upd_int1.gif follows
    Description of the illustration upd_int1.gif


    Note:

    The interaction records are built based on all the fields in the table and cannot be changed manually, even if you change the SQL so that less fields are involved.

  4. Click Finish to implement the modifications made to the interaction definitions.

Viewing the XML Schema

The XML describing the adapter interactions can be viewed in Oracle Studio Design perspective Metadata Source tab.

Creating XML Schemas

The XML schema describing the adapter interactions and the input and output records for these interactions are created automatically during the import procedure, as described in "Generating Outbound Interactions" and in "Generating Inbound Interactions".