MQSUBRQ - Subscription request

Use the MQSUBRQ call to make a request for the retained publication, when the subscriber has been registered with MQSO_PUBLICATIONS_ON_REQUEST.

Syntax

MQSUBRQ (Hconn, Hsub, Action, SubRqOpts, Compcode, Reason)

Parameters

Hconn
Type: MQHCONN - input

This handle represents the connection to the queue manager. The value of Hconn was returned by a previous MQCONN or MQCONNX call.

On z/OS® for CICS® applications the MQCONN call can be omitted, and the following value specified for Hconn :
MQHC_DEF_HCONN
Default connection handle.
Hsub
Type: MQHOBJ - input

This handle represents the subscription for which an update is to be requested. The value of Hsub was returned from a previous MQSUB call.

Action
Type: MQLONG - input
This parameter controls the particular action that is being requested on the subscription. The following value must be specified:
MQSR_ACTION_PUBLICATION

This action requests that an update publication is sent for the specified topic. It can be used only if the subscriber specified the option MQSO_PUBLICATIONS_ON_REQUEST on the MQSUB call when it made the subscription. If the queue manager has a retained publication for the topic, this is sent to the subscriber. If not, the call fails. If an application is sent a publication which was retained, this is indicated by the MQIsRetained message property of that publication.

Since the topic in the existing subscription represented by the Hsub parameter can contain wildcards, the subscriber might receive multiple retained publications.

SubRqOpts
Type: MQSRO - input/output

These options control the action of MQSUBRQ, see MQSRO - Subscription request options for details.

If no options are required, programs written in C or S/390 assembler can specify a null parameter address instead of specifying the address of an MQSRO structure.

CompCode
Type: MQLONG - output
The completion code; it is one of the following:
MQCC_OK
Successful completion
MQCC_WARNING
Warning (partial completion)
MQCC_FAILED
Call failed
Reason
Type: MQLONG - output

The reason code qualifying CompCode.

If CompCode is MQCC_OK:
MQRC_NONE
(0, X'000') No reason to report.
If CompCode is MQCC_FAILED:
MQRC_FUNCTION_NOT_SUPPORTED
2298 (X'08FA') The function requested is not available in the current environment.
MQRC_NO_RETAINED_MSG
2437 (X'0985') There are no retained publications currently stored for this topic.
MQRC_OPTIONS_ERROR
2046 (X'07FE') Options parameter or field contains options that are not valid, or a combination of options that is not valid.
MQRC_Q_MGR_QUIESCING
2161 (X'0871') Queue manager quiescing.
MQRC_SRO_ERROR
2438 (X'0986') On the MQSUBRQ call, the Subscription Request Options MQSRO is not valid.
MQRC_RETAINED_MSG_Q_ERROR
2525 (X'09DD') Retained publications which exist for the subscribed topic string, cannot be retrieved.
MQRC_RETAINED_NOT_DELIVERED
2526 (X'09DE') The retained publications which exist for the subscribed topic string, cannot be delivered to the subscription destination queue, and cannot be delivered to the dead-letter queue.

For detailed information about these codes, see Messages and reason codes.

Usage notes

The following usage notes apply to the use of the Action code MQSR_ACTION_PUBLICATION:

  1. If this verb completes successfully, the retained publications matching the subscription specified have been sent to the subscription and can be received by using MQGET or MQCB using the Hobj returned on the original MQSUB verb that created the subscription.
  2. If the topic subscribed to by the original MQSUB verb that created the subscription contained a wildcard, more than one retained publication can be sent. The number of publications sent as a result of this call is recorded in the NumPubs field in the SubRqOpts structure.
  3. If this verb completes with a reason code of MQRC_NO_RETAINED_MSG then there were no currently retained publications for the topic specified.#
  4. If this verb completes with a reason code of MQRC_RETAINED_MSG_Q_ERROR or MQRC_RETAINED_NOT_DELIVERED then there are currently retained publications for the topic specified but an error has occurred that that meant they were unable to be delivered.
  5. The application must have a current subscription to the topic before it can make this call. If the subscription was made in a previous instance of the application and a valid handle to the subscription is not available, the application must first call MQSUB with the MQSO_RESUME option to obtain a handle to it for use in this call.
  6. The publications are sent to the destination that is registered for use with the current subscription of this application. If the publications must be sent somewhere else, the subscription must first be altered using the MQSUB call with the MQSO_ALTER option.

C invocation


MQSUB (Hconn, Hsub, Action, &SubRqOpts, &CompCode, &Reason)
Declare the parameters as follows: 

MQHCONN Hconn;     /* Connection handle */
MQHOBJ  Hsub;      /* Subscription handle */
MQLONG  Action;    /* Action requested by MQSUBRQ */
MQSRO   SubRqOpts; /* Options that control the action of MQSUBRQ */
MQLONG  CompCode;  /* Completion code */
MQLONG  Reason;    /* Reason code qualifying CompCode */

COBOL invocation


CALL 'MQSUBRQ' USING HCONN, HSUB, ACTION, SUBRQOPTS, COMPCODE, REASON.
Declare the parameters as follows: 

** Connection handle
01 HCONN PIC S9(9) BINARY.
** Subscription handle
01 HSUB PIC S9(9) BINARY.
** Action requested by MQSUBRQ
01 ACTION PIC S9(9) BINARY.
** Options that control the action of MQSUBRQ
01 SUBRQOPTS.
COPY CMQSROV.
** Completion code
01 COMPCODE PIC S9(9) BINARY.
** Reason code qualifying COMPCODE
01 REASON PIC S9(9) BINARY.

PL/I invocation


call MQSUBRQ (Hconn, Hsub, Action, SubRqOpts, CompCode, Reason)
Declare the parameters as follows: 

dcl Hconn fixed bin(31);    /* Connection handle */
dcl Hsub fixed bin(31);     /* Subscription handle */
dcl Action fixed bin(31);   /* Action requested by MQSUBRQ */
dcl SubRqOpts like MQSRO;   /* Options that control the action of MQSUBRQ */
dcl CompCode fixed bin(31); /* Completion code */
dcl Reason fixed bin(31);   /* Reason code qualifying CompCode */

High Level Assembler invocation


CALL MQSUBRQ,(HCONN, HSUB, ACTION, SUBRQOPTS,COMPCODE,REASON)
Declare the parameters as follows: 

HCONN DS F Connection handle
HSUB DS F Subscription handle
ACTION DS F Action requested by MQSUBRQ
SUBRQOPTS CMQSROA , Options that control the action of MQSUBRQ
COMPCODE DS F Completion code
REASON DS F Reason code qualifying COMPCODE