DEFINE SERVICE on Multiplatforms

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


Use MQSC commands

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

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 SERVICE ( name ) define attrsservice attrsDefine attrsDESCR(' ')DESCR(string)LIKE(service-name)NOREPLACEREPLACEService attrsCONTROL(MANUAL)CONTROL(QMGR)CONTROL(STARTONLY)SERVTYPE(COMMAND)SERVTYPE(SERVER)STARTARG(' ')STARTARG(string)STARTCMD(' ')STARTCMD(string)STDERR(' ')STDERR(string)STDOUT(' ')STDOUT(string)STOPARG(' ')STOPARG(string)STOPCMD(' ')STOPCMD(string)


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. We 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 the 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 we 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:

    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. We 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. We 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. Parent topic: MQSC commands


Related reference


Related information