Trigger Data

Trigger data is how IBM MQ passes hints from the queue definition to the application the trigger monitor starts. Without TRIGDATA, every queue sharing PROCESS(CONSUME.SH) might need its own copy of the consumer script with a hard-coded queue name—operational drift guaranteed. With TRIGDATA, the same executable reads "QNAME=ORDERS.UK" or "POOL=2" from the trigger message and opens the right resources. Beginners set TRIGDATA to random text and wonder why the script ignores it—the consumer must actually parse the trigger message or environment the monitor provides. This tutorial explains TRIGDATA on queues, USERDATA on PROCESS objects, what appears in the trigger message, structured formats, multi-queue patterns, security when parsing strings, and debugging when the wrong queue is consumed.

Trigger Message Contents

When triggering fires, MQ places a message on the initiation queue describing the event. Besides process name and trigger type, the message carries data from TRIGDATA and attributes of the triggered queue (name, depth, etc., per platform API). The trigger monitor uses this to start APPLICID; sophisticated consumers also open the initiation queue briefly or receive parameters via documented environment variables on some platforms. Know your platform's programming guide—do not assume Windows behavior on Linux.

Structured TRIGDATA Conventions

Use parseable formats: comma-separated key=value, JSON in advanced estates, or fixed-position codes legacy systems already understand. Document the schema in source control. Example: TRIGDATA('QNAME=PAY.IN;REGION=EU;MAX=500'). The consumer splits on semicolons and validates keys. Avoid free-text TRIGDATA without a parser—operators cannot troubleshoot "batch mode" vs "batch_mode" typos.

1
2
3
4
5
6
DEFINE QLOCAL('PAY.EU') TRIGGER(YES) TRIGTYPE(FIRST) +
  PROCESS('SHARED.CONSUMER') TRIGDATA('QNAME=PAY.EU;REGION=EU')
DEFINE QLOCAL('PAY.US') TRIGGER(YES) TRIGTYPE(FIRST) +
  PROCESS('SHARED.CONSUMER') TRIGDATA('QNAME=PAY.US;REGION=US')
DEFINE PROCESS('SHARED.CONSUMER') APPLICID('/app/consume.py') +
  USERDATA('LOGLEVEL=INFO')

Combining TRIGDATA and USERDATA

USERDATA on PROCESS might set LOGLEVEL=INFO for all regions while TRIGDATA selects REGION=EU. The started Python script reads both: environment from USERDATA via trigger monitor conventions, queue name from TRIGDATA. When changing USERDATA, all queues using that PROCESS see the change on next trigger—plan impact. TRIGDATA changes are per-queue ALTER QLOCAL.

Security Considerations

If APPLICID is a shell script that does eval on TRIGDATA, a compromised MQ admin could inject commands—use strict parsing and allow-lists. TRIGDATA is not a secrets store; do not put passwords in clear text. Length limits prevent huge payloads but not malicious strings—validate in application code.

Debugging Wrong Queue Consumed

1. DISPLAY QLOCAL — confirm TRIGDATA on the queue that had messages.
2. Log TRIGDATA at start of consumer in test environment.
3. Verify script opens queue from TRIGDATA not hard-coded constant.
4. Check multiple triggers did not start race between regions.

Explainer: Sticky Note on the Package

TRIGDATA is the sticky note on a package telling the handler which shelf to put it on. USERDATA on PROCESS is the sign on the handler's uniform saying which team they belong to.

Explain Like I'm Five: Trigger Data

When the bell rings, the note says which toy box to empty. Without the note, the friend might empty the wrong box.

Practice Exercises

Exercise 1

Define two queues with different TRIGDATA; log what your consumer receives on each trigger.

Exercise 2

Design key=value schema for TRIGDATA with five allowed keys documented.

Exercise 3

Identify one security risk of shell eval on TRIGDATA and the fix.

Frequently Asked Questions

Test Your Knowledge