Progress DataDirect: OpenAccess for OpenEdge Application Server

Transcription

1 Progress DataDirect: OpenAccess for OpenEdge Application Server

2

3 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 reserved by Progress Software Corporation. The information in these materials is subject to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear therein. The references in these materials to specific platforms supported are subject to change. Business Making Progress, Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirect XML Converters, DataDirect XQuery, Fathom, Making Software Work Together, OpenEdge, Powered by Progress, Progress, Progress Control Tower, Progress OpenEdge, Progress RPM, Progress Software Business Making Progress, Progress Software Developers Network, Rollbase, RulesCloud, RulesWorld, SequeLink, SpeedScript, Stylus Studio, and WebSpeed are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, AppsAlive, AppServer, BusinessEdge, Progress Easyl, DataDirect Spy, DataDirect SupportLink, Easyl, Future Proof, High Performance 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 Makes Progress are trademarks or service marks of Progress Software Corporation and/or its subsidiaries 3

4 Notices or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any other marks contained herein may be trademarks of their respective owners. June 2014 Last updated with new content: Release

5 Table of Contents Preface...7 Purpose...7 Audience...8 Using this manual...8 Typographical conventions...8 Chapter 1: Installing OpenAccess for OpenEdge Application Server...11 Pre-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...21 Overview...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

6 Configuring OpenEdge...33 Configuring OpenAccess...34 ServerDataSource settings...34 OpenEdge Application Server Connection Scenarios...36 DataSourceLogonMethod...37 Chapter 4: Troubleshooting...39 Connection Exceptions...40 Query Execution Exceptions...41 Appendix A: Appendix...43 Catalog Definition...43 Sample Business Entity ABL Procedures...43 Creating Test Tables in the OpenEdge Database

7 Preface For details, see the following topics: Purpose Audience Using this manual Typographical conventions Purpose Progress DataDirect OpenAccess for Progress OpenEdge Application Server (OpenAccess for OpenEdge Application Server) enables you to access, using SQL, Business Entities deployed in OpenEdge 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 defined in ABL procedures (.p files) that expose results as TempTable or ProDataSet. The schema for business entities is defined in the JSDO catalog, which can be generated using Progress Developer Studio for OpenEdge or the schema can be configured manually. Having the drivers for Business Entities enables efficient and standard integration with third-party tools, such as development software, reporting tools, data warehousing tools, Extract-Transform-Load (ETL) tools, and Online Analytical Processing (OLAP) tools. 7

8 Preface Audience This guide is intended for OpenEdge developers who want to enable ODBC/JDBC connectivity for the data in their OpenEdge business application developed in OpenEdge Advanced Business Language (ABL). Users of this guide are expected to be familiar with OpenEdge ABL and OpenEdge Application Server. Using this manual Using this manual, OpenEdge developers can enable SQL access to their business entities implemented in ABL procedures. Enabling SQL access to business entities requires the procedure for Create/Read/Update/Delete (CRUD) operations to be implemented using the prescribed interface definition. Minimal code changes in ABL and minimal configuration of OpenAccess Service enable SQL access to business entities. OpenAccess Interface Provider does not require any coding. Typographical conventions This manual uses the following typographical and syntax conventions: Convention Description Bold Italic SMALL, BOLD CAPITAL LETTERS KEY1+KEY2 KEY1 KEY2 Bold typeface indicates commands or characters the user types, provides emphasis, or the names of user interface elements. Italic typeface indicates the title of a document, or signifies new terms. Small, bold capital letters indicate OpenEdge key functions and generic keyboard keys; for example, GET and CTRL. A plus sign between key names indicates a simultaneous key sequence: you press and hold down the first key while pressing the second key. For example, CTRL+X. A space between key names indicates a sequential key sequence: you press and release the first key, then press another key. For example, ESCAPE H. Syntax: Fixed width Fixed-width italics A fixed-width font is used in syntax, code examples, system output, and file names. Fixed-width italics indicate variables in syntax. 8

9 Preface Convention Fixed-width bold UPPERCASE fixed width Period (.) or colon (:) [ ] [ ] { } { }... Description Fixed-width bold italic indicates variables in syntax with special emphasis. ABL keywords in syntax and code examples are almost always shown in upper case. Although shown in uppercase, you can type ABL keywords in either uppercase or lowercase in a procedure or class. All statements except DO, FOR, FUNCTION, PROCEDURE, and REPEAT end with a period. DO, FOR, FUNCTION, PROCEDURE, and REPEAT statements can end with either a period or a 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 are used to simplify complex syntax diagrams. Small braces are part of ABL. For example, a called external procedure must use braces when referencing arguments passed by a calling procedure. A vertical bar indicates a choice. Ellipses indicate repetition: you can choose one or more of the preceding items. 9

10 Preface 10

11 1 Installing OpenAccess for OpenEdge Application Server. For details, see the following topics: 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 requirements You should have the OpenEdge and OpenAccess products installed. OpenAccess for OpenEdge Application server supports the following application versions: 11

12 Chapter 1: Installing OpenAccess for OpenEdge Application Server OpenEdge: 10.2B 11.2.x 11.3.x OpenAccess: 7.2. Java: or higher Product Installation The following products should be installed in order to use the OpenAccess for OpenEdge Application Server: OpenEdge OpenAccess OpenAccess for OpenEdge Application Server The following sections provide instructions on how to install these products. OpenEdge Installation Download and install a supported version (10.2b/11.2.X/11.3.X) of OpenEdge(if not installed already). Refer to the Progress OpenEdge Getting Started: Installation and Configuration guide for instructions and further information. OpenAccess Installation Download and install Progress OpenAccess 7.2 (OpenAccess Server and OpenAccess Client, ODBC /JDBC). Refer to the Progress DataDirect: OpenAccess SDK installation guide for instructions and further information. Installing OpenAccess for OpenEdge Application Server To install OpenAccess for OpenEdge Application Server 1. Download the oa_ip_oe_appserver_7_2_0.jar from the Progress Download Center and copy to the OpenAccess Installation location (which is usually C:/Program Files/Progress/DataDirect/oaserver72 for Windows) 2. Open the command prompt and extract the oa_ip_oe_appserver_7_2_0.jar file using the command jar -xvf oa_ip_oe_appserver_7_2_0.jar. This creates the following directories and files. 12

13 Product Installation Directory ip/oajava/oeabl ip/oajava/oeabl ip/oajava/oeabl/lib ip/oajava/oeabl/oasamples ip/oajava/oeabl/tools damip.jar notices.txt Files/Directory messages.jar o4glrt.jar progress.jar tools.jar oe102b oe11 Service_setup Description The OpenAccess IP for OpenEdge Application Server java library file. Third-party vendor license agreements OpenEdge Java Open Client library files and Third Party Libraries Sample ABL procedure files for OpenEdge 10.2B and OpenEdge Details of the ABL Samples can be found in the Appendix. The oasamples folder should be copied to the OpenEdge working directory on the Application Server (example: C:/OpenEdge/WRK ). The directory contains separate samples for Anonymous Login mode and Secure Login mode. security_cfg: directory contains the samples for implementing the Application Server security mechanism using client-principal Scripts to create and remove OpenAccess Service for OpenEdge Application Server: oacreate_oeservice.[bat/sh] script files to create service oacreate_oeservice.[bat/sh] script files to create service ip/oajava/oeabl/tools Test_client Test the application to verify the connection to OpenEdge Application Server. ip/schema/oeabl oe102b oe11 Schema definition JSDO catalog files for OpenEdge 10.2B and OpenEdge Copy the oasamples folder from ip/oajava/oeabl to the OpenEdge Application Server Workspace(example: C:/OpenEdge/WRK ). 13

14 Chapter 1: Installing OpenAccess for OpenEdge Application Server OpenAccess Service setup for OpenEdge Application Server OpenAccess Interface Provider connects to the OpenEdge Application Server using the AppServerURL 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 the installation 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 corresponding operating system: Windows (oacreate_oaservice.bat): USERNAME: Specify the OpenAccess Administrative user account, generally <windows-domain>/<user-name>. This can be empty if OpenAccess Agent ServiceAdminAuthMethods is set to integrated_nt OEVersion: Specify the OpenEdge version, oe11 for OpenEdge 11.x and oe102b for OpenEdge 10.2B. AppServerURL: The OpenEdge application server's URL SessionModel: Specify the application service's model - the valid options are SessionFree or SessionManaged 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 Application Server 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 OpenEdge 10.2B. AppServerURL: The OpenEdge application server's url, SessionModel: Specify the application service's model - the valid options are SessionFree or SessionManaged 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 14

15 Testing the connection to OpenEdge Application Server: 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 Application Server: Before testing the connection, ensure that the OpenEdge Database and the Application Server are running. Refer to Configuring OpenEdge on page 33 section for details. The installed samples are 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 OpenEdge Application Server URL as: test_connection.bat <OpenEdge Application Server URL> 15

16 Chapter 1: Installing OpenAccess for OpenEdge Application Server For example: test_connection.bat AppServerDC://localhost:3090/oebroker Starting the OpenAccess Service for OpenEdge Application Server The following section contains the instructions to start the OpenAccess service for OpenEdge Application Server. On Windows To 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 message appears. Note: Use net stop OpenAccess720_OEAppServer to stop the server. Alternatively, open the OpenAccess SDK Management Console > Manager > Connected to OpenAccessSDK720_Agent > Services, right-click and select Start OpenAccess720_OEAppServer On UNIX Please follow the below steps to start OpenAccess Service on UNIX 1. Execute the script {oa-server-install-dir}/admin/oacla.sh. The oacla prompt opens. 2. At the oacla prompt, type alc to activate local configuration. 3. Enter sl to list the services. The following services are listed: Name Host Status Description OpenAccessSDK720_Agent oesoldev1 active Agent service OpenAccessSDK720_C oesoldev1 inactive Service for C/C++ OpenAccessSDK720_C_SQL oesoldev1 inactive Service for C/C++ OpenAccessSDK720_Java oesoldev1 inactive Service for Java OpenAccessSDK720_Java_SQL oesoldev1 inactive Service for Java OpenAccess720_OEAppServer oesoldev1 inactive Service for Java 16

17 Starting the OpenAccess Service for OpenEdge Application Server 4. Enter ss OpenAccess720_OEAppServer and press Enter to start the OpenAccess720_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 SDK Installation Guide for more information. Use the Interactive SQL for OpenAccess ODBC tool to execute queries against the server data source. The following sample session for Windows shows how 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; Then click Finish. The DataDirect OpenAccess SDK ODBC Driver Setup window appears. On the DataDirect OpenAccess SDK ODBC Driver Setup window, enter appropriate values for 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, 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, check whether the service is running and that you have entered correct values for the field mentioned above. Click Apply and then click OK twice. You can also create another DSN OpenEdgeABLSecure using similar steps to connect to service data source OA_OpenEdgeAppServerSecure. 1. Query using ODBCISQL tool 17

18 Chapter 1: Installing OpenAccess for OpenEdge Application Server On the command prompt, at location [oa-odbc-install-dir]:/program Files/Progress/DataDirect/oaodbc72 execute the following command: odbcisql.exe. For example, C: /Program Files/Progress/DataDirect/oaodbc72/odbcisql.exe. At the Interactive SQL prompt, type CONNECT OpenEdgeABL for anonymous CONNECT for secure connection Note: Ensure that the Server Data Source OA_OpenEdgeAppServerSecure is configured for 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 data source. Refer to the OpenAccess SDK Administrator s Guide for detailed information on using the Interactive 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 window opens 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 connection window. 18

19 Restrictions and Limitations. Restrictions and Limitations Progress 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. 19

20 Chapter 1: Installing OpenAccess for OpenEdge Application Server 20

21 2 Enabling OE Application for data access For details, see the following topics: 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 21

22 Chapter 2: Enabling OE Application for data access Overview The following architecture diagram shows the interface between OpenEdge application server and OpenAccess. ODBC/JDBC clients interface with the OpenAccess server which in turn uses the Java 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 while using OpenAccess Java IP interface. Determining schema definition For determining the schema and procedures, OpenEdge JSDO catalog will be used. OpenEdge JDSO catalog can be generated using PDSOE. Refer to the Generating a JSDO Catalog on page 32Generating JSDO Catalog section. 22

23 Determining schema definition Pseudo-syntax of JSDO catalog for (JSON file) { Services: [{ Name: ServiceName address resources: [ // Resources { // Resource name path schema [ { Type abltype title } ] operations: [ // Operations { // Operation type verb name path params: [ // params { name type } ] // params } ] } ] } ] 23

24 Chapter 2: Enabling OE Application for data access ABL to SQL Mapping The mapping of supported OpenEdge ABL types and OpenAccess SQL types is listed below: ABL data Type SQL data type Default Precision BLOB Character CLOB Date DateTime DateTime TZ Decimal Integer Int64 Logical Raw LONGVARBINARY VARCHAR when MapCharToUnicode=0 WVARCHAR When MapCharToUnicode=1 LONGVARCHAR Date TimeStamp VARCHAR Numeric Integer BigInt Bit VARBINARY N/A N/A N/A N/A

25 Procedures/interfaces to be called for CRUD operations on specific resource/business entity Procedures/interfaces to be called for CRUD operations on specific resource/business entity OpenEdge ABL applications should be developed by exposing CRUD interfaces. The procedures in the ABL applications for CRUD (Create, Read, Update and Delete) operations should confirm to the following procedure signatures. However the existing OpenEdge ABL applications can be allowed for data access by developing wrapper procedures on their existing procedures for CRUD operations support. Execution of CRUD operations on OpenEdge business entities (ABL application files.p files) are performed using the java open client APIs on the OpenEdge Application Server and the ABL applications executed on the Application Server with SINGLE_RUN mode. All the CRUD operations are performed on AutoCommit-mode on the OpenEdge database. OpenEdge for OpenAccess supports both TempTable and ProDataset. The ProDataSet definitions should include the TempTable definitions with BEFORE-TABLE attribute. Note: If the OpenEdge business entities are developed with OO-ABL, then you should develop ABL wrappers (i.e, *.p files) on their existing ABL classes and expose the ABL wrappers as business entities for CRUD operations. Please refer to the ABL samples located in the /ip/oajava/oeabl/oasamples directory for anonymous and secure authentications. The following table lists the JSDO catalog operation type to identify the CRUD operations that are supported on the resource. Table 1: JSDO and SQL Operation equivalents JSDO Operation Type type : create type : read type : update type : delete Corresponding SQL operation Create is mapped to INSERT operation on specific resource. Read is mapped to SELECT operation on specific resource. Update is mapped to UPDATE operation on specific resource Delete is mapped to DELETE operation on specific resource 25

26 Chapter 2: Enabling OE Application for data access Performing CRUD Operations on Business Entities The 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 operations on TempTable. Table 2: CRUD Operations and Procedure Definition for TempTable CRUD operation Create or Insert Read or Select Update Delete PROCEDURE CreateRecords: Procedure definition for TempTable DEFINE INPUT-OUTPUT PARAMETER DATASET FOR tt. PROCEDURE ReadRecords: DEFINE INPUT PARAMETER filterstring AS CHARACTER. DEFINE OUTPUT PARAMETER DATASET FORtt. PROCEDURE UpdateRecords: DEFINE INPUT-OUTPUT PARAMETER DATASET FORtt. PROCEDURE DeleteRecords: DEFINE INPUT-OUTPUT PARAMETER DATASET FORtt. 26

27 Understanding CRUD Operations The following table lists each procedure name and its interface definition for the CRUD operations on ProDataSet. Table 3: CRUD Operations and Procedure Definition for ProDataSet CRUD operation Create or Insert Read or Select Update Delete Procedure definition for TempTable PROCEDURE CreateRecords: DEFINE INPUT-OUTPUT PARAMETER DATASET FOR dset. PROCEDURE ReadRecords: DEFINE INPUT PARAMETER filterstring AS CHARACTER. DEFINE OUTPUT PARAMETER DATASET FOR dset. PROCEDURE UpdateRecords: DEFINE INPUT-OUTPUT PARAMETER DATASET FOR dset. PROCEDURE DeleteRecords: DEFINE INPUT-OUTPUT PARAMETER DATASET FOR dset. Understanding CRUD Operations CRUD 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 CreateRecords for 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 CreateRecords for creating/inserting new records into a resource exposed as ProDataSet. Read The syntax for the Read operation is as follows: 27

28 Chapter 2: Enabling OE Application for data access 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 also filter 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 can also 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 representing filter string as a JSON object. Business Entity supports the following filterstring as a JSON object with 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 not supported. For OpenEdge 10.2B: The filterstring is in plain text with a condition to filter records, in the format <filter conditions. The ABL procedure that prefixes WHERE to the filter string as shown in the following code snippet: DEFINE VARIABLE pcwhere AS CHARACTER. IF filter BEGINS "WHERE " THEN pcwhere = filter. ELSE IF filter NE "" THEN pcwhere = "WHERE " + filter. Note: Use the EnableJSONFilter=0 value in the DataSourceIPCustomProperties when using OpenEdge 10.2B The output TempTable/ProDataSet contains the result rows that match the filter string. 28

29 Understanding CRUD Operations 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 condition to get records that satisfy the filter condition. (Filter condition on update SQL operation) 2. Interface Provider prepares TempTable with updated records and invokes the UpdateRecords procedure. 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 on ProDataSet. Refer to OpenEdge documentation for before-image attribute. Note: OpenAccess IP uses ABL before-image mechanism to perform update operation on ProDataSet. 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 filter condition 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 getting records 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 on ProDataSet. Refer to Progress OpenEdge documentation for information about the before-image attribute. 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: 29

30 Chapter 2: Enabling OE Application for data access 1. OpenAccess IP invokes the ReadRecords procedure by passing a filter condition and get records that satisfies the filter condition. (Filter condition on update SQL operation.) 2. The Interface Provider prepares a dataset with Delete records and invokes the DeleteRecords procedure. Performing Secure CRUD Operations For performing Secure CRUD operations, OpenEdge users should modify their business entities and modify the OpenEdge Application Service settings. Procedures for Handling Connections For ABL applications that use Secure Connections, the following additional security interfaces must be implemented. Refer to Interface Implementation in the sample file, oasamples/oe11/security_cfg/si/oa/connect.p. Table 4: Operations and Procedure Definition Operation Connection PROCEDURE ConnectSession: Procedure Definition DEFINE INPUT PARAMETER p_cuserid AS CHARACTER INITIAL "" NO-UNDO. DEFINE INPUT PARAMETER p_cuserpwd AS CHARACTER INITIAL "" NO-UNDO. Disconnection PROCEDURE DisconnectSession: The ConnectSession and DisconnectSession procedures are explained in this section: ConnectSession The ConnectSession procedure generates the client-principal using the arguments, User-id and password. The ConnectSession procedure is invoked during the ODBC/JDBC client connection to the OpenEdge Application Server. The connection is successful only when client-principal generation is successful. The client-principal is used for the entire session. DisconnectSession The DisconnectSession procedure is invoked during the ODBC/JDBC client disconnection. This secure connection handling procedure (oasamples/oe11/security_cfg/si/oa/connect.p) must be specified as SecConnProc OpenAccess Server DataSource custom-property. Refer to the table in the DataSourceIPCustomProperties section for more information. 30

31 Performing Secure CRUD Operations 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 a sample 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 an AppServer Startup procedure using OpenEdge Explorer or Progress Explorer or by setting the srvrstartupproc property in the AppServer properties file (ubroker.properties). The sample security definitions file securitytokensvc.i installed in the oasamples/oe11/security_cfg/include folder refer to the database name as sports2000.you should change this to use to your database name in the following line: &GLOBAL-DEFINE secdbname <yourdatabase>. Security Validation in CRUD operations on business entities: Each CRUD operation procedure implementation should validate the client-principal value for the execution of the operation. It is recommended to validate the client-principal generated during the ConnectSession. For example, a sample secure ReadRecords procedure for the resource department_pd is as follows: 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)) THEN RETURN ERROR g_clasterror. DO TRANSACTION STOP-AFTER g_imaxreadtime ON 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. 31

32 Chapter 2: Enabling OE Application for data access 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 CRUD operation and NO/FALSE if the session is not allowed to execute the CRUD operation. Generating a JSDO Catalog Use one of the following methods to generate a JSDO Catalog. Generating JSDO Catalog using OpenEdge Development Studio For detailed steps on how to generate JSDO Catalog using OpenEdge Development Studio, refer to Progress OpenEdge: OpenEdge Mobile Mobile Applications. Generating JSDO Catalog Manually You can also generate the OpenEdge JSDO catalog files manually without using the OpenEdge Developer Studio. Note: For a quick start, you can use the sample.json files that are available in the oesamples folder. 32

33 3 Configuring OpenEdge and OpenAccess To access Business Entities on the Application Server, you must configure both OpenEdge and OpenAccess. The following sections describe the configuration steps: For details, see the following topics: 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 sports 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. 33

34 Chapter 3: Configuring OpenEdge and OpenAccess 5. In C:/Progress/OpenEdge/properties, edit the ubroker.properties file to add the following after the Default Rest AppServer section: # # Default OE AppServer # [UBroker.AS.oebroker] appservicenamelist=oebroker brokerlogfile=@{workpath}\oebroker.broker.log controllingnameserver=ns1 defaultservice=0 description=a sample AppServer for Session-free OpenAccess services environment=oebroker operatingmode=state-free password= portnumber= <free port> srvrlogfile=@{workpath}\oebroker.server.log username= 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 of the UBroker.AS. oebroker section. 7. In the proenv command prompt, enter {asbman i <broker-name> -start} to start the AppServer. Note: Use the commands asbman i <broker-name> stop to stop the Application Server 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 OpenAccess The OpenAccess ServerDataSource for OpenEdge must be configured with the following settings. ServerDataSource settings The 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 34

35 Configuring OpenAccess The connection information must be specified in the DataSourceIPCustomProperties value and the connection details must be specified using PropertyName and value. Each value is separated from 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>; 35

36 Chapter 3: Configuring OpenEdge and OpenAccess The following table lists each PropertyName with its description: PropertyName AppServerURL AppServerInfo SessionModel Value and Description The OpenEdge Application Server URL Refer to the Progress OpenEdge documentation for details about the Application Server URL string. App server procedure to be executed during the connection. Application Server session: =SessionFree (default) =SessionManaged Refer to the Progress OpenEdge documentation for details about Application Server Session models. Mandatory/ Optional Mandatory Optional Mandatory MapCharToUniCode EnableJSONFilter CharPrecision SecConnProc =0 (default) Maps ABL character fields to SQL ASCII character fields. =1 Maps ABL character fields to Unicode character fields =1(default) Set this to 1 to generate a filter string according to the OpenEdge 11.X format. =0 Set this to 0 to generate a filter string according to the OpenEdge 10.2B format. If this PropertyName is not specified, then the precision value 8000 is used. The security authentication procedure to be executed during connection to the App Server. This security authentication should be implemented. Optional Optional Optional Optional for Anonymous login Mandatory for secure login OpenEdge Application Server Connection Scenarios The following examples will help you understand the different scenarios in which you can connect to the OpenEdge Application Server. 36

37 Configuring OpenAccess 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-free appserver. 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 a session-free appserver. The database security authentication procedure is connect.p, which is deployed on the appserver at si/oa/connect.p related to the PROPATH. Here all the ABL character fields 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-free appserver. 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 is session-managed appserver. Here the ABL character fields are mapped to UniCode character fields. 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 a session-managed appserver. Here the ABL character fields are mapped to UniCode character fields. Example 6: oebroker running on myhost with port#3090, (with DirectConnect and oebroker running on 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 a session-managed appserver. Here the ABL character fields are mapped to UniCode character fields. DataSourceLogonMethod Secure Login 37

38 Chapter 3: Configuring OpenEdge and OpenAccess This configuration model should be used when the user has to pass user name and password details to the OpenEdge Application Server layer. The DataSourceLogonMethod attribute should be set as DBMSLogon(User ID and Password) and the SecConnProc Property should be specified for the DataSourceIPCustomProperties attribute. For more information,refer to the newly created OA_OpenEdgeAppServerSecure data source's settings 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 is configured to accept anonymous logins. The DataSourceLogonMethod attribute should be set to Anonymous. For more information, refer to the newly created OA_OpenEdgeAppServerSecure data source's settings from figure. 38

39 4 Troubleshooting. For details, see the following topics: Connection Exceptions Query Execution Exceptions 39

40 Chapter 4: Troubleshooting Connection Exceptions If OpenEdge Application Server is not available/running, Error Message = [DataDirect][ODBC OpenAccess SDK driver][openaccess SDK SQL Engine][AppServer]Connect Failure: Application Service oebroker Unknown at NameServer at Host localhost Port (8234) When an invalid value is specified for SessionModel property, Error Message = [DataDirect][ODBC OpenAccess SDK driver][openaccess SDK SQL Engine]Invalid value specified for SessionModel: 1 When an invalid user-id/password is used Error Message = [DataDirect][ODBC OpenAccess SDK driver][openaccess SDK SQL Engine][AppServer]exception: connect session - error: authentication failure,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 SQL Engine]Invalid value specified for EnableJSONFilter: 5 When and invalid value is specified for MapCharToUniCode property, Error Message = [DataDirect][ODBC OpenAccess SDK driver][openaccess SDK SQL Engine]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 SQL Engine]Invalid ABL_CATALOG_PATHXYZ123 40

41 Query Execution Exceptions 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 SQL Engine]Functionality is not supported. If an operation/entry point is not implemented in the ABL procedure Error Message = [DataDirect][ODBC OpenAccess SDK driver][openedge][appserver]error condition: Procedure oasamples\oe11\anonymous\all_types_long_pd.p has no entry point for UpdateReadRecords. (6456) (7211) When a non-existing Table is used Error Message = [DataDirect][ODBC OpenAccess SDK driver][openaccess SDK SQL Engine]Base table:employee_t not found. When updating a CLOB/BLOB/RAW field Error Message = [DataDirect][ODBC OpenAccess SDK driver][openaccess SDK SQLEngine]Update operation not supported on CLOB/BLOB/RAW field. When a large value is provided for integer field, for example, where intfield = , Error Message = [DataDirect][ODBC OpenAccess SDK driver][openedge]unexpected Error. dam_describecondex() failed: Error getting the condition details(left part) When an invalid value is provided for a field, for example, where datefield > ' ', Error Message = [DataDirect][ODBC OpenAccess SDK driver][openedge]error getting the literal value of right operand. 41

42 Chapter 4: Troubleshooting 42

43 A Appendix. For details, see the following topics: Catalog Definition Sample Business Entity ABL Procedures Catalog Definition For information on Catalog definition, refer to the OpenEdge Development: Mobile Applications. Sample Business Entity ABL Procedures The following table lists sample Business Entities (Resources) that are installed: 43

44 Appendix A: Appendix Business Entities: Resource Name Resource Type OE 10.2B OE 11.X Secure(Only for 11.X) 1 Operations Remarks Customer_t Temp Table Y Y Y Read Only Read operation on Customer Table Customer_pd ProDataSet Y Y Y Read Only Read operation on Customer Table Employee_t Temp Table Y Y Y CRUD All CRUD Operations Employee_pd ProDataSet Y Y Y CRUD All CRUD Operations Department_t Temp Table Y Y Y CRUD All CRUD Operations Department_pd ProDataSet Y Y Y CRUD All CRUD Operations All_types_t Temp Table Y CRUD Business Entity with all basic field types. You must create the required table using the steps described in the Creating Test Tables in the OpenEdge Database on page 45 section 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> 44

45 Sample Business Entity ABL Procedures Resource Name Resource Type OE 10.2B OE 11.X Secure(Only for 11.X) 1 Operations Remarks All_types_pd ProDataSet Y CRUD Business Entity with all basic field types. You must create the required table using the steps described in the Creating Test Tables in the OpenEdge Database on page 45 section All_types_long_t Temp Table Y CUD Business Entity with all long field types All_types_long_pd ProDataSet Y CUD Business Entity with all long field types Creating Test Tables in the OpenEdge Database This section describes how to create test tables with sample data used by ALL_TYPES and ALL_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 > Data Definitions(.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 with 5 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> 45

46 Appendix A: Appendix 46