DosCloseQueue: Difference between revisions
mNo edit summary |
|||
| Line 1: | Line 1: | ||
Ends access to a queue, or deletes a queue. | Ends access to a queue, or deletes a queue. | ||
| Line 11: | Line 10: | ||
ulrc = DosCloseQueue(hq); | ulrc = DosCloseQueue(hq); | ||
</PRE> | |||
==Parameters== | ==Parameters== | ||
; | ;hq (HQUEUE) - input : The handle of the queue to be closed. | ||
:This is the handle received from a previous call to [[DosCreateQueue]] or [[DosOpenQueue]]. | |||
==Return Code== | ==Return Code== | ||
ulrc (APIRET) - returns | ulrc (APIRET) - returns | ||
DosCloseQueue returns one of the following values: | DosCloseQueue returns one of the following values: | ||
* 0 NO_ERROR | * 0 NO_ERROR | ||
* 337 ERROR_QUE_INVALID_HANDLE | * 337 ERROR_QUE_INVALID_HANDLE | ||
| Line 30: | Line 27: | ||
For the owner, any outstanding elements are deleted. Other processes that have the queue open will receive the ERROR_QUE_INVALID_HANDLE return code on their next request. | For the owner, any outstanding elements are deleted. Other processes that have the queue open will receive the ERROR_QUE_INVALID_HANDLE return code on their next request. | ||
For a writer of the queue, access to the queue is ended, but the queue elements are not deleted. | For a writer of the queue, access to the queue is ended, but the queue elements are not deleted. | ||
==Example Code== | ==Example Code== | ||
This example creates and opens a queue named "SPECIAL.QUE", writes to it, reads from it, and finally closes it. | This example creates and opens a queue named "SPECIAL.QUE", writes to it, reads from it, and finally closes it. | ||
<PRE> | <PRE> | ||
#define INCL_DOSQUEUES /* DOS Queue values */ | #define INCL_DOSQUEUES /* DOS Queue values */ | ||
#define INCL_DOSPROCESS /* DOS thread and process values */ | #define INCL_DOSPROCESS /* DOS thread and process values */ | ||
| Line 110: | Line 105: | ||
return NO_ERROR; | return NO_ERROR; | ||
} | } | ||
</PRE> | |||
==Related Functions== | ==Related Functions== | ||
* [[ | * [[DosCreateQueue]] | ||
* [[ | * [[DosOpenQueue]] | ||
* [[ | * [[DosPeekQueue]] | ||
* [[ | * [[DosPurgeQueue]] | ||
* [[ | * [[DosQueryQueue]] | ||
* [[ | * [[DosReadQueue]] | ||
* [[ | * [[DosWriteQueue]] | ||
[[Category: | [[Category:Dos]] | ||
Revision as of 02:01, 6 January 2017
Ends access to a queue, or deletes a queue.
Syntax
#define INCL_DOSQUEUES #include <os2.h> HQUEUE hq; /* The handle of the queue to be closed. */ APIRET ulrc; /* Return Code. */ ulrc = DosCloseQueue(hq);
Parameters
- hq (HQUEUE) - input
- The handle of the queue to be closed.
- This is the handle received from a previous call to DosCreateQueue or DosOpenQueue.
Return Code
ulrc (APIRET) - returns
DosCloseQueue returns one of the following values:
- 0 NO_ERROR
- 337 ERROR_QUE_INVALID_HANDLE
Remarks
DosCloseQueue ends further processing of a queue by the requesting process. The action taken depends on whether the requester is the owner of the queue or a writer of the queue.
For the owner, any outstanding elements are deleted. Other processes that have the queue open will receive the ERROR_QUE_INVALID_HANDLE return code on their next request.
For a writer of the queue, access to the queue is ended, but the queue elements are not deleted.
Example Code
This example creates and opens a queue named "SPECIAL.QUE", writes to it, reads from it, and finally closes it.
#define INCL_DOSQUEUES /* DOS Queue values */
#define INCL_DOSPROCESS /* DOS thread and process values */
#define INCL_DOSERRORS /* DOS error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>
int main(VOID) {
PSZ szQueueName = "\\QUEUES\\SPECIAL.QUE";
HQUEUE hqSpecialQue = NULLHANDLE; /* Queue handle */
PSZ DataBuffer = ""; /* Data buffer for queue data */
REQUESTDATA Request = {0}; /* Reques */
PID pidOwner = 0;
ULONG ulDataLen = 0; /* Length of data returned */
BYTE ElemPrty = 0; /* Priority of element (returned) */
APIRET rc = NO_ERROR; /* Return code */
rc = DosCreateQueue(&hqSpecialQue, /* Queue handle */
QUE_FIFO | /* First-In First-Out order */
QUE_CONVERT_ADDRESS, /* Convert 16-bit addresses to 32 */
szQueueName); /* Name of the queue to create */
if (rc!= NO_ERROR) {
printf ("DosCreateQueue error: return code = %u\n", rc);
return 1;
}
rc = DosOpenQueue (&pidOwner, /* PID of queue owner */
&hqSpecialQue, /* Handle for created queue */
szQueueName); /* Name of the queue to open */
if (rc!= NO_ERROR) {
printf ("DosOpenQueue error: return code = %u\n", rc);
return 1;
}
DataBuffer = "To be, or not to be. That is the question...";
rc = DosWriteQueue (hqSpecialQue, /* Queue to write to */
12345L, /* Request data */
strlen(DataBuffer), /* Length of data to write */
DataBuffer, /* Pointer to data */
0L); /* Priority (not applicable here) */
if (rc!= NO_ERROR) {
printf ("DosWriteQueue error: return code = %u\n", rc);
return 1;
}
DataBuffer = ""; /* Clear the DataBuffer */
Request.pid = pidOwner; /* process ID for the DosReadQueue */
rc = DosReadQueue (hqSpecialQue, /* Queue to read from */
&Request, /* Request data from write */
&ulDataLen, /* Length of data returned */
(PVOID) &DataBuffer, /* The data */
0L, /* Remove first element */
DCWW_WAIT, /* Wait for available data */
&ElemPrty, /* Priority of data (returned) */
0L); /* Semaphore to use when not waiting */
if (rc!= NO_ERROR) {
printf ("DosReadQueue error: return code = %u\n", rc);
return 1;
} else {
printf ("DosReadQueue returns: '%s'\n", DataBuffer);
printf (" (Request data = %u)\n", Request.ulData);
}
rc = DosCloseQueue(hqSpecialQue); /* Close the queue */
if (rc!= NO_ERROR) {
printf ("DosCloseQueue error: return code = %u\n", rc);
return 1;
}
return NO_ERROR;
}