Solace function reference

KxSystems/solace

.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 values
• provFlags 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 values
• provFlags is an integer indicating the provision flag used by Solace
• topic 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 values
• provFlags is an integer indicating the provision flag used by Solace
• topic 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 endpoint
• msgid 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 sent
• data is the message payload as either a string, symbol or byte array

Solace direct messages

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 sent
• data is the message payload as either a string, symbol or byte array
• timeout 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 destination
• data is a string/symbol/byte data which forms the message payload
• correlationId 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 destination
• dest is a symbol denoting the name of the queue/topic destination
• data is a string/symbol/byte data which forms the message payload
• timeout is an integer indicating the milliseconds to block/wait (must be greater than zero).
• replyType is an integer representing the reply destination type
• 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 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:

1. eventType is an integer denoting the type of event
2. responseCode is an integer denoting the response code returned for some events, otherwise zero.
3. eventInfo is a string providing further information about the event
4. destType is an integer denoting the type of the destination.
5. 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:

1. destination is a symbol denoting the flow destination (queue from which the subscription originated)
2. payload is a byte array containing the message payload
3. 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.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:

1. destination is a symbol denoting the flow destination (queue from which the subscription originated)
2. 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).
3. 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:

1. eventType is an integer denoting the type of event
2. responseCode is an integer denoting the response code that is returned for some event, otherwise zero
3. eventInfo 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:

1. destination as a symbol
2. payload as a byte array containing the message binary payload
3. 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.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:

1. destination as a symbol
2. 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).
3. 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 to
• isBlocking 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).