HMS Management

This chapter describes how to build HMS and how to start and terminate HMS and check its status.

1. Building 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 the storage to be used, HMS needs to be built with library of the corresponding storage when an external storage is used.

1.1. Pre-Build Tasks

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

In addition to 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.

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

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)
~
~

1.3. Building and Verifying HMS

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.

2. Starting and Stopping HMS

HMS operates while Tmax is running. If Tmax is terminated, Tmax must be started to use HMS. Tmax and HMS can be started together using the tmboot command without any options. If only the Tmax system process is running, HMS must be started separately.

The followings are the commands to start and stop a specified HMS:

  • Start

    tmboot -q <SVGNAME>

  • Stop

    tmdown -q <SVGNAME>

The <SVGNAME> used in the start and stop commands is the name of the SVRGROUP section defined in the Tmax configuration file. For more information, refer to SVRGROUP Section.

3. Checking 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.

For more information about tmadmin, refer to Tmax Administration Guide.

3.1. Viewing 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 displayed as follows.

$$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 each field.

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.

3.2. Viewing Client Information

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

tmadmin st -q <DestinationName> -c

When the command is executed, the client information will be displayed as follows.

$$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 each field.

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: ublisher 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.