com.ibm.ims.db
Class DLIConnection

java.lang.Object
  |
  +--com.ibm.ims.db.DLIConnection

public class DLIConnection
extends java.lang.Object

A DLIConnection object represents a connection to a PSB. The DLIDatabaseView object that all connections require indicates all of the PCBs (in the PSB) and segments that an application can view, as well as their hierarchical positioning within a particular PCB. This class provides the interface to read, write, update, and delete segments in a DL/I database.


Constructor Summary
protected DLIConnection(DLIDatabaseView dbView)
          Creates a connection with a DL/I database.
protected DLIConnection(DLIDatabaseView dbView, java.lang.String draName)
          Creates a connection with a DL/I database.
protected DLIConnection(DLIDatabaseView dbView, java.lang.String psbName, java.lang.String draName)
          Creates a connection with a DL/I database.
protected DLIConnection(java.lang.String url)
          Creates a connection with a DL/I database.
 
Method Summary
 void close()
          Closes the connection to the database.
static DLIConnection createInstance(DLIDatabaseView dbView)
          Creates a connection with a DL/I database.
static DLIConnection createInstance(DLIDatabaseView dbView, java.lang.String draName)
          Creates a connection with a DL/I database.
static DLIConnection createInstance(DLIDatabaseView dbView, java.lang.String psbName, java.lang.String draName)
          Deprecated. Replaced by createInstance(DLIDatabaseView dbView, String draName)
static DLIConnection createInstance(java.lang.String url)
          Creates a connection with a DL/I database.
 void deleteSegments()
          Deprecated. Replaced by deleteSegments(DLISegment) or deleteSegments(DLIRecord)
 void deleteSegments(DLIRecord record)
          Removes a record and its dependents from the database.
 void deleteSegments(DLISegment segment)
          Removes a segment and its dependents from the database.
protected  void finalize()
          Closes the database connection if it has not already been done.
 AIB getAIB()
          Returns the Application Interface Block (AIB) used by the connection.
 DLIDatabaseView getDBView()
          Returns the database view used to create the connection.
 byte[] getHeldSegmentIOArea()
          Returns the ioArea from the last call.
 boolean getNextRecord(DLIRecord record, SSAList ssaList)
          Retrieves segments in a path call sequentially from the database.
 boolean getNextSegment(DLISegment segment, SSAList ssaList)
          Retrieves a segment sequentially from the database.
 DLISegment getNextSegment(SSAList ssaList)
          Retrieves a segment sequentially from the database.
 boolean getNextSegmentInParent(DLISegment segment, SSAList ssaList)
          Retrieves a dependent segment sequentially from the database.
 DLISegment getNextSegmentInParent(SSAList ssaList)
          Retrieves a dependent segment sequentially from the database.
 boolean getUniqueRecord(DLIRecord record, SSAList ssaList)
          Directly retrieves the segments in a path from the database and establishes a starting position in the database for sequential processing.
 boolean getUniqueSegment(DLISegment segment, SSAList ssaList)
          Directly retrieves a segment from the database and establishes a starting position in the database for sequential processing.
 DLISegment getUniqueSegment(SSAList ssaList)
          Directly retrieves a segment from the database and establishes a starting position in the database for sequential processing.
 void insertSegment(DLISegment segment, SSAList ssaList)
          Inserts a segment into the database.
 void replaceSegment(DLISegment segment)
          Replaces a segment in the database.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DLIConnection

protected DLIConnection(DLIDatabaseView dbView)
Creates a connection with a DL/I database.
Parameters:
dbView - a DLIDatabaseView object
See Also:
DLIDatabaseView

DLIConnection

protected DLIConnection(java.lang.String url)
Creates a connection with a DL/I database. The url may be in two different forms: 1. running in IMS or CICS
    DLIConnection connection = DLIConnection.createInstance("samples.ivp.IVPDatabaseView");
2. / running in USS or Websphere Application Server
    DLIConnection connection = DLIConnection.createInstance("samples.ivp.IVPDatabaseView/DRA1");
Parameters:
url - the fully qualified path to a DLIDatabaseView class name, which may also include the DRA name, depending on the environment
See Also:
DLIDatabaseView

DLIConnection

protected DLIConnection(DLIDatabaseView dbView,
                        java.lang.String psbName,
                        java.lang.String draName)
Creates a connection with a DL/I database.
Parameters:
dbView - a DLIDatabaseView object
psbName - the PSB name
draName - the DRA name
See Also:
DLIDatabaseView

DLIConnection

protected DLIConnection(DLIDatabaseView dbView,
                        java.lang.String draName)
Creates a connection with a DL/I database.
Parameters:
dbView - a DLIDatabaseView object
draName - the DRA name
See Also:
DLIDatabaseView
Method Detail

createInstance

public static DLIConnection createInstance(DLIDatabaseView dbView)
Creates a connection with a DL/I database.
Parameters:
dbView - a DLIDatabaseView object
See Also:
DLIDatabaseView

createInstance

public static DLIConnection createInstance(java.lang.String url)
Creates a connection with a DL/I database. The url may be in two different forms: 1. running in IMS or CICS
    DLIConnection connection = DLIConnection.createInstance("samples.ivp.IVPDatabaseView");
2. / running in a DB2 stored procedure or a Websphere Application Server
    DLIConnection connection = DLIConnection.createInstance("samples.ivp.IVPDatabaseView/DRA1");
Parameters:
url - the fully qualified path to a DLIDatabaseView class name, which may also include the DRA name, depending on the environment
See Also:
DLIDatabaseView

createInstance

public static DLIConnection createInstance(DLIDatabaseView dbView,
                                           java.lang.String psbName,
                                           java.lang.String draName)
Deprecated. Replaced by createInstance(DLIDatabaseView dbView, String draName)

Creates a connection with a DL/I database.
Parameters:
dbView - a DLIDatabaseView object
psbName - the PSB name
draName - the DRA name
See Also:
DLIDatabaseView

createInstance

public static DLIConnection createInstance(DLIDatabaseView dbView,
                                           java.lang.String draName)
Creates a connection with a DL/I database.
Parameters:
dbView - a DLIDatabaseView object
draName - the DRA name
See Also:
DLIDatabaseView

getAIB

public final AIB getAIB()
Returns the Application Interface Block (AIB) used by the connection.
Returns:
AIB The Application Interface Block (AIB).

getHeldSegmentIOArea

public byte[] getHeldSegmentIOArea()
Returns the ioArea from the last call.

close

public void close()
           throws IMSException
Closes the connection to the database.

getNextRecord

public boolean getNextRecord(DLIRecord record,
                             SSAList ssaList)
                      throws IMSException
Retrieves segments in a path call sequentially from the database. This call is usually preceded by a getUniqueRecord call, which establishes a starting position for sequential processing. If not, this call will position at the first root of the entire database.
Parameters:
record - the DLIRecord that will be populated with the segments specified by the SSAList parameter
ssaList - the SSA list specifying the desired DL/I segments in the path.
Returns:
true if there was a record in the database matching the SSAList, false otherwise
Throws:
IMSException - if an error occurs trying to retrieve the record

getNextSegment

public boolean getNextSegment(DLISegment segment,
                              SSAList ssaList)
                       throws IMSException
Retrieves a segment sequentially from the database. This call is usually preceded by a getUniqueSegment call, which establishes a starting position for sequential processing. If not, this call will position at the first root of the entire database.
Parameters:
segment - the DL/I segment that will be populated with the segment specified by the SSAList parameter
ssaList - the SSA list specifying the desired DL/I segment
Returns:
true if there was a segment in the database matching the SSAList, false otherwise
Throws:
IMSException - if an error occurs trying to retrieve the segment

getNextSegment

public DLISegment getNextSegment(SSAList ssaList)
                          throws IMSException
Retrieves a segment sequentially from the database. This call is usually preceded by a getUniqueSegment call, which establishes a starting position for sequential processing. If not, this call will position at the first root of the entire database. If the DLIDatabaseView class containing the view of the segments in the database contains only one DB PCB name, then null may be passed in for an unqualified call. To perform an unqualified call when there are multiple DB PCBs in the DLIDatabaseView create an SSAList by passing in the DB PCB name reference. The DB PCB name reference is the database PCB name that was provided via the dbPCBNameReference parameter to either the DLIDatabaseView(String, String, String, DLISegmentInfo[]) constructor or DLIDatabaseView.addDatabase(String, String, DLISegmentInfo[]) method.
Parameters:
ssaList - the SSA list specifying the desired DL/I segment, or null if performing an unqualified call and the DLIDatabaseView contains only one DB PCB
Returns:
the DLISegment satisfying the SSAList or null if one does not exist
Throws:
IMSException - if an error occurs trying to retrieve the segment
DLIException - if a segment is returned from the call that is not in the DLIDatabaseView of the application
See Also:
SSAList.SSAList(String), DLIDatabaseView.DLIDatabaseView(String, String, String, DLISegmentInfo[]), DLIDatabaseView.addDatabase(String, String, DLISegmentInfo[])

getNextSegmentInParent

public boolean getNextSegmentInParent(DLISegment segment,
                                      SSAList ssaList)
                               throws IMSException
Retrieves a dependent segment sequentially from the database. This call is usually preceded by a getUniqueSegment call, which establishes a starting position for sequential processing. If not, this call will position at the first root of the entire database.
Parameters:
segment - the DL/I segment that will be populated with the segment specified by the SSAList parameter
ssaList - the SSA list specifying the desired DL/I segment
Returns:
true if there was a segment in the database matching the SSAList, false otherwise
Throws:
IMSException - if an error occurs trying to retrieve the segment

getNextSegmentInParent

public DLISegment getNextSegmentInParent(SSAList ssaList)
                                  throws IMSException
Retrieves a dependent segment sequentially from the database. This call is usually preceded by a getUniqueSegment call, which establishes a starting position for sequential processing. If not, this call will position at the first root of the entire database. If the DLIDatabaseView class containing the view of the segments in the database contains only one DB PCB name, then null may be passed in for an unqualified call. To perform an unqualified call when there are multiple DB PCBs in the DLIDatabaseView create an SSAList by passing in the DB PCB name reference. The DB PCB name reference is the database PCB name that was provided via the dbPCBNameReference parameter to either the DLIDatabaseView(String, String, String, DLISegmentInfo[]) constructor or DLIDatabaseView.addDatabase(String, String, DLISegmentInfo[]) method.
Parameters:
ssaList - the SSA list specifying the desired DL/I segment, or null if performing an unqualified call
Returns:
the DLISegment satisfying the SSAList or null if one does not exist
Throws:
IMSException - if an error occurs trying to retrieve the segment
DLIException - if a segment is returned from the call that is not in the DLIDatabaseView of the application
See Also:
SSAList.SSAList(String), DLIDatabaseView.DLIDatabaseView(String, String, String, DLISegmentInfo[]), DLIDatabaseView.addDatabase(String, String, DLISegmentInfo[])

getUniqueRecord

public boolean getUniqueRecord(DLIRecord record,
                               SSAList ssaList)
                        throws IMSException
Directly retrieves the segments in a path from the database and establishes a starting position in the database for sequential processing.
Parameters:
record - the DLIRecord that will be populated with the segments specified by the SSAList parameter
ssaList - the SSA list specifying the desired DL/I leaf segment. The SSAs in the SSAList should have the PATH_CALL command code set on each segment to be retrieved. The P processing option must be specified in the PCB to use this function.
Returns:
true if there was a record in the database matching the SSAList, false otherwise
Throws:
IMSException - if an error occurs trying to retrieve the record

getUniqueSegment

public boolean getUniqueSegment(DLISegment segment,
                                SSAList ssaList)
                         throws IMSException
Directly retrieves a segment from the database and establishes a starting position in the database for sequential processing.
Parameters:
segment - the DL/I segment that will be populated with the segment specified by the SSAList parameter
ssaList - the SSA list specifying the desired DL/I segment
Returns:
true if there was a segment in the database matching the SSAList, false otherwise
Throws:
IMSException - if an error occurs trying to retrieve the segment

getUniqueSegment

public DLISegment getUniqueSegment(SSAList ssaList)
                            throws IMSException
Directly retrieves a segment from the database and establishes a starting position in the database for sequential processing. If the DLIDatabaseView class containing the view of the segments in the database contains only one DB PCB name, then null may be passed in for an unqualified call. To perform an unqualified call when there are multiple DB PCBs in the DLIDatabaseView create an SSAList by passing in the DB PCB name reference. The DB PCB name reference is the database PCB name that was provided via the dbPCBNameReference parameter to either the DLIDatabaseView(String, String, String, DLISegmentInfo[]) constructor or DLIDatabaseView.addDatabase(String, String, DLISegmentInfo[]) method.
Parameters:
ssaList - the SSA list specifying the desired DL/I segment, or null if performing an unqualified call
Returns:
the DLISegment satisfying the SSAList or null if one does not exist
Throws:
IMSException - if an error occurs trying to retrieve the segment
DLIException - if a segment is returned from the call that is not in the DLIDatabaseView of the application
See Also:
SSAList.SSAList(String), DLIDatabaseView.DLIDatabaseView(String, String, String, DLISegmentInfo[]), DLIDatabaseView.addDatabase(String, String, DLISegmentInfo[])

insertSegment

public void insertSegment(DLISegment segment,
                          SSAList ssaList)
                   throws IMSException
Inserts a segment into the database. The SSAList parameter specifies where this segment will be inserted.
Parameters:
segment - the segment to be inserted into the database
ssaList - the SSA list specifying where the segment will be added
Throws:
IMSException - if an error occurs trying to insert the segment

replaceSegment

public void replaceSegment(DLISegment segment)
                    throws IMSException
Replaces a segment in the database. This call must be preceded by either getNextSegment, getNextSegmentInParent, or getUniqueSegment, as each of these calls get a 'hold' on a segment so that it may be modified in some way.
Parameters:
segment - the segment that will replace the existing segment in the database that was returned with one of the three hold calls
Throws:
IMSException - if an error occurs trying to replace the segment

deleteSegments

public void deleteSegments(DLISegment segment)
                    throws IMSException
Removes a segment and its dependents from the database. This call must be preceded by either getNextSegment, getNextSegmentInParent, or getUniqueSegment, as each of these calls get a 'hold' on a segment so that it may be modified in some way.
Parameters:
segment - the segment to be deleted
Throws:
IMSException - if an error occurs trying to delete the segment or record

deleteSegments

public void deleteSegments(DLIRecord record)
                    throws IMSException
Removes a record and its dependents from the database. This call must be preceded by either getNextRecord or getUniqueRecord, as each of these calls get a 'hold' on a segment so that it may be modified in some way.
Parameters:
record - the record to be deleted
Throws:
IMSException - if an error occurs trying to delete the segment or record

deleteSegments

public void deleteSegments()
                    throws IMSException
Deprecated. Replaced by deleteSegments(DLISegment) or deleteSegments(DLIRecord)

Removes a segment and its dependents from the database. This call must be preceded by either getNextSegment, getNextSegmentInParent, or getUniqueSegment, as each of these calls get a 'hold' on a segment so that it may be modified in some way. This method deletes the segment retrieved in the last call of the methods mentioned above.
Throws:
IMSException - if an error occurs trying to delete the segment or record

getDBView

public DLIDatabaseView getDBView()
Returns the database view used to create the connection.

finalize

protected void finalize()
                 throws java.lang.Throwable
Closes the database connection if it has not already been done.
Overrides:
finalize in class java.lang.Object


(C) International Business Machines Corporation 2004. All rights reserved.