Query Methods

A query method is run by RODM when a transaction queries the value of a field; but not run when the value subfield is explicitly queried. The query method:

Can determine final returned data value of the field being queried
Is inherited unless locally overridden
Runs in context of a class or object being queried

The query method parameters are:

field_id: FieldID of the field being queried.
long_lived_parms: A SelfDefining string containing application-defined parameters. These parameters are provided to the query method when it is installed.
short_lived_parms: A SelfDefining string containing application-defined parameters. These parameters are provided to the method dynamically during the actual API function request that triggers the query method.

Query methods can be associated with fields of objects. If a query method is defined for a field, the method is run each time the field is queried using the EKG_QueryField function through the user API or method API. If a query method is defined, it is responsible for returning a value for the field to the function that queried the field. The query method can return the current value of the field, or the method can return some other value. For example, a query method can issue a command to some real resource to get the current status of that real resource.

The query can use the EKG_ResponseBlock function to write its response to the caller-provided response block. If the query method does not use the EKG_ResponseBlock function, RODM returns the data in the queried field to the query function. A query method can generate the actual value that is returned. It can check time stamps to verify that the value of a field is current. If you do not want to trigger a query method, use the EKG_QuerySubfield function to query the value subfield of the field rather than querying the field itself.

If a query method submits a command to a real resource to obtain information, it returns immediately to the caller with a reason code indicating that a request for new data has been submitted. No method enters a WAIT state.

A query method is associated with a specific field of a specific object. Only a query of that field of that object triggers the query method to be run.

A query subfield has data type MethodSpec. A query subfield can preserve the name of a query method to be run and a list of field identifiers specifying (long-lived) field parameters to be used by the query method in customizing its behavior to the particular object, field, and environment where the query method is executing. The query method can read the contents of the field parameters using routines available through the method API.

A short-lived parameter is also extracted from the function block submitted by the requesting application and passed to a query method at the time of invocation. Figure 1 shows an example of query method parameters for PL/I. Figure 2 shows an example of query method parameters for C.

Figure 1. Query Method Procedure Interface for PL/I

 QueryMeth: Procedure ( Field_ID, LLParms, SLParms );
  Dcl Field_ID     FieldID;              /* target field of transaction */
  Dcl LLParms     SelfDefiningDataPtr;  /* Pointer to Long-lived field parameters */
  Dcl SLParms     SelfDefiningDataPtr;  /* Pointer to Short-lived Parameter       */
    . . . .
    /* code */
    . . . .
  End;

Figure 2. Query Method Procedure Interface for C

  VOID QueryMeth(FieldID                     *in_FieldID,
                 SelfDefiningDataPtr         **in_LLParms,
                 SelfDefiningDataPtr         **in_SLParms);
  ....
  /* code */
  ....