Oracle9i Enterprise Edition User's Guide
Release 2 (188.8.131.52.0) for OS/390
Part No. A97312-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:
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.
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.
The formal Oracle Net address string for Oracle's cross-memory protocol can be specified using either of two methods:
One method identifies the database instance by its SID:
sid is the SID associated with the database instance.
The other method uses the Oracle subsystem and service names:
ssn is the Oracle subsystem name, and
srvn is the Oracle database service name.
Oracle recommends using the SID form of address because it is simpler and because it avoids application dependence on the subsystem name.
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:
Specifying a tnsname entry which refers to the Oracle Net cross-memory protocol on the connect string.
An ORACLE_SID environment variable is set to the SID of a database instance; The client is connected to that instance. Clients look for ORACLE_SID last, after determining that no TWO_TASK environment variable is set.
You can use three general methods to store connection information:
In an LDAP server pointed to by
In an ONAMES server pointed to by
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".
Use of the cross-memory (XM) protocol from a tool or application in USS causes a thread to be created for break signal (Control-C) processing. This allows the user to interrupt an in-progress server request similar to the attention subtask processing provided in TSO.
Due to a limitation of USS, the presence of the break-handling thread precludes using the fork() system call. The spawn() system call can be used instead. If your application specifically requires fork(), you must use TCP/IP protocol rather than XM.
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/v920, 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 n$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.
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:
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.
File names refer to files in the HFS and adhere to POSIX naming rules. Files designated by the /DSN/ method of naming files are in the OS/390 file system, not the HFS. The /DSN/ notation is not supported.
Parameter redirection (
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.
Example 4-1 //'ORACLE.EXPEMPL'
If you specify the filename on the command line or at a utility prompt, you must escape all forward slashes and the single quotes.
Example 4-2 \\/\/\'ORACLE.EXPEMP\'
The following is an example of running
exp under UNIX System Services:
exp Export: Release 184.108.40.206.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 220.127.116.11.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.
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.
loadpsp -replace -user scott/tiger@WEBDB banner.inc error.psp display_order.psp
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:
$ DGMGRL [options]
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.
$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.
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 */
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 Label Security Administrator's Guide for more information.
A sample session for OWM could be started as follows:
export DISPLAY=my_workstation:0.0 owm
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>(ApplicationFrame.java:75) at oracle.sysman.emSDK.client.appContainer.WebApplication.main(WebApplication.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 Database Globalization 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:
OS/390 UNIX System Services environment
IBM C/370 or IBM C/C++ compiler
DFSMS/MVS Program Management binder
LE/370 runtime library
OS/390 UNIX System Services
c89 shell command
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 using a cross-memory connection to Oracle (PROTOCOL=XM) cannot use the
fork() system call to create a child process. This is because the cross-memory protocol adapter uses a thread to field the SIGINT signal from the Ctrl-C key while it is in cross-memory mode. The UNIX System Services kernel will not deliver a signal to a program running in cross-memory mode. Applications should use the
spawn() system call instead. If the application must use
fork(), it must use TCP/IP to connect to the database.
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:
CEE3250C The system or user abend S0D6 R=00000022 was issued.
The connect capabilities for a child process after a fork are: