API Functions
This chapter describes various APIs that are needed to deliver messages via HMS.
1. Overview
HMS API functions are provided with the server and client libraries that are provided along with Tmax API. Hence, users can use both Tmax APIs and HMS APIs to develop applications. The server library is provided as libsvr.a, and the client library is provided as libcli.a and libclithr.a in the UNIX environment. When an application is compiled, the relevant library must be included.
Tmax APIs use the hmsapi.h header file by default. To use HMS APIs together, the atmi.h, tmaxapi.h, and tx.h header files must be used together. When developing a client application to use HMS, the application must be connected to Tmax via tpstart(). In this case, atmi.h as well as hmsapi.h must be used.
| Header File | Description |
|---|---|
hmsapi.h |
Defines the APIs for the sessions, producers, consumers, and messages that are necessary to use HMS. |
atmi.h |
Defines the APIs for the buffer management and the communication. |
tmaxapi.h |
Defines non-standard API prototypes. |
tx.h |
Defines transaction function prototypes. |
HMS APIs are divided into the following session, message, producer, consumer, and QueueBrowser.
-
Session API
API Description Creates a session to HMS and returns the session handle.
Creates an XA session to HMS and returns the session handle.
Creates an async session and returns the session handle.
Terminates the session.
Unsubscribes the registration of a durable subscriber.
Commits a local transaction that involves the messages sent and received within the session.
Rolls back a local transaction that involves the messages sent and received within a session.
Restarts transmitting the message which ACK has not been sent to the HMS among the messages sent and received within a session.
-
Message API
API Description Allocates a message buffer to use in a messaging service, and returns the buffer’s pointer.
Frees the memory allocated to a message buffer.
Retrieves the information of a property with the name defined in the message
Specifies a property in the message with a specific name.
Retrieves the data part of a message.
Sets the data part of the message.
Sends an ACK in response to a received message.
-
Producer API
API Description Creates a producer that will send a message to a destination, and returns the producer’s handle.
Creates a sender that will send a message to the destination of the queue type.
Creates a publisher that will send a message to the destination of the topic type.
Closes the producer and returns the allocated resources.
Closes the sender of the queue type and returns the allocated resources.
Closes the publisher of the topic type and returns the allocated resources.
Sends a message to the destination specified when the producer was created.
Sends a message only with basic settings.
-
Consumer API
API Description Creates creates a consumer that will receive a message from the destination and returns the consumer’s handle.
Creates a receiver that will receive a message from the destination of the queue type.
Creates a subscriber that will receive a message from the destination of the topic type.
Creates a durable subscriber that will receive a message from the destination of the topic type.
Closes the consumer and returns the allocated resources.
Closes the receiver of the queue type and returns the allocated resources.
Closes the subscriber of the topic type and returns the allocated resources.
Closes a durable subscriber and returns the allocated resources.
Receives a message from the destination.
Waits until a message arrives from the destination.
-
Queue Browser API
API Description Creates QueueBrowser inquire messages in the current destination and returns the browser’s handle
Closes QueueBrowser and returns allocated resources.
Inquires messages from the newest messages first.
Obtains the statement of the message selector that was specified when the browser was created.
Copies the name of the destination that was specified when the browser was created to a buffer, and specifies the length of the name in the LEN parameter.
2. Session API
Session APIs are divided into the APIs for creating and closing sessions and the APIs for processing transactions
2.1. hms_create_session
The hms_create_session function creates a session to HMS and returns the session handle. A session, producer, consumer, message, and queue browser can be created by using the session handle. When a session is created, the option to use local transactions and the ACK mode can be specified. In local transaction mode, either hms_commit or hms_rollback API must be called to complete a transaction.
To use the hms_create_session API in a client application, it is required to connect to Tmax. A session must be created after a connection to Tmax have been established by using tpstart(). Tmax connection is not required to use this API in a server application.
-
Prototype
#include <usrinc/hmsapi.h> HMS_SHND * hms_create_session (char *hms, int transacted, int ackmode, int flags)
-
Parameter
Parameter Description hms
Server group name of the HMS as specified in the SVRGROUP clause of the configuration file.
transacted
Option to use local transactions.
-
0: Local transactions are not used.
-
1: Local transactions are used.
ackmode
-
HMS_AUTO_ACK: An ACK is sent to each message.
-
HMS_CLIENT_ACK: A client directly sends an ACK.
-
HMS_DUPS_OK_ACK: An ACK is sent to multiple messages each time. (currently not supported).
flags
Currently not used.
-
-
Return Value
Return Value Description Pointer to the Generated Session Handle
The function call succeeded.
NULL
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the HMS parameter is null, the function exceeds the specified message length, or ackmode is set to an invalid value.
[TPEOS]
An HMS operating system error occurred, or the specified environment variable is incorrect. This error may occur while a client is using the API.
For example, this error may occur due to a connection failure caused by an incorrect TMAX_HOST_ADDR or TMAX_HOST_PORT value.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPELIMIT]
No more sessions can be created because the maximum number of concurrent sessions that can connect to HMS has been reached.
[TPENOREADY]
The HMS named 'HMS' is in the NOT READY state.
[TPENOENT]
The HMS named 'HMS' does not exist.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; char *hms, *dest; char *buf; int ret; long size = 1024; ... if (argc != 3) return; hms = argv[1]; dest = argv[2]; /* Creates a session in the local transaction mode */ session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } buf = tpalloc("STRING", NULL, 0); if (buf == NULL) { error processing } ret = hms_get_body(msg, buf, &size); if (ret < 0) { error processing } ... ret = hms_commit(session, 0); if (ret < 0) { error processing } ... hms_free(msg); hms_close_consumer(cons, 0); /* Closes the session */ ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_session(), hms_create_producer(), hms_create_consumer(), hms_create_browser(), hms_commit(), hms_rollback(), hms_recover()
2.2. hms_create_xa_session
The hms_create_xa_session function creates an XA session to HMS and returns the session handle. All client’s (producer’s or consumer’s) messages created with this session are handled a transaction. A transaction begins with tx_begin() and ends with tx_commit() or tx_rollback(). A messages that is processed outside of the boundary is not affected by a transaction. If transacted and ackmode is set to 0 and HMS_AUTO_ACK, this function operates the same as hms_create_session. When hms_send and hms_recv APIs are called, the results are applied immediately.
To use the hms_create_xa_session API in a client application, it is required to connect to Tmax. A session must be created after a connection to Tmax have been established by using tpstart(). Tmax connection is not required to use this API in a server application.
-
Prototype
#include <usrinc/hmsapi.h> HMS_SHND * hms_create_xa_session (char *hms, int flags)
-
Parameter
Parameter Description hms
Server group name of the HMS as specified in the SVRGROUP clause of the configuration file.
flags
Currently not used.
-
Return Value
Return Value Description Pointer to the Generated Session Handle
The function call succeeded.
NULL
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the HMS parameter is null or the function exceeds the specified message len.
[TPEOS]
An HMS operating system error occurred, or the specified environment variable is incorrect. This error may occur while a client is using the API.
For example, this error may occur due to a connection failure caused by an incorrect TMAX_HOST_ADDR or TMAX_HOST_PORT value.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPELIMIT]
No more sessions can be created because the maximum number of concurrent sessions that can connect to HMS has been reached.
[TPENOREADY]
The HMS named 'HMS' is in the NOT READY state.
[TPENOENT]
The HMS named 'HMS' does not exist.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_PHND *prod; hms_msg_t *msg; char *hms, *dest, *buf; int ret; long size = 1024; ... if (argc != 3) return; hms = argv[1]; dest = argv[2]; /* Creates a session in the global transaction mode */ session = hms_create_xa_session(hms, 0); if (session == NULL) { error processing } ret = tx_begin(); if (ret < 0) { error processing } prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0); if (prod == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } ... ret = hms_set_body(msg, buf, size); if (ret < 0) { error processing } ret = hms_send(prod, msg, 0); if (ret < 0) { error processing } ... ret = tx_commit(); if (ret < 0) { error processing } ... hms_free(msg); hms_close_producer(prod, 0); /* Closes the session */ ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_session()
2.3. hms_create_async_session
This function creates an async session and returns the session handle. Messages can be handled asynchronously with the session.
To create a consumer and receive messages with an async session, the service to receive and handle messages must be specified instead of calling hms_recv(). The service name can be specified when a consumer is created. As soon as a new message is sent to a destination, the service will receive and handle it. A consumer can be created with an async session in both a client and a server application.
If an async session is closed or a failure occurs in HMS, the Abendfunc callback function is executed. A user can respond to a failure by defining the function.
-
Prototype
#include <usrinc/hmsapi.h> HMS_SHND * hms_create_async_session (char *hms, Abendfunc *func, int flags)
-
Parameter
Parameter Description hms
Server group name of the HMS as specified in the SVRGROUP clause of the configuration file.
func
Callback function to be called when a failure occurs in HMS.
flags
Currently not used.
-
Return Value
Return Value Description Pointer to the Generated Session Handle
The function call succeeded.
NULL
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the HMS parameter is null or the function exceeds the specified message len.
[TPEOS]
An HMS operating system error occurred, or the specified environment variable is incorrect. This error may occur while a client is using the API.
For example, this error may occur due to a connection failure caused by an incorrect TMAX_HOST_ADDR or TMAX_HOST_PORT value.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPELIMIT]
No more sessions can be created because the maximum number of concurrent sessions that can connect to HMS has been reached.
[TPENOREADY]
The HMS named 'HMS' is in the NOT READY state.
[TPENOENT]
The HMS named 'HMS' does not exist.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> HMS_SHND *session; HMS_PHND *cons; HMS_PHND *prod; void abend_callback(HMS_SHND *sess) { hms_close_session(sess, 0); printf("hms_close_session success\n"); while (1) { session = hms_create_async_session(hms, abend_callback, 0); if (session == NULL) { printf("hms_create_session() : FAIL [%d]\n\n", tperrno); if (tperrno == TPENOREADY) { sleep(2); continue; } return; } break; } printf("hms_create_session success\n"); cons = hms_create_receiver(session, dest, "consumer_1", NULL, "MYSVC", 0); if (cons == NULL) { printf("hms_create_receiver() : FAIL tperrno = %d\n\n", tperrno); return; } } main(int argc, char* argv[]) { hms_msg_t *msg; char *hms, *dest, *buf; int ret; long size = 1024; ... if (argc != 3) return; hms = argv[1]; dest = argv[2]; /* Creates an async session */ session = hms_create_async_session(hms, 0); if (session == NULL) { error processing } cons = hms_create_receiver(session, dest, "consumer_1", NULL, "MYSVC", 0); if (cons == NULL) { error processing } prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0); if (prod == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } ... ret = hms_set_body(msg, buf, size); if (ret < 0) { error processing } ret = hms_send(prod, msg, 0); if (ret < 0) { error processing } ... hms_free(msg); hms_close_producer(prod, 0); /* Closes the session */ ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_session()
2.4. hms_close_session
The hms_close_session function closes a session created with hms_create_session(), hms_create_xa_session(), or hms_create_async_session(), and returns the resources allocated to HMS. If a session is no longer necessary, the session should be closed. If a session is closed, all clients (producers and consumers) created with the session are terminated together.
-
Prototype
#include <usrinc/hmsapi.h> int hms_close_session (HMS_SHND *sess, int flags)
-
Parameter
Parameter Description sess
Session pointer to close.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the SESS parameter is null or the specified pointer is invalid.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOREADY]
The HMS named 'HMS' is in the NOT READY state.
-
Related Functions
hms_create_session(), hms_create_xa_session(), hms_create_async_session()
2.5. hms_unsubscribe_durable_subscriber
The hms_unsubscribe_durable_subscriber function unsubscribes the registration of a durable subscriber. If there is a durable subscriber among the clients connected to a destination, the messages of the topic type will be maintained until all durable subscribers receive the messages.
If a session is closed without calling hms_unsubscribe_durable_subscriber(), the client information (the name of the durable subscriber) will remain in a destination. This allows the durable subscriber receive the published Topic messages again that have been created after the termination of the consumer when a new session is created. When the durable subscriber no longer needs to receive the messages of the topic type, this function must be called. The messages sent after the call will not wait until the durable subscriber receives them, and will be removed from the memory.
-
Prototype
# include <usrinc/hmsapi.h> int hms_unsubscribe_durable_subscriber (HMS_SHND *sess, char *des, char *name, int flags)
-
Parameter
Parameter Description sess
Session pointer.
des
Name of the registered destination.
name
Name of the registered durable subscriber.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the SESS or DES parameter is null or the length of the DES or NAME parameter exceeds the specified message len.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPETIME]
Timeout occurred.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates durable_subscriber */ cons = hms_create_durable_subscriber(session, dest, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } ... ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } ... hms_free(msg); ret = hms_close_durable_subscriber(cons, 0); if (ret < 0) { error processing } ... /* Unsubscribes for durable_subscriber */ ret = hms_unsubscribe_durable_subscriber(session, dest, "consumer_1", 0); if (ret < 0) { error processing } ... ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_create_durable_subscriber(), hms_close_durable_subscriber()
2.6. hms_commit
The hms_commut function commits a local transaction that involves the messages sent and received within the session. This function can be used only in a session that was created in the local transaction mode via hms_create_session(). The transacted parameter of hms_create_session() must be set to 0. If the transaction is in the ROLLBACK_ONLY state, it will be rolled back. This function does not require an API that declares the start of a transaction, unlike an XA session which must use tx_commit().
-
Prototype
#include <usrinc/hmsapi.h> int hms_commit (HMS_SHND *sess, int flags)
-
Parameter
Parameter Description sess
Session pointer.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the SESS parameter is null or the specified pointer is invalid.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEPROTO]
The function was called in an improper context. For example, transacted is set to 0 when calling hms_create_session() to create a session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPETIME]
Timeout has occurred.
[TPENOENT]
A producer or consumer that sent a message before this function call has been terminated.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { ... /* Creates a session in the local transaction mode */ session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0); if (prod == NULL) { error processing } ... msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_set_body(msg, buf, size); if (ret < 0) { error processing } ret = hms_send(prod, msg, 0); if (ret < 0) { error processing } ... /* Commits the transactions */ ret = hms_commit(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_create_session(), hms_rollback()
2.7. hms_rollback
The hms_rollback function rolls back a local transaction that involves the messages sent and received within a session.
This function can be used only in a session that was created in the local transaction mode via hms_create_session(). The transacted parameter of hms_create_session() must be set to 1.
-
Prototype
#include <usrinc/hmsapi.h> int hms_rollback (HMS_SHND *sess, int flags)
-
Parameter
Parameter Description sess
Session pointer.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
2.8. hms_recover
The hms_recover function restarts transmitting the message which ACK has not been sent to the HMS among the messages sent and received within a session.
This function can only be used within a session that was created using hms_create_session() in the local transaction mode. The transacted parameter of hms_create_session() must be set to 0.
If a failure occurs while a consumer is receiving a message or the consumer has been terminated without sending an ACK to HMS in response to the message received, the messages will be sent to HMS again by calling the hms_recover function when the session is reconnected.
-
Prototype
#include <usrinc/hmsapi.h> int hms_recover (HMS_SHND *sess, int flags)
-
Parameter
Parameter Description sess
Session pointer.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the SESS parameter is null.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEPROTO]
The function was called in an improper context. For example, transacted is set to 0 when calling hms_create_session() to create a session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPETIME]
Timeout has occurred.
[TPENOENT]
A producer or consumer that sent a message before this function call has been terminated.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { ... /* Creates a session */ session = hms_create_session(hms, 0, HMS_CLIENT_ACK, 0); if (session == NULL) { error processing } cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } ... /* Receives messages from HMS */ msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } buf = tpalloc("STRING", NULL, 0); if (buf == NULL) { error processing } ret = hms_get_body(msg, buf, &size); if (ret < 0) { error processing } ... if ( condition ) { ret = hms_ack(msg, HMS_ACK_ONE); if (ret < 0) { error processing } } else { ret = hms_recover(session, 0); if (ret < 0) { error processing } } ... } -
Related Functions
hms_create_session()
3. Message API
Session APIs are divided into the APIs for creating and closing sessions and the APIs for storing and inquiring the information of messages.
3.1. hms_alloc
This hms_alloc function allocates a message buffer to use in a messaging service, and returns the buffer’s pointer.
The hms_free function must be used to free an unused message buffer. The free function must not be used.
A message buffer consists of property and body. The hms_set_property and hms_set_body function can be used to store information in a message buffer. The property provides basic information on messages and the criteria to select messages. The property consists of the pair of a name and a value. A buffer can have multiple properties. The body includes the main contents of the messages. For more information, refer to Tmax Reference Guide.
-
Prototype
# include <usrinc/hmsapi.h> hms_msg_t * hms_alloc (HMS_SHND *sess, long size)
-
Parameter
Parameter Description sess
Session pointer connected to HMS.
size
Size of the message buffer to allocate.
-
Return Value
Return Value Description Pointer to the Allocated Message Buffer
The function call succeeded.
NULL
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
The SESS parameter is null.
[TPESYSTEM]
An HMS system error occurred.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; long size; ... /* Creates a session in the general mode. */ session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } /* Allocates a message buffer. */ size = 1024; msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } buf = tpalloc("STRING", NULL, 0); if (buf == NULL) { error processing } ret = hms_get_body(msg, buf, &size); if (ret < 0) { error processing } ... ret = hms_ack(msg, HMS_ACK_ONE); if (ret < 0) { error processing } ... /* Frees the message buffer. */ hms_free(msg); hms_close_consumer(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_free()
3.2. hms_free
The hms_free function frees the memory allocated to a message buffer. If a message buffer allocated with hms_alloc() is no longer used, it must be freed with this function. The free function must not be use to free a message buffer. If a message buffer that has been already freed is released again, the result is unknown.
-
Prototype
# include <usrinc/hmsapi.h> void hms_free (hms_msg_t * msg)
-
Parameter
Parameter Description msg
Message pointer to free.
-
Return Value
There is no return value..
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... /* Creates a session in the general mode */ session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } /* Allocates a message buffer */ msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } buf = tpalloc("STRING", NULL, 0); if (buf == NULL) { error processing } ret = hms_get_body(msg, buf, &size); if (ret < 0) { error processing } ... ret = hms_ack(msg, HMS_ACK_ONE); if (ret < 0) { error processing } ... /* Frees the message buffer */ hms_free(msg); hms_close_consumer(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_alloc()
3.3. hms_get_property
The hms_get_property function retrieves the information of a property with the name defined in the message. If the specified name of property exists in the message, the type, value, and len information will be retrieved. If the property does not exist, -1 will be returned and tperrno will be set to TPENOENT. A buffer (value) to store data must have been allocated (or declared) and the size of the buffer must be transmitted along with the buffer. If the size of the received data is greater than that of a buffer, the TPEINVAL error will occur.
The property consists of the pair of a name and a value. The name is unique in a message buffer. If the property which value was already allocated with hms_set_property() is specified again within this function, the existing value will be replaced by the new one. The properties can be set before sending a message to the destination via hms_send() and after receiving it via hms_receive(), so that a received message can be changed to resend. The properties are used as a criteria that a message consumer can use to select the message to receive. A message selector can be set when a consumer is created. For more information, refer to hms_create_consumer or Using a Message Selector.
Macros are provided for the reserved words. The following reserved properties are defined in hmsapi.h. The reserved properties must not be modified. For more information about reserved properties, refer to Messages.
-
Prototype
# include <usrinc/hmsapi.h> int hms_get_property (hms_msg_t *msg, char *name, int *type, char *value, long *len)
-
Parameter
Parameter Description msg
Message pointer to a property.
name
Name of the property to retrieve.
type
Property type.
-
HMS_CHAR
-
HMS_SHORT
-
HMS_INT
-
HMS_LONG
-
HMS_FLOAT
-
HMS_DOUBLE
-
HMS_STRING
-
HMS_CARRAY
value
Pointer to a property. The pointer type is determined according to the property type.
len
Pointer to the size of a buffer used to store a property and the size of a property.
-
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the MSG, NAME, or VALUE parameter is null or the LEN parameter the function is smaller than the length of a property to obtain.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOENT]
The name of the property does not exist in the MSG parameter.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... int type; long len = 256; char buf[256]; /* used for hms_get_property() */ int myval; /* used for hms_get_property() */ /* Creates a session in the general mode */ session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } /* Allocates a message buffer */ msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } ret = hms_get_property(msg, HMSDestination, &type, buf, &len); if (ret < 0) { error processing } ret = hms_get_property(msg, HMSDestination, &type, &myval, sizeof(int)); if (ret < 0) { error processing } ... ret = hms_ack(msg, HMS_ACK_ONE); if (ret < 0) { error processing } ... /* Releases the message buffer */ hms_free(msg); hms_close_consumer(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_set_property(), hms_alloc(), hms_free()
3.4. hms_set_property
The hms_set_property function specifies a property in the message with a specific name. If a property that has the name already exists, the property is changed to a new value. Property types are the same as those supported by a field buffer.
The property consists of the pair of a name and a value. The name is unique in a message buffer. If the property which value was already allocated with hms_set_property() is specified again within this function, the existing value will be replaced by the new one. The properties can be set before sending a message to the destination via hms_send() and after receiving it via hms_receive(), so that a received message can be changed to resend. The properties are used as a criteria that a message consumer can use to select the message to receive.For detailed information, refer to hms_create_consumer or Using a Message Selector.
Macros are provided for the reserved words. The following reserved properties are defined in hmsapi.h. The reserved properties must not be modified. For more information about reserved properties, refer to Messages.
-
Prototype
# include <usrinc/hmsapi.h> int hms_set_property (hms_msg_t * msg, char *name, int type, char *value, long len)
-
Parameter
Parameter Description msg
Message pointer to a property.
name
Name of a property to retrieve. Reserved words cannot be used.
type
Property type.
-
HMS_CHAR
-
HMS_SHORT
-
HMS_INT
-
HMS_LONG
-
HMS_FLOAT
-
HMS_DOUBLE
-
HMS_STRING
-
HMS_CARRAY
value
Pointer to the property.
len
Size of the buffer to specify.
-
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error.
This error may occur when the MSG, NAME, or VALUE parameter is null, the LEN parameter the function is a negative number, or the NAME parameter is a reserved property. There is not enough memory space to set the property in the MSG parameter.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { char buf[256]; ... if (argc != 2 ) return 1; strncpy(buf, argv[1], 255); /* Creates a session in the local transaction mode */ session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0); if (prod == NULL) { error processing } ... msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_set_property(msg, "NAME", HMS_STRING, buf, strlen(buf)); if (ret < 0) { error processing } ret = hms_send(prod, msg, 0); if (ret < 0) { error processing } ... /* Handles transactions */ ret = hms_commit(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_get_property(), hms_alloc(), hms_free()
3.5. hms_get_body
The hms_get_body function retrieves the data part of a message. The property name, "$DATA", is internally used.
The buffer to retrieve data must be allocated with tpalloc(). A buffer to store data must have been allocated and the size of the buffer must be transmitted along with the buffer. If the size of the received data is greater than that of a buffer, the TPEINVAL error will occur.
-
Prototype
# include <usrinc/hmsapi.h> int hms_get_body (hms_msg_t *msg, char *data, long *len)
-
Parameter
Parameter Description msg
Message pointer.
data
Buffer to store the data of a message.
len
Maximum size of the buffer to store the data of a message.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the MSG, DATA, or LENGTH parameter is incorrect or the LEN parameter is smaller than the size of the message data.
[TPENOENT]
The message data does not exist.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; char *buf; ... /* Creates a session in the general mode */ session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } /* Allocates a message buffer */ msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } /* Retreives the data of the message */ buf = tpalloc("STRING", NULL, 0); if (buf == NULL) { error processing } ret = hms_get_body(msg, buf, &size); if (ret < 0) { error processing } ... ret = hms_ack(msg, HMS_ACK_ONE); if (ret < 0) { error processing } ... /* Frees the message buffer */ hms_free(msg); hms_close_consumer(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_set_body()
3.6. hms_set_body
The hms_set_body function sets the data part of the message. The function internally uses the property name, "$DATA".
Body does not have a type unlike a property, and saves information with the number of bytes in len specified in the CARRY type.
-
Prototype
# include <usrinc/hmsapi.h> int hms_set_body (hms_msg_t *msg, char *data, long len)
-
Parameter
Parameter Description msg
Message pointer.
data
Buffer that has the contents to store in the data of a message.
len
Length of the data of a message.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the MSG or DATA parameter is null or the LEN parameter is a negative number.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_PHND *prod; hms_msg_t *msg; char *buf; ... if (argc !=2 ) return 1; /* Creates a session in the local transaction mode */ session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0); if (prod == NULL) { error processing } ... msg = hms_alloc(session, size); if (msg == NULL) { error processing } /* Sets the data of the message */ buf = tpalloc("STRING", NULL, 0); if (buf == NULL) { error processing } strcpy(buf, argv[1]); ret = hms_set_body(msg, buf, strlen(buf)); if (ret < 0) { error processing } ret = hms_send(prod, msg, 0); if (ret < 0) { error processing } ... /* Handles transactions */ ret = hms_commit(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_get_body()
3.7. hms_ack
The hms_ack function sends an ACK in response to a received message. If HMS receives the ACK indicating that a message is successfully received, it cleans up the information of the message. If HMS does not receive the ACK, it will maintain the message. An ACK must be transmitted in the case where a message is received within a session that was created with hms_create_session() and which ackmode was set to HMS_DUPS_OK_ACK or HMS_CLIENT_ACK.
An ACK can be automatically transmitted in the following cases. A message is received via hms_recv() within a session that was created with hms_create_session() and which ackmode is set to HMS_AUTO_ACK. The hms_commit or tx_commit is called within a session that supports transaction. In these cases, hms_ack() needs not to be called.
When the flag is set to HMS_ACK_ONE, the ACK is sent only for the corresponding message. When it is set to HMS_ACK_UPTHROUGH, ACKs are sent for all messages including those received before that message.
-
Prototype
# include <usrinc/hmsapi.h> int hms_ack (hms_msg_t *msg, int flags)
-
Parameter
Parameter Description msg
Pointer to the message where an ACK will be sent.
flags
Sets one of the following:
-
HMS_ACK_ONE: ACK is only sent to the relevant message.
-
HMS_ACK_UPTHROUGH: ACK is sent to all received messages at a time.
-
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the FLAGS parameter is invalid, or HMS_ACK_ONE and HMS_ACK_UPTHROUGH are specified together in FLAGS
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEPROTO]
The function was called in an improper context.
For example, this function was called within an XA session, a session that supports transactions, or a session which ackmode is not set to HMS_DUPS_OK_ACK or HMS_CLIENT_ACK.
[TPEITYPE]
Invalid MSG parameter.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... /* Creates a session in the general mode */ session = hms_create_session(hms, 0, HMS_CLIENT_ACK, 0); if (session == NULL) { error processing } cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } buf = tpalloc("STRING", NULL, 0); if (buf == NULL) { error processing } ret = hms_get_body(msg, buf, &size); if (ret < 0) { error processing } /* Sends ACK for a received message */ ret = hms_ack(msg, HMS_ACK_ONE) if (ret < 0) { error processing } ... hms_free(msg); hms_close_consumer(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_recvex(), hms_recv()
4. Producer API
Producer APIs are divided into the APIs for creating and closing the topic or queue types of producers.
4.1. hms_create_producer
The hms_create_producer function creates a producer that will send a message to a destination, and returns the producer’s handle. A destination is a virtual channel created by an administrator, serving as the source where messages are received and sent.
There are two types of destination; the queue type that supports sending a message with the point-to-point method and the topic type that supports sending a message with the publish-and-subscribe method. The two types can be used in a single application.
A session is necessary to create a produce. After a producer is created, a message can be sent to a destination with hms_send(). If a producer sends a message to the queue or topic type of destination, consumers that access the destination can receive the message.
-
Prototype
#include <usrinc/hmsapi.h> HMS_PHND * hms_create_producer (HMS_SHND *sess, char *des, int destype, char *name, int flags) -
Parameter
Parameter Description sess
Session pointer used to send a message.
des
Name of a destination to send the message to.
destype
Destination type (HMS_QUEUE or HMS_TOPIC).
name
Name of a producer to create.
flags
Currently not used.
-
Return Value
Return Value Description A producer’s handle
Function call is successful.
NULL
Function call failed. tperrno is set to the error code.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the SESS parameter is null, the DES parameter has no name, the length of the DES or NAME parameter exceeds the specified message len, or the DESTYPE parameter is invalid.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOENT]
There is no destination to which the message can be sent, or the destination is inactive.
[TPEITYPE]
The destination type does not match the destination of the producer that will be created.
[TPEOS]
An HMS operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPEMATCH]
The producer name already exists in HMS.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_PHND *prod; hms_msg_t *msg; ... session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates the queue type of a producer */ prod = hms_create_producer(session, dest, HMS_QUEUE, "producer_1", 0); if (prod == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } ... ret = hms_set_body(msg, buf, size); if (ret < 0) { error processing } ret = hms_send(prod, msg, 0); if (ret < 0) { error processing } ... hms_free(msg); hms_close_producer(prod, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_producer()
4.2. hms_create_sender
The hms_create_sender function creates a sender that will send s a message to the destination of the queue type. This function operates the same as hms_create_producer().
-
Prototype
# include <usrinc/hmsapi.h> HMS_PHND * hms_create_sender (HMS_SHND *sess, char *des, char *name, int flags)
-
Parameter
Parameter Description sess
Session pointer used to send a message.
des
Name of a destination to send the message to.
name
Name of a sender to create.
flags
Currently not used.
-
Return Value
Return Value Description A sender’s handle
Function call is successful.
NULL
Function call failed. tperrno is set to the error code.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the SESS parameter is null, the DES parameter has no name, or the length of the DES or NAME parameter exceeds the specified message len.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOENT]
There is no destination to which the message can be sent, or the destination is inactive.
[TPEITYPE]
The destination type does not match the destination of the sender that will be created.
[TPEOS]
An HMS operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPEMATCH]
The sender name is already registered in HMS.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_PHND *prod; hms_msg_t *msg; ... session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates the queue type of a producer */ prod = hms_create_sender(session, dest, "producer_1", 0); if (prod == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } ... ret = hms_set_body(msg, buf, size); if (ret < 0) { error processing } ret = hms_send(prod, msg, 0); if (ret < 0) { error processing } ... hms_free(msg); hms_close_sender(prod, 0); /* Closes the session */ ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_sender()
4.3. hms_create_publisher
The hms_create_publisher function creates a publisher that will send a message to the destination of the topic type. This function operates the same as hms_create_producer().
-
Prototype
# include <usrinc/hmsapi.h> HMS_PHND * hms_create_publisher (HMS_SHND *sess, char *des, char *name, int flags)
-
Parameter
Parameter Description sess
Session pointer used to send a message.
des
Name of a destination to send the message to.
name
Name of a publisher to create.
flags
Currently not used.
-
Return Value
Return Value Description A publisher’s handle
Function call is successful.
NULL
Function call failed. tperrno is set to the error code.
-
Errors
One of the following values is set to tperrno
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the SESS parameter is null, the DES parameter has no name, or the length of the DES or NAME parameter exceeds the specified message len.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOENT]
There is no destination to which the message can be sent, or the destination is inactive.
[TPEITYPE]
The destination type does not match the destination of the publisher that will be created.
[TPEOS]
An HMS operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPEMATCH]
The publisher name is already registered in HMS.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_PHND *prod; hms_msg_t *msg; ... session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates the topic type of a producer */ prod = hms_create_publisher(session, dest, "producer_1", 0); if (prod == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } ... ret = hms_set_body(msg, buf, size); if (ret < 0) { error processing } ret = hms_send(prod, msg, 0); if (ret < 0) { error processing } ... hms_free(msg); hms_close_publisher(prod, 0); /* Closes the session */ ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_publisher()
4.4. hms_close_producer
The hms_close_publisher function closes the producer and returns the allocated resources.
-
Prototype
# include <usrinc/hmsapi.h> int hms_close_producer (HMS_PHND *prod, int flags)
-
Parameter
Parameter Description prod
Handle pointer to a producer to close.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the PROD parameter is null or set to an invalid pointer.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Related Functions
hms_create_producer()
4.5. hms_close_sender
The hms_close_sender function closes the sender of the queue type and returns the allocated resources. This function operates the same as the hms_close_producer() function.
-
Prototype
# include <usrinc/hmsapi.h> int hms_close_sender (HMS_PHND *prod, int flags)
-
Parameter
Parameter Description prod
Handle pointer to a sender to close.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the PROD parameter is null
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Related Functions
hms_create_sender()
4.6. hms_close_publisher
The hms_close_publisher function closes the publisher of the topic type and returns the allocated resources. This function operates the same as hms_close_producer().
-
Prototype
# include <usrinc/hmsapi.h> int hms_close_publisher (HMS_PHND *prod, int flags)
-
Parameter
Parameter Description prod
Handle pointer to a publisher to close.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the PROD parameter is null.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Related Functions
hms_create_publisher()
4.7. hms_sendex
The hms_sendex function sends a message to the destination specified when the producer was created.
There are two kinds of transmission mode: persistent mode and non-persistent mode. In the persistent mode, the messages are stored in a database after being delivered to a destination. If a failure occurs in HMS, all messages that were delivered to a destination can be recovered. When a consumer receives the message, the message stored in the persistent mode will be deleted from the database after a specified time passes. The age of a received message can be specified in the configuration file.
he priority or the validity of messages can be specified when the messages are sent. The priority is used to schedule the messages in a destination. The messages that expires the validity period will be discarded, and cannot be sent for the subsequent requests. When a message is successfully sent, the message ID and the time gap between transmission/response are set in the HMSMessageID and HMSTimeStamp properties.
-
Prototype
# include <usrinc/hmsapi.h> int hms_sendex (HMS_PHND *prod, hms_msg_t *msg, int dlvmode, int priority, int ttl, int flags) -
Parameter
Parameter Description prod
Handle pointer to a producer to send a message.
msg
Pointer to a message to send.
dlvmode
Specifies the delivery mode.
-
HMS_DLV_NON_PERSISTENT
-
HMS_DLV_PERSISTENT
priority
Message priority. Currently not used.
ttl
Time to live, a message’s validity period. (Default value: 0, unit: seconds)
flags
Currently not used.
-
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the PROD or MSG parameter is null, the TTL parameter is smaller than 0, the DLVMODE parameter is invalid, or the size of MSG is too small to specify next properties.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEOS]
An HMS operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPETIME]
Timeout has occurred.
[TPEPROTO]
The function was called in an improper context.
[TPENOENT]
The message was sent by using a closed producer.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_PHND *prod; hms_msg_t *msg; ... session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates the topic type of a producer */ prod = hms_create_publisher(session, dest, "producer_1", 0); if (prod == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } ... ret = hms_set_body(msg, buf, size); if (ret < 0) { error processing } /* Sends a persistent message to a destination */ ret = hms_sendex(prod, msg, HMS_DLV_PERSISTENT, 0, 60, 0); if (ret < 0) { error processing } ... hms_free(msg); hms_close_publisher(prod, 0); /* Closes the session */ ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_send()
4.8. hms_send
The hms_send function sends a message only with basic settings. Messages are delivered in the non-persistent mode. The priority or validity period of a message is not specified when the message is sent. This function operates the same as like hms_sendex().
-
Prototype
# include <usrinc/hmsapi.h> int hms_send (HMS_PHND *prod, hms_msg_t *msg, int flags)
-
Parameter
Parameter Description prod
Handle pointer to the producer to send the message to.
msg
Pointer to a message to send.
flags
Currently not used.
-
Return Value
Return Value Description 1
Function call is successful.
-1
Function call failed. tperrno is set to the error code.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the PROD or MSG parameter is null, the TTL parameter is smaller than 0, the DLVMODE parameter is invalid, or the size of MSG is too small to specify next properties.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEOS]
An HMS operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPETIME]
Timeout has occurred.
[TPEPROTO]
The function was called in an improper context.
[TPENOENT]
The message was sent by using a closed producer.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_PHND *prod; hms_msg_t *msg; ... session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates the topic type of a producer */ prod = hms_create_publisher(session, dest, "producer_1", 0); if (prod == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } ret = hms_set_body(msg, buf, size); if (ret < 0) { error processing } /* Sends the message to a destination */ ret = hms_send(prod, msg, 0); if (ret < 0) { error processing } ... hms_free(msg); hms_close_publisher(prod, 0); /* Closes the session */ ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_sendex()
5. Consumer API
Consumer APIs are used for creating and closing the topic or the queue types of consumers.
5.1. hms_create_consumer
This hms_create_consumer creates a consumer that will receive a message from the destination and returns the consumer’s handle. If a message selector is set, the consumer can only receive the messages that meet the specified condition.
When a producer sends a message, the service to immediately receive the message can be specified in an async session. When a producer is created in an async session, svcname must be specified. However, svcname must not be specified in a non-async session. In addition, a client can only receive the messages that meet a condition by setting a message selector. For more information about a message selector, refer to Using a Message Selector.
-
Prototype
# include <usrinc/hmsapi.h> HMS_CHND * hms_create_consumer (HMS_SHND *sess, char *des, int destype, char *name, char *msgselector, char *svcname, int flags) -
Parameter
Parameter Description sess
Session pointer used to receive a message.
des
Name of a destination to receive the message.
destype
Destination Type.
-
MS_QUEUE
-
HMS_TOPIC
name
Name of a consumer to create.
msgselector
Statement of a message selector.
svcname
Name of a service to receive the message in an async session. (required in an async session)
flags
Currently not used.
-
-
Return Value
Return Value Description A consumer’s handle
The function call succeeded.
NULL
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the SESS or DES parameter is null, the length of the DES, NAME, MSGSELECTOR, or SVCNAME parameter exceeds the specified length, or the SVCNAME parameter is not specified in an async session.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEPROTO]
The function was called in an improper context. For example, this error may occur when another consumer already uses the svcname in an async session, or the svcname is specified in a non-async session, or the consumer name is not specified to create a durable subscriber.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOENT]
There is no destination to which the message can be sent, or the destination is inactive.
[TPEITYPE]
The destination type does not match the destination of the consumer that will be created.
[TPEOS]
An HMS or an operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPEMATCH]
The consumer name is already registered in HMS.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates the queue type of a consumer */ cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } ... ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } ... hms_free(msg); /* Closes the consumer */ hms_close_consumer(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_consumer()
5.2. hms_create_receiver
The hms_create_receiver function creates a receiver that will receive a message from the destination of the queue type. This function operates the same as hms_create_consumer().
-
Prototype
# include <usrinc/hmsapi.h> HMS_CHND * hms_create_receiver (HMS_SHND *sess, char *des, char *name, char *msgselector, char *svcname, int flags) -
Parameter
Parameter Description sess
Session pointer used to receive a message.
des
Name of a destination to receive the message.
name
Name of a receiver to create.
msgselector
Statement of a message selector.
svcname
Name of a service to receive the message in an async session. (required in an async session)
flags
Currently not used.
-
Return Value
Return Value Description A consumer’s handle
The function call succeeded.
NULL
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the DES, NAME, MSGSELECTOR or SVCNAME parameter exceeds the specified length, or the SVCNAME parameter is not specified in an async session.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEPROTO]
Another consumer is already using the svcname in an async session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOENT]
There is no destination to which the message can be sent, or the destination is inactive.
[TPEITYPE]
The destination type does not match the destination of the receiver that will be created.
[TPEOS]
An HMS or an operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPEMATCH]
The name is already registered in HMS.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates the queue type of a receiver */ cons = hms_create_receiver(session, dest, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } ... ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } ... hms_free(msg); /* Closes a receiver */ hms_close_receiver(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_receiver()
5.3. hms_create_subscriber
The hms_create_subscriber function creates a subscriber that will receive a message from the destination of the topic type. It operates the same as hms_create_consumer().
-
Prototype
# include <usrinc/hmsapi.h> HMS_CHND * hms_create_subscriber (HMS_SHND *sess, char *des, char *name, char *msgselector, char *svcname, int flags) -
Parameter
Parameter Description sess
Session pointer used to receive a message.
des
Name of a destination to receive the message.
name
Name of a subscriber to create.
msgselector
Statement of a message selector
svcname
Name of a service to receive the message in an async session. (required in an async session)
flags
Currently not used.
-
Return Value
Return Value Description A consumer’s handle
The function call succeeded.
NULL
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the DES, NAME, MSGSELECTOR or SVCNAME parameter exceeds the specified length, or the SVCNAME parameter is not specified in an async session.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEPROTO]
Another consumer is already using the svcname in an async session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOENT]
There is no destination to which the message can be sent, or the destination is inactive.
[TPEITYPE]
The destination type does not match the destination of the subscriber that will be created.
[TPEOS]
An error has occurred in HMS or OS. For example, memory for an internally used buffer is failed to be allocated.
[TPEMATCH]
The name is already registered in HMS.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates the topic type of a subscriber */ cons = hms_create_subscriber(session, dest, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } ... ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } ... hms_free(msg); /* Closes the subscriber */ hms_close_subscriber(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_subscriber()
5.4. hms_create_durable_subscriber
The hms_create_durable_subscriber function creates a durable subscriber that will receive a message from the destination of the topic type.
A durable subscriber ensures that messages are reliably received. HMS keeps messages until durable subscribers successfully receive the messages. Since HMS identifies each durable subscriber with its names, each durable subscriber must use a unique name.
To delete a durable subscription, unsubscribing process must be performed as well as using hms_close_durable_subscriber(). Without this process, all the messages that the permanant subscriber has not received will not be removed from the memory to wait until they are received or unsubscribing is performed.
-
Prototype
# include <usrinc/hmsapi.h> HMS_CHND * hms_create_durable_subscriber (HMS_SHND *sess, char *des, char *name, char *msgselector, char *svcname, int flags) -
Parameter
Parameter Description sess
Session pointer used to receive a message.
des
Name of a destination to receive the message.
name
Name of a durable subscriber to create.
msgselector
Statement of a message selector.
svcname
Name of a service that will receive a message in an async session. (required in an async session)
flags
Currently not used.
-
Return Value
Return Value Description A consumer’s handle
The function call succeeded.
NULL
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the DES, NAME, MSGSELECTOR or SVCNAME parameter exceeds the specified length, or the SVCNAME parameter is not specified in an async session.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEPROTO]
Another consumer is already using the svcname in an async session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOENT]
There is no destination to which the message can be sent, or the destination is inactive.
[TPEITYPE]
The destination type does not match the destination of the durable subscriber that will be created.
[TPEOS]
An HMS or an operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPEMATCH]
The name is already registered in HMS.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates a durable subscriber */ cons = hms_create_durable_subscriber(session, dest, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } ... ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } ... hms_free(msg); /* Closes the durable subscriber */ ret = hms_unsubscribe_durable_subscriber(session, dest, "consumer_1", 0); if (ret < 0) { error processing } ret = hms_close_consumer(cons, 0); if (ret < 0) { error processing } ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_close_durable_subscriber()
5.5. hms_close_consumer
The hms_close_consumer function closes the consumer and returns the allocated resources.
-
Prototype
# include <usrinc/hmsapi.h> int hms_close_consumer (HMS_CHND *cons, int flags)
-
Parameter
Parameter Description cons
Handle pointer of a consumer to close.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the CONS parameter is null.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Related Functions
hms_create_consumer()
5.6. hms_close_receiver
The hms_close_receiver function closes the receiver of the queue type of the receiver and returns the allocated resources. This function operates the same as hms_close_consumer().
-
Prototype
# include <usrinc/hmsapi.h> int hms_close_receiver (HMS_CHND *cons, int flags)
-
Parameter
Parameter Description cons
Handle pointer to a receiver to close.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the CONS parameter is null.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Related Functions
hms_create_receiver()
5.7. hms_close_subscriber
The hms_close_subscriber function closes the subscriber of the topic type and returns the allocated resources. This function operates the same as hms_close_consumer().
-
Prototype
# include <usrinc/hmsapi.h> int hms_close_subscriber (HMS_CHND *cons, int flags)
-
Parameter
Parameter Description cons
Handle pointer to a subscriber to close.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the CONS parameter is null.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Related Functions
hms_create_subscriber()
5.8. hms_close_durable_subscriber
The hms_close_durable_subscriber function closes the durable subscriber and returns the allocated resources. This function operates the same as hms_close_consumer(). To delete a durable subscription, unsubscribing process must be performed after hms_close_durable_subscriber(). If this process is not performed, a message waits in memory until a subscriber receives the message or the unsubscribing process is performed.
-
Prototype
# include <usrinc/hmsapi.h> int hms_close_durable_subscriber (HMS_CHND *cons, int flags)
-
Parameter
Parameter Description cons
Handle pointer to a durable subscriber to close.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the CONS parameter is null.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... session = hms_create_session(hms, 1, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates a durable subscriber */ cons = hms_create_durable_subscriber(session, dest, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } ... ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } ... hms_free(msg); /* Closes a durable subscriber */ ret = hms_close_consumer(cons, 0); if (ret < 0) { error processing } ... ret = hms_unsubscribe_durable_subscriber(session, dest, "consumer_1", 0); if (ret < 0) { error processing } ... ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_create_durable_subscriber()
5.9. hms_recvex
The hms_recvex function receives a message from the destination. Timeout can be set. If it is set to 0, the consumer will wait until the message arrives. If a message selector is set when a consumer is created, the consumer only receives the messages that meet the specified condition. A message buffer must have been created by using hms_alloc().
-
Prototype
# include <usrinc/hmsapi.h> int hms_recvex (HMS_CHND * cons, hms_msg_t **msg, long timeout, int flags)
-
Parameter
Parameter Description cons
Handle pointer to a consumer to receive a message.
msg
Message buffer allocated with hms_alloc().
timeout
Timeout (Default value: 0, unit: seconds).
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the CONS or MSG parameter is null, or the TIMEOUT parameter is set to a negative number.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEOTYPE]
An invalid message was passed as an argument.
[TPEITYPE]
An invalid message was received.
[TPETIME]
Timeout has occurred.
[TPENOENT]
The message was received with an already closed consumer. The producer and the consumer that were created within a session may have been closed when the session was closed.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... /* Creates a session in the general mode */ session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } /* Receives a message (timeout is set to 20 seconds) */ ret = hms_recvex(cons, &msg, 20, 0); if (ret < 0) { error processing } ret = hms_ack(msg, HMS_ACK_ONE); if (ret < 0) { error processing } ... /* Releases the message buffer */ hms_free(msg); hms_close_consumer(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_recv(), hms_create_consumer(), hms_create_receiver(),hms_create_subscriber(),
hms_create_durable_subscriber(), hms_ack(), hms_commit(), hms_rollback()
5.10. hms_recv
This function waits until a message arrives from the destination. It operates the same as hms_recvex() (timeout = 0)
-
Prototype
# include <usrinc/hmsapi.h> int hms_recvex (HMS_CHND * cons, hms_msg_t **msg, int flags)
-
Parameter
Parameter Description cons
Handle pointer to a consumer to receive the message
msg
Message buffer allocated with hms_alloc().
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the CONS or MSG parameter is null.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEOTYPE]
An invalid message was passed as an argument.
[TPEITYPE]
An invalid message was received.
[TPETIME]
Timeout has occurred.
[TPENOENT]
The message was received with an already closed consumer. The producer and the consumer that were created within a session may have been closed when the session was closed.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_CHND *cons; hms_msg_t *msg; ... /* Creates a session in the general mode */ session = hms_create_session(hms, 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } cons = hms_create_consumer(session, dest, HMS_QUEUE, "consumer_1", NULL, NULL, 0); if (cons == NULL) { error processing } msg = hms_alloc(session, size); if (msg == NULL) { error processing } /* Receives a message */ ret = hms_recv(cons, &msg, 0); if (ret < 0) { error processing } ret = hms_ack(msg, HMS_ACK_ONE); if (ret < 0) { error processing } ... /* Releases the message buffer */ hms_free(msg); hms_close_consumer(cons, 0); ret = hms_close_session(session, 0); if (ret < 0) { error processing } ... } -
Related Functions
hms_recv(), hms_create_consumer(), hms_create_receiver(), hms_create_subscriber(), hms_create_durable_subscriber(), hms_ack(), hms_commit(), hms_rollback()
6. Queue Browser API
QueueBrowser APIs are divided into the APIs for creating and closing QueueBrowser and the APIs for browsing messages.
6.1. hms_create_browser
The hms_create_browser function creates QueueBrowser that can browse messages in the current destination and returns the browser’s handle. QueuBrowser can only be created for the destination of the queue type. If a message selector is set when a browser is created, only the messages that meet the specified condition can be browsed.
-
Prototype
# include <usrinc/hmsapi.h> HMS_BHND * hms_create_browser (HMS_SHND *sess, char *queue, char *msgselector, int flags)
-
Parameter
Parameter Description sess
Session pointer using QueueBrowser.
queue
Name of a queue to browse.
msgselector
Statement of a message selector.
flags
Sets one of the following:
-
HMS_QB_FIRST: Browses the messages available in the destination in the order they were sent.
-
0: Browses the messages in the destination from the most recently sent message. (Default)
-
-
Return Value
Return Value Description Pointer to Browser Handle
The function call succeeded.
NULL
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the SESS or QUEUE parameter is null, or the length of the queue or the msgselector exceeds the specified length.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPENOENT]
There is no destination to which the message can be sent, or the destination is inactive.
[TPEITYPE]
The destination that was sent to the queue is not the queue type.
[TPEOS]
An HMS or an operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_BHND *browser; hms_msg_t *msg; char buf[100]; long len = 100; ... session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } /* Creates QueueBrowser */ browser = hms_create_browser(session, "queue1", "HMSType = 'cat' AND weight < 3"), 0); if (brow == NULL) { error processing } ... msg = hms_alloc(session, 1024); if (msg == NULL) { error processing } buf = tpalloc("STRING", NULL, 0); if (buf == NULL) { error processing } /* Gets message data through QueueBrowser */ hms_browser_nextmsg(browser, &msg, 0); if (ret == -1) { error processing } ret = hms_get_body(msg, buf, strlen(buf)); if (ret == -1) { error processing } else printf("message : %s\n", buf); ... /* Closes QueueBrowser */ ret = hms_close_browser(browser, 0); if (ret == -1) { error processing } ret = hms_close_session(session, 0); if (ret == -1) { error processing } ... } -
Related Functions
hms_close_browser()
6.2. hms_close_browser
The hms_close_browser function closes QueueBrowser and returns allocated resources.
-
Prototype
# include <usrinc/hmsapi.h> int hms_close_browser (HMS_BHND *browser, int flags)
-
Parameter
Parameter Description browser
Pointer to the browser handle.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the BROWSER parameter is null.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_BHND *browser; hms_msg_t *msg; char buf[100]; long len = 100; ... session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } browser = hms_create_browser(session, "queue1", "HMSType = 'cat' AND weight < 3"), 0); if (brow == NULL) { error processing } ... hms_browser_nextmsg(browser, &msg, 0); if (ret == -1) { error processing } ... /* Closes QueueBrowser */ ret = hms_close_browser(browser, 0); if (ret == -1) { error processing } ret = hms_close_session(session, 0); if (ret == -1) { error processing } ... } -
Related Functions
hms_create_browser()
6.3. hms_browser_nextmsg
The hms_browser_netmsg function browses messages in order, starting from the most recently received message. This function internally behaves similar to hms_recv(), but it is different from hms_recv() in that it only browses messages and does not consume the messages from the queue.
If flags is set to HMS_QB_FIRST when QueueBrowser is created with hms_create_browser(), messages are browsed in the order they were sent to the destination. If the default value is set (0), messages are browsed from the most recently received message (the end of the queue).
-
Prototype
# include <usrinc/hmsapi.h> int hms_browser_nextmsg (HMS_BHND *browser, hms_msg_t **msg, int flags)
-
Parameter
Parameter Description browser
Pointer to the browser handle.
msg
Pointer to the message buffer.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error may occur when the BROWSER or MSG parameter is null.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
[TPECLOSE]
A session connection to HMS has been disconnected. Close the current session with hms_close_session(), and then create a new session.
[TPEOS]
An HMS or an operating system error occurred. For example, this error may occur due to an internal memory buffer allocation failure.
[TPEMATCH]
There is no message that can be browsed in the destination.
[TPENOREADY]
The HMS is in the NOT READY state.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_BHND *browser; hms_msg_t *msg; char buf[100]; long len = 100; ... session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } browser = hms_create_browser(session, "queue1", "HMSType = 'cat' AND weight < 3"), 0); if (brow == NULL) { error processing } ... msg = hms_alloc(session, 1024); if (msg == NULL) { error processing } buf = tpalloc("STRING", NULL, 0); if (buf == NULL) { error processing } /* Gets message data through QueueBrowser */ hms_browser_nextmsg(browser, &msg, 0); if (ret == -1) { error processing } ret = hms_get_body(msg, buf, strlen(buf)); if (ret == -1) { error processing } else printf("message : %s\n", buf); ... ret = hms_close_browser(browser, 0); if (ret == -1) { error processing } ret = hms_close_session(session, 0); if (ret == -1) { error processing } ... } -
Related Functions
hms_create_browser(), hms_browser_get_queue(), hms_browser_get_msgselector()
6.4. hms_browser_get_msgselector
The hms_browser_get_msgselector function obtains the statement of the message selector that was specified when the browser was created.
The message selector statement that is set when a browser is created will be copied to a buffer, and the length of the statement will be specified in the LEN parameter. The buffer must be large enough to include the statement, and the size of the buffer must have been specified. If the size of the buffer is smaller than the length of the message selector statement, or a message selector is not specified, -1 will be returned.
-
Prototype
# include <usrinc/hmsapi.h> int hms_browser_get_msgselector(HMS_BHND *browser, char *buf, long *len, int flags)
-
Parameter
Parameter Description browser
Pointer to the browser handle.
buf
Buffer to copy the message selector statement to.
len
Length of the message selector statement is returned when the size of the buffer is specified.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error. This error occurs if browser or buf is NULL, or if the LEN (the size of the buffer) parameter is smaller than the length of the message selector statement.
[TPENOENT]
The message selector is not specified.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_BHND *browser; hms_msg_t *msg; char buf[100]; long len = 100; ... session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } browser = hms_create_browser(session, "queue1", "HMSType = 'cat' AND weight < 3"), 0); if (brow == NULL) { error processing } ... /* Gets a statement of a message selector */ ret = hms_browser_get_msgselector(browser, buf, &len); if (ret == -1) { error processing } else printf("Message Selector : %s\n", buf); ... ret = hms_close_browser(browser, 0); if (ret == -1) { error processing } ret = hms_close_session(session, 0); if (ret == -1) { error processing } ... } -
Related Functions
hms_create_browser(), hms_browser_nextmsg(), hms_browser_get_queue()
6.5. hms_browser_get_queue
The hms_browser_get_queue function copies the name of the destination that was specified when the browser was created to a buffer, and specifies the length of the name in the LEN parameter. The buffer must be large enough to include the destination name, and its size must be set before calling the API.
-
Prototype
# include <usrinc/hmsapi.h> int hms_browser_get_queue (HMS_BHND * browser, char *buf, long *len, int flags)
-
Parameter
Parameter Description browser
Pointer to the browser handle.
buf
Buffer to copy the destination name to.
len
Length of the destination name is returned when the size of the buffer is specified.
flags
Currently not used.
-
Return Value
Return Value Description 1
The function call succeeded.
-1
The function call failed if the size of the buffer to be copied is smaller than the destination name. The error code is set in tperrno.
-
Errors
One of the following values is set to tperrno.
Error Code Description [TPEINVAL]
Input parameter error.
This error may occur if browser or buf is NULL, or if the LEN (the size of the buffer) parameter is smaller than the length of the destination name.
[TPESYSTEM]
An HMS system error occurred. Detailed error information is recorded in the system log file.
-
Example
#include <stdio.h> #include <usrinc/atmi.h> #include <usrinc/hmsapi.h> main(int argc, char* argv[]) { HMS_SHND *session; HMS_BHND *browser; hms_msg_t *msg; char buf[100]; long len = 100; ... session = hms_create_session("svghms", 0, HMS_AUTO_ACK, 0); if (session == NULL) { error processing } browser = hms_create_browser(session, "queue1", "HMSType = 'cat' AND weight < 3"), 0); if (brow == NULL) { error processing } ... /* Gets the name of a destination */ ret = hms_browser_get_queue(browser, buf, &len, 0); if (ret == -1) { error processing } else printf("Destination : %s\n", buf); ... ret = hms_close_browser(browser, 0); if (ret == -1) { error processing } ret = hms_close_session(session, 0); if (ret == -1) { error processing } ... } -
Related Functions
hms_create_browser(), hms_browser_nextmsg(), hms_browser_get_msgselector()