The OSG Discovery Tool allows users to discover the BDII information they need
in order to use grid resources.

ENVIRONMENT

There are some optional environment variables which may be set on the
command line or in the conf/xpathsearch.rc

The URI of the LDAP server and the base to be searched from may be set with
LDAP_URI and LDAP_BASE, respectively. These default to the OSG production
BDII server and "o=grid" base.

The cache location (see below) may be set with XPATHCACHE_DIR. The expiration
time of the cache is set with MAX_CACHE_AGE. The default value is 86400 seconds.

Commands will run slightly faster if the JAVA_HOME variable is set.

For convenience, you may wish to add the "bin" directory of the installation to
your PATH variable, however, the scripts will also work when called using full
or relative paths.

JAVA VERSION

Java version 1.5 or higher is required. The scripts will search for a java
binary in the expected locations, starting with JAVA_HOME, until one of
sufficient version is found. Therefore, if you wish to specify the java binary
to be used, set the JAVA_HOME environment variable.

LOADING THE CACHE

The cache is loaded automatically when a query is run and the cache file is not
present or is older than the value of MAX_CACHE_AGE. To load the cache manually,
type

load_bdii_cache

This gathers all needed information from the BDII. Queries are evaluated
against the cache (except for xpathsearh, see Advanced Usage below). The above
command replaces any exsisting cache with a new one. By default, the cache
location is the "cache" directory of the installation. This may be changed by
setting XPATHCACHE_DIR in the xpathsearch.rc file.

GENERAL COMMAND LINE FORMAT

Each query script is called with a set of parameters specified on the command
line,  some of which may be optional. The command line format is as follows

script_name --parameter_name1 value1 --parameter_name2 value2 ...

All scripts use this form of name/value pair command line arguments. The help
argument is the form of "-h", "-help", or "--help", is supported by all scripts
and must be the first argument when used. When the help argument is specified,
a script will print it's purpose and the list of parameters that it takes, with
descriptions and indications of which are optional.

Script names begin with the prefix "get_". As of version ${discovery.version},
the query scripts are

get_mount_path: Returns a Compute Element mount point for a Storage Element
which authorizes the specified VO, followed by the associated job manager.

get_site_name: Returns a list of sites by name. The --vo option lists names of
sites that authorize a Storage Element access for the specified VO. The --seid
option lists the site name for a storage element with the given id.

get_site_name_for_seid: Returns the site name for a storage element with the
given id. See the command storage_element_ids for finding Storage Element IDs by
VO name.

get_srm_copy_cmd: Returns a list of example srm_copy commands for Storage
Elements on which the specified VO is authorized.

get_srmcp_cmd: Returns a list of example srmcp commands for Storage Elements on
which the specified VO is authorized.

get_srm_reserve_space_cmd: Returns a list of example srm_reserve_space commands
for Storage Elements on which the specified VO is authorized.

get_srm_sp_reserve_cmd: Returns a list of example srm-sp-reserve commands for
Storage Elements on which the specified VO is authorized.

get_storage_element_id: Returns a list of IDs for Storage Elements on which the
specified VO is authorized.

get_surl: Returns a list of example site URLS for Storage Elements on which the
specified VO is authorized.

ADVANCED USAGE

You may search the BDII directly using XPath expressions written using Glue
Schema 1.3. The command line format of the utility is as follows.

xpathsearch [-H <PROTOCOL://HOST:PORT>] [-b <BASE>] [options] xpathexpression

The URI and BASE arguments are options are optional if LDAP_URI and LDAP_BASE,
respectively, are set.

Type the command with the --help option to see a list of options.


FURTHER HELP

If further help is needed, please submit a ticket to
https://ticket.grid.iu.edu/goc/open.
