ims_olcutl

This building block copies a source library with your new definitions to a target library. Issuing the Online Change command sequence to prepare and commit an online change causes the inactive library to become the active library. The libraries concerned are ACBLIB, FORMAT, and MODBLKS.

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.

To run this building block and specify the variables that it needs, you can enter a var_ims_olcutl property in The deployment method step that this building block implements. In the following example, the value of the var_ims_olcutl property is my_var_ims_olcutl, but it can be any other string. 

actions:
    - name: IMS ONLINE CHANGE UTILITY
      short_name: ONLINE_CHANGE
      steps:
      - name: TEST STEP FOR ONLINE_CHANGE
        short_name: TEST_ONLINE_CHANGE
        properties:
        - key: template
          value: ims_olcutl
        - key: var_ims_olcutl
          value: my_var_ims_olcutl

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.

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

The Ansible variables

To run this building block, indicate the following specific variables in an Ansible environment variables file:

my_var_ims_olcutl:
  procname: "OLCUTL"
  lstype:
   - type: "ACBLIB"
     params: 
      - "SOUT='*'"
      - "TYPE=ACB"
      - "IN=S"
      - "OUT=U"   
   - type: "FORMAT"
     params: 
      - "SOUT='*'"
      - "TYPE=FORMAT"
      - "IN=S"
      - "OUT=U"   
   - type: "MODBLKS"
     params: 
      - "SOUT='*'"
      - "TYPE=MODBLKS"
      - "IN=S"
      - "OUT=U"   
  jobcard: "OLCUTL JOB 'WD-OLCUTL',MSGLEVEL=(1,1),MSGCLASS=R,NOTIFY=&SYSUID"
  joblib: "{{hlq.PROCLIB}}"
  wait_time_s: 20
  max_rc : 4
  return_output: false
  encoding:
    from: UTF-8
    to: IBM-1047
You must declare the following variables that are related to var_ims_olcutl (named my_var_ims_olcutl in the deployment method sample):
  • procname to indicate the name of the IMS procedure to be run. The default value is OLCUTL but it can be another name if this procedure has been personalized in the IMS PROCLIB.
  • jobcard to indicate the parameters of the job card for the JCL that runs the OLCUTL procedure.
  • joblib to indicate the libraries where the IMS procedures are stored. If this variable is not indicated, the JCLLIB ORDER line will not be present in the generated JCL.
  • lstype variable to list all the library types concerned (ACBLIB, FORMAT, and MODLBKS). If your IMS system runs with the IMS catalog and managed application control blocks (ACB), the lstype variable does not contain the ACBLIB library.
    Each library type contains the following variables:
    • type, whose value is ACBLIB, FORMAT, or MODLBKS.
    • params, which contains the list of all the parameters to be passed to run the Online Change Copy utility (OLCUTL procedure). For more information, see the OLCUTL procedure in the IBM® IMS documentation.
  • The variables that are used to submit the job:
    • max_rc (optional) to indicate the maximum return code of the JCL execution.
    • return_output (optional) to indicate whether the DD output is to be printed. If it is set to false, an empty list will be returned in the ddnames field. The two possible values are True and False.
      Note: With the version 1.8.0 of Ansible z/OS core, you might encounter an encoding error. If so, you must set this value to False. Future versions of Ansible z/OS core will correct this issue.
    • wait_time_s (optional) to set the maximum time in seconds to wait for the job to complete.
    • An encoding variable if an encoding is needed. To indicate an encoding, you must specify the following variables: from for the initial encoding and to for the target encoding.

    These variables apply to all the types that are defined in lstype.

If you do not indicate the var_ims_olcutl property in a step of the deployment method, then the values of the default ims_olcutl_default variable from an environment variables file are used. The following example shows the ims_olcutl_default variable: 
ims_olcutl_default:
     procname: "OLCUTL"
     lstype:
       - type: "ACBLIB"
         params:
           - "SOUT='*'"
           - "TYPE=ACB"
           - "IN=S"
           - "OUT=U"
       - type: "FORMAT"
         params:
           - "SOUT='*'"
           - "TYPE=FORMAT"
           - "IN=S"
           - "OUT=U"
       - type: "MODBLKS"
         params:
           - "SOUT='*'"
           - "TYPE=MODBLKS"
           - "IN=S"
           - "OUT=U"
     jobcard: "OLCUTL JOB 'WD-OLCUTL',MSGLEVEL=(1,1),MSGCLASS=R,NOTIFY=&SYSUID"
     joblib: "{{hlq.PROCLIB}}"
     max_rc : 4

The Ansible JCL template

An execution JCL is generated and submitted for this building block. This JCL is generated from the following JCL template:

//{{wd_ims_olcutl['jobcard'].strip()}}
{% if wd_ims_olcutl.get('joblib',None) != None %}// JCLLIB ORDER=({{wd_ims_olcutl['joblib'].strip()}})
{% endif %}
{% for item in wd_ims_olcutl.lstype %}
//* COPY {{item.type}} TO {{item.type}}A/B
//*
//{{item.type}} EXEC PROC={{wd_ims_olcutl.procname}},
{% for param in item.params %}{% if loop.index == loop.length %}// {{param}}
{% else %}// {{param}},
{% endif %}{% endfor %}
{% endfor -%}
Note: You can provide your own template. To do so, create your Jinja2 JCL template and place it in the Ansible controller search path.
Then, in the deployment method step that corresponds to the execution of the building block, enter a property to indicate the name of your own template by using one of the following two methods:
  • Enter the template name directly as the value of the template_name property, like in the following example:
    properties: 
- key: "template_name" 
  value: "my_template_name.j2"
  • Enter the name of the variable that contains the template name as the value of the var_template_name property, and declare this variable in the environment variables file.
    In the following example, you enter my_template_variable as the value of the var_template_name property:
    properties: 
- key: "var_template_name" 
  value: "my_template_variable"
    Then, you declare this variable in the environment variables file. In the example, you enter my_template_name.j2 as the value of the my_template_variable variable:
    my_template_variable: my_template_name.j2

To know how to define the variables in your Jinja2 template, see Coding the variables in the Jinja2 templates.

The Python variables

To run this building block, indicate the following specific variables in a Python environment variables file. The whole path to this file is indicated in the --envFile argument of The Python deployment command. 

my_var_ims_olcutl:
  procname: "OLCUTL"
  lstype:
   - type: "ACBLIB"
     params: 
      - "SOUT='*'"
      - "TYPE=ACB"
      - "IN=S"
      - "OUT=U"   
   - type: "FORMAT"
     params: 
      - "SOUT='*'"
      - "TYPE=FORMAT"
      - "IN=S"
      - "OUT=U"   
   - type: "MODBLKS"
     params: 
      - "SOUT='*'"
      - "TYPE=MODBLKS"
      - "IN=S"
      - "OUT=U"   
  jobcard: "OLCUTL JOB 'WD-OLCUTL',MSGLEVEL=(1,1),MSGCLASS=R,NOTIFY=&SYSUID"
  joblib: "{{hlq.PROCLIB}}"
  max_rc: 4
You must declare the following variables that are related to var_ims_olcutl (named my_var_ims_olcutl in the deployment method sample):
  • procname to indicate the name of the IMS procedure to be run. The default value is OLCUTL but it can be another name if this procedure has been personalized in the IMS PROCLIB.
  • jobcard to indicate the parameters of the job card for the JCL that runs the OLCUTL procedure.
  • joblib to indicate the libraries where the IMS procedures are stored. If this variable is not indicated, the JCLLIB ORDER line will not be present in the generated JCL.
  • max_rc (optional) to indicate the maximum return code of the JCL execution.
  • lstype variable to list all the library types concerned (ACBLIB, FORMAT, and MODLBKS). If your IMS system runs with the IMS catalog and managed application control blocks (ACB), the lstype variable does not contain the ACBLIB library.
    Each library type contains the following variables:
    • type, whose value is ACBLIB, FORMAT, or MODLBKS.
    • params, which contains the list of all the parameters to be passed to run the Online Change Copy utility (OLCUTL procedure). For more information, see the OLCUTL procedure in the IBM IMS documentation.
If you do not indicate the var_ims_olcutl property in a step of the deployment method, then the values of the default ims_olcutl_default variable from an environment variables file are used. The following example shows the ims_olcutl_default variable: 
ims_olcutl_default:
   procname: "OLCUTL"
   lstype:
     - type: "ACBLIB"
       params:
         - "SOUT='*'"
         - "TYPE=ACB"
         - "IN=S"
         - "OUT=U"
     - type: "FORMAT"
       params:
         - "SOUT='*'"
         - "TYPE=FORMAT"
         - "IN=S"
         - "OUT=U"
     - type: "MODBLKS"
       params:
         - "SOUT='*'"
         - "TYPE=MODBLKS"
         - "IN=S"
         - "OUT=U"
   jobcard: "OLCUTL  JOB 'WD-OLCUTL',MSGLEVEL=(1,1),MSGCLASS=R,NOTIFY=&SYSUID"
   joblib: "{{ hlq }}.PROCLIB"
   max_rc: 4

The Python JCL template

An execution JCL is generated and submitted for this building block. This JCL is generated from the following JCL template:

//{{parameters['jobcard'].strip()}}
{% if parameters.get('joblib',None) != None %}// JCLLIB ORDER=({{parameters['joblib'].strip()}})
{% endif %}
{% for item in parameters.lstype %}
//* COPY {{item.type}} TO {{item.type}}A/B
//*
//{{item.type}} EXEC PROC={{parameters.procname}},
{% for param in item.params %}{% if loop.index == loop.length %}// {{param}}
{% else %}// {{param}},
{% endif %}{% endfor %}
{% endfor -%}
Note: You can provide your own template. To do this, create your Jinja2 JCL template and place it in a folder of your choice. Set the DEPLOY_TEMPLATES_PATH environment variable like in the following example:
export DEPLOY_TEMPLATES_PATH=MY_TEMPLATE_FOLDER
Then, in the deployment method step that corresponds to the execution of the building block, enter a property to indicate the name of your own template by using one of the following two methods:
  • Enter the template name directly as the value of the template_name property, like in the following example:
    properties: 
- key: "template_name" 
  value: "my_template_name.j2"
  • Enter the name of the variable that contains the template name as the value of the var_template_name property, and declare this variable in the environment variables file.
    In the following example, you enter my_template_variable as the value of the var_template_name property:
    properties: 
- key: "var_template_name" 
  value: "my_template_variable"
    Then, you declare this variable in the environment variables file. In the example, you enter my_template_name.j2 as the value of the my_template_variable variable:
    my_template_variable: my_template_name.j2

To know how to define the variables in your Jinja2 template, see Coding the variables in the Jinja2 templates.

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.