Service Objects

Service objects let the queue manager treat external programs as first-class citizens—start them when the queue manager starts, stop them cleanly at shutdown, and monitor whether they are running. While PROCESS definitions answer "which job should triggering launch?" and LISTENER definitions answer "which TCP port to open?", SERVICE definitions answer "which long-running companion binary should always ride alongside this QM?" Examples include custom file agents, bridge processes, or vendor adapters. This tutorial covers DEFINE SERVICE, STARTCMD and STOPCMD, STARTARG and STOPARG, STDOUT and STDERR, SERVTYPE and CONTROL, DISPLAY SVSTATUS, differences from trigger processes, and Linux container considerations.

SERVICE vs PROCESS vs LISTENER

All three live in the object repository but solve different problems. LISTENER binds a port for inbound TCP. PROCESS tells runmqtrm what executable to fire when a queue triggers. SERVICE tells the queue manager's service agent to run STARTCMD now and keep lifecycle aligned with the QM. Picking the wrong object type leads to programs that never start or start twice from competing mechanisms.

Explainer: Lifecycle with CONTROL(QMGR)

You strmqm QM1. The queue manager loads SERVICE definitions with CONTROL(QMGR) and SERVTYPE(SERVER). For each, it runs STARTCMD—perhaps /opt/agents/filepoller/bin/start.sh. The agent runs continuously, reading files and MQPUTting. Operators run endmqm; the queue manager runs STOPCMD so the agent flushes buffers and exits. Without STOPCMD, orphaned processes may hold files open or duplicate after restart. MANUAL control suits rare admin tools you do not want auto-started in DR failovers.

SERVTYPE SERVER vs COMMAND

SERVER is for daemons: one copy, monitored with DISPLAY SVSTATUS showing STATE(RUNNING) or STOPPED and operating system PID. COMMAND fits utilities you might fire repeatedly—cleanup scripts—where overlapping runs are acceptable and status tracking is less critical. Do not model your primary message bridge as COMMAND if two copies would corrupt shared files.

START SERVICE and DISPLAY SVSTATUS

Operators run START SERVICE(name) for MANUAL services or after fixing a failed auto-start. DISPLAY SVSTATUS(name) shows runtime state on distributed platforms. If STATE is STOPPED but you expect RUNNING, read STDERR, verify file permissions on STARTCMD, and confirm the service user can execute the binary. STOP SERVICE requests graceful shutdown via STOPCMD.

Security and Run-As Identity

Services run under the queue manager's service account unless configured otherwise on your platform. That account needs authority for whatever the program does—MQPUT, file read, database JDBC. Avoid STARTCMD that invokes shells with world-writable paths. Treat SERVICE definitions as privileged: alter authority should be limited to administrators.

Containers and Cloud

In Kubernetes, sidecar containers often replace SERVICE objects for auxiliary processes. Traditional VM installs still use SERVICE for co-located agents. If STARTCMD points outside the container image, the pod will fail. Embed agents in the image and use STDOUT to stream logs to your log stack via file tail sidecars.

Tutorial: Manual Lab Service

1
2
3
4
5
6
7
8
9
10
11
12
13
DEFINE SERVICE('LAB.ECHO.AGENT') REPLACE +
  SERVTYPE(SERVER) CONTROL(MANUAL) +
  STARTCMD('/opt/mq/lab/echo_agent.sh') +
  STOPCMD('/opt/mq/lab/echo_agent_stop.sh') +
  STARTARG('-m QM1') STOPARG('-m QM1') +
  STDOUT('/var/mqm/log/echo_agent.out') +
  STDERR('/var/mqm/log/echo_agent.err') +
  DESCR('Lab companion process')
START SERVICE('LAB.ECHO.AGENT')
DISPLAY SVSTATUS('LAB.ECHO.AGENT')
* Verify PID and STATE RUNNING
STOP SERVICE('LAB.ECHO.AGENT')
DISPLAY SVSTATUS('LAB.ECHO.AGENT')

Common Operational Scenarios

1. File bridge agent with CONTROL(QMGR)—must survive reboot with queue manager.
2. One-off migration utility with CONTROL(MANUAL)—START SERVICE during window only.
3. Health check script SERVTYPE(COMMAND)—run on demand, no SVSTATUS dependency.
4. Failed STOPCMD leaves zombie PID—script stop must kill process group safely.

Explain Like I'm Five: Service Objects

The school bus driver (queue manager) also starts the heater fan (service) when the engine starts so windows do not fog. The fan's on/off buttons are written on a card (SERVICE definition) in the glove box. Triggering is different—that is when the driver honks because mail arrived, and a helper runs out once.

Practice Exercises

Exercise 1

Write DEFINE SERVICE for a log scraper that must start with QMGR and stop before endmqm. Include STDOUT paths.

Exercise 2

SVSTATUS shows RUNNING but applications report no MQ traffic. How do you prove the SERVICE process is the correct binary?

Exercise 3

When would you choose a Kubernetes sidecar instead of DEFINE SERVICE?

Frequently Asked Questions

Test Your Knowledge