Manual de programación de OS/2/Llamadas DOSxxx para colas
GRUPO DE LLAMADAS DOSxxx (8)
(Colas)
<A NAME="DOSCLOSEQUEUE">
DosCloseQueue
</A>
DosCloseQueue finaliza el acceso a una cola si el proceso que lo llama no es su dueño, o bien la elimina, en el caso de que sí lo sea. En el segundo caso, todos los elementos que contenga son borrados, y el resto de procesos que estuviesen conectados a ella recibirían un error.
#define INCL_BASE
#include <os2.h>
HQUEUE QueueHandle;
APIRET rc; /* Codigo de error */
rc = DosCloseQueue(QueueHandle);
Parámetros | |
---|---|
QueueHandle | Handle de la cola a cerrar, dado por DosCreateQueue o por DosOpenQueue. |
Codigos de error | |
---|---|
0 | Sin error |
337 | Handle de cola no válido |
<A NAME="DOSCREATEQUEUE">
DosCreateQueue
</A>
DosCreateQueue crea una nueva cola.
#define INCL_BASE
#include <os2.h>
PHQUEUE phqRWHandle;
ULONG ulQueueFlags;
PSZ pszQueueName;
APIRET rc; /* Codigo de error */
rc = DosCreateQueue(phqRWHandle, ulQueueFlags, pszQueueName);
Parámetros | |||||||||
---|---|---|---|---|---|---|---|---|---|
phqRWHandle | Un puntero a una posición de memoria donde OS/2 devolverá el handle de lectura/escritura de la cola. Este handle puede ser usado inmediatamente por el dueño de la cola sin necesidad de llamar a DosOpenQueue. | ||||||||
ulQueueFlags | Un conjunto de flags que indican el procedimiento de ordenación/prioridad que se debe usar en la cola, así como si se convierten o no a direcciones de 32 bits los elementos introducidos por procesos de 16 bits. El significado de los bits es el siguiente: | ||||||||
| |||||||||
pszQueueName | Un puntero a una cadena ASCIIZ con el nombre de la cola. La cadena tiene que comenzar con \QUEUES\. Este mismo nombre es el que usarán el resto de procesos con DosOpenQueue. |
Codigos de error | |
---|---|
0 | Sin error |
87 | Parámetro no válido |
332 | Cola duplicada |
334 | No hay memoria suficiente |
335 | Nombre no válido |
<A NAME="DOSOPENQUEUE">
DosOpenQueue
</A>
DosOpenQueue da acceso a un proceso a una cola ya creada. Las colas creadas por procesos de 16 bits no son accesibles con peticiones DosOpenQueue de 32 bits.
#define INCL_BASE
#include <os2.h>
PPID ppidOwnerPID;
PHQUEUE phqQueueHandle;
PSZ pszQueueName;
APIRET rc; /* Codigo de error */
rc = DosOpenQueue(ppidOwnerPID, phqQueueHandle, pszQueueName);
Parámetros | |
---|---|
ppidOwnerPID | Un puntero a una posición de memoria donde OS/2 devolverá el PID del proceso dueño de la cola. |
phqQueueHandle | Un puntero a una posición de memoria donde OS/2 devolverá el handle de escritura de la cola. |
pszQueueName | Un puntero a una cadena ASCIIZ con el nombre de la cola a abrir. Esta cadena es definida por el dueño de la cola con DosCreateQueue y tiene que comenzar por \QUEUES\. |
Codigos de error | |
---|---|
0 | Sin error |
334 | No hay memoria suficiente |
341 | Acceso no permitido |
343 | No existe ese nombre |
<A NAME="DOSPEEKQUEUE">
DosPeekQueue
</A>
DosPeekQueue examina un elemento de la cola sin borrarlo de ella. Solo puede ser usado por el dueño de la cola y sus threads. Si se especifica la opción NoWait, es necesario un semáforo de evento. En este caso, cada vez que se añade un elemento a la cola, el semáforo es activado (posted).
#define INCL_BASE
#include <os2.h>
HQUEUE QueueHandle;
PREQUESTDATA pRequest;
PULONG pDataLength;
PPVOID pDataAddress;
PULONG pElementCode;
BOOL32 f32NoWait;
PBYTE pbElemPriority;
HEV SemHandle;
APIRET rc; /* Codigo de error */
rc = DosPeekQueue(QueueHandle, pRequest, pDataLength, pDataAddress, pElementCode, f32NoWait, pbElemPriority, SemHandle);
Parámetros | |||||||
---|---|---|---|---|---|---|---|
QueueHandle | El handle de la cola que se quiere examinar. | ||||||
pRequest | Un puntero a dos dobles palabras donde OS/2 devuelve la siguiente información: | ||||||
| |||||||
pDataLength | Un puntero a una posición de memoria donde OS/2 devolverá la longitud del elemento. Es el mismo valor de DataLength en DosWriteQueue. | ||||||
pDataAddress | Un puntero a una posición de memoria donde OS/2 devolverá un puntero al elemento a examinar. | ||||||
pElementCode | Un puntero a un indicador. Si al hacer la llamada contiene 0, OS/2 devolverá el primer elemento de la cola (según el orden en que fue creada -FIFO, LIFO o prioridad-). Si es distinto de 0, OS/2 devolverá el elemento cuyo número indique este campo. OS/2 devuelve aquí en ambos casos el número del siguiente elemento al leído. | ||||||
f32NoWait | Indica qué se debe hacer cuando no hay elementos en la cola:
| ||||||
pbElemPriority | Un puntero a una posición de memoria donde OS/2 devolverá el valor de prioridad dado al elemento en DosWriteQueue. Este valor se encuentra en el rango 0-15, siendo 15 la prioridad más alta. | ||||||
SemHandle | El handle de un semáforo de evento que es activado (posted) cuando algún elemento es introducido en la cola y NoWait es 1. Si NoWait es 0, el parámetro es ignorado. El semáforo puede ser privado o compartido, dependiendo de si la cola está compartida entre procesos. Nota: es necesario dar siempre el mismo handle de semáforo en cualquier llamada posterior a DosReadQueue o a DosPeekQueue a una misma cola. |
Codigos de error | |
---|---|
0 | Sin error |
87 | Parámetro no válido |
330 | El proceso no es el dueño de la cola |
333 | El elemento no existe |
337 | Handle de cola no válido |
340 | El elemento anterior es el último |
342 | Cola vacía |
433 | Valor de Wait no válido |
<A NAME="DOSPURGEQUEUE">
DosPurgeQueue
</A>
DosPurgeQueue elimina todos los elementos de una cola. Solo puede ser realizado por el dueño de la cola.
#define INCL_BASE
#include <os2.h>
HQUEUE QueueHandle;
APIRET rc; /* Codigo de error */
rc = DosPurgeQueue(QueueHandle);
Parámetros | |
---|---|
QueueHandle | Handle de la cola a borrar. |
Codigos de error | |
---|---|
0 | Sin error |
330 | El proceso no es el dueño de la cola |
337 | Handle de cola no válido |
<A NAME="DOSQUERYQUEUE">
DosQueryQueue
</A>
DosQueryQueue devuelve el número de elementos que contiene una cola. Puede ser ejecutado por el dueño de la cola y por cualquier cliente que haya ganado acceso con DosOpenQueue.
#define INCL_BASE
#include <os2.h>
HQUEUE QueueHandle;
PULONG pNumberElements;
APIRET rc; /* Codigo de error */
rc = DosQueryQueue(QueueHandle, pNumberElements);
Parámetros | |
---|---|
QueueHandle | Handle de una cola a consultar. |
pNumberElements | Un puntero a una posición de memoria donde OS/2 devolverá el número de elementos que contiene la cola. |
Codigos de error | |
---|---|
0 | Sin error |
337 | Handle de cola no válido |
<A NAME="DOSREADQUEUE">
DosReadQueue
</A>
DosReadQueue lee y elimina un elemento de la cola. Solo puede ser usado por el dueño de la cola. Si se especifica la opción NoWait, es necesario un semáforo de evento. En este caso, cada vez que se añade un elemento a la cola, el semáforo es activado (posted).
#define INCL_BASE
#include <os2.h>
HQUEUE QueueHandle;
PREQUESTDATA pRequest;
PULONG pDataLength;
PPVOID pDataAddress;
ULONG ulElementCode;
BOOL32 f32NoWait;
PBYTE pbElemPriority;
HEV SemHandle;
APIRET rc; /* Codigo de error */
rc = DosPeekQueue(QueueHandle, pRequest, pDataLength, pDataAddress, ulElementCode, f32NoWait, pbElemPriority, SemHandle);
Parámetros | |||||||
---|---|---|---|---|---|---|---|
QueueHandle | El handle de la cola que se quiere examinar. | ||||||
pRequest | Un puntero a dos dobles palabras donde OS/2 devuelve la siguiente información: | ||||||
| |||||||
pDataLength | Un puntero a una posición de memoria donde OS/2 devolverá la longitud del elemento. | ||||||
pDataAddress | Un puntero a una posición de memoria donde OS/2 devolverá un puntero al elemento que eliminamos de la cola. | ||||||
ulElementCode | Un indicador. Si vale 0, OS/2 leerá el primer elemento de la cola (según el orden en que fue creada -FIFO, LIFO o prioridad-). Si es distinto de 0 (n), OS/2 devolverá el n-ésimo elemento de la cola. | ||||||
f32NoWait | Indica qué se debe hacer cuando no hay elementos en la cola:
| ||||||
pbElemPriority | Un puntero a una posición de memoria donde OS/2 devolverá el valor de prioridad dado al elemento en DosWriteQueue. Este valor se encuentra en el rango 0-15, siendo 15 la prioridad más alta. | ||||||
SemHandle | El handle de un semáforo de evento que es activado (posted) cuando algún elemento es introducido en la cola y NoWait es 1. Si NoWait es 0, el parámetro es ignorado. El semáforo puede ser privado o compartido, dependiendo de si la cola está compartida entre procesos. Nota: es necesario dar siempre el mismo handle de semáforo en cualquier llamada posterior a DosReadQueue o a DosPeekQueue a una misma cola. |
Codigos de error | |
---|---|
0 | Sin error |
87 | Parámetro no válido |
330 | El proceso no es el dueño de la cola |
333 | El elemento no existe |
337 | Handle de cola no válido |
342 | Cola vacía |
433 | Valor de Wait no válido |
<A NAME="DOSWRITEQUEUE">
DosWriteQueue
</A>
DosWriteQueue añade un elemento a una cola.
#define INCL_BASE
#include <os2.h>
HQUEUE QueueHandle;
ULONG ulRequest;
ULONG ulDataLength;
PVOID pDataBuffer;
ULONG ulElemPriority;
APIRET rc; /* Codigo de error */
rc = DosWriteQueue(QueueHandle, ulRequest, ulDataLength, pDataBuffer, ulElemPriority);
Parámetros | |
---|---|
QueueHandle | Handle de la cola en la que se quiere añadir el elemento. |
ulRequest | Una doble palabra que contiene un código de evento especificado por la aplicación. El significado lo fijan el servidor y el cliente (no tiene un significado propio, y el sistema no lo modifica para nada). |
ulDataLength | La longitud, en bytes, del elemento a enviar. |
pDataBuffer | Un puntero al buffer que contiene el elemento a añadir a la cola. |
ulElemPriority | Prioridad del elemento. Solo es válido si la cola es de tipo prioritario. El valor tiene que estar entre 0 y 15, siendo 15 el de mayor prioridad. Si la prioridad es 0, el elemento se añadirá al final de la cola; si es 15, se añadirá al principio. Los elementos de igual prioridad se agrupan en orden FIFO (First In First Out, el primero en entrar es el primero en salir). Si se da un valor superior al máximo, el sistema le asigna prioridad 15; no devuelve error. |
Codigos de error | |
---|---|
0 | Sin error |
334 | No hay memoria suficiente |
337 | Handle de cola no válido |