Skip to content

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 setTopicRawMsgCallback Set callback for messages from topic subscriptions 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 setQueueRawMsgCallback Set callback for when message sent to an endpoint bindQueue Bind to a queue sendAck Acknowledge processing of a message unBindQueue Remove subscription/binding created with bindQueue

Message functions getPayloadAsXML Get the XML part of the Solace message getPayloadAsString Get the string part of the Solace message getPayloadAsBinary Get the binary part of the Solace message

Utility functions getCapability Value of the specified capability for the session 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

Destination types

-1  null
0   topic
1   queue
2   temp topic
3   temp queue

.solace.bindQueue

Bind to a queue

.solace.bindQueue bindProps

Where bindProps is a symbol-to-symbol dictionary mapping the Solace bind properties to their values.

.solace.createEndpoint

.solace.createEndpoint[options;provFlags]

Create an endpoint

Where

provisions an endpoint on the appliance from the session.

.solace.destroy

Destroy a session

.solace.destroy[]
Destroys the current session.

.solace.destroyEndpoint

Destroy an endpoint

.solace.destroyEndpoint[options;provFlags]

Where

destroys an endpoint from the session.

.solace.endpointTopicSubscribe

Add a topic subscription to an existing endpoint

.solace.endpointTopicSubscribe[options;provFlags;topic]

Where

  • options is a symbol-to-symbol dictionary mapping Solace endpoint properties to their values
  • provFlags is the provision flag used by Solace (integer)
  • topic is a topic subscription (symbol or string)

Topic subscriptions can be added to queues or remote clients.

.solace.endpointTopicUnsubscribe

Unsubscribe from a topic on an endpoint

.solace.endpointTopicUnsubscribe[options;provFlags;topic]

Where

  • options is a symbol-to-symbol dictionary mapping Solace endpoint properties to their values
  • provFlags is the provision flag used by Solace (integer)
  • topic is a topic subscription (symbol or string)

Unsubscriptions from topics may be from either queues or remote clients.

.solace.getCapability

Retrieve the value of the specified capability for the session

.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.getPayloadAsBinary

Get binary part of a Solace msg

.solace.getPayloadAsBinary msg

Where msg is a message provided in the callback function registered with setQueueRawMsgCallback or setTopicRawMsgCallback, returns either

  • a string
  • a long representing the Solace error code if the payload could be retrieved as binary

This API defaults to sending messages as binary (of which string/XML/etc can be used.)

.solace.getPayloadAsString

Get string part of a Solace msg

.solace.getPayloadAsString msg

Where msg is a message provided in the callback function registered with setQueueRawMsgCallback or setTopicRawMsgCallback, returns either

  • a string
  • a long representing the Solace error code if the payload was not a string Solace type

This corresponds to the Solace sender setting the payload using the Solace function to set the payload as a string. (There is no conversion to string by this API.)

.solace.getPayloadAsXML

Get XML part of a Solace msg

.solace.getPayloadAsXML msg

Where msg is a message provided in the callback function registered with setQueueRawMsgCallback or setTopicRawMsgCallback, returns either

  • a byte vector
  • a long representing the Solace error code if the payload was not an XML Ssolace type

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.)

.solace.init

Connect to and create a session

.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, SESSION_RECONNECT_RETRIES and SESSION_SSL_TRUST_STORE_DIR.

You must be connected before running any subsequent Solace functions.

.solace.sendAck

Acknowledge processing of a message

.solace.sendAck[endpointname;msgid]

Where

  • endpointname is the name of an endpoint (string)
  • msgid is the ID of a message (long)

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

.solace.sendDirect[topic;data]

Where

  • topic is the topic to which the message is sent (string)
  • data is the message payload (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

.solace.sendDirectRequest[topic;data;timeout;replyType;replyDest]

Where

argument type value
topic string topic to which message is sent
data string, symbol, or byte vector message payload
timeout integer milliseconds to block/wait (> zero)
replyType integer reply destination type
replyDest symbol topic or queue a reply to this message goes to
(empty for default session topic)

returns either

  • the payload (byte array)
  • an integer error code (integer)

For example, if the result is 7, the reply wasn’t received.

.solace.sendPersistent

Send a persistent message onto a queue or topic

.solace.sendPersistent[destType;dest;data;correlationId]

Where

argument type value
destType integer destination type
dest symbol destination queue or topic
data char/symbol/byte vector message payload
correlationId symbol a Correlation ID to be carried in the Solace message headers unmodified – may be used for peer-to-peer message synchronization; null for default behavior

.solace.sendPersistentRequest

Send a guaranteed message requiring a synchronous reply

.solace.sendPersistentRequest[destType;dest;data;timeout;replyType;replydest]

Where

argument type value
destType integer destination type
dest symbol destination queue or topic
data char/symbol/byte vector message payload
timeout integer milliseconds to block/wait (> zero)
replyType integer reply destination type
replyDest symbol topic/queue a reply to this message goes to
(empty for default session topic)

returns either

  • the payload (byte array)
  • an error code (integer)

For example, if the result is 7, the reply was not received.

.solace.setFlowCallback

Associate the provided function with flow events

.solace.setFlowCallback callbackFunction

Where callbackFunction is a symbol denoting a function in your q session with arguments:

  1. type of event (integer)
  2. response code returned for some events, otherwise zero (integer)
  3. further information about the event (string)
  4. destination type (integer)
  5. destination name (string)

.solace.setQueueMsgCallback

Set a callback function for when a message is sent to an endpoint

.solace.setQueueMsgCallback callbackFunction

Where callbackFunction is a q function with arguments:

  1. flow destination: the queue from which the subscription originated (symbol)
  2. message payload (byte vector)
  3. a dictionary:

    key type value
    destType integer destination type
    destName string destination name
    replyType integer reply destination type
    replyDest string topic/queue to reply to
    correlationId string original message’s correlation ID
    msgId long used for sending acks

.solace.setQueueRawMsgCallback

Set a callback function for when a message is sent to an endpoint

.solace.setQueueRawMsgCallback callbackFunction

Where callbackFunction is a q function with arguments:

  1. flow destination: the queue from which the subscription originated (symbol)
  2. a pointer (long) to the underlying Solace message (can be used within the callback with the functions to get the payload based on the sender’s type e.g. getPayloadAsXML, getPayloadAsString, etc.)
  3. a dictionary:

    key type value
    destType integer destination type
    destName string destination name
    replyType integer reply destination type
    replyDest string topic/queue to reply to
    correlationId string original message’s correlation ID
    msgId long used for sending acks

This is an alternative to .solace.setQueueMsgCallback.

.solace.setSessionCallback

Associate the provided function with session events

.solace.setSessionCallback callbackFunction

Where callbackFunction is a symbol denoting a function in your q session with arguments:

  1. event type of event (integer)
  2. response code returned for some event, otherwise zero (integer)
  3. further information about the event (string)

associates the named function with session events, such as connection notifications or session errors.

.solace.setTopicMsgCallback

Set callback for messages received from topic subscriptions

.solace.setTopicMsgCallback callbackFunction
Where callbackFunction is a q function with arguments:

  1. destination (symbol)
  2. message binary payload (byte vector)
  3. a dictionary:

    key type value
    isRedeliv boolean whether redelivered (
    isDiscard boolean whether messages discarded prior to the current message
    (Congestion discards only; not affected by message eliding.)
    isRequest boolean whether client expects a reply
    (In this case the function should return a byte array.)
    sendTime timestamp client’s send time, if populated

registers a q function to be called on receipt of messages from topic subscriptions. If the dictionary value for isRequest is true, the function should return with the response message contents (a byte list) to indicate the sender requests a reply.

.solace.setTopicRawMsgCallback

Set callback for messages received from topic subscriptions

.solace.setTopicRawMsgCallback callbackFunction

Where callbackFunction is a function with arguments:

  1. destination (symbol)
  2. a pointer (long) to the underlying Solace message (can be used within the callback with the functions to get the payload based on the sender’s type e.g. getPayloadAsXML, getPayloadAsString, etc)
  3. a dictionary:

    key type content
    isRedeliv boolean whether redelivered
    isDiscard boolean whether messages discarded prior to the current message
    (Congestion discards only; not affected by message eliding.)
    isRequest boolean whether client expects a reply
    (In this case the function should return a byte array.)
    sendTime timestamp client’s send time, if populated

registers callbackFunction to be called on receipt of messages from topic subscriptions. If the dictionary value for isRequest is true, the function should return with the response message contents (a byte list) to indicate the sender requests a reply.

This is an alternative to .solace.setTopicMsgCallback.

.solace.subscribeTopic

Subscribe to a topic

.solace.subscribeTopic[topic;isBlocking]

Where

  • topic is the topic to subscribe to (string)
  • isBlocking is whether the subscription is blocking (boolean)

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

.solace.unBindQueue endpointname

Where endpointname is is a string naming an endpoint, removes a subscription or binding created via .solace.bindQueue.

.solace.unBindQueue "endpoint1"

.solace.unSubscribeTopic

Unsubscribe from a topic

.solace.unSubscribeTopic topic

Where topic is a string denoting a topic, unsubscribes from it.

.solace.unSubscribeTopic "topic1"

.solace.version

Current version of the build/deployment

.solace.version[]

Returns Solace API version info as a dictionary.

Back to top