Main Page | Modules | Files | Functions | Code Elements | Data Structures | Deprecated

POM Enquiry

Detailed Description

Supported Operators

POM_enquiry_equal POM_enquiry_not_equal
POM_enquiry_greater_than POM_enquiry_greater_than_or_eq
POM_enquiry_less_than POM_enquiry_less_than_or_eq
POM_enquiry_between POM_enquiry_not_between
POM_enquiry_like POM_enquiry_not_like
POM_enquiry_in POM_enquiry_not_in
POM_enquiry_exists POM_enquiry_not_exists
POM_enquiry_is_null POM_enquiry_is_not_null
POM_enquiry_union POM_enquiry_unionall
POM_enquiry_intersection POM_enquiry_difference
POM_enquiry_substr POM_enquiry_upper
POM_enquiry_lower POM_enquiry_rtrim
POM_enquiry_ltrim POM_enquiry_length
POM_enquiry_concat POM_enquiry_max
POM_enquiry_min POM_enquiry_avg
POM_enquiry_sum POM_enquiry_countall
POM_enquiry_countdist POM_enquiry_and
POM_enquiry_or POM_enquiry_plus
POM_enquiry_minus POM_enquiry_divide
POM_enquiry_multiply POM_array_length_equals
POM_array_length_not_equalsPOM_enquiry_tonumber
POM_enquiry_uid_of POM_enquiry_cpid_of
POM_enquiry_nvl

Tokens

POM_enquiry_asc_order
POM_enquiry_desc_order
POM_enquiry_bind_value
POM_enquiry_const_value

Common Return Values

ENQ_invalid_attribute One of the following:
String class is not a valid POM_class name
String class is not a valid class alias
String class is not a valid pseudo class
String attribute is not a valid attribute of the class
ENQ_invalid_class The class string is not a valid POM_class.
ENQ_invalid_expressionEither the class is not a valid class name or the attribute-expression is not a valid expression.
ENQ_invalid_value No value exists with this identifier ID.
POM_op_not_supported The operator is not supported.
POM_wrong_attr_type Attribute type is one of the following:
POM_untyped_reference
POM_typed_reference
POM_external_reference
and operator is one of the following:
POM_enquiry_greater_than
POM_enquiry_greater_than_or_eq
POM_enquiry_less_than
POM_enquiry_less_than_or_eq
POM_enquiry_like
POM_enquiry_not_like
POM_enquiry_between
POM_enquiry_not_between

Modules

Defines

Functions

Define Documentation

#define POM_enquiry_ask_colum_size   POM_enquiry_ask_column_size

Definition at line 966 of file enq.h.

Function Documentation

POMAPI int POM_combine_enquiries ( tag_t  enq1,
int  op,
tag_t  enq2,
tag_t *  new_enq 
)

Combines two enquiries to create a new one.

If enq1 and enq2 correspond to:

SELECT internal_uid FROM (<class> WHERE <attribute1> <operator1> <value1>);

SELECT internal_uid FROM (<class> WHERE <attribute2> <operator2> <value2>);

then the combination corresponds to:

SELECT internal_uid FROM (<class> WHERE (<attribute1> <operator1> <value1>) <conjunction> (<attribute2> <operator2> <value2>));

For example:

SELECT internal_uid FROM employee WHERE (salary > 5000) AND (title <> "Manager");

This does not delete the original enquiries, so for instance they can be recombined with a different conjunction.

There are two basic combination tokens that can be used to combine two enquiries. There is also a modifier token that can be used in combination with these basic tokens to generate two further combination tokens:

Simple TokensComposite TokensModifier Tokens
POM_and POM_nand POM_not
POM_or POM_nor

Parameters:
enq1  (I) ID of first enquiry
op  (I) Token for combination of enquiries - "and", "or", etc.
enq2  (I) ID of second enquiry
new_enq  (O) ID of combined enquiry

POMAPI int POM_create_enquiry_on_char ( tag_t  classid,
tag_t  attrid,
int  op,
const char *  val,
tag_t *  enqid 
)

Creates an enquiry. This corresponds to the SQL:

SELECT internal_uid FROM (<class> WHERE <attribute> <operator> <value>);

Where <class>, <attribute>, <operator>, and <value> correspond to the values handed to the POM function, and the internal_uid is purely internal to POM (it never appears through the POM interface). The value is passed in as a pointer so that the enquiry can be reused later with a different set of values.

This function does not execute the enquiry.

For string-value attributes, value can contain valid SQL wildcards.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
val  (I) 1
enqid  (O)

POMAPI int POM_create_enquiry_on_chars ( tag_t  classid,
tag_t  attrid,
int  op,
int  start,
int  n_values,
const char *  val,
tag_t *  enqid 
)

Creates an enquiry. This is similar to POM_create_enquiry_on_char but applies to array-valued attributes. The enquiry can still be reused later with a different set of values.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
start  (I)
n_values  (I)
val  (I) n_values
enqid  (O)

POMAPI int POM_create_enquiry_on_date ( tag_t  classid,
tag_t  attrid,
int  op,
const date_t *  val,
tag_t *  enqid 
)

Creates an enquiry. This corresponds to the SQL:

SELECT internal_uid FROM (<class> WHERE <attribute> <operator> <value>);

Where <class>, <attribute>, <operator>, and <value> correspond to the values handed to the POM function, and the internal_uid is purely internal to POM (it never appears through the POM interface). The value is passed in as a pointer so that the enquiry can be reused later with a different set of values.

This function does not execute the enquiry.

For string-value attributes, value can contain valid SQL wildcards.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
val  (I) 1
enqid  (O)

POMAPI int POM_create_enquiry_on_dates ( tag_t  classid,
tag_t  attrid,
int  op,
int  start,
int  n_values,
const date_t *  val,
tag_t *  enqid 
)

Creates an enquiry. This is similar to POM_create_enquiry_on_date but applies to array-valued attributes. The enquiry can still be reused later with a different set of values.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
start  (I)
n_values  (I)
val  (I) n_values
enqid  (O)

POMAPI int POM_create_enquiry_on_double ( tag_t  classid,
tag_t  attrid,
int  op,
const double *  val,
tag_t *  enqid 
)

Creates an enquiry. This corresponds to the SQL:

SELECT internal_uid FROM (<class> WHERE <attribute> <operator> <value>);

Where <class>, <attribute>, <operator>, and <value> correspond to the values handed to the POM function, and the internal_uid is purely internal to POM (it never appears through the POM interface). The value is passed in as a pointer so that the enquiry can be reused later with a different set of values.

This function does not execute the enquiry.

For string-value attributes, value can contain valid SQL wildcards.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
val  (I) 1
enqid  (O)

POMAPI int POM_create_enquiry_on_doubles ( tag_t  classid,
tag_t  attrid,
int  op,
int  start,
int  n_values,
const double *  val,
tag_t *  enqid 
)

Creates an enquiry. This is similar to POM_create_enquiry_on_double but applies to array-valued attributes. The enquiry can still be reused later with a different set of values.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
start  (I)
n_values  (I)
val  (I) n_values
enqid  (O)

POMAPI int POM_create_enquiry_on_ids ( int  n_ids,
const tag_t *  ids,
tag_t *  new_enq 
)

This is used to build a query where the tag of some set of instances is already known. This is distinct from creating an enquiry on tag attributes, since the objects own identity is not accessed as a regular attribute. A trivial example of the use of this function would be to take a list of instance and filter this by some set of attributes to get a shorter list of instances qualifying before loading same.

Example

A more realistic example might be to find which revisions of an item contain a reference to a "production" release status. In this example the tags used are:

rs_c ReleaseStatus class tag.
name_aname attribute tag in releasestatus class.
wso_c WorkSpaceObject class tag.
rsl_a release_status_list attr tag in workspaceobject class.
strptrPointer to a buffer containing the text "production."
insts Input list of item revisions. found is the subset of that list that have a release status of "production." 

        ifail = POM_create_enquiry_on_string (rs_c, name_a, POM_is_equal_to, &strptr, &enq1);
        check_fail(ifail);
        
        ifail = POM_create_enquiry_on_ref (wso_c, rsl_a, POM_has_reference_to, &enq1, &enq2);
        check_fail(ifail);
        
        ifail = POM_create_enquiry_on_ids (no_insts, insts, &enq3);
        check_fail(ifail);
        
        ifail = POM_combine_enquiries (enq2, POM_and, enq3, &enq4);
        check_fail(ifail);
        
        ifail = POM_execute_enquiry(enq4, &nofound, &found);
        check_fail(ifail);
Parameters:
n_ids  (I) Number of instance tags to be supplied
ids  (I) n_ids Tags of instance
new_enq  (O) ID for enquiry

POMAPI int POM_create_enquiry_on_int ( tag_t  classid,
tag_t  attrid,
int  op,
const int *  val,
tag_t *  enqid 
)

Creates an enquiry. This corresponds to the SQL:

SELECT internal_uid FROM (<class> WHERE <attribute> <operator> <value>);

Where <class>, <attribute>, <operator>, and <value> correspond to the values handed to the POM function, and the internal_uid is purely internal to POM (it never appears through the POM interface). The value is passed in as a pointer so that the enquiry can be reused later with a different set of values.

This function does not execute the enquiry.

For string-value attributes, value can contain valid SQL wildcards.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
val  (I) 1
enqid  (O)

POMAPI int POM_create_enquiry_on_ints ( tag_t  classid,
tag_t  attrid,
int  op,
int  start,
int  n_values,
const int *  val,
tag_t *  enqid 
)

Creates an enquiry. This is similar to POM_create_enquiry_on_int but applies to array-valued attributes. The enquiry can still be reused later with a different set of values.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
start  (I)
n_values  (I)
val  (I) n_values
enqid  (O)

POMAPI int POM_create_enquiry_on_logical ( tag_t  classid,
tag_t  attrid,
int  op,
const logical *  val,
tag_t *  enqid 
)

Creates an enquiry. This corresponds to the SQL:

SELECT internal_uid FROM (<class> WHERE <attribute> <operator> <value>);

Where <class>, <attribute>, <operator>, and <value> correspond to the values handed to the POM function, and the internal_uid is purely internal to POM (it never appears through the POM interface). The value is passed in as a pointer so that the enquiry can be reused later with a different set of values.

This function does not execute the enquiry.

For string-value attributes, value can contain valid SQL wildcards.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
val  (I) 1
enqid  (O)

POMAPI int POM_create_enquiry_on_logicals ( tag_t  classid,
tag_t  attrid,
int  op,
int  start,
int  n_values,
const logical *  val,
tag_t *  enqid 
)

Creates an enquiry. This is similar to POM_create_enquiry_on_logical but applies to array-valued attributes. The enquiry can still be reused later with a different set of values.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
start  (I)
n_values  (I)
val  (I) n_values
enqid  (O)

POMAPI int POM_create_enquiry_on_ref ( tag_t  classid,
tag_t  attrid,
int  op,
const tag_t *  subenquiry,
tag_t *  enqid 
)

Creates an enquiry based on a reference attribute (type POM_typed_reference or POM_untyped_reference) and an existing enquiry (subenquiry).

The enquiry produced can act in one of two ways, controlled by the operator token:

  • POM_has_reference_to In this mode, it selects instances of the class_id which have references (via attr_id) to instances which satisfy the enquiry.
  • POM_is_referenced_by In this mode, it selects whatever is referenced by the reference attribute attr_id by the instances of class_id that satisfy the enquiry.
This function does not execute the enquiry.

The subenquiry is passed in as a reference to an enquiry ID so that the enquiry created with this function can be executed several times with different sub enquiries.

If the attribute specified by attr_id is an array type attribute (fixed or variable length) then the functionality of the operation is as follows:

  • POM_has_reference_to - Returns all instances that have one or more references in the array attribute to the instances satisfying the subenquiry.
  • POM_is_referenced_by - Returns all the values in the array attribute for all instances that are selected by the sub-enquiry.
Example

Select all users that are linked to the group "DBA" via one (or more) GroupMember objects, then:

  • Create an enquiry selecting all Groups that have the name "DBA" - call this enquiry ENQ1;
  • Using POM_create_enquiry_on_ref, create an enquiry over the class "GroupMember" (attribute "group") that has-reference-to the instances returned by the enquiry ENQ1. This enquiry, ENQ2, returns all the GroupMember objects that reference the Group "DBA."
  • Create a third enquiry ENQ3, again over the class "GroupMember" but this time using the attribute "user", which returns any object which is-referenced-by the GroupMember objects selected by ENQ2.
  • The result of ENQ3 is the list of Users that are members of the "DBA" Group.

There are seven basic tokens that describe the type of enquiry comparison that can be used, and two "modifier" tokens that can be added to the basic tokens to form composite tokens (five of which are supplied for compatibility with earlier releases).

Simple Tokens Composite Tokens Modifier Tokens
POM_is_equal_to POM_is_not_equal_to POM_not
POM_is_greater_than POM_is_not_greater_thanPOM_case_insensitive
POM_is_less_than POM_is_not_less_than
POM_is_null POM_is_not_null
POM_is_like POM_is_not_like
POM_has_reference_to
POM_is_referenced_by

Parameters:
classid  (I) ID of class from which to select instances
attrid  (I) ID of attribute to use for selection
op  (I) Token for operator - "equal to", "greater than", etc.
subenquiry  (I) 1 Value to compare with value of attribute
enqid  (O)

POMAPI int POM_create_enquiry_on_string ( tag_t  classid,
tag_t  attrid,
int  op,
char **  val,
tag_t *  enqid 
)

Creates an enquiry. This corresponds to the SQL:

SELECT internal_uid FROM (<class> WHERE <attribute> <operator> <value>);

Where <class>, <attribute>, <operator>, and <value> correspond to the values handed to the POM function, and the internal_uid is purely internal to POM (it never appears through the POM interface). The value is passed in as a pointer so that the enquiry can be reused later with a different set of values.

This function does not execute the enquiry.

For string-value attributes, value can contain valid SQL wildcards.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
val  (I) 1
enqid  (O)

POMAPI int POM_create_enquiry_on_strings ( tag_t  classid,
tag_t  attrid,
int  op,
int  start,
int  n_values,
char **  val,
tag_t *  enqid 
)

Creates an enquiry. This is similar to POM_create_enquiry_on_string but applies to array-valued attributes. The enquiry can still be reused later with a different set of values.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
start  (I)
n_values  (I)
val  (I) n_values
enqid  (O)

POMAPI int POM_create_enquiry_on_tag ( tag_t  classid,
tag_t  attrid,
int  op,
const tag_t *  val,
tag_t *  enqid 
)

Creates an enquiry. This corresponds to the SQL:

SELECT internal_uid FROM (<class> WHERE <attribute> <operator> <value>);

Where <class>, <attribute>, <operator>, and <value> correspond to the values handed to the POM function, and the internal_uid is purely internal to POM (it never appears through the POM interface). The value is passed in as a pointer so that the enquiry can be reused later with a different set of values.

This function does not execute the enquiry.

For string-value attributes, value can contain valid SQL wildcards.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
val  (I) 1
enqid  (O)

POMAPI int POM_create_enquiry_on_tags ( tag_t  classid,
tag_t  attrid,
int  op,
int  start,
int  n_values,
const tag_t *  val,
tag_t *  enqid 
)

Creates an enquiry. This is similar to POM_create_enquiry_on_tag but applies to array-valued attributes. The enquiry can still be reused later with a different set of values.

Note:
This function accepts the date in local time.
Parameters:
classid  (I)
attrid  (I)
op  (I)
start  (I)
n_values  (I)
val  (I) n_values
enqid  (O)

POMAPI int POM_delete_enquiries ( int  n_enquiry,
const tag_t *  enqid 
)

Deletes the specified enquiries.

Parameters:
n_enquiry  (I) Number of enquiries to delete
enqid  (I) n_enquiry ID of enquiries to delete

POMAPI int POM_enquiry_add_group_attr ( const char *  enq_id,
const char *  aclass,
const char *  attr 
)

Adds an attribute to the group-by clause of the query.

This method allows the caller to specify a grouping based on an attribute value.

Restrictions:

  1. enq_id must identify an existing query
  2. aclass - as POM_enquiry_set_attr_expr
  3. attr - as POM_enquiry_set_attr_expr
Parameters:
enq_id  (I) The query whose group-by clause is to be modified
aclass  (I) The name of the class, alias or type that owns the attribute
attr  (I) The name of the attribute or property to be added to the group-by clause

POMAPI int POM_enquiry_add_group_expr ( const char *  enq_id,
const char *  expr_id 
)

Adds an attribute-expression to the group-by clause of the query.

This method allows the caller to specify a grouping based on the value of an arbitrary attribute-expression.

Restrictions:

  1. enq_id must identify an existing query
  2. expr_id must identify an existing expression on the query
Parameters:
enq_id  (I) The query whose group-by clause is to be modified
expr_id  (I) The id of an existing expression on the query

POMAPI int POM_enquiry_add_order_attr ( const char *  enq_id,
const char *  aclass,
const char *  attr,
int  sort_order 
)

Adds an attribute to the order-by clause of the query.

This method allows the caller to specify a ordering based on an attribute value.

Restrictions:

  1. enq_id must identify an existing query
  2. aclass - as POM_enquiry_set_attr_expr
  3. attr - as POM_enquiry_set_attr_expr
  4. sort_order must be one of
Parameters:
enq_id  (I) The query whose order-by clause is to be modified
aclass  (I) The name of the class, alias or type that owns the attribute
attr  (I) The name of the attribute or property to be added to the order-by clause
sort_order  (I) Whether the results are to be sorted in ascending or descending order

POMAPI int POM_enquiry_add_order_expr ( const char *  enq_id,
const char *  expr_id,
int  sort_order 
)

Adds an attribute-expression to the order-by clause of the query.

This method allows the caller to specify an ordering based on the value of an arbitrary attribute-expression.

Restrictions:

  1. enq_id must identify an existing query
  2. expr_id must identify an existing expression on the query
  3. sort_order must be one of
    • POM_enquiry_asc_order
    • POM_enquiry_desc_order
Parameters:
enq_id  (I) The query whose order-by clause is to be modified
expr_id  (I) The id of an existing expression on the query
sort_order  (I) Whether the results are to be sorted in ascending or descending order

POMAPI int POM_enquiry_add_select_attrs ( const char *  enq_id,
const char *  aclass,
int  n_attrs,
const char **  attrs 
)

Adds a list of attributes to the select clause of the query.

This method allows the caller to specify one or more simple attributes whose values a query is to return.

Adding an attribute that has already been added to the select clause may or may not add it again.

Restrictions:

  1. enq_id must identify an existing query within the user's current session.
  2. aclass must be one of the following:
    • A valid POM_class name
    • A valid class alias defined in the query
    • A valid pseudo class defined in the query
    • A valid Tc type
  3. n must be a positive integer
  4. attrs must be a valid array of n_attrs C strings, where each string is one of
    • A valid POM attribute defined on aclass
    • A supported Tc compound property defined on aclass
Parameters:
enq_id  (I) The query whose selected clause is to be modified
aclass  (I) The POM class, class or pseudo-class alias or Tc type that the user wants to query
n_attrs  (I) The Number of attributes to be added to query's select clause
attrs  (I) The List of attributes to be added

POMAPI int POM_enquiry_add_select_exprs ( const char *  enq_id,
int  n_expr_ids,
const char **  expr_ids 
)

Adds a list of attribute-expressions to the select clause of the query.

This method allows the caller to specify one or more evaluated expressions whose values a query is to return.

Restrictions:

  1. enq_id must identify an existing query
  2. n_expr_ids must be a positive integer
  3. expr_ids must be a valid array of n_expr_ids C strings, where each string identifies an existing expression in the query. Note that expressions added to select clause cannot have bind variables. Use constant values instead.
Parameters:
enq_id  (I) The query whose select clause is to be modified
n_expr_ids  (I) The number of attribute-expressions to be added to the query's select clause
expr_ids  (I) The list of attribute-expressions identifiers

POMAPI int POM_enquiry_ask_attr_of_alias ( const char *  enq_id,
const char *  alias,
char **  aclass,
char **  attr 
)

This function exposes internal information about the POM class and attribute that was associated with an attribute alias.

Restrictions:

  1. enq_id must identify an existing query.
Parameters:
enq_id  (I) The query being investigated
alias  (I)
aclass  (OF)
attr  (OF)

POMAPI int POM_enquiry_ask_char_value ( const char *  enq_id,
const char *  val_id,
int *  n_vals,
char **  vals 
)

This function returns information about the char value identified by val_id.

Restrictions:

  1. enq_id must identify an existing query.
  2. val_id must identify one of the query's existing char values.
Parameters:
enq_id  (I) The query that owns the value
val_id  (I) The value's id
n_vals  (O) The number of values the value contains
vals  (OF) The list of n_vals values

POMAPI int POM_enquiry_ask_class_of_alias ( const char *  enq_id,
const char *  alias,
char **  aclass,
logical *  is_pom_class 
)

This function exposes internal information about the POM class that was associated with a caller-defined class alias. If the caller had defined the alias the refer to a Tc type, this function returns the name of the underlying POM class.

Restrictions:

  1. enq_id must identify an existing query.
  2. alias must identify one of the query's existing class aliases.
Parameters:
enq_id  (I) The query being investigated
alias  (I) A class alias defined on the query
aclass  (OF) The name of the actual POM class or registered associated with the alias
is_pom_class  (O) true => aclass is the name of a POM class; false => it is the name of a registered table

POMAPI int POM_enquiry_ask_column_count ( const char *  enqid,
int *  count 
)

Get the number of columns selected by the query.

Parameters:
enqid  (I) Enquiry identifier
count  (O) Number of columns

POMAPI int POM_enquiry_ask_column_name ( const char *  enq_id,
int  index,
char **  name 
)

This function exposes internal information about the name assigned to the column returned by a query.

Restrictions:

  1. enq_id must identify an existing query that has been executed.
  2. index must be greater than or equal to 0 and less than the number of attributes and expressions that were added to the query's select clause.
Parameters:
enq_id  (I) The query being investigated
index  (I) The index of the query's selected column
name  (OF) The name assigned internally to the column

POMAPI int POM_enquiry_ask_column_size ( const char *  enq_id,
int  index,
int *  size 
)

This function exposes internal information about the size of the in the specified columns returned by a query.

Restrictions:

  1. enq_id must identify an existing query that has been executed.
  2. index must be greater than or equal to 0 and less than the number of attributes and expressions that were added to the query's select clause.
Parameters:
enq_id  (I) The query being investigated
index  (I) The index of the query's selected column
size  (O) The size of the column's data

POMAPI int POM_enquiry_ask_column_type ( const char *  enq_id,
int  index,
int *  type 
)

This function exposes internal information about the POM types of the specified columns returned by a query. For more information on types, see POM Tokens.

Restrictions:

  1. enq_id must identify an existing query that has been executed.
  2. index must be greater than or equal to 0 and less than the number of attributes and expressions that were added to the query's select clause.
Parameters:
enq_id  (I) The query being investigated
index  (I) The index of the query's selected column
type  (O) POM_TOKEN describing the column's POM type

POMAPI int POM_enquiry_ask_date_value ( const char *  enq_id,
const char *  val_id,
int *  n,
date_t **  vals 
)

This function returns information about the date value identified by val_id.

Restrictions:

  1. enq_id must identify an existing query.
  2. val_id must identify one of the query's existing date values.
Parameters:
enq_id  (I) The query that owns the value
val_id  (I) The value's id
n  (O) The number of values the value contains
vals  (OF) The list of n_vals values

POMAPI int POM_enquiry_ask_distinct ( const char *  enq_id,
const char *  expr_id,
logical *  distinct 
)

This function can be used to determine whether a query may return duplicate rows or not.

Restrictions:

  1. enq_id must identify an existing query.
Parameters:
enq_id  (I) The query being investigated
expr_id  (I) Ignored
distinct  (O) true => the query is set to suppress duplicate rows from the results

POMAPI int POM_enquiry_ask_double_value ( const char *  enq_id,
const char *  val_id,
int *  n,
double **  vals 
)

This function returns information about the double value identified by val_id.

Restrictions:

  1. enq_id must identify an existing query.
  2. val_id must identify one of the query's existing double values.
Parameters:
enq_id  (I) The query that owns the value
val_id  (I) The value's id
n  (O) The number of values the value contains
vals  (OF) The list of n_vals values

POMAPI int POM_enquiry_ask_int_value ( const char *  enq_id,
const char *  val_id,
int *  n_vals,
int **  vals 
)

This function returns information about the integer value identified by val_id.

Restrictions:

  1. enq_id must identify an existing query.
  2. val_id must identify one of the query's existing integer values.
Parameters:
enq_id  (I) The query that owns the value
val_id  (I) The value's id
n_vals  (O) The number of values the value contains
vals  (OF) The list of n_vals values

POMAPI int POM_enquiry_ask_logical_value ( const char *  enq_id,
const char *  val_id,
int *  n,
logical **  vals 
)

This function returns information about the logical value identified by val_id.

Restrictions:

  1. enq_id must identify an existing query.
  2. val_id must identify one of the query's existing logical values.
Parameters:
enq_id  (I) The query that owns the value
val_id  (I) The value's id
n  (O) The number of values the value contains
vals  (OF) The list of n_vals values

POMAPI int POM_enquiry_ask_query_id ( tag_t  enq_tag,
char **  enq_id 
)

Previous query ITK used tags for the query ID, but the new ITK uses string for query ID.

This function will convert the tag of an old POM query into a valid new POM query string so that it can be used in POM_enquiry_copy_query.

Parameters:
enq_tag  (I) A valid POM enquiry tag
enq_id  (OF) The string that maps to the enquiry tag

POMAPI int POM_enquiry_ask_select_attr ( const char *  enq_id,
char **  attr_name 
)

This function is only here to support the re-write of old query system on top of the new POM_enquiry API. This will return the name of the attribute selected by the enqid query. Please note that this assumes that we have only one attr selected because old query system only returns a tag value. so it can either be a PUID or a reference attribute's name. This is not the case for POM_enquiry system where we support multiple selected attributes from diff classes. so please do not use this function with POM_enquiry API.

Parameters:
enq_id  (I)
attr_name  (OF)

POMAPI int POM_enquiry_ask_select_class ( const char *  enq_id,
char **  class_name 
)

Parameters:
enq_id  (I) The query being investigated
class_name  (OF) The name of the POM class associated with the data the query returns

POMAPI int POM_enquiry_ask_string_value ( const char *  enq_id,
const char *  val_id,
int *  n,
char ***  vals 
)

This function returns information about the string value identified by val_id.

Restrictions:

  1. enq_id must identify an existing query.
  2. val_id must identify one of the query's existing string values.
Parameters:
enq_id  (I) The query that owns the value
val_id  (I) The value's id
n  (O) The number of values the value contains
vals  (OF) The list of n_vals values

POMAPI int POM_enquiry_ask_tag_value ( const char *  enq_id,
const char *  val_id,
int *  n,
tag_t **  vals 
)

This function returns information about the tag value identified by val_id.

Restrictions:

  1. enq_id must identify an existing query.
  2. val_id must identify one of the query's existing tag values.
Parameters:
enq_id  (I) The query that owns the value
val_id  (I) The value's id
n  (O) The number of values the value contains
vals  (OF) The list of n_vals values

POMAPI int POM_enquiry_ask_where_exprid ( const char *  enq_id,
char **  where_expr_id 
)

This function returns the id of the expression that has been set of on the query's where clause.

The aim of the function is allow a query's where clause to be set by one software and subsequently altered by another. For example, the module wishing to modify the where clause could replace the where expression with another that has been creating by ANDing the previous where expression with some other condition.

Restrictions:

  1. enq_id must identify an existing query
Parameters:
enq_id  (I) The query being investigated
where_expr_id  (OF) The id of the query's where expression

POMAPI int POM_enquiry_combine_enquiry ( const char *  enq_id,
const char *  set_expr_id,
const char *  lhs_id,
int  set_operator,
const char *  rhs_id 
)

Combines two sub-enquiries into one. The two sub-enquiries must be defined within the scope of the outer enquiry. This is useful if you have a query that looks like the following:

QUERY-1 UNION QUERY-2 UNION QUERY-3

In this case: define QUERY-2 and QUERY-3 as sub-enquiries of QUERY-1,
then use POM_enquiry_combine_enquiry to create a set-expression using QUERY-2 and QUERY-3.
Finally, use POM_enquiry_set_setexpr to set the set-expression of the outer query QUERY-1.

Restrictions:

  1. The enq_id must have already been defined
  2. The set_expr_id must be a unique identifier within the query
  3. The lhs_id must be a sub-enquiry or a set-expression.
  4. The rhs_id must be either a sub-enquiry or a set-expression but never NULL.
  5. The set_operator must be one of the following tokens:
  6. Neither rhs_id nor lvalue can be enq_id.
  7. The two enquiries defined by the lvalue and rhs_id identifiers must be union-compatible. This means that the two enquiries must have the same number of attributes selected, and the attributes must respectively be of the same domain.
Parameters:
enq_id  (I) The query that is to be modified
set_expr_id  (I) The id to be given to the new expression
lhs_id  (I) Either a sub-enquiry or a set-expression
set_operator  (I) Set-expression operator
rhs_id  (I) Either be a sub-enquiry or a set-expression

POMAPI int POM_enquiry_copy_query ( const char *  enq_from,
const char *  enq_to 
)

Copies the contents of one query into a sub-query of another.

The aim of this function is to allow a query that has been created by one software module to be reused as a subquery by another.

If enq_to is a newly created query (one which has been created, but on which no other POM enquiry calls have been made) then, at the end of the call, enq_to is a direct copy of enq_from. If, though, enq_to already contains its own definition, partial or complete, then, at the end of call, enq_to contains the result of merging enq_from into the existing definition.

Restrictions:

  1. enq_from must identify an existing query
  2. enq_to must identify an existing sub-query of another query
Parameters:
enq_from  (I) The query to copy from
enq_to  (I) The query to copy into

POMAPI int POM_enquiry_create ( const char *  enq_id  ) 

Creates a new enquiry.

Restrictions:

  1. enq_id must not be the name of an query that already exists within the user's current session.
Parameters:
enq_id  (I) The id to be given to the new query

POMAPI int POM_enquiry_create_class_alias ( const char *  enq_id,
const char *  aclass,
logical  is_pom_class,
const char *  alias 
)

Creates a class alias for a POM_class, a Tc type or an external table in the database. Once created, the class alias can be used in place of the name of the class, type or table. The most of common use for class aliases to construct queries that have a self-join, such as in the classic example of finding those employees whose manager is X.

Restrictions:

  1. enq_id must identify an existing query.
  2. If pom_class is true, then aclass must be one of the following:
    • A valid POM_class name
    • A valid Tc type
    Otherwise, if pom_class is false, aclass must the name of table that has been previously registered through a call to POM_enquiry_register_table.
  3. alias must not be a POM_class, neither can be the name of one of the query's existing aliases.

Note that, although it is not recommended, aliases may be given the same names as existing Tc types. In queries where this occurs, POM enquiry will always take the name to refer to the alias, and not the type.

Parameters:
enq_id  (I) The query that is to own the new class alias
aclass  (I) The name of the POM class, Tc type or registered table to which the alias is to refer
is_pom_class  (I) true if aclass is a class or type; false if it is a registered table
alias  (I) The name of the class alias that is to be created

POMAPI int POM_enquiry_delete ( const char *  enq_id  ) 

Deletes the query and its sub-queries.

Restrictions:

  1. enq_id must identify an existing query.

The enq_id must have already been defined.

Parameters:
enq_id  (I) The query to be deleted

POMAPI int POM_enquiry_does_class_alias_exists ( const char *  enq_id,
const char *  alias,
logical *  verdict 
)

This function determines whether a specified class alias has already been created on a query.

Restrictions:

  1. enq_id must identify an existing query that has been executed.
Parameters:
enq_id  (I) The query being investigated
alias  (I) The name of a class alias that may have been created on the query
verdict  (O) true => the alias already exists

POMAPI int POM_enquiry_does_query_exists ( const char *  enq_id,
logical *  verdict 
)

This function determines whether a specified query name has already been created in the user's current session.

Restrictions: None

Parameters:
enq_id  (I) The id of a query that may have been created
verdict  (O) true => the query has been created

POMAPI int POM_enquiry_execute ( const char *  enq_id,
int *  rows,
int *  cols,
void ****  report 
)

Executes the query and fetches the data.

Restrictions:

  1. enq_id must identify an existing query, and the query's definition must be valid and complete.
Parameters:
enq_id  (I) The query that is to be executed
rows  (O) Number of rows returned by the query
cols  (O) Number of columns returned by the query
report  (OF) Result of the query

POMAPI int POM_enquiry_is_table_registered ( const char *  table_name,
logical *  is_registered 
)

This function determines whether a specified table is already registered with POM enquiry or not.

Restrictions: None

Parameters:
table_name  (I) The name of a database table that may have been registered with POM enquiry
is_registered  (O) true => the table has been registered

POMAPI int POM_enquiry_register_table ( const char *  table_name,
int  n_columns,
const char **  column_names,
const int *  column_types,
const int *  column_sizes 
)

This function allows the caller to register any arbitrary table in the database. Through this function, the caller specifies which of the table's columns are to be registered, and, for each column, it tells POM the POM type that describes the column's contents and the size of the data each column contains.

Once registered, a table can be included in a query by establishing a class alias for it (see POM_enquiry_create_class_alias). The registered columns can be accessed as the class alias' attributes (the name of the attribute is the column's name); each attribute acts as if it has the POM type that was assigned to it during registration.

Restrictions:

  1. table_name must be the name of an existing table in the POM database.
  2. n_columns must be > 0
  3. column_names must contain n_columns C strings; each string must be a distinct name
  4. column_types must contain n_columns POM_TOKENs, each describing the POM type of the respective column
  5. column_sizes must containt n_columns integers > 0, each describing the size of data in the respective column
Parameters:
table_name  (I) The name of the table the caller wishes to include in a POM query
n_columns  (I) The number of the table's columns that are to be registered with POM
column_names  (I) The list of the columns to be registered
column_types  (I) The corresponding list of the columns' types
column_sizes  (I) The corresponding list of the data sizes for each column

POMAPI int POM_enquiry_set_attr_expr ( const char *  enq_id,
const char *  expr_id,
const char *  aclass,
const char *  attr,
int  op,
const char *  rhs_id 
)

Creates an attribute-expression from

  1. an attribute (the left hand operand)
  2. an operator
  3. an optional right hand operand

This method allows the caller to create a new expression from an attribute, an operator, and an optional expression, value or query.

Restrictions:

  1. enq_id must identify an existing query
  2. expr_id must not be the name of an existing expression on the query
  3. aclass - as POM_enquiry_add_select_attrs
  4. attr must be one of
    • A valid POM attribute defined on aclass, or
    • A supported Tc compound property defined on aclass
  5. op must be a valid POM enquiry operator whose operation must be suitable for the inputs, attr and rhs_id
  6. rhs_id must be one of the following
    • The identifier of an expression that has been defined previously on the query
    • The identifier of a value that has been defined previously on the query
    • The identifier of an existing query
    • The empty string, "" (which is specified if and only if op is a unary operator)
Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The id to be given to the new expression
aclass  (I) The class, alias or type that owns attr
attr  (I) The attribute or supported compound property that is to form the left hand operand
op  (I) The attribute-expression operator
rhs_id  (I) The identifier of the right hand operand

POMAPI int POM_enquiry_set_char_expr ( const char *  enq_id,
const char *  expr_id,
const char *  aclass,
const char *  attr,
int  op,
char  rhs_val 
)

Creates an attribute-expression on a query from

  1. an attribute (the left hand operand)
  2. an operator
  3. a char value

This method is provided as a convenient way of making an expression using a char value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The id to be given to the new expression
aclass  (I) The POM class, alias or Tc type that owns the attribute
attr  (I) The attribute or supported compound property of aclass that acts as the left hand operand
op  (I) The attribute-expression operator
rhs_val  (I) A char constant that acts as the right hand operand

POMAPI int POM_enquiry_set_char_value ( const char *  enq_id,
const char *  val_id,
int  n_vals,
const char *  vals,
int  propriety 
)

Creates a char value on a query.

For details, see POM_enquiry_set_int_value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new value
val_id  (I) The id to be given to the new value
n_vals  (I) The number of values in the list (use 1 for a single scalar value)
vals  (I) The list of n_vals values
propriety  (I) Specifies whether the value is a constant or a bind value

POMAPI int POM_enquiry_set_date_expr ( const char *  enq_id,
const char *  expr_id,
const char *  aclass,
const char *  attr,
int  op,
date_t  rhs_val 
)

Creates an attribute-expression on a query from

  1. an attribute (the left hand operand)
  2. an operator
  3. a date value

This method is provided as a convenient way of making an expression using a date value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The id to be given to the new expression
aclass  (I) The POM class, alias or Tc type that owns the attribute
attr  (I) The attribute or supported compound property of aclass that acts as the left hand operand
op  (I) The attribute-expression operator
rhs_val  (I) A date_t constant that acts as the right hand operand

POMAPI int POM_enquiry_set_date_value ( const char *  enq_id,
const char *  val_id,
int  n_vals,
const date_t *  vals,
int  propriety 
)

Creates a date value on a query.

For details, see POM_enquiry_set_int_value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new value
val_id  (I) The id to be given to the new value
n_vals  (I) The number of values in the list (use 1 for a single scalar value)
vals  (I) The list of n_vals values
propriety  (I) Specifies whether the value is a constant or a bind value

POMAPI int POM_enquiry_set_distinct ( const char *  enq_id,
logical  on 
)

Allows the caller to specify whether the query results should contain duplicate rows or not.

Restrictions:

  1. enq_id must identify an existing query.
Parameters:
enq_id  (I) The query that is to be modified
on  (I) true => the results will contain no duplicate rows; false => the results may contain duplicate rows

POMAPI int POM_enquiry_set_double_expr ( const char *  enq_id,
const char *  expr_id,
const char *  aclass,
const char *  attr,
int  op,
double  rhs_val 
)

Creates an attribute-expression on a query from

  1. an attribute (the left hand operand)
  2. an operator
  3. a double value

This method is provided as a convenient way of making an expression using a double value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The id to be given to the new expression
aclass  (I) The POM class, alias or Tc type that owns the attribute
attr  (I) The attribute or supported compound property of aclass that acts as the left hand operand
op  (I) The attribute-expression operator
rhs_val  (I) A double constant that acts as the right hand operand

POMAPI int POM_enquiry_set_double_value ( const char *  enq_id,
const char *  val_id,
int  n_vals,
const double *  vals,
int  propriety 
)

Creates a double value on a query.

For details, see POM_enquiry_set_int_value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new value
val_id  (I) The id to be given to the new value
n_vals  (I) The number of values in the list (use 1 for a single scalar value)
vals  (I) The list of n_vals values
propriety  (I) Specified whether the value is a constant or a bind value

POMAPI int POM_enquiry_set_expr ( const char *  enq_id,
const char *  expr_id,
const char *  lhs_id,
int  op,
const char *  rhs_id 
)

Creates an attribute-expression that can be used in any of the query clauses.

This method allows the caller to create a new expression from other expressions, values and / or queries. Once created, such an expression can be used in other expressions, or in the query's various clauses. Not all expressions can be used in all places, though; the normal restrictions of SQL apply. To give an obvious example, only expressions that evaluate to true or false can be used in the query's where clause.

Restrictions:

  1. enq_id must identify an existing query
  2. expr_id must not be the name of an existing expression in the query
  3. lhs_id must be one of
    • the identifier of an existing expression in the query
    • the identifier of an existing value in the query
    • the identifier of an existing query
    • the empty string, ""
  4. op must be a valid POM enquiry operator whose operation must be suitable for the inputs, lhs_id and rhs_id
  5. rhs id - as lhs_id
Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The id to be given to the new expression
lhs_id  (I) The id of the left hand operand
op  (I) The expression operator
rhs_id  (I) The id of the right hand operand

POMAPI int POM_enquiry_set_expr_proprety ( const char *  enq_id,
const char *  expr,
int  prop 
)

This ITK function is only used to support the rewrite of the old query system on top of the new POM_enquiry API. The prop argument supports either POM_case_insensitive or POM_tonumber token. Do not use this with the POM_enquiry APIs, but use instead POM_enquiry_upper and POM_enquiry_tonumber/POM_enquiry_tc_to_number.

Parameters:
enq_id  (I)
expr  (I)
prop  (I)

POMAPI int POM_enquiry_set_having_expr ( const char *  enq_id,
const char *  expr_id 
)

Sets the having clause of the query to the specified expression.

Calling this function replaces the query's existing having clause, if it has been set.

Restrictions:

  1. enq_id must identify an existing query
  2. expr_id must identify an existing expression on the query
Parameters:
enq_id  (I) The query whose having clause is to set
expr_id  (I) The id of an existing expression defined on the query

POMAPI int POM_enquiry_set_id ( const char *  enq_id,
char **  id 
)

Parameters:
enq_id  (I)
id  (OF)

POMAPI int POM_enquiry_set_int_expr ( const char *  enq_id,
const char *  expr_id,
const char *  aclass,
const char *  attr,
int  op,
int  rhs_val 
)

Creates an attribute-expression on a query from

  1. an attribute (the left hand operand)
  2. an operator
  3. an integer value

This method is provided as a convenient way of making an expression using an integer value.

Restrictions:

  1. enq_id must identify an existing query
  2. expr_id must not be the name of an existing expression on the query
  3. aclass - as POM_enquiry_set_attr_expr
  4. attr - as POM_enquiry_set_attr_expr
  5. op must be a valid POM enquiry operator whose operation must be suitable for the inputs, attr and rhs_val
Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The id to be given to the new expression
aclass  (I) The POM class, alias or Tc type that owns the attribute
attr  (I) The attribute or supported compound property of aclass that acts as the left hand operand
op  (I) The attribute-expression operator
rhs_val  (I) An integer constant that acts as the right hand operand

POMAPI int POM_enquiry_set_int_value ( const char *  enq_id,
const char *  val_id,
int  n_vals,
const int *  vals,
int  propriety 
)

Creates an integer value on a query.

The value can be a constant or a bind value. Constant values remain the same each time the query is executed. Bind values can have different values from one execution to another; their values must be set prior to each execution.

The value can be a single scalar value or a list of values.

The value can be used in any of the query's expression definitions.

Restrictions:

  1. enq_id must identify an existing query
  2. val_id must not be the name of any of the query's existing values
  3. n_vals must be a positive integer
  4. vals must be a C array of n_vals values
  5. propriety must be either POM_enquiry_bind_value or POM_enquiry_const_value
Parameters:
enq_id  (I) The query that is to own the new value
val_id  (I) The id to be given to the new value
n_vals  (I) The number of values in the list (use 1 for a single scalar value)
vals  (I) The list of n_vals values
propriety  (I) Specifies whether the value is a constant or a bind value

POMAPI int POM_enquiry_set_join_expr ( const char *  enq_id,
const char *  expr_id,
const char *  aclass1,
const char *  attr1,
int  op,
const char *  aclass2,
const char *  attr2 
)

Creates an expression that adds a theta-join from one class to another. The join is based on comparing values of an attribute on one class with the values of an attribute on the other. The comparison can be =, <, or <= (except for external references where only = is allowed).

The caller must ensure that the expression created is ANDed into the query's where expression.

Restrictions:

  1. enq_id must identify an existing query
  2. expr_id must not be the id of any of the query's existing expressions
  3. aclass1 - as POM_enquiry_set_attr_expr
  4. attr1 - as POM_enquiry_set_attr_expr
  5. op must be one of
  6. aclass2 - as POM_enquiry_set_attr_expr
  7. attr2 - as POM_enquiry_set_attr_expr
Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The identifier to be given to the new expression
aclass1  (I) The name of the class, alias or type on the left of the join
attr1  (I) The attribute used to join the left hand class
op  (I) The operator used to create the join
aclass2  (I) The name of the class, alias or type on the right of the join
attr2  (I) The attribute used to join the left hand class

POMAPI int POM_enquiry_set_logical_expr ( const char *  enq_id,
const char *  expr_id,
const char *  aclass,
const char *  attr,
int  op,
logical  rhs_val 
)

Creates an attribute-expression on a query from

  1. an attribute (the left hand operand)
  2. an operator
  3. a logical value

This method is provided as a convenient way of making an expression using a logical value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The id to be given to the new expression
aclass  (I) The POM class, alias or Tc type that owns the attribute
attr  (I) The attribute or supported compound property of aclass that acts as the left hand operand
op  (I) The attribute-expression operator
rhs_val  (I) A constant logical value that acts as the right hand operand

POMAPI int POM_enquiry_set_logical_value ( const char *  enq_id,
const char *  val_id,
int  n_vals,
const logical *  vals,
int  propriety 
)

Creates a logical value on a query.

For details, see POM_enquiry_set_int_value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new value
val_id  (I) The id to be given to the new value
n_vals  (I) The number of values in the list (use 1 for a single scalar value)
vals  (I) The list of n_vals values
propriety  (I) Specifies whether the value is a constant or a bind value

POMAPI int POM_enquiry_set_pseudo_attr ( const char *  enq_id,
const char *  aclass,
const char *  attr,
int  index,
const char *  palias 
)

This function allows callers to define a query that accesses a small array (SA) column, by creating a pseudo-attribute to represent the value at a specified position in the array. The pseudo-attribute can be used in the same way as any other of the class's attributes.

Restrictions:

  1. enq_id must identify an existing query
  2. aclass - see POM_enquiry_create_class_alias
  3. attr must be the name of an SA attribute on aclass
  4. index must be >= 0
  5. palias must not be the name of any of aclass's attributes, or any of its existing pseudo-attributes
Parameters:
enq_id  (I) The query that is to own the definition of the pseudo-attribute
aclass  (I) The class that owns the SA attribute
attr  (I) The name of the SA attribute
index  (I) The position of the value to be accessed
palias  (I) The name that is to be given to the new pseudo-attribute

POMAPI int POM_enquiry_set_pseudo_calias ( const char *  enq_id,
const char *  aclass,
const char *  attr,
const char *  alias 
)

This function allows callers to define a query that accesses a variable length array (VLA) or long array (LA) column by creating a new alias (called a pseudo-class alias) to represent the contents of the array . The pseudo-class alias can be used in the same way as a class alias.

The alias represents a pseudo-class that has two pseudo-attributes: PVAL (holding the value) and PSEQ (holding the index or sequence number). When a query uses a pseudo-class's PVAL or PSEQ pseudo-attributes, POM enquiry automatically adds a join to the array from the class that owns it, producing one row in the results for each member of the array. The upshot is that the results contain no rows that stem from instances of the owning class whose arrays are empty, and it contains multiple rows from instances whose arrays contain multiple values.

Restrictions:

  1. enq_id must identify an existing query
  2. aclass - see POM_enquiry_create_class_alias
  3. alias - see POM_enquiry_create_class_alias
  4. attr must be the name of a valid VLA attribute on aclass

Note that pseudo-class aliases can only be defined for VLA or LA columns, not for columns of type small array (SA). Small arrays are supported through calls to POM_enquiry_set_pseudo_attr.

Parameters:
enq_id  (I) The query that is to own the new alias
aclass  (I) The name of the class that owns the VLA or LA attribute
attr  (I) The name of the VLA or LA attribute
alias  (I) The name to be given to the new alias

POMAPI int POM_enquiry_set_query_hint ( const char *  enq_id,
const char *  hint 
)

Allows the caller to set a hint that can be used in Oracle databases to improve query performance. Setting query hints requires internal understanding of POM enquiry and advanced knowledge of Oracle.

Restrictions:

  1. enq_id must identify an existing query.
Parameters:
enq_id  (I) The query to which the hint is to be added
hint  (I) The query hint

POMAPI int POM_enquiry_set_setenquiry ( const char *  enq_id,
const char *  q1 
)

Parameters:
enq_id  (I)
q1  (I)

POMAPI int POM_enquiry_set_setexpr ( const char *  enq_id,
const char *  set_expr_id,
int  set_op,
const char *  rhs_id 
)

Sets the set-expression of the outer query.

The two enquiries defined by query and rhs_id identifiers must be union-compatible, that is, they must have the same number of attributes selected, and the attributes must respectively be of the same domain.

Restrictions:

  1. enq_id must identify an existing query.
  2. set_expr_id must be a unique identifier within the query.
  3. set_op must be one of the following
  4. rhs_id must identify either a sub-query or a set-expression on the query.
Parameters:
enq_id  (I) The query that is to be modified
set_expr_id  (I) The identifier of the left hand set operand
set_op  (I) A set-expression operator
rhs_id  (I) The sub-query or a set-expression that defines the right hand set operand

POMAPI int POM_enquiry_set_string_expr ( const char *  enq_id,
const char *  expr_id,
const char *  aclass,
const char *  attr,
int  op,
char *  rhs_val 
)

Creates an attribute-expression on a query from

  1. an attribute (the left hand operand)
  2. an operator
  3. a string value

This method is provided as a convenient way of making an expression using a string value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The id to be given to the new expression
aclass  (I) The POM class, alias or Tc type that owns the attribute
attr  (I) The attribute or supported compound property of aclass that acts as the left hand operand
op  (I) The attribute-expression operator
rhs_val  (I) A constant C string that acts as the right hand operand

POMAPI int POM_enquiry_set_string_value ( const char *  enq_id,
const char *  val_id,
int  n_vals,
const char **  vals,
int  propriety 
)

Creates a string value on a query.

For details, see POM_enquiry_set_int_value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new value
val_id  (I) The id to be given to the new value
n_vals  (I) The number of values in the list (use 1 for a single scalar value)
vals  (I) The list of n_vals values
propriety  (I) Specifies whether the value is a constant or a bind value

POMAPI int POM_enquiry_set_sub_enquiry ( const char *  enq_id,
const char *  sub_enq_id 
)

Creates a new sub-query on an existing query.

Restrictions:

  1. enq_id must be the name of a query that already exists within the user's current session.
  2. sub_enq_id must not be the name of an query that already exists within the user's current session.
Parameters:
enq_id  (I) The query one which the new sub-query is to be created
sub_enq_id  (I) The id to be given to the new sub-query

POMAPI int POM_enquiry_set_tag_expr ( const char *  enq_id,
const char *  expr_id,
const char *  aclass,
const char *  attr,
int  op,
tag_t  rhs_val 
)

Creates an attribute-expression on a query from

  1. an attribute (the left hand operand)
  2. an operator
  3. a tag value

This method is provided as a convenient way of making an expression using a tag value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new expression
expr_id  (I) The id to be given to the new expression
aclass  (I) The POM class, alias or Tc type that owns the attribute
attr  (I) The attribute or supported compound property of aclass that acts as the left hand operand
op  (I) The attribute-expression operator
rhs_val  (I) A constant tag value that acts as the right hand operand

POMAPI int POM_enquiry_set_tag_value ( const char *  enq_id,
const char *  val_id,
int  n_vals,
const tag_t *  vals,
int  propriety 
)

Creates a tag value on a query.

For details, see POM_enquiry_set_int_value.

Restrictions: See POM_enquiry_set_int_value.

Parameters:
enq_id  (I) The query that is to own the new value
val_id  (I) The id to be given to the new value
n_vals  (I) The number of values in the list (use 1 for a single scalar value)
vals  (I) The list of n_vals values
propriety  (I) Specifies whether the value is a constant or a bind value

POMAPI int POM_enquiry_set_where_expr ( const char *  enq_id,
const char *  expr_id 
)

Sets the where clause of the query to the specified expression.

Calling this function replaces the query's existing where clause, if it has been set.

Restrictions:

  1. enq_id must identify an existing query
  2. expr_id must identify an existing expression on the query, and the expression must evaluate to either true or false
Parameters:
enq_id  (I) The query whose where clause is to be set
expr_id  (I) The id of an existing expression defined on the query

POMAPI int POM_execute_enquiry ( tag_t  enqid,
int *  nval,
tag_t **  values 
)

Executes the specified enquiry.

This enquiry may have been built up by several calls to POM_create_enquiry_on_<type>, POM_create_enquiry_on_<type>s, POM_create_enquiry_on_ids, POM_create_enquiry_on_ref and POM_combine_enquiries.

If nval is 0, then values is NULL.

This function is provided for completeness.

Usually the enqid is handed to a function like POM_load_instances_by_enq, which executes the enquiry and acts on the instances which the enquiry produces.

Parameters:
enqid  (I) ID of enquiry to execute
nval  (O) Number of selected instances
values  (OF) nval Tags of selected instances

POMAPI int POM_order_enquiry ( tag_t  enq1,
int  n_attrs,
const tag_t *  attr_ids,
const int *  up_or_down_tokens 
)

Specifies the order in which to produce the instances.

Each attribute can be ordered in ascending or descending order. The instances are ordered on the value of each attribute in turn, starting with the first attribute in the array.

This function can be used to override a previously specified order, so that for instance the same enquiry_id can be used more than once to produce different orderings of the same instances.

Parameters:
enq1  (I) ID of enquiry, the result of which is to be ordered.
n_attrs  (I) Number of attributes to use for ordering
attr_ids  (I) n_attrs IDs of attributes to use for ordering
up_or_down_tokens  (I) n_attrs Array of tokens for whether to order attribute values in ascending or descending order such as POM_order_ascending or POM_order_descending