man > join-dctrl(1)

join-dctrl(1)                          General Commands Manual                         join-dctrl(1)

NAME
       join-dctrl - perform relational join on data in dctrl format

SYNOPSIS
       join-dctrl [ options ] filename filename

       join-dctrl --version

       join-dctrl --help

DESCRIPTION
       join-dctrl  performs  a  relational join operation on data given to it in Debian control file
       format.

       A join field must be specified using either the switches -1 and -2 or the switch -j.  Concep‐
       tually, the program creates all ordered pairs of records that  can  be  formed  by  having  a
       record  from the first file as the first member of the pair and having a record from the sec‐
       ond file as the second member of the pair; and then it deletes all such pairs where the  join
       fields  are not equal.  Effectively, each of the input files is treated as a relational data‐
       base table.

       Every input file must be in ascending order on its join field; this  allows  the  program  to
       work fast.  The sort-dctrl(1) program can be used to make it so.

OPTIONS
       -1 field, --1st-join-field=field
              Specify the join field of the first input file.

       -2 field, --2nd-join-field=field
              Specify the join field of the second input file.

       -j field, --join-field=field
              Specify a common join field for all files.

       -a fileno, --unpairable-from=fileno
              Specify  that  unmatched paragraphs from the first (if 1 is given) or the second (if 2
              is given) file are printed.

       -o fieldspec, --output-fields=fieldspec
              Specify which fields are included in the output.  Fields are separated by commas (more
              than one -o option can  be  used,  too).   Each  field  is  specified  in  the  format
              fileno.field  in  which  fileno is the ordinal number of the input file from which the
              field is drawn (either 1 or 2), and field gives the name of the field to  use.   As  a
              special  case,  simple  0  can  be used instead of fileno.field to refer to the common
              value of the join fields.

              The name of the field (not including the file number) is used in  the  output  as  the
              name  of the field.  However, a different name for output purposes can be specified by
              suffixing the field specification by a colon and the preferred visible name.

              For example, the option -o 0,1.Version:Old-Version,2.Version specifies that the  first
              field  in  any output record should be the join field, the second field should be Old-
              Version drawing its data from the Version field of the first input file, and the third
              field should be Version drawing its data from the field with the same name in the sec‐
              ond input file, and these are the only fields in an output record.

              If no -o option is given, all fields of all the records being joined are  included  in
              the output.

       -l level, --errorlevel=level
              Set  log  level  to level.  level is one of fatal, important, informational and debug,
              but the last may not be available, depending on the compile-time options.  These cate‐
              gories are given here in order; every message that is emitted when fatal is in effect,
              will be emitted in the important error level, and so on. The default is important.

       -V, --version
              Print out version information.

       -C, --copying
              Print out the copyright license.  This produces much output; be sure  to  redirect  or
              pipe it somewhere (such as your favourite pager).

       -h, --help
              Print out a help summary.

OPERANDS
       join-dctrl  will treat each file named on the command line as a relational database table.  A
       file called - represents the program's standard input stream.  Currently, exactly  two  files
       must be named.

STDIN
       The standard input stream may be used as input as specified above in the OPERANDS section.

INPUT FILES
       All input to join-dctrl is in the format of a Debian control file.

       A  Debian control (dctrl) file is a semistructured single-table database stored in a machine-
       parseable text file.  Such a database consists of a set of records; each record is a  mapping
       from  field  names  to field content.  Textually, records are separated by empty lines, while
       each field is encoded as one or more nonempty lines inside a record.  A field starts with its
       name, followed by a colon, followed by the field content.  The colon must reside on the first
       line of the field, and the first line must start with no whitespace.   Subsequent  lines,  in
       contrast, always start with linear whitespace (one or more space or tab characters).

       Each input file must be in the ascending order of its join field.

ENVIRONMENT VARIABLES
       The  standard  locale environment, specifically its character set setting, affects the inter‐
       pretation of input and output as character streams.

ASYNCHRONOUS EVENTS
       Standard UNIX signals have their usual meaning.

STDOUT
       All output is sent to the standard output stream.  The output is in the format  of  a  Debian
       control  file, described above in the INPUT FILES section.  The output will be in the ascend‐
       ing order of the join field, if that field is included in the output.

OUTPUT FILES
       There are no output files.

EXIT STATUS
       This utility exits with 0 when successful.  It uses a nonzero exit code  inconsistently  when
       an error is noticed (this is a bug).

CONSEQUENCES OF ERRORS
       In  case of errors in the input, the output will be partially or completely garbage.  In case
       of errors in invocation, the program will refuse to function.

EXAMPLES
       Suppose that a file containing data about binary packages for  the  AMD64  architecture  con‐
       tained  in  the  Debian  squeeze (6.0) release, section main, is in the current directory and
       named Packages.  Suppose that we are currently on a Debian system.  Suppose further that  the
       current  directory  does not contain files named stat and pkg.  The following commands gives,
       for each package currently installed and available in Debian squeeze (6.0), its currently in‐
       stalled version (as Old-Version) and the version in squeeze (as New-Version):
       $ sort-dctrl -kPackage /var/lib/dpkg/status > stat
       $ sort-dctrl -kPackage Packages > pkg
       $ join-dctrl -j Package \
         -o 0,1.Version:Old-Version,2.Version:New-Version \
         stat pkg

AUTHOR
       The join-dctrl program and this manual page were written by Antti-Juhani Kaijanaho.

SEE ALSO
       grep-dctrl(1), sort-dctrl(1), tbl-dctrl(1)


                                                                                       join-dctrl(1)