Setting environment variables

Examples of working with environment variables using runnscnf.

Viewing the environment for a queue manager

To view the actual settings of environment variables of a running queue manager, use runnscnf to list the properties of object ActualEnvironment in class QueueManager.

In this example, assume that the following environment is set in your shell:
HISTCONTROL=ignoredups
UTILSGE=NOG:NOE
_RLD_LIB_PATH=/home/writer/mq8E64/opt/mqm/lib64:/home/alexi/mq8E64/opt/mqm/lib
PWD=/home/writer
HOME=/home/writer
BASH_ENV=/home/writer/.bashrc
TERM=vt220
PATH=/bin:/bin/unsupported:/usr/bin:/usr/ucb:/usr/coreutils/bin:/usr/local/bin:/usr/local/sbin:/home/alexi:.:/var/oss_tools:/usr/local/rm800/rm800/bin:/home/alexi/mq8E64/opt/mqm/bin:/home/alexi:.:/var/oss_tools:/usr/local/rm800/rm800/bin:/home/alexi/mq8E64/opt/mqm/bin
PS1=$PWD:
_=/bin/env
Start queue manager QM1 from that shell:
/home/writer:strmqm QM1
IBM MQ queue manager 'QM1' starting.
IBM MQ queue manager 'QM1' started using V8.1.0.5.

Use runnscnf to list the environment for queue manager QM1:

/home/writer:runnscnf QM1
runnscnf Command Interface
5724-H72 (C) Copyright IBM Corp. 1994, 2023.

NSCNF> list (,Actu*,)
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             BASH_ENV
Instance:             1
Value:                /home/writer/.bashrc
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             HISTCONTROL
Instance:             1
Value:                ignoredups
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             HOME
Instance:             1
Value:                /home/writer
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             MyVariable
Instance:             1
Value:                1
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             PATH
Instance:             1
Value:                /bin:/bin/unsupported:/usr/bin:/usr/ucb:/usr/coreutils/bin
:/usr/local/bin:/usr/local/sbin:/home/writer:.:/var/oss_tools:/usr/local/rm800/rm
800/bin:/home/writer/mq8E64/opt/mqm/bin:/home/writer:.:/var/oss_tools:/usr/local/r
m800/rm800/bin:/home/writer/mq8E64/opt/mqm/bin
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             PS1
Instance:             1
Value:                $PWD:
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             PWD
Instance:             1
Value:                /home/writer
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             TERM
Instance:             1
Value:                vt220
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             UTILSGE
Instance:             1
Value:                NOG:NOE
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             _
Instance:             1
Value:                /home/writer/mq8E64/opt/mqm/bin/strmqm
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             _RLD_LIB_PATH
Instance:             1
Value:                /home/writer/mq8E64/opt/mqm/lib64:/home/alexi/mq8E64/opt/mq
m/lib
NSCNF>

Setting environment variables for an individual queue manager

You set the environment for individual queue managers by using runnscnf for the specified queue manager with class QueueManager and object Environment.

You can configure environment variables used by a queue manager in addition to the settings in the shell. If the ConfiguredEnvOnly property of the currentQMGR object is set to F, the queue manager derives its environment from the shell except where individual variables are overridden by settings made with runnscnf.

In many application scenarios you might want to use only environment variables explicitly configured for a specific queue manager. This is especially true if different queue managers need different settings and are frequently restarted (for example in a test or development environment). In this case, you can set the ConfiguredEnvOnly property of the currentQMGR object to T. All settings in the shell are ignored.

Example 1: deriving settings from runnscnf and shell

This example configures MyVariable for the queue manager QM1 and sets its value to TRUE. runnscnf is used when the queue manager is ended:
/home/writer:runnscnf QM1
runnscnf Command Interface
5724-H72 (C) Copyright IBM Corp. 1994, 2023.

*** Warning: Could not open ConfigManager $X1SWR:5321146969 (error = 14).
    Queue manager may not be started.
NSCNF>class QueueManager
CLASS set to QueueManager
NSCNF>object Environment
OBJECT set to Environment
NSCNF>set MyVariable TRUE
Property MyVariable set to TRUE

NSCNF>
runnscnf finished.

If you examine the shell environment at this point, you see there is no environment variable named MyVariable.

/home/writer:env
HISTCONTROL=ignoredups
UTILSGE=NOG:NOE
_RLD_LIB_PATH=/home/writer/mq8E64/opt/mqm/lib64:/home/writer/mq8E64/opt/mqm/lib
PWD=/home/writer
HOME=/home/writer
BASH_ENV=/home/writer/.bashrc
TERM=vt220
PATH=/bin:/bin/unsupported:/usr/bin:/usr/ucb:/usr/coreutils/bin:/usr/local/bin:/
usr/local/sbin:/home/writer:.:/var/oss_tools:/usr/local/rm800/rm800/bin:/home/writer
/mq8E64/opt/mqm/bin:/home/writer:.:/var/oss_tools:/usr/local/rm800/rm800/bin:/h
ome/writer/mq8E64/opt/mqm/bin
PS1=$PWD:
_=/bin/env

If you then start queue manager QM1, and examine its actual environment by using the runnscnf list command with the ActualEnvironment object, you see that MyVariable is set for queue manager QM1:

/home/writer:strmqm QM1
IBM MQ queue manager 'QM1' starting.
IBM MQ queue manager 'QM1' started using V8.1.0.5.
/home/writer:runnscnf QM1
runnscnf Command Interface
5724-H72 (C) Copyright IBM Corp. 1994, 2023.

NSCNF>list (,Actu*,)
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             BASH_ENV
Instance:             1
Value:                /home/writer/.bashrc
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             HISTCONTROL
Instance:             1
Value:                ignoredups
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             HOME
Instance:             1
Value:                /home/writer
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             MyVariable
Instance:             1
Value:                TRUE
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             PATH
Instance:             1
Value:                /bin:/bin/unsupported:/usr/bin:/usr/ucb:/usr/coreutils/bin
:/usr/local/bin:/usr/local/sbin:/home/writer:.:/var/oss_tools:/usr/local/rm800/rm
800/bin:/home/writer/mq8E64/opt/mqm/bin:/home/writer:.:/var/oss_tools:/usr/local/r
m800/rm800/bin:/home/writer/mq8E64/opt/mqm/bin
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             PS1
Instance:             1
Value:                $PWD:
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             PWD
Instance:             1
Value:                /home/writer
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             TERM
Instance:             1
Value:                vt220
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             UTILSGE
Instance:             1
Value:                NOG:NOE
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             _
Instance:             1
Value:                /home/writer/mq8E64/opt/mqm/bin/strmqm
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             _RLD_LIB_PATH
Instance:             1
Value:                /home/alexi/mq8E64/opt/mqm/lib64:/home/writer/mq8E64/opt/mq
m/lib
NSCNF>

You can use the list command with the Environment object to view the environment variables that have been explicitly set for a queue manager. In this example, only MyVariable has been set:

NSCNF>list (,Env*,)
---------------------------------------------------------
Class:                QueueManager
Object:               Environment
Property:             MyVariable
Value:                TRUE

The actual list of environment variables used by the queue manager is the combination of variables from the shell plus those configured by runnscnf. If a variable is present in the shell and in runnscnf as well, the value set by runnscnf is used. If the value is deleted in runnscnf and the queue manager is restarted, the shell variable is used again, although this change does not take effect until the queue manager is restarted.

Example 2: deriving settings from runnscnf only

With ConfiguredEnvOnly set to T, the shell settings are completely ignored by queue managers. The following example shows this usage:
/home/writer:runnscnf QM1
runnscnf Command Interface
5724-H72 (C) Copyright IBM Corp. 1994, 2023.

*** Warning: Could not open ConfigManager $X1T2M:5321582169 (error = 14).
    Queue manager may not be started.
NSCNF>class QueueManager
CLASS set to QueueManager
NSCNF>object CurrentQMGR
OBJECT set to CurrentQMGR
NSCNF>set ConfiguredEnvOnly  T
*** Warning: Could not send to ConfigManager (error = -1)
     Queue manager may not be started.
Property ConfiguredEnvOnly  set to T

NSCNF>
runnscnf finished.
No shell environment variables will now be used by queue manager QM1, as can be see by viewing the environment for QM1:
/home/writer:strmqm QM1
IBM MQ queue manager 'QM1' starting.
IBM MQ queue manager 'QM1' started using V8.1.0.5.
/home/writer:strmqm QM1
IBM MQ queue manager running.
/home/writer:runnscnf QM1
runnscnf Command Interface
5724-H72 (C) Copyright IBM Corp. 1994, 2023.

NSCNF>list (,Act*,)
NSCNF>
The actual environment is now empty, nothing is inherited from the shell.

Setting environment variables for all queue managers

To configure environment variables to be used by all queue managers, use mode global in runnscnf. Changes only become active after queue managers are restarted. (This example assumes that ConfiguredEnvOnly is set to T, so settings in the shell are ignored.)

The following example sets the environment variable MQEMSEVENTS to the value 255 for all queue managers:

/home/writer:runnscnf
runnscnf Command Interface
5724-H72 (C) Copyright IBM Corp. 1994, 2023.

AMQ8146: IBM MQ queue manager not available.
*** Warning: No default queue manager defined
NSCNF>mode global
MODE set to GLOBAL (all queue managers)
NSCNF>class queuemanager
CLASS set to QueueManager
NSCNF>object Environment
OBJECT set to Environment
NSCNF>set MQEMSEVENTS 255
Property MQEMSEVENTS set to 255

When an existing queue manager is started, it will use the value 255 for MQEMSEVENTS.

/home/writer:strmqm QM1
IBM MQ queue manager 'QM1' starting.
IBM MQ queue manager 'QM1' started using V8.1.0.5.
/home/writer:runnscnf QM1
runnscnf Command Interface
5724-H72 (C) Copyright IBM Corp. 1994, 2023.

NSCNF>list (,Act*,)
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             MQEMSEVENTS
Instance:             1
Value:                255

When a new queue manager is created and started, it also takes the value 255 for MQEMSEVENTS. If a different value is configured for a specific queue manager, this value overwrites the general setting (after restarting the queue manager).

Activating new variables by forced takeover

When environment variables are deleted or their values are changed by using runnscnf, this has no immediate effect on the environment of a queue manager that is actually running. The changes only take effect wen the queue manager is stopped and restarted, or if a forced takeover is performed.

In this example, the queue manager is started with MyVariable1 set to 1, MyVariable2 set to 2 and MyVariable3 not set at all. While the queue manager is running, the value of MyVariable1 is changed to 2, MyVariable2 is deleted from the configuration, and MyVariable3 is added to the configuration. To activate the new configuration, the backup EC is stopped and then a takeover is forced.

First, the queue manager is started:
/home/writer:strmqm QM1
IBM MQ queue manager 'QM1' starting.
IBM MQ queue manager 'QM1' started using V8.1.0.5.
Changes are made to the environment, but they do not affect the running queue manager:
/home/writer:runnscnf QM1
runnscnf Command Interface
5724-H72 (C) Copyright IBM Corp. 1994, 2023.

NSCNF>list (,Act*,)
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             MyVariable1
Instance:             1
Value:                1
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             MyVariable2
Instance:             1
Value:                2
NSCNF>class QueueManager
CLASS set to QueueManager
NSCNF>object ENvironment
OBJECT set to Environment
NSCNF>set MyVariable1 2
Property MyVariable1 set to 2

NSCNF>del MyVariable2
Property deleted successfully.
NSCNF>set MyVariable3 3
Property MyVariable3 set to 3

NSCNF>list (,Env*,)
---------------------------------------------------------
Class:                QueueManager
Object:               Environment
Property:             MyVariable1
Value:                2
---------------------------------------------------------
Class:                QueueManager
Object:               Environment
Property:             MyVariable3
Value:                3
NSCNF>list (,Act*,)
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             MyVariable1
Instance:             1
Value:                1
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             MyVariable2
Instance:             1
Value:                2
NSCNF>
runnscnf finished.
The backup EC is then stopped (note that the stop command as used here might not be available in your OSS shell, depending on how your system is set up, and you might need to use TACL for that step):
/home/writer:dspmq -x
QMNAME(QM1)                                          STATUS(Running)
    PROCESS($Z2DA:5322566745) PRIMARY(3,565) INSTANCE(1)
    PROCESS($Z2DA:5322566745) BACKUP(0,1044) INSTANCE(2)

/home/writer:stop 0,1044
/home/writer:dspmq -x
QMNAME(QM1)                                          STATUS(Running)
    PROCESS($Z2DA:5322566745) PRIMARY(3,565) INSTANCE(1)
    PROCESS($Z2DA:5322566745) BACKUP(0,1005) INSTANCE(2)
Then the primary EC is stopped and the actual environment settings are checked:
/home/writer:stop 3,565
/home/writer:runnscnf QM1
runnscnf Command Interface
5724-H72 (C) Copyright IBM Corp. 1994, 2023.

NSCNF>list (,Act*,)
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             MyVariable1
Instance:             1
Value:                2
---------------------------------------------------------
Class:                QueueManager
Object:               ActualEnvironment
Property:             MyVariable3
Instance:             1
Value:                3
NSCNF>

The new queue manager has activated the new values.