com.ibm.ims.dli

Interface PCB

public interface PCB

The program communication block (PCB) interface is used to generate a SSAList based on the PCB's view of an IMS database and issue DL/I calls to IMS to retrieve, insert, update, and delete database information. The PCB is essentially a cursor position in an IMS database. To obtain a PCB handle, a PSB must first be created to connect to the database. For a code example of how to create the PSB and obtain the PCB handle, see PSB.

The PCB interface also returns the Application Interface Block (AIB) associated with the most recent DL/I call.

See Also:

AIB, PSB, SSAList

Field Summary

Fields

Modifier and Type	Field and Description
static byte[]	DBD_RESOURCE Constant indicating the requested catalog resource is a DBD resource
static byte[]	PSB_RESOURCE Constant indicating the requested catalog resource is a PSB resource

Method Summary

Modifier and Type	Method and Description
int	batchDelete(SSAList ssaList) Performs a batch delete operation in a single network call on multiple records matching a given SSAList criteria.
PathSet	batchRetrieve(SSAList ssaList) Returns a PathSet containing all records that satisfy a given SSAList criteria.
PathSet	batchRetrieve(SSAList ssaList, boolean isHoldCall) Returns a PathSet containing all records that satisfy a given SSAList criteria.
int	batchUpdate(Path path, SSAList ssaList) Performs a batch update operation in a single network call on multiple records matching a given SSAList criteria.
void	close() Closes this PCB and any resources associated with it.
int	create(ByteBuffer buffer, SSAList ssaList) Performs a DL/I insert operation.
int	create(ByteBuffer buffer, SSAList ssaList, int ioAreaUsed) Performs a DL/I insert operation.
int	create(Path path, SSAList ssaList) Performs a DL/I insert operation.
short	delete() Performs a DL/I Delete (DLET) operation to remove existing segments in the database.
short	delete(SSAList ssaList) Performs a DL/I Delete (DLET) operation to remove existing segments in the database.
AIB	getAIB() Returns the Application Interface Block associated with the most recent DL/I call
byte[]	getCatalogMetaDataAsXML(String resourceName, byte[] resourceType) This method returns a byte array containing the requested catalog resource as an XML document.
byte[]	getCatalogMetaDataAsXML(String resourceName, byte[] resourceType, String timestamp) This method returns a byte array containing the requested catalog resource as an XML document.
String	getIMSName() Returns the name of the PCB as defined by IMS
String	getName() Returns the alias/external name of the PCB
Path	getNext(boolean isHoldCall) Issues a GN (Get Next) database call.
boolean	getNext(ByteBuffer buffer, boolean isHoldCall) Issues a GN (Get Next) database call.
boolean	getNext(ByteBuffer buffer, SSAList ssaList, boolean isHoldCall) Issues a GN (Get Next) database call.
boolean	getNext(Path path, SSAList ssaList, boolean isHoldCall) Issues a GN (Get Next) database call.
Path	getNextWithinParent(boolean isHoldCall) Issues a GNP (Get Next Within Parent) database call.
boolean	getNextWithinParent(ByteBuffer buffer, boolean isHoldCall) Issues a GNP (Get Next Parent) database call.
boolean	getNextWithinParent(ByteBuffer buffer, SSAList ssaList, boolean isHoldCall) Issues a GNP (Get Next Parent) database call.
boolean	getNextWithinParent(Path path, SSAList ssaList, boolean isHoldCall) Issue a GNP (Get Next Within Parent) database call.
SSAList	getSSAList(String segment) This method returns an SSAList with a single unqualified SSA for the target segment.
SSAList	getSSAList(String topLevelSegment, String bottomLevelSegment) This method returns an SSAList that consists of unqualified SSAs from the top level segment down to the bottom level segment specified.
Path	getUnique(boolean isHoldCall) Issues a GU (Get Unique) database call.
boolean	getUnique(ByteBuffer buffer, boolean isHoldCall) Issues a GU (Get Unique) database call.
boolean	getUnique(ByteBuffer buffer, SSAList ssaList, boolean isHoldCall) Issues a GU (Get Unique) database call.
boolean	getUnique(Path path, SSAList ssaList, boolean isHoldCall) Issue a GU (Get Unique) database call.
short	insert(ByteBuffer buffer, SSAList ssaList) Issues a DL/I ISRT (Insert) call.
short	insert(ByteBuffer buffer, SSAList ssaList, int ioAreaUsed) Issues a DL/I ISRT (Insert) call.
short	insert(Path path, SSAList ssaList) Issues a DL/I ISRT (Insert) call.
short	replace(ByteBuffer buffer) Issues a DL/I REPL (Replace) call.
short	replace(ByteBuffer buffer, int ioAreaUsed) Issues a DL/I REPL (Replace) call.
short	replace(ByteBuffer buffer, SSAList ssaList) Issues a DL/I REPL (Replace) call.
short	replace(ByteBuffer buffer, SSAList ssaList, int ioAreaUsed) Issues a DL/I REPL (Replace) call.
short	replace(Path path) Issues a DL/I REPL (Replace) call.
short	replace(Path path, SSAList ssaList) Issues a DL/I REPL (Replace) call.
void	setFetchSize(int fetchSize) Gives the client a hint as to the number of rows that should be fetched from the database when more records are needed.

Field Detail

PSB_RESOURCE

static final byte[] PSB_RESOURCE

Constant indicating the requested catalog resource is a PSB resource

See Also:

getCatalogMetaDataAsXML(String, byte[])

DBD_RESOURCE

static final byte[] DBD_RESOURCE

Constant indicating the requested catalog resource is a DBD resource

See Also:

getCatalogMetaDataAsXML(String, byte[])

Method Detail

getIMSName

String getIMSName()

Returns the name of the PCB as defined by IMS

Returns:

the name of the PCB

getName

String getName()

Returns the alias/external name of the PCB

Returns:

the alias/external name of the PCB

getUnique

boolean getUnique(Path path,
                  SSAList ssaList,
                  boolean isHoldCall)
           throws DLIException

Issue a GU (Get Unique) database call. If isHoldCall is true , a GHU (Get Hold Unique) database call is issued.

The following code fragment illustrates how to use getUnique to retrieve patient records where the hospital name is "SANTA TERESA", the ward number is "44", and the number of doctors is greater than 2.

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification("WARD", "WARDNO, SSAList.EQUALS, "44");
 ssaList.appendQualification("WARD",SSAList.AND,"DOCCOUNT","SSAList.GREATER_THAN, "2");
 ssaList.addInitialQualification("HOSPITAL","HOSPNAME",SSAList.EQUALS,"SANTA TERESA");
 ssaList.markAllFieldsForRetrieval("PATIENT", true);
 Path path = ssaList.getPathForRetrieveReplace();
 pcb.getUnique(path, ssaList, true);
 

Parameters:

path - the Path to be used in the database call. It will contain the data returned from the call.

ssaList - the SSAList to be used in the database call

isHoldCall - a boolean indicating whether a hold call is required

Returns:

a boolean indicating whether data was returned

Throws:

DLIException - if an error occurs during processing

getNext

Path getNext(boolean isHoldCall)
      throws DLIException

Issues a GN (Get Next) database call. If isHoldCall is true, a GHN (Get Hold Next) database call is issued.

This method is used when the type of segment returned from the call is not known until the call is successful.

Parameters:

isHoldCall - a boolean indicating whether a hold call is required

Returns:

the Path containing the results of the database call, or null if no data was returned

Throws:

DLIException - if an error occurs during processing

getNext

boolean getNext(Path path,
                SSAList ssaList,
                boolean isHoldCall)
         throws DLIException

Issues a GN (Get Next) database call. Use this method when you don't have an SSAList. The method returns a Path to whatever segment the cursor is currently position on. If isHoldCall is true, a GHN (Get Hold Next) database call is issued.

Parameters:

path - the Path to be used in the database call. It will contain the data returned from the call.

ssaList - the SSAList to be used in the database call

isHoldCall - a boolean indicating whether a hold call is required

Returns:

a boolean indicating whether data was returned

Throws:

DLIException - if an error occurs during processing

getNextWithinParent

Path getNextWithinParent(boolean isHoldCall)
                  throws DLIException

Issues a GNP (Get Next Within Parent) database call. If isHoldCall is true, a GHNP (Get Hold Next Within Parent) database call will be issued.

This method is used when the type of segment returned from the call is not known until the call is successful.

Parameters:

isHoldCall - a boolean indicating whether a hold call is required

Returns:

the Path containing the results of the database call, or null if no data was returned

Throws:

DLIException - if an error occurs during processing

getNextWithinParent

boolean getNextWithinParent(Path path,
                            SSAList ssaList,
                            boolean isHoldCall)
                     throws DLIException

Issue a GNP (Get Next Within Parent) database call. Use this method when you don't have an SSAList. The method returns a Path to whatever segment the cursor is currently position on. If isHoldCall is true, a GHNP (Get Hold Next Within Parent) database call will be issued.

Parameters:

path - the Path to be used in the database call. It will contain the data returned from the call.

ssaList - the SSAList to be used in the database call

isHoldCall - a boolean indicating whether a hold call is required

Returns:

a boolean indicating whether data was returned

Throws:

DLIException - if an error occurs during processing

insert

short insert(Path path,
             SSAList ssaList)
      throws DLIException

Issues a DL/I ISRT (Insert) call. An exception is thrown if a key field is not set.

The following code fragment illustrates how to use insert to add a new PATIENT and ILLNESS segment in the database where the hospital name is "SANTA TERESA" and the ward number is "WARDNO2".

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "ILLNESS");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "SANTA TERESA");
 ssaList.addInitialQualification("WARD", "WARDNO", SSAList.EQUALS, "WARDNO2");
 Path path = ssaList.getPathForInsert("HOSPITAL");
 path.setString("PATIENT", "PATNUM", "PATIENTNO7");
 path.setString("PATIENT", "PATNAME", "ROCKY BALBOA");
 path.setString("ILLNAME", "APPENDICITIS");
 pcb.insert(path, ssaList);
 

Parameters:

path - the Path to be used in the database call.

ssaList - the SSAList to be used in the database call. The segment search arguments in this SSAList must be unqualified, otherwise an exception is thrown.

Returns:

the status code returned by IMS

Throws:

DLIException

replace

short replace(Path path,
              SSAList ssaList)
       throws DLIException

Issues a DL/I REPL (Replace) call. The application must obtain a SSAList and perform a Hold operation before issuing the replace call. The Hold operation can be a getUnique, getNext, or getNextWithinParent method call.

The following code fragment shows how to use the replace method to update a patient's name to "JANET BOENINGER" in patient records where the hospital name is "ALEXANDRIA". In the example, the N command code is used to omit the HOSPITAL and WARD segments in the Path instance from being updated.

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification(1,"HOSPNAME",SSAList.EQUALS,"ALEXANDRIA");

 Path path = ssaList.getPathForRetrieveReplace();
 pcb.getUnique(path, ssaList, true);
 ssaList = pcb.getSSAList("HOSPITAL", "PATIENT");
 ssaList.addCommandCode("HOSPITAL", SSAList.CC_N); // exclude the HOSPITAL segment from updates
 ssaList.addCommandCode("WARD", SSAList.CC_N); // exclude the WARD segment from updates
 
 path.setString("HOSPITAL", "HOSPNAME", "SANTA CRUZ MED"); // update is not performed
 path.setString("WARD", "WARDNAME", "COSMETIC");           // update is not performed
 path.setString("PATIENT", "PATNAME", "JANET BOENINGER");  // update is performed
 pcb.replace(path, ssaList)
 

Parameters:

path - the Path to be used in the database call.

ssaList - the SSAList to be used in the database call

Returns:

the status code returned by IMS

Throws:

DLIException - if an error occurs during processing

replace

short replace(Path path)
       throws DLIException

Issues a DL/I REPL (Replace) call. The application must obtain a SSAList and perform a Hold operation before issuing the replace call. The Hold operation can be a getUnique, getNext, or getNextWithinParent method call.

The following code fragment illustrates how to use replace to update a patient's name in patient records where the patient name is "ANDREA SMITH", the ward name is "SURGICAL", and the hospital name is "ALEXANDRIA".

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification("HOSPITAL","HOSPNAME",SSAList.EQUALS,"ALEXANDRIA");
 ssaList.addInitialQualification("WARD","WARDNAME",SSAList.EQUALS,"SURGICAL");
 ssaList.addInitialQualification("PATIENT","PATNAME",SSAList.EQUALS,"ANDREA SMITH");
 
 Path path = ssaList.getPathForRetrieveReplace();
 if (pcb.getUnique(path, ssaList, true)) {
    path.setString("PATNAME", "ANDREA TAYLOR");
    pcb.replace(path);
 }   
 while (pcb.getNext(path, ssaList, true) {
    path.setString("PATNAME", "ANDREA TAYLOR");
    pcb.replace(path);
 }
 

Parameters:

path - the Path to be used in the database call.

Returns:

the status code returned by IMS

Throws:

DLIException - if an error occurs during processing

delete

short delete(SSAList ssaList)
      throws DLIException

Performs a DL/I Delete (DLET) operation to remove existing segments in the database. The application must obtain a SSAList and perform a Hold operation before issuing the delete call. The Hold operation can be a getUnique, getNext, or getNextWithinParent method call. The delete call must be provided with an unqualified SSAList as an argument. The delete call removes the first segment that is specified by the unqualified SSAList and its child segments if any. An exception is thrown if a qualified SSAList is provided as an argument.

The following code fragment illustrates how to use the delete method to remove all ILLNESS segments and its dependent segments (TREATMNT, DOCTOR) where the patient name is "ANDREA SMITH", the ward name is "SURGICAL", the hospital name is "ALEXANDRIA", and the patient number is "PatientNo7".

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "ILLNESS");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "ALEXANDRIA");
 ssaList.addInitialQualification("WARD", "WARDNAME", SSAList.EQUALS, "SURGICAL");
 ssaList.addInitialQualification("PATIENT", "PATNAME", SSAList.EQUALS, "ANDREA SMITH");
 ssaList.markAllFieldsForRetrieval("PATIENT", true);
 Path path = ssaList.getPathForRetrieveReplace();
 SSAList illnessSSAList = pcb.getSSAList("ILLNESS");
 if (pcb.getUnique(path, ssaList, true)) {
        if (path.getString("PATIENT", "PATNUM").equals("PATIENTNO7")) {
                pcb.delete(illnessSSAList);
        }
 }
 while (pcb.getNext(path, ssaList, true)) {
        if (path.getString("PATIENT", "PATNUM").equals("PATIENTNO7")) {
                pcb.delete(illnessSSAList);
        }
 }
 

Parameters:

ssaList - the SSAList to be used in the database call

Returns:

the status code returned by IMS

Throws:

DLIException - if an error occurs during processing

delete

short delete()
      throws DLIException

Performs a DL/I Delete (DLET) operation to remove existing segments in the database. The application must obtain a SSAList and perform a Hold operation before issuing the delete call. The Hold operation can be a getUnique, getNext, or getNextWithinParent method call. The delete call removes the first segment marked for retrieval and its child segments if any. If no segments are explicitly marked for retrieval, the delete call removes the lowest level segment specified by the SSAList and its child segments.

The following code fragment illustrates how to use delete to selectively remove all PATIENT segments and its dependent segments (ILLNESS, TREATMNT, DOCTOR, BILLING) where the patient name is "ANDREA SMITH", the ward name is "SURGICAL", the hospital name is "ALEXANDRIA", and the patient number is "PatientNo7".

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "ILLNESS");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "ALEXANDRIA");
 ssaList.addInitialQualification("WARD", "WARDNAME", SSAList.EQUALS, "SURGICAL");
 ssaList.addInitialQualification("PATIENT", "PATNAME", SSAList.EQUALS, "ANDREA SMITH");
 ssaList.addCommandCode("PATIENT", SSAList.CC_D);
 Path path = ssaList.getPathForRetrieveReplace();
 if (pcb.getUnique(path, ssaList, true)) {
        if (path.getString("PATIENT", "PATNUM").equals("PATIENTNO7")) {
                pcb.delete();
        }
 }
 while (pcb.getNext(path, ssaList, true)) {
        if (path.getString("PATIENT", "PATNUM").equals("PATIENTNO7")) {
                pcb.delete();
        }
 }
 

Returns:

the status code returned by IMS

Throws:

DLIException - if an error occurs during processing

create

int create(Path path,
           SSAList ssaList)
    throws DLIException

Performs a DL/I insert operation. An exception is thrown if a key field is not set.

The following code fragment illustrates how to use create to add a new PATIENT and ILLNESS segment in the database where the hospital name is "SANTA TERESA" and the ward number is "WARDNO2".

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "ILLNESS");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "SANTA TERESA");
 ssaList.addInitialQualification("WARD", "WARDNO", SSAList.EQUALS, "WARDNO2");
 Path path = ssaList.getPathForInsert("HOSPITAL");
 path.setString("PATIENT", "PATNUM", "PATIENTNO7");
 path.setString("PATIENT", "PATNAME", "ROCKY BALBOA");
 path.setString("ILLNAME", "APPENDICITIS");
 pcb.create(path, ssaList);
 

Parameters:

path - the Path to be used in the database call.

ssaList - the SSAList to be used in the database call. The segment search arguments in this SSAList must be unqualified, otherwise an exception is thrown.

Returns:

the number of rows inserted. For now, this will always return 1.

Throws:

DLIException

batchRetrieve

PathSet batchRetrieve(SSAList ssaList)
               throws DLIException

Returns a PathSet containing all records that satisfy a given SSAList criteria. In a batch retrieve operation, the host will do all of the GHU/GHN processing and will deliver results back to the client in a single batch network operation. Note that the fetch size determines how much data is sent back on each batch network operation.

The following code fragment illustrates how to use batchRetrieve to retrieve all PATIENT segments in the Hospital database.

 SSAList ssaList = pcb.getSSAList("PATIENT");
 PathSet pathSet = pcb.batchRetrieve(ssaList);
 while (pathSet.hasNext()) {
        Path path = pathSet.next();
        String fieldValue = path.getString("PATIENT", "PATNAME");
 }
 

Parameters:

ssaList - the SSAList to be used in the database call

Returns:

the PathSet containing the results of the database call, or null if no data was returned

Throws:

DLIException - if an error occurs during processing

See Also:

PathSet

batchRetrieve

PathSet batchRetrieve(SSAList ssaList,
                      boolean isHoldCall)
               throws DLIException

Returns a PathSet containing all records that satisfy a given SSAList criteria. In a batch retrieve operation, the host will do all of the GU/GN (or GHU/GHN) processing and will deliver results back to the client in a single batch network operation. Note that the fetch size determines how much data is sent back on each batch network operation.

The following code fragment illustrates how to use batchRetrieve to retrieve all PATIENT segments in the Hospital database.

 SSAList ssaList = pcb.getSSAList("PATIENT");
 PathSet pathSet = pcb.batchRetrieve(ssaList, true);
 while (pathSet.hasNext()) {
        Path path = pathSet.next();
        String fieldValue = path.getString("PATIENT", "PATNAME");
 }
 

Parameters:

ssaList - the SSAList to be used in the database call

isHoldCall - if true, GHU/GHN processing is used. if false, GU/GN processing is used.

Returns:

the PathSet containing the results of the database call, or null if no data was returned

Throws:

DLIException - if an error occurs during processing

See Also:

PathSet

batchUpdate

int batchUpdate(Path path,
                SSAList ssaList)
         throws DLIException

Performs a batch update operation in a single network call on multiple records matching a given SSAList criteria. In a batch update operation, the host will do a GU/GN loop and inside the loop perform the updates until there are no more segments to update and then return the number of records updated.

The following code fragment illustrates how to use batchUpdate to modify a patient's name. The SSAList is set to update only records where the patient name is "ANDREA SMITH", the ward name is "SURGICAL", and the hospital name is "ALEXANDRIA". The SSAList.getPathForBatchUpdate method is called to obtain a Path contaning the PATIENT segment and its child segments. Finally, batchUpdate is called to change the value of the patient name field to "ANDREA TAYLOR".

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "PATIENT");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "ALEXANDRIA");
 ssaList.addInitialQualification("WARD", "WARDNAME", SSAList.EQUALS, "SURGICAL");
 ssaList.addInitialQualification("PATIENT", "PATNAME", SSAList.EQUALS, "ANDREA SMITH");
 Path path = ssaList.getPathForBatchUpdate("PATIENT");
 path.setString("PATNAME", "ANDREA TAYLOR");
 pcb.batchUpdate(path, ssaList);
 

Parameters:

path - the Path to be used in the database call.

ssaList - the SSAList to be used in the database call

Returns:

the number of rows updated

Throws:

DLIException - if an error occurs during processing

See Also:

SSAList.getPathForBatchUpdate(String)

batchDelete

int batchDelete(SSAList ssaList)
         throws DLIException

Performs a batch delete operation in a single network call on multiple records matching a given SSAList criteria. In a batch delete operation, the host will do a GU/GN loop and inside the loop delete each record until there are no more segments matching the SSAList and return the number of records deleted.

The following code fragment illustrates how to use batchDelete to remove a patient's records. The SSAList is set to restrict the deletion operation to remove only records where the patient name is "ANDREA SMITH", the ward name is "SURGICAL", and the hospital name is "ALEXANDRIA". The records are deleted by calling batchDelete.

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "PATIENT");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "ALEXANDRIA");
 ssaList.addInitialQualification("WARD", "WARDNAME", SSAList.EQUALS, "SURGICAL");
 ssaList.addInitialQualification("PATIENT", "PATNAME", SSAList.EQUALS, "ANDREA SMITH");
 pcb.batchDelete(ssaList);
 

Parameters:

ssaList - the SSAList to be used in the database call

Returns:

the number of rows deleted

Throws:

DLIException - if an error occurs during processing

getSSAList

SSAList getSSAList(String topLevelSegment,
                   String bottomLevelSegment)
            throws DLIException

This method returns an SSAList that consists of unqualified SSAs from the top level segment down to the bottom level segment specified.

Parameters:

topLevelSegment - the top level segment to be included in the SSAList

bottomLevelSegment - the bottom level segment to be included in the SSAList

Returns:

the SSAList

Throws:

DLIException - if an error occurs during processing

getSSAList

SSAList getSSAList(String segment)
            throws DLIException

This method returns an SSAList with a single unqualified SSA for the target segment.

Parameters:

segment - the name of the segment that the SSAList will represent

Returns:

the SSAList

Throws:

DLIException - if an error occurs during processing

setFetchSize

void setFetchSize(int fetchSize)

Gives the client a hint as to the number of rows that should be fetched from the database when more records are needed. The number of rows ( Path objects) specified affects only data returned using this PCB. If the value specified is zero or negative, the hint is ignored.

Parameters:

fetchSize - the number of rows to fetch

See Also:

batchRetrieve(SSAList)

getAIB

AIB getAIB()

Returns the Application Interface Block associated with the most recent DL/I call

Returns:

the AIB

close

void close()
    throws DLIException

Closes this PCB and any resources associated with it.

Throws:

DLIException - if an error occurs during processing

getCatalogMetaDataAsXML

byte[] getCatalogMetaDataAsXML(String resourceName,
                               byte[] resourceType)
                        throws DLIException

This method returns a byte array containing the requested catalog resource as an XML document.

Parameters:

resourceName - the name of the PSB or DBD resource in the catalog

resourceType - the type of resource (PCB.PSB_RESOURCE or PCB.DBD_RESOURCE)

Returns:

the resource metadata in XML

Throws:

DLIException - if the resource was not found in the catalog or an error occurs during processing

See Also:

PSB_RESOURCE, DBD_RESOURCE

getCatalogMetaDataAsXML

byte[] getCatalogMetaDataAsXML(String resourceName,
                               byte[] resourceType,
                               String timestamp)
                        throws DLIException

This method returns a byte array containing the requested catalog resource as an XML document.

The following code fragment illustrates how to retrieve the timestamp (TSVERS) value from the IMS Catalog.

 PCB pcb = psb.getPCB("DFSCAT00");
 SSAList ssaList = pcb.getSSAList("HEADER", "DBD");
 Path path = ssaList.getPathForRetrieveReplace();
 pcb.getUnique(path, ssaList, false);
 String timestamp = path.getString("TSVERS");
 

Parameters:

resourceName - the name of the PSB or DBD resource in the catalog

resourceType - the type of resource (PCB.PSB_RESOURCE or PCB.DBD_RESOURCE)

timestamp - the TSVERS version for the resource following the pattern yyDDDHHmmssff

Returns:

the resource metadata in XML

Throws:

DLIException - if the resource was not found in the catalog or an error occurs during processing

See Also:

PSB_RESOURCE, DBD_RESOURCE

getUnique

boolean getUnique(ByteBuffer buffer,
                  SSAList ssaList,
                  boolean isHoldCall)
           throws DLIException

Issues a GU (Get Unique) database call. If isHoldCall is true , a GHU (Get Hold Unique) database call is issued.

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

The following code fragment illustrates how to use getUnique to retrieve patient records where the hospital name is "SANTA TERESA", the ward number is "44", and the number of doctors is greater than 2.

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification("WARD", "WARDNO, SSAList.EQUALS, "44");
 ssaList.appendQualification("WARD",SSAList.AND,"DOCCOUNT","SSAList.GREATER_THAN, "2");
 ssaList.addInitialQualification("HOSPITAL","HOSPNAME",SSAList.EQUALS,"SANTA TERESA");
 ssaList.markAllFieldsForRetrieval("PATIENT", true);
 ByteBuffer buffer = ByteBuffer.allocate(40);
 pcb.getUnique(buffer, ssaList, true);
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data returned from the call.

ssaList - the SSAList to be used in the database call

isHoldCall - a boolean indicating whether a hold call is required

Returns:

a boolean indicating whether data was returned

Throws:

DLIException - if an error occurs during processing

getUnique

boolean getUnique(ByteBuffer buffer,
                  boolean isHoldCall)
           throws DLIException

Issues a GU (Get Unique) database call. If isHoldCall is true, a GHU (Get Hold Unique) database call is issued.

This method is used when the type of segment returned from the call is not known until the call is successful.

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data returned from the call.

isHoldCall - a boolean indicating whether a hold call is required

Returns:

the Path containing the results of the database call, or null if no data was returned

Throws:

DLIException - if an error occurs during processing

getUnique

Path getUnique(boolean isHoldCall)
        throws DLIException

Issues a GU (Get Unique) database call. If isHoldCall is true, a GHU (Get Hold Unique) database call is issued.

This method is used when the type of segment returned from the call is not known until the call is successful.

Parameters:

isHoldCall - a boolean indicating whether a hold call is required

Returns:

the Path containing the results of the database call, or null if no data was returned

Throws:

DLIException - if an error occurs during processing

getNext

boolean getNext(ByteBuffer buffer,
                SSAList ssaList,
                boolean isHoldCall)
         throws DLIException

Issues a GN (Get Next) database call. If isHoldCall is true , a GHN (Get Hold Next) database call is issued.

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

The following code fragment illustrates how to use getNext to retrieve patient records where the hospital name is "SANTA TERESA", the ward number is "44", and the number of doctors is greater than 2.

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification("WARD", "WARDNO, SSAList.EQUALS, "44");
 ssaList.appendQualification("WARD",SSAList.AND,"DOCCOUNT","SSAList.GREATER_THAN, "2");
 ssaList.addInitialQualification("HOSPITAL","HOSPNAME",SSAList.EQUALS,"SANTA TERESA");
 ssaList.markAllFieldsForRetrieval("PATIENT", true);
 ByteBuffer buffer = ByteBuffer.allocate(40);
 pcb.getNext(buffer, ssaList, true);
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data returned from the call.

ssaList - the SSAList to be used in the database call

isHoldCall - a boolean indicating whether a hold call is required

Returns:

a boolean indicating whether data was returned

Throws:

DLIException - if an error occurs during processing

getNext

boolean getNext(ByteBuffer buffer,
                boolean isHoldCall)
         throws DLIException

Issues a GN (Get Next) database call. If isHoldCall is true, a GHN (Get Hold Next) database call is issued.

This method is used when the type of segment returned from the call is not known until the call is successful.

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data returned from the call.

isHoldCall - a boolean indicating whether a hold call is required

Returns:

the Path containing the results of the database call, or null if no data was returned

Throws:

DLIException - if an error occurs during processing

getNextWithinParent

boolean getNextWithinParent(ByteBuffer buffer,
                            SSAList ssaList,
                            boolean isHoldCall)
                     throws DLIException

Issues a GNP (Get Next Parent) database call. If isHoldCall is true , a GHNP (Get Hold Next Parent) database call is issued.

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

The following code fragment illustrates how to use getNextWithinParrent to retrieve patient records where the hospital name is "SANTA TERESA", the ward number is "44", and the number of doctors is greater than 2.

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification("WARD", "WARDNO, SSAList.EQUALS, "44");
 ssaList.appendQualification("WARD",SSAList.AND,"DOCCOUNT","SSAList.GREATER_THAN, "2");
 ssaList.addInitialQualification("HOSPITAL","HOSPNAME",SSAList.EQUALS,"SANTA TERESA");
 ssaList.markAllFieldsForRetrieval("PATIENT", true);
 ByteBuffer buffer = ByteBuffer.allocate(40);
 pcb.getNextWithinParent(buffer, ssaList, true);
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data returned from the call.

ssaList - the SSAList to be used in the database call

isHoldCall - a boolean indicating whether a hold call is required

Returns:

a boolean indicating whether data was returned

Throws:

DLIException - if an error occurs during processing

getNextWithinParent

boolean getNextWithinParent(ByteBuffer buffer,
                            boolean isHoldCall)
                     throws DLIException

Issues a GNP (Get Next Parent) database call. If isHoldCall is true, a GHN (Get Hold Next Parent) database call is issued.

This method is used when the type of segment returned from the call is not known until the call is successful.

Uses a ByteBuffer as the output object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data returned from the call.

isHoldCall - a boolean indicating whether a hold call is required

Returns:

the Path containing the results of the database call, or null if no data was returned

Throws:

DLIException - if an error occurs during processing

insert

short insert(ByteBuffer buffer,
             SSAList ssaList)
      throws DLIException

Issues a DL/I ISRT (Insert) call. An exception is thrown if a key field is not set.

Uses a ByteBuffer as the input object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

The following code fragment illustrates how to use insert to add a new PATIENT and ILLNESS segment in the database where the hospital name is "SANTA TERESA" and the ward number is "WARDNO2".

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "ILLNESS");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "SANTA TERESA");
 ssaList.addInitialQualification("WARD", "WARDNO", SSAList.EQUALS, "WARDNO2");
 ByteBuffer buffer = ByteBuffer.allocate(900);
 buffer.put("PATIENTN07".getBytes("Cp1047")
 buffer.put("ROCKY BALBOA".getBytes("Cp1047")
 buffer.put("APPENDICITIS".getBytes("Cp1047")
 pcb.insert(buffer, ssaList);
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data to send to IMS

ssaList - the SSAList to be used in the database call. The segment search arguments in this SSAList must be unqualified, otherwise an exception is thrown.

Returns:

the status code returned by IMS

Throws:

DLIException

insert

short insert(ByteBuffer buffer,
             SSAList ssaList,
             int ioAreaUsed)
      throws DLIException

Issues a DL/I ISRT (Insert) call. An exception is thrown if a key field is not set.

Uses a ByteBuffer as the input object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

The following code fragment illustrates how to use insert to add a new PATIENT and ILLNESS segment in the database where the hospital name is "SANTA TERESA" and the ward number is "WARDNO2".

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "ILLNESS");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "SANTA TERESA");
 ssaList.addInitialQualification("WARD", "WARDNO", SSAList.EQUALS, "WARDNO2");
 ByteBuffer buffer = ByteBuffer.allocate(900);
 buffer.put("PATIENTN07".getBytes("Cp1047")
 buffer.put("ROCKY BALBOA".getBytes("Cp1047")
 buffer.put("APPENDICITIS".getBytes("Cp1047")
 pcb.insert(buffer, ssaList, 50);
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data to send to IMS

ssaList - the SSAList to be used in the database call. The segment search arguments in this SSAList must be unqualified, otherwise an exception is thrown.

ioAreaUsed - the int to be used to specify how much of the ByteBuffer's capacity should be processed for insert

Returns:

the status code returned by IMS

Throws:

DLIException

create

int create(ByteBuffer buffer,
           SSAList ssaList)
    throws DLIException

Performs a DL/I insert operation. An exception is thrown if a key field is not set.

Uses a ByteBuffer as the input object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

The following code fragment illustrates how to use insert to add a new PATIENT and ILLNESS segment in the database where the hospital name is "SANTA TERESA" and the ward number is "WARDNO2".

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "ILLNESS");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "SANTA TERESA");
 ssaList.addInitialQualification("WARD", "WARDNO", SSAList.EQUALS, "WARDNO2");
 ByteBuffer buffer = ByteBuffer.allocate(900);
 buffer.put("PATIENTN07".getBytes("Cp1047")
 buffer.put("ROCKY BALBOA".getBytes("Cp1047")
 buffer.put("APPENDICITIS".getBytes("Cp1047")
 pcb.create(buffer, ssaList);
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data to send to IMS

ssaList - the SSAList to be used in the database call. The segment search arguments in this SSAList must be unqualified, otherwise an exception is thrown.

Returns:

the status code returned by IMS

Throws:

DLIException

create

int create(ByteBuffer buffer,
           SSAList ssaList,
           int ioAreaUsed)
    throws DLIException

Performs a DL/I insert operation. An exception is thrown if a key field is not set.

Uses a ByteBuffer as the input object. The ByteBuffer object can be either direct or non-direct. If running in a 64-bit JVM and require the use of a Direct ByteBuffer, a 31-bit ByteBuffer will need to be allocated. See Application#get31BitDirectByteBuffer(Int)

The following code fragment illustrates how to use insert to add a new PATIENT and ILLNESS segment in the database where the hospital name is "SANTA TERESA" and the ward number is "WARDNO2".

 SSAList ssaList = pcb.getSSAList("HOSPITAL", "ILLNESS");
 ssaList.addInitialQualification("HOSPITAL", "HOSPNAME", SSAList.EQUALS, "SANTA TERESA");
 ssaList.addInitialQualification("WARD", "WARDNO", SSAList.EQUALS, "WARDNO2");
 ByteBuffer buffer = ByteBuffer.allocate(900);
 buffer.put("PATIENTN07".getBytes("Cp1047")
 buffer.put("ROCKY BALBOA".getBytes("Cp1047")
 buffer.put("APPENDICITIS".getBytes("Cp1047")
 pcb.create(buffer, ssaList, 50);
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data to send to IMS

ssaList - the SSAList to be used in the database call. The segment search arguments in this SSAList must be unqualified, otherwise an exception is thrown.

ioAreaUsed - the int to be used to specify how much of the ByteBuffer's capacity should be processed for insert

Returns:

the status code returned by IMS

Throws:

DLIException

replace

short replace(ByteBuffer buffer,
              SSAList ssaList)
       throws DLIException

Issues a DL/I REPL (Replace) call. The application must obtain a SSAList and perform a Hold operation before issuing the replace call. The Hold operation can be a getUnique, getNext, or getNextWithinParent method call.

The following code fragment shows how to use the replace method to update a patient's name to "JANET BOENINGER" in patient records where the hospital name is "ALEXANDRIA". In the example, the N command code is used to omit the HOSPITAL and WARD segments in the Path instance from being updated.

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification(1,"HOSPNAME",SSAList.EQUALS,"ALEXANDRIA");

 Path path = ssaList.getPathForRetrieveReplace();
 pcb.getUnique(path, ssaList, true);
 ssaList = pcb.getSSAList("HOSPITAL", "PATIENT");
 ssaList.addCommandCode("HOSPITAL", SSAList.CC_N); // exclude the HOSPITAL segment from updates
 ssaList.addCommandCode("WARD", SSAList.CC_N); // exclude the WARD segment from updates
 
 ByteBuffer buffer = ByteBuffer.allocate(2700);
 buffer.put("SANTA CRUZ MED".getBytes(Cp1047)); // update is not performed (part of segment Hospital)
 buffer.position(900);
 buffer.put("COSMETIC".getBytes(Cp1047));       // update is not performed (part of segment WARD)
 buffer.postion(1800);
 buffer.put("JANET BOENINGER".getBytes(Cp1047));// update is performed
 pcb.replace(buffer, ssaList);
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data to send to IMS

ssaList - the SSAList to be used in the database call

Returns:

the status code returned by IMS

Throws:

DLIException - if an error occurs during processing

replace

short replace(ByteBuffer buffer,
              SSAList ssaList,
              int ioAreaUsed)
       throws DLIException

Issues a DL/I REPL (Replace) call. The application must obtain a SSAList and perform a Hold operation before issuing the replace call. The Hold operation can be a getUnique, getNext, or getNextWithinParent method call.

The following code fragment shows how to use the replace method to update a patient's name to "JANET BOENINGER" in patient records where the hospital name is "ALEXANDRIA". In the example, the N command code is used to omit the HOSPITAL and WARD segments in the Path instance from being updated.

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification(1,"HOSPNAME",SSAList.EQUALS,"ALEXANDRIA");

 Path path = ssaList.getPathForRetrieveReplace();
 pcb.getUnique(path, ssaList, true);
 ssaList = pcb.getSSAList("HOSPITAL", "PATIENT");
 ssaList.addCommandCode("HOSPITAL", SSAList.CC_N); // exclude the HOSPITAL segment from updates
 ssaList.addCommandCode("WARD", SSAList.CC_N); // exclude the WARD segment from updates
 
 ByteBuffer buffer = ByteBuffer.allocate(5000);
 buffer.put("SANTA CRUZ MED".getBytes(Cp1047)); // update is not performed (part of segment Hospital)
 buffer.position(900);
 buffer.put("COSMETIC".getBytes(Cp1047));       // update is not performed (part of segment WARD)
 buffer.postion(1800);
 buffer.put("JANET BOENINGER".getBytes(Cp1047));// update is performed
 pcb.replace(buffer, ssaList, 2700);
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data to send to IMS

ssaList - the SSAList to be used in the database call

ioAreaUsed - the int to be used to specify how much of the ByteBuffer's capacity should be processed for insert

Returns:

the status code returned by IMS

Throws:

DLIException - if an error occurs during processing

replace

short replace(ByteBuffer buffer)
       throws DLIException

Issues a DL/I REPL (Replace) call. The application must obtain a SSAList and perform a Hold operation before issuing the replace call. The Hold operation can be a getUnique, getNext, or getNextWithinParent method call.

The following code fragment illustrates how to use replace to update a patient's name in patient records where the patient name is "ANDREA SMITH", the ward name is "SURGICAL", and the hospital name is "ALEXANDRIA".

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification("HOSPITAL","HOSPNAME",SSAList.EQUALS,"ALEXANDRIA");
 ssaList.addInitialQualification("WARD","WARDNAME",SSAList.EQUALS,"SURGICAL");
 ssaList.addInitialQualification("PATIENT","PATNAME",SSAList.EQUALS,"ANDREA SMITH");
 
 ByteBuffer buffer = ByteBuffer.allocate(900);
 if (pcb.getUnique(buffer, ssaList, true)) {
          buffer.position(10);
    buffer.put("ANDREA TAYLOR".getBytes(Cp1047));
    pcb.replace(buffer);
 }   
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data to send to IMS

Returns:

the status code returned by IMS

Throws:

DLIException - if an error occurs during processing

replace

short replace(ByteBuffer buffer,
              int ioAreaUsed)
       throws DLIException

Issues a DL/I REPL (Replace) call. The application must obtain a SSAList and perform a Hold operation before issuing the replace call. The Hold operation can be a getUnique, getNext, or getNextWithinParent method call.

The following code fragment illustrates how to use replace to update a patient's name in patient records where the patient name is "ANDREA SMITH", the ward name is "SURGICAL", and the hospital name is "ALEXANDRIA".

 SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
 ssaList.addInitialQualification("HOSPITAL","HOSPNAME",SSAList.EQUALS,"ALEXANDRIA");
 ssaList.addInitialQualification("WARD","WARDNAME",SSAList.EQUALS,"SURGICAL");
 ssaList.addInitialQualification("PATIENT","PATNAME",SSAList.EQUALS,"ANDREA SMITH");
 
 ByteBuffer buffer = ByteBuffer.allocate(900);
 if (pcb.getUnique(buffer, ssaList, true)) {
          buffer.position(10);
    buffer.put("ANDREA TAYLOR".getBytes(Cp1047));
    pcb.replace(buffer, 50);
 }   
 

Parameters:

buffer - the ByteBuffer to be used in the database call. It will contain the data to send to IMS

ioAreaUsed - the int to be used to specify how much of the ByteBuffer's capacity should be processed for insert

Returns:

the status code returned by IMS

Throws:

DLIException - if an error occurs during processing