Copyrighted material John Tullis 9/4/2015 page 1 04/29/00 MQSeries Part 3 John Tullis DePaul Instructor

Copyrighted material John Tullis 9/4/2015 page 2 MQSeries Part 3 MQSeries Documentation MQSeries for Windows NT V5.0 Quick Beginnings MQSeries System Administration MQSeries Command Reference MQSeries Application Programming Guide MQSeries Using C++

Copyrighted material John Tullis 9/4/2015 page 3 MQSeries Part 3 MQSeries System Admin Administration tasks include creating, starting, altering, viewing, stopping, and deleting MQSeries objects, that is, queue managers, queues, processes, and channels. To perform these tasks, you must select the appropriate command from one of the supplied command sets: Control commands MQSC commands PCF commands

Copyrighted material John Tullis 9/4/2015 page 4 MQSeries Part 3 MQSeries Control Commands Queue manager commands, channel commands, & utility commands. These include commands for creating, starting, stopping, and deleting Q managers and command servers. Channel commands, including commands for starting and ending channels and channel initiators. Utility commands, including commands associated with: running MQSC commands, conversion exits, authority management, recording and recovering media images of queue manager resources, displaying and resolving transactions, trigger monitors, displaying the file names of MQSeries objects

Copyrighted material John Tullis 9/4/2015 page 5 MQSeries Part 3 MQSeries Control Commands In MQSeries for Windows NT, you enter control commands at a command prompt. In this environment, control commands and their flags are not case sensitive, but arguments to those commands (such as queue names and queue-manager names) are case sensitive. For example, in the command: crtmqm /u SYSTEM.DEAD.LETTER.QUEUE jupiter.queue.manager The command name can be entered in uppercase or lowercase, or a mixture of the two. These are all valid: crtmqm, CRTMQM, and CRTmqm. The flag can be entered as -u, -U, /u, or /U. The arguments SYSTEM.DEAD.LETTER.QUEUE and jupiter.queue.manager must be entered exactly as shown.

Copyrighted material John Tullis 9/4/2015 page 6 MQSeries Part 3 MQSeries Commands (MQSC) You use the MQSeries (MQSC) commands to manage queue manager objects, including the queue manager itself, channels, queues, and process definitions. For example, there are commands to define, alter, display, and delete a specified queue. When you display a queue, using the DISPLAY QUEUE command, you display the queue attributes. For example, the MAXMSGL attribute specifies the maximum length of a message that can be put on the queue. The command does not show you the messages on the queue.

Copyrighted material John Tullis 9/4/2015 page 7 MQSeries Part 3 PCF Commands The purpose of the MQSeries programmable command format (PCF) commands is to allow administration tasks to be programmed into an administration program. In this way you can create queues and process definitions, and change queue managers, from a program. In fact, PCF commands cover the same range of functions that are provided by the MQSC facility. You can therefore write a program to issue PCF commands to any queue manager in the network from a single node. In this way, you can both centralize and automate administration tasks.

Copyrighted material John Tullis 9/4/2015 page 8 MQSeries Part 3 Getting Started Before you can do anything with messages and queues, you must create at least one queue manager and its associated objects. To create a queue manager, you use the MQSeries control command crtmqm. The crtmqm command automatically creates the required default objects and system objects. Default objects form the basis of any object definitions that you make; system objects are required for queue manager operation. When a queue manager and its objects have been created, you use the strmqm command to start the queue manager.

Copyrighted material John Tullis 9/4/2015 page 9 MQSeries Part 3 Checklist…. You create a queue manager using the crtmqm command. However, before you try this, especially in a production environment, work through this checklist: Specify a unique queue manager name. Limit the number of queue managers. Specify a default queue manager. Specify a dead-letter queue. Specify a default transmission queue. Specify the required logging parameters. Back up configuration files after creating a queue manager. See documentation for details.

Copyrighted material John Tullis 9/4/2015 page 10 MQSeries Part 3 MQSeries file names Each MQSeries queue, queue manager, and process object is represented by a file. Because object names are not necessarily valid file names, the queue manager converts the object name into a valid file name, where necessary. The path to a queue manager directory is formed from the following: A prefix, which is defined in the queue manager configuration file such as: c:\mqm A literal such as: qmgrs A coded name that becomes a directory name: queue.manager. Note - ‘.’ gets transformed into ‘!’, so the path becomes: c:\mqm\qmgrs\queue!manager Note - there are limitations to name length also - see documentation.

Copyrighted material John Tullis 9/4/2015 page 11 MQSeries Part 3 Creating a default Q mgr The following command: creates a default queue manager called saturn.queue.manager; creates the default and system objects; and specifies the names of both a default transmission queue and a dead- letter queue: crtmqm -q -d MY.DEFAULT.XMIT.QUEUE -u SYSTEM.DEAD.LETTER.QUEUE saturn.queue.manager -q indicates this is the default transmission queue. -d specifies the name. -u specifies the name of the dead letter Q. And ‘saturn.queue.manager’ is the name of this Q manager.

Copyrighted material John Tullis 9/4/2015 page 12 MQSeries Part 3 Starting the Q mgr Although you have created a queue manager, it cannot process commands or MQI calls until it has been started. Start the queue manager by typing in this command: strmqm saturn.queue.manager In MQSeries for Windows NT, a queue manager can be invoked automatically when the system starts. To request automatic startup of a queue manager, enter: scmmqm -a -s c:\mqm\startup.cmd saturn.queue.manager -a means the Q manager is added to the list to be auto started -s references a command file of actions for when Q manager is started. Each queue manager that is auto started requires its own command file.

Copyrighted material John Tullis 9/4/2015 page 13 MQSeries Part 3 Stopping Q mgr In order to prevent Windows NT from starting a queue manager automatically, use the following command: scmmqm -d saturn.queue.manager To manually stop a queue manager, use the endmqm command. For example, to stop a queue manager called saturn.queue.manager use this command: endmqm saturn.queue.manager By default, the above command performs a quiesced shutdown of the specified queue manager. This may take a while to complete. A quiesced shutdown waits until all connected applications have disconnected. For immediate shutdown, use: endmqm -i saturn.queue.manager

Copyrighted material John Tullis 9/4/2015 page 14 MQSeries Part 3 Issuing MQSC commands for administration Issue commands using the runmqsc command. Before you can run commands, you must have created and started the Q manager that is going to execute the commands. From an NT command line window, enter: runmqsc If you just do this, since no Q manager was specified, the default Q manager will execute the commands. To display Q manager attributes, enter: DISPLAY QMGR To stop the command mode, enter: END

Copyrighted material John Tullis 9/4/2015 page 15 MQSeries Part 3 Running MQSC commands from text files Running MQSC commands interactively is suitable for quick tests, but if you have very long commands, or are using a particular sequence of commands repeatedly, consider redirecting stdin from a text file. (See documentation for information about stdin and stdout.) To do this, first create a text file containing the MQSC commands using your usual text editor. When you use the runmqsc command, use the redirection operators, like so: runmqsc < myinputfile.in You can also redirect any output from the command to a file: runmqsc myout.out

Copyrighted material John Tullis 9/4/2015 page 16 MQSeries Part 3 Running MQSC commands from text files Running the commands this way use the standard Q manager, because one was not specified. To use a specific Q manager: runmqsc chemco.queue.mgr myresults.out Example of an input command file follows on the next slide.

Copyrighted material John Tullis 9/4/2015 page 17 MQSeries Part 3 Defining a local queue The command to create a Q that has the characteristics of - enabled for gets, disabled for puts, and operates on a first-in-first-out (FIFO) basis, an 'ordinary' queue & not an initiation queue or a transmission queue, does not generate trigger messages, the maximum Q depth is 1000 messages; & the maximum message length is 2000 bytes is: DEFINE QLOCAL (CHEMCO.LOCAL.QUEUE) + DESCR('Queue for messages from other systems') + PUT (DISABLED) + GET (ENABLED) + NOTRIGGER + MSGDLVSQ (FIFO) + MAXDEPTH (1000) + MAXMSGL (2000) + USAGE (NORMAL);.

Copyrighted material John Tullis 9/4/2015 page 18 MQSeries Part 3 The dead letter queue Each queue manager should have a local queue to be used as a dead-letter queue so that messages that cannot be delivered to their correct destination can be stored for later retrieval. You must explicitly tell the queue manager about the dead-letter queue. You can do this by specifying a dead-letter queue on the crtmqm command, or you can use the ALTER QMGR command to specify one later. You must also define the dead-letter queue before it can be used. A sample dead-letter queue called SYSTEM.DEAD.LETTER.QUEUE is supplied with the product.

Copyrighted material John Tullis 9/4/2015 page 19 MQSeries Part 3 Default queue attributes When you define an MQSeries object, it takes any attributes that you do not specify from the default object. For example, when you define a local queue, the queue inherits any attributes that you omit in the definition from the default local queue, which is called SYSTEM.DEFAULT.LOCAL.QUEUE. To see exactly what these attributes are, use the following command: DISPLAY QUEUE (SYSTEM.DEFAULT.LOCAL.QUEUE) You can selectively display queue attributes as follows: DISPLAY QUEUE(CHEMCO.LOCAL.QUEUE) + MAXDEPTH + MAXMSGL;

Copyrighted material John Tullis 9/4/2015 page 20 MQSeries Part 3 Alias queues An alias queue (also known as a queue alias) provides a method of redirecting MQI calls. An alias queue is not a real queue but a definition that resolves to a real queue. The alias queue definition contains a target queue name which is specified by the TARGQ attribute. When an application specifies an alias queue in an MQI call, the queue manager resolves the real queue name at run time, which could be either a local queue or a remote queue defined at this queue manager. The application is not aware that the queue is an alias queue. By changing the value of the TARGQ attribute, you can redirect MQI calls to another queue, possibly on another queue manager. This is useful for maintenance, migration, and load-balancing.

Copyrighted material John Tullis 9/4/2015 page 21 MQSeries Part 3 Alias queues To create an alias queue, do thusly: DEFINE QALIAS (MY.ALIAS.QUEUE) TARGQ (YELLOW.QUEUE) You can also use alias queues to make a single queue (the target queue) appear to have different attributes for different applications. You do this by defining two aliases, one for each application. Suppose there are two applications: Application ALPHA can put messages on YELLOW.QUEUE, but is not allowed to get messages from it. Application BETA can get messages from YELLOW.QUEUE, but is not allowed to put messages on it.

Copyrighted material John Tullis 9/4/2015 page 22 MQSeries Part 3 Triggering MQSeries provides a facility for starting an application automatically when certain conditions on a queue are met. One example of the conditions is when the number of messages on a queue reaches a specified number. This triggering facility is described in detail in the MQSeries Application Programming Guide. An application queue is a local queue that is used by applications for messaging, through the MQI. Triggering requires a number of queue attributes to be defined on the application queue. Triggering itself is enabled by the Trigger attribute (TRIGGER in MQSC). In the example on the next slide, a trigger event is to be generated when there are 5 messages of priority 5 or greater on the local queue CHEMCO.ORDERS.QUEUE, as follows:

Copyrighted material John Tullis 9/4/2015 page 23 MQSeries Part 3 Triggering DEFINE QLOCAL (CHEMCO.ORDERS.QUEUE) + PROCESS (GETTHOSEORDERS.PROCESS) + MAXMSGL (2000) + DEFPSIST (YES) + INITQ (CHEMCO.ORDERS.INIT.QUEUE) + TRIGGER + TRIGTYPE (DEPTH) + TRIGDPTH (5) + TRIGMPRI (5) QLOCAL specfies the name of the Q being defined. PROCESS specifies the name of the application to be triggered. DEFPSIST specifies that messages on this queue are persistent. INITQ is the name of the initiation Q where the queue manager is to put the trigger message. TRIGTYPE specifies that a trigger event occurs when the number of messages (DEPTH) specified in TRIGDPTH of priority TRIGMPRI are present.

Copyrighted material John Tullis 9/4/2015 page 24 MQSeries Part 3 Triggers - the initiation queue When a trigger event occurs, the queue manager puts a trigger message on the initiation queue specified in the application queue definition. Initiation queues have no special settings. For example: DEFINE QLOCAL(CHEMCO.ORDERS.INIT.QUEUE) + GET (ENABLED) + NOSHARE + NOTRIGGER + MAXMSGL (2000) + MAXDEPTH (1000)

Copyrighted material John Tullis 9/4/2015 page 25 MQSeries Part 3 Triggers - process definitions Use the DEFINE PROCESS command to create a process definition. A process definition associates an application queue with the application that is to process messages from the queue. This is done through the PROCESS attribute on the application queue CHEMCO.ORDERS.QUEUE. The following MQSC command defines the required process, GETTHOSEORDERS.PROCESS, identified on the next slide:

Copyrighted material John Tullis 9/4/2015 page 26 MQSeries Part 3 Triggers - process definitions DEFINE PROCESS (GETTHOSEORDERS.PROCESS) + DESCR (‘Get orders for processing’) + APPLTYPE (NT) + APPLICID (’c:\appl\chemco\programs\getorders1.exe') + USERDATA ('open, close, 235') To see the results of the the definition, use: DISPLAY PROCESS (GETTHOSEORDERS.PROCESS)

Copyrighted material John Tullis 9/4/2015 page 27 MQSeries Part 3 MQSeries Admin…winding down Review the documentation for details on how to manage the system. Review areas should include: Protecting the MQSeries objects (security, etc.) Configuration files The dead letter queue handler Instrumentation events (e.g., queue full, etc.) Restart & recovery; logging Problem determination

Copyrighted material John Tullis 9/4/2015 page 28 MQSeries Part 3 MQSeries Programming - API calls MQCONN, MQDISC - connect & disconnect a program to/from a queue manager. MQOPEN, MQCLOSE - open & close an object such as a queue. MQPUT - put messages on a queue. MQGET - get messages from a queue. MQBEGIN, MQCMIT, MQBACK - standard transaction management to begin, commit, or roll back a unit of work. Indicates to the queue manager that all messages put or retrieved since the last syncpoint are to be committed or backed out.

Copyrighted material John Tullis 9/4/2015 page 29 MQSeries Part 3 MQSeries Programming - libraries In the NT environment, application programs that want to call the MQI calls need to link in the following libraries: MQM.lib - server for 32 bit C. IMQ*.lib - server for C++. See documentation for other libraries.

Copyrighted material John Tullis 9/4/2015 page 30 MQSeries Part 3 Connection and object handles For a program to communicate with a queue manager, the program must have a unique identifier by which it knows that queue manager. This identifier is called a connection handle. The connection handle is returned by the MQCONN or MQCONNX call when the program connects to the queue manager. Programs pass the connection handle as an input parameter when they use the other calls. For a program to work with an MQSeries object, the program must have a unique identifier by which it knows that object. This identifier is called an object handle. The handle is returned by the MQOPEN call when the program opens the object to work with it. Programs pass the object handle as an input parameter when they use MQPUT, MQGET, MQINQ, MQSET, or MQCLOSE calls.

Copyrighted material John Tullis 9/4/2015 page 31 MQSeries Part 3 Return codes A completion code and a reason code are returned as output parameters by each call. These are known collectively as return codes. The completion code is usually either MQCC_OK or MQCC_FAILED, showing success and failure, respectively. Some calls can return an intermediate state, MQCC_WARNING, indicating partial success. The reason code shows the reason for the failure, or partial success, of the call. There are many reason codes, covering such circumstances as a queue being full, get operations not being allowed for a queue, and a particular queue not being defined for the queue manager. When the completion code is MQCC_OK, the reason code is always MQRC_NONE.

Copyrighted material John Tullis 9/4/2015 page 32 MQSeries Part 3 MQCONN As input to MQCONN, you must supply a queue manager name. The output from MQCONN is: A connection handle A completion code A reason code You will need to use the connection handle on subsequent MQI calls. If the reason code indicates that the application is already connected to that queue manager, the connection handle that is returned is the same as the one that was returned when the application first connected. So the application might not issue the MQDISC call in this situation since the calling application will expect to remain connected.

Copyrighted material John Tullis 9/4/2015 page 33 MQSeries Part 3 MQDISC When a program that has connected to a queue manager using the MQCONN call has finished all interaction with the queue manager, it must break the connection using the MQDISC call. After MQDISC is called, the connection handle (Hconn) is no longer valid, and you cannot issue any further MQI calls until you call MQCONN again. MQDISC does an implicit MQCLOSE for any objects that are still open using this handle. As input to the MQDISC call, you must supply the connection handle (Hconn) that was returned by MQCONN when you connected to the queue manager. The output from this call is a completion code and a reason code, with the connection handle set to the value MQHC_UNUSABLE_HCONN.

Copyrighted material John Tullis 9/4/2015 page 34 MQSeries Part 3 MQOPEN Use the MQOPEN call to open the object, using the options of the call to specify what you want to do with the object. The only exception is if you want to put a single message on a queue, then close the queue immediately. In this case, you can bypass the "opening" stage by using the MQPUT1 call (see documentation). Objects are closed automatically when a program disconnects from the queue manager. It is good programming practice to close objects you have opened. Use the MQCLOSE call to do this.

Copyrighted material John Tullis 9/4/2015 page 35 MQSeries Part 3 MQCLOSE As input to the MQCLOSE call, you must supply a connection handle (which came from the MQCONN call), and a handle for the object you want to close (which came from the MQOPEN call), MQCO_NONE in the options field. The output from MQCLOSE is a completion code, a reason code, and the object handle now reset to MQHO_UNUSABLE_HOBJ. See the documentation (especially the MQSeries Application Reference Programming Reference) for details.

Copyrighted material John Tullis 9/4/2015 page 36 MQSeries Part 3 MQPUT As input to the MQPUT call, you must supply: A connection handle (HCONN). A queue handle (HObj). A description of the message you want to put on the queue. This is in the form of a message descriptor structure (MQMD). Control information, in the form of a put-message options structure (MQPMO). The length of the data contained within the message (MQLONG). The message data itself.

Copyrighted material John Tullis 9/4/2015 page 37 MQSeries Part 3 MQPUT Example C code MQPUT invocation information: MQPUT (Hconn, Hobj, &MsgDesc, &PutMsgOpts, BufferLength, Buffer, &CompCode, &Reason); MQHCONN Hconn; /* Connection handle */ MQHOBJ Hobj; /* Object handle */ MQMD MsgDesc; /* Message descriptor */ MQPMO PutMsgOpts; /* Options that control the action of MQPUT */ MQLONG BufferLength; /* Length of the message in Buffer */ MQBYTE Buffer[n]; /* Message data */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code qualifying CompCode */

Copyrighted material John Tullis 9/4/2015 page 38 MQSeries Part 3 MQGET As input to the MQGET call, you must supply: A connection handle. A queue handle. A description of the message you want to get from the queue. This is in the form of a message descriptor (MQMD) structure. Control information in the form of a Get Message Options (MQGMO) structure. The size of the buffer you have assigned to hold the message (MQLONG). The address of the storage in which the message must be put.

Copyrighted material John Tullis 9/4/2015 page 39 MQSeries Part 3 MQGET Example C code MQGET invocation information: MQGET (Hconn, Hobj, &MsgDesc, &GetMsgOpts, BufferLength, Buffer, &DataLength, &CompCode, &Reason); MQHCONN Hconn; /* Connection handle */ MQHOBJ Hobj; /* Object handle */ MQMD MsgDesc; /* Message descriptor */ MQGMO GetMsgOpts; /* Options that control the action of MQGET */ MQLONG BufferLength; /* Length in bytes of the Buffer area */ MQBYTE Buffer[n]; /* Area to contain the message data */ MQLONG DataLength; /* Length of the message */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code qualifying CompCode */

Copyrighted material John Tullis 9/4/2015 page 40 MQSeries Part 3 MQ Application programming Read the documentation! Go to the lab - look for samples. Run experiments.