`ims_command`

This building block submits Type-1 and Type-2 IMS commands.

It is not related to artifacts.

To trigger the execution of this building block, you can enter the following code in the deployment method from which the deployment plan is generated. See How to trigger the execution of a building block. The following code is an 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.

If you do not indicate the var_ims_command property in a step of the deployment method, then the default value for this property (ims_command_default) will be used.

In both cases, this value (my_var_ims_command or ims_command_default) must be declared in the environment variables file. For Python, the entire path to this file is indicated in the --envFile argument of The Python deployment command.

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.

The Ansible and Python common environment variables

To run this building block, indicate the following specific variables in an Ansible or a Python environment variables file.

The values of the var_ims_command property or ims_command_default variable must contain the following variables, which come from the ims_command module and are documented there:

batch
command
plex
route

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 on z/OS.

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.

Examples

The following examples illustrate the declaration of the environment variables for this building block:

The following code illustrates batch commands to switch unactive libraries to active librairies:

ims_switch_cat_all:
   route: 
     - "IMS1"
   batch:
     - command: "DISPLAY MODIFY ALL"
       plex: "PLEX1"
     - command: "IMPORT DEFN SOURCE(CATALOG)"
       plex: "PLEX1"
     - command: "MODIFY PREPARE ALL"
       plex: "PLEX1"
     - command: "MODIFY COMMIT"
       plex: "PLEX1"
     - command: "DISPLAY MODIFY ALL"
       plex: "PLEX1"

The following code queries all the programs for IMS1 in PLEX1:

  ims_command:
    command: QUERY PGM SHOW(ALL)
    plex: "PLEX1"
    route: "IMS1"

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.