test

KCMS CMM Reference Manual

KcsIO Class

With a common interface, the KcsIO class maintains device-, platform-, and transport-independent I/O functionality for all derivatives.

The header file for the class is kcsio.h. The constant and #define identifiers for this class are defined in the kcsids.h header file as: 

const KcsId KcsSharIOId = {(0x494F0000UL)}; /* 'IO' */
#define KcsSharIOIdd (0x494F0000UL) /* 'IO' */

The enumerations and protected and public members are described, as well as the member function override rules when deriving from this class.

Enumerations

The KcsIO class provides the following enumerations.

Table 2-1 KcsIO Enumerations

Enumeration 

Description 

 
enum KcsIOPosition {KCS_OFS, KCS_BOO,
 	KCS_CUR};

Used for calls to setCursorPos().

KCS_OFS is relative to beginning of I/O object+baseoffset. KCS_BOO is relative to beginning of the I/O object. KCS_CUR is relative to present I/O cursor.

Protected Members

The KcsIO class provides the following protected members.

Table 2-2 KcsIO Protected Members

Protected Member 

Description 

 
KcsStatus
aSysError(const char *callersName,
 	const char *sysName, KcsStatus stat,
 	const int sysErrCode);

A protected member that returns a KcsStatus object that contains the OS error in the causingError data member. Use callersName for debugging; it is recommended that you change to a non-NULL value.

Public Members

The KcsIO class provides the following public members.

Table 2-3 KcsIO Public Members

Member Function 

Description 

 
virtual
KcsStatus absRead(const long index,
 	const long bytesWanted,
 	void *buffer,
 	const char *callersName = NULL);

Absolute read an I/O object already opened or allocated. Supply a count of number of bytes to read and a buffer.  

 
virtual
KcsStatus absWrite(const long index,
 	const long numBytes2Write,
 	const void *buffer,
 	const char *callersName = NULL);

Absolute write to some number of bytes in numBytes2Write from the buffer to the data store at the current position of the cursor

 
virtual
KcsStatus copyData(KcsIO *anotherIO);

Copies all data in I/O object to anotherIO object.

 
static KcsIO * createIO(KcsStatus *aStatus,
 	const KcsProfileDesc *aDesc);

Static method that creates an I/O object, by calling either a KcsIO derivative constructor within the KCMS library or a run-time loadable constructor. 

virtual
KcsStatus getEOF(long *theEOF) = 0;

Returns the end-of-file (EOF) position. 

 
virtual 
long getOffset();

Returns the permanent offset into the I/O object.. 

 
virtual
KcsIOType getType() = 0;

Returns the type of I/O object. 

 
virtual 
int isEqual(KcsIO *anotherIO) = 0;

Determines if this I/O object and another I/O object are working on the same data stores. The base offsets must also be the same for them to return true. 

 
KcsIO(KcsStatus *status,
 	const unsigned long absBaseOffset = 0);

Constructor that initializes the baseOffset data member with the values passed in.

 
virtual ~KcsIO();

Destructor. 

virtual 
KcsStatus relRead(const long bytesWanted,
 	void *buffer,
 	const char *callersName = NULL) = 0;

Reads bytesWanted from the I/O object from the current position of the cursor. Positions the cursor after the last byte read. 

virtual
KcsStatus relWrite(const long numBytes2Write,
 	const void *buffer,
 	const char *callersName = NULL) = 0;

Relative write of the number of bytes in numBytes2Write from the buffer to the data store at the current position of the cursor. Positions the cursor after the last byte written.

 
virtual
KcsStatus replaceData(const unsigned long offset,
 	const unsigned long oldSize,
 	const void *buffer,
 	const unsigned long newSize,
 	const char *callersName = NULL);

Replaces bytes of different lengths in an I/O object. Specifies where to start writing and size of old and new data. If the old data is longer than the new data, the I/O object is compressed. If the new data is longer than the old data, everything after the old data is moved to the end of the I/O object. If an error occurs, the cursor is where it was before the error occurred.  

 
virtual 
KcsStatus setCursorPos(long position,
 	const KcsIOPosition mode= KCS_OFS,
 	const char *callersName = NULL) = 0;

Sets the I/O object cursor to a caller-supplied position.

Positions the I/O object cursor to a specific spot in the object. Mode is defined by the enum KcsFilePosition.

 
virtual
KcsStatus setEOF(long theEOF) = 0;

Sets the EOF to a caller-supplied position. If the new EOF is greater than the old EOF, the storage for the new space is undefined. 

 
virtual
void setOffset(long theOffset);

Sets the base offset to a specified position.

Member Function Override Rules

The following table tells you which KcsIO member functions you must override and can override. The member functions indicated with an "X" in the Must column are required to derive successfully from this base class. Others can be used and not overridden.

Table 2-4 KcsIO Member Function Override Rules

Member Function 

Override Rules 

Must 

Can 

getEOF()

X 

 

getType()

X 

 

isEqual()

X 

 

KcsIO()

X 

 

~KcsIO()

 

X 

relRead()

X 

 

relWrite()

X 

 

setCursorPos()

X 

 

setEOF()

X 

 

setOffset()

 

X 

Example

The following code shows you how to use a KcsIO derivative as a data member or as an object to pass into a function.

Example 2-1 KcsIO Example

//Read 4 bytes from KcsIO starting at byte 8.
 long getTheSecondLong(KcsStatus *aStat, KcsIO *aIO)
 {
 	long badNumber = -1;
 	long sSecondLong;

 	if (aIO == NULL)
 		return(badNumber);
 	if ((*aStat = aIO->absRead(8, 4, &sSecondLong)) == KCS_SUCCESS)
 		return(sSecondLong);
 	else
 		return(badNumber);
 }