%Net.abstractMQ

abstract class %Net.abstractMQ extends %Library.RegisteredObject

For information on using the API provided by this class, see Using MQ.

Usage

An MQ object is created when an instance of an MQ class is created via %New. Following creation, the class can be assigned an error log file, and connected to an MQ Server.

The %Init() method is a simple way to perform both these functions.

For advanced applications, these steps can be performed via separate method calls.

To establish an error log file for the class, call %ErrLog().

A connection is established by calling the %Connect() method. The connection is maintained until you deallocate the instance. The instance must be successfully connected before it can be used for message queuing.

Use MQSend.%Put() to send messages to a queue.  Use MQRecv.%Get() to read messages from a queue.

All methods return 1 for success, 0 for failure. In case of a failure, the actual MQ error code is available via the method %GetLastError().

Charcter Set Translation

%CharSet(.ccs) Retrieves the Coded Character Set identifier. This value may be altered by the message system after an unsuccessful attempt to convert data in MQGet.

%SetCharSet(id) Sets the Coded Character Set identifier. Incoming messages will be converted to this character set. Outgoing message's character set encoding is identified to the message queue with this value.

For output (MQSend.%Put()), the Coded Character Set Id describes to the system the char set used for the message. If not set, the MQ system assumes the default character set for the MQ client.

For input (MQRecv.%Get()), the Coded Character Set Id indicates to the MQ client how the message should be converted. The conversion is done automatically during message reciept on the client.

Thus one may send messages in any encoding (notifying the system what the encoding used is), and receive messages converting from one encoding to another.

Example:

To convert a message encoded in EBCDIC (Character Coded Set Id 1047, indicating IBM-1047 coding), a user on a Windows system may wish to convert using code 437 (the default on Windows systems). Then the following will convert the EBCDIC message to ascii on the windows system:

Do mq.%SetCharSet(437) ;437 English ascii code on Windows

Do mq.%Get(.msg) ;converts the message to 437 code

MQ Documentation

Consult the IBM WebSphere MQ website for further documentation.
 
 

Property Inventory

• ApplIdentityData
• Channel
• CharSetId
• Connection
• Context
• CorrelationId
• MessageId
• Password
• PutApplType
• QMBehavior
• QMgr
• QName
• ReplyQMgrName
• ReplyQName
• SSLCipherSpec
• Syncpoint
• Transport
• Username

Method Inventory

• %ApplIdentityData()
• %Backout()
• %CharSet()
• %Commit()
• %Connect()
• %CorId()
• %ErrLog()
• %GetLastError()
• %Init()
• %MsgId()
• %PutApplType()
• %ReplyQMgrName()
• %ReplyQName()
• %SetCharSet()
• %Syncpoint()

Parameters

parameter ApplIdentityData = 5;

parameter CorrelationId = 2;

parameter MessageId = 1;

parameter ReplyQMgrName = 3;

parameter ReplyQName = 4;

Properties

property ApplIdentityData as %String;

Message Descriptor Options: Application Identity

Property methods: ApplIdentityDataDisplayToLogical(), ApplIdentityDataGet(), ApplIdentityDataIsValid(), ApplIdentityDataLogicalToDisplay(), ApplIdentityDataLogicalToOdbc(), ApplIdentityDataNormalize(), ApplIdentityDataSet()

property Channel as %String;

Channel Definition Options: Channel Name

Property methods: ChannelDisplayToLogical(), ChannelGet(), ChannelIsValid(), ChannelLogicalToDisplay(), ChannelLogicalToOdbc(), ChannelNormalize(), ChannelSet()

property CharSetId as %Integer;

Message Descriptor Options: Character Set Identifier

Property methods: CharSetIdDisplayToLogical(), CharSetIdGet(), CharSetIdIsValid(), CharSetIdLogicalToDisplay(), CharSetIdNormalize(), CharSetIdSet()

property Connection as %String;

Channel Definition Options: Connection name

Property methods: ConnectionDisplayToLogical(), ConnectionGet(), ConnectionIsValid(), ConnectionLogicalToDisplay(), ConnectionLogicalToOdbc(), ConnectionNormalize(), ConnectionSet()

property Context as %Integer [ InitialExpression = 0 ];

Flag indicating use of message context 0 - DEFAULT, 1 - IDENTITY, 2 - ALL

Property methods: ContextDisplayToLogical(), ContextGet(), ContextIsValid(), ContextLogicalToDisplay(), ContextNormalize(), ContextSet()

property CorrelationId as %String;

Message Descriptor Options: Correlation Id

Property methods: CorrelationIdDisplayToLogical(), CorrelationIdGet(), CorrelationIdIsValid(), CorrelationIdLogicalToDisplay(), CorrelationIdLogicalToOdbc(), CorrelationIdNormalize(), CorrelationIdSet()

property MessageId as %String;

Message Descriptor Options: Message Id

Property methods: MessageIdDisplayToLogical(), MessageIdGet(), MessageIdIsValid(), MessageIdLogicalToDisplay(), MessageIdLogicalToOdbc(), MessageIdNormalize(), MessageIdSet()

property Password as %String;

Channel Definition Options: Password (if any)

Property methods: PasswordDisplayToLogical(), PasswordGet(), PasswordIsValid(), PasswordLogicalToDisplay(), PasswordLogicalToOdbc(), PasswordNormalize(), PasswordSet()

property PutApplType as %Integer;

Message Descriptor Options: Put application type

Property methods: PutApplTypeDisplayToLogical(), PutApplTypeGet(), PutApplTypeIsValid(), PutApplTypeLogicalToDisplay(), PutApplTypeNormalize(), PutApplTypeSet()

property QMBehavior as %Integer [ InitialExpression = 0 ];

Flag indicating Queue Manager behavior 0 - commit on disconnect (DEFAULT), 1 - backout on disconnect

Property methods: QMBehaviorDisplayToLogical(), QMBehaviorGet(), QMBehaviorIsValid(), QMBehaviorLogicalToDisplay(), QMBehaviorNormalize(), QMBehaviorSet()

property QMgr as %String;

Queue Manager name

Property methods: QMgrDisplayToLogical(), QMgrGet(), QMgrIsValid(), QMgrLogicalToDisplay(), QMgrLogicalToOdbc(), QMgrNormalize(), QMgrSet()

property QName as %String;

Queue name

Property methods: QNameDisplayToLogical(), QNameGet(), QNameIsValid(), QNameLogicalToDisplay(), QNameLogicalToOdbc(), QNameNormalize(), QNameSet()

property ReplyQMgrName as %String;

Message Descriptor Options: Reply Q Manager name

Property methods: ReplyQMgrNameDisplayToLogical(), ReplyQMgrNameGet(), ReplyQMgrNameIsValid(), ReplyQMgrNameLogicalToDisplay(), ReplyQMgrNameLogicalToOdbc(), ReplyQMgrNameNormalize(), ReplyQMgrNameSet()

property ReplyQName as %String;

Message Descriptor Options: Reply Q name

Property methods: ReplyQNameDisplayToLogical(), ReplyQNameGet(), ReplyQNameIsValid(), ReplyQNameLogicalToDisplay(), ReplyQNameLogicalToOdbc(), ReplyQNameNormalize(), ReplyQNameSet()

property SSLCipherSpec as %String;

Channel Definition Options: SSL Cipher Spec

Property methods: SSLCipherSpecDisplayToLogical(), SSLCipherSpecGet(), SSLCipherSpecIsValid(), SSLCipherSpecLogicalToDisplay(), SSLCipherSpecLogicalToOdbc(), SSLCipherSpecNormalize(), SSLCipherSpecSet()

property Syncpoint as %Boolean [ InitialExpression = 0 ];

Flag indicating use of SYNCPOINT

Property methods: SyncpointDisplayToLogical(), SyncpointGet(), SyncpointIsValid(), SyncpointLogicalToDisplay(), SyncpointNormalize(), SyncpointSet()

property Transport as %String;

Channel Definition Options: Transport type

Property methods: TransportDisplayToLogical(), TransportGet(), TransportIsValid(), TransportLogicalToDisplay(), TransportLogicalToOdbc(), TransportNormalize(), TransportSet()

property Username as %String;

Channel Definition Options: Username (if any)

Property methods: UsernameDisplayToLogical(), UsernameGet(), UsernameIsValid(), UsernameLogicalToDisplay(), UsernameLogicalToOdbc(), UsernameNormalize(), UsernameSet()

Methods

method %ApplIdentityData(ByRef Value As %String) as %Boolean

The %ApplIdentityData method returns the Application Identity Data for the last message read. 

method %Backout() as %Boolean

%Backout backs out changes to the queue. Used in conjunction with the syncpoint option. If the syncpoint option is set, then when sending, no messages are visible on the queue until commit. If backout is called, all the messages sent since the last commit are removed from the queue. When receiving, the messages are not removed from the queue until commit is issued. If backout is called, the messages are restored to the queue and available to users.

%Backout returns 0 on failure, 1 on success.

method %CharSet(ByRef Value As %Integer) as %Boolean

The %CharSet method returns the current value of the Coded Character Set Id used for message conversion.  The CCSId may also be set to the message's Character Set if conversion was not possible.

method %Commit() as %Boolean

%Commit commits changes to the queue. Used in conjunction with the syncpoint option. If the syncpoint option is set, then when sending, no messages are visible on the queue until commit. When receiving, the messages are not removed from the queue until commit is issued.

%Commit returns 0 on failure, 1 on success.

method %Connect() as %Boolean

%Connect creates a connection to a queue manager and opens the queue object.  A connection and open MQ object (queue, topic, subscription) is required before messages can be sent or received. 

User must first set the standard MQSeries initialization arguments

QName: Host Queue Name (Required)

QMgr: Host Queue Manager name. Passing "" connects to the default queue manager. (Optional)

Channel: Host Channel name (Optional)

Transport: Transport type (TCP, LU62, NETBIOS, SPX) (Optional)

Connection: Connection spec, e.g., "127.0.0.1(1401)" (Optional)

See IBM MQ documentation on establishing defaults, and MQ authentication.

method %CorId(ByRef Value As %String) as %Boolean

The %CorId method returns the Correlation Id for the last message read. 

method %ErrLog(log As %String) as %Boolean

The %ErrLog method creates an error log to be used for errors on this object. 

method %GetLastError() as %Integer

%GetLastError returns the last error or reason code returned from MQ.

method %Init(QName As %String, QMgr As %String, QChannel As %String, ErrorFile As %String = "") as %Boolean

%Init creates a connection to a queue.  A connection is required before messages can be sent or received.  Use the following standard MQSeries initialization arguments:

QName: Host Queue name (Required)

QMgr: Host Queue Manager name. Passing "" connects to the default queue manager. (Optional)

QChannel: Host Channel specification, in form <channel>/TCP/<hostname>(<port>) If not set, MQ connects to the default Channel. (Optional)

ErrorFile: For logging, specify a file name to store MQ system returned messages. (Optional)

%Init returns 0 on failure, 1 on success.

method %MsgId(ByRef Value As %String) as %Boolean

The %MsgId method returns the Message Id for the last message read. 

method %PutApplType(ByRef Value As %Integer) as %Boolean

The %PutApplType method returns the Put Application Type for the last message read. 

method %ReplyQMgrName(ByRef Value As %String) as %Boolean

The %ReplyQMgrName method returns the Reply Queue Manager Name for the last message read. 

method %ReplyQName(ByRef Value As %String) as %Boolean

The %ReplyQName method returns the Reply Queue Name for the last message read. 

method %SetCharSet(Value As %Integer) as %Boolean

The %SetCharSet method sets the Coded Character Set Id to be used for message conversion. 

method %Syncpoint(ByRef Value As %Integer) as %Boolean

The %Syncpoint method returns the current syncpoint status for the connection.