Home
HCL Workload Automation for Z
Welcome to the HCL Workload Automation for Z documentation, where you can find information about how to install, maintain, and use the product.
Workload Automation Programming Language for z/OS User's Guide and Reference
OPTIONS keywords
Use the following keywords with the OPTIONS statement.
FAIL – Action to take with return codes
In normal use, Workload Automation Programming Language is expected to fail with non-zero return codes in the event of errors being found. However, during parallel testing when migrating from an alternative workload automation product to HCL Workload Automation for Z, it is normal to send commands to HCL Workload Automation for Z first, then to the alternative product that is controlling the workload. This enables HCL Workload Automation for Z to be in the correct state to track events from the alternative product.

HCL Workload Automation for Z
Welcome to the HCL Workload Automation for Z documentation, where you can find information about how to install, maintain, and use the product.
- Program Directory
- Dynamic Workload Console Readmes
  For the latest information about a Dynamic Workload Console fix pack, see the appropriate Readme File.
- Planning and Installation
- Customization and Tuning
- Managing the Workload
  You can plan when and how your workload runs and manage it as part of a plan.
- Scheduling End-to-end with z-centric Capabilities
- Quick Reference
- Diagnosis Guide and Reference
- Workload Automation Programming Language for z/OS User's Guide and Reference
  - About this publication
  - Overview
    The Workload Automation Programming Language is a programming language that provides you with easy access to the features of the HCL Workload Automation for Z Program Interface (PIF).
  - Running Workload Automation Programming Language
    You can run Workload Automation Programming Language as a batch job by using the compiled REXX exec, as a load module, online within a TSO session, as a started task workstation, or as a console command. A user program must run as an authorized program.
  - Core programming commands
    The following sections describe the Workload Automation Programming Language commands that control the behavior and logic of the program. Use the commands to set options, return codes, determine an output, modify the flow, change variables, or make decisions.
  - Workload Automation Programming Language functions
    Some commands in Workload Automation Programming Language operate in REXX mode. These commands are CONSOLE, DISPLAY, DO, IF, LOG, SETVAR when the equal sign (=) is used, and WRITE.
  - Data Access commands based on PIF
    The Data Access commands supported by Workload Automation Programming Language are low level commands based on the HCL Workload Automation for Z programming interface (PIF).
  - Current Plan Operation commands
    Use the Current Plan Operation commands to perform specific functions against operations in the current plan, using a common set of keywords to identify the operation you want.
  - Current Plan Occurrence commands
    Use the Current Plan Occurrence commands to perform specific functions against all operations within a single occurrence in the current plan, using a common set of keywords to identify the occurrence.
  - Function Based commands
    The Function Based commands combine various low level PIF commands. Use the Function Based commands to perform specific scheduling or operational functions.
  - Using TSO commands within Workload Automation Programming Language
    Some TSO commands are specific to HCL Workload Automation for Z; you can run them natively in TSO, through program EQQEVPGM, and through Workload Automation Programming Language.
  - Batch loader commands
    The batch loader function of Workload Automation Programming Language uses a set of statements to define or modify objects within the HCL Workload Automation for Z database.
  - Variable substitution
    Workload Automation Programming Language supports variable substitution within its control statements. In this way, the actual values required for each command run are provided (for example, the occurrence name or Input Arrival date).
  - Performance considerations
    With Workload Automation Programming Language you can use different methods to perform the same action. Each method has different implications for ease of use and performance, the balance of which might change depending on the volume of records to which it is being directed.
  - Resource reference
  - OPTIONS keywords
    Use the following keywords with the OPTIONS statement.
    - ACTION – See DBMODE
      This keyword has been deprecated, use OPTIONS DBMODE instead.
    - ADOICHK – Consistency check
      Determines whether AD/OI consistency checks are to be made every time an application is deleted or modified.
    - ADPFX – Prefix for dynamically created applications
      Specifies the application name prefix to be used in commands that generate dynamic applications (ADDJOB). The default is ADHOC#.
    - ADSFX – Suffix for dynamically created applications
      Specifies the application name suffix to be used in commands that generate dynamic applications (ADDJOB). The default is blank.
    - ADVALFROM – Valid From generation
      How to set the Valid From date in generated Batch Loader.
    - ADVERS – Application versioning
      Application version support
    - ADWS – Workstation for dynamically submitted jobs
    - BLSTYLE – Style of Batch Loader output
      The output style to be sent to the Batch Loader output file.
    - CALENDAR – Set default calendar name
      Used for the commands that need to know a calendar name, when none is supplied in the keywords for that command.
    - CHARAT – Set the at sign (@) for object variables
      Within Workload Automation Programming Language, the at sign (@) is used to designate an object variable.
    - CHARBANG – Set the exclamation mark (!) for default variable prefix
      Within Workload Automation Programming Language, the exclamation mark (!) is used as the default variable prefix.
    - CHARHASH – Set the number sign (#) for count object field and ENVATTR
      Within Workload Automation Programming Language, the number sign (#) is used to designate the count of the number of a specified segment in object variables and a count within VARSET ENVATTR.
    - CHARMAIL – Set the at sign (@) for email addresses
      Within Workload Automation Programming Language, the at sign (@) is used to build an email address from any unqualified addresses in the SENDMAIL command by using the character in combination with the OPTIONS MAILSERV setting.
    - CHECK – Application integrity
      Whether to check the existence for workstations with applications, when processing batch loader.
    - COMMIT – File output caching
      Number of output records to hold in storage before committing to disk (default is 1000).
    - COMPSUCC – Set the default values for the ADDJOB and JBSTART commands
      The COMPSUCC keyword of the ADDJOB and JBSTART commands determines what action to take when a successor is identified as already complete.
    - CONINFO – Information level IEExxxI message numbers
      Specifies a list of message numbers for IEExxxI messages to be considered as true informational messages and not cause a return code of 8.
    - CONNAME – MCS console name
      Sets the MCS console name to be activated to run a CONSOLE command.
    - CONWAIT – Wait timing for response messages
      Sets how long the CONSOLE command waits for a response message.
    - CONWARN – Warning level IEExxxI message numbers
      Specifies a list of message numbers for IEExxxI messages to be considered as warning messages to cause a return code of 4.
    - CONTENTION – Retry limits
      What to do in event of contention within HCL Workload Automation for Z.
    - CPDEPR – Current Plan dependency resolution
      Automatic resolution of external dependencies when inserting new current plan occurrences.
    - CPFAIL – How to handle Current Plan modification failure
      PIF commands that update elements in the current plan, such as MODIFY and INSERT, by default will end with RC=8 if they fail. This does not prevent Workload Automation Programming Language from continuing processing, and might result in incomplete updates being committed by a subsequent EXECUTE statement. The CPFAIL option prevents this from happening.
    - DATE – Workload Automation Programming Language internal date
      When using the equal sign (=) to represent a DATE or TIME within Workload Automation Programming Language, by default the date and time when Workload Automation Programming Language started is used.
    - DATA – ILSON data destination
      File Destination (such as DD Name) to override value specified on the OUTPUT DATA keyword.
    - DBMODE – Mode of operation for database updates
      Determines the operating mode for Batch Loader.
    - DECODE – Determine which fields to decode
      When a segment is retrieved from HCL Workload Automation for Z, it can be automatically decoded into its separate fields. The DECODE keyword decides how much of each segment to decode.
    - DELAY – Post update delay specification
      Specifies a number of seconds to pause after issuing any update command to the HCL Workload Automation for Z PIF (default 0).
    - DELAYCMD – Commands to wait after
      PIF commands to consider as update commands to perform a delay after (default DELETE EXECUTE INSERT REPLACE).
    - DELETE – Automatic delete processing
      Sets the default value for the DELETE keyword of the LIST statement.
    - DELFILE – File to write deferred DELETE to
      File Destination where to write deferred DELETE statements.
    - DLM – End of instream data delimiter
      Defines the default delimiter for ending instream data within Batch Loader output. The default is -END-OF-INPUT-TEXT-.
    - DROP – Circumvent occurrence split for ALTER DROPSUCC/PRED
      The OPTIONS DROP keyword provides mechanisms that circumvent occurrence inconsistencies.
    - DUPAUTO – Allow automatic SELECT statements to output duplicates
      Controls if any duplicates automatically listed by OPTIONS SELECT or OPTIONS EXPAND are selected for processing.
    - DURUNIT – Duration unit for Batch Loader
      States the unit to specify durations.
    - DYNATTR – Set attributes for dynamic log
      The OPTIONS DYNLOG keyword causes a dynamic log file to be created to save a copy of the Workload Automation Programming Language log.
    - DYNLOG – Create a dynamic copy of the Workload Automation Programming Language log
      During parallel testing, if the OPTIONS FAIL(N) or SPOOF keywords are used, you cannot identify the problems with the HCL Workload Automation for Z part of the processing. This keyword prompts Workload Automation Programming Language to create a copy of the log in a uniquely named data set, so that the logs can be collated and scanned for errors at points in the testing cycle.
    - EXECUTE – Automatic Current Plan EXECUTE
      Automatically performs an EXECUTE before termination.
    - EXPAND – LIST related objects
      Whether to generate LIST statements for any database elements that might be required by a SELECTed database element.
    - FAIL – Action to take with return codes
      In normal use, Workload Automation Programming Language is expected to fail with non-zero return codes in the event of errors being found. However, during parallel testing when migrating from an alternative workload automation product to HCL Workload Automation for Z, it is normal to send commands to HCL Workload Automation for Z first, then to the alternative product that is controlling the workload. This enables HCL Workload Automation for Z to be in the correct state to track events from the alternative product.
    - FASTPATH – Current Plan search option
      When you want to retrieve only computer and printer operations, FASTPATH makes the search for operations faster.
    - FIELDSEP – ILSON field separator
      The Field Separator character is used to separate fields in the DATA output. You can specify either a single character reference, for example a comma, as in FIELDSEP(,), or a hex value as a two byte notation or two bytes suffixed with x, for example FIELDSEP(00) or FIELDSEP(00x).
    - FILESPEC – File Specification DD statement
      DD name from which to read File Specification.
    - FIRST – Logical First operation
      Sets the default logical first operation within an application for any process that needs a logical start point.
    - FREEMAX – Maximum number of consecutive free days to skip
      To calculate dates using workdays as the offset, a calendar might have been defined with no workdays, causing calculations to loop infinitely. Use the FREEMAX keyword to set a limit of consecutive free days to process before the command fails.
    - GTABLE – Default Global Table
      Used for any commands that need to know a global table name, when none is specified in the keywords for the command.
    - HIGHRC – Highest accessible return code
      Highest acceptable return code.
    - IFCMD – Default step to consider for command return code checking
      The @CMD function is used to check the return code of a previous command. If the command label is not specified, the default command to check is determined by this OPTIONS keyword.
    - IFJCL – Default step to consider for JCL step return code checking
      The @JCL tag is used to check the return code of a previous JCL step in the current job. If the command label is not specified, the default command to check is determined by this OPTIONS keyword.
    - IGNORE – Default value for ADDJOB IGNORE keyword
      Sets the default specification of internal dependencies to ignore.
    - INCLEVEL – Message level for INCLUDE statements
      By default, any statements run as a result of INCLUDE statements is listed only when either the MSGLEVEL is 3 or higher, or the statement fails. Use INCLEVEL to specify an alternative message level for listing the contents of the included members.
    - INPUT – Command input DD statement
      You can name a specific DD statement for Workload Automation Programming Language to read for the main command stream, specify an address for a control block containing the main command stream, or specify INPUT(-OFF-) to prevent Workload Automation Programming Language from attempting to read an INPUT stream from a file, so it reads only from the External Data Queue.
    - JSFILE – DD name of input JCL for JSSTART
      Used to set the input library for the JSSTART batch loader command. The default value is EQQJSPDS.
    - LABELSEP – ILSON label separator
      The Label Separator character used to separate field Labels from Values in the DATA output.
    - LAST – Last logical operation
      Sets the default logical last operation within an application for any process that needs a logical end point.
    - LIMIT – Unconstrained loop limit
      DO WHILE, DO UNTIL, and DO FOREVER loops might run infinitely. This option restricts the types of loops to a maximum number of iterations, before the process fails.
    - LOADER – Batch Loader output destination
      File Destination (such as DD name) to override value specified on the OUTPUT LOADER keyword. Setting a minus sign (-) suppresses LOADER output.
    - LOCK – Batch Loader locking
      Whether to enable the extended Batch Loader locking for the DBMODE UPDATE and DBMODE COPY statements.
    - LTDEPR – Long Term Plan dependency resolution
      Automatic resolution of external dependencies when inserting new LTP occurrences.
    - MAILDD – DD name of input text for SENDMAIL
      Used to set the input library for the SENDMAIL command.
    - MAILFROM – Email address of mail sender
      Used to set the default FROM value for the SENDMAIL command.
    - MAILSERVER – Domain name of the mail server
      Used to set the default SERVER value for the SENDMAIL command.
    - MAILSMTP – DD name of SMTP output
      Used to set the output DD name for the SENDMAIL command.
    - MEMORY – Memory usage
      This OPTIONS keyword is no longer effective. Original values are accepted for backwards compatibility.
    - MMMM – List of months
      Specifies the list of month names to be used in the DATEADD and DATEFORM functions. By default, the names are in English but you can use OPTIONS MMMM to set the months in a different language.
    - MSGLEVEL – Output message level
      Determines the level of messages to be issued.
    - OIFILE – DD name of input text for OISTART
    - OPID – Identify controlling operation
    - OPMSG – Send messages to console
      Whether to issue messages with severity O to Operator Console.
    - OUTMASK – Output mask
      Tells Workload Automation Programming Language to treat the percent sign (%) and asterisk (*) as masking characters for updating fields within Batch Loader statements.
    - OVERWRITE – Whether to overwrite an object during rename
      When using NEW_ prefixes for fields when using Batch Loader in UPDATE or COPY mode, they will result in a new name for the object. This new name might point to another pre-existing object. By default, the update fails. The OVERWRITE option enables you to modify this behaviour to allow the replacement of the existing object.
    - OWNER – Owner ID for tables created by VAR* commands
      When a VARDATE, VARSAVE, or VARSET command tries to save a variable to a table that does not exist, an Owner ID must be provided. This keyword provides the value to use for these eventualities.
    - PGMPIF – Program to use for HCL Workload Automation for Z communication
      Program to call HCL Workload Automation for Z PIF (default is EQQYCOM).
    - PGMSTOR – Program to use to manage storage
      Program to allocate storage (default is EQQSTOR).
    - PGMWAIT – Program to use to wait
      Program to use to wait for contention retry (default is EQQRETWM).
    - POSTPROC – Post process external data queue
      After processing all initial command statements on the external data queue and in the INPUT source (usually SYSIN), Workload Automation Programming Language terminates. If you dynamically generate more command statements into the External Data Queue during execution, for example Batch Loader, use this option to have Workload Automation Programming Language processed these extra statements.
    - PREMPTY – Action to take when creating period with DATELIST and ADID
      Determines the action to take when a period automatically created is about to be created with no intervals.
    - REPORT – Report output width
      Sets the report width for output messages in SYSTSPRT (default is 80).
    - RETMSG <unavailable option>
      Restricted option. Managed internally by Workload Automation Programming Language, not permitted with Workload Automation Programming Language command stream.
    - RETMSGID <unavailable option>
      Restricted option. Handled internally by Workload Automation Programming Language, not permitted with Workload Automation Programming Language command stream.
    - RUNIF – Set defaults for conditional execution
    - RUNSTAT – Alter run cycle status
      Modifies the unloaded values of the Valid From (ADRVALF) and Valid To (ADRVALT) dates of each run cycle. This affects the value in any generated Data or Batch Loader output. It does not affect the database, unless you process the generated Batch Loader output.
    - SENDDATA – Output ILSON data
      Whether to send HCL Workload Automation for Z data information to files specified in the OUTPUT DATA keyword.
    - SENDLOADER – Output Batch Loader
      Whether to send Batch Loader information to files specified on the OUTPUT LOADER keyword.
    - SELECT – Automatic selection
      Sets the default value for the SELECT keyword of the LIST statement.
    - SETMAX – Influence default SETMAX behaviour
      Sets the default behaviour of the SETMAX command.
    - SETUP – Default SETUP attribute for Workload Automation Programming Language variables when saved
      Sets the default SETUP value for any new VARSET and VARDATE variables when saved into a JCL Variable Table.
    - SEVERITY – Message severity levels
      Defines the message severities to display.
    - SILENT – Silent running
      Sets the special message level -1 from the start of Workload Automation Programming Language that prevents all messages except Fatal and Critical from being issued.
    - SHOWDFLT – Show values that are set to defaults
      Whether to create batch loader keywords for fields with default values.
    - SHOWKEYS – Display key information
      Whether to display the key information for each record identified by a LIST statement.
    - STOPRC – Return code to terminate processing
      The return code that causes processing to stop.
    - STRIP – Remove trailing blanks and leading zeroes
      Whether to strip blanks and leading zeroes from DATA and LOADER output.
    - SUBSYS – Input file for controller options
      Workload Automation Programming Language can read subsystem specific OPTIONS statements after it has read the default options from the OPTIONS input source. Use the SUBSYS keyword to specify the DD statement from which to read the subsystem specific options (the default is <blank>).
    - SUFFIX – Object name suffixing
      How to manage the SUFFIX Batch Loader keyword.
    - SUPMSG – Message suppression
      SUPMSG allows you to prevent a message from being written to the message log.
    - SYNTAX – Legacy syntax compatibility
      Restricts Batch Loader output and input syntax to legacy Batch Loader (EQQYLTOP) compatibility.
    - SYSID – Tracker lookup method
      SYSID allows you to set the field with which to look up LPAR specific values in lookup tables such as OPTIONS TRACKERS.
    - TAGMODE – Set automatic tagging
      TAGMODE turns on automatic tagging of descriptions for All Workstations Closed, Calendar Specific Dates, and Workstation Intervals.
    - TAGMASK – Set tagging mask
      Use TAGMASK to describe the layout of the tag to be added to a description of a date related option. Its use is activated by OPTIONS TAGMODE.
    - TEMPFILE – DD name of temporary library allocation
      Used to set the DD name for allocating individual members of a library for processes that allow member name input from a PDS or PDSE.
    - TIME - Workload Automation Programming Language internal time
      When using the equal sign (=) to represent a DATE or TIME within Workload Automation Programming Language, by default the date and time when Workload Automation Programming Language started is used. Workload Automation Programming Language maintains a static internal time to allow you to generate multiple statements with a "current time" that is consistent across all statements, regardless of whether the time changes during run time.
    - TRACE – Perform interface tracing
      The TRACE keyword causes Workload Automation Programming Language to list detailed HCL Workload Automation for Z Program Interface information to help you debug any difficulties you might be having.
    - TRACKERS – Tracker lookup
      The TRACKERS keyword allows you define a lookup table to allow the HCL Workload Automation for Z TSO commands to know the tracker subsystem to which to send events for a combination of Controller and JES Node.
    - UPDATE – Default value for UPDATE keyword
      Sets the default value for any commands that use the UPDATE keyword to determine whether to actually perform updates, or just simulate the process.
    - VARNAMES – Special characters to allow in variable names
      Workload Automation Programming Language allows variable names to consist of letters, numbers, and the characters: at sign (@), number sign (#) and underscore (_).
    - VERADGRD – Verify groups exist
      Application descriptions that are members of an application group have the name of the group definition in field ADGROUPID of segment ADCOM. VERADGRD controls the verification of this field when a new application description is created or an existing application is replaced.
    - VERSION – HCL Workload Automation for Z version
      Specifies the version of HCL Workload Automation for Z with which to communicate. This prevents inappropriate commands from being issued and generates only Batch Loader compatible with the specified version.
    - VERSRWSN – Verify workstations
      The special resource description, SR, has fields representing workstations, the complete workstation names, or generic names; field SRDWSNAME of segment SRDWS for default connected workstations, field SRIWSNAME of segment SRIWS for workstations connected to an interval. VERSRWSN controls the verification of these fields when a new special resource is created or an existing resource is replaced.
    - WWWW – List of days of the week
      Specifies the list of day of the week to be used in the DATEADD and DATEFORM functions. By default, the names are in English but you can use OPTIONS MMMM to set the days in a different language.
    - XMBLK – Whether to return a message control block
      Use this option to specify that when commands are passed to Workload Automation Programming Language through a control block, the log messages are returned in a second control block.
    - XMSEV – Severity of messages to return in a message control block
      Use this option to set the severity of the Workload Automation Programming Language messages that are returned through a control block.
  - Workload Automation Programming Language variables
    In addition to the HCL Workload Automation for Z variables and user variables, Workload Automation Programming Language has access to some additional information relating to the job running Workload Automation Programming Language and when scheduled the operation and occurrence within which it is running.
  - WAPLEXEC programs
    The Workload Automation Programming Language for z/OS is a REXX based tool provided to give you easy access to the features of the HCL Workload Automation for Z Program Interface (PIF). Workload Automation Programming Language can be extended by WAPLEXEC programs, which are REXX programs using Workload Automation Programming Language functions to tackle specific tasks or functions.
  - Messages and Return Codes
    Messages and return codes provide information for problems occurred.
- Driving HCL Workload Automation for Z

FAIL – Action to take with return codes

In normal use, Workload Automation Programming Language is expected to fail with non-zero return codes in the event of errors being found. However, during parallel testing when migrating from an alternative workload automation product to HCL Workload Automation for Z, it is normal to send commands to HCL Workload Automation for Z first, then to the alternative product that is controlling the workload. This enables HCL Workload Automation for Z to be in the correct state to track events from the alternative product.

The following values are valid for FAIL:

YES: Default. Workload Automation Programming Language flushes commands after the OPTIONS STOPRC return code is issued, and returns the highest return code back to the running job.
NO: Workload Automation Programming Language continues processing commands even if the OPTIONS STOPRC return code has been reached, and in most circumstances ends with return code zero. Severe syntax issues causes the Workload Automation Programming Language step to fail, but these should be eliminating in testing before parallel running. All error messages will be echoed to the SYSLOG to be collected as part of the parallel testing process.
QUIET: Workload Automation Programming Language continues processing commands, even if the OPTIONS STOPRC return code has been reached, and in most circumstances ends with return code zero. Severe syntax issues causes the Workload Automation Programming Language step to fail, but these should be eliminating in testing before parallel running. No error messages will be echoed to the SYSLOG.

Note: OPTIONS FAIL overrides any return codes from commands, including SETMAX, but is overridden if OPTIONS SPOOF is coded.

Have feedback?
Google Analytics is used to store comments and ratings. To provide a comment or rating for a topic, click Accept All Cookies or Allow All in Cookie Preferences in the footer of this page.