2
Backward Compatibility Tools

The underlying logic for the session shell, publish, and remove tools was changed for Release 8.1.7. Because of this, each of these tools is not backward compatible to Oracle9i Release 8.1.6 and prior. Thus, Oracle furnishes the following tools for backward compatibility: sess_sh_816, publish_816, and remove_816. These tools will be deprecated in Release 8.2.

This chapter describes the following tools:

• Session Namespace Tools

• publish_816

• remove_816

• sess_sh_816

Session Namespace Tools

Each database instance running the Oracle9i JVM software has a session namespace, which the Oracle9i ORB uses to activate CORBA and EJB objects. A session namespace is a hierarchical collection of objects known as PublishedObjects and PublishingContexts. PublishedObjects are the leaves of the hierarchy and PublishingContexts are the nodes, analogous to UNIX file system files and directories. Each PublishedObject is associated with a class schema object that represents a CORBA or EJB implementation. To activate a CORBA or EJB object, a client refers to a PublishedObject's name. From the PublishedObject, the Oracle9i ORB obtains the information necessary to find and launch the corresponding class schema object.

Creating a PublishedObject is known as publishing and can be done with the command-line publish_816tool or the interactive session shell, both of which this section describes. CORBA server developers create PublishedObjects explicitly after loading the implementation of an object with loadjava. EJB developers do not explicitly load or publish their implementations; the deployejb tool implicitly does both.

A PublishedObject has the following attributes:

• Schema Object Name: the name of the Java class schema object associated with the PublishedObject.

• Schema: the name of the schema containing the corresponding class schema object.

• Helper Schema Object Name: the name of the helper class the Oracle9i ORB uses to automatically narrow a reference to an instance of the CORBA object or EJB.

PublishedObjects and PublishingContexts, as with their file and directory counterparts, have owners and rights (privileges). An owner can be a user name or a role name; only the owner can change the ownership or rights of a PublishedObject or PublishingContext. Table  2-1 describes session namespace rights.

Table 2-1 PublishingContext and PublishedObject Rights  

Right	Meaning for PublishingContext	Meaning for PublishedObject
read	Lists contents and attributes (type, rights and creation time).	List object attributes (type, schema object, schema, helper, rights, and creation time).
write	Creates a PublishedObject or PublishingContext in the PublishingContext.	Republish object.
execute	Uses contents to resolve a name.	Activate associated class.

Oracle9i creates a session namespace automatically when the Oracle9i ORB is configured. The PublishingContexts contained in Table  2-2 are present in all session namespaces:

Table 2-2 Initial PublishingContexts and Rights  

Name	Owner	Read	Write	Execute
/	SYS	PUBLIC	SYS	PUBLIC
/bin	SYS	PUBLIC	SYS	PUBLIC
/etc	SYS	PUBLIC	SYS	PUBLIC
/test	SYS	PUBLIC	PUBLIC	PUBLIC

Because by default only /test is writable by PUBLIC, you will normally create PublishingContexts and PublishedObjects subordinate to /test.

publish_816

The publish_816 tool creates or replaces (republishes) a PublishedObject in a PublishingContext. It is not necessary to republish when you update a Java class schema object; republishing is required only to change a PublishedObject's attributes. To publish, you must have write permission (the write right) for the destination PublishingContext; by default only the PublishingContext /test is writable by PUBLIC. To republish you must additionally have the write right for the PublishedObject.

Syntax

publish_816 [options]
<name> <class> [<helper>] -user <username> -password <password>
-service <serviceURL>

where options are:

  [-describe] 
  [{-g | -grant} {<user> | <role>}[,{<user> | <role>}]...]
  [{-h | -help}] 
  [-idl]
  [-iiop]
  [-replaceIDL]
  [-role <role>] 
  [-republish]
  [-schema <schema>]
  [-keepcase]
  [-ssl]
  [-useServiceName]
  [-version] 

Argument Summary

Table  2-3 summarizes the publish_816 tool arguments.

Table 2-3 publish_816 Tool Argument Summary  

Option	Description
<name>	Name of the PublishedObject being created or republished; PublishingContexts are created if necessary.
<class>	Name of the class schema object that corresponds to <name>.
<helper>	Name of the Java class schema object that implements the narrow() method for <class>.
-user	Specifies identity with which to log into the database instance named in -service.
-password	Specifies authenticating password for the username specified with -user.
-service	URL identifying database whose session namespace is to be "opened" by sess_sh_816. The serviceURL has the form: sess_iiop://<host>:<lport>:<sid>. <host> is the computer that hosts the target database; <lport> is the listener port that has been configured to listen for session IIOP; <sid> is the database instance identifier. Example: sess_iiop://localhost:2481:orcl which matches the default installation on the invoker's machine.
-describe	Summarizes the tool's operation, then exits.
-grant	After creating or republishing the PublishedObject, grants read and execute rights to the sequence of <user> and <role> names. When republishing, replace the existing users/roles that have read/execute rights with the <user> and <role> names. To selectively change the rights of a PublishedObject, use the sess_sh_816's chmod command. Note that to activate a CORBA object or EJB, a user must have the execute right for both the PublishedObject and the corresponding class schema object. The sequence of user and role names must be a comma-separated list, containing no internal spaces.
-help	Summarizes the tool's syntax, then exits.
-idl	Load the IDL interface definition into the IFR.
-iiop	Connects to the target database with IIOP instead of the default session IIOP. Use this option when publishing to a database server that has been configured without session IIOP.
-replaceIDL	If an IDL interface definition currently exists within the IFR, replace it with this version. You must have the appropriate security permissions for this to succeed. If not specified, the publish command will not replace the existing interface within the IFR.
-role	Role to assume for the publish; no default.
-republish	Directs publish_816 to replace an existing PublishedObject; without this option, the publish_816 tool rejects an attempt to publish an existing name. If the PublishedObject does not exist, publish_816 creates it. Republishing deletes non-owner rights; use the -grant option to add read/execute rights when republishing.
-schema	The schema containing the Java <class> schema object. If you do not specify, the publish_816 tool uses the invoker's schema.
-keepcase	Normally, any schema name supplied is uppercased by default. If you created a schema name that requires lowercase letters, specify the -keepcase option. Thus, you would execute publish_816 ... -schema mySchema -keepcase ...
-ssl	Connects to the database with SSL server authentication. You must have configured the database for SSL to use this option, and you must specify an SSL listener port in -service.
-useServiceName	If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID.
-version	Shows the tool's version, then exist.

Here is a publish_816 example.

Publish the CORBA server implementation vbjBankTestbank.AccountManagerImpl and its helper class as /test/bankMgr in the tool invoker's schema:

publish_816 /test/bankMgr vbjBankTestServer.AccountManagerImpl \ 
vbjBankTestServer.AccountManagerHelper \
-user SCOTT -password TIGER \ 
-service sess_iiop://dlsun164:2481:orcl 

remove_816

The remove_816 tool removes a PublishedObject or PublishingContext from a session namespace. It does not remove_816 the Java class schema object associated with a PublishedObject; use dropjava to do that.

Syntax

remove_816 <name> -user <username> -password <password> -service <serviceURL> 
[options]
  [{-d | -describe}]
  [{-h | -help}]
  [-iiop]
  [{-r | -recurse}]
  [-role role]
  [-ssl]
  [-useServiceName]
  [-version]

Argument Summary

Table  2-4 describes the remove_816 arguments.

Table 2-4 remove_816 Argument Summary  

Option	Description
<name>	Name of PublishingContext or PublishedObject to be removed.
-user	Specifies identity with which to log into the instance named in -service.
-password	Specifies authenticating password for the <username> you specified with -user.
-service	URL identifying database whose session namespace is to be "opened" by sess_sh_816. The serviceURL has the form: sess_iiop://<host>:<lport>:<sid>. <host> is the computer that hosts the target database; <lport> is the listener port that has been configured to listen for session IIOP; <sid> is the database instance identifier. Example: sess_iiop://localhost:2481:orcl which matches the default installation on the invoker's machine.
-describe	Summarizes the tool's operation, then exits.
-help	Summarizes the tool's syntax, then exits.
-iiop	Connects to the target database with IIOP instead of the default session IIOP. Use this option when removing from a database server that has been configured without session IIOP.
-recurse	Recursively removes <name> and all subordinate PublishingContexts; required to remove a PublishingContext.
-role	Role to assume for the remove; no default.
-ssl	Connects to the database with SSL server authentication. You must have configured the database for SSL to use this option.
-useServiceName	If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID.
-version	Shows the tool's version, then exits.

Here are examples of remove_816 tool usage.

• Remove a PublishedObject named /test/testhello:

  remove_816 /test/testhello -user SCOTT -password TIGER \ 
  -service sess_iiop://dlsun164:2481:orcl 
  

• Remove a PublishingContext named /test/etrader:

  remove_816 -r /test/etrader -user SCOTT -password TIGER \ 
  -service sess_iiop://dlsun164:2481:orcl 
  

sess_sh_816

The sess_sh_816 (session shell) tool is an interactive interface to a database instance's session namespace. You specify database connection arguments when you start sess_sh_816. It then presents you with a prompt to indicate that it is ready for commands.

The sess_sh_816 gives a session namespace much of the "look and feel" of a UNIX file system you access through a shell, such as the C shell. For example, the session shell command:

ls /alpha/beta/gamma

means "List the PublishedObjects and PublishingContexts in the PublishingContext known as /alpha/beta/gamma". (NT users note: /alpha/beta/gamma, not \alpha\beta\gamma.) Indeed, many session shell command names that operate on PublishingContexts have the same names as their UNIX shell counterparts that operate on directories. For example: mkdir (create a PublishingContext) and cd (change the working PublishingContext).

In addition to UNIX-style manipulation of PublishingContexts and PublishedObjects, the session shell can launch an executable, which is analogous to a Java standalone application, that is, a class with a static main() method. Executables must have been loaded with loadjava, but not published--publishing is for CORBA and EJB objects only.

Syntax

sess_sh_816 [options] -user <user> -password <password> -service <serviceURL>
  [-d | -describe]
  [-h | -help] 
  [-iiop]
  [-role <rolename>]
  [-ssl]
  [-useServiceName]
  [-version]

Argument Summary

Table  2-5 summarizes the sess_sh_816 command line arguments.

Table 2-5 sess_sh_816 Argument Summary  

Option	Description
-user	Specifies user's name for connecting to the database.
-password	Specifies user's password for connecting to the database.
-service	URL identifying database whose session namespace is to be "opened" by sess_sh_816. The serviceURL has the form: sess_iiop://<host>:<lport>:<sid>. <host> is the computer that hosts the target database; <lport> is the listener port configured to listen for session IIOP; <sid> is the database instance identifier. Example: sess_iiop://localhost:2481:orcl which matches the default database installation on the invoker's machine.
-describe	Summarizes the tool's operation, then exits.
-help	Summarizes the tool's syntax, then exits.
-iiop	Connects to the target database with plain IIOP instead of the default session IIOP. Use this option for a database server configured without session IIOP.
-role	Role to pass to database; there is no default.
-ssl	Connect to the database with SSL server authentication. You must have configured the database for SSL and specify an SSL port to use this option.
-useServiceName	If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID.
-version	Shows the command's version, then exits.

Here is a sess_sh_816 example.

Open a session shell on the session namespace of the database orcl on listener port 2481 on host dbserver.

sess_sh_816 -user scott -password tiger -service sess_iiop://dbserver:2481:orcl

cd Command

The cd command is analogous to a UNIX shell's cd command; it changes the working PublishingContext.

Syntax

cd [path] 

Here is an example.

Change to root PublishingContext:

$ cd /

chmod Command

The chmod command is analogous to a UNIX shell's chmod command; it changes the users or roles that have rights for a PublishingContext or PublishedObject. See Table  2-1 for descriptions of the read, write, and execute rights. Only the object's owner can change its rights.

Syntax

chmod  [options] {+|-}{r|w|e} {<user> | <role>} [, {<user> | <role>} ...] \
<objectname>
  [-h | -help] 
  [-version] 

Argument Summary

Table  2-6 summarizes the chmod arguments.

Table 2-6 chmod Argument Summary  

Option	Description
+/-rwe	Specifies the right (read, write, or execute) to be added (+) or removed (-) for <user> or <role>.
<user> | <role>	Specifies the user or role whose rights are to be increased or decreased.
<objectname>	Specifies the name of the PublishingContext or PublishedObject whose rights are to be changed.
-help	Summarizes the command's syntax, then exits.
-version	Shows the command's version, then exits.

Here are some chmod examples.

• Give execute rights for /alpha/beta/gamma to Scott and Nancy:

  $ chmod +x scott nancy /alpha/beta/gamma
  

• Remove Scott's write rights for the same object:

  $ chmod -w scott /alpha/beta/gamma
  

chown Command

The chown command is analogous to the UNIX chown command; it changes the ownership of a PublishingContext or PublishedObject. The owner of a newly created PublishingContext or PublishedObject is the user who publishes it. To change a PublishingContext's or PublishedObject's ownership you must be SYS.

Syntax

chown [options] {<user> | <role>} <objectname>
  [-h | -help] 
  [-version] 

Argument Summary

Table  2-7 summarizes the chown arguments.

Table 2-7 chown Argument Summary  

Option	Description
<user> | <role>	Specifies the user or role to be the new owner.
<objectname>	Specifies the name of the PublishingContext or PublishedObject whose owner is to be changed.
-help	Summarizes the command's syntax, then exits.
-version	Shows the command's version, then exits.

Here is a chown example.

Make Scott the owner of /alpha/beta/gamma:

$ chown scott /alpha/beta/gamma

exit Command

The exit command terminates sess_sh_816.

Syntax

exit

Here is an example:

Leave the session shell:

$ exit
% 

help Command

The help command summarizes the syntax of the session shell commands.

Syntax

help 

Here is a help example.

$ help
Commands are of the format <command> [arg1, ar2...]
Intrinsic Commands:
    exit           exit the shell
    help           prints this message
    version        print version inforamtion
    pwd            print working directory
    cd             change working directory
    ls             list directory
    ln             link name
    chmod          change read, write or execute permissions on an object
    chown          change an objects owner    
    mkdir          create a directory
    mv             move an object or directory to another location
    rm             remove an object or directory
    lpwd           print local file system working directory 
    publish        publish an object
    republish      republish an object
    java           execute the "main" method on a java class

java Command

The java command is analogous to the JDK java command; it invokes a class's static main() method. The class must have been loaded with loadjava. (There is no point to publishing a class that will be invoked with the java command.) The java command provides a convenient way to test Java code that runs in the database. In particular, the command catches exceptions and redirects the class's standard output and standard error to the session shell, which displays them as with any other command output. (The usual destination of standard out and standard error for Java classes executed in the database is one or more database server process trace files, which are inconvenient and may require DBA priviliges to read.)

Syntax

java class [-schema <schema>] [arg1 ... argn] [options]
  [{-h | -help}] 
  [-version] 

Argument Summary

Table  2-8 summarizes the java arguments.

Table 2-8 java Argument Summary  

Option	Description
class	Names the Java class schema object that is to be executed.
-schema	Names the schema containing the class to be executed; the default is the invoker's schema.
arg1 ... argn	Arguments to the class's main() method.
-help	Summarizes the command's syntax, then exits.
-version	Shows the command's version, then exits.

Here is a java command example.

Say hello and display arguments:

package hello;
public class World {
    public World() {
        super();
    }
    public static void main(String[] argv) {
        System.out.println("Hello from the Oracle9i ORB");
        if (argv.length != 0)
            System.out.println("You supplied " + argv.length + " arguments: ");
            for (int i = 0; i < argv.length; i++)
                System.out.println(" arg[" + i + "] : " + argv[i]);
    }
}

Compile, load, publish, and run the executable as follows, substituting your userid, host, and port information as appropriate:

% javac hello/World.java
% loadjava -r -user scott/tiger@localhost:2481:orcl hello/World.class
% sess_sh_816 -user scott -password tiger -service 
sess_iiop://localhost:2481:orcl
$ java testhello alpha beta
Hello from the Oracle9i ORB
You supplied 2 arguments:
arg[0] : alpha
arg[1] : beta
$

ln Command

The ln (link) command is analogous to the UNIX ln command. A link is a synonym for a PublishingContext or PublishedObject. A link can prevent a reference to a PublishingContext or PublishedObject from becoming invalid when you move a PublishingContext or PublishedObject (see "mv Command"); creating a link with the old name makes the object accessible by both its old and new names.

Syntax

ln <object> <link>

Argument Summary

Table  2-9 summarizes the ln arguments.

Table 2-9 ln Argument Summary

Option	Description
<object>	The name of the PublishingContext or PublishedObject for which a link is to be created.
<link>	The synonym by which <object> is also to be known.

Here is an ln command example.

Preserve access through old, although the object's name is changed to new:

$ mv old new
$ ln new old

lpwd Command

The lpwd (local print working directory) command displays the name of the working directory, just as executing pwd outside of the session shell would.

Syntax

lpwd

Here is an example of the lpwd command that shows the working directory:

$ lpwd
/home/usr/billc

ls Command

The ls (list) command shows the contents of PublishingContexts as the UNIX ls command shows the contents of directories.

Syntax

ls [options] [{<pubcon> | <pubobj} [{<pubcon> | <pubobj}] ...] 
  [-dir]
  [-h | -help]
  [-l] 
  [-ld | ldir]
  [-R]
  [-version] 

Argument Summary

Table  2-10 describes the ls arguments.

Table 2-10 ls Argument Summary  

Option	Description
<pubcon> | <pubobj>	Name of PublishingContext(s) and/or PublishingObject(s) to be listed; the default is the working PublishingContext.
-dir	Shows only PublishingContexts; analogous to the UNIX ls -d command.
-help	Summarizes the command's syntax, then exits.
-l	Shows contents in long (detailed) format. The long format includes name, creation time, owner, and rights. For PublishedObjects, the option also shows class, schema, and helper.
-ldir	Lists PublishingContexts in long format, ignoring PublishingObjects; analogous to UNIX ls -ld command.
-R	Lists recursively.
-version	Shows the command's version, then exits.

Here are examples of the ls command.

Show contents of the root PublishingContext in short format:

$ ls /
bin/
etc/
test/

Show contents of the root PublishingContext in long format:

$ ls -l /
Read    Write   Exec      Owner   Date   Time   Name      Schema    Class     Helper 
PUBLIC  SYS     PUBLIC    SYS     Dec 14 14:59  bin/ 
PUBLIC  SYS     PUBLIC    SYS     Dec 14 14:59  etc/ 
PUBLIC  PUBLIC  PUBLIC    SYS     Dec 14 14:59  test/ 

Show contents of the /test PublishingContext in long format:

$ ls -l test 
Read  Write Exec  Owner Date   Time  Name Schema Class                   Helper 
SCOTT SCOTT SCOTT SCOTT Dec 14 16:32 bank SCOTT  Bank.AccountManagerImpl Bank.AccountManagerHelper 

mkdir Command

The mkdir command is analogous to the UNIX shell mkdir command; it creates a PublishingContext. You must have the write right for the target PublishingContext to use mkdir in it.

Syntax

mkdir [options] <name>
 [-path] 

Argument Summary

Table  2-11 describes the mkdir arguments.

Table 2-11 mkdir Argument Summary

Option	Description
<name>	Name of PublishingContext to create.
-path	Creates intermediate PublishingContexts if they do not exist.

Here are examples of the mkdir command.

Create a PublishingContext called /test/alpha (/test exists):

mkdir /test/alpha

Create a PublishingContext called /test/alpha/beta/gamma (/test/alpha/beta does not exist):

$ mkdir -path /test/alpha/beta/gamma

mv Command

The mv command is analogous to the UNIX shell mv command.

Syntax

mv <old> <new>

Here is an example of the mv command.

Change the name of /test/foo to /test/bar:

$ mv /test/foo /test/bar

publish Command

The publish command creates or replaces (republishes) a PublishedObject in a PublishingContext. It is not necessary to republish when you update a Java class schema object that has been published; republish only to change a PublishedObject's attributes. To publish, you must have the write right for the destination PublishingContext; to republish you must also have the write right for the PublishedObject.

Syntax

publish <name> <class> <helper> [options] 
  [{-e | -executable}] 
  [{-g | -grant} {<user> | <role>}[,{<user> | <role>} ... ]]
  [{-h | -help}] 
  [-republish] 
  [-schema <schema>]
  [-version] 

Argument Summary

Table  2-12 summarizes the publish command arguments.

Table 2-12 publish Command Argument Summary  

Option	Description
<name>	Name of the PublishedObject being created or republished; PublishingContexts are created if necessary.
<class>	Name of the class schema object that corresponds to <name>.
<helper>	Name of the Java class schema object that implements the narrow() method for <class>.
-grant	After creating or republishing the PublishedObject, grants read and execute rights to the sequence of <user> and <role> names. When republishing, replaces the existing users/roles that have read/execute rights with the <user> and <role> names. To selectively change the rights of a PublishedObject, use the session shell's chmod command. Note that to activate a CORBA object or EJB, a user must have the execute right for both the PublishedObject and the corresponding class schema object.
-help	Summarizes the command's syntax, then exits.
-republish	Directs publish to replace an existing PublishedObject; without this option, the publish command rejects an attempt to publish an existing name. If the PublishedObject does not exist, it is created. Republishing deletes non-owner rights; use the -grant option to add read/execute rights when republishing.
-schema	The schema containing the Java <class> schema object; if you do not specify, the command uses the invoker's schema.
-version	Shows the command's version, then exits.

Here is an example of the publish command.

Publish the CORBA server implementation Bank.AccountManagerImpl and its helper class as /test/bank in the command invoker's schema:

$ ls -l /test
$ publish /test/bank Bank.AccountManagerImpl Bank.AccountManagerHelper 

$ ls -l /test 
Read  Write Exec  Owner Date   Time  Name  Schema Class                   Helper 
SCOTT SCOTT SCOTT SCOTT Dec 14 16:32 bank  SCOTT  Bank.AccountManagerImpl Bank.AccountManagerHelper 

pwd Command

The pwd command displays the name of the current working PublishingContext. It is analogous to the UNIX pwd command.

Syntax

pwd

Here is an example of the pwd command.

$ pwd
/test/alpha

rm Command

The rm (remove) command is analogous to the rm -r UNIX shell commands; it removes a PublishedObject or a PublishingContext, including its contents. To remove an object, you must have the write right for the containing PublishingContext.

Syntax

rm [options] <object> ... <object>
  [{-h | -help}] 
  [-r]
  [-version] 

Argument Summary

Table  2-13 describes the rm arguments.

Table 2-13 rm Argument Summary  

Option	Description
<object>	Name of PublishedObject or PublishingContext to be removed.
-help	Summarizes the command's syntax, then exits.
-r	Interprets <object> as a PublishingContext; removes it and its contents recursively.
-version	Shows the command's version, then exits.

Here is an example of the rm command.

Remove the PublishedObject /test/bank:

rm /test/bank

Remove the PublishingContext /test/release3 and everything it contains:

rm -r /test/release3

version Command

The version command shows the version of the sess_sh_816 tool.

Syntax

version

Here is an example of the version command.

Display the session shell's version:

$ version
1.0