DosPurgeQueue: Difference between revisions
mNo edit summary |
|||
| Line 1: | Line 1: | ||
Purges a queue of all its elements. | Purges a queue of all its elements. | ||
| Line 7: | Line 6: | ||
#include <os2.h> | #include <os2.h> | ||
HQUEUE hq; /* | HQUEUE hq; /* The handle of the queue to be purged. */ | ||
APIRET ulrc; /* | APIRET ulrc; /* Return Code. */ | ||
ulrc = DosPurgeQueue(hq); | ulrc = DosPurgeQueue(hq); | ||
</PRE> | |||
==Parameters== | ==Parameters== | ||
; | ;hq (HQUEUE) - input : The handle of the queue to be purged. | ||
==Return Code== | ==Return Code== | ||
ulrc (APIRET) - returns | ulrc (APIRET) - returns | ||
DosPurgeQueue returns one of the following values: | DosPurgeQueue returns one of the following values: | ||
* 0 NO_ERROR | * 0 NO_ERROR | ||
* 330 ERROR_QUE_PROC_NOT_OWNED | * 330 ERROR_QUE_PROC_NOT_OWNED | ||
| Line 27: | Line 25: | ||
The server process issues DosPurgeQueue to empty a queue of all its elements. This function is not available to client processes. | The server process issues DosPurgeQueue to empty a queue of all its elements. This function is not available to client processes. | ||
'''Warning:''' This is an unconditional purge of all elements in the queue. | '''Warning:''' This is an unconditional purge of all elements in the queue. | ||
==Example Code== | ==Example Code== | ||
This example creates a queue, writes to it, queries it, purges it, and finally closes it. | This example creates a queue, writes to it, queries it, purges it, and finally closes it. | ||
<PRE> | <PRE> | ||
#define INCL_DOSQUEUES /* DOS Queue values */ | #define INCL_DOSQUEUES /* DOS Queue values */ | ||
#define INCL_DOSERRORS /* DOS Error values */ | #define INCL_DOSERRORS /* DOS Error values */ | ||
| Line 102: | Line 99: | ||
return NO_ERROR; | return NO_ERROR; | ||
} | } | ||
</PRE> | |||
==Related Functions== | ==Related Functions== | ||
* [[ | *[[DosCloseQueue]] | ||
* [[ | *[[DosCreateQueue]] | ||
* [[ | *[[DosOpenQueue]] | ||
* [[ | *[[DosPeekQueue]] | ||
* [[ | *[[DosQueryQueue]] | ||
* [[ | *[[DosReadQueue]] | ||
* [[ | *[[DosWriteQueue]] | ||
[[Category: | [[Category:Dos]] | ||
Revision as of 02:55, 6 January 2017
Purges a queue of all its elements.
Syntax
#define INCL_DOSQUEUES #include <os2.h> HQUEUE hq; /* The handle of the queue to be purged. */ APIRET ulrc; /* Return Code. */ ulrc = DosPurgeQueue(hq);
Parameters
- hq (HQUEUE) - input
- The handle of the queue to be purged.
Return Code
ulrc (APIRET) - returns
DosPurgeQueue returns one of the following values:
- 0 NO_ERROR
- 330 ERROR_QUE_PROC_NOT_OWNED
- 337 ERROR_QUE_INVALID_HANDLE
Remarks
The server process issues DosPurgeQueue to empty a queue of all its elements. This function is not available to client processes.
Warning: This is an unconditional purge of all elements in the queue.
Example Code
This example creates a queue, writes to it, queries it, purges it, and finally closes it.
#define INCL_DOSQUEUES /* DOS Queue values */
#define INCL_DOSERRORS /* DOS Error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>
#define QUE_NAME "\\QUEUES\\PANDAWRITE\\LOCALQUEUE"
int main(VOID) {
HQUEUE QueueHandle = NULLHANDLE; /* Queue handle */
CHAR *DataBuffer = ""; /* Data to write to queue */
ULONG ulNumElems = 0L; /* Number of elements on queue */
APIRET rc = NO_ERROR; /* Return code */
rc = DosCreateQueue(&QueueHandle, /* Queue handle */
QUE_LIFO | /* Last In, First Out ordering */
QUE_CONVERT_ADDRESS, /* Do 16-bit to 32-bit conversion */
QUE_NAME); /* Name of the queue */
if (rc!= NO_ERROR) {
printf ("DosCreateQueue error: return code = %u\n", rc);
return 1;
}
DataBuffer = "Element 1 of 2";
rc = DosWriteQueue (QueueHandle, 100L, strlen(DataBuffer),
(PVOID)DataBuffer, 0L);
if (rc!= NO_ERROR) {
printf ("DosWriteQueue error: return code = %u\n", rc);
return 1;
}
rc = DosQueryQueue (QueueHandle, &ulNumElems);
if (rc != NO_ERROR) {
printf ("DosQueryQueue error: return code = %u\n", rc);
return 1;
} else { printf ("DosQueryQueue: %u elements\n", ulNumElems); }
DataBuffer = "Element 2 of 2";
rc = DosWriteQueue (QueueHandle, 200L, strlen(DataBuffer),
(PVOID)DataBuffer, 0L);
if (rc!= NO_ERROR) {
printf ("DosWriteQueue error: return code = %u\n", rc);
return 1;
}
rc = DosQueryQueue (QueueHandle, &ulNumElems);
if (rc != NO_ERROR) {
printf ("DosQueryQueue error: return code = %u\n", rc);
return 1;
} else { printf ("DosQueryQueue: %u elements\n", ulNumElems); }
rc = DosPurgeQueue (QueueHandle);
if (rc != NO_ERROR) {
printf ("DosPurgeQueue error: return code = %u\n", rc);
return 1; }
rc = DosQueryQueue (QueueHandle, &ulNumElems);
if (rc != NO_ERROR) {
printf ("DosQueryQueue error: return code = %u\n", rc);
return 1;
} else { printf ("DosQueryQueue: %u elements\n", ulNumElems); }
rc = DosCloseQueue(QueueHandle); /* Close the queue */
if (rc!= NO_ERROR) {
printf ("DosCloseQueue error: return code = %u\n", rc);
return 1; }
return NO_ERROR;
}