# sdci.pod: Support Diagnostic Command-Line Interface Manual Pages
# $Id: sdci.pod,v 1.9 2015/11/09 18:51:40 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/Pod/en/sdci.pod,v 1.9 2015/11/09 18:51:40 RDA Exp $

=for stopwords sdci

=head1 NAME

sdci - Support Diagnostic Command-line Interface (SDCI)

=head1 SYNOPSIS

 sdci.sh [-bilnqvy] [-X pkg|-M|-V] [-e edt] [-s nam] [-t lvl] [-u lng]
 [fct arg...]

 sdci.cmd [-bilnqvy] [-X pkg|-M|-V] [-e edt] [-s nam] [-t lvl] [-u lng]
 [fct arg...]

 sdci.pl [-bilnqvy] [-X pkg|-M|-V] [-e edt] [-s nam] [-t lvl] [-u lng]
 [fct arg...]

See the following sections for additional information about the switches.

=head1 DESCRIPTION

SDCI is a command-line tool to manage Oracle diagnostic data collectors and,
more particularly, the Remote Diagnostic Agent (RDA).

The purpose of RDA is to assist in problem analysis and troubleshooting of
local and remote databases, file systems, and operating system environments in
relation to Oracle products. This tool helps automate the task of gathering
information about an Oracle environment for the Oracle Support and Development
teams and customers to analyze the Oracle technology stacks quickly.

For example, if a customer has problems with Oracle Net, then Oracle Support
may want to view the configuration files and the environment related to the
problems. This can include information about the operating system, database,
and file system. The RDA Development team adds content to the tool regularly
to gather information about more products.

You can run RDA concurrently as long as each execution refers to a different
setup file. You can share the same report directory if you specify different
report groups during the setup phase. However, usually the compiled versions of
the RDA engine do not allow concurrent executions.

For more information about this tool, or to download the latest version, see
My Oracle Support documents 314422.1 and 330363.1.

=head1 COMMAND VARIANTS

=over 10

=item F<sdci.sh>

UNIX shell SDCI launcher, which attempts to locate Perl in the Oracle home
directory structure when it is not available in the C<PATH> environment
variable.

=item F<sdci.cmd>

Microsoft SDCI launcher, which attempts to locate Perl in the Oracle home
directory structure.

=item F<sdci.com>

VMS SDCI launcher, which checks the user environment and locates Perl and Zip.

=item F<sdci.pl>

SDCI main script, which can be used directly if Perl is available in the
C<PATH> environment variable (for UNIX) or if the C<.pl> suffix is registered
(for Windows).

=back

=head1 OPTIONS

=head2 Mode Options

=over 4

=item B<-M>

Displays the command manual pages.

=item B<-V>

Displays the software and engine builds.

=item B<-X pkg>

Invokes the specified user interface. The default user interface is C<Rda>.

=back

=head2 Modifiers

=over 8

=item B<-b>

Does not back up the setup file. By default, SDCI renames the setup file with a
C<.bak> suffix before rewriting the file.

=item B<-e key=value[,...]>

Specifies a temporary value for one or more settings. SDCI converts the setting
names automatically to upper case and separates the different assignments by
commas.

For example, the following value enables some ping tests and allows a maximum
of 120 seconds for executing each SQL request.

 -e OS.NET.B_PING_TESTS=1,DFT/N_SQL_TIMEOUT=120

You can use this mechanism also to alter the default setting values when making
non-interactive setups.

=item B<-h>

Displays the command usage and exits.

=item B<-i>

Reads settings from the standard input. Therefore, this option suppresses all
interactive dialogues in setup and all user acknowledge requests in the data
collection or tests.

=item B<-l>

Uses a lock file to prevent concurrent usage of a setup file. RDA derives the
name of the lock file from the setup file name. RDA generates an error if the
lock cannot be acquired immediately.

=item B<-n>

Ignores the content of any existing setup file. This option enables you to
start a new collection without any manual operation on existing setup files.

=item B<-q>

Sets the quiet mode.

=item B<-s nam>

Specifies the name of the setup file (F<output> by default). You can maintain
multiple setup configurations in the same directory structure. The name of the
setup file can contain a directory part. That directory must exist and will
be used as the default location for other files (such as lock files and the
report directory).

=item B<-u lng>

Specifies the language and the character set to use for the engine error
messages and texts. For example,

  -l es.88591

gives the preference to Spanish when available. SDCI will encode them with the
ISO 8859-P1 character set.

=item B<-v>

Sets the verbose mode.

=item B<-y>

Accepts all setting defaults in the module configuration. This option
suppresses all interactive dialogues in setup and all user acknowledge requests
in the data collection or tests.

=back

=head2 Debugging Options

=over 8

=item B<-t lvl>

Enables RDA tracing and specifies the global trace level. The trace level is an
integer number between 0 and 99. The upper digit is dedicated to the agent
operations, while the lower digit is more used by the functional layers.

Specialized dump and trace mechanisms requires the presence of this option,
regardless its value.

=back

=head1 SPECIAL USAGE

The mode flags are exclusive.

By default, SDCI creates collector definition files and their corresponding
diagnostic data directories in the current working directory. The name of the
diagnostic data directory is derived from the collector name. Use the B<-s>
option or the C<RDA_SETUP> environment variable to store them in another
directory.

=head1 ENVIRONMENT

The following environment variables influence the execution of RDA:

=over 13

=item COLUMNS

Used to adjust the page width when displaying manual pages (78 by default).

=item HOME

User home directory.

=item ORACLE_BASE

Oracle base directory.

=item ORACLE_HOME

Oracle home directory.

=item ORACLE_SID

Oracle system identifier.

=item PAGER

Pager that RDA uses to display the manual pages. RDA uses F<more> by default.

=item PATH

Command execution path.

=item RDA_BUNDLE

Path of a complementary XML conversion bundle definition file (none by
default). SDCI ignores the environment variable when the corresponding file
does not exist or cannot be read.

=item RDA_CHARSET

Character set to use when displaying engine message (C<utf8> by default)

=item RDA_CONVERT

Alternative location for the XML conversion plug-in directory structure
(F<Convert> by default).

=item RDA_CWD

Alternative working directory for the setup files or for relative paths to
setup files. When you do not specify this variable, RDA uses the current
working directory.

=item RDA_DOMAIN

Default domain name used to bypass the domain detection. RDA performs this
detection at setup when the domain name is not available from the setup file
and not included in the host name.

=item RDA_EDIT

Specifies a temporary value for one or more settings as for the B<-e> option.

=item RDA_FILTER

Filter definition file to load when creating a new setup file.

=item RDA_LANG

Preferred language to use by the engine (C<en> by default).

=item RDA_LEVEL

Sets the global trace level.

=item RDA_LOCK

Directory where the RDA lock files are stored. By default, they are stored in
the directory that contains the setup file.

=item RDA_MAN

When specified, it does not use C<Pod::Text> to display manual pages.

=item RDA_MRC

Path of a complementary multi-run collection definition file. RDA ignores the
environment variable when the corresponding file does not exist or cannot be
read.

=item RDA_NO_7ZIP

When specified, it disables the search and the use of the F<7zip> command.

=item RDA_NO_COMPRESS

When specified, it disables the search and the use of the F<compress> command.

=item RDA_NO_DBD_ORACLE

When set to a nonzero value, disables the usage of C<DBD::Oracle>. The command
wrappers do not verify that Perl can load this package without errors when a
value is set.

=item RDA_NO_GZIP

When specified, it disables the search and the use of the F<gzip> command.

=item RDA_NO_JAR

When specified, it disables the search and the use of the F<jar> command.

=item RDA_NO_PAX

When specified, it disables the search and the use of the F<pax> command.

=item RDA_NO_TAR

When specified, it disables the search and the use of the F<tar> command.

=item RDA_NO_ZIP

When specified, it disables the search and the use of the F<zip> command.

=item RDA_PID

Directory where the control files for the background collection are stored.
By default, they are stored in the directory that contains the setup file.

=item RDA_PROFILE

Path of a complementary profile definition file. RDA ignores the
environment variable when the corresponding file does not exist or cannot be
read.

=item RDA_SETUP

Specifies the setup name to be used when the B<-s> option is not specified. The
name can contain a directory part. That directory must exist and is used as a
default location for other files (such as the lock files and the report
directory).

=item SHELL

For UNIX, the command interpreter (shell) to use.

=item TERM

Terminal name. When supported by the platform, it identifies the escape
sequences used for controlling the display.

=back

=head1 FILES

For UNIX, F<sdci.sh> or F<rda.sh> creates a F<.config> file to cache where Perl
is located in the Oracle home directory structure.

RDA collects execution events and statistics in an F<RDA.log> file in the data
diagnostic data  directory. Use this file to retrieve the execution history. For
security reasons, it does not contain any setting or command arguments. The
report packages contain the F<RDA.log> file to identify further product
improvements.

The RDA engine can create three lock files. The names are derived from the
setup file name:

=over 16

=item F<E<lt>setupE<gt>.lck>

To avoid concurrent usage of a setup file (see options B<-B> and B<-l>)

=item F<-B-E<lt>setupE<gt>.lck>

To serialize file manipulation tasks between foreground and background RDA
processes.

=item F<-T-E<lt>setupE<gt>.lck>

To monitor thread execution completion.

=back

The C<RDA_LOCK> environment variable influences the location of the lock files.

=head1 PERL PACKAGES USED

An RDA data collection explicitly calls the following Perl packages:

=over 2

=item o F<strict>

=item o F<vars>

=item o F<Cwd>

=item o F<Exporter>

=item o F<File::Basename>

=item o F<File::Copy>

=item o F<File::Spec>

=item o F<Getopt::Std>

=item o F<IO::File>

=item o F<IO::Handle>

=item o F<POSIX>

=item o F<Socket>

=item o F<Symbol>

=item o F<Time::Local>

=back

The following packages are used but they are not required for the data
collection:

=over 2

=item o F<Compress::Zlib> (used for accessing archives)

=item o F<DBD::ODBC> (used for alternative ODBC accesses)

=item o F<DBD::Oracle> (used for alternative accesses to Oracle databases)

=item o F<DBI> (used for alternative database accesses)

=item o F<Digest::MD5> (used for check sums)

=item o F<Fcntl> (used in locking context)

=item o F<Sys::Hostname> (used as help for determining the domain name)

=item o F<Term::Cap> (used to enhance the display)

=item o F<Time::HiRes> (used for clock checks)

=item o F<Win32> (used for spawning processes)

=item o F<Win32::Console> (used for disabling echo)

=item o F<Win32::ODBC> (used for ODBC accesses)

=item o F<Win32::Process> (used for spawning processes)

=back

=head1 COPYRIGHT NOTICE

Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved.

=head1 TRADEMARK NOTICE

Oracle and Java are registered trademarks of Oracle and/or its
affiliates. Other names may be trademarks of their respective owners.

=cut