Retrieving data in a IMS Universal DL/I driver application

The IMS Universal DL/I driver provides support for data retrieval that mirrors DL/I semantics.

The following are the general steps to retrieve segments from the database:

Procedure

  1. Obtain an SSAList instance from the PCB instance representing the database.
  2. Optionally, you can add qualification statements to the SSAList instance.
  3. Specify the segment fields to retrieve. Use the markFieldForRetrieval method to mark a single field, or use the markAllFieldsForRetrieval method to mark all the fields for a segment. Following the IMS default, all of the fields in the lowest-level segment specified by the SSAList instance are initially marked for retrieval. When one or more of the fields in the lowest level segment specified in an SSAList instance is marked for retrieval, only the explicitly marked fields are retrieved.
  4. Get a Path instance by using the SSAList instance from the previous steps and calling the getPathForRetrieveReplace method. When a retrieve call is made, the resulting Path object will contain all the fields that have been marked for retrieval.
  5. Call a DL/I retrieve operation using one of the following methods from the PCB interface:
    Java™ API for DL/I retrieve method Usage
    getUnique Retrieves a specific unique segment. This method provides the same functionality as the DL/I Get Unique (GU) database call. If the isHoldCall parameter is set to true, the call behaves as a DL/I Get Hold Unique (GHU) database call.
    getNext Retrieves the next segment in a Path. This method provides the same functionality as the DL/I Get Next (GN) database call. If the isHoldCall parameter is set to true, the call behaves as a DL/I Get Hold Next (GHN) database call.
    getNextWithinParent Retrieves the next segment within the same parent. This method provides the same functionality as the DL/I Get Next Within Parent (GNP) database call. If the isHoldCall parameter is set to true, the call behaves as a DL/I Get Hold Next Within Parent (GHNP) database call.
    batchRetrieve Retrieves multiple segments with a single call. See Batch data retrieval in a Java API for DL/I application for more information about how to use this method.
  6. Read the values of the retrieved fields out of the Path object after the retrieve call is made.

IMS Universal DL/I driver data retrieval example

The following code fragment illustrates how to use the getUnique method and getNext method to retrieve the hospital name (HOSPNAME), ward name (WARDNAME), patient count (PATCOUNT), nurse count (NURCOUNT), and doctor count (DOCCOUNT) fields from the Hospital database:

import com.ibm.ims.dli.*;


public class HospitalDLIReadClient {

   public static void main(String[] args) {
     PSB psb = null;
     PCB pcb = null;
     SSAList ssaList = null;
     Path path = null;
     PathSet pathSet = null;
        
     try {
        // establish a database connection
        IMSConnectionSpec connSpec 
           = IMSConnectionSpecFactory.createIMSConnectionSpec();
        connSpec.setDatastoreName("IMS1");
        connSpec.setDatastoreServer("ecdev123.svl.ibm.com");
        connSpec.setPortNumber(5555);
        connSpec.setMetadataURL("class://BMP266.BMP266DatabaseView");
        connSpec.setUser("usr");
        connSpec.setPassword("password");
			 connSpec.setDriverType(IMSConnectionSpec.DRIVER_TYPE_4);        
        psb = PSBFactory.createPSB(connSpec); 
        System.out.println("**** Created a connection to the IMS database");
             
        pcb = psb.getPCB("PCb01");
        System.out.println("**** Created PCB object");

        // specify the segment search arguments
        ssaList = pcb.getSSAList("HOSPITAL", "WARD");
        // add the initial qualification
        ssaList.addInitialQualification("HOSPITAL", "HOSPCODE", 
           SSAList.GREATER_OR_EQUAL, 444);
        // specify the fields to retrieve        
        ssaList.markFieldForRetrieval("HOSPITAL", "HOSPNAME", true);
        ssaList.markAllFieldsForRetrieval("WARD", true);
        ssaList.markFieldForRetrieval("WARD", "WARDNO", false);   
        System.out.println("**** Created SSAList object");

        // obtain a Path containing the segments that match the SSAList criteria 
        path = ssaList.getPathForRetrieveReplace();
        System.out.println("**** Created Path object");

        // issue a DL/I GU call to retrieve the first segment on the Path 
       if (pcb.getUnique(path, ssaList, true) {
          System.out.println("HOSPNAME: "+ path.getString("HOSPITAL", "HOSPNAME"));
          System.out.println("WARDNAME: "+ path.getString("WARD", "WARDNAME"));
          System.out.println("PATCOUNT: "+ path.getInt("WARD", "PATCOUNT"));
          System.out.println("NURCOUNT: "+ path.getInt("WARD", "NURCOUNT"));
          System.out.println("DOCCOUNT: "+ path.getShort("WARD", "DOCCOUNT"));
       }
    
       // issue multiple DL/I GN calls until there are no more segments to retrieve 
       while (pcb.getNext(pat, ssaList, true) {
          System.out.println("HOSPNAME: "+ path.getString("HOSPITAL", "HOSPNAME"));
          System.out.println("WARDNAME: "+ path.getString("WARD", "WARDNAME"));
          System.out.println("PATCOUNT: "+ path.getInt("WARD", "PATCOUNT"));
          System.out.println("NURCOUNT: "+ path.getInt("WARD", "NURCOUNT"));
          System.out.println("DOCCOUNT: "+ path.getShort("WARD", "DOCCOUNT"));
       }         
       
       // close the database connection
       psb.close();
       System.out.println("**** Disconnected from IMS database");

     } catch (DLIException e) {
        System.out.println(e);
        System.exit(0);
     }
   }
}