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_multiWrite a multi_array data structure.
dsrw_write_packet_descWrite a packet descriptor in binary format.
dsrw_write_element_descWrite an element descriptor in binary format.
dsrw_write_array_descWrite an array descriptor in binary format.
dsrw_write_dim_descWrite a dimension descriptor in binary format.
dsrw_write_packetWrite packet data in binary format.
dsrw_write_elementWrite an element in binary format.
dsrw_write_arrayWrite an array in binary format.
dsrw_write_listWrite a linked list in binary format.
dsrw_write_packetsWrite the binary representation of many data packets.
dsrw_write_flagWrite a boolean value in binary format to a channel object.
dsrw_read_multiRead the binary representation of a multi_array structure.
dsrw_read_packet_descRead the binary representation of a packet descriptor.
dsrw_read_array_descRead the binary representation of an array descriptor.
dsrw_read_dim_descRead the binary representation of a dimension descriptor.
dsrw_read_packetRead the binary representation of a data packet.
dsrw_read_elementRead the binary representation of an element.
dsrw_read_arrayRead the binary representation of an array.
dsrw_read_listRead the binary representation of a linked list.
dsrw_read_packetsRead the binary representation of many data packets.
dsrw_read_flagRead the binary representation of a boolean.
dsrw_read_typeRead 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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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


Contact: Richard Gooch
Web Development: Ariel Internet Services