Chapter 4. HMS Management

4.1. Building an HMS

HMS manages crucial parts of the information within a storage to provide the reliability. HMS uses the libraries in which the storage function is implemented.

Not only storages supported by default but also external storages installed in a user's operating environment can be used. Since supported libraries are different according to a storage to be used, HMS needs to be built with library of a corresponding storage when an external storage is used.

4.1.1. Preparation

When using an external storage, HMS needs to be newly built with the library of the external storage. To build the HMS, the storage must be installed in OS and the library that supports the storage is required. The environment variables needs to be correctly specified to use the storage.

For example, if Oracle's product is used in a UNIX system as an external storage, the following environment variables must be checked.

ORACLE_HOME=/data/home/oracle
PATH=$PATH:$ORACLE_HOME/bin
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib

Besides the storage's library to be used by HMS, the HMS library provided by Tmax must be prepared. The HMS library named libhms.a is provided when the default storage is used. The HMS library with a name of the 'libhms_<STORAGE>.a' format is provided when an external storage is used.

For example, if Oracle's product is used as an external storage, the HMS library named libhms_ora.a is provided.

Note

If there is no HMS library for an external storage to be used, contact TmaxSoft's product representative.

4.1.2. Makefile

When an external storage is used, HMS is built with Makefile. Makefile needs to be modified according to the user's platform and the development environment.

The following is an example of HMS Makefile to use Oracle's product as an external storage in the Linux environment.

# HMS Makefile for Oracle
# Linux
TARGET  = hms_ora
APOBJ   = dumy.o
APPDIR  = $(TMAXDIR)/appbin
TMAXLIBD= $(TMAXDIR)/lib
TMAXLIBS= -lhms_ora -lpthread 
 
CFLAGS  = 

all: $(TARGET)
 
include $(ORACLE_HOME)/precomp/lib/env_precomp.mk
ORALIBDIR = $(LIBHOME)
ORALIB  = $(PROLDLIBS)
 
$(TARGET): $(APOBJ)
    $(CC) $(CFLAGS) -o $(TARGET) -L$(TMAXLIBD) -L$(ORALIBDIR) $(ORALIB) $(APOBJ) 
    $(TMAXLIBS)
    mv $(TARGET) $(APPDIR)/.
 
$(APOBJ):
    $(CC) $(CFLAGS) -c dumy.c
 
clean:
    -rm -f core $(TARGET) $(APPDIR)/$(TARGET)
~                                                                                                             
~

4.1.3. HMS Build and Verification

When HMS is built with the makefile, the HMS will be moved to the appbin directory under $TMAXDIR. If it is not moved to the appbin directory, manually copy the HMS to the directory. The file name of the HMS can be specified by the user. The specified HMS name becomes the value of HMSNAME in the SVRGROUP clause of the Tmax environment configuration file.

4.2. Starting and Terminating an HMS

HMS can perform in the state that Tmax is running. If Tmax is terminated, Tmax must be started to use HMS. Tmax and HMS can be started together with the tmboot command without specifying any option. If only Tmax is started, HMS must be started separately.

The followings are the commands for starting and terminating a specified HMS.

Start
```
tmboot -q <SVGNAME>
```
Terminate
```
tmdown -q <SVGNAME>
```

<SVGNAME> used for the start and termination is the a name of the SVRGROUP clause defined in the Tmax environment configuration file. For more information, refer to "2.1.3. SVRGROUP Clause".

4.3. Inquiring the HMS Status

It is necessary to manage the information about the HMS status while it is running; current environment configuration, system status, clients connected to HMS, and the delivered, processed, or failed messages. Use the tmadmin program provided by Tmax to manage local and global HMS information.

Note

For more information about tmadmin, refer to the "Tmax Administrator's Guide".

4.3.1. Inquiring the Destination Information

The st command in tmadmin is used to check the list of destinations and the messages and client information being processed in each destination.

tmadmin st -q

When the command is executed, the information about the local HMS environment will be inquired as shown below.

$$2 Locke2 (tmadm): st -q
 ----------------------------------------------------------------------------------
 G  dest       cqcount   type   apqcnt   acqcnt  f_dscrd  t_dscrd cons_cnt prod_cnt
 ----------------------------------------------------------------------------------
 -  queue01         58  QUEUE      169      111        0        0       30        5
 -  topic01         32  TOPIC       42      283        0        0       28        3

The following describes the information of the inquired fields.

Field	Description
G	Displays 0 when the destination is set to GLOBAL. Otherwise, a hyphen (-) will be displayed.
dest	Destination name specified in the HMS clause of the environment configuration file.
cqcount	Number of messages that has not been processed in the destination.
type	Destination type. Options are QUEUE or TOPIC.
apqcnt	Number of the accumulated messages.
acqcnt	Number of the messages processed by consumers. Since a single message must be received by all consumers in the destination of the TOPIC type, the acqcnt value may be greater than the apqcnt value.
f_dscrd	Number of the messages failed to process.
t_dscrd	Number of the failed messages because the TTL (Time to Live) has expired.
cons_cnt	Number of the consumers connected to the destination.
prod_cnt	Number of the producers connected to the destination.

4.3.2. Inquiring the Client Information

The st command in tmadmin is used to check the detailed information about each client in the specified destination.

tmadmin st -q <DESTNAME> -c

When the command is executed, the client information will be inquired as shown below.

$$3 Locke2 (tmadm): st -q queue01 -c
   ------------------------------------------------------------------------------
      sesi     clid     cname      clitype qcnt  cnt  f_dscrd t_dscrd   listener 
   ------------------------------------------------------------------------------
         0    0x39d prodasync        ARCV    49    0    0    0         ASYNCSVC
       0x1        0 prod41           SND      0   32    0    0                 
       0x1        0 prod42           SND      0   11    0    0                 
       0x1        0 cons51           RCV      3    0    0    0                 
       0x1        0 cons52           RCV      9    0    0    0                 

$$4 Locke2 (tmadm): st -q topic01 -c
   ------------------------------------------------------------------------------
      sesi     clid     cname      clitype qcnt  cnt  f_dscrd t_dscrd   listener 
   ------------------------------------------------------------------------------
       0x1        0 prod11           PUB      0    2    0    0                 
       0x1        0 prod12           PUB      0    1    0    0                 
       0x1        0 cons11           SUB     30    0    0    0                 
       0x2      0x2 prod21           PUB      0   16    0    0                 
       0x2      0x2 prod22           PUB      0    8    0    0                 
       0x2      0x2 cons21           SUB     23    0    0    0                 
       0x3        0 prod31           PUB      0    3    0    0                 
       0x4      0x4 cons41           ADSUB   32    0    0    0          ASYNCSVC2

The following describes the information of the inquired fields.

Field	Description
sesi	Session number that the client was created with.
clid	Client ID.
cname	Client name. The specified name is used as a parameter in the following APIs. hms_create_consumer, hms_create_sender, hms_create_subscriber, hms_create_producer, hms_create_receiver, hms_create_publisher
clitype	Type of the client connected to the destination. SND : Sender of the queue type (created with hms_create_sender()) PUB : Publisher of the topic type (created with hms_create_publisher()) RCV : Receiver of the queue type (created with hms_create_receiver()) SUB : Subscriber of the topic type (created with hms_create_subscriber()) DSUB : Durable subscriber of the topic type (created with hms_create_durable_subscriber()) ARCV : Receiver of the queue type created in an async session ASUB : Subscriber of the topic type created in an async session ADSUB : Durable subscriber of the topic type created in an async session
qcnt	Number of the messages that each subscriber contains.
cnt	Number of the messages sent or received by each client.
f_dscrd	Number of the messages failed to process.
t_dscrd	Number of the failed messages because the TTL (Time to Live) has expired.
listener	Name of the service to receive messages when the consumer was created in an async session.

Prev		Next
Chapter 3. API Functions	Home	Chapter 5. Examples