DSS_Connection

dss

1998 12-06

CLASS

SYNOPSIS

CONSTRUCTOR

DSS_Connection()

CONNECTIVITY MEMBER FUNCTIONS

long Connect()
Connect to the daemon. By default the daemon is local and listening on the well known port (as defined in /etc/services in UNIX). This function returns TRUE on success and FALSE on failure. The return codes for this function are not related to failure of this function. The return codes are:


DSS_GETCHUNKCACHE_OK	A valid shared memory chunk cache was located. READ operations on chunks that exist in shared memory may not need to communicate with the local server.
DSS_GETCHUNKCACHE_FAIL	A valid shared memory cache was not located.


long Disconnect()
Disconnect from the daemon. This function returns TRUE on success and FALSE on failure. There are no return codes associated with this function.
NL_Channel *GetChannel()
Get the actual channel. This can be used before Connect() is called to alter the daemon location to be connected. It is possible to connect to remote daemons using this method. See the manpage for NL_Channel for details on configuration of the channel. Warning: use of this function is not guaranteed to be supported in future releases.

SPACE MANAGEMENT MEMBER FUNCTIONS

long Create(char *space)
Create a space with the name space. This function returns TRUE on success and FALSE on failure. The return codes are:


DSS_CREATE_OK	The space was created.
DSS_CREATE_EXISTS	The space was not created because it already exists.


long Join(char *space, char *host)
Join the space space on the node host. This function returns TRUE on success and FALSE on failure. The return codes are:


DSS_JOINSPACE_OK	The space was joined to.
DSS_JOINSPACE_EXISTS	The space was not joined to because it already exists.
DSS_JOINSPACE_FAIL	The space was not joined for some other reason, possibly because there is no space named space on host or there is no server running on host.


long Invite(char *space, char *host)
Invite the node host to the space space on the calling node. This function returns TRUE on success and FALSE on failure. The return codes are the same as for Join() and are relevant to the attempted Join() called from host.
long UnJoin(char *space)
Unjoin the space named space. This function returns TRUE on success and FALSE on failure. The return codes are:


DSS_UNJOINSPACE_OK	The space was unjoined.
DSS_UNJOINSPACE_NOEXIST	The space was not unjoined because it does not exist.


NL_HOST_INET_ADDR *HostList(char *space, long *addr_count)
Get a host list for all the members of space. The returned NL_HOST_INET_ADDR pointer is to an array of *addr_count hosts. This call allocates the memory for the array so it is the callers responsibility to free the memory. NULL is returned on failure. The return codes are:


DSS_SPACEGETHOSTS_OK	The host list was retrieved.
DSS_SPACEGETHOSTS_NOEXIST	The host list was not retrieved because the space does not exist.


DSS_ChunkInfo *ChunkList(char *space, long *chunk_count)

DSS_ChunkInfo *ChunkList(char *space, long *chunk_count, char mode)
Get an array of DSS_ChunkInfo structures for space. The returned DSS_ChunkInfo pointer is to an array of *chunk_count DSS_ChunkInfo structures. This call allocates the memory for the array so it is the caller's responsibility to free the memory. The possible modes are:


DSS_CHUNKLIST_ALL	get an entry for every copy of every chunk
DSS_CHUNKLIST_ALPHA	get an entry for the alpha copy of every chunk
DSS_CHUNKLIST_LOCAL	get an entry for every chunk with a local copy

NULL is returned on failure. The return codes are:


DSS_GETCHUNKLIST_OK	The chunk list was retrieved.
DSS_GETCHUNKLIST_FAIL	The chunk list was not retrieved.


char **SpaceList()
This function returns a pointer to a NULL terminated array of pointers to the names of spaces that exist. It is the caller's responsibility to free the memory. Use wbaFreeEnvpStruct() as an easy way to deallocate the memory.
long Kill(const char *space, const char *host, OSD_PID pid)
Attempt to kill a process on host with process id pid. This call should only be used for processes started with the Spawn() call for space.
long Spawn(const char *space, const char *host, const char *username, const char *password, const char *pathname, char **argp, const char **envp)
Start a process on host as user username. The daemon on host will attempt to execute the file specified by pathname with the arguments specified by argp and the environment specified by envp. If password is non-NULL it is used to authenticate username. The return codes are:


DSS_SPAWNPROCESS_OK	the process was started. pid is returned.
DSS_SPAWNPROCESS_NOSPACE	the specified space could not be found. -1 is returned.
DSS_SPAWNPROCESS_NOHOST	the specified host could not be found. -1 is returned.
DSS_SPAWNPROCESS_FAIL	the process could not be started. system error code for failed spawn is returned.

CHUNK OPERATIONS

char *Read(char *s, char *c, unsigned long *l)
Return a pointer to a byte block of length *l with the contents of chunk with name c in space with name s. NULL is returned if the chunk cannot be read. This call allocates the memory for the byte block. It is the responsibility of the caller to free the memory. The return codes are:


DSS_TRANSACT_CLIENT_READ_OK	The chunk was read.
DSS_TRANSACT_CLIENT_READ_WAITING	The chunk was not read because it did not exist in the specified space.
DSS_TRANSACT_CLIENT_READ_FAIL	The chunk was not read possibly for some other reason such as the non-existence of the space.


char *Wait(char *s, char *c, unsigned long *l)
Return a pointer to a byte block of length *l with the contents of chunk with name c in space with name s. This call will wait until the chunk can be read before returning. This call allocates the memory for the byte block. It is the responsibility of the caller to free the memory. The return codes are:


DSS_TRANSACT_CLIENT_WAIT_OK	The chunk was read.
DSS_TRANSACT_CLIENT_WAIT_FAIL	The chunk was not read, possibly because the space does not exist.


long Write(char *s, char *c, char *b, unsigned long *l)

long Write(char *s, char *c, char *b, unsigned long *l, DSS_ChunkConfig *f)
This call writes the buffer b of length *l to chunk c in space s. The first version uses the default DSS_ChunkConfig structure while the second version uses the structure specified by f. This function returns TRUE on success and FALSE on failure. The return codes are:


DSS_TRANSACT_CLIENT_WRITE_OK	The chunk was written.
DSS_TRANSACT_CLIENT_WRITE_FAIL	The chunk was not written, possibly because the space does not exist.


char *StartRead(char *s, char *c, unsigned long *l)
Return a pointer to a byte block of length *l with the contents of chunk with name c from the space with name s. NULL is returned if the chunk cannot be read. This call marks the chunk as being read which will prevent the local copy from being written to until a StopRead() is called. This call MAY allocate the memory for the byte block depending on the chunk type. However, the interface object keeps track of the pointer and will free allocated memory when StopRead() is called. The return codes are the same as for Read().
long StopRead(char *s, char *c)
Unmark the chunk named c in space s so that it may be written to. This function returns TRUE on success and FALSE on failure. There are no return codes associated with this function.
char *StartWait(char *s, char *c, unsigned long *l)
Return a pointer to a byte block of length *l with the contents of chunk with name c from the space with name (s). NULL is returned if the chunk cannot be read. This call marks the chunk as being read which will prevent the local copy from being written to until a StopWait() is called. This call MAY allocate the memory for the byte block depending on the chunk type. However, the interface object keeps track of the pointer and will free allocated memory when StopWait() is called. The return codes are the same as for Wait().
long StopWait(char *s, char *c)
Unmark the chunk named c in space s so that it may be written to. This function returns TRUE on success and FALSE on failure. There are no return codes associated with this function.
char *StartWrite(char *s, char *c, unsigned long *l)

char *StartWrite(char *s, char *c, unsigned long *l, DSS_ChunkConfig *f)
Mark the chunk with name c in space s as being written to. This chunk cannot be read locally until StopWrite() is called. This call also returns a pointer to the current contents of the chunk. The length of the current byte block is returned in *l. The input value of *l is used to request the chunk size to be used. This is important in the case of shared memory chunks where the space must be allocated before actual writing by the shared memory manager. Note that in the case of a shared memory chunk the returned pointer is to the appropriate location in shared memory itself. However, if a different pointer is handed to StopWrite() and the data is small enough to fit, the data in the different location will automatically be copied to the shared memory location. If the data is too large to fit it is sent via the network connection to dssd at which time a larger block of shared memory is allocated. The first version uses the default DSS_ChunkConfig structure while the second version uses the structure specified by f. This call MAY allocate the memory for the byte block depending on the chunk type. However, the interface object keeps track of the pointer and will free allocated memory when StopWrite() is called. If the connection drops (possibly due to process failure) before StopWrite() is called and the chunk was not already VALID before StartWrite() was called then the chunk will be made INVALID. It is also important to check the returned pointer for NULL because if the chunk does not pre-exist and it is a HEAP (the default) chunk NULL is returned. The return codes are:


DSS_TRANSACT_CLIENT_STARTWRITE_OK	A valid buffer was returned to read from and write to.
DSS_TRANSACT_CLIENT_STARTWRITE_FAIL	A valid buffer was not returned, possibly because the space does not exist.


long StopWrite(char *s, char *c, char *b, unsigned long *l)

long StopWrite(char *s, char *c, char *b, unsigned long *l, DSS_ChunkConfig *f)
This call writes the contents of buffer b of length *l in space s. This call also unmarks the chunk as being written. The first version uses the default DSS_ChunkConfig structure while the second version uses the structure specified by f. This function returns TRUE on success and FALSE on failure. The return code are the same as for Write().
Invalidate(char *s, char *c)
This call invalidates chunk c in space s. This function returns TRUE on success and FALSE on failure. Note that the return codes are the Write() return codes inverted.


DSS_TRANSACT_CLIENT_WRITE_FAIL	The chunk is now invalid which means that either this function has succeeded or that the chunk was already invalid.
DSS_TRANSACT_CLIENT_WRITE_OK	The chunk is now valid which means that this function has failed.

The reason for the inverted return codes is that Invalidate() is actually a specialized Write() and uses the Write() mechanism directly.
char *StartInvalidate(char *s, char *c, unsigned long *l)

long StopInvalidate(char *s, char *c)
These calls are specialized versions of StartWrite and StopWrite which leaves the chunk invalidated when StopInvalidate is complete. The return codes for StartInvalidate are the same as for StartWrite. The return codes for StopInvalidate are the same as for Invalidate.

CONNECTION OBJECT RELATED MEMBER FUNCTIONS

char GetLastReturnCode()
This call returns the last set return code.
char *ReturnCodeString(char return_code)
This call returns a string representation of the return_code. The returned string buffer is part of DSS_Connection and should not be freed or altered.
DSS_ChunkConfig *GetDefaultChunkConfig()
This call returns the default DSS_ChunkConfig structure. Changes to this structure will affect any subsequent use of the DSS_Connection.