Dean HarrisonIBM

Date of presentation (03/11/2015)Session NE

Session feedback – Do it online at conferences.gse.org.uk/2015/feedback/NE

WAPL – A Sheepdog in the Pen

22

Abstract

Traditionally scheduling tools made you decide exactly what is going to happen every day in advance, day in, day out. But gone are the days of static workloads, and scheduling tools need to be able to react dynamically to what happens each day. Previously this might have been possible with multiple versions of your schedules for each possible variance, but this brings effort and risk.

IBM Workload Automation for z/OS 9.3 introduced Workload Automation Programming Language for z/OS (WAPL), which can be embedded within your scheduling definitions, allowing day to day variations from within, even being able to react to things that might happen, but you never know in advance. This session will show you how to embed basic WAPL code within your workload to handle rule based variation in execution, to trigger extra workload if needed and understand how to react to unpredictable events.

33

Agenda

1. Embedding

2. The @ function

3. Occurrence control commands

4. Dealing with the unpredictable

Section 1

Embedding

55

New for IWS for z/OS version 9.3

● Workload Automation Programming Language for z/OS● Based on the SOE toolkit

● Is delivered within IWS

● A new capability is to be able to embed WAPL commands in applications

● Commands are stored in operation user fields

● Can be done with a normal WAPL batch job

● Use of a Started Task workstation removes need for individual jobs

66

Why would I use a started task workstation?

● You write ONE piece of JCL for WAPL and reuse over and over again● It's quick, no initiator waits● There is no system restriction of how many can run simultaneously

● Recommended for short processes only● Leave real batch to initiators

● A separate workstation for WAPL is recommended (e.g. CMD1)

● Allows TWS automation to be controlled and limited if necessary

● Easy to spot where commands are being embedded

77

How do I implement a Started Task Workstation?

● First you need to know the setting of OPCOPTS RCLEANUP● See http://www-01.ibm.com/support/docview.wss?uid=swg21254796

In short...

RCLEANUP(YES)

● EQQSTC must be in Master JCL

● STC jobs have job cards (base on EQQJOBS member EQQWCMD1)

RCLEANUP(NO)

● EQQSTC must be in JES PROC00

● STC jobs look like procs (base on EQQJOBS member EQQWCMD2)

88

Customisation of your WAPL STC job

● Recommended name XXXXCMD1 where XXXX is your subsystem name● CMD1 would be your core task

● Allowing for other variants if needed

● Add a library to access your own modules of reusable code

● JCL //USRCODE DD DISP=SHR,DSN=MY.USER.CODE ● Accessed by INCLUDE USRCODE(MYWAPL)

● SYSIN points to pre-built member to identify the user fields to use -

● INCLUDE USER_FIELD(EQQ-SYSIN-*) ● Create your own if you want an alternate user field prefix

NOTE: You can still embed without STC jobs, just slower.

99

Calling WAPL from user fields

● Hello

--------------------------------- OPERATIONS ----------------- Row 1 to 7 of 7 Command ===> Scroll ===> CSR Enter/Change data in the rows, and/or enter any of the following row commands: I(nn) - Insert, R(nn),RR(nn) - Repeat, D(nn),DD - Delete S - Select operation details, J - Edit JCL Enter the TEXT command above to include operation text, or, enter the GRAPH command to view the list graphically. Application : DEEPFROG1 Demonstrate CMD1 WS Row Oper Duration Job name Internal predecessors Morepreds No.of cmd ws no. HH.MM.SS -IntExt- Conds '''' CMD1 001 00.00.01 WSLCCMD1 ___ ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 010 00.00.01 JOB010__ 001 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 020 00.00.01 JOB020__ 010 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 030 00.00.01 JOB030__ 020 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 040 00.00.01 JOB040__ 030 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 050 00.00.01 JOB050__ 040 ___ ___ ___ ___ ___ ___ 0 0 0 '''' NONR 255 00.00.01 ZLAST___ 050 ___ ___ ___ ___ ___ ___ 0 0 0 ******************************* Bottom of data ********************************

---------------------------- OPERATION USER FIELDS ----------- Row 1 to 4 of 4 Command ===> Scroll ===> CSR Enter/Change data in the rows, and/or enter any of the following row commands: I(nn) - Insert, R(nn),RR(nn) - Repeat, D(nn),DD - Delete Application : DEEPFROG1 Demonstrate CMD1 WS Operation : CMD1 001 Jobname : WSLCCMD1 Row User Field Name User Field Value cmd ----+----1----+----2----+----3----+----4----+----5---- '''' EQQ-SYSIN-01 VARSUB SCAN '''' EQQ-SYSIN-02 NOP @(Y) USRF(NOP=YES) '''' EQQ-SYSIN-03 HOLD @(Y) USRF(HOLD=YES) '''' EQQ-SYSIN-04 NOP @(Y) JOBNAME(JOB050) ******************************* Bottom of data ********************************

WAPL (STC)workstation

WAPLTask

Commandsrun in sortsequence

Section 2

The @ function

1111

WAPL knows when it's @

Syntax: @(rule,date,options)

● Returns TRUE or FALSE depending on whether the rule is true

● Simplest form assumes “date” is current IA date for scheduled, actual date for unschedulede.g. @(“MON”) would return TRUE if the AD is scheduled on a Monday

● The function can be used as part of IF/THEN expressions● The function can be used as part of Occurrence Command rules

1212

So what are the rules?

● Days of the week – MON TUE WED THU FRI SAT SUN● Part of the week - WEEKDAY WEEKEND● Day type – WORKDAY FREEDAY ( WORK, W, FREE or F allowed)● Day of the month - D01 – D31● Month of the year - M01 – M12● Name of the month - JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC● Year - Y00 – Y99● A specific date – yymmdd● A valid ADRULE e.g. ONLY LAST(1) DAY(FRIDAY) MONTH

1313

What's in a date

● Specific date in yymmdd format● Relative date in +/-n format e.g. +1, -3 ● Relative Work date in +/-nWD e.g. +1WD (next working day using occurrence calendar)● Relative Work date with alternate calendar e.g. +1WD/MYCAL

1414

What are the options?

● CALENDAR – specifies alternate calendar for use in rule● FDAYRULE – specifies free day rule for use in rule● IAT – specifies input arrival time for use in rule to accommodate calendar work day end

Note: If rule or options contain spaces they should be enclosed in quotes.

1515

Putting it all together

● Multiple @ functions can be combined● Using REXX boolean operators -

● & for AND

● | for OR

● \ or ¬ for NOT

For example

● @(“WORK”) & (“FREE”,+1) – Is today and workday and tomorrow a free day?

● @(“ONLY LAST(1) DAY(FRIDAY) MONTH”) & @(“FREE”) – Is it last Friday and Free?

● @(“FRI”) & \@(“MON”,+1WD) – Is it Friday with next working day NOT being a Monday?

Section 3

Occurrence control commands

1717

What is an occurrence control command?

● A command that runs embedded at the beginning of an application● It checks user fields of each operation in the occurrence

● Makes decisions based on those user fields

● Modifies the behaviour of the operations if required

● There are currently two occurrence commands ● RUNIF – Decides whether an operation will run or not

● ALTIF – Alters specific attributes

1818

RUNIF – Should I run today?

● RUNIF evaluates rules on every operation to decide if it runs● The decision is made as follows -

● If the operation has no rules, it is allowed to run

● If the operation has a positive rule, it is only allowed to run if the rule is true

● If the operation has a negative rule, it is only allowed to run if the rule is false

● To stop an operation running the following happens

● The operation is moved to a non-reporting workstation

● All special resources are removed (optional, but default behaviour)

● All time dependencies are removed (optional but default behaviour)

Note: There is an optional method to only run operations marked with a particular user field

1919

This is how

--------------------------------- OPERATIONS ----------------- Row 1 to 7 of 7Command ===> Scroll ===> CSR Enter/Change data in the rows, and/or enter any of the following row commands: I(nn) - Insert, R(nn),RR(nn) - Repeat, D(nn),DD - Delete S - Select operation details, J - Edit JCL Enter the TEXT command above to include operation text, or, enter the GRAPH command to view the list graphically. Application : RUNIF Demo RUNIF feature Row Oper Duration Job name Internal predecessors Morepreds No.ofcmd ws no. HH.MM.SS -IntExt- Conds'''' CMD1 001 00.00.01 WSLCCMD1 ___ ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 005 00.00.01 JOB005__ 001 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 010 00.00.01 JOB010__ 005 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 015 00.00.01 JOB015__ 010 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 020 00.00.01 JOB020__ 015 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 025 00.00.01 JOB025__ 020 ___ ___ ___ ___ ___ ___ 0 0 0 '''' NONR 255 00.00.01 ZLAST___ 025 ___ ___ ___ ___ ___ ___ 0 0 0 ******************************* Bottom of data ********************************

RUNIF CRITERIA(RUNME) WSNAME(NONR)

RUNME-POS-01=@(MON)

RUNME-POS-01=@(TUE)

RUNME-POS-01=@(WED)

RUNME-NEG-01=@(THU)

2020

ALTIF – How should I run today

● ALTIF can alter attributes dependent on rules● Rules are contained in user fields (IF)

● Actions to perform are also in user fields (DO)

● The action is defined as keywords of ALTER command

● If the rule is false, or the operation has no rules, no action is taken

● The kind of things that can be altered are

● Time dependency attribute

● Operation input arrival

● Remove special resources

2121

This is how

--------------------------------- OPERATIONS ----------------- Row 1 to 7 of 7Command ===> Scroll ===> CSR Enter/Change data in the rows, and/or enter any of the following row commands: I(nn) - Insert, R(nn),RR(nn) - Repeat, D(nn),DD - Delete S - Select operation details, J - Edit JCL Enter the TEXT command above to include operation text, or, enter the GRAPH command to view the list graphically. Application : ALTIF Demo ALTIF feature Row Oper Duration Job name Internal predecessors Morepreds No.ofcmd ws no. HH.MM.SS -IntExt- Conds'''' CMD1 001 00.00.01 WSLCCMD1 ___ ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 005 00.00.01 JOB005__ 001 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 010 00.00.01 JOB010__ 005 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 015 00.00.01 JOB015__ 010 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 020 00.00.01 JOB020__ 015 ___ ___ ___ ___ ___ ___ 0 0 0 '''' CPU1 025 00.00.01 JOB025__ 020 ___ ___ ___ ___ ___ ___ 0 0 0 '''' NONR 255 00.00.01 ZLAST___ 025 ___ ___ ___ ___ ___ ___ 0 0 0 ******************************* Bottom of data ********************************

ABC-01-IF=@('ONLY LAST(1) DAY(WORKDAY) WEEK')

ABC-01-DO=UFNAME(LATESUB) UFVALUE(23:24 TUESDAY)

ALTIF CRITERIA(ABC)

ABC-01-IF=@(MON) | @(TUE)ABC-01-DO=OPIA(!OYMD1.2359) TIMEDEP(Y)

ABC-02-IF=@(WED) | @(THU)ABC-02-DO=OPIA(!OYMD1.2345) TIMEDEP(Y)

ABC-01-IF=@(MON) ABC-01-DO=TIMEDEP(Y)

2222

Let's pretend

● These techniques can also be used for testing ● Providing the ability to “pretend” it's a different day

● So in the command -EQQ-SYSIN-01 VARSUB SCANEQQ-SYSIN-02 VARSET RULEDATE VALUE(!OYMD1.) USRF(USERDATE)EQQ-SYSIN-02 ALTIF CRITERIA(ABC)

● Then in the rules -@(“MON”,!RULEDATE.)

● So in normal cases RULEDATE is set to the Input Arrival

● But if you add a user field called USERDATE it will use that value insteadINSERT CPOC ADID(MYDYNAMAPPL)MODIFY CPOP OPNO(001)INSERT CPUSRF UFNAME(USERDATE) UFVALUE(151104)

Section 4

Dealing with the unpredictable

2424

It isn't JUST about the @ function

● Rules can combine function calls with other expressions@(MON) & (“!MYVAR.” = “NO”)

● The variable can be● Passed in by a user field

● A TWS supplied variable

● A variable in a TWS table

● Something set or manipulated in the code

● So a rule could be as simple as - “!DATA” = “YES”● Somewhere in your batch you set the variable DATA to YES or NO

● Then RUNIF can be used at any point following to make jobs only run if there is data

2525

You can write as much “program” as you like

● Up to 100 lines directly embedded ● Only 54 characters per line

● INCLUDE can be used to go beyond 100 lines and 54 characters

● WAPL code and other User Fields can co-exist due to EQQ-SYSIN- prefix

● The code can call ANY command, not just restricted to RUNIF or ALTIF

● The Current Plan Operation commands have a special keyword of ==

● When == is coded the search is restricted to operations within the same occurrence

● Essentially a short form replacing the ADID and IA keywords for 54 character limit

2626

Addition instead of subtraction

● For infrequent batch you can decide to add to the plan on demand● Application jobs would decide whether “today is the day”

● These could then set a TWS variable

● Then a WAPL operation can decide to include batch at key pointsVARSUB SCANVARSET DATA = "YES"IF "!DATA" = "YES" THEN ADD ADID(ADHOC) LINK(YES)

● The LINK keyword inserts the new application ahead of the WAPL successors

2727

Any questions?

2828

Please submit your feedback at

http://conferences.gse.org.uk/2015/feedback/NE

Session is NE