Oracle Net for z/OS supports network communications between Oracle applications and Oracle database systems across different z/OS systems and different operating systems. Oracle provides two listeners on z/OS, an OSDI listener (ORANET) and a generic listener (TNSLSNR). This chapter describes the two listeners and how to configure them. For more information about Oracle Net, refer to the Oracle Net Services Book Set.
The following topics are included:
Oracle provides two listeners on z/OS, an OSDI listener and a generic listener. On z/OS, Oracle Net is implemented as a z/OS OSDI service running in its own address space separate from the Oracle service. The OSDI service acts as a listener for the Oracle instances. All protocol-specific code runs inside the OSDI listener.
The OSDI listener (ORANET), also referred to as the Net service, runs as a service under an OSDI subsystem. Previously, TCP and LU62 connections by Oracle applications, both client and server, were performed through the Net or Net8 service. Starting with Oracle9i Release 2, all Oracle clients on z/OS open their own sockets and do not require a Net Service, as in prior releases.
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.
The generic listener is the Oracle listener (TNSLSNR) that runs in a UNIX System Services shell environment. It provides additional functionality that is not present in the OSDI listener. In particular, it provides support for external routines and shared servers.
To create a listener 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 that must be set up before the service can be started 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 z/OS address spaces based on controls that you have specified.
The OSDI DEFINE SERVICE command is described completely in Appendix A, "OSDI Subsystem Command Reference." This appendix describes the DEFINE parameter considerations that are specific to the OSDI listener.
The service name for OSDI listener can be anything that you want within the content limitations described in Appendix A.
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 section "OSDI Listener Region JCL".
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 and also the configuration and debugging features.
The following table lists and describes the OSDI listener keywords:
Table 8-1 OSDI Listener Keywords
Keyword | Description |
---|---|
Specifies support for the TCP/IP protocol. |
|
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. |
|
Specifies the TCP/IP port number |
|
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. |
|
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, then 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 |
|
Specifies that the client operating system USER ID and program name should be passed to the OSDI server. This is used by SMF and the logon exit. |
DEFINE SERVICE NET TYPE(NET) PROC(NET) - DESC('Oracle Network Service') - SID(NET) - PARM('HPNS GTF PORT(1521) DUMP(ORACLE.TRANDMP)')
Note:
The entirePARM()
string must be on one line.As with a database service, a JCL procedure must be placed in a system procedure library before attempting a start of the service. 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:
This DD statement should be the same as specified for the database service. Refer to "Database Region JCL".
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:
If the IBM TCP/IP protocol is used, 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= ORACLE.V10G.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 MAXFILEPROC and MAXSOCKETS parameters (under AF_INET) in the BPXPRMxx
member of SYS1.PARMLIB 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 to use TCP/IP, which is controlled by 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 runtime 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.
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 OSDI Listener Definition" if the subsystem were named 'ORSS'. The OSDI listener PROC should start and the following messages should display:
MIN0001I networking service initializing
MIN0002I networking service NET 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.
Commands for communicating with a running Net service are issued using the z/OS MODIFY (or F) system operator command with the following format, where name
is the jobname or identifier of the OSDI listener, cccc
is the command verb, and pppppp
is a parameter for the command verb:
F name,cccc pppppp
Command verbs and parameters for the z/SO MODIFY (or F) system operator command are listed in the following table:
Table 8-2 Command Verbs for z/OS MODIFY (or F) System Operator Command
Command Verb | Parameter | Description |
---|---|---|
|
|
Starts support for the specified protocol in the OSDI listener. |
|
|
Stops support for the specified protocol. |
|
|
Display 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, assuming both protocols were active:
MIN0098I networking service NET termination in progress MIN0721I HPNS shut down, GoodBye. MIN0099I networking service termination complete
The OSDI listener 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 the 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 oracle_hlq
.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 DDname must point to a PDS containing a TNSUS message file. This file was placed into oracle_hlq
.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.
This section contains information about setting up ASO encryption for testing.
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 the sqlnet.ora
file.
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 Oracle 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 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.
The generic listener, TNSLSNR, is required for Secure Socket Layer (SSL) connections to the RDBMS and Oracle external procedures. SSL connections also require Oracle shared server support. TNSLSNR runs in the POSIX shell environment on z/OS. For more information about the generic listener, refer to Oracle Net Services Administrator's Guide.
Note:
When running both theextproc
agent and shared servers, a separate listener should be used for each.On UNIX, the shared server architecture allows a relatively small number of Oracle server processes to support a much larger number of client sessions. For more information about shared server architecture on UNIX, refer to Oracle Database Concepts.
Although Oracle for z/OS does not employ a UNIX-like process model, the shared server configuration can be run within an OSDI service address space and is required for SSL connections. Except for the support of SSL connections, the use of shared server architecture on z/OS is not recommended. Shared servers on z/OS have the following limitations and restrictions:
All work is done using the velocity goal of the service address space.
All shared servers execute in a single address space.
Some UGA (User Global Area) is allocated from the SGA, which increases the size of the SGA and reduces the amount of the address space available to non-shared server work.
All sockets are owned by a single TCB no matter how many dispatchers are configured.
TCP connections are managed with the poll()
socket call instead of asynchronous I/O .
Shared server sessions may deadlock if all available servers become blocked on a lock.
Oracle external procedures are functions or procedures written in a third-generation language that can be called from PL/SQL code. The supported languages are C and Java. The user-written applications must be invoked in a POSIX shell environment and must be in DLL (dynamic loadable library) form. The use of external procedures requires the generic listener to listen for external procedure calls. For information about configuring the generic listener for external procedures, refer to "Configuring the Generic Listener for External Procedures". For more information about external procedures, refer to Oracle Database Application Developer's Guide - Fundamentals.
To set up an Oracle Net SSL connection, you must use shared servers and the Oracle generic listener, TNSLSNR, running in a POSIX shell environment. The following steps describe the files that must be configured for SSL connections.
The generic listener configuration steps are as follows:
In the server init.ora
file, specify a dispatcher to support the TCPS protocol. For example:
DISPATCHERS="(PROTOCOL=TCPS)"
MAX_DISPATCHERS=1
MAX_SHARED_SERVERS=10
LOCAL_LISTENER=listener
Variables for the previous example are defined, as follows:
listener
is the name of the listener as defined in the server tnsnames.ora
file.
In the server sqlnet.ora file,
specify the directory location of your wallet. For example:
WALLET_LOCATION= (SOURCE= (METHOD=file) (METHOD_DATA= (DIRECTORY=/u/cwang/wallet/v10) ) )
In the server and client tnsnames.ora
files, specify the connect descriptor to the listener.
In the server tnsnames.ora
file, you must add an entry for the listener that was specified in the DISPATCHERS parameters in the server init.ora
file. For example:
listener = (DESCRIPTION= (ADDRESS=(PROTOCOL=TCP) (HOST=hostname)(PORT=nnn1)) )
Client tnsnames.ora
file example:
ora6ssl = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCPS)(HOST = hostname)(PORT = nnn2)) ) (CONNECT_DATA = (SERVICE_NAME = service) ) )
Variables for the previous example are defined, as follows:
Table 8-3 Variable Definitions for Code Example
Variable | Definition |
---|---|
|
is the name of the listener |
|
is the name of the z/OS system where the OSDI RDBMS is running |
|
are the TCP port numbers on which the generic listener will listen for TCPS connections |
|
is the name of the service |
In the $ORACLE_HOME/network/admin/listener.ora
file, used by TNSLSNR, specify the ports and protocols that you will listen on, and specify the directory location of the wallet.
For example:
listener = (ADDRESS_LIST = (ADDRESS=(PROTOCOL=TCP) (HOST=hostname) (PORT=nnn1) ) << tnslsnr (ADDRESS=(PROTOCOL=TCPS) (HOST=hostname) (PORT=nnn2) ) << ports ) WALLET_LOCATION= << wallet locator (SOURCE= (METHOD=file) (METHOD_DATA= (DIRECTORY=/u/cwang/wallet/v10) ) )
Variables for the previous example are defined, as follows:
Table 8-4 Variable Definitions for Code Example
Variable | Definition |
---|---|
|
is the name of the listener |
|
is the name of the z/OS system where the OSDI RDBMS is running |
|
are the TCP port numbers on which the generic listener will listen for TCPS connections |
|
is the name of the service |
Perform the following steps to start the generic listener for SSL and shared servers:
Verify that the ORACLE_HOME environment variable is set to the same value that was used when you installed the Oracle Database.
From the POSIX shell environment, type lsnrctl start
and press the ENTER key to run the generic listener control program.
The following sample dialogue is typical of what you should expect when you run the generic listener control program with the default listener. Output is prefixed with the character ">". The ">" character will not appear on your screen.
Lsnrctl start > LSNRCTL for OSDI390: Version 10.1.0.2.0 - Production on dd-Mon-yyyy hh:mm:ss > (c) Copyright 1991, 2004, Oracle. All rights reserved. > > Starting $ORACLE_HOME/bin/tnslsnr: please wait... > TNSLSNR for OSDI390: Version 10.1.0.2.0 - Production > System parameter file is $ORACLE_HOME/network/admin/listener.ora > Log messagss written to $ORACLE_HOME/network/log/listener.log > Trace inforamtion written to $ORACLE_HOME/network/trace/listener.trc > Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=MVS05.US.ORACLE.COM)(PORT=3044))) > Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=MVS05.US.ORACLE.COM)(PORT=3007))) > Connecting to (address=(protocol=tcp)(host=mvs05)(port=3044)) > STATUS of the LISTENER > ------------------------ > Alias LISTENER > Version TNSLSNR for OSDI390: Version 10.1.0.2.0 - Production > Start Date DD-Mon-yyyy hh:mm:ss > Uptime 0 days 0 hr. 0 min. 1 sec > Trace Level support > Security OFF > SNMP OFF > Listener Parameter File $ORACLE_HOME/network/admin/listener.ora > Listener Log File $ORACLE_HOME/network/log/listener.log > Listener Trace File $ORACLE_HOME/network/trace/listener.trc > Listening Endpoints Summary... > (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=MVS05.US.ORACLE.COM)(PORT=3044))) > (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=MVS05.US.ORACLE.COM)(PORT=3007))) > This listener supports no services > The command completed successfully
The listener should now be running.
The following steps describe the files that must be configured for external routines in a POSIX shell environment.
As with other components that run in a POSIX shell environment, you must set your environment variables correctly, including $PATH, $LIBPATH, and optionally, $TNS_ADMIN. For more information, refer to Oracle Database User's Guide for IBM z/OS on System z.
On most UNIX systems the RDBMS connection to the extproc
agent is made through the Oracle IPC protocol (UNIX Domain Sockets). Oracle for z/OS does not support the IPC protocol, so the TCP protocol must be used instead. Since the use of the TCP protocol allows the external procedures to be invoked from anywhere on the network, special care is necessary when configuring the extproc
agent. It is recommended that the listener used for external procedures be configured as described in the Oracle Net Services Administrator's Guide.
The generic listener configuration steps are as follows:
Add to the Oracle Server TNSNAMES DD
an entry similar to the following:
EXTPROC_CONNECTION_DATA = (DESCRIPTION= (ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=nnnn)) (CONNECT_DATA=(SID=EXTPROC)) )
Variables for the previous example are defined, as follows:
Add to the $ORACLE_HOME/network/admin/listener.ora
file, used by TNSLSNR, an entry similar to the following:
listener = (address_list = (address=(protocol=tcp) (host=hostname) (port=nnnn) ) ) sid_list_listener = (sid_list = (sid_desc = (sid_name = extproc) (oracle_home = oraclehome) (program = extproc) ) )
Variables for the previous example are defined, as follows:
Table 8-6 Variable Definitions for Code Example
Variable | Definition |
---|---|
|
is the name of the listener |
|
is the name of the z/OS system on which the Oracle RDBMS is running |
|
is the TCP port number on which the generic listener will listen for TCP connections |
|
is the value of the ORACLE_HOME environment variable to use for the |
Perform the following steps to start the generic listener for external procedures:
Login to a POSIX shell environment with the user ID under which external procedures should run.
Verify that the ORACLE_HOME environment variable is set to the same value that was used when you installed the Oracle Database.
From the POSIX shell environment, type lsnrctl start listener
and press the ENTER key to run the generic listener control program.
The following sample dialogue is typical of what you should expect when you run the generic listener control program with the default listener. Output is prefixed with the character ">".
The ">"
character will not appear on your screen.
Lsnrctl start > LSNRCTL for OSDI390: Version 10.1.0.2.0 - Production on dd-Mon-yyyy hh:mm:ss > (c) Copyright 1991, 2004, Oracle. All rights reserved. > > Starting $ORACLE_HOME/bin/tnslsnr: please wait... > TNSLSNR for OSDI390: Version 10.1.0.2.0 - Production > System parameter file is $ORACLE_HOME/network/admin/listener.ora > Log messagss written to $ORACLE_HOME/network/log/listener.log > Trace inforamtion written to $ORACLE_HOME/network/trace/listener.trc > Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=MVS05.US.ORAC Lsnrctl start extproc_lsnr > LSNRCTL for OSDI390: Version 10.1.0.2.0 - Production on dd-Mon-yyyy hh:mm:ss > (c) Copyright 1991, 2004, Oracle. All rights reserved. > > Starting $ORACLE_HOME/bin/tnslsnr: please wait... > TNSLSNR for OSDI390: Version 10.1.0.2.0 - Production > System parameter file is $ORACLE_HOME/network/admin/listener.ora > Log messagss written to $ORACLE_HOME/network/log/listener.log > Trace inforamtion written to $ORACLE_HOME/network/trace/listener.trc > Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=MVS05.US.ORACLE.COM)(PORT=3044))) > Connecting to (address=(protocol=tcp)(host=mvs05)(port=3044)) > STATUS of the LISTENER > ------------------------ > Alias extproc_lsnr > Version TNSLSNR for OSDI390: Version 10.1.0.2.0 - Production > Start Date DD-Mon-yyyy hh:mm:ss > Uptime 0 days 0 hr. 0 min. 1 sec > Trace Level support > Security OFF > SNMP OFF > Listener Parameter File $ORACLE_HOME/network/admin/listener.ora > Listener Log File $ORACLE_HOME/network/log/listener.log > Listener Trace File $ORACLE_HOME/network/trace/listener.trc > Listening Endpoints Summary... > (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=hostname)(PORT=nnnn))) > Services Summary > Service "extproc" has 1 instance(s). > Instance "extproc", status UNKNOWN, has 1 handler(s) for this service. > The command completed successfully
The listener should now be running.