The "dsra" Package

These routines are meant to provide a mechanism to read the recursive, heirarchical data structure supported in Karma from open channels, in ASCII format. 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

dsra_multi_desc	Read ASCII representation of a multi_array data structure.
dsra_packet_desc	Read ASCII representation of a packet descriptor.
dsra_element_desc	Read ASCII representation of an element descriptor.
dsra_array_desc	Read ASCII representation of an array descriptor.
dsra_dim_desc	Read ASCII representation of a dimension descriptor.
dsra_multi_data	READ ASCII representation of data in a multi_array descriptor.
dsra_packet	Read ASCII representation of a data packet.
dsra_element	Read ASCII representation of an element.
dsra_array	Read ASCII representation of an array of data packets.
dsra_list	Read ASCII represention of a linked list.
dsra_flag	Read ASCII representation of a boolean value.
dsra_type	Read ASCII representation of a data type.
dsra_uint	Read the ASCII representation of an unsigned integer.
dsra_int	Read the ASCII representation of a signed integer.
dsra_float	Read the ASCII representation of a floating point value.
dsra_double	Read ASCII representation of a double floating point value.

Functions

multi_array * dsra_multi_desc (Channel channel)

This routine will read the ASCII representation of a multi_array data structure descriptor from a channel object.

Parameters:

channel : The channel object to read from.

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

The routine will NOT allocate space for data, nor will it read any data.

packet_desc * dsra_packet_desc (Channel channel)

This routine will read the ASCII 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 to read from.

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

flag dsra_element_desc (Channel channel, unsigned int *type, char name[])

Read ASCII representation of an element descriptor.

Parameters:

channel : The channel object to read from.
type : The type of the element is written here.
name : The name of the element is written here. The length of the buffer must be STRING_LENGTH bytes.

Returns: TRUE if a valid element descriptor was read, else FALSE.
Multithreading Level: Unsafe

array_desc * dsra_array_desc (Channel channel, unsigned int type)

Read ASCII representation of an array descriptor.

Parameters:

channel : The channel object to read from.
type : The type of the array. Legal values for this are: ARRAYP K_ARRAY

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

dim_desc * dsra_dim_desc (Channel channel)

Read ASCII representation of a dimension descriptor.

Parameters:

channel : The channel object to read from.

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

flag dsra_multi_data (Channel channel, multi_array *multi_desc)

READ ASCII representation of data in a multi_array descriptor.

Parameters:

channel : The channel object to read from.
multi_desc : The multi_array descriptor to store the data in. This is modified.

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

The routine will only allocate space for linked list as it reads them.

flag dsra_packet (Channel channel, packet_desc *descriptor, char *packet)

This routine will read the ASCII representation of a data packet. The routine will recursively read in sub arrays and linked lists.

Parameters:

channel : The channel object to read from.
descriptor : The packet descriptor.
packet : The packet data will be written here. The packet storage must already have been allocated.

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

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

Read ASCII representation of an element.

Parameters:

channel : The channel object to read from.
type : The type of the element.
desc : The descriptor for the element.
element : The element data will be written here.

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

flag dsra_array (Channel channel, array_desc *descriptor, char *array)

Read ASCII representation of an array of data packets.

Parameters:

channel : The channel object to read from.
descriptor : The array descriptor.
array : The array data will be written here.

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

flag dsra_list (Channel channel, packet_desc *descriptor, list_header *header)

This routine will read in the ASCII 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 to read from.
descriptor : The descriptor for the list packets.
header : The linked list header. This is modified. The linked list entries will be contiguous in memory.

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

flag dsra_flag (Channel channel, flag *logical)

Read ASCII representation of a boolean value.

Parameters:

channel : The channel object to read from.
logical : The boolean value will be written here.

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

flag dsra_type (Channel channel, unsigned int *type)

Read ASCII representation of a data type.

Parameters:

channel : The channel object to read from.
type : The type value will be written here.

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

flag dsra_uint (Channel channel, unsigned int *value)

Read the ASCII representation of an unsigned integer.

Parameters:

channel : The channel object to read from.
value : The result is written here.

Returns: TRUE if successful, else FALSE.
Multithreading Level: Unsafe

flag dsra_int (Channel channel, int *value)

Read the ASCII representation of a signed integer.

Parameters:

channel : The channel object to read from.
value : The result is written here.

Returns: TRUE if successful, else FALSE.
Multithreading Level: Unsafe

flag dsra_float (Channel channel, float *value)

Read the ASCII representation of a floating point value.

Parameters:

channel : The channel object to read from.
value : The result is written here.

Returns: TRUE if successful, else FALSE.
Multithreading Level: Unsafe

flag dsra_double (Channel channel, double *value)

Read ASCII representation of a double floating point value.

Parameters:

channel : The channel object to read from.
value : The result is written here.

Returns: TRUE if successful, else FALSE.
Multithreading Level: Unsafe

Contact: Richard Gooch
Web Development: Ariel Internet Services