The "dsxfr" Package

Library: karma
Link With: -lkarma

Functions

Prototype Functions

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.
  

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

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.
  

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 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.
  

• 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.

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.
  

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.
  

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.
  

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.