DATASERV (koldgeom) functions


LIBRARY ROUTINE

kgeom_open_object - create an object associated with an input or output transport

LIBRARY CALL

kobject kgeom_open_object(
   char *name,
   int   flags)

INPUT

OUTPUT

none

RETURN VALUE

kobject on success, KOBJECT_INVALID on 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 kgeom_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. The construction of transport descriptions will be explained later.

The second argument to this function is a flags argument which indicates how then the object is going to used. The flags argument is analogous to the flags for kopen. The following flags are available :

KOBJ_READ : Open an existing file or transport for reading. By using this flag, you are indicating that the file or transport exists and that it contains valid data. If it does not exist, then an error message will be generated and this function will return KOBJECT_INVALID.

KOBJ_WRITE : Open a file or transport for writing. 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.

This simple example illustrates how an input data object would be opened.

kobject obj;

obj = kgeom_open_object("existing.viff",KOBJ_READ);

It is possible to write data to an input object. If data is written to an input object, then subsequent calls to get data will contain the new data. However, the file or transport that is associated with this input object will not be changed. 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 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.

Khoros transport names are constructed using a transport token and an identifier. The transport name simply a string consisting of "token=identifier".

The following tokens are available :

file (Unix file : permanent storage) pipe (Unix pipe : no permanent storage) mmap (virtual memory : permanent storage) shm (shared memory : permanent storage) socket (sockets : no permanent storage) stream (named stream/pipe : no permanent storage)

If no token is provided, the file transport is used. The identifier is specific to the type of transport; for files, it is simply a filename, for a socket, it is the socket number. See kopen for more information.

Only the file transport is reliably supported at this time.

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

none

FILES

$DATASERV/objects/library/koldgeom/src/geometry.c

SEE ALSO

koldgeom(3)

COPYRIGHT

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