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 Reason codes.
Usage notes
The following usage notes apply to the use of the Action code MQSR_ACTION_PUBLICATION:
- 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.
- 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.
- If this verb completes with a reason code of MQRC_NO_RETAINED_MSG then there were no currently retained publications for the topic specified.#
- 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.
- 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.
- 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 COMPCODEParent topic: Function calls