WebSphere MQ Call Routines

MQRMH

Creates or manipulates a reference message header so that an application can put a message in this format, omitting the bulk data.

Syntax
Arguments
Details
Example

Syntax

CALL MQRMH(hrmh, action, rc, parms, value1, value2, ...);

Specifies a Base SAS internal handle to a reference message header. The handle is generated as output when action is to generate default message header parameters. The handle should be supplied when you are setting or querying a parameter.

action

Character, input

Specifies the desired action of this routine. The following action values are valid:

GEN: Generate a handle representing default reference message header parameters as defined by WebSphere MQ.
SET: After a message header handle has been generated, you can set values as necessary.
INQ: After a message header handle has been generated, you can query its values.

rc

Numeric, output

Provides the Base SAS return code from this function. If an error occurs, then the return code is nonzero. You can use the Base SAS function SYSMSG() to obtain a textual description of the return code.

parms

Character, input

Specifies an optional string of reference message header parameters that you want to set. Each parameter must be separated by a comma and must have a value associated with it in the function's parameter list. The OBJECTTYPE, SRCNAME, and DESTNAME parameters should be defined.

value

Numeric or character, input or output

Provides a value for a reference message header parameter that is specified in the parms string. You must provide a value parameter for each reference message header parameter that is specified in the parms string and the data type must be of the proper type. Variables that are used to store character values being returned in an inquiry (INQ action) should be initialized appropriately to guarantee that truncation of a returned value does not occur.

The following reference message header parameters (parms) and values are valid:

ENCODING

Numeric, input

Data encoding

CODEDCHARSETID

Numeric, input

Coded character set identifier

FORMAT

Character8, input

Format name

OBJECTTYPE

Character8, input

Object type

SRCNAME

Character, input

Source object name

DESTNAME

Character, input

Destination object name

Details

When the reference message header is read from the transmission queue by a message channel agent (MCA), a user-supplied message exit is invoked to process the reference message. A sample message exit is supplied by WebSphere MQ, amqsxrm. You must add this message exit to the sending and receiving channel definitions. The message exit on the sending side can append to the reference message the bulk data identified by the reference message header before the MCA sends the message through the channel to the next queue manager.

When a reference message is received, the receiving message exit should create the object from the bulk data that is associated with the reference message header, and then pass on the reference message without the bulk data so that the reference message (without the bulk data) can later be retrieved by a program.

Example

This example goes through the process of connecting to a queue manager, preparing the queue, generating the message, closing the queue, and freeing all resources.

   data _null_;
   length hconn hobj cc reason 8;
   length rc hod hpmo hmd hrmh 8;
   length msg $ 200;

   hconn=0;
   hobj=0;
   hod=0;
   hpmo=0;
   hmd=0;
   hrmh=0;

   put '---------------- Connect to QMgr --------------';
   call mqconn("TESTQMGR", hconn, cc, reason);
   if cc ^= 0 then do;
      if reason = 2002 then do;
         put 'Already connected to QMgr ' qmgr;
      end;
      else do;
         if reason = 2059 then
            put 'MQCONN: QMgr not available...
               needs to be started';
         else
            put 'MQCONN: failed with reason= ' reason;
         goto exit;
      end;
   end;
   else put 'MQCONN: successfully connected to QMgr ' qmgr;


   put '---------- Generate object descriptor ---------';
   call mqod(hod, "GEN", rc, "OBJECTNAME", "TESTQ");
   if rc ^= 0 then do;
      put 'MQOD: failed with rc= ' rc;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQOD: successfully generated
      object descriptor';


   put '-------- Open queue object for output ---------';
   call mqopen(hconn, hod, "OUTPUT", hobj, cc, reason);
   if cc ^= 0 then do;
      put 'MQOPEN: failed with reason= ' reason;
     goto exit;
   end;
   else put 'MQOPEN: successfully opened queue for output';


   put '--------- Generate put message options --------';
   call mqpmo(hpmo, "GEN", rc);
   if rc ^= 0 then do;
      put 'MQPMO: failed with rc= ' rc;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQPMO: successfully generated put
      message options';


   put '--------- Generate message descriptor ---------';
   /* format must be set to reference message header */
   call mqmd(hmd, "GEN", rc, "PERSISTENCE,FORMAT",
      "PERSISTENT", "MQHREF");
   if rc ^= 0 then do;
      put 'MQMD: failed with rc= ' rc;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQMD: successfully generated
      message descriptor';

   /** reference message header **/
   call mqrmh(hrmh, "GEN", rc,
      "SRCNAME,DESTNAME,OBJECTTYPE",
      "d:\test.txt", "d:\testdup.txt", "FLATFILE");
   if rc ^= 0 then do;
      put 'MQRMH: failed with rc= ' rc;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQRMH: successfully generated reference
      message header';

   put '------------- Put message on queue ------------';
   call mqput(hconn, hobj, hmd, hpmo, hrmh, cc, reason);
   if cc ^= 0 then do;
      put 'MQPUT: failed with reason= ' reason;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQPUT: successfully put message on queue';


   exit:
   if hobj ^= 0 then do;
      put '----------------- Close queue ---------------';
      call mqclose(hconn, hobj, "NONE", cc, reason);
      if cc ^= 0 then do;
         put 'MQCLOSE: failed with reason= ' reason;
      end;
      else put 'MQCLOSE: successfully closed queue';
   end;


   if hconn ^= 0 then do;
      put '------------ Disconnect from QMgr -----------';
      call mqdisc(hconn, cc, reason);
      if cc ^= 0 then do;
         put 'MQDISC: failed with reason= ' reason;
      end;
      else put 'MQDISC: successfully disconnected
         from QMgr';
   end;


   if hod ^= 0 then do;
      call mqfree(hod);
      put 'Object descriptor handle freed';
   end;
   if hpmo ^= 0 then do;
      call mqfree(hpmo);
      put 'Put message options handle freed';
   end;
   if hmd ^= 0 then do;
      call mqfree(hmd);
      put 'Message descriptor handle freed';
   end;
   if hrmh ^= 0 then do;
      call mqfree(hrmh);
      put 'Reference message header handle freed';
   end;
   run;

Top of Page

MQRMH

Syntax

Arguments