# DCextra.ctl:E998:Collects User Defined Data
# $Id: DCextra.ctl,v 1.4 2013/11/26 09:58:48 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/collect/RDA/DCextra.ctl,v 1.4 2013/11/26 09:58:48 RDA Exp $
#
# Change History
# 20131126  MSC  Improve the documentation.

=head1 NAME

RDA:DCextra - Collects User Defined Data

=head1 DESCRIPTION

This module collects user-defined operating system commands and files. RDA
provides a command-line user interface for managing its content. It includes
following functionality:

Adds extra operating system commands for collecting data. The report title is
specified as the first argument.

  <rda> -XExtra add cmd <title> <command> ...

Adds extra files to a standard RDA data collection.

You can specify additional files explicitly or search in directories by
patterns. RDA sorts resulting files and discards duplicates. It collects the
last lines of log files only. The C<EXTRA_TAIL> setting controls the number of
log lines.

  <rda> -XExtra add files <file> ...

  <rda> -XExtra add dir <dir> <pattern> <options>

Files and directories can contain references to other settings, such as
C<${name}> or C<${name:default}>. Such values should be quoted to avoid shell
substitutions. Relative paths are evaluated from the RDA working directory,
where the collector definition is stored. Regular expressions are used in
patterns. The valid search options are as follows:

=over 6

=item B<  'i'>

Ignores case distinctions in both the pattern and the results.

=item B<  'r'>

Searches files recursively under each subdirectory. To avoid loops in the
directory structure, the recursion level is limited to 8.

=item B<  'v'>

Inverts the sense of matching to select non-matching files.

=back

For instance,

  <rda> -XExtra add dir '${CFG.D_RDA}' '\.p[lm]' ir

This collects all Perl scripts and packages used by RDA.

It is possible to collect binary files as follows:

  <rda> -XExtra add data <file> ...

The list of extra collection requests can be obtained as follows:

  <rda> -XExtra list

Extra elements can be removed selectively from the list as follows:

  <rda> -XExtra delete <pos> ...

E<lt>posE<gt> represents the position of the element in the
list. Alternatively, the list can be cleared completely by running the
following command:

  <rda> -XExtra delete -a

Collected information is regrouped under C<Extra Commands>, C<Extra Files>, and
<Extra Binary Files>.

=cut

echo tput('bold'),'Processing RDA.EXTRA module ...',tput('off')

# Initialization
var $TAIL = ${N_TAIL}

# Load the common macros
run RDA:library()

# Collect the extra commands
pretoc '1:Extra Commands'
var $cnt = 0
loop $rec (@{T_CMD})
{var ($ttl,@cmd) = @{$rec}
 var $cmd = join(' ',map(@cmd,code(quote(determine(last)))))
 report concat('cmd',$cnt)
 prefix
 {write '---+ ',$ttl
  write '---## Using: ',encode($cmd)
 }
 call writeCommand($cmd)
 if isCreated(true)
 {toc '2:[[',getFile(),'][rda_report][',$ttl,']]'
  incr $cnt
 }
}
if isTocCreated(true)
 pretoc '%SPLIT%'

# Get the file list
var @fil = (map(@{T_FIL},code(catFile(determine(last)))))
loop $rec (@{T_DIR})
{var ($dir,@arg) = @{$rec}
 call push(@fil,grepDir(catDir(determine($dir)),@arg))
}

# Collect the extra elements
pretoc '1:Extra Files'
call sort_files(2,$TAIL,@fil)
if isTocCreated(true)
 pretoc '%SPLIT%'

# Collect the binary files
pretoc '1:Extra Binary Files'
loop $fil (@{T_DAT})
{if ?testFile('r',$fil = catFile(determine($fil)))
  var $dat{dirname($fil),basename($fil)} = $fil
}
loop $grp (keys(%dat))
{toc '2:',encode(addSymbol($grp)),' '
 loop $nam (keys($dat{$grp}))
 {data concat('dat','_',$nam,'.dat')
  if writeData($dat{$grp,$nam})
   toc '3:[[',getFile(),'][rda_report][',encode($nam),']]'
 }
}

=head1 SEE ALSO

L<SAMPLE:DCextra|collect::SAMPLE:DCextra>,
L<RDA:library|collect::RDA:library>

=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