DATASERV (kappserv) functions


LIBRARY ROUTINE

kpds_open_object - create an object associated with an input or output transport.

LIBRARY CALL

kobject kpds_open_object(
   char *name,
   int flags)

INPUT

OUTPUT

none

RETURN VALUE

kobject on success, KOBJECT_INVALID upon failure

DESCRIPTION

This function is used to instantiate a data object (kobject) that is associated with a permanent file or transport. If a permanent file is not desired (i.e. the object is going to be used as temporary storage, and will not be used by any other process) then the kpds_create_object function call should be used instead.

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 kpds_open_object function call, flags, is used to provide polymorphic 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 to determine how the file or transport is opened and subsequently manipulated. This is done by bitwise OR'ing any combination of these options. For example KOBJ_READ | KOBJ_WRITE will result in a read/write file object. This implies that the file already exists and will be read from using kpds_get_data and written to using kpds_put_data. When kpds_close is called, the changes that are a result of calls to kpds_put_data will be stored to the file or transport.

However, if you intend to open an output object, but you need to occasionally 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 kpds_put_data on an input object (one which was opened without the KOBJ_WRITE flag). If this is done, then subsequent calls to kpds_get_data on a region that has been written to will contain the new data. However, the file or transport 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 or transport 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 raw data. The structured file formats that are currently recognized are VIFF (The Khoros 2.0 standard file format), Viff (The Khoros 1.0 standard file format, which was referred to as VIFF in Khoros 1.0), Pnm (Portable Any Map, which includes PBM, PGM, and PNM), and Sun Raster.

The default index order will be set to KWIDTH, KHEIGHT, KDEPTH, KTIME and KELEMENTS for the value and mask data, to KMAP_WIDTH, KMAP_HEIGHT, KMAP_ELEMENTS, KMAP_DEPTH and KMAP_TIME for the map data and KWIDTH, KHEIGHT, KDEPTH and KDIMENSION for the location data. The only way to get the index order to reflect the stored index order of the data is to call kpds_sync_object. See the man page for kpds_sync_object for more information.

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

The KOBJ_RAW flag will have unpredictable results if it is combined with the KOBJ_WRITE flag. This limitation will be removed in a later release of the Khoros 2.0 system.

MODIFICATION

none

FILES

$DATASERV/objects/library/kappserv/src/polymorph.c

SEE ALSO

kappserv(3)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.