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

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 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

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.

Table 2-3 KcsIO(Continued)

Member Function	Description
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 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.

Code 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); }

KcsMemoryBlock Class

The KcsMemoryBlock class is a memory-based I/O derivative of the KcsIO class. It provides a way to manipulate blocks of memory by creating a KcsIO object. You can use the protected and public member functions in this class in the implementation of your CMM; you cannot override any member function in this class.

The header file for the class is kcsmblk.h.

---

Note - It is highly recommended that you do not use any of the variables and functions for handle-based memory in the kcsmblk.h header file. Handle-based memory is not required on the Solaris system.

---

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

const KcsId KcsIOMBlkId = {(0x4D426C6BUL)}; /* 'MBlk' */
#define KcsIOMBlkIdd (0x4D426C6BUL) /* 'MBlk' */

In addition to the KcsIO virtual member functions that must be overridden for a minimal KcsIO implementation, the KcsMemoryBlock class has member functions for manipulating blocks of memory. See Table 2-4 on page 7 for a list of the member functions minimally required to derive from the KcsIO class.

The enumerations and protected and public members are described.

Enumerations

The KcsMemboryBlock class provides the following enumerations.

Table 2-5 KcsMemoryBlock

Enumeration	Description
enum KcsMemoryKind { KCS_APPLICATION_HEAP, KCS_SYSTEM_HEAP };	enum used in setCursorPos(). The object is in the application or system heap.

Protected Members

The KcsMemboryBlock class provides the following protected members

Table 2-6 KcsMemoryBlock

Protected Member	Description
long allocMe;	Determines whether memory block is allocated.
char* curPtr();	Returns the current address of the memory block + position.
long numElements;	Number of elements if memory block is an array.
long pos;	Current position in memory block.
long realEOF;	Number of bytes actually written to memory file.
long size;	Number of bytes allocated to contain memory file.
char *startPtr;	Start of char-pointer-based memory block.

Public Members

The KcsmemoryBlock class provides the following public members.

Table 2-7 KcsMemoryBlock

Public Member	Description
KcsStatus get(char* buf, long nbytes);	Gets nbytes of data starting at the current cursor position. Post-increments the cursor position by nbytes.
long getNumElements() {return numElements;}	Returns the number of elements in the KcsMemoryBlock object as a long.
long getSize();	Returns the size of the KcsMemoryBlock object.
KcsMemoryBlock(KcsStatus *status, char *start, long size, long numElements = 1, const unsigned long absBaseOffset = 0);	Constructor. Specifies a character pointer in start, block size in size, and number of elements in numElements.

Table 2-7 KcsMemoryBlock(Continued)

Public Member	Description
KcsMemoryBlock(KcsStatus *status, long size, long numElements = 1, const unsigned long absBaseOffset = 0, const KcsMemoryKind kind = KCS_APPLICATION_HEAP);	Constructor. Allocates and deallocates the memory.
virtual ~KcsMemoryBlock();	Destructor.
long position() {return pos;}	Returns the current cursor position.
void position(long posit) {pos=posit;}	Sets the current cursor position.
KcsStatus put(char* buf, long nbytes);	Puts nbytes of data into the KcsMemoryBlock object at the current cursor position. Post- increments the cursor position by nbytes.

Example

This example shows you how to change the size of memory with the KcsMemoryBlock class.

Code Example 2-2 Resizing Memory with KcsMemoryBlock

KcsStatus resizeIt() { unsigned long sNewSize = 10; KcsStatus sStatus; KcsMemoryBlock *memBlock; char * buffer = {'a','b','c','d'}; // create a new KcsMemoryBlock object memBlock = new KcsMemoryBlock(&sStatus,4); if (sStatus != KCS_SUCCESS) return (sStatus); // put the four bytes above into the new KcsMemoryBlock sStatus = memBlock->put(buffer,4); if (sStatus != KCS_SUCCESS) return (sStatus); // resize the KcsMemoryBlock from 4 to 10 sStatus = memBlock->reSize(sNewSize); //Finished with the data

Code Example 2-2 Resizing Memory with KcsMemoryBlock (Continued)

delete memBlock; return (sStatus); }

KcsFile Class

The KcsFile class is a file I/O derivative of the KcsIO class. It provides a way to manipulate files by creating a KcsIO object. You can use the protected and public member functions in this class in the implementation of your CMM; you cannot override any member function in this class.

The header file for the class is kcsfile.h.

---

Note - It is highly recommended that you do not use any of the variables and functions for handle-based memory in the kcsmblk.h header file. Handle-based memory is not required on the Solaris system.

---

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

const KcsId KcsIOFileId = {(0x46696C65UL)}; /* 'File' */
#define KcsIOFileIdd (0x46696C65UL) /* 'File' */

In addition to the KcsIO virtual functions that must be overridden for a minimal KcsIO implementation, the KcsFile class has member functions for reading from and writing to a file. See Table 2-4 on page 7 for detailed information on the virtual functions that are minimally required to derive from the KcsIO class.

This class does not have any protected members; the public members are described.

Public Members

The KcsFile class provides the following public members.

Table 2-8 KcsFile

Member Function	Description
virtual long getFref();	Gets the file description being used.
KcsFile(KcsStatus *status);	Constructor. Creates a file object without a file and offset. You must use setFref() to establish a link to a file before using any other methods.
KcsFile(KcsStatus *status, const KcsFileId anFref, const unsigned long absBaseOffset = 0);	Constructor. Creates a file object with an open file and offset.
virtual ~KcsFile();	Destructor.
virtual void setFref(long theFref);	Sets the file to use and the offset.

Examples

The following examples show you how to use the KcsFile class.

Reading a File From a Specified Offset This example shows you how to read a file from a specified offset with absRead(). See the kcsio.h header file for a description of absRead().

Code Example 2-3 Reading a File From a Specified Offset

KcsStatus readIt() { KcsStatus sStatus; KcsFileId sFileRef; long index = 32; long number; // open the file, put the fileRef into sFileRef sFileRef = open ("Profile", O_RDWR); if (sFileRef == -1) return (KCS_IO_ERROR); // create a file object file = new KcsFile(&sStatus, sFileRef, 0); if (sStatus != KCS_SUCCESS)

Code Example 2-3 Reading a File From a Specified Offset (Continued)

return(sStatus); // using the file object, read from the file into a buffer. sStatus = file->absRead(index, sizeof(long), &number); delete file; close(sFileRef); return (sStatus); }

Writing to a File From the Last Cursor Position This example shows you how to write to a file with relWrite(). See Table 2-3 on page 5 for a full definition of relWrite().

Code Example 2-4 Writing to a File From the Last Cursor Position

KcsStatus writeIt() { KcsStatus sStatus; KcsFileId sFileRef; long nbytes; char *buffer; // open the file, get a fileRef sFileRef = open ("Profile", O_RDWR); if (sFileRef == -1) return (KCS_IO_ERROR); // create a file object file = new KcsFile(&sStatus, sFileRef); if (sStatus != KCS_SUCCESS) return(sStatus); // Allocate memory for the buffer, fill it with data. // Set nbytes to the length of the buffer. if ((buffer = (char*) malloc(nbytes)) == NULL) return (KCS_IO_ERROR); delete file; close(sFileRef); // using the file object, write the buffer to the file. sStatus = file->relWrite(nbytes, buffer);

Code Example 2-4 Writing to a File From the Last Cursor Position (Continued)

// Free the buffer's memory. free (buffer); delete file; close(sFileRef); return (sStatus); }

KcsSolarisFile Class

The KcsSolarisFile class is a derivative of the KcsIO class. It is a Solaris-specific KcsIO class that provides member functions that:

• Open a file with a partial name
• Search through a list of known directories
• Check for string endings for filename suffixes (inp, mon, out, and spc)
• Access files on a remote machine

---

Note - The KCMS daemon, kcms_server, must be running to access remote files. Remote access is read only. See the kcms_server(1) man page.

---

The KcsSolarisFile class creates a pointer to a KcsFile or KcsRemoteFile object depending on the host location. The derived public methods (relWrite(), relRead(), getEOF(), and setEOF()) then call the KcsIO pointer to do the actual operation.

The header file for this class is kcssolfi.h.

The const and #define for this class are defined in the kcsids.h header file as:

const KcsId KcsIOsolfId = {(0x736f6c66UL)}; /* 'solf' */
#define KcsIOsolfIdd (0x736f6c66UL) /* 'solf' */

This class does not have any protected members; the public members are described.

Public Members

The KcsSolarisFile class provides the following public members.

Table 2-9 KcsSolarisFile

Public Member	Description
virtual KcsIO* getIO();	Returns the I/O pointer.
KcsSolarisFile(KcsStatus *status, const char *filename, const char *hostname, const int oflag, const mode_t mode);	Constructs a new I/O object pointer to a file (full path and suffix not needed) either a remote or local machine. The file is opened with the specified permissions. See the open(2) man page for information on oflag and mode.
virtual ~KcsSolarisFile();	Destructor.

KcsXWindow Class

The KcsXWindow class is a derivative of the KcsIO class. It provides an interface for the X11 Window System connection. It turns X11 information into filenames for access at known directories either on a local or remote system. The KCMS daemon, kcms_server(1) must be running to access remote files. Remote access is read only.

The KcsXWindow class creates a pointer to a KcsFile or KcsRemoteFile object depending on the host location which is derived from the X11 Window System information. The derived public members (relWrite(), relRead(), getEOF(), and setEOF()) then call the KcsIO pointer to do the actual operation.

The header file for the class is kcsxwin.h.

The const and #define for this class are defined in the kcsids.h header file as:

const KcsId KcsIOxwinId = {(0x7877696EUL)}; /* 'xwin' */
#define KcsIOxwinIdd (0x7877696EUL) /* 'xwin' */

In addition to the KcsIO methods overridden by this class, there are methods for creating filenames remotely or locally with X Window System information. See Table 2-4 on page 7 for detailed information on the virtual functions that are minimally required to derive from the KcsIO class.

This class does not have any protected members; the public members are described.

Public Members

The KcsXWindow class has the following public members.

Table 2-10 KcsXWindow

Public Member	Description
virtual KcsIO* getIO();	Returns the I/O pointer.
KcsXWindow(KcsStatus *status, const Display *dpy, const int screen, const Visual *visual, const long caller)	Constructs a new IO object pointer to a profile connected to the machine and display. The specific X Window System profile name is constructed. The location is either a known local directory or a path specified by the KCMS_XTERMINAL_PROFILES environment variable.
virtual ~KcsXWindow()	Destructor.

Constructing a KcsXWindow Profile Name

The X Window System profiles are created with the KCMS configuration program kcms_configure; see the kcms_configure(1) on-line man page for more information. The KCMS Calibrator Tool (kcms_calibrate) supplies monitor calibration, as well as configuration of the X profiles. See the kcms_calibrate(1) man page for more information.

X Window System visual profiles follow this naming convention:

<Visual Class><Visual ID in Hex>:<Display #>.<Screen #>

For example, for the PseudoColor visual on display 0, screen 0, with Visual ID 0x20, has the following profile name: PseudoColor0x20:0.0.

The Visual ID is provided with the visual argument as well as an indicator to one of the visual names ("StaticGray", "GrayScale", "StaticColor", "PseudoColor", "TrueColor", or "DirectColor").

Similar entries exist for the other visuals. X11 Window System visual profiles are overwritten when a system is recalibrated after setup. The base uncalibrated monitor profiles are in the /usr/openwin/etc/profiles directory; therefore, you can always reset the system, if for some reason one of the per-machine profiles is corrupted.