This manual describes the configuration of ProcMan handover processes for IWS z/OS. This book is aimed at ProcMan administrators with knowledge of IWS z/OS.

Most of IWS handover settings are stored in PHP files. To be able to change these settings therefor requires at least basic knowledge of PHP syntax. These PHP configuration files will be prepared to your needs by the HORIZONT support and consulting team.

Process configuration consists of these parts:

• Process definition configuration – definition of process made directly in ProcMan administration

• PHP Process definition – configuration of process workflow, IWS program modules, their configuration and links

• Data environment of the process – configuration setting of data that are handled by process (for example subsystems, technical users, libraries on host)

Further detailed information about handover architecture can be found in document HOS configuration guide.

Process definition configuration

General handover process definition and its workflow are made directly in ProcMan administration web dialog. Most of IWS activities must be configured with the command "hos_ctrl.php?root=twaz".

For further details on how to setup process definition see Process definitions

Module m_tws_ad_appl_load

The most important module is the module m_tws_ad_appl_load which provides main ProcMan IWS windows with links to all important IWS functions. It provides the main page for IWS handover activities.

The module hos_tws_ad_appl_load consists of 3 PHP pages:

• hos_tws_ad_appl_load_i.php – module input

• hos_tws_ad_appl_load.php – module main PHP code

• hos_tws_ad_appl_load_o.php – module output

Module m_tws_auto_ad_update

The module m_tws_auto_module is used for the update of IWS applications to the host in automatic activities. This module runs in the background and has no visible module dialog for user.

If the module runs without problems, the module continues to the next task. All results are stored in the report for AD applications. The data about IWS update are written to Host Logs (Clientlog, Hostlog, Eqqmlog) and AD update log.

If the module ends in error, all error messages are written to Report -> Information.

This configuration applies to global configuration of whole IWS part of ProcMan.

Configuration is stored in file hos_tws_config.php in etc directory of your ProcMan installation. All configuration options in Hos_tws_config.php have comments about their meaning and possible values.

Please note that these PHP configuration files will be prepared to your needs by the HORIZONT support and consulting team. Please ask for assistance.

Common settings

$twaz_logging – enable or disable logging of specific parts of IWS applications, for ProcMan are used only settings for core, ad, tws_rules, ad2db

$twaz_logging_msg – specify application logging at specific level (message, warning, error, trace, audit)

$twaz_admin_tws_systems_def_vals – default values for new IWS system

$twaz_ad_app_def_vals - application predefined values, when new empty application is created, these setting are applied.

$twaz_ad_op_def_vals - operation predefined values, when new empty operation is inserted to application, these setting are applied

Settings for IWS ADHOC processes

$tws_ws_mapping – is setting that maps workstation to IP addresses of Z/OS machines. The ZO/S machines are used for executing basic JCL scripts. If no Z/OS machine is defined, then IP address of selected subsystem will be used

$hos_jcl_to_tws_new – template for operations of new application, that is created in subprocess to previous JCL handover

$tws_system_mapping - The list of all schedulers (IWS) and their IP where the template for reading of JCL is executed, used only in IWS ADHOC on demand process. If no Z/OS machine is defined, then IP address of selected subsystem will be used

System_mapping in HOS configuration hos_config2 – setting connect to „Host Ip Address” in “IWS System” in dialog “IWS systems administration and settings”. For example synchronization for IWS system TABS use „Host Ip Address” IWSZ_IP then in hos_config2 must be setting for 'IWSZ_IP' see below

'system_mapping' => array (
            'IWSZ_IP' => array (
                        'name' => 'PROD',
                        'id'   => 'PROD_ID'
            ),
)	

Settings for IWS Additional data

$addata_conf – default configuration, names of config files that are used as default

$addata_editor - additional data editor in Codemirror, applied to additional data in JCL format

Settings for IWS Object Browser

$twaz_objectbrow – settings for object browser set to action

Data environment is used to specify options that don’t affect the process tree. For IWS the most important part of environment are IWS systems that are used by modules.

Data environment is stored in directly in file etc/hos_config2.php or in PHP files which are included to this file.

Data environment are PHP arrays, where array keys are names of processes, activities and tasks to which data environment is connected.

Common environment settings for all IWS processes

Setting tws_source_system - defines source iws system of iws task

Setting tws_target_system - defines target iws system of iws task

Example snapshot of task made from module m_tws_ad_appl_load that has set source iws system to DEV-TWS, target tws system is set to TEST-TWS.

Environment Settings for ADHOC processes

ADHOC processes (to insert applications in the IWS Current Plan) require settings for editing and checking of JCL scripts

Setting template – templates for JCL scripts are used in adhoc processes, in this setting key 'adhoc_on_demand_%name of subsys%' is the name of JCL template for JCL jobs in ADHOC application,

Example: define JCL template for subsystem TWEC to file HOJOD860

'adhoc_on_demand_twec'      => 'HOJOD860' 

Setting template_dsn_cntl - DSN containing job templates on various Z/OS systems (e.g. hlq.procman.SKELS)

Setting temp_dsn_alloc_site - options used for allocation of temporary datasets

The structure of IWS additional data is defined in XML files. The XML files have 2 different formats – wai format and JCL format. The format is configured by process config setting addata_format.

Wai format is default XML format. This XML format is used for configuration of form and items that are stored in it. XML files are configuring input dialogue for fields that can be stored in additional data. The XML files are placed to directory etc/addata of ProcMan installation directory.

Example of XML file in wai format:

<?xml version="1.0" encoding="UTF-8"?>
<form action="" name="twaz_ad_addata" method="post" id="twaz_ad_addata" remember="false">
	<!--example note 1, that shows textbox 80 characters long-->
	<fi key="note1" type="text" name="note1" maxlength="80" translate="false" heading="Note 1" help="Help for note 1" remember="true"></fi>
	<!--example note 2, that shows text area -->
	<fi key="note2" type="textarea" name="note2" rows="10" cols="70" maxlength="100" translate="false" heading="Note 2 heading" help="Help for note 2" remember="true"></fi>
	<!--example checkbox 3, that shows check box -->
	<fi key="checkbox3" type="checkbox" name="checkbox3" translate="false" heading="Add operation" help="Add operation help" remember="true"></fi>
	<!--example select 3, that shows simple select true/false -->
	<fi key="select4" type="select" name="select4" heading="Test select" translate="false" remember="true" help="select true or false">
		<val heading="true">1</val>
		<val heading="false">0</val>
	</fi>
</form>

JCL format is XML format that is used also for entering JCL user data. Detailed description of this format you can find in chapter 6 of document “ProcMan - Customization JCL Module”. The files are stored in directory etc/forms.

Additional data are using two tables with identical table structure – twaz_addata, twaz_addata_hist.

Table Twaz_addata stores additional data for actual, modified, inserted tws app records.

Twaz_addata_hist stores additional data for history, interim tws app records.

Structure of both tables

Additional data are configurable customer’s data used in IWS handover that are connected to iws applications or operations. These data are stored only in ProcMan database but not in data structures of IBM Workload scheduler on z/OS.

IWS additional data that are not integral part of IWS data and they are not accessible on z/OS.

Structure of IWS additional data is configurable to suit needs of certain handover process.

Configuration of data structure is done using XML files see chapter 6.2.

The default IWS additional data configuration is stored in etc/hos_tws_config.php file. It contains setting addata_conf, addata_editor.

The addata_conf setting is array list. The list can contain two keys.

• Key adcom defines XML configuration file used for edit and display additional data connected to common segment (adcom).

• Key adop defines XML configuration used for edit and display additional data connected to operation segment (adop).

The addata_editor setting is array list. This setting is applied only to JCL format and is configuring Codemirror editor, which is used for Additional data value editing. Array key is filter to additional data key. Array value is Codemirror editor keyword.

Example for editing with XML mode all additional data containing TWSRULEAPP

$addata_editor['TWSRULEAPP:'] = "XML";

To customize the certain handover process default configuration can be overwritten by PHP process definition file.

The interfaces of modules that can display or edit additional data have configuration settings addata_conf, addata_format, addata_edit.

The addata_conf setting is array list. The list can contain two keys.

• Key adcom defines XML configuration file used for edit and display additional data connected to common segment (adcom).

• Key adop defines XML configuration used for edit and display additional data connected to operation segment (adop).

The addata_format setting is array list. The list can contain two keys.

• Key adcom defines XML file format used for edit and display additional data connected to common segment (adcom). Possible values are wai or jcl.

• Key adop defines XML file format used for edit and display additional data connected to operation segment (adop). Possible values are wai or jcl.

The interfaces of modules that can display or edit additional data have configuration option addata_edit. This setting will enable (addata_edit=true) or disable (addata_edit=false) editing of additional data. The default setting for addata_edit is false, so without setting addata_edit option additional data will be read only.

Example: This configuration list use XML file addata_example.xml to configure additional data in common segment, XML file twsmod_adop.xml to configure additional data in operations segment

addata_conf = [adcom = "addata_example",adop = "twsmod_adop"] , addata_format=[adcom = "jcl",adop = "wai"], addata_edit=true

-h show help menu

-o option for manipulation - import, export

-s IWS data segment – adcom (applications) or adop (operations), default value adcom

-f Filename for command ouput or input

-c csv file format, txt or excel, default txt, txt is csv format for common text editors, excel means csv format readable by MS Excel, the main format differences are in multiline text fields

-e text encoding of csv file, UTF-8 or CP1252 (Windows-1252), default UTF-8

-m file export mode, w - overwrite existing file, a - append existing file

-i export filter, option for exporting only part of IWS applications, consisting from pairs of name=value separated by semicolons, example adid=AD*;subsys=TWGC – filter for all applications starting with AD from system TWGC,

The export filter can use following fields:

adid - Application ID

subsys - IWS system

Owner - Application owner

type - Type

stat - Status

authgrp - Group Definition

grpdef - IWS Authority group id

addname - Additional data field name

dbstat - State (ACTUAL, INSERTED, MODIFIED)

IWS additional data can imported or exported to text based csv files. Import and export is done using the batch file tws_addata.cmd, which is located in the bin directory in ProcMan installation.

The command is using for export and import of data csv format (comma separated text). csv file consists from 3 common fields and 1 optional field:

• application key – application key for tws application

• operation number – optional field operation number for operation data for operations

• field name – field name of additional data

• field value – field value of additional data

The csv file is by default in character encoding UTF-8, but it is possible to use also character encoding Windows-1252.

Example of csv file with IWS additional data

application key, field name, field value

application key, field name, field value
"ACTUAL.TWEC.BGT3000A.P.A.20711231","note1","test1"
"ACTUAL.TWEC.BGT3000A.P.A.20711231","note2","test 2 \n test22"
"ACTUAL.TWEC.BGT3000A.P.A.20711231","select4","1"
"ACTUAL.TWEC.BGT3001A.P.A.20711231","checkbox3",""
"ACTUAL.TWEC.BGT3001A.P.A.20711231","note1","test 1"
"ACTUAL.TWEC.BGT3001A.P.A.20711231","note2","test 2"
"ACTUAL.TWEC.BGT3001A.P.A.20711231","select4","1"

IWS rules XML configuration files are stored in

etc/tws_rules

directory in your ProcMan installation. The structure of XML files is controlled by document type definition declaration in file tws_rules.dtd. The name of the rule that should be applied in the process step is configured in the ProcMan process config file.

IWS rules basically consist from two parts with rule basic elements:

• INIT element – create or initialize rule parameters that are used later by processing elements

• Processing elements (TEST, CHANGE, DELETE, INSERT, CHECK) – any combination of elements that directly check or alter AD record.

All rule basic elements are identified using attribute ID, which must be unique within the iws rules XML file.

tws_addata -o export -s adcom -f export.csv -- export additional data in common segment to file export.csv

tws_addata -o export -s adop -f export_oper.csv -- export additional data in operation segment to file export_oper.csv

tws_addata -o import -s adcom -f export.csv -- import additional data from file export.csv to additional data in common segment

tws_addata -o import -s adop -f export_oper.csv -- import additional data from file export.csv to additional data in operation segment

tws_addata –o export –s adcom –i adid=BG*;owner=P368V – export all applications with id starts with BG, owner of application is P368V

IWS rules is an XML markup language extension for manipulating applications description (AD) in the IBM Workload scheduler for z/OS (IWSz).

IWS rules make it easy to automatically check, modify, delete, or create certain parts of AD.

IWS rules can be used in ProcMan processes to provide control of AD according to your internal organization rules such as convention of application names, operation workstation mapping, or run cycle conventions. IWS rules can be executed in any step during ProcMan activities.

This manual describes IWS rules and how to use them for checking, modifying, or creating application descriptions (AD) in the Tivoli Workload scheduler (TWS) and how IWS rules are configured using XML markup language.

This configuration applies to global configuration of whole IWS part of ProcMan.

Configuration is stored in file hos_tws_config.php in etc directory of your ProcMan installation. All configuration options in Hos_tws_config.php have comments about their meaning and possible values.

Please note that these PHP configuration files will be prepared to your needs by the HORIZONT support and consulting team. Please ask for assistance.

Common settings

$twaz_logging – enable or disable logging of specific parts of IWS applications, for ProcMan are used only settings for core, ad, tws_rules, ad2db

$twaz_logging_msg – specify application logging at specific level (message, warning, error, trace, audit)

$twaz_admin_tws_systems_def_vals – default values for new IWS system

$twaz_ad_app_def_vals - application predefined values, when new empty application is created, these setting are applied.

$twaz_ad_op_def_vals - operation predefined values, when new empty operation is inserted to application, these setting are applied

Settings for IWS ADHOC processes

$tws_ws_mapping – is setting that maps workstation to IP addresses of Z/OS machines. The zO/S machines are used for executing basic JCL scripts. If no z/OS machine is defined, then IP address of selected subsystem will be used

$hos_jcl_to_tws_new – template for operations of new application, that is created in subprocess to previous JCL handover

$tws_system_mapping - The list of all schedulers (IWS) and their IP where the template for reading of JCL is executed, used only in IWS ADHOC on demand process. If no z/OS machine is defined, then IP address of selected subsystem will be used

System_mapping in HOS configuration hos_config2 – setting connect to „Host Ip Address” in “IWS System” in dialog “IWS systems administration and settings”. For example synchronization for IWS system TABS use „Host Ip Address” IWSZ_IP then in hos_config2 must be setting for 'IWSZ_IP' see below

'system_mapping' => array (
        'IWSZ_IP' => array (
            'name' => 'PROD',
            'id'   => 'PROD_ID'
        ),
	)	

Settings for IWS Additional data

$addata_conf – default configuration, names of config files that are used as default

$addata_editor - additional data editor in Codemirror, applied to additional data in JCL format

Settings for IWS Object Browser

$twaz_objectbrow – settings for object browser set to action

For basic functionality, IWS rules need no database objects. Database tables are used only when IWS rule do value lookup in processing element CHANGE. In this case tws rule use data from database table rules_lookup.

Structure of table rules_lookup

The lookup table data are managed using command line utility tws_rules_lut.cmd that is located in bin directory of your PMN installation. This utility is able to import, delete and show lookup data values

Lookup table values are used to replace values by matching against a list of values. Other possible use of lookup table outside the tws rules in customizing lists in pickers for various fields in edit dialog for tws application.

In PHP process definition file is definition of IWS rule filename, that is used during process.

The interfaces of modules that can use IWS rules have configuration settings i_tws_ad_appl_ins, i_tws_ad_appl_copy, i_tws_ad_appl_mod, i_tws_ad_copy_all_appl, i_tws_adhoc_appl, i_tws_ad_appl_tws_upd.

Inside the TEST element it is possible to use element PARALLEL_CHECK. This element checks whole PMN database, whether the current processed IWS application is used in another PMN process, which is not currently completed. If the IWS application is really used, then the element text is printed as rule message and the rest of TEST element is skipped. The message level is configured using the attribute level as in the element MESSAGE. With the attribute ONLY_MODS can be used, when you want to check only modification (MODIFIED version) in the other processes.

Example: If the application is used parallel then error message is displayed, when it is not used then only notice is displayed

<TEST ID="PARA1">
	<PARALLEL_USE ONLY_MODS="false" level="error">Parallel use of
		application in processes %1</PARALLEL_USE>
	<MESSAGE level="notice"> Parallel use of application not detected
	</MESSAGE>
</TEST>

The check element is similar to TEST, but its functionality is different.

This element is used in segments that have several distinct items, for example segment ADOP have several operations. The check iterates through the segment and process all items inside of it, for example go through all runcycles and process each runcycle independently.

Example: Test all operation with CPU workstation and print warning message when it has empty jobname

Instructions in INIT element are used for rule parameters creation or initialization from application environment. Each parameter is initialized with LOAD element.

Attribute SRC of LOAD element has the following values:

• RULE – rule parameter is created from values that origins from rule itself

• HWM – rule parameter is created from ProcMan HWM application environment

• IWSAPP – rule parameter is loaded from IWS application

• IWSOPER - rule parameter is loaded from operation in IWS application, the operation is specified by additional SCOPE attribute (FIRST, LAST)

• DATE – rule parameter is loaded from date relative notation

• LOOKUP – rule parameter is created from lookup

• CLONE – rule parameter is assigned during processing clone module

• Rule parameters can be created with simple assigned text value.

Example: Rule is processing AD application with application ID FP391X, load will assign simple text value FP391X to parameter PARAM1

<LOAD SRC="RULE"> PARAM1 = FP391X</LOAD> 

Rule parameter can be created using value from HWM application environment. This option can be used for automatically load values from ProcMan process data. It is possible to load values from both general and additional process data.

Example: parameter JOBKURZ is created using JOBK value, which was configured by process administrator during process creation in additional process data.

<LOAD SRC="HWM"> JOBKURZ=JOBK </LOAD>

Rule parameter can be created using value from IWS application common segment.

Example: load part of Application ID from 4th character to 11th character to parameter PARAM4

<LOAD SRC="IWSAPP"> PARAM4 = adid(4,11)</LOAD>

Rule parameter can be created using value from IWS application operation.

Example: load operation number from the first operation in the IWS application

<LOAD SRC="IWSOPER" SCOPE="FIRST">V_OPFIRST=adopno</LOAD>

Rule parameter can be created using values from date relative notation. The resulting parameter is string in YYYYMMDD date format. Possible relative notation are TODAY,TOMORROW,YESTERDAY,NEXT,LAST,PREVIOUS WORKDAY,FIRST,LAST DAY OF THIS,CURRENT,LAST,PREVIOUS,NEXT YEAR,MONTH,WEEK.

Example: When this rule is run on 27.10.2017, the PARAM1 is set to 20171030

<LOAD SRC="DATE">PARAM1 = NEXT WORKDAY</LOAD>

The date parameters can also altered from other date params by relative time notations as are + 1 DAY

Example: When this rule is run on 26.10.2017, the PARAM2 is set to 20171029

<LOAD SRC="DATE">PARAM1 = NEXT WORKDAY</LOAD>
<LOAD SRC="DATE">PARAM2=PARAM1 + 2 DAYS</LOAD>

Rule parameter can be created using values from rule lookup. The resulting parameter is array.

Example: load part of Application ID and use it for loading the lookup to parameter INIT1

<LOAD SRC="LOOKUP">
	INIT1
	<TABLE ID_LOOKUP="ADDINIT" SRCH="column1" REPLACE="column2" />
</LOAD>                                                           

Rule parameter can parameter can be created by cloning module.

Example: load part of cloning parameter, that is created by cloning module from additional data value *PAR_INST

<LOAD SRC="CLONE">INT = INST(3,1)</LOAD>

Rule parameter can be created using combination of other rule parameters. The expression is using + operator to concatenate text values.

Example: parameter PARAM3 is created using values of PARAM1, PARAM3 and text „job”.

<LOAD SRC="RULE"> PARAM3 = PARAM1 + PARAM2 + job </LOAD>

Processing element test is used to check value of AD fields against rule parameter or text value. According to check result iws rule can perform further action – alter applications print messages. The test is made using condition in COND element.

The TEST element is searching for all data within the AD application and applying conditions to all of them. If you for example test the values of workstation for AD operation, then the test will run over all operations a test their values. If at least one of the operation workstations will fulfill the condition, then the test will return true.

The more complicate testing the TEST element can use regular expression. The syntax of regular expression must comply PCRE Perl compatible regular expression, which is used as standard in PHP.

Example: Test whether application owner is P390K. If it is P390K, insert new operation and runcycle

Example: Test whether application ID is starting with string P3

Example: Testing using regular expression. Test is true if is 5th character in application id (adid) is a digit

Change element will in rule initialize process of changing existing segment of AD.

The app segment that will be changed is configured using attribute segment. Attribute segment has 7 possible values: ADCOM (common segment), ADOP (operations), ADRUN (runcycles), ADDEP (external dependencies), ADSR (Special resources), ADDATA (additional data).

Change process consists from number of action that will change certain application field value.

Example: this action change application description to simple text, simple text was written directly to action element

<CHANGE SEGMENT="ADCOM" ID="ch01">
<ACTION PARM="addesc" NEWVALUE="test tws rules" />
</CHANGE> 

Example: this action change application owner in common segment (adcom) to existing param PARAM1, that was defined in INIT element

<CHANGE SEGMENT="ADCOM" ID="ch02">
<ACTION PARM="adowner" SETVALUE="PARAM1" />  
</CHANGE> 

Example: this action will change jobname using lookup values from lookup with ID lookup2, in original data the rule will search for values from column column2 and will substitute them with values from column1

<CHANGE SEGMENT="ADOP" SCOPE="ALL" ID="ch03">
<ACTION PARM="adopjn(3,1)" LOOKUP="true">  
<TABLE  ID_LOOKUP="lookup2" SRCH="column2" REPLACE="column1" />
</ACTION>
</CHANGE> 

The scope of change is configured using attribute scope. Scope can have following values:

• ALL - apply to all data, default value

• FIRST - apply to first record only

• LAST - apply to last record only

Any integer value -number in the sequence, for example <CHANGE SEGMENT="ADOP" SCOPE="3"> means third operation from beginning of operation segment

Example: Change action that has scope all, it will change workstations in all operations in given application

<CHANGE SEGMENT="ADOP" SCOPE="ALL" ID="ch02">
	<ACTION PARM="adopwsid" SETVALUE="PARAM2" />  
</CHANGE>

Example: change workstation only in first operation

<CHANGE SEGMENT="ADOP" SCOPE="FIRST" ID="ch03">
	<ACTION PARM="adopwsid" NEWVALUE="START" /> 
</CHANGE>

Example: Change workstation only in 3rd operation

<CHANGE SEGMENT="ADOP" SCOPE="3" ID="ch05">
	<ACTION PARM="adopwsid" NEWVALUE="WS3" />  
</CHANGE>

Inside the change element condition element can be placed in order to test all data within scope. Only data that tested in condition as true are changed.

Example: Change workstation only for operation that has number 100

<CHANGE SEGMENT="ADOP" SCOPE="ALL" ID="chng05">
	<COND>adopno = 100</COND> 
	<ACTION PARM="adopwsid" NEWVALUE="WS100" />  
</CHANGE>

By element change it is possible to change also AD application note using the PARM _adidnote in segment ADCOM

Example: Change AD application note to contains text with 3 separate lines, as line separator is used special character &#10;

<CHANGE SEGMENT="ADCOM" ID="ch04">
		<ACTION PARM="_adidnote" NEWVALUE="line1 &#10;line 2----&#10;line 3---" />
</CHANGE>

Resulting AD application will be:

In IWS rule it is possible to change the runcycle offset of IWS application. The IWS rule must change two field in the runcycle.

For positive offset the first is field is field adposoffsets, that must be filled with values with plus operators. The second field is field adrinpos, that must be filled with number of values from the field adposoffsets.

Example: Change runcycle WOCHE positive with one positive offset

<CHANGE SEGMENT="ADRUN" ID="c1" SCOPE="ALL">
<COND>adrper = WOCHE</COND>
<ACTION PARM="adposoffsets" NEWVALUE="+006"/>
</CHANGE>
<CHANGE SEGMENT="ADRUN" ID="c12" SCOPE="ALL">
    <COND>adrper = WOCHE</COND>
     <ACTION PARM="adrinpos" NEWVALUE="001"/>
</CHANGE>

For negative offsets the first is field is field adnegoffsets that must be filled with values with plus operators. The second field is field adrinneg, that must be filled with number of values from the field adnegoffsets.

Example: Change runcycle WOCHE with three negative offsets

<CHANGE SEGMENT="ADRUN" ID="c1" SCOPE="ALL">
    <COND>adrper = WOCHE</COND>
    <ACTION PARM="adnegoffsets" NEWVALUE="-002-003-005"/>
</CHANGE>
<CHANGE SEGMENT="ADRUN" ID="c12" SCOPE="ALL">
    <COND>adrper = WOCHE</COND>
    <ACTION PARM="adrinneg" NEWVALUE="003"/>
</CHANGE>

Delete element will initialize process of deleting data in existing applications segment. Delete of data is possible in these IWS application segments run cycle segment (ADRUN), operation segment (ADOP), external dependencies (ADDEP), special resources (ADSR). Delete in common segment (ADCOM) is not possible. Except IWS application segments it is possible to use DELETE also in IWS additional data (ADDATA).

The scope of delete is configured using attribute scope the same way as for element change.

Example: delete from IWS application all external dependencies

<DELETE SEGMENT="ADDEP" SCOPE="ALL" ID="del01">
	<COND>addepadid NB </COND>
</DELETE>

Example: delete from IWS application completely special resource SYSH.TWS.SR1

<DELETE SEGMENT="ADSR" ID="sr_del">
	<COND>adsrn = SYSH.TWS.SRS1</COND>
</DELETE>

Insert element in rule will insert segment to application record. The inserted data are configured by elements that has the same PIF name as segment – ADCOM, ADRUN, ADOP, ADDEP, ADSR and OI. The PIF field names are stored as attributes to these elements.

Example:

Rule will insert new common segment with application ID (ADID) from PARAM2, which must be created in INIT element. Field valid to (ADTO) is set value 20211231 (date 31.12.2021).

<INSERT ID="ins1">
		<ADCOM adid="PARAM2"  adto="20211231" />
</INSERT>

It is possible to insert segments OI and ADDEP inside the CHECK element with conditions. This configuration enables rule to process all operations and add to them external dependencies or operator instructions.

Example: Process all operations, to operations with CP* workstation and jobname add external dependency to operation 001 from application INPUTAPP1, the attribute addepownop="%adopno" is configuration that will add external dependency to current operation

<CHECK SEGMENT="ADOP" ID="addep12" SCOPE="ALL">
	<COND>adopwsid(1,2) = CP</COND>
	<COND>adopjn NB </COND>
	<INSERT ID="insaddep1">
		<ADDEP addepownop="%adopno" addepadid="INPUTAPP1" addepopno="001" addepwsid="CPU"/>
	</INSERT>
</CHECK>

Message is elements, which configures which messages will be printed during rule processing.

Messages have 4 levels – message, notice, warning, and error. Levels are configured using attribute level. The message levels are affecting the style how the message is printed in web page and helps to distinguish relevance of message to user.

Messages can be inside other rules element for example TEST or CHANGE. Then messages are printed only when all parent element and all actions above line with message run.

Text of message can be configured using 3 ways:

1. Text is placed directly to rule – example:

 <MESSAGE>init1 finished</MESSAGE> 

Text is loaded from system dictionary from directory etc/dictionaries, for example tws rule will print system message “There is no data for the selected Application. Please try it again.” , message is loaded from dictionary twaz_dictionary.xml from id CPIN001-

<MESSAGE translate="true"> CPIN001-41</MESSAGE>  

Text can loaded from custom dictionary twaz_custom_dictionary.xml from directory etc/dictionaries

Example: twaz_custom_dictionary.xml contains following text

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dictionary SYSTEM "dictionary.dtd">
<dictionary languages="en;de" update="2008-07-31">
<dis>
<di id="SAMPLE-rule">
  		<en>Sample message for IWS rule.</en>
  		<de>Beispielnachricht für IWS rule.</de>
</di>
</dis>
</dictionary>

Tws rule will print this text by following message element

<MESSAGE translate="true">PMTWS-FIRST-ACT-HINT</MESSAGE>

In this element are conditions that are applied to Operator Instruction segment data. This type of condition can be used together with other conditions, when the CHECK element is processing the ADOP segment with operations. In the expression can be used pif fields from operation escaped with % character – for example %adopno as operation number or %adopjn as job name.

Example condition that is testing that there is no operator instruction for operation, %adopno is operation number from operations, oiopno is operation number from operator instructions

<OICOND>%adopno NI oiopno</OICOND>

Example processing operations and print message for each operation that is missing operator instruction

<CHECK SEGMENT="ADOP" ID="oi1" SCOPE="ALL">
<OICOND>%adopno NI oiopno</OICOND>
	<MESSAGE level="notice">Operation Opno %adopno has no Operator
			instructions , new OI was inserted </MESSAGE>
</CHECK>

Example processing operations, for operations that have jobname and no operator instruction add operator instruction with operation number and jobname, the special characters &#10; and &#xA; are translated to newline in the operator instruction text, the attribute oipno="%adopno" is configuration that will add operator instruction to current operation

<CHECK SEGMENT="ADOP" ID="oi2" SCOPE="ALL">
<COND>adojn NB </COND>
	<OICOND>%adopno NI oiopno</OICOND>
	<INSERT ID="insoi1">
		<OI oiopno="%adopno" oitext="Operator instruction  &#10; operation number %adopno  &#xA; jobname %adopjn " />
		</INSERT>
</CHECK> 

Condition has syntax of comparing two values with operator. The values can be rule parameters, AD field values or simple text values. Conditions are evaluated as part of elements TEST, CHANGE and DELETE to define conditions under which rule actions are processed.

Conditions are using following operators:

• = equal to

• EQ equal to

• /= not equal

• NE not equal

• EXISTS

• EX – exists

• NOTEXISTS

• NX – not exists

• NOTBLANK

• NB – not blank

• ~= match regular expression

• REGEXP_MATCH match regular expression

• RM match regular expression

• !~ do not match regular expression

• NM do not match regular expression

• NOT_REGEXP_MATCH do not match regular expression

• IN compares one value with set of values, one record from the set of values equals to the value

• NI compares one value with set of values, the set of values does not contain the value

Regular expression are using PHP PCRE regular expression syntax.

The condition operator in COND need two blank characters, one blank char before and one blank character after.

Example: testing whether application owner is user P390R

<COND>adowner=P390R</COND>

Or

<COND>adowner EQ P390R</COND>

Example: testing applications that there is no operation with number 002

<COND>adopno /= 002 </COND>

Or

<COND>adopno NE 002 </COND>

Example: Testing that at application exists at least one operation

<COND>adopno NE 002 </COND>

Or

<COND>adop EX </COND>

Example: Testing Group Definition is not blank

<COND>adgroupid NOTBLANK </COND>

Or

<COND>adgroupid NB </COND>

Example: comparing param value with values loaded from lookup, load PAR5 with values from lookup table, if the workstation name equals to the one of the values from PAR5 print warning message

<INIT ID="init1">
<LOAD SRC="LOOKUP">PAR5
		<TABLE  ID_LOOKUP="ws_e2f" SRCH="column1" REPLACE="column1" />
	</LOAD>
</INIT>
<TEST  ID="test1">
	<COND>adopwsid IN PAR5</COND>
	<MESSAGE level="warning">test message 1</MESSAGE>
</TEST>

The tws rule is saving information about processing to file named twaz_rules-<date>.log, which is located in the log directory of ProcMan installation.

Each action is logged one line in log file file. In log file you find following information:

[timestamp], [username] in process [process id] [id of processing tag, name of xml ] M: rule processing message, information about action done by tws rule

Example of tws rules log, tws rule starts processing IWS app, change in tws application workstation in operation No. 001

[2015.08.17 13:16:25] usr p391x in proc 314 [ TWDC_to_TWEC.xml] M: start processing application MODIFIED.TWGC.ADS1093A.A.A.20711231

[2015.03.24 14:02:32] p391x process 2217 [ch03 TWDC_to_TWEC.xml] M: changing oper No 001 adopwsid to DMYT

All values of rule parameters or AD fields can be casted by substring operation. The substring will return part of original value specified by start and length parameters.

The syntax of substring is: input value (Start, Length)

• Input value – rule parameter or AD field

• Start - is non-negative, the returned value will start at the this position in string, counting from one.

• Length – length or returned value

The IWS ADHOC simple process can process multiple IWS AD records and updates the to the IWS plan.

The user cannot alter the JCL source code in operations or the AD record data.

All AD records in one process share the same parameters for the plan – input arrival, deadline.

User can set additional parameters manual hold, priority and group definition for the updated IWS occurrence.

It etc/app_sec these three fields must be enabled for the dialog in the module m_tws_adhoc_save_many

Example app_sec setting for module m_tws_adhoc_save_many

*^ADHOCSAVEMANY.ADHOCMANY.HOLD_SLT              hidden=false disabled=false
*^ADHOCSAVEMANY.ADHOCMANY.GROUPDEF_TXT          hidden=false disabled=false
*^ADHOCSAVEMANY.ADHOCMANY.PRIORITY_SLT          hidden=false disabled=false

ADHOC SIMPLE process first creates record with DB state ON_DEMAND, this record is AD record with additional Current plan fields – input arrival, deadline, variable table.

By default after successful update to Z/OS the ON_DEMAND record is converted to DB state HISTORY, this record is AD record with additional Current plan fields – input arrival, deadline, variable table.

If settings result_dbstat in interface i_tws_adhoc_simple is set to to IN_PLAN , after successful update to z/OS process creates record with DB state IN_PLAN. IN_PLAN records are records that are connected with their occurence in current plan, user can see occurence status in current plan and with proper environment settings user can change them in current plan.

HOS IWS adhoc processes can insert IWS applications to the current plan of IWS z/OS scheduler.

IWS adhoc simple process select one or more application from IWS and puts it to current plan. All IWS applications are updated to host in one transaction.

IWS adhoc on demand process select one or more application from IWS, provide dialog for change and then puts it to current plan. Each IWS application is updated to host separately,

IWS adhoc on time process loads set of JCL scripts. These JCL scripts are grouped together to one IWS application and updated to host.

.

IWS ADHOC ONE TIME process gets JCL from parent JCL process or from JCL archive. JCL scripts are transformed to operations jobs.

The operations are grouped together to one IWS application with automatically generated name.

User cannot set manual hold and priority to the IWS occurrence.

ADHOC ONE TIME process creates record with DB state ONE_TIME, this record is AD record with additional Current plan fields – input arrival, deadline, variable table. ONE_TIME record is after successful update to Z/OS converted to record with DB state HISTORY and the process is finished.

The user can change and check the JCL source code for operations inside the IWS application in dialog.

The IWS AD application data can be changed in dialog or at the background using IWS rules.

Multiple applications are updated with independent separate transactions to the host.

User cannot set manual hold, priority and group definition for the updated IWS occurrence.

ADHOC ON DEMAND process creates record with DB state ON_DEMAND, this record is AD record with additional Current plan fields – input arrival, deadline, variable table. ON_DEMAND record is after successful update to Z/OS converted to record with DB state HISTORY and the process is finished.

For modification of operations in current plan is used module m_tws_cp_opsel.

This module is configured by process environment by following settings

• Setting cp_update – if set to false save only request to database, if set to true save request and update the current plan with request

• Setting cp_tasks – configure the user’s dialog, each item in this setting configures one button in user interface, the item has 3 configurations action, button, params.

• Action – the predefined CP task that will be executed by button.

• Button – description of the button, description is loaded from twaz_custom_dictionary.xml in directory Procman/etc/dictionaries

• Params – parameters for predefined CP task

Action setting - predefined CP task can contain following values.

• wsmod – change workstation for operations with value WSNAME from params

• opst - change status for operations with value STATUS from params

• occst – modify occurrence status with value STATUS from params

• rsocc – restart occurrence, no parameters

• jcledit - edit JCL of one operation, no parameters

Params setting – name of parameter is taken basically from BatchCP, currently supported params in Procman

• WSNAME – workstation name

• STATUS – status of CP operation or occurence, value C for complete operation, value R for restart operation

• USERDATA – operation user data

Example environment setting for task t0110 with m_tws_cp_opsel module :

       't0110' => array (
                 'tws_source_system'  => array ('%(ADHOC_SUBSYS).'),
         'tws_target_system'  => array ('%(ADHOC_SUBSYS).'),
      	  'cp_request' => true,
             'cp_update' => true,                                                                              
		  'cp_tasks'=> array (
                  'wsdummy' => array(
				'action' => 'wsmod',                                                                    
				'button' => 'CUST_WS_Dummy',
                       'params' => array(                                                                       
                              'WSNAME' => 'DMY'                                                                
                        ),                                                                      
                      ),                                                                                
                 'stcomp' => array(                                                                             
                       'action' => 'opst',                                                               
                       'button' => 'CUST_SET_OP_COMPLETE',                                                                       
                       'params' => array(                                                                       
                              'STATUS' => 'C'                                                                
                       ),                                                                               
                     ),                                                                         
                 'occomp' => array(                                                                                                                                                                   
                       'action' => 'occst',                                                               
                       'button' => 'CUST_SET_CPOC_COMPLETE',                                                                       
                       'params' => array(
                              'STATUS' => 'C'                                                                        
                       ),                                                                       
                     ),                                                 
                'strestart' => array(                                                                              
                      'action' => 'opst',                                                                        
                      'button' => 'CUST_STATUS_RESTART',                                                                
                      'params' => array(                                                                
                               'STATUS' => 'R'                                                               
                       ),                                                                       
                     ),                                                                         
            ),                                                                                          
                                                                                              

Example CP Dialog created by the Procman environment from previous page.

Dictionary for the ProcMan environment from previous page

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dictionary SYSTEM "dictionary.dtd">
<dictionary languages="en;de" update="2008-07-31">
<dis>
<di id="CUST_WS_Dummy">
  <en>Set to Dummy</en>
  <de></de>
</di>
<di id="CUST_WS_WAIT">
  <en>Set to Wait</en>
  <de></de>
</di>

<di id="CUST_STATUS_RESTART">
  <en>Restart</en>
  <de></de>
</di>
<di id="CUST_SET_CPOC_COMPLETE">
  <en>Occurence Complete</en>
  <de></de>
</di>
<di id="CUST_SET_OP_COMPLETE">
  <en>Operation Complete</en>
  <de></de>
</di>

<di id="CUST_JCL_EDIT">
  <en>Edit JCL</en>
  <de></de>
</di>
</dictionary>  

Example setting for CP task that completes operation and write custom text to user data

'opcomplete' => array(
		'action' => 'opst',
		'button' => 'CUST_SET_OP_COMPLETE',
		'params' => array(
			'STATUS' => 'C',
			'USERDATA' => 'PMN%(process).CMP',
		)
 )

Example setting for CP task that completes occurrence and write custom text to user data in first operation of the occurrence

	'occomplete' => array(
               'action' => 'occst',
               'button' => 'CUST_SET_CPOC_COMPLETE',
               'params' => array(
				'STATUS' => 'C',
				'USERDATA' => array('segment' =>'CPOP',
							'value'=> 'PMN%(process).OCC',
							'scope'=>  'FIRST'),
                                         ),
			),
)            

IWS ADHOC processes on demand and on time require setting for managing the creation, update and check of JCL scripts.

In data environment of process are located settings used setting for JCL template. For more information see chapter Data environment-> Environment Settings for ADHOC processes.

In process definition are for JCL used settings in interface i_tws_jck to set settings for JCL check. It enables the processing of JCL code by SmartJCL. Results of JCL check are then displayed in operation list. Setting jcl_check=true means that for job is required JCL check result OK or Warning.

HOS IWS CP processes and functions can modify objects in the current plan of IWS z/OS scheduler.

CP functions can be used in ADHOC SIMPLE processes for IN_PLAN records.

CP functions are customized using the Procman process environment.

CP current plan data are not synchronized, CP functions are not recording all data from current plan. CP functions record only changes made to the current plan.

In case you want to use IWS additional data in object you have to enter setting twaz_objectbrow to file etc/hos_tws_setting. This setting in array, key is action name, value is interface configuration of interface i_tws_ad_appl_mod for object browser. It is similar to setting for module m_tws_ad_appl_load in process config.

Example setting for browser action TWS_BROWSE:

$twaz_objectbrow = array(
   'TWS_BROWSE' => array(
       'i_tws_ad_appl_mod' => ' interrupt=false,'.
       'addata_conf = [adcom =   "conf_sample1",adop = "conf_sample2"],'.
       'addata_format = [adcom = "jcl",adop =  "wai"],'.
       'addata_edit=false' 
    ) 
);

The IWS part supports creation of automatic activities that run on the background without user interaction and can be scheduled to specific time and date. The automatic activities must be configured with command hos_autoexec_jcl.php?root=twaz in ProcMan administration web dialog. The Automatic activies support 3 functionalities - IWS update to host, Copy all applications and Reject.

IWS update to host use module m_tws_auto_ad_update. The module use interface i_tws_ad_appl_tws_upd. In this interface you can specify check IWS rule with option tws_rules_ctrl. If the check rule prints error message the IWS update of current IWS application ends with error without sending the application to host. In process environment the IWS update must have configuration for tws_source_system. The automatic IWS update cannot use the actually logged in user as normal IWS update module. Instead of current user are used configuration settings user and password in file etc\ hwm_autoexec_config.php.

For copying all IWS applications from one IWS system to other one is used module m_tws_auto_ad_copy_all. It works the same way as copyall module called with button 'Copy Source->Target'. The module use interface i_tws_ad_copy_all_appl. In this interface you can specify IWS rule with option tws_rules. This rule can change the IWS applications during copy. In process environment the module must have configuration for both tws_source_system and tws_target_system. The environment setting tws_target_system_selected_index is optional.

For Reject is used module m_tws_reject_auto. Task with this module must be placed to process config to the automation actitivy and before the tasks for IWS update or Copy All. The configuration is done using interfaces i_reject and i_tws_reject. The task configuration in process config is identical with reject configuration for module m_tws_ad_appl_load.

To enable in CP process JCL edit add to process environment ProcMan task jcl edit.

Example task that for jcl edit

'jcleditor' => array(
                     'action' => 'jcledit',
                                   'button' => 'CUST_JCL_EDIT',
                                   'seq' => 20,
                       ),

This task displays for CP operation this dialog

It is possible to add JCL check and check JCL source with SmartJCL. For usage of JCL check add to process environment setting 'jcl_check' => true and to process configuration interface i_tws_jck

Process environment settings with JCL check

'jcleditor' => array(
        'action' => 'jcledit',
        'button' => 'CUST_JCL_EDIT',
        'jcl_check' => true,
        'seq' => 20,
),

Process configuration for module m_tws_cp_opsel with JCL check

array (
        'name' => 't0110',
        'type' => 'task',
        'module' => 'm_tws_cp_opsel',
        'input' => array (
                'i_goto' => 'error=""',
                'i_environment' => '',
                'i_tws_cp_settings' => 'interrupt=true, limit="cp"',
                'i_tws_ad_selection' => '',
                'i_tws_jck' => 'jcl_check=true,template_index="jck_job_approve",hwm_parm=["ADHOC_DATE","ADHOC_TIME"], usr_parm =[par1="test1", par2="test2"]',
         ),
        'output' => array (
                'i_environment' => '',
                'i_tws_ad_selection' => '',
        )
),

For some process activities it is possible to configure custom process messages.

Basic IWS modules are offering interface i_tws_msg, which can alter process message according to your needs.

Custom messages can be placed to xml dictionary twaz_custom_dictionary.xml, which is located in directory etc/dictionaries.

File twaz_custom_dictionary.xml can be edited by any XML enabled editor.

1. In file twaz_custom_dictionary add new element di. Set id attribute to unique key. To child element en add your text in English language, to child element de add your text in German language.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dictionary SYSTEM "dictionary.dtd">
<dictionary languages="en;de" update="2008-07-31">
<dis>
<di id="SAMPLE-Message">
  		<en>Sample message for IWS handover.</en>
  		<de>Beispielnachricht für IWS handover</de>
</di>
</dis>
</dictionary>

Find in PHP process definition interface i_tws_msg in your target task. Example:

'input' => array (
     'i_tws_msg' => 'msg="CompletedStep", 
                    msg_translate=true, 
                   msg_type="message"' 
              ),

Change the msg property of interface i_tws_msg to match the id attribute from step 1.

'input' => array (
     'i_tws_msg' => 'msg="SAMPLE-Message", 
                    msg_translate=true, 
                   msg_type="message"' 
              ),

It is possible the dialog, in which user specifies the criteria for searching for AD applications.

In app_sec in INIT section that corresponds with the process specify the properties for input.

Example 1: Process IWSZ_NEW settings that sets input for Owner ID to readonly and hide input for Owner description

USER IWSZ1
   CLIENT=*+ROLE=*+LOGON=*+REQUEST= IWSZ_NEW
BEGIN
    INIT        
       *^T0140^T_TWS_AD_APPL_NEW_MODIFY_01^ADSEL.ADSL001.OWNERID_TXT      readonly=true 
        *^T0140^T_TWS_AD_APPL_NEW_MODIFY_01^ADSEL.ADSL001.OWNERDESC_TXT  hidden=true disabled=true
END
END

The resulting dialog

It is possible to use in APP_SEC HWM Variables from process definition.

In app_sec is used syntax {}%(parameter_name).{}

Example 2: – use of value HWM variable TL to set value to input Application ID

 T^T0110^CPOPSEL.SELECT_FORM.APPLID_TXT value="_%(TL)._"

When creating app_sec it is very useful to use Options->Show Elements IDs->All

This configuration will enable to load data for picker list from dataset. Advantage of this approach is that it allows to manage regularly the values in pickers.

Prepare csv file picker.csv with data for pickers, it should be list of values in which all rows are ended with comma.

ALLDAY,
BAYERN,
BERLIN,
DEFAULT,

Copy file picker.csv to bin directory of ProcMan . Load the values from file using command line utility tws_rules_lut.cmd . Run command

Tws_rules_lut – o import –i picker –f=“picker.csv“  

You should see message

imported 4 rows to lookup table

To PHP process config file to module m_tws_ad_appl_load interface i_tws_ad_appl_mod add the option picker_conf. The setting picker conf is list (associative array). Array key is name PIF name of field in AD picker (possible key values adcal,adgrpdef,adgroup,adowner) , array value is name of tws rules lookup in database. To enable lookup with id picker to calendar picker list add

picker_conf=[adcal="picker"]

When your press modify button it in the activity with module m_tws_ad_appl_load you should see following dialog.

For ProcMan 4.0.11. and later you can put restrictions to the AD list to individual users or ProcMan groups. The (key) settings are always connected to three parameters:

ProcMan Client, Process name, Limit setting (a flag or string in process configurations and tws_sec table).

Limit setting can be specified in modules m_tws_ad_appl_sel and m_tws_ad_appl_load.

In module m_tws_ad_appl_sel it is configured in interface i_tws_ad_appl_sel.

In module m_tws_ad_appl_load it is used in interfaces for selections: i_tws_ad_appl_sel_mod, i_tws_ad_appl_sel_del.

Interface i_tws_ad_appl_sel_mod is used to select AD for modification and copy.

Interface i_tws_ad_appl_sel_del is used for selection AD for delete.

Example setting in process config, sel setting is used for modification and copy, del setting is used for delete

'name' => 't0140',
        'type' => 'task',
        'module' => 'm_tws_ad_appl_load',
          'input' => array (
             'i_environment' => '',
             'i_tws_ad_appl_sel_mod' => 'tws_target_system="source",
                 interrupt=false, limit="sel"',
             'i_tws_ad_appl_sel_del' => 'tws_target_system="source",
                 interrupt=false, limit="del"',
             'i_tws_ad_appl_mod' => 'interrupt=true',
             'i_tws_ad_appl_ins' => '',
             'i_tws_ad_appl_del' => 'interrupt=false',
             'i_tws_ad_oper_load'=> 'silent=false',
   ),

In the bin directory of ProcMan is commandline utility tws_sec. This utility can import or export settings from csv file.

Columns in csv file

• Role – ProcMan role

• User – ProcMan Account (login user)

• Adid – IWS Application ID

• Adowner – IWS Owner ID

• Adgroupid – IWS Authority group ID

• Jobname – jobname, this column can be used in ProcMan 5.0.3 and higher

For all setting you can use wildcards:

• wildcard represents zero, one or multiple characters

% wildcard represents exactly one character

Example hos_sec.csv file with settings,

role,user,adid,adowner,adgroupid

role,user,adid,adowner,adgroupid
D*,P370V,%V*,,
D*,P370V,T*,,
D*,P371B,%P*,,
D*,P371B,T*,,
D*,P3*,TE*,P*,

For all setting you can use parameters from ProcMan process with the expression %(<parameter name>).

Example for security using ProcMan parameter ADHOC_APP loaded from ProcMan process

role,user,adid,adowner,adgroupid
D*,P370J,%%%(ADHOC_APP).*,,

Conditions in one line are connected with logical AND operator – role D* AND user P370V AND application ID is %V*.

More lines with identical user and role are connected with logical OR operator, in our example for role D* and user P370V the applications ID can be %V* or T*.

In cmdline you can import this csv file to ProcMan client HORIZONT and process IWSZ_TEST with command

tws_sec -f hos_sec.csv -c HORIZONT -p IWSZ_TEST -l sel -o import

to get the syntax enter tws_sec without parameter or with -h:

tws_sec -h 

script for export and import of security data for ProcMan -IWSz
  -h  Show this help menu
  -o  Option for manipulation -  import, export, delete, show
  -f  Filename for command output or input
  -c  ProcMan  client name
  -p  ProcMan  process name
  -l  ProcMan  setting limit in process config
  -m  file export mode, w - overwrite existing file, a - append existing file
example usage:
 tws_sec -o show
  - shows summary of all security data
 tws_sec -f sec1.csv -c HORIZONT -p IWSZ_ADHOC -l sel -o import
  - import data from file sec1.csv to ProcMan  process IWSZ_ADHOC,
     client HORIZONT, limit setting sel
 tws_sec -f sec2.csv -c HORIZONT -p IWSZ_ADHOC -l sel -m w -o export
  - export data to file sec2.csv from ProcMan  process IWSZ_ADHOC,
     client HORIZONT, limit setting sel
 tws_sec -c HORIZONT -p IWSZ_ADHOC -l sel -o delete
  - delete data from ProcMan  process IWSZ_ADHOC, client HORIZONT,
      limit setting sel

The security setting always apply only one combination of role and user that has the best match for the current user.

In our example when user P370V log in process IWSZ_TEST then settings for user P370V and role D* are applied, the general setting for user P3* and D* is ignored.

In our example when user P370C log in process IWSZ_TEST then settings for user P3* and D* are applied, all specific settings for users P370V and P371B are ignored.

Alternative to csv file it is possible to insert data directly to database table twaz_hos_sec by SQL INSERT.

Columns in Table procman.TWAZ_HOS_SEC (all varchar):

• FLAG,

• CLIENT_NAME,

• PROCESS_NAME,

• ROLE_NAME,

• USER_NAME,

• ADID_COND,

• ADOWNER_COND,

• ADGROUPID_COND,

• JOBNAME_COND

Sample Insert, to allow user P370V to select in process IWSZ_TEST applications T* only:

 
INSERT INTO procman.TWAZ_HOS_SEC VALUES (      
   'sel',                                      
   'HORIZONT',                                 
   'IWSZ_TEST',                          
   'D*',                                       
   'P370V',                                    
   'T*',                           
   '',                                         
   '',
   ''                                          
   );                                          

It is possible to configure the behavior of pickers that are used in dialog that edit tws application. This pickers are showing possible values for some fields in IWS dialog.

Example of picker list that displays possible values for authority group id

The following picker lists can be customized:

• Owner ID

• Authority group id

• Calendar id

• Group definition

One way how to customize picker is to use app_sec that has inside values for picker list. This method is preferred when you are using list of values that are not frequently change during time.

The following app_sec setting

Will change the picker list to show 4 predefined values for calendar

This chapter describes the topic of parallel modifications of one IWS application in more than one PMN process. By default, the modification of IWS application in more PMN processes is denied and the PMN user get the the following error message.

To enable the parallel modification in IWS process you have to change the process configuration. For the modify operation that use the button ‘Start Modify AD’ you have to add configuration option parallel_mod=true to interface i_tws_ad_appl_sel_mod in module m_tws_ad_appl_load. In case when the process is using cloning with cloning module m_tws_ad_appl_clone, add to it the interface i_tws_ad_appl_sel with the setting parallel_mod=true.

For the copy operation that use the button ‘Start Copy AD’ the modifications of IWS applications are by default enabled.

Example process config for cloning process with parallel modifications:

array(
        'name' => 't0140',
        'type' => 'task',
        'module' => 'm_tws_ad_appl_load',
        'input' => array(
                'i_environment' => '',
                'i_jcl_approved_files' => '',
                'i_tws_ad_appl_ins' => '',
                'i_tws_ad_appl_load' => 'show_current=true, empty_source=true, tws_update=false, cancel=false',
                'i_tws_ad_appl_sel_mod' => 'tws_target_system="source", interrupt=true,parallel_mod=true',
                'i_tws_ad_appl_del' => 'interrupt=false',
                'i_tws_ad_oper_load' => 'silent=false',
                
        ),
        'output' => array(
                'i_goto' => '',
                'i_environment' => '',
                'i_tws_ad_selection' => ''
        )
),
array(
        'name' => 't0155',
        'type' => 'task',
        'module' => 'm_tws_ad_appl_clone',
        'input' => array(
                'i_goto' => 'cancel="t0140",list="t0140"',
                'i_environment' => '',
                'i_tws_ad_appl_sel' => 'parallel_mod=true',
                'i_tws_ad_copy_all_appl' => 'same_adid_act="mod"',
                'i_tws_ad_clone' => 'conf=['.
                '[type="clone", addata_prefix=["DEV", "TEST", "PROD"]],'.
                '[type="tws", rule="rule_defaults"],'.
                ']'
        ),
        'output' => array(
                'i_environment' => '',
                'i_goto' => ''
        )
),

To disable the parallel modification in IWS process you have to change process config for Copy operation. Add to interface i_tws_ad_appl_copy in module m_tws_ad_appl_load setting create_mods=false. For modify operation the parallel modification is by default disabled.

In process definition it is possible to configure parameters. These parameters are entered by user at process start and can be later used for IWS system selection.

Process definition parameter can directly contain IWS system name and this value is then used by IWSz process environment.

For example we have two IWS systems IWSA and IWSB. To process definition we define parameter IWSYS with two possible values IWSA and IWSB. To process environment for ProcMan activity we define usage of parameter IWSYS this way:

activity' => array (
     'TWS_MODULAR_TEST' => array (
         'environment' => array (
             '!Test environment 1' => array (
                 'task' => array (
                     '*' => array (
                         'tws_source_system'  => array ('%(IWS_SYSTEM).')
                     )
                 )
             )
         )
     )

Process definition parameter can be used indirectly as key to IWS systems list. This approach is reasonable for configuration with more IWS systems and more ProcMan activities. In process environment are used two settings tws_source_system_selected_index and tws_target_system_selected_index.

For example we have four IWS systems IWSA, IWSB, IWSC, IWSD. One process definition parameter GROUP has values TEST1 and TEST2. In process environment we specify usage of IWS system workflow:

• data from IWS system IWSA are copied to IWS system IWSC

• data from IWS system IWSB are copied to IWS system IWSD

'IWS_AUTOEXEC_1' => array (
   environment' => array (
      '!Test environment 1' => array (
           'task' => array (
               't0130' => array (
                   'tws_source_system'  => array ('IWSR'),
                   'tws_target_system'  => array (
                                                  'TEST1'=>'IWSA',
                                                  'TEST2'=>'IWSB'
                   ),
                   'tws_target_system_selected_index' =>'%(GROUP).'
               ),
               't0230' => array (
                   'tws_source_system' => array(
                           'TEST1' => 'IWSA',
                           'TEST2' => 'IWSB'
                   ),
                   'tws_source_system_selected_index' => '%(GROUP).',
                                   'tws_target_system'  => array (
                                               'TEST1'=>'IWSC',
                                               'TEST2'=>'IWSD'
                                   ),
                   'tws_target_system_selected_index' =>'%(GROUP).'
                ),
           )
        )
    )
),

It is possible to customize user used to update or read IWSz data with settings from ProcMan environment.

In ProcMan environment is possible to setup in ProcMan activity setting iwsz_tech_user, this setting overwrites the settings set in “IWS systems administration and settings”.

Setting iwsz_tech_user is on first level divided to IWS system, symbol * apply to all IWS systems or exactly name od IWS system.

Inside setting for IWS system are three settings: user, pwd, actions.

Setting user is username of technical user.

Setting pwd is encrypted password of technical user.

Setting actions is array of update actions, symbol * means any action, value ad_upd means update of AD record to z/OS, value cp_read means read of CP records from z/OS, value cp_upd means update of CP records to z/OS

Example ProcMan environment setting that uses technical user T567A for update of AD records to IWS system OPIT

'iwsz_tech_user'=>array (
  'OPIT' => array (               
	'user' => 'T567A',             
	'pwd'  => '==F5j3wR6Jcw3ddXYSWEEHiBN6T1HcdD5liPrPskL1PPFonJwKVOlTcw==',
'actions' => array ('ad_upd' => true),
     ),
   )

Example ProcMan environment setting that uses technical user T568B for update of CP records to any IWS system

'iwsz_tech_user'=>array (
  '*' => array (               
	'user' => 'T568B',             
	'pwd'  => '==F5j3wR6Jcw3ddXYSWEEHiAM6T1HcdD5liPrPskL1PPFonJwKVOlTcw==',
	'actions' => array ('cp_upd' => true),
     ),
   )