The Concept object represents a concept identified by a ReadCode which has one or more associated Terms and is related to other Concepts through the hierarchy (Parents and Children) and through qualifier Template objects. Concept may also be associated with persistent or redundant Twin concepts which represent duplicate codes issued inadvertently to the same concept.
Concept objects can be created using the NewConcept method of the Reference object or by Concept object methods that find related Concepts.
Data Type: RCODE – Read-only
The Read Code for the Concept.
The ReadCode property is Read-only – The NewConcept method of the Reference object is used to create a Concept object for a different ReadCode.
Data Type: RSTAT – Read-only
The ConceptStatus of this concept. See data type RSTAT for details of representation.
Data type: Configuration
The object handle of a Configuration object associated with the current instance of the Concept object. The property settings of the referenced Configuration object apply to search and test methods applied to the specified Concept.
When a Concept is created it inherits a pointer to the Configuration object that applied to the object from which it was created (e.g. usually the Reference object or another Concept). Changed to the Configuration settings affect all objects that share a common Configuration object. However, in some cases a temporary change to a Concept configuration may be desirable without altering the Configuration applicable to other objects. In this case a new configuration object must be created as outlined in the following example:
Data Type: BOOLEAN – Read-only
The linguistic role of this concept:
Data Type: STRING – Read-only
The subject type Read Code(s) for this Concept. This consists of any ancestors that are flagged as representing types. Typically these are the top level concepts in the hierarchy. If several subject type codes are found, each is separated from the next by a comma.
Data type: INT32 – Read-only
A count of the total number of terms associated with this concept. If this number cannot be determined, or is only an estimate, the TermCountAccuracy property is set accordingly.
Data type: INTEGER
Data type: INT32 – Read-only
A count of the total number of parent Concepts associated with this Concept. If this number cannot be determined, or is only an estimate, the ParentCountAccuracy property is set accordingly.
Data type: INTEGER
Data type: INT32 – Read-only
A count of the total number of child Concepts associated with this Concept. If this number cannot be determined, or is only an estimate, the ChildCountAccuracy property is set accordingly.
Data type: INTEGER
Data type: INT32 – Read-only
A count of the total number of entries in an array generated by the last preceding list method (ListParents, ListChildren, ListDescendants, ListTemplates) applied to this object. If the list method is interrupted by a time-out, the list count is the total number of items at the time of the interruption (i.e. the total found so far by the initial list method and any subsequent continuations of the same list method).
Data type: Concept
The handle of the Concept object for a specified item in a list returned by the last preceding concept list method (ListParents, ListChildren, ListDescendants, ) applied to this object.
Data type: Template
The handle of the Template object for a specified item in a list returned by the last preceding concept ListTemplates method applied to this object.
Data Type: STRING
The string "Concept". The Name property has been added to all CLUE API objects to simplify debugging of client code. It can also be used to check the object type when a general object handle is used.
Data Type: INTEGER
An integer containing the error or status code generated by the last method applied to this object.
Returns an object handle to a new instance of the Term object. The properties of the object are set to those appropriate to the preferred term associated with the Concept. Other synonymous Terms associated with the same concept are returned using the NextTerm method.
FirstTerm can also be considered as a property pointing to the preferred term. It can be used to directly access a property of the preferred term. (e.g. Concept.FirstTerm.Term60 is the sixty character text of the preferred term for Concept).
Returns an object handle to a new instance of the Term object. The properties of the object are set to those appropriate to a term associated with the Concept. If the FirstTerm method has already been applied to this Concept, the term object returned by each application of this method will be a synonym.
If this method is applied to an object without applying the FirstTerm method to the same object, its effect is identical to the FirstTerm method.
If there are no more synonymous terms a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Returns an object handle to a new instance of the Concept object. The properties of the new Concept are set to those appropriate to the first hierarchical child of the Concept to which the method is applied. Subsequent children can be found using the Next Child method.
If there are no children a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Note: The ListChildren method provides a faster alternative to the FirstChild/NextChild approach when generating picking lists. It is readily accessible from Visual Basic™ 4 but support for the variant data type in other languages may not allow easy interpretation of the returned array. In this case alternative forms for the returned data may be considered in the production version of CLUE.
Returns an object handle to a new instance of the Concept object. The properties of the new Concept are set to those appropriate to the next hierarchical child of the Concept to which the method is applied.
If this method is applied to an object without applying the FirstChild method to the same object, its effect is identical to the FirstChild method.
If there are no more children a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Returns an object handle to a new instance of the Concept object. The properties of the new Concept are set to those appropriate to the first hierarchical parent of the Concept to which the method is applied. If a Concept has multiple hierarchical parents, subsequent parents can be found using the NextParent method.
If there are parents a null object handle is returned. This only applies to the root object of the hierarchy.
Note: The ListParents method provides a faster alternative to the FirstParent/NextParent approach when generating picking lists. It is readily accessible from Visual Basic™ 4 but support for the variant data type in other languages may not allow easy interpretation of the returned array. In this case alternative forms for the returned data may be considered in the production version of CLUE.
Returns an object handle to a new instance of the Concept object. The properties of the new Concept are set to those appropriate to the next hierarchical parent of the Concept to which the method is applied.
If this method is applied to an object without applying the FirstParent method to the same object, its effect is identical to the FirstParent method.
If there are no more parents a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Returns an object handle to a new instance of the Concept object. The properties of the new Concept are set to those appropriate to the first hierarchical descendant of the Concept to which the method is applied. Subsequent descendants can be found using the NextDescendant method.
Descendants include all children and children of children following the hierarchy recursively until the end of all branches.
If there are no descendants a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Note: The ListDescendants method provides a much faster alternative to the FirstDescendant/NextDescendant approach when generating picking lists. It is readily accessible from Visual Basic™ 4 but support for the variant data type in other languages may not allow easy interpretation of the returned array. In this case alternative forms for the returned data may be considered in the production version of CLUE.
Returns an object handle to a new instance of the Concept object. The properties of the new Concept are set to those appropriate to the next hierarchical descendant of the Concept to which the method is applied.
Descendants include all children and children of children following the hierarchy recursively until the end of all branches.
If this method is applied to an object without applying the FirstDescendant method to the same object, its effect is identical to the FirstDescendant method.
If there are no more descendants a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Returns an object handle to a new instance of the Concept object. The properties of the new Concept are set to those appropriate to a Concept that is mapped by the persistent-redundant table as equivalent to the Concept to which the method is applied.
Unless the current Concept is the persistent twin the concept returned by the FirstTwin method is the persistent Twin. This is true even if there are several redundant Twin Concepts. In this case, the NextTwin method returns subsequent redundant Twins.
If there are no Twins a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Returns an object handle to a new instance of the Concept object. The properties of the new Concept are set to those appropriate to the next Concept that is mapped by the persistent-redundant table as equivalent to the Concept to which the method is applied.
If this method is applied to an object without applying the FirstTwin method to the same object, its effect is identical to the FirstTwin method.
If there are no more twins a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
These methods return an object handle to a new instance of the Template object. The properties of the new Template are set to those appropriate to the first template for which Concept is the "Object Read Code".
If Attrib is specified, the Template must also contain the specified "Attribute Read Code". The method FirstTemplate requires Ancestor to be indicated by an object handle. The method FirstTemplateRC requires Ancestor to be represented by a Read Code as described for the data type RCODE.
If there are no matching Templates a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Note: The ListTemplates method provides a faster alternative to the FirstTemplate/NextTemplate approach when generating picking lists. It is readily accessible from Visual Basic™ 4 but support for the variant data type in other languages may not allow easy interpretation of the returned array. In this case alternative forms for the returned data may be considered in the production version of CLUE.
This method returns an object handle to a new instance of the Template object. The properties of the new Template are set to those appropriate to the next template for which Concept is the "Object Read Code". The criteria for selection are as specified by the previous FirstTemplate or FirstTemplateRC method.
The order in which templates are returned by this method is determined by the TemplateOrder parameter of the previous FirstTemplate or FirstTemplateRC method. The value of the Order property of the new instance of the Template object created by this method is also set in accordance with this parameter.
If this method is applied to an object without applying the FirstTemplate or FirstTemplateRC to that object a null object handle is returned and ObjErr is set to ERR_NEXT_WITHOUT_FIND.
If there are no more templates a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Returns an object handle to a new instance of the CrossMap object. The properties of the new CrossMap are set to those appropriate to those of the first Cross Mapping table entry for the Concept to which the method is applied. TargetScheme must be specified to identify the cross mapping table to be used. Alternative or additional mapping table entries are retrieved using the NextCrossMap method.
If TargetScheme is not specified, or there are no CrossMaps for the Read Code of the current Concept object, a null object handle is returned and ObjErr is set to ERR_NO_MATCH.
Returns an object handle to a new instance of the CrossMap object. The properties of the new CrossMap are set to those appropriate to those of the next Cross Mapping table entry for the Concept to which the method is applied. The TargetScheme for mapping is as specified in the previous FirstCrossMap method applied to the same object.
If this method is applied to an object without applying the FirstCrossMap method to that object, or if there are no more cross maps a null object handle is returned and ObjErr is set to ERR_NEXT_WITHOUT_FIND or ERR_NO_MATCH.
Returns a Visual Basic™ variant data type containing an array of elements in a form suitable for display in a picking list. Each element in the array represents a child of Concept. The form of each item in the array is determined by the value ListMode.
The number of children in the returned array is available as the property ListCount.
Object handles for each of the children returned are available as the property array FoundConcept.
Note: The ListChildren method provides a faster alternative to the FirstChild/NextChild approach when generating picking lists. It is readily accessible from Visual Basic™ 4 but support for the variant data type in other languages may not allow easy interpretation of the returned array. In this case alternative forms for the returned data may be considered in the production version of CLUE.
Returns a Visual Basic™ variant data type containing an array of elements in a form suitable for display in a picking list. Each element in the array represents a descendant of Concept. The form of each item in the array is determined by the value ListMode.
The number of descendants in the returned array is available as the property ListCount.
The object handle for each of the descendants is available as the property array FoundConcept.
The ListDescendants method may return an incomplete search if the search takes longer than the EventInterval property of the associated Configuration object if the internal array held by the CLUE server is full. In these cases an ERR_TIMEOUT or ERR_ARRAY_FULL error will be generated. The ListDescendants method can be called again with the same set of parameters to continue the search.
The ERR_TIMEOUT error is intended to help client applications to manage the display of a long list that may take several seconds to complete. The client can update the display intermittently after each timeout and can then continue the search.Continuation of the search after an ERR_TIMEOUT does not restart the array. The array returned by each call contains the results of the first and all subsequent calls the ListCount. The ListCount property therefore is the total number found for this search and the object handles for all the items in the list are available in the FoundConcept property array.
The ERR_ARRAY_FULL error is only returned when the array contains more than 4000 entries. This exceeds most practical uses of this method by a wide margin. After an ERR_ARRAY_FULL error the continuation restarts the array from the next matching term. Thus if a continuation call is issued by the application references to the items already listed are discarded by the server.
Note: The ListDescendants method provides a much faster alternative to the FirstDescendant/NextDescendant approach when generating picking lists. It is readily accessible from Visual Basic™ 4 but support for the variant data type in other languages may not allow easy interpretation of the returned array. In this case alternative forms for the returned data may be considered in the production version of CLUE.
Returns a String containing a comma-quote separated list of all the unique hierarchical descendants of a concept. The form of this string is suitable for direct use in an SQL expression.
"Where ReadCode In (" & Concept.UniqueDescendants & ")"
The optional MaxCount value limits the list to a specified number. This avoids the server attempting to enumerate the entire Read Thesaurus if the root code is used. Experience suggests that value of 2000 is reasonable for this purpose. The client application should report an error if the number of unique descendants reaches the specified limit.
The optional AllowRanges parameter causes a shortening of the string by combining multiple adjacent values as a range. A hyphen replaces the separating comma to indicates a range. For example, "A1231","A1232","A1233","A1234","A1237" becomes "A1231"–"A1234","A1237". This more compact form is compatible with the Health Query Language developed by the NHS MIQUEST Project.
The optional Version parameter specifies the Read Code version to be included in the descendant list. By default the Version 3 superset is includes subject to any configuration limitations. If Version is set as 0 or 4, only 4 byte codes are includes. If Version is set as 1, 2 or 5 then only 5 byte codes in versions 1 and 2 are included.
NOTE: The configuration settings may restrict this list. To ensure that all codes are included run the following lines prior to calling UniqueDescendants.
Returns a Visual Basic™ variant data type containing an array of elements in a form suitable for display in a picking list. Each element in the array represents a parent of Concept. The form of each item in the array is determined by the value ListMode.
The number of parents in the returned array is available as the property ListCount.
The object handle for each of the array elements returned is available as the property array FoundConcept.
The total number of parents of any concept is likely to be small and as a result this method never returns ERR_TIMEOUT or ERR_ARRAY_FULL.
Note: The ListParents method provides a faster alternative to the FirstParent/NextParent approach when generating picking lists. It is readily accessible from Visual Basic™ 4 but support for the variant data type in other languages may not allow easy interpretation of the returned array. In this case alternative forms for the returned data may be considered in the production version of CLUE.
Returns a Visual Basic™ variant data type containing an array of elements in a form suitable for display in a picking list. Each element in the array represents a template applicable to Concept. The form of each item in the array is determined by the value ListMode.
The optional parameters Attrib and TemplateOrder have the same role as the equivalent named parameters in the FindTemplate method.
NOTE: In all currently supported list modes attributes and values can be distinguished as the Tab character (ASCII 09) precedes the text of each value in the array -- Attributes are not indented by a prefixing Tab character.
The number of Templates in the returned array is available as the property ListCount.
The object handle for each of the Templates is available as the property array FoundConcept.
The total number of Templates for any concept is unlikely to be sufficient to justify returning the ERR_TIMEOUT or ERR_ARRAY_FULL.
Note: The ListTemplates method provides a faster alternative to the FirstTemplate/NextTemplate approach when generating picking lists. It is readily accessible from Visual Basic™ 4 but support for the variant data type in other languages may not allow easy interpretation of the returned array. In this case alternative forms for the returned data may be considered in the production version of CLUE.
These methods return a Boolean value indicating whether or not Concept is hierarchically descended from Ancestor.
This test ignores configuration settings with the exception of TestTwinsAsDescendants. If this property is "True" (the default), persistent/redundant Twins of a concept or its descendants are considered as descendants in their own right. However, TestTwinsAsDescendants can be set to false if persistent/redundant Twins of the concet are to be ignored.
The method IsDescendant requires Ancestor to be indicated by an object handle. The method IsDescendantRC requires Ancestor to be represented by a Read Code as described for the data type RCODE.
NOTE: To test hundred number of ReadCodes against a single putative ancestor use IsAncestorRC rather than IsDescendant. This is optimised to avoid creating and destroying objects for code tested.
These methods return a Boolean value indicating whether or not Concept is a hierarchical ancestor of Descendant.
This test ignores configuration settings with the exception of TestTwinsAsDescendants. If this property is "True" (the default), persistent/redundant Twins of a concept or its descendants are considered as descendants in their own right. However, TestTwinsAsDescendants can be set to false if persistent/redundant Twins of the concet are to be ignored.
The method IsAncestor requires Descendant to be indicated by a Concept object handle. The method IsAncestorRC requires Descendant to be represented by a Read Code as described for the data type RCODE.
NOTE: IsAncestorRC is the fastest way to test a large number of ReadCodes against a single putative ancestor is to use.
Example:
E.g. Does this patient have any respiratory diseases -- descendant of of "H...."
An alternative when conducting searches for a narrow slice of the hierarchy is to use the UniqueDescendants method to generate an SQL or HQL query expression that includes all the descendants of a specified ancestor.
These methods return a Boolean value indicating whether or not Concept is related to Twin by an entry in the persistent-redundant table. This test ignores all configuration settings.
The method IsTwin requires Twin to be indicated by a Concept object handle. The method IsTwinRC requires Twin to be represented by a Read Code as described for the data type RCODE.