|Oracle9i Enterprise Edition User's Guide
Release 1 (9.0.1) for OS/390
Part Number A90087-01
This chapter explains how to run selected Oracle utilities under OS/390 UNIX System Services (USS). Information about implementing your own customer-written Oracle applications so they run under OS/390 UNIX System Services in included at the end of this chapter. The following topics are discussed in this chapter:
Oracle9i includes several tools designed and built to run exclusively in the OS/390 UNIX System Services environment. OS/390 UNIX System Services is similar to other UNIX environments, and the Oracle9i utilities built for OS/390 UNIX System Services behave like their UNIX counterparts with very few, if any, differences.
When the guide describes Oracle utilities running under OS/390 UNIX System services, it assumes that you have some familiarity with UNIX (whether it is OS/390 UNIX System Services or some other version). This guide describes what you have to do to be able to run any of the Oracle9i utilities designed for OS/390 UNIX System Services and it highlights some differences between using Oracle utilities in the traditional OS/390 environment and in the OS/390 UNIX System Services environment.
The Oracle database instance on OS/390 is implemented as a service under a given Oracle subsystem. This chapter discusses considerations for connecting local USS Oracle utilities or applications to Oracle database instances running on the OS/390 system.
Oracle9i database server users on OS/390 communicate with the local Oracle database instance using OS/390 cross memory services. This facility allows both data and program operation to cross address space boundaries in a secure and controlled manner.
Each USS user of an Oracle9i for OS/390 instance runs as a separate and autonomous address space. You can only access an Oracle instance after a valid connection is established between the user address space and the Oracle instance. A valid connection occurs when the Oracle instance accepts the logon user id and possibly a password provided by the user.
This section discusses considerations for connecting local USS Oracle utilities or applications to Oracle database instances running on the same OS/390 system. Such connections use OS/390 cross-memory facilities and do not involve Oracle Net. However, since the Oracle database server logically views all client connections as network connections, Oracle network terminology and some of the mechanisms of Oracle Net play a role in local connections.Enabling OS/390 Local Client Access
Oracle database clients use a cross-memory protocol for connecting to database instances. The protocol is based on Oracle Net architecture.
Since Oracle's cross-memory protocol is based on Oracle Net, the formal mechanism for specifying a local target Oracle instance is to supply a name that is looked up in the client's tnsnames file (
tnsnames.ora). Applications supply the name by appending an "@" character followed by the name to the userid and password that are passed during an Oracle connect request. The entry in the tnsnames file contains an Oracle Net address string with PROTOCOL=XM and additional parameters identifying the target database service. The complete format of the PROTOCOL=XM Oracle Net address is described under "Cross-Memory Protocol Address". Usually the target service is identified by its SID. Every service must have a SID that is unique throughout the OS/390 image. Even services that are defined in different Oracle subsystems cannot have the same SID if they are on the same OS/390 image.
It also is possible to append the complete Oracle Net address string directly to the userid and password to avoid using the tnsnames file. Oracle does not recommend this technique, however.Cross-Memory Protocol Address
The formal Oracle Net address string for Oracle's cross-memory protocol can be specified using either of two methods:
Oracle recommends using the SID form of address because it is simpler and because it avoids application dependence on the subsystem name.
An optional parameter, STAX=yes, enables the user to interrupt the session with Ctrl-C. this parameter should not be specified when running any server processes such as OEM agent, nor if the user wishes to use the host command in SQL*Plus.Specifying Connections
There are three ways, including hardcoding a tnsname entry on the connect string as described in the previous section, to specify a target instance. In descending order of precedence, the three ways are:
You can use three general methods to store connection information:
All files are located in $TNS_ADMIN if specified or in
$ORACLE_HOME/network/admin. For a complete discussion on connect strings to remote servers, see the Oracle9i Net Services Administrator's Guide. for a discussion of specifying a local connection, see Chapter 2, "Using the OS/390 Database Instance".
The following sections describe the environment variables needed to run Oracle utilities under UNIX System Services.
OS/390 UNIX System Services, like other UNIX systems, supports the use of environment variables. These are character values that are maintained by the UNIX shell and made available to any program that asks for them. The various values are given a name, to make it easier to reference them. UNIX programs typically require that one or more environment variables be properly set before the program is run. Oracle9i programs are no different. This section describes the key environment variables that can be used with Oracle9i utilities that run under OS/390 UNIX System Services.
When an Oracle product is installed on OS/390 UNIX System Services, it is placed into a home directory. The directory name must be defined by the ORACLE_HOME environment variable before any Oracle product is run. For example, assuming the Oracle home directory is
/oracle/v901, the following statement would set the variable ORACLE_HOME:
Shell scripts are often used to set the value of ORACLE_HOME and other environment variables that need to be specified. The actual value of
ORACLE_HOME must be provided by your Oracle system administrator.
tnsnames.ora contains tnsnames entries which could be used by Oracle utilities or user-written programs as connect string specifications. Its default location is
$ORACLE_HOME/network/admin and can be overridden by using the TNS_ADMIN environment variable. Refer to the Oracle9i Net Services Administrator's Guide for further details.
A TWO_TASK environment variable is set to an Oracle Net tnsnames-style name or to an explicit Oracle Net address string. If a name is specified, then the
tnsnames.ora file is opened and read to resolve the name to an Oracle Net address. The
tnsnames.ora file location may be specified in $TNS_ADMIN, or is in
$ORACLE_HOME/network/admin by default. If the Oracle Net address specifies PROTOCOL=XM, then the client is connected to the indicated database service. (The Oracle Net address could also specify PROTOCOL=TCP, in which case the client would connect to a remote Oracle instance via OSDI Network service as discussed in Chapter 10, "Oracle Net".) In terms of precedence, Oracle clients look for TWO_TASK after determining that no ORA@sid DD is allocated in the address space.
An ORACLE_SID environment variable is set to the SID of an OSDI-managed database instance: OSDI connects the client to that instance. Oracle clients look for ORACLE_SID last, after determining that no TWO_TASK environment variable is set.
Oracle9i includes comprehensive National Language Support (NLS) that transparently handles all necessary conversions between ASCII and EBCDIC. However, it needs to understand which character set is in use by your OS/390 UNIX System Services session. NLS_LANG is used to convey several pieces of NLS-related information, including the name of the character set in use, to the Oracle utilities running in OS/390 UNIX System Services. The default character set for Oracle9i for OS/390 is WE8EBCDIC1047, which matches the character set assumed by OS/390 UNIX System Services. If these defaults are suitable (and they often are), then you might let NLS_LANG default.
If you decide to use a different character set, then you need to set NLS_LANG accordingly. For example, assuming you need to use Swedish characters on OS/390 UNIX System Services, the following might set appropriate values into NLS_LANG:
The LIBPATH environment variable controls the search path for DLLs or shared objects under OS/390 UNIX System Services. Several Oracle executables use DLLs. To locate the Oracle DLLs, LIBPATH must include the
$ORACLE_HOME/lib directory. You can prepend the
$ORACLE_HOME/lib directory to the LIBPATH environment variable by issuing the following command:
The PATH environment variable controls the search path for OS/390 UNIX System Services programs. It is a list of directories in the following form:
This chapter assumes that the path to the Oracle9i program has been specified in the PATH environment variable. For example:
The Oracle OS/390 utilities support a number of file name features that are unnecessary on OS/390 UNIX System Services.
ddnameform of naming a file is not supported.
dsname) is not supported. In addition to the use of OS/390 file system files, the facility is designed for the OS/390 JCL PARM field; OS/390 UNIX System Services does not have access to the PARM field.
When run under USS, the
sqlldr utilities are called in the same manner as on other UNIX platforms. In addition, these utilities can access OS/390 data sets by simply specifying the filenames by preceding them with a double forward slash and enclosing them in single quotes.
If you specify the filename on the command line or at a utility prompt, you must escape all forward slashes and the single quotes.
The following is an example of running
exp under UNIX System Services:
exp Export: Release 22.214.171.124.1 - Production on Thu Aug 10 10:53:20 2000 (c) Copyright 2000 Oracle Corporation. All rights reserved. Username: scott Password: Connected to: Oracle9i Enterprise Edition Release 126.96.36.199.1 - Production With the Partitioning option Enter array fetch buffer size: 4096 > Export file: expdat.dmp > \/\/\'ORACLE.EXPEMP\' (2)U(sers), or (3)T(ables): (2)U > 3 Export table data (yes/no): yes > Compress extents (yes/no): yes > Export done in WE8EBCDIC1047 character set and WE8EBCDIC1047 NCHAR character set About to export specified tables via Conventional Path ... Table(T) or Partition(T:P) to be exported: (RETURN to quit) > EMP . . exporting table EMP 14 rows exported Table(T) or Partition(T:P) to be exported: (RETURN to quit) > Export terminated successfully without warnings.
The following utilities are available under OS/390 UNIX System Services.
The PL/SQL wrapper enables you to produce a binary version of your PL/SQL packages that is suitable for shipping in a tamper-proof way. To run it, enter the following at the command prompt:
For additional information, refer to the PL/SQL User's Guide and Reference.
The Oracle9i PL/SQL Server Page Loader enables you to load PL/SQL Server Pages (PSP) into the database as stored procedures.
Additional information can be found in the Oracle9i Application Developer's Guide - Fundamentals, in the chapter named "Developing Web Applications with PL/SQL".
The Data Guard command-line interface allows you to control and monitor a Data Guard configuration from the DGMGRL command-line prompt or from within scripts. You can perform most of the activities required to manage and monitor the objects in the configuration using the command-line interface.
To run the Data Guard command-line interface, you must have SYSDBA privileges. Start the command-line interface by entering DGMGRL at the command line prompt on a system where Oracle9i Data Guard is installed:
Additional information can be found in the Oracle9i Data Guard Concepts and Administration Guide.
OEM Intelligent Agent allows you to monitor events, start and stop an Oracle Instance in OS/390. Data Gatherer allows you to gather database and operating system statistics on OS/390. See the Oracle9i Enterprise Edition System Administration Guide for OS/390 and Oracle Intelligent Agent User's Guide for further information.
The Oracle JDBC thin driver is a Type IV JDBC driver targeted to application developers. Written entirely in Java, it complies fully with the JDBC 1.2.2 standard. It requires the use of TCP/IP. For additional information, refer to the Oracle9i JDBC Developer's Guide and Reference.
To run the Oracle JDBC thin driver, you must add the following to the CLASSPATH environment variable that is in effect when the JDBC driver runs:
$ORACLE_HOME/jdbc/lib/classes111.zip /*Oracle JDBC thin driver*/ <installation-specific path> /*IBM JDK classes */
The SQLJ translator is conceptually similar to other Oracle Precompilers, SQLJ consists of both a translator and a runtime component. The translator replaces embedded SQL calls to the SLQJ runtime, which implements the SQL operations. When the end user runs the SQLJ application, the runtime is invoked to handle the SQL operations in real-time. For additional information, refer to the Oracle9i JDBC Developer's Guide and Reference.
To run the SQLJ translator, you must add the following to the CLASSPATH environment variable that is in effect when SQLJ runs. For example:
current directory $ORACLE_HOME/sqlj/lib/translator.zip /*SQLJ translator */ $ORACLE_HOME/jdbc/lib/classes111.zip /*Oracle JDBC thin driver*/ <installation-specific_path> /*IBM JDK classes */
In addition, to be able to run the
sqlj script (which invokes the SQLJ translator) without having to fully specify the path, include the following in your PATH environment variable:
loadjava utility is used to load java source code or byte code into an Oracle database as Java stored procedure. The
dropjava removes it.
> loadjava -thin -verbose -user email@example.com:1493:ORAJ -resolve Test1.class initialization complete loading : Test1 creating : Test1 resolver : resolving: Test1
A sample session for
dropjava of a class file:
> dropjava -thin -verbose -user firstname.lastname@example.org:1493:ORAJ Test1.class dropping class : Test1
A sample session for
loadjava of a source file:
> loadjava -thin -verbose -user email@example.com:1493:ORAJ -resolve -encoding Cp1047 Test2.java initialization complete loading : Test2 creating : Test2 resolver : resolving: Test2
A sample session for
dropjava of a source file:
> dropjava -thin -verbose -user firstname.lastname@example.org:1493:ORAJ Test2.java dropping source : Test2
Oracle Wallet Manager (OWM) is a Java application that requires Java 1.1.8, an X11 server and a graphics terminal. OWM allows the user to administer certificates in his wallet directory, including generating certificate requests, importing/exporting user certificates and importing/exporting trustpoint certificates. See the Oracle Advanced Security Administrator's Guide for more information.
A sample session for OWM could be started as follows:
my_workstation is your workstation name or IP address and the environment variable ORACLE_HOME must be set.
If Java returns the following message, your DISPLAY value is invalid:
java.lang.LNullPointerException java.lang.NullPointerException at oracle.ewt.lwAWT.BufferedFrame._init(Unknown Source) at oracle.ewt.lwAWT.BufferedFrame.<init>(Unknown Source) at oracle.sysman.emSDK.client.appContainer.ApplicationFrame.<init>(Applicat ionFrame.java:75) at oracle.sysman.emSDK.client.appContainer.WebApplication.main(WebApplicati on.java:2908)
TNSPING is a command line executable that tests tns connectivity. See the Oracle9i Net Services Administrator's Guide for more information.
Refer to Chapter 10 of the Oracle9i Globalization and National Language Support Guide for information on using the Character Set Scanner utility. Also refer to Appendix D of the Oracle9i Enterprise Edition System Administration Guide for OS/390 to obtain the list of supported character sets for OS/390 databases.
Please note that the Character Set Scanner under UNIX System Services can only support databases running with the EBCDIC character set.
To run the Locale Builder, you must have the
JAVA_HOME environment variable set to the root directory that JAVA is currently installed under.
Also, you may have to customize the
CLASSPATH environment variable in shell script
LBuilder.ksh to point to the current Oracle, Sun, and IBM classes.
JAVALIB classes.zip for JRE 1.1.8 CLASSPATH current directory LocaleBuilder.jar swingall.jar required for JRE 1.1.8 only jewt-all-dbg-4_1_0.jar required for JRE 1.1.8 only
Please note that the Locale Builder is currently supported under JRE 1.1.8 only.
Oracle9i database servers can be accessed by programs run from the OS/390 UNIX System Services Hierarchical File System (HFS). These programs must be coded in C programming language and must utilize OCI or the Oracle Pro*C Precompiler. You need a thorough understanding of the following:
OCI programs can be compiled, prelinked, and linkedited (bound) entirely within the OS/390 UNIX System Services shell using the
c89 command. Oracle Pro*C precompiler programs can now be precompiled, compiled, prelinked, and linkedited (bound) entirely within the OS/390 UNIX System Services shell. An OS/390 UNIX System Services compatible version of the IBM C/370 or IBM C/C++ compiler and LE/370 runtime library must be used. Depending on the nature of the application, you might also need to call the C/370 or C/C++ prelinker.
Once the OCI or Oracle Precompiler application is created, it is typically run from the OS/390 UNIX System Services shell. The environment variables described in "Running an Oracle Utility on OS/390 Under USS" are also applicable for the execution of user-written programs.
An application can take advantage of the
fork()function with OS/390 UNIX System Services. This allows a parent process to create some number of child processes. The Oracle9i database server does not allow a child process to make use of a connection established by a parent. If this is attempted, then the result is:
If Oracle Net is being used, then you cannot establish a connection from a forked address if the parent process already holds a connection. The attempt to make a connection will work; however, this will hang the user's session when the child process ends and the parent process attempts to access Oracle on the connect it originally held prior to the
fork() call. If the user escapes out, then the parent process is orphaned and must be ended using a shell
kill command or an OS/390 CANCEL command. Therefore, each process must establish a unique connection with the Oracle9i database server and use it exclusively.
The connect capabilities for a child process after a fork are:
|Connection Type||PCC Program||OCI Program|
|Oracle Net||Yes (see details above)||Yes|
OS/390 UNIX System Services also provides for POSIX threading. If the application uses threads, then it must ensure two or more threads do not attempt to use the same connection simultaneously.