Skip to content

Latest commit

 

History

History
568 lines (354 loc) · 18.4 KB

reference.md

File metadata and controls

568 lines (354 loc) · 18.4 KB

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
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
getPayloadAsBinary Get the binary part of the Solace message
getPayloadAsString Get the string part of the Solace message
getPayloadAsXML Get the XML part of the Solace message

Utility functions
getCapability Value of the specified capability for the session
version Current version of the build/deployment

Event notifications

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

Connect-disconnect

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

Destroy a session

.solace.destroy[]

Destroys the current session.

Endpoint management

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

.solace.createEndpoint[options;provFlags]

Create an endpoint

Where

provisions an endpoint on the appliance from the 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)

💡 Un-subscriptions from topics may be from either queues or remote clients.

Direct messaging

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

Topic subscription

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

Unsubscribe from a topic

.solace.unSubscribeTopic topic

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

.solace.unSubscribeTopic "topic1"

Guaranteed/persistent messaging

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

Flow bindings

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

Message functions

.solace.getPayloadAsBinary

Get binary part of a Solace message

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

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

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

Utility functions

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

Current version of the build/deployment

.solace.version[]

Returns Solace API version info as a dictionary.

Destination types

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