Change, Copy, and Create Process

The Change Process command changes existing process definitions. The Copy and Create Process commands create new process definitions - the Copy command uses attribute values of an existing process definition.

The Change Process (MQCMD_CHANGE_PROCESS) command changes the specified attributes of an existing IBM MQ process definition. For any optional parameters that are omitted, the value does not change.

The Copy Process (MQCMD_COPY_PROCESS) command creates an IBM MQ process definition, using, for attributes not specified in the command, the attribute values of an existing process definition.

The Create Process (MQCMD_CREATE_PROCESS) command creates an IBM MQ process definition. Any attributes that are not defined explicitly are set to the default values on the destination queue manager.


Required parameters (Change and Create Process)

    ProcessName (MQCFST)
    The name of the process definition to be changed or created (parameter identifier: MQCA_PROCESS_NAME).

    The maximum length of the string is MQ_PROCESS_NAME_LENGTH.


Required parameters (Copy Process)

    FromProcessName (MQCFST)
    The name of the process definition to be copied from (parameter identifier: MQCACF_FROM_PROCESS_NAME).

    Specifies the name of the existing process definition that contains values for the attributes not specified in this command.

    On z/OS, the queue manager searches for an object with the name you specify and a disposition of MQQSGD_Q_MGR or MQQSGD_COPY to copy from. This parameter is ignored if a value of MQQSGD_COPY is specified for QSGDisposition . In this case, an object with the name specified by ToProcessName and the disposition MQQSGD_GROUP is searched for to copy from.

    The maximum length of the string is MQ_PROCESS_NAME_LENGTH.

    ToProcessName (MQCFST)
    To process name (parameter identifier: MQCACF_TO_PROCESS_NAME).

    The name of the new process definition. If a process definition with this name exists, Replace must be specified as MQRP_YES.

    The maximum length of the string is MQ_PROCESS_NAME_LENGTH.


Optional parameters (Change, Copy, and Create Process)

    ApplId (MQCFST)
    Application identifier (parameter identifier: MQCA_APPL_ID).

    ApplId is the name of the application to be started. The application must be on the platform for which the command is executing. The name might typically be a fully qualified file name of an executable object. Qualifying the file name is particularly important if you have multiple IBM MQ installations, to ensure the correct version of the application is run.

    The maximum length of the string is MQ_PROCESS_APPL_ID_LENGTH.

    ApplType (MQCFIN)
    Application type (parameter identifier: MQIA_APPL_TYPE). Valid application types are:

      MQAT_OS400
      IBM i application.

      MQAT_DOS
      DOS client application.

      MQAT_WINDOWS
      Windows client application.

      MQAT_AIX
      AIX application (same value as MQAT_UNIX).

      MQAT_CICS
      CICS transaction.

      MQAT_NSK
      HP Integrity NonStop Server application.

      MQAT_ZOS
      z/OS application.

      MQAT_DEFAULT
      Default application type.

    integer: System-defined application type in the range zero through 65 535 or a user-defined application type in the range 65 536 through 999 999 999 (not checked).

    Only specify application types (other than user-defined types) that are supported on the platform at which the command is executed:

    • On IBM i: MQAT_OS400, MQAT_CICS, and MQAT_DEFAULT are supported.
    • On HP Integrity NonStop Server: MQAT_NSK, MQAT_DOS, MQAT_WINDOWS, and MQAT_DEFAULT are supported.
    • On UNIX: MQAT_UNIX, MQAT_OS2, MQAT_DOS, MQAT_WINDOWS, MQAT_CICS, and MQAT_DEFAULT are supported.
    • On Windows: MQAT_WINDOWS_NT, MQAT_OS2, MQAT_DOS, MQAT_WINDOWS, MQAT_CICS, and MQAT_DEFAULT are supported.
    • On z/OS: MQAT_DOS, MQAT_IMS MQAT_MVS, MQAT_UNIX, MQAT_CICS, and MQAT_DEFAULT are supported.

    CommandScope (MQCFST)
    Command scope (parameter identifier: MQCACF_COMMAND_SCOPE). This parameter applies to z/OS only. Specifies how the command is executed when the queue manager is a member of a queue sharing group. We can specify one of the following:

    • Blank (or omit the parameter altogether). The command is executed on the queue manager on which it was entered.
    • A queue manager name. The command is executed on the queue manager you specify, providing it is active within the queue sharing group. In a shared queue environment, we can provide a different queue manager name from the one we are using to enter the command. The command server must be enabled.
    • An asterisk (*). The command is executed on the local queue manager and is also passed to every active queue manager in the queue sharing group.

    The maximum length is MQ_QSG_NAME_LENGTH.

    EnvData (MQCFST)
    Environment data (parameter identifier: MQCA_ENV_DATA).

    A character string that contains environment information pertaining to the application to be started.

    The maximum length of the string is MQ_PROCESS_ENV_DATA_LENGTH.

    ProcessDesc (MQCFST)
    Description of process definition (parameter identifier: MQCA_PROCESS_DESC).

    A plain-text comment that provides descriptive information about the process definition. It must contain only displayable characters.

    The maximum length of the string is MQ_PROCESS_DESC_LENGTH.

    Use characters from the coded character set identifier (CCSID) for this queue manager. Other characters might be translated incorrectly if the information is sent to another queue manager.

    QSGDisposition (MQCFIN)
    Disposition of the object within the group (parameter identifier: MQIA_QSG_DISP). This parameter applies to z/OS only. Specifies the disposition of the object to which we are applying the command (that is, where it is defined and how it behaves). The value can be any of the following values:

    QSGDisposition Change Copy, Create
    MQQSGD_COPY The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameter MQQSGD_COPY. Any object residing in the shared repository, or any object defined using a command that had the parameters MQQSGD_Q_MGR, is not affected by this command. The object is defined on the page set of the queue manager that executes the command using the MQQSGD_GROUP object of the same name as the ToProcessName object (for Copy) or ProcessName object (for Create).
    MQQSGD_GROUP The object definition resides in the shared repository. The object was defined using a command that had the parameters QSGDISP(GROUP). On the page set of the queue manager that executes the command, only a local copy of the object is altered by this command. If the command is successful, the following command is generated. 
    DEFINE PROCESS(process-name)
REPLACE QSGDISP(COPY)
    The command is sent to all active queue managers in the queue sharing group to attempt to refresh local copies on page set zero. The Change for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.    		 The object definition resides in the shared repository. GROUP is allowed only if the queue manager is in a queue sharing group. If the definition is successful, the following command is generated. 
    DEFINE PROCESS(process-name)
REPLACE QSGDISP(COPY)
    The command is sent to all active queue managers in the queue sharing group to attempt to make or refresh local copies on page set zero. The Copy or Create for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
    MQQSGD_PRIVATE The object resides on the page set of the queue manager that executes the command, and was defined with MQQSGD_Q_MGR or MQQSGD_COPY. Any object residing in the shared repository is unaffected. Not permitted.
    MQQSGD_Q_MGR The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameter MQQSGD_Q_MGR. Any object residing in the shared repository, or any local copy of such an object, is not affected by this command. MQQSGD_Q_MGR is the default value. The object is defined on the page set of the queue manager that executes the command. MQQSGD_Q_MGR is the default value.

    Replace (MQCFIN)
    Replace attributes (parameter identifier: MQIACF_REPLACE).

    If a process definition with the same name as ToProcessName exists, specify whether to replace it.

    The value can be any of the following values:

      MQRP_YES
      Replace existing definition.

      MQRP_NO
      Do not replace existing definition.

    UserData (MQCFST)
    User data (parameter identifier: MQCA_USER_DATA).

    A character string that contains user information pertaining to the application (defined by ApplId) that is to be started.

    For Microsoft Windows, the character string must not contain double quotation marks if the process definition is going to be passed to runmqtrm.

    The maximum length of the string is MQ_PROCESS_USER_DATA_LENGTH.

Parent topic: Definitions of the Programmable Command Formats