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_write_multi	Write a multi_array data structure.
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_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.

Functions

void dsrw_write_multi (Channel channel, 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: Nothing.
Multithreading Level: Unsafe

void dsrw_write_packet_desc (Channel channel, 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: Nothing.
Multithreading Level: Unsafe

void dsrw_write_element_desc (Channel channel, unsigned int type, 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: Nothing.
Multithreading Level: Unsafe

void dsrw_write_array_desc (Channel channel, 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: Nothing.
Multithreading Level: Unsafe

void dsrw_write_dim_desc (Channel channel, 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: Nothing.
Multithreading Level: Unsafe

void 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: Nothing.
Multithreading Level: Unsafe

void dsrw_write_element (Channel channel, unsigned int type, 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: Nothing.
Multithreading Level: Unsafe

void dsrw_write_array (Channel channel, 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: Nothing.
Multithreading Level: Unsafe

void dsrw_write_list (Channel channel, packet_desc *pack_desc, 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: Nothing.
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

void 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: Nothing.
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

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 *descriptor, 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.
descriptor : 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

Contact: Richard Gooch
Web Development: Ariel Internet Services