XDR-based I/O is supported: DBin automatically generates the filters and associated code necessary for XDR I/O on databases and data structures.
In a single-language program environment DBin is useful to maintain databases and data structures in an organized, easily transportable, self-documented way, with much tedious coding of I/O routines, include files, XDR filters, and so on eliminated by DBin's automatic code generation.
It is, however, in multi-language environments -- programs which either support coding in multiple languages or are migrating between languages (most commonly, from Fortran to C++) -- that DBin's utility is greatest. Without DBin such an environment can present a maintenance nightmare requiring redundant coding of Fortran and C/C++ I/O codes, careful maintenance of consistency between the Fortran and C/C++ data structures coded into the header files, multiple coding changes in multiple languages when a data structure or database object changes, etc. With DBin, the coding overhead remains the same as for a single language: zero. DBin makes a multiple language environment much more practical and maintainable.
DBin maps the Fortran and C databases/data structures onto the same memory, so that inter-language data sharing concerns are eliminated and data can be accessed from either language in a transparent way.
The DBin program is a lex program that runs on any Unix platform. Auxiliary material for DBin (mostly parsers) is in Fortran and C.
The databases and data structures generated by DBin are implemented using conventional C structures on the C side and VMS-style Fortran structures on the Fortran side. A Fortran 90 option is under consideration. If only a Fortran 90 compiler is available, a VMS to Fortran 90 structure syntax converter is available from the author and can be run on DBin's output to turn it into Fortran 90.
foo (using the database
directive; see the reference section).
foo_read.F
foo_init.F
foo_db.inc
incname directive is used to direct
header material to one or more files with user-defined
names rather than the default behaviour of everything being
written to this file.
fooRead.c
fooInit.c
foo_db.h
fooXDR.c
fooXDRall.c
fooXDRinc.h
fooXDRmgr.c
fooGUI.h
The other object type is the template, which can be
multiply instantiated (implemented as an array of C structures
in the code). Data values cannot be declared within the template
definition, because multiple instantiations can exist. Rather,
instantiations are created and their data values set using the
make directive.
In the data structure definition application, the make
directive is not used, because no explicit instantiations
are declared in this case.
Within structures and templates, the standard data types are available: integer, real, double precision, and character string, with keywords int, real, double, char. Arrays are permitted; singly dimensioned only, for the database application. Arrays of higher dimension are permitted in data structure definitions. Nested templates are permitted in data structure definitions. They are not permitted in databases because of the complexity it would introduce to declaring the data values.
keyword name(dimension) [names and values]
If a declaration has an associated dimension, it always
appears as a dimension on the second token.
template one
int i
end template
make one 4 ! OK
make one 5 ! OK
...
template two
real r
end template
make two 6. ! OK
make two 27.4 ! OK
make one 7 ! illegal line. Intervening template.
include directive is available to include
other files.
end directive is a required final termination of the
full definition file.
make directive.
By convention, DBin database files have file type .db .
The basic structure of a database file, with examples of both structures and templates, is as follows.
------------------------------------------------------------------------
database mydb 0100 ! name and version number
incname pars ! specify pars.h, pars.inc as destination
! for header material
structure pars
char name "An example"
real rad 320.
real zlen 400.
int nphi 36
real origin(3) 10. 20. 30.
end structure
incname plane ! new destination: plane.h, plane.inc
template plane
char name
int index
real normal(3)
real point(3)
end template
make plane "xy" 1 0. 0. 1. 0. 0. 0.
make plane "yz" 2 1. 0. 0. 0. 0. 0.
include otherstuff.db ! include material in another file
end
------------------------------------------------------------------------
make) or DBin structures
(structure). The declaration mode internal
must appear as the first line in the DBin file to indicate
the application mode is generation of program-internal data
structures rather than a database (the default usage mode).
By convention, DBin data structure definition files have file type .dst .
Because DBin does not have the job of handling actual data in this application, DBin's rules on allowed declarations are more liberal. The following are permitted in data structure definitions, but not in the database application:
dimension directive. eg.
dimension nmxsiz
template foo
real array(nmxsiz)
...
end template
nest directive. eg.
template inner
int i
end template
template outer
real r
nest inner(5)
end template
------------------------------------------------------------------------
mode internal ! usage mode = data structure def. Must be 1st line.
database mcfdat 0100
!
! Definition of data structures used internal to MCFast
!
!******************** hit_trk ********************
incname trk_channel_struct ! include file for structure declaration
template trk_channel
int devtype !Type of device
int devnum !Device # of this type
int devlayer !Layer #
int devwid(3) !Info within layer
end template
incname hit_trk_struct ! include file for structure declaration
provide trk_channel_struct ! provide the channel declaration
template hit_trk
int hep !Position of track in /HEPEVT/ list
int trace !Position of hit in trace list
nest trk_channel chan !Device info
double pos(3) !Position of wire
double dircos(3) !Dir. cosines
end template
incname hit_trk ! instantiations go to a separate include file
provide hit_trk_struct ! provide the structure declaration
dimension hit_trk_max 10000 ! define the dimension parameter
record hit_trk(hit_trk_max) ! create an array: hit_trk
incname another_hit_trk ! create another include file
provide hit_trk_struct ! provide the structure declaration
dimension hit2_trk_max 10000 ! define the dimension parameter
record hit_trk(hit2_trk_max) hit2_trk ! create an array, hit2_trk
end
------------------------------------------------------------------------
dbin dbfile.db [-help] [-list] # database application or dbin dstfile.dst [-help] [-list] # data structure def'n -help: list available command line options -list: debug listing as DBin executes
dbin.lex.
Lex is a standard unix utility used for
developing parsers. Auxiliary code includes parser code for
database reading in Fortran and C, dbinf.F and dbinc.c.
mode internal
The mode directive is used to change the mode of operation of the program from the default database mode to something else. One other mode is presently defined: internal mode, in which DBin is used to define a program's internal data structures. If present, it must appear as the first line of the DBin file as above.
database db_name version
The database directive names the database; it sets the name used in filenames generated by DBin. It also defines a version number, used to ensure that DBin-generated code is used only with compatible database files (ie. with matching version number).
The database directive must appear, and should be the first directive in the DBin file (unless preceded by the mode directive).
include file_name
The include directive permits the in-line inclusion of DBin statements from another file (just like the cpp #include command). The file name will be looked for in the same directory as the parent DBin file, unless the name includes a relative or absolute path name.
incname file_name_root
The incname directive reroutes include file code generated by DBin to a file of the specified name, rather than to DBin's master include file (the master include file instead uses #include to include these user-specified files). Using this directive the user has complete control over the partitioning of include file code among files.
The specified file name should not contain an extension. Appropriate extensions (.inc,.h) will be added by DBin for the Fortran and C/C++ versions of the file.
incname muon ! header code directed to muon.inc, muon.h [...DBin statements...] incname ecal ! header code directed to ecal.inc, ecal.h
provide include_file_root
The provide directive inserts an #include
statement for the named include file into the current header file.
The file type should not be given. File types of .inc
and .h will be added for the Fortran and C includes
respectively.
provide muon ! inserts '#include "muon.[inc,h]"' into Fortran,C header
end
The end statement signals the end of the dbin file.
It must be present.
Note that included files should not contain an end statement.
real array(5).
In databases, only one dimensional arrays with an explicit numeric
dimension are allowed. In structure definitions, multi-dimensional
arrays are allowed, comma delineated. Also, dimensions can be
given in terms of constants declared (previously) with the
dimension directive.
In structure definitions (ie. only in databases), a type declaration is followed by the data for the parameter. A single value if undimensioned, all N values if dimensioned. In all other contexts (ie. templates, in either database or data structure def'n applications), the type declaration does not include data.
Arrayed types can be followed by the keyword variable
to indicate that it is a variable size array; that is, its declared
size is an upper bound on the number of elements actually used.
The previous element in the template declaration should be an
integer, and is interpreted as the number of elements actually used.
eg.
real hits(100) variable
integer name[(dimension)] [variable]
real name[(dimension)] [variable]
double name[(dimension)] [variable]
char name[(dimension)] [variable]
material name[(dimension)] [variable]
Identical to char. Flags the string as of a special
type, one specifying the name of a material. Provokes special
treatment eg. in GUI menu code.
dimension name value
Acts like a PARAMETER statement in Fortran or static const
statement in C (these are how it is implemented).
dimension maxsz 30
index prefix name1 name2 name3 ...
Sets up an array of index mnemonics useful for referencing elements
of arrays with mnemonics. Handles the 0/1 array start discrepancy
between Fortran and C such that the mnemonic in the given language
refers to the same element. The example below defines
ix_x, ix_y, ix_z, ix_px, ... to be mnemonics pointing to
the 1st (0th), 2nd (1st), etc. element in an array in Fortran (C).
index ix x y z px py pz e
structure name
Start a structure declaration. Structure is terminated by
end structure.
template name
Start a template declaration. Template is terminated by
end template.
record template_name[(dimension)] [alternate_name]
Data structure definition mode only. Create an instantiation of a declared template, ie. create an object in memory. Dimension is optional. By default (no third parameter), name of the created structure as the template name. The third parameter is used to specify an alternate name.
record fourvec(3) products ! == record /fourvec_s/ products(3) in Fortran
child template_name
Databases only. Appears in a template declaration. Declares that the object has a child array of the stated type at the current point in the object. The preceding element should be an integer (if not another child) which is interpreted as the number of child elements in use.
nest template_name[dimension] [variable]
Data structure definitions only. Equivalent to child. In the context of a data structure definition, the effect of the nest directive is to insert a nested structure in the declared structure.
parent parent_template_name
Database definitions only. Appears in template definitions.
If the template is a child of another template, the parent
directive should be inserted in the child template definition (anywhere)
to flag that the template has the named parent.
make template_name template_parameters
Create an instantiation of a template. Template instantiations must follow the template definition with no intervening template or structure definitions. That is, template instantiations must be grouped together and appear right after the template definition.
template point real x real y real z end template make point 1. 2. 3.
Not presently used. Reserved to re-implement the old style make
command that included a name for each instantiation.
'index' assigns 1,2,3,4... (C: 0,1,2,3...) to the symbols. Token following 'index'
! is a prefix to attach to each subsequent symbol, eg
! 'index mu px py pz' defines mu_px=1, mu_py=2, mu_pz=3