This module shows files that are ready to be copied to the target libraries. The files originate from the previous activity (in 2 and more step processes) or are inserted directly in the approve module. The module started via REST-API is useful mainly in the second case. Files can be provided via input JSON object and imported to the process. It is also possible to continue in the process just after import is done or to interrupt it for later access in interactive mode. You can import JCL, PROC and SYSIN files via REST-API, as is illustrated by the following examples.

Example 1 (import of JCL members)

As interrupt element is specified and equals true then the process is interrupted after requested members are imported to the process by m_jcl_approve module. This allows you to open the process in interactive mode and check the result. The import element must be an object, which can contain these items:

duplicity

Specifies what to do when an imported member already exists in the process (optional, the default value is "error"). Possible values are:

error - an error is written to the log and the module fails

skip - the member is not imported

overwrite - the existing member is overwritten.

jcl

contains masks of JCL members that are imported (optional)

proc

contains masks of PROC members that are imported (optional)

sysin

contains masks of SYSIN members that are imported (optional)

jcl, proc and sysin objects must contain mask item, which must be an array of elements in SYS/DSN(MEM) format. The system must exist in system_mapping configuration option in hos_config2.php. DSN is a library where members are read from (wildcards are not allowed here). Members can contain wildcards. All members matching the specified masks are imported.

The following example imports members from SYSH_ID system and P391D.HOS.TEST library matching OPC* mask. The members are imported as JCL objects. When a member that already exists in the process exists also in the library, it is skipped and the old one remains unchanged in the process.

{
    "process": 250,
    "action": "JCL_INIT_API_APPROVE",
    "ignore_predprocess_status": true,
    "activity_input_data": {n
        "task" : { 
            "t0400": {
                "interrupt": true,
                "import": {
                    "duplicity": "skip",
                    "jcl": {
                        "mask": [
                            "SYSH_ID/P391D.HOS.TEST(OPC*)"
                        ]
                    }
                }
            }
        }
    }
}

Example 2 (import of JCL, PROC and SYSIN members)

In this example members matching the masks specified in jcl object are imported as JCL members. Procedures matching the mask in proc object are imported as PROC members and sysin files matching masks in sysin object are imported as SYSIN members. If any of the imported members already exists in the process then it is overwritten. When the module succeeds to import members then the next task automatically starts, as interrupt option equals false. If all the following tasks are silent (require no interaction) then the activity runs to its end (is set as Complete when finished).

{
    "process": 259,
    "action": "JCL_INIT_API_APPROVE",
    "ignore_predprocess_status": true,
    "activity_input_data": {
        "task" : { 
            "t0400": {
                "interrupt": false,
                "import": {
                    "duplicity": "overwrite",
                    "jcl": {
                        "mask": [
                            "SYSH_ID/P391D.HOS.TEST(OPC*)",
                            "SYSH_ID/P391D.XXX.TEMP1(OPC*)"
                        ]
                    },
                    "proc": {
                        "mask": [
                            "SYSH_ID/P391D.HOS.TEST.PROCLIB(MYPROC*)"
                        ]
                    },
                    "sysin": {
                        "mask": [
                            "SYSH_ID/P391D.HOS.TEST.PROCLIB(COMMENT)",
                            "SYSH_ID/P391D.HOS.DATA.SYS(#*)"
                        ]
                    }
                }
            }
        }
    }
}

You can import SYSIN members with any LRECL. The module recognizes LRECL of the dataset that contain imported SYSIN members and stores this information together with the member to the database.

Every module that supports REST-API is included in this section where the format of input JSON object is fully described.

This module selects the environment used in the process and returns it via i_environment interface. When only one environment exists in your configuration then it is selected automatically and no input in interactive mode or via REST-API is needed. If more environments exist in your configuration then:

• A prompt is displayed in the interactive mode and you must select the environment from a select box

• An exact specification of the environment is required in JSON input object in REST-API mode

Example (selects ENV1 environment in REST-API mode)

This module shows a list of filer that must be confirmed. In case of REST-API execution the list of confirmed members must be provided via the input JSON object.

Example 1 (explicitly specified members)

If all members of the process are found in the list of confirmed members then the module ends successfully.

The format of the file name must be (exactly): SYSTEM/DSN(MEMBER).

In the following example OPCTEST1, OPCTEST2 and OPCTEST3 members from P391D.HOS.TEMP1 on SYSH_ID system are confirmed.

{
    "process": 226,
    "action": "JCL_NEW_CONFIRM_FI",
    "ignore_predprocess_status": false,
    "activity_input_data": {
        "task": {
            "t0200": {   /* task that calls m_hos_jcl_confirm module */
                "confirm": [
                    "SYSH_ID/P391D.HOS.TEMP1(OPCTEST1)", 
                    "SYSH_ID/P391D.HOS.TEMP1(OPCTEST2)",
                    "SYSH_ID/P391D.HOS.TEMP1(OPCTEST3)"
                ]                
            }
        }
    } 
}

Example 2 (confirmation of all members without explicit listing)

Confirms all members of the process. To do it set the value of confirm to 'all'.

{
    "process": 226,
    "action": "JCL_NEW_CONFIRM_FI",
    "ignore_predprocess_status": false,
    "activity_input_data": {
        "task": {
            "t0200": {   /* task that calls m_hos_jcl_confirm module */
                "confirm": "all"
            }
        }
    } 
}

In the interactive mode this module allows you to enter user data required for JCL statements. In REST-API mode your process in always automatically interrupted when this module is reached in case some user input is required. When no input is needed (i.e. when PRX rules set all fields or when no form is requested) then it is possible to set automatic confirmation and continuation with next tasks. This is controlled by the interrupt parameter. In the following examples we suppose that m_jcl_fillforms is started by t0700 task.

Example 1

In this case the process started via REST-API always interrupts in m_jcl_fillforms module as interrupt=true. Such interrupted process can then be opened interactively and you can enter missing user fields and then continue.

{
    "process": 362,
    "action": "JCL_NEW_EX_REQUEST_FI",
    "ignore_predprocess_status": false,
    "activity_input_data": {
        "task" : { 
            ...  // here is setting of preceding tasks... 
            "t0700": {
                "interrupt": true
            }
        }
    }
}

Example 2

In this case the process started via REST-API interrupts in m_jcl_fillforms module only when some user input is required (because interrupt=false). When all fields are properly set by PRX rules and their state is set to OK then no interruption occurs and the process automatically starts following tasks.

{
    "process": 362,
    "action": "JCL_NEW_EX_REQUEST_FI",
    "ignore_predprocess_status": false,
    "activity_input_data": {
        "task" : { 
            ...  // here is setting of preceding tasks... 
            "t0700": {
                "interrupt": false
            }
        }
    }
}

In the interactive mode this module is used for displaying content of generated jobs, procedures and SYSIN members. It also allows checking of SmartJCL log files. In the REST-API mode this module ends automatically when no error was issued by SmartJCL generator and when the automatic interruption is not set. When there is an error then the process is always interrupted so that you can open it interactively and check the result. Let's suppose that t1000 task calls m_jcl_generate module in the following examples.

Example 1

In this case, the process started via REST-API always interrupts in m_jcl_generate module as interrupt=true.

{
    "process": 362,
    "action": "JCL_NEW_EX_REQUEST_FI",
    "ignore_predprocess_status": false,
    "activity_input_data": {
        "task" : { 
            ...  // here is setting of preceding tasks... 
            "t1000": {
                "interrupt": true
            }
        }
    }
}

Example 2

In this case, the process started via REST-API interrupts in m_jcl_generate module only when the JCL generator failed (its return code was greater than 4).

{
    "process": 362,
    "action": "JCL_NEW_EX_REQUEST_FI",
    "ignore_predprocess_status": false,
    "activity_input_data": {
        "task" : { 
            ...  // here is setting of preceding tasks... 
            "t1000": {
                "interrupt": false
            }
        }
    }
}

This module performs checks of file uniqueness and their usage in parallel processes. When some of these checks fails then an error or a warning is shown, depending on the configured check severity. In the interactive mode the user if informed by a message printed on the screen. When just a warning is shown then the user can confirm the message and continue. This is not possible for errors, where the continuation is not allowed.

In REST-API mode no such page is visible. When an error is found then the process is always interrupted and the message can be seen in the report. When a warning is detected then stop_when_warning parameter configures what to do. In the following examples we suppose that m_jcl_check_parallel module is started by t0450 task.

Example 1

In this case, the process is not interrupted when the check finds warnings because stop_when_warning=false. The process is interrupted only when the check finds errors.

{
    "process": 362,
    "action": "JCL_NEW_EX_REQUEST_FI",
    "ignore_predprocess_status": false,
    "activity_input_data": {
        "task" : { 
            ...  // here is setting of preceding tasks... 
            "t0450": {
                "stop_when_warning": false
            }
        }
    }
}

Example 2

In this case, the process is interrupted when the check finds any warning or error.

{
    "process": 362,
    "action": "JCL_NEW_EX_REQUEST_FI",
    "ignore_predprocess_status": false,
    "activity_input_data": {
        "task" : { 
            ...  // here is setting of preceding tasks... 
            "t0450": {
                "stop_when_warning": true
            }
        }
    }
}

In the interactive mode this module allows you to select files you want to add to your JCL/PROC/SYSIN process from the archive. When this process starts via REST-API then it is silent (not visible at all) and all the input must by provided via JSON object. In this case it is necessary to specify all information needed, which means: source system and library, target system and library, check system and members. Source files can be specified with wildcards in dataset/member names. Also versions can be specified, but they are optional and can't be used together with wildcards. When they are missing then the latest versions of selected files are used.It is also possible to optionally specify mapping using map_source_system, map_source_library, map_target_system and map_target_library. By default this mapping is not used.

Example 1 (imports archived JCL members with wildcards in their names and without versions)

As the interrupt parameter is specified and equals true then the process is interrupted after requested members are imported to the process by m_jcl_select_file_arc module. This allows you to open the process in interactive mode and check the result.

The import element must be an object, which must contain these items:

check_system

items

specifies members to be imported. Each of them is described by an object with target key:

The example imports all members matching OPC* member mask that exist in P391D.HOS.TEST library on SYSH_ID system.

• The target and source libraries are equal (there is no mapping).

• SmartJCL analysis runs on SYSH_ID system.

• the process is interrupted after the members have been imported.

Example 2 (imports archived JCL members without wildcards in their names. Some of imported members have versions specified)

As the interrupt parameter is specified and equals true then the process is interrupted after requested members are imported to the process by m_jcl_select_file_arc module. This allows you to open the process in interactive mode and check the result.The import element must be an object, which must contain these items:

check_system

items

Specifies members to be imported. Each of them is described by an object with target key. The format of files (specified as an array of strings) is SYS/DSN(MEM) or SYS/DSN(MEM)/MainVersion.SubVersion when versions are explicitly specified.

• The example imports the latest versions of TEST1 and TEST2 members and 3.1 version of TEST3 member from P391D.HOS.TEST library on SYSH_ID system.

• The target and source libraries are equal (there is no mapping).

• SmartJCL analysis runs on SYSH_ID system.

• The process is interrupted after the members have been imported.

Example 3 (imports deleted members ABC and DEF)

When the process config allows to process also deleted members then they can be imported into m_jcl_select_file_arc module when deleted=true is set. In this example two deleted members are loaded. The process immediately continues after successful import because interrupt=false is set:

Example 4 (using the mapping feature)

When you specify any of map_source_system, map_source_library, map_target_system and map_target_library then the appropriate standard values (without map_ prefix) are replaced with mapped ones just before the module ends. This way you can select a file from a library but save it somewhere else. You can therefore copy a file instead of changing it.In this example the latest version of TEST1 and 3.1 version of TEST3 members from P391D.HOS.TEST library are loaded from the archive. The target location is not the same but is changed to P391D.COPY.JOBLIB.

In the interactive mode this module allows you to select files you want to add to your JCL/PROC/SYSIN process. When this process starts via REST-API then it is silent (not visible at all) and all the input must by provided via JSON object. In this case it is necessary so specify all information needed, which means: source system and library, target system and library and check system. Source files can be specified with wildcards in dataset/member names.

Example 1 (import existing JCL members with wildcards in their names)

As interrupt parameter is specified and equals true then the process is interrupted after requested members are imported to the process by m_jcl_select_file_sys module. This allows you to open the process in interactive mode and check the result. The import element must be an object, which must contain these items:

check_system

Specifies the system where members are checked (where SmartJCL runs). It must be one of systems defined in system_mapping array.

items

Specifies members to be imported. Each of them is described by an object with these options:

source: the files to import. It must be an array where each item has SYS/DSN(MEM) format. Wildcards are allowed in member names.

target: the target library where the file should be stored in SYS/DSN format.

The example imports all members matching OPC* member mask that exist in P391D.HOS.TEST library on SYSH_ID system.

• The requested target location is P391D.HOS.JOBLIB on SYSH_ID system.

• SmartJCL analysis runs on SYSH_ID system.

• The process is interrupted after the members have been imported.

{
  "process": 250,
  "action": "JCL_NEW",
  "ignore_predprocess_status": true,
  "activity_input_data": {
    "task": {
      "t0400": {
        "interrupt": true,
        "import": {
          "check_system": "SYSH_ID",
          "items": [
            {
              "source": [
                "SYSH_ID/P391D.HOS.TEST(OPC*)"
              ],
              "target": "SYSH_ID/P391D.HOS.JOBLIB"
            }
          ]
        }
      }
    }
  }
}

Example 2 (import JCL members which are defined exactly)

• The example imports P391D.HOS.TEST(ABC) and P391D.HOS.TEST(DEF) members from SYSH_ID system.

• The requested target location is P391D.HOS.JOBLIB on SYSH_ID system.

• SmartJCL runs on SYSH_ID system.

• Once members are imported, the next tasks start automatically because interrupt=false.

{
  "process": 250,
  "action": "JCL_NEW",
  "ignore_predprocess_status": true,
  "activity_input_data": {
    "task": {
      "t0400": {
        "interrupt": false,
        "import": {
          "check_system": "SYSH_ID",
          "items": [
            {
              "source": [
                "SYSH_ID/P391D.HOS.TEST(ABC)",
                "SYSH_ID/P391D.HOS.TEST(DEF)"
              ],
              "target": "SYSH_ID/P391D.HOS.JOBLIB"
            }
          ]
        }
      }
    }
  }
}

Example 3 (import JCL members into two different target libraries)

• The example imports P391D.HOS.TEST(ABC) and P391D.HOS.TEST(DEF) and sets their target location to P391D.HOS.JOBLIB on SYSH_ID system.

• The example imports P391D.HOS.TEST(MEM1) and P391D.HOS.TEST(MEM2) and sets their target location to P391D.HOS.JOBLIB2 on SYSH_ID system.

• SmartJCL runs on SYSH_ID system.

• Once members are imported the next tasks start automatically, because interrupt=false.

{
    "process": 250,
    "action": "JCL_NEW",
    "ignore_predprocess_status": true,
    "activity_input_data": {
        "task" : { 
            "t0400": {
                "interrupt": false,
                "import": {
                    "check_system": "SYSH_ID",
                    "items": [
                        {
                            "source": ["SYSH_ID/P391D.HOS.TEST(ABC)",
                                       "SYSH_ID/P391D.HOS.TEST(DEF)"],
                            "target": "SYSH_ID/P391D.HOS.JOBLIB"
                        },
                        {
                            "source": ["SYSH_ID/P391D.HOS.TEST(MEM1)",
                                       "SYSH_ID/P391D.HOS.TEST(MEM2)"],
                            "target": "SYSH_ID/P391D.HOS.JOBLIB2"
                        },
                    ]
                }
            }
        }
    }
}

Example 4 (create members from supplied data)

• The example creates a new member, whose source lines are provided in the input JSON object in lines array.

• CommentShare feedback on the editorthe requested target location is P391D.HOS.JOBLIB(NEWMEM) on SYSH_ID system.

• CommentShare feedback on the editorSmartJCL runs on SYSH_ID system

{
    "process": 250,
    "action": "JCL_NEW",
    "ignore_predprocess_status": true,
    "activity_input_data": {
        "task" : { 
            "t0400": {
                "interrupt": true,
                "new": {
                    "check_system": "SYSH_ID",
                    "items": [
                        {
                            "member": "NEWMEM",
                            "target": "SYSH_ID/P391D.HOS.JOBLIB",
                            "lines": [
                                "//NEWMEM JOB",
                                "//EX     EXEC PGM=IEFBR14"
                            ]        
                        }
                    ]
                }
            }
        }
    }
}

The REST-API for this module can only be used to edit content.

In the interactive mode this module allows you to edit files provided in input interfaces. When the activity is started by REST-API then you can provide new content of selected members via the input JSON object.

Example 1 (change of JOBA member)

As the interrupt parameter is specified and equals true then the process is interrupted after the new content of JOBA is set. It allows you to open it later in the interactive mode and check it.The change array contains all required changes in selected files. It must be an array of object, there each object must contain member and lines attributes.

• The member is a member name that is searched for in input interfaces (i_file_list_sys, i_file_list_arc, i_file_list). When it is not found then en error is triggered.

• lines is an array of strings, where each array element is a line of a member.

{
    "process": 250,
    "action": "JCL_CHANGE",
    "ignore_predprocess_status": true,
    "activity_input_data": {
        "task" : { 
            "t0500": {
                "interrupt": true,
                "change": [
                    {
                        "member": "JOBA",
                        "lines": ["//JOBA JOB NOTIFY=&SYSUID",
                                  "//STEP1 EXEC PGM=IEFBR14",
                                  "//STEP2 EXEC PGM=IEFBR14"
                        ]
                    }
                ]
            }
        }
    }
}

Example 2 (change of JOBA and JOBB members)

As interrupt parameter is missing the module starts another module in the sequence once it has finished.Two members are edited: JOBA and JOBB.

{
    "process": 250,
    "action": "JCL_CHANGE",
    "ignore_predprocess_status": true,
    "activity_input_data": {
        "task" : { 
            "t0500": {
                "change": [
                    {
                        "member": "JOBA",
                        "lines": ["//JOBA JOB NOTIFY=&SYSUID",
                                  "//STEPA EXEC PGM=IEFBR14"
                        ]
                    },
                    {
                        "member": "JOBB",
                        "lines": ["//JOBB JOB NOTIFY=&SYSUID",
                                  "//STEPB EXEC PGM=IEFBR14"
                        ]
                    }
                ]
            }
        }
    }
}

The REST-API for this module can only be used to create or modify ADHOC records in IWSz process.

In the interactive mode, this module allows to create or modify ADHOC records and edit the operation list with JCL edit and JCL check.

Example 1 - Create ADHOC record without parameters

In the most simple case it is possible to create ADHOC record where all parameters are adjusted using Procman process config and environment config.

The REST-API should only contain the instruction "CreateADHOC" for the task with m_tws_adhoc_appl module.

{
  "process": 999,
  "action": "CREATE_ADHOC",
  "ignore_predprocess_status": true,
  "activity_input_data": {
    "task": {
      "t0140": {
        "instruction": {
          "type": "CreateADHOC"
        }
      }
    }
  }
}

Example 2 - Create ADHOC record with selected JCL jobs

In case that the ADHOC record loads JCL from the z/OS request, you have to call the previous task m_jcl_select_file_sys (t0130 in the example below) with selection criteria.

In the following example, the member JOB1 from the library JOBLIB1 is loaded.

{
  "process": 999,
  "action": "CREATE_ADHOC",
  "ignore_predprocess_status": true,
  "activity_input_data": {
    "task": {
      "t0130": {
        "interrupt": false,
        "import": {
          "check_system": "SYSTEM_ID",
          "items": [
            {
              "source": [
                "SYSTEM_ID/LIBS.JOBLIB1(JOB1)"
              ],
              "target": "SYSTEM_ID/LIBS.JOBLIB1"
            }
          ]
        }
      },
      "t0140": {
        "instruction": {
          "type": "CreateADHOC"
        }
      }
    }
  }
}

Example 3 - Create ADHOC record with ADHOC parameters

The request for ADHOC record can contain ADHOC parameters.

The parameters are placed in request to the adcom section inside inputAD node.

List of available parameters that can be used:

• adowner: Owner ID

• addesc: Text

• adodesc: Owner Text

• adprior: Priority

• adgroup: Authority group id

• adrjvtab: Variable table

{
  "process": 9999,
  "action": "CREATE_ADHOC",
  "ignore_predprocess_status": true,
  "activity_input_data": {
    "task": {
      "t0140": {
        "instruction": {
          "type": "CreateADHOC",
          "inputAD": {
            "adcom": {
              "addesc": "test ADHOC app",
              "adowner": "T139A",
              "adodesc": "ADHOC user",
              "adprior": "7",
              "adgroup": "GRPGROUP1",
              "adrjvtab": "ADHOCTABLE1"
            }
          }
        }
      }
    }
  }
}