  Summary on the new configuration resources for NCBI network clients
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      By Denis V. Vakatov NCBI/NLM/NIH (vakatov@ncbi.nlm.nih.gov)


Due to the recent works on the old NCBI dispatcher replacement
I introduced some new resources which affect the new NCBI network
client functionality.

Supported network interfaces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SRV_CONN_MODE -- to specify which one of the now available network
                 interfaces should be used.
Value:
   DISPATCHER -- old NCBI dispatcher
   WWW        -- Web-based dispatcher in the stateful connection mode [default]
   FIREWALL   -- just like "WWW" but the data connection goes through the NCBI
                 firewall daemon that listens at one of well-known hosts/ports
   STATELESS  -- Web-based dispatcher in the stateless connection mode
   DEBUG      -- direct client-to-server connection(bypass dispatchers)


Resources for WWW, FIREWALL and STATELESS interfaces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SRV_ENGINE_****:  to compose URL of the NCBI HTTP-based dispatcher
[default = http://www.ncbi.nlm.nih.gov:80/Service/nph-dispd.cgi]

SRV_ENGINE_HOST:  [default = www.ncbi.nlm.nih.gov]
SRV_ENGINE_PORT:  [default = 80]
SRV_ENGINE_URL:   [default = /Service/nph-dispd.cgi]


SRV_HTTP_PROXY_HOST:    [default = n/a]
SRV_HTTP_PROXY_PORT:    [default = 80]
Value:
   Address of an HTTP proxy server (host:port)
Note:
   SRV_HTTP_PROXY_PORT is ignored if SRV_HTTP_PROXY_HOST is not specified

| The "SRV_HTTP_PROXY_*" are used in the dispatching stage, which engages
| WWW-based NCBI dispatcher (nph-dispd.cgi).
| If "SRV_HTTP_PROXY_*" are specified, then client sends the dispatching
| HTTP request to NCBI through your HTTP proxy server at:
| 		  http://SRV_HTTP_PROXY_HOST:SRV_HTTP_PROXY_PORT/
| rather than directly to:
| 		  www.ncbi.nlm.nih.gov:80/Service/nph-dispd.cgi



SRV_PROXY_HOST:         [default = n/a]
Value:
   Host name of a non-transparent CERN-like firewall proxy server

| SRV_PROXY_HOST can be used to establish a connection to transfer the data
| between client & server (after the dispatching).
| If "SRV_PROXY_HOST" is specified, then client connects to your
| non-transparent firewall server at the specified (by "SRV_PROXY_HOST")
| host rather than directly to the NCBI server.
| In this case, you must work in the FIREWALL connection mode
| (set SRV_CONN_MODE=FIREWALL), and map the well-known ports
| on your proxy firewall server to those of NCBI
| (see in http://www.ncbi.nlm.nih.gov/cpp/network/firewall.html).
| Thus the mapping on your non-transparent firewall server
| shoul look like this:
| 
| SRV_PROXY_HOST:5853    -->    130.14.22.1:5853
| SRV_PROXY_HOST:5859    -->    130.14.22.2:5859
| SRV_PROXY_HOST:5840    -->    130.14.22.8:5840
| SRV_PROXY_HOST:5810    -->    130.14.22.30:5810
| SRV_PROXY_HOST:5812    -->    130.14.22.31:5812
| SRV_PROXY_HOST:5811    -->    130.14.22.32:5811
| 
| NOTE:  It's pretty rare (if ever) when you have to use
|        "SRV_PROXY_HOST" as most of firewalls are "transparent"
|        nowdays.


SRV_DEBUG_PRINTOUT:  to printout messages sent by dispatcher when
                     establishing client-server connection
Value:
   "1", "yes", "true" (case-insensitive) -- do printout
   otherwise -- do not printout [default]


SRV_NO_LB_DIRECT:  to prohibit the use of local load-balancing daemon
Value:
   "0", "false", "no" (case-insensitive) -- do not use local load-balancing
   otherwise -- try to use local load-balancing [default]


SRV_CONN_TIMEOUT:  timeout to use in the dispatcherization stage, and to
                   connect (only to connect, not for the I/O) to the server.
Value:
   a positive integer or floating-point value (in sec.)  [default = 30]


SRV_CONN_TRY:  maximum number of attempts to establish the connection
Value:
   a positive integer  [default = 3]


Resources for DEBUG interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

NI_DEBUG_HOST:  the server host to connect to
Value(mandatory):
   smth. like "123.45.67.89" or "mysrvhost" or "xxx@yyy.zzz.gov"

NI_DEBUG_PORT:  the server port to connect to
Value(mandatory):
   a positive integer

NI_DEBUG_TRY:  maximum number of attempts to establish the connection
Value:
   a positive integer [default = 2]


How to set the resource values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The above resource values can be set either by using the NCBI resource
(configuration) file or (on UNIX, MS Windows and VMS) by setting relevant
environment variable.  The environment variable overrides the value
set in the NCBI resource file.

[NET_SERV]
SRV_CONN_MODE
SRV_DEBUG_PRINTOUT
SRV_NO_LB_DIRECT
SRV_CONN_TIMEOUT
SRV_CONN_TRY

[ENTREZ_NET]
NI_DEBUG_HOST
NI_DEBUG_PORT
NI_DEBUG_TRY


For example, in order to set the connection establishment timeout to
12.345 sec. you should set environment variable:

UNIX csh:
   setenv SRV_CONN_TIMEOUT 12.345
UNIX sh, bash:
   SRV_CONN_TIMEOUT=12.345
   export SRV_CONN_TIMEOUT
DOS prompt:
   set SRV_CONN_TIMEOUT=12.345

or, in the NCBI configuration file:

   [NET_SERV]
   SRV_CONN_TIMEOUT=12.345


NOTES
~~~~~

1. STATELESS connection mode is usually not available for the distributed
applications. It is hardcoded to be unavailable unless the "ni_lib_.c"
module is compiled with the "-DALLOW_STATELESS" flag.

2. The local LOAD-BALANCING is *never* available for the distributed
applications. It is hardcoded to be unavailable unless "ni_lib_.c"
and "lbapi.c" modules are compiled with the "-DLB_DIRECT" flags, on
Solaris or IRIX. Then, the client must run on the host that:
a) belongs to one of NCBI subnets and
b) has "lbdaemon"(load-balance daemon) application running on it.

$Date: 2001/02/20 20:15:52 $
