path: root/debian/TAO_ORB_Options.sgml

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  <!ENTITY applname "TAO_ORB_Options">
  <!ENTITY revision "$Revision$">
  <!ENTITY progname "tao_program">
  <!ENTITY year "1999">
  <!ENTITY username "Douglas C. Schmidt">
  <!ENTITY useremail "<email>&lt;schmidt@cs.wustl.edu&gt;</email>">
]>
<refentry>
  <refmeta>
    <refentrytitle>TAO_ORB_OPTIONS</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>&applname;</refname>
    <refpurpose>Common options for programs that use TAO</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <title>SYNOPSIS</title>
    <cmdsynopsis>
      <command>&progname;</command>
      <arg>ORB_options</arg>
      <arg>program_options</arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>
    <para>
      All programs relying on TAO understand the same set of
      parameters: the <emphasis>-ORB</emphasis> options that affect
      the ORB behaviour.
    </para>
    <para>
      This manual page describe these parameters. Please note that the
      ORB behaviour can also be altered using a
      <filename>svc.conf</filename>. See TAO's documentation for help
      on that topic.
    </para>
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>
    <variablelist>
      <varlistentry>
	<term><parameter>-ORBSvcConf</parameter> <replaceable>configfilename</replaceable></term>
	<listitem>
	  <para>
            Specifies the name of the file used to read service
            configuration directives via the Service Configurator
            framework. By default, a service configurator-based
            application will look for a file named
            <filename>svc.conf</filename> in the current directory.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBSvcConfDirective</parameter> <replaceable>directivestring</replaceable></term>
	<listitem>
	  <para>
            Specifies a service configuration directive, which is
            passed to the Service Configurator. You can pass multiple
            of these options on the same command-line.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBDebug</parameter></term>
	<listitem>
	  <para>
            Instructs the ORB to print debugging messages from the
            service configurator framework. This option does not have
            a value but is used as a toggle to enable or disable
            debugging messages.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBDebugLevel</parameter> <replaceable>level</replaceable></term>
	<listitem>
	  <para>
            Control the level of debugging in the ORB. Higher numbers
            generate more output (try 10). The default value of this
            option is 0.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBVerboseLogging {0,1,2}</parameter></term>
	<listitem>
	  <para>
            Controls the amount of status data printed on each line of
            the debug log. Higher numbers generate more output.  The
            default value of this option is <parameter>0</parameter>.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBLogFile</parameter> <replaceable>logfilename</replaceable></term>
	<listitem>
	  <para>
            Causes all <function>ACE_DEBUG</function> and
            <function>ACE_ERROR</function> output to be redirected to
            the designated <replaceable>filename</replaceable>.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBObjRefStyle {IOR,URL}</parameter></term>
	<listitem>
	  <para>
            Specifies the user-visible style of object references. The
            <parameter>IOR</parameter> style (default) is the conventional 
	    CORBA object reference, whereas the <parameter>URL</parameter> 
	    style looks more like a URL.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBCDRTradeoff</parameter> <replaceable>maxsize</replaceable></term>
	<listitem>
	  <para>
            Control the strategy to tradeoff between copy vs. no copy
            marshaling of octet sequences. If an octet sequence is
            smaller than <replaceable>maxsize</replaceable> (which
            defaults to
	    <constant>ACE_DEFAULT_CDR_MEMORY_TRADEOFF</constant>) --
            and the current message block contains enough space for it
            -- the octet sequence is copied instead of appended to the
            CDR stream.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBCollocation {global,per-orb,no}</parameter></term>
	<listitem>
	  <para>
           Specifies the use of collocation object optimization. If
           <parameter>global</parameter> is specified (default), objects
           in the same process will be treated as collocated.  If
           <parameter>per-orb</parameter> is specified, only objects in
           the same ORB are treated as collocated. When
           <parameter>no</parameter> is specified, no objects are
           treated as collocated.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBCollocationStrategy {thru_poa,direct}</parameter></term>
	<listitem>
	  <para>
            Specifies what type of collocated object to use. If the
            <parameter>thru_poa</parameter> (default) strategy is used,
            TAO uses the collocation object implementation that
            respects POA's current state and policies. When using the
            <parameter>direct</parameter> strategy, method invocations
            on collocated objects become direct calls to servant
            without checking POA's status, which can increase
            performance. If you use the 
            <parameter>direct</parameter> strategy, your interfaces must 
            be compiled with the <parameter>-Gd</parameter> IDL compiler option.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBNodelay {0,1}</parameter></term>
	<listitem>
	  <para>
            Enable or disable the <constant>TCP_NODELAY</constant> option 
            (Nagle's algorithm). By default, 
            <constant>TCP_NODELAY</constant> is enabled.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBRcvSock</parameter> <replaceable>recv_size</replaceable></term>
	<listitem>
	  <para>
            Specify the size of the socket receive buffer as a
            positive, non-zero integer. If not specified, the
            <constant>ACE_DEFAULT_MAX_SOCKET_BUFSIZ</constant> default
            is used.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBSndSock</parameter> <replaceable>snd_size</replaceable></term>
	<listitem>
	  <para>
            Specify the size of the socket send buffer as a positive,
            non-zero integer. If not specified, the
            <constant>ACE_DEFAULT_MAX_SOCKET_BUFSIZ</constant> default
            is used.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBStdProfileComponents {0,1}</parameter></term>
	<listitem>
	  <para>
            If <parameter>0</parameter> then the ORB does not generate
            the OMG standardized profile components, such as the ORB
            type and code sets. Notice that the presence of this
            components is optional in GIOP 1.1 The default value is
            controlled by a compile-time flag (check
            <filename>orbconf.h</filename>).
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBSingleReadOptimization {0,1}</parameter></term>
	<listitem>
	  <para>
            This option controls whether TAO's ``single read
            optimization'' is used when receiving requests. If this
            option is disabled (<parameter>0</parameter>), the ORB will
            do two reads to read a request: one reads the request
            header and the other reads the request payload. If this
            option is enabled (<parameter>1</parameter>), the ORB will
            do a read of size <constant>TAO_MAXBUFSIZE</constant>,
            hoping to read the entire request.  If more than one
            request is read they will be queued up for processing
            later.
          </para>
          <para>
            This option defaults to <parameter>1</parameter> because it
            can provide better performance. However, in the case of
            RT-CORBA, this option should be set to
            <parameter>0</parameter>. Consider the following scenario:
            <itemizedlist>
	      <listitem>
		<para>two requests are read from one socket,</para>
	      </listitem>
	      <listitem>
		<para>the additional request is queued, and</para>
	      </listitem>
	      <listitem>
		<para>the ORB uses its Reactor's notification
            mechanism to wake up the follower threads. </para>
	      </listitem>
	    </itemizedlist>
          </para>
	  <para>
            If at the same time, however, new requests arrive on
            others sockets of higher priority the lower priority
            queued message will be processed before the newly arrived
            higher priority request since Reactor notifications are
            given preferences over normal I/O, thereby causing
            priority inversion.
          </para>
	</listitem>	
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBDisableRTCollocation {0,1}</parameter></term>
	<listitem>
	  <para>
            This option controls whether the application wants to use
            or discard RT collocation decisions made by the RT ORB. A
            value of <parameter>1</parameter> disables RT collocation
            decisions and falls back on the default collocation
            decisions implemented in the default ORB. This is very
            useful for applications using the RT ORB and doesn't want
            to use the RT collocation decisions but fallback on the
            default decisions for better performance. The default
            value is <parameter>0</parameter>.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBDefaultInitRef</parameter> <replaceable>ior_prefix</replaceable></term>
	<listitem>
	  <para>
            This argument allows resolution of initial references not
            explicitly specified with
            <parameter>-ORBInitRef</parameter>. It requires a URL prefix
            that, after appending a slash `/' (`|' for the UIOP
            pluggable protocol) and a simple object key, forms a new
            URL to identify an initial object reference. The URL
            prefix format currently supported is based on the standard
            corbaloc mechanism in the CORBA Interoperable Naming
            Service.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBDottedDecimalAddresses {0,1}</parameter></term>
	<listitem>
	  <para>
            Use the dotted decimal notation for addresses. This option
            can be used to workaround broken DNS implementations and
            may also reduce the time spent resolving IP addresses. By
            default, this option is disabled (<parameter>0</parameter>)
            since domain names are the standard address notation for
            IORs.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBEndpoint</parameter> <replaceable>endpoint</replaceable></term>
	<listitem>
	  <para>
            This option is similar to the
            <parameter>-ORBListenEndPoints</parameter> option described
            below. This option will be deprecated in later versions on
            TAO since the CORBA specification now defines the
            <parameter>-ORBListenEndpoints</parameter> option instead.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBListenEndpoints</parameter> <replaceable>endpoint</replaceable></term>
	<listitem>
	  <para>
            This option was introduced with the CORBA ORT (Object
            Reference Template) specification. It instructs a server
            ORB to listen for requests on the interface specified by
            <replaceable>endpoint</replaceable>. TAO endpoints are
            specified using a URL style format. An endpoint has the
            form: `protocol://V.v@addr1,...,W.w@addrN' 
            where V.v and W.w are optional protocol versions for each
            address.  An example of an IIOP endpoint is:
	    `iiop://hostname:port'
          </para>
	  <para>
            Sets of endpoints may be specified using multiple
            <parameter>-ORBEndpoint</parameter> options or by delimiting
            endpoints with a semi-colon (`;'). For example, 

            `-ORBEndpoint iiop://localhost:9999 -ORBEndpoint uiop:///tmp/mylocalsock -ORBEndpoint shmiop://10002'

            is equivalent to:

	    `-ORBEndpoint 'iiop://localhost:9999;uiop:///tmp/mylocalsock;shmiop://10002''

            Notice the single quotes (') in the latter option
            specification. Single quotes are needed to prevent the
            shell from interpreting text after the semi-colon as
            another command to run.

            If an endpoint is specified without an addr such as the
            following:

            `-ORBEndpoint uiop:// -ORBEndpoint shmiop://'

            then a default endpoint will be created for the specified
            protocol.
          </para>
	</listitem>	
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBImplRepoServicePort</parameter> <replaceable>portspec</replaceable></term>
	<listitem>
	  <para>
            Specifies which port the Implementation Repository is
            listening on for multicast requests. By default, the
            <constant>TAO_DEFAULT_IMPLREPO_SERVER_REQUEST_PORT</constant> (10018) is used.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBInitRef</parameter> <replaceable>ObjectId=IOR</replaceable></term>
	<listitem>
	  <para>
	  Allows specification of an arbitrary object reference for an
	  initial service. The IOR could be in any one of the following
	  formats: OMG IOR, URL, corbaloc (including uioploc) or file.
	  corbaloc is a multiple end-point IOR understood by
	  <function>ORB::string_to_object()</function> and used as a
	  boot-strapping mechanism by the
	  <function>ORB::resolve_initial_references()</function>. The
	  mappings specified through this argument override the ORB
	  install-time defaults.
	  The file://pathname interprets the contents of the pathname file as
	  an object reference in any of the above formats.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBMulticastDiscoveryEndpoint</parameter> <replaceable>endpoint</replaceable></term>
	<listitem>
	  <para>
	  Specifies the endpoint that should be used for locating the
	  Naming Service through multicast.
	  <replaceable>endpoint</replaceable> is of the form
	  ip-number:port-number (e.g., "tango.cs.wustl.edu:1234" or
	  "128.252.166.57:1234"). If there is no `:' in the
	  <replaceable>endpoint</replaceable> it is assumed to be a port
	  number, with the IP address being <constant>INADDR_ANY</constant>.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBNameServicePort</parameter> <replaceable>portspec</replaceable></term>
	<listitem>
	  <para>
	  Specifies which port the Naming Service is listening on for multicast 
	  requests. By default, the 
	  <constant>TAO_DEFAULT_NAME_SERVICE_REQUEST_PORT</constant> (10013) 
	  value is used.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBTradingServicePort</parameter> <replaceable>portspec</replaceable></term>
	<listitem>
	  <para>
	  Specifies to which port the Trading Service is listening on for 
	  multicast requests. By default, the 
	  <constant>TAO_DEFAULT_TRADING_SERVICE_REQUEST_PORT</constant> (10016) 
	  value is used.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBUseIMR {0,1}</parameter></term>
	<listitem>
	  <para>
	  This argument specifies that for POAs with the PERSISTENT policy, 
	  that the TAO Implementation Repository should be used for 
	  notification of startup and shutdown and object references should 
	  be changed to use the Implementation Repository also.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBId</parameter> <replaceable>orb_name</replaceable></term>
	<listitem>
	  <para>
	  This option allows the name of an ORB to be set to 
	  <replaceable>orb_name</replaceable>. The ORBId will be passed to the 
	  <function>ORB_init()</function> method to differentiate coexisting 
	  ORBs (when there are more than one ORBs).
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBServerId</parameter> <replaceable>server_id</replaceable></term>
	<listitem>
	  <para>
	  This option allows setting a name/id to a server to uniquely 
	  identify a server to TAO's Implementation Repository.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-ORBDaemon</parameter></term>
	<listitem>
	  <para>
	  Specifies that the ORB should daemonize itself, i.e., run as a 
	  background process. This option is only meaningful on OS 
	  platforms that support daemonization.
          </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>ENVIRONMENT VARIABLES</title>
    <para>
      Environment variables have a limited use in TAO ORB
      configuration. The currently supported environment variables are
      listed below. They are used to specify the IOR and port numbers
      for three of TAO's ORB services.
    </para>

    <variablelist>
      <varlistentry>      
        <term><parameter>NameServicePort</parameter></term>
        <listitem>
          <para>
            Specifies which port the Naming Service is listening on
            for multicast requests.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>TradingServicePort</parameter></term>
	<listitem>
	  <para>
            Specifies which port the Trading Service is listening on
	    for multicast requests.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>ImplRepoServicePort</parameter></term>
	<listitem>
	  <para>
	    Specifies which port the Implementation Repository is
	    listening on for multicast requests.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      In addition to being able to define the port where these known
      services are listening for multicast requests, as above, it is
      possible to set an environment variable that specifies the IOR
      of any named service. For example
      NameServiceIOR=<replaceable>which</replaceable>,
      TradingServiceIOR=<replaceable>which</replaceable>,
      ImplRepoServiceIOR=<replaceable>which</replaceable>,
      MyServiceIOR=<replaceable>which</replaceable>. This will have a
      similar effect to defining an <parameter>-ORBInitRef</parameter>
      value on the command line (see above). Any value set as a
      command line <parameter>-ORBInitRef</parameter> option will
      override any value set as an environment variable for the same
      service name.

      In general, setting environment variables is not particularly
      portable or convenient, which is why users can also set these
      options via command-line options.
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>
    <para>&username; &useremail;</para>
  </refsect1>
</refentry>