G2 Knowledge Bases used with DM_G2_GSI
Seven knowledge bases (KBs), namely idx-common, idx-socketserver.kb, idx-socketclient.kb, idx-database.kb, idx-slots.kb, idx-all-top.kb and idx-all-demo-top.kb are provided with IDX, and can be found in the path: InstallPath\IDX\\utils\g2\kbs after installation. idx-all-top.kb's required modules provide the G2 API & supporting G2 objects that allow G2 to interact with DM_G2_GSI:
· Mailslot API (idx-socketclient.kb)
· TCP/IP Client Socket API (idx-socketclient.kb)
· TCP/IP Server Socket API (idx-socketserver.kb)
· DB Slot API (idx-slots.kb)
· Database API (idx-database.kb)
· Calculating Debug Levels (idx-common.kb)
· The IDX interface toolkit (utility gsi-interface subclasses provided in idx-common.kb)
The diagram below shows the module hierarchy of idx-all-top:
Using old versions of the IDX-G2 utility KBs will have undefined results. Errors arising from usage of legacy KBs with newer versions of IDX will not be supported.
Three IDX KB versions are provided to match a specific version of G2:
· Version 5
· Version 6
· Version 7
Please use the appropriate KB versions with your corresponding version-series of G2. Each version is found in a respective directory in the InstallPath\IDX\\utils\g2\kbs path.
The DM_G2_GSI API consists of the set of G2 objects, methods and procedures found in InstallPath\IDX\utils\g2\kbs\idx-all-top.kb and its required modules.
The philosophy of the API is that each API procedure/method call takes one parameter only of type idx-obj. idx-obj is the ultimate superior class of any object that may be passed to a DM_G2_GSI API procedure. idx-obj itself is never instantiated directly - rather an appropriate subclass instance is passed to API calls.
DM_G2_GSI both reads any input data it needs from relevant attributes of the idx-obj subclass instance, and writes results directly into the attributes of that same idx-obj. At the very least, DM_G2_GSI normally writes error information (an error-integer and an error-text) into the attributes of the idx-obj. Because of this methodology, it is not necessary to return anything from an API call, although some API's do return error information due to legacy reasons. Whenever given a choice, always prefer the error information written directly into the idx-obj, rather than that returned by an API.
Because DM_G2_GSI writes directly to the idx-obj, every idx-obj must have a handle attribute, the value of which is transparently determined by GSI at the time of the first API call with that idx-obj, and should never be changed by the user.
The demonstration knowledge base is found in InstallPath\IDX\utils\g2\kbs\idx-all-demo-top.kb. It has demos and examples of how to use all facets of the DM_G2_GSI API in G2. Open this knowledge base in G2 for online examples.
If only partial interfacing functionality is required (for example, just the database functionality) then only the appropriate KB (idx-database.kb in this case) may be merged into your G2 module hierarchy.
idx-all-demo-top.kb provides a number of demos of how to use the above G2 API:
· Mailslot Demo
· TCP/IP Socket Demo
· Slot Demo
· Database Demo
The Gensym utility KBs sys-mod.kb and uilroot.kb are also provided with IDX, although the latest versions of these KBs are available from Gensym.
Note: This procedure applies to any IDX-G2 knowledge bases released before September 2000.
idx-database is a module which contains the G2 classes and APIs for all database G2 communications via DM_G2_GSI. As such, it replaces the previous modules g2-sql-database-io, used in IDX versions before 5.3.0. The following is an example of how to upgrade to idx-database from g2-sql-database-io:
Suppose you have a top-level application module, my-app say, which directly requires the g2-sql-database-io module:
· Do an inspect to show the module hierarchy
· Change the name of the g2-sql-database-io module to idx-database
· In all top-level workspaces assigned to g2-sql-database-io, go to the workspace table and change the module-assignment attribute to idx-database
· In the directly-required-modules attribute of the my-app module-information object (at the top of the module hierarchy), remove g2-sql-database-io, and add idx-database
· Now save the my-app module. DO NOT SAVE ANY OTHER MODULE.
· Copy idx-database.kb from \idx5\utils\g2\kbs\ to your application directory.
· Load my-app.kb again, with automatically-resolve-conflicts selected.
· All instances of G2-IDX database objects in my-app should be seamlessly updated.
The signatures of the APIs used in g2-sql-database-io remain unchanged. There are also new APIs, which are now recommended for use instead of the originals, although this is not strictly required. All documentation refers to the new APIs, which follow the standard of taking only one input parameter.
With the exception of mailslot classes, the original attribute and class names of classes used in previous versions of idx-mio & g2-sql-database-io remain intact. Therefore it should be possible to re-use all older user code (with the exception of mailslot code, which will have to be re-written). It is recommended, however, that a gradual change of code be made to leverage the new G2 APIs.