The "dsrw" Package

These routines are meant to provide a mechanism to read and write the recursive, heirarchical data structure supported in Karma from and to open channels. The use of these routines is NOT recommended. The dsxfr routines are the preferred means of transferring data structures.

Library: karma
Link With: -lkarma

Functions

dsrw_filter_setup	Set up a Karma data filter.
dsrw_filter_process	Read in data and write in Karma format.
dsrw_write_multi	Write a multi_array data structure.
dsrw_write_multi_header	Write a multi_array data structure header.
dsrw_write_packet_desc	Write a packet descriptor in binary format.
dsrw_write_element_desc	Write an element descriptor in binary format.
dsrw_write_array_desc	Write an array descriptor in binary format.
dsrw_write_dim_desc	Write a dimension descriptor in binary format.
dsrw_write_packet	Write packet data in binary format.
dsrw_write_element	Write an element in binary format.
dsrw_write_array	Write an array in binary format.
dsrw_write_list	Write a linked list in binary format.
dsrw_write_packets	Write the binary representation of many data packets.
dsrw_write_flag	Write a boolean value in binary format to a channel object.
dsrw_read_multi	Read the binary representation of a multi_array structure.
dsrw_read_multi_header	Read the binary representation of a multi_array header.
dsrw_read_packet_desc	Read the binary representation of a packet descriptor.
dsrw_read_array_desc	Read the binary representation of an array descriptor.
dsrw_read_dim_desc	Read the binary representation of a dimension descriptor.
dsrw_read_packet	Read the binary representation of a data packet.
dsrw_read_element	Read the binary representation of an element.
dsrw_read_array	Read the binary representation of an array.
dsrw_read_list	Read the binary representation of a linked list.
dsrw_read_packets	Read the binary representation of many data packets.
dsrw_read_flag	Read the binary representation of a boolean.
dsrw_read_type	Read the binary representation of a data type.

Prototype Functions

dsrw_PROTO_read_func

Read data and write to a buffer.

Functions

EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * dsrw_filter_setup (Channel channel, CONST array_desc *arr_desc, CONST char *infile, CONST char *outfile)

Set up a Karma data filter.

Parameters:

channel : The channel to write to.
arr_desc : The array descriptor.
infile : The input filename.
outfile : The output Karma filename.

Returns: A multi_array pointer on success, else NULL.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag dsrw_filter_process (Channel channel, multi_array *multi_desc, flag (*read_func) (), void *info)

Read in data and write in Karma format.

Parameters:

channel : The channel to write the Karma data to.
multi_desc : The multi_array descriptor to write.
func : The function to call when new data should be read. The prototype function is dsrw_PROTO_read_func.
info : An arbitrary pointer which will be passed to func.

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

flag dsrw_write_multi (Channel channel, CONST multi_array *multi_desc)

This routine will write a binary multi_array descriptor to a channel object. All descriptors and data, as well as history strings are written.

Parameters:

channel : The channel object.
multi_desc : The data structure.

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

flag dsrw_write_multi_header (Channel channel, CONST multi_array *multi_desc)

This routine will write a binary multi_array descriptor header to a channel object. The various top-level packet descriptors, data and history are not written.

Parameters:

channel : The channel object.
multi_desc : The data structure.

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

flag dsrw_write_packet_desc (Channel channel, CONST packet_desc *pack_desc)

This routine will write the binary format of a packet descriptor to a channel object. The routine will also write all lower levels of array or linked list descriptors.

Parameters:

channel : The channel object.
pack_desc : The packet descriptor.

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

flag dsrw_write_element_desc (Channel channel, unsigned int type, CONST char *desc)

This routine will write the binary format of an element descriptor to a channel object. If the element is an array pointer or a linked list pointer, that descriptor will also be written.

Parameters:

channel : The channel object.
type : The type of the element.
desc : The element descriptor.

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

flag dsrw_write_array_desc (Channel channel, CONST array_desc *arr_desc)

This routine will write the binary representation of an array descriptor to a channel object. The packet descriptor for the array will also be written (this is a recursive process).

Parameters:

channel : The channel object.
arr_desc : The array descriptor.

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

flag dsrw_write_dim_desc (Channel channel, CONST dim_desc *dimension)

This routine will write the binary representation of a dimension descriptor to a channel object.

Parameters:

channel : The channel object.
dimension : The dimension descriptor.

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

flag dsrw_write_packet (Channel channel, CONST packet_desc *pack_desc, CONST char *packet)

This routine will write the binary representation of a data packet to a channel object. The routine will recursively write sub arrays and linked lists of packets.

Parameters:

channel : The channel object.
pack_desc : The packet descriptor.
packet : The packet data.

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

flag dsrw_write_element (Channel channel, unsigned int type, CONST char *desc, CONST char *element)

This routine will write the binary representation of an element to a channel object.

Parameters:

channel : The channel object.
type : The type of the element.
desc : The descriptor for the element.
element : A pointer to the element data.

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

flag dsrw_write_array (Channel channel, CONST array_desc *arr_desc, CONST char *element, flag pad)

This routine will write the binary representation of an array to a channel object. The routine will recursively write any sub arrays or linked lists of packets.

Parameters:

channel : The channel object.
arr_desc : The array descriptor.
element : The element to write the array pointer to.
pad : If TRUE the array will be padded on a selected boundary (this is the case when writing .kf files).

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

flag dsrw_write_list (Channel channel, CONST packet_desc *pack_desc, CONST list_header *list_head)

This routine will write the binary representation of the data in a linked list to a channel object. The routine will recursively write any sub arrays or linked lists of packets.

Parameters:

channel : The channel object.
pack_desc : The packet descriptor for the list entries.
list_head : The linked list header.

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

flag dsrw_write_packets (Channel channel, CONST packet_desc *descriptor, CONST char *source, unsigned long num_packets)

This routine will write the binary representation many data packets to a channel object. The routine will recursively write out sub arrays and linked lists.

Parameters:

channel : The channel object.
descriptor : The descriptor for the packets.
source : The packet data.
num_packets : The number of packets to write.

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

flag dsrw_write_flag (Channel channel, flag logical)

Write a boolean value in binary format to a channel object.

Parameters:

channel : The channel object.
logical : The boolean value.

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

multi_array * dsrw_read_multi (Channel channel)

This routine will read the binary representation of a multi_array general data structure header from a channel object and will allocate the required descriptors. The routine will then read in the data from the channel object and will write it into the data structure(s) created.

Parameters:

channel : The channel object.

Returns: A pointer to the multi array header on success, else NULL.
Multithreading Level: Unsafe

multi_array * dsrw_read_multi_header (Channel channel)

This routine will read the binary representation of a multi_array general data structure header from a channel object. The various top-level packet descriptors, data and history are not read.

Parameters:

channel : The channel object.

Returns: A pointer to the multi array header on success, else NULL.
Multithreading Level: Unsafe

packet_desc * dsrw_read_packet_desc (Channel channel)

This routine will read the binary representation of a packet descriptor from a channel object. The routine will recursively read in array and linked list descriptors if required.

Parameters:

channel : The channel object.

Returns: A pointer to the packet descriptor on success, else NULL.
Multithreading Level: Unsafe

array_desc * dsrw_read_array_desc (Channel channel, unsigned int type)

This routine will read the binary representation of an array descriptor from a channel object. The routine will recursively read the packet descriptor for the array.

Parameters:

channel : The channel object.
type : The type of the array. Legal values are: ARRAYP (old format) K_ARRAY (new format)

Returns: A pointer to the array descriptor on success, else NULL.
Multithreading Level: Unsafe

dim_desc * dsrw_read_dim_desc (Channel channel)

This routine will read the binary representation of a dimension descriptor from a channel object.

Parameters:

channel : The channel object.

Returns: A pointer to the dimension descriptor on success, else NULL.
Multithreading Level: Unsafe

flag dsrw_read_packet (Channel channel, CONST packet_desc *descriptor, char *packet)

This routine will read the binary representation of a data packet from a channel object. The routine will recursively read in sub arrays and linked lists.

Parameters:

channel : The channel object.
descriptor : The descriptor for the packet.
packet : The packet data will be written here.

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

flag dsrw_read_element (Channel channel, unsigned int type, char *desc, char *element)

This routine will read the binary representation of an element from a channel object. If the element type is a pointer to an array or linked lists, the routine will recursively read in the array or linked list of packets.

Parameters:

channel : The channel object.
type : The type of the element.
desc : The element descriptor.
element : A pointer to the element storage. This will be written to.

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

flag dsrw_read_array (Channel channel, CONST array_desc *arr_desc, char *element, flag pad)

This routine will read the binary representation of an array from a channel object. The routine will recursively read in array packets.

Parameters:

channel : The channel object.
arr_desc : The array descriptor.
element : The array pointer will be written here.
pad : If TRUE the array will be padded on a selected boundary (this is the case when reading .kf files).

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

flag dsrw_read_list (Channel channel, CONST packet_desc *descriptor, list_header *header)

This routine will read in the binary representation of a linked list of data from a channel object. The routine will recursively read in sub arrays and linked lists.

Parameters:

channel : The channel object.
descriptor : The packet descriptor for the list entries.
header : The linked list header. The linked list entries and data will be contiguous in memory.

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

flag dsrw_read_packets (Channel channel, CONST packet_desc *descriptor, char *dest, unsigned long num_packets)

This routine will read the binary representation many data packets from a channel object. The routine will recursively read in sub arrays and linked lists.

Parameters:

channel : The channel object.
descriptor : The descriptor for the packets.
dest : The packet data will be written here.
num_packets : The number of packets to read.

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

flag dsrw_read_flag (Channel channel, flag *logical)

This routine will read in the binary representation of a boolean flag from a channel object.

Parameters:

channel : The channel object.
logical : The boolean value is written here.

Returns: TRUE if the flag was read in without error, else FALSE.
Multithreading Level: Unsafe

flag dsrw_read_type (Channel channel, unsigned int *type)

This routine will read in the binary representation of a data type from a channel object.

Parameters:

channel : The channel object.
type : The type value is written here.

Returns: TRUE if the type was read without error, else FALSE.
Multithreading Level: Unsafe

Prototype Functions

flag dsrw_PROTO_read_func (void *buffer, uaddr num_values, void *info)

Read data and write to a buffer.

Parameters:

buffer : The buffer to write to.
num_values : The number of values to read.
info : The arbitrary function information pointer.

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

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services