This chapter describes the following KCMS input/output (I/O) classes:
KcsIO
KcsFile
KcsMemoryBlock
KcsSolarisFile
KcsXWindow
The KcsIO class provides a common interface for I/O operations such as read and write. The KcsIO class is a derivative of the KcsShareable class (see Chapter 1, KcsShareable Class). The KcsFile, KcsMemoryBlock, KcsSolarisFile, and KcsXWindow are derivatives of the KcsIO class. These derivatives provide I/O for more specific types of data storage.
As you read this chapter, you will find it helpful to have access to the following header files:
kcsio.h, kcsfile.h, kcsmblk.h, kcssolfi.h, and kcsxwin.h
kcsshare.h and kcsids.h
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.
The KcsIO class provides the following enumerations.
Table 2-1 KcsIO Enumerations
The KcsIO class provides the following protected members.
Table 2-2 KcsIO Protected Members
The KcsIO class provides the following public members.
Table 2-3 KcsIO Public Members
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 |
The following code shows you how to use a KcsIO derivative as a data member or as an object to pass into a function.
//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); } |
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.
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 for a list of the member functions minimally required to derive from the KcsIO class.
The enumerations and protected and public members are described.
The KcsMemboryBlock class provides the following enumerations.
Table 2-5 KcsMemoryBlock Enumerations
Enumeration |
Description |
---|---|
enum KcsMemoryKind { KCS_APPLICATION_HEAP, KCS_SYSTEM_HEAP }; |
enum used in setCursorPos(). The object is in the application or system heap. |
The KcsMemboryBlock class provides the following protected members
Table 2-6 KcsMemoryBlock Protected Members
The KcsmemoryBlock class provides the following public members.
Table 2-7 KcsMemoryBlock Public Members
This example shows you how to change the size of memory with the KcsMemoryBlock class.
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 delete memBlock; return (sStatus); } |
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.
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 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.
The KcsFile class provides the following public members.
Table 2-8 KcsFile Public Members
The following examples show you how to use the KcsFile class.
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().
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) 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); } |
This example shows you how to write to a file with relWrite(). See Table 2-3 for a full definition of relWrite().
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); // Free the buffer's memory. free (buffer); delete file; close(sFileRef); return (sStatus); } |
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
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.
The KcsSolarisFile class provides the following public members.
Table 2-9 KcsSolarisFile Public Members
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 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.
The KcsXWindow class has the following public members.
Table 2-10 KcsXWindow Public Members
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.