progress datadirect: ® openaccess for openedge · pdf fileprogress datadirect : openaccess...

Progress DataDirect: ®

OpenAccess for OpenEdgeApplication Server

Notices

For details, see the following topics:

• Copyright

Copyright

© 2014 Progress Software Corporation and/or its subsidiaries or affiliates.All rights reserved.These materials and all Progress® software products are copyrighted and all rights are reservedby Progress Software Corporation.The information in these materials is subject to change withoutnotice, and Progress Software Corporation assumes no responsibility for any errors that mayappear therein. The references in these materials to specific platforms supported are subject tochange.

Business Making Progress, Corticon, DataDirect (and design), DataDirect Cloud, DataDirectConnect, DataDirect Connect64, DataDirect XML Converters, DataDirect XQuery, Fathom, MakingSoftware Work Together, OpenEdge, Powered by Progress, Progress, Progress Control Tower,Progress OpenEdge, Progress RPM, Progress Software Business Making Progress, ProgressSoftware Developers Network, Rollbase, RulesCloud, RulesWorld, SequeLink, SpeedScript, StylusStudio, and WebSpeed are registered trademarks of Progress Software Corporation or one of itsaffiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, AppsAlive, AppServer,BusinessEdge, Progress Easyl, DataDirect Spy, DataDirect SupportLink, Easyl, Future Proof, HighPerformance Integration, OpenAccess, Pacific, ProDataSet, Progress Arcade, Progress Pacific,Progress Profiles, Progress Results, Progress RFID, Progress Responsive Process Management,Progress Software, ProVision, PSE Pro, SectorAlliance, SmartBrowser, SmartComponent,SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame,SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, WebClient, and Who MakesProgress are trademarks or service marks of Progress Software Corporation and/or its subsidiaries

3Progress DataDirect : OpenAccess for OpenEdge Application Server: Version 7.2.0

or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or itsaffiliates. Any other marks contained herein may be trademarks of their respective owners.

June 2014

Last updated with new content: Release 7.2.0

Progress DataDirect : OpenAccess for OpenEdge Application Server: Version 7.2.04

Notices

Table of Contents

Preface.............................................................................................................7Purpose...................................................................................................................................................7

Audience.................................................................................................................................................8

Using this manual....................................................................................................................................8

Typographical conventions......................................................................................................................8

Chapter 1: Installing OpenAccess for OpenEdge Application Server.....11Pre-requisites and system requirements...............................................................................................11

Product Installation................................................................................................................................12

OpenEdge Installation................................................................................................................12

OpenAccess Installation.............................................................................................................12

Installing OpenAccess for OpenEdge Application Server..........................................................12

OpenAccess Service setup for OpenEdge Application Server..............................................................14

Testing the connection to OpenEdge Application Server:.....................................................................15

Starting the OpenAccess Service for OpenEdge Application Server....................................................16

On Windows...............................................................................................................................16

On UNIX.....................................................................................................................................16

Querying Sample Business Entities from ODBC:.......................................................................17

Querying Sample Business Entities from JDBC:........................................................................18

Restrictions and Limitations..................................................................................................................19

Chapter 2: Enabling OE Application for data access................................21Overview...............................................................................................................................................22

Determining schema definition..............................................................................................................22

ABL to SQL Mapping.............................................................................................................................24

Procedures/interfaces to be called for CRUD operations on specific resource/business entity............25

Performing CRUD Operations on Business Entities..............................................................................26

Understanding CRUD Operations.........................................................................................................27

Performing Secure CRUD Operations...................................................................................................30

Procedures for Handling Connections .......................................................................................30

Security configurations for OpenEdge Application Server:.........................................................31

Security Validation in CRUD operations on business entities:....................................................31

Generating a JSDO Catalog..................................................................................................................32

Generating JSDO Catalog using OpenEdge Development Studio.............................................32

Generating JSDO Catalog Manually..........................................................................................32

Chapter 3: Configuring OpenEdge and OpenAccess...............................33


Configuring OpenEdge..........................................................................................................................33

Configuring OpenAccess......................................................................................................................34

ServerDataSource settings.........................................................................................................34

OpenEdge Application Server Connection Scenarios.....................................................36

DataSourceLogonMethod................................................................................................37

Chapter 4: Troubleshooting.........................................................................39Connection Exceptions..........................................................................................................................40

Query Execution Exceptions.................................................................................................................41

Appendix A: Appendix.................................................................................43Catalog Definition..................................................................................................................................43

Sample Business Entity ABL Procedures.............................................................................................43

Creating Test Tables in the OpenEdge Database.......................................................................45


Preface


• Purpose

• Audience

• Using this manual

• Typographical conventions

PurposeProgress DataDirect OpenAccess for Progress OpenEdge Application Server (OpenAccess forOpenEdge Application Server) enables you to access, using SQL, Business Entities deployed inOpenEdge Application Server through drivers (ODBC driver, JDBC driver, and ADO.NET provider).While the drivers for OpenEdge SQL enable you to access data in the OpenEdge RDBMS,OpenAccess for OpenEdge Application Server enables you to access Business Entities.OpenAccess for OpenEdge Application Server enables SQL access to Business Entities definedin ABL procedures (.p files) that expose results as TempTable or ProDataSet. The schema forbusiness entities is defined in the JSDO catalog, which can be generated using Progress DeveloperStudio for OpenEdge or the schema can be configured manually. Having the drivers for BusinessEntities enables efficient and standard integration with third-party tools, such as developmentsoftware, reporting tools, data warehousing tools, Extract-Transform-Load (ETL) tools, and OnlineAnalytical Processing (OLAP) tools.


AudienceThis guide is intended for OpenEdge developers who want to enable ODBC/JDBC connectivityfor the data in their OpenEdge business application developed in OpenEdge Advanced BusinessLanguage (ABL). Users of this guide are expected to be familiar with OpenEdge ABL and OpenEdgeApplication Server.

Using this manualUsing this manual, OpenEdge developers can enable SQL access to their business entitiesimplemented in ABL procedures. Enabling SQL access to business entities requires the procedurefor Create/Read/Update/Delete (CRUD) operations to be implemented using the prescribed interfacedefinition. Minimal code changes in ABL and minimal configuration of OpenAccess Service enableSQL access to business entities. OpenAccess Interface Provider does not require any coding.

Typographical conventionsThis manual uses the following typographical and syntax conventions:

DescriptionConvention

Bold typeface indicates commands or characters the user types,provides emphasis, or the names of user interface elements.

Bold

Italic typeface indicates the title of a document, or signifies newterms.

Italic

Small, bold capital letters indicate OpenEdge key functions andgeneric keyboard keys; for example, GET and CTRL.

SMALL, BOLD CAPITAL

LETTERS

A plus sign between key names indicates a simultaneous keysequence: you press and hold down the first key while pressing thesecond key. For example, CTRL+X.

KEY1+KEY2

A space between key names indicates a sequential key sequence:you press and release the first key, then press another key. Forexample, ESCAPE H.

KEY1 KEY2

Syntax:

A fixed-width font is used in syntax, code examples, system output,and file names.

Fixed width

Fixed-width italics indicate variables in syntax.Fixed-width italics


Preface

DescriptionConvention

Fixed-width bold italic indicates variables in syntax with specialemphasis.

Fixed-width bold

ABL keywords in syntax and code examples are almost alwaysshown in upper case. Although shown in uppercase, you can typeABL keywords in either uppercase or lowercase in a procedure orclass.

UPPERCASE fixed width

All statements except DO, FOR, FUNCTION, PROCEDURE, and REPEATend with a period. DO, FOR, FUNCTION, PROCEDURE, and REPEATstatements can end with either a period or a colon.

Period (.) or colon (:)

Large brackets indicate the items within them are optional.[ ]

Small brackets are part of ABL.[ ]

Large braces indicate the items within them are required. They areused to simplify complex syntax diagrams.

{ }

Small braces are part of ABL. For example, a called externalprocedure must use braces when referencing arguments passed bya calling procedure.

{ }

A vertical bar indicates a choice.|

Ellipses indicate repetition: you can choose one or more of thepreceding items.

...


Preface


Preface

1Installing OpenAccess for OpenEdgeApplication Server

.


• Pre-requisites and system requirements

• Product Installation

• OpenAccess Service setup for OpenEdge Application Server

• Testing the connection to OpenEdge Application Server:

• Starting the OpenAccess Service for OpenEdge Application Server

• Restrictions and Limitations

Pre-requisites and system requirementsYou should have the OpenEdge and OpenAccess products installed. OpenAccess for OpenEdgeApplication server supports the following application versions:


OpenEdge:

• 10.2B

• 11.2.x

• 11.3.x

OpenAccess:

• 7.2.

Java:

• 1.7.0.02 or higher

Product InstallationThe following products should be installed in order to use the OpenAccess for OpenEdge ApplicationServer:

• OpenEdge

• OpenAccess

• OpenAccess for OpenEdge Application Server

The following sections provide instructions on how to install these products.

OpenEdge InstallationDownload and install a supported version (10.2b/11.2.X/11.3.X) of OpenEdge(if not installedalready). Refer to the Progress OpenEdge Getting Started: Installation and Configuration guidefor instructions and further information.

OpenAccess InstallationDownload and install Progress OpenAccess 7.2 (OpenAccess Server and OpenAccess Client,ODBC /JDBC). Refer to the Progress DataDirect: OpenAccess SDK installation guide for instructionsand further information.

Installing OpenAccess for OpenEdge Application ServerTo install OpenAccess for OpenEdge Application Server

1. Download the oa_ip_oe_appserver_7_2_0.jar from the Progress Download Center and copyto the OpenAccess Installation location (which is usually C:/ProgramFiles/Progress/DataDirect/oaserver72 for Windows)

2. Open the command prompt and extract the oa_ip_oe_appserver_7_2_0.jar file using thecommand jar -xvf oa_ip_oe_appserver_7_2_0.jar.

This creates the following directories and files.


Chapter 1: Installing OpenAccess for OpenEdge Application Server

DescriptionFiles/DirectoryDirectory

The OpenAccess IP forOpenEdge Application Serverjava library file.

damip.jarip/oajava/oeabl

Third-party vendor licenseagreements

notices.txtip/oajava/oeabl

OpenEdge Java Open Clientlibrary files and Third PartyLibraries

messages.jar o4glrt.jarprogress.jar tools.jar

ip/oajava/oeabl/lib

Sample ABL procedure filesfor OpenEdge 10.2B andOpenEdge 11.0.

Details of the ABL Samplescan be found in the Appendix.

The oasamples folder shouldbe copied to the OpenEdgeworking directory on theApplication Server (example:C:/OpenEdge/WRK ).

The directory containsseparate samples forAnonymous Login mode andSecure Login mode.

security_cfg: directorycontains the samples forimplementing the ApplicationServer security mechanismusing client-principal

oe102b oe11ip/oajava/oeabl/oasamples

Scripts to create and removeOpenAccess Service forOpenEdge Application Server:

• oacreate_oeservice.[bat/sh]script files to create service

• oacreate_oeservice.[bat/sh]script files to create service

Service_setupip/oajava/oeabl/tools

Test the application to verifythe connection to OpenEdgeApplication Server.

Test_clientip/oajava/oeabl/tools

Schema definition JSDOcatalog files for OpenEdge10.2B and OpenEdge 11.0.

oe102b oe11ip/schema/oeabl

3. Copy the oasamples folder from ip/oajava/oeabl to the OpenEdge Application ServerWorkspace(example: C:/OpenEdge/WRK ).


Product Installation

OpenAccess Service setup for OpenEdge ApplicationServer

OpenAccess Interface Provider connects to the OpenEdge Application Server using theAppServerURL in one of the following methods:

• Through a NameServer:AppServer:<//Name-server-host><:Name-server-port>/<AppService-name>

• Directly to an AppServer:AppServerDC:<//AppServer-host><:AppServer-port>/<AppService-name>

You require the AppServerURL for your deployment before you can proceed with the rest of theinstallation steps. For further information, refer to the guide, Progress OpenEdge Application Server:Developing Appserver Applications.

You must update the following script files (located in ip/oajava/oeabl/tools) for the correspondingoperating system:

Windows (oacreate_oaservice.bat):

• USERNAME: Specify the OpenAccess Administrative user account, generally<windows-domain>/<user-name>. This can be empty if OpenAccess AgentServiceAdminAuthMethods is set to integrated_nt

• OEVersion: Specify the OpenEdge version, oe11 for OpenEdge 11.x and oe102b for OpenEdge10.2B.

• AppServerURL: The OpenEdge application server's URL

• SessionModel: Specify the application service's model - the valid options are SessionFree orSessionManaged

• OASERVER: The OpenAccess Server's installation location

• JVMLOCATION: The location of the JVM library – jvm.dll,

• OAAppServerPort:The port number for the new OpenAccess service for OpenEdge ApplicationServer

UNIX (oacreate_oeservice.sh):

• USERNAME: Specify the OpenAccess Administrative user account

• PASSWORD: Specify the OpenAccess Administrative user account’s password

• OEVersion: Specify the OpenEdge version, oe11 for OpenEdge 11.x and oe102b for OpenEdge10.2B.

• AppServerURL: The OpenEdge application server's url,

• SessionModel: Specify the application service's model - the valid options are SessionFree orSessionManaged

• OASERVER: The OpenAccess server's location

• JVMLOCATION: The location of the JVM library – jvm.so/.sl

• OAAppServerPort: The port number for the new OpenAccess service to be created



After setting the values in the script, execute the script. This creates the new OpenAccess service“OpenAccess720_OEAppServer” configured to listen to port# OAAppServerPort.

The following image shows the new service that is created after running the script.

Figure 1: OpenAccess Management Console

Testing the connection to OpenEdge ApplicationServer:

Before testing the connection, ensure that the OpenEdge Database and the Application Serverare running. Refer to Configuring OpenEdge on page 33 section for details. The installed samplesare based on the Sports2000 database.

To test the connection to OpenEdge Application Server:

Run the test_connection.bat script ( test_connection.sh for UNIX), providing the OpenEdgeApplication Server URL as: test_connection.bat <OpenEdge Application ServerURL>


Testing the connection to OpenEdge Application Server:

For example: test_connection.bat AppServerDC://localhost:3090/oebroker

Starting the OpenAccess Service for OpenEdgeApplication Server

The following section contains the instructions to start the OpenAccess service for OpenEdgeApplication Server.

On WindowsTo start the OpenAccess Service for OpenEdge Application Server:

From the command prompt, execute the command

C:\> net start OpenAccess720_OEAppServer

The OpenAccess720_OEAppServer service was started successfully messageappears.

Note: Use net stop OpenAccess720_OEAppServer to stop the server.

Alternatively, open the OpenAccess SDK Management Console > Manager > Connectedto OpenAccessSDK720_Agent > Services, right-click and select StartOpenAccess720_OEAppServer

On UNIXPlease follow the below steps to start OpenAccess Service on UNIX

1. Execute the script {oa-server-install-dir}/admin/oacla.sh. The ‘oacla’promptopens.

2. At the oacla prompt, type alc to activate local configuration.

3. Enter sl to list the services. The following services are listed:

DescriptionStatusHostName

Agent serviceactiveoesoldev1OpenAccessSDK720_Agent

Service for C/C++inactiveoesoldev1OpenAccessSDK720_C

Service for C/C++inactiveoesoldev1OpenAccessSDK720_C_SQL

Service for Javainactiveoesoldev1OpenAccessSDK720_Java

Service for Javainactiveoesoldev1OpenAccessSDK720_Java_SQL

Service for Javainactiveoesoldev1OpenAccess720_OEAppServer



4. Enter ss OpenAccess720_OEAppServer and press Enter to start theOpenAccess720_OEAppServer service.

5. Enter sl to list the services.

The OpenAccess720_OEAppServer now shows the status as active.

Querying Sample Business Entities from ODBC:Create a new OpenAccess ODBC DSN and test the connection to the‘OpenAccess720_OEAppServer’ server data source‘OA_OpenEdgeAppServer’ OR‘OA_OpenEdgeAppServerSecure’. Refer to the Progress DataDirect: OpenAccess 7.2 SDKInstallation Guide for more information. Use the Interactive SQL for OpenAccess ODBC tool toexecute queries against the server data source. The following sample session for Windows showshow to create DSN “OpenEdgeABL”

To Query the Sample Business Entities using ODBC:

1. Create ODBC DSN

• Go to Control Panel > Administrative Tools; Then double-click on Data Sources (ODBC).

The ODBC Data Source Administrator window appears.

• On the User DSN tab, click ADD.

The Create New Data Source window appears.

• On the Create New Data Source window, select DataDirect OpenAccess SDK 7.2; Thenclick Finish.

The DataDirect OpenAccess SDK ODBC Driver Setup window appears.

• On the DataDirect OpenAccess SDK ODBC Driver Setup window, enter appropriate valuesfor the following fields:

• Data Source Name: The data source name. For example, OpenEdgeABL

• Service Host: The service host. For example, localhost.

• Service Port: The port at which the service is available. For example, 19991.

• Service Data Source: The service data source name active on the OpenAccess server.For example, OA_OpenEdgeAppServer.

• Click Test Connect and click OK.

The Connection test was successful. window appears. If you receive an error, checkwhether the service is running and that you have entered correct values for the fieldmentioned above.

• Click Apply and then click OK twice.

You can also create another DSN OpenEdgeABLSecure using similar steps to connect toservice data source OA_OpenEdgeAppServerSecure.

1. Query using ODBCISQL tool


Starting the OpenAccess Service for OpenEdge Application Server

On the command prompt, at location [oa-odbc-install-dir]:/ProgramFiles/Progress/DataDirect/oaodbc72 execute the following command:odbcisql.exe.

•

• For example, C: /ProgramFiles/Progress/DataDirect/oaodbc72/odbcisql.exe.

• At the Interactive SQL prompt, type

• CONNECT OpenEdgeABL for anonymous

• CONNECT <user-id>*<password>@OpenEdgeABLSecure for secure connection

Note: Ensure that the Server Data Source OA_OpenEdgeAppServerSecure is configuredfor secure CRUD support. Refer to Performing Secure CRUD Operations.

• Type an SQL query. For example, type:

• SELECT * FROM employee_pd;

• The SQL Query results appear.

Querying Sample Business Entities from JDBC:Use the Interactive SQL for JDBC tool (jdbcisql) to execute queries against the Default server datasource. Refer to the OpenAccess SDK Administrator’s Guide for detailed information on using theInteractive SQL for JDBC tool.

1. Go to [oa-jdbc-install-dir]/testforjdbc. For example,C:/oajdbcclient/testforjdbc.

2. Double-click testforjdbc.bat.

The Test for JDBC Tool window opens.

3. Click Press Here To Continue.

4. From the Connection menu, click Connect to DB….

The Select A Database window appears.

5. In the Database field enter the following string:jdbc:openaccess://localhost:19991;ServerDataSource=OA_OpenEdgeAppServer"

The connection is established with the OA_OpenEdgeAppServer and a connection windowopens up.

6. On the newly opened window, go to Connection > Load and Go….

The Get Load And Go SQL window opens.

7. In Type SQL Here, you can execute SQL queries to obtain table and column information.

For example, type the following query:

Select * from employee_pd

The data is fetched from the employee_pd table and records are displayed on the connectionwindow.



.

Restrictions and LimitationsProgress OpenAccess for Progress ApplicationServer has the following limitations:

• Connections to the OpenEdge 10.2B application servers do not support secure authentication.

• Update operations are not supported for BLOB, CLOB and RAW type fields.


Restrictions and Limitations

2Enabling OE Application for data access


• Overview

• Determining schema definition

• ABL to SQL Mapping

• Procedures/interfaces to be called for CRUD operations on specific resource/business entity

• Performing CRUD Operations on Business Entities

• Understanding CRUD Operations

• Performing Secure CRUD Operations

• Generating a JSDO Catalog


OverviewThe following architecture diagram shows the interface between OpenEdge application server andOpenAccess. ODBC/JDBC clients interface with the OpenAccess server which in turn uses theJava IP interface to connect OpenEdge application using OpenEdge Java Open client.

Figure 2: Architecture diagram

Schema and procedure definitions are necessary to connect to the OpenEdge application whileusing OpenAccess Java IP interface.

Determining schema definitionFor determining the schema and procedures, OpenEdge JSDO catalog will be used. OpenEdgeJDSO catalog can be generated using PDSOE. Refer to the Generating a JSDO Catalog on page32Generating JSDO Catalog section.


Chapter 2: Enabling OE Application for data access

Pseudo-syntax of JSDO catalog for (JSON file)

{ Services: [{Name: ServiceNameaddressresources: [ // Resources

{ // Resourcename

pathschema [

{TypeablTypetitle

}]operations: [ // Operations{ // Operation

typeverbnamepathparams: [ // params{nametype

}] // params}] } ] } ]


Determining schema definition

ABL to SQL MappingThe mapping of supported OpenEdge ABL types and OpenAccess SQL types is listed below:

Default PrecisionSQL data typeABL data Type

1000000LONGVARBINARYBLOB

8000VARCHAR – whenMapCharToUnicode=0WVARCHAR – WhenMapCharToUnicode=1

Character

1000000LONGVARCHARCLOB

N/ADateDate

19TimeStampDateTime

8000VARCHARDateTime – TZ

127NumericDecimal

N/AIntegerInteger

N/ABigIntInt64

N/ABitLogical

32000VARBINARYRaw



Procedures/interfaces to be called for CRUDoperations on specific resource/business entity

OpenEdge ABL applications should be developed by exposing CRUD interfaces. The proceduresin the ABL applications for CRUD (Create, Read, Update and Delete) operations should confirmto the following procedure signatures. However the existing OpenEdge ABL applications can beallowed for data access by developing wrapper procedures on their existing procedures for CRUDoperations support. Execution of CRUD operations on OpenEdge business entities (ABL applicationfiles .p files) are performed using the java open client APIs on the OpenEdge Application Serverand the ABL applications executed on the Application Server with ‘SINGLE_RUN’ mode. All theCRUD operations are performed on AutoCommit-mode on the OpenEdge database. OpenEdgefor OpenAccess supports both TempTable and ProDataset. The ProDataSet definitions shouldinclude the TempTable definitions with BEFORE-TABLE attribute.

Note: If the OpenEdge business entities are developed with OO-ABL, then you should developABL wrappers (i.e, *.p files) on their existing ABL classes and expose the ABL wrappers as businessentities for CRUD operations.

Please refer to the ABL samples located in the /ip/oajava/oeabl/oasamples directory for anonymousand secure authentications.

The following table lists the JSDO catalog operation type to identify the CRUD operations that aresupported on the resource.

Table 1: JSDO and SQL Operation equivalents

Corresponding SQL operationJSDO Operation Type

“Create” is mapped to INSERT operation onspecific resource.

type : create

“Read” is mapped to SELECT operation onspecific resource.

type : read

“Update” is mapped to UPDATE operation onspecific resource

type : update

“Delete” is mapped to DELETE operation onspecific resource

type : delete


Procedures/interfaces to be called for CRUD operations on specific resource/business entity

Performing CRUD Operations on Business EntitiesThe following CRUD operations can be performed on the business entities.

• Create

• Read

• Update

• Delete

The following table lists the procedure name and its interface definition for the CRUD operationson TempTable.

Table 2: CRUD Operations and Procedure Definition for TempTable

Procedure definition for TempTableCRUD operation

PROCEDURE CreateRecords:

DEFINE INPUT-OUTPUT PARAMETER DATASET FOR tt.

Create or Insert

PROCEDURE ReadRecords:

DEFINE INPUT PARAMETER filterString AS CHARACTER. DEFINE OUTPUTPARAMETER DATASET FORtt.

Read or Select

PROCEDURE UpdateRecords:

DEFINE INPUT-OUTPUT PARAMETER DATASET FORtt.

Update

PROCEDURE DeleteRecords:

DEFINE INPUT-OUTPUT PARAMETER DATASET FORtt.

Delete



The following table lists each procedure name and its interface definition for the CRUD operationson ProDataSet.

Table 3: CRUD Operations and Procedure Definition for ProDataSet

Procedure definition for TempTableCRUD operation

PROCEDURE CreateRecords: DEFINEINPUT-OUTPUT PARAMETER DATASET FORdset.

Create or Insert

PROCEDURE ReadRecords: DEFINE INPUTPARAMETER filterString AS CHARACTER.DEFINE OUTPUT PARAMETER DATASETFOR dset.

Read or Select

PROCEDURE UpdateRecords: DEFINEINPUT-OUTPUT PARAMETER DATASET FORdset.

Update

PROCEDURE DeleteRecords: DEFINEINPUT-OUTPUT PARAMETER DATASET FORdset.

Delete

Understanding CRUD OperationsCRUD operations are explained in detail with syntax in this section.

Create

The Syntax for the Create operation is as follows:

If the Business entity is exposed as TempTable

PROCEDURE CreateRecords:DEFINE INPUT-OUTPUT PARAMETER TABLE FOR tt.

OpenAccess IP prepares TempTable tt (using the Java open client) and invokes CreateRecordsfor creating/inserting new records into a resource exposed as TempTable.

If the Business entity is exposed as ProDataSet

PROCEDURE CreateRecords:DEFINE INPUT-OUTPUT PARAMETER DATASET FOR dset.

OpenAccess IP prepares ProDataSet dset (using the Java open client) and invokes CreateRecordsfor creating/inserting new records into a resource exposed as ProDataSet.

Read

The syntax for the Read operation is as follows:


Understanding CRUD Operations

If the Business entity is exposed as a TempTable

PROCEDURE ReadRecords:DEFINE INPUT PARAMETER filterString AS CHARACTER.DEFINE OUTPUT PARAMETER TABLE FOR tt.

This procedure returns TempTable records. Before it returns the results, the procedure can alsofilter the records using the filterString parameter.

If the Business entity is exposed as ProDataSet

PROCEDURE ReadRecords:DEFINE INPUT PARAMETER filterString AS CHARACTER.DEFINE OUTPUT PARAMETER DATASET FOR dset.

This procedure returns ProDataSet records. Before returning the results the, the procedure canalso filter the records using filterString parameter.

Filter string input for ReadRecords

The filterString parameter is a CHARACTER variable.

For OpenEdge 11.X:

The Filter string is represented as a JSON object. The following approach is used for representingfilter string as a JSON object. Business Entity supports the following filterString as a JSON objectwith the following format:

{"ablFilter":"<filter conditions>"}.

ablFilter: The text of an ABL based WHERE clause used to filter records.

Note: The clause may not start with “WHERE”, as in an ablFilter, WHERE is implicit.

Examples:

(Str2 <> 'a' AND Str2 <> 'b' AND Str2 <> 'c')

(State = 'MA') OR (State = 'GA')

Note: Only the ablFilter tag is supported and skip, id, top and orderby tags are notsupported.

For OpenEdge 10.2B:

The filterString is in plain text with a condition to filter records, in the format <filter conditions. TheABL procedure that prefixes ‘WHERE’ to the filter string as shown in the following code snippet:

DEFINE VARIABLE pcWhere AS CHARACTER.

IF filter BEGINS "WHERE " THENpcWhere = filter.

ELSE IF filter NE "" THENpcWhere = "WHERE " + filter.

Note: Use the EnableJSONFilter=0 value in the DataSourceIPCustomProperties whenusing OpenEdge 10.2B

The output TempTable/ProDataSet contains the result rows that match the filter string.



Update

The syntax for the update operation is as follows:

If the Business entity is exposed as a TempTable

PROCEDURE UpdateRecords:DEFINE INPUT-OUTPUT PARAMETER TABLE FOR tt.

During the Update operation, the following steps are performed:

1. OpenAccess IP invokes the ReadRecords procedure (refer 2.2.2), by passing a filter conditionto get records that satisfy the filter condition. (Filter condition on update SQL operation)

2. Interface Provider prepares TempTable with updated records and invokes the UpdateRecordsprocedure.

If the Business entity is exposed as a ProDataSet

PROCEDURE UpdateRecords:DEFINE INPUT-OUTPUT PARAMETER DATASET FOR dset.

OpenAccess IP uses the ABL before-image mechanism to perform the Update operation onProDataSet. Refer to OpenEdge documentation for before-image attribute.

Note: OpenAccess IP uses ABL before-image mechanism to perform update operation onProDataSet. Please refer OpenEdge documentation for before-image attribute.

To perform and Update operation, the OpenAccess IP executes the following steps:

1. OpenAccess IP(Interface Provider) invokes the ReadRecords procedure by passing a filtercondition and retrieving records that satisfy the filter condition.

2. The IP then prepares a dataset with updated records and invokes the UpdateRecords procedure.

Delete

If the Business entity is exposed as a TempTable:

PROCEDURE DeleteRecords:DEFINE INPUT-OUTPUT PARAMETER TABLE FOR tt.

To perform a Delete operation, the OpenAccess Interface Provider executes the following steps:

1. OpenAccess IP invokes ReadRecords procedure, by passing a filter condition and gettingrecords that satisfy the filter condition. (Filter condition on update SQL operation)

2. The IP then prepares TempTable with deleted records.and invokes DeleteRecords procedure.

If the Business entity is exposed as a ProDataSet:

PROCEDURE DeleteRecords:DEFINE INPUT-OUTPUT PARAMETER DATASET FOR dset.

OpenAccess IP uses the ABL before-image mechanism to perform the Delete operation onProDataSet. Refer to Progress OpenEdge documentation for information about the before-imageattribute.

Note: If the exposed ProDataSet doesn’t have a before-image attribute set in the schema,OpenAccess IP doesn’t allow Update and Delete operations on the resource/ProDataSet.

To perform a Delete operation, the OpenAccess Interface Provider executes the following steps:


Understanding CRUD Operations

1. OpenAccess IP invokes the ReadRecords procedure by passing a filter condition and getrecords that satisfies the filter condition. (Filter condition on update SQL operation.)

2. The Interface Provider prepares a dataset with Delete records and invokes the DeleteRecordsprocedure.

Performing Secure CRUD OperationsFor performing Secure CRUD operations, OpenEdge users should modify their business entitiesand modify the OpenEdge Application Service settings.

Procedures for Handling ConnectionsFor ABL applications that use Secure Connections, the following additional security interfacesmust be implemented. Refer to Interface Implementation in the sample file,oasamples/oe11/security_cfg/si/oa/connect.p.

Table 4: Operations and Procedure Definition

Procedure DefinitionOperation

PROCEDURE ConnectSession:

DEFINE INPUT PARAMETER p_cUserID AS CHARACTER INITIAL "" NO-UNDO.

DEFINE INPUT PARAMETER p_cUserPwd AS CHARACTER INITIAL "" NO-UNDO.

Connection

PROCEDURE DisconnectSession:Disconnection

The ConnectSession and DisconnectSession procedures are explained in this section:

ConnectSession

The ConnectSession procedure generates the client-principal using the arguments, User-id andpassword. The ConnectSession procedure is invoked during the ODBC/JDBC client connectionto the OpenEdge Application Server. The connection is successful only when client-principalgeneration is successful. The client-principal is used for the entire session.

DisconnectSession

The DisconnectSession procedure is invoked during the ODBC/JDBC client disconnection. Thissecure connection handling procedure (oasamples/oe11/security_cfg/si/oa/connect.p) must bespecified as ‘SecConnProc’ OpenAccess Server DataSource custom-property. Refer to the tablein the DataSourceIPCustomProperties section for more information.



Security configurations for OpenEdge Application Server:Secure CRUD operations require additional configurations on the OpenEdge Application Server.Users must specify the startup procedure, that is, the srvrStartupProc property. the following is asample entry for setting the srvrStartupProc property in the AppServer properties file(ubroker.properties).

srvrStartupProc=oasamples/oe11/security_cfg/handlers/startup.p

A Startup procedure executes as an AppServer agent starts up.You can specify the name of anAppServer Startup procedure using OpenEdge Explorer or Progress Explorer or by setting thesrvrStartupProc property in the AppServer properties file (ubroker.properties).

The sample security definitions file securitytokensvc.i installed in theoasamples/oe11/security_cfg/include folder refer to the database name as sports2000.You shouldchange this to use to your database name in the following line:

&GLOBAL-DEFINE secdbname <yourdatabase>.

Security Validation in CRUD operations on businessentities:

Each CRUD operation procedure implementation should validate the client-principal value for theexecution of the operation. It is recommended to validate the client-principal generated during theConnectSession.

For example, a sample secure ReadRecords procedure for the resource “department_pd” is asfollows:

PROCEDURE ReadRecords :DEFINE INPUT PARAMETER filter AS CHARACTER.DEFINE OUTPUT PARAMETER DATASET FOR dsDepartment.

DEFINE VARIABLE cReadQuery AS CHARACTER NO-UNDO.DEFINE VARIABLE hQuery AS HANDLE NO-UNDO.

_init().

IF (NOT _setUser(INPUT g_cUserToken)) THENRETURN ERROR g_cLastError.

DO TRANSACTION

STOP-AFTER g_iMaxReadTimeON STOP UNDO, RETURN ERROR "read operation timed out"ON ERROR UNDO, RETURN ERROR "internal read error: " +

error-status:get-message(1) :

/* TODO: Do the record read options here... */

RUN applyFillMethod (INPUT filter).END.catch e as Progress.Lang.Error:

RETURN ERROR e:getMessage(1).end catch.

END PROCEDURE.


Performing Secure CRUD Operations

Sample files are located in oasamples/oe11/secure/department_pd.p

The internal function _setUser returns YES/TRUE if the session is allowed to execute the CRUDoperation and NO/FALSE if the session is not allowed to execute the CRUD operation.

Generating a JSDO CatalogUse one of the following methods to generate a JSDO Catalog.

Generating JSDO Catalog using OpenEdge DevelopmentStudio

For detailed steps on how to generate JSDO Catalog using OpenEdge Development Studio, referto Progress OpenEdge: OpenEdge Mobile Mobile Applications.

Generating JSDO Catalog ManuallyYou can also generate the OpenEdge JSDO catalog files manually without using the OpenEdgeDeveloper Studio.

Note: For a quick start, you can use the sample .json files that are available in the oesamplesfolder.



3Configuring OpenEdge and OpenAccess

To access Business Entities on the Application Server, you must configure both OpenEdge andOpenAccess. The following sections describe the configuration steps:


• Configuring OpenEdge

• Configuring OpenAccess

Configuring OpenEdge

Note: Users familiar with OpenEdge Application Server may ignore this section.

To configure OpenEdge for access to Business Entities:

1. Click Start > All Programs > Progress > OpenEdge > proenv.

2. In the proenv command prompt, enter prodb <target-db> sports2000

Example: prodb sports2000 sports2000

3. Enter proserve <db-name> -S <port#> to start the Progress Database

4. Enter proadsv –start to start the Admin server

Note: Use the commands proadsv –stop to stop and proadsv –q to query the Admin Server.If you see an error message about the port already being in use, restart the Admin server.


5. In C:/Progress/OpenEdge/properties, edit the ubroker.properties file to add the followingafter the Default Rest AppServer section:

## Default OE AppServer#[UBroker.AS.oebroker]appserviceNameList=oebrokerbrokerLogFile=@{WorkPath}\oebroker.broker.logcontrollingNameServer=NS1defaultService=0description=A sample AppServer for Session-free OpenAccess servicesenvironment=oebrokeroperatingMode=State-freepassword=portNumber= <free port>srvrLogFile=@{WorkPath}\oebroker.server.loguserName=srvrStartupParam=-db <your-db-name> -H <db-server-machine name/address>-S<port-number>

6. Add {srvrStartupParam=-db sports2000 -H localhost -S 15000}at the end ofthe “UBroker.AS. oebroker” section.

7. In the proenv command prompt, enter {asbman –i <broker-name> -start} to start theAppServer.

Note: Use the commands asbman –i <broker-name> –stop to stop the ApplicationServer and asbman –i <broker-name> –q to query the Application Server. For example:asbman –i oebroker –start where oebroker is the name of the Application Server.

Configuring OpenAccessThe OpenAccess ServerDataSource for OpenEdge must be configured with the following settings.

ServerDataSource settingsThe ServerDataSource settings are listed below with details for each setting:

DataSourceIPProperties

ABL_CATALOG_PATH=<location of *.json files>

Specify the location of .json files, for example:

ABL_CATALOG_PATH=C:/Program Files/Progress/DataDirect/oaserver72/ip/schema/oeabl

DataSourceIPType

• DAMIP

DataSourceIPClass

• oajava/oeabl/damip

DataSourceIPCustomProperties


Chapter 3: Configuring OpenEdge and OpenAccess

The connection information must be specified in the DataSourceIPCustomProperties value andthe connection details must be specified using PropertyName and value . Each value is separatedfrom the others using a semi-colon(;) as shown in the following example:

DataSourceIPCustomProperties:AppServerURL=<AppSrvURL>;AppServerInfo=<AppSrvInfo>;SessionModel=<SessionFree/SessionManaged>;MapCharToUniCode=<0/1>;EnableJSONFilter=<1/0>;CharPrecision=<8000>;SecConnProc=<Sec_Conn_Proc.p>;


Configuring OpenAccess

The following table lists each PropertyName with its description:

Mandatory/ OptionalValue and DescriptionPropertyName

MandatoryThe OpenEdge ApplicationServer URL Refer to theProgress OpenEdgedocumentation for details aboutthe Application Server URLstring.

AppServerURL

OptionalApp server procedure to beexecuted during the connection.

AppServerInfo

MandatoryApplication Server session:=SessionFree (default)=SessionManaged Refer to theProgress OpenEdgedocumentation for details aboutApplication Server Sessionmodels.

SessionModel

Optional=0 (default) Maps ABLcharacter fields to SQL ASCIIcharacter fields. =1 Maps ABLcharacter fields to Unicodecharacter fields

MapCharToUniCode

Optional=1(default) Set this to ‘1’ togenerate a filter string accordingto the OpenEdge 11.X format.=0 Set this to ‘0’ to generate afilter string according to theOpenEdge 10.2B format.

EnableJSONFilter

OptionalIf this PropertyName is notspecified, then the precisionvalue 8000 is used.

CharPrecision

Optional for Anonymous login

Mandatory for secure login

The security authenticationprocedure to be executedduring connection to the AppServer. This securityauthentication should beimplemented.

SecConnProc

OpenEdge Application Server Connection ScenariosThe following examples will help you understand the different scenarios in which you can connectto the OpenEdge Application Server.



Example 1: oebroker running on localhost with default NameServer port# 5162

DataSourceIPCustomProperties:AppServerURL=AppServer://localhost/oebroker;SessionModel=SessionFree;MapCharToUniCode=0;EnableJSONFilter=1;

This connects to the oebroker running on the local host, where the oebroker is session-freeappserver.

Example 2: With database security authentication

DataSourceIPCustomProperties:AppServerURL=AppServer://myhost:2290/oebroker;SessionModel=SessionFree;MapCharToUniCode=1; EnableJSONFilter=1;SecConnProc=si/oa/connect.p;

This connects to the AppServer oebroker on myhost, port#2290, where the oebroker is asession-free appserver. The database security authentication procedure is connect.p, which isdeployed on the appserver at si/oa/connect.p related to the PROPATH. Here all the ABL characterfields are mapped to UniCode character fields.

Example 3: oebroker running on myhost with NameServer port# 6000

DataSourceIPCustomProperties:AppServerURL=AppServer://myhost:6000/oebroker;AppServerInfo="";SessionModel=SessionFree;MapCharToUniCode=0; EnableJSONFilter=1;

This connects to the oebroker running on the myhost, where the oebroker is a session-freeappserver.

Example 4: When the oebroker is running on myhost with port#3090, i.e with DirectConnect)

DataSourceIPCustomProperties:AppServerURL=AppServerDC://myhost:3090;AppServerInfo="";SessionModel=SessionManaged;MapCharToUniCode=1;EnableJSONFilter=1;

This will connect to the oebroker running on port 3090 on the myhost , where the oebroker issession-managed appserver. Here the ABL character fields are mapped to UniCode characterfields.

Example 5: When the oebroker is running on myhost, with AppServerInfo as “testApp.p)

DataSourceIPCustomProperties:AppServerURL=AppServerDC://myhost:3090;AppServerInfo="TestApp.p";SessionModel=SessionManaged;MapCharToUniCode=1;EnableJSONFilter=1;

This connects to the oebroker running on port 3090 on the myhost , where the oebroker is asession-managed appserver. Here the ABL character fields are mapped to UniCode characterfields.

Example 6: oebroker running on myhost with port#3090, (with DirectConnect and oebroker runningon OpenEdge 10.2B)

DataSourceIPCustomProperties:AppServerURL=AppServerDC://myhost:3090;AppServerInfo="";SessionModel= SessionManaged;MapCharToUniCode=1; EnableJSONFilter=0;

This connects to the oebroker running on port 3090 on the myhost , where the oebroker is asession-managed appserver. Here the ABL character fields are mapped to UniCode characterfields.

DataSourceLogonMethodSecure Login


Configuring OpenAccess

This configuration model should be used when the user has to pass user name and passworddetails to the OpenEdge Application Server layer. The DataSourceLogonMethod attribute shouldbe set as DBMSLogon(User ID and Password) and the SecConnProc Property should be specifiedfor the DataSourceIPCustomProperties attribute.

For more information,refer to the newly created ‘OA_OpenEdgeAppServerSecure’ data source'ssettings from figure

For more information, refer to OA_OpenEdgeApplication ServerSecure Settings

Anonymous Login

This configuration model should be used when the OpenEdge Application Server Service isconfigured to accept anonymous logins. The DataSourceLogonMethod attribute should be set toAnonymous. For more information, refer to the newly created ‘OA_OpenEdgeAppServerSecure’data source's settings from figure.



4Troubleshooting

.


• Connection Exceptions

• Query Execution Exceptions


Connection Exceptions

• If OpenEdge Application Server is not available/running,

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenAccess SDK SQLEngine][AppServer]Connect Failure: Application Service oebroker Unknown atNameServer at Host localhost Port 5162. (8234)

• When an invalid value is specified for SessionModel property,

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenAccess SDK SQLEngine]Invalid value specified for SessionModel: 1

• When an invalid user-id/password is used

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenAccess SDK SQLEngine][AppServer]exception: connect session - error: authenticationfailure,ERROR condition: The Server application has returned an error. (7243)(7211)

• When an invalid value is specified for EnableJSONFilter property,

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenAccess SDK SQLEngine]Invalid value specified for EnableJSONFilter: 5

• When and invalid value is specified for MapCharToUniCode property,

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenAccess SDK SQLEngine]Invalid value specified for MapCharToUniCode: 4

• When a wrong value is specified for DataSourceIPProperties property as XYZ123,

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenAccess SDK SQLEngine]Invalid ABL_CATALOG_PATHXYZ123


Chapter 4: Troubleshooting

Query Execution Exceptions

• On using an unsupported operation on a resource, for example, INSERT on customer_t resource

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenAccess SDK SQLEngine]Functionality is not supported.

• If an operation/entry point is not implemented in the ABL procedure

Error Message = [DataDirect][ODBC OpenAccess SDKdriver][OpenEdge][AppServer]ERROR condition: Procedureoasamples\oe11\anonymous\all_types_long_pd.p has no entry point forUpdateReadRecords. (6456) (7211)

• When a non-existing Table is used

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenAccess SDK SQLEngine]Base table:employee_t not found.

• When updating a CLOB/BLOB/RAW field

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenAccess SDKSQLEngine]Update operation not supported on CLOB/BLOB/RAW field.

• When a large value is provided for integer field, for example, where intfield = 215123456676767,

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenEdge]UnexpectedError. dam_describeCondEx() failed: Error getting the condition details(leftpart)

• When an invalid value is provided for a field, for example, where datefield > '1233490',

Error Message = [DataDirect][ODBC OpenAccess SDK driver][OpenEdge]Errorgetting the literal value of right operand.


Query Execution Exceptions


Chapter 4: Troubleshooting

AAppendix

.


• Catalog Definition

• Sample Business Entity ABL Procedures

Catalog DefinitionFor information on Catalog definition, refer to the OpenEdge Development: Mobile Applications.

Sample Business Entity ABL ProceduresThe following table lists sample Business Entities (Resources) that are installed:


Business Entities:

RemarksOperationsSecure(Onlyfor 11.X) 1

OE 11.XOE10.2B

ResourceType

Resource Name

Only Readoperation onCustomerTable

ReadYYYTemp TableCustomer_t

Only Readoperation onCustomerTable

ReadYYYProDataSetCustomer_pd

All CRUDOperations

CRUDYYYTemp TableEmployee_t

All CRUDOperations

CRUDYYYProDataSetEmployee_pd

All CRUDOperations

CRUDYYYTemp TableDepartment_t

All CRUDOperations

CRUDYYYProDataSetDepartment_pd

BusinessEntity withall basicfield types.

CRUDYTemp TableAll_types_t

You mustcreate therequiredtable usingthe stepsdescribed inthe CreatingTest Tablesin theOpenEdgeDatabaseon page 45section

1 All samples in the oasamples/oe11/secure folder refer to the database, sports2000.To use your database, edit the following line in thePreprocessor Definitions section:&GLOBAL-DEFINE oaDBName <yourdatabase>


Appendix A: Appendix

RemarksOperationsSecure(Onlyfor 11.X) 1

OE 11.XOE10.2B

ResourceType

Resource Name

BusinessEntity withall basicfield types.You mustcreate therequiredtable usingthe stepsdescribed inthe CreatingTest Tablesin theOpenEdgeDatabaseon page 45section

CRUDYProDataSetAll_types_pd

BusinessEntity withall long fieldtypes

CUDYTemp TableAll_types_long_t

BusinessEntity withall long fieldtypes

CUDYProDataSetAll_types_long_pd

Creating Test Tables in the OpenEdge DatabaseThis section describes how to create test tables with sample data used by ALL_TYPES andALL_TYPES_LONG business entities. To create test tables in the OpenEdge database:

1. Using OpenEdge procedure editor, connect to the OpenEdge database.

2. Go to Tools > Data Administration > Admin > Load Data and Definitions > DataDefinitions(.df file) > .df file to load the table definition file (.df) from data administration tool.The table is created.

3. Load the records in to the table (.d) using the data administration tool

• Tools > Data Administration > Admin > Load Data and Definitions > Table contents(.d file) – and select the .d file

• After loading the file, the records are inserted in to the table.

The ‘All_types’ table is now loaded with 10 records and ‘All_types_long’ table is now loaded with5 records.

For more information, refer to Progress OpenEdge Data Management: Database Administration.

1 All samples in the oasamples/oe11/secure folder refer to the database, sports2000.To use your database, edit the following line in the

Preprocessor Definitions section:&GLOBAL-DEFINE oaDBName <yourdatabase>


Sample Business Entity ABL Procedures


Appendix A: Appendix

progress datadirect: ® openaccess for openedge · pdf fileprogress datadirect : openaccess...

Documents