copyrighted material john tullis 9/4/2015 page 1 04/29/00 mqseries part 3 john tullis depaul...

Copyrighted materialJohn Tullis

04/21/23page 1

04/29/00 MQSeries Part 3

John TullisDePaul [email protected]


04/21/23page 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++


04/21/23page 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


04/21/23page 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


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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!managerNote - there are limitations to name length also - see documentation.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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


04/21/23page 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


04/21/23page 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 < mycomfile.in > myout.out


04/21/23page 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 < mycom.in > myresults.out• Example of an input command file follows on the next slide.


04/21/23page 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);

.


04/21/23page 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.


04/21/23page 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;


04/21/23page 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.


04/21/23page 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.


04/21/23page 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:


04/21/23page 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.


04/21/23page 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)


04/21/23page 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:


04/21/23page 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)


04/21/23page 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


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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.


04/21/23page 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 */


04/21/23page 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.


04/21/23page 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 */


04/21/23page 40

MQSeries Part 3

MQ Application programming • Read the documentation!• Go to the lab - look for samples.• Run experiments.

copyrighted material john tullis 9/4/2015 page 1 04/29/00 mqseries part 3 john tullis depaul...

Documents