com.ibm.ims.dli

Interface PSB

public interface PSB

A Program Specification Block (PSB) contains one or more PCB objects. Use this interface to obtain a handle to any PCB contained in the PSB. The PCB handle is used to access the particular database referenced by the PCB.

The code fragment below shows how to create and use PSB to obtain a PCB handle. First, create an instance of IMSConnectionSpec using the IMSConnectionSpecFactory. Next, pass the connection request properties to the PSBFactory to create the PSB. When the PSB is created, a connection is made to the database. Finally, call the getPCB method, using the PCB name as a parameter, to obtain a PCB handle to access the database.

 IMSConnectionSpec connSpec = IMSConnectionSpecFactory.createIMSConnectionSpec();
 connSpec.setDatastoreName("SYS1");
 connSpec.setDatastoreServer("9.876.543.21");
 connSpec.setPortNumber(50);
 connSpec.setDatabaseName("class://testdb.jdbo.HospitalDatabaseView");
 connSpec.setDriverType(IMSConnectionSpec.DRIVER_TYPE_4);
 connSpec.setUser("usr");
 connSpec.setPassword("usrpwd");
 PSB psb = PSBFactory.createPSB(connSpec);
 PCB pcb = psb.getPCB("Pcb01");
 

PSB provides support for local transaction processing. A local transaction consists of a unit of work with several units of recovery. In the IMS Universal DL/I driver, the local transaction is scoped to the PSB. No explicit call is needed to begin a local transaction. A unit of recovery consists of a sequence of DL/I calls followed by either a call to commit the current unit of recovery with commit(), or a call to undo the changes up to the last unit of recovery with rollback(). If commit or rollback is called and the PSB is not deallocated, a new unit of recovery is started. By default, the local transaction ends when the PSB is deallocated. To persist changes made to the database, your application must always call commit prior to PSB.deallocate or PSB.close, otherwise the changes are rolled back to the last point commit was called.

The following code fragment illustrates how to create and use PSB in a local transaction.

   PSB psb = PSBFactory.createPSB(imsConnectionSpec);
   PCB pcb = psb.getPCB("PCb01");
    
   // perform an insert operation
   SSAList ssa = pcb.getSSAList("HOSPITAL");
   Path path = ssa.getPathForInsert("HOSPITAL");
   path.setString("HOSPCODE", "R1210020000A");
   path.setString("HOSPNAME", "SANTA TERESA");
   pcb.insert(path);
   
   // commit the changes or use psb.rollback() to undo the insert
   psb.commit(); 
   ...
   psb.deallocate();
   psb.close();
 

See Also:

PCB, PSBFactory.createPSB(IMSConnectionSpec)

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALL ALL indicates that all messages should be logged.
static int	FINE FINE indicates basic tracing.
static int	FINER FINER indicates fairly detailed tracing.
static int	FINEST FINEST indicates highly detailed tracing.
static int	OFF OFF indicates that no messages should be logged.

Method Summary

Modifier and Type	Method and Description
void	allocate() Allocates the PSB, making all databases referenced by the contained PCBs accessible.
void	close() Closes any physical resources associated with this PSB.
void	commit() Commits the current local transaction and releases all locks and database position held by the underlying EIS instance.
DBArray	createArrayOf(java.lang.String typeName) Factory method for creating DBArray objects.
DBStruct	createStruct(java.lang.String typeName) Factory method for creating DBStruct objects.
void	deallocate() Deallocates the PSB and free up all IMS resources associated with the PSB.
GSAMPCB	getGSAMPCB(java.lang.String pcbName) This method returns a GSAMPCB object that represents an actual GSAM PCB contained in the PSB.
java.lang.String	getIMSName() Returns the name of the PSB as defined to IMS
PCB	getIOPCB() This method returns a PCB object that represents an IOPCB Use PCB to access the database it references.
PCB	getPCB(java.lang.String pcbName) This method returns a PCB object that represents an actual PCB contained in the PSB.
short	initStatusGroupA() To avoid abendu3303, use INIT STATUS GROUPA.
short	initStatusGroupB() To avoid deadlock conditions(Abend u777), use INIT STATUS GROUPB.
boolean	isAllocated() Indicates whether or not the PSB is currently allocated.
boolean	isOpen() Indicates whether or not the PSB is currently open (has a physical connection to the host system).
void	open() Opens any physical resources associated with this PSB.
DLICall	prepareIMSRegionDLICall(DLICall.Function function) Creates an instance of DLICall for programmatically issuing DL/I calls to IMS from your Java application.
DLICall	prepareIMSRegionDLICall(DLICallProperty properties) Creates an instance of DLICall for programmatically issuing DL/I calls to IMS from your Java application.
void	rollback() Rolls back the current local transaction
void	setLogWriter(java.io.PrintWriter writer) Sets the log writer for this PSB instance.
void	setLogWriterTraceLevel(int level) Sets the trace level for this PSB instance.

Field Detail

FINE

static final int FINE

FINE indicates basic tracing.

See Also:

Constant Field Values

FINER

static final int FINER

FINER indicates fairly detailed tracing.

See Also:

Constant Field Values

FINEST

static final int FINEST

FINEST indicates highly detailed tracing.

See Also:

Constant Field Values

ALL

static final int ALL

ALL indicates that all messages should be logged.

See Also:

Constant Field Values

OFF

static final int OFF

OFF indicates that no messages should be logged.

See Also:

Constant Field Values

Method Detail

getPCB

PCB getPCB(java.lang.String pcbName)
    throws DLIException

This method returns a PCB object that represents an actual PCB contained in the PSB. Use PCB to access the database it references.

Parameters:

pcbName - the name of a PCB within the PSB

Returns:

the specified PCB object

Throws:

DLIException - if an error occurs during processing

getGSAMPCB

GSAMPCB getGSAMPCB(java.lang.String pcbName)
            throws DLIException

This method returns a GSAMPCB object that represents an actual GSAM PCB contained in the PSB. Use GSAMPCB to access the GSAM database it references.

Parameters:

pcbName - the name of a GSAM PCB within the PSB

Returns:

the specified GSAMPCB object

Throws:

DLIException - if an error occurs during processing

getIOPCB

PCB getIOPCB()
      throws DLIException

This method returns a PCB object that represents an IOPCB Use PCB to access the database it references.

Returns:

the specified PCB object

Throws:

DLIException - if an error occurs during processing

getIMSName

java.lang.String getIMSName()

Returns the name of the PSB as defined to IMS

Returns:

the name of the PSB

allocate

void allocate()
       throws DLIException

Allocates the PSB, making all databases referenced by the contained PCBs accessible.

Note: This method will be called internally by the libraries. It is not necessary for client applications to call this method.

Throws:

DLIException - if an error occurs during processing

deallocate

void deallocate()
         throws DLIException

Deallocates the PSB and free up all IMS resources associated with the PSB.

Throws:

DLIException - if an error occurs during processing

close

void close()
    throws DLIException

Closes any physical resources associated with this PSB. If the actual PSB was never deallocated, this close method will also deallocate the PSB.

Throws:

DLIException - if an error occurs during processing

open

void open()
   throws DLIException

Opens any physical resources associated with this PSB. Calling the PSB.open method from a distributed environment will create a socket connection and allocate the PSB. Calling this method from local non-IMS environments will simply allocate the PSB.

Throws:

DLIException - if an error occurs during processing

isAllocated

boolean isAllocated()

Indicates whether or not the PSB is currently allocated.

Returns:

true if allocated, false otherwise

isOpen

boolean isOpen()

Indicates whether or not the PSB is currently open (has a physical connection to the host system).

Returns:

true if open, false otherwise

setLogWriter

void setLogWriter(java.io.PrintWriter writer)

Sets the log writer for this PSB instance. All tracing will be logged using this PrintWriter.

Parameters:

writer - the PrintWriter to use for logging

setLogWriterTraceLevel

void setLogWriterTraceLevel(int level)

Sets the trace level for this PSB instance.

Parameters:

level - the trace level

commit

void commit()
     throws DLIException,
            com.ibm.ims.dli.NotSupportedException

Commits the current local transaction and releases all locks and database position held by the underlying EIS instance.

Throws:

com.ibm.ims.dli.NotSupportedException - if the operation is not supported

DLIException - if the operation fails

rollback

void rollback()
       throws DLIException,
              com.ibm.ims.dli.NotSupportedException

Rolls back the current local transaction

Throws:

com.ibm.ims.dli.NotSupportedException - if the operation is not supported

DLIException - if the operation fails

prepareIMSRegionDLICall

DLICall prepareIMSRegionDLICall(DLICallProperty properties)
                         throws DLIException

Creates an instance of DLICall for programmatically issuing DL/I calls to IMS from your Java application.

Parameters:

properties - a DLICallProperty instance that represents input parameters for the DL/I call. See DLICall for examples of how to set the properties..

Returns:

DLICall the DLICall instance

Throws:

DLIException

See Also:

DLICall

prepareIMSRegionDLICall

DLICall prepareIMSRegionDLICall(DLICall.Function function)
                         throws DLIException

Creates an instance of DLICall for programmatically issuing DL/I calls to IMS from your Java application.

Parameters:

function - the function name of the DL/I call. Use the constants defined in DLICall to specify this parameter.

Returns:

DLICall the DLICall instance

Throws:

DLIException

See Also:

DLICall

createStruct

DBStruct createStruct(java.lang.String typeName)
               throws DLIException

Factory method for creating DBStruct objects.

Parameters:

typeName - the type name of the structured type that this DBStruct object maps to. The typeName is the name of a defined type that has been defined in the DBD for this database. It needs to be in the following format: pcbName.segmentName.structName It is the value returned by DBStruct.getTypeName.

Returns:

a DBStruct object that maps to the given type

Throws:

DLIException - if the typeName is null or invalid

See Also:

DBStruct

createArrayOf

DBArray createArrayOf(java.lang.String typeName)
               throws DLIException

Factory method for creating DBArray objects.

Parameters:

typeName - the name of the type the elements of the array map to. The typeName is the name of a defined type that has been defined in the DBD for this database. It needs to be in the following format: pcbName.segmentName.arrayName It is the value returned by DBArray.getTypeName.

Returns:

a DBArray object that maps to the given type

Throws:

DLIException - if the typeName is null or invalid

See Also:

DBArray

initStatusGroupA

short initStatusGroupA()
                throws DLIException

To avoid abendu3303, use INIT STATUS GROUPA. IMS will give you a status code for unavailable databases. Example: BA

Parameters:

properties - a DLICallProperty instance that represents input parameters for the DL/I call. See DLICall for examples of how to set the properties..

Returns:

the status code returned by IMS

Throws:

DLIException - if the operation fails

initStatusGroupB

short initStatusGroupB()
                throws DLIException

To avoid deadlock conditions(Abend u777), use INIT STATUS GROUPB. IMS will give you a status code for unavailable databases. Example: BC

Returns:

the status code returned by IMS

Throws:

DLIException - if the operation fails