Coding ABL for Data Object operations

No matter how you obtain the ABL class or procedure to implement a Data Object resource, any ABL routines that you define in the source file to implement Data Object operations must conform to specific coding requirements. Otherwise, a client cannot access the data using client-side Data Objects (JSDOs). These requirements depend on the operation and the data that you want the resource to provide:

• The ABL routines that implement Data Object CRUD and Submit operations must all operate on the same data model.
• Each ABL routine that implements a standard Data Object Create, Read, Update, Delete, or Submit operation must have a prescribed parameter list, based on the data model that the Data Object resource supports. When you create a new Business Entity for a data model, the wizard generates correct parameter lists for interacting with that data model.
• For the fields of temp-tables in the data model, and for the parameter lists and return types of ABL routines that implement custom Invoke operations, you can include all supported ABL data types except RAW and RECID. The ABL RAW and RECID data types are not supported by OpenEdge Data Objects.
• For all standard Data Object CRUD and Submit operations, the return type for class methods must be VOID, and any return values from internal procedures and user-defined functions are ignored.

The following table shows a complete description of the prescribed parameter list for each standard Data Object CRUD and Submit operation. The notes in the table describe important additional requirements and limitations that you need to consider.

INPUT-OUTPUT { TABLE table-name | DATASET dataset-name  
  | TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }2

INPUT filter3 AS CHARACTER ,
OUTPUT { TABLE table-name | DATASET dataset-name  
  | TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }2

INPUT-OUTPUT { TABLE table-name | DATASET dataset-name  
  | TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }2

INPUT-OUTPUT { TABLE table-name | DATASET dataset-name  
  | TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }2

INPUT-OUTPUT { TABLE table-name | DATASET dataset-name  
  | TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }2,4 

As noted previously, when you define a Data Object resource by creating a new Business Entity class, it creates the class methods to implement the Data Object CRUD and Submit operations using the correct parameter list, and in some cases, leaves the code block for each method empty for you to complete. For this purpose, and for any revisions you might need to make to an existing class or procedure you are using to define a Data Object resource, you need to account for certain features of the client-side Data Object (JSDO):

• A JSDO has an internal data store (JSDO memory) that is structured to match the data model selected for the Data Object resource that it accesses. So, if the data model is a ProDataSet containing ten temp-tables with data-relations, JSDO memory is structured to map the data for these ten temp-tables and their data-relations.
• If your Data Object resource supports both Data Object CRUD and Submit operations on a ProDataSet, the JSDO created for it includes before-image support to work with multi-record transactions over the network. This means that the ABL routine that implements the Submit operation needs to be written to access the ProDataSet to handle these multi-record transactions using before-imaging. In addition, the ABL routines that implement the Create, Update, and Delete operations handle single-record transactions only, but also work with the before-image features of the ProDataSet. For example, if a record-change (CUD) operation fails on a ProDataSet, the value of the ERROR-STRING attribute on the associated temp-table buffer object is typically set to provide information about the error that can be returned to the JSDO on the client. As noted previously, OpenEdge provides a pre-defined ABL abstract class (OpenEdge.BusinessLogic.BusinessEntity) that you can use as a base class to implement these Data Object operations with before-image support.
• If your Data Object resource supports Data Object CRUD operations without before-image support, the JSDO created for it also does not include before-image support and only supports single-record transactions over the network. Therefore, each Data Object Create, Update, and Delete operation can only change a single record at a time, and the ABL routines that you use to implement these operations can only update a single input record per invocation on the server.

  The standard Data Object CRUD operations without before-image support interact directly with the JSDO memory accordingly. The Read operation reads a set of records from its single temp-table, or from the temp-tables of its single ProDataSet on the server and loads them into JSDO memory. The Create, Update, and Delete operations each send only a single record from JSDO internal memory to the server, where they, respectively, add the new record, update the existing record, or delete the existing record from the OpenEdge data source. These operations execute across the network multiple times in order to update multiple records on the server. So, if the data model is a ProDataSet with multiple tables, the ABL routine that implements the operation must query each table for which the operation applies in order to find that one record to Create in, Update in, or Delete from the data source.

  When a Data Object Create, Update, or Delete operation completes, it can only return a single record to JSDO memory. For example, if an update operation fails, it might return the record with the field values that currently exist in the data source, along with raising an ABL error explaining how the update failed.

• If your Data Object resource supports a Submit operation on a single temp-table, it can process multiple record changes in a single network request to the server. However, without before-image support, you must manage individual record changes using your own semantics in both client JSDO memory and in the server Data Object resource.