COMMON MESSAGE INFRASTRUCTURE MQ PROGRAMMER'S GUIDE

Transcription

1 COMMON MESSAGE INFRASTRUCTURE MQ PROGRAMMER'S GUIDE MAY 14, 2018

2 Copyright 2018 The Depository Trust & Clearing Corporation ("DTCC"). All rights reserved. This work (including, without limitation, all text, images, logos, compilation and design) is proprietary and protected by copyright, and is for the exclusive use of users authorized by DTCC. If this work is received from DTCC in any electronic medium, authorized users of this work are granted a limited, non-exclusive, non-transferable, nonsublicensable and freely revocable license to make reproductions and transmissions necessary for downloading and storage of this work on the users' computers and to print one or more paper copies from the electronic version for their own use. Other than to this limited extent, no part of this work (including any paper copies thereof or print versions thereof) may be printed, copied, altered, modified, posted, reproduced, displayed, published, sold, licensed, used or distributed (including by transmission) in any form or by any means, or stored in any information storage and retrieval system, without DTCC's prior written permission. DTCC is the brand name under which certain affiliates of The Depository Trust & Clearing Corporation provide services in particular geographic areas. The Depository Trust & Clearing Corporation does not provide services to clients. Each of The Depository Trust & Clearing Corporation s affiliates is a legally separate and independent entity, and each is subject to the laws and regulations of the particular country in which it operates. Please see for more information on the legal structure of The Depository Trust & Clearing Corporation and its related entities. All product or service names are the property of their respective owners. Publication Date: May 14, 2018 Publication Code: CP012 Title: MQ Programmer's Guide

3 CONTENTS Contents 3 Preface 4 About This Guide 4 Audience 4 Changes in This Version of the Document 4 Related Documents and Training 4 Questions? 4 1. Message Envelope and XML Processing (ALERT, CTM, and OASYS) 5 Introduction 5 Syntax Formatting Key 5 XML Processing Instructions and Declarations 5 Column Header Key 6 Message Layout 6 A. Example Messages (CTM and OASYS) 9 Introduction 9 Inbound Messages to DTCC 9 Outbound Messages From DTCC 9 B. Error Codes and Resolutions Handling 11 Introduction 11 CMI Errors 11

4 PREFACE About This Guide The common message infrastructure (CMI) allows you to use an XML interface to send different types of trade messages to multiple Omgeo services. This document describes the CMI message envelope layout and elements required on all messages you submit to and receive from DTCC. This document does not describe the message body for XML trade messages. For those message specifications, see the applicable product documentation. Audience This document is for systems analysts, programmers, and others involved in creating and receiving messages that flow between orderers (usually investment managers), executors (broker/dealers), other trade parties, and the CMI service. Changes in This Version of the Document This version includes branding updates only no content changes. Related Documents and Training For related documents and training in the DTCC Learning Center, go to Institutional Trade Processing area and select the service you are using. Questions? The DTCC Client Center provides general assistance and technical help. Visit to: Enter a service request or check the status of an existing service request Search the knowledge base Obtain contact information Preface 4

5 1. MESSAGE ENVELOPE AND XML PROCESSING (ALERT, CTM, AND OASYS) Introduction CMI treats a message as two parts: The CMI message envelope contains XML fields that make up a common wrapper of every CMI message. The second part is the message body. The content of the message body does not depend on the message envelope. In practice, the message body contains complete messages specific to the target service (such as CTM), or contains XML from the common message. Syntax Formatting Key Table 1.1 outlines the syntax and formatting described in the Syntax column of the message envelope layout (Table 1.3). Table 1.1 Syntax Formatting With Examples Use this symbol... Comprised of... To indicate... n Digits Format Element 16n ProcessingSequence c A B C D E F G H I J K L M N O P Q R S T U V W X Y Z !c A B C D E F G H I J K L M N O P Q R S T U V W X Y Z z The ISO /IEC (Latin 1) characters without <cr> or <lf> Value Uppercase alphanumerics Format example 4c Uppercase alphanumerics with exact field length ISO/IEC (Latin 1) character Element Value Format Element Value Format Element Value <ProcessingSequence> </ProcessingSequence> PartyType <PartyType>TFID</PartyType> 4!c PartyRole <PartyRole>EXEC</PartyRole> 40z PartyValue <PartyValue>BBBBGB2L</PartyValue> XML Processing Instructions and Declarations DTCC recommends that the prolog (first line) of each message have the following XML processing instruction: <?xml version= 1.0 encoding= <encoding value>?> Message Envelope and XML Processing (ALERT, CTM, and OASYS) 5

6 Where <encoding value> represents a valid encoding. You can enter any valid encode value as an encoding value; however, the underlying This version includes branding updates only no content changes. service can require specific encoding values. For example, for Omgeo CTM messages use: <?xml version= 1.0 encoding= iso ?> The first line of the OmgeoMessageContainer element must contain the envelope schema. You can declare additional schema file web addresses in the OmgeoMessageContainer element to parse prefixed elements in the message envelope. These additional schemas depend on the underlying service. See Example Messages (CTM and OASYS) on page 9 for an example. Column Header Key Table 1.2 describes the column headings for the message envelope layout shown in the Table 1.3. Table 1.2 Column Header Key for the Message Envelope Column Header Indent XML Element Min. Description The nesting level of the message envelope element. Indent level 1 is the highest level in the hierarchy. Child elements in composites are inset from the left with numbers that indicate nested levels. The name of the element in the message envelope. Minimum number of occurrences of the message envelope element: 0 indicates an optional element. Some optional composites have required child fields. If you use an optional composite on an inbound message to DTCC, ensure that you provide values in its required child fields. 1 indicates a mandatory XML element. Max. Syntax Notes/Enumerated Values Maximum number of occurrences of the message envelope element. Do not expect to receive more than the number of allowed occurrences of the element. An asterisk (*) indicates that no established maximum exists. The size and data type of the message envelope field. A composite element contains one or more other message envelope fields, and has the label Composite in the Syntax column. Composite element rows are shaded in blue. Contains more information about the element. Message Layout Table 1.3 describes the CMI message envelope elements. Composite element rows are shaded in blue. Table 1.3 Message Envelope Elements Ind. XML Element Min. Max. Syntax Notes/Enumerated Values 1 OmgeoMessageContainer 1 1 Composite 2 MessageParties 1 1 Composite 3 SenderParty 1 1 Composite Identifies the sender according to message direction: When inbound to [[[Undefined variable OmgeoVariables.CompanyName]]] identifies the client When outbound to you value is Omgeo 4 PartyRole 1 1 4!c Valid value is MEOR (Message Originator). 4 PartyType 1 1 4c Valid values: TFID Thomson Financial Identifier BIC Bank Identifier Code OTM OASYS-TradeMatch SM. Message Envelope and XML Processing (ALERT, CTM, and OASYS) 6

7 Table 1.3 Message Envelope Elements (continued) Ind. XML Element Min. Max. Syntax Notes/Enumerated Values 4 PartyValue z Valid identifier of the sender according to the PartyType. 3 ReceiverParty 1 1 Composite Identifies the message owner in the OmgeoMessage component field, which occurs later in this message. When inbound to DTCC value is Omgeo. When outbound to you identifies the client. 4 PartyRole 1 1 4!c Valid value is MERE (Message Recipient). 4 PartyType 1 1 4c Valid values: TFID Thomson Financial Identifier BIC Bank Identifier Code OTM OASYS-TradeMatch 4 PartyValue z Valid identifier of the recipient according to the PartyType. 3 DataOwnerParty 1 1 Composite Identifies the owner of the message in the OmgeoMessage component. 4 PartyRole 1 1 4!c Valid values: 4 PartyType 1 1 4c Valid values: INST Instructing Party EXEC Executing Broker UNKN Unknown TFID Thomson Financial Identifier BIC Bank Identifier Code OTM OASYS-TradeMatch 4 PartyValue z The client identification number based on the selected PartyType value. 2 ClientIdentifier z Your client user identifier or other identifier. 2 ClientMessageReference z Your message identifier. This reference is not returned on the outbound response message. 2 QualityOfService 0 1 Composite This group provides additional values to support reliable, concurrent, and ordered message transmission when connecting to your Omgeo CTM service. 3 TransportMessageId z A unique identifier on the envelope or communications layer of a message, which uniquely identifies each message and enables tracking, rollback, and so on. 3 ProcessingHash z Identifies the queue which processes your inbound message to DTCC. For the Omgeo CTM service only. Valid values: Query messages=0 Trade messages= ProcessingSequence n A unique identifier that tracks the processing order of all XML message types and correlating response message from DTCC. 3 Duplicate 0 1 5z Indicates whether an XML message was resent. Valid values: True XML message is a duplicate. False XML message is not a duplicate. 2 Errors 0 1 Composite The group of one or more possible MQ errors that appear on outbound messages only. 3 Error 1 * Composite An individual error appearing on an outbound message to you. Message Envelope and XML Processing (ALERT, CTM, and OASYS) 7

8 Table 1.3 Message Envelope Elements (continued) Ind. XML Element Min. Max. Syntax Notes/Enumerated Values 4 ErrorId n Identifies the error number. This field begins at 1 and increments for each error in the list. 4 ErrorSeverity 1 1 7c Valid values: INFO WARNING FATAL 4 ErrorCode 1 1 8c Identifies the specific error code. 4 ErrorParameter 0 * z The field with an incorrect value prompting an error. 2 OmgeoService 1 1 Composite The parameters that define the DTCC service. 3 Route 1 1 Composite Indicates the target service and service version. 4 Service 1 1 6c Valid values: 4 ServiceVersion 1 1 8z Valid values: ALERT (requires 1.0 or 5.0 as ServiceVersion value) CTM (requires 1.3 as ServiceVersion value) OASYS (requires 7.0 as ServicedVersion value) For ALERT, supply (requires ALERT as Service value): o o 1.0 for GCD 5.0 for API 4 ServiceInfo z Reserved for future use. For CTM, supply 1.3 (requires CTM as Service value) For OASYS, supply 7.0 (requires OASYS as Service value) 3 OmgeoMessage 1 1 ##any This field contains the service-specific message. NA ContentType 1 1 8c Valid values: XML SWIFT (reserved for future use) CSV (reserved for future use) FIX (reserved for future use) RAW (reserved for future use) The indent on this field is NA (not applicable) because ContentType occurs at the end of the preceding OmgeoMessage field. Message Envelope and XML Processing (ALERT, CTM, and OASYS) 8

9 A. EXAMPLE MESSAGES (CTM AND OASYS) Introduction This section contains examples of message envelopes. Inbound Messages to DTCC Figure A.1 shows a message envelope example inbound to DTCC, with OASYS as the underlying service. The example displays a portion of the message body as indicated. Figure A.1 Inbound Message Envelope and Message Body Outbound Messages From DTCC Figure A.2 shows a message envelope example outbound from the CTM service to you. This example displays envelope-specific tags, with a portion of the message body as indicated. Example Messages (CTM and OASYS) 9

10 Figure A.2 Outbound Message Envelope and Message Body Example Messages (CTM and OASYS) 10

11 B. ERROR CODES AND RESOLUTIONS HANDLING Introduction This chapter describes how DTCC handles errors. CMI Errors Table B.1 describes CMI CTM and OASYS service error codes and provides error examples with resolutions. Table B.1 CMI Errors and Resolutions Error Code E2951 E4240 E4362 Error Description Error Example Example Resolution Invalid XML encoding value (envelope line 1) Invalid application and version in input XML message User not authorized to route messages to the service <Errors> <Error> <ErrorId>1</ErrorId> <ErrorSeverity>FATAL </ErrorSeverity> <ErrorCode>E2951</ErrorCode> <ErrorText>Invalid XML Encoding value %1.</ErrorText> <ErrorParameter>utf-8</ErrorParameter> </Error> </Errors> Errors> <Error> <ErrorId>1</ErrorId> <ErrorSeverity>FATAL</ErrorSeverity> <ErrorCode>E4240</ErrorCode> <ErrorText>Invalid Application and Version %1 in input XML message</errortext> <ErrorParameter>OASYS_1.3</ErrorParameter> </Error> </Errors> <Errors> <Error> <ErrorId>1</ErrorId> <ErrorSeverity>FATAL </ErrorSeverity> <ErrorCode>E4362</ErrorCode> <ErrorText>User %1 NOT authorized for the service %2</ErrorText> <ErrorParameter>machj01,SYSTEM_1.0 </ErrorParameter> </Error> </Errors> Correct the encoding value on line 1 of the message envelope (utf-8 is valid). Then, resend the message. Correct the envelope Service element and ServiceVersion element value combination. Then, resend the message. Contact the Client Center to verify subscription and role combination for your organization. Error Codes and Resolutions Handling 11

12 Table B.1 CMI Errors and Resolutions (continued) Error Code E5004 E5025 Error Description Error Example Example Resolution Invalid character in the message Value exceeds max length for field <Errors> <Error> <ErrorId>1</ErrorId> <ErrorSeverity>FATAL </ErrorSeverity> <ErrorCode>E5004</ErrorCode> <ErrorText>XML Parser error at %1. An invalid XML character (Unicode: 0x49) was found in the prolog of the document.</errortext> <ErrorParameter>XMLNSC</ErrorParameter> </Error> </Errors> <Errors> <Error> <ErrorId>1 </ErrorId> <ErrorSeverity>FATAL</ErrorSeverity> <ErrorCode>E5025</ErrorCode> <ErrorText>Schema validation error at %1, The length of value "XXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \XXXXXXXXXXXXX" is "1999" which is not valid with respect to maxlength facet with value"32".</errortext> <ErrorParameter>ClientMessageRef</ErrorParameter> </Error> </Errors> Correct the payload in the message and resend. Correct the envelope element that exceeds the maximum length. Then, resend the message. Error Codes and Resolutions Handling 12

13 FOR MORE INFORMATION DTCC Learning at: or visit us on the web at: