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.

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.

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

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.

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.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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>

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>

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>

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>

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

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