Usage and Management

To use the RQ system to develop an application, two steps must be followed: Configuring RQ in the Tmax configuration file and developing actual applications. This chapter describes the steps and how to apply RQ when developing applications using various examples.

1. Environment Configuration

Before developing an actual application, the RQ system needs to be started and a basic configuration must be set. The RQ system is managed in a unit in a server group and requires proper definitions in the SVRGROUP section and RQ section of the Tmax configuration file.

For more information about the Tmax environment configuration file, refer to Tmax Administration Guide.

1.1. SVRGROUP Section

To use the RQ system, define the server groups that contain RQ. To do this, specify the SVGTYPE item to ‘RQMGR' in addition to the default items of the SVRGROUP section. The efficiency of system operations can be increased by configuring the CPC. RQ does not support COUSIN.

Set the SVRGROUP section in the environment configuration as follows:

*SVRGROUP
SVRGROUP Name    NODENAME = node-name,
                 CPC = number,
                 SVGTYPE = RQMGR,
                 TMSNAME= "POD"

  • SVRGROUP Name = string

    • Size: Up to 15 characters

    • Server group name. Must be unique in the SVRGROUP section.

  • NODENAME = string

    • Node name where a server group belongs to. The node name must be the same as the one defined in the NODE section.

  • CPC = numeric

    • Range: 4~128

    • If the RQ item, which sets the number of parallel communication channels between the RQS process and the CLH process, is not used, then this will be ignored. If RQ is used frequently, its process speed can be improved by maintaining multiple channels.

  • SVGTYPE = RQMGR

    • Server group type

      Value Description

      RQMGR

      Enables the use of RQ.

      TXRQMGR

      Enables the use of RQ in a transaction environment.

      The following must be noted when setting a transaction environment.

      • The RQ server group type (SVGTYPE) must be set to 'TXRQMGR' instead of 'RQMGR'.

      • The existing tpenq/tpdeq APIs do not support transactions.

      • tpenq_ctl and tpdeq_ctl cannot be bound into a single transaction.

      • When binding tpenq_ctl into a transaction, up to the process of storing in RQ can be handled as a transaction. Transactions are not supported for the svc call.

      • When setting a deq_time, svc call will be performed after the specified time. The format is "Current time + delay_time".

        The following is an example of seting delay_time to 10.

        time(&t); ctl->deq_time = t + 10;

      • deq_time cannot be used with a transaction.

  • TMSNAME = "POD"

    • RQ works the same way as the POD server. If TMSNAME is set to "POD", it starts only upon a tpenq request.

Example
*SVRGROUP
svg1    NODENAME = tmax1,
        CPC = 4,
        SVGTYPE=RQMGR

The following is an example configuration for using RQ in a transaction environment.

*SVRGROUP
Txrqsvg    NODENAME = tmaxh4,
           CPC = 4 ,
           SVGTYPE = TXRQMGR

1.2. RQ Section

Each server group can use one or more RQs. In the RQ section, set the management method of the RQ. The RQ section has the QSIZE, FILEPATH, BOOT, FSYNC, and BUFFERING fields. Among them, SVGNAME is mandatory.

Set the RQ section in the environment configuration as follows:

*RQ
RQ Name  SVGNAME = server-group-name,
         BOOT = COLD | WARM,
         QSIZE = number,
         BUFFERING = Y | N ,
         FSYNC = Y | N ,
         FILEPATH = file-path

  • RQ Name = string

    • Size: Up to 14 characters

    • Logical name of the RQ section. Multiple RQs can be defined in the RQ section. Each RQ name must be unique. In a single server group, multiple RQs can be defined.

  • SVGNAME = string

    • Server group name that uses RQ. The server group name must be defined in the SVRGROUP section.

  • BOOT = COLD | WARM

    • Default value: COLD

    • The BOOT field adjusts the data stored in RQ when the Tmax system reboots.

    • The following describes configurable values:

      Value Description

      COLD

      Deletes the data stored in a disk when the Tmax system restarts.

      WARM

      Enables data recovery in a queue after recovery from a system error.

  • QSIZE = numeric

    • Range: 1~2047Mbyte

    • Default value: 16Mbyte

    • RQ size can be specified. RQ is created in the TMAXDIR path by default. If the queue entries exceed the specified queue size as a result of continuous services, TPEQFULL will occur when performing tpenq(). The RQ size will not be increased automatically so the size must be set properly. If RQ data will not be stored even after a RQ file is written, the file will be deleted automatically when Tmax is terminated.

  • BUFFERING = Y | N

    • Default value: Y

    • Option to cache the RQ file content to memory.

    • The following describes a configurable value:

      Value Description

      N

      The RQ process will get relatively slower but the required memory will get smaller.

  • FSYNC = Y | N

    • Default value: Y

    • Even BUFFERING is set to 'N', OS does not store data to a disk directly but stores the data in a memory at most 30 seconds. This field eliminates such waiting time and stores the data in a memory to a disk.

    • The following describes configurable values:

      Value Description

      N

      Data might be lost when an error occurs in the system but the RQ process speed will get faster.

      Y

      RQ data does not use memory and is always stored in a disk safely but the process speed is slower than that when the value is set to 'N'.

  • FILEPATH = literal

    • Default value: $(TMAXDIR)/path/RQ name.data

    • Path to the file used by RQ. This field creates the RQ data files and must be defined with the entire file name and the directory name.

      TMAXDIR is a home directory of Tmax installation. Hereafter the Tmax home directory will be referred to as "TMAXDIR."

  • MAX_MEMQCOUNT = numeric

    • Default value: 1024

    • Maximum number of messages to save for the TPRQS_NON_PERSISTENT type, where data is stored only in memory instead in a file.

Example
*RQ
rqtest  SVGNAME = svg1,
        BOOT = COLD,
        QSIZE = 1024,
        BUFFERING = Y,
        FSYNC = Y,
        FILEPATH = "/user1/tmax/myrq.data"

2. System Management

The RQ system management is not different than that of the regular Tmax system. Administrators can start or terminate the RQ system separately and can check the RQ state information using tmadmin.

2.1. Starting and Shutting Down

tmboot

The RQ system starts along with the Tmax system with the tmboot command.

  • Usage

    $ tmboot [-q SVGNAME]
    Option Description

    [-q SVGNAME ]

    Starts only the RQ server group, which is given as an independent parameter.

  • Example

    • If the [-T] option is used, only Tmax will start. RQS will not start. The following shows the execution result:

      $ tmboot –T

TMBOOT for node(tmaxs7) is starting:
       TMBOOT: TMM is starting: Thu Aug 23 16:29:16 2012
       TMBOOT: CLL is starting: Thu Aug 23 16:29:16 2012
       TMBOOT: CLH is starting: Thu Aug 23 16:29:16 2012
(I) CLH9991 Current Tmax Configuration: Number of client handler(MINCLH) = 1
                Supported maximum user per node = 16040
                Supported maximum user per handler = 16040 [CLH0141]
       TMBOOT: TLM(tlm) is starting: Thu Aug 23 16:29:16 2012

    • If the [-q] option is used, the RQS corresponding to the server group that manages RQ can be started. The following shows the execution result:

      $ tmboot –q svg1

TMBOOT for node(tmaxs7) is starting:
       TMBOOT: SVR(rqs) is starting: Thu Aug 23 16:33:22 2012
tmdown

The RQ system is terminated by the tmdown command.

  • Usage

    $ tmdown [-q SVGNAME]
    Option Description

    [-q SVGNAME]

    Terminates only a specified RQ server group given as a parameter.

  • Example

    If the [-q] option is used, the RQS corresponding to the server group that manages a RQ can be terminated. The following shows the execution results:

    $ tmboot –q svg1

TMDOWN for node(tmaxs7) is starting:
       TMDOWN: RQS(_rqsvg:34) downed: Thu Aug 23 16:37:56 2012

2.2. State Information Management

Once the Tmax system starts, a system state can be managed using tmadmin, the management tool provided by Tmax.

The following are the two modes for execution in tmadmin:

  • Sub administrator mode

    In this mode, the state of a system operation can be checked but the system configuration cannot be changed. The following shows how to run the mode:

    $ tmadmin [–s]

  • Master administrator mode

    In this mode, the state of a system operation can be checked and the system configuration can be changed. The following shows how to run the mode:

    $ tmadmin [–m]

For more information about the tmadmin execution mode, refer to Tmax Administration Guide.
rqs

After executing tmadmin, the rqs command can be used to print the currently available RQ state or to manipulate the data in a disk queue.

  • Usage

    $$1 tmax1 (tmadm): rqstat (rqs) [-l] [-s rqname] [-f rqname] [-c rqname] [-a]
    Option Description

    [-l]

    Displays all available RQs.

    [-s rqname]

    Displays the state information of the specified RQ.

    [-f rqname]

    Handles services in the specified RQ.

    [-c rqname]

    Deletes the pending RQ.

    [-a]

    Displays state information of all RQs in a list.

    To handle RQ using the [-f] and [-c] options, you must enable master mode by specifying the tmadmin -m option.

  • Example

    • Displaying all RQ states (-a)

      Each record expresses the following items.

      $$1 tmaxi9 (tmadm): rqs -a

             rq1 RDY  0 0 0 0 0 5 5
total count : 1

      Printed data are displayed in the following format.

      rq name state request reply fail requestenqueued requestdequeued replyenqueued replydequeued

      The last record indicates the total count.

    • Displaying available RQs (-I)

      The following is an example of displaying available RQs.

      $$1 tmax1 (tmadm): rqs -l
list of available RQs:
rq1 rq2

    • Displaying the RQ State (-s)

      The following is an example of the RQ state.

      $$1 tmax1 (tmadm): rqs -s rq1
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Number of queue entries
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
request                       0
reply                         0
fail                          0
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Accumulated queue activities
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
request enqueued             0
request dequeued             0
reply enqueued               10
reply dequeued               0
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    • Handling the RQ services (-f)

      The following is an example of handling services accumulated in the RQ.

      $$1 tmax1 (tmadm): rqs -f rq2
RQ(rq2) flushed

    • Deleting RQ (-c)

      The following is an example of deleting the pending RQ.

      $$1 tmax1 (tmadm): rqs -c rq2
RQ(rq2) statics cleared