Query & Schema Management Logic

There are a number of functions that need to be wired up within your host application to manage the operation of query editing and execution. Each of those functions are briefly discussed in this topic. Examples of the implementation of each of these discussion items can be viewed within the source code of the provided sample application.

Loading a Query & Handling cQuery Events

To load a query, your host application will determine which query definition to load/edit - most probably by requesting the user to pick a query using its friendly name.  Once the desired query has been selected, the following typical chain of events will be executed:

1. Your Host Application will instantiate a new cQuery object and will subscribe to some or all (as appropriate) of the following cQuery events for the new object (for examples of subscribing to each of these events, see the source code for the sample application):
    

   cQuery Events	Subscription	Description/Purpose
   QueryNeedsSavingChanged	Optional	By subscribing to this event, you will receive notification that the query needs saving as a result of changes to its design.  This event fires only the first time that the state changes.  If you want notification every time a change occurs, use the QueryDefinitionChanged event instead.
   QueryDefinitionChanged	Optional	By subscribing to this event, you will receive notification every time the query definition changes.  You may also determine if it has been changed at any time by referencing the cQuery.NeedsSaving property
   QueryNameChanged	Optional	If you would like immediate notification if the cQuery object's display name has changed.
   QuerySchemaNeeded	Recommended	You should subscribe to this event so that SQL Designer can request the host application to provide the schema definition for the query in the case that the correct schema was not provided on cQuery Instantiation, or, a new query is loaded but the schema was not pre-identified.
   QueryNeedsOptionsList	Required (if your schema designs incorporate criteria that may use pre-defined lists (other than static lists) to determine possible values for criteria.)	You can specify in schema design that a field used in criteria obtains a list of possible values from (amongst other options) the results of either a pre-defined SQL statement, or, a named DataView. This event is fired when SQL designer needs your host application to process either of these items and return a list of possible values for the user to select from.
   QueryNeedsFunctionList	Optional	If you wish to use SQL Designer's advanced Value Function functionality and want your application to be able to supply possible Value Functions available for a criteria condition, you must subscribe to this event so that your host application may provide a list of available functions during construction of query criteria.
   QueryNeedsFunctionResult	Optional	This event will be raised if you have implemented the QueryNeedsFunctionList event; the user has used one of those host application provided value functions; and, the query is being built and hence needs the current value of the Value Function.
   QueryNeedsUserInput	Required	You must subscribe to this event to handle the case where SQL Designer is building SQL text for a query, but, needs user input for a condition's value.  If the value is to come from the user running the query, the WinUI namespace provides the (fUserPrompt) class to prompt for and process the user input.
   QueryNeedsCustomEditor	Optional	If you have implemented and specified custom editors for one or more fields in a schema design and the user will be editing criteria, this event should be subscribed so that you may supply a reference to the required editor when needed.
   QueryDisplayMessage	Optional	This event is used to pass editor validation error information raised as a result of the user incorrectly responding to a condition value prompt. If not subscribed and a UI is assigned for criteria, SQL Designer will display the validation error in a standard message box.
   QueryInvalidDefinition	Required	When building SQL for a query, if any items are incomplete in the query designer or some other consistency is encountered, this event will be raised, providing information about the issues encountered.   Errors may be fatal or non-fatal.  Non-fatal errors will allow construction of the SQL but omit all SQL referencing the offending elements.

    

2. Next, load the desired query definition into the cQuery object using the cQuery.LoadQueryDefinition method.
   Note: If the cSchema is not provided at time of cQuery instantiation, the QuerySchemaNeeded event will fire and your host application will be responsible for returning a cSchema object via the event arguments.  This is the recommended method for providing cSchema objects to support cQuery objects rather than providing them as cQuery instantiation.  See the sample application for example code that implements the QuerySchemaNeeded event handler. Also note, that cSchema objects should also have event handlers' attached before they are returned to the cquery objects. See cSchema Events below for addiional information.
    

3. If you are editing the query, assign the Query property of the uQueryPanel components to the newly loaded cQuery Object.

For information on the query editing interface, please refer to the chapter entitled End User Query Help which is also provided in source form so that you may edit and/or include it in the help project for your application.

Using this approach, all actions that may then be required will be handled by one of the subscribed events listed above.  At the conclusion of any editing and depending on the modality of your host application, the cQuery.NeedsSaving property can be accessed to determine whether the query definition needs to be re-persisted using one of the cQuery.SaveDefinition overloads.

Handling cSchema Events

When instantiating new cSchema objects prior to passing them to cQuery's in response to the QuerySchemaNeeded event, you should first attach some event handlers to the cSchema object to ensure that your host application is able to respond to requests from the object.  The following events are available to be subscribed for cSchema objects:

Building SQL

To build SQL text for any loaded query, you need only to access the cQuery.SQL property, optionally specifying the part of the SQL string that you want built.

The act of building the SQL can cause any of the following events to fire, so, ensure that you are subscribed to these events prior to accessing the cQuery.SQL property (Note: As described in the section on Loading A Query, many of these events will probably already be subscribed to.  Refer to this table for detailed information on all of the query events and this table for the cSchema events.)

• cQuery.QueryNeedsFunctionResult - may fire to obtain the result of a custom Value Function result from your application.

• cQuery.QueryNeedsUserInput - may fire to request you to satisfy one or more conditions that are set to user prompt type.

• cQuery.QueryInvalidDefinition - may fire to notify you that the query definition or part thereof is invalid.

If the schema being used contains advanced functions such as tables defined by either a nested SQL Designer Query or defined SQL text, one or both of the following cSchema events may also fire on building of SQL for the query:

• cSchema.SchemaQueryObjectNeeded - may fire if the schema is of advanced design, incorporating cQuery definitions to define virtual tables.

• cSchema.SchemaQueryExecutionNeeded - may fire to actually request execution of SQL that creates a virtual table within the schema to service the Query's SQL generation.

For additional guidance, refer to the getting started guides in the Developer's Reference Help Document.