2 Configuring the OracleAS CDC Adapter for Adabas

This chapter describes how to configure a change data capture using the OracleAS CDC Adapter for Adabas.

Most of the configurations are done using Oracle Studio. To use Oracle Studio, you first configure it to enable access to the z/OS computer where the Adabas data resides. If you are using Adabas with ADD data, you set up an Adabas data source and then create the change data capture solution. If you are using Adabas with Predict data, you only set up the CDC solution.

This chapter contains the following topics:

• Setting Up the IBM z/OS Platform in Oracle Studio

• Securing Access to Oracle Connect

• Setting up Metadata for the OracleAS Adabas Data Source

• Setting Up a Change Data Capture with the OracleAS CDC Adapter for Adabas

Note:

These tasks assume you have permission to access the IBM 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 z/OS Platform in Oracle Studio

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

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

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

   Figure 2-1 The Add Machine screen

   
   

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

4. Specify the user name 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.

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

During modeling the following security mechanisms can be applied:

• Setting Password Access to Oracle Studio

• Specifying Users with Administrative Rights

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

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

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

   Figure 2-2 The Preferences screen

   
   

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

   Figure 2-3 The Change Master Password screen

   
   

5. Leave the Enter current master password field blank and type a new master password in the Enter new master password field.

6. Enter the new passoword again in the Confirm new master password field.

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 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 Programs, Oracle, and then select Studio.

2. In the Design perspective Configuration view, Right-click the computer and select Administration Authorization.

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

   Figure 2-4 The Administration Authorization Identities tab

   
   

   The screen has the following sections:

   Administrators: Administrators can view and modify all the definitions in Oracle Studio for the selected computer. On initial entry to Oracle Studio, every user is defined as a system administrator.

   Designers: Designers can view all the definitions for the computer in Oracle Studio and can modify any of the definitions under the Bindings and Users nodes for the selected computer. For example, Oracle Studio database administrator can add new data sources and adapters and can change metadata definitions for a table in a data source.

   Users: Users can view all the definitions for the computer in Oracle Studio for the selected computer. Regular users cannot modify any of the definitions.

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 that logs on with that user name has the relevant authorization.

Setting Up Run-Time User Access to the IBM 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. From the Start menu, select, Programs, Oracle, and then select Studio. Oracle Studio opens.

2. From the Design perspective, Configuration view, expand the Machines folder, then expand the machine where you want to set the user name and password.

3. Expand Users.

4. Right-click NAV and select Open The NAV user profile editor is displayed:

   Figure 2-5 The User Editor

   
   

5. In the User editor, click Add. The Add Authenticator screen is displayed:

   Figure 2-6 The Add Authenticator screen

   
   

6. Select Remote Machine from the Resource Type list.

7. Enter the name of the IBM z/OS computer defined in Oracle Studio.

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

9. Click OK.

Setting up Metadata for the OracleAS Adabas Data Source

Setting up a change data capture with the OracleAS CDC Adapter for Adabas is done using Oracle Studio. If you are using Adabas with ADD data, you must first define an Adabas data source and import the metadata. The definitions are created on a z/OS computer.

If you are using Predict data, you do not have to set up the metadata in the data source, you should go directly to Setting Up a Change Data Capture with the OracleAS CDC Adapter for Adabas.

This section contains the following:

• Setting Up the Adabas Data Source (ADD Data only)

• Configuring the Data Source Driver

• Importing Metadata for the Adabas Data Source

• Verifying the Metadata Definition

Setting Up the Adabas Data Source (ADD Data only)

You should configure an Adabas data source as the first step in setting up the CDC adapter.

Perform the following steps to set up the Adabas data source:

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

2. In the Design perspective, Configuration view expand the Machines folder.

3. Expand the machine defined in Setting Up the IBM z/OS Platform in Oracle Studio.

4. Expand the Bindings folder. The binding configurations available on this computer are listed.

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

6. Right-click Data sources and select New Data source.

   The New Data Source wizard is displayed.

   Figure 2-7 The New Data Source screen

   
   

7. Enter a name for the Adabas data source. The name can contain letters and numbers and the underscore character only.

8. In the Type field, select Adabas (ADD).

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

10. Enter the parameters for the Data source connect string.

    • Database number: Type the number for the Adabas database that you are using.

11. Click Finish.

The new data source is displayed in the Configuration Explorer.

Configuring the Data Source Driver

After setting up the Adabas (ADD) data source, you can set its driver properties according to specific requirements. To edit the properties, right-click the Adabas data source you created in the Oracle Studio Configuration view, and select Open. The properties described in the following sections are listed in the editor.

You can set the following:

• Adabas (ADD) Properties

• Configuring the Data Source Driver Advanced Properties

Adabas (ADD) Properties

The following properties can be configured for the Adabas (ADD) data source. You set the properties in Oracle Studio, Design perspective. For information on how to set data source properties in Oracle Studio.

1. In the Configuration view, right-click the Adabas data source that you created and select Open.

2. Click the Configuration tab.

   The Adabas (ADD) data source configuration is displayed in the editor. This editor has two sections.

   The Connection section shows the connections you defined when Setting Up the Adabas Data Source (ADD Data only).

   The Properties section displays thefollowing properties, which can be configured for the Adabas (ADD) data source:

   • svcNumber: The installation on MVS places the SVC number of Adabas in the GBLPARMS file. Alternatively, you can specify the SVC number using this attribute. This simplifies configuration in sites where several Adabas installations on different SVC numbers must be accessed from a single installation. Each SVC requires a different workspace, but the same GBLPARAMS and the same RACF profile can be used for the different workspaces.

   • addMuInPeCounter: Until version 4.6 Oracle Connect did not support counters for MUs inside of PEs. In version 4.6 this support was added, but since it changes behavior for existing users, this attribute was added to allow existing users to turn off this new feature to preserve compatibility. Default: addMuInPeCounter='true'.

   • disableExplicitSelect: This attribute indicates whether the Explicit Select option is disabled. If disables, a select * query on an Adabas table returns all fields in the table, including ISN and subfields which are normally suppressed unless explicitly requested in the query (for example, select ISN, *…). Default: disableExplicitSelect='false'.

   • disregardNonselectable: (Predict, ADD) This attribute enables you to configure the data source to ignore descriptors defined on a multiple value (MU) field, a periodic group (PE) field or phonetic/hyper descriptors. The special ACSEARCH fields which are normally created for a table are referred to as 'non-selectable' because you cannot specify them in the select list of a query. Setting the disregardNonselectable attribute to 'true' prevents these fields from being created. Default: disregardNonselectable='false'.

   • fileList: This attribute is passed as the record buffer to the OP command. Adabas allows a list of file numbers to be provided in the record buffer of the OP command, along with the operations allowed on each file. By using this attribute a user can restrict access to the database, allowing only specific operations on specific files. For more information, see the Software AG documentation of the OP command for more information on the syntax allowed. Note that the value provided in this attribute is passed 'as-is' to Adabas - no validation is performed. Default: fileList='.' (unrestricted access to all files in the database).

   • lockWait: This attribute specifies whether the data source waits for a locked record to become unlocked or returns a message that the record is locked. In Adabas terms, if this attribute is set to true a space is passed in command option 1 of the HI/L4 commands. Otherwise an 'R' is passed in command option 1. Default: lockWait='false'.

   • multiDatabasePredict: Turn this flag on if your Predict file includes metadata for several different databases. This has two effects on the way that the Predict information is read:

     • Only tables that belong to the current database are returned in the table list.

     • The file number for a table is read separate from the metadata as different databases may include the same table using a different file number.

   • multifetch: This parameter controls the number of records to be retrieved in a single read command (L2, L3, S1-L1). The value provided in this attribute controls the value passed in the ISN lower limit control block field. By default no multifetch is used. The multifetch buffer size can be controlled as follows:

     • multifetch='0': Lets the driver decide the number of records to retrieve. The driver retrieves rows to fill a 10k buffer. No more than 15 rows are fetched simultaniously.

     • multifetch='n': Causes n rows to be read at a time, where n is a number from 2 to 15.

     • multifetch='-n': Defines a read-ahead buffer with a fixed size, where n is less than or equal to 10000 bytes.

     • multifetch='1': Disables the read-ahead feature. (default)

   • nullSuppressionMode: This attribute controls the behavior of the Adabas driver for Null Suppression Handling. This attributes allows a user to change this default NULL suppression policy. Note that changing this setting improperly may result in incomplete query results. The following values can be selected:

     • full: (default) NULL suppressed fields are exposed as NULLABLE and must be qualified for the Oracle optimizer to consider using a descriptor based on a NULL suppressed field.

     • disabled: NULL suppressed fields are handled like any other field. Use this setting only if you completely understand the potential implications as incomplete query results may returned.

     • indexesOnly: Only NULL suppressed fields that are part of a descriptor/super-descriptor are exposed as NULLABLE. Other NULL suppressed fields are handled normally. This setting is as safe as the 'full' setting and does not include the risk of incomplete results as the 'disabled' option does.

   • scanUsingL1: A scan strategy on a table is normally implemented by an L2 command. It is possible, however, to turn on this attribute to scan using the L1 command. This has the advantage of providing better data consistency at some performance penalty. Default: scanUsingL1='false'.

   • supportL3Range: Older versions of Adabas did not allow for a range specification on an L3 command (for example, AA,S,AA in the search buffer). Only the lower limit could be provided. If your version of Adabas supports a range in the L3 command you can turn on this attribute to enjoy better performance in some queries. Default: supportL3Range='false'.

   • traceValueBuffer: This is a debugging tool to be used when driverTrace='true' in the environment. Turning on driverTrace records the Adabas commands executed in the server log file. If you also want a binary dump of the value buffer and record buffer, set this attribute to true. Default: traceValueBuffer='false'.

   • userInfo: This attribute specifies the value passed as a null-terminated string to Adabas as the seventh parameter on the adabas call. The value provided is then available in Adabas user exits. This has no affect at all on Oracle Connect, but some users have taken advantage of this feature to implement specific types of auditing. Note that it is possible to control the value of the userInfo attribute dynamically at run time using the nav_proc:sp_setprop stored procedure. Default: userInfo=''.

   • useUnderscore: This attribute indicates whether to convert hyphens (-) in table and column names into underscores (_). The inclusion of hyphens in Adabas table names and field names poses an inconvenience when accessing these tables from SQL because names that include a dash must be surrounded with double quotes. To avoid this inconvenience, the data source can translate all hyphens into underscores. Default: useUnderscore='true'.

   • verifyMetadata: This attribute indicates whether to cross-check the Predict or ADD metadata against the LF command. Resulting discrepancies are written to the log and removed from the metadata at run time. It is usually unnecessary to use this attribute. Default: verifyMetadata='false'.

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

Configuring the Data Source Driver Advanced Properties

You configure the advanced properties for a data source in the Advanced tab of the data source editor. The advanced settings are the same for every data source. Advanced settings let you do the following:

• Define the transaction type

• Edit the syntax name

• Provide a table owner

• Determine if a data source is updatable or readable

• Provide repository information

• Set the virtual view policy

Use the following procedure to configure the data source advanced features.

1. Open Oracle Studio.

2. In the Design Perspective Configuration View, expand the Machine folder and then expand the machine where you want to configure the data source.

3. Expand the Data sources folder, right click the data source you are configuring, then select Open.

4. Click the Advanced tab to make changes. The following table describes the available fields:

Table 2-1 Data Source Advanced Configuration

Field	Description
Properties
Transaction type	The transaction level (0PC, 1PC or 2PC) that is applied to this data source, no matter what level the data source supports. The default is the data source's default level.
Syntax name	A section name in the NAV.SYN file that describes SQL syntax variations. The default syntax file contains the following predefined sections: OLESQL driver and the SQL Server 7 OLE DB provider (SQLOLEDB): syntaxName="OLESQL_SQLOLEDB" OLESQL driver and JOLT: syntaxName="OLESQL_JOLT" Rdb driver and Rdb version: syntaxName="RDBS_SYNTAX" ODBC driver and EXCEL data: syntaxName="excel_data" ODBC driver and SQL/MX data: syntaxName="SQLMX_SYNTAX" ODBC driver and SYBASE SQL AnyWhere data: syntaxName="SQLANYS_SYNTAX" Oracle driver and Oracle case sensitive data: syntaxName="ORACLE8_SYNTAX" or, syntaxName="ORACLE_SYNTAX" For case sensitive table and column names in Oracle, use quotes (") to delimit the names. Specify the case sensitivity precisely.
Default table owner	The name of the table owner that is used if an owner is not indicated in the SQL
Read/Write information	Select one of the following: Updatable data: Select this to update the data on the data source. Read only data: Select this to allow users to only view the data on the data source.
Repository Directory
Repository directory	Enter the location for the data source repository.
Repository name	Enter the name of a repository for a data source. The name is defined as a data source in the binding configuration. It is defined as the type Virtual and is used to store Oracle Connect views and stored procedures for the data source, if required instead of using the default SYS data.
Virtual View Policy
Generate sequential view	Select this to map a non-relation file to a single table. This parameter is valid only if you are using virtual array views. You configure virtual array views in the Modeling section of thewhen Configuring a Binding Environment.
Generate virtual views	Select this to create an individual table for every array in the non-relational file. This parameter is valid only if you are using virtual array views. You configure virtual array views in the Modeling section when Configuring a Binding Environment.
Include row number column	Select this to include a column that specifies the row number in the virtual or sequential view. This parameter is valid only if you are using virtual array views. You configure virtual array views in the Modeling section when Configuring a Binding Environment.
All parent columns	Select this for virtual views to include all the columns in the parent record. This parameter is valid only if you are using virtual array views. You configure virtual array views in the Modeling section when Configuring a Binding Environment.

Importing Metadata for the Adabas Data Source

Oracle Connect requires metadata describing the Adabas (ADD) data source records and the fields in these records. Use the Import Metadata procedure to import metadata for the Adabas data source from DDM declaration files, which describe the data.

The metadata import procedure is described in Importing Metadata from DDM Files.

Importing Metadata from DDM Files

If the metadata exists in DDM files, you can use the DDM_ADL import utility to import this metadata to Oracle metadata. This utility is available on Windows and UNIX, from the platform's command line interface. This utility is not available on z/OS platforms. You must perform the import on a Windows or UNIX computer and then move the generated metadata to the z/OS computer with Oracle Connect.

The metadata is not imported using Oracle Studio.

To display online help for this utility, run the command DDM_ADL HELP.

To generate the ADD metadata, use the appropriate command according to the platform type.

The following table lists the MDD file list format according to platform type.

Table 2-2 DDM File List Format

Platform Type	Format
UNIX	This parameter is at the end of the command. Separate the files in this list with spaces.
Windows	The name of the file containing the list and the names of the files in the list must be less than or equal to eight characters (with a suffix of three characters). Separate the files in this list with commas.

Verifying the Metadata Definition

After you finish Importing Metadata for the Adabas Data Source, you must verify that the metadata is correct. Do the following to verify that the metadata was imported correctly.

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

2. In the Design perspective, Configuration view expand the Machines folder.

3. Expand the machine defined in Setting Up the IBM z/OS Platform in Oracle Studio.

4. Expand the Bindings folder. The binding configurations available on this computer are listed.

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

6. Expand the Data Sources folder.

7. Right-click the data source that you set up when Setting Up the Adabas Data Source (ADD Data only), and select Show Metadata View. The Metadata view opens with the data source you selected expanded.

8. Expand the Tables folder.

9. Right-click the table or tables where you carried out the metadata import and select Test. The Test wizard opens.

10. Click Next to view the metadata. The tables are displayed from the metadata. Check to see that the correct information is displayed.

Adding Adabas Data Tracing to the Log

Select the General Trace environment parameter in the Debug section to generate entries in the standard log tracing the access to Adabas data.

Setting Up a Change Data Capture with the OracleAS CDC Adapter for Adabas

You must set up the Oracle Connect CDC adapter for Adabas on the z/OS platform to handle capture changes to the Adabas data.

To work with the Adabas CDC adapter, you must set up the ATTSRVR started task, set up the tracking file, and register archived PLOG files. After you finish making the required configurations on the z/OS computer, configure the change data capture using the Oracle Studio CDC Solution perspective. Oracle Studio must be installed on a Windows or UNIX computer

Do the following to set up the change data capture and configure the OracleAS CDC Adapter for Adabas:

• Setting up the ATTSRVR Started Task

• Setting up a Change Data Capture in Oracle Studio

• Setting up the Tracking File

• Deploying a Change Data Capture

Setting up the ATTSRVR Started Task

In the ATTSRVR started task STEPLIB, check that there is a DD card that defines the used Adabas load library.

Setting up a Change Data Capture in Oracle Studio

You set up the change data capture in Oracle Studio. Oracle Studio can be installed on Windows XP or Vista operating systems, or on UNIX.

A change data capture is defined in the CDC Solution perspective, which contains a series of links to guide you through the CDC set up process. The CDC solution perspective guides display the following symbols in front of a link to show you what tasks should be done, and what tasks were completed.

• Triangle: This indicates that there are subtasks associated with this link. When you click the link, the list expands to display the subtasks.

• Asterisk (*): This indicates that you should click that link and perform the tasks and any subtasks presented. If multiple links have asterisks, you can perform the marked tasks in any order.

• Check mark (✓): This indicates that the tasks for this link and any sublink are complete. You can double click the link to edit the configuration at any time.

• Exclamation mark (!): This indicates a potential validation error.

Carry out the following to set up a change data capture:

• Create a CDC Project

• Set up the CDC Server

• Set up the Staging Area Server

Create a CDC Project

Do the following to create a CDC Project

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

2. Open the CDC Solution perspective, click the Perspective button on the perspective toolbar and select CDC Solution from the list.

   The CDC Solution perspective opens with the Getting Started guide in the left pane of the workbench.

3. Click Create new project.

   The Create new project screen opens.

4. In the Project name field, enter a name for your project.

   The types of projects available are listed in the left pane.

5. Select Change Data Capture.

   From the right pane, select ADD Adabas (Mainframe) if you are using ADD data or Adabas (Mainframe) if you are using Predict data.

   Figure 2-8 Create New Project

   
   

6. Click Finish. The Project Overview guide is displayed in the left pane.

7. Click Design. The Design wizard opens. Use this wizard to enter the basic settings for your project.

   Note:

   The wizard screens are divided into sections. Some sections provide information only and other sections let you to enter information about the project. If you do not see any information or fields for entering information, click the triangle next to the section name to expand the section.

   Figure 2-9 Design Wizard (Design Options)

   
   

8. In the Client Type you can select Oracle SOA/ODI only. The Use staging area is selected and cannot be changed, you must use a staging area with the OracleAS CDC Adapter for Adabas.

9. Click Next.

   The Design Wizard's second screen is displayed. In this step you configure the machines used in your solution. Enter the following information:

   • Server Machine Details: Information about the machine where Oracle Connect is installed. The selection here is always Server Machine and Mainframe.

   • Staging Area Details: Information about the machine platform where the staging area is located.

     For the server machine Name, select one of the following:

     • CDC Stream Service: Select this if the Staging Area is on a staging area computer. This is the default selection.

     • Server Machine: Select this if the staging area is on the same machine where Oracle Connect is installed.

     • Client Machine: Select this if the Staging area is on the local compuer.

     In the Platform list, select the operating system for the staging area. This can be Windows, Linux or UNIX. The available options are:

     • Microsoft Windows

     • HP-UX

     • IBM AIX

     • Sun Solaris

     • Linux (Red Hat)

     • Suse (Linux)

   Figure 2-10 Design Wizard (Configure Solution Machines)

   
   

10. Click Finish. The wizard closes.

Set up the CDC Server

Click Implement in the Getting Started guide to open the Implementation guide.

In the Implementation guide, do the following to set up the CDC server:

• Set up the Machine

• Configure the Adabas Data Source

• Copy the Metadata

• Set up the CDC Service

Set up the Machine

You do the following to define the IP Address/host name and Port for the CDC server machine.

1. Click Machine.

   The machine definition screen is displayed:

   Figure 2-11 Machine Definition

   
   

2. In the IP address/host name field, do one of the following:

   • Enter the server machine's numeric IP address.

   • Click the Browse button and select the host machine from the ones presented, then click Finish.

     Figure 2-12 Select Machine

     
     

     Note:

     The machine you enter must be compatible with the platform designated in the Design Wizard (Configure Solution Machines) screen.

3. Enter the port number.

   The default port number is 2551.

4. To connect with user authentication, enter a user name and password, with confirmation, in the Authentication Information area.

5. Select the Connect via NAT with a fixed IP address check box if you are using Network Access Translation and want to always used a fixed IP address for this machine.

6. Click OK.

Continue setting up the CDC Server on the z/OS computer.

Configure the Adabas Data Source

In this step, configure the Adabas data source that is part of the Adabas ADD or Adabas Predict solution. Do the following to configure the data source.

1. In the CDC Solution perspective, click Implement.

2. In the Server Configuration section, click Data Source. The Data Source Configuration window is displayed.

3. Define the parameters for your data source in the Data Source Configuration window.

   • Database number: The Adabas database number.

   • PREDICT file number: The Precict file number. (For Adabas with Predict data only).

   • PREDICT database number: When the Predict file resides in a different database than the data indicate the database number in which the Predict file resides. If the Predict file resides in the same database, enter -1. (For Adabas with Predict data only).

4. Click Finish.

Continue setting up the CDC Server on the z/OS computer.

Copy the Metadata

Use this step for Adabas with ADD data only. If you are using Predict data, go to the Set up the CDC Service step. In this step, copy the metadata that you imported when Importing Metadata for the Adabas Data Source. Do the following to copy the metadata.

1. Click Metadata.

   The Create metadata definitions view is displayed.

   Note:

   The Select Metadata Source link has an asterisk (*) next to it to indicate that you must perform this operation first.

2. Click the Select Metadata Source link.

3. Select Copy from existing metadata.

4. Click Finish. The screen closes.

5. Click Copy from existing metadata source.

   The Copy Existing Metadata Source screen is displayed showing your local machine and with metadata compatible with the data source selected.

   Figure 2-13 Copy Existing Metadata Source

   
   

6. From the sources in the left pane, expand the list until you see the tables from the data source you configured when Importing Metadata for the Adabas Data Source.

7. Using the arrow buttons, select the required tables and move them into the right pane.

8. Once you have selected all the desired tables, click Finish.

9. Click Customize Metadata.

   The customize metadata screen is displayed.

   Note:

   If you do not want to make any custimizations to the metadata, click Finish to close this screen. A check mark (✓) appears next to Customize Metadata indicating that this step is complete.

   Continue with another step in the design wizard.

   Figure 2-14 Customize Metadata

   
   

10. To change a table name, right-click in the any field under Customize Metadata, and select Add.

11. Enter the table name in the field presented, and click OK.

    Note:

    You may have validation errors in the tables created, which you can correct by the end of the procedure.

12. To make changes to any field in a table, right-click the table created and select Fields Manipulation.

    The Field Manipulation screen is displayed.

    Figure 2-15 Field Manipulation

    
    

13. Right-click in the upper pane and select Field|Add|Field.

14. Enter the name of the field in the screen provided, and click OK.

15. Default values are entered for the table. To manipulate table information or the fields in the table, right-click the table and choose the option you want. The following options are available:

    • Add table: Add a table.

    • Field manipulation: Access the field manipulation window to customize the field definitions.

    • Rename: Rename a table name. This option is used especially when multiple tables with the same name are generated from the COBOL.

    • Set data location: Set the physical location of the data file for the table.

    • Set table attributes: Set table attributes.

    • XSL manipulation: You specify an XSL transformation or JDOM document that is used to transform the table definition.

    The Validation tab in the bottom half of the window displays information about what you must do 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).

16. Correct any remaining validation errors.

17. Click Finish to generate the metadata.

Continue setting up the CDC Server on the z/OS computer.

Set up the CDC Service

In this step you define the starting point or event for the change capture and then indicate the name of the change logger. Do the following to set up the CDC service.

1. In the CDC Solution perspective, click Implement.

2. In the Server Configuration section, click CDC Service. The CDC Service wizard is displayed.

3. In the first screen select one of the following to determine the Change Capture starting point:

   • All changes recorded to the journal

   • On first access to the CDC (immediately when a staging area is used, otherwise, when a client first requests changes

   • Changes recorded in the journal after a specific date and time.

     When you select this option, click Set time, and select the time and date from the dialog box that is displayed.

     Note:

     For the OracleAS Adapter for Adabas the time stamp is defined per block. The time stamp of a block is defined as the last event in a block. When you configure Set Stream Position by Timestamp, it is possible to get events that occurred before the requested event and reside in the same block as the event requested by the time stamp.

     When capturing all changes, this returns the changes from all Adabas archive files registered in the Oracle tracking file.

     When capturing changes from a specific time stamp, you can select a time that is later than the creation time of the last archive file created.

4. Click Next to define the logger. The following is displayed.

   Figure 2-16 CDC Logger Definition Window

   
   

5. In the Tracking file name field, enter the name of the tracking file used in the UE2 procedure. For more information, see the following:

   • The Tracking File

   • Setting up the Tracking File

   • Registering the Archived PLOG Files

6. In the Adabas version field, select the Adabas version you are working with from the list. If you are using a version earlier than version 7.4, then select V62; if you are using version 7.4, select V74.

7. Click Next to go to the next step where you set the CDC Service Logging. Select the log level to use from the Logging level list.

   Figure 2-17 Logging Level

   
   

   Select one of the following from the list:

   • None

   • API

   • Debug

   • Info

   • Internal Calls

8. Click Finish.

Continue setting up the CDC Server on the z/OS computer.

Set up the Staging Area Server

Click Implement in the Getting Started guide to open the Implementation guide.

In the Implementation guide, do the following under the Stream Service Configuration section, to set up the staging area server:

• Set Up the Staging Area Machine

• Set up the Stream Service

• Configure the Access Service Manager

Set Up the Staging Area Machine

To set up the machine for the staging area, do the following.

1. Under the Stream Service Configuration section, click Machine.

2. Use the same configurations used to Set up the Machine for the CDC server.

Continue setting up the staging area Server.

Set up the Stream Service

In this step you set up the stream service. The Stream Service configures the following:

• Staging area

• Filtering of changed columns

• Auditing

Note:

Null filtering is currently unsupported. Filtering empty values is supported. Space values are truncated and are handled as empty values.

1. Click Stream Service. The Stream Service wizard opens.

   Figure 2-18 Staging Area

   
   

   Note:

   This screen appears only if you selected the inclusion of a staging area in your solution.

2. You can configure the following parameters in this screen:

   • Select Eliminate uncommitted changes to eliminate uncommitted changes from your CDC project.

   • Select the Use secured connection check box to configure the staging area to have a secured connection to the server. This is available only if you logged into the server using user name and password authentication.

   • Set the event expiration time in hours.

   • Under File Locations, click the Browse buttons to select the location of the changed files, and temporary staging files, if necessary.

3. Click Next to select the tables to include in the filtering process.

   Figure 2-19 Select Tables

   
   

4. Click the required tables in the left pane and move them to the right pane using the arrow keys.

   Note: You can remove the tables and add new ones to be captured after you add the tables to the right pane. For more information, see Adding and Removing Tables.

5. Click Next. From the tables selected above, select the columns that receive changes. Select the check box next to the table to use all columns in the table.

   Figure 2-20 Column Selection

   
   

   Note:

   Table headers appear grouped in a separate table at the beginning of the list. You can also request the receipt of changes in the headers' columns.

   Any data changes in the columns selected are recorded.

6. Click Next. The Filter selection screen is displayed. the types of changes you want to receive in the tables and which columns to display.

   Figure 2-21 Filter Selection

   
   

7. You can do the following in this screen:

   Select the actions from which you want to receive change information:

   • • Update

     • Insert

     • Delete

     Note:

     These items are all selected by default.

   • Under the Changed Columns Filter column, select the columns for which you want to receive notification of changes.

     Notes:

     • If you do not select a column, you receive notification of all changes.

     • If you select only one, you receive change information only if the field selected undergoes a change.

     • If you make multiple selections, but do not select all, then you receive change information only if any or all of the selected fields undergo a change

8. In the Content Filter column of the Filter screen, double-click a table column and then click the Browse button to filter content from the selected column.

   The Content Filter screen is displayed.

   Figure 2-22 Content Filter

   
   

9. Select a filter type:

   • Select In for events to be returned where the relevant column value equals the values you specify (if a column is NULL, it is not captured).

   • Select Not In for events to be returned where the column value is not in the values you specify (if the column is NULL, it is captured).

   • Select Between for when the column value is between the two values you specify (if a column is NULL, it is not captured).

10. Click Add in the lower-left corner of the Content Filter screen.

    Note:

    If you select multiple conditions, you receive the change information if one condition is true.

11. Depending on your selection, do one of the following:

    • If you selected In/Not In, continue with step12.

    • If you selected Between, continue with step 14.

12. Click Add in the Add items to the list screen. Enter a value for events to be returned where the column value appears (or does not appear) in that value. To filter empty values ('') for the Not In filter type, leave this field blank in the dialog box that is displayed.

    Figure 2-23 Add Items (In or Not In)

    
    

13. Repeat steps 12 as many times as necessary, and then proceed to step 16.

14. Click Add in the Add items to list screen.

    The Add between values screen is displayed.

    Figure 2-24 Add Items (Between)

    
    

15. Enter values for events to be returned where the column value is between the two values you specify.

16. In the content filter screen, click Next.

    Figure 2-25 Auditing Configuration

    
    

17. Select the required auditing level when receiving changes. Your options are:

    • None: For no changes.

    • Summary: For an audit that includes the total number of records delivered and system and error messages.

    • Headers: For an audit that includes the total number of records delivered, system and error messages, and the record headers for each captured record.

    • Detailed: For an audit that includes the total number of records delivered, system and error messages, the record headers for each captured record, and the content of the records.

18. Click Finish.

Continue setting up the staging area Server.

Configure the Access Service Manager

In this step you set up a daemon workspace for the CDC adapter. Do the following to configure the access service manager.

1. Click Access Service Manager.

   The Setup Workspace wizard opens.

   Figure 2-26 Select Scenario

   
   

2. Select the scenario that best meets your site requirements:

   • Application Server using connection pooling

   • Stand-alone applications that connect and disconnect frequently

   • Applications that require long connections, such as reporting programs and bulk extractors

3. Click Next.

   The Application Server with connection pooling scenario screen is used to create a workspace server pool. The parameters available depend on the selection you made in the first screen. The following are the available parameters:

   • If you selected Application Server using connection pooling:

     • What is the average number of expected concurrent connections? Enter the number of expected connections, which cannot be greater than the number of acutal available connections.

     • What is the maximum number of connections you want to open? Enter the number of connections you want opened.

   • If you selected Stand-alone applications that connect and disconnect frequently, in addition to the choices listed in the item above, you can also set the following:

     • What is the minimum number of server instances you want available at any time? Enter the number of instances, which cannot be greater than the number of actual available instances.

     • What is themaximum number of server instances you want available at any time? Enter the number of instances you want to be available.

   • If you selected Stand-alone applications that connect and disconnect frequently:

     • How many connections do you want to run concurrently? Enter the number of concurrent connections to run.

4. Click Next. In the next screen you set time out parameters. These parameters should be changed if the system is slow or overloaded. The parameters are:

   • How long do you want to wait for a new connection to be established? Enter the amount of time you want to wait for a new connection to be established (in seconds).

   • How long do you want to wait for a response that is usually quick? Change this parameter if you have a fast connection. Enter the amount of time to wait for a response (in seconds).

5. Click Next. In the next screen you set security parameters. You should consult with the site security manager before changing these parameters.

   Edit the following parameters in this screen:

   • Enter the operating system account (user name) used to start server instances.

   • Select Allow anonymous users to connect via this workspace, to allow this option.

   • Enter the permissions for the workspace. You can allow All users to access the workspace, or select Selected users only to allow only the selected users/groups to have exclusive access.

   • Select Do you want to access server instances via specific ports, to allow this option. If this option is cleared, the defaults are used.

     If you select this option, indicate the From port and To port and ensure that you reserve these ports in the TCP/IP system settings.

   Figure 2-27 Site Security

   
   

6. Click Next.

   The summary screen opens.

   Figure 2-28 Workspace Setup Summary

   
   

7. Click Save and then click Finish.

When you complete all the Implementation operations, a check mark (✓) is displayed next to every link. Click Done to return so you can begin Deploying a Change Data Capture.

Continue setting up the staging area Server.

Setting up the Tracking File

To enable Adabas CDC, you must do the following:

• Create the Tracking File

After creating the tracking file, you should do one of the following procedures:

• Registering the Archived PLOG Files

• Registering the PLOG Files using a Generation Data Group (GDG)

Create the Tracking File

Use the following procedure to create the tracking file:

To create the tracking file

• Edit and submit the JOB from the BADATRF member of NAVROOT.USERLIB.

  The following shows the BADATRF member:

  //BADATRF JOB 'RR','TTT',MSGLEVEL=(1,1),CLASS=A,// MSGCLASS=A,NOTIFY=&SYSUID,REGION=8M//DEFTRF EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//SYSIN DD *DEFINE CLUSTER -(NAME(navroot.DEF.ASADATRF.DBXXX) -INDEXED -UNIQUE -VOL(DEV001) -TRACKS(10 1) -RECORDSIZE(256 1024) -KEYS(14 0) -SHAREOPTIONS(3 3)) -DATA -(NAME(navroot.DEF.ASADATRF.DBXXX.DATA)) -INDEX -(NAME(navroot.DEF.ASADATRF.DBXXX.INDEX))//VERTRF EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//SYSIN DD *LISTCAT ENTRIES('navroot.DEF.ASADATRF.DBXXX') ALL/*
  

• To edit this file, you should:

  • Change navroot to the used Oracle HLQ.

  • Change DBXXX so that the XXX specifies the used Adabase database number.

  • Change the JOB card according to your site demands.

Registering the Archived PLOG Files

You must provide a procedure to save the archived PLOG files on DASD and register them in the tracking file. If the UE2 procedure used by Adabas saves the archived files on DASD, you can update this procedure as described in the following example. In other cases, you must provide your own procedure that copies the arechive files to DASD and registers them. In all cases, the registration step should be defined as follows:

//name EXEC PGM=UADATRF,PARM='<parameters>'
//STEPLIB DD DISP=SHR,DSN=navroot.LOAD
//ASADTRF DD DISP=SHR,DSN=<tracking file name> 

The UADATRF program recieves two positional parameters:

• The name of the archive file.

• The length of the STCK (store clock). The value of this parameter depends on the Adabas version.

  If using an Adabas version 7.4 or later, then set this parameter to a value of 8. This value indicates that the store clock uses 8 bytes.

  For Adabas versions earlier than version 7.4, use a value of 4.

The following is an expample of the registration step in the UE2 procedure:

//ASUPDBSD EXEC PGM=UADATRF,// PARM='ADB.PLOG.D&SDATE..T&STIME 8'
//STEPLIB DD DISP=SHR,DSN=Oracle.LOAD//ASADTRF DD DISP=SHR,DSN=Oracle.DEF.ADATRF.DB005

Registering the PLOG Files using a Generation Data Group (GDG)

When you restore the archived PLOG files to DASD from cartridges or tapes, you must use GDG to store the archived PLOGS. In this case, always copy each archive log to GDG 0 generation. The UADATRF program translates the GDG data set name to its physical name and saves it in the tracking file.

The following is an example of the registration step:

//ASUPDBSD EXEC PGM=UADATRF,// PARM='ADB.GDG.PLOG(0) 8'
//STEPLIB DD DISP=SHR,DSN=Oracle.LOAD//ASADTRF DD DISP=SHR,DSN=Oracle.DEF.ADATRF.DB005

Deploying a Change Data Capture

After you complete the design and implementation guides, the following procedures are available.

• Deployment Procedure: This section is used to deploy the project.

• Control: This section is used to activate or deactivate workspaces after the project is deployed and you are ready to consume changes. In this section, you can deactivate the workspace anytime you want to suspend consumption of changes from the staging area.

Do the following to deploy the CDC solution:

1. Click Deploy. The Deployment Procedure and Control sections are displayed in the Deployment view.

2. Click Deploy in the Deployment Procedure section.

   ­Oracle Studio processes the naming information. This may take a few minutes. If there are naming collisions, a message is displayed asking if you want Oracle Studio to resolve them.

   Figure 2-29 Resolve Naming Collision

   
   

3. Click Yes to resolve any naming collisions.

   The Deployment Guide screen is displayed.

   Figure 2-30 Deployment Guide

   
   

4. If you are ready to deploy, click Finish.

   Otherwise, click Cancel and you can return to Create a CDC Project, Set up the CDC Server, or Set up the Staging Area Server to make any changes.

   If this project was deployed previously, you are notified that re-deployment overrides the previous instance.

   Notes:

   • When you redeploy a project where the metadata is changed, the Staging Area (SA) tables should be deleted so that no incorrect information is reported.

   • When you redeploy a solution, a new binding is created for the solution. The new binding is created with the default parameters only. Any temporary features that were added are lost.

5. Where applicable, click OK to redeploy.

6. Click the Deployment Summary link.

   The Deployment Summary is displayed. It includes the ODBC connection string, JDBC connection string, and specific logger scripts to enable CDC capturing.

   Figure 2-31 Deployment Summary

   
   

7. Cut and paste any information required from the Deployment Summary screen to your environment as necessary.

8. If there is nothing wrong with your deployment results, click Finish.

   If you found problems, click Cancel and to return Create a CDC Project, Set up the CDC Server, or Set up the Staging Area Server to modify the solution.

Note:

If you are redeploying a solution you must follow these directions to ensure that the context and adapter_context fields of the SERVICE_CONTEXT table are saved. Follow these directions to save the fields:

1. In the staging area data source run: select context, agent_context from SERVICE_CONTEXT; and save the returned values.

2. Delete the SERVICE_CONTEXT table physical files.

3. Redeploy the solution.

4. Activate the router to create the SERVICE_CONTEXT table.

5. Disable the router.

6. In the staging area data source run: insert into SERVICE_CONTEXT (context, agent_context) values('XXX', 'YYY'). This inserts the saved values to the SERVICE_CONTEXT table.

7. Activate the solution.

Activating and Deactivating Solution Workspaces

In the Project guide for your OracleAS CDC Adapter solution, click Deploy, then do one of the following to activate or deactivate the workspaces for a solution

• To activate workspaces, under the Control section iclick the Activate Workspaces link.

• To deactivate workspaces, click the Deactivate Workspaces link.

During the activation/deactivation process, you may receive messages indicating that the daemon settings on one or more of the machines involved in your solution have changed. Click Yes to proceed.