Accessing IMS data with the DLIInteractionSpec class

Use the DLIInteractionSpec class to retrieve, insert, update, and delete data from an IMS database using DL/I-like programming semantics with the IMS Universal Database resource adapter.

Before your application component can retrieve, insert, update, or delete data from an IMS database, you need to obtain a javax.resource.cci.Connection instance for the physical connection to the database.

To retrieve, insert, update, or delete data using the DLIInteractionSpec class:

Procedure

In your application component, create a new javax.resource.cci.Interaction instance using the Connection.createInteraction method.
For example, in the following code sample, con is a javax.resource.cci.Connection instance for an IMS database:
```
Interaction ix = con.createInteraction();
```
Create a new com.ibm.ims.db.cci.DLIInteractionSpec instance.
```
DLIInteractionSpec iSpec = new DLIInteractionSpec();
```

Set the function to perform using the DLIInteractionSpec.setFunctionName method, and specifying the function constant value listed in the table below as the input parameter.

Data operation to perform	setFunctionName value
Data retrieval	DLIInteractionSpec.RETRIEVE
Data insertion	DLIInteractionSpec.CREATE
Data update	DLIInteractionSpec.UPDATE
Data deletion	DLIInteractionSpec.DELETE

For example, the following code sample specifies a data retrieval operation:

iSpec.setFunctionName(DLIInteractionSpec.RETRIEVE);

Set the PCB name using the DLIInteractionSpec.setPCBName method.
For example, the following code sample specifies the PCB to be used for this interaction as PCB01:
```
iSpec.setPCBName("PCB01");
```
Set the segment search argument (SSA) list using the DLIInteractionSpec.setSSAList method.
The setSSAList method allows you to specify an SSA in a syntax similar to traditional DL/I.
- You can manually provide the SSA qualification statement as a string in the argument. The syntax is as follows:
  Figure 0. Syntax for segment search argument qualification statement in the setSSAList method
  segName
  
  The name of the segment as defined in the Java™ metadata class generated by the IMS Enterprise Suite Explorer for Development.
  
  cmdCode (optional)
  
  All DL/I command codes except Q and C are supported.
  
  fldName
  
  The name of the field.
  
  relOp
  
  The SSA qualification statement's relational operator. Supported values are:
  
  =
  
  Equals
  
  !=
  
  Not equal
  
  >
  
  Greater than
  
  >=
  
  Greater than or equals
  
  <
  
  Less than
  
  <=
  
  Less than or equals
  
  value
  
  A string representation of the field value. If the value is character-based, the string has to be enclosed in quotation marks. If the value is numeric, it does not need to be enclosed in quotation marks. If the character-based value has quotation marks, use a single quote as an escape for the quote in the value. For example, if the value is O'brian, you would enter it as O''brian.
  
  boolOp
  Boolean operators for adding additional field-level qualifications. The supported Boolean operators are:
  
  logical AND (specified * or &)
  
  logical OR (specified + or |)
  
  independent AND (specified #)
  The following code example shows how to set the segment search argument list to return the last patient admitted to all wards with more than five doctors and less than three nurses in hospital ALEXANDRIA. The *L command means "last occurrence".
```
String ssaList = 
"Hospital(HospName='ALEXANDRIA') Ward(Doccount>5 | Nurcount<3) Patient *L";
iSpec.setSSAList(ssaList);
```
- Instead of providing the string manually, you can use the com.ibm.ims.db.cci.SSAListHelper class to generate the string.
  The following code example shows how to set the SSA qualification statement string using the SSAListHelper:
```
SSAListHelper sh = new SSAListHelper();
sh.addInitialQualification
  ("Hospital","HospName",SSAListHelper.EQUALS, "ALEXANDRIA");
sh.addInitialQualification("Ward","Doccount",
   SSAListHelper.GREATER_THAN, 5); 
sh.appendQualification("Ward",SSAListHelper.OR, "Nurcount",
   SSAListHelper.LESS_THAN, 3);
sh.addCommandCode("Patient",SSAListHelper.CC_L);
iSpec.setSSA(sh.toString());
```
Create a javax.resource.cci.RecordFactory instance using the ConnectionFactory.getRecordFactory method.
For example, the following code sample creates a ConnectionFactory instance rf:
```
RecordFactory rf = cf.getRecordFactory();
```
This step is not needed for a DELETE operation.
Create a javax.resource.cci.MappedRecord instance using the RecordFactory.getMappedRecord method. For a RETRIEVE operation, pass the name of the record you want to create as an argument to this method. For a CREATE or UPDATE operation, the argument is the name of the segment to insert or update.
For example, in the following code sample for a RETRIEVE operation, rf is a javax.resource.cci.RecordFactory instance:
```
MappedRecord input = rf.createMappedRecord("myHospitalRecord");
```
This step is not needed for a DELETE operation because the MappedRecord is not used.
Specify the field to target for the data operation using the MappedRecord.put method. Pass the name of the field as the first argument to this method. For a CREATE or UPDATE operation, the MappedRecord is used to specify the field to insert or update as well as its values. Pass in the value of the field as the second argument. For a RETRIEVE operation, the MappedRecord is used to specify the field that the application is interested in retrieving as a result of the call, and the second argument in the put method call is ignored (you can pass in a null). If you do not specify any fields, the RETRIEVE operation will return all the fields of the leaf segment for that record, along with all the fields in segments which have SSAs specified with a *D command. For CREATE, UPDATE, and RETRIEVE operations, you can specify multiple fields by making multiple MappedRecord.put method calls.
For example, in the following code sample, input is a javax.resource.cci.MappedRecord instance and HospCode is the name of the field we want to retrieve:
```
input.put("HospCode", null);
```
This step is not needed for a DELETE operation as the MappedRecord is not used.
Execute the query by calling the Interaction.execute method. Pass the DLIInteractionSpec object and the MappedRecord object as arguments.
If the query is successful, the method returns a Record object with the query results. You can cast the Record instance to javax.resource.cci.ResultSet and process the results as tabular data in your application component. For example, in the following code sample, results is a javax.resource.cci.ResultSet instance, ix is a javax.resource.cci.Interaction instance, iSpec is a com.ibm.ims.db.cci.DLIInteractionSpec instance, and input is a javax.resource.cci.MappedRecord instance:
```
results = (ResultSet)ix.execute(iSpec, input);
```

Example code for IMS data operations using the DLIInteraction interface

The following complete code example shows how to use the DLIInteraction interface to retrieve fields from a WARD segment.


package client;

import java.sql.SQLException;
import javax.naming.InitialContext;
import javax.resource.ResourceException;
import javax.resource.cci.Connection;
import javax.resource.cci.ConnectionFactory;
import javax.resource.cci.Interaction;
import javax.resource.cci.ResultSet;
import javax.transaction.UserTransaction;
import com.ibm.ims.db.cci.SQLInteractionSpec;

/**
 * Bean implementation class for Enterprise Bean: StatefulBeanManaged
 */
public class BeanManagedSampleDLIBean implements javax.ejb.SessionBean {

    private javax.ejb.SessionContext mySessionCtx;

    public void execute() throws Exception {
        InitialContext ic = new InitialContext();
        ConnectionFactory cf = 
				(ConnectionFactory) ic.lookup("java:comp/env/MyMCF");
        Connection conn = null;
        UserTransaction ut = null;
        
        try {
            ut = this.mySessionCtx.getUserTransaction();
            ut.begin();

            conn = cf.getConnection();
            Interaction ix = conn.createInteraction();

            DLIInteractionSpec iSpec = new DLIInteractionSpec();
            iSpec.setFunctionName("RETRIEVE");
            iSpec.setPCBName("PCB09");

            // This query will return the WARDNAME, PATCOUNT, DOCCOUNT, 
            // and NURCOUNT fields for all WARDs with WARNNO = 51
            iSpec.setSSAList("WARD (WARDNO = '51')");

            // Create RecordFactory
            RecordFactory rf = cf.getRecordFactory();

            // Create Record             
            MappedRecord input = rf.createMappedRecord("WARD");
            // Specify the fields to retrieve
            input.put("WARDNAME", null);
            input.put("PATCOUNT", null);
            input.put("DOCCOUNT", null);
            input.put("NURCOUNT", null);

            ResultSet results = (ResultSet) ix.execute(iSpec, input);
            while (results.next()) {
                System.out.println(results.getString("WARDNAME"));
                System.out.println(results.getString("PATCOUNT"));
                System.out.println(results.getString("DOCCOUNT"));
                System.out.println(results.getString("NURCOUNT"));         
            }   

            rs.close();
            ix.close();
            ut.commit();
            conn.close();
        } catch (ResourceException e) {
            ut.rollback();
            conn.close();
        } catch (SQLException e) {
            ut.rollback();
            conn.close();
        }
    }

    /**
     * getSessionContext
     */
    public javax.ejb.SessionContext getSessionContext() {
        return mySessionCtx;
    }

    /**
     * setSessionContext
     */
    public void setSessionContext(javax.ejb.SessionContext ctx) {
        mySessionCtx = ctx;
    }

    /**
     * ejbCreate
     */
    public void ejbCreate() throws javax.ejb.CreateException {
    }

    /**
     * ejbActivate
     */
    public void ejbActivate() {
    }

    /**
     * ejbPassivate
     */
    public void ejbPassivate() {
    }

    /**
     * ejbRemove
     */
    public void ejbRemove() {
    }
}