Solace function reference
.solace Solace interface
Event notifications setSessionCallback Set a callback function for session events setFlowCallback Set a callback function for flow events
Connect-disconnect init Connect to and create a session destroy Destroy a previously created session
Endpoint management createEndpoint Create an endpoint from a session destroyEndpoint Destroy an endpoint from a session endpointTopicSubscribe Add a topic subscription to an existing endpoint endpointTopicUnsubscribe Unsubscribe from a topic on an endpoint
Direct messaging sendDirect Send a direct message sendDirectRequest Send a direct message requiring a sync response
Topic subscription setTopicMsgCallback Set callback for messages from topic subscriptions (provides binary payload) setTopicRawMsgCallback Set callback for messages from topic subscriptions (provides original msg) subscribeTopic Subscribe to a topic unSubscribeTopic Unsubscribe from a topic
Guaranteed/persistent messaging sendPersistent Send a persistent message onto a queue or topic sendPersistentRequest Send a guaranteed message for a synchronous reply
Flow bindings setQueueMsgCallback Set callback for when message sent to an endpoint (provides binary payload) setQueueRawMsgCallback Set callback for when message sent to an endpoint (provides original msg) bindQueue Bind to a queue sendAck Acknowledge processing of a message unBindQueue Remove subscription/binding created with bindQueue
Message functions .solace.getPayloadAsXML Get the XML part of the Solace message .solace.getPayloadAsString Get the string part of the Solace message .solace.getPayloadAsBinary Get the binary part of the Solace message
Utility functions .solace.getCapability Value of the specified capability for the session .solace.version Current version of the build/deployment
Endpoint-management functions may be used to create or destroy endpoints from the kdb+ session. In some deployments, endpoints may already be created for you by an admin.
Endpoint management must be enabled for the user in order to use this functionality.
.solace.bindQueue
Bind to a queue
Syntax: .solace.bindQueue[bindProps]
Where bindProps
is a symbol-to-symbol dictionary mapping the Solace bind properties to their values.
.solace.createEndpoint
Provision an endpoint on the appliance from a session
Syntax: .solace.createEndpoint[options;provFlags]
Where
options
is a symbol-to-symbol dictionary mapping Solace endpoint properties to their values.provFlags
is an integer indicating the provision flag used by Solace
.solace.destroy
Destroy a previously created session
Syntax: .solace.destroy[]
.solace.destroyEndpoint
Destroys an endpoint from a session
Syntax: .solace.destroyEndpoint[options;provFlags]
Where
options
is a symbol-to-symbol dictionary mapping Solace endpoint properties to their valuesprovFlags
is an integer indicating the provision flag used by Solace
.solace.endpointTopicSubscribe
Add a topic subscription to an existing endpoint
Syntax: .solace.endpointTopicSubscribe[options;provFlags;topic]
Where
options
is a symbol-to-symbol dictionary mapping Solace endpoint properties to their valuesprovFlags
is an integer indicating the provision flag used by Solacetopic
is a symbol or string denoting a topic subscription
Topic subscriptions can be added to queues or remote clients.
.solace.endpointTopicUnsubscribe
Unsubscribe from a topic on an endpoint
Syntax: .solace.endpointTopicUnsubscribe[options;provFlags;topic]
Where
options
is a symbol-to-symbol dictionary mapping Solace endpoint properties to their valuesprovFlags
is an integer indicating the provision flag used by Solacetopic
is a symbol or string denoting a topic subscription
Unsubscriptions from topics may be from either queues or remote clients.
.solace.getCapability
Retrieve the value of the specified capability for the session
Syntax: .solace.getCapability[capabilityName]
Where capabilityName
is a symbol or string denoting a capability returns the capability value for the session.
The returned value type will vary depending on the capability requested.
.solace.init
Connect to and create a session
Syntax: .solace.init[options]
Where options
is a symbol-to-symbol dictionary mapping Solace properties to their values.
Common properties are SESSION_HOST
, SESSION_VPN_NAME
, SESSION_USERNAME
, SESSION_PASSWORD
, and SESSION_RECONNECT_RETRIES
.
You must be connected before running any subsequent Solace functions.
.solace.sendAck
Acknowledge processing of a message
Syntax: .solace.sendAck[endpointname;msgid]
Where
endpointname
is a string denoting the name of an endpointmsgid
is a long denoting the ID of a message
This function allows you to acknowledge messages. It should be called by the subscriptions callbackFunction
to acknowledge that the message has been processed, in order to prevent the message from being consumed on a subsequent subscription.
This is only required when you wish to take control and run with auto acks off (e.g. FLOW_ACKMODE
disabled in the flow binding).
.solace.sendDirect
Send a direct message
Syntax: .solace.sendDirect[topic;data]
Where
topic
is a string denoting the topic to which the message is sentdata
is the message payload as either a string, symbol or byte array
Each message will automatically be populated with message-eliding eligibility enabled and dead message queue (DMQ) eligibility enabled.
.solace.sendDirectRequest
Send a direct message which requires a sync reply
Syntax: .solace.sendDirectRequest[topic;data;timeout;replyType;replyDest]
Where
topic
is a string denoting the topic to which a message is sentdata
is the message payload as either a string, symbol or byte arraytimeout
is an integer indicating the milliseconds to block/wait (must be greater than zero).replyType
is an integer (see below)replyDest
is a symbol denoting the topic/queue that you wish a reply to this message to go to (empty for default session topic).
returns a byte array containing the payload on successful execution; else an integer return code. For example, if the result is 7, the reply wasn’t received.
replyType:
-1 null
0 topic
1 queue
2 temp topic
3 temp queue
.solace.sendPersistent
Send a persistent message onto a queue or topic
Syntax: .solace.sendPersistent[destType;dest;data;correlationId]
Where
destType
is an integer indicating the type of destination (see below)dest
is a symbol denoting the name of the queue/topic destinationdata
is a string/symbol/byte data which forms the message payloadcorrelationId
is an optional parameter with default behavior accessed with null. Otherwise this is a symbol denoting e.g. a Correlation ID is carried in the Solace message headers unmodified which may be used for peer-to-peer message synchronization
destType:
-1 null
0 topic
1 queue
2 temp topic
3 temp queue
.solace.sendPersistentRequest
Send a guaranteed message requiring a synchronous reply
Syntax: .solace.sendPersistentRequest[destType;dest;data;timeout;replyType;replydest]
Where
destType
is an integer denoting the type of destinationdest
is a symbol denoting the name of the queue/topic destinationdata
is a string/symbol/byte data which forms the message payloadtimeout
is an integer indicating the milliseconds to block/wait (must be greater than zero).replyType
is an integer representing the reply destination typereplyDest
is a symbol denoting the topic/queue that you wish a reply to this message to go to (empty for default session topic).
returns a byte array containing the payload on successful execution; else an integer return code. For example, if the result is 7, the reply was not received.
destType: replyType:
-1 null -1 null
0 topic 0 topic
1 queue 1 queue
2 temp topic 2 temp topic
3 temp queue 3 temp queue
.solace.setFlowCallback
Associate the provided function with flow events
Syntax: .solace.setFlowCallback[callbackFunction]
Where callbackFunction
is a symbol named for a function within your q session which takes five arguments:
eventType
is an integer denoting the type of eventresponseCode
is an integer denoting the response code returned for some events, otherwise zero.eventInfo
is a string providing further information about the eventdestType
is an integer denoting the type of the destination.destName
is the destination name as a string
.solace.setQueueMsgCallback
Set a callback function for when a message is sent to an endpoint
Syntax: .solace.setQueueMsgCallback[callbackFunction]
Where callbackFunction
is a q function taking three arguments:
destination
is a symbol denoting the flow destination (queue from which the subscription originated)payload
is a byte array containing the message payloadmsg values
is a dictionary specifying message information as follows:
destType type of destination (integer) destName destination name (string) replyType reply destination type (integer) replyDest topic/queue to reply to (string) correlationId original message’s correlation ID (string) msgId used for sending acks (long)
Values for destType
and replyType
.solace.setQueueRawMsgCallback
Set a callback function for when a message is sent to an endpoint. This is an alternative to .solace.setQueueMsgCallback
.
Syntax: .solace.setQueueRawMsgCallback[callbackFunction]
Where callbackFunction
is a q function taking three arguments:
destination
is a symbol denoting the flow destination (queue from which the subscription originated)msg
as a long pointing to the underlying solace msg (can be used within the callback with the functions to get the payload based on the senders type e.g.getPayloadAsXML
,getPayloadAsString
, etc).msg values
is a dictionary specifying message information as follows:
destType type of destination (integer) destName destination name (string) replyType reply destination type (integer) replyDest topic/queue to reply to (string) correlationId original message’s correlation ID (string) msgId used for sending acks (long)
Values for destType
and replyType
.solace.setSessionCallback
Associate the provided function with session events such as connection notifications or session errors
Syntax: .solace.setSessionCallback[callbackFunction]
Where callbackFunction
is a symbol denoting a function within your q session which takes three arguments:
eventType
is an integer denoting the type of eventresponseCode
is an integer denoting the response code that is returned for some event, otherwise zeroeventInfo
is a string providing further information about the event
.solace.setTopicMsgCallback
Set callback for messages received from topic subscriptions
Syntax: .solace.setTopicMsgCallback[callbackFunction]
Where callbackFunction
is a function taking three arguments:
destination
as a symbolpayload
as a byte array containing the message binary payloadmsg values
as a dictionary: see below
isRedeliv whether redelivered (boolean)
isDiscard whether messages have been discarded prior to the current message (boolean)
(Indicates congestion discards only; not affected by message eliding.)
isRequest whether client expects a reply (boolean)
(In this case the function should return a byte array.)
sendTime client’s send time, if populated (timestamp)
registers a q function to be called on receipt of messages from topic subscriptions. If the msg values
contains a value of 1b
for the key isRequest
, the function should return with the response message contents (type byte list) as this indicate the sender requests a reply.
.solace.setTopicRawMsgCallback
Set callback for messages received from topic subscriptions. This is an alternative to .solace.setTopicMsgCallback
.
Syntax: .solace.setTopicRawMsgCallback[callbackFunction]
Where callbackFunction
is a function taking three arguments:
destination
as a symbolmsg
as a long pointing to the underlying solace msg (can be used within the callback with the functions to get the payload based on the senders type e.g.getPayloadAsXML
,getPayloadAsString
, etc).msg values
as a dictionary: see below
isRedeliv whether redelivered (boolean)
isDiscard whether messages have been discarded prior to the current message (boolean)
(Indicates congestion discards only; not affected by message eliding.)
isRequest whether client expects a reply (boolean)
(In this case the function should return a byte array.)
sendTime client’s send time, if populated (timestamp)
registers a q function to be called on receipt of messages from topic subscriptions. If the msg values
contains a value of 1b
for the key isRequest
, the function should return with the response message contents (type byte list) as this indicate the sender requests a reply.
.solace.subscribeTopic
Subscribe to a topic
Syntax: .solace.subscribeTopic[topic;isBlocking]
Where
topic
is a string denoting the topic to subscribe toisBlocking
is a boolean indicating if the subscription is blocking
Solace format wildcards (*, >)
can be used in the topic subscription value.
If isBlocking
is true then block until confirm or true to get session event callback on sub activation.
.solace.unBindQueue
Remove a subscription/binding created via .solace.bindQueue
Syntax: .solace.unBindQueue[endpointname]
Where endpointname
is is a string denoting the name of an endpoint
q).solace.unBindQueue["endpoint1"]
.solace.unSubscribeTopic
Unsubscribe from an existing topic subscription
Syntax: .solace.unSubscribeTopic[topic]
Where topic
is a string denoting the topic to unsubscribe from.
q).solace.unSubscribeTopic["topic1"]
.solace.version
Current version of the build/deployment
Syntax: .solace.version[]
Returns Solace API version info as a dictionary.
.solace.getPayloadAsXML
Get XML part of a Solace msg
Syntax: .solace.getPayloadAsXML[msg]
Where msg
is a msg provided in the callback function registered with setQueueRawMsgCallback
or setTopicRawMsgCallback
. This corresponds to the Solace sender setting the payload using the solace function to set the payload as XML (there is no conversion to XML by this API).
Returns byte array (or long representing the solace error code if the payload wasnt an XML solace type)
`.solace.getPayloadAsString
Get string part of a Solace msg
Syntax: .solace.getPayloadAsString[msg]
Where msg
is a msg provided in the callback function registered with setQueueRawMsgCallback
or setTopicRawMsgCallback
. This corresponds to the Solace sender setting the payload using the solace function to set the payload as string (there is no conversion to string by this API).
Returns char array (or long representing the solace error code if the payload wasnt an string solace type)
`.solace.getPayloadAsBinary
Get binary part of a Solace msg
Syntax: .solace.getPayloadAsBinary[msg]
Where msg
is a msg provided in the callback function registered with setQueueRawMsgCallback
or setTopicRawMsgCallback
.
Returns char array (or long representing the solace error code if the payload could be retrieved as binary). This API defaults to sending msgs as binary (of which string/xml/etc can be used).