2 Installing and Configuring OracleAS Adapter for CICS

Hardware Requirements

The following table summarizes the hardware requirements for Oracle Connect.

Software Requirements

The following table summarizes the software requirements for Oracle Connect.

Hardware Requirements

The following table summarizes the hardware requirements for Oracle Studio:

Software Requirements

The following table summarizes the software requirements for Oracle Studio.

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\CICS 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 following 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 (restart) of the computer.

  
  

• Move the INSTROOT.USERLIB(ATTDAEMN) and INSTROOT.USERLIB(ATTSRVR) members to any active proclib, such as user.proclib. The ATTDAEMN and ATTSRVR members 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 changes.

• 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 is 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, which 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, which 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, then 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 subtasking. Therefore, move INSTROOT.LOAD to the Link Pack Area (LPA).

Where INSTROOT 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.

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:

1. From the Start menu, select 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 as shown in the following figure:

   
   Description of the illustration prefer.gif
   
   

3. Select the Studio node.

4. Click Change master password to display the Change master password screen.

5. In the Change master password screen, leave the Enter current master password field empty 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".

Perform the following steps to specify a user with administrative rights:

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

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:

   
   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 runtime, 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 during runtime, 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 User Editor pane is displayed as shown in the following figure:

   
   Description of the illustration user.gif
   
   

4. In the User editor, click Add to display the Add Authenticator screen.

5. Select Remote Machine from the Resource type list, as shown in the following figure:

   
   Description of the illustration adduser.gif
   
   

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.

Configuring an Oracle Connect Adapter

To work with the Oracle Connect, you need to configure adapter definitions on the IBM OS/390 or z/OS platform to handle the interactions to and from a CICS program. You use Oracle Studio to specify these definitions.

Perform the following steps:

1. From the Start menu, select 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 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 to name an adapter.

   
   

7. Select CICS as the back-end adapter type from the Type list as shown in the following figure:

   
   Description of the illustration addcics.gif
   
   

8. Select Events.

9. Click Finish. The back-end adapter is added to the list 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:

    
    Description of the illustration adprop.gif
    
    

    The Properties tab comprises fields, as listed in the following table:

    Property	Description
    exciTransid	The CICS TRANSID. This value must be EXCI or a copy of this transaction
    targetSystemApplid	The VTAM applid of the CICS target system. 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.
    transactionSupport	For future use. The level of transaction support for this adapter that is reported to the transaction manager In the current version leave this value as 0PC
    vtamNetname	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 You see on the display screen that the netname is BATCHCLI (this is the default connection supplied by IBM upon the installation of CICS). If you plan to use the IBM defaults, then specify BATCHCLI as the VTAM_netname parameter, otherwise, define a specific connection (with EXCI protocol) and use the netname you provided there for this parameter.

    
    

Generating Outbound Interactions

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

If COBOL copybooks describing the adapter input and output structures are available, then you can import the adapter definition using the Metadata Import wizard in Oracle Studio Design perspective to generate interaction metadata. If the metadata is provided in a number of COBOL copybooks, with different filter settings (such as whether the first six columns are ignored or not), then you first import the metadata from copybooks with the same settings and later import the metadata from the other copybooks.

If COBOL copybooks describing the input and output structures are not available, then you need to manually define the metadata.

The following information is required during the import procedure:

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

The names of the CICS programs run through the application adapter.

Use the Metadata Import procedure using Oracle Studio to generate interaction metadata, as follows:

1. In the Configuration Explorer, right-click the CICS back-end adapter defined.

2. Select Edit Metadata to display the Metadata tab, with the CICS back-end adapter displayed under the Adapters list.

3. Right-click the Imports node and select New Import. The New Metadata Import screen is displayed.

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

5. Select CICS Import Manager from the Import type list, as shown in the following figure:

1. Click Finish. The Metadata Import wizard is displayed.

2. 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.

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

4. 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, click the Anonymous connection checkbox) then click OK. The FTP site is added to the list of available sites.

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

   
   Description of the illustration import3.gif
   
   
   
   

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

   
   

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

6. Expand the list of the added site until you find the necessary COBOL files. To change the high-level qualifier, right-click the computer and select Change Root Directory. Enter the new high-level qualifier enclosed in quotes, and click OK.

7. Select the required COBOL copybook 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 the illustration new_import1.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.

   
   

8. Click Next. The Apply Filters screen is displayed as shown in the following figure.

   
   Description of the illustration new_import2.gif
   
   

9. Apply filters to the copybooks, as needed.

   The following table lists the available filters:

   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 (_)	Replaces 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.
   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

   
   

10. In the import wizard, click Next. The Add Interactions screen is displayed, as shown in the following figure:

    
    Description of the illustration new_import3.gif
    
    

11. Click Add to add an interaction for the CICS adapter. Provide the information as listed in the following table:

    Parameter	Description
    Name	The name of the interaction. You can change the default name specified.
    Mode	The interaction mode. You can select one of the following: sync-send-receive: The interaction sends a request and expects to receive a response. This is the default mode. sync-receive: The interaction expects to receive a response sync-send: The interaction sends a request and does not expect to receive a response.
    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. If the interaction does not require an input record, then the record specified here is ignored.
    Output	Identifies an output record. The output record is the data structure for the results of the interaction. The records generated from the files specified at the beginning of the procedure are listed. Select the relevant record for the interaction. Note: You must specify an output record for the interaction if the mode is set to sync-send-receive or sync-receive, before you can click Next.
    Description	Free text describing the interaction.
    Interaction-Specific Parameters	CICS specific parameters: commitMode: The interaction commit mode. maxSegmentSize: The maximum size of the segment. The default value is 32768 (bytes). transaction: The name of the transaction that runs. You must specify a transaction name for each interaction. The maxSegmentSize parameter enables dynamically splitting large messages into smaller segments. Although the default value can be changed, the logic of CICS transaction must correspond accordingly. The transaction must per'form a GU call followed by a series of GN calls in order to compile the entire input message. A transaction output message, larger than 32K, is handled by the OTMS C/I interface which performs the task of assembling the output segments into a single buffer.

    
    

12. Add as many interactions as necessary and click Next to generate the metadata definitions for the adapter.

13. 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 also generated.

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

    
    

    See Also: Appendix A, "Advanced Tuning of the Metadata" for details about fine tuning the adapter metadata

    
    

Generating Inbound Interactions

Inbound interactions are defined as events in Oracle Studio. When you defined the Oracle Connect for CICS back-end adapter with Events selected, as described in Configuring 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 skip from the adapter definition to the event definition by right-clicking the adapter or event in the Configuration Explorer list and selecting the Linked Event or Linked Adapter option, respectively.

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

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

1. In the Configuration Explorer, right-click the CICS back-end adapter defined in "Configuring 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. Select 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 and right-click the users property to add the user. The Properties tab is shown in the following figure:

6. Enter the name of 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. The New Import screen is displayed.

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

13. Select Event Queue Import Manager Using Cobol COPYBOOK Input Files as the import type, and click Finish. The New Import screen is shown in the following figure:

    
    Description of the illustration new_import.gif
    
    

After defining an import type, 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.

1. 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 FTP the files from another computer.

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

3. 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, click 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 Add Resource screen is shown in the following figure:

   
   Description of the illustration import3.gif
   
   

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

5. 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.

6. 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 the illustration new_import1_in.gif
   
   

7. In the Import wizard, click Next. The Apply Filters screen is displayed as shown in the following filter:

   
   Description of the illustration import5.gif
   
   

8. Apply filters to the copybooks. The following table lists the available filters:

   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 (_)	Replaces 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.
   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

   
   

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

10. Click Add to add an event for the CICS adapter. Provide the following information:

    Parameter	Description
    Name	The name of the event. You can change the default name specified.
    Mode	The event mode. You can select the async-send mode, which is the event sends a request and does not expect to receive a response.
    Input	Identifies an input record. The input record is the data structure for the event. The records generated from the COBOL files specified at the beginning of the procedure are listed. Select the relevant record for the event. Note: You must specify an input record for each event before you can click Next. If the interaction does not require an input record, then the record specified here is ignored.
    Description	Free text describing the event.

    
    

    The Add Events screen is shown in the following figure:

    
    Description of the illustration new_import3_in.gif
    
    

11. Add the required events.

12. Click Next to genrate the metadata definitions for the adapter.

13. Specify that you want to transfer the data from the Windows computer to the IBM OS/390 or z/OS platform, and click Finish as shown in the following figure:

    
    Description of the illustration 26.gif
    
    

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 also generated.

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