The lhasa Command

The lhasa command manages Lhasa objects. A Lhasa object is able to read and utilize the original Lhasa transform files as source of detailed reaction knowledge.

The command has the following subcommands:

lhasa append

lhasa append lhandle ?property value?...
l.append({?property:value,?...})
l.append(?property,value,?...)

Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data.

The command returns the first data value.

lhasa assign

lhasa assign lhandle srcprop dstprop
l.assign(srcproperty=,dstproperty=)

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

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

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

Examples

lhasa assign $lh L_IDENT L_NAME

lhasa classify

lhasa classify lhandle ehandle ?fgclass?

Sub-classify functional groups in the structure according to the Lhasa definition. This is used for checking compatibility of standard reaction conditions with functional groups outside the reaction path.

This command is currently not fully implemented.

lhasa collection

lhasa collection
Lhasa.Collection()

Look into the Lhasa transform directory and identify pre-compiled transform files stored therein. The command returns a tuple of the found transform IDs, which are valid identifiers for the lhasa read command.

lhasa create

lhasa create ?ruledata? ?subroutinedata?..
lhasa create -fromfile/-fromfiles rulefilename ?libfilename?...
Lhasa(?ruledata?,?subroutinedata?,...)
Lhasa.Create(?ruledata?,?subroutinedata?,...)
Lhasa.CreateFromFile(rulefilename,?libfilename?,...)

Create a new Lhasa object and return its object handle. Usually, the content of a transform source file and any required subroutine file contents are specified at creation time. These are directly parsed into an internal byte code representation.

The first command variant expects the rule source code as Latin1 or UTF8 (with BOM ) string blob data, while the second version expects a set of file names, with the file containing Latin1 or UTF8 (with BOM ) source code. The first version is useful in contexts where, for example, the rule source is extracted from a database or other non-file source. The second variant automatically sets the sourcefiles attribute, which is not possible for the first version because the file name is not directly known.

The rule data can either be the source code for a single transform (with one set of 1D and optionally 2D and New1D PATRAN patterns), or a concatenation of one or more classification rules (for example, for the determination of subclasses of functional groups). It is not possible to load more than one transform into a Lhasa object, but any number of these objects, with the same or different rule sources, may be instantiated at any time.

If subroutine source code is used, every subroutine source block must be passed as its own argument. It is neither possible to concatenate transform sources and subroutine sources, nor to used merged subroutine source files. Empty subroutine data blobs or filename arguments, or, for filename input, file names which are actually directories are silently skipped. When reading a rule, an attempt is made to automatically load missing library files by trying to locate a file named, in lowercase, like the subroutine name with a .csr suffix along the directory path specified in : :cactvs(lhasapath) or its Python dictionary equivalent. This only succeeds if the subroutine name to source file mapping follows this scheme - this is the case for most of the original Lhasa library files, but not all of them.

Certain object metadata components, such as the transform name and ID, or the substructure match patterns, are automatically extracted from the rule source during parsing and set as object attributes.

The lhasa react sub command requires the presence of one or more 2D or New1D retro-reaction patterns in the rule source, and these should, on the left - retro-reaction reagent - side, correspond to the 1D patterns as closely as possible, but without excluding any structure motifs which are matched by the somewhat more expressive 1D patterns. Many original Lhasa rules to not provide 2D patterns. If that is the case, they must be manually added before a rule becomes fully usable.

The 2D patterns which can be parsed by the toolkit are an extension of the original Lhasa implementation. There is no requirement that the path is encoded on the reaction arrow line with the offpath components drawn above or below this line. Also, aromatic systems are automatically detected if a full ring with proper VB bond orders is drawn. Diagonal double bonds can be encoded as // or \\ character pairs where one of the characters is one position to the left or right of the normal bond continuation. The 2D patterns become subject to a reaction mapping analysis. For performance reasons, it is advisable to use tagged substituent groups like R1, R2 etc instead of anonymous carbon atoms for large patterns.

Example:

set lh [lhasa create [read_file huisgen.src]]
set lh [lhasa create -fromfile huisgen.src]

lhasa dataset

lhasa dataset lhandle ?filterlist?
l.dataset(?filters=?)

Return the dataset handle or reference of the dataset the Lhasa object is a member of. It the object is not member of a dataset, or does not pass all of the optional filters, an empty string or None for Python is returned.

Putting Lhasa objects into datasets is primarily intended for use with the multi-threading dataset threadexec command.

Example:

lhasa dataset $lhandle

lhasa defined

lhasa defined lhandle property
l.defined(property)

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

lhasa delete

lhasa delete ?lhandle?...
lhasa delete all
l.delete()
Lhasa.Delete(?lhandle/lref?,...)
Lhasa.Delete(“all”)

Delete specific or all Lhasa objects from the toolkit instance. The return value is the number of deleted Lhasa objects.

lhasa dget

lhasa dget lhandle propertylist ?filterset? ?parameterdict?
l.dget(property=,?filters=?,?parameters=?)

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

lhasa exists

lhasa exists lhandle ?filterlist?
l.exists(?filters=?)
Lhasa.Exists(lref=,?filters=?)

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

lhasa filter

lhasa filter lhandle filterlist
l.filter(filters)

Check whether the Lhasa object passes a filter list. The return value is 1 for success and 0 for failure.

lhasa get

lhasa get lhandle propertylist ?filterset? ?parameterdict?
lhasa get lhandle attribute
l.get(property=,?filters=?,?parameters=?)
l.get(attribute)
l.property/attribute
l[property/attribute]

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

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

In addition to retrieving property data, this command is also used to retrieve a large set of attribute values from the Lhasa object. All attributes which can be set (see lhasa set command) can also be queried. In addition, there are a number of attributes which cannot be set by script commands but are automatically updated when a rule is compiled, or a lhasa react or lhasa score command is executed. These are:

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

lhasa getparam

lhasa getparam lhandle property ?key? ?default?
l.getparam(property=,?key=?,?default=?)

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

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

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

lhasa jget

lhasa jget lhandle propertylist ?filterset? ?parameterdict?
l.jget(property=,?filters=?,?parameters=?)

This is a variant of lhasa get which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects. The command is usable only for property data, not attribute retrieval.

lhasa jnew

lhasa jnew lhandle propertylist ?filterset? ?parameterdict?
l.jnew(property=,?filters=?,?parameters=?)

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

lhasa jshow

lhasa jshow lhandle propertylist ?filterset? ?parameterdict?
l.jshow(property=,?filters=?,?parameters=?)

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

lhasa list

lhasa list ?pattern?
Lhasa.List(?pattern=?)

Return a list of all currently existing Lhasa object handles or references. If a filter pattern is specified, only objects matching it are listed. The pattern syntax is the same as in the standard Tcl command string match .

lhasa metadata

lhasa metadata lhandle property ?field ?value??
l.metadata(property=,?field=?,?value=?)

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

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

lhasa move

lhasa move lhandle ?datasethandle? ?position?
l.move(?target=?,?position=?)

Make the Lhasa object a member of a dataset, or remove it from a dataset. If the dataset handle or reference parameter is omitted, or is an empty string, or None for Python , the object is removed from its current dataset.

If a target dataset handle or reference is specified, the object is added to the dataset, if allowed by the acceptance bits of the dataset, and removed from any dataset it was member of before the execution of the command. By default the object is added to the end of the dataset object list, but the final optional parameter allows the specification of a dataset object list index. The first position is index zero. If the parameter value end is used, or the index is bigger than the current number of dataset objects minus one, the object is appended as per the default. It is legal to use this command for moving objects within the same dataset.

Another special position value is random or rnd . This value moves to the object to a random position in the dataset.

The dataset handle cannot be a transient dataset.

The return value of the command is the dataset of the object prior to the move operation. It is either a dataset handle/reference, or an empty string ( Tcl ) or None ( Python ) if it was not member of a dataset.

lhasa mutex

lhasa mutex lhandle mode
l.mutex(mode)

Manipulate the object mutex. During the execution of a script command, the mutex of the major object(s) associated with the command are automatically locked and unlocked, so that the operation of the command is thread-safe. This applies to builds that support multi-threading, either by allowing multiple parallel script interpreters in separate threads or by supporting helper threads for the acceleration of command execution or background information processing. This command locks major objects for a period of time that exceeds a single command. A lock on the object can only be released from the same interpreter thread that set the lock. Any other threaded interpreters, or auxiliary threads, block until a mutex release command has been executed when accessing a locked command object. This command supports the following modes:

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

The command returns the current lock count.

lhasa need

lhasa need lhandle propertylist ?mode? ?parameterdict?
l.need(property=,?mode=?,?parameters=?)

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

The return value is the original table handle or reference.

lhasa new

lhasa new lhandle propertylist ?filterset? ?parameterdict?
l.new(property=,?filters=?,?parameters=?)

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

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

lhasa nget

lhasa nget lhandle propertylist ?filterset? ?parameterdict?
l.nget(property=,?filters=?,?parameters=?)

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

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

lhasa nnew

lhasa nnew lhandle propertylist ?filterset? ?parameterdict?
l.nnew(property=,?filters=?,?parameters=?)

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

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

lhasa properties

lhasa properties lhandle ?pattern? ?noempty?
l.properties(?pattern=?,?noempty=?)

Return a list of the valid properties on the Lhasa object. If desired, the property list can be filtered by the optional string match pattern. Since Lhasa objects incorporate no minor objects, only true Lhasa object properties (standard prefix L_ ) are listed.

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

The command may also be written as short form lhasa props .

lhasa purge

lhasa purge lhandle propertylist/table ?emptyonly?
l.purge(?properties=?,?emptyonly=?)

Delete property data from the Lhasa object. In contrast to performing property deletions on, for example, ensembles this operation does not branch out to properties which are stored on objects embedded in the Lhasa objects.

This command only deletes proper Lhasa object properties (usually starting with L_). If the object class name lhasa is used instead of a property name, the data of all Lhasa object properties is deleted.

The optional boolean flag emptyonly restricts the deletion to those properties where the value of a property is identical to the default.

lhasa react

lhasa react lhandle ehandle/ensspec ?ehandle/ensspec?...
l.react(ehandle/eref/espec,?ehandle/eref/espec?,...)

Generate a comprehensive set of forward reaction products of starting materials according to all matching 2D or New1D patterns from the current transform. If New1D patterns are present, only these are used for matching. The starting materials need to match the right side of the patterns, and the number of specified starting material ensembles must be the same as the number of fragments in the pattern. Every substructure pattern fragment must match on a different starting material molecule from the merged input ensemble in the default intermolecular reaction mode, or be part of the same molecule ( intramolecular mode, see forwardmode attribute of the Lhasa object). The order of the input structures vs. the left/right sequence of patterns in the transform code is arbitrary. All possible, but symmetry-filtered pattern match variants of all eligible patterns with respect to the input structure set are evaluated.

The starting material structures can either be normal persistent ensemble handles/references or a decodable structure specification (see ens create ). In the latter case, the decoded input structures are transient and are automatically deleted after the command completes.

The result is a list of all possible duplicate-filtered reaction product ensemble handles or references which could be generated by checking all applicable patterns in all possible match orientations and, upon any successful match, performing the atom and bond changes encoded in the pattern, going from the right side of the pattern to the left. Duplicate result structure filtering is performed according to the configured hash code (see hashproperty Lhasa object attribute). The reaction products reside in a dataset object embedded in the Lhasa object (see reactiondataset attribute) and may be further manipulated there, or moved out by additional script commands. The reagent structures, if they are not transient objects, are not consumed.

When this command is run, any existing product ensembles in the reaction dataset are deleted before the execution commences.

If there is no match, this is not an error. The result structure set is simply empty in that case.

The reagent structures used with this command are usually structures found by scanning a starting material catalog with automatically extracted reagent queries (see reagentquery[1234] attribute).

A successfully performed reaction does not guarantee that the reverse reaction scoring arrives at the same starting materials. There can be alternative retro-synthetic pattern matches, additional potential starting materials like Cl/Br/I alternative leaving group substitutions, starting materials with generic superatoms like „ alkyl “ instead of a specific group, markers for required functional group protection, etc. The products generated by this command are only to be used as starting points for retro-synthetic evaluation. The reagent structures returned by lhasa score need to be matched again vs. a starting material catalog (potentially after attaching protective groups where required, etc.), and the matches from that operation are the real starting materials to be stored in a Lhasa -scored synthetically accessible structure catalog, not the input structures used in this command.

lhasa read

lhasa read bytecodefilename/trafoid
Lhasa.Read(bytecodefilename/trafoid)

Create a Lhasa object by reading a compiled byte code file (see lhasa write command). The argument is either a single file name or transform ID. Any library subroutine files which are required and were specified when the transform was compiled from source (see lhasa create ) are part of the single byte code file.

It is possible to specify input pipes (with a leading vertical bar in the name) and stdin as input. If the file is not specified as full path name, and not readable in the current directory, an attempt is made to find it in the standard transform directory. If the filename is missing the standard .clb suffix, it is automatically appended. If the file name is a simple integer transform ID, a short file name is constructed from this identifier and searched. The default transform collection contains links from the transform ID short file name to the corresponding fully named transform file with the highest version number.

The return value is a new Lhasa object handle or reference.

lhasa ref

Lhasa.Ref(identifier)

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

lhasa rename

lhasa rename lhandle srcproperty dstproperty
l.rename(srcproperty=,dstproperty=)

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

lhasa reset

lhasa reset lhandle
l.reset()

Reset the Lhasa object from an empty state. All result structures and reaction currently associated with the object are deleted, and the transform definition is purged.

The command is not used in normal processing. Both lhasa react and lhasa score automatically clear their respective result sets when the command is started and can thus be invoked any number of time without resetting.

The command returns the original object handle or reference.

lhasa score

lhasa score lhandle ehandle/ensspec
l.score(ehandle/eref/ensspec)

This command performs a full retro-synthetic evaluation of a product structure according to the CHMTRN script commands encoded in the rule source.

Usually the input structure is one from the result set generated by lhasa react from potential starting materials, but this is not required. The examined structure may either be a normal persistent ensemble handle, or a decodable structure specification (see ens create ). In the latter case, the structure is decoded transiently and automatically deleted when the command finishes.

The command exclusively uses the 1D reaction path specifications encoded in the transform code. All possible, symmetry-filtered matches are found and processed. The result is a duplicate-filtered set of forward reactions, which contain newly created potential reagents and a duplicate of the target structure. Sometimes, transform rules may also encode intermediates. These also become part of the reaction with a suitable E_REACTION_ROLE property value, usually intermediate . These result reactions reside in the dataset embedded in the Lhasa object (see scoredataset attribute) and may be further processed there. Existing score result reactions associated with this Lhasa object are deleted whenever the command it run, so they have to be saved or moved out of their dataset before the command is re-used if they are still needed.

Depending on the transform rule coding, the proposed reagents may contain expandable superatoms (alkyl, halogen) and/or other markers (such as functional groups requiring protection). A second-pass match operation against a starting material catalog is required to obtain real starting materials, and there may be multiple catalog matches if the starting material structure contains variable groups, or different pre-attached protecting groups may be suitable.

A scored structure may be matched by multiple 1D patterns, and any of these may be positioned in multiple different match orientations. Furthermore, multiple reaction variants may be generated from within a transform rule (for example, by means of a BRANCH CHMTRN statement). Therefore, frequently more than a single reaction is the result of a scoring operation on a single structure. It is also possible that no result reactions are reported for a given structure/transform combination, either because no pattern matches, or all possible reaction paths were discarded by means of CHMTRN KILL statements, or unmet score thresholds. This is even possible when the tested structure was generated by a lhasa react command with the same transform - that command performs only pattern matching and atom/bond updates, not reaction knowledge evaluation.

The return value of the command is the highest score among all found retro-reaction paths for the tested product structure, or 0 if there were no result reactions. Every retro-reaction result object holds detailed transform result and logging information in property X_LHASA_SCORE , including its individual score. The result reactions additionally have atom mapping information in A_MAPPING and may contain additional information on the role of specific atoms in property A_FLAGS (especially in bits protected, interfering, participating).

lhasa set

lhasa set lhandle ?property/attribute value?...
lhasa set lhandle ?dictionary?
l.set(property/attribute,value,...)
l.set({property/attribute:value,...})
l.property/attribute = value
l[property/attribute] = value

Set one or more attributes of the Lhasa object. All attributes which can be set can also be queried via the lhasa get command. Attributes which cannot be modified are listed under lhasa get .

These are the recognized attributes:

The default execution flag value is exclusivereagentquery|countedreagentquery.

lhasa setparam

lhasa setparam lhandle property ?keyword value?...
lhasa setparam lhandle property dictionary
l.setparam(property,?key,value?...)
l.setparam(property,dict)

Set parameter values in the metadata section of existing property data attached to the Lhasa object. This command does not change the parameters for computations in the property definition (see prop setparam command for this function). It only stores its data in the parameter set which was copied into the metadata when the property was computed for the table.

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

lhasa show

lhasa show lhandle propertylist ?filterset? ?parameterdict?
l.show(property=,?filters=?,?parameters=?)

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

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

lhasa sqldget

lhasa sqldget lhandle propertylist ?filterset? ?parameterdict?
l.sqldget(property=,?filters=?,?parameters=?)

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

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

lhasa sqlget

lhasa sqlget lhandle propertylist ?filterset? ?parameterdict?
l.sqlget(property=,?filters=?,?parameters=?)

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

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

lhasa sqlnew

lhasa sqlnew lhandle propertylist ?filterset? ?parameterdict?
l.sqlnew(property=,?filters=?,?parameters=?)

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

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

lhasa sqlshow

lhasa sqlshow lhandle propertylist ?filterset? ?parameterlist?
l.sqlshow(property=,?filters=?,?parameters=?)

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

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

lhasa transfer

lhasa transfer lhandle propertylist ?targethandle? ?targetpropertylist?
l.transfer(properties=,?target=?,?targetproperties=?)

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

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

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

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

lhasa valid

lhasa valid lhandle propertylist
l.valid(property/propertysequence)

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

lhasa has is an alias to this command.

lhasa verify

lhasa verify lhandle property
l.verify(property)

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

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

lhasa write

lhasa write lhandle ?filename?
l.write(?filename=?)

Write a byte code file encapsulating the currently loaded and compiled transform or classification rule. This file can be used as input for a lhasa read command to restore the Lhasa object at a later time. Only the rule content and the object metadata is stored, not the current execution state and result data of the Lhasa object. The byte code contains the code generated from all included CHMTRN library files, not just the primary transform file, if applicable.

If no file name is specified, it is constructed from the Lhasa object name and the suffix .clb ( Cactvs Lhasa Binary) without a directory path component. It is possible to use output pipes or (on Linux/Unix) Tcl or Python file handles or references as special output file names. If an explicit empty filename is set (including None for Python ), no disk file is written. Instead, the file contents are returned as byte blob.

The primary purpose of the binary format is distribution of rule content without access to the source code. We have permission from the Lhasa rights holders to distribute binary versions of original Lhasa transforms, but not their source code. Transform source code is only available as part of the standard toolkit package for newly added transform rules not authored by Lhasa Inc. or Lhasa Ltd. Additional source may be made available for customers with an extended license or the legal successors of the members of the original industry consortium sponsoring the development of these rules. In addition, a large part of the Lhasa UK source part has been put into the public domain.

The binary format in this CHMTRN interpreter implementation is intentionally not compatible to the original Lhasa byte code, avoiding its limitations due to insufficient number of bits in the 32-bit values of the virtual processor code.

The return value of the command is the filename, which may have been auto-generated, except in case when the output is a blob.