**** dbfilter.pl 1.7 -- parse db files ****
                            Goetz Pfeiffer 2014

Syntax:
  dbfilter.pl {options} [file1] [file2...]

  options:

    -h: help
    --summary: give a summary of the script

  specify the type of output:

    -i dump internal hash structure
    -r print results in db-file format (default)
    -s --short print results, one line per record
    -l just list the names of the matching records

  remove/filter records:
    --skip_empty_records: records that have no fields (due to
       filtering options that remove fields) are not printed

  remove/filter fields:
    --fields --FIELDS [field1,field2...]
      print only these fields

    -e --empty remove empty fields

    -E --rm-capfast-defaults
      remove fields that have still their capfast default value.
      CAUTION: used together with "-v" or "--fields" this option
      may remove the very fields you are looking for.

  regular expressions:
    [regexp] stands for a perl regular expression. A leading '!'
    means that the filter is inverted ('do not match'). The regexp
    may be enclosed in '/' characters, but the may be omitted.

  special options:

    --percent [+-number]
      keep the first or last n percent of all records
      if number is negative, filter the LAST n percent of all
      records, otherwise filter the FIRST n percent of all records

    --unresolved-variables
      List all unresolved variables like $(VARNAME) in the db file.
      This option can be combined with "-r", in this case
      all the contents of the shown records are printed in
      db-file format. With "--db" just the records in db format
      are printed.

    --unresolved-links {verbosity}
      Try to find unresolved links in the db-file.
      list all links that cannot be resolved within the
      db file. Currently the followings list of fields is expected to
      contain links:
      DOL,DOL1,DOL2,DOL3,DOL4,DOL5,DOL6,DOL7,DOL8,DOL9,DOLA,FLNK,INP,INPA,INPB,INPC,INPD,INPE,INPF,INPG,INPH,INPI,INPJ,INPK,INPL,INPM,INPN,INPO,INPP,INPQ,INPR,INPS,INPT,INPU,LNK1
      LNK2,LNK3,LNK4,LNK5,LNK6,LNK7,LNK8,LNK9,LNKA,OUT,OUTA,OUTB,OUTC,OUTD,OUTE,OUTF,OUTG,OUTH,OUTI,OUTJ,OUTK,OUTL,OUTM,OUTN,OUTO,OUTP,OUTQ,OUTR,OUTS,OUTT,OUTU,SDIS,SELL,SUBL,TSEL
      All values that seem to be a number or an empty string are ignored

      verbosity may be a number between 0 and 2.
      0   : just list the link values (the default)
      1   : list record names and link values
      2   : print a list of record names, then a list of
            record names and link values

      This option can be combined with "-r", in this case
      all the contents of the shown records are printed in
      db-file format. With "--db" just the records in db format
      are printed.

    --record-references -R [regexp{,regexp2}]
      list which record (whose name matches regexp) is connected
      to which other record. regexp may be "all" or "//" in which
      case all records that are connected to other records are
      shown.

      Effects of [regexp2]:

      If given, all dependencies must match this regular expression.
      Dependencies that to not match are not shown. 
      With option "--rec" (see below) records that do not match are not
      followed. Note that this may be an inverse regular expression (see
      "regular expressions:" further above). 

      Effects of other options:

      -r  : additionally show all records in db-file format
      -l  : just list the record names
      --ll: list record names and dependent record names
      --restrict :
            show only dependencies that are also present in the list of
            records. The restricts the shown dependencies if a regexp (see
            above) or option --name-file is given.
      --db: only show records in db-file format, do not show dependency
            details.
      --dot :
            produce a graphviz file. Use for example 
              dbfilter.pl {options...} --dot | dot -Tpdf > plot.pdf 
            to create a pdf file with a dependency plot.
      --extended :
            use a more verbose format for the report
      --rec [distance]: recursively look for connected records up to
            [distance]. A direct connection has distance 1. 

      recipe to explore connections to a record, start with 
        echo RECORDNAME > recs
        # loop
        dbfilter -e DBFILE -R ALL --name-file recs --ll | \
            grep -v EXPRESSION | tee recs.tmp
        # evaluate the results, adapt EXPRESSION
        # if results are good, copy:
        cp recs.tmp recs
        # go to "loop"
     

    --recursive --rec [distance]
      this option can be used together with --record-references.
      no specifies the maximum path length that is allowed for
      indirectly connected records in order to be printed.

    --dot
      this option can be used with --record-references. It produces an output
      suitable for graphviz. 

    --rm-prefix [PREFIX]
      Remove PREFIX in all record names in all reports.

    --allow_double -A : allow double record names
      (for debugging faulty databases)

    --single -S : forbid double record names
      (for debugging faulty databases)

    --lowcal {filters}
      print records with DTYP=lowcal and decode
      the CAN link. Record names and can-link properties are
      printed in a table format.
      The optional  parameter is comma-separated a
      list in the form
        name=regexp
      where name is a property of the CAN link and regexp is
      a perl regular expression. Note that  is actually
      the field-name of the canlink-hash as defined in
      the perl-module canlink.pm (see "man canlink").
      Among others, the following field names are recognized:
        dir          : either "INP" or "OUT", the type of the record
        srv,server   : the server-type, "1" for server, "0" for client
                       NOTE: you may match for "1" or "0" in your
                       regexp or the string printed in the table.
        mul, multi   : the multiplex type, "1" for multiplex vars, "0" else
                       NOTE: you may match for "1" or "0" in your
                       regexp or the string printed in the table.
        rw,access    : the type of the CAL variable (r,w or rw)
        arr,array    : array type, 1 for array variables, 0 else
                       NOTE: you may match for "1" or "0" in your
                       regexp or the string printed in the table.
        s,signed     : the signed type, ("1" for signed, "0" for unsigend)
                       NOTE: you may match for "1" or "0" in your
                       regexp or the string printed in the table.
        type         : the variable type (zero,string,char,short,mid,long)
        len,length,l : the length of the CAN object
        prt,port,p   : the port number
        in,in_cob    : the CAN object ID of the IN-object
        out,out_cob  : the CAN object ID of the OUT-object
        mplx,mux,multiplexor: the value of the multiplexor
        inh,inhibit  : the inhibit-time
        tmo,timeout  : the timeout-value
        asz,arraysize: the arraysize

    --Lowcal {filters}
      identical to --lowcal except that the record
      names are in the last, not in the first column

    --sdo {options}
      print records with DTYP=SDO and decode
      the CAN link. Record names and can-link properties are
      printed in a table format
      The optional  parameter is comma-separated a
      list in the form
        name=value
      currently known options are:
        hex          : when not 1, print everything in decimal
                       when 1, print the index, subindex, in-cob
                       and out-cob in hex

    --Sdo {options}
      identical to --sdo except that the record
      names are in the last, not in the first column

   filter info fields:
    --infovalue [regexp]
      process only records where any info value matches a regular expression.
    --info [infoname,regexp]|[infoname]
      process only records where an infoname is defined. If regexp is omitted
      just test for the existence of that info name. If regexp is defined,
      process only records where for the given info name the info value matches
      the given regexp.

   filter field values:

    --value [regexp]
      print a list of all fields in records where the field-value matches a
      regular expression,

    -v [regexp]
      filter records where at least one field matches the given regular
      expression

    --field [field,regexp]|[field]
      process only records where field matches regexp  if regexp is omitted
      just test for the existence of that field if field is a perl-regular
      expression starting enclosed in '//' it is treated as a regular
      expression

    --NAME|--name|-n [regexp]
      filter records whose name match the given regular expression

    --NOTNAME|--notname [regexp]
      same as above but filter records whose names DO NOT match the regular
      expression

    --name-file [file]
      filter records that are listed in the given file

    --notname-file [file]
      filter records that are NOT listed in the given file

    --DTYP [regexp] : filter DTYP field

    --TYPE|-t [regexp] : filter record type

    -T : add record type to record names with --lowcal option
    
    -X : extended format for --record-references

    if no file is given dbfilter.pl reads from standard-input