Try OpenEdge Now
skip to main content
Web Services
Creating OpenEdge REST Web Services : Data Object Services : Coding Business Entities to implement Data Objects : Coding ABL for Data Object operations
 
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.
Table 10. Prescribed ABL parameters for standard Data Object operations
Standard operation
Prescribed ABL parameter list1
Create
INPUT-OUTPUT { TABLE table-name | DATASET dataset-name  
| TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }2
Read
INPUT filter3 AS CHARACTER ,
OUTPUT { TABLE table-name | DATASET dataset-name  
| TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }4
Update
INPUT-OUTPUT { TABLE table-name | DATASET dataset-name  
| TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }5
Delete
INPUT-OUTPUT { TABLE table-name | DATASET dataset-name  
| TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }6
Submit
INPUT-OUTPUT { TABLE table-name | DATASET dataset-name  
| TABLE-HANDLE table-hdl | DATASET-HANDLE dataset-hdl }7,8
1 If the implementing ABL routine is a class method, its return type must be VOID. The return value of any ABL routine is ignored.

2 Because all the standard operations of a Data Object resource must support the same schema, their implementations all must share either a TABLE, TABLE-HANDLE, DATASET, or DATASET-HANDLE parameter with exactly the same temp-table or ProDataSet schema.

3 The filter parameter is passed as a query string or a JSON object that is intended to filter the records returned for the temp-table or ProDataSet parameter of a read operation. Your ABL routine can use this value for any purpose, or ignore the parameter entirely. Note that to allow the prescribed mapping to work between the ABL routine for the standard Read operation and the JavaScript method that calls it, you must name this parameter filter in the signature of the ABL routine.

4 Because all the standard operations of a Data Object resource must support the same schema, their implementations all must share either a TABLE, TABLE-HANDLE, DATASET, or DATASET-HANDLE parameter with exactly the same temp-table or ProDataSet schema.

5 Because all the standard operations of a Data Object resource must support the same schema, their implementations all must share either a TABLE, TABLE-HANDLE, DATASET, or DATASET-HANDLE parameter with exactly the same temp-table or ProDataSet schema.

6 Because all the standard operations of a Data Object resource must support the same schema, their implementations all must share either a TABLE, TABLE-HANDLE, DATASET, or DATASET-HANDLE parameter with exactly the same temp-table or ProDataSet schema.

7 Because all the standard operations of a Data Object resource must support the same schema, their implementations all must share either a TABLE, TABLE-HANDLE, DATASET, or DATASET-HANDLE parameter with exactly the same temp-table or ProDataSet schema.

8 The implementation for a Submit operation (like the other standard operations) supports either a single ProDataSet or a single temp-table parameter, and all CRUD operations that you define for the same Data Object resource must support the same parameter type. However, note that the single temp-table parameter does not support before-imaging, and you cannot use the OpenEdge.BusinessLogic.BusinessEntity as a base class for the resource implementation because it only supports Submit with a single ProDataSet parameter; therefore, you must code the entire resource implementation yourself.

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.