2 Installing and Configuring OracleAS Adapter for VSAM

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\VSAM_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). 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 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 (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, 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'

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 sub command. 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).

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 Up Oracle Connect to Update VSAM Data

Perform the following to set up Oracle Connect so that you can update VSAM data.

CEDA DEF PROG(UPDTRNS) G(ORA) LANG(C) DA(ANY) DE(ORACLE VSAM UPDATE PROG)

CEDA IN G(ORA)

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

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 the password:

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

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:

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

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

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 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 which you want to set the user name and password.

2. Expand the Users node.

3. Right-click NAV and select Edit User. The NAV user profile editor is displayed.

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

   
   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.

Setting Up the VSAM Data Source

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

Perform the following steps to setup the VSAM 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.

   The New Data Source screen is displayed.

6. Enter a name for the VSAM 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 VSAM data under CICS, then select VSAM (CICS).

   • If you are accessing VSAM data directly, then select VSAM.

     
     

     Note: Only use the VSAM option to connect directly to the VSAM data in the following circumstances: The VSAM records are not managed by CICS. The VSAM records are required for read only purposes and changes to the data buffered by CICS while reading the data are not expected.

     
     

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

   
   Description of the illustration addvsam.gif
   
   

8. Click Next. The Data Source Connect String screen is displayed.

9. Enter the Data source connect string. If you select VSAM (CICS), then the following screen is displayed:

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

   • Transaction ID: The mirror transaction within CICS that receives control through MRO, which transfers the transaction from the Oracle Connect for VSAM 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 VSAM to enable updating VSAM data.

     
     

     See Also: "VSAM 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 VSAM, then the Data Source Connect String screen is displayed, where

   • Data HLQ: The high-level qualifier where the data files are located. If a value is not specified in this field, then data files are written to the DEF high-level qualifier where Oracle Connect for VSAM 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.

Importing Metadata for the VSAM Data Source

Oracle Connect requires metadata describing the VSAM data source records and the fields in these records. Use the Import Metadata procedure in Oracle Studio to import metadata for the VSAM data source from COBOL copybooks, which describe the data.

Perform the following steps to import metadata for the VSAM data source, 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 Data sources node.

6. Right-click the VSAM data source defined in "Setting Up the VSAM Data Source".

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

8. Right-click the VSAM 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.

    
    Description of the illustration import1.gif
    
    
    
    

    Note: The same New Import screen is displayed for both VSAM imports (VSAM under CICS and VSAM direct), with the exception of the Import type field value: either VSAM Under CICS Import Manager or VSAM 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, then 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, then click the Anonymous connection check-box) 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:

    
    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 COBOL 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:

    
    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.

    
    

18. Click Next. The Apply Filters screen is shown in the following figure.

    
    Description of the illustration new_import2.gif
    
    

19. Apply filters to the copybooks as required.

    The following table lists the avaiable 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

    
    

20. Click Next.

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

    
    Description of the illustration new_import3.gif
    
    

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

    The Import Manipulation screen is displayed as shown in the following figure.

    
    Description of the illustration new_import4.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:

      • Merging sequential fields into one for simple fields.

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

      • Adding, deleting, hiding, or renaming fields.

      • Changing a data type.

      • Setting a field size and scale.

      • Changing the order of the fields.

      • Setting a field as nullable.

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

      • Setting 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.

      • Creating arrays and setting 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).

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

    
    

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

24. Click Next. The next step depends whether the VSAM Under CICS Import Manager or the VSAM Import Manager is used.

    If the VSAM Under CICS Import Manager is used, then the Assign File Names screen is displayed, as shown in the following figure:

    
    Description of the illustration vsam_assignfilename.gif
    
    

    In this screen you specify the physical file name, including the high-level qualifiers and the logical file name, for each record listed.

    If the VSAM Import Manager is used, then the Create VSAM Indexes screen is displayed.

25. Click Next to retrieve index information.

    If the VSAM Under CICS Import Manager is used and this step fails for any reason (such as the IBM OS/390 or z/OS platform is temporarily not accessible), a warning message is issued and you continue to the next step. Click Continue in the message box to continue with the next step.

    
    

    Note: If the indexes are not generated, then define manually in the Metadata tab of Oracle Studio Design perspective. For details, refer to "Metadata for the VSAM Data Source".

    
    

26. The next step (assigning index file names) applies only if the VSAM under CICS Import Manager is used.

    The Assign Index FIle Names screen is shown in the following figure:

    
    Description of the illustration new_import6.gif
    
    

27. For each table listed, specify the logical file name for the index.

28. Click Next.

29. Specify that you want to transfer the metadata from the 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. You can also make any fine adjustments to the metadata and maintain it, as necessary.

Setting Up an Oracle Connect Adapter

To work with the Oracle Connect against the VSAM data source from an 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 VSAM 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 VSAM data source from Oracle Application Server.

8. Select Events to create an event queue for the adapter.

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

    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 VSAM data source name you used to define in Oracle Studio for the defaultDatasoure 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 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 VSAM table, enabling you to run the SELECT, INSERT, UPDATE, and DELETE commands.

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

     
     

     Note: VSAM does not support the stored procedure option.

     
     

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

   If you select Automatic generation, then perform the following steps:

   1. Click Next. The Select Tables screen is displayed, enabling you to add tables from the VSAM data source that you want to access with the interaction.

   2. Click Add to add 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.

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

   4. Click Finish. The selected tables are displayed.

   5. Click Finish. Four interactions are generated for each table selected, together with the record structures to support the interactions and the responses from the VSAM data source.

   6. 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, then 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 SQL query.

      
      

      Note: If Database query 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).

      
      

      The SELECT or Modification query is built as follows:

      • Selecting Tables: In the left-hand pane, expand the data source node where the required table resides and select the required table. Drag and drop it to the first available row in the Tables tab in the right-hand pane.

      • Selecting Columns: Click the Columns tab in the right-hand pane. In the left-hand pane, expand the data source and the table containing the required column. Select the required column and drag and drop it into the Columns tab in the right-hand pane.

      • Joining columns from different tables: When a column from a different table is selected, the Join Tables wizard is displayed. Expand the table node in the left-hand pane, select the required column and click the right-pointing arrow. Click Next to set the operator and logical parameters for each column/segment as required, and then click Finish to close the wizard.

      • Adding conditions in a WHERE clause: Select the column you are setting the WHERE clause for, and drag and drop it into the Where tab in the right-hand pane. Set the operator, value and logical parameters as required.

      • Grouping columns: Select the required columns and drag and drop them into the Group tab in the right-hand pane.

      • Filtering results using a HAVING clause: The HAVING clause provides conditions for grouping columns. Select the required column and drag and drop it into the Having tab in the right-hand pane. Set the operator, value and logical parameters as required.

      • Sorting results: Select the column whose results you want to sort and drag and drop it into the Sort tab in the right-hand pane. Set the sort order as required.

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

      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, then the column is skipped.

      
      

   5. Click Next. The Interaction Parameters screen is displayed, enabling you to 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.

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 skip from the adapter definition to the event definition by right-clicking the adapter or event in the Configuration Explorer and selecting the Linked Event or Linked Adapter, respectively.

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

Perform the following steps to generate inbound interaction metadata:

1. In the Configuration Explorer, right-click the VSAM 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. 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, right click Users, and then select Add Item, as shown in the following figure.

   
   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, right click User, and then select Add item. A new entry is added under the User node.

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 Imports and select New Import to open the New Metadata Import wizard.

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, as shown in the following figure.

    
    Description of the illustration new_import.gif
    
    

14. Click Finish. After defining the 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.

15. Click Add in the metadata import wizard. The Select Resources screen is

16. 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 as shown in the following figure:

    
    Description of the illustration addFtpSite.gif
    
    

17. 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, then select Anonymous connection) then click OK.

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

    
    

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

    
    
    
    Description of the illustration import3.gif
    
    

18. Right-click the computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) 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 the illustration new_import1.gif
    
    

20. Click Next.

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

    
    Description of the illustration import5.gif
    
    

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

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

23. Click Add to add an event for the VSAM 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 that 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 the illustration new_import3_in.gif
    
    

24. Add as many interactions as necessary.

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

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

27. 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, then select Anonymous connection) then click OK.

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

    
    

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

    
    
    
    Description of the illustration import3.gif