molfile add

molfile add filehandle ?objecthandle/objecthandlelist?...

f.add(objectsequence/objectref,...)

Molfile.Add(filename,objectsequence/objectref,...)

If the filehandle argument refers to an open chemistry data file, this command is indistinguishable from molfile write .

A difference only exists if the filehandle argument is a file name (or, in cased of Python , the class method is used). In that case, molfile write overwrites an existing file, while molfile add attempts to temporarily open the file for appending, as with a molfile open filename a command. If the format of the output file supports appending, the output objects are written as new records after the last existing record.

It is not possible to append to single-record file formats.

Example:

molfile add smilerecords.smi $eh

molfile append

molfile append filehandle ?property value?...

f.append({?property:value,?...})

f.append(?property,value,?...)

Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data. This is not a command to append file records. Use the molfile write command for this purpose.

The command returns the first data value.

Example:

molfile append $fh F_GAUSSIAN_JOB_PARAMS(route) “Opt=(AddRed,CalcFC)”

molfile assign

molfile assign filehandle srcproperty dstproperty

f.assign(srcproperty=,dstproperty=)

Assign property data to another property on the same ensemble. Both properties must be associated with the same object class. This process is more efficient than going through a pair of molfile get/molfile set commands, because in most cases no string or Tcl/Python script object representations of the property data need to be created.

Both source and destination properties may be addressed with field specifications. A data conversion path must exist between the data types of the involved properties. If any data conversion fails, the command fails. For example, it is possible to assign a string property to a numeric property - but only if all property values can be successfully converted to that numeric type. The reverse example case always succeeds, out-of-memory errors and similar global events excluded.

The original property data remains valid. The command variant molfile rename directly exchanges the property name without any data duplication or conversion, if that is possible. In any case, the original property data is no longer present after the execution of this command variant.

The command returns the object handle for Tcl , or object reference for Python .

molfile backspace

molfile backspace filehandle ?nrecords?

f.backspace(?records=?)

Position the file pointer backwards. If no record counter is specified, the file is backspaced by a single record. It is an error to attempt to reposition the file before the beginning of the file.

Examples:

molfile backspace $fh

molfile set $fh record [expr [molfile get $fh record]-1]

These two sample lines provide identical functionality.

The molfile backspace command is often used in combination with the molfile copy command in order to copy records with specific properties verbatim:

set eh [molfile read $fh]

if {[strucuture_passes_condition $eh]} {

	molfile backspace $fh

	molfile copy $fh $outfilehandle

}

molfile blob

molfile blob enshandle/reactionhandle/datasethandle ?attribute value?...

molfile blob enshandle/reactionhadle/datasethandle? ?attribute_dict?

Molfile.Blob(eref/xref/dref,?attribute,value?,...)

Molfile.Blob(eref/xref/dref,attribute_dict)

This is an alias of molfile string . Please refer to the section on that command for more information.

molfile close

molfile close ?filehandle? ...

molfile close all

f.close()

Molfile.Close(“all”)

Molfile.Close(mrefsequence/mref/mhandle,...)

Close one or more file handles. If the file handle corresponds to a scratch file, the file is deleted. If it corresponds to a pipe, all programs in the pipe are shut down.

If all is passed instead of a set of file handles, all currently opened structure files are closed. Standard Tcl or Python files upon which a molfile handle has been piggybacked are not affected, i.e. these language channels are flushed and remain open, while the molfile object component is closed.

It is a good idea to close files when they are no longer needed. In addition, while most file format I/O modules commit all data to disk after each record has been written, so that a clean close-down is not absolutely required, there are file formats for which the I/O module has a cleanup or finalization routine which is only called if the file is properly closed.

The command returns the number of files which were closed.

Example:

set fhandle [molfile open scratch]

molfile close $fhandle

The example closes a scratch file, which is automatically deleted from disk when it is closed.

On normal interpreter program exit, the close functions of all remaining open file handles are automatically called.

molfile copy

molfile copy filehandle ?channel? ?count? ?startrecord/startrecordlist?

f.copy(?outfile=?,?count=?,?startrecord=?)

Copy a record to a Tcl or Python file I/O channel, to a Cactvs structure file handle, or retrieve it as a byte image. No interpretation or formatting of the data in the file record(s) takes place - the data is copied verbatim, byte by byte.

If file format conversion is desired, the data items (ensembles, reactions, datasets) must be explicitly read ( molfile read command) as chemistry objects and written to another molfile opened for output in the desired format ( molfile write command). That procedure involves re-formatting and potential loss of formatting or information which was not captured by the input routine, or cannot be written by the output routine.

By default the next record after the current file pointer position is returned as a byte image. The optional parameters allow the selection of a specific start record (beginning with 1 for the first record), the copying of multiple records in one command (by default, a single record is processed), and output to alternative Tcl or Python file I/O channels or Cactvs molfile structure file handles. If an empty string, None in Python , or the value 0 are used as start record number, the file is copied from the current position. If the start record is negative, it is interpreted as offset from the current position. Therefore, passing -1 as parameter instructs the command to backspace by one record prior to copying. Not all files can be backspaced. The start record can also be specified as a record list ( Tcl ) or record sequence ( Python ). In that case, the input file pointer is positioned to every specified record in order, and from that position the selected number of records is copied. If the special record count values end or all are used, all remaining records in the input file are copied. Otherwise, if the number of available records is smaller than the requested copy count, an error results.

If the output channel argument is omitted, or set to an empty string, the record(s) are returned as a byte sequence command result. Otherwise, the data is written to the file handle the argument is connected to. For Cactvs molfile handles, the destination is the current write position of the underlying file handle. On Unix / Linux systems, writable active Tcl file or socket handles (in the form filexxx or sockxxx ) are also supported, but not on Windows. Additionally, the special output channel names stdout and stderr can be used. If output is written to a channel, and not returned as blob, the number of actually copied records is returned as the command result.

The I/O modules for some formats like SDF provide optimized fast copy routines and are thus notably faster to copy then other file formats without explicitly encoded record positions. These still need to read the file line by line and maintain a parser state, though they can avoid decoding the record contents as structures or reactions.

Example:

set eh [molfile read $fhandle]

set fhout [open “metal_compounds.sdf” w]

if {[ens atoms $eh metal exists]} {

	molfile copy $fhandle $fhout 1 [expr [molfile get $fhandle record]-1]

}

This example reads a structure from an input file, checks whether is contains a metal atom, and if yes, copies the record unchanged to an output file, which is opened as a simple Tcl text file channel in this example. The expression which forms the last parameter backspaces the input file by one record, so that the same record which was just read can be copied. A simpler solution for the same functionality is to simply pass -1 as argument. This works of course only if the input file can be repositioned backwards. i.e. normal text files are fine, standard input or a socket connection do not work.

molfile count

molfile count filehandle ?maxrecords? ?readscope?

f.count(?maxrecords=?,?readscope=?)

Molfile.Count(filename,?maxrecords=?,?readscope=?)

Count the number of records in the file.

If the file format contains an internal or external record index with information about the complete file, the answer is produced from the index, and thus is typically obtained fast. Otherwise, the file is skipped from the current position until the end, and the sum of the number of records encountered while skipping and the record index when the count started is returned. In case of files which are rewindable, the original input file pointer position is then be restored. On non-rewindable files, the file contents are consumed, and no return to the old input position is possible. For files which are opened for writing, the count usually is simply the current output position, except for those few file formats which support in-file record replacement in combination with a complete file index. In the latter case, the count is again extracted from the index.

During the record skipping part the file contents are not physically read if possible. Rather, the skip function of the responsible file format I/O module is used to scan the file effectively. After arriving at the end of the file, a full in-memory record position index has been assembled for the file, and future record selection within files which support re-positioning is fast.

The type of record boundaries counted depends on the input scope of the file. For file formats which support multiple input modes, such as for extraction of ensembles or molecules or datasets, the count is dependent on the type of object which is configured to be read. If the file input object type is changed, the in-memory record index table is discarded.

If the maxrecords parameter is specified, and is not a negative number, it is the maximum count reported. No attempt is made to position the file beyond this mark during the count process. This has no effect on future input operations - these may still proceed beyond the reported count. This option is not intended to be generally useful, but is used for example in the structure browser csbr with the -m option to enable quick inspection of a file without full scanning.

The optional readscope parameter can be used to temporarily modify the read scope under which the file is processed. It can be any of the generally recognized values (mol, ens, reaction, dataset). If the file format does not support the specified mode, its default mode is silently used. If the file is not positioned at the beginning of the data, the count reports the sum of the currently known records as perceived by the previous read scope, and the remaining file records under the new one. If these values are different, the result may only be useful under very specific circumstances. The the parameter is not set, or an empty string is passed, the currently set, or, for one-shot file operations, the default read scope, is used.

Example:

set nrecs [molfile count “thefile.sdf”]

set nrecs [molfile count “test.spl” -1 mol]

molfile dataset

molfile dataset filehandle ?filterlist?

f.dataset(?filters=?)

Return the handle of the dataset associated with the file handle. If no such dataset is set, the command returns an empty string, or None for Python . The command

molfile get $filehandle dataset

is equivalent.

This command is different from the dataset commands for ensembles, reactions or tables, where it indicates membership in a dataset. File objects cannot be a member of a dataset. This dataset association is explained in more detail in the molfile set command section.

molfile defined

molfile defined filehandle property

f.defined(property)

This command checks whether a property is defined for the structure file. This is explained in more detail in the section about property validity checking. Note that this is not a check for the presence of property data! The molfile valid command is used for this purpose.

molfile delete

molfile delete filehandle recordlist ?rebuildindex?

f.delete(records=,?rebuildindex=?)

Molfile.Delete(filename,records=,?rebuildindex=?)

Delete records from the file. The file must have been opened for writing or update, and be rewindable. In case the file is not a simple record sequence, the I/O module for its format must provide a deletion function, or the operation will fail.

The deletion record list is a single or set of record numbers in any order. They are sorted and duplicates removed before file modification commences. It is no error to specify an empty removal record list. The record numbering starts with one, and the record numbers are referring to the record numbering at the moment the command is issued. There is no need to compensate for intermediate record numbering shifts when more than one record is deleted.

The optional index rebuild parameter, a boolean value, can be set to optimize the deletion process for files in formats which maintain field index information. By default, indices are updated as part of the deletion process. In case many records are deleted, it may be more efficient to drop the indices prior to the deletions and rebuild them after the records have been removed. In order to select this alternative procedure, a true parameter value can be set. At this time, the only file format which actually can use that parameter is the bdb database file format.

In case the file is to be truncated, the molfile truncate command is usually more efficient.

This command returns the number of deleted records. It does not close or destroy the file handle, or the underlying file.

molfile dget

molfile dget filehandle propertylist ?filterset? ?parameterdict?

f.dget(property=,?filters=?,?parameters=?)

Molfile.Dget(filename,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the molfile get command. The difference between molfile get and molfile dget is that the latter does not attempt computation of property data, but rather initializes the property values to the default and return that default if the data is not yet available. For data already present, molfile get and molfile dget are equivalent.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile dup

molfile dup filehandle

f.dup()

This command duplicates a file handle. The duplicate handle or reference points to the same underlying file or other data channel, is opened in the same access mode, and positioned at the same record. Also, all file object attributes and file properties are set to identical values.

Currently, it is not possible to duplicate virtual file sets opened by a molfile lopen command.

The command returns a new file handle or reference.

molfile exists

molfile exists filehandle ?filterlist?

f.exists(?filters=?)

Molfile.Exists(mref,?filters=?)

Check whether a molfile handle is valid. The command returns 0 or 1. Optionally, the molfile may be filtered by a standard filter list, and if it does not pass the filter, it is reported as not valid.

molfile extract

molfile extract filehandle retrievallist

f.extract(retrievallist)

Extract the contents of data fields from the file, without reading full structure or reaction records if possible. This operation requires a support function in the I/O module for the file format. Generally, only formats optimized for query operations, such as the Cactvs bdb and cbs formats provide such a function in their I/O module.

This command is essentially a shortcut for a molfile scan command with an empty query condition and a propertylist retrieval mode. Please refer to that command for details about the possible contents of the retrieval list.

The result is a nested list of extracted property values, with one outer list element for every file record to the end of the file, and inner list with one element per retrieval field.

molfile filter

molfile filter filehandle filterlist

f.filter(filters)

Check whether the structure file passes a filter list. The return value is boolean 1 for success and 0 for failure.

Example:

molfile filter $fhandle $filter

molfile fullscan

molfile fullscan filehandle queryexpression ?mode? ?parameterdict?

f.fullscan(query=,?mode=?,?parameters=?)

Molfile.Fullscan(filename,query=,?mode=?,?parameters=?)

This command is the same as molfile scan , except that an automatic rewind (see molfile rewind ) is performed before the query is executed. The same effect can be achieved by setting the startposition parameter value to 1.

molfile get

molfile get filehandle propertylist ?filterset? ?parameterdict?

molfile get filehandle attribute

f.get(property=,?filters=?,?parameters=?)

f.get(attribute)

f[property/attribute]

f.property/attribute

Molfile.Get(filename,property=,?filters=?,?parameters=?)

Molfile.Get(filename,attribute)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

The molfile object possesses a rather extensive set of built-in attributes, which can be retrieved with the get command (but not its related subcommands like dget, sqlget , etc.). Most of them can also be manipulated with a set command. In addition, molfile objects can possess file-level properties. The standard prefix for these is F_ .

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

Example:

set c [molfile get $fhandle F_COMMENT]

These built-in attributes are:

• address_city
  The city part of the author contact address.
• address_country
  The country part of the author contact address, following the ISO3166 standard.
• address_state
  The state part of the author contact address. Empty if not applicable.
• address_street
  The street address part of the author contact address. Includes floor, house number, etc.
• address_zip
  The ZIP code or other applicable postal code of the author contact address.
• affiliation
  The institution the author works for.
• affiliationduns
  The DUNS registration ID of the affiliated institution. This is primarily useful for US government projects.
• affiliationurl
  The URL of the affiliated institution.
• atomlabelproperty
  The name of a property which holds data for a parallel user-defined atom numbering scheme (see writeflags / writelabels attribute) which can be output by some I/O modules. The default property is A_LABEL . The property must be associated with atoms, but is not required to be an integer, if the I/O modules supports alternative data types (i.e. for CDX / CDXML the label data in the file format is internally a string, and any different property data type is converted as necessary). This attribute has an effect only if the writelabels flag is also set in the writeflags attribute .
• author
  The author of the file, as free-form string data.
• authorization
  A service authorization URL , which might for example be presented to the user for approval of access to a resource. In the case of dropbox file access, this data is copied from the global value of the I/O module (see filex get command). For normal files, this attribute is empty, and setting it to a string value has no effect.
• authorurl
  A URL with information on the author, or an empty string if unset.
• batchsize
  The number of records in a standard processing batch. The default batch size are 10 records.
• bondlength
  The standard bond length to be used in the file. The unit is points (1/72 inch). If the value is negative (the default), the standard format-specific bond length is used. This attribute is only supported in a few graphics-oriented file formats, such as CDX or SKC files, or EMF images.
• cachesize
  The size of the record prefetch cache the file should use. Normally, the size is zero and no such cache is employed. The I/O modules for a few file formats, such as PubChem CID and SID files, where the individual retrieval of a record via the Internet is almost as expensive as fetching a sizable batch, use a cache if allowed and prefetch multiple records when a record read operation is performed and the cache is empty or the requested record is not in the cache. A later read can, if the input record is in the cached set, return the data without establishing a new network connection.Using a cache is beneficial only when the expected access pattern is linear and in ascending record order. It decreases performance if the record access pattern is random and not limited to a continuous record set that fits into the cache.
• category
  A category string to be used if the file is stored in a repository.
• chain
  A single-letter code indicating the chain to be read from records with structure disorder data. These can for example be found in PDB files. The default value ‘?’ automatically selects the first chain which is encountered in the file record. After a record has been read, the attribute is set to the actual character of the chain which was selected, so it needs to be reset in case more than one record is input via this file handle. If the chain character is set to an empty string, all atoms are read from files even if they belong to multiple overlapping disordered structure instances. This can of course lead to problems in connectivity representation. The alternative name disordered is an alias for this attribute.
• classuuid
  The base class UUID of this file object, copied from its I/O module UUID .
• coords
  If the toolkit was compiled with factory support, these are the coordinates of the object icon on its workbench, encoded as integer pair. This attribute can be changed
• compact
  A boolean flag indicating whether the file is present in a abridged form, or should be written as compact as possible. This attribute effects few file formats. An example is the native Cactvs ASCII format ( cascii ).
• complexresolver
  A boolean flag which enables or disables bond type processing after input. It the flag is on, typical complex bonds between metal atoms and ligands, or between metal atoms, are recognized and re-coded as complex bonds, which provide connectivity, but do not participate in valence electron counting. In many cases, this improves the general representation quality of the structures. However, since most chemical data exchange formats do not support this type of bonds, it can also make export of the data difficult. By default, this flag is on . For maximum portability, it should be switched off. This attribute is a convenience shortcut operating on the readflags attribute.
• computationlog
  A read-only attribute. It is a list of all properties which were computed during a record write operation, either implicitly or explicitly via the computelist attribute. This can be used to determine which effects the output has had on the information content of a written object, or to optimize I/O throughput by performing pre-computation of these properties in a separate thread.
• computelist
  A list of properties which are automatically computed before an output object is written if they are not yet valid. Computation failures are silently ignored.
• compression
  The detected file compression type. It can be one of none , compress , pack , gzip or bzip2 . Compressed files are automatically opened for reading via a pipe to the suitable decompressor program, if it can be located. This attribute can also be set, but it currently has no effect on the actual output in any format. In order to write compressed files, open an output as a pipe to a compressor program.
• corsdomain
  If specified, and the httpheader attribute is also set to a value larger than zero, the output HTTP header contains a CORS domain header line ( Access-Control-Allow-Origin: ). Useful values for this parameter are either * (for free access), a host name, or a domain name. If this parameter is not specified, HTTP headers do not contain information, which usually is equivalent to allowing access for AJAX queries only from the same server as the requesting page.
• ctime
  A read-only attribute reporting the time of the last status change of the file. Its unit are seconds since January 1st, 1970. This value is meaningful only for normal disk files.
• date
  The date the file structure was defined. This is not the same as the filesystem time stamps, such as the ctime or mtime attributes.
• deletable
  Flag indicating whether this molfile can be deleted or closed with a standard molfile close command. The attribute is read-only. Molfiles which are, for example, property data values or a part of a molfile loop command cannot be deleted by standard means.
• deselection
  This somewhat awkwardly named attribute is the inverse of the selection attribute. For further explanation, refer to the paragraph on selection.
• device
  A read-only attribute reporting the device number of the file. This is meaningful only for normal disk files, and only supported on Unix/Linux.
• doi
  A digital object identifier for the file content, if defined.
• downloadfilename
  If the httpheader attribute is set to a value larger than zero, this value is included in the HTTP header as save file name, with a MIME type of application/save-to-disk which overrides any native file format MIME type.
• droplist
  A list of properties which are not to be written to the file, even if they are already present on output objects and the file format can encode them. Naming a property in this list does not delete them from the property set of objects which are written to the file, just suppresses their output.
• email
  A contact email of the file author.
• embedformat
  The format of embedded objects encoded in another format. This is meaningful only for a few file formats, for example zip (which contains single-record files of a different type) or rtf (which may contain cdx or skc embedded OLE objects). If this attribute is not set, the default depends on the wrapper format (i.e. SDF files for zip , cdx OLE objects for rtf ). Setting it to an empty string or none disables embedding where applicable. The attribute is updated on input and can be read when a file record is input which contains embedded data.
• encoding
  The detected encoding type of the file. It can be one of ascii , binary or unicode . This is a read-only attribute.
• eof
  This read-only boolean attribute indicates whether the file read pointer is at the end of the file.
• eolchars
  A sequence of characters which are used as line terminators for the output of text-based file formats which do not define a specific line end character. The default value is platform-dependent. It is a single newline character on Linux/Unix, CR/LF on Windows and a single CR on Macs. This attribute has no effect on input. All input routines automatically recognize and read all three variants on all platforms.

On setting, the magic strings windows , mac (both checked for the first three characters only) as well as unix and linux are translated to the standard platform line terminators and not copied verbatim. Alternative names for these standard system encodings are crlf , cr and lf . The special value default resets the attribute to the platform-dependent default.

• eor
  A read-only attribute which indicates at what type of record terminator the current read position is located. Possible values are none , mol , ens , reaction and dataset . The none value indicates that reading did stop in the middle of a record due to some problem.
• errorproperty
  A read-only attribute which holds the name of the last property where input failed. This is not supported by all file I/O modules. It is especially useful for binary formats where a line number cannot be used for simple visual inspection of an input problem.
• failures
  A list of properties for which computation failed on this object. This is a read-only attribute. Depending on configuration settings, this information may be used to block pointless attempts at re-computation of incomputable data.
• fd
  A read-only attribute which reports the system channel number the file object is associated with.
• fields
  This is a list of the names and potentially attributes of data fields in the file. For simple formats such as SD files, this is simply a list of property names, and it is updated after each read record to track a potentially changing field set. For more complex formats such as bdb and cbs , every list item is a nested list which contains the field name, field flags, field object class association and partition file. The field output for simple formats such as SD is controlled via the writelist attribute, and the value of the fields attribute has no effect on output. However, the I/O modules for complex database-type formats such as bdb and cbs provide a handler function which translates an updated value of this attribute into a changed database layout. Depending on the I/O module, this may be supported only for an empty file ( cbs ), or may be possible even for files which already store records ( bdb ). This attribute can also be addressed by the alias fieldnames .
• filelock
  On reading, this is a boolean flag indicating whether a file lock is currently set on the file or not. On setting, the argument can be release , trylock , forcelock or test . The first variant attempts to release an existing file lock, the second variant attempts to set a file lock, but returns immediately if that is not possible, the third variant blocks until the lock can be established, and the fourth version tests for the presence of a lock. The return value is a boolean status result. This command is not supported on Windows. File locking may pose special problems if the file is not residing on a local file system.The underlying system call is lockf64() or lockf() . Please consult your operating system manual for more details.
• fileset
  A read-only attribute containing a list of the names of the physical files which are behind the file handle. For normal files, this is a single list element for a single file. However, for file handles opened by means of the molfile lopen command to access a virtual file assembled from multiple physical files, this can be a list with more than one element.
• filter
  A query expression (see molfile scan command) which input records must match to yield a result object when a molfile read command is run. The read command is automatically looped until a matching record is found, or the end of the input source is reached. Since the test is only applied after a prospective input object has already been fully read internally, this style of record filtering is in many cases considerably less effective than using molfile scan for file formats which possess query acceleration features, such as CBS , BDB or the Pubchem virtual file module. For the reading of simple text files, such as SDF , there is no performance difference to using molfile scan in the ens or reaction object retrieval mode, and this type of filter which can be easily adjusted or disabled (by setting it to an empty string) can be convenient.
• fontsize
  The standard font size for text in graphics-oriented formats, such as CDX or SKC . The value is a floating point number measured in points (1/72 inch). A value of zero or less, which corresponds to the default, lets the software chose a suitable value, which is dependent on scaling and bond length.
• fold
  The number of characters after which the software should look for a good position to use a continuation character and line break. This is only used in a few formats, such as SLN .
• footer
  If the toolkit was compiled with factory support, this is the footer of the object icon on a workbench. This attribute can be changed.
• format
  The standard name of the file format the molfile object is linked to. This is normally only set in scripts for output files, because the format for input files is auto-detected. Nevertheless, it is possible to set a format explicitly also for input files, and even to switch it when records have already been read. When setting a format, generally a set of alias names are recognized in addition to the short official name.
• from
  The sender of a file. This is only set when the file has been extracted from a mail message or attachment.
• gflags
  If the toolkit was compiled with factory support, this is the currently set object icon rendering flag collection.
• handle
  The handle of the file as a read-only attribute. Not generally useful, because in standard access modes you already need the handle to identify the file object.
• header
  If the toolkit was compiled with factory support, this is the header of the object icon on a workbench. This attribute can be changed.
• height
  The maximum height of a structure or reaction depiction in points (1/72 of an inch). This is only used for graphics-oriented formats, such as CDX , SKC or EMF . If the attribute is set to a negative value, which is the default, the size is indirectly controlled by the bond length and atom coordinates. In case this attribute is set to a positive value, and the depiction would exceed the maximum height, it is automatically scaled down proportionately.
• hidden
  Flag indicating whether the object is hidden. This is not the same as the invisible state. This attribute is intended to be used for rendering object selections. This attribute can be set.
• highmaprecord
  The maximum record to include in a memory-mapped section of the file for accelerated read access. If set to a negative value, which is the default, the system automatically determines if mapping is worthwhile, and if it is, map the full file. This attribute is primarily useful for the acceleration of queries which repeatedly operate in a section of a larger file, for example when running distributed queries with multiple processes handling different parts of a large file.
• host
  This is a shortcut for the host name part of a file or virtual file addressed via an URL. For simple retrieval it is equivalent to the URL field attribute url(hostname) . For some I/O modules, for example the interface to access Mysql tables as virtual structure files, a change of the host name does have an effect and results in (re)-connection to a different database host. For normal files accessed via a URL a change of the attribute is ignored after the file has been opened. Files that are not associated with an URL have an empty host name value.
• httpheader
  Configure whether the file content output should be prefixed by a HTTP header. This can be useful when scripting CGI or FCGI applications. The value can be 0 (no HTTP header prefix, the default), 1 (standard HTTP header prefix, without status code) or 2 ( HTTP header including 200 status code). String values none , default and status are also recognized. Not all table I/O modules support this feature. This attribute has an effect only if the file is opened for output, and has no records when it is opened. The data is written immediately after the file is opened, before any other output is performed. The configured corsdomain , mimetype and downloadfilename attribute data is part of the output. Note that prefixed files are only useful in Web application CGI/FCGI contexts, where the header is stripped before the data is seen. They cannot be read as normal structure files.
• hydrogenfilter
  A hint about the desired output style of hydrogen atoms of the structure. In contrast to the hydrogens attribute, this hint does not actually change the structure by adding or removing hydrogen atoms, neither on the original output object nor a temporary processed structure or reaction duplicate. Not all I/O modules support this flag. Its availability can be queried via the capabilities attribute of the filex command for the format. The possible values are default (or -1), which is the default and selects the default hydrogen write mode of the file format, none (or 0) which suppresses hydrogen output, special (or 1) which writes hydrogens shown normally with a symbol only, and all (or 2), which writes all extant hydrogens. Since this attribute does not change the hydrogen atom set, setting for example the mode to all when there are no hydrogens attached to the structure has no effect.
• hydrogens
  The hydrogen processing mode of the file. Its default can be controlled via the system variable ::cactvs(default_hydrogen_addition_mode) . Its standard setting is asis , meaning the hydrogen set is to kept as it stored in the objects for output, or defined in the original file records for input. Possible modes for this attribute, or the system control variable, are add (add a complete standard set of hydrogens), asis (keep unchanged), strip (strip hydrogens except those which are normally displayed, such as bonded to hetero atoms or at stereo centers), stripall (strip all hydrogen), stripadded (strip all hydrogens which were added by a hydrogen add command, automatic hydrogen addition on input, or similar mechanisms) and addblind (which is the same as add, but does not register the added hydrogen atoms as implicit in property A_IMPLICIT ). When writing a structure object to a file with enabled hydrogen processing, the original object is not changed. Hydrogen processing takes place on a ephemeral duplicate object. On input, hydrogens which are no explicitly encoded, but defined via implicit valence rules in the format specification are still instantiated in asis mode. For example, a single C atom in an MDL Molfile is read as a single atom, because there are no default valence rules, but a C as a SMILES string is expanded into one carbon plus four hydrogen atoms. For a method to suppress the expansion of valence-implicit hydrogen atoms, see the readflags attribute.
• hydrogenstatus
  An enumerated value providing information about the hydrogen status of the file. Possible values are unknown , complete (all hydrogens present), partial (some hydrogens present) and missing (no hydrogens present). This attribute is updated when data is read from files which encode this information. It may also be set and has an effect on some post-processing operations on objects read from the file.
• ignoreempty
  A boolean flag which instructs, when set, the I/O module of the file format associated with the molfile object to ignore empty records without atoms when reading from the file. By default, this flag is not set and empty records are retrieved as empty ensembles or other objects.
• ignoreerrors
  A boolean flag which tells the I/O module of the file format associated with the molfile object to ignore errors and to attempt to read or write the next record instead. By default the flag is not set and errors in I/O result in Tcl script command errors.
• ignorelist
  A list of properties which should not be read from the file, even if they are explicitly encoded in the records.
• incomplete
  This is a boolean read-only boolean flag which indicates that a record was only read partially. This is the same as checking for the presence of the incomplete flag in the flags attribute.
• infourl
  A URL with information on the file content, or an empty string if unset.
• inode
  A read-only attribute reporting the inode number of the file. This is meaningful only for normal disk files, and only supported on Unix/Linux.
• instanceuuid
  The UUID for this object instance.
• invisible
  Flag indicating whether the molfile object is invisible. This is not the same as the hidden state. An invisible object is no longer accessible via its handle. This is usually the case for objects which are scheduled for deletion, but still have lingering referring pointers. This attribute is read-only.
• iscompressed
  A boolean read-only attribute which is set when the file is compressed by one of the recognized compression algorithms ( gzip , bzip2 by default). In that case, the file is not accessed directly but via a pipe the the appropriate decompression program, which changes the file handling characteristics.
• ismapped
  A boolean read-only attribute which is set when the file is read via a memory-mapping method.
• ispipe
  A boolean read-only attribute which is set when the file is accessed via a pipe, either because it was explicitly opened to a pipe, or because decompression ( gzip , bzip2 ) or character encoding ( iconv ) programs where automatically spliced in.
• javaobject
  If the toolkit was compiled with JNI support, this attribute reports the memory address of the JNI wrapper class instance, if it exists.
• jstreversal
  A boolean flag indicating whether the JST special encoding variant for MDL Molfiles should be used.
• keywords
  A list of keywords associated with the file.
• lastrecord
  The value of the file record read position before the last molfile read command. This is normally the value of the record molfile attribute after the read operation minus one and corresponds to the file record number of the read object in the data file.
• license
  The license class associated with this file. Setting the license to a standard type updates the associated URL with a standard location.
• licenseurl
  A URL with details about the network object license.
• literature
  A free-form literature reference.
• line
  A read-only attribute returning the current line number. lc is an alias name for this attribute. Generally this attribute is meaningful only for text-based file formats. For most binary formats, the value of this attribute is the same as the record number. This line number always refers to the current physical file. To get the global line number of a virtual file set, use the vline attribute.
• loinc
  The LOINC code ( https://loinc.org/ ) describing the file contents. For I/O formats where this information us used (currently SPL ) and the attribute is not set, the default is 64124-1 ( Indexing - substance ). Setting a LOINC value for the first time takes a second or two because this is a controlled vocabulary, and the term table is loaded from disk for verification.
• loopitem
  The current file input item in a molfile loop statement. This is the same as the content of the loop variable. If no loop is active, this is an empty string. This is a read-only attribute.
• lowmaprecord
  The minimum record to include in a memory-mapped section of the file for accelerated read access. If set to a negative value, which is the default, the toolkit automatically determines if mapping is worthwhile, and if it is, map the full file. This attribute is primarily useful for the acceleration of queries which repeatedly operate in a section of a larger file, for example when running distributed queries with multiple processes handling different parts of a large file.
• mailencoding
  This is a read-only attribute which is only set if the file has been extracted from an email message or attachment. Possible values are unknown , ascii , iso (for ISO 8859-1), quoted (for quoted printable), base64 and utf8 .
• mailproperties
  This is a read-only attribute which is only set if the file has been extracted from an email message or attachment. It is a list of properties which were requested for computation in a header field. This attribute is typically used for setting up email-based property computation services.
• maxblobsize
  The maximum size of Cactvs ensemble or reaction blobs which are part of the file records, measured in bytes. This attribute only applies to those few file formats which store structure and reaction data as Cactvs toolkit blobs. Currently these are CBS and BDB . If the blob size exceeds the limit, the input or output of the record fails. The default value are 256K, which is more than sufficient for standard applications. If the attribute is changed, a minimum value of 64K is silently enforced. Increasing the attribute can have a small negative effect on I/O performance, but is otherwise safe.
• mimeboundary
  This is a read-only attribute which is only set if the file has been extracted from an email message or attachment. This is the string which was used to separate MIME data blocks in the message.
• mimedefaulttype
  A read-only attribute giving the default MIME type associated with the current file format.
• mimetype
  The currently configured MIME type for the file. Initially, it is set to the default type (attribute mimedefaulttype ). However, it can be changed, and it is used for transmitting the file data via various types of Internet connections.
• modcount
  The molfile object modification count. This is a read-only attribute.
• mode
  This is a read-only attribute which describes the general file access mode which was established when the file handle was created by a molfile open or molfile lopen command. Possible values are append , pipe , read , string , write and update . Note that in this attribute there is no difference between the standard read and the restricted read-only modes (see molfile open ). The file mode cannot be changed at a later time by directly changing the mode attribute. However, with some limitations, a file may be switched back and forth between input and output modes with the aid of the molfile toggle command.
• mtime
  A read-only attribute reporting the time of the last modification of the file. The unit is seconds since January 1st, 1970. This value is meaningful only for normal disk files.
• mutexcount
  The number of recursive mutex locks held for this object. Only supported on Linux.
• name
  On input, this attribute simply reports the full path name of the underlying file, or the original magic name in case of special files. This attribute can also be set, and in case of normal disk files, the physical file is renamed, too, if the file access permissions are sufficient for this operation.
• nitrostyle
  The nitro (and similar) group encoding conventions associated with the file handle. There are actually independent settings of this attribute for input and output. The version reported by the command is dependent on whether the file is in input or output mode. Possible values are asis , ionic neutral, xionic and xneutral . The default input value is ionic , while the default output value is asis . When the value is modified, the new value is stored both for input and output. If the value is not asis and a structure item is read, its nitro group (and related groups) connectivity is automatically adjusted to the preferred style. If processing is requested for output, the connectivity change is performed on a temporary duplicate, so that the original output object is not modified.
• nullstring
  A string which on input is used to identify NULL values, or used on output to encode NULL values. This attribute is only used by a few I/O modules. The most important application is in reading text-based tables with embedded structure notations by means of the table structure I/O module.
• offset
  A read-only attribute reporting the current byte offset position of the read or write pointer. It is not meaningful for all types of data channels.
• orcid
  The ORCID code of the author (see www.orcid.org).
• orientation
  This value can be none (the default), landscape or portrait . It describes the orientation of a drawing area specified via the paper attribute. Few I/O modules use this information. The most important formats which implement this is are CDX and CDXML .
• originalname
  The name as originally used to create the molfile object. The standardized name, with path information in case of disk files, can be accessed via the name attribute. Changing this attribute has no effect on the file system. This is different from the handling of the name attribute.
• pagecount
  The number of (vertically stacked) pages in the document. This attribute is currently only used for the CDX and CDXML formats.
• paper
  An attribute describing the size of the drawing areas for formats such as CDX or CDXML , which can encode this type of information. Possible values are none (the default), a3 , a4 , a5, a6, a7, b3, b4, b5, b6, letter, legal and executive . The associated orientation of the drawing orientation can be set via the orientation attribute.
• parameters
  A free-form string which can be used to pass additional, non-standardized parameters to a file format I/O module. Few I/O modules use this, one example is the XFIG output code.
• password
  A file access password. It is used in various contexts, for example for authentication when using URL-based access to files, to enable the I/O of encrypted records in files which support partial data encryption, such as the Cactvs CBS and BDB formats, or to proceed with the execution of a remote query received via a listener port. In most cases a change of the attribute value after a file has been opened has no effect. An exception are modules which access database tables as virtual structure files. These will react to a changed user name with re-authentication to the database and table, which may result in different access permissions.
• path
  The repository path for displaying hierarchical repository trees. This attribute is independent of any file system paths.
• phone
  A contact phone number of the file author.
• polysymbol
  A free-form string used to override the standard symbol used by a file format I/O module to indicate polymer components. If set to an empty string, the standard symbol is used, which depends on the file format. The default is an empty string.
• port
  The number of a port on which the file handler should accept remote query requests. If set to a negative value (the default), no such requests are accepted, and in case a monitor thread was executing before the value was changed, it is shut down. If a positive port number is set, a monitor thread is automatically started as listener on the specified port.
• position
  This read-only attribute describes the relative position of the read or write pointer in the full file, as an integer in the range between 0 and 100. It is primarily intended to be used in progress meters and similar widgets. In case the relative position is unknown, for example because the total size of the input file is unknown, the value is zero.
• preservelist
  A list of properties which should not be changed if a file record is updated, even if the value in principle depends on, for example, changed connectivity of the main structure record. Currently, the only I/O module which supports this feature is BDB .
• previousrecord
  This read-only attribute is a convenience function to obtain the value of the record number of the file handle that before the current record was read. Usually, it is the same as the record attribute minus one, but if reactions from files where reagents and products are separate sub-records, or complete datasets were read, the difference may be larger.
• progress
  A user-defined progress value intended to track the state of lengthy operations on the file. It is an integer between zero and one hundred and is initially set to zero. When the argument is set, it accepts a floating point value, but the stored value is automatically rounded to the next integer and forced into the 0..100 range.
• pyobject
  If the toolkit was compiled with Python support, this attribute reports the memory address of the Python wrapper class instance, if it exists. This attribute is read-only.
• pyrefcount
  If the toolkit was compiled with Python support, this attribute contains the reference count of the Python wrapper class instance, if it exists. This attribute is read-only.
• reactioncolumn
  This attribute is the numerical index of a column in table-style data files which are, for example, read by the reaction table I/O module. The column is expected to contain a string notation for the reaction object which is returned by a molfile read operation. To this decoded object the contents of the other columns is attached as property data. Typically the content of the structure column is a Reaction SMILES string or similar line notation. A negative value of this attribute indicates that the presence of structure data in a specific column is unconfirmed. In that case, an attempt is made to determine the reaction column automatically, and the attribute is updated accordingly. However, setting it explicitly may still be required in case there are multiple columns with reaction data, or there are too many unreadable or NULL row entries to allow automatic determination.
• reactionscreen
  The name of the property which is used for bitvector screening in filtering records for reaction transform matching. Its default default value is controlled by the global variable ::cactvs(default_reaction_screen_property) and is usually X_SCREEN . If a file is opened that contains information about the screen property set when the file was written (for example, CBS and BDB formats), this attribute is automatically set to the value stored in the file.
• readflags
  This attribute controls a set of input processing flags. If the attribute is queried, the result is a list of the names of all flags which are currently set. For modification, the preferred method is to use the bit manipulation prefixes for generic bitset operations. In case just additional flags should be activated, the molfile append command can also be conveniently used. There are also a few shortcut alias attribute names which set or reset selected, frequently used flags directly ( complexresolver ). The following flag names are currently recognized:
• none
  no flags.
• aroresolver
  resolve aromatic bonds into a Kekulé form. A frequent application is the input of records from MDL SD files which are not used as query structures, but where aromatic bonds in the original data are nevertheless and illegally encoded as the aromatic structure query bond type with magic bond order 4. This flag should not be used on formats which are guaranteed to already encode a proper Kekulé form. This includes all native toolkit formats ( cbin , cbs , bdb, cda, cpc ).
• autowrap
  When the end of the file has been reached, automatically start reading from the beginning of the file again, until the full file has been scanned once. This operation effects only the molfile scan command and is used there in order to perform full-file queries starting from an arbitrary position in the middle of the file.
• basiconly
  only read basic property data set, not full record. This is supported in CBIN , CBS and BDB formats in order to accelerate fast filter and query operations.
• chargebalancer
  Try to neutralize and balance charges.
• chargecombiner
  Try to merge opposing charge pairs where possible, changing the bond orders of paths between them if necessary.
• complexresolver
  perform a bond analysis and re-code typical bonds in metal complexes as non-VB bonds, which do not participate in valence electron counting. For a more detailed explanation, see the alias shortcut complexresolver . This flag is set by default.
• continueafterhetatm
  For PDB files, consider any atom line after the first HETATM to be a heterogen, regardless of the line type. This feature helps to cope with ligands which contain amino acid substructures and which some other PDB write software misclassified as part of the protein.
• fixdoublespace
  If set, this flag instructs I/O modules with support for this feature to read structure files which contain one spurious empty line after each data line, which unfortunately appears to happen sometimes when DOS -encoded files are transferred to Apple systems. This is not the same as reading CR/LF files on CR -only or NL -only platforms, or vice versa, which is always possible and fully automatic. This flag addresses the problem that, due to mishandling by obscure transfer software, duplicated EOL -markers are introduced in the file (two identical CR/LF , or CR , or NL pairs after each data line).
• fixstereo
  Remove spurious stereo descriptors on atoms and bonds which are not stereogenic.
• fixwedges
  Re-code wedges which are attached with the broad base to a stereo center (for example as written by IDBS software) into standard IUPAC format with tips at the stereo centers.
• hetatmonly
  In PDB files, read only HETATM lines.
• ignorecr
  Allow an isolated carriage return ( ASCII 13) character without following NL ( ASCII 10) character as data content instead of examining it as potential line break symbol. This flag is necessarily ignored on Mac-style input files which only use CR as EOL markers.
• ignoreitherdb
  If set, ignore any either attribute data for double bonds in MDL Molfiles . Instead, determine their stereochemistry from coordinates.
• ignoreempty
  When reading an empty record, with no atoms, from a multi-record file, ignore the record and immediately proceed with the next.
• ignoreerrors
  When reading a corrupted record from a multi-record file, ignore the error and instead attempt to re-synchronize and read the next record.
• ignorenorecall
  If set, the norecall field flag supported in some file formats ( CBS , BDB ) is ignored. By default, data from fields which carry this flag is not merged into the property set of ensembles or reactions when they are retrieved as objects from these files, as an optimization to avoid recalling data which is useful for queries, but not so much as object data (for example, screen bits, element counts). With a set attribute flag, all fields of the record are attached as property data to recalled objects.
• ignorevisibility
  Ignore any display attributes in the input data which would make atoms or bonds invisible in renderings.
• latehprocessing
  If this flag is set, the standard hydrogen addition/removal operations are performed after other selected processing steps have been performed. By default, hydrogen processing takes place before charge equilibration, radical charging, etc. This flag should be set if the hydrogen set in the file records is known to be complete, but the charge and radical situation is dubious.
• lockmemory
  Lock the shared memory mapping arena of the file into memory, preventing it from being swapped out. This is only supported on Linux, and has an effect only if the sharedmap flag has been set. Depending on the size of the arena, and the system configuration, this operation may require enhanced privileges.
• logqueries
  If the file formats supports operation logging, activate the log.
• keepcoords
  In case multiple molecules or ensembles are read in one operation, the system normally verifies that they do not have overlapping 2D display coordinates, and moves them apart if necessary. If this flag is set, the 2D display coordinates in property A_XY are always passed unchanged.
• mergedata
  In case there are repeat instances of the same data item in an input record, attempt to append it in a suitable fashion to the first property instance on the input object. By default, multiple data items with the same name are not merged, but result in multiple property data instances. This is a problem which is encountered typically while reading data from formats with limited syntactic expressiveness that cannot properly distinguish between these cases.
• multibondcheck
  attempt to correct unlikely clusters of multiple bonds.
• nocoordinatecheck
  do not attempt to discover and fix mixed-in missing 2D or 3D coordinates, for example encoded as all-0 values. All coordinate data is to be preserved verbatim.
• noorigin
  do not register the origin of the property data values from the current file as metadata information.
• noeof
  do not attempt to detect EOF . More data may be coming.
• noimplicith
  do not add a standard valence set of hydrogens to explicitly encoded atoms, even if the file format specification defines such a set. The most common application is for reading SMILES strings without the default hydrogen atoms. nohadd is a (slightly misleading) alias for this flag. This flag is independent of the generic hydrogen addition/removal processing option, which can be configured with the hydrogens attribute.
• nometa
  if this flag is set, it asserts that the file does not contain metal atoms. This is for example useful for reading PDB files which frequently possess ambiguous encodings such as CA for calcium or alpha carbon.
• nometalh
  suppress addition of hydrogens to metal atoms.
• noradicals
  assert that the file does not contain records with atoms that are radicals. This is a hint which is used for hydrogen addition, radical charging, and other operations.
• pedantic
  apply pedantic checking of file syntax rules. For some frequently abused file formats, such as MDL Molfiles or PDB , this may result in quite a percentage files being rejected for file format specification violations.
• radicalcharger
  Edit radicals which are typically formed by reading a file without formal atomic charge information by adding standard formal charges, for example replacing NR 4 with N (+) R 4 and OR with O (-) R. This only works reasonably well if the file contains a complete hydrogen set.
• readas2d
  Force the interpretation of atomic coordinates as 2D, regardless of the file type encoding or presence of a third coordinate column, which may have been abused as an additional atom data store.
• readparity
  If this flag is set, the parity fields in MDL Molfiles and derivatives are read and the data stored in property A_LABEL_STEREO . In accordance with MDL rules, this field is normally ignored, and stereochemistry decoded from wedge bonds and atom coordinates.
• sharedmap
  If the file is memory-mapped, use a shared memory segment for the data. This can be useful if there are many processes accessing the same file for reading. This flag is only supported on Unix/Linux.
• simpleradicals
  If this flag is set, the input file is assumed to contain only simple doublet radicals, if any. Any encoding of other, probably miscoded radical forms is changed to a doublet.
• tautoresolver
  Perform a tautomer standardization on the read structure. This operation invalidates numerous atom and bond properties, such as coordinates, but in this special case all ensemble properties which were attached to the processed structure are retained, regardless of their sensitivity toward atom and bond changes. Tautomer resolution requires a complete hydrogen set, so either these must be present in the input file, or a suitable hydrogen addition mode must have been set on the file handle. The processing behind this input option is comparatively expensive. For normal input, when speedy input and maximum fidelity of the data to the original file is desired, this flag should not be set.
• readkey
  This attribute is only used in certain library configurations which have been configured to restrict read access to specific types of files. The key and data computed from the file name must together match the signature. Usually restricted applications have a compiled-in signature, and one or more read keys which enable read access to the same number of specific files.
• readkeysignature
  This attribute is used for certain library configurations which have been configured to restrict read access to specific files. This signature is required to verify the read access key.
• readkeystatus
  A read-only attribute which reports the access key status for a file for which a read key has been specified. It can be unchecked , verified or error .
• readscope
  This attribute controls which types of objects are read from a file, in case the file contains more than one object type. For example,. MDL RXN files can be read as en ensemble record stream, or as a reaction record stream. Cactvs CBIN files can be read as a multi-record stream of individual ensemble or reaction records, or as a single dataset with additional dataset properties. CTX files allow access to individual molecules or ensembles. The hierarchical FDA SPL format supports read modes for molecules, ensembles, and datasets. The default value for this attribute depends on the file format and is automatically updated whenever the format is analyzed or changed. It is generally set to the most commonly used access variant for that format, for example reactions for RXN files and ensemble streams for CBIN , but it may also be set explicitly. Possible values are none , mol , ens , reaction , dataset, biologics, hierarchy and auto . In case a file format does not support a specific variant, the next supported type to the right in this sequence is automatically used. The auto mode performs a new content analysis for every record and use the most suitable scope. Examples where this is useful are RDF files with mixed structure and reaction records, or RTF documents which mix reaction and structure OLE objects. The dataset mode is potentially dangerous when reading large multi-record files which do not contain multiple smaller datasets. In that case, the whole file is interpreted as a single dataset, and that can lead to a large amount of memory being consumed.
• record
  The number of the next record to be read or written, starting with one. This value always refers to the current physical file, even if the file handle manages a virtual file. In case a virtual file is read, the vrecord attribute can be used to access the global record number. rc is an alias name for the attribute.

It is possible to set this attribute in order to reposition the file pointer. In case the file is opened for output, and is not in update or append mode, this operation truncates the file. Repositioning while reading does not modify the file. It is not possible to position the file pointer any further to the rear of a file than immediately behind the end of the last existing record. In case of virtual files, a record setting implicitly changes the vrecord attribute, not the current physical file record.

When setting the attribute, the special values end and last can be used to position the file pointer behind the last, or before the last record, and a negative value is interpreted as a backspace from the current position. The return value is the resolved record number.

• recordtable
  This is a read-only attribute. It returns a nested list of the attributes of the currently known record positions in the file. Every list element is itself a list which contains, in this order, the record number, the file offset, the line number (which is the same as the record number for binary formats), the eor type of that record, a boolean flag indicating whether the record is physically present in the disk file (0) or virtual (1)., and the original file name used to create the handle. In case of multi-file handles, this is not a constant over all records. In order to guarantee that all records of a file and their offsets are known, execute for example a molfile count command before querying the record table.
• refcount
  If the Tcl interpreter is using native Cactvs objects instead of string-based major object handles and integer-based minor object labels to identify toolkit objects, this returns the number of Tcl object references active for this object. The attribute is read-only.
• references
  Cross references of the file. This is a nested list of class UUID s and reference type tags.
• replyto
  The future recipient of a file. This is only set when the file has been extracted from a mail message or attachment. In order to send mail messages to specific destinations via the mail wrapper I/O module, this attribute may also be set.
• resolution
  A resolution value in DPI (dots per inch). The default value is 0, meaning that it is undefined. This information can be used by a couple of I/O modules, for example for reading structure data from image files by performing chemical OCR via the interface to the OSRA program.
• returnformat
  The name of the desired return format if the original file was received by mail. This is only set when the file has been extracted from a mail message or attachment.
• scandata
  This is a read-only attribute which reports statistics on the last molfile scan command. The returned data is a Tcl dictionary with keys start_time (in seconds since 1970-1-1), stop_time (in seconds since 1970-1-1), scan_time (in seconds), ens_read (count of ensemble objects instantiated), miniens_read (count of Minimol objects decoded), reactions_read (count of reaction objects instantiated), properties_read (count of property records read), ens_screened (count of bit-screen filtering operations performed for substructure/superstructure searches), reactions_screened (count of bit-screen filtering operations performed for reaction matching), records_examined (count of records looked at), records_matched (number of matched records), start_record (record the scan started at), end_record (last visited record), eof_reached (boolean indicator whether the end of the file was reached), max_mmap_used (maximum used size of memory mapping arena), max_mmap_requested (maximum requested size of memory mapping arena), records_skipped (number of records which where skipped with need for re-synchronization), records_repositioned (number of records which were finished without the need for a re-synchronizing skip operation) scores_computed (the number of scoring function calls executed).
• scoped
  A boolean object visibility control flag. If set, and global control flag ::cactvs(object_scope) is also set, the object is visible only in the Tcl interpreter which set the scope flag and thus claimed it. Object list commands executed in other interpreters omit this object, and attempts to decode its handle in other interpreters will fail. The most common use of this feature is the hiding of persistent chemistry objects in scripted property computation functions.
• selected
  Flag indicating whether the object is selected. This attribute can be changed.
• selection
  This attribute is not a molfile handle attribute, but a flag attached to individual records. If queried, the return value is a list of all record numbers for which this flag is set. Using molfile set with a list of record numbers in any order to modify the attribute resets the current flags, and creates a new set. Modifying the attribute via molfile append adds selection flags without resetting the current selection. The selection flag can only be set for existing records. If an attempt is made to set the selection flag ahead of the currently known position set, the command scans the record structure (as in molfile count ), which can be a problem in case of non-rewindable input. In order to facilitate resetting of selection flags, the virtual attribute deselection can be accessed as the inverse of the selection. Setting it to an empty list selects all records up to the end of the file (again this triggers automatic forward scanning, if necessary), and appending a list of records removes them from the selection. The default value of the selection flag for any record is false .
• separator
  A string containing one or more column separator characters. This is used for example by the structure and reaction table I/O module. The attribute is also set when a table with an auto-detected separator character was read via the file handle. The default separator is a single tab character.
• sessionkey
  A free-form string intended to be used to identify sessions.
• shmid
  In case the memory map arena of the file is in shared memory, this is the shared memory key as read-only value. If the file is not mapped into shared memory, or on platforms where memory mapping is not supported, the value is always minus one.
• signature
  The signature of a mail message. This is only set when the file has been extracted from a mail message or attachment.
• similarityproperty
  The name of the property which is used for bitvector similarity computation in file scans. Its default default value is controlled by the global variable ::cactvs(default_similarity_property) and is usually either E_SCREEN or E_QUERY_SCREEN . If a file is opened that contains information about the similarity property set when the file was written (for example, CBS and BDB formats), this attribute is automatically set to the value stored in the file.
• size
  The file size in bytes as read-only data. In case it is not known, for example because the file is accessed via a special stream or a pipe, zero is reported.
• sizehint
  The expected maximum record count of the file. This attribute is used by some I/O modules to pre-allocate room in files with complex storage layout, in order to avoid the need for expensive re-organization during later record writes. The CBS format especially benefits from this information. File formats which are simple record sequences have no use for this information. A value of zero, which is the default, specifies an unknown future size. If the final size is not known exactly, it is generally preferable to overestimate it somewhat than to be slightly short.
• statusflags
  A list of boolean flags which describe the status of the machinery behind the I/O operations of this handle. All set flags are reported. When checking for the presence of a flag, make sure not to use simple string comparison, because other flags may also be set. While it is possible to change the flags, this is not a common operation, and if done carelessly can disrupt the I/O functionality of the handle. The older attribute name flags is still a valid alias. The following flags are commonly seen:
• append - all file output is append to the end of the file, ignoring the current write pointer position.
• binary - the file is binary, without a line structure.
• bzip2-compressed - the file is accessed via a pipe to the bzip2 program.
• checkedbinary - the file contents were checked to determine whether they contain non-ASCII characters.
• edited - the file contains virtual edited records, or virtual deletes.
• fakeposition - the file has no meaningful offset positions for the beginnings of records, the offset data structures contain other forms of access information
• gzip-compressed - the file is accessed via a pipe to the gzip program.
• incomplete - the last file record was not read completely. This can be intentional in file formats which support basic and extended data groups, or can be an indication of a non-critical decoder problem.
• indexed - the file is accessed via an index file with record positions, not directly.
• nommap - memory-mapping of the file contents is suppressed.
• initialized - an initialization function of in the associated I/O module has been called
• locked - there is currently a flock()/lockf() style file lock active on the file.
• mapallocated - the memory mapping arena for the file was allocated and filled via some read operation, not mmap()ed .
• memlocked - a mapping of the file are locked into memory and are not swapped out.
• readable - the file handle can be read from.
• readonly - the file has been opened for read-only access, without the possibility to switch the handle to a different mode.
• remotefs - the physical file resides on a non-local file system.
• rewindable - the file can be rewound if necessary
• scratch - the file is a scratch file and is automatically deleted when the file is closed.
• shared - the file contents reside in shared memory.
• validcount - the current number of known positions is known to correspond to the total of records in the file.
• virtual - the file is a virtual file build from multiple physical files.
• ucs2-encoded - the file is accessed via a pipe to the iconv program.
• url - the file is accessed via a URL, not a file system path.
• updating - the file is currently being updated
• writeable - the file handle can be written to.
• xdr - the file is associated with an XDR encoder or decoder structure.
• style
  A free-format string identifying a predefined attribute bundle for graphics-oriented file formats. This is currently supported for CDX , CDXML , SKC and TGF , where, for example, the acs value selects settings corresponding to the “ACS Journal” settings in ChemDraw or ISISDraw .
• structurecolumn
  This attribute is the numerical index of a column in table data files which are, for example, read by the structure table I/O module. The column is expected to contain a string notation for the basic structure object which is returned by a molfile read operation. This string is decoded and the content of the other columns is attached as property data to this object. Typically the content of the structure column is a SMILES, SLN or InChI string. A negative value of this attribute indicates that the presence of such structure data is not confirmed. In that case, an attempt is made to determine the structure column automatically, and the attribute is updated accordingly. However, setting it explicitly may still be required in case there are multiple column with structure data, or there are too many unreadable or NULL row entries to allow automatic determination.
• subformat
  A enumerated value which encodes the subtype of the main file format. The most common values are mol2d , mol3d and mol0d , to indicate structure records with 2D or 3D or no coordinates. The type reaction can be encountered for RDF and CTX files with reaction data, since these can also be structure files in other cases. The attribute is automatically set when a file is read,. For some formats a explicit specification of the attribute controls the output formatting, for example for all file formats which contain an MDL ctab block, which can store either 2D, 3D, or 0D information, but not simultaneously.
• substructurescreen
  The name of the property which is used for bitvector screening in filtering records for substructure matching. Its default default value is controlled by the global variable ::cactvs(default_substructure_screen_property) and is usually either E_SCREEN or E_QUERY_SCREEN . If a file is opened that contains information about the screen property set when the file was written (for example, CBS and BDB formats), this attribute is automatically set to the value found in the file.
• superstructurescreen
  The name of the property which is used for bitvector screening in filtering records for superstructure matching. Its default default value is controlled by the global variable ::cactvs(default_superstructure_screen_property) and is usually either E_NO_HYDROGEN_SCREEN or E_NO_HYDROGEN_QUERY_SCREEN . If a file is opened that contains information about the screen property set when the file was written (for example, CBS and BDB formats), this attribute is automatically set to the value found in the file.
• template
  The name of a template file to be used for output formatting. At this time, only the RTF I/O module uses this information. It switches between de novo RTF formatting and replacing chemistry tags in the template file. If this value is set to an empty string, no template is used.
• timeout
  The maximum number of seconds to spend in a molfile scan command. When the time is exhausted, the scan terminates after the respective current record has been cleanly processed by all query threads, even if the end of the file has not been reached. Setting the attribute to zero, which is the default, allows an unlimited time to be spent on a query. Another function where the timeout value is used is in reading a record via an Internet connection, for example an http or ftp URL. If the timeout expires and the record has not been downloaded, an error results.
• tooltip
  If the toolkit was compiled with factory support, this is the tooltip of the object icon on a workbench. This attribute can be changed.
• url
  A read-only attribute with the URL in case the file is accessed via an Internet connection. If no such connection exists, the result is an empty string. If a URL has been set, this attribute may be indexed using the same fields as a URL property data item in order to retrieve URL components.

The allowed field names are hash , host , hostname , href , pathname , port , protocol , search , user , password , directory , file , ipaddr , lastmodified and mimetype . Note that in this context the port field name is the port the file is transferred via the Internet connection, which generally is not the same as the listener port for remote requests (see molfile get attribute port ). Likewise, the mimetype here is the MIME type as reported by the server, not the file MIME type defined by the file format handler module. Example:

set ip [molfile get $fh url(ipaddr)]

• user
  This is a shortcut for the user name part of a file or virtual file addressed via an URL. For simple retrieval it is equivalent to the URL field attribute url(user) . For some I/O modules, for example the interface to access Mysql tables as virtual structure files, a change of the user name has an effect and results in a re-authentication of the database and table access, which can result in different access permissions. For normal files accessed via a URL a change of the attribute is ignored after the file has been opened. Files that are not associated with an URL have an empty user name value.
• uuid
  An automatically generated UUID globally identifying the object. This attribute is read-only, different for every object, and not dependent on the contents or format of the disk file this object is associated with.
• valencelevel
  For files which support this concept, an indicator what kind of structure (stable, intermediate, MS ion, etc.) is stored in the file.
• version
  The file format version as a string. This attribute is set automatically when a file is opened for reading. If it is not set, files are generally read or written in the latest supported version. If a data file contains a known version indicator, input routines in some cases adjust to older encoding standards. The I/O modules of some file formats support the writing of old versions. An example are the CDX and CDXML modules, which in the context of file versions explicitly set to less than 8.0 do not write the InterpretChemically tag which is not understood by older ChemDraw releases.
• versionuuid
  The version UUID associated with this file as per its authorship attributes.
• vline
  The current virtual line count as a read-only attribute. For simple files, this is identical to the standard line count (attribute line or lc ). However, for virtual files opened by means of the molfile lopen command, this attribute is the global line number in the virtual file, while line/lc refers to the line count within the current physical file. The attribute name vlc is an alias.
• vrecord
  The virtual record number of the next record to be read, starting with one. For simple files, this is identical to the standard record count (attribute record or rc ). However, for virtual files opened by means of the molfile lopen command, this attribute is the global record number in the virtual file, while record/rc refers to the record count within the current physical file. The attribute name vrc is an alias.

This attribute can be set and changing it results in repositioning of the file pointer, and potentially even a change in the active physical file.

When setting the attribute, the special values end and last can be used to position the file pointer behind the last, or before the last record, and a negative value is interpreted as a backspace from the current position. The return value is the resolved record number.

• width
  The maximum width of a structure or reaction depiction in points (1/72 of an inch). This is only used for graphics-oriented formats, such as CDX , SKC or EMF . If the attribute is set to a negative value, which is the default, the size is indirectly controlled by the bond length and atom coordinates. In case this attribute is set to a positive value, and the depiction would exceed the maximum width or height, it is automatically scaled down proportionately.
• writeend
  An enumerated value indicating what kind of record end marker should be written on output, if the file format has such a concept. Possible values are none , mol and block . The default value is block , which translates into the standard record terminator for almost all file formats. The mol type is only significant for CTX format output. The none value can be useful if a programmer wants to add custom data to the end of a record and then writes an end marker himself, as it could be done without too much effort for example for an SD file.
• writeflags
  A collection of boolean flags controlling output details. When queried, this attribute returns a list of the names of all set flags. Modification of this flag supports the standard bit manipulation prefixes. The following flag names are currently recognized:
• none - no flags
• computeprops - attempt to compute properties in the write list if they are not yet present in the output objects.
• contracthydrogens - whether to store displayed hydrogens as explicit atoms, or contracted and linked to their bond partner atom as a hybrid object. This option only applies to the CDX and CDXML formats. By default, the option is not set.
• miniheader - keep the file header as concise as possible.
• nohydrogenisotopesymbol - if set, the default isotope symbols for heavy hydrogen (D and T) are not used in output. Instead, a simple H symbol is always written. Setting this flag does not suppress isotope output per se - if the file supports other means to define isotopes (e.g. M ISO lines in MDL files) these are still used.
• multiwriter - prepare the file to handle multiple simultaneous writers. The only file format I/O module which currently supports this is BDB .
• noimplicith - do not output hydrogen atoms which were added as implicit atoms.
• nomoleculesplit - do not split the ensembles into individual sub-records when this is normally required by the output format. This currently is only used by the MDL RXN and RD I/O modules. RXN files usually store every reaction component as a sub-record. This flag can be used to force writing of a single reagent and product record each, where each part may contain multiple un-separated components.
• nopropertymapping - always synthesize property descriptions, do not attempt to map them onto existing standard system definitions. The only module currently supporting this feature is the PubChem ASN.1 module.
• nostereo - do not write stereo information into the file, even if present in the output structures.
• nostereoperception - do not attempt to perceive stereochemistry from the available object data such as 2D coordinates and wedges, or 3D atomic coordinates, even if the file format normally requires this information.
• omitct - if the inclusion of a structure connectivity table is optional, this flag can be used to suppress the output this block.
• pedantic - perform pedantic output format checking, for example by refusing to write long lines in text formats which exceed the exact format specification, or refusing to write structures with more atoms than officially supported.
• rawcoordinates - do not perform any coordinate checking, scaling, and centring but write the coordinates exactly as they are currently stored.
• recalcbaseprops - if the output file content is a single property (for example E_GIF for GIF or PNG files, E_EMF_IMAGE for EMF and WMF files), force recalculation of this property before output.
• supergroupexpansion - If a file format can either be written with expanded or contracted superatom groups (specified as type SUP in property G_TYPE and group label in G_NAME ), the default is to write them contracted. If this flag is set, the expanded form is used instead. This option affects few file formats (currently cdx and cdxml ). It does not perform expansion of superatoms which are only present as a single pseudo atom in the ensemble by decoding their tag (see ens expand command to achieve this). Rather, it expects the full set of atoms of the expanded form in the ensemble, plus one or more properly set up group objects indicating the atoms of the expanded form of a functional group or fragment which are not shown in the contracted style. If these groups are present, only the first atom in any group is shown, with the G_NAME data as atom tag, which overrides all other label information. However, the output file still contains the hidden atoms and their data. Tools like ChemDraw use this data to support interactive group expansion utilizing the original layout coordinates of the previously hidden atoms and other information.
• synchronous - use synchronous writes for files which normally use buffering to increase performance, for example in the bdb format.
• splitmol - Split output into individual ensembles and write each molecular fragment as a separate record.
• upgrade - if this flag is set, and the format of a file is not of the most current version, but there is an upgrade function available in the support library, invoke the upgrade function to change the file layout to the most current version. The bdb module is the only one which currently supports this feature.
• write0d - write records without coordinates if possible
• write2d - write 2D records if possible
• write3d - write 3D records if possible
• writearo - write aromatic bonds instead of a Kekulé form if the file format supports this. An example where this makes sense are SMILES files. A counterexample are MDL Molfiles - you can enforce the encoding of aromatic bonds of non-query structures as the aromatic query bond type with this option, but that is technically incorrect and violating the format specification. Nevertheless, there are third party programs which require data in that format aberration for further processing.
• writecolor - write atom and bond colouring information if this is an optional part of the file format specification.
• writeenzymes - if the output data contains enzyme superatoms, include them in the output if that is an option. The SDF3000 I/O module is an example for a module recognizing this flag.
• writelabels - write explicit atom labels, as defined in the attribute atomlabelproperty , if the file format supports it. This does not override the natural numbering of the written atom objects. It only applies to formats which support a parallel user-defined labelling scheme, such as CDX/CDXML .
• writename - write a structure name section if this is optional information in the output. An example are SMILES files.
• writekey
  This attribute is only used in certain library configurations which have been configured to restrict write access to specific types of files. The key and data computed from the file name must together match the signature. Usually restricted applications have a compiled-in signature, and one or more write keys which enable write access to the same number of specific files.
• writekeysignature
  This attribute is used for certain library configurations which have been configured to restrict write access to specific files. This signature is required to verify the write access key.
• writekeystatus
  A read-only attribute which reports the access key status for a file for which a write key has been specified. It can be unchecked, verified or error.
• writelist
  A list of properties that should be included in the output if the file format supports this. Standard properties defining basic connectivity etc. usually do not need to be listed because they are written out by default where needed. Normally, this list contains only ensemble- or reaction-level properties, like SD data fields. Properties listed both in the write list and the drop list are not written. By default properties listed here are not computed. If they are not already present in the output objects, they are omitted. The computeprops bit in the writeflags attribute can be used to automatically initiate a computation attempt. Still, if a computation attempt fails, the output of that property data is silently omitted.
• x
  If the toolkit was compiled with factory support, this is the x coordinate of the object icon on its workbench. This attribute can be changed.
• y
  If the toolkit was compiled with factory support, this is the y coordinate of the object icon on its workbench.This attribute can be changed.

The attribute list above is also referenced by the molfile set command. This is the reason why it contains information about the read-only status of the individual attributes. Only attributes that can be set can be addressed by the molfile set command.

For the use of the optional property parameter list argument, refer to the documentation of the ens get command.

Filters in the optional filter set must apply directly to the file object. Filters which operate on other object types are ignored.

Variants of the molfile get command are molfile new, molfile dget, molfile jget, molfile jnew, molfile jshow, molfile nget, molfile show, molfile sqldget, molfile sqlget, molfile sqlnew, and molfile sqlshow . These commands only work on property data and cannot be used to access attributes..

molfile getline

molfile getline filehandle ?skiprecord?

f.getline(?skiprecord=?)

Read a text line from the file, with repositioning of the file pointer. This operation is only possible on text files which have been opened for reading. The command is not frequently used, because it tends to disrupt the normal file record parsing.

If the skiprecord boolean argument is set, the file is positioned to the beginning of the next record after the line has been retrieved.

The command returns the line read. Line termination characters are removed.

molfile getparam

molfile getparam filehandle property ?key? ?default?

f.getparam(property=,?key=?,?default=?)

Retrieve a named computation parameter from valid property data. If the key is not present in the parameter list, an empty string is returned ( None for Python ). If the default argument is supplied, that value is returned in case the key is not found.

If the key parameter is omitted, a complete set of the parameters used for computation of the property value is returned in dictionary format.

This command does not attempt to compute property data. If the specified property is not present, an error results.

Example:

molfile getparam $fhandle F_QUERY_GIF format

returns the actual format of the data in that property, which could be a GIF , PNG or a bitmap format.

molfile hloop

molfile hloop filehandle objvar ?maxrec? body

f.hloop(function=,?maxloop=?,?variable=?)

Molfile.Hloop(filename,function=,?maxloop=?,?variable=?)

This command is functionally equivalent to the molfile loop command. The difference is that for the duration of the loop command hydrogen addition is enabled for the file handle. The original hydrogen addition mode of the file object is restored when the loop finishes.

molfile hread

molfile hread fhandle ?datasethandle/enshandle/#auto/new? ?recordcount?

molfile hread fhandle ?datasethandle/enshandle/#auto/new? ?parameterdict?

f.hread(?target=?,?parameters=?)

Molfile.Hread(filename,?target=?,?parameters=?)

This command is identical to the molfile read command, except that standard hydrogen addition is enabled for the duration of the command. The original hydrogen mode is reset when the command completes.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

Example:

set eh [molfile hread “myfile.mol”]

This is a simple single-record structure input with hydrogen addition, using a file name instead of a file handle. The file is automatically opened and then close for the duration of the command.

molfile jget

molfile jget filehandle propertylist ?filterset? ?parameterdict?

f.jget(property=,?filters=?,?parameters=?)

Molfile.Jget(filename,property=,?filters=?,?parameters=?)

This is a variant of molfile get which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects.

The Python class method is a one-shot command. The transient dataset created from the initialization items is automatically deleted when the command finishes.

molfile jnew

molfile jnew filehandle propertylist ?filterset? ?parameterdict?

f.jnew(property=,?filters=?,?parameters=?)

Molfile.Jnew(filename,property=,?filters=?,?parameters=?)

This is a variant of molfile new which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects.

The Python class method is a one-shot command. The transient dataset created from the initialization items is automatically deleted when the command finishes.

molfile jshow

molfile jshow filehandle propertylist ?filterset? ?parameterdict?

f.jshow(property=,?filters=?,?parameters=?)

Molfile.Jshow(filename,property=,?filters=?,?parameters=?)

This is a variant of molfile show which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects.

The Python class method is a one-shot command. The transient dataset created from the initialization items is automatically deleted when the command finishes.

molfile list

molfile list ?filterlist=?

Molfile.List(?filters=?)

This command returns a list of the molfile handles currently registered in the application. This list may optionally be filtered by a standard filter list.

Example:

molfile list

lists the handles of all open molfiles in the application.

molfile lock

molfile lock filehandle propertylist/objclass/all ?compute?

f.lock(property=,?compute=?)

Lock property data of the file handle, meaning that it is no longer subject to the standard data consistency manager control. The data consistency manager deletes specific property data if anything is done to the file handle which would invalidate the information. Property data remains locked until is it explicitly unlocked.

The property data to lock can be selected by providing a list of the following identifiers:

• Property names
  Valid property instances on the file object are locked. If the boolean compute flag is set, an attempt is made to compute the property if it is not yet present. Otherwise, a request to lock non-existent data is silently ignored. It is not possible to lock individual property fields.
• all
  All valid file properties are locked. The compute flag is ignored.
• molfile
  This is an object class identifier. All property data which is controlled by the file major object and attached to the specified object class is locked. Since files do not incorporate minor objects, this identifier is equivalent to all .

The lock can be released by a molfile unlock command.

This command is a generic property data manipulation command which is implemented for all major objects in the same fashion and is not related to disk file locking. Disk file locks can be set or reset by modifying the molfile object attribute lock. This is explained in more detail in the paragraph on the molfile get command.

The return value is the original molfile handle or reference.

molfile loop

molfile loop filehandle objvar ?maxrec? body

f.loop(function=,?maxloop=?,?variable=?)

Molfile.Loop(filename,function=,?maxrecords=?,?variable=?)

for obj in f:

Execute a loop over the file. Objects are read from the file from the current file position onwards. The type of object read (usually ensemble or reaction, but in principle it could also be a table or dataset object) depends on the read scope of the file. In the Tcl variant, the handle of every object input from a file record is assigned to the specified Tcl object variable. Next, the Tcl script code in the body argument is executed. The body code typically uses the value of the variable to perform some operations with the currently read object. After the body code has been executed, the object which was just read is deleted, and the cycle is repeated, either until EOF has been reached on the file (the default), or the maximum number of records specified by the optional parameter has been reached, whichever comes first. In either case, no error is generated when the end of file has been reached. Setting the maximum record count parameter to an empty string, or to a negative value, results in the default processing style running until the end of the file.

For Tcl scripts, within the loop, the standard Tcl break and continue commands work as expected. If the body script generates an error, the loop is exited. If the loop code generates an error, the loop is terminated and the error reported. Programs should not expect that the same object handle value stored in the variable is reused in each iteration.

Since the input objects are automatically deleted after they have been processed, it is not required to delete them in the loop code. Deletion requests on the loop object executed within the loop are ignored. Any other operation on the structure object is allowed. The loop code may perform repositioning operations on the input file, but not close it.

The Python version of the loop method does intentionally have a different argument sequence for convenience. The function argument may either be a multi-line string (similar to the Tcl construct), or a function reference. Functions are called with the reference of the current loop object as single argument, and have their own context frame, so that the specification of a reference variable is not generally useful in that call style, though is is allowed. For string function blocks the code is executed in the local call frame, and the variable with the current object reference is visible locally. Script code blocks must be written with an initial indentation level of zero. Within the Python functions, the normal break and continue loop control commands cannot be used to to scope limitations. Instead, the custom exceptions BreakLoop and ContinueLoop can be raised. These are automatically caught and processed in the loop body handler code.

In Python , there is also an object iterator so that simple loops over structure file contents can be written with a for statement. The molfile object iterator is of the self style (i.e. there is one per molfile , these are not independent objects), so nesting them is not possible on the same dataset. There is no distinct hloop iterator, but that can be emulated by setting the hydrogens attribute on the molfile object.

Python object loop constructs and their peculiarities are discussed in more detail in the general chapter on Python scripting.

The return value is the number of processed records.

Example:

set th [table create]

table addcol $th E_NAME

table addcol $th E_WEIGHT

molfile loop $myfile eh {

	table addrow $th #auto end [list [ens get $eh E_NAME] [ens get $eh E_WEIGHT]]

}

This sample loop successively reads all records from the file and stores the ensemble handles in variable eh . In the loop body, the handle is used to extract name and molecular weight information from the structure and store it in a table object.

molfile lopen

molfile lopen filelist ?mode? ?attribute value?...

molfile lopen filelist ?mode? ?attributedict?

Molfile(filenamesequence,?mode=?,?attribute=?)

Molfile.Open(filenamesequence,?mode=?,?attributes=?)

Molfile.Lopen(filenamesequence,?mode=?,?attributes=?)

Open a list of files as a virtual file. The files identified by the file list items are implicitly concatenated in the list order. In addition to normal files, the standard set of special input types such as URL s, pipes, Tcl file handles or standard channels may be used. This command returns a single file handle, regardless of the number of input files passed as parameter.

A file list can only be opened for read operations on input objects. Writing, appending, updating or string input are not supported.

Most input file operations can be performed on virtual files. One important exception is currently file scanning with query expressions. This only works for lists of standard sequential files, not files which contain optimized query layouts, such as the native Cactvs CBS and BDB file formats. These can only be used as a single file for molfile scan commands. However, simple structure input is possible across file boundaries even with these formats.

The rest of the options are processed in the same way as the standard molfile open command.

In the Python interface, there is no distinction between the lopen and open commands, because it can be unequivocally established whether the filename argument is a sequence (tuple or list of filenames), or a single file name. The interpretation is performed according to the argument type. The Python command always uses a file attribute dictionary, not a keyword/value argument set.

Example:

set fhandle [molfile lopen [lsort [glob *.mol]]]

molfile max

molfile max filehandle property ?filterset?

f.max(property=,?filters=?)

Molfile.Max(filename,property=,?filters=?)

Scan the file for the maximum value of the specified property from the current read position to the end of the file. If no error occurs, the file is at end-of-file after the end of the command.

If a filter set is provided, it is applied to the objects read from the file during the scan, not the molfile object proper. Objects which do not pass the filter are ignored.

The property may correspond either to a data column in the file, or to a computable property on the structure or reaction objects read during the scan. Read objects are transient and automatically discarded. The property argument may contain a field specification, and in that case, only the field value is compared.

The maximum value determination uses the standard property comparison function associated with its data type. For properties which are implicitly defined during file I/O, an explicit property definition with a correct data type may be beneficial. For example, when testing the values of an SD data field, by default the data is read as an implicitly created string property. If the field content is actually an integer, the comparison as a string value does not yield the same results as when the data is compared as an integer. For file formats which encode a proper data type of its contents this is not necessary.

The return value is the maximum property or property field value found, or an empty string if no input was processed.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile metadata

molfile metadata filehandle property ?field ?value??

f.metadata(property=,?field=?,?value=?)

Obtain property metadata information, or set it. The handling of property metadata is explained in more detail in its own introductory section. The related commands molfile setparam and molfile getparam can be used for convenient manipulation of specific keys in the computation parameter field. Metadata can only be read from or set on valid property data.

Valid field names are bounds , comment , info , flags , parameters and unit .

molfile min

molfile min filehandle property ?filterset?

f.min(property=,?filters=?)

Molfile.Min(filename,property=,?filters=?)

Scan the file for the minimum value of the specified property from the current read position to the end of the file. If no error occurs, the file is at end-of-file after the end of the command.

If a filter set is provided, it is applied to the objects read from the file during the scan, not the molfile object proper. Objects which do not pass the filter are ignored.

The property may correspond either to a data column in the file, or to a computable property on the structure or reaction objects read during the scan. Read objects are transient and automatically discarded. The property argument may contain a field specification, and in that case, only the field value is compared.

The minimum value determination uses the standard property comparison function associated with its data type. For properties which are implicitly defined during file I/O, an explicit property definition with a correct data type may be beneficial. For example, when testing the values of an SD data field, by default the data is read as an implicitly created string property. If the field content is actually an integer, the comparison as a string value does not yield the same results as when the data is compared as an integer. For file formats which encode a proper data type of its contents this is not necessary.

The return value is the maximum property or property field value found, or an empty string if no input was processed.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile mutex

molfile mutex filehandle mode

f.mutex(mode)

Manipulate the object mutex.

During the execution of a script command, the mutex of the major object(s) associated with the command are automatically locked and unlocked, so that the operation of the command is thread-safe. This applies to toolkit builds that support multi-threading, either by allowing multiple parallel script interpreters in separate threads or by supporting helper threads for the acceleration of command execution or background information processing.

Going beyond this automatic per-statement protection, this command locks major objects for a period of time that exceeds a single command. A lock on the object can only be released from the same interpreter thread that set the lock. Any other threaded interpreters, or auxiliary threads, block until a mutex release command has been executed when accessing a locked command object. This command supports the following modes:

• lock
  Increase the recursive mutex lock count on the object. The command returns the current lock count after the command, excluding the transient single-command lock.
• reset
  Release all persistent locks on the object, if any exist.
• test
  Return the current persistent lock count on the object. This excludes the transient per-command lock.
• unlock
  Decrease the recursive lock count on the object. The command returns the current lock count after the command, excluding the transient single-command lock. Unlocking an object which has not been persistently locked results in an error.

There is no trylock command variant because the command already needs to be able to acquire a transient object mutex lock for its execution.

The command returns the current lock count.

molfile need

molfile need filehandle propertylist ?mode? ?parameterdict?

f.need(property=,?mode=?,?parameters=?)

Standard command for the computation of property data, without immediate retrieval of results. This command is explained in more detail in the section about retrieving property data.

The return value is the original file handle or reference.

Example:

molfile need $fhandle F_AVERAGE_ATOM_COUNT

molfile new

molfile new filehandle propertylist ?filterset? ?parameterdict?

f.new(property=,?filters=?,?parameters=?)

Molfile.New(filename,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the molfile get command. The difference between molfile get and molfile new is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile nget

molfile nget filehandle propertylist ?filterset? ?parameterdict?

f.nget(property=,?filters=?,?parameters=?)

Molfile.Nget(filename,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the molfile get command. The difference between molfile get and molfile nget is that the latter always returns numeric data, even if symbolic names for the values are available.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile nnew

molfile nnew filehandle propertylist ?filterset? ?parameterdict?

f.nnew(property=,?filters=?,?parameters=?)

Molfile.Nnew(filename,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data and attributes. It is explained in more detail in the section about retrieving property data.

For examples, see the molfile get command. The difference between molfile get and molfile nnew is that the latter always returns numeric data, even if symbolic names for the values are available, and that property data re-computation is enforced.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile open

molfile open filename ?mode? ?attribute value?...

molfile open filename ?mode? ?attributedict?

Molfile(filenamesequence,?mode=?,?attribute=?)

Molfile.Open(filenamesequence,?mode=?,?attributes=?)

This command opens a structure file or other input source for input or output. The filename argument may be any of:

• A disk file

This is the most common case. File names may be absolute or relative. On the Windows platform, the path naming follows the Tcl convention, with backslashes replaced by forward slashes, and optional drive letters, in the same way as the standard Tcl open command. Tilde substitution is also supported and built into the command. In case a file name could possibly collide with a reserved name, the file name can be prefixed with ./ in order to force interpretation as a file name. File name expansion can be conveniently performed by means of the standard Tcl glob command. File names must currently be spelled in the 8-bit ISO8859-1 character set. Unicode file names are not yet supported. On Unix platforms, named pipes and sockets may also be opened with this command.

Examples:

molfile open ./stdout r

molfile open ~theuser/data/newleads.sdf

molfile open C:/temp/calicheaamycin.pdb w

• A standard channel

The file names stdout , stderr and stdin are reserved and connect the file handle to a standard I/O channel. stdout and stderr can only be opened for output, and stdin can only be read from. The character ’-’ (minus) is an alternative name for standard input.

Example:

molfile open stdout w format mdl

molfile open ./stdout 

The first line opens an MDL file for output on standard output. The second sample line opens the file in the current directory which is named “stdout” for input. By prefixing file names with directory information any file with a reserved name can be opened as standard file.

• A scratch file

The name scratch is reserved as the name of a generic scratch file. The file is initially opened for writing, but may be switched to input later by a molfile toggle command. The magic filename is translated into the name of a platform-specific temporary file. Every invocation of this command variant generates a new scratch file, with a different name. The true file name can be obtained with an attribute query:

set fh [molfile open scratch]

set name [molfile get $fh name]

Scratch files are automatically deleted when they are closed, or when the program exits.

• A pipe

If a file name starts with a vertical bar character “|”, a pipe is opened from (in read mode) or to (write mode) the commands listed after the bar.

Example:

molfile open “|gzip >thefile.sdf.gz” w format mdl

When the file is closed, the pipe and all programs connected to it are automatically shut down. Pipes cannot be rewound, or switched from input to output and vice versa.

• An URL

The Cactvs toolkit supports reading from various types of URLs. Currently, the schemes ftp , http, file and gopher are supported. file URLs are just another notation for normal disk files, as described above. From among the other URL schemes, only ftp and http connections may be opened for writing. The support for ftp URLs includes username and password components. If the server side supports it, passive ftp is the preferred mode. Http connections opened for writing use the PUT http command, which often is not activated in standard Web server set-ups and may therefore be of limited practical usefulness. URL connections can be rewound and backspaced, but this is costly because the existing connection has to be disconnected and the initial data from the beginning of the file to the desired position needs to be re-transferred and discarded.

Examples:

set fh [molfile open http://www.yourcompany.com/repository/jcamp/ir1.jcp]

molfile open ftp://yourid:yourpasswd@ftp.yourcompany.com/upload/ideas.sdf

• A directory

If the target is a directory, all files in the directory are scanned. Those files which were identified as structure data files by any of the built-in or currently loaded I/O module extensions are concatenated to a virtual file which comprises all individual files. The order in which the files are concatenated is largely unpredictable, because it is defined by the order of the file name entries in the directory, and not any alphabetic sort criterion. The files may be of different formats, and may be any mixture of single-record and multi-record files. Subdirectories of the opened directory are not entered by default, but this may be activated by appending a ‚d‘ character to the open mode. Directories may only be opened for reading.

Example:

set fh [molfile open .]

set fh [molfile open $mydir rd]

The second example opens not only perceived structure files in the source directory, but also in all subdirectories thereof.

• A string

The Cactvs toolkit can read most file formats directly from a string. There is no need to write structure data which was obtained as a string image to a temporary file to decode it. Data strings are opened as structure file with mode ’s’. Only input is possible, but navigation within the string with molfile rewind etc. works as expected. The complementary molfile string command can be used to generate a string image of a file record.

Example:

set fh [molfile open $thedatablob s]

set eh1 [molfile read $fh]

set eh2 [molfile read $fh]

molfile close $fh

• A Tcl file or socket handle, or a Python file reference

Any file name beginning with file or sock , and where the rest of the file name is a sequence of digits, are interpreted as references to Tcl file handles.

Example:

set tcl_fh [open thefile.txt w]

set cactvs_fh [molfile open $tcl_fh w]

A Tcl handle can only be accessed by this command in a mode which is compatible to the mode it was opened with, i.e. it is not possible to write to a file via a Tcl handle if it was opened for reading. If a structure file coupled to a Tcl handle is closed with a molfile close command, the Tcl handle remains valid, and my be used freely once the association to the structure file I/O object is broken. Closing the Tcl file handle while the piggybacked structure file handle is being used is illegal. No input, output or positioning should be performed on the Tcl handle with standard Tcl commands while it is being referred to by a molfile object.

In the Python interface, the same mechanisms apply, except that the argument is a Python file handle object.

The Tcl handle functionality is not available on Windows, because on this platform Tcl internally uses Windows handles for I/O, while the Cactvs toolkit builds on standard Posix C library FILE* pointers.

• A virtual file

Some I/O modules implement access to a variety of information sources as a virtual file, which has neither a presence on the local disk, nor is one of the standard magic file names or access methods. Such virtual file names are by convention written with pointed brackets.

Example:

set fh [molfile open <pubchem>]

This command loads the PubChem virtual file access module, and returns a handle which may be used in a similar fashion as, for example, a handle to a huge local SD file. Depending on the I/O module, various operations on the handle may be optimized to be performed remotely. For example, the PubChem module offloads as many query operations of molfile scan commands as possible to the NCBI computers and downloads result structures only if they are needed as results, or query sub-expressions were specified which cannot be processed by the NCBI system.

The first optional parameter is the file access mode. It may be one of:

• r
  Open for reading, but with the option of later changing the mode to writing or appending. This is the default.
• rt
  As above, but automatically start a thread which immediately starts gathering file status information, such as the record count and record positions. This mode can be useful when operations, such as reading data for display, are to be commenced immediately, but ultimately overall record count information needs to be displayed, which can take a while to collect for larger files. The status thread is only started for rewindable files, and has no effects on files which directly provide record index and total record count information. Operations which would duplicate the efforts of the statistics thread, such as molfile count , are automatically blocked until the thread has completed,, and then directly use its results. Operations which change the nature of the access to the file, or its record contents or positions, silently terminate the status thread.
• ro or rot
  Open for read-only. If a file is opened in this mode, it is not possible to switch to write access later via a molfile toggle command. If the file permissions do not allow write access, the standard ‘r’ mode automatically falls back to this variant. Mode ‘rot’’ is also possible and additionally starts a file status thread (see mode ‘rt’).
• w
  Open for writing. If the file exists, it is overwritten. If not overridden by an explicit format specification, the file format is inferred from the suffix of the file name, if possible.
• a
  Open for appending. If the file exists, new data written to it is appended. If not overridden by an explicit format specification, the file format is inferred from the suffix of the file name, if possible. Not all file formats support appending.
• u
  Open an existing file for updating, i.e. the replacement of specific records. Not all file formats support this mode. It is generally useful for database-style formats such as Cactvs BDB and, to a limited degree, CBS . It can also be used for simple record sequence files like SD, though in this case it can be inefficient because a lot of data copying may be required to adjust the file layout. For single-record file formats, this command is not useful, and multi-record files which are not simple record sequences and for which the I/O module does not provide a special function, this mode is not supported.
• s
  Open string image of a file. If the mode is used, the file name is interpreted as an in-memory image of a structure file in any of the formats the toolkit understands, and not as a file name, URL, or any of the other types of input objects. Binary file formats may be used with this command.
• p
  Open in pipe reader mode. The input is expected to be a pipe or socket, where sporadically new data is posted. If an attempt is made to read from the file, a check is made if any data is present. If no data is waiting, the input command immediately returns without blocking. At a later time, new data may be present and the input succeed. If just a single byte of data is present on a pipe input channel, the read routine hangs on until the record for which input has begun has been read completely.
• R, Ro, Rot
  Open the file for reading and infer the format of the file from the suffix alone, without actually attempting to read the initial section of the file contents, which is the default method to determine its format. This mode can be useful in case the data contains text with embedded structure data, where the plain text is read by scripted commands and the occasional embedded structure or reaction record is to be extracted by means of molfile read commands. For such files, an automatic format detection would fail. The ‘o’ and ‘t’ flags may also be appended, and have the same meaning as in the standard ‘r’ mode.

For some files and file formats, two more mode characters have meaning if appended to the primary mode: They are silently ignored if the file argument or file format do not support them.

• d
  Recursive opening. This is for example useful when opening a directory as a pseudo file for input. If this flag is set, the all files recursively found under the specified directory form the virtual file, not just the files directly located under the specified directory.
• f
  Fast mode. The file is opened for maximum performance, taking chances with respect to data integrity in case of program or computer crashes, etc. One file format where this flag is supported is the Cactvs Data Archive ( CDA ) format.

The remaining parameters of the molfile command are optional keyword/value pairs, or alternatively a single dictionary with the same function. The processing of these parameters is exactly the same as in the molfile set command.

In the Python interface, there is no distinction between the lopen and open commands, because it can be unequivocally established whether the filename argument is a sequence (tuple or list of filenames), or a single file name. The interpretation is performed according to the argument type. The Python command always uses a file attribute dictionary, not a keyword/value argument set.

Example:

set fhandle1 [molfile open thefile.pdb]

molfile set $fhandle1 hydrogens add nitrosyle ionic

set fhandle2 [molfile open thefile.pbp r hydrogens add nitrostyle ionic]

The first two lines and file final line perform exactly the same task: Open an input file, and set up input flags so that a complete set of hydrogens is added, and nitro groups and similar groups are converted to an ionic (as opposed to pentavalent) representation.

When a file is opened for reading, its format is automatically determined. Do not use the format attribute except under very special circumstances.

The command returns the file handle or reference of the opened input file. This is the handle which is required by most other molfile commands which refer to an opened file.

Depending on the encoding of the opened file, the actual access mode to the file may be different than expected. In case a disk file is compressed with gzip or bzip2 , the file is opened via a pipe to the responsible decompressor program. Likewise, an UCS-2 encoded file is opened via a pipe to the iconv program which converts the contents to the UTF-8 encoding. Files which are opened indirectly via such helper pipes have different access characteristics than directly addressed files. For example, backspacing is expensive, because the pipe has to be closed, re-opened, and the data stream skipped to the desired position. This takes much longer than simply repositioning a file pointer.

molfile peek

molfile peek filehandle

f.peek()

Molfile.Peek(filename)

This is a convenience command which combines three operations: Read the next record ( molfile read ), discard whatever object is read by the command as configured by the file handle settings ( ens/reaction/dataset delete ), and backspace by one record ( molfile backspace ).

The purpose of this command is to learn more about the contents and characteristics of the file by performing a full parse of the next record. One of the most common applications of the command is to detect the field structure (such as SD data fields) of that record before the read. The detected field set is consequently the return value of the command, equivalent to a molfile get filehandle fields statement.

This command can only be used on files which can be backspaced, or at least rewound and skipped forward to the last position. It cannot be used on files not opened for input, on empty files, or files which are at EOF . In all these cases, an error results.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile properties

molfile properties filehandle ?pattern? ?noempty?

f.properties(?pattern=?,?noempty=?)

Generate a list of the names of all properties attached to the molfile object. Optionally, the list may be filtered by a string match pattern.

In most cases, this list is empty. Only structure file properties, such as F_COMMENT , etc., are listed, but no object attributes, such as readflags , nitrostyle , etc. Few file formats support the concept of storing file-level properties, and therefore an empty property set is usually reported. Since file objects do not contain minor objects, and currently cannot be a member of other major objects such as datasets or reactions, no properties belonging to other classes except file objects are ever listed.

If the noempty flag is set, only properties where at least one data element is not the property default value are output. By default, the filter pattern is an empty string, and the noempty flag is not set.

The property list may become modified by input operations. In some cases, the defined file-level properties may vary with the record position, or may become only available only after the first input operation, not immediately after opening the file.

The command may be abbreviated to props instead of the full name properties .

Example:

set plist [molfile properties $fhandle]

molfile purge

molfile purge filehandle propertylist/molfile/all ?emptyonly?

f.purge(?properties=?,?emptyonly=?)

Delete property data from the molfile object. Only molfile property data may be deleted with this command (these usually have a F_ prefix). Molfile attributes are not deletable.

If the optional flag is set, only file property values which are identical to the default of the property are deleted. By default, or when this flag is 0, properties are deleted regardless of their values. In case a listed property is not present, or not a file property, the request is silently ignored, but using property names which cannot be resolved leads to an error. If the object class name molfile is used instead of a property name, all file-level property data is deleted from the molfile object.

The command returns the original molfile handle or reference.

Example:

molfile purge $fhandle F_COMMENT

molfile purge $fhandle all

The first command deletes a specific property, the second command deletes all file property data associated with the handle.

molfile putline

molfile putline filehandle ?lines?

f.putline(?line?,...)

Write user-specified string lines to a file, bypassing the normal record writing mechanism. This operation is only supported on files which are opened for output and contain text data. The lines should not contain end-of-line characters. These are automatically supplied depending on the file object configuration set in the eolchars attribute.

The command returns the original file handle or reference.

molfile read

molfile read fhandle ?datasethandle/enshandle/#auto/new? ?recordcount?

molfile read fhandle ?datasethandle/enshandle/#auto/new? ?parameterdict?

m.read(?target=?,?parameters=?)

Molfile.Read(filename,?target=?,?parameters=?)

This important command reads chemistry objects from a structure or reaction file. The type of objects returned depends on the read scope of the file. They can be ensembles, reactions, or datasets. Read scope mol returns single-molecule ensembles, but (with I/O modules supporting this feature) reads only individual molecules into the output ensemble, splitting a multi-molecule file data ensemble if necessary. The return value of the command is a list of the handles or references of all objects which were generated, except when the #auto dataset creation method was used, or an unlimited number of objects was read into a dataset. In that case, the recipient dataset handle or reference is returned.

By default, the returned objects are not a member of any dataset. If a dataset handle is passed as fourth parameter, the returned objects are appended to that dataset if possible. The special value #auto or new creates a new dataset as container. This is equivalent to using the nested statement [dataset create] as dataset handle argument. If the fourth parameter is an ensemble handle, and the object read from the file is also an ensemble, the read data is stored in the shell of the old ensemble, after all old ensemble data has been deleted. Its object handle remains unchanged, as is its dataset membership. The reuse of reaction handles is currently not supported. This parameter can be skipped by specifying an empty string.

In addition to passing an empty string, or a simple dataset or ensemble handle or reference, as the fourth command argument, a list/tuple consisting of a handle or reference and a modifier flag set can be specified. The only flag value which is currently recognized is checkroom . If that flag is set, and the input objects are to become members of a dataset with enabled maximum size or insertion mode control, a test is made whether the dataset has sufficient room to allow the insertion of the new object(s), or whether a suitable alternative action is configured to handle the read object in a different fashion, such as discarding it. If that is not the case, the command returns immediately, without performing any input, and returns an empty string ( None for Python ). If the test succeeds, the input operation is atomic, since the dataset is locked for the full duration of the command, so that no other threads can manipulate its status between the initial check and the file input result object transfer.

The final optional parameter is either a single argument specifying the number of objects which should be read, or a dictionary with key/value attributes. The default is equivalent to passing a simple numerical value of one, in the first, simple format. In order to read until the end of the file, the special value all may be used instead of a numerical count. With an all parameter value, the input operation is finished when no more data is available on the file. Until this condition is met, an unlimited number of records is read. No error is generated when EOF is met. There are also no EOF errors reported if a numerical record count of more than one was specified, and at least one object could be successfully read. Another magical value of the simple argument form is batch , which is substituted by the batch record set size configured on the molfile handle (see molfile get/set ).

In the second form of the final parameter, an attribute dictionary is persistently applied equivalent to a molfile set command before the input commences. Standard file handle attributes and an input limit may be both set in parallel by using the special attribute name limit as part of the dictionary. It is only recognized in this context, but not with molfile set or molfile string . The allowed values of the limit attribute are the same as in the simple command variant.

The command raises an error if input could not be completed, regardless whether the reason is a file syntax error, or simple EOF (but see above for exceptions). If an input error occurs, the EOF attribute of the file handle should therefore be checked in order to distinguish between these two conditions. In case the input file was opened for pipe reading (mode ’p’), or is connected to a Tcl channel, an EOF report may only indicate that no current data is available on the pipe or Tcl channel, but it could still arrive at a future point in time.

Examples:

if {[catch {molfile read $fhandle} ehandle]} {

	if {![molfile get $fhandle eof]} {

		puts “Error: $ehandle”

	}

} else {

	puts “Read [ens get $ehandle E_NAME]”

}

The prototypical snippet above shows the input of the next ensemble record from a previously opened file, with proper error checking.

molfile read “acd.sdf” [dataset create] all

This sample command reads a complete input file (we are using the single-operation feature of the molfile command to open and close the file acd.sdf automatically for the duration of this command) into a newly created dataset in memory. Reading huge datasets is of course not necessarily a good idea without large amounts of RAM . On typical current workstations, 10.000 or 20.000 compounds are no problem, but beyond that the risk of running out of memory is a real problem.

In default mode, hydrogens are not automatically added to the read items with the exception of file formats where a clearly defined hydrogen set is implied, like SMILES , but not MDL molfiles ). This is probably the most common problem developers run into when using this command. Generally, Cactvs wants to operate on hydrogen-complete structures, and its internal file formats use explicit hydrogen encoding. Working with hydrogen-incomplete structures is possible, and sometimes useful, but can lead to unexpected artifacts like radical centers on atoms with missing hydrogens. In order to continue with a standard hydrogen set, the most common options are:

• Use molfile set to change the hydrogens attribute to a suitable automatic hydrogen addition mode. The molfile open command can also configure this attribute directly in a single statement, or you can use the attribute dictionary form of this command for the same purpose.
• Use molfile hread instead of molfile read
• Execute a ens/reaction/dataset hadd command after the input object is returned and before processing the read objects further.

molfile ref

Molfile.Ref(identifier)

Python only method to get a molfile reference from a handle or another identifier. For molfiles , other recognized identifiers are molfile references, integers encoding the numeric part of the handle string or the UUID of the molfile object.

molfile rename

molfile rename filehandle srcproperty dstproperty

f.rename(srcproperty=,dstproperty=)

This is a variant of the molfile assign command. Please refer the command description in that paragraph.

molfile reorganize

molfile reorganize filehandle

f.reorganize()

This command only has an effect for file formats for which the I/O module provides a reorganizer function. This function typically optimizes and compacts the file for input and queries, and should usually be called after all records have been written. Writing to a reorganized file is typically at least initially slower than writing to a file which has not been processed.

The function returns a boolean value indicating whether any reorganization has actually been performed. In case the command is applied to a file which is not writable, an error results.

molfile rewind

molfile rewind filehandle

f.rewind()

Reposition the file before first record, and clear all error status information. If the file is already at the first record, and no error condition is set, this command does nothing.

Not all file channels can be rewound, and for some which can, it can be an expensive operation. For example, standard input or pipe input channels are not rewindable, and an FTP URL channel has to be closed and re-opened.

Rewinding a virtual file set positions the file pointer before the first record of the first file in the set.

Standard text-stream style output files can be rewound, too. This effectively truncates them. Files which are opened for appending are truncated to their original length.

Rewinding is not necessary in all cases. The molfile scan command automatically rewinds the input file if it is at EOF at the begin of a scan.

The return value of the command is the original file handle or reference.

molfile rewrite

molfile rewrite filehandle recordlist propertylist ?values? ?query? ?callback?

m.rewrite(records=,properties=,?values=?,?query=?,?callback=?)

This command updates specific property fields in a file, without rewriting the complete record. This is only supported if the file was opened for writing or updating, and the I/O module for the format of the file supports this operation by a special function. This typically limits the applicability of this command to database-style file formats such as Cactvs CBS and BDB .

The record list parameter is either a simple sequence of numerical records, with one as the first file record, or one of the special values all (all file records are updated), current , next , previous (the indicated record is updated), or a table handle, optionally followed by a table column name. In the last case, the table is expected to contain the data for rewriting, and in case a column name is specified, that column should contain the applicable record numbers. If the table version is selected without a record column, the file records from one to the number of table rows are updated. None of the special values can be combined with the simple numerical record sequence style. If the parameter is a numerical record sequence, the order of the records is significant.

The values sequence can be empty, or it must match the length of the property list. In the latter case, every specified value must be a valid value for the property in the same list index position. Note that while it is possible to manipulate multiple records in one step with this command, it is not possible to assign a different set of values to the data fields for each processed record. For this operation, multiple rewrite statements must be issued. If the value list is absent, or empty, the values are recomputed from the structure or reaction object that is temporarily read from the file record for this purpose. This is a useful feature in case the computation function for a computable property has changed. In case the record list references a table instead of a numerical record list or a magic record name, the value list is ignored. Instead, the table is expected to contain table columns which match the properties in the list, but not necessarily in the same column order, or containing exclusively the properties in the list.

The optional query argument is a query expression in the same style as used in the molfile scan command. If a filter expression is supplied, only records which match the expression are changed. Non-matching records are skipped. In case no filter is used, all records selected by the record list are processed

After processing, the file pointer is on the last processed record.

If the name of a callback procedure is specified in the Tcl interface, it is called after each processed record. The Tcl procedure arguments depend on the processing mode. In case of table-based processing, the arguments are the table handle, the current table row, the file handle and the current file record. In the Python interface, the callback is either a function name given as string, or a function reference.

This command is not fully implemented yet. CBS files currently only support re-computation of property data from object data, not updates from explicit value lists. Neither BDB nor CBS I/O modules currently call the Tcl or Python callback procedures except in table-based processing mode.

The command returns the number of updated records.

Example:

molfile rewrite $fh current E_NAME “Black tar, grade A”

molfile rewrite $fh all E_XLOPG2

molfile rewrite $fh [list $mytable records] [list E_IDENT E_REGID]

The first command changes the property field E_NAME in the current record to the specified value. The second variant recomputes all E_XLOGP2 values in the file from the stored structure data - for example after updating the computation function of that property, or having added it as a new field to the file. The final version changes the fields E_IDENT and E_REGID for the records stored in table column records, replacing them with the data found in the table columns of the same name.

A complication in the use of this command is that database-type files like the Cactvs CBS and BDB formats store property definitions themselves. After opening the file, a newly set up property definition, which may for example possess an upgraded computation function, can have been replaced by the old definition from the file. In that case, the new property definition must be explicitly re-read to gain the upper hand again, for example with a prop read command.

molfile scan

molfile scan filehandle|remotehandle expression/queryhandle ?mode? ?parameterdict?

f.scan(query=,?mode=?,?parameters=?)

Molfile.Scan(filename,query=,?mode=?,?parameters=?)

Execute a query on the file and return results. The structure file is scanned, by default starting from its current read position, and results are gathered until either the end of the file has been reached (or the scan wrapped once around the file, if the wraparound file flag has been set) or a scan condition caused the stopping of the scan procedure. If the scan finished without reaching the end of the file, it can be resumed with another molfile scan command at a later time.

The file scan works in principle on any file, but with very different efficiency. Files managed by file format I/O modules which support direct field access, and can supply structure and reaction data in binary form, can be queried much (often a factor of 1000 or more) faster than, for example, a plain SD file. In the latter format, every record needs to be fully parsed, the structure compared against the query expression, and most of the structure data is discarded immediately after the record has been checked. Files in formats which support various types of indexing for numerical values, bit-screen filtering for super- and substructure searches, hash codes for full-structure matching and other means of acceleration can be effectively queried with typical expressions in a few seconds, even while containing millions of compounds.

The two basic built-in Cactvs formats for effective searching are CBS (static files, good performance on CDROM and other linear media) and BDB (efficiently updateable, and with more advanced indexing than CBS ) . In contrast the systematic reading of a million-record SD file takes a few hours. Nevertheless, the feature of universal query support is very useful for working with typical data sets of a few thousand records. These do not need to be converted from their original formats to a query file for a quick exploratory data scan.

set demerits [molfile scan $fh [read_file 9_aminoacridine.qry] {record demerit}]

molfile scan $fh $leafexpression1

molfile scan $fh [list “and” $l1 $l2]

molfile scan $fh [list “or” $l1 [list “and” $l2 $l3 $l4]]

molfile scan $fh [list “orcontinue” [list not $l1] [list “xor” $l2 $l3]]

molfile scan $fh [list bind mol [list and $l1 $l2]]

“record <= 100”

“vrecord <-> {1 1000}”

“record in {1 7 19 230}”

“filename = part1.sdf”

“isnull E_NAME”

“notnull product:E_ASSAY_RESULT”

„subset 0.6“

property {operator ?modifiers?..} value ?threshold? ?multimode? ?filter? ?c1? ?c2?

“E_NAME = methane”

“solvent:E_NAME {in ignorecase} [list benzene toluene ethylbenzene]”

“E_IRSPECTRUM(source) {= shell nocase} *bruker*”

“E_WEIGHT {<= object} $ehtest”

“E_CAS {= ignoredashes ignorecase} 88337-96-6”

“E_SCREEN {>= tanimoto object} $eh 95”

“A_ELEMENT = 6 {} all ringatom”

“E_SCREEN {>= tversky object} $eh 90 {} {} 30 70”

"V_ONTOLOGY_TERM(substructure) {>= swap  stereo isotope charge} $eh"

set ehss [ens create C]

set ehss [ens create C smarts]

molfile open $file r hydrogens asis readflags noimplicith

“structure ~=> $eh 90”

“product <-> C(=O)\[OH\] {2 3}”

“structure %>= $eh 90 30 70”

set ss [ens create {C=C=C.C=C} smarts]

set q "and {structure {<-> exactaro distinctfgatoms} {$ss 1} 1} {not {structure {>= exactaro} {$ss 2} {} {} {} {{$ss 1}}}}"

echo [dataset scan [list C=C C=C=C C=C=CCCCC=C] $q reclist] (2)

set q {structure >= [c][OH] {} {} {} {{[n]}} burnaroringsystems}

echo [dataset scan {c1ccccc1O c1cccnc1O} $q reclist]

prop setparam E_SCREEN extended 0/1/2

“smartsearch = c1ncccc1”

“smartsearch {= stereo} \“L-lysine\””

“formula = C6H6”

“formula = C5-6H6-”

“formula >= (Cl+Br)2”

“formula > \[4M\]>=3” or {formula > [4M]>=3}

“formula = (2C-H)-6”

“formula = CH3COOH”

“formula = \[Het\]>1“ or {formula = [Het]>1}

“formula = N1-{0.25C}“

“formula = C6H6|C7H8”

“formula = |H2O”

and “formula = C6H6|C7H8” “formula = C6H6C7H8”

molfile scan $fh “structure >= C1NCCC1” vrecordlist \	[dict create “order” [list 3 6 29 157]]

molfile scan $fh “structure ~>= $ehcmp 90” {table E_SMILES score} \	[dict create “order” {sortup E_WEIGHT}}

molfile scan $fh {structure = c1ccccc1} recordlist

molfile scan $fh {E_WEIGHT < 100} {propertylist E_SMILES E_NAME E_WEIGHT}

molfile scan $fh {notnull E_CAS} {table E_SMILES E_CAS}

molfile scan $fh {structure ~>= c1nnccc1 90} {score record}

molfile scan $fh “and {structure >= $ehss} {formula >= N3}}” ens

set dh [dataset create]

dataset set $dh port 10001

molfile scan $remotehost:10002 {structure >= c1ncccc1} \

	{table record E_NAME E_CAS} {} {target $localhost:10001 startposition 1}

while {![dataset tables $dh {} count]} {

	sleep 1

}

molfile open $dbfile r port 10002

vwait

molfile set

molfile set filehandle ?property/attribute value?...

molfile set filehandle attribute_dictionary

f.set(property,value,...)

f.set({property:value,...})

f.property = value

f[property] = value

A standard data manipulation command. It is explained in more detail in the section on setting property data. The alternative short form with the single dictionary argument is functionally equivalent to using the expanded dictionary as separate property and value arguments.

Examples:

molfile set $fhandle F_GAUSSIAN_JOB_PARAMS(link0) [list \	“%chk=144__303_2EVE_PDB_Opt8.chk” “%mem=128MB” “%nprocshared=2”]

The command can also be used to set a broad range of object attributes. The list of attributes is documented in the section on the molfile get command.

If an attribute is set for a multi-file virtual file, in most cases the attributes are set for all the files in the set. Some attributes, such as the record, apply to the virtual handle only and their modification indirectly addresses only one physical file. An important example for this is the record attribute, which positions the record I/O pointer into the physical file which contains the record in the virtually concatenated file.

Example:

molfile set $fhandle record 2

Above command repositions the file read/write pointer to the second record.

This command supports a special attribute value syntax for manipulating bitset-type attributes (only attributes, not property values). If the first character of the argument is a minus character (-), the named bits in the set identified by the remainder of the argument are unset. If it is a plus (+), they are additionally set. With an equal sign (=), or no special lead character, the flag set replaces the old value. A leading caret character (^ ) toggles the selected bits.

Example:

molfile set $fhandle readflags +pedantic

molfile setparam

molfile setparam filehandle property ?key value?...

molfile setparam filehandle property dictionary

f.setparam(property,?key,value?...)

f.setparam(property,dict)

Set or update a property computation parameter in the metadata parameter list of a valid property. This command is described in the section about retrieving property data. The current settings of the computation parameters in the property definition are not changed.

The return value is the updated property computation parameter dictionary.

molfile show

molfile show filehandle propertylist ?filterset? ?parameterdict?

f.show(property=,?filters=?,?parameters=?)

Molfile.Show(filename,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the molfile get command. The difference between molfile get and molfile show is that the latter does not attempt computation of property data, but raises an error if the data is not present and valid. For data already present, molfile get and molfile show are equivalent.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile skip

molfile skip filehandle ?recordcount?

f.skip(?records=?)

Skip records in a file opened for input. If the file pointer is at the beginning of a new record, this next record is the first skipped. If the file pointer is stuck in the middle of a record, for example because a molfile read command failed due to a file syntax error, the first record counted is the remainder of the current record. An attempt is made to re-synchronize to the beginning of the next record.

By default a single record is skipped. If the record count parameter is specified, more than one record can be skipped. Because of the partially read record re-synchronization feature, negative record counts are not allowed in this command. The molfile backspace and molfile set record commands can be used to go back in a file.

The command returns the number of the next record to be read. In case an attempt was made to position behind the end of a file, or a record re-synchronization failed, an error is reported.

molfile sort

molfile sort fhandle {{property ?direction ?cmpflags ?cmpvalue???}...} 	?outfile/handle?

f.sort(sortby=,?output=?)

Sort the records in the file according to the values of one or more properties or property fields contained in the file records, or computable on the objects read from the file. The output are byte-for-byte identical images of the input records, not records reconstructed from read data objects.

The property sort set consists of o sequence of zero or more sort specification elements. Every specification element is parsed as a sublist, but only the first element therein is mandatory. This element is either a property name, a property field name, or one of the magic names #record or record (for the file record) or # random or random or rnd (for a random number assigned to that record). The optional sort direction element may be up /ascending or down /descending. The default sort direction is upwards. The third optional comparison flags parameter can be set to a combination of any of the values allowed with the prop compare command. The default is an empty flag set.

If a comparison value is supplied as fourth argument, the sort utilizes the comparison results of read file object property values against this value for ranking, not the direct comparison result between the read file object property values. This is for example useful when sorting according to a bitvector similarity value to an external structure.

The first property or magic name in the sort list has the highest priority. In addition to the specified properties, the original record number is implicitly added as tie breaker to yield a stable sort. This automatic value is always sorted upwards. If an empty property list is specified, the result is thus a simple file copy without record rearrangement. In order to randomize the record order in a file, use a single #random sort property.

The sort properties do not need to be already present in the file. If necessary, an attempt is made to compute these on the objects read from the file in the first pass. It is possible to sort on properties which are not of the object class read from the file, for example atom properties when ensembles are read, or ensemble properties when reactions are read. In that case, the record is output at the position determined by the lowest sort rank of the property of that object, for example the minimum or maximum value of all values of an atom property in an ensemble. Additional data instances of the property associated with a given record are ignored, so no record duplicates are output.

The optional output parameter can either be the handle or reference of an opened Tcl or Python channel, including standard output and standard error or the name of a (preferably new) file, or a pipe construct. Output is appended to this output channel. If the parameter is omitted, the output is first written to a temporary file, the original file deleted and the temporary file renamed to the original file. In that case, the original file handle is automatically re-opened for reading on the new file. The input file handle must be positionable, because file records are accessed twice, once for reading the sort data and once for copying the records out. Sorting from standard input, pipes or other non-rewindable sources is therefore not supported, and neither is the sorting of files which are not simple record sequences. Sorting such files is currently only possible by using explicitly scripted record data buffering mechanisms.

On Windows, output to an open Tcl file handle or Python file reference s not supported, except for the standard output and error channels.

The return value of the command is the number of records written. The position of the sort file handle is set to the same location as before the command.

Examples:

molfile sort $fh {{E_NAME up {dictionary nocase}}} dict.sdf

molfile sort myfile.sdf {{record down}}

set fhtcl [open “randomized.sdf” w]; molfile sort $fh {{random}} $fhtcl

molfile sort $fh {{A_ELEMENT down} {E_WEIGHT up}} “|gzip >heavy.sdf.gz”

The first example creates a new file dict.sdf which contains the remaining records in the file associated with the file handle sorted by the value of property E_NAME in case-insensitive dictionary order. The second example reverses the order of the records in the file, replacing the original file in the process. The third example randomizes the record sequence in the original file, outputting the records in a new file which was opened for writing as a normal Tcl text file. The final example outputs a compressed SD file, with structures sorted by the heaviest element in the ensembles, and using the molecular weight as tie breaker.

molfile sqldget

molfile sqldget filehandle propertylist ?filterset? ?parameterdict?

f.sqldget(property=,?filters=?,?parameters=?)

Molfile.Sqldget(filename,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the molfile get command. The differences between molfile get and molfile sqldget are that the latter does not attempt computation of property data, but initializes the property value to the default and returns that default, if the data is not present and valid; and that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile sqlget

molfile sqlget filehandle propertylist ?filterset? ?parameterdict?

f.sqlget(property=,?filters=?,?parameters=?)

Molfile.Sqlget(filename,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the molfile get command. The difference between molfile get and molfile sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile sqlnew

molfile sqlnew filehandle propertylist ?filterset? ?parameterdict?

f.sqlnew(property=,?filters=?,?parameters=?)

Molfile.Sqlnew(filename,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the molfile get command. The differences between molfile get and molfile sqlnew are that the latter forces re-computation of the property data, and that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile sqlshow

molfile sqlshow filehandle propertylist ?filterset? ?parameterdict?

f.sqlshow(property=,?filters=?,?parameters=?)

Molfile.Sqlshow(filename,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the molfile get command. The differences between molfile get and molfile sqlshow are that the latter does not attempt computation of property data, but raises an error if the data is not present and valid, and that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile string

molfile string enshandle/reactionhandle/datasethandle ?attribute value?...

molfile string enshandle/reactionhadle/datasethandle? ?attribute_dict?

Molfile.String(eref/xref/dref,?attribute,value?,...)

Molfile.String(eref/xref/dref,attribute_dict)

This command creates a byte vector representation of a structure file. The third argument in the Tcl variant (first for Python ) is an ensemble, reaction or dataset handle or reference, not a file handle or reference as for other molfile commands.

If the selected output format module supports direct output into a string, the record image is created without intermediary forms. Otherwise, a anonymous temporary file is opened, the ensemble or reaction(s) written to that file, and the file content returned as string with all newlines etc.. The file is then removed.

Writing to binary formats is possible. The return value of the command is a byte vector, not a simple text string, so it may contain NUL bytes. By default, in the absence of an explicit format specification, a MDL Molfile is written.

The remaining parameters are interpreted as in the molfile set command. There are two equivalent command variants, either using attribute and value argument pairs or a dictionary as a single argument. The parameters in the extra arguments or dictionary are typically used to set a hydrogen status, select the output format, etc.

molfile blob is an alias to this command.

Example:

set jmestring [string trim [molfile string [ens create C1CC1] format jme]]

The example creates an input string for the popular JME Java structure editor by P. Ertl/Novartis. The string trim statement deletes the trailing newline. The necessary JME output module is automatically loaded if it is not already loaded or compiled-in when the format parameter is decoded.

String record representations generated by this command can be opened for input as string data with the s mode of the molfile open command:

set fh [molfile open [molfile string $eh] s]

molfile subcommands

molfile subcommands

dir(Molfile)

Lists all subcommands of the molfile command. Note that this command does not require a handle.

molfile sync

molfile sync filehandle

f.sync()

This command synchronizes the file contents with the file system. The I/O modules for most file formats automatically performs a simple file buffer flushing upon finishing the output of a record, so this command is needed only under special circumstances where complete file system synchronization is required, the file was written without immediate commits, the I/O module for the file format provides a special synchronization function, or the output was done via asynchronous I/O. In any case, every file is fully synchronized when it is closed, so calling this function for normal output operations is not required.

The command returns the original file handle or reference.

molfile toggle

molfile toggle filehandle

f.toggle()

Switch a file from input to output, or vice versa. If the file was in write, append or update mode when the command is executed, the file is rewound and the read pointer is now pointing to the first record, or the original end point for append files. If the file was configured for input, the file output mode is changed to append if the file is a normal file. If the file is a scratch file, the file is truncated to an empty file and the write position set to the first record.

Not all file types can be toggled. Special file types except FTP streams cannot, and it is not possible to toggle a simple disk file which was originally opened in read only mode (see molfile open command).

The command returns the original file handle or reference.

molfile transfer

molfile transfer filehandle propertylist ?targetpropertylist? 

f.transfer(properties=,?target=?,?targetproperties=?)

Copy property data from one molfile object to another molfile object or other major object, without going through an intermediate scripting language object representation, or dissociate property data from the molfile object. If a property in the argument property list is not already valid on the source file object, an attempt is made to compute it.

If a target object is specified, the return value is the handle or reference of the target object. The source and target object cannot be the same object.

If a target property list is given, the data from the source is stored as content of a different property on the target. For this, the data types of the properties must be compatible, and the object class of the target property that of the target object. No attempt is made to convert data of mismatched types. In case of multiple properties, the source property list and the target property list are stepped through in parallel. If there is no target property list, or it is shorter than the source list, unmatched entries are stored as original property values, and this implies that the object class of the source and target objects are the same.

If no target object is specified, or it is spelled as an empty string or Python None , the visible effect of the command is the same as a simple molfile get , i.e. the result is the property data value or value list. The property data is then deleted from the source object. In case the data type of the deleted property was a major object (i.e. an ensemble, reaction, table, dataset or network), it is only unlinked from the source object, but not destroyed. This means that the object handles returned by the command can henceforth the used as independent objects. They can be deleted by a normal object deletion command, and are no longer managed by the source object.

molfile truncate

molfile truncate filehandle ?record?

f.truncate(?record=?)

Molfile.Truncate(filename=,?record=?)

Truncate a file. If no explicit record is given, the file is truncated after the current record. In case the current record count of the file is less than the specified record, the command raises an error.

Only files which are rewindable can be truncated. In addition, the program must have write permission to the file, although it is not required that the file handle is opened for writing. The I/O modules for files formats which are not a simple record sequence must provide a truncation function or the operation will fail.

The command returns the original file handle or reference.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile unlock

molfile unlock filehandle propertylist/molfile/all

f.unlock(property=)

Unlock property data for the file object, meaning that they are again under the control of the standard data consistency manager.

The property data to unlock can be selected by providing a list of the following identifiers:

• Property names or references
  Valid property instances on the file object are unlocked. Non-existent data is silently ignored. It is not possible to unlock individual property fields.
• all
  All valid file object properties are unlocked.
• molfile
  This is an object class identifier. All property data which is controlled by the molfile major object and attached to the specified object class is unlocked. Since files do not incorporate minor objects, this identifier is equivalent to all .

Property data locks are obtained by the molfile lock command.

This command is a generic property data manipulation command which is implemented for all major objects in the same fashion and is not related to disk file locking. Disk file locks can be set or reset by modifying the molfile object attribute lock. This is explained in more detail in the paragraph on the molfile get command.

The return value is the original molfile handle or reference.

molfile upgrade

molfile upgrade filehandle

f.upgrade()

Molfile.Upgrade(filename)

If the I/O module provides a function to upgrade the format of an older file to the latest version of the format, for example after a support library upgrade, that function may be used. The only format which currently supports this feature is BDB .

The command returns the original molfile handle or reference.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

molfile valid

molfile valid filehandle propertylist

f.valid(property/propertysequence)

Returns a list of boolean values indicating whether values for the named properties are currently set for the structure file. No attempt at computation is made.

Example:

if [molfile valid $fhandle F_COMMENT] {...}

molfile has is an alias to this command.

molfile vappend

molfile vappend filehandle objectlist

f.vappend(objectref/objectrefsequence)

Virtually append records to an open file handle. The underlying file is not modified, but all future input operations on this file behave as if the extra records were present.

Because no actual output is generated, this command can only be applied on files opened for reading , not output files. In addition, the file handle needs to refer to a normal disk file and to support going backwards in the file, i.e. this command cannot be used on structure files opened via URL s, standard I/O channels, socket connections or composite virtual files with multiple physical files or the contents of a directory. The file format must support multiple records and the records must be encoded as a simple concatenated byte sequence. Examples for formats which work are SMILES or SD files for structures, or RXN or RD files for reactions.

The object list may contain ensemble, reaction or dataset handles. The data is split into virtual records according to the storage capabilities of the file. The format of the data written to the virtual records can be controlled by setting the writelist , droplist and hydrogens status attributes on the file handle.

When executed for the first time on a file handle for which the record count is yet unknown, the existing file records must be tallied and all current physical record positions be registered. For very large files, this can take some time. However, this is not equivalent to reading the complete file, so it does not consume much memory and the command can in principle work on arbitrarily large files.

Virtual records are held as string images in memory. A couple of thousand such records should not be a problem for typical workstations, but for systematic editing of large files where every record is touched an explicit scripted input/output loop is preferable.

The return value is the new record count of the file.

Changes to the file can be committed to disk by means of the molfile vrewrite command.

Example:

molfile vappend $fhandle [ens create c1ccccc1]

molfile vdelete

molfile vdelete filehandle recordlist

f.vdelete(record/recordsequence)

Virtually delete records from an open file handle. The underlying file is not modified, but all future input operations on this file behave as if the specified records had been deleted.

Because no actual output is generated, this command can only be applied on files opened for reading , not output files. In addition, the file handle needs to refer to a normal disk file and to support going backwards in the file, i.e. this command cannot be used on structure files opened via URL s, standard I/O channels, socket connections or composite virtual files with multiple physical files or the contents of a directory. The file format must support multiple records and the records must be encoded as a simple concatenated byte sequence. Examples for formats which work are SMILES or SD files for structures, or RXN or RD files for reactions.

When executed for the first time on a file handle for which the record count is yet unknown, the existing file records must be tallied and all current physical record positions be registered. For very large files, this can take some time. However, this is not equivalent to reading the complete file, so it does not consume much memory and the command can in principle work on arbitrarily large files.

The record list is a list of integer values, with one as the first file record. The list does not need to be sorted, and duplicate record numbers or record numbers out of range are ignored. It is possible to virtually delete file records which are themselves virtual, i.e. were added by the vappend, vreplace or vinsert subcommands and are not physically present in the file.

Virtually deleted records have negligible memory demands, but will slightly slow down input operations on edited files.

The return value is the new record count of the file.

Changes to the file can be committed to disk by means of the molfile vrewrite command.

Example:

molfile vdelete $fhandle [list 3 9 6]

molfile verify

molfile verify filehandle property

f.verify(property)

Verify the values of the specified property on the molfile object. The property data must be valid, and a molfile property. If the data can be found, it is checked against all constraints defined for the property, and, if such a function has been defined, is tested with the value verification function of the property.

If all tests are passed, the return value is boolean 1, 0 if the data could be found but fails the tests, and an error condition otherwise.

molfile vinsert

molfile vinsert filehandle objectlist

m.vinsert(objectref/objectrefsequence)

Insert virtual records for the specified objects into the file. The insertion position is before the current read position.

Except for the difference in the location where the virtual records are inserted, the command is equivalent to the molfile vappend command and has the same features and limitations. Please refer to that command for details.

The return value is the new record count of the file.

Changes to the file can be committed to disk by means of the molfile vrewrite command.

molfile vreplace

molfile vreplace filehandle objectlist

m.vreplace(objectref/objectrefsequence)

Insert virtual records for the specified objects into the file. The current input record is virtually overwritten.

Except for the difference in the location where the virtual records are inserted, and the fact that an existing record is replaced, the command is equivalent to the molfile vappend command and has the same features and limitations. Please refer to that command for details.

It is possible to replace a record which is itself virtual, i.e. was introduced by a vappend, vinsert or vreplace subcommand. If more than one output object is passed, or the object is written as multiple file records, additional virtual records are created and the record count of the file increased accordingly.

The return value is the new record count of the file.

Changes to the file can be committed to disk by means of the molfile vrewrite command.

Example:

set eh [molfile read $fh]

ens expand $eh

molfile backspace $fh

molfile vreplace $fh $eh

ens delete $eh

This command sequence virtually replaces a record with a version where superatoms are expanded.

molfile vrewrite

molfile vrewrite filehandle ?filename?

m.vrewrite(?filename=?)

Commit all virtual record additions, deletions or replacements to a physical file. If no file name is given, the current file name is used. After writing, the file handle remains valid. It is open for reading, and positioned before the first record. At this moment, the file no longer contains any virtual modifications, but the file handle may again be subjected to virtual edit operations. In case a file name is specified, and is not the same as the name of the current file, the file handle refers to the new file when the command has finished.

All valid records are copied verbatim to the new file, without going through decoding and re-encoding or records (see molfile copy command). A temporary file in the same directory as the current file is created, and sufficient disk space needs to be present to hold both the original file and the edited version at the same time. In case a problem occurs, the temporary file is deleted and the current file remains active. Only if all write operations succeed the old file is deleted and the temporary file renamed if necessary. In case a file name is specified, and it is not the same as that of the current file, the original file remains untouched, but is no longer linked to the molfile handle. For large files, this operation can take some time because massive amounts of data may need to be moved.

If the file referenced by the file handle has not been edited with virtual record operations ( vappend, vdelete, vinsert, vreplace ), the command does nothing and is equivalent to a molfile rewind .

The command returns the number of records written.

Example:

set fh [molfile open „myfile.sdf“]

molfile vinsert $fh 1 [ens create c1ncccc1]

molfile vrewrite $fh „myfile_with_pyrdine_inserted_in_rec_1.sdf“

molfile write

molfile write filehandle ?objecthandle/objecthandlelist?...

f.write(objectsequence/objectref,...)

Molfile.Write(filename,objectsequence/objectref,...)

This commands writes structure and reaction data to a file. Object handles may be ensemble handles, reaction handles, dataset handles, or molfile handles.

If an object is an input molfile handle, objects are read from the file until EOF is encountered if the output file supports multiple records. If the output file type is single-record, only the next record is read. The types of objects which are collected from the input molfile handle are dependent on its read scope. These objects are then treated as if they were used as parameter objects directly. Objects obtained via a molfile handle are automatically deleted after they have been written. If the input file is already at EOF when the command is executed, no objects are read, and no error is generated. However, this does not trigger the NULL record output handling described below, because the file object was specified as an argument.

The type of data which is actually written to the file depends on its format. A file opened for ensemble output can be fed with any type of handle. If reactions or datasets are passed, these are taken apart and written as individual records. If the output file is a reaction file, and an ensemble is passed, the reaction it is a member of is looked up and used as output object. If the ensemble is not a reaction ensemble, an attempt is made to store it as a plain ensemble outside any reaction. If the output routine rejects this, an error is raised. In case of datasets passed as objects for reaction output, the individual dataset objects (ensembles or reactions) are written, in combination with reaction reference substitution in case ensembles instead of reactions are found. For full-dataset output, it is legal to pass non-dataset objects. No dataset-level information is written and the objects stored as an anonymous dataset.

It is legal to supply no object handles at all. Normally, this means that simply no output is performed. However, I/O modules for specific file formats may support the output of special NULL records. In that case, the output function is called once without any objects. An example are Gaussian job files, which allow you to write records in multi-link files, where the computation instructions are taken from the file property F_GAUSSIAN_JOB_PARAMS , without supplying a structure record.

As part of the output process, new information may be computed on the objects. In case the active settings on the output molfile handle demand a structural change of an object, for example the addition or removal of hydrogen atoms, or the re-coding of ionic versus pentavalent nitro groups and similar functionality, the write objects are temporarily duplicated and these duplicates undergo the structure changes. The original output objects are never indirectly edited in their connectivity by this command.

The writelist attribute of molfiles may be set to a list of properties which should be included in the output. This has an effect only for file formats which support the storage of custom data values and which can cope with the data types of the listed properties. By default, no attempt is made to actively compute these properties for output. If they are not present in the input data, their output is silently omitted, or NULL values are written, depending on how the output format encodes these things. However, if the computeprops flag is set on the output molfile , an attempt for computation is made, and after output, the objects retain this additional data if the computation succeeds.

If the hydrogen set mode of the output molfile calls for a change in hydrogen status, the stage when these computations are performed depends on the hydrogen addition mode. If the output mode calls for potential hydrogen additions, the computations are executed after the addition - and this means, on the temporary duplicate, so the original object does not see the new property data. If the hydrogen mode does not change the hydrogen set, or potentially removes hydrogens, computations are performed on the original objects and then the object is potentially duplicated, with all its data, for hydrogen removal and output. In the latter case, the additional property data is visible on the original input objects.

The command returns a list of the object handles or references which were actually written to file. In cases like a reaction being split into ensembles, or a dataset taken apart, this is not necessarily the same object handle collection as the input object list. For output from an input molfile argument, the total number of objects written is returned instead, because the read objects are not retained.

The Python class method is a one-shot command. The transient molfile created from the initialization items is automatically closed when the command finishes.

Examples:

molfile write “myfile.sdf” $eh1 $eh2

set fhandle [molfile open z.cbin w hydrogens add format cbin]

molfile write $fhandle $dset1

molfile write $fhandle $dset2

molfile close $fhandle

The first sample line uses the single-shot file operation feature of the molfile command. Instead of a molfile handle, a file name is passed, and that file is automatically opened, the output performed, and then the file is closed. Two ensembles are written with a single statement to the output file myfile.sdf. The desired file format is guessed from the file name suffix. No change in hydrogen status, etc. is performed, and no extra data is written out.

The next four example lines show how two complete datasets can be written to a native Cactvs toolkit binary file. Hydrogens are added to structures or reactions in the dataset - but the original dataset elements are not changed, since the addition is performed on temporary object duplicates. Also, the Cactvs binary format is requested explicitly by setting the format attribute. In this case, this is not really required, since the file format could also be guessed from the file name suffix. However, in case a non-standard file name suffix is used, formats must be specified explicitly, or the default format ( MDL SD -file) is used. If the Cactvs binary file is later opened for reading with a read scope of dataset , all dataset elements plus the dataset-level property data can be recovered.