This chapter explains how to configure access to Adabas data by using Oracle Studio for IMS, VSAM, and Adabas Gateways. It contains the following sections:
To be able to access Adabas data, you must have a working connection to Oracle Connect for IMS, VSAM, and Adabas Gateways, which is installed on the IBM z/OS computer where your Adabas files are located. You establish this connection by using Oracle Studio for IMS, VSAM, and Adabas Gateways.
Whenever needed, you can also use Oracle Studio for IMS, VSAM, and Adabas Gateways to configure Oracle Connect for IMS, VSAM, and Adabas Gateways.
Note:The following task assumes that you have permission to access the IBM z/OS platform and that the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon is running on this computer. Check with the system administrator to ensure these requirements are fulfilled.
Perform the following steps to set up access to a computer that runs Oracle Connect for IMS, VSAM, and Adabas Gateways.
From the Start menu, select Programs, point to Oracle, and select Studio. Oracle Studio for IMS, VSAM, and Adabas Gateways opens.
In the Design perspective's Configuration view, right-click the Machines folder and select Add Machines.
The Add machine screen opens, as shown in Figure 8-1.
Enter the following information in each field:
Host name/IP address: Enter the name of the machine on the network or click Browse, to browse all the machines running a daemon listener on the specified port currently accessible over the network.
Port: Enter the port number where the daemon is running. The default port is 2551.
Display name: Enter an alias used to identify the machine when different from the host name (optional).
User name: Enter the machine administrator's user name.
Note:You indicate the machine administrator when the machine is installed or by using the NAV_UTIL utility ADD_ADMIN operation. For details, see Oracle Connect Installation and Configuration Guide for IBM z/OS.
Password: Enter the machine administrator's password. This is the password for the user entered in the User name field. If no password is necessary to access this machine, do not enter anything.
Connect via NAT with fixed IP address: Select this if the machine uses the NAT (Network Address Translation) firewall protocol, with a fixed configuration, mapping each external IP to one internal IP, regardless of the port specified.
The computer is displayed in the Configuration view, in the Machine folder. You can edit the machine's login information, or configure bindings, daemons, and users for each machine.
Oracle Connect for IMS, VSAM, and Adabas Gateways supports the following types of Adabas data sources:
Adabas (Predict): The Adabas (Predict) data source uses Predict metadata.
ADD-Adabas: The ADD-Adabas data source uses Oracle's internal repository (ADD), which is usually imported from Natural Data Definition Module (DDM) files. Alternatively, Predict metadata can be exported and subsequently imported into the ADD-Adabas data source.
Both Adabas data sources provide very similar functions. The ADD-Adabas data source enjoys some added flexibility and functions resulting from the ability to customize the metadata in the ADD. Unless explicitly stated, all features and procedures described apply to both data sources.
This section describes how to set up an Adabas data source using Oracle Studio for IMS, VSAM, and Adabas Gateways. It includes the following tasks:
After you defined and configured the data source, proceed to Setting Up Adabas Data Source Metadata.
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:
Expand the Machines folder.
Expand the Bindings folder, and then expand the binding where the data is located.
Right-click the Data Source folder and select New Data Source.
The New Data Source screen is displayed, as shown in Figure 8-2.
In the Name field, enter a name for the new data source.
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
The Data Source Connect String screen is displayed.
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:
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.
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:
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:
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, *…).
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:
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:
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:
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:
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:
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.
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.
NULL suppressed fields that are part of a descriptor/super-descriptor are exposed as
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:
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:
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:
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:
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:
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:
Perform the following steps to configure the Adabas data source properties:
Right-click the data source and select Edit Data Source.
The Configuration Properties screen is displayed.
Select the Properties tab. The configuration properties are displayed.
Configure the data source parameters as required.
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.
Save your settings.
This section includes the following topics:
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:
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.
This parameter is at the end of the command. Separate the files in this list with spaces.
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.
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
Perform the following steps to export Predict metadata into Adabas ADD.
To export, execute the following NAV_UTIL command, according to your platform:
c:\> nav_util export table -native adapredict * adapredict.xml
$ 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'
To import, execute the following NAV_UTIL command, according to your platform:
c:\> nav_util import adaadd adapredict.xml
$ nav_util import adaadd adapredict.xml
MVS (After executing the NAVCMD Rexx script in USERLIB):
Local> import adaadd '<HLQ>.XML.ADAPRED'