# The CorbaScript User's Guide

This document describes the following items:

- The ORB Administration Commands
- The CorbaScript Configuration Repository
- The CorbaScript Environment Variables
- The CorbaScript Initialization Script

# The ORB Administration Commands

CorbaScript runs on various ORB products (MICO, OAK, OmniBroker, omniORB, ORBacus, Orbix 2000, TAO, VisiBroker, ...). However each ORB has its specific rules to configure and start initial services like the Interface Repository, the Name Service and other required daemons (e.g. a process activator, the Implementation Repository and so on). Depending of the ORB product, users' CORBA applications can know this initial configuration via various approaches: command line arguments with MICO, a configuration file with ORBacus, or a set of daemons with OAK and VisiBroker. Moreover, needed dynamic librairies are different for each ORB product. So even if we use the CORBA way to build portable applications we will always depend of specificities of the used ORB product ;-(

Then on Unix and Windows systems, CorbaScript provides a set of commands to unify and simplify in the same way its use on any ORB products, i.e. same shell commands for all ORB products. These commands are:

- cssh_install: it creates a configuration repository where are stored the IOR, the process ID and log files of the various ORB servers (ORB daemons, Interface Repository and Name Service). Then it starts the ORB daemons (if required), the Interface Repository and the Name Service.

- cssh_deinstall: it stops the Name Service, the Interface Repository and the ORB daemons (if required). Then the configuration repository is deleted.

- orb_start: it starts the ORB daemons (if required).

- orb_stop: it stops the ORB daemons (if required) started with orb_start.

- ir_start: it starts the Interface Repository and stores its IOR and process ID into the configuration repository.

- ir_stop: it stops the Interface Repository started with ir_start.

- ir_load: it loads an OMG IDL file into the Interface Repository.

- ir_destroy: it removes an OMG IDL definition from the Interface Repository.

- ns_start: it starts the Name Service and stores its IOR and process ID into the configuration repository.

- ns_stop: it stops the Name Service started with ns_start.
- nssh: it starts the CorbaScript's Naming Service Shell.

A session counter is stored in the CorbaScript Configuration Repository that is incremented every time a session is started (`cssh_install`) and is decremented every time a session is stopped (`cssh_deinstall`). The CorbaScript Configuration Repository would then only be removed when the counter reaches zero. Then this avoids to stop the Interface Repository and the Name Service already used by another session.

These commands are strongly used in provided demonstrations (look at demo/win.bat and demo/*/run.sh and run.csh files). This allows us to write portable demonstration shell scripts which are independent of the used OS and ORB product.

These commands are generated in the CorbaScript compilation directory and are contained into three shell script files according to the system:

- envi.ORB.sh for Unix Bourne shells and GNU Bash on Windows.
To load it, do:

         prompt> . envi.ORB.sh

- envi.ORB.csh for Unix C shells.
To load it, do:

         prompt> source envi.ORB.csh

- envi.bat for Windows command shells.
  To load it, do:

           prompt> call envi.bat

  Warning, this script does not provide *_stop commands, then we need to manually stop started processes.

Moreover, these shell files set environment variables (e.g. PATH and LD_LIBRARY_PATH) to access to the binaries and the libraries of the used ORB product.

For instance, you could do:

        prompt> # Loads the set of commands and variable setting.
        prompt> source /path_where_CorbaScript_is_compiled/envi.ORB.csh

        prompt> # Starts the Interface Repository and the Name Service.
        prompt> cssh_install

        prompt> # Feeds an IDL file into the Interface Repository.
        prompt> ir_load MyFile.idl

        prompt> # Starts CorbaScript.
        prompt> cssh
        ....
        >>> # Type CTRL-D to stop it on Unix systems.
        >>> # Type CTRL-Z to stop it on Windows systems.

        prompt> # Deinstalls the previously started Interface Repository
                # and Name Service.
        prompt> cssh_deinstall

However, you could always directly used the programs and options provided by the used ORB product, have a look into the associated ORB documentation. Then CorbaScript is simply a CORBA program that accepts all the command line options supported by the ORB.

For instance, the ORBacus User Guide fully describes accepted binary commands and their command line options. You can use -ORBInitRef to supply initial references, it is covered in the ORBacus 3.2.1 Manual in section 4.3.2. It takes the form "-ORBInitRef name=ior". "InterfaceRepository" and "NameService" are the standard names for those services. For example, you could redirect the IORs of the services to files and then use the file URI's as arguments to ORBInitRef, i.e.

        prompt> nameserv -i > /tmp/ns.ior &
        prompt> irserv -i > /tmp/ifr.ior &
        prompt> cssh -ORBInitRef InterfaceRepository=file://tmp/ifr.ior -ORBInitRef NameService=file://tmp/ns.ior

Let's note that the CorbaScript unified commands contained into envi.* files do similar things on ORBacus ;)

# The CorbaScript Configuration Repository

The CorbaScript configuration repository, previously mentioned, is simply a directory that can contain the following files:

- InitialServices lists the initial services which MUST be used by the CorbaScript interpreter.
When CorbaScript needs an initial service, it searches it into this list and if it doesn't find it then it invokes the ORB.
Each line of this file contains the name of one service. For each listed service S, the configuration repository must contain a file named S.IOR which contains the stringified IOR of this service.
- InterfaceRepository.IOR contains the IOR of the Interface Repository used by the CorbaScript interpreter.
- InterfaceRepository.PID contains the process ID of the Interface Repository server. It is used by ir_stop.
- NameService.IOR contains the IOR of the Name Service used by the CorbaScript interpreter.
- NameService.PID contains the process ID of the Name Service server. It is used by ns_stop.

The CS_CONFIG_HOMEDIR shell variable defines the directory path containing the configuration repository.

By default, this variable is set to $HOME/CS_for_${CS_ORB_NAME}. Then each user has its own ORB configuration.
But this variable can be set to another path allowing to share an ORB configuration between several users.
If it is set to /tmp/ORB then each host has its own ORB configuration.
If it is set to a NFS directory then the ORB configuration can be shared by all hosts allowed to access to the NFS server.

Warning to fix another configuration repository path, the CS_CONFIG_HOMEDIR must be set before loading the envi.ORB.sh or envi.ORB.csh file, for instance with a Unix C shell:

         unix> setenv CS_CONFIG_HOMEDIR /nfs/a_path_to/the_configuration_repository
         unix> source envi.ORB.csh

On OAK and VisiBroker, the configuration repository is not necessary because these ORBs provide daemons to locate services on the network.

# The CorbaScript Environment Variables

Currently, the following variables can be used to configure the CorbaScript interpreter:

- CS_CONFIG_HOMEDIR: see the configuration repository.
- CSPATH: it defines the list of paths where CorbaScript searches downloadable modules. Modules are simply CorbaScript files suffixed by the `.cs' extension. They can be loaded by the 'import' statement.
- CSSHRC: it defines the script file name which CorbaScript could execute at initialization time.

# The CorbaScript Initialization Script

CorbaScript could execute a script at initialization time before running interactively or executing a script file. This initialization script is searched according the following steps:

1. If the command line -e file.cs is provided then CorbaScript executes the specified file.cs.
2. Else CorbaScript executes the file specified by the CSSHRC environment variable if set.
3. Else CorbaScript tries to execute the $HOME/.csshrc file if exist.