8 Configuring Access to Adabas Data

8.2.1 Define the Adabas Data Source Connection

The Adabas data source connection is set using the Design Perspective's Configuration View in Oracle Studio for IMS, VSAM, and Adabas Gateways. Perform the following steps:

1. Expand the Machines folder.

2. Expand the Bindings folder, and then expand the binding where the data is located.

3. Right-click the Data Source folder and select New Data Source.

   The New Data Source screen is displayed, as shown in Figure 8-2.

   Figure 8-2 New Data Source Screen

   
   

4. In the Name field, enter a name for the new data source.

5. Select one of the following options from the Type list:

   • Adabas (Predict): to define an Adabas data source that is to use Predict metadata

   • Adabas (ADD): to define an Adabas data source that is to use Oracle metadata

6. Click Next.

   The Data Source Connect String screen is displayed.

7. Specify the connect string according to the data source type selected:

   • If you are defining an Adabas ADD data source, specify only the Database number.

   • If you are defining an Adabas Predict data source, specify the following:

     • Database number.

     • Predict File Number: The Adabas Predict file number that describes the specified database.

     • Predict database number: Specify this field only in case the Predict file does not reside in the same database as the data.

8. Click Finish.

8.2.2 Configure the Adabas Data Source Properties

After defining the connection, you set the data source properties.

The following properties can be configured for the Adabas data source in the Properties tab of the Configuration Properties screen:

• dbNumber: (Predict, ADD) The Adabas database number.

• predictFileNumber: (Predict only) The Predict file number.

• predictDbNumber: (Predict only) In some cases the Predict file is located in a different database than the data. If so, use this attribute to specify the database number in which the Predict file is located.

• svcNumber: (Predict, ADD; MVS only) 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 need to be accessed from a single installation. Each SVC will still require a different workspace, but the same GBLPARAMS and the same RACF profile can be used for the different workspaces.

• addMuInPeCounter: (Predict, ADD) Until version 4.6 Oracle Connect for IMS, VSAM, and Adabas Gateways 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'.

• defaultOccurences: (Predict only) If the Predict occurrences field for multiple value fields or periodic group fields is not specified, the value of this parameter is used. If a record is retrieved with more occurrences than specified, an error is returned. Default: defaultOccurances='10'.

• disableExplicitSelect: (Predict, ADD) This attribute indicates whether or not the Explicit Select option is disabled. If disabled, a select * query on an Adabas table will return all fields in the table, including ISN and subfields that 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 that 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' will prevent these fields from being created. Default: disregardNonselectable='false'.

• fileList: (Predict, ADD) 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 on the allowed syntax, visit the Software AG Documentation Web site at: http://documentation.softwareag.com/adabas/default.htm

  Note:

  Note that the value provided in this attribute is passed "as-is" to Adabas. No validation is performed. The default value grants unrestricted access to all files in the database: fileList='.'

• lockWait: (Predict, ADD) 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: (Predict only) 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: (Predict, ADD) 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 will generally retrieve rows to fill a 10k buffer. No more than 15 rows are fetch at once.

  • 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: (Predict, ADD) This attribute controls the behavior of the Adabas driver with regard to 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: (Predict, ADD) A scan strategy on a table is normally implemented by an L2 command. It is possible, however, to turn on this attribute in order to scan using the L1 command. This has the advantage of providing better data consistency at some performance penalty. Default: scanUsingL1='false'.

• supportL3Range: (Predict, ADD) Older versions of Adabas did not allow for a range specification on an L3 command (such as 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 in conjunction with driverTrace='true' in the environment. Turning on driverTrace will record 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: (Predict, ADD) 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 for IMS, VSAM, and Adabas Gateways, but some users have taken advantage of this feature to implement some specific 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: (Predict, ADD) This attribute indicates whether or not 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 need to be surrounded with double quotes. To avoid this inconvenience, the data source can translate all hyphens into underscores. Default: useUnderscore='true'.

• verifyMetadata: (Predict, ADD) This attribute indicates whether or not 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'.

Perform the following steps to configure the Adabas data source properties:

1. Right-click the data source and select Edit Data Source.

   The Configuration Properties screen is displayed.

2. Select the Properties tab. The configuration properties are displayed.

   Figure 8-3 Configuration Properties Screen

   
   Description of "Figure 8-3 Configuration Properties Screen"
   
   

3. Configure the data source parameters as required.

4. On the Advanced tab, configure how arrays will be handled by selecting the relevant check boxes in the Virtual View Policy section. The following options are available:

   • Generate sequential view: Select this option if you want to map a non-relation file to a single table.

   • Generate virtual views: Select this option if you want to have an individual table created for every array in the non-relational file.

   • Include row number column: Select this option if you want to include a column that specifies the row number in the virtual or sequential view.

   • Inherit all parent columns: Select this option if you want the virtual views to include all the columns of the parent record.

5. Save your settings.

8.3.1 Import Oracle 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 MVS platforms. MSV users need to perform the import on one of the supported platforms and then move the generated metadata to MVS.

The metadata is not imported using Oracle Studio for IMS, VSAM, and Adabas Gateways.

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

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

Table 8-1 lists the MDD file list format according to platform type.

8.3.2 Export Predict Metadata into Adabas ADD

Some users who have Predict still prefer to use ADD to store metadata. The process of moving metadata from Predict to ADD is simple, although manual. It involves exporting from Predict and importing to ADD. The process is carried out using the NAV_UTIL command line interface.

In the procedure below, for the purposes of the example, note first of all that the native qualifier is required. On the export side, the procedure generates all table definitions from a Predict data source called adapredict to an XML file. On the import side, the exported metadata is imported to a data source called adaadd.

Perform the following steps to export Predict metadata into Adabas ADD.

1. To export, execute the following NAV_UTIL command, according to your platform:

   • Windows: c:\> nav_util export table -native adapredict * adapredict.xml

   • UNIX: $ nav_util export table -native adapredict * adapredict.xml

   • MVS (After executing the NAVCMD Rexx script in USERLIB): Local> export table -native adapredict * '<HLQ>.XML.ADAPRED'

2. To import, execute the following NAV_UTIL command, according to your platform:

   • Windows: c:\> nav_util import adaadd adapredict.xml

   • UNIX: $ nav_util import adaadd adapredict.xml

   • MVS (After executing the NAVCMD Rexx script in USERLIB): Local> import adaadd '<HLQ>.XML.ADAPRED'