DEFINE SERVICE on Multiplatforms

Use the MQSC command DEFINE SERVICE to define a new IBM® MQ service definition, and set its parameters.

Using MQSC commands

For information on how you use MQSC commands, see Performing local administration tasks using MQSC commands.

Syntax diagram
Usage notes
Parameter descriptions for DEFINE SERVICE

Values shown above the main line in the railroad diagram are the defaults supplied with IBM MQ, but your installation might have changed them. See Syntax diagrams.

DEFINE SERVICE

Define attrs

Service attrs

Usage notes

A service is used to define the user programs that are to be started and stopped when the queue manager is started and stopped. You can also start and stop these programs by issuing the START SERVICE and STOP SERVICE commands.

Attention: This command allows a user to run an arbitrary command with mqm authority. If granted rights to use this command, a malicious or careless user could define a service which damages your systems or data, for example, by deleting essential files.

For more information about services, see Services.

Parameter descriptions for DEFINE SERVICE

The parameter descriptions apply to the ALTER SERVICE and DEFINE SERVICE commands, with the following exceptions:

The LIKE parameter applies only to the DEFINE SERVICE command.
The NOREPLACE and REPLACE parameter applies only to the DEFINE SERVICE command.

(service-name)

Name of the IBM MQ service definition (see Rules for naming IBM MQ objects ).

The name must not be the same as any other service definition currently defined on this queue manager (unless REPLACE is specified).

CONTROL(string)

Specifies how the service is to be started and stopped:

MANUAL: The service is not to be started automatically or stopped automatically. It is to be controlled by use of the START SERVICE and STOP SERVICE commands.
QMGR: The service being defined is to be started and stopped at the same time as the queue manager is started and stopped.
STARTONLY: The service is to be started at the same time as the queue manager is started, but is not requested to stop when the queue manager is stopped.

DESCR(string)

Plain-text comment. It provides descriptive information about the service when an operator issues the DISPLAY SERVICE command (see DISPLAY SERVICE on Multiplatforms).

It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.

LIKE(service-name)

The name of a service the parameters of which are used to model this definition.

This parameter applies only to the DEFINE SERVICE command.

If this field is not completed, and you do not complete the parameter fields related to the command, the values are taken from the default definition for services on this queue manager. Not completing this parameter is equivalent to specifying:


LIKE(SYSTEM.DEFAULT.SERVICE)

A default service is provided but it can be altered by the installation of the default values required. See Rules for naming IBM MQ objects.

REPLACE and NOREPLACE

Whether the existing definition is to be replaced with this one.

This parameter applies only to the DEFINE SERVICE command.

REPLACE: The definition must replace any existing definition of the same name. If a definition does not exist, one is created.
NOREPLACE: The definition should not replace any existing definition of the same name.

SERVTYPE

Specifies the mode in which the service is to run:

COMMAND: A command service object. Multiple instances of a command service object can be executed concurrently. You cannot monitor the status of command service objects.
SERVER: A server service object. Only one instance of a server service object can be executed at a time. The status of server service objects can be monitored using the DISPLAY SVSTATUS command.

STARTARG(string)

Specifies the arguments to be passed to the user program at queue manager startup.

STARTCMD(string)

Specifies the name of the program which is to run. You must specify a fully qualified path name to the executable program.

STDERR(string)

Specifies the path to a file to which the standard error (stderr) of the service program is redirected. If the file does not exist when the service program is started, the file is created. If this value is blank then any data written to stderr by the service program is discarded.

STDOUT(string)

Specifies the path to a file to which the standard output (stdout) of the service program is redirected. If the file does not exist when the service program is started, the file is created. If this value is blank then any data written to stdout by the service program is discarded.

STOPARG(string)

Specifies the arguments to be passed to the stop program when instructed to stop the service.

STOPCMD(string)

Specifies the name of the executable program to run when the service is requested to stop. You must specify a fully qualified path name to the executable program.

Replaceable inserts can be used for any of the STARTCMD, STARTARG, STOPCMD, STOPARG, STDOUT or STDERR strings, for more information, see Replaceable inserts on service definitions.