Using a server service object

These examples shows how to define, use, and alter a server service object to start a trigger monitor or other program.

Before you begin

Note: These examples require you to run MQSC commands. How you do this varies by platform. See Administering IBM® MQ using MQSC commands.

These examples are written with UNIX style path separator characters, except where otherwise stated.

Procedure

Define a server service object, using the DEFINE SERVICE MQSC command:
```
DEFINE SERVICE(S1) +
CONTROL(QMGR) +
SERVTYPE(SERVER) +
STARTCMD('+MQ_INSTALL_PATH+bin/runmqtrm') +
STARTARG('-m +QMNAME+ -q ACCOUNTS.INITIATION.QUEUE') +
STOPCMD('+MQ_INSTALL_PATH+bin/amqsstop') +
STOPARG('-m +QMNAME+ -p +MQ_SERVER_PID+')
```
Where:
- +MQ_INSTALL_PATH+ is a token representing the installation directory.
- +QMNAME+ is a token representing the name of the queue manager.
- ACCOUNTS.INITIATION.QUEUE is the initiation queue.
- amqsstop is a sample program provided with IBM MQ which requests the queue manager to break all connections for the process ID. amqsstop generates PCF commands, therefore the command server must be running.
- +MQ_SERVER_PID+ is a token representing the process ID passed to the stop program.
See Using replaceable inserts on service definitions for a list of the common tokens.
An instance of the server service object executes when the queue manager is next started. However, you can start an instance of the server service object immediately with the START SERVICE MQSC command:
```
START SERVICE(S1)
```
Display the status of the server service process, using the DISPLAY SVSTATUS MQSC command:
```
DISPLAY SVSTATUS(S1)
```
Alter the server service object and have the updates picked up by manually restarting the server service process, using the ALTER SERVICE MQSC command.

The server service object is altered so that the initiation queue is specified as JUPITER.INITIATION.QUEUE.
```
ALTER SERVICE(S1) +
STARTARG('-m +QMNAME+ -q JUPITER.INITIATION.QUEUE')
```
Note: A running service does not pick up any updates to its service definition until it is restarted.
Restart the server service process so that the alteration is picked up, using the STOP SERVICE and START SERVICE MQSC commands:
```
STOP SERVICE(S1)
```
Followed by:
```
START SERVICE(S1)
```
The server service process is restarted and picks up the alterations made in 4.
Note: The MQSC command, STOP SERVICE, can only be used if a STOPCMD argument is specified in the service definition.

More examples of passing arguments

Define a server service object to start a program called runserv when a queue manager is started.
Do this using the DEFINE SERVICE MQSC command.

This example is written with Windows style path separator characters.

One of the arguments that is passed to the starting program is a string containing a space. This argument needs to be passed as a single string. To achieve this, double quotation marks are used as shown in the following command to define the command service object.
```
DEFINE SERVICE(S1) SERVTYPE(SERVER) CONTROL(QMGR) +
STARTCMD('C:\Program Files\Tools\runserv.exe') +
STARTARG('-m +QMNAME+ -d "C:\Program Files\Tools\"') +
STDOUT('C:\Program Files\Tools\+MQ_SERVICE_NAME+.out')


DEFINE SERVICE(S4) +
CONTROL(QMGR) +
SERVTYPE(SERVER) +
STARTCMD('C:\Program Files\Tools\runserv.exe') +
STARTARG('-m +QMNAME+ -d "C:\Program Files\Tools\"') +
STDOUT('C:\Program Files\Tools\+MQ_SERVICE_NAME+.out')
```
Where:
- +QMNAME+ is a token representing the name of the queue manager.
- C:\Program Files\Tools\ is a string containing a space, which will be passed as a single string.
Define a server service object that can be used to automatically start the Trigger Monitor when the queue manager starts.
Do this using the DEFINE SERVICE MQSC command.
```
DEFINE SERVICE(TRIG_MON_START) +
CONTROL(QMGR) +
SERVTYPE(SERVER) +
STARTCMD('runmqtrm') +
STARTARG('-m +QMNAME+ -q +IQNAME+')
```
Where:
- +QMNAME+ is a token representing the name of the queue manager.
- +IQNAME+ is an environment variable defined by the user in one of the service.env files representing the name of the initiation queue.