Background - HandyJDOAdapter Template
The HandyJDODataAdapter template is an existing CHT procedure template used to create CHT Client Server data packaging procedures. It creates procedures that hook into a CHT server application by attaching to the main server via a server VIEW created there with a server-plug-in template called ClientServerQueryBrancher_BIC. All remote web-client queries directed at a particular VIEW name are routed by the server through a HandyJDODataAdatpter procedure attached to a matching VIEW name. A server may have numerous versions of this data packaging procedure- as many as the data requirements of your application dictate - each servicing a different back end data view consisting of one or more data tables. So asking, "How many HandyJDODataAdapter procedures does my server require?", is a lot like asking, "How many browses does my application require?" Depends. It's basically up to you to decide.
Extra Generation Control Features HandyJDOAdaper Template
A new dialog called "Generate" has been added to the HandyJDODataAdapter template (see image below). It's purpose is to give you more control over the existing code-generation features of this template and to add some new features particularly useful with SQL back ends - situations where your server is serving data to a web client application from an SQL data base without directly exposing the data base to the web.
The "Generate" dialog has been added as indicated above, just below the existing "Files" dialog. See the next image for the details of the dialog itself.
No Generate SetUpdateRecord() Pre-fetch Code
Inside all HandyJDOAdapter procedures is an OOP method called SetUpdateRecord(). This method is used to fetch a record - or a set of records described in a Clarion View - before updating or deleting. Your client will send an unambiguous filter that describes exactly one recordset during an update or delete operation. This filter is usually something as simple as CUS:SysID = 1234. The fetching operation is called a "Pre-Fetch" because the fetch is accomplished - and required - before the actual update or delete operation can take place.
There are also times when a "Pre-Fetch" using SetUpdateRecord() is required even in an "INSERT" operation. Inserting a child record to an invoice header,for instance, may require you to pre-fetch the header record so that the ID of the header can be primed into the child record's join field. Or you may want the child record to contain data from a related record as, for example, the CHT Support Forum does, where a copy of your original posting is inserted into your REPLY.
Suffice to say, that how and when your pre-fetch is performed can depend significantly on your data design. This first dialog "No Generate SetUpdateRecord() Pre-fetch Code" stops generation of default pre-fetch code so as to allow you to insert case-specific code of your own design.
Generate SQL-Style Primary Table Fetch
When you check, and set ON the "No Generate SetUpdateRecord Pre-fetch Code" switch mentioned above, the second switch, "Generate SQL-Style Primary Table Fetch" becomes enabled. This generates a simple fetch on the Primary Table in your procedure's data view based on the "FetchFilter" being passed up from your client. With this switch set, you don't need to write the SQL-style fetch code yourself, if what's generated applies to your design. The code generated looks as follows and, as already stated, applies only to the Primary table in your view.
By juggling your view layout, you can often achieve the end result you want in order to pre-fetch the data record you want without writing any code. However, you must decide whether the code created by the template is what you want or need. If not, leave "Generate SQL-Style Primary Table Fetch" unchecked and write more complex pre-fetch code that better fulfills your design. These switches give you the option of doing that.
No Generate TakeWebUpdateRecord() HTTPInsert Code
Also inside your HandyJDOAdapter procedure is an OOP method called TakeWebUpdateRecord(). This method is used to actually perform record INSERT, UPDATE and DELETE operations at the command of your web client. This specific switch lets you turn OFF code generation of the INSERT code normally produced by our template. That provides you with the opportunity to craft your own insert code based on specific requirements that our template has not forseen or generic insert code just won't handle. The image below, illustrates some hand-embedded code in a server I recently created. The main bit of knowledge you need to have that is CHT server specific is the return value after a successful insert.
There are three requirements after a successful insert. These are: 1) Call xServer.SetCurrentQuery() with the filter statement that your CHT server will use to refetch this new record just created. This is a simple, unambiguous "FetchFilter" used to recall this newly inserted record. 2) Set the procedure returnvalue to HPROP:WebCycleToEdit. The server uses this value to literally switch itself into update mode and return the data to your web client app now operating in update mode. In other words, the record is pre-inserted and returned to your web-client primed to the extent your insert requires and the client form procedure completes the record. 3) The procedure return error code is set to HND_MESSAGE_BRWSVR_CYCLE_EDIT This is really not an error code, just a signal to the main server code that it should go into edit mode using the record just inserted.
What If The Client Cancels An Insert Operation?
While we're on the topic of web-client record insertion, since records are pre-inserted by the server - for obvious reasons - what happens if the web-client operator decides to cancel record insertion? There are two ways to handle this. They can be used exclusively by implementing one or the other, or they can be used together. Each server back end data packaging procedure built with HandyJDOAdapter is always populated with another template called ClientServerDataBuilder.
This template describes the tables, the view and the fields to be operated on by the procedure. It provides among other things a dialog called "Garbage Collection" (see image below). Here you can describe a background operation that purges incomplete records on a time scale determined by you. The purging operation requires a few specific fields that signal to the server that a record has been abandonded without having being completed.
If you don't want to avail yourself of this "Garbage Collection" facility - implemented on the server end - you can simply configure the client applicaton to delete the pre-inserted record if the user cancels out of insert mode without completing and saving the record. That's a more traditional, Clarion-like behaviour to handle housekeeping of cancelled inserts (see image below).
No-Generate Query Keyword File Fetches
A built-in capability of all CHT Back-end data packaging procedures created with HandyJDODataAdapter is the ability to dynamically switch in or out, query keywords from the application's configuration file. For example, you might have a server that serves both English and French users who are operating browses that allow them to construct native language queries using CHT's query builder or QueryParsingFilterControl. With a signal from the client indicating French or English, your data procedure can, in real time, read and BIND the approrpriate set of Query Keywords from it's configuration file and thus be able to interpret both sets of queries from either French or English clients. The switch "No-Generate Query Keyword File Fetches" turns off this dynamic query keyword capability in favor of the query keywords that you've pre-configured on our template. Doing so generates less code - that you probably aren't using anyway - and eliminates the requirement to complete the "Server Variables File" dialog on our ClientServerDataBuilder template (see next image). In fact, this "Server Variables File" dialog becomes disabled when "No Generate Query Keyword File Fetches" is checked.
That concludes "Build 13C1.00 Feature Review Part 3" describing changes on the HandyJDODataAdapter template and how they impact other parts of your server/client systems.
Cheers...
Gus Creces
The Clarion Handy Tools Page
www.cwhandy.com
support@cwhandy.com
August 4, 2009
No comments:
Post a Comment