kobject
kdms_open(
char *name,
int flags)
none
The first argument to this function is the transport or file name. This argument indicates the name of the transport that is associated with the object. The transport name can be any legal khoros transport description. While this will usually be a regular UNIX file name, it is also possible to specify such things as shared memory pointers, memory map pointers, sockets, streams, and even transports on other machines. For more information on the syntax of a Khoros transport name, refer to the online man page for the Khoros function kopen.
The second argument to the kdms_open function call is used to provide data services with specific information about how the object is going to be manipulated. The flags argument is analogous to kopen's flags argument. The flags argument is constructed by bitwise OR'ing predefined values from the following list:
KOBJ_READ Open an existing file or transport for reading (input). By using this flag, you are indicating that the file or transport exists and that it contains valid data. If it does not exist, or the data is not recognized, then an error message will be generated and this function will return KOBJECT_INVALID.
KOBJ_WRITE Open a file or transport for writing (output). By using this flag, you are indicating that any data that you write to the object will be stored in the file or transport specified.
KOBJ_STREAM If the transport is a stream then polymorphic services does not attempt to buffer the data. By setting this value, you are indicating that that process reads and/or writes the data strictly sequentially from the object in its native index order, and it is not necessary to buffer the data in a temporary transport that can be accessed randomly.
KOBJ_RAW When an object is opened, data services usually attempts to recognize the file format by examining the first part of the file. By setting this value, you will bypass this operation, forcing the file to be read as raw unformatted data.
These flags can be combined arbitrarily (with the exceptions given above) to alter the interpretation of the file or transport. For example, specifying both KOBJ_READ and KOBJ_WRITE will result in a read/write file object. This implies that the file already exists and will be read from using kdms_get_data and written to using kdms_put_data. When kdms_close is called, the changes that are a result of calls to kdms_put_data will be stored to the file.
However, if you intend to open an output object, but you need to occationally read data from it that you have already written, it is not necessary to specify KOBJ_READ (in fact, doing so may result result in an error if the file or transport does not already exist).
Likewise, it is possible to call kdms_put_data on an input object (one which was opened without the KOBJ_WRITE flag). If this is done, then subsequent calls to kdms_get_data on a region that has been written to will contain the new data. However, the file that is associated with this input object will not be changed. Thus, the KOBJ_READ and KOBJ_WRITE flags only indicate what operations are allowed on the permanent file that is associated with the object, not what operations are allowable on the object itself.
If KOBJ_READ is specified, then the Data Services will attempt to recognize the file format automatically. If it fails, then this function will return KOBJECT_INVALID, indicating that it was unable to open the object, unless the KOBJ_RAW flag was also specified, in which case, it will assume that the input file is simply headerless data. The structured file formats that are currently recognized are Kdf (The Khoros 2.0 standard file format), Viff (The Khoros 1.0 standard file format, Pnm (Portable Any Map, which includes PBM, PGM, and PNM), and Sun Raster.
none
none
The Kdbm file format has a bug in it that prevents it from being used on a stream base output. This will be fixed in a future release of the Khoros 2.0 system.
$DATASERV/objects/library/kdataman/src/public.c