Using Byte Buffers with the IMS Universal DL/I driver

The IMS Universal DL/I driver includes several methods to handle complex data types that are not fully represented by the IMS Catalog.

The IMS Universal DL/I driver includes several methods that implement ByteBuffer input and output (I/O) objects instead of the traditional Path objects. Using ByteBuffers as I/O areas allows an application to retain full control in managing and interpreting data inserted or retrieved from IMS. These methods are useful when dealing with complex data types that are not fully represented by the IMS Catalog.


getUnique();
getNext();
getNextWithinParent();
insert();
create();
replace();

Note:

The ByteBuffer support is extended to support the IMS Message Queue interface.

Programming examples using ByteBuffers and the IMS Universal DL/I Driver

The following example shows an example of inserting multiple segments along the same hierarchical path. The hierarchical path consists of three segments that are children of the root segment Hospital.

// DEFINE SSA1 for INSERTS
SSAList ssaList = pcb.getSSAList("HOSPITAL", "ILLNESS");
ssaList.addInitialQualification("HOSPITAL", "HOSPCODE", SSAList.EQUALS, "R1210010000A");
ssaList.addCommandCode("WARD", SSAList.CC_D);
ssaList.addCommandCode("PATIENT", SSAList.CC_D);
ssaList.addCommandCode("ILLNESS", SSAList.CC_D);

// Allocate a ByteBuffer
ByteBuffer bufferInsert = ByteBuffer.allocate(1000);

// WARD
bufferInsert.position(0);
bufferInsert.putShort((short) 900);
bufferInsert.put("0010".getBytes("Cp1047"));
bufferInsert.put("NEW WARD".getBytes("Cp1047"));

// PATIENT
bufferInsert.position(900);
bufferInsert.putShort((short) 37);
bufferInsert.put("9999".getBytes("Cp1047"));
bufferInsert.put("JACKSON".getBytes("Cp1047"));

// ILLNESS
bufferInsert.position(937);
bufferInsert.putShort((short) 900);
bufferInsert.put("FRECKLES".getBytes("Cp1047"));

// Insert ByteBuffer
pcb.insert(bufferInsert, ssaList);

The following example issues a GU call with a hold on the segment to replace that retrieved segment.

// DEFINE SSA2 FOR RETRIEVE/REPLACE
SSAList ssaList2 = pcb.getSSAList("HOSPITAL", "PATIENT");
ssaList2.addInitialQualification("HOSPITAL", "HOSPCODE", SSAList.EQUALS, "R1210010000A");

// Retrieve the segment with the ByteBuffer as an output object
ByteBuffer bufferRetrieve = ByteBuffer.allocate(900);
pcb.getUnique(bufferRetrieve, ssaList2, true);
   
    // Replace
bufferReplace = ByteBuffer.allocate(42);
bufferReplace.putShort((short) 27);
bufferReplace.put("9999".getBytes("Cp1047"));
bufferReplace.put("FRANKLIN".getBytes("Cp1047"));
pcb.replace(bufferReplace);

Considerations for ByteBuffers and Type-2 Java applications

If your JDBC application is running in Type-2 mode, you have the option of obtaining a direct ByteBuffer to optimize JVM storage use. You can obtain direct storage in the following ways:

Directly using the java.nio.ByteBuffer class

ByteBuffer directBuffer = ByteBuffer.allocateDirect(10);

Using the Universal Drivers Application object to obtain direct 31-bit storage

Application app = new ApplicationFactory.createApplication();
          ByteBuffer directBuffer = app.get31BitDirectByteBuffer(20);

Note: If an application is running in the 64-bit JVM, ByteBuffer.allocateDirect() will not work with your application and you must directly request 31-bit storage using the Application.get31BitDirectByteBuffer() method. ByteBuffer.allocateDirect() works in a 31-bit JVM.

It is important to release and free the buffers correctly in your application. You can free buffers that were obtained using the Application class in the following ways:

Specifically freeing buffers

Application app = new ApplicationFactory.createApplication();
ByteBuffer directBuffer = app.get31BitDirectByteBuffer(20);
 
   // Doing work
app.free31BitDirectByteBuffer(directBuffer);

IMS silently tracks all buffers allocated using the Application class and automatically releases all the checked out buffers during the end() procedure.

Application app = new ApplicationFactory.createApplication();
  ByteBuffer directBuffer = app.get31BitDirectByteBuffer(20);
  // Doing work
app.end();