When this constant is FALSE then no debug information is printed to the log file. To print debug information set it to TRUE:

define('DEBUG_FILE_ENABLED', true);    // print debug info to file

This constant is false by default, which deactivates debug information on the screen. It is intended only for HORIZONT support and you should keep it false.

define('DEBUG_SCREEN_ENABLED', false);    // print debug info on the screen

$wai_ext_dicitionary_files

This PHP variable in an array that contains names of files with dictionaries. By default only hos.xml file is added to this list. This file contains translations of all text appearing in Procman/HOS in English and German language. Maybe you need to define your own dictionary with text used in your processes. As you should never put your own text to hos.xml (as it is always a part of official new release and your changes would be lost), you can create your own dictionary and register it by this variable.

Example (default setting) :

To add another dictionary (in this case loaded from my_own_dictionary.xml), add another line similar to this:

The order of the files is important. If the same text id is used in more files then the one lastly read is used. Therefore, always use hos.xml at the top and your own dictionaries below.

Introduction

This document contains complete description of Procman/HOS configuration (i.e. configuration that is required for running JCL, SYSIN, DSN and IWSz processes).It does not contain description of the Procman/HWM part, which is a framework that executes processes.

The document is structured as follows:

The basic configuration (options not related to processes) is divided to several files:

There are three file formats used for a configuration of Procman/HOS.

XML

Standard XML format is used for user forms and dictionaries. The files must be syntactically correct in order the parser is able to open them. It is very important to have all user forms in a valid format, as all user forms are in some cases included in HOSXIN XML member that is sent to the host for JCL analysis. In case of an invalid form the whole HOSXIN XML become invalid and the analysis fail. Therefore make sure that you don't have old or temporary and unchecked XML user forms in etc/forms dictionary.

INI

PHP

The vast majority of configuration is in PHP format. PHP config files are included in other PHP scripts and are interpreted when the web application starts. Therefore it is strictly required that the PHP syntax in your config files is correct, otherwise the web application can't start. The advantage of this approach is that you can use any constructs that are supported by PHP in your config files. This for example allows you to include your own file with PHP variables that you can use in all PHP config files. You can build complex strings by concatenations, split big arrays to smaller blocks and much more. This makes the whole configuration more readable and maintainable.

This option controls compatibility of PHP code with z/OS modules. If you use PRC scripts (i.e. the older version) on the host then you should set version to "3.2". If you use the latest PRX scripts (extended version of PRC) then "5.0" version is required.

define('HOS_VERSION', '5.0');

This constant sets how detailed logs are written to HOS log file when DEBUG_FILES_ENABLED is true. The higher number is used the more detailed information is printed.

define('DEBUG_ML', 2);    // message level

This file is included from hos_config.php and extends $hos_config PHP variable (array allocated in hos_config.php) with many options that configure your installation.

For the initial setup, e.g. after an installation, please look into the following article:

Procman/HOS allocates temporary datasets on the system where it submits jobs (for JCL analysis, generation, checking or copying). The dataset name is built by appending the last qualifier to the prefix that is configured by base_tmp_dsn option.

In the sample below, all datasets created on DEMO_ID system start with P391D.HOS.DEMO.TEMP and datasets created on SYSH_ID system start with P391D.HOS.SYSH.TEMP.

This setting is valid for all clients (as there is an asterisk). You can replace it with a client name (and also add more clients) to have the prefix different for each client.

• format - specifies format of the generated members.

• automatically_filled - specifies a number of jobs per source member generated when Duplicate button is pressed.

• silent - allows to create copies without any page being displayed when it equals true.

'duplicate_member' => [
    'format'                     => 'D&member5.$inc2',
    'automatically_filled'       => 1,
    'silent'                     => false

Deprecated - duplicate_member_automatically_filled

'duplicate_member_automatically_filled' => 1,

This option specifies the number of generated job names per each source member when the Duplicate button is pressed.

Deprecated - duplicate_member_format

This option specifies how new member names are generated when Duplicate button is pressed. By default (when the option is empty) the names are constructed by concatenating 'DUP' and a serial number coded on 5 positions and filled with zeroes from left. For example if you want to duplicate 3 members then DUP00001, DUP00002 and DUP00003 are generated by default. Of course these names can be later edited.

Alternatively, if you are not satisfied with the default format, you can set another rules via duplicate_member_format option.

Tokens listed below are searched in duplicate_member_format option and if they are found then they are replaced with values they represent. All remaining letters are kept at their positions.

&userid. name of the current user.

&userid[1-8]. results in the user name complemented from right with 'X' letter up to the length specified by the number or it is a substring of userid if the number is lower then the name's length. [1-8] means a number in 1-8 range. &procid. process id.

&procid[1-8]. results in the process id complemented from left with 0 up to the length specified by the number or it is a substring of procid if the number is lower then a length of the process id. [1-8] means a number in 1-8 range.

&suffix. one automatically generated letter.

&inc. sequence number (1, 2, ....).

&inc[1-8]. sequence number coded on the specified number of positions, filled from left with zeroes. &member. source member name.

&member[1-8]. substring of the source member name (the number specifies the new length).

&var(?). HWM variable's value (code variable name in a place of the question mark).

&var(?)[1-8]. substring of the HWM variable value.

'duplicate_member_format' => '',

The dot coded at the very end of duplicate_member_format can be omitted.

A few samples (assuming that the user name is P391D, PID=166, automatically generated suffix is 'W' and the sequence number is 12):

$&userid.&suffix - result: $P391DW

TEST&suffix.&procid3 - result: TESTW166

&suffix.&procid6.&suffix - result: W000166W

PO&inc6 - result: PO000012

The process configuration defines a list of operations (tasks) executed in sequence. This sequence configures what the process does. But you must also set where and with what data the process works, what JCL skeletons are used, what dataset and systems are used, what JCL statements are supported and so on. For setting this kind of options you must use the environment.You can have general part of the environment, that is valid for all processes and a specific one that is valid only for some process. The general part and the specific part are usually merged together, which produces the final set of environmental options.

The environment is sometimes very large, especially when you have many processes or several clients. In this case it is a good practice to split the environment to more files, for example one per a client, and include them like in the following example:

'environment' => array(
    'client' => array_merge(
        include('hos_env_general.php'),
        include('hos_env_client1.php'),
        include('hos_env_client2.php'),
        include('hos_env_client3.php')
    ),
),

A content of each included file looks like in the sample below (only a part is displayed here, as the setting is too large).

This example is used for generic part of the environment that is valid for all clients, processes, activities and names of environment. This is because of to asterisks used for client, process, activity and name. This way you can predefine default values (typically templates - sometimes they are called skeletons, supported statements, ...). This general part should be placed on the top (therefore hos_env_general.php is the first included file in the sample). Some options can be later overwritten by other included files. There is a rule that the last setting wins. Procman processes the complete environment definition from the top to the bottom. If some option is defined more times then the last one is finally used.

For this reason always follow this simple rule: put the most general setting (with most wildcards) on the top and more restrictive ones (with named clients, processes, activities, ... ) below.

Comments typed in green in the sample explain what is the meaning of the value on the line where they are coded.

• You can type * (it means all clients) or a real client name on the line with '// client name' comment.

• You can type * (it means all processes) or a real process name on the line with '// process name' comment.

• You can type * (it means all activities) or a real activity name on the line with '// activity name' comment.

• You can type * (it means all environment names) or a real environment name on the line with '// environment name' comment.

return array (
    '*' => array (  // client name
        'request' => array (  // process name
            '*' => array (  // activity name
                'activity' => array (
                    '*' => array (
                        'environment' => array (
                            '*' => array (  // environment name
                                'codepage' => '273',
                                'temp_dsn_alloc_site' => 'cy pri=15 sec=30 di=500',
                                'template' => array (
                                    'jck_job_new'         => 'HOSJCHKN',
                                    'jck_job_change'      => 'HOSJCHKC',
                                    'jck_job_editchk1'    => 'HOSJEDIT',
                                    'jck_job_approve'     => 'HOSJEDTA',
                                    'jck_job_reft'        => 'HOSJREFT',
                                    'jck_job_ref'         => 'HOSJREF',
                                    'jck_job_final'       => 'HOSJEDTF',
                                    'jcl_new_gen'         => 'JCLGEN', // for JCL_NEW
                                ),
                                'jcl_result_files' => array (
                                    'JCKSUMO'  => true,
                                    'SYSPRINT' => true,
                                    'JCKDTLO'  => true
                                ),
                                'jcl_supported_statements' => array (
                                    'OUTPUT' => true,
                                    'SET'    => true,
                                    'INCLUDE'=> true
                                ),
                                'jcl_dd_forms' => array (
                                    '_'                         => 'DDI_Other',
                                    'FRM_JCK_DD_DSN_IZ'         => 'DDI_Output',
                                    'FRM_JCK_DD_REPORT_IZ'      => 'DDI_List',
                                    'FRM_JCK_DD_DSNIW_IZ'       => 'DDI_Workdataset',
                                    'FRM_JCK_DD_SYSOUT_IZ'      => 'DDI_Protocol',
                                    'FRM_JCK_DD_SYSIN_IZ'       => 'DDI_Controlcards',
                                    'FRM_JCK_DD_DSNI_IZ'        => 'DDI_Input'
                                ),
                            )
                        )
                    )
                )
            )
        )
    )
);

Of course you easily put the environment directly into hos_config2.php without splitting to more files. Then the option looks like this (also not complete):

'environment' => array (
    'client' => array (
        '*' => array (
            'request' => array (
                '*' => array (
                    'activity' => array (
                        '*' => array (
                            'environment' => array (
                                '*' => array (
                                    'codepage' => "273",
                                    'temp_dsn_alloc_site' => 'cy pri=15 sec=30 di=500',
                                    'template' => array (
                                        'jck_job_new'       => 'HOSJCHKN',
                                        'jck_job_change'    => 'HOSJCHKC',
                                        'jck_job_editchk1'  => 'HOSJEDT',
                                        'jck_job_approve'   => 'HOSJEDTA',
                                        'jck_job_reft'      => 'HOSJREFT',
                                        'jck_job_ref'       => 'HOSJREF',
                                        'jck_job_final'     => 'HOSJEDTF',
                                        'jck_job_fast'      => 'HOSJEDTF',
                                        'jck_proc_new'      => 'HOSPCHKN'
                                    )
                                )
                            )
                        )
                    )
                )
            )
        )
    )
)

A sample with explicitly specified values (no more asterisk is used):

return array (
    'CLIENT1' => array (
        'request' => array (
            'JCL_NEW_GEN_FI' => array (
                'activity' => array (
                    'JCL_NEW_GEN_REQUEST_FI' => array (
                        'environment' => array (
                            '!Test environment 1' => array (
                                'task' => array (
                                    '*' => array (
                                        'source_system' => 'SYSH_ID',
                                        'target_system' => 'SYSH_ID',
                                        'check_system'  => 'SYSH_ID',
                                    ),
                                    't0400' => array (
                                        'source_library' => array (),
                                        'target_library' => array ('!P391D.PETRH.TEMP1'),
                                        'member'         => array ('*'),
                                        'member_mask'    => '.*'
                                    )
                                )
                            )
                        )
                    )
                )
            ),
            'JCL_NEW_GEN_APPROVE_FI' => array (
                'environment' => array (
                )
            )
        )
    )
);

It is clear what client, process and activity are. But what is the environment? Every process contains m_environment module at the beginning. This module scans your environment setting and finds all distinct values used as environment names. In case of our samples only 'Test environment 1' is found. Therefore we have only one environment name. When the module finds only one environment then it uses it automatically. If more environment names are found then the module offers a selection. Once the environment is selected the whole process works with its setting. Therefore you can define more than one environment (which can contain system definitions, templates, ...) and allow the user to choose the one he wants at the beginning of the process. In spite of the fact this idea can be useful in some cases it is not usually configured in real installations. Most often you have only one environment name that is used throughout all your configuration files. Just make sure that once you run some process then the environment name in your configuration is not changed any more.

In the following sub sections all environmental options are described in details.

By this option you can specify datasets that can never be deleted or from which members can never be deleted. If a user select such a dataset in DELETE process then he is informed that the deletion is not allowed.

/* excluded datasets and members (files that can never be deleted)
 * you can use '*' instead of the client
 * you can use wildcards for filenames, a few samples:
 *    A.B.C    - doesn't allow to delete dataset A.B.C (PO or PS). Members is PO can be deleted
 *    A.B.C(*) - doesn't allow to delete any member from the dataset and the dataset itself
 * you can use wildcards (? and *) also in the dataset name (not only member)
 */
 
 'exclude_delete' => array (
    'SYSH_ID' => array (  
        'P391D.HOS.DATA.OUT(*)',
        'P391D.HOS.DATA.MIRROR1(*)',
        'P391D.HOS.DATA.MIRROR2',
        'P391D.HOS.DATA.MIRROR3'
    )
)

You can use wildcards instead of the system id (SYSH_ID in the example). In the inner array you can specify datasets or masks with wildcards. If the real dataset that a user selects in the process matches an item in exclude_detete then the deletion is not allowed. If you specify ( and ) like in first two lines in the example then the dataset can't be deleted as well as any of its members. When brackets are missing then members from the dataset can be deleted, but not the dataset itself. The result of the example is as follows:

• members can't be deleted from P391D.HOS.DATA.OUT

• members can't be deleted from P391D.HOS.DATA.MIRROR1

• P391D.HOS.DATA.OUT can't be deleted

• P391D.HOS.DATA.MIRROR1 can't be deleted

• P391D.HOS.DATA.MIRROR2 can't be deleted

• P391D.HOS.DATA.MIRROR3 can't be deleted

Typically you have several user forms defined for DD statements in your Procman/HOS installation and typically PRX code recognizes what form to assign to every DD statement while the JCL analysis is running. After the analysis you can see all DD statements found in the analyzed job in a table and you can start to enter user input:

The content of select boxes in DD Type column is built from jcl_dd_forms option. This option maps form names (names of form XML without ".XML" extension) to a text id used in a dictionary. As a result you see correct texts in the select boxes and you can change the form type by mouse.

'jcl_dd_forms' => array (
    '.'                         => 'DDT_Other',
    'FRM_JCK_DD_DSN_IZ'         => 'DDT_Output',
    'FRM_JCK_DD_REPORT_IZ'      => 'DDT_List',
    'FRM_JCK_DD_DSNW_IZ'        => 'DDT_Workdataset',
    'FRM_JCK_DD_SYSOUT_IZ'      => 'DDT_Protocol',
    'FRM_JCK_DD_SYSIN_IZ'       => 'DDT_Controlcards',
    'FRM_JCK_DD_DSNI_IZ'        => 'DDT_Input'
),

• template template name used as a base for the job that is generated and submitted (calls PGM=OSJIBAT).

• tws_sys id if the system where the substitution runs.

• app_id_pad letter used for padding of the application id to 16 letters if app_id_prefix is not specified.

• app_id_prefix prefix used for padding of application id to 16 letters. When it exists then app_id_pad is ignored.

• wsid id if the workstation that appears in the substituted job.

• iat input arrival time in HHMM format that appears in the substituted job.

/*
'jcl_osj' => array (
    '<TargetSysIdMask>' => array (
        '<TargetDsnMask>' => array (
            'template'      => '<template_job_name>',
            'tws_sys'       => '<tws_system_id>',
            'app_id_pad'    => '<padding characters for app>',
            'app_id_prefix' => 'prefix of up to 12 letters, has higher prio than pad when specified',
            'wsid'          => '<workstation id>',
            'iat'           => '<input arrival time>'
        )
    )
)
*/

'jcl_osj' => array (
    '*' => array (
        'P391D.DEV.*' => array (
            'template'      => 'HOSJOSJ',
            'tws_sys'       => 'SYSH_ID',
            'app_id_pad'    => 'X',
            'app_id_prefix' => 'TEST',
            'wsid'          => 'CPU',
            'iat'           => '0600'
        )
    )
),

This option sets what log files are downloaded after JCL analysis. You can deactivate some of the files if you don't need them, nevertheless it is not recommended. Every file contains useful information. Setting the value to true like in the example enables the log file and Procman/HOS downloads it.

'jcl_result_files' => array (
    'JCKSUMO'  => true,
    'SYSPRINT' => true,
    'JCKDTLO'  => true
),

• JCKDTLO detailed listing of errors, warnings and notifications found by SmartJCL

• JCKSUMO summary listing.

• SYSPRINT SYSPRINT of SmartJCL.

The value entered here is used when skeletons are substituted (when ##CODEPAGE## variable is replaced). PRX code must know the codepage used on z/OS so that it is able to correctly convert special characters. The default value (if it is not explicitly set by codepage option) is 273.

Example:

'environment' => array (
    '*' => array (
        'codepage' => "037",

'jcl_supported_statements' => array (
    'OUTPUT'  => true,
    'SET'     => true,
    'INCLUDE' => true
),

Note that JOB, EXEC and DD are always enabled. You can disable only OUTPUT, SET and INCLUDE.

Use this option if you want to copy members by the copy module also to additional libraries. Members written to mirrored datasets are not stored in a database. This option only ensures that a backup of members that are copied to target libraries is also copied to mirrored libraries. If the real target system and dataset match the ones specified by target_mirror option then copying to locations specified in the inner array is done. You can copy members to more than one library or system if you want. You can use wildcards both in and and also in and , as is shown in the sample below.

/*
 * 'target_mirror' => array (
 *     '<TargetSysId>' => array (
 *         '<TargetDsn>' => array (
 *             '<MirrorSysId>' => array (
 *                 '<MirrorDsn1>',
 *                 '<MirrorDsn2>',
 *                 '...'
 *             )
 *         )
 *     )
 * )          
 */              

'target_mirror' => array (                                          
    'SYSH_ID' => array (
        'P391D.HOS.DATA.SYS' => array (
            'SYSH_ID' => array (
                'P391D.HOS.DATA2.SYS'
            )
        ),                                          
        'P391D.HOS.DATA.OUT' => array (
            'SYSH_ID' => array (
                'P391D.HOS.DATA.MIRROR1',
                'P391D.HOS.DATA.MIRROR2',
                'P391D.HOS.DATA.MIRROR3'
            ),
            'SYSH2_ID' => array (
                'P391D.HOS.DATA.PRE.MIRROR1',
                'P391D.HOS.DATA.PRE.MIRROR2'
            )
        )
    )                                          
),

In the case of the above example this mirroring occurs:

• If the target dataset is P391D.HOS.DATA.SYS on SYSH_ID system then members are mirrored to P391D.HOS.DATA2.SYS on the same SYSH_ID system.

• If the target dataset is P391D.HOS.DATA.OUT on SYSH_ID system then members are mirrored to:

  1. P391D.HOS.DATA.MIRROR1, ...MIRROR2, ...MIRROR3 on SYSH_ID system

  2. P391D.HOS.DATA.PRE.MIRROR1,, ...MIRROR2 in SYSH2_ID system.

In the following examples mapping takes effect then any qualifier(s) appears at the place of asterisk:

'target_mirror' => [
    'DEST_ID' => [
        'DDD.PROCMANT.TARGET.*.STEUKA' => [
            'SRC_ID' => [
                'DDD.PROCMANT.TARGET.*.STEUKA.MIRROR'
            ]
        ]
    ]
]

Or with their variables:

'target_mirror' => [
    $vwpmss_DEST_id => [
        'DDD.PROCMANT.TARGET.*.STEUKA' => [
            $vwpmss_SRC_id => [
                'DDD.PROCMANT.TARGET.*.STEUKA.MIRROR'
            ]
        ]
    ]
]

It will map:

DDD.PROCMAN.TARGET.AAA.STEUKA to DDD,PROCMAN.TARGET.AAA.STEUKA.MIRROR DDD.PROCMAN.TARGET.BBB.STEUKA to DDD,PROCMAN.TARGET.BBB.STEUKA.MIRROR DDD.PROCMAN.TARGET.AAA.BBB.STEUKA to DDD,PROCMAN.TARGET.AAA.BBB.STEUKA.MIRROR

The mirroring works also when files are deleted. In this case approved members are deleted from target libraries as well as from all their mirrors.

When Procman/HOS needs to submit a job on the host then it first reads an appropriate template (skele-ton of the JOB) and makes substitution of special variables (they are surrounded with ##). A result of this substitution is a real valid job that is subsequently copied to temporarily allocated dataset and sub-mitted. There are many templates in Procman/HOS which are used in many scripts. There are templates for JCL analysis and generation, for checking JCL after is has been edited, for copying to the host and much more. In PHP scripts names of templates are used instead of member names in order to allow to set member names freely. The mapping of template names to member names must be correctly defined by template option. The example below is not complete, it only shows the syntax. A list of standard tem-plates is listed below the sample.

'template' => array (
    'jck_job_new'          => 'PRXJNEW',
    'jck_job_change'       => 'PRXJCHA',
    'jck_job_editchk1'     => 'HOSJEDT',
    'jck_job_editchk1_tws' => 'HOSJEDT1',
    'jck_job_approve'      => 'HOSJEDTB',
    'jck_job_tws_approve'  => 'HOSJJCKT',
    'jck_job_reft'         => 'HOSJREFT',
    'jck_job_ref'          => 'HOSJREF',
    'jck_job_final'        => 'HOSJEDTF',
    'jck_job_fast'         => 'HOSJEDTF',
    'jck_proc_new'         => 'HOSPCHKN',
    'jck_proc_change'      => 'HOSPCHKC',
    ...
)

Standard templates:

• jck_job_new JCL analysis in JCL NEW processes (m_jcl_analyse_1 module).

• jck_job_change JCL analysis in JCL CHANGE processes (m_jcl_analyse_1 module).

• jck_job_editchk1 JCL check of jobs in the request activity (m_jcl_change, m_jcl_change_objects, m_jcl_generate modules and in the preview started from m_jcl_fillforms module).

• jck_job_editchk1_tws JCL check of jobs with IWS variable substitution in the request activity (m_jcl_change, m_jcl_change_objects, m_jcl_generate modules and in the preview started from m_jcl_fillforms module).

• jck_job_ref JCL generator in JCL processes (m_jcl_analyse_2 module).

• jck_job_approve JCL check of jobs started from m_jcl_approve module.

• jck_job_tws_approve JCL check of jobs with TWS variable substitution started from m_jcl_approve module.

• jck_job_final final JCL check of jobs executed after members have been copied to the target libraries (m_jcl_final_check module).

• jck_job_fast fast JCL check of jobs (from target libraries, members are not copied to temporary dataset), available in m_hos_jcl_approve module.

• approve_regenerate_job JCL generator started from m_jcl_approve module (uses selected jobs as the input).

• jck_proc_new JCL analysis in PROC NEW processes (m_jcl_analyse_1 module).

• jck_proc_change JCL analysis in PROC CHANGE processes (m_jcl_analyse_1 module).

• jck_proc_editchk1 JCL check of procedures in the request activity (m_jcl_change, m_jcl_change_objects, m_jcl_generate modules and in the preview started from m_jcl_fillforms module).

• jck_proc_editchk1_tws JCL check of procedures with IWS variable substitution in the request activity (m_jcl_change, m_jcl_change_objects, m_jcl_generate modules and in the preview started from m_jcl_fillforms module).

• jck_proc_ref JCL generator in PROC processes (m_jcl_analyse_2 module).

• jck_proc_approve JCL check of procedures started from m_jcl_approve module.

• jck_proc_tws_approve JCL check of procedures with TWS variable substitution started from m_jcl_approve module.

• jck_proc_final final JCL check of procedures executed after members have been copied to the target libraries (m_jcl_final_check module).

• jck_proc_fast fast JCL check of procedures (from target libraries, members are not copied to temporary dataset), available in m_hos_jcl_approve module.

• approve_regenerate_proc JCL generator started from m_jcl_approve module (uses selected procedures as the input).

• change_by_parm_jobname1 analysis of selected JCL/PROC members in 'Change by parameters' function in m_jcl_fillforms module.

• change_by_parm_jobname2 generation of new JCL/PROC members that performs required changes in 'Change by parameters' function in m_jcl_fillforms module.

• change_cc when control cards are processed in JCL processes then a special job with variables that are substituted is analyzed instead of the selected member (because valid JCL is required by the analyzer). The member that is analyzed (by subsequent m_jcl_analyse_1 module) is specified by this template.

• copy copying of members to target libraries by m_jcl_copy module (members are first copied to temporary library and then the copy job is submitted).

• fast_copy copying of members to target libraries by m_jcl_fast_copy module (assumes the members already exist on the host, which is typically a case of INIT processes).

• delete deletion of members from target libraries by m_jcl_delete module.

• gdg_change_limit changing GDG limit in DSN processes by m_dsn_gdg_submit module.

• dsn_append_tape appending (merging) datasets into the target dataset (newly created) in DSN_APPEND processes (m_dsn_append_submit mudule) in case of TAPE device type.

• dsn_append_volume appending (merging) datasets into the target dataset (newly created) in DSN_APPEND processes (m_dsn_append_submit mudule) in case of VOLUME device type.

• dsn_rename renaming datasets in DSN_RENAME processes by m_dsn_rename_submit module.

• dsn_copy copying datasets in DSN_COPY processes by m_dsn_copy_submit module.

• idcams an alternative template used instead of gdg_change_limit. When this template is defined then it has a higher priority (by default it calls IDCAMS utility).

• dsn_gtyp finds current GDG limits of selected datasets in DSN processes by m_dsn_gdg_enter module.

• dsn_parm finds parameters of selected datasets in DSN processes by m_dsn_append_enter module.

• split members that are checked by JCL checker or members where IWS variables should be substituted have to be copied to the host into a temporary dataset. This copying takes a while when members are copied one by one. If more members are copied then Procman/HOS can use a fast method of saving members to the host. All files are concatenated in one single PS dataset and split to members by IEBUPDTE utility. To enable this fast method the split template must be defined. Even when the template is defined Procman/HOS can decide to use the standard one by one method if the number of analyzed files is small.

• universal job that is submitted in UNIVERSAL processes by m_universal_submit module.

There can be other user-defined templates as well. They are used in interfaces of process configuration in cases when the template name is configurable by the user. Names of such templates are fully under control of the administrator who prepares your process definition. A typical example of such a template is (extracted from process configuration):

array (
    'name'     => 't0500',
    'type'     => 'task',
    'module'   => 'm_jcl_final_jck_auto',
    'input'    => array (
        'i_goto'          => '',
        'i_environment'   => '',
        'i_jcl_approve'   => '',
        'i_log'           => '',
        'i_jcl_final_jck' => 'template_index_jcl="jck_job_final", ' .
                             'template_index_proc="jck_proc_final", ' .
                             'skip_in_manual_mode=true',
    ),
    'output'   => array (
        'i_log'         => '',
        'i_jcl_approve' => '',
        'i_goto'        => '',
        'i_environment' => ''
    )
)

By this option you can specify parameters used for allocation of temporary PO datasets. These datasets are allocated for jobs that Procman/HOS submits and for members that are analyzed. You can specify units (tr, cy), primary and secondary quantities, directory blocks and type.

Example:

'environment' => array (
    '*' => array (
        'temp_dsn_alloc_site' => 'tr pri=15 sec=30 di=500 dsntype=library',
    )
)

This option is needed for specifying parameters of tasks used in process configuration. The process configuration consists of several tasks grouped into activities. Many of tasks used there need to know some input data, for example system names, dataset names, and much more. The options which are required are described in details in the online help of Procman/HOS and therefore we show only a sam-ple demonstrating how to configure these options. The fact that the process definition and task options are separated helps to separate process logic from the data like systems, datasets, content of select boxes,...

The example is just a little part of the environment definition. All preceding options of the environment are usually inserted in the request and activity specified with wildcards. But this is usually not the case of task option. This is because task options must be valid for concrete process definition and the task names in the environment and in the process definition must match. In the example we use t0400 task and we define several options in the inner array. These options will therefore be available in t0400 task of JCL_CHANGE_PROD_APPROVE activity of JCL_CHANGE_PROD process in HORIZONT client. In this case t0400 in the corresponding process configuration calls m_jcl_approve module, which shows the approve web page. Systems and datasets coded in the environment are required by this module in order it is able to offer correct systems and libraries in its select boxes.

There are a few methods how to define items in the task array. Each one produces a different result on the web page. All available methods are listed below.

• constant:

In this case there is no visible field on the web page, where the user can select or see the value. The value is always SYSH_ID and it can't be edited and it is hidden.

• empty text field:

In this case an empty text field is displayed on the web page:

• initialized text field:

In this case a text field is rendered on the web page and its content is initialized with the value speci-fied in the array.

• read-only text field:

In this case the value can't be changed (like when you define a constant), but it is visible on the screen. You can make the field read-only by adding ! in front of the value. The result is:

• select box:

In this case a select box is rendered on the web page. When you specify only values like in case of the target library then you see exactly the values from the array. You can also specify a value and a label separated by a colon. In this case you see the label but the value is used when an item is selected. This is common when you specify systems, as their ID is im-portant for Procman/HOS while the label is important for users.

• select box with a default value:

Enter ! in front of the value you wish to select by default:

In this case P391D.PETRH.TEMP2 is selected by default when the page is first displayed:

• reference:

Use it when the value is the same as a value of another field:

• conditional field:

It is possible to render a field by any of the preceding methods conditionally. That means the rendering method depends on a value of another field:

In this case when SYSH_ID export system is selected then the export library shows an edit field initial-ized with your SYSUID followed with '.DATA.TEST'. If SYSH2_ID system is selected then the export library changes to a select box with two items.

and

You can also use remote dependencies in conditional fields. They are available only in some cases (when the referenced task stores data to JCKIN database table). This shows a reference in the same activity:

The target library is rendered as a read-only edit field initialized with P391D.PETRH.TEMP1 if the tar-get library selected at task t0500 in the same activity is P391D.NEW.TEMP1. The second row should be clear, it is analogous.

This sample shows a reference to another activity:

In this case the condition is based on target_library option of t0500 task in JCL_CHG_REQUEST activity.

You can use variables in any value used in task options. Please note the mandatory dot at the end. Available variables are:

• %SYSUID. it is replaced with the user that is logged in Procman in upercase.

• %(VAR). it is replaced with VAR HWM variable.

• %(VAR,n). it is replaced with a substring of VAR HWM variable that starts at 'n' position. The position is 1-based.

• %(VAR,n,p). it is replaced with a substring of VAR HWM variable that starts at 'n' position and has a maximal length equal to 'p' . The position is 1-based.

Let's now assume that the current user is P391D and that HWM variable DEPARTMENT equals 'DEP14':

%SYSUID..JOBLIB.* is substituted as P391D.JOBLIB.* %SYSUID..JOBLIB.%(DEPARTMENT)..* is substituted as P391D.JOBLIB.DEP14.* %SYSUID..JOBLIB.%(DEPARTMENT,3)..* is substituted as P391D.JOBLIB.P14.* %SYSUID..JOBLIB.%(DEPARTMENT,1,4)..* is substituted as P391D.JOBLIB.DEP1.*

You can use variables also in keys of conditions. A few examples:

If the selected source_system equals the value of TESTVAR1 HWM variable then use the first value. If the selected source_system equals the value of TESTVAR2 HWM variable then use the second value. Else use the last default value:

If the value of client HWM variable equals TEST then use the first value. If the value of client HWM variable equals HORIZONT then use the second value.

Else use the last default value:

By this option you can specify parameters used for allocation of temporary PS datasets. This is used when HOSXIN dataset is created. You can specify space and units (tr, cy).

This option configures how the page with files listed from an archive reacts on mouse clicks and what columns the list contains.

• grid_member_action configures mouse click reaction at the member name in the main table (the top one). Possible values are:

• empty string do nothing - in this case the member is not rendered as a hyperlink.

• browse member is browsed when clicked.

• select clicked member is selected and the page is confirmed, which triggers continuation in the process with further tasks.

• add member is added to the table below (table with selected members).

• sel_member_action configures mouse clicks in the table below the main table. Possible values are:

• empty string do nothing, no hyperlink is rendered.

• browse the file that you click on is browsed.

• order configures what columns are displayed and their order in the table. Type tokens from the following list separated by commas.

  • version file version.

  • group group of the process that last updated the file

  • process_id id of the process that last updated the file.

  • status status of the process that last updated the file.

  • member member name.

  • library target library

  • system target system

  • cre_user user who created the file.

  • cre_date date of creation.

  • cha_user user of the last change of the file.

  • cha_date last change date.

In case of the sample above the table has 6 columns only. When a member is clicked in the top table then it is automatically selected, when it is clicked in the bottom table then it is browsed.

You can use HWM variables and %SYSUID. (which is replaced with the current user name).

Setting at activity level for SYSH_ID system

Setting at task level for SYSH_ID system:

This option specifies how a name of JOB statement of jobs created by substitution of templates is created. It is empty by default, which generates the job name as the user id followed with one additional automatically computed character. If you do not like this format then you can set a new one. Tokens listed below are searched in the jobname format and if they are found then they are replaced with values they represent. All remaining letters are kept at their positions.

• &userid. name of the user who submits the job.

• &userid[1-8] user name complemented from right with 'X' letter up to the length specified by the number or it is a substring of userid if the number is lower then the name's length. [1-8] means a number in 1-8 range.

• &procid. process id.

• &procid[1-8]. process id complemented from left with 0 up to the length specified by the number or it is a substring of procid if the number is lower then a length of the process id. [1-8] means a number in 1-8 range.

• &suffix. one automatically generated letter.

A dot coded at the very end of jobname_format can be omitted.

The default value used when the option is empty is: '&userid.&suffix'

A few samples (assuming that the user name is P391D, PID=166 and automatically generated suffix is 'W'):

$&userid.&suffix - result: $P391DW TEST&suffix.&procid3 - result: TESTW166 &suffix.&procid6.&suffix - result: W000166W

This option sets the maximal number of rows listed in a view of files read from an archive. It is used only when paging is disabled.

There are several modules which support loading of files from the host in parallel. It can improve the performance. This feature can be activated by member_processing_method option. Available values are:

• 'serial' standard serial processing.

• 'parallel' advanced parallel downloading.

The default value is 'serial'.

This option specifies whether the view listing files from an archive uses a pager at the bottom. If the pager is enabled ('enable' parameter is true) then you can also adjust the number of rows listed per page ('page_size') and the number of page numbers displayed in the navigator ('pager_size').

This option specifies a separator used for splitting members in JUPJCLO output file of JCKIRFMT program.

By default members are separated with ./ADD MEMBER=.... line. You can edit it (the ADD token) if you have reasons to do it. To keep the default value is recommended.

You can use HWM variables and %SYSUID. (which is replaced with the current user name).

Setting at activity level for SYSH_ID system:

Setting at task level for SYSH_ID system:

Some modules support copying of files via PS dataset. This method is much faster than copying members one by one. Files are stored in one big file and split to members on the other side. Because this method of copying requires a job submission then it is faster than the standard method only when a number of files is higher than a threshold (currently set to 5). Set actions for which you want to activate this method to true. Note that PS method is used only when the number of files equals at least the defined threshold.

'ps_transfer' => array(
    '*' => array(                     // SystemId
        '*' => array(                 // Request
            'actions' => array(
                'read'   => true,
                'export' => true,
                'import' => true
            ),
            'threshold' => 5          // if 5 or more members
        )
    )
)

In the example PS method is used for reading, exporting and importing files when at least 5 members are selected.

When a process in interrupted then it usually keeps its environment in the cache. Reopening the process uses the cached environment setting. In some cases (mainly when you are testing new processes) it can be useful to reload values stored in the environment (like skeletons, libraries,...) from the config file.

To activate it, set this option to true. Then the environment is always reloaded when interrupted process is started. Please note that not all environment settings can be reloaded, for example, task names can't change.

When completed process is deleted then it is possible to delete also files it has stored in JCL, PROC or SYSIN archives. This behavior is controlled by remove_from_archive_on_delete option. Available values are:

• true - files are deleted without asking.

• false - files are kept in the archive.

• 'ASK' - a prompt opens and the user can choose what to do.

Please note that it works only for completed processes. Processes in other states always delete also files they have created.

This option sets a code page of data received by HORILST tool. You should keep the default value 'iso-8859-1'.

/*
 * code page of data received by HORILST
 */
'rot_client_code_page' => 'iso-8859-1',

This option specifies the separator used in case of fast download method of members. The default value used when the option is missing is a pipe character (|).

This option defines how JCL or SYSIN members look like in view and edit modes (when they are browsed or edited).

There are four possible values for 'view' and 'edit' options for JCL:

• 'DISABLED' no syntax highlighting but it can be enabled on the web page when syntax_highlighter_combo option allows it.

• 'WEB' the content is rendered with white background convenient for web.

• 'ISPF' the content is rendered in ISPF black style.

• false standard text area is displayed instead of the editor with highlight support.

max_line_length option sets the maximal number of letters per line.

'syntax_highlighter' => array (
    'jcl' => array (
        'view'            => 'WEB',
        'edit'            => 'WEB',
        'max_line_length' => 80
    ),
    'sysin' => array (
        'max_line_length' => 100
    )
),

This options sets the temporary folder on the server where some temporary files are written to. It is recommended to keep the default setting.

/*
 * folder for temp files
 */
'tmp_dir' => $hwi_config['hwi_root'] . "/tmp",

This option sets the code page in which the web page is displayed. It must be 'utf-8'.

Never change this default value.

/*
 * code page of web pages
 */
'web_code_page' => 'utf-8',

'template_dsn_cntl' => array (
    '*' => array (
        'DEMO_ID' => 'P391D.HOS.DEMO.CNTL',
        'SYSH_ID' => 'P391D.HOS.SYSH.CNTL'
    )
),

In this case templates are downloaded from P391D.HOS.DEMO.CNTL on DEMO_ID system and from P391D.HOS.SYSH.CNTL on SYSH_ID system. This is client independent.

This option maps domain names or IP addresses to names displayed on web pages and stored in the database. It can be best illustrated by the following example:

'system_mapping' => array(
    '192.168.47.25' => array(
        'name' => 'DEMO',
        'id'   => 'DEMO_ID'
    ),
    '192.168.47.14' => array(
        'name' => 'SYSH',
        'id'   => 'SYSH_ID'
    ),
    'SYSH1' => array(
        'name' => 'SYSH1',
        'id'   => 'SYSH1_ID'
    ),
    'SYSH2' => array(
        'name' => 'SYSH2',
        'id'   => 'SYSH2_ID'
    ),
),

There are 4 systems defined in this example. First two by IP addresses and last two by domain names.

The name parameter contains a text displayed on the web page (in select boxes for instance). The id parameter is stored to the database. You should never edit id once it has been used at least once. This is because every member stored in the database is uniquely identified by the system id, dataset name and member. If you want for some reason to edit a name of a system that has already been used in a process in the past, you can edit the name parameter, but never its id.

Sometimes it can be useful (mainly for testing) to have two different system names but the same IP address. It can be achieved by the following syntax, there is one more array level (SYSH and SYSH_COPY use the same IP address):

'system_mapping' => array(
    '192.168.47.25' => array(
        'name' => 'DEMO',
        'id'   => 'DEMO_ID'
    ),
    '192.168.47.14' => array(
        array(
            'name' => 'SYSH',
            'id'   => 'SYSH_ID'
        ),
        array(
            'name' => 'SYSH_COPY',
            'id'   => 'SYSH_COPY_ID'
        )
    )
),

In this file you must set connection parameters to Procman/HOS database. A typical example follows:

<?php
if (!isset($hos_config))
    $hos_config = array();

$hos_config = array_merge($hos_config, array(
    'db' => array (
        'prefix'  => 'MHOS.',
        'actions' => array (
            '*' => array (
                'keep_alive' => 10,
                'host'       => '',
                'port'       => '',
                'schema'     => '',
                'type'       => 'db2',
                'alias'      => 'DALLASX',
                'user'       => 'P391D',
                'pwd'        => '==5vY227ADdswsVYOALRNWJAwJzgDbqDic

In case of DB2 fill items of the array this way:

• keep_alive use 10.

• type use 'db2'.

• alias database alias.

• user database user name.

• pwd an encrypted password.

• platform use 'zos'.

1. [GLOBAL] section

• MSGLEVEL enter a value in [1-5] range. The higher the value is the more detailed output is written to the log file. The default value is 1.

• HORCCLNT_PATH absolute path to a directory where horcclnt.exe tool is stored.

• TEMP_PATH path to a the directory where temporary data are created.

• WORK_DIR keep it empty.

• LOG_PATH path to the directory where log files are created.

• CODEPAGE code page used on the host. Use value 17 or "Austria, Germany (IBM-1141)".

1. [TCP] section

• TCPDEBUG set it to NO unless you need to enable TCP/IP log output to tcptool.log file. In this case set it to YES and ensure that tcplogger.xml file exists in HORCCLNT_PATH. This XML file can be created by running: horccltn.exe -x-

• IP_ADDR default IP address where to connect when it is not set as a program parameter (Procman/HOS PHP scripts use program parameter when they call horcclnt.exe, so the value entered for IP_ADDR is not used in this case).

• HOST_PORT port where the service is listening on the host.

• MEMBER STC member name on z/OS.

• USERISSTEPNAME set it to YES if the current user name is used as a step name in the task started on the host. Use NO otherwise. The default value is YES.

• TCPCRYPT this option controls how data are encrypted. Possible values are:-

  • 0 weak password encryption. Passwords on the host can have only up to 8 characters. No TLS.

  • 1 default, strong password encryption. Passwords on the host can have up to 8 or 14 - 100 characters. No TLS

  • 2 reserved, not used.

  • 3 strong password and data encryption with TLS. Passwords (1-8) and passphrases (14-100) are supported. It requires HORILST module on the host.

• TCPCOMMONNAME specifies the Common Name of the server certificate. It is required only when TCPCRYPT=3. The default value is * and should be changed as soon as you set your own certificate.

• TCPPEMCA specifies a file containing trusted certificates that are used during server authentication. The certificates can be concatenated and need to be in PEM format. If the value is empty the Windows Certificate Store (Trusted Root Certification Authorities) is used instead. Please make sure the root certificate of the server certificate can be found either in the file specified or in the Windows Certificate Store. It is required only when TCPCRYPT=3. As the default value you should use hor-ca-store.pem.

• PASSCHK specifies whether a password is checked with RACF (when set to YES) or only the user name is checked with RACF (when set to NO). Use YES as the default value.

1. [FTP] section

• T0 communication timeout in seconds. If it expires then HORCCLNT is closed automatically. The default value is 30.

• T1 timeout when connection is being established. If it expires then HORCCLNT is closed automatically. The default value is 60.

• LISTLIMIT count of dataset or member names downloaded when they are listed. Use zero if you do not want to set any limit. This option prevents long delays when too many names match the search criteria. When it is in effect (i.e. when there are more matching items on the host) then you are informed about it on the web page and you can set a new limit by pressing a button. Please note then you can see even less data on the web page due to additional filtering (there can be another filter for only PO or PS datasets in the process configuration). The default value is 0.

1. [SQLITE] section

• T0 timeout applied if SQLITE table is locked (in seconds). The default value is 30

• DBNAME name of SQLITE database file. The default value is rotbintf.db.

This file is reserved for configuration of SYSIN processes only. Currently it doesn't add any options to $hos_config array but is defines one constant:

• ALLOW_EMPTY_SYSIN set it to true if you want to allow processing of SYSIN members without any content. If you set false then empty SYSIN members are not accepted by Procman/HOS.

This option allows you to set user name and password of technical users. You can set it for any system and process. Asterisk can be used instead of system or process name. In this case it is valid for all systems or processes. The password must be encoded. The actions array supports three options: read, write, check. Set them to true if you want to use the technical user for the appropriate action. For example if you set write=true, check=true and read=false then the technical user is used only for writing to z/OS and running JCL analysis, but not for reading (from personal libraries). The current logon user is used for all systems, processes and actions for which the technical user is not defined.

This option specifies parameters for XINFO analysis. It is used in case of DELETE processes where Procman/HOS checks for example whether deleted procedures or SYSIN files are used by other existing jobs. As real XINFO table and column names can differ from the default ones then this setting ensures that correct tables and columns are always known. This option also allows you to set an user that is used for reading data from XINFO database and also allows you to set values for XXRDATCLIENT, XXRDATENV and XXRDATINFO columns, which are important if your XINFO installation has multi client support activated.

• You can use an asterisk in the place of 'target_system' or 'client'. Then the setting becomes valid for all systems or clients.

• The 'name' parameter maps table names (without a prefix) to real database table names used in SQL queries. In the example any SQL query that reads data from XXRTDDF table uses XINFO43.XXRTDDF table name in the generated SQL queries.

• Column names are in vast majority (if not in all cases) unchanged in real XINFO installations. If this is your case then the key and value (which have a meaning of Procman/HOS names and DB table columns) are equal.

• In case of multi-client XINFO installation you can edit parameters in 'system' array. In the example 'XXRDATCLIENT='CLIENT1' AND XXRDATENV='ENV1' AND XXRDATINFO='INFO1'' is added to every SQL query listing data from XINFO database. The 'system' array is optional. Do not specify it if you don't need it.

• Parameters in 'conn' array configure connection parameters used for querying data from XINFO database. Do not specify this block if the user used for all other Procman/HOS database queries should also be used for the XINFO database.

This file is reserved for configuration of JCL processes only. Currently it doesn't add any options to $hos_config array but is defines 3 constants:

• HOS_JCL_BLOCK_SIZE when you process a lot of files in JCL analysis then the files are analyzed in blocks. This constant defines how many files are analyzed in one single block.

• USR_FORM_MAX_FREETEXT_SIZE specifies the maximal length of a text field used in user forms in case of 'freetext' item type.

• FORCE_SLOW_DOWNLOAD_METHOD when this option exists and equals true then the slow method of downloading members in JCL analyzer is used. By default this constant does not exist in the config file or it is set to false.

<?php

define("HOS_JCL_BLOCK_SIZE", 30);
define("USR_FORM_MAX_FIELD_SIZE", 1900);
define("USR_FORM_MAX_FREETEXT_SIZE", 3900);

$hos_page_ids = array_merge($hos_page_ids,
    array(
    )
);

// user-defined options
//
$hos_config = array_merge($hos_config,
    array(
        // reserved for future user-defined options
    )
);

?>

You can edit the block size but please do not edit USR_FORM_MAX_FIELD_SIZE and USR_FORM_MAX_FREETEXT_SIZE values.

This type of item does not render any visible field.

Required attributes:

• id unique identification of the item (unique in the whole form).

• type item type: 'hidden'.

Optional attributes:

• default default value of the item. It is used by default unless it is explicitly set by PRX rules.

Procman supports four languages, English,German, France and Spanish. Texts that correspond to the selected language are loaded from XML dictionary. Dictionaries are stored in etc/dictionaries directory. A small extract of hos.xml dictionary file:

The configuration of processes is divided into two files:

hos_process_config.php

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).

Environment definition

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.

Example of hos_process_config.php

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:

return array (
     'JCL_NEW_PRE_PROD' => array (
            'activity' => array (
                'JCL_NEW_PRE_PROD_REQUEST' => array (
                    array (
                        'name'   => 't0100',
                        'type'   => 'task',                       
                        'module' => 'm_jcl_start',
                        'pass'   => array (
                            'i_jcl_config' => 'is_proc=false, is_sysin=false'
                        )
                    ),                  
                    array (
                        'name'   => 't0200',
                        'type'   => 'task',
                        'module' => 'm_set_hwm_parm',
                        'input'  => array (
                            'i_set_hwm_parm' => 'OBJECT_COUNT = ""'                           
                        ),
                        'pass'   => array (
                            'i_jcl_config' => ''
                        )                       
                    ),                  
                    array (
                        'name'   => 't0300',
                        'type'   => 'task',
                        'module' => 'm_environment',
                        'input'  => array (
                            'i_goto'        => 'error=""'
                        ),
                        'output' => array (
                            'i_environment'  => '',
                            'i_goto'         => ''
                        ),
                        'pass' => array (
                            'i_jcl_config'  => ''
                        )
                    ),                  
                    array (
                        'name'   => 't0400',
                        'type'   => 'task',
                        'i'module' => 'm_jcl_select_file_sys',
                        'input'  => array (
                            'i_goto'                => '',
                            'i_jcl_config'          => '',
                            'i_environment'         => '',
                            _jcl_select_file_sys'   => 'interrupt=true, cancel=false, savepoint=true'),
                        'output' => array (
                            'i_jcl_config'    => '',
                            'i_environment'   => '',
                            'i_file_list_sys' => '')
                    ),
                             . . .

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.

 'activity' => array (
            'JCL_NEW_PRE_PROD_REQUEST' => array (
                'environment' => array (
                    '!Test environment 1' => array (
                        'task' => array (
                            '*' => array (
                                'source_system'  => 'SYSH_ID',
                                'target_system'  => 'SYSH_ID',
                                'check_system'   => 'SYSH_ID'
                            ),
                            't0400' => array (
                                'source_library' => array ('%SYSUID..*'),
                                'target_library' => array ('P391D.PETRH.TEMP1', 'P391D.PETRH.TEMP2'),
                                'member'         => array ('*')
                            )
                        )
                    )
                )
            ),
            'JCL_NEW_PRE_PROD_APPROVE' => array (
             ... setting of another activity follows here...

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.

Each item must contain type attribute that defines a visual appearance of the form field. Available item types are:

• wai_input displays an edit field:

• wai_select displays a select box.

• hidden does not display anything.

• text does not require any user input. Its purpose is only to display CSS-styled information read from XML definition. Values of this type of item can't be set in PRX rules and are not delivered to the JCL generator.

Each of the item type requires or allows other attributes. This is described in details in the following sections.

Required attributes:

• id unique value that identifies the group.

• title text displayed in the group's header.

Optional attributes:

• expand flag that determines whether the group can be expanded (type Y or N). The option equals 'N' by default.

• cond condition that controls when the group is visible. There must be item id on the left side of = sign and a value on the right. When it is missing then the group is always visible. Use this option if you want to render a group conditionally based on a value of a select box item.

Required attributes when expand='Y'

• allow_empty Expandable groups can be extended by clicking on 'add' or 'duplicate' links in their header and added copies of groups can be removed by clicking on 'remove' link. If you set allow_empty='N' then at least one group must always exist. Setting this option to 'Y' allows you to remove all copies of the group.

Required attributes:

• version the version of the form.

Optional attributes:

• translate when this attribute equals Y (i.e. translate="Y") then titles and help text are translated by using the dictionary.

Required attributes:

• id unique identification of the item (unique in the whole form).

• type item type: 'wai_select'.

• label label displayed next to the item.

Optional attributes:

• help any text that should help to understand what value is required. It is displayed on the right of the item.

• must set 'Y' when the value is required, 'N' otherwise.

• default the default value of the item. It is used by default unless it is explicitly set by PRX rules.

• disabledset 'N' if the field can't be edited. Set 'Y' if a modification is allowed.

Required attributes:

• id unique identification of the item (unique in the whole form).

• type item type: 'wai_input'.

• label label displayed next to the item.

• size number of letters a user can enter.

Optional attributes:

• help any text that should help to understand what value is required. It is displayed on the right of the item.

• must set 'Y' when the value is required, 'N' otherwise.

• expr predefined expression or regular expression. Predefined expressions are here for ease of use and have special meaning. Regular expressions support standard regex patterns.

Available predefined expressions are:

• expr="MEMBER=[]" requires a valid member name.

• expr="DSN=[]" requires a valid DSN without a member.

• expr="DSNMEMBER=[]" requires a valid DSN optionally also with a member in parentheses.

• expr="CUSTOM=[]" makes no validity checks when coded like this.

As you can see there are square brackets after the keyword. A test of validity of user data has two phases:

1. it checks member and/or dsn if MEMBER, DSN or DSNMEMBER is specified .

2. it also performs checks specified in square brackets. In case of member and dsn no further check is usually needed, but it is still possible. The additional check is useful primarily for CUSTOM keyword. See this example:

expr="CUSTOM=[expr='/^[a-z]+$/',maxlength=44,maxlinelength=10]"

Here are 3 additional checks (currently the only ones supported):

expr: regular expression (in this sample it allows only small letters.

maxlength: maximal number of letters entered.

Besides predefined expressions you can use standard regular expression coded in the "old style" without CUSTOM keyword: expr='/^[a-z]+$/'

The newer style for the same check is: expr="CUSTOM=[expr='/^[a-z]+$/']"

• range range of allowed integer values in format from-to. For example: range="1-99"

• default the default value of the item. It is used by default unless it is explicitly set by PRX rules.

• disabled set 'N' if the field can't be edited. Set 'Y' if a modification is allowed.

User forms appear on a web page when you press any of Modify Job, Modify DD,... buttons:

PRX rules that analyze JCL assign form names to JCL statements. The content of forms is loaded from XML files stored in etc\forms directory. Every user form must start with frm_ prefix. This is an important rule because there are also other forms used by Procman/HOS in this folder, but only forms starting with frm_ prefix can be used as user forms. It is also very important to ensure that the XML syntax of all user forms is correct. The forms are sent to the host when JCL is analyzed. In case of wrong XML syntax in any of user forms the analyzer fails.

The aim of user forms is to ask users for additional data that is needed for proper JCL generation. The forms are fully customizable. This is a typical (and quite simple) form definition:

And this is how the form looks in the web browser:

The XML file must have just one section like at 2nd source line of the sample. Then several sections follow. Each group in XML results in a group in the form. There are 3 groups in this case. There are several sections inside of every . Each item results in exactly one data line in the group that contains it. Each item must have id that is unique in the whole form. A name of this id should be chosen carefully because once it is set and used in processes it should not be edited. Values entered in the form are associated with this id in the database and are reused when JCL/PROC change process (that loads old user data for initialization of the items) is started.

It is possible to initialize options of select boxes from the database. This is often used when the values change dynamically. For example a job that writes all available options can be scheduled for every night. When a new process starts then the options are always fresh. Once the process is started and options are read then the they remain in the cache. When the process is later interrupted and opened again it still contains its original options.

The FORMCONT database table is defined this way:

CREATE TABLE MHOS.FORMCONT (
FORMNAME VARCHAR(64) NOT NULL,
STMT VARCHAR(16) NOT NULL,
NAME VARCHAR(64) NOT NULL,
LBL VARCHAR(512) NOT NULL,
VAL VARCHAR(1024),
USR VARCHAR(32)
) IN ....

• FORMNAME name of the form in uppercase without .xml extension.

• STMT statement type (JOB, EXEC,...).

• NAME id specified inXML section.

• LBL label of the item visible on the web page.

• VAL value of the item used when its label is selected on the web page. NULL is allowed and has a meaning of an empty string.

• USR NULL or user id. If the value is NULL then the option is available for all users. If you want to offer it only for a particular Procman user then use his user id.

When options for a form field exist in the database then they always completely overwrite options coded in XML form definition.

It is highly recommended to have options only in one place - in XML or in FORMCONT to prevent problems.

It is also possible to add additional options by calling ADDFORMOPTION rule function. This function appends options to the ones that already exist.

Required attributes:

• id unique identification of the item (unique in the whole form).

• typei tem type: 'multiline'.

Optional attributes:

• style CSS style. In case of the blue example it is: style="color: blue;"

• default value that is displayed.

Required attributes:

• id unique identification of the item (unique in the whole form).

• type item type: 'multiline'.

• label label displayed next to the item.

• size number of letters a user can enter.

• cols number of columns of the text area.

• rows number of rows of the text ar ea.

Optional attributes:

• help any text that should help to understand what value is required. It is displayed on the right of the item.

• must set 'Y' when the value is required, 'N' otherwise.

• default default value of the item. It is used by default unless it is explicitly set by PRX rules.

• disabled set 'N' if the field can't be edited. Set 'Y' if a modification is allowed.