6 Advanced Features of OracleAS Adapter for VSAM

Oracle Connect includes a number of tuning parameters that can improve performance. Specifically, the daemon can be configured to optimize communication between the IBM OS/390 or z/OS platform and a client. In addition, the binding environment can be tuned to optimize the request handling.

This chapter contains the following sections:

Configuring the Daemon for High Availability
Configuring a Binding Environment
Migration Considerations
Security Considerations
Transaction Support

Configuring the Daemon for High Availability

The daemon workspace is responsible for allocating server processes to clients. You can configure a workspace to use a pool of server processes so that a server process is always available for a client request. Use Oracle Studio to maintain the daemon and the daemon workspace parameters to control the allocation of server processes and their management in a pool.

You can also have a number of daemon workspace configurations. Thus, you can create individual workspaces for use with different adapters.

Adding a New Daemon Workspace Configuration

Use Oracle Studio to add a new daemon configuration. You can set up different daemon configurations for different situations.

Perform the following steps to add a new daemon workspace configuration:

From the Start menu, select Programs, Oracle, and then select Studio.
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".
Expand the Daemons node. The daemon configurations available on this computer are listed.
Right-click IRPCD and select New Workspace. The New Daemon Workspace screen is displayed.
Specify a name for the new workspace and optionally add a description.
Specify whether you want it to have default settings or to copy the properties of an existing workspace.

To copy the properties of an existing workspace, click Ellipsis and select the workspace from which you want to copy the properties.
Click Next. The Select Scenario screen is displayed.
Select Application Server using connection pooling and click Next.
Continue through the wizard, specifying the required values for the workspace.
To complete the workspace definition, click Finish.

The workspace is displayed under the IRPCD daemon node.

Editing the Workspace

You edit a workspace by using the tabs described in the following table:

Tab	Description
WS Info	Specifies general information including the server type, the command procedure used to start the workspace, the binding configuration associated with this workspace and the timeout parameters.
WS Server Mode	Specifies workspace server information including features that control the operation of the servers started up by the workspace and allocated to clients.
WS Logging	Specifies parameters for logging and the format to use for a log file.
WS Security	Specifies administration privileges, user access, ports available to access the workspace and workspace account specifications.
WS Governing	This tab is not applicable for use with OracleAS Adapter for VSAM.

Use Oracle Studio to access these tabs, as follows:

From the Start menu, select Programs, Oracle, and then select Studio.
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".
Expand the Daemons node. The daemon configurations available on this computer are listed.
Expand the IRPCD node. The daemon workspaces are listed.
Right-click IRPCD and select Edit Workspace.
Select the tab which contains the information you want to edit. For full details of the tabs and the fields in these tabs, refer to "Workspaces".
After editing the workspace, click Save.

Configuring the Server Mode

The server mode dictates how the daemon starts up new processes. The daemon supports the following server modes:

singleClient: Each client receives a dedicated server process. The account in which a server process runs is determined either by the client login information or by the specific server workspace.

This mode enables servers to run under a particular user account and isolates clients from each other (because each receives its own process). However, this server mode incurs a high overhead due to process startup times and may use a lot of server resources (because it requires as many server processes as concurrent clients).
multiClient: Clients share a server process and are processed serially.
This mode has low overhead because the server processes are already initialized. However, because clients share the same process, they may impact one another, especially if they issue lengthy queries.
The number of clients that share a process is determined by the Clients per server limit (the maximum number of concurrent clients a server process for the current workspace accepts).
reusable: This is an extension of the single client mode. Once the client processing finishes, the server process does not die and can be used by another client, reducing startup times and application startup overhead.
This mode does not have the high overhead of single client mode because the servers are already initialized. However, this server mode may use a lot of server resources (because it requires as many server processes as concurrent clients).

The other modes can be set so that the server processes are reusable by setting the number of times a process can be reused with the Reuse limit value (the maximum number of times a particular server process can be reused or how many clients it can serve before it is retired). Reuse of servers enhances performance because it eliminates the need to repeat initializations. However, reuse runs a risk of higher memory leakage over time. The default value for the Reuse limit field is None, indicating that no reuse limit is enforced.

Set the server mode in the WS Server tab of the daemon workspace editor, as shown in the following figure: The daemon workspace server mode tab.
Description of the illustration wsserver.gif

When using any of the server modes you can specify a pool of server processes. These server processes are started when the daemon starts and are maintained in a pool. The server processes are available for use by new client requests from the pool, saving initialization time. Instead of starting a new server process each time one is requested by a client, the client receives a process immediately from the pool of available processes. When the client finishes processing, this server process either dies, or if reusable servers have been specified, it is returned to the pool.

You set up a pool of server processes by specifying the following parameters in the WS Server tab.

Initial number of servers: The number of server processes that are prestarted for this workspace when the daemon starts up. These are available for use by new client processes with minimal initialization time. Instead of starting a new server process each time one is requested by a client, the daemon immediately allocates (to the client) a server from a pool of available servers. When the number of available server processes drops lower than the value specified in the Minimum number of available servers field, the daemon again starts server processes until the specified number of available servers is reached. The default for this parameter is 0, meaning that no servers are prestarted for this workspace.
Minimum number of available servers: The minimum number of server processes in the prestarted server's pool before the Oracle Connect daemon resumes creating new server processes (up to the number specified in the Initial number of servers field value, described earlier). If this parameter is set to a value greater than that of the Initial number of servers field value, then the daemon considers the value to be the same as the value specified in the

Initial number of servers field. In this case, a new server process is started and added to the pool each time a server process is removed from the pool and allocated to a client). The default for this parameter is 0, meaning that new servers are created only when there are no other available servers.
Set maximum number of servers: The maximum number of available server processes pooled for this workspace. If the server is reusable, once a client disconnects from the server, then the daemon returns the server to the pool of available servers. If the limit is reached, then excess server processes are discarded.
Number of sub-tasks: The number of sub-tasks for a server that are prestarted for this workspace when the daemon starts up. In addition to setting up a pool of server processes as described earlier, you can set additional server processes as sub-tasks by specifying this parameter. Thus, setting 10 servers and 10 prestarted sub-tasks results in 100 tasks started (10 sub-tasks for each process).

Configuring a Binding Environment

Each binding configuration includes the following information:

Environment settings, which are used to configure the environment used by any of the adapters defined in the binding.
Application adapters on the current computer.

Configuring data sources and adapters is described in Chapter 3, "Deployment and Integration with the Oracle OC4J Container". To configure environment settings in Oracle Studio, perform the following steps:

From the Start menu, select Programs, Oracle, and then select Studio.
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".
Expand the Bindings node. The binding configurations available on this computer are listed.
Right-click NAV and select Edit Binding.
In the Properties tab, edit the environment settings as needed. To edit an environment setting, expand the property category and select the value to edit.

The binding Properties tab is shown in the following figure:

Description of the illustration bindenv.gif

The binding environment is divided into the following categories:

comm Category
debug Category
miscellaneous Category
odbc Category
oledb Category
optimizer Category
queryProcessor Category
transactions Category
tuning Category

These categories are described in the following paragraphs.

comm Category

The following table lists the parameters that define the communication buffers:

Parameter	Description
`comCacheBufferSize`	Specifies the size of a memory buffer on a client, which is used by the Oracle Connect client/server to store read-ahead data. The default is 200000 bytes.
`comMaxSocketSize`	Specifies the maximum bytes that can be written in one chunk on a socket. The default is -1 (no limitation).
`comMaxXmlInMemory`	Specifies the maximum size of an XML document held in memory. The default is 65535 bytes.
`comMaxXmlSize`	Specifies the maximum size of an XML document passed to another computer. The default is 65535 bytes.

debug Category

The following table lists the parameters that define debugging and logging operations:

Parameter	Description
`acxTrace`	When set to true, the input xml sent to the back-end adapter and the output xml returned by the back-end adapter, are written to the log.
`analyzerQueryPlan`	This parameter is not applicable for use with OracleAS Adapter for VSAM.
`gdbTrace`	This parameter is not applicable for use with OracleAS Adapter for VSAM.
`generalTrace`	When set to true, logs general trace information. The default writes only error messages to the log.
`logFile`	The high-level qualifier of the log file for messages. The following types of message are written to the log: Error messages. Trace information and information about the query optimization strategy if generalTrace is set to `true`.
`oledbTrace`	This parameter is not applicable for use with OracleAS Adapter for VSAM.
`optimizerTrace`	This parameter is not applicable for use with OracleAS Adapter for VSAM.
`queryWarnings`	This parameter is not applicable for use with OracleAS Adapter for VSAM.
`traceDir`	This parameter is not applicable for use with OracleAS Adapter for VSAM.

miscellaneous Category

The following table lists the parameters that define miscellaneous operations, including globalization support and the directory where temporary files are written:

Parameter	Description
`codepage`	For use with globalization support to identify the codepage for the workspace. See also: Appendix E, "Globalization Settings".
`cvtSeverityLevel`	The data type conversion policy when a conversion error occurs: 0 (Default): The data in the output column will be a null or empty value. 1: The data in the output column will be a null or empty value and the error is reported to the log. 2: An error is reported and processing stops
`edit`	This parameter is not applicable for use with OracleAS Adapter for VSAM.
`language`	Identifies the application language. A default codepage is selected based om the value specified for this parameter. See also: Appendix E, "Globalization Settings".
`nlsString`	Specifies the codepage used by a field whose data type is defined as "nlsString". Use this for a field whose codepage is other than that of the computer codepage. This parameter includes the following values: The name of the codepage. Whether the character set reads from right to left (as in middle eastern character sets). The default is false.
`tempDir`	The directory where temporary files are written, including the temporary files created for use by hash joins and for sorting files. The default is the current high-level qualifier.
`year2000Policy`	Determines the way 2-digit years are converted into 4-digit years. When the parameter year2000Policy is not set, or when it is set to a value outside the range of values defined for the policy, as described in the following paragraphs, a default value of 5 and the Sliding Base Year policy is used. Two policies are provided: Fixed Base Year: year2000Policy is set to a value greater than, or equal to 1900. In this case, the value of year2000Policy is the first 4-digit year after 1900 that can be represented by a 2-digit year. For example, if year2000Policy is set to 1905, the years 2000->2004 will be represented by 00->04. All other 2 digits will map to 19xx. This solution is most required if there is live data at the low end (close to the year 1900), which the user wants to keep with the current 2-digit format. The user will probably change the base date only after ensuring that these old dates have been deleted from the data source. Sliding Base Year: year2000Policy is set to a positive value less than 100. In this case, the value of year2000Policy represents the number of years ahead of the current year that can be represented by a 2-digit number. With each passing year the earliest year that can be represented by a 2-digit number changes to a year later.

odbc Category

The odbc parameters are not applicable for use with OracleAS Adapter for VSAM.

oledb Category

The oledb parameters are not applicable for use with OracleAS Adapter for VSAM.

optimizer Category

The following parameters enable you to customize the performance:

goal: The optimization policy, which can be specified as one of the following:

none (default): All row optimization is used.
first: First row optimization is performed based on the assumption that the results produced by the query are used as the rows are retrieved. The query optimizer uses a strategy that retrieves the first rows as fast as possible, which might result in a slower overall time to retrieve all the rows.
all: Optimization is performed based on the assumption that the results produced by the query are used after all the rows have been retrieved. The query optimizer uses a strategy that retrieves all the rows as fast as possible, which might result in a slower time to retrieve the first few rows.

Aggregate queries automatically use all row optimization, regardless of the value of this parameter.

queryProcessor Category

The following table lists the parameters which enable you to fine tune how queries are processed:

Parameter	Description
`compileAfterLoad`	For internal use.
`dsoThreadingBoth`	For internal use.
`emptyStringIsNull`	When set to "true", all empty strings are reported as "NULL".
`firstTreeExtensions`	The maximum size allowed for an SQL query after compilation. The default value is 150 KB.
`forceQualifiedNames`	For internal use.
`ignoreSegmentBindFailure`	For internal use.
`maxColumnsInParsing`	The maximum number of columns that a query references. The default is 500 columns.
`maxSqlCache`	The maximum number of SQL queries stored in cache memory. The default value is 3.
`noCommandReuse`	When set to true, sets Query Processor not to cache for reuse the fd state of a query.
`noCompilationCache`	When set to true, sets Query Processor not to save a successfully compiled statement in the cache.
`noDSPropertyCache`	For internal use.
`noInsertParameterization`	When set to true, sets Query Processor not to parameterize constants in INSERT statements.
`noMarkRowFailedFetch`	When set to true, enables Query Processor to continue fetching data after a failure in retrieving a row.
`noMetadataCaching`	When set to true, Query Processor does not take object metadata from the cache but directly from VSAM.
`noParallelExecution`	For internal use.
`noQueryParametrization`	When set to true, sets Query Processor not to convert constants into parameters when accessing VSAM.
`noQueryReadAhead`	For internal use.
`noSessionPooling`	For internal use.
`noSQSCache`	For internal use.
`noThreadedReadAhead`	For internal use.
`noThreads`	For internal use.
`noTreeAutoExtend`	For internal use.
`optimisticForUpdate`	When set to true, optimistic locking becomes the default for locking behavior.
`parserDepth`	The maximum depth of the expression list.
`proceduresCacheSize`	For internal use.
`promptDbUserPassword`	For internal use.
`tokenSize`	The maximum length of a string in an SQL query. The minimum value is 64. The default value is 350.
`useAlternateQualifier`	For internal use.
useTableFilterExpressions	When set to "true", enables the use of tables that have filter expressions specified in their metadata.

transactions Category

The following table lists the parameters that define the transaction support:

Parameter	Description
`convertAllToDistributed`	When set to "true", converts all simple transactions into distributed transactions.
`convertAllToSimple`	When set to "true", converts all distributed transactions into simple transactions.
`disable2PC`	When set to "true", disables two phase commit capabilities, even in drivers that support two phase commit.
`logFile`	The high-level qualifier and name of the log file that logs activity when using transactions. The logfile parameter can also include the keyword NORRS after a comma (so that the format is log,NORRS) when RRS is not running on the OS/390 or z/OS platform.
`recoveryDelay`	The number of minutes from the start of a transaction before any recovery operation on that transaction can be attempted. The default is 15 minutes.
`useCommitConfirmTable`	This parameter is not applicable for use with OracleAS Adapter for VSAM.

tuning Category

The following table lists the parameters that define the tuning:

Parameter	Description
`dsmMaxBufferSize`	The maximum size of a cache memory. This cache is used when memory is required on a temporary basis (as when Oracle Connect sorts data for a query output, for a subquery, or for aggregate queries). This cache size is not used for hash joins and lookup joins (see the `hashBufferSize` parameter). The default value is `1000000` bytes.
`dsmMaxSortBufferSize`	The maximum size of the sort buffers. Use this parameter instead of `dsmMaxBufferSize` for sorts only. The default value is `1000000` bytes.
`dsmMidBufferSize`	The maximum size of the index cache. This cache is not used for hash joins and lookup joins. The default value is `100000` bytes.
`hashBufferSize`	The amount of cache memory that is available for each hash join or lookup join. The default is `1000000` bytes.
`hashEnableParallelism`	Both sides of a hash join are read concurrently. The default is `true`.
`hashMaxDiskSpace`	The maximum amount of disk space (in MBs) that a query can use for hash joins. The default is unlimited (all the free space on the allocated disk). If a query requires more space than allocated through this parameter, then the query execution will stop. The minimum value for this parameter is 20 MB. Temporary files are written per query. Therefore, if several users can run queries at the same time, adjust the amount of space available, so that the total that can be allocated at any one time does not exceed the available space.
`hashMaxOpenFiles`	The maximum number of files that a query can open at one time for use when performing hash joins. The number assigned to this parameter must not exceed the system maximum. The default is 90 files.

Migration Considerations

You can migrate an adapter configuration from one platform to another. The configuration information is stored in the Oracle Connect repository on the source platform and is exported to an XML file which can then be imported to the target platform. Note that when migrating a configuration, any file names and paths that are specific to the source platform must be changed to valid files on the target platform.

To migrate an adapter configuration using Oracle Studio, perform the following steps:

From the Start menu, select Programs, Oracle, and then select Studio.
In the Configuration Explorer, right-click the computer defined in "Setting Up the IBM OS/390 or z/OS Platform in Oracle Studio" and select Export XML definitions.
Specify the path and name of the XML file where the XML representation of the computer and its complete configuration is stored.
Edit any paths in the XML definition to the paths required on the target platform. For example, the setting for the serverLogFile parameter may require changing, depending on the platform.
Set up the target platform in Oracle Studio in the same way you set up the source platform, as described in "Setting Up the IBM OS/390 or z/OS Platform in Oracle Studio".
In the Configuration Explorer, right-click the target computer and select Import XML definitions.
Import the XML file to the target platform.

Security Considerations

Oracle Connect works within the confines of the platform security system. For example, on an OS/390 computer with RACF installed, and with the workspace server mode set to multi-tasking, a RACROUTE VERIFY is performed for each task in the address space, according to the client connection.

In addition, Oracle Connect provides the following security:

Design Time: Security within Oracle Studio to grant access to Oracle Studio itself and to grant access to computers, user profiles and workspaces.
Run time: Security used to access VSAM, including controlling the daemon for the access.

Setting Design Time Security

Setting design time security is described in the following sections:

Securing access to Oracle Studio is described in "Setting Password Access to Oracle Studio".
Securing rights to configure a computer in Oracle Studio is described in "Specifying Users with Administrative Rights".
Securing access to user profiles is accomplished by right-clicking the relevant user profile in Oracle Studio and selecting Change Master Password. In the dialog box that is displayed, specify a password that must be provided in the future to edit the specific user profile.
Securing access to workspaces is accomplished by right-clicking the relevant workspace in Oracle Studio and selecting Set Authorization. In the dialog box that is displayed, specify a valid user and password that must be provided in the future to edit the specific workspace.

Setting Run Time Security

During run time, security considerations are implemented as follows:

When the client request accesses the legacy platform through the daemon, either anonymous access is allowed or a valid user name and password must be provided for the computer in the user profile. The userName and password properties in the J2CA 1.0 VSAM adapter are used at this stage to access the daemon.

Note:
The user name used to access the daemon must also be the name of a user profile used.
Access by the client must be through a valid port, according to the list of ports specified in the Workspace Access section of the WS Security tab in Oracle Studio. For details on the WS Security tab, refer to "WS Security".

Note:
Access to the legacy platform through a firewall using the NAT protocol is specified when the computer is added to Oracle Studio.
To be allocated a server process, the client must be granted anonymous access to the workspace or be listed in the Workspace Users section of the WS Security tab in Oracle Studio. For details of the WS Security tab, refer to "WS Security".
The ability to run commands on the daemon, such as starting or stopping a daemon or ending server processes is available only to administrators who have been registered in Oracle Connect as a daemon administrator. A client is registered as a valid daemon administrator in the Daemon Security tab in Oracle Studio, as described in "Daemon Security".

Note:
You can also specify administrators who can run commands only at the level of the workspace. Specify these administrators in the WS Security tab, as described in "WS Security".

Transaction Support

OracleAS Adapter for VSAM supports two-phase commit (2PC) and can fully participate in a distributed transaction.

Note:

To use OracleAS Adapter for VSAM under CICS with 2PC, you must have RRS installed and configured.

To work with 2PC, set the convertAllToDistributed transaction environment property to True, as shown in the following figure:

The convertAllToDistributed property set to true.

Description of the illustration tran2pc.gif

To use two-phase commit capability to access data on the OS/390 or z/OS computer, define every library in the ATTSRVR JCL as an APF-authorized library.

To define a DSN as APF-authorized, in the SDSF screen, enter the following command:

"/setprog apf,add,dsn=instroot.library,volume=ac002"

Where ac002 is the volume where you installed Oracle Connect and INSTROOT is the high level qualifier where Oracle Connect is installed.

If the Oracle Connect installation volume is managed by SMS, when defining APF-authorization, then enter the following command in the SDSF screen:

"/setprog apf,add,dsn=instroot.library,SMS"

Make sure that the library is APF-authorized, even after an IPL (restart) of the computer.

If RRS is not running, then OracleAS Adapter for VSAM can participate in a distributed transaction, as the only one-phase commit resource, if the transaction environment property logFile includes the keyword NORRS, as shown in the following figure:

Description of the illustration tran2pc1.gif

Note:

If a log file is not specified, then the format for the logFile parameter when RRS is not running is: ,NORRS.