| Oracle® Transparent Gateway for DB2 Installation and User's Guide 10g Release 2 (10.2) for IBM z/OS (OS/390) Part Number B16220-02 |
|
|
View PDF |
| Oracle® Transparent Gateway for DB2 Installation and User's Guide 10g Release 2 (10.2) for IBM z/OS (OS/390) Part Number B16220-02 |
|
|
View PDF |
Oracle Net for z/OS supports network communications between Oracle applications and Oracle gateway systems across different z/OS systems and different operating systems. Oracle provides OSDI listener (ORANET). This chapter describes how to configure it. For more information on Oracle Net, refer to the Oracle Database Net Services Administrator's Guide.
This chapter includes the following sections:
The OSDI listener (ORANET), also referred to as the Net service, runs as a service under an OSDI subsystem. In Oracle8i, Release 8.1.7 and Oracle9i, Release 1, all TCP and LU62 connections by Oracle applications, both client and server, were performed through the Net or Net8 service. Now, all Oracle clients on z/OS open their own sockets.
The OSDI listener's primary function is to listen for inbound remote connections to an Oracle instance. For compatibility purposes, the OSDI listener still provides outbound connectivity services for Oracle9i, R1 and Oracle8i, 8.1.7 Oracle clients.
Note that in the case of a database link from an OSDI database instance to an OSDI gateway instance, the OSDI database instance is considered as an Oracle client in the context of OSDI listener for the Oracle gateway instance. Moreover, if the OSDI database instance resides in the same OS390 image as the OSDI gateway instance, then Oracle Net cross-memory protocol could be used.
An OSDI listener is not required for Oracle Net cross-memory protocol. The syntax of cross-memory protocol could be in either of two forms:
(DESCRIPTION=
(ADDRESS= (PROTOCOL=XM) (SUBSYS=snn) (SERVICE=service_name) )
(HS=) )
where ssn is the OSDI subsystem name and service_name is the OSDI gateway service name.
or:
(DESCRIPTION=
(ADDRESS= (PROTOCOL=XM) (SID=gateway_sid) )
(HS=) )
where gateway_sid is the chosen OSDI gateway service SID.
Oracle recommends using the SID format for simplicity.
On z/OS, Oracle Net is implemented as a z/OS OSDI service running in its own address space separate from the gateway service. The OSDI service acts as a listener for the Oracle z/OS instances and gateway instances. All protocol-specific code runs inside the OSDI listener.
Remote clients that access an OSDI service through an OSDI listener are dispatched on a lightweight unit of work called an enclave SRB. An enclave is created either once per session or for each SRB depending on the ENCLAVE keyword (described under "PARM"). An SRB is scheduled each time work is required to be done by the kernel. The enclave is deleted when the SRB completes. The z/OS Workload Manager component may be used to control the execution characteristics of these enclave SRBs. Refer to the Oracle Database System Administration Guide for IBM z/OS (OS/390) for further details.
For client and server support, the OSDI listener uses the IBM macro implementation and a TCP/IP network to support network communications between the Oracle server and any remote OSDI listener TCP/IP client or server. For more information, refer to "TCP/IP Network Considerations".
The product documentation, Oracle Database Net Services Administrator's Guide, refers to files in the following form:
basename.extension
where:
| Variable | Description |
|---|---|
basename |
is the product name. |
extension |
is the extension. |
An example of this form is SQLNET.ORA.
These files are then converted to DD names. The following DD names are implemented under z/OS:
| DD name | Description |
|---|---|
SQLNET |
defines a data set containing any SQLNET.ORA diagnostic, ASO, or Oracle names parameters. It is not necessary to allocate this DD unless these features are desired. Refer to Oracle Database Net Services Administrator's Guide or the Oracle Database Advanced Security Administrator's Guide for more information. |
SQLNETTC |
defines a data set into which trace output is written. It is recommended that this be defined as a SYSOUT data set in a held output class. |
SQLNETLG |
defines a data set into which any logging output is written. It is recommended that this be defined as a SYSOUT data set in a held output class. |
TNSNAMES |
defines a data set containing all the TNS connect descriptors and aliases for your installation. For further information about TNS connect descriptors, refer to the Oracle Database Net Services Administrator's Guide. This DDname is not necessary on server JCL unless DBLINKS originates from the server. |
LDAP |
defines the location of the LDAP server. |
TNSNAV |
TNS client navigation. (Generally not used on z/OS.) |
INTCHG |
Interchange. (Generally not used on z/OS.) |
Example of diagnostic entries in SQLNET file
trace_file_client =/trace/sysout=x,hold trace_file_server =/trace/sysout=x,hold trace_file_agent =/trace/sysout=x,hold trace_level_client = 16 trace_level_server = 16 trace_level_agent = 16 trace_functions_all = yes
Example of TNSNAMES entry for use by DBLINK definition
G4XXDB2 =
(DESCRIPTION =
(ADDRESS=(PROTOCOL=TCP)(HOST=your.host.tcpip.name)
(PORT=port#)(SSN=net_sid))
(HS=)
(CONNECT_DATA=(SID=G4XX))
To create a Network Service under OSDI, you must first define the OSDI listener as a service using the OSDI DEFINE SERVICE command. In addition to defining the service, two other items must be set up before the service can be started. They are a JCL procedure and network protocol-specific (TCP/IP) configuration. After you have defined OSDI listener as a service and have set up the additional items, you can start the service, which creates a z/OS address space based on controls that you have specified.
The OSDI DEFINE SERVICE command is described completely in Appendix B. Below, we describe DEFINE parameter considerations that are specific to the OSDI listener.
The service name for Oracle Net can be anything that you want within the content limitations described in Appendix B.
This procedure specifies the name of a service JCL procedure that you will place in one of your system procedure libraries. The procedure need not exist when DEFINE SERVICE is issued, but it must be in place before the service is started. The procedure name can be anything that you choose or that the naming standards of your installation require. The requirements for this procedure are discussed in the "OSDI Listener Region JCL"section.
The PARM string is used to specify additional initialization parameters that are specific to the OSDI listener. These parameters are in the form of keywords and determine which protocols are initialized at OSDI listener startup as well as configuration and debugging features.
A description of the OSDI Listener keywords follows:
| OSDI Listener Keywords | Description |
|---|---|
HPNS |
specifies support for the TCP/IP protocol. |
ENCLAVE(SESS|CALL) |
specifies the duration of the enclave. When SESS is specified, the enclave is created at logon and deleted at logoff. When CALL is specified, the enclave is created when the server is sent a request and is deleted when the server waits for a receive. |
PORT(nnnn) |
specifies the TCP/IP port number (nnnn) on which to listen for incoming connections. The default is 1521. |
GTF |
may be specified at the request of Oracle Support Services. This allows the OSDI listener internal trace to be captured to the z/OS Generalized Trace Facility. |
DUMP(nodename) |
specifies the high level node, or nodes, of transaction dump data set names. The character string can be up to 26 characters in length, must follow the rules for z/OS data set names, and must not end with a period. When an OSDI listener transaction dump occurs, the value defined here will be prefixed to a string that includes a time and date stamp to generate a unique data set name. The default is ORACLE.TRANDMP. |
DEFINE SERVICE NET92 TYPE(NET) PROC(ORANET92) -
DESC(' Oracle Network Service 9.2') -
SID(NETG) -
PARM('HPNS GTF PORT(1521)) DUMP(ORACLE.TRANDMP)')
Note:
The entirePARM() string must be on one line.Note:
if you have an active OSDI database instance, you could use an existing OSDI subsystem for the Oracle gateway instance and/or use existing NET service instance for the Oracle gateway instance.As with a gateway service, a JCL procedure must be placed in a system procedure library prior to attempting a start of the service. The OSDI listener JCL procedure name must have an associated z/OS user ID. Refer to the next topic, "TCP/IP Network Considerations" for details. The EXEC card of the JCL must be equivalent to the following:
//NET EXEC PGM=ORANET,REGION=0M
REGION=0M is specified to ensure that the service can allocate as much private virtual memory as it needs. Some z/OS systems may prohibit or alter a REGION parameter such as this, so you might want to check with your systems programmer to determine if any changes must be made to allow the system to accept your REGION parameter. In addition, the following DD statements are required:
STEPLIB: This DD statement should point to the Oracle-supplied AUTHLOAD which contains the gateway and Net load modules.
NET8LOG: Connection-related informational messages, warning messages, and error messages are written to this sequential output file. Oracle recommends that it also be assigned to a JES spool file.
Note:
The OSDI listener JCL procedure name must have an associated z/OS user ID. Refer to the next topic, "TCP/IP Network Considerations", for details.//NET EXEC PGM=ORANET,REGION=0M //STEPLIB DD DSN=ORAN.ORAV.AUTHLOAD,DISP=SHR //NET8LOG DD SYSOUT=X
2000034 09:50:35.0 MIN0017I message service subtask initialized 2000034 09:50:35.0 MIN0016I command service subtask initialized 2000034 09:50:35.1 MIN0018I bind/unbind service subtask initialized 2000034 09:50:35.2 MIN0026I timer service subtask initialized 2000034 09:50:35.2 MIN0002I networking service NETC initialization complete 2000034 09:50:35.2 MIN0005I global vector is at 19F0A000 2000034 09:50:35.2 MIN0024I connected to WLM subsystem OSDI 2000034 09:50:50.4 MIN0700I HPNS INITAPI call performed. RC=0000, EC=00000 2000034 09:50:50.5 MIN0724I HPNS GHBY INITAPI call performed. RC=0000, EC=00000 2000034 09:50:51.1 MIN0728I HPNS KID INITAPI call performed. RC=0000, EC=00000 2000034 09:50:51.1 MIN0728I HPNS KID INITAPI call performed. RC=0000, EC=00000 2000034 09:50:51.1 MIN0728I HPNS KID INITAPI call performed. RC=0000, EC=00000 2000034 09:50:51.2 MIN0728I HPNS KID INITAPI call performed. RC=0000, EC=00000 2000034 09:50:51.2 MIN0728I HPNS KID INITAPI call performed. RC=0000, EC=00000 2000034 09:50:51.2 MIN0728I HPNS KID INITAPI call performed. RC=0000, EC=00000 2000034 09:50:51.2 MIN0713I I am listening on port 01522 socket 00000 2000034 10:05:58.8 MIN0733I Socket 0000 connected Subtask Kid1, IP 144.025.040.217, Port 01129. 2000034 10:05:58.8 MIN0733I Socket 0000 connected Subtask Kid2, IP 144.025.040.217, Port 01130. 2000034 12:00:13.9 MIN0098I networking service NETC termination in progress 2000034 12:00:18.9 MIN0722I HPNS Kid #003 shut down. 2000034 12:00:18.9 MIN0722I HPNS Kid #001 shut down. 2000034 12:00:18.9 MIN0722I HPNS Kid #006 shut down. 2000034 12:00:18.9 MIN0722I HPNS Kid #002 shut down. 2000034 12:00:18.9 MIN0722I HPNS Kid #005 shut down. 2000034 12:00:18.9 MIN0722I HPNS Kid #004 shut down. 2000034 12:00:18.9 MIN0723I HPNS Gethostbyname subtask ended. 2000034 12:00:18.9 MIN0721I HPNS shut down, GoodBye. 2000034 12:00:18.9 MIN0091I timer service subtask terminated 2000034 12:00:18.9 MIN0095I bind/unbind service subtask terminated 2000034 12:00:18.9 MIN0093I command service subtask terminated 2000034 12:00:18.9 MIN0094I message service subtask terminated MIN0000I End of Net8 Log.
The OSDI Listener uses the MACRO API interface for TCP/IP, and distributes the communications processing workload across multiple tasks in the OSDI listener address space.
If the IBM stack is being used, then particular attention must be paid to the MAXFILEPROC and MAXSOCKETS parameters (under AF_INET) in the BPXPRMxx member of SYS1.PARMLIB. These parameters must be set high enough to support the expected connection load. Both of these parameters can limit the number of connections that the OSDI listener will be able to open. Also, the OSDI listener JCL procedure name must have an associated z/OS user ID in order to use TCP/IP, which is controlled by z/OS UNIX System Services. The user ID must have an OMVS RACF segment (or equivalent, if a product other than RACF is used) if the installation is not using a default OMVS segment.
In addition, the interface resolves names through the standard GETHOSTBYNAME API. Thus the resolution depends on how IBM TCP/IP is configured. If a DNS is defined to TCP/IP, then it will be used. Otherwise, TCP/IP will default the processing to its SITEINFO file. Also, IBM's Language Environment run-time library (LE) must be available through a STEPLIB DD or linklist to the OSDI listener address space in order for GETHOSTBYNAME to work. This is an IBM requirement. TNS does a GETHOSTBYNAME call at startup to test the function. This call may take minutes to complete if a busy name server is involved. The interface is not ready for work until the MIN0713I message is displayed on the system console. For more information about the GETHOSTBYNAME API, refer to the relevant IBM documentation on TCP/IP.
Note:
In this section, the term 'client' refers to the Oracle integrating server in the context of a database link session to an OSDI gateway instance.Remote (inbound) clients access Oracle gateway instances through the OSDI listener as follows:
The OSDI network service listens on a single endpoint (network address) for each protocol. All remote clients that go through a particular OSDI listener with a particular protocol use the same network address regardless of which gateway instance they want to access. All TCP/IP clients specify the same host name (or IP) and port number.
Clients indicate the target gateway instance that they want with the '(CONNECT_DATA=(SID=ssss))' clause in the OSDI listener address string.
The following is an example of a tnsname entry for a database link from a remote Oracle database server to an OSDI gateway instance through TCP/IP.
(DESCRIPTION= (ADDRESS= (PROTOCOL=TCP)(HOST=MVS08)(PORT=1999) ) (HS=) (CONNECT_DATA=(SID=TGD4) ) )
MVS08 is the host name that the gateway resides in. 1999 is the port number that OSDI NET listens on that serves the gateway instance. TGD4 is the OSDI TG4DB2 SID it is trying to connect to.
Note that if the remote Oracle database server is an OSDI database instance of release 9.1 or earlier, then you would need to specify SSN parameter (within the ADDRESS specification) that specifies the OSDI NET SID that serves the outbound traffic for the OSDI database instance.
For MPM and OSDI compatibility, refer to Chapter 11.
Oracle clients on z/OS are also able to use an Oracle Names or LDAP server running on another platform to resolve connection requests. The following samples of the OSDI listener configuration file are required to make use of this service.
SQLNET DD or SQLNET.ORA Definitions
###############
# Names .........: (CONNECT_TIMEOUT = 0) -MUST- be specified
###############
NAMES.DEFAULT_DOMAIN = world
NAMES.DEFAULT_ZONE = my.domain.com
NAMES.DIRECTORY_PATH = (TNSNAMES,ONAMES,LDAP)
NAMES.PREFERRED_SERVERS =
(ADDRESS_LIST =
(DESCRIPTION =
(ADDRESS =
(PROTOCOL = TCP)
(HOST = names_host)
(Port = 1575)
)
(CONNECT_TIMEOUT = 0)
)
)
##
The OSDI listener is started by the OSDI subsystem start command, for example:
ORSS START NET
This command would start the OSDI listener defined in the earlier example for "Example of Network Service Definition" if the subsystem were named 'ORSS'. You should then see the OSDI listener PROC start up followed by the following messages from the OSDI listener address space:
MIN0001I networking service initializing
MIN0002I networking service NET8 initialization complete
MIN0713I I am listening on port 01521 socket 00000
Additional messages are written to the NET8LOG DD, but message traffic to the console is limited to error and warning messages.
Several commands are available for communicating with a running Net service. Commands are issued using the z/OS MODIFY (or F) system operator command with the general format:
F name,cccc pppppp
where:
| Variable | Description |
|---|---|
name |
is the jobname or identifier of the OSDI listener |
cccc |
is a command verb from the table below |
pppppp |
represents an appropriate parameter for that command |
Table 6-1 Command Verbs for z/OS MODIFY (or F) System Operator Command
| Command | Parameter | Description |
|---|---|---|
|
|
|
Starts support for the specified protocol in the OSDI listener. |
|
|
|
Stops support for the specified protocol. |
|
|
|
Displays information about existing connections for the specified protocol or storage pool statistics. |
The OSDI listener can be stopped with the z/OS stop command (STOP or P), as in 'p net', or through the OSDI subsystem stop command, as in 'ORSS STOP NET'. In either case, the following messages will be seen on the console:
MIN0098I networking service NET termination in progress MIN0721I HPNS shut down, GoodBye. MIN0099I networking service termination complete
The OSDI listener service will also respond to the OSDI subsystem 'display' and 'display long' commands with appropriate information from the address space. Finally, the OSDI subsystem 'drain' command will prevent any new connections on either protocol. Existing connections will not be affected. The OSDI subsystem 'RESUME' command will restore the ability of clients to establish new connections through the OSDI listener.
The OSDI listener provides a utility program called TRCASST that formats the trace files OSDI listener can produce. You may be asked to run TRCASST to help gather diagnostic information required by Oracle Support Services. Sample JCL for TRCASST is provided in oran.orav.SRCLIB(TRCASST).
Before you use TRCASST, ensure that the trace files have not been created with carriage control. TRCASST will be unable to process such files.
When TRCASST runs, the TNSUSMSG DD name must point to a PDS containing a TNSUS message file. This file was placed into oran.orav.MESG(TNSUS) during OSDI listener installation.
The OSDI listener supports CHECKSUM and encryption algorithms. The following sections describe a basic method of verifying this feature, if it is to be used by your site. The easiest way to tell if Oracle Advanced Security Option (ASO) encryption is attempting to work is to deliberately set wrong configuration parameters and attempt a connection between the server and client. Incorrect parameters cause the connection to fail.
After receiving the expected failure message, set the configuration parameters to the correct settings and try the connection again. ASO encryption is working properly if no further error messages are received.
The following procedures test ASO encryption by this method. The incorrect parameter settings produce error 12660.
Perform the following steps to set up ASO encryption:
Set ASO encryption parameters for the server.
Set ASO encryption parameters for the client.
Use ISPF to edit the OSDI listener configuration file on the z/OS system (server system) to add the following parameters and values. If the server is remote (not z/OS), then use the appropriate editor for the server platform to change SQLNET.ORA.
SQLNET.CRYPTO_CHECKSUM_SERVER = REJECTED
SQLNET.ENCRYPTION_SERVER = REJECTED
SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER = (MD5)
SQLNET.ENCRYPTION_TYPES_SERVER = (DES40,RC4_40)
SQLNET.CRYPTO_SEED = "abcdefg"
The value shown for SQLNET.CRYPTO_SEED is only an example. Set it to the value you want. Refer to the Oracle Database Advanced Security Administrator's Guide for more information.
Edit the OSDI listener configuration file on the client system to add the following parameters:
SQLNET.CRYPTO_CHECKSUM_CLIENT = REQUIRED
SQLNET.ENCRYPTION_CLIENT = REQUIRED
SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT = (MD5)
SLQNET.ENCRYPTION_TYPES_CLIENT = (DES40,RC4_40)
SQLNET.CRYPTO_SEED = "abcdefg"
The value shown for SQLNET.CRYPTO_SEED is only an example. Set it to the same value used on the server system.
After completing Steps 1 and 2 of the configuration procedure, you are ready to test the operation of the ASO encryption.
Connect client and server.
Reset configuration parameters on server.
Attempt a connection between the server and client systems. You should receive the following error message:
ORA-12660: Encryption or crypto-checksumming parameters incompatible
Change the ASO encryption parameters on the server to:
SQLNET.CRYPTO_CHECKSUM_SERVER = REQUIRED SQLNET.ENCRYPTION_SERVER = REQUIRED
Attempt the connection between the client and server again. If no error message is returned and the connection completes, then ASO encryption is working properly.
