`ims_command`

This building block submits IMS commands. It is not related to artifacts.

To run correctly, this building block requires environment variables. Indicate them in a .yml file. Indicate The generic environment variables for the Ansible and Python building blocks and adapt their values to your target z/OS environment. Indicate also the variables that are specific to this building block.

To indicate the IMS command to submit and the variables that it needs, you can enter a var_ims_command property in The deployment method step that this building block implements, like in the following example:

actions:
    - name: RUN IMS COMMAND
      short_name: IMS_COMMAND
      steps:
      - name: TEST STEP FOR IMS_COMMAND
        short_name: TEST_IMS_COMMAND
        properties:
        - key: template
          value: ims_command
        - key: var_ims_command
          value: my_var_ims_command

In this example, the value of the var_ims_command property is my_var_ims_command, but it can be any other string.

The specific variables

If you specify the var_ims_command property in a step of the deployment method, you must indicate the values of the specific variables that it needs.

Indicate the specific variables of this building block in an Ansible or a Python environment variables file.

Note: For Python, the entire path to this file is indicated in the --envFile argument of The Python deployment command.

The following extract shows only the variables that are used by this building block.

my_var_ims_command:
   batch:
     - command: "QUERY PGM SHOW(ALL)"
       plex: "PLXWZ"
     - command: "DISPLAY STATUS"
       plex: "PLXWZ"

All the variables correspond to the parameters of the Ansible module. They are explained in ims_command – Submit IMS Commands.

Note: Due to a known limitation in ims_command in the Ansible z/OS IMS collection, the value of the command variable cannot exceed 250 characters. As a workaround, you can use the job_submit building block with a template to run a command that is longer than 250 characters.

Enter the IMS SDFSRESL data set as the value of the STEPLIB variable in the following way:

For Ansible, indicate the value in the Ansible environment variables file, under the environment_vars root, like in the following example:
```
environment_vars:
  STEPLIB: 'DFSF10.SDFSRESL'
```
For Python, export the value with the EXPORT command, like in the following example:
```
export STEPLIB=DFSF10.SDFSRESL
```
Set this environment variable with the other environment variables. For more information, see Installing Wazi Deploy.

If you do not indicate the var_ims_command property in a step of the deployment method, then the values of the default ims_command_default variable from an environment variables file are used.

The following example shows the ims_command_default variable:

ims_command_default:
   command: "QUERY PGM SHOW(ALL)"
   plex: "PLXWZ"
   route:
     - "IMWZ"

Note: You can add a parameter to ignore certain errors. If the output provided by the specified IMS command returns an ims_output that contains a type_2_response.CC field and if your command fails, you can enter the value of the returned completion code (CC) in the success_type_2_response_cc_list parameter. The command will then be successful.

For example, you want to run the following command:

my_var_ims_command:
     batch:
       - command: "UPD PGM NAME(RPPPGM) START(REFRESH)"
         plex: "PLEX1"

If the program is not loaded, the command fails with a completion code (CC) 220.

To ignore this error and make the command successful, add 220 in the success_type_2_response_cc_list parameter. So, enter the following code:

my_var_ims_command:
   batch:
     - command: "UPD PGM NAME(RPPPGM) START(REFRESH)"
       plex: "PLEX1"
   success_type_2_response_cc_list:
     - '220'

A warning in the console indicates that some errors have been ignored.

The Wazi Deploy conditional deployment provides this type of operation and other particular processing.

Return values

The result of each building block task is displayed in the evidence file, in The results level that is embedded in step_result.