c-treeRTG V2 Update Guide

Support for retrieving locker ID in ACUCOBOL

This modification allows a COBOL programmer using ACUCOBOL with c-treeRTG to call the ct_lockerid() function to get the c-treeACE Server Task# of the client holding a lock. The change simply adds a new function (ct_lockerid) to the list of functions loaded during runtime initialization so is callable from the ACUCOBOL runtime. In addition, the ACUCOBOL runtime needs to be re-compiled with ACUCOBOL's list of available C functions updated to include the ct_lockerid() function in the source module direct.c as follows:

extern int ct_lockerid (void); /* add this line */

struct DIRECTTABLE LIBDIRECT[] = {

{ "LOCKERID", FUNC ct_lockerid, C_int }, /* add this line */

{ NULL, NULL, 0 }

};

The function can be called from the COBOL application as follows:

working-storage section.

77 lockerid pic x(4) comp-5.

...

if stat = "93"

call "LOCKERID" giving lockerid

display "file is locked by task# " lockerid

Four steps are required to take advantage of this ability (this assumes you have already included the FairCom c-treeRTG file handler in the RTG runtime - see the c-treeRTG manual for complete information):

1. Copy the new ctreeacu.c into the /lib directory of your ACUCOBOL installation. A common location is /opt/acugt/lib.
2. Edit the direct.c module as indicated above.
3. Execute the system make utility to compile new c-treeRTG functionality into your ACUCOBOL runcbl runtime module. (This requires a compiler installed and available on your system.)
4. Copy the new runcbl into the /bin directory of your ACUCOBOL installation.

   Note: Be sure to back up existing runcbl modules first.

Once enabled, the “LOCKERID” function is available to any COBOL application using the newly compiled runtime. The Task ID is an internal thread ID per connection available within the c-treeRTG Server. This ID is not directly associated with your operating system PIDs in any way.

A task ID can be viewed via the c-treeRTG c-treeACE Monitor utility to identify exactly which runtime is holding a lock. If that connection is associated with other identifying information, such as their process ID (PID), an administrator can quickly determine who is holding a lock.

For example, consider with the following LOCKERID error output:

File is locked by task# : 23

ERROR: [9/057]

*** Execution aborted ***

Press <ENTER> key to exit...

A Task ID can be identified using c-treeACE Monitor as shown in the screenshot below:

If ctree.conf specifies a PID to be passed in for each runtime user, an actual user can be determined. Any identifying information can be included in the name attribute, including IP addresses, local machine names, etc., from users’ environment variables. In this case, inside the instance tag, include the name attribute with %p for the PID:

<instance user=”ADMIN” password=”ADMIN” server=”BSTREET1” name=”%p”>

...

</instance>

In fact, if absolutely necessary, an administrator can right-click on a connection in c-treeACE Monitor and kill that connection. This action should be very carefully considered, however.