prop alias

prop alias

prop alias propertyname aliasname ?propertyname aliasname?...

This command defines an alias name for a property name. After defining an alias, any time the alias name is used as a property name, it is silently and automatically translated to the original property name. It is possible to map an alias name to another alias. Name resolution recursively proceeds until the name can no longer be resolved. Aliases have precedence over basic property names. If an alias name is the same as an existing property name, that existing property becomes effectively invisible and is replaced by the property the alias links to.

The name the alias maps to must be resolvable at the time of definition.

In case the command is used without arguments, it returns a dictionary of current alias definitions. The keys are the recognized alias names and the values the property or second-level alias name the keys are translated to.

Example:

prop alias E_NATOMS E_ATOM_COUNT

After execution, the number of atoms in an ensemble can both be queried via property E_NATOMS (original name) and E_ATOM_COUNT (new alias name).

The default start-up files of the toolkit include a set of alias definitions which map older, less systematic property names as aliases to current official property names.

prop check

prop check propertyname ?objecthandle?...

Verify the syntactic correctness of property data on a list of major objects, such as ensembles, reactions or datasets. The return value is a boolean list of check results, 1 if the data is formatted correctly, 0 if not. If the property is not set for the object, the returned status value is -1.

In case there is no check function (attribute checkfunction , see prop set ) defined, or it cannot be found, an error results. More details on the operation of the check function can be found in the prop set subcommand documentation.

Example:

prop check E_CAS $eh

This command checks, if property E_CAS is set for the ensemble, whether it is formatted correctly by calling the Tcl check function defined for E_CAS . For this property, the check function runs the CAS check digit algorithm on the data value. It catches encoding errors where the check digit does not match the value as re-computed from the other digits.

prop compare

prop compare propertyname value1 value2 ?cmpflags? ?param1? ?param2?

prop compare propertyname(field) value1 value2 ?cmpflags? ?param1? ?param2?

prop compare datatypename value1 value2 ?cmpflags? ?param1? ?param2?

Compare two property values. In the first two forms, the name of the property, or of a property field, is used primarily to get the data type for the decoding of the comparison values and the selection of the applicable comparison function. Alternatively, a data type name can also be supplied directly.

The value parameters are expected to be suitable string representations for the underlying data type. If the property name form of the command is used, they may be specified as enumerated values and other formats which can only be decoded with the aid of information attached to a specific property. The comparison values are converted using the string or Tcl object input function associated with the data type. If the property name form is used, they are also subject to any other tests associated with the property, such as constraints or regular expression pattern matches.

The cmpflags argument is a list of words which are used to select specific comparison function modes. The default is an empty list. In that case, no c modification flags are passed to the comparison function. In case a mode bit is selected which is not supported by a specific comparison function, it is silently ignored. Some of the flags may be combined to yield specific useful comparison results, but it is the responsibility of the implementation of a data-type specific comparison function to determine which flags can be combined, and which have precedence in case of conflicts. The following words are currently recognized:

• none
  Equivalent to an empty string, no bits set
• absolute
  For numerical comparisons, use the absolute value.
• anymatchelement
  In case of data types with separate elements (vectors, etc.) check whether any element in the first value is identical to the corresponding element in the second vector. If yes, return 1, else 0.
• anymisselement
  In case of data types with separate elements (vectors, etc.) check whether any element in the first value is different from the corresponding element in the second vector. If yes, return 1, else 0.
• approximate
  Perform an approximate comparison. For string types, this means that white space, punctuation characters, digits and character case are ignored. If combined with the withdigits flag, the comparison takes digits into account, but still ignore whitespace, punctuation and case.

For floating-point comparisons, this flag indicates that rounded integers should be used for comparison, not the float values.

If the toolkit was compiled with support for the TRE library, this attribute can also be used in combination with a regular expression comparison. In that case, the result is a percentage similarity score between the query expression and the test string, with character substitutions, deletions and insertions all having the same weight.

• asnumber
  In case of strings, compare string contents as signed floating point numbers instead of characters.
• bitcount
  For bit vector and integer types, compare the number of set bits, not the numerical value.
• bitset
  For bit vector and integer types, check whether all set bits in the second argument are also set in the first argument. The return value is -1 if the second argument contains set bits which are not in the first argument, 0 if the values are identical, and 1 if the first value contains set bits that are not set in the second argument. In case there are set bits in either of the two arguments with no corresponding set bit in the other argument, the return value is -1.
• bitunset
  For bit vector and integer types, check whether all unset bits in the second argument are also unset in the first argument. The return value is -1 if the second argument contains unset bits which are not in the first argument, 0 if the values are identical, and 1 if the first value contains unset bits that are not unset in the second argument. In case there are unset bits in either of the two arguments with no corresponding unset bit in the other argument, the return value is -1.
• contained
  Check whether the value of the second argument is contained in the first. return 1 if it is, 0 otherwise. For strings, this is a substring search. For integers and bit types, it counts the number of common bits. For vectors, it checks whether all elements of the second argument are also found in the first vector, but there is no requirement that the matching element indices are the same.
• correlation
  For bit types and numerical vector types, compute the correlation coefficient between the vector arguments. The result is multiplied by 100 and rounded to the next integer.
• cosine
  This operation is only supported for bit vectors. It returns the cosine similarity coefficient as an integer, multiplied by one hundred.
• dice
  Compute scaled (0..100) Dice similarity coefficient for bit vectors, bit sets and strings (via bigraphs).
• dictionary
  Compare strings in dictionary order.
• euclid
  For bit types and numerical vector types, compute the Euclidean distance between the points represented by the vector arguments. The result is rounded to the next integer.
• extended
  For string comparisons with regular expressions, use extended regular expression syntax.
• glob
  For string comparisons, the second value is interpreted as a shell-style glob expression. The return value is 1 if the expression matches, 0 otherwise. The position of the expression argument vs. the simple string can be changed with the swap flag.
• ignorecase
  For string-type comparisons, ignore character case.
• ignoredashes
  Ignore any dash/minus characters in string comparisons. This is useful for comparing CAS numbers with non-standard separator locations.
• ignorewhitespace
  For string comparisons, ignore white space, but not character case.
• left
  For string comparisons, match the left side of the target strings.
• like
  For string comparisons, interpret the comparison value as SQL -style like pattern.
• precision
  use the precision as defined by the property attribute precision for comparison, instead of the native data type precision. If the first optional parameter of the command is specified, its value is used instead of the precision set in the property definition. The precision value an integer, defining the number of significant digits after the decimal point. Negative values are allowed to define significance limited to differences in tens or hundreds in a property value.
• overlap
  This operation is only supported for the float pair type. For each value, the pair defines a minimum and maximum range. If the ranges overlap, zero is returned, otherwise -1 (in case the first range is entirely to the left) or 1 (in the opposite case).
• regexp
  For string comparisons, the second value is interpreter as a regular expression. The return value is 1 if the expression matches, 0 otherwise. This flag can be combined with the ignorecase and extended flags, which further modify the interpretation of the regular expression. The argument position of the expression argument vs. the comparison string can be changed with the swap flag. Starting with toolkit version 3.352, the regular expression syntax on all platforms is that of the PCRE library, i.e. the Perl style.
• right
  For string comparisons, match the right part of the target string.
• swap
  Exchange the left/right roles of the arguments. This also affects the special interpretation of arguments in certain positions, as with the glob and regexp modifiers.
• trim
  In case of string comparisons, ignore leading and trailing white space, but not embedded.
• tanimoto
  For bit types and numerical vector types, compute the Tanimoto coefficient. The result is multiplied by 100 and rounded to the next integer.
• tversky
  For bit vectors, compute the Tversky score between the vector arguments. This is one of the few modes where the extra arguments have an effect. Here, they are expected to be values in the 0..100 range. They are divided by 100 and used as floating-point c1 and c2 parameters. In case both are set to 50, the result is the same as a Tanimoto comparison. Note that the default values of zero for the extra arguments are not useful for this mode and reasonable values must be supplied.
• withdigits
  For approximate string comparisons, recognize and compare digits. By default, they are ignored in that mode. In any case, approximate string comparisons ignore white space and punctuation.

The return value is the integer value returned by the comparison function. For most modes, this is either 0 (values are equal), 1 (left value is larger) or -1 (right value is larger). Some modes do however return other values. For example, similarity bit vector or bit set comparisons return a value between 0 and 100.

The default values for the optional extra parameters are both zero.

Example:

prop compare E_SCREEN [ens get $eh1 E_SCREEN] [ens get $eh2 E_SCREEN] tanimoto

This command performs a Tanimoto comparisons on the screening vectors of the two ensembles and returns a score in the range 0..100.

prop configure

prop configure propertyname

Execute the property configuration function (attribute configfunction ). If there is no function defined, or the execution of the configuration function fails, the command does nothing. By convention, a property configuration function opens a Tk window with various GUI elements for the convenient adjustment of computation parameters. Because this is usually a graphical operation, and the overhead of extending the property slave interpreter to a fully GUI-enabled version, this command is always executed in the global interpreter.

Note that this function usually does not directly result in the change of property attributes and parameters. The standard approach is to set up and display a Tk window, which remains open until it is closed by the user, while this command returns immediately. Changes from adjustments in the property panel take effect asynchronously only after an apply button has been pressed by the user.

prop create

prop create propertyname ?attribute value?...

Create a new property definition, and optionally set attributes.

The name of the new property must conform to the general property naming conventions in the toolkit. Indexed fields, instance identifiers, registration ID and other name parts aside from the base name are ignored.

In case a property definition for the same property name is available, and either already loaded or can be found by in the property autoloader path, the command internally succeeds, but still returns a Tcl error. This is intended to prevent the accidental overwriting of system property definitions, which can lead to problems which are difficult to detect and may lead to crashes, for example when the data type of an internally used property is changed in an incompatible fashion. Acceptance of the command when overwriting is desired can be forced by surrounding it in a catch statement.

A property created without additional attributes has no associated functions, is of data type string and generally has empty default values for all attributes. The only exception is the URN namespace, which is set to the local namespace, and the creation date, which is set to the current time. In addition, the property object class is automatically set from the prefix of the specified name.

The processing of the attribute/value pairs is equivalent to a prop set command. The possible attributes are described under that subcommand.

Example:

prop create A_MYPROPERTY datatype int author “A. Nonymouse”

This statement creates an atom property (determined by the standard A_ prefix) of data type integer and a curious author attribution.

prop defined

prop defined propertyname

Attempt to resolve the specified property name. If the property name is not yet part of the internal property database, an attempt is made to resolve it via the auto-loading mechanism. This is different from the similar prop exists command. The boolean return value is zero if the property name could not be resolved, one otherwise.

prop available is a deprecated alias of this command.

prop delete

prop delete propertyname ?force?

This command deletes a property definition from memory. It does not remove the files the property is defined by, if it exists. Property names which are not defined when the command is run are silently ignored. By default built-in properties cannot be deleted. In order to force this, the optional fourth boolean parameter must be set. Deleting built-in properties is risky and can lead to crashes if the property is required as part of internal computations.

The property is not actually removed from the internal database until all instances of data of that property attached to chemical objects have been deleted. In such a case, the property name is not usable any longer in script commands, but implicitly information such as data type and formatting instructions are still used until all data associated with the original definition has been purged. The name of a half-deleted property still shows up in commands like ens props , but commands such as ens get fail, even for existing property data because the translation of the property name in the request to the internal data structure is no longer possible. However, operations such as file I/O which do not rely on properties looked up by string name may still succeed. The deletion of chemical objects with data from deleted properties always succeeds, decrements the reference counts and frees memory.

It is possible to re-define a property with the same name as a deleted one, even if there is still pending data. However, this is highly discouraged and potentially confusing.

If the supplied property name is an alias, the property the alias is pointing to is deleted, not the alias definition (see prop unalias for this function). In addition, all alias definitions which point to the deleted property are also recursively deleted.

prop dup

prop dup propertyname newpropertyname

Create a new property definition using an existing definition as a template. In typical cases, the property duplicate is further customized by prop set commands. The new property name should not be the name of an existing property, though this is not illegal. In that case, it hides the definition of the original name similar to an alias definition.

The return value of this function is the name of the duplicated property.

prop exists

prop exists propertyname

This command checks whether a property is currently loaded in the in-memory database. No attempt is made to look up the definition via the auto-loading mechanism if it is not yet present. The boolean return value is zero if the definition is currently unknown, one otherwise. For a related command with implied auto-loading, see the prop defined command.

prop get

prop get propertyname attribute

Get the value of a property attribute. The property attributes are explained in the paragraph dealing with the prop set subcommand. The return value is the current setting of the requested attribute.

The parameters attribute is a special case in multi-threaded scripts. Its value is thread-local. Every thread may have a different parameter set for each property. In order to obtain the base parameter set, the attribute globalparameters may be read.

prop getparameter

prop getparameter propertyname parametername ?usedefault?

Get the value of a computation function parameter, or of a computation function default parameter.If the last command argument is not specified, or set to a boolean false , the queried parameter collection is the current parameter set (property attribute parameters ). Otherwise, it is the default parameter collection (property attribute defaultparams ). If the requested parameter is not found in the parameter set, an error results. Otherwise, the result of the command is the retrieved parameter value.

In a multi-threaded environment, a returned parameter value (but not a default parameter value) is thread-dependent. Every script thread has an independent property computation parameter set which is copied from the global value in the base interpreter the first time a property is referenced in a thread.

This command may be abbreviated to prop getparam .

prop isdefault

prop isdefault propertyname value

Check whether a property data value is the same as the property default value. The return value is the boolean test result.

prop ismagic

prop ismagic propertyname value

Check whether a property data value is the same as the property magic value. The return value is the boolean test result.

prop list

prop list ?pattern? ?computable_only?

List all currently loaded property definitions, including built-in definitions. If desired, a string pattern filter can be supplied to select only specific properties. The optional fourth parameter can be used to restrict the list to properties which are associated with a computation function.

Example:

prop list E_* 1

lists all currently defined and loaded ensemble property definitions which are computable. Computability is only checked at the property definition level. It is no guarantee that the property computation succeeds for any specific ensemble or other chemistry object.

prop query

prop query keyword ?objectclass? ?mode? ?casesensitivity?

Search the internal property database by matching the keyword against a standard set of property attributes, such as name, description, keywords, category, comment and UUIDs. Only the current memory database is checked, no auto-loading or repository checks are performed.

By default all property definitions are matched. The object class argument (such as atom ) can be used to limit the search to properties for a specific object class. Providing an empty argument is the same as omitting the argument.

The optional mode argument changes the string comparison mode. The default is equal , other possibilities are substring , left (match beginning of string), right (match end of string), like (as the SQL operator), glob or regexp .

The final argument can be case (case-sensitive matching) or nocase (case-insensitive comparison, this is the default).

The return value is a list of the version UUIDs of the matched properties.

prop read

prop read filename ?doinstances?

Read a file with one or more property definitions. All property definitions found in the file are added to the internal in-memory database. By default, or when the doinstances parameter is set to 0, a definition from the file which refers to the same property as one already loaded implicitly deletes the old definition (see prop delete for a discussion of the consequences of this operation) from memory before the new definition is added. If the optional argument is set to a true boolean value, an additional definition with an instance number one higher than the highest currently defined instance is created instead.

The return value of the command is a list where the first element is the total number of property definitions read from the file, and the second element the name of the first read property.

prop reload

prop reload propertyname

A convenience command for property computation module development. It first attempts to delete the current property definition. If this fails because its reference count is not zero, and attempt is made to reach zero by deleting all objects which may contain property data of the object class the property is associated with (e.g. ensembles if the property is an atom, ring or ensemble property). If the deletion now succeeds, the property is auto-loaded again, presumably with an updated processing script or module. Specifying an unknown property, a property where the reference count cannot be decremented to zero, or for which the definition cannot be found in the property loader path is an error.

The command returns the property name.

prop set

prop set propertyname ?attribute value?...

This command is used to modify the attribute sets of existing property definitions. If the property name cannot be resolved, an error results. The following attributes are currently supported:

• access
  This argument controls the general access to property computation servers which accept remote requests. This is an enumerated property with possible values none (unset, no access by anyone if running as server), private (access only if client user is the same as server user, and client and server are on the same subnet), local (client user must be valid on local host, and client and server are on the same subnet), registered (client user must be in net group named propname _users), and finally free (no first line access checking on user IDs, subnets or net groups). If this access condition lets a request pass, script-based access checking still applies. This attribute has no effect on property computations which do not operate over a client/server connection.It has no effect in standard local scripts.
• accessfunction
  This name of an access check procedure if the property is computed on a server and remote requests are accepted. If there is no access function, only rudimentary access control (see access attribute) is performed. If an access function is set, it is called with the handle of the chemistry object the computation is requested for, and the name of the property. Additionally, request information including user name, email, host and password are stored in the global array variable ::server. The access function may reject requests based both on the variable contents (wrong password, etc.) or the data of the chemical object the computation is requested for (too many heavy atoms, etc.). In order to reject a request, the access function can either return a boolean false value, or throw an error. Currently, the access check function is always executed in the global interpreter. Different from the computation, verification and configuration Tcl script functions, the access function is never automatically integrated into property definition files written by the prop write command. This function is intended to remain confidential and local. The access function is only called if a computation request is executed in a client/server relationship. It has no effect in standard local scripts.
• affiliation
  The institution the author of the property definition works for.
• altdatatypes
  A list of alternative data types the property functions can handle. For example, most image types such as E_GIF or E_EPS_IMAGE can be computed both as datatype diskfile and blob . If a list of alternative data types is set, the property can only be reconfigured to use one of these (for details refer to the datatype attribute). If no list of alternative data types is specified, the data type can only be changed between types which use the same internal representation (e.g. float and double , or int and short ).
• altmodule
  The name of an alternative structure representation interface module. Properties which have this attribute set are not computed on the normal internal Cactvs data structure, or by calling an external program by means of a script, but are linked with a third-party software component and interface code to translate between the data structures of Cactvs and the other program. This attribute is rarely encountered in normal use scenarios.
• application
  The name of an external application which generates the property data. This is a free-form string.
• applicationdate
  The release or version date of an external application which generates the property date. Must be a valid date specification.
• applicationversion
  The version of an external application which generates the property data. This is a free-form string.
• attachment
  This is a deprecated alias name for the objclass attribute.
• author
  The author of the property definition. This is a free-form string.
• authorurl
  A URL with information on the author, or an empty string if unset.
• auxdata
  This is the name of a file with arbitrary additional data the property computation function may need to perform its duties. When a property definition file is written with the prop write command, this data is encapsulated in the definition file. When the definition file is later read by an application, the data is written out to a temporary file, and the file name returned for this attribute is the name of the temp file, not the original file name. By this mechanism, it is not required to supply auxiliary data files as a separate files which may be difficult to locate and are easy to get lost. If this field is empty, no auxiliary data file is present.
• category
  A category string to be used if the property definition is stored in a repository.
• charset
  The character set this property uses for encoding and decoding. While this attribute is currently maintained as a free-form text field, it should only be set to values in standard character set syntax, such as ISO-8859-1. The latter value is the default in case it is not set.
• checkfunction
  The name of a scripted Tcl procedure designed to verify that a value of a property is correct. This function is called with the property name and a chemistry major object handle as arguments. It should return 1 if the property data is set and the check succeeds, or 0 otherwise. It should not attempt to compute the data if it is not present. If the function can be found in the private slave interpreter of the property, it is executed there. Otherwise, an attempt is made to locate and run it in the main interpreter. When a property definition file is written with prop write , and the function can be located, it is encapsulated in the definition file and is available for all further interpreters which read the definition file. Example:

prop check E_CAS $eh

This command checks, if property E_CAS is set for the ensemble, whether it is formatted correctly by calling the Tcl check procedure defined for E_CAS . With this example property, the check function runs the CAS check digit algorithm on the data value. It catches cases where the re-computed check digit does not match the one found in the data.

• classuuid
  The base class UUID of this property.
• comment
  A free-form text comment.
• computefunction
  The name of the computation function. For computation functions implemented as compiled code, this data is for information only and cannot be changed in scripts. For scripted functions, this is the name of the function which performs the computation. The function is called with the handle of the chemical object as parameter. In case the computation succeeds, the function should attach the property data to the object. In case of an error, an error condition should be raised in the script.

If the function can be found in the private slave interpreter of the property, it is executed there. Otherwise, an attempt is made to locate and run it in the main interpreter. When a property definition file is written with prop write , and the function can be located, it is encapsulated in the definition file and is available for all further interpreters which read the definition file. Example:

ens get $eh E_CAS

This request calls the Tcl script function CSgetE_CAS which is defined in the property definition file as computation function for E_CAS .

Properties which cannot be computed have an empty compute function name.

In case of Tcl script computation functions, all default and current computation parameters are automatically copied to the global (to the property slave interpreter, not visible in the main interpreter) array ::params . This is done by first traversing the default parameter list and then the current list, so that parameters in the current list overwrite any default values. In addition, the current property computation time-out value is stored in ::params(timeout). Alternatively, the parameter values can be queried by prop getparam commands in the function. In multi-threaded scripts, each thread interpreter sees its private version of property computation parameters. Therefore, it is possible to compute different versions of the same property in parallel threads.

• configfunction
  The name of the configuration function for the property. This is a Tcl script function which is supposed to present a Tk panel with configuration options for that property. The apply function associated with the panel should modify the current parameter set of this property. The function is called with the property name as only parameter. Different from computation and check functions, this function is always executed in the main interpreter, in order to avoid the need to extend the slave interpreter into a full Tk -enabled interpreter with much larger overhead. When a property definition file is written with prop write , and the function can be located, it is encapsulated in the definition file and is available for all further interpreters which read the definition file. Example:

prop configure E_GIF

This command calls the configuration function for property E_GIF , which attempts to display a pretty large GUI panel with lots of sliders and dials allowing the user to adjust the rendering parameters.

Properties which cannot be configured graphically have an empty configuration function name.

• constraints
  A set of flags to impose additional constraints on property values. Attempting to set a property value which does not meet these constraints in a script raises an error, or the value may be implicitly modified to fit the constraint. The check only applies to string conversions and conversions from Tcl or Python script interpreter objects. It is still possible to set a value in violation of the constraints by rogue compiled code in computation functions and by similar means. Not all flags are implemented, or make sense, for all data types. Implementing constraint checks is the responsibility of the data type handler module. Flags not supported for a specific data type are silently ignored. Any combination of flags can be supplied as a list argument. The currently supported values are
• none
  no constraints, other than the native capabilities of the underlying data type
• notnegative
  no negative numerical value
• notpositive
  no positive numerical value), notzero (no zero value)
• nolowercase
  no lower-case characters)
• nouppercase
  no uppercase characters
• trimmed
  leading and trailing white space are removed
• nowhitespace
  all white space is removed
• odd
  numerical value must be odd
• even
  numerical value must be even
• notempty
  input cannot be an empty string)
• maptolowercase
  translate to lower case
• maptouppercase
  translate to upper case
• mapwhitspace
  all white space sequences are translated to a single underscore character
• no8bitchars
  characters cannot have 8th bit set
• maptotitle
  translate to title formatting, with first letter of every word in upper case and all other letters in lower case

Example:

prop set E_ID constraints {notzero notnegative}

Assuming that E_ID has a numerical data type, any attempt to set it to 0 or a negative value in a script will fail.

Another method to apply constraints to property data is by means of the regexp and regexpflags attributes. Both methods may be used in combination.

• cost
  This is an integer parameter which is intended to give a rough estimate of the cost involved in computing a property. The default value is 1. Currently, its only use if when merging ensembles with different sets of property data. Here, no attempt is made to compute properties which have a cost of more than 5 and are only present on one of the ensembles.
• ctxkey
  The tag for this property in the ctx file format. If it is not set, a reasonable default tag is derived from the property name. This attribute is deprecated, the more general filetags attribute is the recommended replacement.
• datatype
  The attribute sets the data type of the property. The exact set of possible data types varies. Besides the rich set of built-in data types, an attempt is also made to locate a property handler module with the specified name in case the argument cannot be resolved with the built-in and currently loaded I/O handler modules. The default value is string - a simple 8-bit ISO 8859-1 string property.

It is not possible to change the data type of a property if data instances of that property exist on chemical objects in the current application, and the internal representation of the old and new type is not identical. For example, it is possible to switch between bool and int types, but not between int and string, if active data of the old type has already been stored.

The altdatatypes attribute imposes additional restrictions on possible values of this attribute.

• date
  This attribute stores the date of the property definition. It is used for information purposes only. If a new property is defined, it is initialized to the current date.
• dbflags
  This attribute encodes a set of hint flags for setting up SQL database columns for storing data of that property. The argument is a list of words representing bits which should be set. The following flags are currently supported:
• none
  the default, no special treatment, key - property data will likely be used as query key,
• primarykey
  column is a primary key for the table
• notnull
  disallow the storage of NULL values for that data
• indexed
  set up index on the property column,
• fixedlen
  set up database column as fixed-width data, with actual width stored in the length attribute
• timeonly
  for datetime data type, store only time part
• dateonly
  for datetime data type, store only date part.
• default
  This attribute defines the default value for the property. Usually, the syntax for this item is the same as setting a specific data value, but data type handlers can set up a special default value decoder function. For example, array types allow a syntax like 10:0 for a default value of 10 elements set to 0 each, but this syntax is not supported when setting individual data instances.

In case of properties of complex multi-field structure, the default value is a list of values in the order of the field definitions. The the default value list is shorter than the field list, the remaining fields have a zero/empty default value.

Property data values which are identical to the default are not written explicitly in native Cactvs binary files. If such data is restored, and the default value has changed, the input data assumes the new default value because it is set from the current property definition, not the file contents.

• defaultparams
  The default set of parameters, as a keyword/value list or dictionary. The syntax is the same as that of the parameters attribute. This attribute set is intended to be used as a quick way to reset the normal parameter set after changes have been made. Example:

prop set $p parameters [prop get $p defaultparams]

• deletefunction
  This is the name of a Tcl function which is called whenever property data instances are deleted. The only argument to the function is the value of the data item. This function may perform custom clean-up operations, such as taking down editing forms.

If the function can be found in the private slave interpreter of the property, it is executed there. Otherwise, an attempt is made to locate and run it in the main interpreter. When a property definition file is written with prop write , and the function can be located, it is encapsulated in the definition file and is available for all further interpreters which read the definition file.

• depends
  A list of properties which this property depends on as input data when it is computed. This information is used to automatically invalidate or re-compute data instances when underlying, more basic data changes on the chemical object. This is a recursive process. The invalidation of one set of properties is cascaded to all property instances on the chemical object which themselves depend on the just invalidated data. An update cascade can be triggered for example implicitly by statements such as atom set or ens new , or explicitly by ens taint . Note that simple data deletion commands such as ens purge are not triggers. Property data can be prevented from auto-deletion by using lock statements such as ens lock . The updated data which acts as the trigger is never itself deleted, even if a dependency cycle exists.

For this argument, it is explicitly allowed to set dependency property names which are not yet defined. No attempt is made to resolve these, but every loading or creation of a new property definition in another context will lead to a regeneration of the pre-parsed form of dependencies on all current internally held property definitions, potentially adding more, or different, dependency links. Property names which cannot be resolved are silently ignored.

• description
  This is a free-form string which describes the property.
• displaywidth
  A default value for the width of a display column, measured in characters. The default value is negative, meaning that scaling is dynamic.
• doi
  A digital object identifier for the property, if defined.
• email
  The email address of the creator of the property definition, useful in case a definition file is distributed and anybody has questions.
• enum
  This attribute defines enumerated symbolic names for specific property values. They can be used for mnemonic data input, and many output modes also use these names by default (cf. ens get vs. ens nget ). Input of enumerated values is always case-insensitive. It is not illegal to store data values of an enumerated property which are not represented by a corresponding symbolic name. These values are simply encoded as or decoded from numerical values.

For properties which consist of multiple independent sub-items, or sub-item data types, the enumeration is a list. The list is split, and each element applies to a different field in the order of field definitions. Examples for this are the compound and choice types, but not simple vectors. For simple vectors, the enumerated names apply to each element.

The enumeration is a string, where blocks corresponding to a specific value are separated by a colon. In the absence of an explicit value designator, the first block corresponds to value zero. Multiple words separated by commas are interpreted as alias names. On output, the first word is used as the canonic designator. Example:

prop set E_CLEARANCE enum \ “public:private:topsecret,destroy_before_reading”

The enumeration defines symbolic names for value 0 ( public ), 1 ( private ) and 2 ( topsecret , or alias destroy_before_reading ). On output, a data value 2 is always displayed as topsecret .

There are a couple of additional syntax elements. A code which is not in the automatic value sequence can be specified with a =n construct. The next value block, if it has not an explicit value designation of its own, is the value of the previous block plus one. Here is the enumeration for property A_LABEL_STEREO , with codes for standard parities and square planar stereochemistry:

M,-=-1:undef=0:P,+=1:U,C=2:Z,N=3:X=4

The normal 0,1,2... implicit value sequence can be changed to a power-of-two sequence by prefixing the enumeration string with a “^” character. In that case, the implicit numerical value o the blocks are zero, one, two, four, etc. For bit types (64-bit set and bit vector), this interpretation of the enumeration string is automatic and does not need to be spelled explicitly. Output of data items for properties with a bit-based implicit or explicit enumeration string consists of a set of all words with corresponding set bits, and one possible input format is a list of words for all bits that are set.

A final syntactic shortcut is the use of the “@” character as prefix. In that case, the enumeration is interpreted as a symmetric value set centered around zero. If there are three value blocks in the enumeration string, and no explicit value designations, the encoded numerical values are, from left to right, minus one, zero and plus one.

Characters with special meaning in parsing enumeration strings (equal, comma, colon) cannot be part of a symbolic name. Prefix characters may be used in enumeration names, but not as part of the first word.

• fielddatatypes
  A list of the field data types defined for the property. This is a subset of the information encoded by the fields attribute, and read-only.
• fieldindices
  A list of the choice indices of the field definitions. This attribute is useful only for choice and choicevector properties. This is a read-only attribute.
• fieldnames
  A list of the field names defined for the property. This is a subset of the information encoded by the fields attribute, and read-only.
• fieldproperties
  A list of the secondary properties associated with the fields of the current property. Fields which are not property-associated report an empty element. This is a subset of the information encoded by the fields attribute, and read-only.
• fields
  This attribute describes fields of a property. Its exact meaning depends on the data type of the property. The attribute is a nested list. Each list element is a list which contains a field name, its data type (optional, defaults to string ) and its unit (optional, defaults to undefined ). Simple properties which do not have sub-items do not possess a field set. For simple vectors, field names may be defined to facilitate convenient vector element access, but they have no effect on the internal representation of the property values. Example:

prop set A_XYZ fields {x y z}

echo [atom get $eh $label A_XYZ(x)]

The code above shows you how to name elements in a simple vector, and how to use them conveniently for retrieval. For the bit and bitvector data types, such fields are interpreted as individual bits.

However, the field set is essential for the definition of properties with a complex internal structure, such as data types compound and choice , and the vector variants thereof. For these types, the field set should be set up when the property is defined, and not changed at any time later. Example:

prop create E_MYCOMPOUND datatype compound \
fields {{name string} {fval double angstrom} \ {timestamp date}}

The statement above defines a compound property with three fields of different data types, one of them with a standard unit. Another use is for the definition of choice properties, which hold one of several possible variants of data, possibly of different data types:

prop create E_MYCHOICE datatype choice \
fields {{name string} {ival int} {timestamp date}}

The difference is that the example compound property contains three parallel fields of different data types, while the choice property has just a single field, but it can be of one of three different data types at any time. For the compound example, the string input or output form of a property value is a list of three values, where each element is parsed or formatted according to the data type of the field. For the choice example, the string format is a single two-element list, where the first element is the field name, which implicitly defines the data type, and the second element the value. Another example:

prop create E_MYCOMPOUNDVEC datatype compoundvec \
field {{name string} {ival int} {timestamp date}}

This is the specification for a compound vector. Each vector element is a compound of three data items. It could be set to a vector with two elements with a statement like

ens set $eh E_MYCOMPOUNDVEC \
{{“name1” 1 now} {“name2” 2 tomorrow}}

In the same fashion, choice vectors may be defined and set. A choice vector has a single data item per element, but each of these elements can be of a different data type from among the selection defined in the field set.

In addition to having a simple basic data type, the fields of complex data types can also be indirectly defined by a reference to a secondary property, which defines the structure of that field. These indirect references can be of complex types themselves. If the secondary property has a defined unit, this unit automatically sets the field unit, too. Example:

prop create T_NCBI_PUBLICATION_PATENT_ID \
datatype compound \
fields {{country string} {id T_NCBI_BIBLIO_PATENT_ID} {doc-type string}}

This compound property has three fields. The first and second are simple basic types, but the third is a complex property of type compound with its own fields, which potentially could themselves be recursively defined by more property references. The string representation of data for this definition is a list of three elements, where the middle element is itself a (potentially deeply nested) list.

If an input list for a complex property is shorter than the size of the field list, the rest of the items are set to their respective default values.

If the data type of a field cannot be decoded from the information currently in memory, an attempt is made to auto-load the data type I/O handler or, in case of property references, a property definition. If that fails too, an error occurs. Data types must be specified in lower case. This is needed to distinguish them from property names, which are upper case.

In case of symbolic names assigned to vector fields, the data type of the field is ignored and can be omitted, since it directly follows from the vector definition.

The native Cactvs file formats are designed to cope with complex property data for which the field definitions have changed between the time the file was written and when the data is read again. Every field is stored with its explicit name and data type. If the current property definition has additional fields compared to what is stored in the file, these fields are initialized to the default value. Fields which are no longer present in the property definition, but whose data type can be decoded from the information in the file are skipped and ignored.

If a prop get command is executed for this attribute, the output is a nested list. Each field description always contains the field name and the data type. If the property is of the choice or choicevector data type, the choice index of this field is appended next. Finally, there can be a property reference or unit element which is appended only if a secondary property reference or a standard unit is defined for the field. Ultimately, each field record can consist of two to four elements.

• fieldunits
  A list of the units of the fields defined for the property. Fields without a defined standard unit report an empty element. This is a subset of the information encoded by the fields attribute, and read-only.
• filetags
  A dictionary of the tags to be used for storing property data in various file formats. Currently, only the cml, cex and ctx I/O modules make use of this information. The keys of the dictionary entries are the file format names, the values the associated tag strings. This attribute does not trigger the autoloading of the specified I/O modules at the moment the attribute is set. Rather, these tags are resolved or disabled when a matching I/O module is loaded or unloaded by another mechanism, for example explicit loading ( filex load) or implicitly via a file suffix match. There can only be one tag per file format - the last is used in case of duplicates -, and the total number of different file formats a tag can be set for is ten per property, though the tag/file format sets of different properties do not need to be identical.
• filters
  This attribute is a list of filters which limit the definition range of a property to a subset of objects. Example:

prop set A_FREE_ELECTRONS filters classicatom

This statement, which just mirrors the actual definition of property A_FREE_ELECTRONS , tells the toolkit that the concept of free electrons is meaningful only for classic atoms with are an element, but not for super-atoms, query atoms and similar constructs which are subclasses of the atom minor object. In case there are multiple filters, the object must pass all of them in order to make a property data item defined. In case a specified filter name is not yet defined, an attempt to autol.oad the filter definition is made.

Currently, there is a maximum of 10 filters per property definition.

• flags
  The flags attribute holds a collection of general flags which encode the status and operation mode of the property. This is an enumerated set. Currently supported flag names include
• autobackup
  when property is changed via script, automatically save last values in backup property, i.e. A_LABEL in A_LABEL%
• expandpriority
  if a chemistry object such as an atom which hold a data item of this property is replaced by, for example, an expanded fragment, this data is transferred to the first replacement atom of the expanded fragment, and not computed from the properties of the new atom.
• fixedlength
  the size of property data is constant, even for data types where each data item could have an individual size, for example vector types, or strings. This information is useful to optimize storage layouts in various contexts. The actual length of the data item is either taken from the length property attribute, or from a sample data item on a chemical object which is expected to be a representative with the correct length. The short form fixedlen is an alias-
• globalexecution
  execute computation script and other scripts associated with this property always in the global interpreter, not a property-specific slave.
• labelkey
  this property is the minor object label key property for the object class it is associated with. For atoms, this is A_LABEL , for bonds, B_LABEL , etc. There can only be one such property per object class, and there must be one such property for all object classes which are not major objects. Changing the label key properties should only be attempted under extraordinary circumstances.
• localupdate
  the property computation function supports the update of a single specific object, not all objects of the same class linked to a major object (i.e. it can recompute data on a single atom and not just all atoms in the ensemble). This flag is for information only. Do not set it directly.
• locked
  if set, the property cannot be overwritten by reading property definition records describing properties with the same name. Individual attributes of the property may still be changed, including resetting this flag by script commands. This attribute is for example useful when the current definition of a property should be maintained after opening a cbs or bdb file - these include the property definitions used at the time the file was written.
• mergedata
  merge multi-line input data into a single data item, for example a string with tab separators. Has an effect only for input from multi-line MDL SD data fields.
• mergedefault
  if data of a non-computable property is present only on one object in an object merge operation, by default this property data is discarded in the process because there is no way to obtain it for the second object. If this flag is set, the object without the data is instead initialized with default data for the property, and the merge does not discard the original information from the object where it was present.
• none
  no flags are set. On setting, you can also pass an empty string.
• portable
  the property has no OS-dependent components such as DLLs or shared libraries for the computation module, or at least such components are available for all currently supported toolkit platforms.
• trace
  for scripted properties, trace execution when the computation function is called.
• trusted
  the property is trusted, relax usage restrictions and safety belt features.
• nominmax
  property has no definition of, or use for, minimum and maximum property values. This can reduce memory usage and increase performance.
• nosighandler
  run without signal handler to trap core dumps etc. even if property is not trusted. Signal handlers are expensive to set up and tear down, so if a function of an untrusted is called millions of times, this can significantly improve performance.
• notimeout
  disable computation timeout watchdog, even if a timeout value is set.
• synthetic
  the property was synthesized from minimal information without a proper property definition. Its name contains an asterisk to make this immediately obvious.This flag is for information only, do not set it directly.
• timing
  measure execution time for each computation function call and store in property metadata record on the major object the computation was performed for.
• threadtrace
  trace multi threading-related synchronization operations.

The standard bit set manipulation prefixes ( +,-,^) are supported. Example:

prop set A_XY flags +notimeout|trace

This command adds two flags to the current flag set.

• format
  Internal use only
• functionsource
  The source code of all of the script functions which are contained in the property definition. Code for functions which are not defined in the definition file, but for example reside in global library source files, are not returned.
• functiontype
  The type of computation function this property provides. Possible values are none (no computation function), c (built-in function), cdyn (dynamically loaded C module), tclscript (interpreted Tcl script), syncserver (synchronous client/server computation, Cactvs native RPC protocol), asyncserver (asynchronous client/server computation, Cactvs native RPC protocol), mail (send request and receive answer by email), altrepmodule (via an alternative data representation module), default (pseudo-function, a computation request always results in default values as result), disabled (temporarily disabled) and soap (communication via SOAP -based service). Python-enabled toolkit versions additionally support the pythonscript function type.

In most cases,.the function type is defined once when the property is set up and not changed later. One potentially useful application of changing the function type is when a computation is farmed out to a public or access-controlled server, for example because a local optional computation module is missing. Example:

prop set A_XYZ functiontype syncserver \
host www.xemistry.com port 17890 password xxx

After this statement, requests for atomic 3D coordinates will no longer be made by attempting to load a local module and execute the coordinate generation code on the client machine, but by communicating with the server specified above. this is a sample host name and not a real publicly accessible service.

• globalparameters
  This is the global version of the current parameter set. Its meaning is explained in the paragraph detailing the parameters attribute.
• helpful
  This is a list of source data properties which can be helpful for computing this property, but do not need to be present for the computation to succeed. This is for example used as a hint in network communication. If the property data is already present, it is sent, but no attempt is made to compute it, and the computation function will either do without these additional data, or compute it itself. This attribute has no effect for local computations. Its counterpart is the required attribute.
• host
  The name of the host to contact to request a remote computation for this property. This applies only to properties which are farmed out to servers and is ignored otherwise.
• id
  Get the internal integer ID code of the property. An ID value is automatically assigned when a property is created or, for built-in properties, on start-up. This is a read-only attribute and cannot be set.
• indirect
  If this attribute is set to the name of another property, the computation function of that other property is expected to compute the data for this property as a side effect. This property should be listed in the windfall attribute of the second property. When the computation of this property is requested in a script, the request is re-schedule as a computation request for the indirect property.

This mechanism is useful because you only need to maintain a single computation module or script for a set of properties which are computed synchronously. One of the properties provides the computation function, and lists the other properties in its windfall attribute. The other properties from the group all simply refer via an indirect attribute to the single property with the computation function.

• infourl
  A URL with information on the property definition, or an empty string if unset.
• invalidation
  This set of flags describes under which circumstances the property data attached to an object is automatically discarded. The flag sets augments the property dependency relationships defined via the depends attribute. These are s global operations on a structure beyond the scope of isolated property data changes. With the exception of the never value, multiple code words can be usefully combined into a list. The currently supported flags are:
• never
  no automatic invalidation
• atomchange
  any major atom change in an ensemble, such as an atom type or element change, or the addition or deletion of atoms
• bondchange
  any major bond change in an ensemble, such as a bond type or order change, or the addition or deletion of bonds
• stereochange
  any stereochemistry change in an ensemble
• groupchange
  any major group data change in an ensemble, similar to the atomchange and bondchange criteria
• merge
  data of two objects is merged
• 3dop
  the 3D structure of an ensemble changes in a way that affects inter-atomic distances
• 3dglop
  the 3D coordinates of an ensemble change globally, but inter-atomic distances remain constant
• shuffle
  the order of atoms changes in an ensemble
• hadd
  hydrogens are automatically added or removed to an ensemble
• dup
  a major object is duplicated.
• atom
  the atom list composition changes for an ensemble
• bond
  the bond list composition changes for an ensemble
• mol
  the molecule list composition changes for an ensemble
• ring
  the ring list composition changes for an ensemble
• sigma
  the sigma system list composition changes for an ensemble
• pi
  the pi system list composition changes for an ensemble
• group
  the group list composition changes for an ensemble
• surface
  the surface patch list composition changes for an ensemble
• ringsystem
  the ringsystem list composition changes for an ensemble
• reaction
  reaction membership changes for an ensemble, or the ensemble set changes for a reaction
• dataset
  dataset membership changes, either for an object in a dataset, or the dataset object proper for which the object set changes
• file
  the association of an object with a structure file changes, for either of the sides
• table
  the association of an object with a table object changes, for either of the sides
• network
  the association with a network object changes
• vertex
  the vertex list composition changes on a network object
• connection
  the connection list composition changes on a network object

Example:

prop set E_MY_UNIQUE_ID invalidation dup

Property data for E_MY_UNIQUE_ID is discarded from the cloned structure when duplicating ensembles.

A signal indicating that certain operations have taken place can be explicitly sent by the taint major object subcommands. Example:

ens taint $eh {atomchange bondchange}

Above command leads to the shedding of all property data on the ensemble which is not robust with respect to atom and bond edits. These events are always global on the controlling major object. It is not possible to signal an update event for a single atom or bond.

• keycolumn
  The name of a database column for keyed properties which are retrieved from a database-style source. In case of data sources which do not have a concept of columns, this is an empty string.
• keydatatype
  The data type of the access key of a keyed property. If the key is another property ( keyproperty attribute), the data type is derived from the property definition of the key property and potentially its field index and should not be changed. For keys which are not properties, this attribute must be set. It can be any supported property data type, including those which need to be loaded as external handler module on demand.
• keyenum
  An enumeration similar to the enum attribute for the encoding and decoding of key values for keyed properties. It the key is a property, this attribute overrides the enum attribute the key property might possess itself in the context of key operations.
• keyproperty
  The name of a property which is used as access key to obtain property values by retrieval from an external data source. This must be resolvable to a property definition. If no key property is used, this is an empty string.
• keyreference
  The data source for key-based property retrieval, encoded as a URN . The protocol field of the URN determines the name of the key resolver used. An attempt is made to auto-load the proper key resolver module if the handler has not yet been loaded.The rest of the URN fields are interpreted by the resolver module. They usually follow the standard URN syntax with user IDs, passwords, hosts, ports, and a file or database table component, with reasonable defaults if any parts are not specified.
• keywords
  A list of keywords associated with the property.
• length
  The data length of the property. A value of -1 (the default) indicates that the length should be expected to vary. The exact interpretation of the attribute is dependent on the data type. For example, for strings and Unicode strings it is the character count, for blobs the byte count, and for vectors of constant element size (for example, floating-point and integer vectors) the element count. If a length is set, it is only used as a hint for internal optimizations. It becomes a binding statement only if the fixedlength bit in the flags property attribute and/or the dbflags attribute has been set.
• license
  The license class associated with this property. Setting the license to a standard type updates the associated URL with a standard location.
• licenseurl
  A URL with details about the property license.
• literature
  This is a free-form string for a literature reference describing the meaning and/or algorithm behind the property.
• logfile
  In case the property logging mode is set to write to a file, this is the name of the file the log output is written to.
• logmode
  This attribute is an enumerated set of words which describe the handling of log or debug output during calls of the property computation routine. If any mode except ignore is set, standard output and standard error are redirected to the selected output channel before the function is called, and restored to the previous channels afterwards. The default should be ignore , because redirection involves several system calls and therefore can significantly slow down the computation of trivial properties. The supported values are:
• ignore
  neither redirection nor restoration
• suppressed
  redirection to /dev/null or NUL on Windows
• console
  redirection to the /dev/console (not on Windows)
• filewrite
  redirect to the file specified in attribute logfile . The file is deleted before each computation function call.
• fileappend
  redirect to the file specified in attribute logfile . The output is appended.
• stdout
  redirect both standard output and standard error to original standard output
• stderr
  redirect both standard output and standard error to original standard error
• magic
  Define a magic value for the property. This is a convenient way to mark one specific property data value as an indicator for a special condition outside the normal validity range of the property. The attribute must be a parseable representation of a property value.

Magic values are not written out explicitly in native Cactvs binary files. If therefore the magic value changes, newly read magic property data values automatically assume the current magic value because they are set from the current property definition, not the file contents.

• max
  The maximum expected property value. This value is not enforced - it is primarily intended to be used to compute color scales etc. from property values. See also the min attribute. The attribute must be set to a valid string representation which can be decoded with the current property definition, and should not be the same as either the magic or null attributes.
• menugroup
  The name of a menu group the property should be sorted into under the name specified in menuname . This is only used in graphical user interfaces.
• menuname
  This is an alternative, user-friendly name to be used in menu displays and similar circumstances. This attribute is a free-form string. Since it is not decoded as property name, it does not need to adhere to the Cactvs property naming conventions.
• mergefunction
  The name of a function which is called when property data attached to a major object is prepared for merging, for example in the context of the ens merge command. The type of the function must be the same as that of the compute function. In case this is a Tcl procedure, it is called with the the two object handles as argument.

If the merge function can be found in the private slave interpreter of the property, it is executed there. Otherwise, an attempt is made to locate and run it in the main interpreter. When a property definition file is written with prop write , and the function can be located, it is encapsulated in the definition file and is available for all further interpreters which read the definition file.

The purpose of the merge function is to modify the data values in the second object in order to prepare its merge with the first object. It must not perform any merge operation itself. For example, the built-in merge functions for minor object labels (properties A_LABEL , B_LABEL , etc.) adds an offset to the label values of the second object in order to avoid the assignment of identical labels to two minor objects in the merged ensemble. The merge function for atomic 2D coordinates (property A_XY ) scales the coordinates of the second object to fit with the scaling of the first, and then adjust the coordinates so that the structures are displayed side by side after merging.

• min
  The minimum expected property value. This value is not enforced - it is primarily intended to be used to compute color scales etc. from property values. See also the max attribute. The attribute must be set to a valid string representation which can be decoded with the current property definition, and should not be the same as either the magic or null attributes.
• name
  This is the name of the property. Changing it after it has been defined originally is generally considered bad style, but it is possible. Internal data references use pointers, not strings with names.
• nativename
  Internal use only.
• null
  The string representation of the first NULL property value. Usually this is set to the same string as the magic attribute, or an empty string. The value must be a valid string representation that can be decoded with the current property definition if it is not an empty string. An empty string disables the null value check and is not parsed, even if that is a valid representation of a property value.
• null1
  This is an alias for the null attribute above.There are a maximum of three recognized NULL values - this follows the SPSS statistical analysis package data model. The second value is only applied if the first value is set, and the third only if the first and second are defined.
• null2
  The second null value.
• null3
  The third null value.
• nullrange
  A list with a pair of elements defining an inclusive lower and upper value limit for property values regarded as NULL data. The format of each of those elements is the same as for the null attribute described above. This range criterion is distinct from the normal null parameter - both may be used in combination. For properties where the associated property data type does not support larger/smaller comparisons, this attribute is not useful.
• objclass
  The name of a chemical object class the property is attached to. By default, this is automatically set by decoding the prefix of the property name, and it is highly recommended that you do not override this automatic prefix scheme. attachment is an alias for this attribute.
• objectfile
  This is the name of the shared object (DLL, Bundle) file for a dynamically loaded computation modules. This attribute is empty for properties which do not possess a compiled computation module.
• originalname
  The original name of the property. When data is read from a file, and the tag the data is stored under does not match the Cactvs property name, this attribute is automatically globally updated and set to the name as found in the file. There is currently no mechanism to remember multiple original names from different files in parallel.

When property data is written to a file, and an original name is set for an output property, this name is used in preference to the Cactvs name if the file syntax allows it. For example, this is the attribute which should be changed in order to set arbitrary SD data field names for property data.

This attribute can be set to arbitrary strings and does not need to follow the Cactvs property naming conventions. Nevertheless, names set via this attribute are used to resolve properties only as fall-back. The priorities for name resolution are aliases first, then proper Cactvs names, and finally original names. Menu names are never used for property lookup.

• orcid
  The ORCID code of the author of the property definition (see www.orcid.org).
• outputlevel
  Deprecated. Originally intended to allow the selection of groups of properties up to a certain level of importance in output sets without the need to name them explicitly. The higher the specified level for a property, the more important it is supposed to be. Its output level value is compared to the output level of, for example, a structure file handle, and the property is included if its level is equal to or larger than the file object level. In practical experience, this does not work too well. In any case, the decision to include or suppress the data of a property via this criterion can be overruled by the property outputmode attribute, and the write and suppress lists of structure file objects.
• outputmode
  This attribute is one of several attributes which control whether data for a property is included in output or not. It can be one of three values:
• suppressed
  the data is never output
• standard
  the property output is decided by other factors, such as the outputlevel attribute or property control lists of structure file objects
• forced
  the property is always written, regardless of other settings.

The default value is standard .

• path
  The repository path for displaying hierarchical repository trees. This attribute is independent of any file system paths.
• parameters
  This is a keyword/value list of the adjustable parameters used in the property computation routine. It must be set as a proper Tcl list with an even number of elements. or, equivalently, a Tcl dictionary.

For multi-threaded scripts, this attribute is thread-local. When a script thread first refers to a property, its thread-local parameter set is copied from the current global setting. All further manipulations only change the thread-local copy. The only exception is the base thread, which updates the master copy. In case a script thread needs to change or query the global setting, it can use the globalparameters attribute. For the base thread, these two attribute names are identical. The split of the parameter set into thread-local versions allows multiple threads to compute different variants of data for the same property simultaneously.

Convenient methods to access the parameter set are via statements like

array set params [prop get $pname parameters]

set paramdict [dict create {*}[prop get $pname parameters]

The first example initializes the array variable params to proper element names and values. The second method initializes a Tcl dictionary.

The reverse path is also straightforward:

prop set $pname parameters [array get params]

Please refer also to the paragraph about the computefunction attribute for more details on how to access the parameter set in computation functions.

• password
  A free-´form text password which is transmitted as part of the request data for computations which are performed on a remote server. The server may use this information to grant or deny the processing request. This attribute is not used for local computations.
• port
  The port used to contact a remove computation server. The default port for distributed Cactvs computation servers is 16520. For local computations, this attribute is ignored.
• precision
  The number of significant digits after the decimal point for floating-point data.
• precompute
  This is a list of properties for which an attempt is made to pre-compute them before the computation function for this property is called. In case the computation fails, it is silently ignored.

This attribute is primarily useful to control the location of computation for low-level property data when using server-based set-ups. In case the computation is performed implicitly in the computation function running on a server, the low-level computations also take place there if they are not themselves farmed out. If these properties are listed as precompute properties, they are computed on the client side before the request is sent.

• profile
  Internal use only.
• regexp
  This attribute provides a method to check the encoding of property data values that are read from strings, or from Tcl interpreter objects. The argument is a regular expression. If input data does not match it, it is rejected. The check is only performed at the time of input via the handler function. Compiled code manipulating internal data structures directly can still produce data which does not pass the expression filter.

Data format handler modules need to implement this function individually. At this time, the data types which support this are string , stringevector , unicode and unicodevector . Data format handlers which do not support regular expression filtering silently ignore it. The match operation of the regular expression can be further controlled with the regexpflags attribute.

This attribute can be used in combination with the constraints attribute.

Example:

prop set E_REGID regexp {TinyPharma[0-9]+}

• references
  Cross references of the property definition. This is a nested list of class UUIDs and reference type tags.
• regexpflags
  This set of flags controls the match condition for regular expressions set via the regexp attribute. It is a set of flags. The currently supported flags
• none
  no flags, can also be set as empty string
• extended
  use extended regular expression syntax
• nocase
  ignore case

Example:

prop set E_REGID regexpflags {nocase extended}

• regid
  The official registration ID of the property. Properties of general usefulness can be registered and be assigned an official numerical identifier. This attribute must be set by a (potentially, digitally signed) property definition record. It cannot be set by script commands.
• required
  This attribute is a list of properties which need to be present before a remote or threaded computation of property data can be attempted. In client/server computations, the client tries to compute all these properties and send the data (together with helpful, but not mandatory data - see helpful attribute) to the server. In case of a threaded property computation, the required properties are computed on the original object before it is duplicated for use with the independent thread. This attribute has no effect on local computations.
• scale
  A scaling value for numerical data. The default is 1.0. This attribute is defined, but currently only passed on for MDL XDF file format output. It has no effect on the interpretation of property data
• separator
  A field separator which enables word-indexed addressing in string-style property data types. Example:

prop create E_MYID separator :

set eh [ens create $smiles]

ens set $eh E_MYID “p345:c64587:u45”

ens show $eh E_MYID(1)

This returns “c64587”. In case the separator is more than a single character, any of the listed characters is considered a word boundary. The split occurs on any sequence of characters from the separator set. The default separator is white space.

• sourcefile
  The name of the source file of a compiled property computation module. No guarantee is given that the file is contained in any specific toolkit distribution.
• status
  A read-only attribute which lists the currently set flags in the internal status word of the property. This is primarily useful for debugging purposes.
• testdata
  The name of a file with sample structures and result data which can be used to verify the correct computation of property data in an installation. It should contain a reasonable set of structurally different structures and result data for this property which has been verified to be correct. The most suitable type of file for this data is a native Cactvs binary structure file.

When a property definition file is written with the prop write command, this data is encapsulated in the definition file. When the definition file is later read by an application, the data is written out to a temporary file, and the file name returned for this attribute is the name of the temp file, not the original file name. By this mechanism, it is not required to supply test data files as a separate files which may be difficult to locate and are easy to get lost.

If this field is empty, which is the default, no test data is present.

• timeout
  A timeout for the property computation in seconds. If it is set to zero, the default, no timeout is in effect. Once a property computation exceeds its maximum computation time, it is aborted, and the computation fails. The timeout value is the total CPU time spent in the call to the computation routine. This includes all time spent with the computation of low-level properties which are requested inside the computation function of the current property.

Computation aborts can lead to serious memory leaks. Time-outs should therefore not be used without need. Additionally, checking the time and setting interrupt handlers involves multiple system calls. The computation of trivial properties can slow down significantly if time-outs are enabled.

Time-outs may be stacked if required, i.e. a timed computation routine can request the computation of another timed property. In that case, in the inner computation routine, both timers are active, and the timeout of any of these will lead to an overall computation failure.

• trace
  This is a deprecated attribute to control the tracing of computations in script functions. Please use the flags attribute.
• traits
  A couple of indicator bits describing the general type of the property. The value can currently be none , or any combination of hashcode , stereodescriptor , rendering , pixelimage , vectorimage , linenotation , 3dmodel , spectrum and interactive .
• unit
  An information string describing the unit the proper data is using. The string is not parsed to enforce a recognized set of units, but built-in unit conversions only work if a standard unit is used. Supported unit sets currently include length, energy, mass, time, pressure, temperature, volume and mols. For any of these, a standard range of units is recognized (e.g. picoseconds/ ps to years/ y for time, and Joules, kcals , etc. for energy).
• version
  The version of the property definition. This is a free-form string.
• versionuuid
  The version UUID associated with this property definition version.
• width
  The width of the property. This is the number of slots the property is occupying in the data storage area of chemistry objects. The vast majority of properties has a width of one, and this is the default. The only standard exception are certain bond properties which are directional, i.e. there are two values, one for looking from the first atom to the second, and a different value for looking into the reverse direction. These bond properties have a width of two. In principle, it is possible to define properties of larger width, or to use this functionality on properties which are not attached to bonds.

Property values of properties which are of a width larger than one are returned and input as lists in Tcl scripts. The length of these lists must be the same as the width in the property definition. It is not possible to access single-slot subsets of the property data directly.

Use of this feature is no longer recommended. For multi-value properties, the use of compound data type properties, or a split into two independent properties are often better solutions.

• windfall
  A set of properties that is attached as result data as a side effect of computing this property. For local computations, this is for information only. For server property computations, it prepares the client to expect these additional property data records to be transmitted. Note that this list is not supposed to include minor, dependent properties which are needed as input for the computation. Rather, this should be used if there are two or more potentially interesting result properties which are most conveniently computed in parallel, and where computation of any of the additional properties in a separate request would essentially require to run the same computation over again.

In a typical set-up, the windfall properties do not define their own computation functions, but redirect to the computation of this property via an indirect attribute, resulting in a set of two or more properties which are always computed together and where the combined computation function is maintained in a single place, on the property which lists them as windfall results.

The prop set command supports a special attribute value syntax for manipulating bitset-type attributes. 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:

prop set E_SCREEN flags +locked:fixedlength

prop set E_SCREEN flags -locked

prop setparameter

prop setparameter propertyname ?parameter value?...

prop setparameter propertyname dictionary

Set zero or more computation parameters. In multi-threaded scripts, this effects only the thread-local parameter set. Only the base interpreter, and its slaves, manipulate the global parameter set, in addition to its own thread-local set.

In the second command variant, the dictionary argument must be a properly formed Tcl dictionary with suitable keyword/value pairs. If that is the case, the dictionary is implicitly expanded and processing proceeds as in the first command variant.

An attempt to set a parameter whose name is not listed in the current parameter set fails with an error. This is a safety mechanism to prevent typos in parameter names. Nevertheless, setting such an unknown parameter does succeed internally. In order to force the addition of a new parameter, the statement can be written with a catch command:

catch {prop setparam $pname my_new_parameter “New World!”}

This command can be abbreviated as prop setparam .

There is no command to unset a single parameter. This can be done by retrieving and manipulating the complete parameter list via a command like

set d [dict create {*}[prop get $propname parameters]]

dict unset d $obsolete_param

prop set $propname parameters $d

prop sqldecode

prop sqldecode propertyname value

Attempt to decode a property value from a string formatted in SQL -style encoding. If it succeeds, its standard Tcl representation is returned. Otherwise, an error results.

prop sqlencode

prop sqlencode propertyname value

Encode a property value in SQL formatting. The value parameter must be a valid representation of the property value in its Tcl format. If the decoding succeeds, and the data type handler supports SQL formatting, the returned value is suitable for constructing SQL statements.

prop sqlformat is an alias for this command.

prop string

prop string propertyname

Get the XML-style property definition record as a string. This is equivalent to writing out the property definition and reading the output file as text data.

prop subcommands

prop subcommands

This command returns a list of all the subcommands of the prop command.

prop unalias

prop unalias ?alias_name?...

Remove one or more alias definitions introduced by a prop alias command. If a specified alias name does not exist, it is silently ignored. If an existing property was hidden by an alias definition, it becomes visible again. However, existing property data in the name of the old alias on chemical objects continues to refer to the property definitions it was alias-mapped to when it was created.

prop write

prop write propertyname ?filename?

Write the current definition of the property to a file. The file can be loaded into future script interpreters explicitly (see prop read command) or implicitly via the property definition auto-load mechanism. If no file name is given, the name of the file is automatically constructed from the property name in lower case and the suffix . xpd for the new-style XML property definitions .

In addition to normal file names, the magic names stdout and stderr may be used, as well as already opened Tcl socket and file handles, plus pipes indicated by a file name which starts with “|”. Writing to Tcl channels is not supported on the MS Windows platform.If the file name argument is a directory, the file name is still automatically generated, and the file written in that directory. If a file name with an explicit .prp suffix is specified, the output is written in the legacy keyword/value ASCII -based file format. Old property definition files continue to be supported for both input and output. They are backward-compatible with earlier toolkit versions, though they cannot store all content of the newer XML format.

If the output is written to a regular file named in the command, the suffix .xpd is automatically added if necessary, and the output contain a single property definition record. By writing to a Tcl channel, it is possible to write multiple properties into a single file, and these can be read in a single operation by the prop read command. For explicit file input, neither one of the two standard suffixes nor the standard file name derived from the property name are mandatory, but the naming convention must be adhered to in order to enable auto-loading of property definitions.

It is possible to write out built-in property definitions. For reference purposes, current toolkit distributions contain a BUILTIN directory which contains dumps of the property definitions of the built-in property set.

The command returns the name of the file written to.