Advanced Training For WLOADCTL: Understanding Functions and Logical Expressions

Overview

The introduction of functions and logical expressions makes the design of workflows and schedulers more flexible.

This article covers the following topics:

1. Introduction to functions and logical expressions

2. Logical operators

3. Scope of application for functions and logical expressions

4. The difference between function calls and variable references

5. Function reference list

1. Introduction to Functions and Logical Expressions

Let's start with a simple example from a workflow definition:

<serial>
  <name>MainModul_rootnode</name>
  <begin>
  <nulljob>
    <name>startctljob</name>
    <jobdesc>Start trigger control node</jobdesc>
    <!--Point 1-->
    <condition>if($(startdatetime)<=systime('yyyymmddhhmiss')) CTL_DOIT else CTL_WAIT</condition>
  </nulljob>
  <sh>
    <name>job12</name>
    <progname>$HOME/shellpath/job12.sh</progname>
    <!--Point 2-->
    <para>$(substr('$(startdatetime)',0,8))</para>
    <maxnum>3</maxnum>
    <!--Point 3-->
    <ignoreerr>dayofweek() in (1,3,5)</ignoreerr>
  </exe>
  <flow>
  <modivarv>
    <name>passflow</name>
    <!--Point 4-->
<para>varname=startdatetime,varvalue=$(addday('$(startdatetime)','yyyymmddhhmiss',1))</para>
    <jobdesc>Flip: modify variable</jobdesc>
  </modivarv>
  <end>
</serial>

Code Walkthrough

• Point 1 : The job executes only when the value of the startdatetime variable is <= to the corresponding system time.

• Point 2 : The substr function extracts the first 8 characters from the value of the startdatetime variable.

• Point 3 : The ignoreerr attribute specifies that if the current day is Monday, Wednesday, or Friday, the job will be allowed to pass after 3 consecutive failures. Otherwise, the job fails and the downstream workflow does not continue.

• Point 4 : The addday function adds one day to the existing value of startdatetime.

2. Logical Operators

Logical expressions are mainly used within the condition and ignoreerr attributes. The table below lists the logical operators supported by WLOADCTL and their meanings.

3. Scope of Application for Functions and Logical Expressions

progname — Program Name

For custom jobs, the program name refers to the executable entity associated with the job, for example, the Job name in a DataStage job, the corresponding program name in Informatica, a shell script name, or a stored procedure name. There are some special job nodes such as begin, end, nulljob, and include do not require this attribute.

para — Runtime Parameters

The para attribute defines the entry parameters that a job program needs at runtime, for instance, command-line arguments for a shell script, or entry parameters for a DataStage job at execution time.

Across different job types, WLOADCTL represents these parameters uniformly as strings within its module code. This format is intuitive for command-line-style programs (shell scripts, executables, Java programs, etc.). For example, a shell program might actually run as:

sh /home/myshellpath/test.sh -user abc -password cba;

Here, -user abc -password cba are parameters.

However, for jobs that require a specialized runtime platform, such as DataStage, the parameter format expected by the underlying program isn't directly visible to us. For these job types, parameters are converted into the required format via a dedicated plugin, following a specific convention.

Below is an example showing how parameters are applied to jobs:

<dsjob>
  <name>SubModul0_JobNode2</name>
  <progname>DSJob1</progname>
  <para>user = $user:password = $password</para>  <!-- DataStage job parameters -->
</dsjob>
<proc>
  <name>SubModul0_JobNode2</name>
  <progname>DSJob1</progname>
  <para>workdate=$workdate</para>  <!-- Stored procedure task parameters -->
</proc>

exppara — Environment Parameters

There are some differences between environment parameters and runtime parameters.

Environment parameters refer to information that must be available at runtime, regardless of the job's own parameters. For example, when a DataStage job runs, it needs to know which project it belongs to. Similarly, when a stored procedure runs, it needs database name, username, and password information. These are treated as environment parameters as well. Some job types (such as shell scripts) don't require any environment parameters at all, since they can simply be executed directly.

The key distinction between environment parameters and runtime parameters is: environment parameters are what the runtime platform itself needs in order to execute the program correctly, while runtime parameters are what the program's internal logic needs. Below is an example of environment parameters applied to a stored procedure job and a DataStage job:

<proc>
  <name>shelljob</name>
  <progname>proc_job1</progname>
  <para>workdate=$workdate</para>
  <!-- Stored procedure environment parameters -->
  <exppara>user=$(user),password=$(password)</exppara>  
</proc>
<dsjob>
  <name>dsjob1</name>
  <progname>ds_job1</progname>
  <para>user=$(user),password=$(password),workdate=$(workdate)</para>
  <!-- DataStage job environment parameters -->
  <exppara>projectname=ocrm</exppara>  
</dsjob>

Beyond the three attributes discussed above (progname, para, exppara), attributes that support function usage include:

4. Function Calls vs. Variable References

Within a workflow, you can reference either a function's return value or a private/public variable's value. While the two share similarities, there are also important differences:

• Referring a function's return value works the same way as referring a variable, both are simply "value references."

• A variable reference must always be wrapped in $(), regardless of context.

• Usually, A function's return value doesn't have to be wrapped in $() unless they are used inside an if condition or nested within another function call.

5. Function Reference List

5.1 String Functions

5.2 Date/Time Functions

5.3 Other Functions

5.4 getjstate — Job Status Reference Table

The table below lists all possible status values returned by getjstate for a job within the current workflow:

Functions and logical expressions help workflows and schedulers in WLOADCTL gain a significant amount of expressive power, if you are interested in those expressions, feel free to try a demo in our Official Website.

← Prev | Job Control By Condition