The prop Command

The prop or property command is used to create, modify, query and delete property definitions.

The command has the following subcommands:

prop addparameterdict

prop addparameterdict propertyname parametername datadict
Prop.Addparameterdict(property/pref,parametername,dict)
p.addparameterdict(parametername,dict)

Add a new parameter to a property definition. The recognized dictionary items are the same as in the prop getparamdict command, with the exception that all parsed values are ignored - parameter values, defaults, min and max values are defined via string data, for which a parse is attempted and an error generated if it fails. All dictionary items are optional. If a parameter definition attribute is not defined in the dictionary, an empty or undefined default parameter specification field value is entered.

If the named parameter is already defined, an error is produced.

The command returns the property name or handle.

prop addparamdict is an alias to this command.

prop alias

prop alias
prop alias propertyname
prop alias propertyname aliasname ?propertyname aliasname?...
Prop.Alias()
Prop.Alias(propertyname/pref)
Prop.Alias(propertyname/pref,aliasname,?property/pref,aliasname?...)
Prop.Alias(dict)
p.alias(?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 property or alias name the new alias maps to must be resolvable at the time of definition. Alias names must conform to the Cactvs property naming scheme, e.g. is not not possible to define arbitrary aliases. This is not an equivalent for setting the originalname property attribute.

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. If only the property name is specified, a list of the aliases for this property is reported.

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 scripts of the toolkit include a set of alias definitions which map older, less systematic property names as aliases to current official property names.

prop cast

prop cast srcproperty/srcdatatype dstproperty/dstdatatype value
p.cast(destination=,value=)
Prop.Cast(srcproperty/srcdatatype,dstproperty/dstdatatype,value)

This command is used to convert or reformat property data. Its arguments are different from that of other prop subcommands. In addition to a simple property name, an indexed property name or the name of a toolkit property data type can be specified both as source and target description.

The value argument is parsed into a toolkit data item using the input routines associated with the property datatype, property field datatype, or directly specified datatype. All data format variants supported by a data manipulation command such as ens set are allowed, and different input formats may lead to the same internal representation.

The data item is then cast to the target datatype, and re-output as Tcl or Python interface object using the output routines associated with the target data type. There is no permanent storage of the value in any object. If there is a direct cast path encoded between the source and target data types, it is used, otherwise internally an attempt is made to convert the data item to a string and re-parse it with the target data type I/O routines.

The return value of the command is the argument value encoded in the target data type and/or field format.

Examples:

prop cast int string 3
prop cast E_NAME E_NAMESET “a single name”

The first line casts an integer 3 to a string with characters “3”. The second example casts the input value from string (the data type of E_NAME ) to a single-element string vector (the datatype of E_NAMESET ).

prop compare

prop compare propertyname value1 value2 ?cmpflags? ?auxvalue1? ?auxvalue2?
prop compare propertyname(field) value1 value2 ?cmpflags? ?auxvalue1? ?auxvalue2?
prop compare datatypename value1 value2 ?cmpflags? ?auxvalue1? ?auxvalue2?
p.compare(value1=,value2=,?comparisonflags=?,?auxvalue1=?,?auxvalue2=?)
Prop.Compare(propertyname?(field)?/pref?,value1=,value2=,?comparisonflags=?,	?auxvalue1=?,?auxvalue2=?)
Prop.Compare(datatypename/dref,value1=,value2=,?comparisonflags=?,?auxvalue1=?,	?auxvalue2=?)

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 or interpreter language 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 or Python 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 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:

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.

This function is not supported in the Python interface.

prop create

prop create propertyname ?attribute value?...
prop create propertyname dict
Prop(propertyname,?attribute,value?,...)
Prop(propertyname,dict)
Prop(propertyname,?attribute=value?,...)
Prop.Create(propertyname,?attribute,value?,...)
Prop.Create(propertyname,dict)
Prop.Create(propertyname,?attribute=value?,...)

Create a new property definition, and optionally set attributes of the new property.

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 scripting language 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 Tcl catch or Python try/except statement. In the Python case, the simple constructor always succeeds (due to lack of language features to support partial failure in the constructor), while the factory function Prop.Create() works like the Tcl equivalent.

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.

Creating a property for which already a loadable definition exists in the installation environment results in this definition to be read first. The creation attributes then overwrite the values of the existing definition. In order to create a new property with all default fields, use the prop xcreate variant.

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 ?alloworiginalname?
Prop.Defined(property=,?alloworiginalname=?)

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.

If the alloworiginalname flag is set, the property lookup will also use original names (such as SD file field tags) for identification. By default, only native toolkit names are recognized.

prop available is a deprecated alias of this command.

prop delete

prop delete propertylist ?force?
p.delete(?force=?)
Prop.Delete(properties=,?force?)

This command deletes zero or more property definitions from memory. It does not remove the files the property is defined by, if these exist. 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 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 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.

The command returns the number of properties successfully deleted.

prop dup

prop dup propertyname newpropertyname
p.dup(newpropertyname)
Prop.Dup(propertynamename/pref,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
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
p.get(attribute)
p.attribute
p[attribute]
Prop.Get(pname/pref,attribute)

Get the value of a property attribute. The property attributes are explained below 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?
p.getparameter(parameter=,?usedefault=?)
Prop.Getparameter(propertyname/pref,parameter=,?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 getparameterdict

prop getparameterdict propertyname parametername
p.getparameterdict(parameter=)
Prop.Getparameterdict(propertyname/pref,parameter=)

Get the full definition of a property parameter, in addition to its current value. The command returns a dictionary which contains the following entries:

Parsed value entries are omitted if their corresponding string value is not defined, or the parse with the datatype-specific decoder fails. Parsed values are returned with the normal mapping to scripting language types (e.g. integer values if the parameter type is an integral numeric type), all other items are strings.

prop getparamdict is a command alias.

prop isdefault

prop isdefault propertyname value
p.isdefault(value)
Prop.Isdefault(propertyname/pref,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
p.ismagic(value)
Prop.Ismagic(propertyname/pref,value)

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

prop isnull

prop isnull propertyname value
p.ismagic(value)
Prop.Isdmagic(propertyname/pref,value)

Check whether a property data value is the same as one of the potentially multiple defined NULL values.The return value is the boolean test result.

prop list

prop list ?pattern? ?constraints?
Prop.List(?pattern=?,?constraints=?)

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 set to a combination of the bit flag values computable and testable (or none, if an explicit unset value is desired). These flags restrict the output to properties which have a true value in the attributes of the same name.

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.

The return value is a string list for Tcl , or a reference list for Python .

prop query

prop query keyword ?objectclass? ?mode? ?casesensitivity?
Prop.Query(keyword=,?objclass=?,?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 UUID s. 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 UUID s of the matched properties.

prop read

prop read filename ?doinstances?
prop read dirname ?doinstances?
prop read all
Prop.Read(filename=,?doinstances=?)
Prop.Read(“all”)

The first command variant reads 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 a false boolean value, 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 second command variant identifies all property definition files in XML -based or old keyword-based formats in the specified directory and loads them, without enforcing a specific load order. In the Python variant, the argument name is always filename, regardless whether the argument value is a file or directory name.

The third variant traverses all directories in the property autoloader path and executes a directory property read, like the second command version, on all readable directories.

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

prop readblob

prop readblob data
Prop.Readblob(data=)

Decode a property definition stored in the data argument without the need to access the file system. The data argument is expected to contain a single XML -style property definition record.

If the decoding succeeds, the return value is the name or reference of the read property.

prop ref

Prop.Ref(propertyname)

Python -only method to get a reference of the property, which allows terser attribute retrieval commands and other operations.

prop reload

prop reload propertyname
Prop.Reload(property=)

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, even in Python (i.e. no reference).

prop set

prop set propertyname ?attribute value?...
prop set propertyname dict
Prop.Set(propertyname/pref,?attribute,value?,...)
Prop.Set(propertyname/pref,dict)
p.set(?attribute,value?,...)
p.set(dict)
p.attribute = value
p[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:

 

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 setparameterdict

prop setparameterdict propertyname parametername datadict
Prop.Setparameterdict(property/pref,parametername,dict)
p.setparamdict(parametername,dict)

Modify an existing parameter of a property definition. The recognized dictionary items are the same as in the prop getparameterdict command, with the exception that all parsed values are ignored - parameter values, defaults, min and max values are defined via string data, for which a parse is attempted and an error generated if it fails. All dictionary items are optional. If a parameter definition attribute is not defined in the dictionary, the existing definition is retained.

If the named parameter is not already defined, an error is produced.

prop setparamdict
 is an alias to this command.

prop setparameter

prop setparameter propertyname ?parameter value?...
prop setparameter propertyname dictionary
p.setparameter(?parameter,value?,...)
p.setparameter(dict)
Prop.Setparameter(propertyname/pref,?parameter,value?,...)
Prop.Setparameter(propertyname/pref,dict)

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
Prop.Sqldecode(propertyname/pref,value)
p.sqldecode(value)

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

prop sqlencode

prop sqlencode propertyname value
Prop.Sqlencode(propertyname/pref,value)
p.sqlencode(value)

Encode a property value in SQL formatting. The value parameter must be a valid representation of the property value in its Tcl or Python 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
Prop.String(propertyname/pref)
p.string()

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
dir(Prop)

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

prop test

prop test ?propertyname?...
Prop.Test(?propertyname/pref?,...)
p.test()

Run the property test functions on a list of properties. The return value is a list of integers containing one integer per property. In case a listed property does not have a test function, the value is -1. If a test succeeds, the value is one. If it fails, the value is 0, and in case of a critical error in any of the tests, the test is canceled and the error reported.

prop unalias

prop unalias ?alias_name?...
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 use

prop use propertyname
p.use()
Prop.Use(propertyname/pref)

Warm up property computation, make sure that the property definition and associated computation dynamic libraries are loaded and the property computation is internally initialized. The latter function works by re-computing the property either on specifically set structures, reactions, etc. ( warmupobjects attribute), or on default ensemble/reaction/etc. objects from ::cactvs(default_warmup_structure) or ::cactvs(default_warmup_reaction ). The class of warm-up object corresponds to the major object of the property (i.e. ensembles for atom/bond/ensemble properties, reactions for reaction properties, etc.). The warm-up objects are created only temporarily for the duration of the command, and a failure to compute the property on a warm-up object is no error.

Calling the computation function, if it exists, during program initialization is intended to allow the computation routine to perform initialization tasks, such as decoding fragments or setting global variables, so that later invocations in a multi-threaded script or application are safe even if the function writer was not careful about asset mutex locking during first-call initializations, and property database and property reference locking can be omitted if the overall property database is locked - see : :cactvs(property_lock) control variable.

The command returns nothing.

prop verify

prop verify propertyname ?objecthandle?...
Prop.Verify(propertyname/pref,?objecthandle/objectref?,...)
p.verify(?objecthandle/objectref?,...)

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 command) 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 verify E_CAS $eh

This command checks if property E_CAS is set for the ensemble, whether it is formatted correctly by calling the scripted Tcl check function defined for property 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 check is an alias for this command.

prop write

prop write propertyname ?filename/dirname/emptystring?
p.write(?filename/dirname/emptystring?)
Prop.Write(propertyname/pref,?filename/dirname/emptystring?)

Write the current definition of the property to a file. The file can be loaded into other 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 or Python socket and file handles, plus pipes indicated by a file name which starts with “|”. Writing to Tcl or Python 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 into 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 contains a single property definition record. By writing to a Tcl or Python 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.

If the file name argument is an empty string, or None for Python , the definition is returned as an in-memory string blob and not written to disk.

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 if the output is not a blob.

prop xcreate

prop xcreate propertyname ?attribute value?...
prop xcreate propertyname dict
Prop.Xcreate(propertyname,?attribute,value?,...)
Prop.Xcreate(propertyname,dict)
Prop.Xcreate(propertyname,?attribute=value?,...)

Create a new property definition, and optionally set attributes.

The command, and the difference to the normal prop create command is explained in the paragraph on that command.