 |
 |
||||||||
|
 |
||||||||
|
|
 |
New Features and Updates for APPX Router
Last Update: 11/17/01
9. Programming a Remote Encryption Database Transaction or Database DLL ======================================================================= - Database DLL Considerations - Remote Encryption Database Transaction Considerations A Remote Encryption Database Transaction or Database DLL is a wrapper around an encryption exit call from the APPX Router. Encryption exits are described in Section 1, "APPX Router v1.40 Enhancements", "Encryption Exits." When accessing an external encryption database source, the APPX Router places an ENCR_EXIT_BLOCK structure (from the encryption exit call from the driver) into an APPXROUTER_ENCRYPTION_EXIT_BLOCK (AEEB) structure, and passes that structure to the external database. In addition, there are non-encryption exit request defined in the AEEB block which are used to manage the link between the APPX Router and the external database source. Both remote encryption databases and database DLLs use the same AEEB block, but the mechanics of moving the data around are different. A database DLL, after being loaded, is simply called from the APPX Router, with a single parameter: a pointer to the AEEB block. The database DLL then proceeds to update fields in the block as appropriate. A remote database transaction is started by an APPX Connect from the Router, and begins with its own APPX Connect. The transaction then issues an APPX Receive to get the AEEB block from the APPX Router, updates it as appropriate, and then uses an APPX Send to return the updated block to the APPX Router. There are six functions that the APPX Router can request of the remote database source. These are described below: AREN_XREQ_VERSION ----------------- Return version information about remote database source. The following fields should be filled in: module_version, module_version_string, and module_support_level. The first two are informational, and are logged at the APPX Router. The module_support_level should be used to indicate what level of support the module provides. Currently only one level is defined, ENCRX_MODULE_LEVEL_1, which requires the support of all six functions documented here. In addition, the module may inspect the caller_support_level at any time (not just during this function) to check the support level of the APPX Router. This function should always return AREN_XRC_OK. AREN_XREQ_INIT -------------- Initialize module. This request will occur before any other requests, except AREN_XREQ_VERSION. The module should perform any initialization required. In the case of a database DLL, any required per-instance storage should be allocated, and a pointer to that storage returned in the "ws" field. The APPX Router will return the ws pointer on all subsequent calls. The parm1 and parm2 fields are passed by the APPX Router on this function. For a remote database transaction, these will be from the "Exit: Name" and "Exit: Data" fields in the Router configuration for the Encryption Database Source, and for a database DLL, these will be from the "DLL Parm 1" and "DLL Parm 2" fields. The parm1 and parm2 fields have no predefined meaning in the APPX Router, but are intended to supply parameters to the module. For example, a database DLL might use parm1 to specify the file it will access. If necessary, the module should save the contents of the parm1 and parm2 fields. This function may return AREN_XRC_OK or AREN_XRC_ERROR. AREN_XREQ_FREE -------------- Free/close module. The module should close and free all resources and prepare to be terminated. A remote database transaction should issue an APPX Disconnect after receiving this request and then terminate. A database DLL should clean up, and then return to the caller (the Router), at which point the DLL will be unloaded. This function should always return AREN_XRC_OK (database DLL only, a remote database transaction will not return in response to this request). AREN_XREQ_LOAD_DB ----------------- Load the associated encryption/security database. Any action required to load the database that will be access should be taken at this time. For example, a module that parses and loads a flat file database into memory would do so at this point. For some modules, this may not perform any function, for example, if the module is accessing a database file dynamically. After this call completes, the module must be ready to accept encryption exit (AREN_XREQ_ENCR_EXIT_REQUEST) requests. If the database is already loaded, the database must be reloaded, if such an action is possible/meaningful for the module. Reloads occur in response to the "Reload Encryption Databases" menu action in the Router Manager application. This would usually occur if the administrator updated the source data, and wanted to activate the new security data. +-----------------------------------------------------------------+ | Implementation note: contrary to the above documentation, | | current versions of the APPX Router do not pass "Reload" | | requests to remote database transactions. "Reload" requests | | are passed to database DLLs as documented. In all cases, the | | initial "Load" request is passed to the remote database | | transaction or database DLL. | +-----------------------------------------------------------------+ If a "load" (or "reload") action is performed successfully, the module should return AREN_XRC_OK. If a "load" (or "reload") action is performed, but some non-fatal errors are detected (for example, syntax errors in a database source file that cause some parts to be ignored), the module should return AREN_XRC_DB_LOADED_WITH_ERRORS. If a module does not perform any action during a AREN_XREQ_LOAD_DB request, it should return AREN_XRC_DB_DOES_NOT_USE_LOAD. The Router does not treat this as an error, rather the distinct return code is used so that statistics are kept correctly. Note: a module might do a "load" action initially, but not support a "reload." In that case it should return AREN_XRC_DB_DOES_NOT_USE_LOAD for the "reload" requests. This function may return AREN_XRC_OK, AREN_XRC_DB_LOADED_WITH_ERRORS, AREN_XRC_DB_DOES_NOT_USE_LOAD, or AREN_XRC_ERROR. AREN_XREQ_UNLOAD_DB ------------------- Unload or release a loaded database. This function is issued just before the AREN_XREQ_FREE, and provides the module with an opportunity to shut down and still return a message before the session is terminated. The APPX Router will not issue any AREN_XREQ_LOAD_DB requests after this function. This function may return AREN_XRC_OK or AREN_XRC_ERROR. AREN_XREQ_ENCR_EXIT_REQUEST --------------------------- Execute the ENCR_EXIT_BLOCK (encr_exit_block) request (see that control block). These are the actual database queries from the encryption support in the device driver. Encryption exits are described in Section 1, "APPX Router v1.40 Enhancements", "Encryption Exits." In general, if the module was able to perform the ENCR_EXIT_BLOCK function, even if that function did not succeed, it should return AREN_XRC_OK. An error during an encryption exit request should be reported as an ENCR_XRC_xxx result in the ENCR_EXIT_BLOCK, along with the AREN_XRC_OK result in the outer block. Only a gross, session level error (for example, the module is unable to call the handler for the "inner" request), should return AREN_XRC_ERROR. An external database will usually handle all encryption exit requests, except for ENCR_XREQ_GET_ID and ENCR_XREQ_GET_SHARED_SECRET, which only apply to the originating side of a session (these should return ENCR_XRC_ERROR). When handling a ENCR_XREQ_VALIDATE_SESSION or ENCR_XREQ_VALIDATE_SESSION_SPECIAL request, the module may supply additional data back to the APPX Router if the validate succeeds. Additional security classes may be returned. These security classes are added to the APPX Router security classes specified in the TCP/IP Listener "General" and "Addresses" tabs. The syntax requirements for the class names follow the same requirements as for the APPX Router (in v1.40, class names "A" through "Z" are allowed). The additional security classes are returned as an array ("sc") of 64 ASCIIZ strings with a maximum length of 16 bytes. The number of additional security classes must be specified in sc_count. Optional overrides of host connection parameters ("Host Connection Overrides") may be returned. These are overrides as described in Appendix D of the "APPX Router Implementation Guide and Reference." In addition to the overrides which may be specified at the client, additional overrides may be specified by the external database module. Overrides are applied in the following order: 1. Base definitions (lowest priority) 2. overrides2 from external database 3. overrides1 from external database 4. Overrides from client (Fmt-3) (highest priority) Overrides are returned as ASCIIZ strings in two fields, overrides1 and overrides2. Finally, the module may return 32 bytes of data that is passed unchanged to the APPX mainframe application in the exit_data field. While the APPX Router assigns no meaning to this data, it is intended to allow an external database module to pass a "cookie" or token to the application to allow the application to correlate its activity with that of the external database module. For AREN_XREQ_ENCR_EXIT_REQUEST requests, the APPX Router values the session_number field. This number corresponds to the session number assigned by the APPX Router. Note: this field cannot generally be used for tracking or grouping database queries for a single session, except under special circumstances. The following limitations apply: Session numbers are restarted at 1 whenever the APPX Router is restarted. For a remote database which has been configured to allow multiple worker threads, different database requests from the same session may be handled by different worker threads (and thus different instances of the remote database transaction). For any remote database, even with only a single active worker thread, the worker thread may be shut down and restarted during an APPX Router session, possibly causing different database requests from the same session to be handled by different instances/sessions of the remote database transaction. This field can be used to correlate activity in the external database module with logged events at the APPX Router. This function may return AREN_XRC_OK or AREN_XRC_ERROR. The following result codes may be returned (in the "result" field) from the external database module: AREN_XRC_OK ----------- Request processed successfully. AREN_XRC_DB_LOADED_WITH_ERRORS ------------------------------ Database was loaded or reloaded, but some errors occurred. AREN_XRC_DB_DOES_NOT_USE_LOAD ----------------------------- A database load or reload was requested, but this module does not use/support loads. AREN_XRC_ERROR -------------- An error occurred, a message must be returned in "msg". AREN_XRC_NOT_PROCESSED ---------------------- This return code must not be set by an external database module. It is reserved for internal management in the APPX Router. Database DLL Considerations --------------------------- A database DLL is loaded at APPX Router startup. It may be loaded more than once if more than one Encryption Database Source specifies the same DLL. The DLL should keep its local storage in an allocated area, and return a pointer ("ws") to that area for AREN_XREQ_INIT. The APPX Router will pass the pointer (in ws) on subsequent calls. The APPX Router loads the database DLL dynamically, and resolves its entry point via ordinal 101. The entry point should be defined as follows: int __stdcall database_dll_entry(pAPPXROUTER_ENCRYPTION_EXIT_BLOCK aeeb) (The routine name is not significant). The database DLL can be called from multiple threads, and must be compiled as a multithreaded ("-MT") module. A database DLL can internally force single threaded operation by setting up a mutex or critical section to allow only a single entry into the inner layers of code at a time, but even then the entry point will still be called from multiple threads. The structure of the main route would typically be along these lines: int __stdcall database_dll_entry(pAPPXROUTER_ENCRYPTION_EXIT_BLOCK aeeb) { switch (aeeb->request) { case AREN_XREQ_VERSION: ; return version data break; case AREN_XREQ_INIT: ; init module break; case AREN_XREQ_FREE: ; shutdown module break; case AREN_XREQ_LOAD_DB: ; load database break; case AREN_XREQ_UNLOAD_DB: ; unload database/prepare for shutdown break; case AREN_XREQ_ENCR_EXIT_REQUEST: ; execute encryption exit request break; default: ; invalid request, return error aeeb->result = AREN_XRC_ERROR; strcpy(aeeb->msg, "Invalid AEEB Request"); break; } return(aeeb->request); } The required header files, and a short sample database DLL are distributed with the APPX Router. The source files are installed in the \dbdll directory under the main APPX Router installation directory. Remote Encryption Database Transaction Considerations ----------------------------------------------------- Remote encryption database transactions are started dynamically by the Router when database requests are queued. More than one worker thread may be started, resulting in multiple instances of the remote database transaction. The Router caches running sessions, and will attempt to queue additional work onto already established sessions, but activate additional sessions if database requests spend too much time in the queue. The Router will shut sessions down if they are idle for the configured interval. The APPX Router establishes an APPX session with the remote data transaction, and sends requests via APPX Sends of an APPXROUTER_ENCRYPTION_EXIT_BLOCK (AEEB) structure, and expects results to be returned via an APPX send of the updated AEEB structure from the remote database transaction. The Router may send any pending database requests on any active remote database transaction session. This may include splitting sequential requests from a single client session across more than one instance of the remote database transaction. The APPX Router sends the AEEB structure in transparent (binary) mode. Data in this structure is in ASCII, and uses little-endian byte order. A remote database transaction running on a host with a different character set or byte order, will need to do translations as appropriate (for example, a transaction running in CICS would usually use EBCDIC and big-endian byte order). The Remote Database Transaction would typically be structured as follows: Start APPX Connect Loop APPX Receive - AEEB Block ASCII to EBCDIC translations (if needed) Byte order conversions (if needed) switch (aeeb.request) { case AREN_XREQ_VERSION: ; set version data in AEEB block break; case AREN_XREQ_INIT: ; init module break; case AREN_XREQ_FREE: ; shutdown module APPX Disconnect Exit Program case AREN_XREQ_LOAD_DB: ; load database break; case AREN_XREQ_UNLOAD_DB: ; unload database/prepare for shutdown break; case AREN_XREQ_ENCR_EXIT_REQUEST: ; execute encryption exit request break; default: ; invalid request, return error aeeb.result = AREN_XRC_ERROR; strcpy(aeeb->msg, "Invalid AEEB Request"); break; } EBCDIC to ASCII translations (if needed) Byte order conversions (if needed) APPX Send - AEEB Block (with updated values) EndLoop The required header files, copybooks, and a short sample CICS remote database transaction are distributed with the APPX Router. The source files are installed in the \dbdll directory under the main APPX Router installation directory.
| << Previous Page | Next Page >> |
