c_qinsert - Insert an object into a queue

SYNTAX

long FUNCTION c_qinsert(q, object, compare)

     long q;        
     void *object;   
     long (compare)();

PARAMETERS

q (long, input)

The number of the queue in which to insert. This number is returned by c_qcreate().

object (void *, input)

A pointer to the object to insert into the queue.

compare (long function, input)

A function used to compare two objects in the queue. This function should accept two pointers as arguments and return a value less than zero if the first object is less than the second, zero if the two objects are equal, and a value greater than zero if the first is greater than the second.

DESCRIPTION

This routine is used to insert an object into a queue. If the queue was created in ascending or descending order, the compare() function is used to find the proper position in the queue for the new object before it is inserted. If the queue was created "fifo" the new object will be inserted at the end of the queue. If the queue was created "lifo" the new object will be inserted at the beginning of the queue.

The application is required to allocate new space for each object that is added to the queue.

The current position in the queue is set to the new object inserted into the queue.

RETURN VALUE

c_qinsert() returns

      0 --> Successful completion.  The object was inserted into the 
	    queue.
     -1 --> Operation failed.  No such queue exists or error allocating 
	    memory for the new object.