com.ibm.cics.server
Class KeyedFile

java.lang.Object
  |
  +--com.ibm.cics.server.API
        |
        +--com.ibm.cics.server.Resource
              |
              +--com.ibm.cics.server.RemotableResource
                    |
                    +--com.ibm.cics.server.File
                          |
                          +--com.ibm.cics.server.KeyedFile
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
ESDS, KSDS

public class KeyedFile
extends com.ibm.cics.server.File
implements java.io.Serializable

This is the implementation class for the KeyedFile interface.

See Also:
Serialized Form

Constructor Summary
KeyedFile()
          Construct a default KeyedFile object.
 
Method Summary
 void read(byte[] key, RecordHolder holder)
          Read a specific record from a file.
 void read(byte[] key, SearchType searchType, RecordHolder holder)
          Read a record from a file using the specified type of search.
 void readForUpdate(byte[] key, RecordHolder holder)
          Read a specific record from a file, locking it for update.
 void readForUpdate(byte[] key, SearchType searchType, RecordHolder holder)
          Read a record from a file using the specified type of search, locking it for update.
 void readGeneric(byte[] key, RecordHolder holder)
          Read a record from a file using a generic key.
 void readGeneric(byte[] key, SearchType searchType, RecordHolder holder)
          Read a record from a file using a generic key and specifying the type of search..
 void readGenericForUpdate(byte[] key, RecordHolder holder)
          Read a record for update from a file using a generic key.
 void readGenericForUpdate(byte[] key, SearchType searchType, RecordHolder holder)
          Read a record for update from a file using a generic key.
 void rewrite(byte[] data)
          Update a record in a file.
 KeyedFileBrowse startBrowse(byte[] key)
          Create a browse against the file.
 KeyedFileBrowse startBrowse(byte[] key, SearchType searchType)
          Create a browse against the file with a starting position determined by the type of search specified.
 KeyedFileBrowse startGenericBrowse(byte[] key, int fullKeyLength)
          Create a browse against the file using a generic key to specify the starting position.
 KeyedFileBrowse startGenericBrowse(byte[] key, int fullKeyLength, SearchType searchType)
          Create a browse against the file with a starting position determined by the type of search specified.
 void unlock()
          Unlock a file.
 
Methods inherited from class com.ibm.cics.server.RemotableResource
getSysId, setSysId
 
Methods inherited from class com.ibm.cics.server.Resource
getDescription, getName, setDescription, setName
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

KeyedFile

public KeyedFile()
Construct a default KeyedFile object.
Method Detail

read

public void read(byte[] key,
                 RecordHolder holder)
          throws FileDisabledException,
                 DuplicateKeyException,
                 FileNotFoundException,
                 LogicException,
                 InvalidRequestException,
                 IOErrorException,
                 ISCInvalidRequestException,
                 NotAuthorisedException,
                 RecordNotFoundException,
                 NotOpenException,
                 InvalidSystemIdException
Read a specific record from a file.
Parameters:
key - The key for the record.
holder - A RecordHolder in which is returned a byte array containing the record. If you know in advance the size of the object to be returned you can initialise the holder with a byte array of the correct size and CICS will not then allocate one. If you pass in a byte array shorter than is necessary CICS will ignore it and allocate an array of the correct size. The reference to the original array will be lost.
Throws:
FileDisabledException - a
DuplicateKeyException - a
FileNotFoundException - a
LogicException - a
InvalidRequestException - a
IOErrorException - a
ISCInvalidRequestException - a
NotAuthorisedException - a
RecordNotFoundException - a
NotOpenException - a
InvalidSystemIdException - a

read

public void read(byte[] key,
                 SearchType searchType,
                 RecordHolder holder)
          throws FileDisabledException,
                 DuplicateKeyException,
                 FileNotFoundException,
                 LogicException,
                 InvalidRequestException,
                 IOErrorException,
                 ISCInvalidRequestException,
                 NotAuthorisedException,
                 RecordNotFoundException,
                 NotOpenException,
                 InvalidSystemIdException
Read a record from a file using the specified type of search.
Parameters:
key - a
searchType - a
holder - a
Throws:
FileDisabledException - a
DuplicateKeyException - a
FileNotFoundException - a
LogicException - a
InvalidRequestException - a
IOErrorException - a
ISCInvalidRequestException - a
NotAuthorisedException - a
RecordNotFoundException - a
NotOpenException - a
InvalidSystemIdException - a

readForUpdate

public void readForUpdate(byte[] key,
                          RecordHolder holder)
                   throws FileDisabledException,
                          DuplicateKeyException,
                          FileNotFoundException,
                          LogicException,
                          InvalidRequestException,
                          IOErrorException,
                          ISCInvalidRequestException,
                          NotAuthorisedException,
                          RecordNotFoundException,
                          NotOpenException,
                          InvalidSystemIdException
Read a specific record from a file, locking it for update.
Parameters:
key - a
holder - a
Throws:
FileDisabledException - a
DuplicateKeyException - a
FileNotFoundException - a
LogicException - a
InvalidRequestException - a
IOErrorException - a
ISCInvalidRequestException - a
NotAuthorisedException - a
RecordNotFoundException - a
NotOpenException - a
InvalidSystemIdException - a

readForUpdate

public void readForUpdate(byte[] key,
                          SearchType searchType,
                          RecordHolder holder)
                   throws FileDisabledException,
                          DuplicateKeyException,
                          FileNotFoundException,
                          LogicException,
                          InvalidRequestException,
                          IOErrorException,
                          ISCInvalidRequestException,
                          NotAuthorisedException,
                          RecordNotFoundException,
                          NotOpenException,
                          InvalidSystemIdException
Read a record from a file using the specified type of search, locking it for update.
Parameters:
key - The key to be used when searching for the record.
searchType - A value specifying the type of search to use. Possible values are:
  • EQUAL
  • GTEQ
holder - A RecordHolder in which is returned a byte array containing the record.
Throws:
FileDisabledException - This exception is thrown if 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.
FileNotFoundException - This exception is thrown if the file is not found in the File Definitions (FD).
LogicException - This exception is thrown if an error occurs that does not map to any other exception.
InvalidRequestException - This exception is thrown in the following circumstances:
  1. read operations are not currently allowed for the file.
IOErrorException - This exception is thrown if an I/O error occurs.
ISCInvalidRequestException - This exception is thrown if a remote system indicates a failure that does not correspond to a known condition.
NotAuthorisedException - This exception is thrown in the following situations:
  1. a resource security check is unsuccessful for the file
  2. the file was constructed with a SYSID and the current transaction has the RSLCheck attribute set to either internal or external.
RecordNotFoundException - This exception is thrown if a record could not be found with the key specified.
NotOpenException - This exception is thrown if the file is not open.
InvalidSystemIdException - This exception is thrown if the SYSID used to construct the File object is not defined in the Communications Definitions (CD).

readGeneric

public void readGeneric(byte[] key,
                        RecordHolder holder)
                 throws FileDisabledException,
                        DuplicateKeyException,
                        FileNotFoundException,
                        LogicException,
                        InvalidRequestException,
                        IOErrorException,
                        ISCInvalidRequestException,
                        NotAuthorisedException,
                        RecordNotFoundException,
                        NotOpenException,
                        InvalidSystemIdException
Read a record from a file using a generic key.
Parameters:
key - The generic key. The length of the generic key must be less than the full key length.
holder - A RecordHolder in which is returned a byte array containing the record.
Throws:
FileDisabledException - This exception is thrown if 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.
FileNotFoundException - This exception is thrown if the file is not found in the File Definitions (FD).
LogicException - This exception is thrown if an error occurs that does not map to any other exception.
InvalidRequestException - This exception is thrown in the following circumstances:
  1. read operations are not currently allowed for the file.
IOErrorException - This exception is thrown if an I/O error occurs.
ISCInvalidRequestException - This exception is thrown if a remote system indicates a failure that does not correspond to a known condition.
NotAuthorisedException - This exception is thrown in the following situations:
  1. a resource security check is unsuccessful for the file
  2. the file was constructed with a SYSID and the current transaction has the RSLCheck attribute set to either internal or external.
RecordNotFoundException - This exception is thrown if a record could not be found with the key specified.
NotOpenException - This exception is thrown if the file is not open.
InvalidSystemIdException - This exception is thrown if the SYSID used to construct the File object is not defined in the Communications Definitions (CD).

readGeneric

public void readGeneric(byte[] key,
                        SearchType searchType,
                        RecordHolder holder)
                 throws FileDisabledException,
                        DuplicateKeyException,
                        FileNotFoundException,
                        LogicException,
                        InvalidRequestException,
                        IOErrorException,
                        ISCInvalidRequestException,
                        NotAuthorisedException,
                        RecordNotFoundException,
                        NotOpenException,
                        InvalidSystemIdException
Read a record from a file using a generic key and specifying the type of search..
Parameters:
key - The generic key. The length of the generic key must be less than the full key length.
searchType - A value specifying the type of search to use. Possible values are:
  • EQUAL
  • GTEQ
holder - A RecordHolder in which is returned a byte array containing the record.
Throws:
FileDisabledException - This exception is thrown if 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.
FileNotFoundException - This exception is thrown if the file is not found in the File Definitions (FD).
LogicException - This exception is thrown if an error occurs that does not map to any other exception.
InvalidRequestException - This exception is thrown in the following circumstances:
  1. read operations are not currently allowed for the file.
IOErrorException - This exception is thrown if an I/O error occurs.
ISCInvalidRequestException - This exception is thrown if a remote system indicates a failure that does not correspond to a known condition.
NotAuthorisedException - This exception is thrown in the following situations:
  1. a resource security check is unsuccessful for the file
  2. the file was constructed with a SYSID and the current transaction has the RSLCheck attribute set to either internal or external.
RecordNotFoundException - This exception is thrown if a record could not be found with the key specified.
NotOpenException - This exception is thrown if the file is not open.
InvalidSystemIdException - This exception is thrown if the SYSID used to construct the File object is not defined in the Communications Definitions (CD).

readGenericForUpdate

public void readGenericForUpdate(byte[] key,
                                 RecordHolder holder)
                          throws FileDisabledException,
                                 DuplicateKeyException,
                                 FileNotFoundException,
                                 LogicException,
                                 InvalidRequestException,
                                 IOErrorException,
                                 ISCInvalidRequestException,
                                 NotAuthorisedException,
                                 RecordNotFoundException,
                                 NotOpenException,
                                 InvalidSystemIdException
Read a record for update from a file using a generic key.
Parameters:
key - The generic key. The length of the generic key must be less than the full key length.
holder - A RecordHolder in which is returned a byte array containing the record.
Throws:
FileDisabledException - This exception is thrown if 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.
FileNotFoundException - This exception is thrown if the file is not found in the File Definitions (FD).
LogicException - This exception is thrown if an error occurs that does not map to any other exception.
InvalidRequestException - This exception is thrown in the following circumstances:
  1. read operations are not currently allowed for the file.
IOErrorException - This exception is thrown if an I/O error occurs.
ISCInvalidRequestException - This exception is thrown if a remote system indicates a failure that does not correspond to a known condition.
NotAuthorisedException - This exception is thrown in the following situations:
  1. a resource security check is unsuccessful for the file
  2. the file was constructed with a SYSID and the current transaction has the RSLCheck attribute set to either internal or external.
RecordNotFoundException - This exception is thrown if a record could not be found with the key specified.
NotOpenException - This exception is thrown if the file is not open.
InvalidSystemIdException - This exception is thrown if the SYSID used to construct the File object is not defined in the Communications Definitions (CD).

readGenericForUpdate

public void readGenericForUpdate(byte[] key,
                                 SearchType searchType,
                                 RecordHolder holder)
                          throws FileDisabledException,
                                 DuplicateKeyException,
                                 FileNotFoundException,
                                 LogicException,
                                 InvalidRequestException,
                                 IOErrorException,
                                 ISCInvalidRequestException,
                                 NotAuthorisedException,
                                 RecordNotFoundException,
                                 NotOpenException,
                                 InvalidSystemIdException
Read a record for update from a file using a generic key.
Parameters:
key - The generic key. The length of the generic key must be less than the full key length.
searchType - A value specifying the type of search to use. Possible values are:
  • EQUAL
  • GTEQ
holder - A RecordHolder in which is returned a byte array containing the record.
Throws:
FileDisabledException - This exception is thrown if 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.
FileNotFoundException - This exception is thrown if the file is not found in the File Definitions (FD).
LogicException - This exception is thrown if an error occurs that does not map to any other exception.
InvalidRequestException - This exception is thrown in the following circumstances:
  1. read operations are not currently allowed for the file.
IOErrorException - This exception is thrown if an I/O error occurs.
ISCInvalidRequestException - This exception is thrown if a remote system indicates a failure that does not correspond to a known condition.
NotAuthorisedException - This exception is thrown in the following situations:
  1. a resource security check is unsuccessful for the file
  2. the file was constructed with a SYSID and the current transaction has the RSLCheck attribute set to either internal or external.
RecordNotFoundException - This exception is thrown if a record could not be found with the key specified.
NotOpenException - This exception is thrown if the file is not open.
InvalidSystemIdException - This exception is thrown if the SYSID used to construct the File object is not defined in the Communications Definitions (CD).

rewrite

public void rewrite(byte[] data)
             throws FileDisabledException,
                    DuplicateRecordException,
                    FileNotFoundException,
                    LogicException,
                    InvalidRequestException,
                    IOErrorException,
                    ISCInvalidRequestException,
                    LengthErrorException,
                    NoSpaceException,
                    NotAuthorisedException,
                    NotOpenException,
                    InvalidSystemIdException
Update a record in a file.
Parameters:
data - The data comprising the new value of the record.
Throws:
FileDisabledException - This exception is thrown if the file is disabled.
DuplicateRecordException - This exception is thrown if the underlying file has an active alternate index that accepts only unique keys, and the record to be updated for this index has a key that duplicates an existing value.
FileNotFoundException - This exception is thrown if the file is not found in the File Definitions (FD).
LogicException - This exception is thrown if an error occurs that does not map to any other exception.
InvalidRequestException - This exception is thrown in the following circumstances:
  1. read operations are not currently allowed for the file.
IOErrorException - This exception is thrown if an I/O error occurs.
ISCInvalidRequestException - This exception is thrown if a remote system indicates a failure that does not correspond to a known condition.
LengthErrorException - This exception
NoSpaceException - This exception
NotAuthorisedException - This exception is thrown in the following situations:
  1. a resource security check is unsuccessful for the file
  2. the file was constructed with a SYSID and the current transaction has the RSLCheck attribute set to either internal or external.
NotOpenException - This exception is thrown if the file is not open.
InvalidSystemIdException - This exception is thrown if the SYSID used to construct the File object is not defined in the Communications Definitions (CD).

startBrowse

public KeyedFileBrowse startBrowse(byte[] key)
                            throws FileDisabledException,
                                   FileNotFoundException,
                                   LogicException,
                                   InvalidRequestException,
                                   IOErrorException,
                                   ISCInvalidRequestException,
                                   NotAuthorisedException,
                                   RecordNotFoundException,
                                   NotOpenException,
                                   InvalidSystemIdException
Create a browse against the file.
Parameters:
key - The key of the record at which to start the browse. This key must be an exact key.
Returns:
A browse object
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:
  • Browse operations are not currently allowed for the file.
  • The length of the key differs from the length defined for 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).

startBrowse

public KeyedFileBrowse startBrowse(byte[] key,
                                   SearchType searchType)
                            throws FileDisabledException,
                                   FileNotFoundException,
                                   LogicException,
                                   InvalidRequestException,
                                   IOErrorException,
                                   ISCInvalidRequestException,
                                   NotAuthorisedException,
                                   RecordNotFoundException,
                                   NotOpenException,
                                   InvalidSystemIdException
Create a browse against the file with a starting position determined by the type of search specified.
Parameters:
key - The key of the record at which to start the browse. This key must be a full-length key but it is not necessary for the key to exactly match a record in the file if the search type is GTEQ.
searchType - A value specifying the type of search to use. Possible values are:
  • EQUAL
  • GTEQ
Returns:
A KeyedFileBrowse object interface.
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:
  • Browse operations are not currently allowed for the file.
  • The length of the key differs from the length defined for 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).

startGenericBrowse

public KeyedFileBrowse startGenericBrowse(byte[] key,
                                          int fullKeyLength)
                                   throws FileDisabledException,
                                          FileNotFoundException,
                                          LogicException,
                                          InvalidRequestException,
                                          IOErrorException,
                                          ISCInvalidRequestException,
                                          NotAuthorisedException,
                                          RecordNotFoundException,
                                          NotOpenException,
                                          InvalidSystemIdException
Create a browse against the file using a generic key to specify the starting position.
Parameters:
key - The key of the record at which to start the browse. This key must be a generic key, that is be shorter than the full key.
fullKeyLength - The length of the full key of the file.
Returns:
A KeyedFileBrowse object interface.
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:
  • Browse operations are not currently allowed for the file.
  • The length of the key differs from the length defined for 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).

startGenericBrowse

public KeyedFileBrowse startGenericBrowse(byte[] key,
                                          int fullKeyLength,
                                          SearchType searchType)
                                   throws FileDisabledException,
                                          FileNotFoundException,
                                          LogicException,
                                          InvalidRequestException,
                                          IOErrorException,
                                          ISCInvalidRequestException,
                                          NotAuthorisedException,
                                          RecordNotFoundException,
                                          NotOpenException,
                                          InvalidSystemIdException
Create a browse against the file with a starting position determined by the type of search specified.
Parameters:
key - The key of the record at which to start the browse. This key must be a generic key, that is, be shorter than the full key.
fullKeyLength - The length of the full key of the file.
searchType - A value specifying the type of search to use. Possible values are:
  • EQUAL
  • GTEQ
Returns:
A KeyedFileBrowse object interface.
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:
  • Browse operations are not currently allowed for the file.
  • The length of the key differs from the length defined for 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).

unlock

public void unlock()
            throws FileDisabledException,
                   FileNotFoundException,
                   LogicException,
                   IOErrorException,
                   ISCInvalidRequestException,
                   NotAuthorisedException,
                   NotOpenException,
                   InvalidSystemIdException
Unlock a file.
Throws:
FileDisabledException -  
FileNotFoundException -  
LogicException -  
IOErrorException -  
ISCInvalidRequestException -  
NotAuthorisedException -  
NotOpenException -  
InvalidSystemIdException -