Skip Headers

Oracle9i Enterprise Edition User's Guide
Release 2 ( for OS/390
Part No. A97312-01
Go To Table Of Contents
Go To Index

Previous Next

Accessing Oracle9i Under USS

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 Overview

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.

Oracle Database Instance Overview

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.

Connecting to an Oracle Instance

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:

  • One method identifies the database instance by its SID:

    (ADDRESS=(PROTOCOL=XM)(SID=sid) [(STAX=yes)])

    where sid is the SID associated with the database instance.

  • The other method uses the Oracle subsystem and service names:


    where 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.

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:

  1. Specifying a tnsname entry which refers to the Oracle Net cross-memory protocol on the connect string.

  2. A TWO_TASK environment variable that is set to an Oracle Net tnsnames-style name or to an explicit Oracle Net address string.

  3. 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.

Storing Connection Information

You can use three general methods to store connection information:

  1. In a tnsnames.ora

  2. In an LDAP server pointed to by sqlnet.ora and ldap.ora

  3. In an ONAMES server pointed to by sqlnet.ora

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".

Break Processing

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.

Running an Oracle Utility on OS/390 Under USS

The following sections describe the environment variables needed to run Oracle utilities under UNIX System Services.

Environment Variables

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:

export ORACLE_HOME=/oracle/v920

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.


The file 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.


Oracle9i includes comprehensive National Language Support (NLS) that transparently handles all necessary conversions between ASCII and EBCDIC.

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:

export NLS_LANG=Swedish_Sweden.S8EBCDIC278

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:

absolute_pathname[:absolute_pathname ...]

This chapter assumes that the path to the Oracle9i program has been specified in the PATH environment variable.  For example:


File Names in OS/390 UNIX System Services

The Oracle OS/390 utilities support a number of file name features that are unnecessary on OS/390 UNIX System Services.

  • DD statements are not normally used in OS/390 UNIX System Services, so the /DD/ddname form of naming a file is not supported.

  • 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.

  • On OS/390, the Oracle FNA service supports the construction of file names compatible with the OS/390 file system.  Files in the HFS are accessed, not OS/390 files, so FNA is not supported.

  • Parameter redirection (++/DD/ddname or ++/DSN/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.

Accessing OS/390 Data Sets

When run under USS, the imp, exp, and 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:


Export: Release - Production on Thu Aug 10 10:53:20 2000

(c) Copyright 2000 Oracle Corporation.  All rights reserved.

Username: scott


Connected to: Oracle9i Enterprise Edition Release - 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.

Utilities Available Under OS/390 USS

The following utilities are available under OS/390 UNIX System Services.

PL/SQL Wrapper

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.

PL/SQL Server Page Loader

The Oracle9i PL/SQL Server Page Loader enables you to load PL/SQL Server Pages (PSP) into the database as stored procedures.

For example:

loadpsp -replace -user scott/tiger@WEBDB 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".

Data Guard Command-line Utility

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 and Data Gatherer

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.

Oracle JDBC Thin Driver

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/      /*Oracle JDBC thin driver*/

<installation-specific path>              /*IBM JDK classes        */

SQLJ Translator

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/      /*SQLJ translator        */

$ORACLE_HOME/jdbc/lib/      /*Oracle JDBC thin driver*/

<installation-specific_path>              /*IBM JDK classes         */

Loadjava/Dropjava Utilities

The loadjava utility is used to load java source code or byte code into an Oracle database as Java stored procedure.  The dropjava removes it.

For example:

> loadjava  -thin -verbose -user scott/tiger@

-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 scott/tiger@


dropping class   : Test1

A sample session for loadjava of a source file:

> loadjava -thin -verbose -user scott/tiger@

-resolve -encoding Cp1047

initialization complete

loading  : Test2

creating : Test2

resolver :

resolving: Test2

A sample session for dropjava of a source file:

> dropjava -thin -verbose -user scott/tiger@

dropping source  : Test2

Oracle Wallet Manager

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


where: 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:



        at oracle.ewt.lwAWT.BufferedFrame._init(Unknown Source)

        at oracle.ewt.lwAWT.BufferedFrame.<init>(Unknown Source)






TNSPING is a command line executable that tests tns connectivity.  See the Oracle9i Net Services Administrator's Guide for more information.

Character Set Scanner

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.

Locale Builder

To run the Locale Builder, you must have the JAVA_HOME environment variable set to the root directory that JAVA is currently installed under.

For example:

export JAVA_HOME=/usr/lpp/java/J1.1

Also, you may have to customize the JAVALIB and CLASSPATH environment variable in shell script LBuilder.ksh to point to the current Oracle, Sun, and IBM classes.

For example:

JAVALIB                         for JRE 1.1.8


  current directory


  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.

Customer-Written Applications Under USS

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.

Child Process Restrictions

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:

POSIX Thread Support

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.

Previous Next
Oracle Logo
Copyright © 2002 Oracle Corporation

All rights reserved
Go To Table Of Contents
Go To Index