STOMP (RPGLE)

Stomp : Main Module
Details ....

Copybooks  

de STOMPSRC,STOMP_H
de STOMPSRC,STOMPFRM_H
de STOMPSRC,STOMPUTL_H
de STOMPSRC,STOMPPAR_H
de STOMPSRC,STOMPEXT_H
de QLOG4RPG,PLOG4RPG
SrvPgm: LOG4RPG - Type Definitions public
QLOG4RPG,FDMSG
cpybk : Message
de '/usr/local/include/message_h.rpgle'
de '/usr/local/include/libc_h.rpgle'
de '/usr/local/include/errno_h.rpgle'
de '/usr/local/include/libtree/libtree_h.rpgle'
de STOMPSRC,STOMPFRM_H
de '/usr/local/include/llist_h.rpgle'
de STOMPSRC,STOMPCMD_H
de STOMPSRC,STOMPEXT_H
de STOMPSRC,STOMPEXTAH
de STOMPSRC,FILEDESC_H
de STOMPSRC,NET_H
de STOMPSRC,SOCKET_H
de STOMPSRC,STOMP_T

Procedures  

ackMessage
Ack Message Frame
stomp_addOpenReceiptexported
Add open receipt
stomp_closeexported
Close socket connection
stomp_createexported
Create stomp client instance
stomp_finalizeexported
Dispose client
stomp_getExtensionexported
Get extension
stomp_getNumberOfOpenReceiptsexported
Get number of open receipts
stomp_getOptionValueexported
Get option value
stomp_getSessionIdexported
Get session id
stomp_hasOptionexported
Check client configuration option
stomp_isUsingReceiptsexported
Receipt usage
stomp_openexported
Open socket connection
stomp_receiveFrameexported
Receive frame
stomp_sendFrameexported
Send frame
stomp_setAckModeexported
Set ack mode
stomp_setClientIdexported
Set client id
stomp_setDurableSubscriberNameexported
Set durable subscriber name
stomp_setExtensionexported
Set extension
stomp_setExtensionByNameexported
Set extension by name
stomp_setPersistMessagesexported
Set messages persistent
stomp_setSessionIdexported
Set session id
stomp_setTimeoutexported
Set timeout
stomp_useReceiptsexported
Set usage of receipts
waitForReceipts
Wait for receipts

Detailed Description  

STOMP is a simple text protocol for transporting messages. It can be used to talk to a JMS messaging system like ActiveMQ or Apollo. For further details on STOMP see http://stomp.codehaus.org.

The networking is done via plain socket programming. The sockets will act in non-blocking mode.

A typical workflow of a stomp session sending a message could be:
  1. create stomp client instance (stomp_create)
  2. open socket connection (stomp_open)
  3. connect to/register at messaging system (stomp_command_connect)
  4. send message (stomp_command_send)
  5. disconnect from messaging system (stomp_command_disconnect)
  6. close socket connection (stomp_close)
  7. clean up (stomp_finalize)


Any data will be sent in ASCII (codepage 819).

This module uses the logger de.rpgng.stomp. There is no appender configured for this logger. Feel free to add log appenders for this logger.
Author:
Mihael Schmidt
Date:
27.01.2011
Links:
http://stomp.codehaus.org
http://stomp.googlecode.com
http://www.rpgnextgen.com
http://www.tools400.de

Procedure Documentation  

ackMessage  

voidackMessage(Pointer, Pointer)
If the frame is a MESSAGE frame and the ack mode is "client" then an ACK frame must be send with the message id from the original frame.
Parameter:
Pointer   constConnection
Pointer   constFrame

stomp_addOpenReceipt  

voidstomp_addOpenReceipt(Pointer, stomp_receiptid_t)
Adds a receipt to the list of open receipts.
Parameter:
Pointer   constClient
stomp_receiptid_t   constReceipt id
Exported.

stomp_close  

voidstomp_close(Pointer)
Closes the network socket. This procedure does not send a disconnect frame to the message queuing system.
Parameter:
Pointer   constClient
Exported.

stomp_create  

Pointerstomp_create(Zeichen, Integer)
Creates a stomp client instance.

The default socket timeout is set to 500ms.
Parameter:
Zeichen (255)   const   varyingHostname (messaging system)
Numerisch (Integer) (10)   constPort
Return value:
PointerPointer to client
Exported.
Infos:
  The caller must make sure to free all allocated resource of the client with the procedure stomp_finalize().

stomp_finalize  

voidstomp_finalize(Pointer)
Frees all allocated resources. Any open socket will be closed. Any allocated resource from a set extension will also be freed.
Parameter:
PointerClient
Exported.

stomp_getExtension  

Pointerstomp_getExtension(Pointer)
Returns previously set extension.
Parameter:
Pointer   constClient
Return value:
PointerExtension or *null if no extension has been set
Exported.

stomp_getNumberOfOpenReceipts  

Integerstomp_getNumberOfOpenReceipts(Pointer)
Returns the number of open receipts.
Parameter:
Pointer   constClient
Return value:
Numerisch (Integer) (10)Number of open receipts
Exported.

stomp_getOptionValue  

Pointerstomp_getOptionValue(Pointer, Integer)
Returns the option value for the passed configuration option.
Parameter:
Pointer   constClient
Numerisch (Integer) (10)   constConfiguration option
Return value:
PointerPointer to value or *null if the client doesn't have this option
Exported.

stomp_getSessionId  

stomp_sessionid_tstomp_getSessionId(Pointer)
Returns the session id.
Parameter:
Pointer   constClient
Return value:
stomp_sessionid_tSession or *blank if no session id has been set
Exported.

stomp_hasOption  

Booleanstomp_hasOption(Pointer, Integer)
Checks if the client is configured for the passed option.
Parameter:
Pointer   constClient
Numerisch (Integer) (10)   constOption
Return value:
Boolean*on = client is configured for passed option
*off = client has no configuration for passed option
Exported.

stomp_isUsingReceipts  

Booleanstomp_isUsingReceipts(Pointer)
Returns if the client ask for server receipts for sent frames.
Parameter:
Pointer   constClient
Return value:
Boolean*on = ask server for receipts
*off = don't ask server for receipts
Exported.

stomp_open  

voidstomp_open(Pointer)
This procedure just opens a socket connection to the server. It does not communicate with the message queuing system (means it does not send any Stomp frames).
Parameter:
Pointer   constClient
Exported.

stomp_receiveFrame  

Pointerstomp_receiveFrame(Pointer)
Receive a frame from the message system. The next incoming socket data will be passed to the frame parser and the resulting frame is returned to the caller. The socket connection must have been established (stomp_open) before receiving any frames. If no frame is received over the socket connection in the timeout time then *null will be returned.

If the received frame is a MESSAGE frame and the ack mode is client then an ACK frame will be sent automatically before returning to the caller.

Any buffered frame will be returned by this procedure before trying to receive a frame over the socket connection.
Parameter:
Pointer   constClient
Return value:
PointerPointer to frame or *null if no frame could be received in time
Exported.
Infos:
  The call must make sure to free any resources allocated by the frame with stomp_frame_finalize().

stomp_sendFrame  

voidstomp_sendFrame(Pointer, Pointer)
Sends the passed frame to the connected system. The socket connection must have been established (stomp_open) before sending any frames.

If the client is configured for receipts (stomp_useReceipts) then every frame (except the CONNECT frame) will get a receipt header with the timestamp as a value. This procedure will wait until the correct receipt has been received. Any frames in between will be buffered and returned in the correct order by the next call to stomp_receiveFrame().
Parameter:
Pointer   constClient
Pointer   constFrame
Exported.

stomp_setAckMode  

voidstomp_setAckMode(Pointer, Zeichen)
The successful receiving of a message from the messaging system can either be automatically acknowledged or manually. If the client is configured for ack mode auto then the server assumes that every sent message from the server is also received by the client. The client does not need to do anything. If the client is configured for ack mode client then every received message must be acknowledged by the client by sending in ACK frame. In ack mode client every not acknowledged frame will be sent again.

Default is ack mode auto.
Parameter:
Pointer   constClient
Zeichen (10)   constAck mode (STOMP_ACK_MODE_AUTO, STOMP_ACK_MODE_CLIENT)
Exported.

stomp_setClientId  

voidstomp_setClientId(Pointer, Zeichen)
Sets the client id. This value is needed for a durable topic subscription. This id must be unique with the whole system.
Parameter:
Pointer   constClient
Zeichen (100)   const   varyingClient id
Exported.

stomp_setDurableSubscriberName  

voidstomp_setDurableSubscriberName(Pointer, Zeichen)
This value is needed for a durable topic subscription at the messaging system.
Parameter:
Pointer   constClient
Zeichen (100)   const   varyingDurable subscriber name
Exported.

stomp_setExtension  

voidstomp_setExtension(Pointer, Pointer)
Sets the extension to be used by the client. Any previously set extension will be removed and the allocated resources freed.
Parameter:
Pointer   constClient
Pointer   constExtension
Exported.

stomp_setExtensionByName  

voidstomp_setExtensionByName(Pointer, Zeichen, Pointer, Zeichen)
Creates an instance of the STOMP extension and adds that to the client configuration. Only one extension may be used at any time. Any previsously set extension will be replaced and disposed.
Parameter:
Pointer   constClient
Zeichen (10)   constExtension name (service program name)
Pointer   const   optionalUserdata
Zeichen (256)   const   optionalProcedure name
Exported.

stomp_setPersistMessages  

voidstomp_setPersistMessages(Pointer, Boolean)
Configures the client to send persistent messages. Only messages with the header persistent will be sent to all durable topic subscribers.
Parameter:
Pointer   constClient
Boolean   constPersistent messages
Exported.

stomp_setSessionId  

voidstomp_setSessionId(Pointer, stomp_header_t.sessionId)
Sets the session id.
Parameter:
Pointer   constClient
stomp_header_t.sessionId   constSession id
Exported.

stomp_setTimeout  

voidstomp_setTimeout(Pointer, Integer)
Sets the timeout for the socket operations.
Parameter:
Pointer   constClient
Numerisch (Integer) (10)   constTimeout (in ms)
Exported.

stomp_useReceipts  

voidstomp_useReceipts(Pointer, Boolean)
Configures if the client as for server receipts for every sent frame (except CONNECT).
Parameter:
Pointer   constClient
Boolean   constValue *on/*off
Exported.

waitForReceipts  

voidwaitForReceipts(Pointer)
The procedures receives frames over the socket of the client and waits until all open receipts has been received.
Because receipts may not be sent directly after the frame with the receipt header all non RECEIPT frames will be buffered and returned by calling the stomp_receiveFrame procedure.
Parameter:
Pointer   constPointer to client