Query

Modules
	PFF
	Query Errors
	Report Writer
	Server Side Reports

Data Structures
struct	QRY_user_query_row_s

Macros
#define	QRY_puid   (POM_MAX_type_token + 3)

Typedefs
typedef enum QRY_append_wildcard_pref_e	QRY_append_wildcard_pref_t
typedef enum QRY_attribute_type_e	QRY_attribute_type_t
typedef enum QRY_domain_e	QRY_domain_t
typedef struct QRY_user_query_row_s	QRY_user_query_row_t
typedef enum QRY_where_run_e	QRY_where_run_t

Enumerations
enum	QRY_append_wildcard_pref_e { QRY_no_automatic_wildcards, QRY_suffix_wild_card, QRY_prefix_wild_card, QRY_prefix_and_suffix_wild_cards }
enum	QRY_attribute_type_e {   QRY_attribute_char = POM_char, QRY_attribute_date = POM_date, QRY_attribute_double = POM_double, QRY_attribute_float = POM_float,   QRY_attribute_int = POM_int, QRY_attribute_logical = POM_logical, QRY_attribute_short = POM_short, QRY_attribute_string = POM_string,   QRY_attribute_typed_reference = POM_typed_reference, QRY_attribute_untyped_reference = POM_untyped_reference, QRY_attribute_external_reference = POM_external_reference, QRY_attribute_note = POM_note,   QRY_attribute_relationship = PROP_typed_relation, QRY_attribute_puid = QRY_puid }
enum	QRY_domain_e { QRY_DOMAIN_LOCAL, QRY_DOMAIN_REMOTE }
enum	QRY_where_run_e {   QRY_RUN_BY_TC, QRY_RUN_BY_USER_EXIT, QRY_RUN_BY_USER_QUERY, QRY_RUN_BY_KEYWORD_SEARCH,   QRY_RUN_BY_EINT_EXIT, QRY_RUN_BY_BOM_REP, QRY_RUN_BY_USAGEWC, QRY_RUN_BY_TC_PLUS_PROCESS,   QRY_RUN_BY_USER_EXIT_BO }

Functions
QRY_API int	QRY_ask_class (tag_t query_tag, char qclass[QRY_class_size_c+1])
QRY_API int	QRY_ask_class2 (tag_t query_tag, char **qclass)
QRY_API int	QRY_ask_clauses (tag_t query_tag, char **qclauses)
QRY_API int	QRY_ask_description (tag_t query_tag, char qdesc[QRY_desc_size_c+1])
QRY_API int	QRY_ask_description2 (tag_t query_tag, char **qdesc)
QRY_API int	QRY_ask_name (tag_t query_tag, char qname[QRY_name_size_c+1])
QRY_API int	QRY_ask_name2 (tag_t query_tag, char **qname)
QRY_API int	QRY_ask_search_domain (tag_t query_tag, QRY_domain_t *search_domain)
QRY_API int	QRY_ask_where_run (tag_t query_tag, QRY_where_run_t *where_run)
QRY_API int	QRY_compute_sort_preference_names (tag_t query_tag, char **keyname, char **ordername, char **pkeyname, char **pordername)
QRY_API int	QRY_describe_query (tag_t query_tag, int *num_clauses, char ***attr_names, char ***entry_names, char ***logical_ops, char ***math_ops, char ***values, tag_t **lov_tags, int **attr_types)
QRY_API int	QRY_details (tag_t query_tag, logical substitute_keyword, int *num_clauses, char ***attribute_names, char ***entry_names, char ***entry_names_display, char ***logical_operators, char ***math_operators, char ***values, tag_t **lov_tags, int **attached_specifiers, int ***dependent_indexes, int **key_lov_ids, int **attribute_types)
QRY_API int	QRY_execute (tag_t query_tag, int entry_count, char **entries, char **values, int *num_found, tag_t **results)
QRY_API int	QRY_execute_at_site (int site_id, tag_t query_tag, int entry_count, char **entries, char **values, int *num_found, tag_t **results)
QRY_API int	QRY_execute_at_site_with_sort (int site_id, tag_t query_tag, int entry_count, char **entries, char **values, int num_to_sort, char **keys, int *orders, int *num_found, tag_t **results)
QRY_API int	QRY_execute_bus_obj_query (char *requestId, tag_t typeTag, int entryCount, char **entryNames, char **entryValues, char **entryMathOp, char **entryLogicOp, int *componentCount, tag_t **componentTags)
QRY_API int	QRY_execute_on_list (tag_t query_tag, int entry_count, char **entries, char **values, int limit_list_count, tag_t *limit_list, int *num_found, tag_t **results)
QRY_API int	QRY_execute_on_list_with_sort (tag_t query_tag, int entry_count, char **entries, char **values, int limit_list_count, tag_t *limit_list, int num_to_sort, char **keys, int *orders, int *num_found, tag_t **results)
QRY_API int	QRY_execute_query (tag_t queryTag, int entryCount, char **entryNames, char **entryValues, int limitCount, tag_t *limitList, int resultsType, int *componentCount, int **hierarchicalMap, tag_t **componentTags)
QRY_API int	QRY_execute_query_with_cancel_option (char *queryrequestId, tag_t queryTag, int entryCount, char **entryNames, char **entryValues, int limitCount, tag_t *limitList, int resultsType, int *componentCount, int **hierarchicalMap, tag_t **componentTags)
QRY_API int	QRY_execute_tuples (tag_t query_tag, int entry_count, char **entries, char **values, int limit_list_count, tag_t *limit_list, int *num_rows, int *num_cols, tag_t **results)
QRY_API int	QRY_execute_user_exit_query (tag_t query_tag, int entry_count, char **entries, char **values, int *num_columns, char ***results, QRY_user_query_row_t **rows)
QRY_API int	QRY_execute_with_sort (tag_t query_tag, int entry_count, char **entries, char **values, int num_to_sort, char **keys, int *orders, int *num_found, tag_t **results)
QRY_API int	QRY_extent (int *query_count, tag_t **query_tags)
QRY_API int	QRY_find (const char name[QRY_name_size_c+1], tag_t *query_tag)
QRY_API int	QRY_find2 (const char *name, tag_t *query_tag)
QRY_API int	QRY_find_objects_based_on_attributes_and_values (char *class_name, int attribute_count, char **names, char **operations, char **values, char **clauses_rules, int *num_rows, tag_t **results)
QRY_API int	QRY_find_user_entries (tag_t query_tag, int *entry_count, char ***entries, char ***values)
QRY_API int	QRY_ignore_case_on_search (logical ignore_case)
QRY_API int	QRY_readFromFile (char *fileName, char **queryName)
QRY_API int	QRY_set_class (tag_t query_tag, const char qclass[QRY_class_size_c+1])
QRY_API int	QRY_set_class2 (tag_t query_tag, const char *qclass)
QRY_API int	QRY_set_clauses (tag_t query_tag, const char *qclauses)
QRY_API int	QRY_set_description (tag_t query_tag, const char qdesc[QRY_desc_size_c+1])
QRY_API int	QRY_set_description2 (tag_t query_tag, const char *qdesc)
QRY_API int	QRY_set_name (tag_t query_tag, const char qname[QRY_name_size_c+1])
QRY_API int	QRY_set_name2 (tag_t query_tag, const char *qname)
QRY_API int	QRY_set_name_mode (tag_t query_tag, logical name_mode)
QRY_API int	QRY_set_search_domain (tag_t query_tag, QRY_domain_t search_domain)
QRY_API int	QRY_set_where_run (tag_t query_tag, QRY_where_run_t where_run)
QRY_API int	QRY_update_fts_index (tag_t object_tag, logical delete_index)
QRY_API int	QRY_writeToFile (tag_t query_tag, char *fileName)

Define attribute size
#define	QRY_name_size_c   128
#define	QRY_desc_size_c   512
#define	QRY_class_size_c   32
#define	QRY_clause_size_c   240
#define	QRY_uid_name_size_c   32

Sort Order
#define	OrderAscending   1
#define	OrderDescending   2

Detailed Description

The query ITK module provides user methods to ask and set query attributes, find a specific query with a specified name, find all queries in the database, ask for a list of user entries of a query, execute a query, set query search mode, and set query's display name mode.

Warning

The constants defined below specify the size of variables. Do not write more than this number of bytes into the buffers.

Common Return Values

QRY_invalid_query - Specified tag is not that of a saved query object.
QRY_invalid_search_domain - Specified search domain is not valid.

Macro Definition Documentation

#define OrderAscending   1

Definition at line 122 of file qry.h.

#define OrderDescending   2

Definition at line 123 of file qry.h.

#define QRY_class_size_c   32

Definition at line 113 of file qry.h.

#define QRY_clause_size_c   240

Definition at line 114 of file qry.h.

#define QRY_desc_size_c   512

Definition at line 112 of file qry.h.

#define QRY_name_size_c   128

Definition at line 111 of file qry.h.

#define QRY_puid   (POM_MAX_type_token + 3)

Define the symbol QRY_puid which is an attribute type supported in saved query clauses.

Definition at line 44 of file qry.h.

#define QRY_uid_name_size_c   32

Definition at line 115 of file qry.h.

Typedef Documentation

typedef enum QRY_append_wildcard_pref_e QRY_append_wildcard_pref_t

Defines the supported values for the "search_automatic_wildcard" preference

typedef enum QRY_attribute_type_e QRY_attribute_type_t

Defines the supported attribute types for Saved Query clauses

typedef enum QRY_domain_e QRY_domain_t

typedef struct QRY_user_query_row_s QRY_user_query_row_t

See user_query.c for the user-exit functions that use this structure

typedef enum QRY_where_run_e QRY_where_run_t

Enumeration Type Documentation

enum QRY_append_wildcard_pref_e

Defines the supported values for the "search_automatic_wildcard" preference

Enumerator
QRY_no_automatic_wildcards	Do not append wildcards
QRY_suffix_wild_card	Append suffix wildcard
QRY_prefix_wild_card	Append prefix wildcard
QRY_prefix_and_suffix_wild_cards	Append prefix and suffix wildcards

Definition at line 69 of file qry.h.

enum QRY_attribute_type_e

Defines the supported attribute types for Saved Query clauses

Enumerator
QRY_attribute_char	Value is a single character
QRY_attribute_date	Value is a date
QRY_attribute_double	Value is a double
QRY_attribute_float	Value is a float
QRY_attribute_int	Value is an integer
QRY_attribute_logical	Value is a logical
QRY_attribute_short	Value is a short
QRY_attribute_string	Value is a character string
QRY_attribute_typed_reference	Value is a typed reference
QRY_attribute_untyped_reference	Value is an untyped reference
QRY_attribute_external_reference	Value is an external reference
QRY_attribute_note	Value is a note
QRY_attribute_relationship	Value is a typed relation
QRY_attribute_puid	Value is a puid

Definition at line 79 of file qry.h.

enum QRY_domain_e

Enumerator
QRY_DOMAIN_LOCAL
QRY_DOMAIN_REMOTE

Definition at line 46 of file qry.h.

enum QRY_where_run_e

Enumerator
QRY_RUN_BY_TC	A standard query
QRY_RUN_BY_USER_EXIT	Calls USER_query_execute and displays text results
QRY_RUN_BY_USER_QUERY	Calls USER_execute_saved_query and displays returned objects
QRY_RUN_BY_KEYWORD_SEARCH	Calls user exit code that configures and uses search engine
QRY_RUN_BY_EINT_EXIT	Exit similar to user exit which belongs to eIntegrator
QRY_RUN_BY_BOM_REP	Calls internal ITKs to generate BOM report
QRY_RUN_BY_USAGEWC	Calls USAGEWC ITKs to return proxy objects from TcBOM
QRY_RUN_BY_TC_PLUS_PROCESS	A standard query plus post process results
QRY_RUN_BY_USER_EXIT_BO	Query which returns business objects, this is user exit query but does not return runtime ( external ) objects

Definition at line 54 of file qry.h.

Function Documentation

QRY_API int QRY_ask_class	(	tag_t	query_tag,
		char	qclass[QRY_class_size_c+1]
	)

Deprecated:

This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use QRY_ask_class2

Returns the search class of the specified query.

Parameters

query_tag	(I) Tag of the saved query
qclass	(O) Search class of the saved query

QRY_API int QRY_ask_class2	(	tag_t	query_tag,
		char **	qclass
	)

Returns the search class of the specified query.

Parameters

query_tag	(I) Tag of the saved query
qclass	(OF) Search class of the saved query

QRY_API int QRY_ask_clauses	(	tag_t	query_tag,
		char **	qclauses
	)

Retrieves the query clauses of a specified query

The parameter #qclauses is a concatenated string consisting of multiple query criteria clauses defined in the Query Builder

Returns

• ITK_ok on success
• QRY_invalid_query if the query tag is invalid

Parameters

query_tag	(I) Tag of the saved query
qclauses	(OF) Search clauses of the query

QRY_API int QRY_ask_description	(	tag_t	query_tag,
		char	qdesc[QRY_desc_size_c+1]
	)

Deprecated:

This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use QRY_ask_description2

Returns the description of the specified query.

Parameters

query_tag	(I) Tag of the saved query
qdesc	(O) Description of the saved query

QRY_API int QRY_ask_description2	(	tag_t	query_tag,
		char **	qdesc
	)

Returns the description of the specified query.

Parameters

query_tag	(I) Tag of the saved query
qdesc	(OF) Description of the saved query

QRY_API int QRY_ask_name	(	tag_t	query_tag,
		char	qname[QRY_name_size_c+1]
	)

Deprecated:

This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use QRY_ask_name2

Returns the name of the specified query.

Parameters

query_tag	(I) Tag of the saved query
qname	(O) Name of the saved query

QRY_API int QRY_ask_name2	(	tag_t	query_tag,
		char **	qname
	)

Returns the name of the specified query.

Parameters

query_tag	(I) Tag of the saved query
qname	(OF) Name of the saved query

QRY_API int QRY_ask_search_domain	(	tag_t	query_tag,
		QRY_domain_t *	search_domain
	)

Returns the current search domain of the specified saved query. The returned search domain value can be one of the following:

QRY_DOMAIN_LOCAL - Query will be executed at the local site against the local database
QRY_DOMAIN_REMOTE - Query will be executed at a remote site against a remote database

Restrictions:

Remote queries can only be executed in a D-Teamcenter environment.

Parameters

query_tag	(I) Tag of the saved query
search_domain	(O) Current search domain of the specified saved query

QRY_API int QRY_ask_where_run	(	tag_t	query_tag,
		QRY_where_run_t *	where_run
	)

Parameters

query_tag	(I)
where_run	(O)

QRY_API int QRY_compute_sort_preference_names	(	tag_t	query_tag,
		char **	keyname,
		char **	ordername,
		char **	pkeyname,
		char **	pordername
	)

Parameters

query_tag	(I)
keyname	(OF)
ordername	(OF)
pkeyname	(OF)
pordername	(OF)

QRY_API int QRY_describe_query	(	tag_t	query_tag,
		int *	num_clauses,
		char ***	attr_names,
		char ***	entry_names,
		char ***	logical_ops,
		char ***	math_ops,
		char ***	values,
		tag_t **	lov_tags,
		int **	attr_types
	)

Returns full details (i.e., full details of each clause in string lists) of the specified query. This ITK is primarily used by Teamcenter-PC where the details are used to reconstruct a query form.

Parameters

query_tag	(I) Tag of the saved query
num_clauses	(O) Number of clauses in this query
attr_names	(OF) num_clauses List of attribute names. Number of list elements is the same as num_clauses.
entry_names	(OF) num_clauses List of user entry names. Number of list elements is the same as num_clauses. For fixed entry clause, that entry name element will be a NULL string.
logical_ops	(OF) num_clauses List of logical operators
math_ops	(OF) num_clauses List of math operators
values	(OF) num_clauses List of default values. Each value corresponds to each attribute. If there is no default value defined for a particular clause, that value element will be a NULL string.
lov_tags	(OF) num_clauses List of LOV tags. If there is no LOV that corresponds to the attribute, that lov_tag element will be 0.
attr_types	(OF) num_clauses List of attribute types

QRY_API int QRY_details	(	tag_t	query_tag,
		logical	substitute_keyword,
		int *	num_clauses,
		char ***	attribute_names,
		char ***	entry_names,
		char ***	entry_names_display,
		char ***	logical_operators,
		char ***	math_operators,
		char ***	values,
		tag_t **	lov_tags,
		int **	attached_specifiers,
		int ***	dependent_indexes,
		int **	key_lov_ids,
		int **	attribute_types
	)

Retrieves full details for each clause of a specified query.

Each clause is a search criteria entry defined in Query Builder in the rich client.

Returns

• ITK_ok on success
• QRY_invalid_query if the qclauses is invalid

Parameters

query_tag	(I) The query tag
substitute_keyword	(I) Flag of substituting keyword with real value
num_clauses	(O) Number of clauses
attribute_names	(OF) num_clauses Attribute names. The returned array is packed, which means that only the container needs to be deallocated using MEM_free
entry_names	(OF) num_clauses Entry L10N keys. The returned array is packed, which means that only the container needs to be deallocated using MEM_free
entry_names_display	(OF) num_clauses Entry display names. The returned array is packed, which means that only the container needs to be deallocated using MEM_free
logical_operators	(OF) num_clauses Logical operators. The returned array is packed, which means that only the container needs to be deallocated using MEM_free
math_operators	(OF) num_clauses Math operators. The returned array is packed, which means that only the container needs to be deallocated using MEM_free
values	(OF) num_clauses Display values. The returned array is packed, which means that only the container needs to be deallocated using MEM_free
lov_tags	(OF) num_clauses LOV tags
attached_specifiers	(OF) num_clauses The attached specifiers for the LOVs
dependent_indexes	(OF) num_clauses Dependent indexes. The first dimension is num_clauses clauses, the second dimension is 2 indexes of clauses each clause depends on. The returned array is not packed, which means that both the elements and the container need to be deallocated using MEM_free.
key_lov_ids	(OF) num_clauses IDs of the key LOVs
attribute_types	(OF) num_clauses Types of the attributes, possible values are defined in QRY_attribute_type_e

QRY_API int QRY_execute	(	tag_t	query_tag,
		int	entry_count,
		char **	entries,
		char **	values,
		int *	num_found,
		tag_t **	results
	)

Executes the saved query with the specified user entries and returns the number of found objects and object tags. Use the MEM_free to free the memory pointed to by results. Use QRY_find_user_entries to get a list of user entries. You do not have to have all the user entries in your entries array for execution. The entries array can be equal or less than the user entries found by QRY_find_user_entries ITK. However, the size of the values array should be the same as the entries array so that each entry is matched with a value.

Parameters

query_tag	(I) Tag of the saved query
entry_count	(I) Number of user entries in this query
entries	(I) Array of user entries
values	(I) Array of values for the user entries. Each array element, values[n], specifies the value of entries[n].
num_found	(O) Number of found objects
results	(OF) num_found List of found object tags

QRY_API int QRY_execute_at_site	(	int	site_id,
		tag_t	query_tag,
		int	entry_count,
		char **	entries,
		char **	values,
		int *	num_found,
		tag_t **	results
	)

Executes the saved query at the specified site.

Restrictions:

Valid only in a D-Teamcenter environment.

Parameters

site_id	(I) Site ID of remote site where the query will executed. If zero, the query will be executed at the default ODS site.
query_tag	(I) Tag of the saved query
entry_count	(I) Number of user entries in this query
entries	(I) Array of user entries
values	(I) Array values for the user entries. Each array element, values[n], specifies the value of entries[n].
num_found	(O) Number of objects found
results	(OF) num_found List of found object tags

QRY_API int QRY_execute_at_site_with_sort	(	int	site_id,
		tag_t	query_tag,
		int	entry_count,
		char **	entries,
		char **	values,
		int	num_to_sort,
		char **	keys,
		int *	orders,
		int *	num_found,
		tag_t **	results
	)

This API executes the query at the given site. It returns the published objects that meet the given search criteria. The order of the objects in the returned array is determined according to the given sort criteria.

Return Values:

QRY_enquiry_not_available - Invalid query
QRY_not_a_number - String xxx is found when expecting a number. Please see other query error codes.

Parameters

site_id	(I) The site id
query_tag	(I) The tag of a remote query object
entry_count	(I) The number of the user entries
entries	(I) The array of the user entry names
values	(I) The array of the values. Each user name in the "entries" array must have a corresponding value in the "values" array.
num_to_sort	(I) The number of the PublicationRecord class attributes to be sorted
keys	(I) The array of the names of the attributes that the found objects are to be sorted against. An attribute must be from the PublicationRecord class.
orders	(I) The array of the sort orders. The possible values of a sort order are: 1 (Ascending Order) 2 (Descending Order)
num_found	(O) The number of the found objects
results	(OF) num_found The tag array of the found objects

QRY_API int QRY_execute_bus_obj_query	(	char *	requestId,
		tag_t	typeTag,
		int	entryCount,
		char **	entryNames,
		char **	entryValues,
		char **	entryMathOp,
		char **	entryLogicOp,
		int *	componentCount,
		tag_t **	componentTags
	)

Parameters

requestId	(I) A string representing the execute operation request
typeTag	(I) Tag of business object type
entryCount	(I) Number of user entries in this query
entryNames	(I) Array of property names
entryValues	(I) Array of property values
entryMathOp	(I) Array of property values
entryLogicOp	(I) Array of property values
componentCount	(O) Number of objects found
componentTags	(OF) Array of tags for found objects

QRY_API int QRY_execute_on_list	(	tag_t	query_tag,
		int	entry_count,
		char **	entries,
		char **	values,
		int	limit_list_count,
		tag_t *	limit_list,
		int *	num_found,
		tag_t **	results
	)

Executes the saved query with the specified user entries and returns the number of found objects and object tags of those objects in the database that are also in the limit_list. If the limit_list is null, or the limit_list_count is 0, the objects returned are exactly the same as those returned by QRY_execute. Use MEM_free to free the memory pointed to by results. Use QRY_find_user_entries to get a list of user entries. You do not have to have all the user entries in your entries array for execution. The entries array can be equal or less than the user entries found by QRY_find_user_entries ITK. However, the size of the values array should be the same as the entries array so that each entry is matched with a value.

Restrictions:

This function does not work with user_exit_queries.

Parameters

query_tag	(I) Tag of the saved query
entry_count	(I) Number of user entries in this query
entries	(I) Array of user entries
values	(I) Array of values for the user entries. Each array element, values[n], specifies the value of entries[n].
limit_list_count	(I) The number of tags in the limit_list
limit_list	(I) The list of object tags used to limits the search
num_found	(O) The number of objects found
results	(OF) num_found The list of object tags of the objects found in the database intersected with the limit_list tags.

QRY_API int QRY_execute_on_list_with_sort	(	tag_t	query_tag,
		int	entry_count,
		char **	entries,
		char **	values,
		int	limit_list_count,
		tag_t *	limit_list,
		int	num_to_sort,
		char **	keys,
		int *	orders,
		int *	num_found,
		tag_t **	results
	)

This API returns the objects that meet the given search criteria and that are in the given limit list. The order of the objects in the returned array is determined according to the given sort criteria.

For other arguments, please see QRY_execute_with_sort

Parameters

query_tag	(I) The tag of a saved query object
entry_count	(I) The number of the user entries
entries	(I) The array of the user entry names
values	(I) The array of the values. Each user name in the "entries" array must have a corresponding value in the "values" array.
limit_list_count	(I) The length of the limit_list array
limit_list	(I) The tag array of the objects
num_to_sort	(I) The number of the class attributes to be sorted
keys	(I) The array of the names of the attributes that the found objects are to be sorted against. An attribute must be from the query target class.
orders	(I) The array of the sort orders. The possible values of a sort order are: 1 (Ascending Order) 2 (Descending Order)
num_found	(O) The number of the found objects
results	(OF) num_found The tag array of the found objects

QRY_API int QRY_execute_query	(	tag_t	queryTag,
		int	entryCount,
		char **	entryNames,
		char **	entryValues,
		int	limitCount,
		tag_t *	limitList,
		int	resultsType,
		int *	componentCount,
		int **	hierarchicalMap,
		tag_t **	componentTags
	)

This API returns the objects that meet the given search criteria and that are in the given limit list. This API also takes into account any sort preferences, where-run, and search domain, when executing the search.

Parameters

queryTag	(I) Tag of saved query to execute
entryCount	(I) Number of user entries in this query
entryNames	(I) Array of user entries
entryValues	(I) Array of values for the user entries. Each array element, value[n], specifies the value of entries[n]
limitCount	(I) Number of tags in the limit_list
limitList	(I) List of object tags used to limit the search scope
resultsType	(I) An integer specifying the results type - 0 (flat), 1 (hierarchical)
componentCount	(O) Number of objects found
hierarchicalMap	(O) If the results type is specified as "hierarchical", this integer array acts as a map for the found objects to be presented in a hierarchical fashion
componentTags	(OF) Array of tags for found objects

QRY_API int QRY_execute_query_with_cancel_option	(	char *	queryrequestId,
		tag_t	queryTag,
		int	entryCount,
		char **	entryNames,
		char **	entryValues,
		int	limitCount,
		tag_t *	limitList,
		int	resultsType,
		int *	componentCount,
		int **	hierarchicalMap,
		tag_t **	componentTags
	)

Parameters

queryrequestId	(I) A string representing the execute operation request
queryTag	(I) Tag of saved query to execute
entryCount	(I) Number of user entries in this query
entryNames	(I) Array of user entries
entryValues	(I) Array of values for the user entries. Each array element, value[n], specifies the value of entries[n]
limitCount	(I) Number of tags in the limit_list
limitList	(I) List of object tags used to limit the search scope
resultsType	(I) An integer specifying the results type - 0 (flat), 1 (hierarchical)
componentCount	(O) Number of objects found
hierarchicalMap	(O) If the results type is specified as "hierarchical", this integer array acts as a map for the found objects to be presented in a hierarchical fashion
componentTags	(OF) Array of tags for found objects

QRY_API int QRY_execute_tuples	(	tag_t	query_tag,
		int	entry_count,
		char **	entries,
		char **	values,
		int	limit_list_count,
		tag_t *	limit_list,
		int *	num_rows,
		int *	num_cols,
		tag_t **	results
	)

Executes the saved query with the specified user entries, limited by the limit_list. If the limit_list is null, or the limit_list_count is 0, the limit list is ignored and the query is run against all data in the database.

Returned is a list of object tags organized as tuples (subsets). The list is num_rows * num_cols long. Each tuple subset corresponds to one result, comprising of qualifying objects from multiple levels of the queried object hierarchy. The classes of objects that are selected to be part of the tuple subset are determined by the class names in the query criteria.

Example 1: If the query is: Find all Items where the Item Revisions have a Specification Dataset with name = "xyz1", then each tuple subset will contain: Item, qualifying Item Revision and qualifying Dataset. The num_cols return value will be 3. The result list will contain Item tag 0, Item Revision tag 0, Dataset tag 0, Item tag 1, Item Revision tag 1, Dataset tag 1 and so on... for as many entries in the database that satisfy the query.

Example 2: If the query is: Find all Item Revisions that have a Specification Dataset with name = "xyz1" AND Form of type Item Revision Master with user_data_1 = "xyz2", then each tuple subset will contain: Item Revision, qualifying Dataset, qualifying Form and qualifying Item Revision Master. The num_cols return value will be 4. The result list will contain Item Revision tag 0, Dataset tag 0, Form tag 0, Item Revision Master tag 0, Item Revision tag 1, Dataset tag 1, Form tag 1, Item Revision Master tag 1 and so on... for as many entries in the database that satisfy the query.

Use the MEM_free to free the memory pointed to by results. Use QRY_find_user_entries to get a list of user entries. You do not have to have all the user entries in your entries array for execution. The entries array can be equal or less than the user entries found by QRY_find_user_entries ITK. However, the size of the values array should be the same as the entries array so that each entry is matched with a value.

Restrictions:

This function does not work with user_exit_queries.

Parameters

query_tag	(I) Tag of the saved query
entry_count	(I) Number of user entries in this query
entries	(I) Array of user entries
values	(I) Array of values for the user entries. Each array element, values[n], specifies the value of entries[n].
limit_list_count	(I) The number of tags in the limit_list
limit_list	(I) The list of object tags used to limits the search
num_rows	(O) The number of tuples found
num_cols	(O) The number of objects in each tuple
results	(OF) num_found The list of object tags of the objects found in the database intersected with the limit_list tags. num_rows*num_cols long.

QRY_API int QRY_execute_user_exit_query	(	tag_t	query_tag,
		int	entry_count,
		char **	entries,
		char **	values,
		int *	num_columns,
		char ***	results,
		QRY_user_query_row_t **	rows
	)

Parameters

query_tag	(I)
entry_count	(I)
entries	(I)
values	(I)
num_columns	(O)
results	(OF) num_columns
rows	(OF)

QRY_API int QRY_execute_with_sort	(	tag_t	query_tag,
		int	entry_count,
		char **	entries,
		char **	values,
		int	num_to_sort,
		char **	keys,
		int *	orders,
		int *	num_found,
		tag_t **	results
	)

This API returns the objects that meet the given search criteria. The order of the objects in the returned array is determined according to the given sort criteria.

Return Values:

QRY_enquiry_not_available - invalid query
QRY_not_a_number - String xxx is found when expecting a number. Please see other query error codes.

Parameters

query_tag	(I) The tag of a saved query object
entry_count	(I) The number of the user entries
entries	(I) The array of the user entry names
values	(I) The array of the values. Each user name in the "entries" array must have a corresponding value in the "values" array.
num_to_sort	(I) The number of the class attributes to be sorted
keys	(I) The array of the names of the attributes that the found objects are to be sorted against. An attribute must be from the query target class.
orders	(I) The array of the sort orders. The possible values of a sort order are: 1 (Ascending Order) 2 (Descending Order)
num_found	(O) The number of the found objects
results	(OF) num_found The tag array of the found objects

QRY_API int QRY_extent	(	int *	query_count,
		tag_t **	query_tags
	)

Returns the number of saved queries and a list of saved query tags. Use MEM_free to free the memory pointed to by query_tags.

Parameters

query_count	(O) Number of the saved queries or the size of the array
query_tags	(OF) query_count List of saved query tags

QRY_API int QRY_find	(	const char	name[QRY_name_size_c+1],
		tag_t *	query_tag
	)

Deprecated:

This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use QRY_find2 Performs a case sensitive search for the specified query name and returns its tag.

Parameters

name	(I) Name of the query
query_tag	(O) Tag of the saved query

QRY_API int QRY_find2	(	const char *	name,
		tag_t *	query_tag
	)

Performs a case sensitive search for the specified query name and returns its tag.

Parameters

name	(I) Name of the query
query_tag	(O) Tag of the saved query

QRY_API int QRY_find_objects_based_on_attributes_and_values	(	char *	class_name,
		int	attribute_count,
		char **	names,
		char **	operations,
		char **	values,
		char **	clauses_rules,
		int *	num_rows,
		tag_t **	results
	)

Finds the objects of the input class with the specified attributes & values.

Example 1:

If the query is: Find all Items where object_name = "x*z1;x*z2" AND object_type="Document",

Use the MEM_free to free the memory pointed to by results.

Restrictions: At present operations supports = operation. In future this will be extened for other operations too This function designed to work for local queries only.

Parameters

class_name	(I) primiary class to find the objects
attribute_count	(I) Number of user entries in this query
names	(I) Array of attribute names
operations	(I) Array of operations
values	(I) Array of values for attribute names and operations Each array element, values[n], specifies the value of entries[n].
num_rows	*<(I) Array of values to club different clauses. For example AND,OR etc. At present AND is assumed. For future use only. Right now pass NULL (O) The number of objects found
results	(OF)num_found The list of object tags of the objects found in the database.

QRY_API int QRY_find_user_entries	(	tag_t	query_tag,
		int *	entry_count,
		char ***	entries,
		char ***	values
	)

Finds all user entries of the specified query. Use MEM_free to free the memory pointed to by entries and values.

Parameters

query_tag	(I) Tag of the saved query
entry_count	(O) Number of user entries in this query
entries	(OF) entry_count Array of user entries
values	(OF) entry_count Array of default values for the user entries. Each array element, values[n], specifies the default value of entries[n]. A values[n] can be an empty string if there is no default value defined.

QRY_API int QRY_ignore_case_on_search

(

logical

ignore_case

)

Sets the TC_ignore_case_on_search preference for the current ITK session. This ITK does not set the value in the preference file.

If ignore_case is TRUE, searching will be case insensitive.
If ignore_case is FALSE, searching will be case sensitive.

Parameters

ignore_case

(I) Flag for case insensitive or sensitive search

QRY_API int QRY_readFromFile	(	char *	fileName,
		char **	queryName
	)

Parameters

fileName	(I)
queryName	(OF)

QRY_API int QRY_set_class	(	tag_t	query_tag,
		const char	qclass[QRY_class_size_c+1]
	)

Deprecated:

This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use QRY_set_class2

Sets the search class of the specified query. It is not saved to the database until an explicit call to AOM_save occurs.

Note

Maximum length is 32 characters. Ensure that query clauses or the attribute-value pairs of the query are still valid for the new search class. Otherwise, this query can be invalidated.

Parameters

query_tag	(I) Tag of the saved query
qclass	(I) Search class of the query to be saved

QRY_API int QRY_set_class2	(	tag_t	query_tag,
		const char *	qclass
	)

Sets the search class of the specified query. It is not saved to the database until an explicit call to AOM_save occurs.

Note

Maximum length is 32 characters. Ensure that query clauses or the attribute-value pairs of the query are still valid for the new search class. Otherwise, this query can be invalidated.

Parameters

query_tag	(I) Tag of the saved query
qclass	(I) Search class of the query to be saved

QRY_API int QRY_set_clauses	(	tag_t	query_tag,
		const char *	qclauses
	)

Sets the clauses of the specified query
The change is not saved to the database until an explicit call to AOM_save occurs

The parameter #qclauses is a concatenated string consisting of multiple query criteria clauses. To obtain a sample valid string, export the saved query through the Query Builder in the rich client or use QRY_ask_clauses.

Note

qclauses will be verified to make sure it's valid clauses

Returns

• ITK_ok on success
• QRY_invalid_query if the qclauses is invalid

Parameters

query_tag	(I) Tag of the saved query.
qclauses	(I) Search clauses of the query to be saved.

QRY_API int QRY_set_description	(	tag_t	query_tag,
		const char	qdesc[QRY_desc_size_c+1]
	)

Deprecated:

This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use QRY_set_description2

Sets the description of the specified query. It is not saved to the database until an explicit call to AOM_save occurs.

Note

Maximum length is 512 characters.

Parameters

query_tag	(I) Tag of the saved query
qdesc	(I) Description of the query to be saved

QRY_API int QRY_set_description2	(	tag_t	query_tag,
		const char *	qdesc
	)

Sets the description of the specified query. It is not saved to the database until an explicit call to AOM_save occurs.

Note

Maximum length is 512 characters.

Parameters

query_tag	(I) Tag of the saved query
qdesc	(I) Description of the query to be saved

QRY_API int QRY_set_name	(	tag_t	query_tag,
		const char	qname[QRY_name_size_c+1]
	)

Deprecated:

This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use QRY_set_name2

Sets the name of the specified query. It is not saved to the database until an explicit call to AOM_save occurs.

Note

The query name must be unique and the maximum length is 128 characters.

Parameters

query_tag	(I) Tag of the saved query
qname	(I) Name of the query to be saved

QRY_API int QRY_set_name2	(	tag_t	query_tag,
		const char *	qname
	)

Sets the name of the specified query. It is not saved to the database until an explicit call to AOM_save occurs.

Note

The query name must be unique and the maximum length is 128 characters.

Parameters

query_tag	(I) Tag of the saved query
qname	(I) Name of the query to be saved

QRY_API int QRY_set_name_mode	(	tag_t	query_tag,
		logical	name_mode
	)

Sets the name mode of the specified query to display real property names or to display presentation names. Default name mode is presentation mode. Set name_mode to TRUE for real property name, and set name_mode to FALSE for presentation name.

Parameters

query_tag	(I) Tag of the saved query
name_mode	(I) TRUE for real property name and FALSE for presentation name

QRY_API int QRY_set_search_domain	(	tag_t	query_tag,
		QRY_domain_t	search_domain
	)

Sets the domain of a saved query to specified search domain. The search domain value can be one of the following:

QRY_DOMAIN_LOCAL - Query will be executed at the local site against the local database
QRY_DOMAIN_REMOTE - Query will be executed at a remote site against a remote database

Restrictions:

Remote queries can be executed only in a D-Teamcenter environment.

Parameters

query_tag	(I) Tag of the saved query
search_domain	(I) Search domain to set for the specified query

QRY_API int QRY_set_where_run	(	tag_t	query_tag,
		QRY_where_run_t	where_run
	)

Parameters

query_tag	(I)
where_run	(I)

QRY_API int QRY_update_fts_index	(	tag_t	object_tag,
		logical	delete_index
	)

Update / delete the FTS index of the given object. It will index the object only if it is mentioned as a Type under the preference �TC_fts_indexed_types�.

Parameters

object_tag	(I) The tag of the object whose FTS index you want to update.
delete_index	(I) Whether to delete the FTS index of the given object.

QRY_API int QRY_writeToFile	(	tag_t	query_tag,
		char *	fileName
	)

Parameters

query_tag	(I)
fileName	(I)