Package com.ibm.cics.server

Class KeyedFileBrowse

java.lang.Object

com.ibm.cics.server.API

com.ibm.cics.server.FileBrowse

com.ibm.cics.server.KeyedFileBrowse

Direct Known Subclasses:

ESDS_Browse

public class KeyedFileBrowse
extends FileBrowse

This class implements browsing a keyed file.

See Also:

• com.ibm.cics.server.API for general restrictions on using the JCICS API.

Since CICS TS version:

1.3

Method Summary

Modifier and Type	Method	Description
void	next(byte[] inputKey, RecordHolder record, KeyHolder outputKey)	Read the next record during a browse, changing the current position.
void	next(RecordHolder record, KeyHolder outputKey)	Read the next record during a browse.
void	previous(byte[] inputKey, RecordHolder record, KeyHolder outputKey)	Read the previous record during a browse, changing the current position.
void	previous(RecordHolder record, KeyHolder outputKey)	Read the previous record during a browse.
void	reset(byte[] key)	Reset the browse.
void	reset(byte[] key, boolean generic)	Reset the browse.
void	reset(byte[] key, boolean generic, SearchType theSearchType)	Reset the browse.
void	reset(byte[] key, SearchType theSearchType)	Reset the browse.

Methods inherited from class com.ibm.cics.server.FileBrowse

end, getRequestID

Methods inherited from class com.ibm.cics.server.API

getCICSServerApiVersion

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

next

public void next(byte[] inputKey,
 RecordHolder record,
 KeyHolder outputKey)
          throws FileDisabledException,
DuplicateKeyException,
EndOfFileException,
FileNotFoundException,
LogicException,
InvalidRequestException,
IOErrorException,
ISCInvalidRequestException,
LengthErrorException,
NotAuthorisedException,
RecordNotFoundException,
NotOpenException,
InvalidSystemIdException,
ChangedException,
LockedException,
LoadingException

Read the next record during a browse, changing the current position.

Parameters:

inputKey - The (possibly generic) key of the record at which to (re)start the browse.

record - The record read

outputKey - The key of the record read

Throws:

FileDisabledException - The file is disabled.

DuplicateKeyException - This exception is thrown if a record is retrieved by way of an alternate index that supports non-unique keys, and another alternate index record with the same key follows. It does not occur as a result of a next() call that reads the last of the records having the non-unique key.

EndOfFileException - This exception is thrown if an end-of-file condition is detected during the browse.

FileNotFoundException - The file is not defined in the File Definitions (FD).

LogicException - An error not covered by any other exception occurred.

InvalidRequestException - This exception is thrown for the following reasons:

• A browse has not been started on the file
• A browse through a different interface is already in progress on the file

IOErrorException - This exception is thrown if there is an I/O error during the file control operation.

ISCInvalidRequestException - This exception is thrown if the remote system indicates a failure that does not correspond to a known condition.

LengthErrorException - This exception is thrown if an incorrect length is specified for a file with fixed-length records

NotAuthorisedException - This exception is thrown for the following reasons:

• When a resource security check is unsuccessful on the file.
• When the file is constructed with a SYSID and the current transaction is defined with the RSLCheck attribute set to either internal or external.

RecordNotFoundException - This exception is thrown if an attempt is made to start the browse positioned on a record which cannot be found.

NotOpenException - This exception is thrown for the following reasons:

• When the file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
• When the file is OPEN and in use by other transactions, but a CLOSE request has been received. Current activity is allowed to complete, but no new activity is allowed to start.

InvalidSystemIdException - This exception is thrown if the named connection cannot be found in the Communications Definitions (CD).

LoadingException - LOADING

LockedException - LOCKED

ChangedException - CHANGED

Since CICS TS version:

1.3

next

public void next(RecordHolder record,
 KeyHolder outputKey)
          throws FileDisabledException,
DuplicateKeyException,
EndOfFileException,
FileNotFoundException,
LogicException,
InvalidRequestException,
IOErrorException,
ISCInvalidRequestException,
LengthErrorException,
NotAuthorisedException,
RecordNotFoundException,
NotOpenException,
InvalidSystemIdException,
ChangedException,
LockedException,
LoadingException

Read the next record during a browse.

Parameters:

record - The record read

outputKey - The key of the record read

Throws:

FileDisabledException - The file is disabled.

DuplicateKeyException - This exception is thrown if a record is retrieved by way of an alternate index that supports non-unique keys, and another alternate index record with the same key follows. It does not occur as a result of a next() call that reads the last of the records having the non-unique key.

EndOfFileException - This exception is thrown if an end-of-file condition is detected during the browse.

FileNotFoundException - The file is not defined in the File Definitions (FD).

LogicException - An error not covered by any other exception occurred.

InvalidRequestException - This exception is thrown for the following reasons:

• A browse has not been started on the file
• A browse through a different interface is already in progress on the file

IOErrorException - This exception is thrown if there is an I/O error during the file control operation.

ISCInvalidRequestException - This exception is thrown if the remote system indicates a failure that does not correspond to a known condition.

LengthErrorException - This exception is thrown if an incorrect length is specified for a file with fixed-length records

NotAuthorisedException - This exception is thrown for the following reasons:

• When a resource security check is unsuccessful on the file.
• When the file is constructed with a SYSID and the current transaction is defined with the RSLCheck attribute set to either internal or external.

RecordNotFoundException - This exception is thrown if an attempt is made to start the browse positioned on a record which cannot be found.

NotOpenException - This exception is thrown for the following reasons:

• When the file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
• When the file is OPEN and in use by other transactions, but a CLOSE request has been received. Current activity is allowed to complete, but no new activity is allowed to start.

InvalidSystemIdException - This exception is thrown if the named connection cannot be found in the Communications Definitions (CD).

LoadingException - LOADING

LockedException - LOCKED

ChangedException - CHANGED

Since CICS TS version:

1.3

previous

public void previous(byte[] inputKey,
 RecordHolder record,
 KeyHolder outputKey)
              throws FileDisabledException,
DuplicateKeyException,
EndOfFileException,
FileNotFoundException,
LogicException,
InvalidRequestException,
IOErrorException,
ISCInvalidRequestException,
LengthErrorException,
NotAuthorisedException,
RecordNotFoundException,
NotOpenException,
InvalidSystemIdException,
ChangedException,
LockedException,
LoadingException

Read the previous record during a browse, changing the current position.

Parameters:

inputKey - The (possibly generic) key of the record at which to (re)start the browse.

record - The record read

outputKey - The key of the record read

Throws:

FileDisabledException - The file is disabled.

DuplicateKeyException - This exception is thrown if a record is retrieved by way of an alternate index that supports non-unique keys, and another alternate index record with the same key follows. It does not occur as a result of a previous() call that reads the last of the records having the non-unique key.

EndOfFileException - This exception is thrown if an end-of-file condition is detected during the browse.

FileNotFoundException - The file is not defined in the File Definitions (FD).

LogicException - An error not covered by any other exception occurred.

InvalidRequestException - This exception is thrown for the following reasons:

• A browse has not been started on the file
• A browse through a different interface is already in progress on the file

IOErrorException - This exception is thrown if there is an I/O error during the file control operation.

ISCInvalidRequestException - This exception is thrown if the remote system indicates a failure that does not correspond to a known condition.

LengthErrorException - This exception is thrown if an incorrect length is specified for a file with fixed-length records

NotAuthorisedException - This exception is thrown for the following reasons:

• When a resource security check is unsuccessful on the file.
• When the file is constructed with a SYSID and the current transaction is defined with the RSLCheck attribute set to either internal or external.

RecordNotFoundException - This exception is thrown if an attempt is made to start the browse positioned on a record which cannot be found.

NotOpenException - This exception is thrown for the following reasons:

• When the file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
• When the file is OPEN and in use by other transactions, but a CLOSE request has been received. Current activity is allowed to complete, but no new activity is allowed to start.

InvalidSystemIdException - This exception is thrown if the named connection cannot be found in the Communications Definitions (CD).

LoadingException - LOADING

LockedException - LOCKED

ChangedException - CHANGED

Since CICS TS version:

1.3

previous

public void previous(RecordHolder record,
 KeyHolder outputKey)
              throws FileDisabledException,
DuplicateKeyException,
EndOfFileException,
FileNotFoundException,
LogicException,
InvalidRequestException,
IOErrorException,
ISCInvalidRequestException,
LengthErrorException,
NotAuthorisedException,
RecordNotFoundException,
NotOpenException,
InvalidSystemIdException,
ChangedException,
LockedException,
LoadingException

Read the previous record during a browse.

Parameters:

record - The record read

outputKey - The key of the record read

Throws:

FileDisabledException - The file is disabled.

DuplicateKeyException - This exception is thrown if a record is retrieved by way of an alternate index that supports non-unique keys, and another alternate index record with the same key follows. It does not occur as a result of a previous() call that reads the last of the records having the non-unique key.

EndOfFileException - This exception is thrown if an end-of-file condition is detected during the browse.

FileNotFoundException - The file is not defined in the File Definitions (FD).

LogicException - An error not covered by any other exception occurred.

InvalidRequestException - This exception is thrown for the following reasons:

• A browse has not been started on the file
• A browse through a different interface is already in progress on the file

IOErrorException - This exception is thrown if there is an I/O error during the file control operation.

ISCInvalidRequestException - This exception is thrown if the remote system indicates a failure that does not correspond to a known condition.

LengthErrorException - This exception is thrown if an incorrect length is specified for a file with fixed-length records

NotAuthorisedException - This exception is thrown for the following reasons:

• When a resource security check is unsuccessful on the file.
• When the file is constructed with a SYSID and the current transaction is defined with the RSLCheck attribute set to either internal or external.

RecordNotFoundException - This exception is thrown if an attempt is made to start the browse positioned on a record which cannot be found.

NotOpenException - This exception is thrown for the following reasons:

• When the file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
• When the file is OPEN and in use by other transactions, but a CLOSE request has been received. Current activity is allowed to complete, but no new activity is allowed to start.

InvalidSystemIdException - This exception is thrown if the named connection cannot be found in the Communications Definitions (CD).

LoadingException - LOADING

LockedException - LOCKED

ChangedException - CHANGED

Since CICS TS version:

1.3

reset

public void reset(byte[] key)
           throws FileDisabledException,
FileNotFoundException,
LogicException,
InvalidRequestException,
IOErrorException,
ISCInvalidRequestException,
NotAuthorisedException,
RecordNotFoundException,
NotOpenException,
InvalidSystemIdException,
ChangedException,
LockedException,
LoadingException

Reset the browse. This version resets the type of browse to a searchType of GTEQ and to be the opposite of GENERIC.

Parameters:

key - The key of the record at which to restart the browse.

Throws:

FileDisabledException - The file is disabled.

FileNotFoundException - The file is not defined in the File Definitions (FD).

LogicException - An error not covered by any other exception occurred.

InvalidRequestException - This exception is thrown for the following reasons:

• A browse has not been started on the file
• A browse through a different interface is already in progress on the file

IOErrorException - This exception is thrown if there is an I/O error during the file control operation.

ISCInvalidRequestException - This exception is thrown if the remote system indicates a failure that does not correspond to a known condition.

NotAuthorisedException - This exception is thrown for the following reasons:

• When a resource security check is unsuccessful on the file.
• When the file is constructed with a SYSID and the current transaction is defined with the RSLCheck attribute set to either internal or external.

RecordNotFoundException - This exception is thrown if an attempt is made to start the browse positioned on a record which cannot be found.

NotOpenException - This exception is thrown for the following reasons:

• When the file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
• When the file is OPEN and in use by other transactions, but a CLOSE request has been received. Current activity is allowed to complete, but no new activity is allowed to start.

InvalidSystemIdException - This exception is thrown if the named connection cannot be found in the Communications Definitions (CD).

LoadingException - LOADING

LockedException - LOCKED

ChangedException - CHANGED

Since CICS TS version:

1.3

reset

public void reset(byte[] key,
 SearchType theSearchType)
           throws FileDisabledException,
FileNotFoundException,
LogicException,
InvalidRequestException,
IOErrorException,
ISCInvalidRequestException,
NotAuthorisedException,
RecordNotFoundException,
NotOpenException,
InvalidSystemIdException,
ChangedException,
LockedException,
LoadingException

Reset the browse. This version resets the type of browse to a specified searchType and to be the opposite of GENERIC.

Parameters:

key - The key of the record at which to restart the browse.

theSearchType - A value specifying the type of search to use. Possible values are:

• EQUAL
• GTEQ

Any other value defaults to GTEQ.

Throws:

FileDisabledException - The file is disabled.

FileNotFoundException - The file is not defined in the File Definitions (FD).

LogicException - An error not covered by any other exception occurred.

InvalidRequestException - This exception is thrown for the following reasons:

• A browse has not been started on the file
• A browse through a different interface is already in progress on the file

IOErrorException - This exception is thrown if there is an I/O error during the file control operation.

ISCInvalidRequestException - This exception is thrown if the remote system indicates a failure that does not correspond to a known condition.

NotAuthorisedException - This exception is thrown for the following reasons:

• When a resource security check is unsuccessful on the file.
• When the file is constructed with a SYSID and the current transaction is defined with the RSLCheck attribute set to either internal or external.

RecordNotFoundException - This exception is thrown if an attempt is made to start the browse positioned on a record which cannot be found.

NotOpenException - This exception is thrown for the following reasons:

• When the file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
• When the file is OPEN and in use by other transactions, but a CLOSE request has been received. Current activity is allowed to complete, but no new activity is allowed to start.

InvalidSystemIdException - This exception is thrown if the named connection cannot be found in the Communications Definitions (CD).

LoadingException - LOADING

LockedException - LOCKED

ChangedException - CHANGED

Since CICS TS version:

1.3

reset

public void reset(byte[] key,
 boolean generic)
           throws FileDisabledException,
FileNotFoundException,
LogicException,
InvalidRequestException,
IOErrorException,
ISCInvalidRequestException,
NotAuthorisedException,
RecordNotFoundException,
NotOpenException,
InvalidSystemIdException,
ChangedException,
LockedException,
LoadingException

Reset the browse. This version resets the type of browse to a searchType of GTEQ and to be GENERIC or not depending on the value of the generic parameter.

Parameters:

key - The key of the record at which to restart the browse.

generic - Whether or not the browse should use generic keys.

Throws:

FileDisabledException - The file is disabled.

FileNotFoundException - The file is not defined in the File Definitions (FD).

LogicException - An error not covered by any other exception occurred.

InvalidRequestException - This exception is thrown for the following reasons:

• A browse has not been started on the file
• A browse through a different interface is already in progress on the file

IOErrorException - This exception is thrown if there is an I/O error during the file control operation.

ISCInvalidRequestException - This exception is thrown if the remote system indicates a failure that does not correspond to a known condition.

NotAuthorisedException - This exception is thrown for the following reasons:

• When a resource security check is unsuccessful on the file.
• When the file is constructed with a SYSID and the current transaction is defined with the RSLCheck attribute set to either internal or external.

RecordNotFoundException - This exception is thrown if an attempt is made to start the browse positioned on a record which cannot be found.

NotOpenException - This exception is thrown for the following reasons:

• When the file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
• When the file is OPEN and in use by other transactions, but a CLOSE request has been received. Current activity is allowed to complete, but no new activity is allowed to start.

InvalidSystemIdException - This exception is thrown if the named connection cannot be found in the Communications Definitions (CD).

LoadingException - LOADING

LockedException - LOCKED

ChangedException - CHANGED

Since CICS TS version:

1.3

reset

public void reset(byte[] key,
 boolean generic,
 SearchType theSearchType)
           throws FileDisabledException,
FileNotFoundException,
LogicException,
InvalidRequestException,
IOErrorException,
ISCInvalidRequestException,
NotAuthorisedException,
RecordNotFoundException,
NotOpenException,
InvalidSystemIdException,
ChangedException,
LockedException,
LoadingException

Reset the browse. This version allows the search type to be specified and also whether or not the search key is a generic key.

Parameters:

key - The key of the record at which to restart the browse.

generic - Whether or not the browse should use generic keys.

theSearchType - A value specifying the type of search to use. Possible values are:

• EQUAL
• GTEQ

A null value defaults to GTEQ.

Throws:

FileDisabledException - The file is disabled.

FileNotFoundException - The file is not defined in the File Definitions (FD).

LogicException - An error not covered by any other exception occurred.

InvalidRequestException - This exception is thrown for the following reasons:

• A browse has not been started on the file
• A browse through a different interface is already in progress on the file

IOErrorException - This exception is thrown if there is an I/O error during the file control operation.

ISCInvalidRequestException - This exception is thrown if the remote system indicates a failure that does not correspond to a known condition.

NotAuthorisedException - This exception is thrown for the following reasons:

• When a resource security check is unsuccessful on the file.
• When the file is constructed with a SYSID and the current transaction is defined with the RSLCheck attribute set to either internal or external.

RecordNotFoundException - This exception is thrown if an attempt is made to start the browse positioned on a record which cannot be found.

NotOpenException - This exception is thrown for the following reasons:

• When the file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
• When the file is OPEN and in use by other transactions, but a CLOSE request has been received. Current activity is allowed to complete, but no new activity is allowed to start.

InvalidSystemIdException - This exception is thrown if the named connection cannot be found in the Communications Definitions (CD).

LoadingException - LOADING

LockedException - LOCKED

ChangedException - CHANGED

Since CICS TS version:

1.3