The report Command

The report command is used to interact with report objects. The purpose of report objects is to generate reports in PDF or HTML format from structure data. PDF files can contain a hidden structure-searchable database with the structure and rendered or auxiliary data items.

The format of a report is defined by an XML style file, which describes a record box with arbitrary positioning of data or image fields. These record boxes can be stacked horizontally and vertically on report pages. The XML style file is embedded in PDF s written by report objects, so these files can contain both human-readable and computer-readable data content plus the layout information used to generate the file. It is for example possible to re-render content with a different style file, or use the style file extracted from a template file to render additional documents in exactly the same style.

The unit for describing report object placements are 72 DPI pixels. The are converted and/or scaled to the selected output format.

report create

report create ?attribute value?...
report create dict

Create a new report object. Additionally, an set of attributes of the object may be defined in the same statement. The settable attributes are the same as in the report set command.

The command returns the handle or reference of the new report object.

report delete

report delete ?rhandle?...
report delete all

Delete one of more report objects which are identified by their handles or references. The second variant deletes all currently defined report objects.


report delete {*}[report list]

This command is equivalent to report delete all .

report extract

report extract rhandle pdf_filename ?mode? ?outfilenamenbase?

Extract the SQLITE database and the report style XML file from a PDF report.

The default mode is all, meaning that both the database and the formatting information is extracted, written to external files, and attached to the report object. Other supported modes are style (formatting only) and database (data only).

The final optional argument sets the base filename of the extracted SQLITE and XML style files. If it is not set, a file name is automatically generated.

The return value of the command depends on the extraction mode. In the all mode, is is a list of the respective filenames for the database and style file. In other modes, it is a single string with the specific filename.

report get

report get rhandle attribute

Query an attribute of a report object. The currently supported attributes are:

If database fields have not yet been defined on the report object, querying or setting this attribute instantiates a standard set for a structure (but not reaction) database. Additionally, all properties currently associated with a data display field in the layout are automatically added, so that every visible data value can also be read from the database.

When setting this attribute, every field sublist must contain only between one and three elements. The last two items reported are automatically deduced from the type of data to be stored. If no explicit field name is specified, the field name is copied from the first argument. If no third element is supplied, the database column has no auxiliary SQL attributes, i.e. it is not indexed, may contain multiple entries of the same value, can be NULL , and an attempt will be made to compute its value when a structure or reaction record is written and the ensemble or reaction does not currently hold a value for the property or pseudo-property of the database column.

report list

report list ?pattern?

Return the handles of all currently defined report objects. The handles may optionally be filtered by a standard Tcl string match condition.

report read

report read rhandle pdf/db/html_filename ?dataset?,?target=?)

Read data for a report from a PDF file with an embedded database, a SQLITE database with the property structure (typically extracted from a report PDF ) or a HTML file generated by the report command with embedded data.

If an existing destination dataset is specified, all read structure or reaction objects are put into that dataset. A new dataset is automatically created if the argument is omitted, specified as an empty string (including None for Python ), or as the magic name #new.

The return value is the handle or reference of the dataset holding the extracted chemistry objects.

report ref


Python -only method to get a reference of the report object from its handle.

report set

report set rhandle ?attribute value?...
report set rhandle dict
r.attribute = value
r[attribute] = value

Set attributes of the report object. The attributes are explained in the section on the report get command.


report set $rhandle stylefile „mystyle.xml“ paper A4 xblocks 2 yblocks #auto \	scale #auto

This is a typical page set-up operation. The PDF or HTML form of the report will contain 2 top-level boxes arranged horizontally, a suitable (as computed from the aspect ratio of the paper) number of vertically stacked blocks, and everything scaled so that either the horizontal or vertical extent of the block stacks, plus the border, just fit onto the selected paper, without overspill.

report subcommands

report subcommands

Return a list of all subcommands of report objects. The command does not have any parameters.

report write

report write rhandle ?filename? ?source? ?flagdict?
report write rhandle ?filename? ?source? ?flagname flagvalue?...

Write a report file from the existing report definition and a structure data source.

The file name specifies an output data file. Its type is initially inferred by the filename suffix - .pdf for PDF files, . htm or .html for HTML files, and .db or . sqlite for a raw SQLITE database. The file name can be omitted if the pdffilename attribute is set, and the output format should be PDF , or another format is set in the flags argument and the corresponding format-specific filename attribute is set. If an explicit format is specified in the flags argument, the automatic format selection from the filename is overridden. The filename can also be a directory. In that case, an automatically generated file name based on the report instance UUID is constructed and the file written to that directory. The magic output file names stdout and stderr are also recognized.

The structure data source can either be the handle or reference of a dataset with structure or reaction objects, or the handle (reference) of an open molfile structure or reaction file. If no structure object data source is specified, but there is a current SQLITE database file associated with the report object, data is read from that database.

The output flags can be from the following set:

The return value of the command is the output file name, which may have been auto-generated.