Ir al contenido

Manual de programación de OS/2/Llamadas DOSxxx para colas

Añadir enlaces
De Wikilibros, la colección de libros de texto de contenido libre.

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:
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.

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:
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).
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:


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.

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:
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).
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:


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.

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
Obtenido de «https://es.wikibooks.org/w/index.php?title=Manual_de_programación_de_OS/2/Llamadas_DOSxxx_para_colas&oldid=197480»