Table of Contents
This chapter describes various APIs that are needed to deliver messages via HMS.
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
| Name | Description |
|---|---|
| hms_create_session | Creates a session to HMS and returns the session handle. |
| hms_create_xa_session | Creates an XA session to HMS and returns the session handle |
| hms_create_async_session | Creates an async session and returns the session handle. |
| hms_close_session | Closes a session. |
| hms_unsubscribe_durable_subscriber | Unsubscribes the registration of a durable subscriber. |
| hms_commit | Commits a local transaction that involves the messages sent and received within the session. |
| hms_rollback | Rolls back a local transaction that involves the messages sent and received within a session. |
| hms_recover | Restarts transmitting the message which ACK has not been sent to the HMS among the messages sent and received within a session. |
Message API
| Name | Description |
|---|---|
| hms_alloc | Allocates a message buffer to use in a messaging service, and returns the buffer's pointer. |
| hms_free | Frees the memory allocated to a message buffer. |
| hms_get_property | Retrieves the information of a property with the name defined in the message. |
| hms_set_property | Specifies a property in the message with a specific name. |
| hms_get_body | Retrieves the data part of a message. |
| hms_set_body | Sets the data part of the message.. |
| hms_ack | Sends an ACK in response to a received message. |
Producer API
| Name | Description |
|---|---|
| hms_create_producer | Creates a producer that will send a message to a destination, and returns the producer's handle. |
| hms_create_sender | Creates a sender that will send s a message to the destination of the queue type. |
| hms_create_publisher | Creates a publisher that will send a message to the destination of the topic type. |
| hms_close_producer | Closes the producer and returns the allocated resources. |
| hms_close_sender | Closes the sender of the queue type and returns the allocated resources. |
| hms_close_publisher | Closes the publisher of the topic type and returns the allocated resources. |
| hms_sendex | Sends a message to the destination specified when the producer was created. |
| hms_send | Sends a message only with basic settings. |
Consumer API
| Name | Description |
|---|---|
| hms_create_consumer | Creates creates a consumer that will receive a message from the destination and returns the consumer's handle. |
| hms_create_receiver | Creates a receiver that will receive a message from the destination of the queue type. |
| hms_create_subscriber | Creates a subscriber that will receive a message from the destination of the topic type. |
| hms_create_durable_subscriber | Creates a durable subscriber that will receive a message from the destination of the topic type. |
| hms_close_consumer | Closes the consumer and returns the allocated resources. |
| hms_close_receiver | Closes the receiver of the queue type and returns the allocated resources. |
| hms_close_subscriber | Closes the subscriber of the topic type and returns the allocated resources. |
| hms_close_durable_subscriber | Closes a durable subscriber and returns the allocated resources. |
| hms_recvex | Receives a message from the destination. |
| hms_recv | Waits until a message arrives from the destination. |
QueueBrowser API
| Name | Description |
|---|---|
| hms_create_browser | Creates QueueBrowser inquire messages in the current destination and returns the browser's handle. |
| hms_close_browser | Closes QueueBrowser and returns allocated resources. |
| hms_browser_nextmsg | Inquires messages from the newest messages first. |
| hms_browser_get_msgselector | Obtains the statement of the message selector that was specified when the browser was created. |
| hms_browser_get_queue | 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. |
Session APIs are divided into the APIs for creating and closing sessions and the APIs for processing transactions.
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)
Parameters
| Parameter | Description |
|---|---|
| hms | Server group name of the HMS as specified in the SVRGROUP clause of the configuration file. |
| transacted | Options are: - 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 Values
| Return Value | Description |
|---|---|
| Pointer of an allocated message buffer | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| hms | Server group name of the HMS as specified in the SVRGROUP clause of the configuration file. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| The pointer of a created session's handle | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
The hsm_create_async_session 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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| The pointer of a created session's handle | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| sess | Session pointer to close. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| sess | Session pointer. |
| des | Name of the registered destination. |
| name | Name of the registered durable subscriber. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| sess | Session pointer. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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.
In an XA session, the tx_commit API must be used.
Prototype
#include <usrinc/hmsapi.h> int hms_rollback (HMS_SHND *sess, int flags)
Parameters
| Parameter | Description |
|---|---|
| sess | Session pointer. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
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)
Parameters
| Parameter | Description |
|---|---|
| sess | Session pointer. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
Session APIs are divided into the APIs for creating and closing sessions and the APIs for storing and inquiring the information of messages.
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 the section of each API.
Prototype
# include <usrinc/hmsapi.h> hms_msg_t * hms_alloc (HMS_SHND *sess, long size)
Parameters
| Parameter | Description |
|---|---|
| sess | Session pointer connected to HMS. |
| size | Size of the message buffer to allocate. |
Return Values
| Return Value | Description |
|---|---|
| Pointer of an allocated message buffer | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| msg | Message pointer to free. |
Return Values
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()
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 "3.5.1. hms_create_consumer" or "Appendix A. 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 "1.3.4. Messages".
Prototype
# include <usrinc/hmsapi.h>
int hms_get_property (hms_msg_t *msg, char *name, int *type, char *value,
long *len)
Parameters
| Parameter | Description |
|---|---|
| msg | Message pointer to a property. |
| name | Name of the property to retrieve. |
| type | Property type.
|
| 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 Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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 "3.5.1. hms_create_consumer" or "Appendix A. 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 "1.3.4. Messages".
Prototype
# include <usrinc/hmsapi.h>
int hms_set_property (hms_msg_t * msg, char *name, int type, char *value,
long len)
Parameters
| Parameter | Description |
|---|---|
| msg | Message pointer to a property. |
| name | Name of a property to retrieve. Reserved words cannot be used. |
| type | Property type.
|
| value | Pointer to the property. |
| len | Size of the buffer to specify. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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.
Prototype
# include <usrinc/hmsapi.h> int hms_ack (hms_msg_t *msg, int flags)
Parameters
| Parameter | Description |
|---|---|
| msg | Pointer to the message where an ACK will be sent. |
| flags | - 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 Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
Producer APIs are divided into the APIs for creating and closing the topic or queue types of producers.
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, is 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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| A producer's handle | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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 where a 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()
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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| A sender's handle | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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 where a 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()
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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| A publisher's handle | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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 where a 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()
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)
Parameters
| Parameter | Description |
|---|---|
| prod | Handle pointer to a producer to close. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| prod | Handle pointer to a sender to close. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| prod | Handle pointer to a publisher to close. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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.
The 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)
Parameters
| Parameter | Description |
|---|---|
| prod | Handle pointer to a producer to send a message. |
| msg | Pointer to a message to send. |
| dlvmode | Message transmission mode (HMS_DLV_NON_PERSISTENT or HMS_DLV_PERSISTENT). |
| priority | Message priority. Currently not used. |
| ttl | Time to live, a message's validity period. This value is set in seconds and the default value is 0. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
Consumer APIs are used for creating and closing the topic or the queue types of consumers.
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 "Appendix A. 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)
Parameters
| Parameter | Description |
|---|---|
| sess | Session pointer used to receive a message. |
| des | Name of a destination to receive the message. |
| destype | Destination type (MS_QUEUE or 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 Values
| Return Value | Description |
|---|---|
| A consumer's handle | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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 where a 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()
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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| A consumer's handle | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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 where a 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()
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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| A consumer's handle | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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 where a 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()
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)
Parameters
| 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 Values
| Return Value | Description |
|---|---|
| A consumer's handle | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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 where a 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()
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)
Parameters
| Parameter | Description |
|---|---|
| cons | Handle pointer of a consumer to close. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| cons | Handle pointer to a receiver to close. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| cons | Handle pointer to a subscriber to close. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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. Without this process, all the messages that the permanent 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> int hms_close_durable_subscriber (HMS_CHND *cons, int flags)
Parameters
| Parameter | Description |
|---|---|
| cons | Handle pointer to a durable subscriber to close. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
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)
Parameters
| Parameter | Description |
|---|---|
| cons | Handle pointer to a consumer to receive a message. |
| msg | Message buffer allocated with hms_alloc(). |
| timeout | Timeout (the unit: second, the default value: 0). |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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] | Incorrect MSG parameter. |
| [TPEITYPE] | Incorrect MSG parameter. |
| [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()
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)
Parameters
| Parameter | Description |
|---|---|
| cons | Handle pointer to a consumer to receive the message. |
| msg | Message buffer allocated with hms_alloc(). |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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] | Incorrect MSG parameter. |
| [TPEITYPE] | Incorrect MSG parameter. |
| [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()
QueueBrowser APIs are divided into the APIs for creating and closing QueueBrowser and the APIs for inquiring messages.
The hms_create_browser function creates QueueBrowser that can inquires 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 inquired.
Prototype
# include <usrinc/hmsapi.h>
HMS_BHND * hms_create_browser (HMS_SHND *sess, char *queue, char *msgselector,
int flags)
Parameters
| Parameter | Description |
|---|---|
| sess | Session pointer using QueueBrowser. |
| queue | Name of a queue to inquire. |
| msgselector | Statement of a message selector. |
| flags | - HMS_QB_FIRST: Inquires messages in the destination in the order they are sent. - 0 (the default value): Inquires messages in the destination from the newest messages first. |
Return Values
| Return Value | Description |
|---|---|
| A browser's handle pointer | Function call is successful. |
| NULL | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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 where a 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()
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)
Parameters
| Parameter | Description |
|---|---|
| browser | Browser's handle pointer. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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()
The hms_browser_netmsg function inquires messages from the newest messages first. This function internally behaves similar to hms_recv(), but it is different from hms_recv() in that it only inquires messages and does not consume the messages in a queue. If flags is set to HMS_QB_FIRST when QueueBrowser is created with hms_create_browser(), messages will be inquired in the order they arrive at the destination. If the flags is set to the default value (0), messages are inquired from the newest message first. (the end of a queue)
Prototype
# include <usrinc/hmsapi.h> int hms_browser_nextmsg (HMS_BHND *browser, hms_msg_t **msg, int flags)
Parameters
| Parameter | Description |
|---|---|
| browser | Handle pointer to the browser. |
| msg | Pointer to the message buffer. |
| flags | Currently not used. |
Return Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| 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 inquired 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()
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)
Parameters
| Parameter | Description |
|---|---|
| browser | Handle pointer to the browser. |
| 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 Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| Error Code | Description |
|---|---|
| [TPEINVAL] | Input parameter error. This error may occur when the LEN (the size of the buffer) parameter is smaller than the length of the message selector statement. |
| [TPENOENT] | A 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()
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 have been specified. If the size of a buffer is smaller than the length of the destination name, -1 will be returned.
Prototype
# include <usrinc/hmsapi.h> int hms_browser_get_queue (HMS_BHND * browser, char *buf, long *len, int flags)
Parameters
| Parameter | Description |
|---|---|
| browser | Handle pointer to the browser. |
| 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 Values
| Return Value | Description |
|---|---|
| 1 | Function call is successful. |
| -1 | Function call failed. fberror is set to the error code. |
Errors
One of the following values is set to fberrno.
| Error Code | Description |
|---|---|
| [TPEINVAL] | Input parameter error. This error may occur when 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()