Cancel Message - OMCNLMSG
Cancel Message (OMCNLMSG) RI
Required Parameter Group:
| 1 | Global Message Handle | Input | Packed(9,0) |
| 2 | Return Status | Output | Char(1) |
| 3 | Reason Code | Output | Char(4) |
API Overview:
The Cancel Message API (OMCNLMSG) provides a mechanism for an external application to cancel a QTRACS forward message. More accurately, this API accepts a cancellation request , which may or may not finally cancel the previous forward message. The API will attempt to cancel the forward transmittable component(s) of a forward message specified by the input GMH. This API is the same one that is triggered via the QTRACS Message Directory by placing option 7 against a forward message.
Required Parameter Group Details:
(1) Global Message Handle
INPUT; PACKED(9,0)
This parameter must contain the unique global message handle of the existing forward message to be cancelled.
(2) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Success, forward message cancelled |
| 1 | Failure, forward message not cancelled |
| A | Failure, API failed when called remotely |
(3) Reason Code
OUTPUT; CHAR(4)
This parameter contains a reason code. Possible values returned include;
| 0000 | Success, scheduled message cancelled; status set to 'CNLD - Cancelled'. |
| 0001 | Success, the message has not been sent to the NMC yet, but once it is, a cancellation request will be sent immediately; status set to 'CNLG - Canceling'. |
| 0002 | Success, the transmitting forward message was sent to the NMC. A cancellation request will be sent to the NMC as well. Its status has been set to 'CNLG - Canceling'. |
| 0011 | Failure, the specified message was not a forward message. |
| 0012 | Failure, the specified forward message was already received by the recipient. |
| 0013 | Failure, the specified message was not found or some component was missing. |
Effect
Calling this API from an external application will result in one of the following:
- A scheduled forward message will be cancelled immediately. In this case, the status of the specified forward message will be changed from SCHD to CNLD. Reason code 0000 will be returned to the caller.
- A pending forward message will be cancelled as soon as its associated transaction is processed by the QTRACS Communications Manager. In this case, the status of the specified forward message will be changed from PEND to CNLG. Reason code 0001 will be returned to the caller. The external application that sent the original forward message should expect an FMC to be routed to it when the cancellation request completes. At this time, the status of the forward message would be set to CNLD.
- An attempt will be made to cancel a transmitting forward message by sending a Message Delete transaction to the NMC. In this case, the status of the specified forward message will be changed from XMIT to CNLG. Reason code 0002 will be returned to the caller. The external application that sent the original forward message should expect an FMC to be routed to it when the cancellation request completes. At this time, the status of the forward message will be set to CNLD or RCVD based on whether the cancellation request was successful or not.
- None of the above will happen because the API was unable to process the cancellation request for the specified forward message. If so, a return status of 1 and an associated 'failure' reason code will be returned to the caller.