GRUPO DE LLAMADAS DOSxxx (8)
(Colas)


DosCloseQueue

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

QueueHandleHandle de la cola a cerrar, dado por DosCreateQueue o por DosOpenQueue.

Codigos de error

0Sin error
337Handle de cola no válido


DosCreateQueue

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

phqRWHandleUn 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.
ulQueueFlagsUn 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:
Bit Definición
31-3 Reservado
2 Flag de conversión de direcciones.
0 (QUE_NOCONVERT_ADDRESS) Las direcciones de elementos depositados por procesos de 16 bits no se convierten.
1 (QUE_CONVERT_ADDRESS) Las direcciones de elementos depositados por procesos de 16 bits son convertidas a 32 bits.
1-0 Flags de prioridad-algoritmo.
0 (QUE_FIFO) Cola de tipo FIFO.
1 (QUE_LIFO) Cola de tipo LIFO.
2 (QUE_PRIORITY) Cola por prioridad. El proceso especifica un valor de prioridad entre 0 y 15, siendo 15 la mayor.
pszQueueNameUn 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

0Sin error
87Parámetro no válido
332Cola duplicada
334No hay memoria suficiente
335Nombre no válido


DosOpenQueue

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

ppidOwnerPIDUn puntero a una posición de memoria donde OS/2 devolverá el PID del proceso dueño de la cola.
phqQueueHandleUn puntero a una posición de memoria donde OS/2 devolverá el handle de escritura de la cola.
pszQueueNameUn 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

0Sin error
334No hay memoria suficiente
341Acceso no permitido
343No existe ese nombre


DosPeekQueue

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

QueueHandleEl handle de la cola que se quiere examinar.
pRequestUn puntero a dos dobles palabras donde OS/2 devuelve la siguiente información:
Doble palabra Contenido
1 El número de proceso (PID) que introdujo el elemento en la cola.
2 Un código de evento especificado por la aplicación. El contenido es el mismo que en el parámetro Request de DosWriteQueue. El significado lo fijan el servidor y el cliente (no tiene un significado propio, y el sistema no lo modifica para nada).
pDataLengthUn puntero a una posición de memoria donde OS/2 devolverá la longitud del elemento. Es el mismo valor de DataLength en DosWriteQueue.
pDataAddressUn puntero a una posición de memoria donde OS/2 devolverá un puntero al elemento a examinar.
pElementCodeUn 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.
f32NoWaitIndica qué se debe hacer cuando no hay elementos en la cola:
0 (DCWW_WAIT) El thread es dormido hasta que entra un elemento en la cola.
1 (DCWW_NOWAIT) La llamada retorna inmediatamente con el error La cola está vacía.
pbElemPriorityUn 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.
SemHandleEl 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

0Sin error
87Parámetro no válido
330El proceso no es el dueño de la cola
333El elemento no existe
337Handle de cola no válido
340El elemento anterior es el último
342Cola vacía
433Valor de Wait no válido


DosPurgeQueue

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

QueueHandleHandle de la cola a borrar.

Codigos de error

0Sin error
330El proceso no es el dueño de la cola
337Handle de cola no válido


DosQueryQueue

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

QueueHandleHandle de una cola a consultar.
pNumberElementsUn puntero a una posición de memoria donde OS/2 devolverá el número de elementos que contiene la cola.

Codigos de error

0Sin error
337Handle de cola no válido


DosReadQueue

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

QueueHandleEl handle de la cola que se quiere examinar.
pRequestUn puntero a dos dobles palabras donde OS/2 devuelve la siguiente información:
Doble palabra Contenido
1 El número de proceso (PID) que introdujo el elemento en la cola.
2 Un código de evento especificado por la aplicación. El contenido es el mismo que en el parámetro Request de DosWriteQueue. El significado lo fijan el servidor y el cliente (no tiene un significado propio, y el sistema no lo modifica para nada).
pDataLengthUn puntero a una posición de memoria donde OS/2 devolverá la longitud del elemento.
pDataAddressUn puntero a una posición de memoria donde OS/2 devolverá un puntero al elemento que eliminamos de la cola.
ulElementCodeUn 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.
f32NoWaitIndica qué se debe hacer cuando no hay elementos en la cola:
0 (DCWW_WAIT) El thread es dormido hasta que entra un elemento en la cola.
1 (DCWW_NOWAIT) La llamada retorna inmediatamente con el error La cola está vacía.
pbElemPriorityUn 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.
SemHandleEl 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

0Sin error
87Parámetro no válido
330El proceso no es el dueño de la cola
333El elemento no existe
337Handle de cola no válido
342Cola vacía
433Valor de Wait no válido


DosWriteQueue

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

QueueHandleHandle de la cola en la que se quiere añadir el elemento.
ulRequestUna 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).
ulDataLengthLa longitud, en bytes, del elemento a enviar.
pDataBufferUn puntero al buffer que contiene el elemento a añadir a la cola.
ulElemPriorityPrioridad 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

0Sin error
334No hay memoria suficiente
337Handle de cola no válido

 Indice