Functions to attach and detach the Data-Sources from a ProDataSet

The reason why all the FILL event procedures can be defined in the Data Access object, even though the procedure's ProDataSet instance is not really used to hold data at run time, is that the Data Access object takes responsibility for attaching those procedures to any ProDataSet instance passed into the Data Access object. OrderSource.p has an attachDataSet function to do this, as shown:

FUNCTION attachDataSet RETURNS LOGICAL (INPUT phDataSet AS HANDLE):
  phDataSet:GET-BUFFER-HANDLE("ttOline"):SET-CALLBACK-PROCEDURE
    ("AFTER-FILL", "postOlineFill", THIS-PROCEDURE).
  phDataSet:GET-BUFFER-HANDLE("ttItem"):SET-CALLBACK-PROCEDURE
    ("AFTER-ROW-FILL", "postItemRowFill", THIS-PROCEDURE).
  phDataSet:GET-BUFFER-HANDLE("ttOrder"):ATTACH-DATA-SOURCE
    (DATA-SOURCE srcOrder:HANDLE, "Customer.Name,CustName").
  phDataSet:GET-BUFFER-HANDLE("ttOline"):ATTACH-DATA-SOURCE
    (DATA-SOURCE srcOline:HANDLE).
  phDataSet:GET-BUFFER-HANDLE("ttItem"):ATTACH-DATA-SOURCE
    (DATA-SOURCE srcItem:HANDLE).
END FUNCTION. /* attachDataSet */

This could just as easily be an internal procedure, of course. A more thorough implementation of the function should check the return value for each SET-CALLBACK-PROCEDURE and ATTACH-DATA-SOURCE method and return an ERROR status to the caller. The SET-CALLBACK-PROCEDURE methods attach the needed FILL events handlers, and the ATTACH-DATA-SOURCE methods connect the ProDataSet instance to its database tables.

If a repository or other persistent store holds the field mapping and Data-Source mapping for the ATTACH-DATA-SOURCE methods, and the callback procedure names and locations for the SET-CALLBACK-PROCEDURE methods, then this function could become generic, and be part of a standard procedure that supports all Data Access objects (as a super procedure, for instance).

There should also be a function or procedure to detach all Data-Sources, as in this example:

FUNCTION detachDataSet RETURNS LOGICAL (INPUT phDataSet AS HANDLE):
  DEFINE VARIABLE iBuff AS INTEGER NO-UNDO.

  DO iBuff = 1 TO DATASET dsOrder:NUM-BUFFERS:
    phDataSet:GET-BUFFER-HANDLE(iBuff):DETACH-DATA-SOURCE().
  END.
END FUNCTION. /* detachDataSet */

As this sample shows, this function can easily be made generic, so it is written only once and resides in a Data Access support procedure.

It is important to note that once the Data-Sources are attached and any callback procedures established, the calling procedure that passed in the ProDataSet instance to attachDataSet can simply do a FILL if the Data-Source definitions and FILL event handlers fully determine what rows to populate the ProDataSet with. In other words, once the ProDataSet is returned to the caller, the Data-Sources and callback procedures remain associated with it through its handle, so these associations remain intact even in the ProDataSet instance is passed around within the session, so that other procedures and invoke a FILL or other methods on that handle from anywhere in the session. In many cases, however, a FILL will require that the ProDataSet's queries first be prepared to retrieve only a selected set of related rows before doing the FILL. An API for such calls is discussed in the next section.