The configuration of processes is divided into two files:
Contains definition of processes in XML format. To define a process is not an easy task and it is done by HORIZONT. It requires a knowledge of modules - code elements from which processes are built. They are described in details in the online Procman/HOS guide (doc.php script opens this documentation).
Each process definition calls modules and these modules are wrapped in tasks. Every task calls exactly one module and adds interfaces that configure how modules work and how they interchange data. When a module needs to know some data (i.e. not the program logic, but data elements like systems, datasets, ...) then this data is loaded from the environment. Process names, activities and task names are the keys that allow to link environment definition to the concrete task in the process definition.
This is just a brief introduction to the syntax of hos_process_config.php file that configures how processes work.
In case of a big installation there are many processes. To make the configuration more readable it is a good practice to split the process configuration to more files. Then hos_process_config.php can look like this:
Here processes for each client are defined in a special file and they are merged together and added to $hos_process['process'] array. Configuration for individual clients then has this format (just a few lines are shown):
The file must return an array (return array at 2nd line). Of course splitting the configuration to more files is not necessary and you can code your process definition directly in hos_process_config.php. Then it looks similar to this:
Every process is defined in one big array with a process name as the key. This key must match the process name in definition of processes in HWM (ProcMan administration web page):
In our sample the process name is JCL_CHANGE_PROD. There must be a sub array with 'activity' key, which contains definition of all activities of the process. In our sample the activity name is JCL_CHANGE_PROD_APPROVE and this activity must also exist in HWM in the list of Actions:
The activity consists of tasks that are defined in its sub arrays. Every sub array contains these mandatory items:
name unique identification of the task in its activity. It must be unique in the activity. Task names must be sorted by alphabet. That means a name of the first task must be alphabetically smaller than a name of second one and so on.
type currently it must equal 'task'.
module a name of a module called by the task when the process is running. The modules are building blocks of the process. They contain a real source code that is interpreted. All available modules are described in online documentation (doc.php script).
The majority of modules require some input data and configuration and also provide some data and configuration. There are 2 methods how this information can be passed to the modules.
1. Interfaces Modules communicate with other modules via their interfaces. Interfaces are information canals that connect modules in the activity. They can contain configuration options which control how the modules behave and they can contain also data that are passed from one module to another. There is detailed information about interfaces that each module requires and provides in the online documentation (doc.php script). Modules can accept some interfaces also optionally - some of them are not mandatory. All input interfaces (both mandatory and optional) must be specified in the task in 'input' array. If some interface that the module can provide should be passed to succeeding module (because it requires it) then its name must be listed in the 'output' array. There already exist 'pass' array. It is used when a module provides an interface that is not required by next module but by another one (if it is far away then such an interface can be passed through several modules via 'pass' array). Let's illustrate it on a sample:
This is an extract of a configuration of JCL_NEW_PRE_PROD_REQUEST activity from JCL_NEW_PRE_PROD process. Four tasks of the activity are shown (the full activity has about 10 tasks).
t0100 this task calls m_jcl_start module. The module does not require any input interface and that's why 'input' array is missing. This task creates i_jcl_config interface. This interface is created "inline", that means by setting all its options in the configuration. More about it later.
t0200 this task calls m_set_hwm_parm module. This module sets HWM variable and therefore it requires its name and value on the input. The input is provided via i_hwm_set_parm interface, which the module requires (you can verify it in doc.php documentation). Also in this case the interface is allocated "inline". The module doesn't accept i_jcl_config interface and because this interface was allocated by t0100 task (as it is needed later in the process) it must be passed through t0200 so that m_set_hwm_parm module does not see it. Interfaces passed this way must be specified in 'pass' array.
t0400 this task prompts a user to select files processed by the process. it calls m_jcl_select_file_sys module that can list datasets and members directly from z/OS. This module needs to know the environment (to offer correct datasets and systems). It also requires i_jcl_config that contains an information about a type of data (JCL/PROC/SYSIN) and it must know where to go in case of errors (i_goto). Finally it requires configuration of itself via i_jcl_select_file_sys. All these interfaces are required and must be specified in the 'input' array. The task outputs interfaces that are required in other tasks of the process.
Inline interfaces are allocated by the engine at the moment the module starts. Very often you can see non-empty value of the interface (in our example it is the case of i_jcl_select_file_sys, i_jcl_config and i_set_whm_parm). Inline interfaces can be allocated by the task that calls a module that requires it in its 'input' array. It is also possible to allocate it by the preceding task in its 'pass' array. There are slight differences between these two methods which go beyond a scope of this document. When the value of an interface in 'input' array is empty that the interface must already exist. It must be passed to the module from preceding task. That means the preceding module must contain this interface in its 'output' or 'pass' array.
There are several modules in the process definition that must know ID of systems where data are loaded from, where there are analyzed and where generated members should be stored. In order we avoid specifying these values for every task we put this information (source_system, target_system, check_system) in a block with * in a place of task name. As a result all tasks in the activity know these values.On the other hand, source_library, target_library and member is required in t0400 task only (calls m_jcl_select_file_sys module). For this reason we put this information only in the array with 't0400' key. We could put it in the previous one as well, it would work, too.
Contains definition of data available in processes. The definition is a part of hos_config2.php script, but it is very often moved to an external file and included from hos_config2.php.
t0300 this tasks offers (by calling m_environment module) a selection of environments or it select the only one that exists. On the input it requires i_goto interface that says to the module where to redirect in case on an error. On the output it provides i_environment interface that keeps the selected and all its setting in memory. This interface is not allocated inline but by the module and that's why its value in empty. The module does not accept i_jcl_config so the task passes it through by putting it to 'pass' array.
Environment setting Interfaces set how the process work (what functionality it offers) and environment setting sets with what kind of data it works. Detailed description of all options available in the environment is included in section of this document. Here we only show how the environment and process definition are linked together. This is a sample how the environment can look like for our JCL_NEW_PRE_PROD_REQUEST activity:
