Change Methods

A change method can be associated with a field of an object as a subfield of that field. A change method is run every time a transaction is run (a user API or method API transaction) that changes the contents of the field. A change transaction whose target is a simple field triggers whatever change method has been assigned to the change subfield of the target field. Change methods can be triggered by these transactions through either the user API or method API.

A change method is also triggered when a transaction issues the EKG_LinkTrigger function request or the EKG_UnlinkTrigger function request to link two fields in two objects and those fields have change methods defined. These change methods cannot change the value of the fields. The change methods must set a return code to indicate whether the link or unlink can proceed. If the change methods do not exist, or if they do not explicitly set the return code, RODM assumes the return code is zero and the link or unlink proceeds. Change methods on fields other than ObjectLink and ObjectLinkList are run only when the field on which they are defined is directly changed. A change method is not run when the same field on the parent class is changed and the changed value is inherited. A change method is not run by changes in a child object or class. A change method is not run by changes to subfields. The triggering of change methods can be avoided by the use of transactions that manipulate the value subfield of a field.

If a field has a change method defined on it, that change method is responsible for making any changes to the value of that field; RODM will not change the value of that field. The change method must use the EKG_ChangeSubfield function to update the value subfield of the field. If the change method uses the EKG_ChangeField or EKG_ChangeMultipleFields functions to update the value subfield, the change method recursively runs itself. RODM detects and blocks the recursive method execution but does not change the value subfield.

If a change method needs to interact with a resource outside of RODM, it sends any request to the resource asynchronously and set the appropriate flags to indicate that the request has been sent. The change method does not wait for a reply from the real resource before it continues processing.

A change method is associated with a specific field of a specific object. Only a change to that specific field of that object triggers the change method to be run. Change methods for a field of an object can automatically exist on the object by inheritance at the time the object is created. A change method on a field of an object is not triggered by the creation or deletion of that object.

A change subfield has data type MethodSpec. The MethodSpec data type identifies the method that is run. It optionally contains long-lived parameters that are passed to the method when it is run. The long-lived parameters can be used to adapt a general purpose method to a particular situation.

The long-lived parameters can be a list of field identifiers. They are defined when the method is assigned to the change subfield. The list of field identifiers is static. However, the values in the fields are dynamic; they can be changed at any time.

A method can read the contents of fields through the method API. So with a list of field identifiers specifying which fields contain its parameters, a change method can find its own execution-time parameters and take the intended actions. Most methods are written as general-purpose methods by IBM®, and several parameters might be required to adapt the general-purpose method to the specific function to be performed to manage a change to a field. This design has the advantage of making parameters to methods visible through the user API for debugging purposes.

Another parameter (besides the long-lived parameters) is passed to a change method when the method is run. The function blocks in the user API and method API for changing fields all include a short-lived parameter, which is SelfDefining data with a maximum length of 254 bytes. When a function block is filled in, a requestor can use these 254 bytes for any data that needs to be passed at invocation time to any methods triggered by the transaction.

To change the value subfield of the field, the change method obtains the data supplied through the API. That information is passed as the fourth and fifth parameters.

Figure 1 shows example change method parameters for PL/I. Figure 2 shows example change method parameters for C.

 ChngMeth: Procedure ( Field_ID, LLParms, SLParms, DataType, CharDataLen, DataPtr )
  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       */
  Dcl DataType    Smallint;                /* Data type of field                     */
  Dcl CharDataLen Integer;                 /* Valid for data type CharVar and GraphicVar */
  Dcl DataPtr     pointer;                 /* Pointer to new data from API call      */
    . . . .
    /* code */
    . . . .
  End;  

  VOID ChngMeth(FieldID                      *in_FieldID,
                SelfDefiningDataPtr          **in_LLParms,
                SelfDefiningDataPtr          **in_SLParms,
                Smallint                     *in_DataType,
                Integer                      *in_CharDataLen,
                Pointer                      **in_DataPtr);
  ....
  /* code */
  ....  

The return code and reason code for the entire transaction can be controlled from a change method through calls in the method API available to the method.