DB2 Native REST API – Bonus Features with APARs PI86867/8

Introduction

In the last blog we focused on the new TSO/Batch BIND SERVICE and FREE SERVICE and a sample DB2XML UDF to drive services from z/OS. In doing so, we skated over some of the other features that were delivered with these APARs. Two of these are documented (a bit) in the APAR text, but one of them (the X-Correlation-ID header) doesn’t seem to have been mentioned and was spotted whilst playing with Python!

Initial Availability Enhancement

As covered in the APAR text, one of the features delivered is the removal of the need to restart DDF to have it look for the REST control table SYSIBM.DSNSERVICE and its index. The initial implementation of this check was only performed when DDF was started and this required a little planning when implementing – i.e.

• Do the SMP/E work
• Copy the DSNTIJRS job from SMP/E target library SDSNSAMP, tailor and run it to create the objects
• (create the DSNR class ssid.REST profile)
• Deliver the maintenance
  • Stop DB2
  • Roll out the maintenance libraries
  • Start DB2

On restart with the maintenance applied, DDF would detect the presence of the objects and REST would then be available. If you forgot to create the table before delivering the maintenance, then no REST until the next restart.

With this APAR applied DDF will now detect when the DSNTIJRS objects have been created without the need to restart DDF, which will remove the potential need for an additional service restart.

HTTP Connection Persistence

Previously, when a service had completed successfully, the connection with the client was immediately closed. Client servers can be driving a high volume of short execution services, and the cost of recreating the connections can become significant.

To help overcome this, the DB2 REST interface will now keep the connection available for up to 15 seconds following a successful (status code = 200) REST call. Note that 15 seconds is the initial position – your mileage may vary as this gets “tuned” in subsequent maintenance.

To indicate this back to the client, DB2 REST returns an additional Connection HTTP header in the response:

Connection : keep-alive

The default for this is “close” – i.e. close at the end of this request, so DB2 returning “keep-alive” invites the client to reuse the connection.

Reported DB2 Connection Correlation ID

One of the challenges when auditing a distributed transaction or diagnosing an issue with one is how to align the client-side operation with what happened in the back end. Where thousands of transactions can be running at a time, being able to identify which client request drove which DB2 for z/OS service is vital.

The logical unit of work ID (as reported in Omegamon for DB2 and friends) is now returned in the X-Correlation-ID header:

This ties up with what we see in QWHSLWID (standard header logical unit of work ID) and is referred to in monitors as the Logical Unit of Work ID (LUWID).

Note that like all other distributed workload, REST calls will be subject to accounting rollup.

Access all of James Gill’s Native REST API blogs here.

• Share