# The "dsxfr" Package

These routines are meant to provide high level transfer of the recursive, heirarchical data structure supported in Karma from and to files and connections.

Library: karma
Link With: -lkarma

#### Functions

dsxfr_register_connection_limits | Register connection limits for "multi_array" protocol.
dsxfr_put_multi | Write a multi_array data structure.
dsxfr_send_multi | Send a multi_array data structure over a connection.
dsxfr_get_multi | Read a multi_array data structure.
dsxfr_register_read_func | Register callback for new "multi_array" data.
dsxfr_register_close_func | Register callback for closed "multi_array" connection.
dsxfr_test_split | Test if a file is part of a split Karma file.
dsxfr_read_split | Read a multi_array data structure.

#### Prototype Functions

dsxfr_PROTO_read_func | New "multi_array" data callback.
dsxfr_PROTO_close_func | Callback for "multi_array" connection closures.

## Functions

void dsxfr_register_connection_limits (int max_incoming, int max_outgoing)

This routine will register the maximum number of incoming (server) and outgoing (client) connections for the transfer of the general data structure. The protocol used is: "multi_array".

Parameters:

- max_incoming : The maximum number of incoming connections. If this is less than 0, no connections are permitted. If this is 0, an unlimited number of connections is permitted.
- max_outgoing : The maximum number of outgoing connections. If this is less than 0, no connections are permitted. If this is 0, an unlimited number of connections is permitted.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

- This routine ONLY registers the server and client callback routines, the application must first call <conn_register_managers> in all cases and must call <conn_become_server> if it wishes to accept connections.

flag dsxfr_put_multi (CONST char *object, multi_array *multi_desc)

This routine will put (write to disc, transmit over connection) a multi_desc general data structure to a named object.

Parameters:

- object : The object name. If the object is named "connections" then the data will be transmitted to all available connections with the "multi_array" protocol. If the object is named "connections:{module_name}" then the data will be transmitted to all available connections to modules with the name {module_name} and with the "multi_array" protocol. If the object is named "connections:!module_name" then the data will be transmitted to all available connections with the "multi_array" protocol to all modules except those with the name module_name. If the object is named "connection[#]" then the data will be transmitted to the "multi_array" protocol connection with index: # (starting from 0). If the object is named "filename_connection" then the data will be transmitted to all available connections with the "multi_array" protocol. In all other cases the data will be written to a disc file. The routine will append a ".kf" extension if not already specified. If the disc file already exists, the old data file is first renamed to have a trailing '~' (tilde) character.
- multi_desc : A pointer to the data structure.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag dsxfr_send_multi (Connection connection, CONST multi_array *multi_desc, CONST char *name)

Send a multi_array data structure over a connection.

Parameters:

- connection : The connection to send the data to. If this is NULL the data will be sent to all "multi_array" connections.
- multi_desc : The data to send.
- name : The event name. This may be NULL.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

multi_array * dsxfr_get_multi (CONST char *object, flag cache, unsigned int mmap_option, flag writable)

This routine will get (read from disc, read from connection) a multi_desc general data structure from a named object.

Parameters:

- object : The object name. If the object is named "connection[#]" then whatever data has been previously sent over the "multi_array" protocol connection with index: # (starting from 0) will be returned. In all other cases the data will be read from a disc file. The routine will append a ".kf" extension if not already specified.
- cache : If TRUE and the data is read from a disc, the data structure and filename relationship is cached. This means that a subsequent attempt to read the data will not require the disc to be accessed. This relationship is lost if the data structure is destroyed. Also, in both this case and the case where the data structure is "read" from a connection, the attachment count for the data structure is incremented *every time* this routine is called. Read the documentation for the <ds_dealloc_multi> routine for information on attachment counts. The attachment count is *not* incremented when reading a disc file without adding it to the cache list.
- mmap_option : Option to control memory mapping when reading from disc. See ch_MAP_CONTROLS for a list of legal values.
- writable : If TRUE, the mapped structure will be writable. When the data structure data is modified these changes will be reflected in the disc file. The shape of the data structure cannot be changed though mapping. If FALSE and the structure is written to, a segmentation fault occurs.

Returns: A pointer to the data structure on success, else NULL.
Multithreading Level: Unsafe
Note:

- Reading from a connection with this routine does *not* block, if no prior data was transmitted, the routine returns NULL. Multiple calls to this routine will return the same data structure *until* new data is received over the connection.

void dsxfr_register_read_func (void (*read_func) ())

This routine will register a function which is to be called when new data arrives on a "multi_array" connection.

Parameters:

- read_func : A pointer to the function. The prototype function is dsxfr_PROTO_read_func.

Returns: Nothing.
Multithreading Level: Unsafe

void dsxfr_register_close_func ( void (*close_func) () )

This routine will register a function which is to be called when a "multi_array" connection closes.

Parameters:

- close_func : A pointer to the function. The prototype function is dsxfr_PROTO_close_func.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag dsxfr_test_split (CONST char *filename)

Test if a file is part of a split Karma file.

Parameters:

- filename : The name of any file in the Karma file set.

Returns: TRUE if the file is part of a Karma file set, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * dsxfr_read_split (char *filename, flag ascii, flag guess)

Read a multi_array data structure.

Parameters:

- filename : The filename with some extension. This will be modified.
- ascii : If TRUE the data file is assumed to be ASCII, else binary.
- guess : If TRUE the function attempts to guess whether the data file is ASCII or binary (and ignores the value of ascii).

Returns: A pointer to the data structure on success, else NULL.
Multithreading Level: Unsafe

## Prototype Functions

void dsxfr_PROTO_read_func (flag first_time_data, unsigned int connection_num)

This routine is called when new data arrives on any "multi_array" connection.

Parameters:

- first_time_data : If data appears on a connection for the first time, this will be TRUE. Any subsqeuent data that appears on a connection will not set this flag.
- connection_num : The index number of the connection.

Returns: Nothing.
Multithreading Level: Unsafe

void dsxfr_PROTO_close_func (flag data_deallocated)

This routine is called when any "multi_array" connection closes.

Parameters:

- data_deallocated : If there was a multi_array data structure already received over the connection, it is deallocated and this is TRUE.

Returns: Nothing.
Multithreading Level: Unsafe

Back to Karma Home Page