Interfaz de administración Guía de programación y consulta

Transcripción

1 MQSeries Interfaz de administración Guía de programación y consulta SC

2

3 MQSeries Interfaz de administración Guía de programación y consulta SC

4 Atención Antes de utilizar esta información y el producto al que da soporte, lea sin falta la información general que figura en el Apéndice E. Avisos en la página 133. Segunda edición (Marzo de 2000) Esta publicación es la traducción del original en inglés MQSeries Administration Interface Programming Guide and Reference, SC Esta edición se aplica a los siguientes productos: v MQSeries para AIX V5.1 v MQSeries para AS/400 V5.1 v MQSeries para HP-UX V5.1 v MQSeries para OS/2 Warp V5.1 v MQSeries para Sun Solaris V5.1 v MQSeries para Windows NT V5.1 Se aplica asimismo a todos los releases y modificaciones ulteriores hasta que se indique lo contrario en nuevas ediciones. Copyright International Business Machines Corporation 1999, Reservados todos los derechos.

5 Contenido Figuras vii Tablas ix Acerca de este manual xi Destinatarios del manual xi Conocimientos necesarios para comprender este manual xi Cómo utilizar este manual xi Presentación del texto en este manual..... xi Resumen de cambios xiii Cambios correspondientes a esta edición (SC ) xiii Capítulo 1. Introducción a la interfaz de administración de MQSeries (MQAI).. 1 Conceptos y terminología de la MQAI Utilización de la interfaz MQAI Cómo utilizar la MQAI? Visión general Construir la aplicación con MQAI Capítulo 2. Utilización de paquetes de datos Tipos de paquetes de datos Creación y supresión de paquetes de datos Supresión de paquetes de datos Tipos de elementos de datos Adición de elementos de datos a paquetes Adición de un mandato de consulta a un paquete 9 Cambiar la información de un paquete Cómo contar los elementos de datos Supresión de elementos de datos Supresión de elementos de datos de un paquete con la llamada mqdeleteitem Cómo vaciar un paquete utilizando la llamada mqclearbag Cómo truncar un paquete utilizando la llamada mqtruncatebag Consulta del contenido de los paquetes de datos.. 13 Elementos del sistema Capítulo 3. Configuración de MQSeries utilizando mqexecute Envío de mandatos de administración al servidor de mandatos Código de ejemplo Consejos y sugerencias para configurar MQSeries. 17 Capítulo 4. Intercambio de datos entre aplicaciones Convertir paquetes y almacenamientos intermedios 19 Cómo transferir y recibir paquetes de datos Enviar mensajes PCF a una cola especificada.. 20 Recibir mensajes PCF procedentes de una cola especificada Capítulo 5. Consulta de MQAI mqaddinquiry Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic Códigos de mandatos INQUIRE soportados.. 25 mqaddinteger Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqaddstring Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqbagtobuffer Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqbuffertobag Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqclearbag Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqcountitems Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqcreatebag Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic Copyright IBM Corp. 1999, 2000 iii

6 mqdeletebag Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqdeleteitem Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqexecute Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqgetbag Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqinquirebag Sintaxis Parámetros Invocación en lenguaje C Invocación en Visual Basic mqinquireinteger Sintaxis Parámetros Invocación en lenguaje C Invocación en Visual Basic mqinquireiteminfo Sintaxis Parámetros Invocación en lenguaje C Invocación en Visual Basic mqinquirestring Sintaxis Parámetros Invocación en lenguaje C Invocación en Visual Basic mqpad Sintaxis Parámetros Notas de utilización Invocación en lenguaje C mqputbag Sintaxis Parámetros Invocación en lenguaje C Invocación en Visual Basic mqsetinteger Sintaxis Parámetros Invocación en lenguaje C Invocación en Visual Basic mqsetstring Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic mqtrim Sintaxis Parámetros Notas de utilización Invocación en lenguaje C mqtruncatebag Sintaxis Parámetros Notas de utilización Invocación en lenguaje C Invocación en Visual Basic Capítulo 6. Ejemplos de cómo utilizar la MQAI Creación de una cola local (amqsaicq.c) Hacer consultas sobre colas e imprimir información (amqsailq.c) Visualizar sucesos utilizando un supervisor de sucesos (amqsaiem.c) Capítulo 7. Temas avanzados Indexado Conversión de datos Uso del descriptor de mensaje Apéndice A. Códigos de retorno Códigos de terminación Códigos de razón Apéndice B. Constantes en C Lista de constantes Tipos de datos elementales en C Apéndice C. Archivos de cabecera 129 Apéndice D. Selectores Selectores de usuario Selectores del sistema Apéndice E. Avisos Marcas registradas Glosario de términos y abreviaturas 137 Bibliografía Publicaciones de las distintas plataformas de MQSeries Publicaciones específicas de cada plataforma MQSeries Manuales en copia software Formato BookManager Formato HTML Portable Document Format (PDF) Formato PostScript iv MQSeries Interfaz de administración, Guía de programación y consulta

7 Formato de ayuda Windows Información de MQSeries disponible en Internet 155 Envío de comentarios a IBM Índice Contenido v

8 vi MQSeries Interfaz de administración, Guía de programación y consulta

9 Figuras 1. Jerarquía de conceptos de la MQAI Cómo administra la MQAI el producto MQSeries Añadir elementos de datos Modificar un elemento de datos Modificar todos los elementos de datos Suprimir un solo elemento de datos Suprimir todos los elementos de datos Cómo truncar un paquete Anidar Utilización de mqexecute para crear una cola local Utilización de mqexecute para consultar atributos de cola Convertir paquetes en mensajes PCF Convertir mensajes PCF en paquetes AMQSAICQ.C: crear una cola local AMQSAILQ.C: hacer consultas sobre colas e imprimir información AMQSAIEM.C: visualizar sucesos Indexado Copyright IBM Corp. 1999, 2000 vii

10 viii MQSeries Interfaz de administración, Guía de programación y consulta

11 Tablas 1. Proceso de CCSID Tipo de mandato PCF Parámetros Format y MsgType de la estructura MQMD Valores de descriptor de mensaje Archivos de cabecera Copyright IBM Corp. 1999, 2000 ix

12 x MQSeries Interfaz de administración, Guía de programación y consulta

13 Acerca de este manual Este manual describe la interfaz de administración de IBM MQSeries. Forma parte del producto denominado Interfaz de administración de MQSeries (MQAI). La MQAI es una interfaz de programación que simplifica el uso de mensajes PCF para configurar MQSeries. Se suministra formando parte de los siguientes productos: v MQSeries para AIX V5.1 v MQSeries para AS/400 V5.1 v MQSeries para HP-UX V5.1 v MQSeries para OS/2 Warp V5.1 v MQSeries para Sun Solaris V5.1 v MQSeries para Windows NT V5.1 Destinatarios del manual La información incluida en este manual va dirigida a los programadores de sistemas y de aplicaciones que deseen administrar MQSeries. Conocimientos necesarios para comprender este manual Cómo utilizar este manual Para comprender este manual, es preciso tener conocimientos básicos de MQSeries y saber escribir programas en el lenguaje de programación C o en Visual Basic para Windows NT. También es útil saber cómo se utilizan los PCF (formato de mandato programable). Hallará información adicional sobre los PCF en el manual MQSeries Programmable System Management. Los cuatro primeros capítulos presentan la interfaz de administración de colas de mensajes (MQAI) e indican cómo se utiliza. El Capítulo 5. Consulta de MQAI en la página 23 contiene información de consulta. El Capítulo 6. Ejemplos de cómo utilizar la MQAI en la página 85 proporciona algunos programas de ejemplo. El Capítulo 7. Temas avanzados en la página 105 describe el indexado, la conversión de datos y el descriptor de mensaje. En los apéndices figura una lista de los códigos de retorno, las constantes de MQAI, los archivos de cabecera y los selectores de usuario y del sistema. Después de los apéndices se incluye un glosario y bibliografía. Presentación del texto en este manual En este manual se utiliza el siguiente tipo de letra: CompCode Ejemplo del nombre de un parámetro de una llamada o del atributo de un objeto. Copyright IBM Corp. 1999, 2000 xi

14 Cómo utilizar este manual xii MQSeries Interfaz de administración, Guía de programación y consulta

15 Resumen de cambios Esta sección describe los cambios realizados en esta edición demqseries Interfaz de administración, Guía de programación y consulta. Los cambios realizados a partir de la edición anterior del manual se marcan mediante líneas verticales situadas a la izquierda de los cambios. Cambios correspondientes a esta edición (SC ) En esta edición no se ha realizado ningún cambio técnico. Lo único que ha cambiado es que MQSeries para AS/400 ha entrado a formar parte del grupo de productos de la versión 5.1 que dan soporte a la interfaz MQAI. Copyright IBM Corp. 1999, 2000 xiii

16 Cambios xiv MQSeries Interfaz de administración, Guía de programación y consulta

17 Capítulo 1. Introducción a la interfaz de administración de MQSeries (MQAI) Este capítulo describe: v Los conceptos y la terminología principales de la interfaz de administración de MQSeries (MQAI) v Cuándo puede utilizarse la MQAI v Cómo utilizar la MQAI Conceptos y terminología de la MQAI La MQAI es una interfaz de programación de MQSeries que utiliza el lenguaje C y también Visual Basic para Windows NT. Realiza tareas de administración en un gestor de colas de MQSeries utilizando paquetes de datos. Los paquetes de datos permiten manejar las propiedades (o parámetros) de los objetos de manera más fácil que utilizando la otra interfaz de administración, los PCF (formato de mandato programable). Con la MQAI resulta más fácil manipular los PCF que con las llamadas MQGET y MQPUT. Si desea más información sobre los paquetes de datos, consulte el Capítulo 2. Utilización de paquetes de datos en la página 7. Hallará información adicional sobre los PCF en el manual MQSeries Programmable System Management. El paquete de datos contiene cero o más elementos de datos. Estos se van ordenando dentro del paquete a medida que entran en él. Esto se denomina orden de inserción. Cada elemento de datos contiene un selector que identifica el elemento de datos y un valor del elemento de datos que puede ser un entero, una serie o un asa de otro paquete. Existen dos tipos de selectores: selectores de usuario y selectores del sistema. Estos selectores se describen en el Apéndice D. Selectores en la página 131. Los selectores suelen ser exclusivos, aunque es posible tener varios valores para un mismo selector. En tal caso, hay un índice que identifica la aparición concreta del selector necesario. Los índices se describen en la sección Indexado en la página 105. En la Figura 1 en la página 2 se muestra la jerarquía de los conceptos arriba mencionados. Copyright IBM Corp. 1999,

18 Utilización de la interfaz MQAI Paquete de datos Elemento de datos contiene cero o más contiene Selector de tipo Valor de datos de tipo Utilización de la interfaz MQAI Usuario Sistema Entero Serie Asa de paquete Figura 1. Jerarquía de conceptos de la MQAI Puede utilizar la MQAI para: v Implementar aplicaciones de autoadministración y herramientas de administración. Por ejemplo, el servicio de directorios activo (ADS) proporcionado en Windows NT Versión 5 utiliza la interfaz MQAI. Puede encontrar más información sobre la interfaz de servicio de directorios activo (ADSI) en el manual MQSeries para Windows NT Utilización de la interfaz de modelo de objetos componentes. v Simplificar el uso de mensajes PCF. Con la MQAI, resulta fácil administrar MQSeries; no es necesario que escriba sus propios mensajes PCF, evitando así los problemas asociados a las estructuras de datos complejas. v Manejar las condiciones de error con mayor facilidad. Es difícil obtener códigos de retorno de los mandatos MQSeries (MQSC); sin embargo, con la MQAI, al programa le resultará más fácil manejar las condiciones de error. 2 MQSeries Interfaz de administración, Guía de programación y consulta

19 Utilización de la MQAI Cómo utilizar la MQAI? Programa de aplicación utiliza MQAI genera mensaje PCF system.admin.command.queue mensajes de respuesta cola de respuestas devuelve Servidor de mandatos configura Gestor de colas Figura 2. Cómo administra la MQAI el producto MQSeries Capítulo 1. Introducción a la interfaz de administración de MQSeries (MQAI) 3

20 Utilización de la MQAI La MQAI proporciona un acceso de programación más fácil a los mensajes PCF. Para pasar parámetros en los programas que se han escrito utilizando llamadas MQI, el mensaje PCF debe contener el mandato y los detalles de los datos de tipo serie o de tipo entero. Para ello, es necesario escribir varias sentencias en el programa para cada estructura y debe asignarse espacio de memoria. En cambio, los programas escritos con la MQAI pasan parámetros al paquete de datos y solo es necesaria una sentencia para cada estructura. Gracias al paquete de datos, el programador ya no necesita manejar matrices ni asignar almacenamiento, y además se logra cierto grado de aislamiento de los detalles de PCF. La MQAI, para administrar MQSeries, envía mensajes PCF al servidor de mandatos y espera una respuesta, tal como se muestra en la Figura 2 en la página 3. Visión general Las siguientes instrucciones dan una breve visión general de 1) qué se puede hacer con la MQAI y 2) cómo se utiliza la MQAI. Encontrará más información en el resto del manual. Si desea utilizar la MQAI para administrar MQSeries: 1. Decida la tarea que desea llevar a cabo; por ejemplo, cambiar cola (Change Queue). 2. La publicación MQSeries Programmable System Management le servirá de manual de consulta para los mandatos y las respuestas que se intercambian un programa de aplicación de gestión de sistemas de MQSeries y un gestor de colas de MQSeries. Por ejemplo, consulte el mandato Change Queue (cambiar cola) en el manual MQSeries Programmable System Management. 3. Elija los valores de los selectores para los parámetros obligatorios y los parámetros opcionales que desee establecer. 4. Cree un paquete de datos utilizando la llamada mqcreatebag y entre los valores para cada uno de estos selectores utilizando las llamadas mqaddinteger, mqaddstring y mqaddinquiry. Esto se describe en el Capítulo 2. Utilización de paquetes de datos en la página Asegúrese de que el servidor de mandatos está funcionando. 6. Mediante la llamada mqexecute, envíe el mensaje al servidor de mandatos y espere una respuesta. Esto se describe en el Capítulo 3. Configuración de MQSeries utilizando mqexecute en la página 15. Si desea utilizar la MQAI para intercambiar datos entre aplicaciones: v El emisor debe: 1. Crear un paquete de datos destinado a enviar los datos utilizando mqcreatebag. Consulte la sección Creación y supresión de paquetes de datos en la página Mediante mqaddinteger o mqaddstring, añadir al paquete los datos que van a enviarse. Consulte la sección Adición de elementos de datos a paquetes en la página Utilizar la llamada mqputbag para convertir los datos del paquete en un mensaje PCF y poner el mensaje en la cola pertinente. Consulte la sección Cómo transferir y recibir paquetes de datos en la página 20. v El receptor debe: 4 MQSeries Interfaz de administración, Guía de programación y consulta

21 1. Crear un paquete de datos destinado a recibir los datos utilizando mqcreatebag. Consulte la sección Creación y supresión de paquetes de datos en la página Utilizar la llamada mqgetbag para obtener el mensaje PCF de la cola y volver a crear un paquete a partir del mensaje PCF. Consulte la sección Cómo transferir y recibir paquetes de datos en la página 20. En los capítulos siguientes encontrará una descripción más detallada de cómo se utiliza la MQAI. Construir la aplicación con MQAI Utilización de la MQAI Para construir la aplicación utilizando la MQAI, debe enlazarse con las mismas bibliotecas que para MQSeries. Encontrará más información sobre cómo puede construir las aplicaciones MQSeries en el manual MQSeries Application Programming Guide. Capítulo 1. Introducción a la interfaz de administración de MQSeries (MQAI) 5

22 Cambios 6 MQSeries Interfaz de administración, Guía de programación y consulta

23 Capítulo 2. Utilización de paquetes de datos Tipos de paquetes de datos Un paquete de datos es un medio que permite manejar las propiedades (o parámetros) de los objetos utilizando la MQAI. Este capítulo trata sobre la configuración de los paquetes de datos. En él se describen: v Los distintos tipos de paquetes y sus usos v Cómo crear y suprimir paquetes de datos v Tipos de elementos de datos v Cómo añadir elementos de datos a paquetes de datos v Cómo cambiar la información que hay en un paquete de datos v Cómo contar los elementos de datos que hay en un paquete de datos v Cómo suprimir elementos de datos v Cómo consultar el contenido de los paquetes de datos v Los elementos del sistema Puede elegir el tipo de paquete de datos que desea crear en función de la tarea que piensa realizar: paquete de usuario Paquete simple utilizado para datos de usuario. paquete de administración Paquete creado para datos que se utilizan para administrar los objetos de MQSeries, enviando mensajes de administración a un servidor de mandatos. El paquete de administración implica utilizar automáticamente determinadas opciones, tal como se describe en la sección Creación y supresión de paquetes de datos. paquete de mandatos Paquete creado para mandatos también con el fin de administrar los objetos de MQSeries. Sin embargo, a diferencia del paquete de administración, el paquete de mandatos no implica que se utilicen automáticamente determinadas opciones aunque estas estén disponibles. Estas opciones de describen en la sección Creación y supresión de paquetes de datos. Además, la MQAI crea el paquete del sistema cuando se devuelve un mensaje de respuesta del servidor de mandatos y se coloca en un paquete de salida de un usuario. El usuario no puede modificar un paquete del sistema. Creación y supresión de paquetes de datos Para utilizar la MQAI, primero debe crear un paquete de datos utilizando la llamada mqcreatebag. Como entrada para esta llamada, se suministran una o varias opciones para controlar la creación del paquete. El parámetro Options de la llamada MQCreateBag le permite elegir si va a crear un paquete de usuario, un paquete de mandatos o un paquete de administración. Si desea crear un paquete de usuario o un paquete de mandatos, puede elegir una o varias opciones adicionales con el fin de: Copyright IBM Corp. 1999,

24 Paquetes de datos v v v Utilizar el formato de lista donde haya dos o más apariciones contiguas del mismo selector en un paquete. Reordenar los elementos de datos a medida que se van añadiendo a un mensaje PCF para asegurar que los parámetros están en el orden correcto. Comprobar los valores de los selectores de usuario correspondientes a los elementos que añada al paquete. Los paquetes de administración implican automáticamente estas opciones. Un paquete de datos se identifica mediante su asa. El asa del paquete la devuelve mqcreatebag y se debe proporcionar en todas las demás llamadas que utilizan el paquete de datos. Si desea ver una descripción completa de la llamada mqcreatebag, consulte la sección mqcreatebag en la página 39. Supresión de paquetes de datos Todos los paquetes de datos creados por el usuario también deben suprimirse con la llamada mqdeletebag. Por ejemplo, si se crea un paquete en el código de usuario, también debe suprimirse en el código de usuario. Tipos de elementos de datos La interfaz MQAI crea y suprime automáticamente los paquetes del sistema. Para más información, consulte la sección Envío de mandatos de administración al servidor de mandatos en la página 15. El código de usuario no puede suprimir un paquete del sistema. Si desea ver una descripción completa de la llamada mqdeletebag, consulte la sección mqdeletebag en la página 43. A continuación figuran los tipos de elementos de datos que están disponibles en la MQAI: v Entero v Serie de caracteres v Asa de paquete Después de crear un paquete de datos, puede llenarlo con elementos de tipo entero o de tipo serie de caracteres. Puede efectuar consultas sobre los tres tipos de elementos. Nota: No puede insertar asas de paquetes. Estos elementos de datos pueden ser elementos de usuario o del sistema. Los elementos de usuario contienen datos de usuario como, por ejemplo, atributos de objetos que se están administrando. Los elementos del sistema se deben utilizar para controlar mejor los mensajes generados; por ejemplo, para controlar la generación de cabeceras de mensajes. Para más información sobre elementos del sistema, consulte la sección Elementos del sistema en la página MQSeries Interfaz de administración, Guía de programación y consulta

25 Añadir elementos de datos Adición de elementos de datos a paquetes La interfaz MQAI permite añadir a los paquetes elementos de tipo entero y elementos de tipo serie de caracteres, tal como se muestra en la Figura 3. Los elementos se identifican mediante un selector. Normalmente un selector identifica únicamente un elemento, aunque no siempre es así. Si en el paquete ya existe un elemento de datos con el selector especificado, se añade una instancia adicional de dicho selector al final del paquete. añadir elemento de datos 0 elemento de datos elemento de datos 4 elemento de datos 5 paquete de datos Figura 3. Añadir elementos de datos Para añadir elementos de datos a un paquete, utilice las llamadas mqadd*. Para añadir elementos de tipo entero, utilice la llamada mqaddinteger, como se describe en la sección mqaddinteger en la página 26. Para añadir elementos de tipo serie de caracteres, utilice la llamada mqaddstring, como se describe en la sección mqaddstring en la página 28. Adición de un mandato de consulta a un paquete La llamada mqaddinquiry permite añadir un mandato de consulta a un paquete. La llamada se utiliza específicamente a efectos administrativos, por lo que solo se puede emplear con los paquetes de administración. Le permite especificar los selectores de los atributos que desea consultar desde MQSeries. Si desea ver una descripción completa de la llamada mqaddinquiry, consulte la sección mqaddinquiry en la página 24. Filtrar y consultar elementos de datos Cuando utilice la MQAI para hacer consultas sobre los atributos de los objetos de MQSeries, puede controlar de dos maneras los datos que se devuelven al programa. 1. Puede filtrar los datos que se devuelven utilizando las llamadas mqaddinteger y mqaddstring. Este enfoque le permite especificar una pareja formada por un Selector yunitemvalue; por ejemplo: mqaddinteger(inputbag, MQIA_Q_TYPE, MQQT_LOCAL) Este ejemplo especifica que el tipo de cola (Selector) debe ser local (ItemValue) y esta especificación debe coincidir con el atributo del objeto (en este caso sería una cola) al que se refiere la consulta. Otros atributos que pueden filtrarse corresponden a los mandatos PCF Inquire* que pueden encontrarse en el manual MQSeries Gestión de sistemas programables. Por ejemplo, para hacer consultas sobre los atributos de un canal, vea la publicación MQSeries Programmable System Management. Los parámetros obligatorios y los parámetros opcionales del mandato Inquire Channel (consultar canal) identifican los selectores que pueden usarse para filtrar. Capítulo 2. Utilización de paquetes de datos 9

26 Añadir elementos de datos 2. Puede consultar atributos concretos de un objeto utilizando la llamada mqaddinquiry. Esta llamada especifica el selector que le interesa. Si no especifica el selector, se devuelven todos los atributos del objeto. A continuación hay un ejemplo de cómo puede filtrar y consultar los atributos de una cola: /* Solicitar información sobre todas las colas */ mqaddstring(adminbag, MQCA_Q_NAME, * ) /* Filtrar atributos para que solo se devuelvan las colas locales */ mqaddinteger(adminbag, MQIA_Q_TYPE, MQQT_LOCAL) /* Consultar los nombres y las profundidades actuales de las colas locales */ mqaddinquiry(adminbag, MQCA_Q_NAME) mqaddinquiry(adminbag, MQIA_CURRENT_Q_DEPTH) /* Enviar una consulta al servidor de mandatos y esperar a que responda */ mqexecute(mqcmd_inquire_q,...) Si desea ver más ejemplos de cómo puede filtrar y consultar elementos de datos, vea el Capítulo 6. Ejemplos de cómo utilizar la MQAI en la página 85. Cambiar la información de un paquete La interfaz MQAI permite cambiar la información incluida en un paquete mediante las llamadas mqset*. Puede: 1. Modificar los elementos de datos incluidos en un paquete. El índice permite sustituir la instancia individual de un parámetro identificando la aparición del elemento que debe modificarse (vea la Figura 4). ÍNDICE elemento de datos 0 elemento de datos elemento de datos 4 paquete de datos Figura 4. Modificar un elemento de datos 2. Suprimir todas las apariciones existentes del selector especificado y añadir una nueva aparición al final del paquete. (Vea la Figura 5). Hay un valor de índice especial que permite sustituir todas las instancias de un parámetro. 10 MQSeries Interfaz de administración, Guía de programación y consulta

27 Cambiar la información de un paquete ÍNDICE añadir elemento de datos 0 elemento de datos elemento de datos 4 elemento de datos 5 paquete de datos Figura 5. Modificar todos los elementos de datos Nota: El índice conserva el orden de inserción que existe dentro del paquete, pero puede afectar a los índices de otros elementos de datos. La llamada mqsetinteger permite modificar elementos de tipo entero incluidos en un paquete y la llamada mqsetstring permite modificar elementos de tipo serie de caracteres. Si lo desea, puede utilizar estas llamadas para suprimir todas las apariciones existentes del selector especificado y añadir una nueva aparición al final del paquete. El elemento de datos puede ser un elemento de usuario o un elemento del sistema. Si desea ver una descripción completa de estas llamadas, consulte las secciones mqsetinteger en la página 73 y mqsetstring en la página 76. Cómo contar los elementos de datos La llamada mqcountitems cuenta los elementos de usuario, los elementos del sistema, o ambos, almacenados en un paquete de datos y devuelve el total. Por ejemplo, mqcountitems(bag, 7,...), devuelve el número de elementos del paquete que tienen el selector 7. Puede contar los elementos correspondientes a un selector concreto, a selectores del usuario, a selectores del sistema, o a todos los selectores. Nota: Esta llamada cuenta el número de elementos de datos, no el número de selectores exclusivos del paquete. Un selector puede aparecer varias veces, por lo tanto, es posible que haya menos selectores que elementos de datos en el paquete. Si desea ver una descripción completa de la llamada mqcountitems, consulte la sección mqcountitems en la página 37. Supresión de elementos de datos Los elementos se pueden suprimir de los paquetes de distintas formas. Puede: v Eliminar de un paquete uno o más elementos de usuario. v Suprimir de un paquete todos los elementos de usuario, es decir vaciar un paquete. v Suprimir elementos de usuario del final de un paquete, es decir, truncar un paquete. Supresión de elementos de datos de un paquete con la llamada mqdeleteitem La llamada mqdeleteitem elimina uno o más elementos de usuario de un paquete. El índice permite suprimir ya sea: Capítulo 2. Utilización de paquetes de datos 11

28 Supresión de elementos de datos 1. Una sola aparición del selector especificado. (Vea la Figura 6). ÍNDICE elemento de datos 0 elemento de datos elemento de datos 4 paquete de datos Figura 6. Suprimir un solo elemento de datos o bien 2. Todas las apariciones del selector especificado. (Vea la Figura 7). ÍNDICE elemento de datos 0 selector A elemento de datos 1 selector B elemento de datos elemento de datos 4 selector B selector C paquete de datos Figura 7. Suprimir todos los elementos de datos Nota: El índice conserva el orden de inserción que existe dentro del paquete, pero puede afectar a los índices de otros elementos de datos. Por ejemplo, la llamada mqdeleteitem no conserva los valores del índice de los elementos de datos que van a continuación del elemento suprimido porque los índices se reorganizan para rellenar el hueco que queda una vez suprimido el elemento. Si desea ver una descripción completa de la llamada mqdeleteitem, consulte la sección mqdeleteitem en la página 45. Cómo vaciar un paquete utilizando la llamada mqclearbag La llamada mqclearbag elimina todos los elementos de usuario de un paquete de usuario y restablece los elementos del sistema a sus valores iniciales. También se eliminan los paquetes del sistema incluidos en el paquete. Si desea ver una descripción completa de la llamada mqclearbag, consulte la sección mqclearbag en la página 36. Cómo truncar un paquete utilizando la llamada mqtruncatebag La llamada mqtruncatebag reduce el número de elementos de usuario de un paquete de usuario eliminando los elementos del final del paquete, empezando por el último elemento añadido. Por ejemplo, puede utilizarse al emplear la misma información de cabecera para generar más de un mensaje. 12 MQSeries Interfaz de administración, Guía de programación y consulta

29 Supresión de elementos de datos TRUNCAMIENTO elemento de datos 0 elemento de datos elemento de datos 4 Si desea ver una descripción completa de la llamada mqtruncatebag, consulte la sección mqtruncatebag en la página 82. Consulta del contenido de los paquetes de datos Elementos del sistema paquete de datos Figura 8. Cómo truncar un paquete Puede hacer consultas sobre: v El valor de un elemento de tipo entero utilizando la llamada mqinquireinteger. Vea la sección mqinquireinteger en la página 59. v El valor de un elemento de tipo serie utilizando la llamada mqinquirestring. Vea la sección mqinquirestring en la página 65. v El valor de un asa de paquete utilizando la llamada mqinquirebag. Vea la sección mqinquirebag en la página 56. También puede efectuar consultas sobre el tipo (entero, serie de caracteres o asa de paquete) de un elemento específico utilizando la llamada mqinquireiteminfo. Vea la sección mqinquireiteminfo en la página 62. Los elementos del sistema se pueden utilizar para: v Generar cabeceras PCF. Los elementos del sistema pueden controlar el identificador de mandatos PCF, las opciones de control, el número de secuencia del mensaje y el tipo de mandato. v Convertir datos. Los elementos del sistema manejan el identificador de juego de caracteres correspondiente a los elementos de tipo serie que hay en el paquete. Al igual que todos los elementos de datos, los elementos del sistema se componen de un selector y un valor. Si desea más información sobre estos selectores y su función, consulte el Apéndice D. Selectores en la página 131. Los elementos del sistema son exclusivos. Un selector del sistema puede identificar uno o más elementos del sistema. Solo hay una aparición de cada selector del sistema. La mayoría de los elementos del sistema se pueden modificar (consulte la sección Cambiar la información de un paquete en la página 10), pero el usuario no puede cambiar las opciones de creación del paquete. Los elementos del sistema no se pueden suprimir. (Vea Supresión de elementos de datos en la página 11). Capítulo 2. Utilización de paquetes de datos 13

30 Cambios 14 MQSeries Interfaz de administración, Guía de programación y consulta

31 Capítulo 3. Configuración de MQSeries utilizando mqexecute Una vez que ha creado y llenado con datos el paquete de datos, puede enviar un mensaje de mandato de administración al servidor de mandatos de un gestor de colas y esperar los mensajes de respuesta. La manera más fácil de hacerlo es con la llamada mqexecute. Esta llamada maneja el intercambio con el servidor de mandatos y devuelve las respuestas en un paquete. Envío de mandatos de administración al servidor de mandatos La llamada mqexecute envía un mensaje de mandato de administración en forma de mensaje no permanente y espera las respuestas. Estas se devuelven en un paquete de respuesta. Las respuestas pueden incluir, por ejemplo, información sobre atributos relacionados con varios objetos MQSeries o una serie de mensajes de respuesta de error PCF. Por lo tanto, el paquete de respuesta podría contener un código de retorno o bien paquetes anidados. Los mensajes de respuesta se colocan en paquetes del sistema creados por el sistema. Por ejemplo, para efectuar consultas sobre nombres de objetos, se crea un paquete del sistema para guardar estos nombres de objetos y el paquete se inserta en el paquete de usuario. A continuación, las asas de estos paquetes se insertarán en el paquete de respuesta y el selector MQHA_BAG_HANDLE puede acceder al paquete anidado. El paquete del sistema permanece guardado, si no se suprime, hasta que se suprime el paquete de respuesta. El concepto de anidar se muestra en la Figura 9. ANIDADO mensaje de respuesta asa de paquete paquete del sistema paquete de usuario/respuesta paquete del sistema Figura 9. Anidar Como entrada de la llamada mqexecute, debe proporcionar: v Un asa de conexión MQI. v El mandato que debe ejecutarse. Debe ser uno de los valores de tipo MQCMD_*. Nota: El valor se acepta aunque la MQAI no lo reconozca. Sin embargo, si se ha utilizado la llamada mqaddinquiry para insertar valores en el paquete, este parámetro debe ser un mandato INQUIRE reconocido por la MQAI. Es decir, el parámetro debe tener el formato MQCMD_INQUIRE_*. Copyright IBM Corp. 1999,

32 Enviar mandatos de administración v v v Opcionalmente, un asa del paquete que contiene opciones que controlan el proceso de la llamada. También es donde puede especificar el máximo intervalo de tiempo, en milisegundos, que la MQAI debe esperar a cada mensaje de respuesta. Un asa del paquete de administración que contiene detalles del mandato de administración que va a emitirse. Un asa del paquete de respuesta que recibe los mensajes de respuesta. Los siguientes elementos son opcionales: v Un asa de objeto de la cola donde se debe colocar el mandato de administración. Si no se especifica ningún asa de objeto, el mandato de administración se coloca en la cola SYSTEM.ADMIN.COMMAND.QUEUE que pertenece al gestor de colas conectado actualmente. Es el valor por omisión. v Un asa de objeto de la cola en la que se deben colocar los mensajes de respuesta. Si lo desea, puede elegir colocar los mensajes de respuesta en una cola dinámica creada automáticamente por la MQAI. La cola creada solo existirá mientras dure la llamada, y la interfaz MQAI la suprimirá al salir de la llamada mqexecute. Código de ejemplo A continuación se muestran algunos ejemplos de cómo se usa la llamada mqexecute. El ejemplo que se muestra en la figura 10 crea una cola local (con una longitud máxima de mensajes igual a 100 bytes) en un gestor de colas: /* Crear un paquete para los datos que se han de incluir en el mensaje PCF */ mqcreatebag(mqcbo_admin_bag, &hbagrequest) /* Crear un paquete que se ha de rellenar con la */ /* respuesta del servidor de mandatos */ mqcreatebag(mqcbo_admin_bag, &hbagresponse) /* Crear una cola */ /* Suministrar el nombre de cola */ mqaddstring(hbagrequest, MQCA_Q_NAME, "QBERT") /* Suministrar el tipo de cola */ mqaddstring(hbagrequest, MQIA_Q_TYPE, MQQT_LOCAL) /* La longitud máxima de mensajes es un parámetro opcional */ mqaddstring(hbagrequest, MQIA_MAX_MSG_LENGTH, 100) /* Solicitar al servidor de mandatos que cree la cola */ mqexecute(mqcmd_create_q, hbagrequest, hbagresponse) /* Eliminar la memoria asignada */ mqdeletebag(hbagrequest) mqdeletebag(hbagresponse) Figura 10. Utilización de mqexecute para crear una cola local El ejemplo que se muestra en la figura 11 consulta todos los atributos de una cola concreta. La llamada mqaddinquiry identifica todos los atributos de objeto MQSeries de una cola que ha de devolver el parámetro Inquire en mqexecute. 16 MQSeries Interfaz de administración, Guía de programación y consulta

33 /* Crear un paquete para los datos que se han de incluir en el mensaje PCF */ mqcreatebag(mqcbo_admin_bag, &hbagrequest) /* Crear un paquete que se ha de rellenar con la */ /* respuesta del servidor de mandatos */ mqcreatebag(mqcbo_admin_bag, &hbagresponse) /* Consultar una cola suministrando el nombre de la cola */ /* (los demás parámetros son opcionales) */ mqaddstring(hbagrequest, MQCA_Q_NAME, "QBERT") /* Solicitar al servidor de mandatos que consulte la cola */ mqexecute(mqcmd_inquire_q, hbagrequest, hbagresponse) /* Si ha funcionado, se devuelven los atributos de la cola */ /* en un paquete del sistema dentro del paquete de respuesta */ mqinquirebag(hbagresponse, MQHA_BAG_HANDLE, 0, &hbagattributes) /* Consultar el nombre de la cola y su profundidad actual */ mqinquirestring(hbagattributes, MQCA_Q_NAME, &stringattribute) mqinquirestring(hbagattributes, MQIA_CURRENT_Q_DEPTH, &integerattribute) /* Eliminar la memoria asignada */ mqdeletebag(hbagrequest) mqdeletebag(hbagresponse) Enviar mandatos de administración Figura 11. Utilización de mqexecute para consultar atributos de cola La forma más sencilla de administrar MQSeries es utilizando mqexecute, pero también pueden utilizarse las llamadas mqbagtobuffer y mqbuffertobag, que son de nivel más bajo. Si desea más información sobre cómo se usan estas llamadas, consulte el Capítulo 4. Intercambio de datos entre aplicaciones en la página 19. Si desea ver programas de ejemplo, consulte el Capítulo 6. Ejemplos de cómo utilizar la MQAI en la página 85. Consejos y sugerencias para configurar MQSeries La interfaz MQAI utiliza mensajes PCF para enviar mandatos de administración al servidor de mandatos, en vez de tratar directamente con el servidor de mandatos. A continuación se proporcionan algunos consejos para configurar MQSeries utilizando la MQAI: v v v v Las series de caracteres en MQSeries se rellenan con blancos hasta llegar a una longitud fija. Al utilizar C, las series terminadas en nulo pueden suministrarse normalmente como parámetros de entrada en las interfaces de programación de MQSeries. Para borrar el valor de un atributo de tipo serie, déle el valor de un blanco en vez de dejar la serie vacía. Conviene que sepa con antelación los atributos que desea cambiar y que solo efectúe consultas sobre esos atributos. Ello se debe a que el número de atributos que el mandato Inquire Queue (Response) puede devolver (vea el manual MQSeries Programmable System Management) es mayor que el número de atributos que se pueden cambiar mediante el mandato Change Queue. (Vea el manual MQSeries Programmable System Management). Por lo tanto, no conviene que intente modificar todos los atributos que consulta. Si una llamada MQAI no se ejecuta correctamente, algunos de los detalles de la anomalía se devuelven en el paquete de respuesta. También se puede encontrar más información en un paquete anidado al que el selector MQHA_BAG_HANDLE pueda acceder. Por ejemplo, si una llamada mqexecute Capítulo 3. Configuración de MQSeries utilizando mqexecute 17

34 Consejos y sugerencias de programación no se ejecuta correctamente con un código de razón MQRCCF_COMMAND_FAILED, esta información se devuelve en el paquete de respuesta. Sin embargo, una causa posible de este código de razón es que un selector especificado no sea válido para el tipo de mensaje de mandato y esta información se encuentra en un paquete anidado al que puede accederse por medio de un asa de paquete. Puede verlo en el siguiente diagrama: Paquete del sistema que corresponde al primer mensaje de respuesta devuelto desde el servidor de mandatos MQIASY_COMP_CODE MQIASY_REASON MQCC_FAILED MQRCCF_COMMAND_FAILED MQIACF_PARAMETER_ID <selector no válido> MQIASY_MSG_SEQ_NUMBER 1 Paquete de respuesta MQIASY_COMP_CODE MQIASY_REASON MQHA_BAG_HANDLE MQHA_BAG_HANDLE MQCC_FAILDED MQRCCF_COMMAND_FAILED paquete anidado paquete anidado MQIASY_COMP_CODE MQIASY_REASON MQCC_FAILED MQRCCF_COMMAND_FAILED MQIASY_CONTROL MQCFC_LAST MQIASY_MSG_SEQ_NIMBER 2 Paquete del sistema que corresponde al mensaje final (de resumen) devuelto desde el servidor de mandatos 18 MQSeries Interfaz de administración, Guía de programación y consulta

35 Capítulo 4. Intercambio de datos entre aplicaciones La interfaz MQAI también puede utilizarse para intercambiar datos entre aplicaciones. Los datos de aplicación se envían en formato PCF, y la interfaz MQAI los empaqueta y desempaqueta. Si los datos del mensaje constan de enteros y series de caracteres, puede utilizar la MQAI para sacar partido a la conversión de datos incorporada de MQSeries para los datos PCF. Gracias a esto no es necesario escribir rutinas de salida de conversión de datos. Para intercambiar datos, el emisor debe, en primer lugar, crear el mensaje y enviarlo a la aplicación receptora. A continuación, el receptor debe leer el mensaje y extraer los datos. Esto puede llevarse a cabo de dos maneras: 1. Convirtiendo paquetes y almacenamientos intermedios, es decir, utilizando las llamadas mqbagtobuffer y mqbuffertobag. 2. Transfiriendo y obteniendo paquetes, es decir, utilizando las llamadas mqputbag y mqgetbag para enviar y recibir mensajes PCF. Estas dos opciones se describen en este capítulo. Nota: No puede convertir en un mensaje un paquete que contenga paquetes anidados. Convertir paquetes y almacenamientos intermedios Para enviar datos entre aplicaciones, en primer lugar los datos del mensaje se colocan en un paquete. A continuación, los datos del paquete se convierten en un mensaje PCF utilizando la llamada mqbagtobuffer. El mensaje PCF se envía a la cola requerida utilizando la llamada MQPUT. Esto se muestra en la Figura 12. Si desea ver una descripción completa de la llamada mqbagtobuffer, consulte la sección mqbagtobuffer en la página 31. datos de mensaje mqbagtobuffer mensaje PCF MQPUT mensaje PCF paquete almacenamiento intermedio cola Figura 12. Convertir paquetes en mensajes PCF Para recibir datos, el mensaje se recibe en un almacenamiento intermedio utilizando la llamada MQGET. Después los datos del almacenamiento intermedio se convierten en un paquete utilizando la llamada mqbuffertobag, siempre que el almacenamiento intermedio contenga un mensaje PCF válido. Esto se muestra en la Figura 13. Si desea ver una descripción completa de la llamada mqbuffertobag, consulte la sección mqbuffertobag en la página 34. Copyright IBM Corp. 1999,

36 Transferir y obtener paquetes de datos mensaje PCF MQGET mensaje PCF mqbuffertobag datos de mensaje cola almacenamiento intermedio paquete Figura 13. Convertir mensajes PCF en paquetes Cómo transferir y recibir paquetes de datos Los datos también pueden enviarse entre distintas aplicaciones transfiriendo y obteniendo paquetes de datos con las llamadas mqputbag y mqgetbag. Esto permite que sea la interfaz MQAI la que maneje el almacenamiento intermedio, en lugar de hacerlo la aplicación. La llamada mqputbag convierte en un mensaje PCF el contenido del paquete especificado y envía el mensaje a la cola indicada; luego, la llamada mqgetbag elimina el mensaje de la cola y lo vuelve a convertir en un paquete de datos. Por lo tanto, la llamada mqputbag es equivalente a la llamada mqbagtobuffer seguida de MQPUT, y la llamada mqgetbag es equivalente a la llamada MQGET seguida de mqbuffertobag. Nota: Si utiliza la llamada mqgetbag, los detalles de PCF que hay en el mensaje deben ser correctos; si no lo son, se produce el correspondiente error y no se devuelve el mensaje PCF. Enviar mensajes PCF a una cola especificada Para enviar un mensaje a una cola especificada, la llamada mqputbag convierte el contenido del paquete especificado en un mensaje PCF y envía el mensaje a la cola indicada. El contenido del paquete no varía después de la llamada. Como entrada de esta llamada, debe proporcionar: v Un asa de conexión MQI. v Un asa de objeto de la cola en la que se va a colocar el mensaje. v Un descriptor de mensaje. Encontrará más información sobre el descriptor de mensaje en el manual MQSeries Application Programming Reference. v Opciones de transferir mensaje (PMO) utilizando la estructura MQPMO. Puede hallar más información sobre la estructura MQPMO en el manual MQSeries Application Programming Reference. v El asa del paquete que se va a convertir en un mensaje. Nota: Si el paquete contiene un mensaje de administración y se ha utilizado la llamada mqaddinquiry para insertar valores en el paquete, el valor del elemento de datos MQIASY_COMMAND debe ser un mandato INQUIRE reconocido por la MQAI. Si desea ver una descripción completa de la llamada mqputbag, consulte la sección mqputbag en la página 71. Recibir mensajes PCF procedentes de una cola especificada Para recibir un mensaje de una cola especificada, la llamada mqgetbag obtiene un mensaje PCF de la cola y convierte los datos del mensaje en un paquete de datos. Como entrada de esta llamada, debe proporcionar: v Un asa de conexión MQI. 20 MQSeries Interfaz de administración, Guía de programación y consulta

37 Transferir y obtener paquetes de datos v Un asa de objeto de la cola en la que se va a leer el mensaje. v Un descriptor de mensaje. En la estructura MQMD, el parámetro Format debe ser MQFMT_ADMIN, MQFMT_EVENT o MQFMT_PCF. v v Nota: Si el mensaje se recibe dentro de una unidad de trabajo (es decir, con la opción MQGMO_SYNCPOINT) y el mensaje tiene un formato no soportado, la unidad de trabajo puede restituirse. El mensaje se restablecerá y podrá recuperarse utilizando la llamada MQGET en lugar de la llamada mqgetbag. Hallará más información acerca del descriptor de mensaje en el manual MQSeries Application Programming Reference. Opciones de obtener mensaje (GMO) utilizando la estructura MQGMO. Puede encontrar más información sobre la estructura MQGMO en el manual MQSeries Application Programming Reference. El asa del paquete que va a contener el mensaje convertido. Si desea ver una descripción completa de la llamada mqgetbag, consulte la sección mqgetbag en la página 53. Capítulo 4. Intercambio de datos entre aplicaciones 21

38 Cambios 22 MQSeries Interfaz de administración, Guía de programación y consulta

39 Capítulo 5. Consulta de MQAI Este capítulo contiene información de consulta de la MQAI. Existen tres tipos de llamadas: v v v Llamadas de manipulación de paquetes de datos para configurar paquetes de datos: mqaddinquiry en la página 24 mqaddinteger en la página 26 mqaddstring en la página 28 mqclearbag en la página 36 mqcountitems en la página 37 mqcreatebag en la página 39 mqdeletebag en la página 43 mqdeleteitem en la página 45 mqinquirebag en la página 56 mqinquireinteger en la página 59 mqinquireiteminfo en la página 62 mqinquirestring en la página 65 mqsetinteger en la página 73 mqsetstring en la página 76 mqtruncatebag en la página 82 Llamadas de mandatos para enviar y recibir mandatos de administración y mensajes PCF: mqbagtobuffer en la página 31 mqbuffertobag en la página 34 mqexecute en la página 48 mqgetbag en la página 53 mqputbag en la página 71 Llamadas de programas de utilidad para manejar series rellenadas con blancos y series que terminan con nulo: mqpad en la página 69 mqtrim en la página 80 Estas llamadas se describen por orden alfabético en las secciones que siguen. Copyright IBM Corp. 1999,