Upload
owen-farmer
View
220
Download
0
Embed Size (px)
Citation preview
Copyrighted materialJohn Tullis
04/21/23page 1
04/29/00 MQSeries Part 3
John TullisDePaul [email protected]
Copyrighted materialJohn Tullis
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++
Copyrighted materialJohn Tullis
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
Copyrighted materialJohn Tullis
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
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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
Copyrighted materialJohn Tullis
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
Copyrighted materialJohn Tullis
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
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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);
.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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;
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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:
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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)
Copyrighted materialJohn Tullis
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:
Copyrighted materialJohn Tullis
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)
Copyrighted materialJohn Tullis
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
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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 */
Copyrighted materialJohn Tullis
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.
Copyrighted materialJohn Tullis
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 */
Copyrighted materialJohn Tullis
04/21/23page 40
MQSeries Part 3
MQ Application programming • Read the documentation!• Go to the lab - look for samples.• Run experiments.