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
  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
  bindQueue                  Bind to a queue
  sendAck                    Acknowledge processing of a message
  unBindQueue                Remove subscription/binding created with bindQueue
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.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 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.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.