NAME

parse_db - a Perl module to parse epics db-files

SYNOPSIS

use parse_db;
undef $/;

my $st= <>;

my $r_records= parse_db::parse($st);
parse_db::dump($r_records);

DESCRIPTION

Preface

This module contains a parser function for epics DB-files. The contents of the db-file are returned in a perl hash-structure that can then be used for further evaluation.

Implemented Functions:

parse()
```
my $r_records= parse_db::parse($st,$filename,$mode);
```
This function parses a given scalar variable that must contain a complete db-file. It returns a perl data structure containing the parsed data. The way the data structure is created depends on the $mode parameter. See also the chapter "data structures" for some examples.

These are the possible values of $mode:

"standard"

parse returns a reference to a db hash. This hash maps record names to references of record hashes.

"array"

parse returns a reference to a db array. This array contains references to record hashes.

"extended"

parse returns a reference to an extended db hash. This hash contains a db hash, an alias map and a real record hash.

For backwards compability, the following values for $mode are also allowed:

undef

like mode "standard"

""

like mode "standard"

"asArray"

like mode "array"
parse_file()
```
my $r_records= parse_db::parse_file($filename,$mode);
```
This function parses the contents of the given file. If parameter $filename is undef it tries to read form STDIN. If parameter $filename is a list reference, the function parses the contents of all files in the list. If the file cannot be opened, it dies with an appropriate error message. For the meaning of parameter $mode and the format of the returned data see description of function "parse".
create_record()
```
parse_db::create_record($record_name,$r_records)
```
Print the contents of the given record in the standard db format to the screen. The second parameter must be a reference to a record hash.
create_aliases()
```
parse_db::create_aliases($r_alias_hash)
```
Print alias statements from an alias hash to the screen. The parameter must be a reference to an alias hash.
create()
```
parse_db::create($r_records,$r_record_list)
```
Print the contents of all records in the standard db format to the screen. The first parameter must be a reference to a db hash. The parameter $r_record_list is optional. The default is that records are printed in alphabetical order. If the second parameter is given, only records from this list and in this order are printed.
dump()
```
parse_db::dump($r_records)
```
Dumps a db hash with Data::Dumper. The parameter must be a reference to a db hash.
dump_real()
```
parse_db::dump_real($r_ext_recs)
```
Dumps the real records and the aliases from an extended db hash with Data::Dumper. The parameter must be a reference to an extended db hash.
handle_double_names()
```
parse_db::handle_double_names($mode)
```
Determine how double record names are treated. The following modes are known:

"0"

With $mode=0, a warning is printed and the second definition of the record is ignored.

"1"

With $mode=1 (the default), the second record definition is merged with the first definition. Definitions of the same fields that come later in the file overwrite earlier definitions. This is the standard behaviour when the IOC loads a database file.

"2"

With $mode=2, the parse-module handles double record-names by appending a number of each double name that is encountered. This feature may be used to track down errors in databases that were generated with double record names without the intention to do so.

data structures

field hash

A field hash maps field names to field values, both are perl strings. Here is an example:

(
  'PRIO' => 'LOW',
  'DESC' => 'subroutine',
  'HIGH' => ''
)

info hash

An info hash maps "info" names to "info" values. This is the information from the "info" statement in a db file. Here is an example:

(
  'Author'   => 'John Doe',
  'Revision' => '1.2',
  'Notes'    => 'not yet tested'
)

record hash

A record hash contains all information about a single record. It is part of the data structure created by the functions parse and parse_file. Depending on the "mode" parameter of these functions, the record hash may be slightly different.

It always includes a key "FIELDS" that maps to a reference of a field hash and a key "TYPE" that maps to a string that is the record type.

When parse or parse_file were called with mode "array", the hash also includes a key "NAME" that maps to the record name and a key "ORDERDFIELDS" that maps to a reference of a list of field names in the order they were found in the db file. When parse or parse_file were is called with mode "extended" the record includes a field "INFO" that maps to a reference to an info hash.

Here are some examples,

created in mode "standard":

(
  'TYPE'  => 'sub',
  'FIELDS'=> { 'PRIO' => 'LOW',
               'DESC' => 'subroutine',
               'HIGH' => ''
             }
)

created in mode "array":

(
  'NAME'  => 'UE52ID5R:BaseCmdHome',
  'TYPE'  => 'sub',
  'FIELDS'=> {
               'PRIO' => 'LOW',
               'DESC' => 'subroutine',
               'HIGH' => ''
             },
  'ORDERDFIELDS' => [ 'DESC', 'PRIO', 'HIGH' ]
)

created in mode "extended":

(
  'TYPE'  => 'sub',
  'INFO'  => {
               'Author'   => 'John Doe',
               'Revision' => '1.2',
               'Notes'    => 'not yet tested'
             },
  'FIELDS'=> {
               'PRIO' => 'LOW',
               'DESC' => 'subroutine',
               'HIGH' => ''
             }
)

db hash

A db hash is created when function "parse" is called in mode "standard". It maps record names to references of record hashes. Here is an example:

(
  'UE52ID5R:BaseCmdHome' =>
     { 'TYPE'  => 'sub',
       'FIELDS'=> { 'PRIO' => 'LOW',
                    'DESC' => 'subroutine',
                    'HIGH' => ''
                  }
     }
  'UE52ID5R:BaseStatAStat' =>
     { 'TYPE'  => 'sub',
       'FIELDS'=> { 'PRIO' => 'HIGH',
                    'DESC' => 'subroutine',
                    'HIGH' => '1'
                  }
     }
)

db array

A db array is created when function "parse" is called in mode "array". It is a list of references to record hashes. Here is an example:

[ {
    'NAME'  => 'UE52ID5R:BaseCmdHome',
    'TYPE'  => 'sub',
    'FIELDS'=> {
                 'PRIO' => 'LOW',
                 'DESC' => 'subroutine',
                 'HIGH' => ''
               },
    'ORDERDFIELDS' => [ 'DESC', 'PRIO', 'HIGH' ]
  },
  {
    'NAME'  => 'UE52ID5R:BaseStatAStat',
    'TYPE'  => 'sub',
    'FIELDS'=> {
                 'PRIO' => 'HIGH',
                 'DESC' => 'subroutine',
                 'HIGH' => '1'
               },
    'ORDERDFIELDS' => [ 'DESC', 'PRIO', 'HIGH' ]
  },

alias map

This is a hash that maps alias names of records to real names of records. There is an example:

(
  'HomeRecord' => 'UE52ID5R:BaseCmdHome',
  'StatRecord' => 'UE52ID5R:BaseStatAStat,
)

real record hash

This is a hash that maps real names of records to record hashes. Here is an example:

(
  'UE52ID5R:BaseCmdHome' =>
     { 'TYPE'  => 'sub',
       'FIELDS'=> { 'PRIO' => 'LOW',
                    'DESC' => 'subroutine',
                    'HIGH' => ''
                  }
     }
  'UE52ID5R:BaseStatAStat' =>
     { 'TYPE'  => 'sub',
       'FIELDS'=> { 'PRIO' => 'HIGH',
                    'DESC' => 'subroutine',
                    'HIGH' => '1'
                  }
     }
)

extended db hash

A db hash contains a db hash, an alias map and a real record hash. Note that aliases to record names are resolver in the db hash, meaning that this hash may contain keys that map to the same record hash. The well known Data::Dumper module doesn't handle these cases well (at least in my opinion), here is a quote from the Data::Dumper documentation:

Any references that are the same as one of those passed in will 
be named $VARn (where n is a numeric suffix), and other duplicate 
references to substructures within $VARn will be appropriately 
labeled using arrow notation.

Here is an example (not created by Data::Dumper) for a db hash:

(
  'dbhash' => {
                'UE52ID5R:BaseCmdHome' =>
                   { 'TYPE'  => 'sub',
                     'FIELDS'=> { 'PRIO' => 'LOW',
                                  'DESC' => 'subroutine',
                                  'HIGH' => ''
                                }
                   }
                'HomeRecord' =>
                   { 'TYPE'  => 'sub',
                     'FIELDS'=> { 'PRIO' => 'LOW',
                                  'DESC' => 'subroutine',
                                  'HIGH' => ''
                                }
                   }
                'UE52ID5R:BaseStatAStat' =>
                   { 'TYPE'  => 'sub',
                     'FIELDS'=> { 'PRIO' => 'HIGH',
                                  'DESC' => 'subroutine',
                                  'HIGH' => '1'
                                }
                   }
                'StatRecord' =>
                   { 'TYPE'  => 'sub',
                     'FIELDS'=> { 'PRIO' => 'HIGH',
                                  'DESC' => 'subroutine',
                                  'HIGH' => '1'
                                }
                   }
              },
  'aliasmap' => {
                  'HomeRecord' => 'UE52ID5R:BaseCmdHome',
                  'StatRecord' => 'UE52ID5R:BaseStatAStat,
                },
  'realrecords' =>
              {
                'UE52ID5R:BaseCmdHome' =>
                   { 'TYPE'  => 'sub',
                     'FIELDS'=> { 'PRIO' => 'LOW',
                                  'DESC' => 'subroutine',
                                  'HIGH' => ''
                                }
                   }
                'UE52ID5R:BaseStatAStat' =>
                   { 'TYPE'  => 'sub',
                     'FIELDS'=> { 'PRIO' => 'HIGH',
                                  'DESC' => 'subroutine',
                                  'HIGH' => '1'
                                }
                   }
              },
)

AUTHOR

Goetz Pfeiffer, Goetz.Pfeiffer@helmholtz-berlin.de