ESP Workload Manager Version 5.4

Reference Guide

ESP-5.4-RG-05

Fifth Edition (April 2005)

This edition applies to Version 5 Release 4 of ESP Workload Manager documentation. The software and related manuals are protected by copyright law.

Trademark Notice

Cybermation, ESP Workload Manager, and ESP Workstation are registered trademarks of Cybermation, Inc.

ESP Encore is a registered trademark of Cybermation Inc.

IBM and z/OS are registered trademarks of IBM.

All other brand and product names are trademarks or registered trademarks of their respective companies.

ESP Workload Manager documentation© 2005 Cybermation Inc.All rights reserved.

No portion of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written permission of

Cybermation International Distribution SRLwww.cybermation.com

U.S. Government Users. RESTRICTED RIGHTS—Use, duplication or disclosure restricted by the GSA ADP Schedule Contract with Cybermation USA, Inc., a subsidiary of Cybermation International Distribution SRL.

Contents

iii

Overview ...........................................................................................................1Term definitions ................................................................................................4Conventions used in the Guide .........................................................................6Summary of changes .........................................................................................8ABANDON DEPENDENCIES Statement: Submit Job WithoutPredecessor Dependencies ..............................................................................14ABANDON RESOURCES Statement: Submit Job Without Resource Dependencies .................................................................................16ABANDON SUBMISSION Statement: Bypass Job Submission ..................18ABAPNAME Statement: Run ABAP Steps Within an SAP Job ...................21ABENDLIM Command: Set ABEND Queue Size ........................................23ABSORB Statement: Reserve Resources .......................................................25ADJUST Command: Adjust Run Time ..........................................................26AFTER Statement: Specify Predecessors .......................................................28AGENT Command: Define an ESP Agent to ESP Workload Manager .........32AGENT Command: Display Agent Definition ..............................................35AGENT Statement: Identify Where Job Runs ................................................38AGENT_MONITOR Statement: Define Monitoring Workload Objects .......40AGENTMSG Command: Send Messages to Agent .......................................41AGENTRCV Command: Agent Receiver Definition ....................................48AIX_JOB Statement: Identify the Name of AIX Jobs ...................................51ALERTDEF Command: Define Alert ............................................................52ALLOWUNDEF Statement: Turn Off Flagging of Undefined Symbols .......54ALTCAL Command: Alter Calendar Definitions ..........................................55ALTEVENT Command: Alter Events ............................................................57ALTGROUP Command: Alter Groups ..........................................................60ALTSIG Command: Alter Signals .................................................................62ALTTJ Command: Alter Job Tracking Data ..................................................63ALTUSER Command: Alter User Definitions ...............................................65AMNOTIFY Statement: Notify when Agent Becomes Inactive ....................68APPL Statement: Identify and Set Applications .............................................69APPLDISPLNAME Statement: Identify the Application Name of an Oracle Application ......................................................................74APPLEND Statement: Perform Processing Automatically at End of Application .....................................................................................75APPLINS Command: Insert commands and statements ................................77

Contents

Contents

iv

APPLJOB(AJ) - Command: Controlling Applications ..................................80APPLJOB(AJ) Command: Controlling Jobs and subApplications ................82APPLSHORTNAME Statement: Identify the Application Short Name for an Oracle Application ...........................................................96ARCCLIENT Statement: Specify SAP Archive Link Client .........................97ARCCONNECT Statement: Specify SAP Archive Link Communication Connection ..........................................................................98ARCDATE Statement: Specify SAP Archive Link Archiving Date ............100ARCDOCCLASS Statement: Specify SAP Archive Link Document Class ....................................................................................101ARCDOCTYPE Statement: Specify the SAP Archive Document Type .....103ARCFORMAT Statement: Specify SAP Archive Output Format ...............104ARCHOSTLINK Statement: Specify SAP Archive Link RPC Host ...........105ARCINFO Statement: Specify the SAP Archive Link Information .............107ARCMODE Statement: Specify the SAP Archive Mode .............................108ARCOBJNAME Statement: Identify Name of SAP Archiving Object .......109ARCOBJTYPE Statement: Specify SAP External System Archive ............110ARCOBJVARIANT Statement: Identify Name of SAP Archiving Object Variant .............................................................................111ARCPATH Statement: Specify SAP Standard Archive Path .......................112ARCPRINTER Statement: Specify SAP Archive Target Printer .................113ARCPROTOCOL Statement: Specify SAP Archive Storage Connection Protocol ....................................................................................114ARCREPORT Statement: Specify SAP Archive Link Report Name ..........116ARCSERVICE Statement: Specify SAP Archive Link RPC Service/Destination ......................................................................................118ARCSTORAGE Statement: Specify SAP Archive Link Target Storage System .................................................................................120ARCTEXT Statement: Specify SAP Archive Link Text Information Field .........................................................................................122ARCUSER Statement: Specify SAP Archive Data Element for User .........124ARCVERSION Statement: Specify SAP Archive Version Number ............125ARGDEFAULTS Statement: Pass Default Arguments ................................127ARGS Statement: Pass Operands .................................................................129ARGS Statement (Oracle Applications): Pass Arguments ...........................131AS400_JOB Statement: Identify the Name of AS400 Jobs .........................133AS400FILE Statement: Identify OS/400 Source Files .................................134AS400LIB Statement: Specify Library Name ..............................................135AUX_AS Command: Start and Stop the Auxiliary Address Space .............136BANNER Statement: Include SAP Cover Page ...........................................138BANNERPAGE Statement: Include SAP Cover Page with Report .............139

v

BDC_JOB Statement: Start a Batch Input Session Job Definition (SAP) ....140BDCERRRATE Statement: Specify the Maximum Acceptable Error Rate (SAP) ..........................................................................................142BDCEXTLOG Statement: Generate Advanced Logging of the Batch Input Session (SAP) ..........................................................................143BDCPROCRATE Statement: Specify Minimum Acceptable Process Rate (SAP) ......................................................................................144BDCSYSTEM Statement: Specify Name of Background Server Processing the Batch Input Session (SAP) .......................................145BEAN Statement: Specify the JNDI Name of the Stateless Session Bean (J2EE) ......................................................................146BKUPEVS Command: Back Up Event Data Set .........................................147BKUPHIST Command: Back Up History Data Set .....................................148BKUPINDX Command: Back Up Index Data Base ....................................149BKUPJNDX Command: Back Up Job Index Data Base ..............................151BKUPUDEF Command: Back Up User Definition Data Set .......................153BREAK Command: Insert Breaks ................................................................155BWIP_JOB Statement: Start a Business Warehouse InfoPackage Job Definition (SAP) ..............................................................157BWPC_JOB Statement: Start a Business Warehouse Process Chain Job Definition (SAP) .........................................................................159CALENDAR Command: Specify Calendars ................................................161CCCHK Statement: Specify Job Processing Based on Condition Codes .....163CCEXIT Statement: Call Exit Program when Job Completes .....................169CCFAIL Statement: Identify Failures by Condition Code ...........................170CELLTRC Command: Trace Storage Cell Usage ........................................173CHAIN Statement: Identify Name of Business Warehouse Process Chain on SAP System .....................................................................176CHECKEXC Statement: Check for Exclusion Character ............................178CHILDMONITOR Statement: Enable Monitoring of Children Jobs (SAP) .....................................................................................181CHILDMONITOR Statement: Enable Monitoring of Children Jobs (Oracle Applications) .............................................................182CLASS Command: Manipulate Class Queues .............................................183CLEANUP Command: Delete Data Sets That Will Be Allocated by a Restarted Job ........................................................................186clearspool Command: Clear Agent Spool files .............................................187CLPNAME Statement: Identify OS/400 Programs to Run ..........................189CLRSYSMS Command: Clear System Messages ........................................190CMDNAME Statement: Run Agent-Platform Commands ..........................191CMDPRFX Command: Specify Command Prefix .......................................195

Contents

vi

COLUMNS Statement: Specify Line Width of List .....................................196COM Command: Insert Comments ..............................................................197COMMAND Statement: Run OS/400 Commands .......................................198CONNECT Command: Connect to Groups ..................................................199CONNECTION_FACTORY Statement: Specify JNDI Name of Connection Factory (J2EE) .....................................................................201CONSOLE Command: Set Console .............................................................202COPY Command: Copy Job History Records ..............................................204COPYJCL Statement: Generate Copy of JCL ..............................................206COREQ Statement: Specify Name of Co-Requisite .....................................209CPROC Command: Display and Delete Cache Entries ................................212CPU Command: Define CPUs ......................................................................214CPU Statement: Specify Conditions to Monitor CPU Use Within CPU_MON ......................................................................................218CPU_MON Statement: Monitor CPU Usage ...............................................221CRITERIA Command: Specify Reporting Criteria ......................................223CRITPATH Command: Enable Critical Path Analysis ................................226CRITPATH Statement: Enable Critical Path Analysis .................................228CRYPTKEY Command: Defines and Stores Encryption Key .....................230CURLIB Statement: Specify Current Library (OS/400) ..............................232cybAgent Command: Controlling Agents ....................................................233DAB Command: Display ABENDed Jobs ...................................................237DATA_OBJECT Statement: Set Data Repositories .....................................239DATASET Statement: Specify JCL Libraries ..............................................241DATEFORM Command: Set Date Format ..................................................243DB_JOB Statement: Identify the Name of Database Jobs ...........................245DEFAT Command: Define Authorization Table ..........................................247DEFAULT Command: Define Default Job Card Values .............................250DEFCAL Command: Define Calendars .......................................................251DEFGROUP Command: Define Groups ......................................................254DEFHOL Command: Define Holidays .........................................................257DEFPN Command: Define Pnodes ...............................................................260DEFPRINT Command: Define Logical Reports - DATASET Option ........263DEFPRINT Command: Define Logical Reports - SYSOUT Option ...........265DEFPRINT Command: Define Output to File .............................................267DEFPRIO Command: Assign Default Priorities ..........................................269DEFSIG Command: Define Signals .............................................................270DEFSPEC Command: Define Special Days .................................................272DEFSYML Command: Define Symbolic Variable Library .........................275DEFTJ Command: Define Tracking for Jobs ...............................................277DEFTM Command: Define Tracking Models ..............................................279

vii

DEFUSER Command: Define Users ............................................................283DELAT Command: Delete Authorization Tables ........................................287DELAYINT Command: Delay Intervals ......................................................288DELAYSUB Statement: Delay Submissions ...............................................289DELCAL Command: Delete Calendars .......................................................292DELETE Command: Delete Events (In Definition) .....................................293DELETE Command: Delete Events (General) .............................................294DELGROUP Command: Delete Groups ......................................................295DELHOL Command: Delete Holidays .........................................................296DELPN Command: Delete Pnodes ...............................................................298DELSIG Command: Delete Signals .............................................................299DELSPEC Command: Delete Special Days or Periods ................................300DELSYML Command: Delete Symbolic Variable Library .........................302DELTJ Command: Delete Tracked Job Definitions .....................................303DELTM Command: Delete Tracking Model Definitions .............................305DELUSER Command: Delete Users ............................................................306DEQUEUE Statement: Remove Resource Names from Enqueue List ........307DESCRIPTION Statement: Describe an Oracle Applications Single Request .........................................................................308DESELECT Statement: Deselect Jobs or SubApplications .........................310DEST Statement: Specify Output Destination File (J2EE) ..........................313DESTINATION Statement: Specify Destination File Within DB_JOB ......316DESTNAME Statement: Specify JNDI Name of the Topic/Queue .............318DFLTUSER Command: Define Default Users ............................................320DFPNODE Command: Set or Display Default Pnodes ................................322DIRECTION Statement: Specify Transfer Direction Within FTP_JOB ......324DISABLE_RESTART Statement: Disable Restart Feature (PeopleSoft) ....325DISCONN Command: Disconnect Users .....................................................326DISK Statement: Specify Conditions to Monitor Disk Within DISK_MON .....................................................................................327DISK_MON Statement: Monitor Disk Space ..............................................331DISPLAY Command: Display Reporting Fields ..........................................333DISTRFOLDER Statement: Set Distribution Folder (PeopleSoft) ..............335DISTRLISTROLES Statement: Specify Distribution List of Roles (PeopleSoft) ...................................................................................336DISTRLISTUSERS Statement: Specify Distribution List of Operator IDs (PeopleSoft) ...........................................................................338DJCDATA Statement: Introduce DJC ..........................................................340DJCNET Statement: Identify that Jobs are Controlled by DJC ....................345DN Command: Display Names ....................................................................347DO Statement: Identify Start of Set of Instructions ......................................350

Contents

viii

DOCLIB Statement: Identify Job Documentation Library ...........................352DQ Command: Display Pnode Queues ........................................................354DROPNOTW Statement: Remove Entries from NOTWITH List ...............356DSN Statement: Specify Target Data Source Name (DSN) Within DB_JOB ....................................................................357DSNAME Statement: Identify Data Sets for Data Set Triggers ...................359DSTRDLY Command: Delay Data Set Triggers .........................................368DSTREXCL Command: Exclude Data Set Triggers ....................................370DSTRIG Command: Define Data Set Triggers - Event Level .....................371DSTRIG Statement: Define Data-set Triggers - Job Level ..........................384DSTRST Command: Control Data Set Triggers ..........................................386DUEOUT Statement: Indicate Due Out Times ............................................388DURATION Statement: Specify Durations .................................................392EARLYSUB Statement: Specify Changed Job Submission Times ..............393ECHO Command: Echo Data .......................................................................396EICLASS Command: Control Event Initiator Classes .................................398EJB_JOB Statement: Start an EJB Job Definition (J2EE) ...........................401EJECT Command: Advance Output to New Page .......................................403ELSE Statement: Specify Alternate Actions ................................................404EMAILADDR Statement: Specify Email Addresses (PeopleSoft) ..............406EMAILADDR Statement: Email SAP Spool File Upon ABAP Completion/Failure ......................................................................................407EMAILLOG Statement: Email Job Logs (PeopleSoft) ................................408EMAILSUBJECT Statement: Include Email Subject (PeopleSoft) .............409EMAILTEXT Statement: Include Email Body Text (PeopleSoft) ...............410EMAILWEBREPORT Statement: Include Web Report (PeopleSoft) .........411ENCLOG Command: Display Additional Information About the Most Recent ESP Encore Request ...............................................412ENCPARM Command: List All ENCPARM Commands in Effect .............414ENCPARM ABENDER Command: Specify a Program That Abends on Behalf of Another Program ................................................415ENCPARM AUTOREST Command: Recover Data Sets Automatically For a Job Restart ............................................................416ENCPARM BACKOUT Command: Control Whether a Data Set is Backed Out Under ESP Encore ..........................................................421ENCPARM CLEANUP Command: Delete Data Sets That Will Be Allocated By a Restart Job ..............................................................423ENCPARM COMMENT Command: Insert a Comment in the ESP Encore Job Run Report ...................................................................425ENCPARM CONDCODE Command: Specify the Condition Codes That the ESP Encore Job Step Produces ...........................426

ix

ENCPARM DELETE Command: Undo an ENCPARM Command ............427ENCPARM DIAG Command: Produce All Diagnostic Sections of the ESP Encore Job Run Report ................................................429ENCPARM EXCLUDE Command: Specify a Step to Exclude From a Job Restart ..........................................................................430ENCPARM FORCE Command: Run a Job Even If ESP Encore Predicts Errors ..........................................................................432ENCPARM FROMSTEP Command: Specify a Step From Which a Job Is Restarted .....................................................................433ENCPARM GDGADJ Command: Specify How ESP Encore Processes Relative Generations For a Job Restart .........................................................434ENCPARM HONORCC Command: Control ESP Encore Condition Code Checks of Previous Job Runs ............................................437ENCPARM IGNOREDS Command: Specify Data Sets to Ignore on Job Restart ....................................................................................438ENCPARM JOBID Command: Specify the Job ID of the Job That Is Being Restarted by ESP Encore .......................................440ENCPARM JOBNAME Command: Specify a Job to Be Backed Out or Whose EXH Record Is to Be Dumped .................................441ENCPARM MODE Command: Specify How a Job Is Processed by ESP Encore .............................................................................442ENCPARM MODIFY Command: Modify the Internal Processing of ESP Encore ............................................................................444ENCPARM PREDICT Command: Specify the Error Types That ESP Encore Predicts .............................................................................446ENCPARM PREVTIME Command: Specify a Reader-On (RDRON) Time to Find a Job in the EXH Data Set ..................450ENCPARM PRINT Command: Select Sections of the ESP Encore Job Run Report to Print ............................................................452ENCPARM PURGE Command: Configure Automatic Purge of ESP Encore Job History Records .............................................................454ENCPARM QUIESCE Command: Quiesce ESP Encore ............................458ENCPARM RESTART Command: Restart ESP Encore .............................459ENCPARM STATUS Command: List the Status of ESP Encore ................461ENCPARM SUBSYS Command: Specify the Subsystem Identifier for a Job Processed by ESP Encore .............................................462ENCPARM TAPESCR Command: Request a Tape Scratch From a TMS .................................................................................................466ENCPARM TOSTEP Command: Specify a Step To Which a Job Runs When It Is Restarted ...................................................................470ENCPARM TRACE Command: Specify Modules to Be Traced ................471

Contents

x

ENCPARM TYPE Command: Specify the Type of Processing That ESP Encore Does ..................................................................................................472ENCPARM VOLUME Command: Specify Data Set Processing Based on Volume Serial ..............................................................................474ENCPARM WARNING Command: Display Extra Warning Messages to Support Manual Restart Tasks ................................................476ENCREQ Command: List or Unlock Access-Serialization Locks ...............478ENCRYPT Command: Enable Encrypted Communications ........................484ENCTRACE Command: Trace ESP Encore Programs ................................487END Command: End ESP Sessions .............................................................489ENDDEF Command: End Event Definitions ...............................................490ENDDO Statement: Identify End of Action Statements ..............................491%ENDEXCL Statement: End Exclusion of JCL ..........................................493ENDHC Command: End Output Data ..........................................................494%ENDINCL Statement: End Inclusion of JCL ............................................495ENDJOB Statement: End Job Definitions ....................................................496ENDMODEL Command: End Model Definitions .......................................498ENDPRINT Command: Close Report Data Files .........................................499ENDPROC Command: Terminate an ESP Procedure ..................................500ENDR Command: End History Report Definitions .....................................501ENDTEMPL Statement: End Template Definitions ....................................502ENQSELF Command: Specify Jobs Enqueue on Themselves .....................503ENQUEUE Command: Display Enqueue Status ..........................................505ENQUEUE Statement: Specify Resources to Enqueue ................................507ENVAR Statement: Pass Environment Variables ........................................509ESP Statement: Issue ESP Commands .........................................................513ESPCOM Command: Control ESP Communications ..................................515ESPCTR Command: Control ESP Counters ................................................518ESPmgr Command: Send Messages to ESP Manager (Recommended) ...........................................................................................520ESPmsg Command: Send Messages to ESP Manager .................................528ESPNOMSG Statement: Suppress Responses ..............................................536//*ESPSYMBOL Statement: Change Symbol Introducer ............................538EVENT Command: Start Event Definition ..................................................540EVENT Statement: Specify the SAP Event to Monitor or Trigger ..............545EVENTCATEGORY Statement: Specify Windows Event Category Within EVENTLOG_MON .........................................................547EVENTCOMPUTER Statement: Specify Local Machine for Windows Event Log Within EVENTLOG_MON .......................................548EVENTDESCRIPTION Statement: Specify Windows Event Description Within EVENTLOG_MON .....................................................549

xi

EVENTID Statement: Specify Windows Event ID Within EVENTLOG_MON .........................................................................551EVENTLOG_MON Statement: Monitor the Windows Event Log ..............552EVENTOPT Command: Allow Write to Operator .......................................554EVENTSET Command: Define Event Data Set ...........................................556EVENTSOURCE Statement: Specify Windows Event Source Within EVENTLOG_MON .........................................................................559EVENTTYPE Statement: Specify Windows Event Type Within EVENTLOG_MON .........................................................................560%EXCLUDE Statement: Request Exclusion of JCL ...................................562EXIT Command: Establish User Exits .........................................................566EXIT Statement: Quit ESP Procedures ........................................................568EXITCODE Statement: Identify Failures by Exit Code ...............................571EXPECT Command: Expect Events to Execute ...........................................572EXPEDITE Command: Define or Alter Expedite Policy .............................574EXPEDITE Statement: Associate ESP Expedite Policy ..............................580EXPIRATION Statement: Specify Expiration of SAP Spool Request ........582EXTMON Statement: Monitors a Workload Object on an External Scheduler .............................................................................583EXTSCHEDULER Statement: Name of External Scheduler .......................585FAILUREMSG Statement: Specify Failure Message for ABAP (SAP) ......586FILE_TRIGGER Statement: Define File Triggers .......................................587FILENAME Statement: Specify Files Monitored by FILE_TRIGGER ......588FILTER Statement: Specify Filter for JMS Subscribe Jobs (J2EE) .............606FLAGUNDEF Statement: Find Reference to Undefined Symbols ..............608FLOW Command: Identify Flow Chart ........................................................610FLOWDOC Command: Generate Reports ...................................................612FOOTING Command: Print Footing Line ....................................................615FROM Command: Start Reporting From .....................................................618//* FROM Statement: Identify Initial Date for Temporary JCL ...................620FTP Command: Select SMF Record ............................................................622FTP_JOB Statement: Identify the Name of FTP Jobs ..................................623FTPFORMAT Statement: Specify FTP Format Within FTP_JOB ..............625GENDOC Command: Generate Job Documentation ...................................627GENFLOW Command: Generate Flow Charts ............................................630GENPROJ Command: Generate Projects .....................................................632GENTIME Command: Generate Times .......................................................635GO Command: Indicate Completion ............................................................639GROUP Command: Switch Groups Access .................................................640HARDCOPY Command: Divert Output to Data Set ....................................642HARDCOPY Command: Divert Output to DD File ....................................644

Contents

xii

HARDCOPY Command: Divert Output to Sysout Class .............................646HISTFILE Command: Include History Files in Report ................................648HISTFILE Command: Define or Alter History File .....................................650HOLD Command: Hold Events ....................................................................652HOLD Command: Hold Events at Specific Time ........................................654HPUX_JOB Statement: Identify the Name of HPUX Jobs ..........................656IF Statement: Process Instructions Conditionally .........................................657%INCLUDE Statement: Request Inclusion of JCL ......................................659INET Command: Manipulate TCP/IP Attributes .........................................663INFOCOMM Command: Control InfoServ Transaction Servers .................667INFOMSG Command: Display Messages in Screen Body ..........................669INFOPACK Statement: Identify Name of Business Warehouse InfoPackage on SAP System ....................................................671INIT Command: Manipulate Initiators .........................................................672INITIAL_CONTEXT Statement: Specify Initial Context Factory (J2EE) ..674INPUT Command: Request Input from Data Sets ........................................676INPUTDS Statement: Extract Tape Information ..........................................678INTEGER Statement: Define Integer Variables ...........................................680INVOKE Command: Invoke ESP Procedures ..............................................682IP_MON Statement: Monitor IP Addresses or Ports ....................................684IPADDRESS Statement: Specify IP Address for IP_Monitor Within IP_MON .......................................................................685IPPORT Statement: Specify IP Port for IP_Monitor Within IP_MON ........686JCLLIB Statement: Identify JCL Library .....................................................687JESCOMCH Command: Specify Command Prefixes ..................................690JESTYPE Command: Specify JES Type ......................................................691JMSP_JOB Statement: Start a JMS Publish Job Definition (J2EE) .............692JMSS_JOB Statement: Start a JMS Subscribe Job Definition (J2EE) .........694JNDIUSER Statement: Specify JNDI User ID (J2EE) .................................696JOB Statement: Identify the Name of Jobs ...................................................697JOBATTR Statement: Change Job Attributes ..............................................708JOBCLASS Statement: Assign Job Class to a Job .......................................711JOBCOPY Statement: Copy an Existing SAP Job .......................................713JOBD Statement: Specify Jobs Description (OS/400) .................................714JOBENQ Command: Manipulate Enqueue List ...........................................715JOBINFO Command: Display Job Documentation ......................................716JOBMAP Command: List Job Mapping Information ...................................720JOBNAME Statement: Specify Jobs Name (OS/400) ..................................724JOBQ Statement: Specify Job Queues (OS/400) ..........................................725JOBRES Command: Set Job Resources .......................................................726JOBTREE Command: Produce Job Descendant Tree ..................................727

xiii

JTPEXCL Command: Exclude Programs from Status .................................729JUMPTO Statement: Jump to Next Label ....................................................731LABEL Command: Label Documentation Library ......................................734LANGUAGE Statement: Specify Language for ABAP (SAP) ....................737LATESUB Statement: Specify Late Submission .........................................738LAX Command: List External Jobs ..............................................................741LCMDPRFX Command: List Commands Prefixing ....................................743LDSN Command: List Data Sets ..................................................................744LDSTCELL Command: List Data-Set-Trigger Cells ...................................745LDTE Command: List Data Set Triggers .....................................................746LDTREL Command: List Data Set Trigger Excludes ..................................747LDXE Command: List Objects Awaiting Triggers ......................................748LIBL Statement: Specify Library Name (OS/400) .......................................749LIBSUB Command: Submit JCL from Librarian Data Set ..........................751LINES Statement: Specify Number of Lines per List Page (SAP) ..............753LINUX_JOB Statement: Identify the Name of LINUX Jobs .......................754LIST Command: List Event Information ......................................................755LISTAPPL Command: List Applications .....................................................758LISTAPTF Command: List Application File ...............................................763LISTAT Command: List Authorization Tables ............................................764LISTCAL Command: List Calendars ...........................................................766LISTCKPT Command: List Checkpoints .....................................................768LISTEVS Command: List Event Data Sets ..................................................769LISTGRP Command: List Groups ...............................................................771LISTHIST Command: List History Files .....................................................773LISTHOL Command: List Holidays ............................................................774LISTJTML Command: List Tracking Models ..............................................776LISTPN Command: List Pnodes ..................................................................777LISTQ Command: List Queue Data Set .......................................................778LISTROOT Command: Save List of Waiting Jobs for Rerun into Data Set .................................................................................................779LISTSADL Command: List SADLINKs .....................................................781LISTSCH Command: List Schedules ...........................................................782LISTSIG Command: List Signals .................................................................785LISTSPEC Command: List Special Days ....................................................787LISTSYML Command: List Symbol Libraries ............................................790LISTTRAK Command: List Tracking Files .................................................792LISTUSER Command: List User Definitions ..............................................793LISTXMEZ Command: List Cross-Memory Elements ................................795LJ Command: List Jobs ................................................................................796LMOD Command: Display Module Level ...................................................799

Contents

xiv

LOAD Command: Load Commands ............................................................800LOADAGDF Command: Load Agent Definition ........................................802LOADJTDT Command: Load Job Tracking Definition Table ....................803LOADNL Command: Load MAILLIST Data Set ........................................805LOADSCHF Command: Load Schedule File ..............................................806LOADUPDT Command: Load User Profile Definition Table .....................807LOCALFILENAME Statement: Specify Local Filenames Within FTP_JOB .........................................................................................808LOCATION Statement: Specify the Service Provider URL (J2EE) ............810LOGPRT Command: Display Event Log .....................................................812LSAR Command: List Scheduled Activity Report .......................................813LSYS Command: List System ......................................................................817LSYSMSGS Command: List System Messages ..........................................819LTCELL Command: List Tracking Cells .....................................................820LTJ Command: List Tracked Jobs ................................................................821LTM Command: List Tracking Models ........................................................823LTZONE Command: List Time Zones .........................................................824MAILBOX Command: List Mailboxes ........................................................825MANAGER Command: Describe the ESP Workload Manager Subsystem Controlling the ESP Agents .......................................................826MAPGEN Command: Create Job Mapping Data Sets .................................828MAPUSER Command: Map User IDs to SAF .............................................830MAXCXME Command: Set Maximum Space – Checkpoint file ................831MAXINITS Command: Define Maximum Initiators ...................................832MAXQXME Command: Set Maximum Space – Queue file .......................834MCS Command: Control MCS Extended Console ......................................835MEMBER Statement: Specify Members Name ...........................................836METHOD Statement: Specify EJB Method to be Invoked Remotely .........838MGRADDR Command: Specify Manager’s Address ..................................839MGRMSG Command: Send Messages to Manager .....................................841MODEL Command: Start Model Process ....................................................852MODEL Statement: Specify Tracking Models ............................................855MONITOR Statement: Identify Prefix of Job Monitor ................................856MONITORDELAY Statement: Delay Monitoring Children for Oracle Applications Programs ..................................................................................858MREPORT Command: Select Model Reports .............................................860MSG Command: Set Messages ....................................................................865MSGCLASS Statement: Specify the Java Class of the JMS Message (J2EE) ....................................................................................867MSGLIMIT Statement: Limit Console Message Number ...........................869MSGQLEN Statement: Limit Number of Messages ....................................870

xv

MSGTYPE Command: Set Messages from Type ........................................871NCR_JOB Statement: Identify the Name of NCR Jobs ...............................874NETAUTH Command: Control Authorization Profiles ...............................875NETDEST Command: NDS Destination Profile ..........................................876NETWORK Command: Control NDS .........................................................882NEXT Command: Display Next Execution of Events .................................891NJETOL Command: Set NJE tolerance .......................................................893NOCHECKEXC Statement: Do not Check Last Not Blank Character ........894NODE Command: Define System Nodes .....................................................895NORUN Statement: Do not Select Jobs .......................................................898NOSCHED Command: Do Not Schedule Events ........................................901NOTIFY Statement: Notify Users or Consoles ............................................903NOTWITH Statement: Specify Mutually Exclusive Jobs ............................909NT_JOB Statement: Identify the Name of Windows Jobs ...........................912NTRCLASS Command: No Track Class .....................................................913NULLPSWD Command: Specify Password ................................................914OA_JOB Statement: Start an Oracle Applications Job Definition ...............915OAUSER Statement: Identify an Oracle Applications User Name ..............917ON Command: Specify Actions Based on Type of Day ..............................918OPENVMS_JOB Statement: Identify the Name of OPENVMS Jobs .........921OPTIONS Statement: Override Default Options ..........................................922OTHERS Statement: Specify Additional Parameters (OS/400) ...................926OUTDESTFORMAT Statement: Specify Output Destination Format (PeopleSoft) .....................................................................................927OUTDESTPATH Statement: Specify Path of Output (PeopleSoft) .............929OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft) .....................................................................................931PANSUB Command: Submit JCL From Panvalet .......................................933PARAM Statement: Specify Additional Parameters (OS/400) ....................935PARAM Statement: Define InfoPackage Data Selection Criteria (SAP) .....936PARAMETER Statement: Specify the Method/MessageParameters (J2EE) .........................................................................................938PASSWORD Command: Define Agent User IDs and Passwords ...............940PASSWORD Statement: Specify Passwords ...............................................942PCACHE Command: Use Procedure Caching .............................................943PNODES Statement: Specify User-Defined Pnodes ....................................944POST Command: Post Job Complete ...........................................................947POSTREQ Statement: Specify Jobs to Run After ........................................949PREALLOC Command: Pre-allocate Data Sets ...........................................953PREREQ Statement: Specify Jobs to Run Before ........................................955PRINTCOPIES Statement (SAP): Specify Number of

Contents

xvi

Copies for SAP Report .................................................................................959PRINTCOPIES Statement (Oracle Applications): SpecifyNumber of Copies .........................................................................................960PRINTCOVER Statement: Specify SAP Cover Page Text ..........................962PRINTDATASET Statement: Specify Data Set Name for SAP Print Spool ...........................................................................................963PRINTDEPARTMENT Statement: Specify Department Name (SAP) .......964PRINTDEST Statement: Specify Print Destination (SAP) ..........................965PRINTER Statement: Specify Printer ...........................................................966PRINTFOOTER Statement: Print Footer on SAP Report ............................968PRINTFORMAT Statement: Specify Output Format for SAP Report ........969PRINTHOSTPAGE Statement: Print Host Page (SAP) ...............................970PRINTIMMED Statement: Specify Immediate Print After Job Completion (SAP) ........................................................................................971PRINTNEWSPOOL Statement: Create New Spool Request (SAP) ............972PRINTPRIORITY Statement: Specify the Priority of the SAP Spool Request ..............................................................................................973PRINTPW Statement: Specify SAP Authorization String for Viewing Print Spool List .............................................................................975PRINTREL Statement: Specify Deletion of Spool Request (SAP) ..............976PRINTREQTYPE Statement: Specify Print Request Type (SAP) ...............977PRINTSPOOLNAME Statement: Specify Name of SAP Print Spool .........978PRINTSTYLE Statement: Specify Print Style .............................................979PRIORITY Statement: Specify Relative Priorities .......................................981PROC Command: Introduce an ESP Procedure ...........................................983PROCESS Statement: Specify Process Within PROCESS_MON ...............984PROCESS_MON Statement: Monitor Process Execution ...........................986PROCESSMONITOR Statement: Specify the SAP Process Status to Monitor .........................................................................................988PROCESSNAME Statement: Specify PeopleSoft Report to Run Within PS_JOB ....................................................................................990PROCESSTYPE Statement: Specify PeopleSoft Report Type Within PS_JOB ............................................................................................991PROGARGS Statement: Pass Arguments ....................................................992PROGDATA Statement: Identify an Oracle Program ..................................994PROGPRINTCOPIES Statement: Specify Number of Copies .....................996PROGPRINTER Statement: Specify Printer ................................................998PROGPRINTSTYLE Statement: Specify Print Style ................................1000PROGRAM Statement: Identify an Oracle Applications Single Request Program .......................................................................................................1002PROGSAVEOUTPUT Statement: Save Output .........................................1003

xvii

PS_JOB Statement: Identify the Name of PeopleSoft Jobs ........................1005PSOPRID Statement: Specify Operator ID (PeopleSoft) ...........................1007PURGSCHF Command: Purge Schedule Information ...............................1008PUTINOUTBOX Statement: Save Outgoing Documents to SAPoffice Outbox ......................................................................................1010QUERY Statement: Specify SQL Statement Within DB_JOB ..................1011QUIESCE Command: Put ESP in a Quiesced State ...................................1013QUIT Statement: Quit Procedures ..............................................................1014QUPDATE Command: Force JES Status and Pnode Queue Information ..1016RACROUTE Command: Specify Events Processing .................................1017RANGE Statement: Specify Search Range Within TEXT_MON ..............1020RECIPIENT Statement: Specify Recipient Name for SAP Cover Page ....1024RECIPIENTBCC Statement: Blind Carbon Copy the SAP Spool .............1025RECIPIENTCC Statement: Carbon Copy the SAP Spool ..........................1026RECIPIENTEXPRESS Statement: Send SAP Spool Using Express Delivery ........................................................................................1027RECIPIENTFORWARD Statement: Allows Forwarding of SAP Spool ...1028RECIPIENTPRINT Statement: Allow Printing of SAP Spool ..................1029RECIPIENTTYPE Statement: Specify Recipient Type for SAP Spool .....1030REEXEC Statement: Re-Execute Procedures ............................................1031RELCOUNT Statement: Specify Hold Counts ..........................................1034RELDELAY Statement: Delay Jobs Submission .......................................1036RELEASE Command - Event Level: Decrement Hold Counts .................1038RELEASE Command - General: Decrement Hold Counts ........................1040RELEASE Statement: Identify Successors .................................................1041REMOTEFILENAME Statement: Specify Remote Filename Within FTP_JOB .......................................................................................1044REMOVE Command: Identify Lines to be Removed ................................1047REPORT Command: Begin Report Definition ..........................................1049REQUESTSET Statement: Identify an Oracle Applications Request Set ..1050RERUNM Command: Rerun Multiple Jobs ...............................................1051RESDEF Command: Define Resources .....................................................1055RESDFLT Command: Identify Default Resources ....................................1064RESOLVE Statement: Resolve External Job Dependencies ......................1068RESOURCE Statement: Identify Resources ..............................................1070RESPNAME Statement: Identify an Oracle ApplicationsResponsibility Name ...................................................................................1075RESREFR Command: Refresh Devices List ..............................................1076RESTART Command: Restart Events Scheduling/ApplicationProcessing ...................................................................................................1077RESTORE Command: Restore ESP Data Sets ...........................................1078

Contents

xviii

RESUME Command - Event Level: Decrement Suspend Counts .............1080RESUME Command - General: Decrement Suspend Counts ....................1082REXXOFF Statement: Turn Off REXX Processing ...................................1083REXXON Statement: Turn On REXX Processing .....................................1084RFCDEST Statement: Specify SAP Destination ........................................1087ROSSUB Command: Submit JCL ..............................................................1088ROUTE Statement: Insert Route Statements ..............................................1089ROUTING Command: Route Proxies Subsystem Requests ......................1091RUN Statement: Identify Schedule Frequency ...........................................1093RUNCONTROLID Statement: Identify PeopleSoft Run Parameters ........1100SADGEN Command: Create Data Set for Reports ....................................1102SADLINK Command: Assign Scheduled Activity Data Sets ....................1106SADLOAD Command: Refresh Tables .....................................................1108SADUPD Command: Update Scheduled Activities ...................................1110SAFOPTS Command: Control Processing Options ...................................1111SAP_JOB Statement: Start an SAP Job Definition ....................................1114SAPA_JOB Statement: Start an SAP Data Archiving Job Definition ........1116SAPCLIENT Statement: Specify SAP Client ............................................1118SAPE_JOB Statement: Start an SAP Event Monitor Job Definition .........1119SAPEMAILADDR Statement: Email SAP Spool File Upon Job Completion/Failure ....................................................................................1121SAPFAILUREMSG Statement: Specify Failure Message for SAP Job ....1122SAPJOBCLASS Statement: Specify SAP Job Class ..................................1123SAPJOBNAME Statement: Specify SAP Job Name .................................1124SAPLANGUAGE Statement: Specify SAP Language for Login ..............1126SAPM_JOB Statement: Start an SAP Process Monitor Job Definition .....1127SAPSUCCESSMSG Statement: Specify Success Message for SAP Job ...1129SAPTARGETSYSTEM Statement: Specify SAP Application Server .......1130SAPUSER Statement: Specify RFC Logon for SAP System User ............1131SAVEOUTPUT Statement: Save Output ...................................................1133SCAN Command: Scan JCL Data Set ........................................................1134SCHEDULE Command: Define Schedules ................................................1138SCRIPTNAME Statement: Specify UNIX Shell Script to Run .................1141SEARCHRANGE Statement: Specify Search Range WithinTEXT_MON ...............................................................................................1144SECURE Statement: Secure Symbols ........................................................1148SELECT Statement: Select Jobs or SubApplications .................................1149SEND Command: Send Messages ..............................................................1153SEQUENT_JOB Statement: Identify the Name of Sequent Jobs ...............1156SERVERADDR Statement: Specify FTP Server Name Within FTP_JOB ...................................................................................................1157

xix

SERVERPORT Statement: Specify FTP Server Port Number Within FTP_JOB .......................................................................................1159SERVICE_MON Statement: Monitor Windows Services .........................1161SERVICENAME Statement: Specify Windows Service Name Within SERVICE_MON ...........................................................................1162SET Command: Set Environment Variables ..............................................1163SETPRINT Command: Set Default Output ................................................1164SETVAR Command: Define Variables ......................................................1165SETWIDTH Command: Set Output Width ................................................1166SHADGOAL Command: Instruct Shadow Manager .................................1167SHADOW Command: Control and Display Shadow Manager ..................1169SHELL Statement: Specify UNIX Shell to Run Script ..............................1171SIGCYCLE Command: Cycle Signals .......................................................1173SIGPOST Command: Post Complete Signal Generations .........................1175SIGWAIT Command: Identify Signal Conditions .....................................1177SIMULATE Command: Simulate Event Functions ...................................1179SKIPPARMUPDATES Statement: Control Updates to Job Parameters (PeopleSoft) ............................................................................1187SMFSTATS Command: Display SMF Status ............................................1189SNDESPMSG Command: Send Messages to ESP Manager .....................1190SORT Command: Specify Ascending/Descending Sort Sequence ............1191SPACE Command: Space Output ...............................................................1193SPINLOG Command: Spin Audit Log .......................................................1194SPOOLRECIPIENT Statement: Specify SAP Spool Recipient .................1195SPUSER Command: Identify Initial Users .................................................1197SQL Statement: Specify SQL Statement Within DB_JOB ........................1198STARTMODE Statement: Specify Startmode for Readied Job (SAP) ......1200STATINTV Statement: Set Status Check Interval .....................................1201STATUS Command: Display Processing Status ........................................1202STATUS Statement: Specify Status of Process (PROCESS_MON), Service (SERVICE_MON), or IP Address and Port (IP_MON) ............................................................1203STEPEND Statement: Release Resources at End of Step ..........................1206STEPUSER Statement: Specify User for ABAP Program (SAP) ..............1208subAgent Command: Start in Debug Mode ................................................1209SUBAPPL Statement: Identify SubApplications .......................................1210SUBMIT Command: Submit JCL Into Internal Reader .............................1215SUCCESSMSG Statement: Specify Success Message for ABAP(SAP) ...1217SUN_JOB Statement: Identify the Name of SUN Jobs ..............................1218SUSPEND Command - Event Level: Suspend Events ...............................1219SUSPEND Command - General: Suspend Events .....................................1221

Contents

xx

SYMLIB Command: Request Inclusions ...................................................1222SYSMSGS Command: Intercept Messages ................................................1224TAG Statement: Tag Jobs ...........................................................................1228TANDEM_JOB Statement: Identify the Name of Tandem Jobs ...............1230TAPETRAK Command: Tape usage count control ...................................1231TEMPLATE Statement: Set Templates ......................................................1234TEMPLIB Statement: Identify Temporary JCL Library ............................1238TEST Command: Test Schedule Criteria ...................................................1240TEXT_MON Statement: Monitor Content of Text File .............................1242TEXTFILE Statement: Specify Text File Name and Location for Text Search Within TEXT_MON ..............................................................1244TEXTSTRING Statement: Specify Text String to Search for Within TEXT_MON ..................................................................................1246THEN Statement: Specify Actions .............................................................1249TIME Command: Set Start Time ................................................................1251TIMEFORMAT Statement: Specify Time Format for Searching Log File Within TEXT_MON ...................................................................1252TIMEZONE Statement: Specify Time Zone (PeopleSoft) .........................1255TITLE Command: Define Titles .................................................................1256TOPIC Statement: Publish/Subscribe to a Topic/Queue (J2EE) ................1259TPAPPL Command: Interaction with Remote Partner Application ...........1261TPDISP Command: Display System Status ...............................................1263TPRETRY Command: Interval to Retry Contacting an LU .......................1264TPSTART Command: Reopen VTAM ACB .............................................1265TPTERM Command: Terminate Communication ......................................1266TPTIME Command: I/O Timeout ..............................................................1267TPTRAN Command: Issue Control Commands ........................................1268TRACE Command: Activate Trace Facility ...............................................1269TRACEDEF Command: Identify Data Sets ...............................................1271TRACEPRT Command: Print Trace Data ..................................................1273TRACKDEF Command: Specify Tracking Definitions .............................1275TRACKING Command: Enable/Disable ESP Tracking Facility ...............1280TRACKOPT Command: Set Various Tracking Options ............................1282TRANSFERCODETYPE Statement: Specify FTP Format Within FTP_JOB ...................................................................................................1285TRANSFERDIRECTION Statement: Specify Transfer Direction Within FTP_JOB .......................................................................................1288TRDFLT Command: Specify Installation Default .....................................1289TRIGGER Command: Trigger Events Execution ......................................1290TRYJOIN Command: Join XCF Groups ....................................................1294

xxi

UNALLOC Command: Unallocate Data Sets ............................................1295UNIX_JOB Statement: Identify the Name of UNIX Jobs ..........................1296//* UNTIL Statement: Specify Limit Date for TEMPLIB ..........................1297USE Command: Display Event Statistics ...................................................1299USER Command: Identify Users as Valid ESP User .................................1301USER Statement: Define User IDs .............................................................1302USERMOD Command: Define User Modifications ..................................1305VARIANT Statement: Specify Variant Name (SAP) .................................1307VDEL Command: Delete Global Variables ...............................................1308VGET Command: Retrieve Global Variables ............................................1309VINCR Command: Increment Numeric Global Variables .........................1311VPUT Command: Store Global Variables ..................................................1312VS Command: Issue Commands to the Operating System ........................1313VSET Command: Set Global Variables .....................................................1316VTDEFINE Command: Define Global Variable Tables ............................1317VTDELETE Command: Delete Global Variable Tables ...........................1318VTLIST Command: List Global Variable Tables ......................................1319VTRDEF Command: Define Global Variable Triggers .............................1321VTRDEL Command: Delete Global Variable Triggers .............................1323WEBPOSTING Statement: Post SAP Job Log and Spool on Web ............1324WILDCARD Command: Define Wildcards for JTDT ...............................1325WLM Command: Display Service Policies ................................................1327WOBCMD Command: Run Job-specific Commands ................................1329WOBDATA Statement: Retrieve Data From Data Object .........................1331WOBDEF Command: Define Workload Objects .......................................1332WORKMGR Command: Define Enclave support ......................................1334XCF DELETE Command: Remove Members ...........................................1336XCF DISPLAY Command: View XCF Attributes .....................................1338XCF FORCE Command: Terminate Active Members ...............................1342XCF HELP Command: List XCF Commands ............................................1344XCF PURGE Command: Terminate and Restart XCF Services ................1346XCF SET MEMBER Command: Instruct Shadow Manager .....................1348XCF SET SERVICE Command: Specify Fixed Intervals ..........................1349XCF SET TERMOPT Command: Preset Groups Termination ..................1350XCF SET TRACE Command: Define Sysout Classes ...............................1352XCF SPIN TRACE Command: Spool Trace Data .....................................1353XCF START SERVICE Command: Restart XCF Services .......................1354XCF START TRACE Command: Initialize/Activate Trace Files .............1355XCF STOP GROUP Command: Stop All XCF Group Members ..............1356XCF STOP MEMBER Command: Stop XCF Members ............................1357XCF STOP SERVICE Command: Stop XCF Services ..............................1358

Contents

xxii

XCF STOP TRACE Command: Stop Trace File .......................................1359XCF VERIFY Command: Verify Two XCF Members ..............................1360XMITMDL Command: Identify Tracking Models to Transmit .................1361

Index ............................................................................................................... 1363

1

Overview

This manualThe ESP Workload Manager Reference Guide contains all the commands and statements available to ESP Workload Manager users. Use it as a reference for when you want a complete description of the commands or statements, and all valid keywords and operands. Use the examples to see how each command and statement can be used.If you know the command you want to use, and are familiar with its options, but simply want to see the syntax, use the ESP Workload Manager Quick Reference.

Entering commandsESP commands may be entered in Line mode, Page mode, batch, loaded from a data set (using the LOAD command), or ESP Workstation. Many can also be entered from a system console.ESP statements must be entered in a data set specific to the type of statement used.Consult the ESP Workload Manager User’s Guide for more background information on any commands or statements in this Reference Guide.

Entering statementsNote: The content of this section also applies to commands and initialization parameters when contained in a data set.

ContinuationType either a hyphen or a plus sign as the last non-blank character on a line to continue a line of input. The hyphen attaches the next line including any leading blank position. The plus sign strips leading blanks from a continuation line. Blanks preceding the hyphen or the plus sign are retained. Statements cannot extend beyond column 72. The continuation character can be placed in columns 72 or before.Note: A hyphen can also be used as a wildcard character. If the wildcard hyphen is the last character on the line, it will be interpreted as a continuation character and not as a wildcard. For the hyphen to be interpreted as a wildcard, it must be followed by a semicolon or something else on the line such as a comment: (/* */).

Overview

2

Wildcards and maskingMany statements, commands, or initialization parameters permit the use of the following wildcard characters (also called masking.):• An asterisk matches a specific single character.• An hyphen matches zero or more characters. It must be used as the last character

of the operand. If the wildcard hyphen is the last character on the line, it will be interpreted as a continuation character and not as a wildcard. For the hyphen to be interpreted as a wildcard, it must be followed by a semicolon or something else on the line such as a comment: (/* */).

CommentsEnclose comments between /* and */. Comments can be written anywhere in an ESP Workload Manager Procedure.

Data setsCybermation recommends that you enclose all data-set names in single quote marks. Although this is not required, it will preserve your intentions across all environments. For example, in a TSO environment a user's TSO ID will be added as a prefix if the TSO PREFIXING option is active and single quote marks have not been used. Use LIB- or PAN- prefixes to identify Librarian and Panvalet data sets.

DelimitersUse single quotation marks when you want to denote character strings and literal data in expressions, in assignment statements, and in built-in functions. You must include single quotation marks around a string that contains blanks.

IndentationYou can use indentation to improve readability.

ExamplesIssuing console commandsTo issue a command from the system console, use the MODIFY command, as in F ESP, where ESP is the started task name. For example:F ESP, STATUS

Issuing OPER commandsTo issue a command that requires OPER authority, precede it with OPER. For example: OPER STATUS

3

Issuing commands in batchTo issue a command in batch, use the following JCL after your job card://EXEC PGM=ESP,REGION=4000K//SYSPRINT DD SYSOUT=*//SYSIN DD *ESP command...ESP command

Subsystem nameIf the subsystem name for ESP is not ESP, you need to type the subsystem name when entering a command in batch. For example, if the subsystem name is ESPA, type://EXEC PGM=ESP,PARM='SUBSYS(ESPA)',REGION=4000K

SteplibIf the TSO command processor is not in a LINKLIST library, you need a STEPLIB or JOBLIB statement in your JCL. Your statement may look like://STEPLIB DD DSN=CYB.ESP.LOAD,DISP=SHR

Wildcards and maskingMany of the commands permit the use of wildcard characters also called masking. Use the asterisk as a wildcard to match any single character. Use a hyphen to match zero or more characters.For example, to display all calendars:LISTCAL –

To display all calendars with names containing XY in character positions three and four:LISTCAL **XY-

To display all calendars with two-character names:LISTCAL **

Term definitions

4

Term definitions

This section defines basic terminology in the context of ESP Workload Manager.

ApplicationA group of workload objects that is generated from a procedure when an Event is triggered and that runs under the control of ESP Workload Manager. Applications include the scheduling relationship between workload objects.

CommandA request made to ESP Workload Manager. The most frequent types of commands are:• General commands—issued without general restrictions• OPER commands—must be preceded by the word OPER• Authorized commands—can be issued by users authorized in the security system• Authorized OPER commands—can be issued by users authorized in the security

system and must be preceded by the word OPERCommands and statements are listed alphabetically in the ESP Workload Manager Reference Guide.

EventAn anticipated scheduling milestone. Events include the conditions under which they are triggered and the commands to be performed when they are triggered. Events are used to determine the conditions under which workload objects are scheduled.

Initialization parameterA request made to ESP Workload Manager at initialization time. Initialization parameters are listed alphabetically in ESP Workload Manager Installation and Configuration Guide.

OperandA parameter of a statement, command, or initialization parameter.

5

ProcedureA source list of statements and commands entered by users. Procedures are read sequentially when an Event is triggered. Procedures containing the APPL statement are used by ESP Workload Manager to generate Applications. Procedures are used to specify how the workload is scheduled.

StatementAn item of information about a workload object given to ESP Workload Manager. Statements are always included in procedures.Commands and statements are listed alphabetically in the ESP Workload Manager Reference Guide.

Workload objectA unit of work that runs under the control of ESP Workload Manager. Workload objects represent the work to be scheduled.

Conventions used in the Guide

6

Conventions used in the Guide

InputESP Workload Manager is not case sensitive. Even though we show commands in uppercase, when you type a command on the command line, you do not need to type the command in uppercase letters.

Syntax conventionsThe syntax diagrams in this guide use the following conventions:

Notation MeaningQuote marks '' or ' Must be entered as shown.Comma , Must be entered as shown.Ellipsis … The operand can be repeated. Do not enter ellipsis.Lower Case Italics operand

An operand must be substituted. User supplied variable or character string.

Uppercase operand The operand must be spelled as shown. You can enter the command and the operand in either upper or lower case.

OR-bar ( | ) Indicates an exclusive value on left or right of bar. You must enter one of the items. You cannot enter more than one.

Underline _______ If you do not enter one of the operands, the system supplies the underlined operand, this is the default

Parentheses ( ) and special characters

Operand enclosed in parentheses is mandatory and must be entered as shown.

Single operand in square brackets [ ]

Optional operand; do not type the brackets.

Stacked operands in braces { } { }

Mandatory; you must enter one of the operands. You cannot enter more than one.

Stacked operands in square brackets [ ] [ ]

Optional operand; you can enter one value, or none.

Operands with OR-bars ( | ) and square brackets [ ]|[ ]

Optional, mutually exclusive operands. Enter one or none.

7

If an operand has complex syntax, it will be followed by “See expanded syntax”. Expanded syntax is documented in a separate table after the main syntax table.

Stacked operands in square brackets within braces {[ ]}

Mandatory; you must enter one of these operands. You can enter more than one.

Notation Meaning

Summary of changes

8

Summary of changes

Changes in edition five• AGENTMSG command: Changed note in MSGADDR subverb section from “R5

Agents can respond...” to “R5 Agents or higher can respond to...”• CHAIN Statement: Added operand “Simulate”• DEFPN command: Added operand “OWNER”• ENCPARM JOBID: Changed “Jjesid” to “JOBnnnnn|Jnnnnnnn”• ESPmgr and ESPmsg commands: Corrected the letter case of STATE verb

keywords Tag, User1, User2, User3, User4, and UserStatus. The keywords were upper-case before.

• NJETOL command: Sets.NJE tolerance. Added existing command to the Reference Guide.

• PTF SU01763, defect DEF12477:• AGENT statement: Added note in introduction, corrected Authority section,

changed description of ROUTING operand, and changed comment on second example.

• CPU command: In the CPU AGENT operand, removed limitation of AGENT to those with HPO.

• RESDEF command: Added NODAL as an alias for the GLOBAL operand.• PTFs SU01813, SU01814, and SU1815; defect DEF12612:

Added documentation on limits for• Defining a holiday and a special day with the same name• Defining holidays with the same name, start date, and start timeSee the “Usage notes” section of the DEFHOL and DEFSPEC commands.

• PTFs SU01833 and SU01834, defects DEF12330, DEF12334, and DEF13154:• ENQUEUE statement: Added HOLD operand. • RESOURCE statement: Added HOLD and NOHOLD operands and corrected

error in syntax• PTF SU01892 and SU01893, defect DEF12687 and DEF13148:

In the CCCHK statement• Added ASK operand, and rewrote documentation for the statement• In the “Ignoring an abend” section, changed “Step-level monitors still see an

abend as before” to “Step-level monitors also ignore the abend”.

9

• REEXEC statement:• Changed description of NOMAXIMUM operand• Added note about how you should use the MAXIMUM(count) operand

• RUNCONTROLID Statement: The statement now supports the checking of the status of child processes when the Agent determines the parent's completion status

Changes in edition four

New commands and statements• “APPLDISPLNAME Statement: Identify the Application Name of an Oracle

Application” on page 74• “APPLSHORTNAME Statement: Identify the Application Short Name for an

Oracle Application” on page 96• “ARGDEFAULTS Statement: Pass Default Arguments” on page 127• “ARGS Statement (Oracle Applications): Pass Arguments” on page 131• “CHILDMONITOR Statement: Enable Monitoring of Children Jobs (Oracle

Applications)” on page 182• “DESCRIPTION Statement: Describe an Oracle Applications Single Request” on

page 308• “MONITORDELAY Statement: Delay Monitoring Children for Oracle

Applications Programs” on page 858• “OA_JOB Statement: Start an Oracle Applications Job Definition” on page 915• “OAUSER Statement: Identify an Oracle Applications User Name” on page 917• “PRINTCOPIES Statement (Oracle Applications): Specify Number of Copies” on

page 960• “PRINTER Statement: Specify Printer” on page 966• “PRINTSTYLE Statement: Specify Print Style” on page 979• “PROGARGS Statement: Pass Arguments” on page 992• “PROGDATA Statement: Identify an Oracle Program” on page 994• “PROGPRINTCOPIES Statement: Specify Number of Copies” on page 996• “PROGPRINTER Statement: Specify Printer” on page 998• “PROGPRINTSTYLE Statement: Specify Print Style” on page 1000• “PROGRAM Statement: Identify an Oracle Applications Single Request

Program” on page 1002• “PROGSAVEOUTPUT Statement: Save Output” on page 1003

Summary of changes

10

• “REQUESTSET Statement: Identify an Oracle Applications Request Set” on page 1050

• “RESPNAME Statement: Identify an Oracle Applications Responsibility Name” on page 1075

• “SAVEOUTPUT Statement: Save Output” on page 1133

Updated commands and statements• “ABANDON SUBMISSION Statement: Bypass Job Submission” on page 18• “EXPEDITE Command: Define or Alter Expedite Policy” on page 574• “FILENAME Statement: Specify Files Monitored by FILE_TRIGGER” on

page 588• “LISTROOT Command: Save List of Waiting Jobs for Rerun into Data Set” on

page 779• “NOTWITH Statement: Specify Mutually Exclusive Jobs” on page 909• “RERUNM Command: Rerun Multiple Jobs” on page 1051• “ROUTING Command: Route Proxies Subsystem Requests” on page 1091• “VS Command: Issue Commands to the Operating System” on page 1313• “XCF SET MEMBER Command: Instruct Shadow Manager” on page 1348• “XCF SET SERVICE Command: Specify Fixed Intervals” on page 1349

Changes in edition three

New commands and statements• “BEAN Statement: Specify the JNDI Name of the Stateless Session Bean (J2EE)”

on page 146 • “CONNECTION_FACTORY Statement: Specify JNDI Name of Connection

Factory (J2EE)” on page 201• “DEST Statement: Specify Output Destination File (J2EE)” on page 313• “DESTNAME Statement: Specify JNDI Name of the Topic/Queue” on page 318• “EJB_JOB Statement: Start an EJB Job Definition (J2EE)” on page 401• “ENCLOG Command: Display Additional Information About the Most Recent

ESP Encore Request” on page 412• “ENCPARM Command: List All ENCPARM Commands in Effect” on page 414• “ENCPARM ABENDER Command: Specify a Program That Abends on Behalf

of Another Program” on page 415

11

• “ENCPARM AUTOREST Command: Recover Data Sets Automatically For a Job Restart” on page 416

• “ENCPARM BACKOUT Command: Control Whether a Data Set is Backed Out Under ESP Encore” on page 421

• “ENCPARM CLEANUP Command: Delete Data Sets That Will Be Allocated By a Restart Job” on page 423

• “ENCPARM COMMENT Command: Insert a Comment in the ESP Encore Job Run Report” on page 425

• “ENCPARM CONDCODE Command: Specify the Condition Codes That the ESP Encore Job Step Produces” on page 426

• “ENCPARM DELETE Command: Undo an ENCPARM Command” on page 427• “ENCPARM DIAG Command: Produce All Diagnostic Sections of the ESP

Encore Job Run Report” on page 429• “ENCPARM EXCLUDE Command: Specify a Step to Exclude From a Job

Restart” on page 430• “ENCPARM FORCE Command: Run a Job Even If ESP Encore Predicts Errors”

on page 432• “ENCPARM FROMSTEP Command: Specify a Step From Which a Job Is

Restarted” on page 433• “ENCPARM GDGADJ Command: Specify How ESP Encore Processes Relative

Generations For a Job Restart” on page 434• “ENCPARM HONORCC Command: Control ESP Encore Condition Code

Checks of Previous Job Runs” on page 437• “ENCPARM IGNOREDS Command: Specify Data Sets to Ignore on Job Restart”

on page 438• “ENCPARM JOBID Command: Specify the Job ID of the Job That Is Being

Restarted by ESP Encore” on page 440• “ENCPARM JOBNAME Command: Specify a Job to Be Backed Out or Whose

EXH Record Is to Be Dumped” on page 441• “ENCPARM MODE Command: Specify How a Job Is Processed by ESP Encore”

on page 442• “ENCPARM MODIFY Command: Modify the Internal Processing of ESP

Encore” on page 444• “ENCPARM PREDICT Command: Specify the Error Types That ESP Encore

Predicts” on page 446• “ENCPARM PREVTIME Command: Specify a Reader-On (RDRON) Time to

Find a Job in the EXH Data Set” on page 450

Summary of changes

12

• “ENCPARM PRINT Command: Select Sections of the ESP Encore Job Run Report to Print” on page 452

• “ENCPARM PURGE Command: Configure Automatic Purge of ESP Encore Job History Records” on page 454

• “ENCPARM QUIESCE Command: Quiesce ESP Encore” on page 458• “ENCPARM RESTART Command: Restart ESP Encore” on page 459• “ENCPARM STATUS Command: List the Status of ESP Encore” on page 461• “ENCPARM SUBSYS Command: Specify the Subsystem Identifier for a Job

Processed by ESP Encore” on page 462• “ENCPARM TAPESCR Command: Request a Tape Scratch From a TMS” on

page 466• “ENCPARM TOSTEP Command: Specify a Step To Which a Job Runs When It

Is Restarted” on page 470• “ENCPARM TRACE Command: Specify Modules to Be Traced” on page 471• “ENCPARM TYPE Command: Specify the Type of Processing That ESP Encore

Does” on page 472• “ENCPARM VOLUME Command: Specify Data Set Processing Based on

Volume Serial” on page 474• “ENCPARM WARNING Command: Display Extra Warning Messages to Support

Manual Restart Tasks” on page 476• “ENCREQ Command: List or Unlock Access-Serialization Locks” on page 478• “ENCTRACE Command: Trace ESP Encore Programs” on page 487• “FILTER Statement: Specify Filter for JMS Subscribe Jobs (J2EE)” on page 606• “INITIAL_CONTEXT Statement: Specify Initial Context Factory (J2EE)” on

page 674• “JNDIUSER Statement: Specify JNDI User ID (J2EE)” on page 696• “JMSP_JOB Statement: Start a JMS Publish Job Definition (J2EE)” on page 692• “JMSS_JOB Statement: Start a JMS Subscribe Job Definition (J2EE)” on

page 694• “LISTROOT Command: Save List of Waiting Jobs for Rerun into Data Set” on

page 779• “LOCATION Statement: Specify the Service Provider URL (J2EE)” on page 810• “METHOD Statement: Specify EJB Method to be Invoked Remotely” on

page 838• “MSGCLASS Statement: Specify the Java Class of the JMS Message (J2EE)” on

page 867

13

• “PARAMETER Statement: Specify the Method/Message Parameters (J2EE)” on page 938

• “RERUNM Command: Rerun Multiple Jobs” on page 1051• “TOPIC Statement: Publish/Subscribe to a Topic/Queue (J2EE)” on page 1259

Updated commands and statements• “AGENT Statement: Identify Where Job Runs” on page 38• “ARGS Statement: Pass Operands” on page 129• “CMDNAME Statement: Run Agent-Platform Commands” on page 191• “CPU_MON Statement: Monitor CPU Usage” on page 221• “DB_JOB Statement: Identify the Name of Database Jobs” on page 245• “DISK_MON Statement: Monitor Disk Space” on page 331• “ENDJOB Statement: End Job Definitions” on page 496• “ENVAR Statement: Pass Environment Variables” on page 509• “EVENTLOG_MON Statement: Monitor the Windows Event Log” on page 552• “EXITCODE Statement: Identify Failures by Exit Code” on page 571• “FILE_TRIGGER Statement: Define File Triggers” on page 587• “FILENAME Statement: Specify Files Monitored by FILE_TRIGGER” on

page 588• “FTP_JOB Statement: Identify the Name of FTP Jobs” on page 623• “IP_MON Statement: Monitor IP Addresses or Ports” on page 684• “NT_JOB Statement: Identify the Name of Windows Jobs” on page 912• “PROCESS_MON Statement: Monitor Process Execution” on page 986• “RELEASE Statement: Identify Successors” on page 1041• “RUN Statement: Identify Schedule Frequency” on page 1093• “SERVICE_MON Statement: Monitor Windows Services” on page 1161• “SPINLOG Command: Spin Audit Log” on page 1194• “TEXT_MON Statement: Monitor Content of Text File” on page 1242• “UNIX_JOB Statement: Identify the Name of UNIX Jobs” on page 1296• “USER Statement: Define User IDs” on page 1302

ABANDON DEPENDENCIES Statement: Submit Job Without Predecessor Dependencies

14

AABANDON DEPENDENCIES Statement: Submit Job WithoutPredecessor Dependencies

The ABANDON DEPENDENCIES statement is used to submit a job without its predecessor dependencies, after it meets a specified time. This does not override a manual hold, a time dependency, or a resource dependency for a job.

SyntaxABANDON DEPENDENCIES criteria

Usage notesSpecifying ABANDON DEPENDENCIES does not override a:• Manual hold• Time dependency• Resource dependency.

Related informationFor information on abandoning a submission time for a job, see the ABANDON SUBMISSION statement.For information on abandoning a job’s resource requirements, see the ABANDON RESOURCES statement.For information on manipulating jobs within Applications or subApplications, see the APPLJOB or AJ command.

Examples Submit job at 9 pm or when predecessor completesThe following ABANDON DEPENDENCIES statement submits PAYJOB2 at 9 pm or when PAYJOB1 completes, whichever comes first.JOB PAYJOB1 RUN DAILY RELEASE PAYJOB2ENDJOBJOB PAYJOB2 RUN DAILY ABANDON DEPENDENCIES 9PMENDJOB

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time.

15

Do not submit before 6 pm, abandon dependency at 7The following ABANDON DEPENDENCIES statement does not submit PAYJOB4 until 6 pm, and its dependency on PAYJOB3 is abandoned at 7 pm.JOB PAYJOB3 RUN DAILY RELEASE PAYJOB4ENDJOBJOB PAYJOB4 RUN DAILY DELAYSUB 6PM ABANDON DEPENDENCIES 7PMENDJOB

Submit job without predecessor dependency, but wait for resourceIn the following example, PAYJOB6 has a dependency on PAYJOB5 that is abandoned two hours from the time the Application is scheduled. However, PAYJOB6 is not submitted until one unit of a resource called T3480 is available:JOB PAYJOB5 RUN DAILY RELEASE PAYJOB6ENDJOBJOB PAYJOB6 RUN DAILY RESOURCE (1,T3480) ABANDON DEPENDENCIES NOW PLUS 2 HOURSENDJOB

ABANDON RESOURCES Statement: Submit Job Without Resource Dependencies

16

ABANDON RESOURCES Statement: Submit Job Without Resource Dependencies

The ABANDON RESOURCES statement is used to submit a job without its resource dependencies at a specified time.

SyntaxABANDON RESOURCES criteria

Usage notesSpecifying ABANDON RESOURCES does not override a:• Manual hold• Time dependency.

Related informationFor information on abandoning a submission time for a job, see the ABANDON SUBMISSION statement.For information on abandoning a job’s predecessor dependencies, see the ABANDON DEPENDENCIES statement.

Examples Submit job at 9 pm or when resource availableIn the following example, PAYJOB1 is submitted at 9 pm or when one unit of a resource called T3480 is available, whichever comes first:JOB PAYJOB1 RUN DAILY RESOURCE (1,T3480) ABANDON RESOURCES 9PMENDJOB

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time

17

Submit job in one hour or when resource availableIn the following example, PAYJOB2 is submitted one hour from the time the Application was scheduled or when one unit of a resource called CICSUP is available, whichever comes first:JOB PAYJOB2 RUN DAILY RESOURCE (1,CICSUP) ABANDON RESOURCES NOW PLUS 1 HOURENDJOB

Submit different times depending on dayIn the following example, PAYJOB3 is submitted at:• 7 am on Mondays or when one unit of a resource called CICSUP is available• 9 am on all other days or when one unit of a resource called CICSUP is available.JOB PAYJOB3 RUN DAILY RESOURCE (1,CICSUP) IF TODAY('MONDAY') THEN - ABANDON RESOURCES 7AM ELSE - ABANDON RESOURCES 9AMENDJOB

ABANDON SUBMISSION Statement: Bypass Job Submission

18

ABANDON SUBMISSION Statement: Bypass Job Submission

The ABANDON SUBMISSION statement is used to bypass job submission at a specified time.

SyntaxABANDON SUBMISSION criteria

Related informationFor information on abandoning a job’s dependency on preceding jobs, see the ABANDON DEPENDENCIES statement.For information on abandoning a job’s resource requirements, see the ABANDON RESOURCES statement.

Examples Usage note 1When a job’s submission is abandoned, ESP Workload Manager flags the job with a status of EXEC ABANDONED on the CSF, but retains the PREDWAIT PNode until the job’s predecessors complete. Once the predecessors complete, the job is then bypassed.The following example shows an abandoned job’s PNODE and STATUS information:Consolidated Status: View PAYROLL Row 1 of 3, Col 1

COMMAND ===> SCR ===> CSR

Jobname APPL PNODE STATUS

___ PAYJOB1 PAYROLL EXEC EXECUTING STEP1

___ PAYJOB2 PAYROLL PREDWAIT COMPLETE, EXEC ABANDONED

___ PAYJOB3 PAYROLL PREDWAIT WAITING, HC=1

In the above example, PAYJOB2’s submission was abandoned, but it retained the PREDWAIT PNode. It waits for PAYJOB1 to complete before it becomes bypassed.Usage note 2If you want to run PAYJOB3 immediately when PAYJOB2 is bypassed, use the ABANDON DEPENDENCIES statement in combination with the ABANDON SUBMISSION statement.

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time.

19

Specifying ABANDON SUBMISSION does not override a:• Manual hold• Time dependency• Resource dependency.Abandon submission if predecessor not complete by 9 pmIn the following example, submission of PAYJOB2 is abandoned at 9 pm if PAYJOB1 is not complete by that time:JOB PAYJOB1 RUN DAILY REL PAYJOB2ENDJOBJOB PAYJOB2 RUN DAILY ABANDON SUBMISSION 9PMENDJOB

Abandon submission in one hour if predecessor not completeIn the following example, PAYJOB4’s submission is abandoned one hour from the time the Application was scheduled if PAYJOB3 has not completed by that time:JOB PAYJOB3 RUN DAILY REL PAYJOB4ENDJOBJOB PAYJOB4 RUN DAILY ABANDON SUBMISSION NOW PLUS 1 HOURENDJOB

Abandon submission of two jobs by 9 pmIn the following example, if PAYJOB5 does not complete by 9 pm, PAYJOB6 and PAYJOB7 are not run:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB5 RUN WORKDAYS REL PAYJOB6JOB PAYJOB6 RUN WORKDAYS REL PAYJOB7 ABANDON SUBMISSION 9PMJOB PAYJOB7 RUN WORKDAYS ABANDON SUBMISSION 9PMENDJOB

ABANDON SUBMISSION Statement: Bypass Job Submission

20

Note: To abandon a group of jobs, consider using subApplications. You can then use Alert processing to bypass a group of jobs with one command. Refer to the ESP Workload Manager Advanced User’s Guide for more information.

Abandon submission of a job after the abandon submission timeThis example shows you how to handle the following scenario:An Event invokes an Application containing PAYJOB1 and PAYJOB2. PAYJOB1 includes the statement ABANDON SUBMISSION 9:00AM.1. The Event is triggered at 8:00AM and PAYJOB1 starts running.2. The system goes down at 8:10 AM, before PAYJOB2 runs.3. The system comes back up at 10:00AM.4. PAYJOB1 completes and PAYJOB2 is submitted, which is probably not what you

expected to happen.PAYJOB2 is submitted because the current time (10:00AM) is later than the time specified in the ABANDON SUBMISSION statement (9:00AM). In this case, ESP Workload Manager will abandon submission at 10:00AM the next day.To avoid the problem, you need to add “TODAY” to the ABANDON SUBMISSION statement to abandon submission of a job generated after the specified abandon time.JOB PAYJOB1 RUN DAILY REL PAYJOB2ENDJOBJOB PAYJOB2 RUN DAILY ABANDON SUBMISSION 9AM TODAYENDJOB

21

ABAPNAME Statement: Run ABAP Steps Within an SAP Job

The ABAPNAME statement starts a step definition within the SAP_JOB definition and identifies the ABAP step to be run.

ApplicabilityESP Business Agents for SAP, Version 1 (one step per job only) and higher.

SyntaxABAPNAME ABAP_name

Usage notesABAPNAME is mandatory within an SAP_JOB.Use the ABAPNAME statement within the boundaries of the job definition statement. Define multiple ABAPs within a job definition using multiple ABAPNAME statements.ABAPNAME corresponds to the SAPGUI ABAP program Name field on the Create Step dialog.Note: When defining a new SAP job, try to limit the number of steps (ABAPs) to one

per job. It will help if a job fails. If you are adding SAP jobs from a list, however, your jobs may contain multiple ABAPs. ESP Workload Manager supports multiple ABAPs per job, but if you run a job and one of the ABAPs fails, the job is marked as failed. You cannot re-run an individual ABAP. You need to re-run the whole job.

ExampleSpecifying an ABAPSAP_JOB CYBJG01.JOB2 AGENT HPSAP RUN DAILY ABAPNAME RSPARAM PRINTDEST ATLYENDJOB

Operand DescriptionABAP_name Valid ABAP name as defined on the SAP system.

Note: For SAP version 4.5/4.6, ABAP_name has a maximum length of 40 valid SAP characters.

ABAPNAME Statement: Run ABAP Steps Within an SAP Job

22

Specifying multiple ABAPsSAP_JOB CYBJG01.JOB2 AGENT HPSAP RUN DAILY ABAPNAME RSPARAM PRINTDEST ATLY ABAPNAME RSPARAG PRINTCOPIES 2ENDJOB

23

ABENDLIM Command: Set ABEND Queue Size

Displays or sets the abend queue size for jobs that ESP is tracking that produce a non-zero return code.

TypeGeneral command.

AuthorityYou must have OPER authority to issue the ABENDLIM command.

SyntaxABENDLIM [count]

Usage notesWhen ESP detects that one of the jobs it is tracking abends or produces a non-zero return code, it adds an entry to a list of abended jobs. The entry identifies the job name, job number, termination time and completion code. The ABENDLIM command specifies how long the list is to be allowed to grow. Once the list has grown to its full size, for example, the count you specify, each newly abended job causes the removal of the oldest job from the list. Thus, specifying ABENDLIM 100 causes ESP to keep track of the last 100 abended jobs.It is not required that an ABENDLIM count be specified, as job abend information can be displayed using other commands, for example, LJ, LTJ jobname I and the CSF.If an ABENDLIM count is specified, you can display abended jobs using the DAB (display abended jobs) command.If you increase the ABENDLIM count, ESP begins to store a longer list of jobs from the point at which you issue the command. For example, if you change ABENDLIM from 20 to 100, you will not immediately see any changes in a DAB display.

Related informationFor information on displaying the abended queue, see the DAB (display abended queue) command.For information on displaying job information, see the LJ (list job status) command.For information on displaying job information, see the LTJ (list a tracked job definition) command.

Operand Descriptioncount Indicates the abend queue size. There is no default. If a count is not

specified, the abend queue size is displayed.

ABENDLIM Command: Set ABEND Queue Size

24

For information on displaying abended jobs using the CSF, see the ESP Workload Manager User’s Guide.

Examples Display abend queue sizeThe following ABENDLIM command displays the abend queue size:ABENDLIM [count]

In the above example, when the ABENDLIM command is issued with no count operand, the following display is produced indicating the abend queue size and the number of abended jobs:ABEND QUEUE MAX = 20, 4 CURRENTLY QUEUED

Set abend queue sizeIn the following example, the abend queue size is set to 100, indicating that ESP keeps track of the last 100 abended jobs:ABENDLIM 100

25

ABSORB Statement: Reserve Resources

The ABSORB statement is used to reserve a quantity of resources for jobs that require a large resource count. Resource Absorption reserves the resources that are available at the time the job is next in the queue and holds them while waiting to accumulate the remainder of resources required for that job. Jobs with smaller resource requirements cannot use the reserved resource. The ABSORB statement prevents jobs with large resource requirements from incurring a processing delay.A job with a higher priority and the same resource requirements takes the resources and runs before a lower priority job with the ABSORB statement.

AuthorityYou require read access to the SAF resource: REABSORB.

SyntaxABSORB

Types of resourcesAbsorption is available for the following types of resources:• Renewable• Depletable.

Usage notesThe ABSORB statement will ABSORB resources only if the request is for less than or equal to the maximum resource defined. Code an ABSORB statement within the scope of the job statement, above the RESOURCE statement, where Resource Absorption is to occur. ABSORB can also be used at the Application level.

Example Reserve resources for a jobThe following example reserves four units of T3480 for JOBX. Jobs that follow JOBX in the queue that require less than or equal to the same resource, and are the same job priority, are not submitted before JOBX:APPL ABSRES JCLLIB 'CYBER.JCLLIB.CNTL'JOB JOBX RUN DAILY ABSORB RESOURCE (4,T3480)ENDJOB

ADJUST Command: Adjust Run Time

26

ADJUST Command: Adjust Run Time

Adjusts the execution time or CPU time for one or more jobs when using ESP’s Modeling feature to forecast future workload.

TypeModel command.

SyntaxADJUST [EXECTIME(factor)] [CPUTIME(factor)] [JOBS(jobname[,jobname]...)]

RestrictionThe ADJUST command is available only with Modeling.

Usage notesESP estimates a job’s execution time and CPU time based on historical data. An adjustment factor alters these estimates. You can adjust the execution time or CPU time for one or more jobs. This may be useful when elapsed run times for jobs vary greatly at different times of the year, such as at year-end.

Operand DescriptionEXECTIME Indicates that an adjustment is to be made to the execution time

(or elapsed run time) of the requested jobs.CPUTIME Indicates that an adjustment is to be made to the CPU time of the

requested jobs.factor Indicates the adjustment factor expressed as a percentage. Prefix

the adjustment factor with a + or - sign, which allows the MODEL processor to determine whether the execution time or CPU time should be increased or decreased.

JOBS Limits the adjustments to one or more job names or job prefixes. The adjustments are applied to all jobs in the modeling period if the JOBS keyword is not specified.

jobname Indicates one to eight alphanumeric character job name or list of job names to which the adjustments apply. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book.) can be used to perform masking.

27

Related informationFor information on forecasting future workload, see the ESP Workload Manager User’s and Advanced User’s Guides.

Examples Adjust execution and CPU timeIn the following example:• The execution time is adjusted by -10%• The CPU time is adjusted by -30%.ADJUST EXECTIME(-10) CPUTIME(-30)

Adjust by job nameIn the following example, the execution time is adjusted by +300% for all jobs beginning with ACC, or having YEND as the first four characters of their jobnames:ADJUST EXECTIME(+300) JOBS(ACC-,YEND****)

Adjust on last day of monthIn the following example, the execution time is adjusted by +200% for PAYJOB1 on the last day of the month:IF TODAY('LAST DAY OF MONTH') THEN - ADJUST EXECTIME(+200) JOB(PAYJOB1)

AFTER Statement: Specify Predecessors

28

AFTER Statement: Specify Predecessors

The AFTER statement is used to specify any jobs which are predecessors to a job and should indicate a release to this job upon completion. The default is successful completion.

SyntaxAFTER {jobname} {(jobname{(A)|(U)|(N)[,jobname(A)|(U)|(N]...})} {ADD(jobname{(A)|(U)|(N)[,jobname(A)|(U)|(N]...})} {DROP(jobname{(A)|(U)|(N)[,jobname(A)|(U)|(N]...})}

Usage notesUse AFTER to indicate the names of jobs that are predecessors to this job and which will decrement the hold count on this job upon completion.The termination operands (A, U, N) are available only for jobs in an Application. Note: This is different from the way the AFTER support on a DJCDATA statement

works.

Related informationFor information on other ways to specify predecessor and successor relationships, see the RELEASE, PREREQ and POSTREQ statements or the ESP Workload Manager User’s Guide.For jobs in JES3 or DJC jobnets, see the ABNORMAL and NORMAL parameters as documented in the JES3 or DJC User’s Guide.

Operand Descriptionjobname Indicates a job name up to eight characters. Enclose multiple job

names in parentheses, separated by a blank or a comma. Job names may be qualified.

ADD Indicates that the specified jobs be added to the currently defined AFTERs.

DROP Indicates that the specified jobs be dropped from the currently defined AFTERs.

A Release on abnormal termination of a predecessor. This includes condition code failures.

U Release on any termination of a predecessor.N Release on successful termination of a predecessor. This is the

default.

29

Examples Submit after successful completion of jobIn the following example, PAYJOB2 is submitted after the successful completion of PAYJOB1:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILYENDJOBJOB PAYJOB2 RUN DAILY AFTER PAYJOB1ENDJOB

Submit after any completion of jobIn the following example, PAYJOB5 is submitted after any completion of PAYJOB3 and the successful completion of PAYJOB4:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 RUN DAILYENDJOBJOB PAYJOB4 RUN DAILYENDJOBJOB PAYJOB5 RUN DAILY AFTER (PAYJOB3(U),PAYJOB4)ENDJOB

AFTER Statement: Specify Predecessors

30

Submit after successful completion of two jobsIn the following example, the AFTER and AFTER ADD statements are used to indicate job relationships. PAYJOB8 is submitted after the successful completion of PAYJOB6 and PAYJOB7:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB6 RUN DAILYENDJOBJOB PAYJOB7 RUN DAILYENDJOBJOB PAYJOB8 RUN DAILY AFTER PAYJOB6 AFTER ADD(PAYJOB7)ENDJOB

Submit after with conditionsIn the following example, PAYJOB10 is submitted after the successful completion of PAYJOB9. PAYJOB11 is conditional upon the abnormal completion of PAYJOB10. If PAYJOB10 completes successfully, PAYJOB11 is bypassed:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB9 RUN DAILYENDJOBJOB PAYJOB10 RUN DAILY AFTER PAYJOB9ENDJOBJOB PAYJOB11 CONDITIONAL RUN DAILY AFTER (PAYJOB10(A))ENDJOB

Submit after three jobsThe following example indicates that PAYJOB4 has three predecessors that must complete successfully before it is submitted:JOB PAYJOB4 AFTER (PAYJOB1,PAYJOB2,PAYJOB3)

31

Submit after abnormal completion of jobThe following example indicates that PAYJOB5 is to be released after an abnormal termination of PAYJOB1:JOB PAYJOB5 AFTER (PAYJOB1(A))

Submit after multiple conditionsThe following example indicates that PAYJOB6 is to be released after all three of the following conditions are met:• The successful completion of PAYJOB1• An abnormal termination of PAYJOB2• Any termination of PAYJOB3.JOB PAYJOB6 AFTER PAYJOB1 AFTER ADD(PAYJOB2(A)) AFTER ADD(PAYJOB3(U))

AGENT Command: Define an ESP Agent to ESP Workload Manager

32

AGENT Command: Define an ESP Agent to ESP Workload Manager

The AGENT command defines an ESP Agent to ESP Workload Manager.

TypeMaster (AGENTDEF member).

SyntaxAGENT name {ADDRESS(IP address)} {PORT(port)} [platform] {ASCII|EBCDIC} {TCPIP|APPC} [PREFIXING|NOPREFIXING] [ENCRYPT|ENCRYPT(x'nnnnnnnnnnnnnnnn')|NOENCRYPT]

Operand Descriptionname Specifies the Agent name. The Agent name will be used in ESP

Workload Manager Applications. It should be as descriptive as possible (could include the location or type of product workload).• Can be up to 16 characters in length• Must start with an alphabetic character• Remaining characters can be any combination of

alphanumeric characters including underscore, but cannot contain blank characters.

IP address Specifies the TCP/IP address of the Agent. The address can be in dotted decimal notation or Host Name format.

port Identifies the TCP/IP port number on the Agent platform. This port definition must match the port specified on the Agent.

33

ExampleThe following example shows an AGENT initialization parameter in an AGENTDEF:AGENT TORSUN ADDRESS(xxx.xx.xx.xx) PORT(9999) UNIX ASCII +TCPIP PREFIXING ENCRYPT(X'nnnnnnnnnnnnnnnn')

AGENTDEFThe Agent definition data set or AGENTDEF is a file that contains information on the remote systems that form ESP Workload Manager’s span of control. An AGENTDEF may be a sequential data set or a member of a partitioned data set. The initialization parameters that make up an AGENTDEF are:

platform Identifies the Agent platform. Specify one of the following platforms:

• AS400• HP3000• z/OS• NT• OPENVMS• OS2• UNISYS• UNIX• TANDEM

ASCII|EBCDIC Indicates the remote system is an ASCII or EBCDIC machine. Specify ASCII for all Agents except:

• AS400• IBM UNIX System Services.

TCPIP|APPC Indicates the network protocol used to connect to the Agent.PREFIXING| NOPREFIXING

Enables the Agent to know how many TCP/IP packets to expect. Message prefixing should be enabled to avoid potential loss of data.NOPREFIXING is the default.

ENCRYPT|NOENCRYPT

Enables encryption for the Agent. The ENCRYPT key field is a hexadecimal eight byte field. If ENCRYPT is specified without a key, it will use the key specified in the ENCRYPT operand. For more information, see page 484.

Operand Description

AGENT Command: Define an ESP Agent to ESP Workload Manager

34

• MANAGER see page 826• ENCRYPT see page 484• MAPUSER see page 830• AGENT see page 32• DMANAGER initialization parameter, see the ESP Workload Manager

Installation and Configuration Guide

Example of an AGENTDEF The following is an example of an Agent definition data set without the DMANAGER initialization parameter:MANAGER NAME(CM_CENTRAL) TCPIPENCRYPT KEY(X'xxxxxxxxxxxxxxxx')MAPUSER JDOE TO(CYBJD01) AGENT(TORSUN1)AGENT TORSUN1 ADDRESS(xxx.xx.xx.xx) PORT(9999) UNIX ASCII +TCPIP PREFIXING AGENT TORNT1 ADDRESS(xxx.xx.xx.xx) PORT(9998) NT ASCII +TCPIP PREFIXING ENCRYPTAGENT TORAS4001 ADDRESS(xxx.xx.xx.xx) PORT(9997) AS400 EBCDIC +TCPIP PREFIXING ENCRYPT(X'xxxxxxxxxxxxxxxx')

Related informationThe following initialization parameters are used for ESP Workload Manager distributed workload:• WOBDEF see page 1332• LOADAGDF see page 802• AGENTRCV see page 48• MGRADDR see page 839• COMMQ see page • INET see page 663

35

AGENT Command: Display Agent Definition

The AGENT command is used to display the contents of the agent definition normally called AGENTDEF, and controls the flow of messages to the Agent.

TypeGeneral command.

AuthorityYou require OPER authority to issue the AGENT command. Read access to the SAF profile systemAGENT.agentname is also required.

SyntaxThe syntax of the AGENT command is:AGENT [agentname [LIST[ALL|CM_OWNED|DM_OWNED|MSGS|ORPHANS|ALIASES]]] |agentname {FLUSH|QUIESCE|RESTART}]

Operand DescriptionAGENT Displays the contents of the agent definition when issued

without parameters.agentname Specify a valid agent name as defined in the agent definition, or

wild cards – (any character wild card) or * (single character wild card). If agentname is left blank, the contents of the agent definition are listed.

LIST Lists the contents of the agent definition for the named agent. This is the default.Results include:• Name of the agent• TCP/IP address and port of the agent• Communication protocol• Prefixing options• Encryption options• Character set• OS platform• Retry interval• Owning ESP Workload Manager• Active sessions

AGENT Command: Display Agent Definition

36

Examples:List defined agents The following example requests a list of the agents defined.

OPER AGENT

This is a sample response:

AS401Address 131.50.25.12Port 3001CommType TCP/IP, Charcode ASCII, OS OS400Retry Interval 0Owned by 131.50.30.150 Messages sent

NT_CHIAddress 131.50.25.12|Port 3001CommType TCP/IP, No Prefixing, No encryption, Charcode ASCII, OS NTRetry Interval 0Owned by 131.50.30.15No active session for this Agent.

In this example, there are two agents defined to the ESP Workload Manager issuing the command.

ALL Lists all types of agents, including those owned by the central ESP Workload manager, those owned by a distributed manager, and those that have no current owner. This is the default.

CM_OWNED Lists all agents owned by the central ESP Workload Manager.DM_OWNED Lists all agents owned by Distributed Managers.

MSGS Lists all pending messages (AFMs) for the agent.ORPHANS Lists all agents that currently have no owner assigned.

ALIASES If any, lists all of the agent’s aliases.QUIESCE Holds all messages to be sent to the named agent until the

AGENTMSG RESTART command is issued.RESTART Resumes sending messages to the named Agent. Used following

the use of QUIESCE.

Operand Description

37

Display the definition statement of an agentTo display the details of the agent definition, which pertain to the OS401 agent, type the following:OPER AGENT OS401

This is a typical response:OS401Address 131.50.25.12Port 3001CommType TCP/IP, Charcode ASCII, OS OS400Retry Interval 0Owned by 131.50.30.150 Messages sent

Hold messages to an agentThis an example of the AGENT command used to hold the messages to an agent:OPER AGENT OS4_CHI QUIESCE

Restart an agentThis an example of the AGENT command used to restart the sending of messages to the agent after a QUIESCE command was issued:AGENT OS4_CHI RESTART

AGENT Statement: Identify Where Job Runs

38

AGENT Statement: Identify Where Job Runs

Identifies the specific distributed platform where the job runs.Note: Make sure resources are defined only in nodes where the workload in question

can run.

TypeApplication statement.

Authority You require READ access to the AGENT.agentname resource in the SAF environment.

SyntaxAGENT agentname [ROUTING|NOROUTING]

Usage notesUse AGENT within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition to apply to the entire Application.

Examples Defining Agent workloadThis example of a job definition contains the Agent statement:AS400_JOB MFGDATA RUN DAILY RELEASE MFGSORT AGENT AS401 CLPNAME MFGTEST.DATAENDJOB

In the above example, AS401 is the Agent defined to run the AS400_JOB.

Operand Descriptionagentname Valid Agent name as defined in the Agent definition.ROUTING ESP Workload Manager selects an Agent based on

resource availability. ESP Workload Manager selects an Agent based on resource availability. If you are routing between nodes, you must specify the GRAVITY operand in the RESDEF command.

NOROUTING ESP Workload Manager uses the Agent specified by agentname.

39

Defining an Agent job with Agent workload balancingNT_JOB myntjob RUN DAILY RESOURCE(1,RESWIN) AGENT AGwin1 ROUTING CMDNAME C:\myjob.exeENDJOB

The ROUTING operand specifies that the job can run on any CPU representing an Agent that has enough resources.

AGENT_MONITOR Statement: Define Monitoring Workload Objects

40

AGENT_MONITOR Statement: Define Monitoring Workload Objects

The AGENT_MONITOR statement defines a workload object that monitors the status of an ESP Agent and is used in conjunction with the AGENT, MSGQLEN, and STATINTV statements.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use AGENT_MONITOR, you must load the Agent Monitor workload object module: CYBESOAM with the ESP OPER WOBDEF command or with the WOBDEF initialization parameter.Also refer to the JOB statement usage notes.Refer to the AMNOTIFY statement if you want to be notified if the Agent becomes inactive.

ExampleIn the following example, AGENT_MONITOR TORONTO will perform status checks on Agent CYBNT1. The status checks occur every 5 minutes and the object will store 10 messages.APPL AGENTMON

AGENT_MONITOR TORONTO STATINTV 5 MSGQLEN 10 AGENT CYBNT1ENDJOB

41

AGENTMSG Command: Send Messages to Agent

Issues commands and send messages to agents.

TypeGeneral command.

AuthorityYou require OPER authority to issue the AGENTMSG command, and you require read access to the SAF resource: system.AGENTMSG.verbsubverb.name.

SyntaxAGENTMSG . . agentname . {objectname | .} verb subverb [(keyword)]

CONTROL {CANCEL|CLRFILES|FLUSH|GETSPOOLFILE|GETTRACEFILE| MGRADDR PORT(number) ADDRESS(address)|REFRESH Security| SETINITS nnnn|SHUTDOWN|STATUS}

RUN . DATA {(FILENAME=filename)|(CLPNAME=clpname)|COMMAND(command)} [CCEXIT(ccexitname)] [CURLIB(curlib)] [JOBD(jobd)] [JOBQ(jobq)] [JOBNAME(jobname)] [LIBL(listname)] [MFUSER(mfuser)] [OTHERS(others)] [PARAMETERS(parameters)] [USER(user)]}

TRIGGER MONITOR MonitoredNode(node) Nodetype(Manager) Nodename(name) Domain(MAIN) Applname(applname) Applegen(applgen) Jobname(jobname) Jobqual(jobqual) State(state) Status(status)

Operand Description. . The first period is a placeholder for the date the message is sent and the

second one for the time. agentname The name of the target agent. This is a required parameter

AGENTMSG Command: Send Messages to Agent

42

CONTROL verbRequests the agent to perform an action specified by the associated subverb.

. The period is a placeholder indicating the name of the ESP Workload Manager sending the message.

objectname | . Indicates the name of the object to which the command refers. Alternatively, for commands not related to a specific job, specify a period in place of the job name.

Note: To cancel the job, specify the fully-qualified job name.verb Indicates the action to be taken. The possible values are:

• “CONTROL verb”, see page 42• “RUN verb”, see page 43• “TRIGGER verb”, see page 45

subverb Further defines the action to be taken. keyword Modifies the verb /subverb combination.

Operand Description

Subverb DescriptionCANCEL Stops the specified job if it has already started.CLRFILES Instructs the agent to archive and clear the log files. FLUSH Flushes the specified job from the input queue, if it has not already

started to run. It does not affect the job if it has already started.It also sends the job’s status to the ESP Workload Manager.

GETSPOOLFILE Applicable only to the following agents:• AIX• HPUX• PeopleSoft• Solaris• UNIX• Windows NTInstructs the agent to retrieve the spool file.

GETTRACEFILE Applicable only to the PeopleSoft agent. Instructs the agent to retrieve the trace file.

MGRADDR Tells the agent to respond to messages from the ESP Workload Manager on a new TCP/IP address and port. For details about MGRADDR and its operands, see “MGRADDR subverb” on page 43.

REFRESH Security Reloads the security file. The word Security is case sensitive when issued to an agent running on a UNIX platform.This parameter is not supported on the ESP Agent for OS/400 V2.0.

43

MGRADDR subverbTells the agent to respond to messages from the ESP Workload Manager on a new TCP/IP address and port. Use this when: • You move the ESP Workload Manager to a new master• You want the agent to take direction from a different ESP Workload ManagerYou can issue the AGENTMSG with the MGRADDR verb from the original master or from the new master.Note: You can also issue the MGRADDR command from the new master only.

MGRADDR is also an initialization parameter.Note: R5 agents or higher can respond to multiple masters. Therefore, if you use

them, there will be less or no need to use the MGRADDR subverb of the AGENTMSG.CONTROL command.

Note: This is a temporary change, until the next time the agent is restarted. You must specify the following operands:

RUN verbNote: The RUN verb is used to request that a unit of work be run. The positional

parameter (.) and the DATA subverb are required with the RUN verb. For example:

AGENTMSG "joby RUN . DATA(CLPNAME TEST/PAY.DATA)"

The following are valid operands to use with the DATA( ) subverb of the RUN verb. Each set of operand and value should be separated by a comma. For example: AGENTMSG "joby RUN . DATA(CLPNAME SESP,LIBRARY U400)"

SETINITS nnnn Sets the maximum number of initiators allowed on the agent to nnnn. Initiators indicate the maximum number of concurrent jobs by the agent.This parameter is not supported on the ESP Agent for OS/400 V2.0.

SHUTDOWN Instructs the agent to shut down after the current work is completed.STATUS Requests an Agent to supply its status. Applicable only to Agent

Monitor.

Subverb Description

Operand DescriptionPORT(number) Specifies the port number of the new ESP Workload Manager master.ADDRESS(address) Specifies the TCP/IP address of the new ESP Workload Manager

master.

AGENTMSG Command: Send Messages to Agent

44

Operand Description(FILENAME=filename) Applicable to the OS/400 agent only. Specifies the OS/400 source file

and member that contain the CL source for the program to run. Mutually exclusive with CLPNAME and COMMAND.

(FILENAME=filename) Applicable to the OS/400 agent only. Specifies the OS/400 source file and member that contain the CL source for the program to run. Mutually exclusive with CLPNAME and COMMAND.

(FILENAME=filename) Applicable to the OS/400 agent only. Specifies the OS/400 source file and member that contain the CL source for the program to run. Mutually exclusive with CLPNAME and COMMAND.

CCEXIT(ccexitname) Applicable to the OS/400 agent only. Specifies an exit program to run when the job completes.

CLPNAME(clpname) Applicable to the OS/400 agent only. Identifies the OS/400 program to be run. Mutually exclusive with FILENAME and COMMAND.

COMMAND command Applicable to the OS/400 agent only. Specifies a command that runs in the batch job. Mutually exclusive with FILENAME and CLPNAME.

CURLIB(curlib) Applicable to the OS/400 agent only. Specifies the current library associated with the target job. If the User Profile specifies the CURLIB parameter (default *CRTDFT), the agent will use this value instead of the default *CURRENT as the CURLIB parameter in SBMJOB command.

JOBD(jobd) Applicable to the OS/400 agent only. Specifies the OS/400 job description for the program in the form libraryname.descriptionname.

JOBQ(jobq) Applicable to the OS/400 agent only. Specifies the OS/400 job queue in the form libraryname.jobqueuenname.

JOBNAME(jobname) Applicable to the OS/400 agent only. Specifies the name of the OS/400 job to display in the job queue, or on the Work with Active Jobs display. If you do not specify a job name, the name defaults to the name specified with CLPNAME. If you do not specify CLPNAME, the name defaults to the job name in the ESP Workload Manager procedure.

45

TRIGGER verbSignals to the Agent that an SNMP trap should be created and sent to the SNMP management console. The MONITOR subverb is required with the TRIGGER verb and specifies the required information passed to the Agent in an AFM.

LIBL(listname) Applicable to the OS/400 agent only. Initial user part of the library list that is used to search for operating-system object names that were specified without a library qualifier. The library names passed to the OS/400 SBMJOB command define the INLLIBL parameter of the SBMJOB command. The INLLIBL parameter in the SBMJOB command will override the Job Description's INLLIBL parameter that is defined by the JOBD statement in the ESP Workload Manager job definition.If LIBL is not defined, but USER is defined within the job definition, the following applies:• The agent uses the USER default library list• The agent uses *SYSVAL instead of the default *CURRENT, as

the INLLIBL parameter in SBMJOB command if the OS/400 user profile does not specify the JOBD parameter. (The default JOBD parameter of the OS/400 User Profile is QGPL/QDFTJOBD.

• The agent uses the INLLIBL parameter from the Job Description (JOBD) instead of the default *CURRENT as the INLLIBL parameter in SBMJOB command if the user profile has a specific JOBD parameter.

• The agent uses the OS/400 user profile’s CURLIB parameter instead of the default *CURRENT, as the CURLIB parameter in the SBMJOB command.

MFUSER(mfuser) Applicable to the OS/400 agent only. Specifies the user ID used by ESP Workload Manager to submit workload objects.

OTHERS(parms) Applicable to the OS/400 agent only. Specifies additional parameters to pass to the OS/400 SMBJOB command. They must be valid SBMJOB parameters. The list of parameters must be enclosed in parentheses and separated by a space.

PARAMETERS(parms) Applicable to the OS/400 agent only. The list of parameters must be enclosed in parentheses and separated by a space. Specify each parameter within single quotes.

USER(user) Applicable to the OS/400 agent only. Specify the user ID under which to run the job. Specify USER or *CURRENT for an OS/400 SBMJOB command if *RQD is specified in the job description.

Operand Description

AGENTMSG Command: Send Messages to Agent

46

You must specify the following operands with the MONITOR subverb of the TRIGGER verb:

ExamplesIn this example, the agent named MYAGENT is shut down:AGENTMSG . . MYAGENT . . CONTROL SHUTDOWN

In this example, the job named PAYROL of the 12th generation of Application PAY, running on the MYAGENT agent is cancelled:AGENTMSG . . MYAGENT . PAYROL/PAY.12/MAIN CONTROL CANCEL

In this example, the agent named MYAGENT is requested to respond to ESP Work-load Manager master at port number 5100 and address 111.11.11.11OPER AGENTMSG . . MYAGENT..CONTROL Mgraddr Port(5100)+ Address(111.11.11.11)

Call an OS/400 programOPER AGENTMSG .. A4 . JOB3.AS400/TESTA400.0/MAIN RUN . DATA+ (FILENAME=TESTFILE) LIBL(A01CURRENT A02CURRENT A03CURRENT+ A04CURRENT A05CURRENT A06CURRENT A07CURRENT A08CURRENT+ A024CURRENT)PARAMETERS('JOB1_param111''JOB1_param222')+ OTHERS(OUTQ(AGENTV20/AGENTOUTQ) MSGQ(AGENTV20/AGENTMSGQ))+ USER(USER2) CURLIB(VFM_PP)JOBNAME(JOB2)MFUSER(CYBJAK2CYBUSR)

Operand DescriptionMonitoredNode(node) Specifies ESP Workload Manager master TCP/IP address.Nodetype(Manager) Specifies the node type. The value is Manager.Nodename(name) Specifies the name of the ESP Workload Manager master that is

submitting the AFM as specified in the Agent definition. Domain(MAIN) Specifies the name of the domain. The value is MAIN.Applname(applname) Specifies the name of the Application that satisfies the NOTIFY

statement that triggered the Alert. Applgen(applgen) Specifies the generation number of the application that contains the

monitored job.Jobname(jobname) Specifies the name of the job that satisfies the Notify statement. Jobqual(jobqual) Specifies the job qualifier. If the job does not have a qualifier, it is set to

null.State(state) Is a free-format eight-character field. It is intended to specify the state

of the application. The value can include: STARTED, the name of any pnode, or the character representation of any completion code.

Status(status) Is a free-format 28-character field. It is intended to specify the system status string of the job that is passed by an Agent through the ESPmgr command.

47

In the above example: • AGENTMSG is the command name. This message is passed from the ESP

Workload Manager to the agent.• A4 is the name of the target agent.• JOB3.AS400/TESTA400.0/MAIN is the name of the target job.• RUN is the verb that requests the agent to run a job.• TESTFILE is the agent source file and member that contain the CL source for the

job to run.• LIBL adds several libraries to the user’s library list.• PARAMETERS and OTHERS pass parameters to the job.• USER2 is the user ID under which to run the job.• VFM_PP is the job’s current library.• JOB2 is the job name displayed in the job queue, or on the Work with Active Jobs

display.• CYBJAK2 CYBUSR is the user ID of the ESP Workload Manager sending the

agent message.Send information to build an SNMP trapESP AGENTMSG . . CYBNT . . -TRIGGER MONITOR MonitoredNode(10.1.15.1) Nodetype(Manager) -Nodename(CM_CENTRAL) Domain(MAIN) Applname(UNAGTEST) -Applgen(41) Jobname(IEFBR14) JobQual(SNMP) State(STARTED) -Status()

AGENTRCV Command: Agent Receiver Definition

48

AGENTRCV Command: Agent Receiver Definition

The AGENTRCV command is used to define and display the ESP Workload Manager’s receiver function for communication with ESP Agents. It can be used dynamically to add another agent receiver while ESP Workload Manager is active. It can also be used as a parameter of ESP Workload Manager’s initialization parameters to activate the receivers each time it is started.

TypeGeneral command.

AuthorityYou require OPER authority to issue the AGENTRCV command.

SyntaxAGENTRCV {DISPLAY|LIST|DELETE|HALT| QUIESCE|RESTART|DEFINE|SET} [NAME(rcvname)] [PORT(portnumber)][DUMPMSGS|NODUMPMSGS] [ENCRYPTEDONLY|NOENCRYPTEDONLY]}

Operand DescriptionAGENTRCV Indicates the command name. Displays the status of the ESP

subsystem’s Agent receivers when entered by itself. DISPLAY Displays the status of the ESP Workload Manager subsystem’s

agent receivers. It is equivalent to LIST. LIST Displays the status of the ESP subsystem’s agent receivers. It is the

default. DELETE Stops an agent receiver and deletes it from the ESP subsystem.HALT Stops an agent receiver without deleting it.QUIESCE Stops an agent receiver without deleting it. It is equivalent to HALT.RESTART Restarts an agent receiver that has been HALTed or QUIESCEd.DEFINE Defines an agent receiver to the ESP Workload Manager subsystem

and starts it.SET Sets an agent receiver parameter dynamically.NAME(rcvname) Indicates a unique 1—8 character agent receiver name. The first

character must be alphabetic or national. It is optional for the LIST and DISPLAY options and required for all other options.

49

Usage notesThe AGENTRCV command is normally included in the ESP Workload Manager initialization parameters to activate the agent receivers each time it initializes.You can use the AGENTRCV command to dynamically change the attributes of an existing agent receiver or to add another one.

Examples Display agent receiver statusIn the following example, the status of the ESP subsystem’s agent receivers are displayed:AGENTRCV

ESPMTCP1 Port(5100) EncryptedOnly 337 messages received Last successful receive at 13.58.39 on THURSDAY SEPTEMBER 14TH, 2000 Current state Listen since 13.58.39 on THURSDAY SEPTEMBER 14TH, 2000

ESPMTCP2 Port(5101) 746 messages received Last successful receive at 13.58.29 on THURSDAY SEPTEMBER 14TH, 2000 Current state Listen since 13.58.30 on THURSDAY SEPTEMBER 14TH, 2000

PORT(portnumber) Indicates the TCP/IP port number of a TCP/IP agent receiver. It is only valid with the DEFINE and SET options. If specified with the SET option, the agent receiver must be in a halted state.

DUMPMSGS|NODUMPMSGS

DUMPMSGS—Indicates that all the specified agent receiver’s messages are written to the console in a dump format. NODUMPMSGS—Indicates that no messages are written to the console. It is the default.

Note: May be specified only with the DEFINE and SET options.ENCRYPTEDONLY|

NOENCRYPTEDONLYENCRYPTEDONLY—Specifies only encrypted data is accepted. NOENCRYPTEDONLY—Specifies that both encrypted and unencrypted data are accepted. It is the default.

Note: May be specified only with the DEFINE and SET options.

Operand Description

AGENTRCV Command: Agent Receiver Definition

50

Define and start an agent receiverIn the following example, an agent receiver named RCVTCPIP is started. RCVTCPIP listens for incoming connections on TCP/IP port 6664:AGENTRCV DEFINE NAME(RCVTCPIP) PORT(6664)

Define and start an agent receiver that accepts only encrypted dataTo define and start a TCP/IP agent receiver named CYBTCPIP that listens for incoming connections on TCP port 6665 but accepts only encrypted data, enter:AGENTRCV DEFINE NAME(CYBTCPIP) PORT(6665) ENCRYPTEDONLY

Stop an agent receiverIn the following example, an agent receiver named RCVTCPIP is stopped using either HALT or QUIESCE:AGENTRCV HALT NAME(RCVTCPIP)

orAGENTRCV QUIESCE NAME(RCVTCPIP)

Reset port numberIn the following example, the port number is changed to port 6667 for the agent receiver named RCVTCPIP:AGENTRCV SET NAME(RCVTCPIP) PORT(6667)

51

AIX_JOB Statement: Identify the Name of AIX Jobs

The AIX_JOB statement is used to identify the name of an AIX job in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use AIX jobs, you must load a workload object module. The AIX_JOB workload object module is CYBESOAX. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Refer to the JOB statement usage notes.

Example:AIX_JOB PAYDATA RUN DAILY RELEASE PAYRPT AGENT AIX_NY SCRIPTNAME /usr/data/payENDJOB

ALERTDEF Command: Define Alert

52

ALERTDEF Command: Define Alert

Defines and displays alert definitions. An Alert definition points to an Event that is automatically triggered when the Alert is processed as part of a NOTIFY statement.

TypeGeneral command.

AuthorityYou require OPER authority to issue the ALERTDEF command.

SyntaxALERTDEF {ADD|ALTER|DELETE|LIST} [ID(xxxx)] [EVENT(eventid)]

Usage notesThe Alert feature enables ESP to trigger an Event for all jobs, or only specific jobs, in an ESP Application. You can trigger the Event at different monitor points, such as time of job submission, job start time, or when a job becomes overdue at any processing stage. These correspond to the different processing points supported on the NOTIFY statement.

To use the Alert feature, take these three steps:1. Use the NOTIFY statement in an ESP Application to identify when to trigger the

Alert.2. Define the Alert with the ALERTDEF command.3. Define the Event triggered by the Alert.

Operand DescriptionADD Add an Alert definition.ALTER Alter the Event identifier of a previously defined Alert definition.DELETE Delete an Alert definition.LIST Display one or more Alert definitions. This is the default.xxxx One to four-character logical identifier of the Alert definition. This

identifier is used in conjunction with a NOTIFY statement in an ESP Procedure.

eventid Name of the Event to be automatically triggered when this Alert is invoked as a result of workload reaching a particular stage in processing, for example, jobend or failure.

53

Alerts can be defined dynamically, via Page mode, but are not retained across recycles of ESP. To ensure that Alert definitions are retained across recycles of ESP, insert the appropriate ALERTDEF commands in the ESP Workload Manager initialization parameters.

Related informationFor information on triggering Events automatically when workload reaches a particular stage in processing, see the ESP Workload Manager User’s Guide.For information on notifying users or consoles, or triggering an Event when workload reaches a particular stage in processing, see the NOTIFY statement.

Examples Define an AlertThe following ALERTDEF command defines an Alert and associates that Alert with an Event name:ALERTDEF ADD ID(INFO) EVENT(CYBER.CREATE_RECORD)

In the above example, an Alert with a logical identifier of INFO is defined and associated with an Event called CYBER.CREATE_RECORD, which is automatically triggered when the following NOTIFY statement appears in an ESP Application:NOTIFY ABEND ALERT(INFO)

Change the Event nameIn the following example, an Alert with a logical identifier of INFO is altered to associate it with a new Event—CYBER.CREATE_INFO_RECORD:ALERTDEF ALTER ID(INFO) EVENT(CYBER.CREATE_INFO_RECORD)

Display all AlertsIn the following example, all defined Alerts are displayed:ALERTDEF

Delete an AlertIn the following example, an Alert with a logical identifier of INFO is deleted.ALERTDEF DELETE ID(INFO)

Display an AlertIn the following example, an Alert with a logical identifier of INFO is displayed.ALERTDEF ID(INFO)

ALLOWUNDEF Statement: Turn Off Flagging of Undefined Symbols

54

ALLOWUNDEF Statement: Turn Off Flagging of Undefined Symbols

The ALLOWUNDEF statement is used to turn off the flagging of undefined symbols in a symbolic variable library data set.

TypeSymbolic variable library statement.

SyntaxALLOWUNDEF

RestrictionThe ALLOWUNDEF statement cannot be used in ESP Procedures.

Usage notesThe ALLOWUNDEF statement complements the FLAGUNDEF statement, which requests the flagging of undefined symbols.ALLOWUNDEF turns off the flagging so that undefined symbols can be processed without an error message being issued. By default, ESP allows undefined symbols.

Related informationFor information on flagging undefined symbols, see the FLAGUNDEF statement.

Example Turn flagging of undefined symbols on then offThe following FLAGUNDEF and ALLOWUNDEF statements turn the flagging of undefined symbols on and off: FLAGUNDEFA=%BCALLOWUNDEFB=%XY

In the above example, when ESP encounters these undefined symbols while submitting a job:• A=%BC results in an error message—flagging is on (FLAGUNDEF)• B takes on the value of %XY—flagging is off (ALLOWUNDEF).

55

ALTCAL Command: Alter Calendar Definitions

Modifies an existing calendar definition.

TypeGeneral command.

AuthorityYou require SPECIAL or CALENDARDEF authority to issue the ALTCAL command in non-SAF environments. With SAF you control access to calendars using the CALENDAR.calname resource.

Syntax{ALTCAL|ALTC} calname [LOGICAL|ABSOLUTE] [SHIFT(hh:mm)] [WEEKSTART(day)] [WORKDAYS(workday[,workday]...)]

Usage notesCybermation recommends you use absolute calendars because of their ease of use.

Related informationFor information on defining and deleting calendars, see the DEFCAL and DELCAL commands.

For information on working with calendars, see the ESP Workload Manager User’s Guide.

Operand Descriptioncalname Indicates the name of the calendar to be modified.LOGICAL/ABSOLUTE

Indicates a logical or absolute calendar. If you are modifying from an absolute calendar to a logical calendar, you need to specify both logical and SHIFT(hh:mm).

hh:mm Modifies the start time of a logical day.day Indicates the first day of the week.workday Indicates which days are to be considered workdays. Separate each

with a blank or comma.

ALTCAL Command: Alter Calendar Definitions

56

Examples Modify first day of weekIn the following example, the first day of the week is changed to MONDAY on the PAYROLL calendar.ALTCAL PAYROLL WEEKSTART(MONDAY)

Shift start time of logical dayIn the following example, each logical day on the FISCAL calendar is changed to start a 9 am. ALTCAL FISCAL SHIFT(09:00)

57

ALTEVENT Command: Alter Events

Changes certain characteristics of one or more Events. Specify any number of operands to cause multiple changes to a single Event or group of Events to which you have access.

TypeGeneral command.

AuthorityYou can only alter Events to which you have access.

SyntaxALTEVENT eventid {[CLASS(classname)]} {[CALENDAR(cal1[,cal2]...)]} {[ADD(hours,minutes)|SUBTRACT(hours,minutes)]} {[EVENTSET(evdsid)]} {[SYMLIB(sym1[,sym2]...)]} {[SYSTEM(newsys,oldsys)]}

Operand Descriptioneventid Indicates an Event identifier.Wildcard characters asterisk and hyphen (see

“Overview” at the beginning of this book.) can be used to perform masking when a group of Events are to be altered at one time.

classname Indicates a new ESP class, up to eight alphanumeric characters, the first of which must be alphabetic.

cal1 Indicates a calendar name, up to eight alphanumeric characters, the first of which is alphabetic.

cal2 Indicates a calendar name, up to eight alphanumeric characters, the first of which is alphabetic.

hours,minutes Indicates the changes you want to make to the scheduled execution times. You can add or subtract hours and minutes to compute a new set of time and date schedules. If you only want to change the time by a certain number of minutes, specify a zero in the hours field, for example, ADD(0,45).

evdsid Indicates the ID of an Event data set. This allows you to limit changes to a particular Eventset in a non-SAF environment.

sym1-sym3 Indicates one, two or three-replacement symbol-library names, separated by a blank or comma. An asterisk is permitted instead of a name if you want to change one symbol library without affecting others.

ALTEVENT Command: Alter Events

58

Usage notesUse the SYSTEM operand to change Events queued to a specific system or systems. This is required when the ESP system identifier changes.If you are altering the system ID or changing execution times, the schedule is altered at the next scheduled scan. If the Event is already scheduled on another system, it executes on that system. When the next day’s schedule is built, the new system ID is taken into account. In the same way, the schedule changes come into effect following the schedule scan. To alter other characteristics of an Event or group of Events such as JCL library:• Use the LIST command with the ALL operand in Page mode • Type EDIT• Make the required changes and then save them to a data set (for example,

CREATE)• Use the LOAD command to load the data set to ESP.Note: When the ALTEVENT command contains asterisks or a hyphen, all matching

entries are altered. If you are unsure which Events a particular command affects, use a LIST command to test the specified mask. You cannot alter the Eventset for one or more Events with the ALTEVENT command.

Related informationFor information on working with Events, see the ESP Workload Manager User’s Guide.

Examples Change the system on which Events executeIn the following example, Events in MYGROUP are altered to execute on system PROD, instead of system TEST:ALTEVENT MYGROUP.- SYSTEM(PROD TEST)

newsys Indicates an ESP system ID. This is the SYSTEM identifier to which you are changing.

oldsys Indicates an ESP system ID on which an ESP subsystem is running. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book.) can be used to perform masking. It limits changes to Events to be executed on the specified system ID. This is the SYSTEM identifier from which you are changing.

Operand Description

59

Change Event classIn the following example, Events that start with PROD.PAY have their Event class changed to PAYJOBS:ALTEVENT PROD.PAY- CLASS(PAYJOBS)

Change symbol libraryIn the following example, Events in MYGROUP are altered to access symbol libraries SYSSM1 and MYSYM:ALTEVENT MYGROUP.- SYMLIB(SYSSM1,MYSYM)

Note: If you want to change the second or third SYMLIB without affecting an intervening one, specify an asterisk in the place of the unaffected SYMLIB as follows:

ALTEVENT PROD.- SYMLIB(* * PRODSYMS)

In the above example, the third SYMLIB is changed to PRODSYMS. The first and second SYMLIBS remain the same.Advance scheduled execution timeIn the following example, CYBER.EARLY’s scheduled execution time is advanced (brought forward) by 30 minutes:ALTEVENT CYBER.EARLY SUBTRACT(0,30)

Change system identifierIn the following example, the system identifier is changed from SYSA to SYSB, for all Events in Eventset CLIENT1:ALTEVENT - SYSTEM(SYSB,SYSA) EVENTSET(CLIENT1)

Change calendars referencedIn the following example, PAYROLL.JOBS’ secondary calendar is changed to reference PAYCAL3:ALTEVENT PAYROLL.JOBS CALENDAR(*,PAYCAL3)

Delay execution timeIn the following example, all of the PROD.DAILY Events have their scheduled execution time delayed by 2 hours and 30 minutes:ALTEVENT PROD.DAILY ADD(2,30)

ALTGROUP Command: Alter Groups

60

ALTGROUP Command: Alter Groups

Modifies an existing group definition.Note: ALTGROUP is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou require SPECIAL or GROUPDEF authority to issue the ALTGROUP command.

Syntax{ALTGROUP} groupname{ALTG} {[EVENTSET(eventdsid)]} {[DEPARTMENT(deptid)]} {[AUTH {(OPER)|(NOOPER)]} {[UREAD|NOUREAD]} {[RACID|NORACID]} {[CALENDAR(cal1[,cal2]...)]}

Operand Descriptiongroupname Indicates the specific name of an ESP group.eventdsid Indicates the logical identifier of the Event data base used to store Events

prefixed with the group name.deptid Indicates a department name of up to eight characters to which this group

belongs. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book.) can be used to perform masking.

OPER Indicates that Events having this group name as a prefix can contain operator commands.

NOOPER Removes the OPER attribute.UREAD Indicates that universal read access is available for any Event defined using this

group prefix.RACID Indicates that the security attributes of the group name should be used when ESP

processes an Event rather than the ID of the defining user.NORACID Indicates that the security attributes of the group name should no longer be used

when ESP processes an Event.

61

Usage notesTo set the second default calendar without affecting the setting of the first calendar, code an asterisk as the first calendar name. To nullify a calendar, specify NONE.

Examples Change the second default calendarIn the following example, GROUP’s secondary calendar is altered to reference CAL3. The first default calendar is left as is:ALTGROUP GROUP1 CALENDAR(* CAL3)

Change group attributesThe following example alters various attributes of a group:ALTGROUP GROUP27 DEPARTMENT(ACCOUNTS)- NOUREAD AUTH(NOOPER)

In the above example, GROUP27:• Is assigned to a department called ACCOUNTS• Has its universal read access removed• Has its ability to issue operator commands removed.

cal1 Indicates the name of the first default calendar, up to eight alphanumeric characters.

cal2 Indicates the name of the second default calendar, up to eight alphanumeric characters.

Operand Description

ALTSIG Command: Alter Signals

62

ALTSIG Command: Alter Signals

Alters the number of generations of a signal.

TypeGeneral command.

AuthorityYou can only alter a signal beginning with the prefix of your user ID or a group to which you have access.

SyntaxALTSIG signalname GEN(genno)

Related informationFor information on defining and working with signals, see the ESP Workload Manager Advanced User’s Guide.For information on defining and deleting signals, see the DEFSIG and DELSIG commands.

Examples Change signal, specifying groupIn the following example, CYBER.SIGNAL1 is altered to store 10 generations:ALTSIG CYBER.SIGNAL1 GEN(10)

Change signal using default groupIn the following example, DAILY_SIGNAL2 is altered to store seven generations. If the current group is PROD, then PROD.DAILY_SIGNAL2 is altered:ALTSIG DAILY_SIGNAL2 GEN(7)

Operand Descriptionsignalname Indicates a signal name in the format prefix.signalname, where

signalname is 1-16 alphanumeric characters. If the prefix is not specified, the current group prefix set by the GROUP command is used.

genno Indicates the number of generations of a signal that are to be stored.

63

ALTTJ Command: Alter Job Tracking Data

Temporarily changes selected characteristics of a tracked job. Normally tracked jobs are defined in a Job Tracking Definition Table and this command is not required.

TypeGeneral command.

AuthorityYou require UPDATE authority on the TJD.jobname resource to issue the ALTTJ command in a SAF environment.You require SCHEDULER authority or a matching ownership string to issue the ALTTJ command in a non-SAF environment.

SyntaxALTTJ jobname {[PREFIX]} {[OWNER(ownerid)]} {[TRACK|NOTRACK]} {[MODEL(modelname)]} {[INDEX(indexcount)]}

Operand Descriptionjobname Indicates the job definition or definitions to be altered. The jobname can

contain wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book), requesting that all job definitions matching the mask be altered.

PREFIX Indicates that the entry being altered is a jobname prefix entry rather than an explicit job entry.

Note: This operand is only applicable if you are not using a job tracking definition table.

ownerid Indicates an ownership string for the jobs. It consists of up to eight alphanumeric characters. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. This is valid only in non-SAF environments.

TRACK Indicates that you want the job to be tracked.NOTRACK Indicates that you do not want the job to be tracked.modelname Indicates the name of the tracking model to be associated with the job or jobs.indexcount Indicates the number of ancestors of a job that are to remain on the job index

data set.

ALTTJ Command: Alter Job Tracking Data

64

Usage notesIf the job that you have specified in the ALTTJ command is submitted from outside ESP, the tracking model will revert to its old definition.

Related informationFor information on tracking workload, see the ESP Workload Manager System Programmer's Guide.

Examples Change tracking model for group of jobsIn the following example, all jobs beginning with PA are associated with a tracking model called PAYROLL:ALTTJ PA- MODEL(PAYROLL)

Change characteristics for specific jobIn the following example, WEEKLYBK should now be tracked and be associated with a tracking model called MODEL2.ALTTJ WEEKLYBK TRACK MODEL(MODEL2)

65

ALTUSER Command: Alter User Definitions

Changes the definition of a user.Note: ALTUSER is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou must have SPECIAL or USERDEF authority to issue the ALTUSER command.

Syntax{ALTUSER|ALTU} userid [GROUP(USERID)|(groupname)|(PREFIX)] [PASSWORD(password)] [EVENTSET(eventdsid)] [HISTFILE(histfile)] [DEPARTMENT(deptid)] [AUTH( [OPER|NOOPER] [SPECIAL|NOSPECIAL] [ANY|NOANY] [SCHEDULER|NOSCHEDULER] [USERDEF|NOUSERDEF] [GROUPDEF|NOGROUPDEF] [CONNECTDEF|NOCONNECTDEF] [CALENDARDEF|NOCALENDARDEF])] [AUTHTAB(tabname)] [CALENDAR(cal1[,cal2]...)]

Operand Descriptionuserid Indicates the name of the user entry to be modified.USERID Indicates the user ID is to be used as an Event name prefix.groupname Indicates the group that is to be used as the Event name prefix.PREFIX Requests the current TSO profile data set prefix is used as the Event name

prefix.password Indicates a password of up to eight characters which is to be associated

with the user ID for accessing the ESP command through a batch job. This applies only if you are not using a security product.

ALTUSER Command: Alter User Definitions

66

eventdsid Indicates the logical identifier of the Event data base used to store Events prefixed with the user ID.

histfile Indicates the history file ID or mask to which the user has access.deptid Indicates a department name of up to eight characters to which this user

belongs. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

SPECIAL Indicates the user can access the Administrator command set of ESP.OPER Indicates Events having the user ID as a prefix can contain operator

commands.ANY Indicates the user can define and access Events with any group prefix.SCHED Allows the user to define Pnodes, tracking models and job tracking

parameters.USERDEF Indicates the user can define other users within the same department, or

department sub-group, provided they use the same Eventset. This user can define other users with equal or lesser authority than him or herself. The DEPARTMENT operand must also be used with this keyword.

GROUPDEF Indicates the user can define other groups within the same department, or department sub-group, provided they use the same Eventset. This user can define groups with equal or less authority than his or her own group, but will not be able to use the RACID option which is only available with the DEFGROUP command to a user with the SPECIAL attribute.

CONNECTDEF Indicates the user can connect any user to any group within the same department, or department sub-group.

CALENDARDEF Indicates the user can define calendars and assign their use to other users within the same department, or department sub-group.

NOSPECIAL Removes the SPECIAL attribute.NOOPER Removes the OPER attribute.NOANY Removes the ANY attribute.NOSCHED Removes the SCHED attribute.NOUSERDEF Removes the USERDEF attribute.NOGROUPDEF Removes the GROUPDEF attribute.NOCONNECTDEF Removes the CONNECTDEF attribute.tabname Indicates the name of the authorization table assigned to the user.cal1 Indicates the name of the first default calendar, up to eight characters.cal2 Indicates the name of the second default calendar, up to eight characters.

Operand Description

67

Usage notesTo set the second default calendar without affecting the setting of the first calendar, code an asterisk as the first calendar name. To nullify a calendar, specify NONE.

Examples Change a user’s attributesIn the following example, USER1’s authority attributes are changed to SPECIAL, ANY and OPER:ALTUSER USER1 AUTH(SPECIAL,ANY,OPER)

Change a user’s calendar informationIn the following example, USER2’s second default calendar is removed:ALTUSER USER2 CALENDAR(* NONE)

Allow access to history filesIn the following example, GX991 is allowed to access any history file beginning with HIST:ALTUSER GX991 HISTFILE(HIST-)

Change user’s authorization tableIn the following example, an authorization table called AT0001 is assigned to CYTR:ALTUSER CYTR AUTHTAB(AT0001)

AMNOTIFY Statement: Notify when Agent Becomes Inactive

68

AMNOTIFY Statement: Notify when Agent Becomes Inactive

The AMNOTIFY statement is valid only for an AGENT_MONITOR workload object.This statement triggers an alert or an Event when the status of the Agent monitored by AGENT_MONITOR becomes INACTIVE.

SyntaxAMNOTIFY [INACTIVE] {ALERT(alertid)|EVENT(eventname)} [USERS(userid[,userid]...)] [MAILBOX(box_name)]

Usage notesIf you specify that an Event is triggered, that Event cannot use monitor variables. If you need to use monitor variables, trigger an alert that will, in turn, trigger the Event defined within the alert definition using the ALERTDEF command.

Operand DescriptionALERT(alertid) Specifies the four-character ID of the alert that is

triggered when the status of the Agent monitored by AGENT_MONITOR becomes INACTIVE.

EVENT(eventname) Specifies the name of the Event that will be triggered when the status of the Agent monitored by AGENT_MONITOR becomes INACTIVE.

USERS(userid) Indicates up to three TSO user IDs to receive notification.MAILBOX(box_name)

Specifies the name of a mailbox that contains the destination for messages coming from the AMNOTIFY statement. Mailboxes must be defined in the MAILLIST data set. Refer to the MAILLIST data set section in the ESP Workload Manager Installation and Configuration Guide for information on the MAILLIST data set.

69

APPL Statement: Identify and Set Applications

The APPL statement is used to identify the name of an Application, and to indicate certain processing options for the Application.

SyntaxAPPL applid [WAIT] [HOLD] [POST_WHILE_WAITING|NOPOST_WHILE_WAITING] ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ [JOB_ANCESTOR_WAIT(LAST|ANY)] [NOPOST_UNTIL_READY|POST_OLDEST|NOPOST_OLDEST] ¯¯¯¯¯¯¯¯¯¯¯¯¯ [INDEX(nn)] [SAF_PROF_APPL|SAF_PROF_GROUP] ¯¯¯¯¯¯¯¯¯¯¯¯¯¯ [NOTIFY_SUBAPPL_COMPLETE] [OWNER(CENTRAL_MANAGER|manager)] ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

Operand Descriptionapplid Indicates an Application identifier up to eight-character long.

Characters must be either alphanumeric, a national character ($ # @), or an underscore (_). The first character cannot be numeric.

WAIT Indicates that concurrent processing of different generations of an Application is not permitted.

HOLD Indicates that the Application is to be generated on hold.POST_WHILE_WAITING Indicates that EXTERNAL and MANUAL jobs within the

Application are posted complete even if the Application is in:APPLWAITSUBAPPL WAITJOB_ANCESTOR_WAIT.This is the default.

Note: POST_OLDEST specified on APPL or TRACKOPT will affect the result. See POST_OLDEST/NOPOST_OLDE

NOPOST_WHILE_WAITING Indicates that EXTERNAL and MANUAL jobs within the Application are not posted complete if the Application is in:APPLWAITSUBAPPL WAITJOB_ANCESTOR_WAIT.

APPL Statement: Identify and Set Applications

70

Usage notesUse the WAIT operand to specify that an Application should not begin processing until the previous generation of the Application is complete. By default, ESP allows concurrent processing of different generations of the same Application. If you select the WAIT operand, you can use other keywords to control posting of jobs.

NOPOST_OLDEST Indicates that EXTERNAL and MANUAL jobs are posted complete in all active generations of an Application. This is the default. This overrides the TRACKOPT setting for this Application.

POST_OLDEST Indicates that EXTERNAL and MANUAL jobs are posted complete in the oldest active generation of an Application. This overrides the TRACKOPT setting for this Application.

NOPOST_UNTIL_READY Prevent each job in this Application from being marked complete until the job has been readied.

JOB_ANCESTOR_WAIT(LAST)

Prevent each job in this Application from being submitted until a previous run of the same job has completed. LAST requires that the job be complete in the previous generation. This is the default.

JOB_ANCESTOR_WAIT(ANY)

Prevent each job in this Application from being submitted until a previous run of the same job has completed. ANY requires that the job be complete in all previous generations.

INDEX(nn) Indicates the number of generations of the Application to be retained on the APPLFILE. The default is 20; the maximum allowed is 99.

SAF_PROF_GROUP Indicates that jobs within the Application are to be protected by the GROUP.groupname and GROUPX.groupname resources. This is only applicable if SAF is used for ESP security. This is the default.

SAF_PROF_APPL Indicates that jobs within the Application are to be protected by the APPL.applname.jobname and APPLX.applname.jobname resources. This is only applicable if SAF is being used for ESP security.

NOTIFY_SUBAPPL_COMPLETE

Indicates that ESP should generate a console message (that is, ESP1276) when a subApplication completes.

OWNER Indicates the name of the owning ESP Manager for Links and Tasks in this Application, if you are using Distributed Manager. Specify a valid Distributed Manager name, up to 16 alphanumeric characters in length, where the first character must be alpha or a national character. If you do not specify OWNER, the central ESP manager is the default. The owning Manager is the only one with authority to update the status of the Application.

Operand Description

71

Use the JOB_ANCESTOR _WAIT keyword when you want to allow concurrent processing of two generations of an Application but want to ensure that a previous run of a job (for example, in the prior, or in all previous generations) has completed prior to submitting the same job.The NOPOST_UNTIL_READY option prevents a job from being considered complete until it is readied (for example, all dependencies met). This is useful where a job in an Application requires the completion of a manually submitted predecessor that runs multiple times.When an EXTERNAL or MANUAL job completes and multiple generations of the Application exist, ESP must decide which generation of the Application to post the job complete in. You can use the POST_OLDEST or NOPOST_OLDEST keywords to control this, but the recommended method is to use EXTERNAL SCHEDULED('criteria') on the JOB statement. Use the INDEX operand to control the number of generations of the Application to retain on the APPLFILE. An incomplete Application is not deleted unless the number of generations exceeds 99; ESP temporarily expands the index when necessary. Only one APPL statement is allowed in an ESP Procedure. If you are running a distributed Application and you want it to be able to complete when the mainframe is unavailable, specify a Distributed Manager as the owner.

Related informationFor information on manipulating Applications, subApplications, jobs within Applications or jobs within subApplications, see the APPLJOB or AJ command.For information on displaying Applications or subApplications, see the LISTAPPL OR LAP command.For information on displaying Application file information, see the LISTAPTF command.For information on posting EXTERNAL or MANUAL jobs complete when multiple generations of an Application exist, see “Posting of external and manual jobs” in the ESP Workload Manager Advanced User’s Guide.

Examples Name an ApplicationIn the following example, the name PAYROLL is used to identify this ESP Application:APPL PAYROLL

Allow one generation at a timeIn the following example, no more than one generation of the PAYROLL Application can process at the same time:APPL PAYROLL WAIT

APPL Statement: Identify and Set Applications

72

Retain 50 generations in Index fileIn the following example, the number of generations of the PAYROLL Application retained in the ESP Application file is 50:APPL PAYROLL INDEX(50)

Process multiple generationsIn the following example:• No more than one generation of the PAYROLL Application can process at the

same time• External and manual jobs are not marked complete in any generation of the

PAYROLL A+pplication that is waiting for another generation of the same Application to complete:

APPL PAYROLL WAIT NOPOST_WHILE_WAITING

Mark externals & manuals in oldest generationIn the following example, external and manual jobs are marked complete only in the oldest active generation of the PAYROLL Application:APPL PAYROLL POST_OLDEST

Alternate Manager on weekendsThe following example defines the central ESP Manager as the owning Manager of this Payroll Application Monday to Friday, and the Distributed Manager DMCHI as the owning ESP Manager on weekends:IF TODAY('WEEKENDS') THEN DO APPL PAYROLL OWNER DMCHI ELSE DO APPL PAYROLLENDDO

Each job must wait for ancestorIn the following example, more than one generation of the PAYROLL Application can process at the same time, but each job must wait until its ancestor job (for example, in the previous generation) is complete:APPL PAYROLL JOB_ANCESTOR_WAIT(LAST)JCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1

Generate on holdThe following statement indicates that Application PAYROLL is to be generated on hold:APPL PAYROLL HOLD

73

Mark external or manual jobs completeThe following statement indicates that external and manual jobs are marked complete even if the Application is in:• APPLWAIT• SUBAPPL WAIT• JOB_ANCESTOR_WAIT.APPL PAYROLL POST_WHILE_WAITING

Specify SAF protectionThe following statement indicates that jobs within the PAYROLL Application are to be protected by the APPL.applname.jobname and APPLX.applname.jobname resources, if SAF is used for ESP security:APPL PAYROLL SAF_PROF_APPL

Notify console of subApplication completionIndicates that ESP should generate a console message when each subApplication within the PAYROLL Application completes:APPL PAYROLL NOTIFY_SUBAPPL_COMPLETEJCLLIB 'CYBER.JCL.CNTL'SUBAPPL ACCREC

APPLDISPLNAME Statement: Identify the Application Name of an Oracle Application

74

APPLDISPLNAME Statement: Identify the Application Name of an Oracle Application

The APPLDISPLNAME statement identifies an Oracle Applications application name.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

SyntaxAPPLDISPLNAME name

Tip: In Oracle Applications, the application name is part of the request definition, and is found in the Application field.

Usage notesUse either APPLDISPLNAME or APPLSHORTNAME in an ESP Workload Manager OA_JOB definition to identify an Oracle Applications application name. The short form DISPLNAME can be used in place of APPLDISPLNAME.Using either APPLDISPLNAME or APPLSHORTNAME is mandatory for OA_JOB definitions.

ExampleIdentify an Oracle Applications application nameIn the following example, the display name is Application Object Library.APPL ACC07 AGENT CYBOA OA_JOB AOL1905.AP034 PROGRAM XXCOFI RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN ENDJOB

Operand Descriptionname The application name. The name must match an existing Oracle

Applications application name. If you use delimiters, such as spaces, the name must be enclosed in single quotes. Maximum 240 characters.

75

APPLEND Statement: Perform Processing Automatically at End of Application

The APPLEND workload object is a self-completing workload object. You can use APPLEND to automatically perform processing at the end of an Application. The APPLEND object automatically succeeds any object in the Application that does not have a successor and is not a successor to the APPLEND object itself. APPLEND executes automatically after all other workload objects have completed, other than workload objects that are defined as successors to APPLEND.The APPLEND object also detects any objects inserted into an active Application. If an inserted object has no successors and it is not a successor to the APPLEND object, the APPLEND object becomes a successor to the inserted object.Only one APPLEND workload object can exist in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use the APPLEND feature, you must load a workload object module. The APPLEND workload object module is CYBESOAE. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Also refer to the JOB statement usage notes.

ExampleIn the following example, the APPLEND workload object named FRED becomes a successor to JOB2, as JOB2 has no other successors. However, job AFTERAE2 and AFTRAELA, which also do not have successors, are successors to FRED, so are not also made predecessors to it. APPL APPL1JCLLIB 'CYBER.JCL.CNTL'

JOB JOB1 RUN DAILY REL JOB2ENDJOB

JOB JOB2 RUN DAILYENDJOB

APPLEND FREDREL (AFTERAE1,AFTERAE2)SE 'APPLEND RUNNING' U(*)

APPLEND Statement: Perform Processing Automatically at End of Application

76

ENDJOB

JOB AFTERAE1 RUN DAILY REL AFTRAELAENDJOB

JOB AFTERAE2 RUN DAILYENDJOB

JOB AFTRAELA RUN DAILYENDJOB

Additional ConsiderationsThere is an additional consideration when using the APPLEND workload object.

The APPLEND object does not generate any SMF records by itself. If it has no successors, then the ESP1159I message will be the only external indication that an Application has ended (this is not new, this message is always produced whenever any Application completes). To generate an SMF record, a z/OS job will need to be run as a successor to the APPLEND object. For example:APPL EXAMPLEJCLLIB 'CYBER.JCL.CNTL'

JOB JOB1 RUN DAILYENDJOB

APPLEND TERMIN8 RELEASE TERMIN8RENDJOB

JOB TERMIN8R RUN DAILYENDJOB

Limitations of APPLENDWhen a workload object is inserted in an Application and becomes a predecessor to APPLEND, the HoldCount of the APPLEND workload object is incremented by one. However, the HC=n data in CSF is not immediately updated. Simulation will not display the relationships between the APPLEND workload object and its predecessors.

77

APPLINS Command: Insert commands and statements

This function allows the user to insert additional commands and statements into an active application. The function can be invoked as either an IW line command in CSF or as an APPLINS command entered from ESP in page mode, line mode, ESP Workstation, or in a procedure. Note: You cannot insert global statements or commands without inserting at least one

workload object.

SyntaxAPPLINS APPLICATION(applspec)|APPL(applspec) [STATEMENTS('stmt1;stmt2;...')] [SIMULATE]

Operand Descriptionapplspec Indicates the Application name. If more than one generation of

the Application is active, the relative or absolute generation of the Application (or the OLDEST keyword) must also be specified. This is in the form aaa.nnn where aaa is the Application name and nnn is the absolute generation number, or aaa.-rrr where rrr is the relative generation, zero being the most recent.

stmt1;stmt2;... Specifies the workload definition statements of ESP procedure language separated by semicolons. The entire block of statements must be enclosed in single quotes. Any single quote that is a part of a statement itself must be duplicated. If you use the STATEMENTS operand, you must include the SIMULATE operand to cause the simulation and you must omit it to cause the insertion. If you omit the STATEMENTS operand in page mode, an ISPF edit session will be started to collect statements.

SIMULATE Requests the insertion to be simulated with the statements provided in the command. The target application will not be modified. If you omit the STATEMENTS operand, the SIMULATE keyword is ignored.

APPLINS Command: Insert commands and statements

78

Usage notesIf an APPLINS command with statements is entered in the ISPF environment (in page mode), ISPF does some processing on it before passing the command to ESP. If the ISPF command delimiter is set to a semicolon (IBM default), ISPF will cut the statement block into separate commands. For this reason, using the APPLINS with STATEMENTS() in page mode requires that the ISPF command delimiter be first set to something other than a semicolon (use ISPF Setting menu). All commands and statements available in a procedure can be used with the following two exceptions:• An APPL command will be ignored and the following warning message will be

issued:==>ESP1171W APPLID STATEMENT ONLY ALLOWED ONCE

This will not affect any other commands and statements within the same insertion.• A RUN statement will be ignored because the workload object is automatically

selected.You cannot insert global statements or commands without inserting at least one workload object.Any global statements contained in the APPLINS command apply only to workload objects defined within the command. They do not apply to other workload objects defined in the target Application specified by the APPLINS command.Both the simulation and the actual insertion are based only on the statements included within the APPLINS command. No statements contained in the target Application specified by the APPLINS command are taken into consideration. The simulation correctly reflects the job definitions that are going to be generated, but it may not show exactly how the jobs will be submitted. This is because, at the time you submit the APPLINS command, the entire Application was already processed possibly containing statements affecting the inserted job. For example, if the inserted job does not specify a restart step option, the final result may depend on global statements contained in the Application.The supplied commands and statements are processed in application generation mode, with current or scheduled time set to the moment when the request was received by ESP. Thus inserting a job with: EARLYSUB NOW PLUS 1 HOUR

will be resolved to one hour after the job was inserted. Any time-sensitive language within the inserted commands and statements that will be executed later in application processing mode, for example, a LINK PROCESS, will see the same scheduled time as the rest of the application—the scheduled time of the event that created that application.

79

Example

Coding APPLINS in an application:APPL APPLINSOPTIONS RESTARTSTEPJCLLIB 'CYB1.ESPQ.TESTJCL'EXPEDITE ALLJOB AINLINK LINK PROCESS| RUN DAILY| IF TODAY('WORKDAY') THEN DO| | SEND ' INSERTING JOB IN APPLICATION AIN002.0' U(*)| | ESP APPLINS APPLICATION(AIN002.0) STATEMENTS('JOB JOBA.TWO;+| | OPTIONS RESTARTSTEP; +| | LATESUB 2PM; +| | DELAYSUB 3PM; +| | ABANDON DEPENDENCIES 4PM; +| | ABANDON RESOURCES 5PM; +| | ABANDON SUBMISSION 6PM; +| | DUEOUT EXEC 7PM; +| | DUEOUT INPUT 8PM; +| | RELEASE AINLINK; +| | AFTER AINTASK; +| | ENDJOB')| ENDDOENDJOB

Coding APPLINS in line mode:In the following example, the SIMULATE operand is used. The simulation occurs, but the job NORM1A is not inserted.--> applins appl(ain002.1) statements('job NORM1A MANUAL;endjob') simulate

job NORM1A MANUAL;endjobSIMULATION OF EVENT CYBER.AIN002 AT 13.17.54 ON FRIDAY JUNE 29TH, 2001JOBS: (NONE)NO JOBS SELECTED FOR SUBMISSION

JOB TYPE-JOBNAME--HC-RELEASESMAN SUB NORM1A 0 (NONE)

In the following example, the SIMULATE operand is not used. The job NORM1A is inserted.--> applins appl(ain002.1) statements('job NORM1A MANUAL;endjob')

APPLJOB(AJ) - Command: Controlling Applications

80

APPLJOB(AJ) - Command: Controlling Applications

Controls jobs, subApplications and Applications. The short form of this command name is AJ.For clarity, the APPLJOB command description is split into two sections—Controlling Applications, and Controlling Jobs and subApplications. You can recognize an APPLJOB command described in this section, Controlling Applications, when the first operand is ALL. If the first operand is jobspec, refer to “APPLJOB(AJ) Command: Controlling Jobs and subApplications” on page 82.

TypeGeneral command.

Syntax{APPLJOB|AJ} ALL APPL(applspec) [COMPLETE] [HOLD] [RELEASE] [UNWAIT] [OLDEST]

Operand DescriptionALL Specifies that the APPLJOB command controls an Application. It is mandatory

when you want to control an Application. If you want to control a job or a subApplication, use jobspec and refer to “APPLJOB(AJ) Command: Controlling Jobs and subApplications” on page 82.

APPL(applspec)

Specifies the Application name. If more than one generation of the Application is active, you may specify the relative or absolute generation of the Application (or the OLDEST keyword). This is in the form aaa.nnn where aaa is the Application name and nnn is the absolute generation number, or aaa.-rrr where rrr is the relative generation, zero being the current generation. This is the default.

COMPLETE Completes an Application.HOLD Holds an Application. This stops submission of jobs in the Application and

places the Application in APPLHOLD status.RELEASE Releases an Application (removes from APPLHOLD status.)UNWAIT Removes an Application from APPLWAIT status. OLDEST Performs the action on the oldest active generation of the Application.

81

Usage Note

To issue AJ command from a system console:Use the AJ command within a MODIFY command.In the following example, the current generation of the PAYROLL Application is completed:F ESP,AJ ALL COMPLETE APPL(PAYROLL.0)

Related informationFor information on Applications, see the ESP Workload Manager User’s Guide.For information on manipulating jobs and subApplications, see “APPLJOB(AJ) Command: Controlling Jobs and subApplications” on page 82.

Examples Complete current generationIn the following example, the current generation of the PAYROLL Application is completed:APPLOB ALL APPL(PAYROLL.0) COMPLETE

Complete -1 generationIn the following example, the -1 generation of the PAYROLL Application is completed:AJ ALL APPL(PAYROLL.-1) COMPLETE

Remove from APPLWAIT statusIn the following example, generation 293 of the PAYROLL Application is removed from APPLWAIT status:AJ ALL UNWAIT APPL(PAYROLL.293)

Release current generationIn the following example, the current generation of PAYROLL is released. This removes it from APPLHOLD status:AJ ALL RELEASE APPL(PAYROLL.0)

APPLJOB(AJ) Command: Controlling Jobs and subApplications

82

APPLJOB(AJ) Command: Controlling Jobs and subApplications

Controls jobs, subApplications and Applications. The short form of this command name is AJ.For clarity, the APPLJOB command description is split into two sections—Controlling Applications, and Controlling Jobs and subApplications.You can recognize an APPLJOB command described in this section, Controlling Jobs and subApplications, when the first operand is jobspec. If the first operand is ALL, refer to “APPLJOB(AJ) - Command: Controlling Applications” on page 80.

TypeGeneral command.

Syntax{APPLJOB|AJ} jobspec [LIST] [ANCESTOR(number)] [APPLICATION(applspec)] [OLDEST] {SETREASON} [REASON('string')] {BYPASS|UNBYPASS} {COMPLETE} {DROPDEP[(jobname[,jobname]...)]} {DROPRES} {HOLD[(ESP|JES)]|RELEASE[(ESP|JES)]} {INSERT} See Expanded Syntax below {READY} {REQUEST|UNREQUEST} {RESET} See Expanded Syntax below {RESUBMIT} See Expanded Syntax below {UNWAIT} [EXPEDITE] [DISPLAY] [QUIESCE] [RESUME] [STOP] [CANCEL[(DUMP|PURGE)]]

83

INSERT [PREDECESSORS(name[,name]...)] [SUCCESSORS(name[,name]...)] [ATTRIBUTES(type)] [SUBAPPL(name)] [TAG(tag)] [VERIFY|NOVERIFY] [DATASET(dsname)] [MEMBER(membername)

RESET [DROPEXEC('time')] [DELAYSUB('time')|EARLYSUB('time')] [LATESUBMIT('time')] [LATESTART('time')] [LATEEND('time')] [ABANDONRESOURCETIME('time')] [ABANDONDEPENDENCYTIME('time')]

RESUBMIT [DATASET(dsname)] [MEMBER(membername)] [JOBNAME(name)] [RRJOBID(jobid)] [USER1(userinfo)] [USER2(userinfo)] [USER3(userinfo)] [USER4(userinfo)] [ENCPARM1(encparmoperand)] [ENCPARM2(encparmoperand)] [ENCPARM3(encparmoperand)] [ENCPARM4(encparmoperand)] [ENCPARM5(encparmoperand)] [ENCPARM6(encparmoperand)] [ENCPARM7(encparmoperand)] [ENCPARM8(encparmoperand)] [ENCPARM9(encparmoperand)] [ENCPARMA(encparmoperand)] [ENCPARMB(encparmoperand)] [ENCPARMC(encparmoperand)] [FROMSTEP(stepname)] [TOSTEP(stepname)] [EXCLSTEP(stepname,...)] [VERIFY|NOVERIFY] [RESTART]

APPLJOB(AJ) Command: Controlling Jobs and subApplications

84

Operand Descriptionjobspec Specifies the job or subApplication. The jobspec operand can take any

of the following forms:• job 1-8 alphanumeric job name• job.qual 1-8 alphanumeric job name followed by 1-8

alphanumeric job qualifier• subapplid 1-8 alphanumeric subApplication identifier.If you want to control an Application, use ALL and refer to “APPLJOB(AJ) - Command: Controlling Applications” on page 80.

LIST Requests detailed information about the specified job. This is the default. If you specify LIST, APPLICATION is the only other valid operand.

ANCESTOR(number) Specifies the number of generations to go back. Can be specified as + or -; both are treated the same (for example, -2 and 2 both mean 2 generations back from current). The default is 0, meaning the current generation.

APPLICATION (applspec)

Specifies the name and generation of the Application containing the job that the APPLJOB command operates on. This operand is optional. However, it is mandatory when REQUEST, RESUB or INSERT are specified. If the job is not yet submitted, You must specify the Application name. If more than one generation of the Application is active, You may specify the relative or absolute generation of the Application (or the OLDEST keyword). This is in the form aaa.nnn where aaa is the Application name and nnn is the absolute generation number, or aaa.-rrr where rrr is the relative generation, zero being the current generation. This is the default.

OLDEST Performs the action on the oldest incomplete generation of the Application.

SETREASON Sets a User Status field to the specified string. When you specify SETREASON, you must also specify REASON. SETREASON can be abbreviated to SET.

REASON('string') Specifies a reason for a particular action to be performed. It can consist of up to 28 characters enclosed in single quotes. Use a period to reset this field. The information in this field is displayed in the User Status and Status fields of the Consolidated Status Panel.

BYPASS Indicates that a job is no longer required. As soon as the dependencies are met, the job is bypassed. Successor jobs are posted as in a normal job completion. If a job is bypassed, it can be unbypassed at any time up to submission.

UNBYPASS Indicates that a job is no longer to be bypassed.

85

COMPLETE Simulates normal completion of a job. This immediately posts successor jobs and EXTERNAL references. It can be used in a situation where the job failed, but a rerun is not necessary. The command can also be used prior to a job beginning execution.

DROPDEP (jobname) Removes predecessor relationships from a job by marking the specified predecessor dependencies as satisfied. If you specify DROPDEP without any value, all predecessor relationships are removed.

DROPRES Removes all resource requirements for this job.HOLD(ESP) Places a job not yet submitted in an ESP Workload Manager hold state.

This is the default when you use the HOLD operand.HOLD(JES) Places a submitted job into a JES hold state.RELEASE(ESP) Takes a job not yet submitted out of an ESP Workload Manager hold

state. This is the default when you use the RELEASE operand.RELEASE(JES) Takes a submitted job out of a JES hold state.INSERT Inserts the job specified into the Application specified by the APPL

operand. Refer to “INSERT” on page 86 for the INSERT operands.READY Removes all job dependencies (except resources) from a job (including

time, predecessors, manual hold).REQUEST Specifies that an on-request job is required. The job must be identified

as an on-request job by specifying the REQUEST keyword on the JOB statement in ESP procedure. A job can be requested or unrequested up to the time of submission. If it is not requested at the time of submission, the job is bypassed. Normal end is signaled to successor jobs.

UNREQUEST Specifies that an on-request job is no longer required. The job must be identified as an on-request job by specifying the REQUEST keyword on the JOB statement in ESP procedure. A job can be requested or unrequested up to the time of submission. If it is not requested at the time of submission, the job is bypassed. Normal end is signaled to successor jobs.

RESET Resets a time associated with a job. Refer to “RESET” on page 87 for the RESET operands.

RESUBMIT Specifies the job is to be resubmitted. Refer to “RESUBMIT” on page 88 for the RESUBMIT operands.

UNWAIT Removes a job, or subApplication, from wait status when it is waiting on a previous generation of the same job (job ancestor wait), or subApplication (sub-appl wait).

DISPLAY Displays the JES status of a job.

Operand Description

APPLJOB(AJ) Command: Controlling Jobs and subApplications

86

INSERTInserts the job specified into the Application specified by the APPL operand.

Note: Alternatively, you can use the APPLINS command to insert jobs in Applications. The APPLINS command gives you additional capabilities.

EXPEDITE Expedites a job manually. Requires the ESP Workload Manager High Performance Option (HPO).

QUIESCE Quiesces an executing job on a goal mode system. This operand is available only if HPO is installed.

RESUME Resumes the original service class of an executing job on a goal mode system. This operand is available only if HPO is installed.

STOP Issues a z/OS STOP command on an executing job. The job step will terminate only if it is programmed to respond to a STOP command.

CANCEL[(DUMP|PURGE)]

Cancels an executing job, and optionally purges it or requests a dump.

Operand Description

Operand DescriptionPREDECESSORS (joblist)

Specifies the predecessor jobs. It can only be used in conjunction with the INSERT keyword. The default is none.joblist specifies the job names to be used for an insert request. A maximum of 50 job names can be specified. The job names can have a conditional relationship associated with them as follows:• (jobname(cond),jobname, jobname(cond),...)Where jobname is the name of a job and cond is a conditional relationship as follows:• U—insert on unconditional completion• N—insert on normal completion only (default)• A—insert on abnormal completion only.

SUCCESSORS (joblist) Specifies the successor jobs. It can only be used in conjunction with the INSERT keyword. The default is none.joblist specifies the job names to be used for an insert request. A maximum of 50 job names can be specified. The job names can have a conditional relationship associated with them as follows:(jobname(cond),jobname, jobname(cond),...)Where jobname is the name of a job and cond is a conditional relationship as follows:U—insert on unconditional completionN—insert on normal completion only (default)A—insert on abnormal completion only.

87

RESETResets a time associated with a job. The times that can be reset are:

• DROPEXEC• DELAYSUB/EARLYSUB• LATESUBMIT• LATESTART• LATEEND• ABANDONRESOUCETIME• ABANDONDEPENDENCYTIME

ATTRIBUTES(type) Specifies the attributes of the job. The following are valid: JOB, TASK, LINK, CONDITIONAL, HOLD, REQUEST, MANUAL, and EXTERNAL. The default is JOB. It can only be used in conjunction with the INSERT keyword.

SUBAPPL(subappl) Inserts the job as a member of the specified subApplication.TAG(tag) Associates the specified tag with the inserted job.VERIFY Verifies that a data set and member exist by opening and closing it.NOVERIFY Does not verify that a data set and member exist. DATASET(dsname) Specifies an explicit JCL library name (may include member name).

Note: If, when resubmitting an inserted job, you specify a JCL library name, the JCL library that you supply in the RESUBMIT DATASET operand will continue to be used for future resubmits. To revert to the original JCL library, specify an asterisk in the RESUBMIT DATASET operand. This applies to the resubmit where you code the asterisk and to any future resubmits.

MEMBER(membername)

Specifies an explicit overriding JCL member name.

Operand Description

Operand DescriptionDROPEXEC('time') Specifies a time after which a job is not to be submitted. This time

corresponds to the time specified with the ABANDON SUBMISSION statement.

DELAYSUB | EARLYSUB('time')

Specifies a time before which a job is not to be submitted. This time corresponds to the time specified with the DELAYSUB or EARLYSUB statements.

LATESUBMIT('time') Specifies a time at which, if a job has not been submitted, it is to be considered overdue. This corresponds to the LATESUB time.

APPLJOB(AJ) Command: Controlling Jobs and subApplications

88

RESUBMITSpecifies the job is to be resubmitted. The last data set from which the job was submitted is used, unless you use the DATASET keyword to specify an alternate data set.

LATESTART('time') Specifies a time at which, if a job has not started executing, it is to be considered overdue. This corresponds to the DUEOUT INPUT time.

LATEEND('time') Specifies a time at which, if a job has not ended execution, it is to be considered overdue. This corresponds to the DUEOUT EXEC time.

ABANDON RESOURCETIME ('time')

Specifies a time at which any resources for which a job is waiting are to be ignored, and the job is dropped from the Resource Manager’s control and readied. This time corresponds to the time specified with the ABANDON RESOURCES statement.

ABANDON DEPENDENCYTIME ('time')

Specifies a time at which any predecessors for which a job is waiting are ignored, and the job is readied for submission. This time corresponds to the time specified with the ABANDON DEPENDENCIES statement.

Operand Description

Operand DescriptionDATASET(dsname) Specifies an explicit JCL library name from which a job is to be

resubmitted (may include member name). The last data set from which the job was submitted is used, unless you use the DATASET operand to specify an alternate data set.

Note: If, when resubmitting an inserted job, you specify a JCL library name, the JCL library that you supply in the RESUBMIT DATASET operand will continue to be used for future resubmits. To revert to the original JCL library, specify an asterisk in the RESUBMIT DATASET operand. This applies to the resubmit where you code the asterisk and to any future resubmits.

Note: With the exception of RESUBMIT, entering an asterisk in the DATASET operand has the same effect as entering a blank.

MEMBER (membername)

Specifies a member name of the JCL data set for resubmission of the job.

JOBNAME(name) Specifies the job name for rerun, if different from the original job name.RRJOBID(jobid) Specifies the JES job number of the job being rerun. It can only be used

for jobs being restarted using ESP Encore. By default, this corresponds to the previous run of the job.

89

Usage notesThe APPLJOB command can be used to manipulate jobs and subApplications. The keywords that can be used with subApplications are:• BYPASS and UNBYPASS• REQUEST and UNREQUEST• HOLD and RELEASE• COMPLETE• READY• UNWAITIf an EXTERNAL job is marked complete in the home Application, ESP Workload Manager marks that job complete in all other active Applications to which the job belongs.The APPLJOB command can be issued from a system console to complete an entire Application, or a job within an Application. This functionality requires USERMOD 35 and is restricted to complete an entire Application, or a job within an Application.

USER1(userinfo)Also applies to USER2 to USER4

Specifies user data for resubmitted jobs. These are passed to the USER1-USER4 ESP symbolic variables. Initially these variables are set to a null string (' ').Up to 68 characters of information can be specified for each value.

ENCPARM1(encparmoperand)Also applies to ENCPARM2 to ENCPARMC

Specifies an operand of the ENCPARM command. Up to 60 characters of information can be specified for each operand.

FROMSTEP (stepname)

Specifies the first step of the job to be rerun. Use (stepname.procstepname) for steps within a procedure. Can only be used with ESP Encore.

TOSTEP(stepname) Specifies the last step of the job to be rerun. Use (stepname.procstepname) for steps within a procedure. The default is the last step. Can only be used with ESP Encore.

VERIFY Verifies that a data set and member exist by opening and closing it. NOVERIFY Does not verify that a data set and member exist. EXCLSTEP(stepname,...)

Excludes a specific step or a list of specific steps from the list specified with FROMSTEP and TOSTEP. You can exclude a maximum of 100 steps.

RESTART Restarts the job using ESP Encore. It can only be used in conjunction with the RESUB function.

Operand Description

APPLJOB(AJ) Command: Controlling Jobs and subApplications

90

To issue AJ command from a system console:Use the AJ command within a MODIFY command.In the following example, PAYJOB16 is completed.F ESPM,AJ PAYJOB16 COMPLETE APPL(PAYROLL.0)

Related informationFor information on Applications, see the ESP Workload Manager User’s Guide.For information on manipulating entire Applications, see the “APPLJOB(AJ) - Command: Controlling Applications” on page 80.

Examples:

Obtaining detailed information about a jobThe following AJ command requests a detailed display of job JOB001 that has the job qualifier J1 and the job number 142255 in Application APPL001, generation 4.APPLJOB JOB001.J1(142255) LIST APPLICATION(APPL001.4)

The following is a sample response:Job=JOB001.J1(142255), Started, Step=1 Submitted ................ 2003/12/04 16:51 Started .................. 2003/12/04 16:51 Expected completion ...... 2003/12/04 16:51 Class=C, Priority=7, Step=STEP1, SrvClass=JES, SysName=SYSC, Sysplex=SYSAPLEX, Asid=0023, SmfId=SYSC, JesNode=NODEA, EspProc=CYBUSR1.ESPPROC(PROC001)

Successors: Job=JOB002.J2, PredWait, Hold=1, Job=JOB003.J3, PredWait, Hold=1

Resources: 3 RES001

Appl=APPL001.4 Scheduled ................ 2003/12/04 16:51 Built .................... 2003/12/04 16:51 DueOutPropagation, Event=CYBUSR1.EVENT001, TrigUser=CYBUSR1

The following AJ command requests a detailed display of job JOB003 that has the job qualifier J3 in Application APPL001, generation 4.APPLJOB JOB003.J3 LIST APPLICATION(APPL001.4)

91

Job=JOB003.J3, PredWait, Hold=1 Expected completion ...... 2003/12/04 17:02 EspProc=CYBUSR1.ESPPROC(PROC001)

Predecessors: Job=JOB001.J1(42255), Started, Step=1

Successors: Job=JOB004.J4, PredWait, Hold=2

Resources: 3 RES001

Enqueues: Shr ENQRES01, Excl ENQRES02, Shr ENQRES03, Excl ENQRES4, Shr ESPENQ_JOB(JOB001.J1)_APPL(-.-), Shr ESPENQ_JOB(JOB002.J2)_APPL(-.-), Excl ESPENQ_JOB(JOB003.J3)_APPL(APPL001.4)

Appl=APPL001.4 Scheduled ................ 2003/12/04 16:51 Built .................... 2003/12/04 16:51 DueOutPropagation, Event=CYBUSR1.EVENT01, TrigUser=CYBUSR1

Changing jobsSet the User Status FieldThe following AJ command sets the User Status Field:AJ PAYJOB17 SETREASON REASON('WAITING FOR TAPE') - APPL(PAYROLL.0)

In the above example, the User Status Field for PAYJOB17 indicates that the job is waiting for a tape.Reset a delayed submission timeThe following AJ command resets a job delayed submission time:AJ PAYJOB7 RESET DELAYSUB('9PM') APPL(PAYROLL.0)

In the above example, PAYJOB7’s delayed submission time is reset to 9 pm.

Requesting or holding jobsRequest a jobThe following AJ command requests a job:AJ PAYJOB1 REQUEST APPL(PAYROLL.0)

APPLJOB(AJ) Command: Controlling Jobs and subApplications

92

In the preceding example, PAYJOB1 is requested in the current generation of the PAYROLL Application.Hold a job by job nameThe following AJ command holds a job by job name:AJ PAYJOB3 HOLD APPL(PAYROLL.0)

In the above example, PAYJOB3 is held.Hold a job with a reasonThe following AJ command holds a job with a reason:AJ PAYJOB8 HOLD REASON('WAITING FOR TAPE 09999') - APPL(PAYROLL.0)

Release a job and reset the reasonThe following AJ command releases a job and resets the reason field to null: AJ PAYJOB8 RELEASE REASON(.) APPL(PAYROLL.0)

Display the JES status of a jobThe following AJ command displays the JES status of job MYJOB that has the qualifier J1. This job is part of Application MYJOB generation 39. The system response is below the command. AJ MYJOB.J1 APPL(MYJOB.39) DISPLAY$DJ(60211),JM=MYJOB$HASP890 JOB(MYJOB) STATUS=(AWAITING EXECUTION),CLASS=C,$HASP890 PRIORITY=10,SYSAFF=(ANY),HOLD=(JOB)

Requesting or bypassing subApplicationsRequest a subApplicationThe following AJ command requests a subApplication: AJ REQJOBS REQUEST APPL(PAYROLL.0)

In the above example, a subApplication called REQJOBS is requested. Each REQUEST job in this subApplication is requested. This eliminates the need to request each job individually.Bypass a subApplicationThe following AJ command bypasses a subApplication:AJ PAYJOBS BYPASS APPL(PAYROLL.0)

In the above example, a subApplication called PAYJOBS is bypassed. This indicates that all remaining jobs in this subApplication are no longer required.

93

Inserting jobsInsert a job into an ApplicationThe following AJ command inserts a job into an Application: AJ PAYJOB4 INSERT APPL(PAYROLL.293) -PREDECESSORS(PAYJOB3) SUCCESSORS(PAYJOB5)

In the above example, PAYJOB4 is inserted into generation 293 of the PAYROLL Application. It runs after PAYJOB3 completes successfully, but before PAYJOB5.Insert a job on holdThe following AJ command inserts a job on hold:AJ PAYJOB9 INSERT ATTRIBUTES(HOLD) APPL(PAYROLL.0)

In the above example, PAYJOB9 is inserted on hold into the current generation of the PAYROLL Application. Insert a job with time dependencyThe following series of AJ commands insert a job with a time dependency:AJ PAYJOB19 INSERT ATTRIBUTE(HOLD) APPL(PAYROLL.0)AJ PAYJOB19 RESET DELAYSUB('9PM') APPL(PAYROLL.0)AJ PAYJOB19 RELEASE APPL(PAYROLL.0)

In the above example, PAYJOB19 is inserted on hold into the current generation of the PAYROLL Application. PAYJOB19's submission time is set to 9 pm and it is then released from hold.Insert a job with one predecessorThe following AJ command inserts a job into an Application with one predecessor:AJ PAYJOB13 INSERT APPL(PAYROLL.0) - PREDECESSORS(PAYJOB11(U))

In the above example, PAYJOB13 is inserted into the current generation of the PAYROLL Application. It runs after PAYJOB11 completes, whether or not it is successful. Insert a link into an ApplicationInsert a linkThe following AJ command inserts a link into an Application:AJ LINKIT INSERT APPL(PAYROLL.0) -PREDECESSOR(PAYJOB14) SUCCESSOR(PAYJOB15) - ATTRIBUTE(LINK)

In the above example, a link called LINKIT is inserted into the current generation of the PAYROLL Application. It runs after PAYJOB14 completes successfully, but before PAYJOB15.

APPLJOB(AJ) Command: Controlling Jobs and subApplications

94

Insert a job with two predecessorsThe following AJ command inserts a job with two predecessors into an Application:AJ PAYJOB12 INSERT PREDECESSORS(PAYJOB10,PAYJOB11) - APPL(PAYROLL.0)

In the above example, PAYJOB12 is inserted into the current generation of the PAYROLL Application. It runs after PAYJOB10 and PAYJOB11 complete successfully.Insert a task into an ApplicationThe following AJ command inserts a task into an Application:AJ REPORT.BALANCE INSERT APPL(PAYROLL) - PREDECESSORS(PAYJOB6) ATTRIBUTES(TASK)

In the above example, a task called REPORT.BALANCE is inserted into the current generation of the PAYROLL Application. It runs after PAYJOB6 completes successfully.

Resubmitting jobsResubmit a jobThe following AJ command resubmits a job:AJ PAYJOB18 RESUB RESTART APPL(PAYROLL.0)

In the above example, PAYJOB18 is resubmitted and ESP Encore is used.Resubmit a job and select which steps are rerunThe following AJ command resubmits a job and selects which steps are rerun:AJ PAYJOB2 APPL(PAYROLL.0) RESTART RESUB -FROMSTEP(STEP020) TOSTEP(STEP060) -EXCLSTEP(STEP0030 STEP0050)

The AJ command reruns only the steps marked with an asterisk. PAYJOB2 has the following steps:• STEP005• STEP020 *• STEP030• STEP040 *• STEP050• STEP060 *• STEP070

95

Resubmit a job from a different libraryThe following AJ command resubmits a job from a different library:AJ PAYJOB2 RESUB APPL(PAYROLL.0) - DATASET('CYBER.COPY.JCL')

In the above example, PAYJOB2 is resubmitted from CYBER.COPY.JCL.Resubmit a job with a variableThe following AJ command resubmits a job using original JCL library. The character string ',RESTART=STEP20' is passed to the JCL as the USER1 variable.AJ PAYJOB10 RESUB USER1(',RESTART=STEP20') - APPL(CYBER1)

The following is a sample jobcard and the corresponding jobcard used for resubmission:PAYJOB10 JOB...MSGCLASS=X%USER1

resolves to:PAYJOB10 JOB...MSGCLASS=X,RESTART=STEP20

Resubmit a job and pass a run type operand to a restart program PAYJOB11 is resubmitted using the USER2 symbolic variable. It is used to pass a run type operand to a restart program. For the first run of the job, the run type operand is P; on the resubmit of the job, the run type operand is R.In the JCL: //STEP1 EXEC UCC11RMS,RUNTYPE='%USER2'In the ESP Procedure or Symbol Library: IF USER2='' THEN USER2='P'On Resubmit: AJ PAYJOB11 RESUB USER2('R') APPL(PAYROLL)

APPLSHORTNAME Statement: Identify the Application Short Name for an Oracle Application

96

APPLSHORTNAME Statement: Identify the Application Short Name for an Oracle Application

The APPLSHORTNAME statement identifies an Oracle Applications application short name.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

SyntaxAPPLSHORTNAME name

Usage notesUse either APPLSHORTNAME or APPLDISPLNAME in an ESP Workload Manager OA_JOB definition to identify an Oracle Applications application name.The short form SHORTNAME can be used in place of APPLSHORTNAME.Using either APPLSHORTNAME or APPLDISPLNAME is mandatory for OA_JOB definitions.

ExampleIdentify an Oracle Applications application nameIn the following example, the Oracle Applications application short name is ACCOUNTS.APPL ACC08 AGENT CYBOA OA_JOB AOL1805.AP444 PROGRAM XXCOFI RUN DAILY APPLSHORTNAME ACCOUNTS RESPNAME ‘System Administrator’ OAUSER SYSADMIN ENDJOB

Operand Descriptionname The application short name. The name must match an existing

Oracle Applications application short name. If you use delimiters, such as spaces, the name must be enclosed in single quotes. Maximum 50 characters.

97

ARCCLIENT Statement: Specify SAP Archive Link Client

The ARCCLIENT statement specifies the SAP archive link client.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCCLIENT client

Usage notesYou can use the ARCCLIENT statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCCLIENT statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCCLIENT statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

Operand Descriptionclient Specifies the archive link client. It is numeric, up to three digits

in length.

ARCCONNECT Statement: Specify SAP Archive Link Communication Connection

98

ARCCONNECT Statement: Specify SAP Archive Link Communication Connection

The ARCCONNECT statement specifies the SAP archive link communication connection.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCCONNECT connection

Usage notesYou can use the ARCCONNECT statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCCONNECT statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCCONNECT statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptionconnection Specifies the archive link communication connection. It is case

sensitive and can be up to 14 valid SAP characters in length. If connection contains delimiters (such as spaces), enclose it in single quotes.

99

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 ARCCONNECT arcconnect RUN DAILYENDJOB

ARCDATE Statement: Specify SAP Archive Link Archiving Date

100

ARCDATE Statement: Specify SAP Archive Link Archiving Date

The ARCDATE statement specifies the SAP archive link archiving date.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCDATE date

Usage notesYou can use the ARCDATE statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCDATE statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCDATE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCDATE 20040408 ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800RUN DAILYENDJOB

Operand Descriptiondate Specifies the archive link archiving date. It is numeric, up to

eight digits in length. The format is yyyymmdd.

101

ARCDOCCLASS Statement: Specify SAP Archive Link Document Class

The ARCDOCCLASS statement specifies the SAP archive link document class.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCDOCCLASS doc_class

Usage notesYou can use the ARCDOCCLASS statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCDOCCLASS statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCDOCCLASS statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptiondoc_class Specifies the archive link document class. It is case sensitive

and can be up to 20 valid SAP characters in length. If doc_class contains delimiters (such as spaces), enclose it in single quotes.

ARCDOCCLASS Statement: Specify SAP Archive Link Document Class

102

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCDOCCLASS arcdocclass ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

103

ARCDOCTYPE Statement: Specify the SAP Archive Document Type

The ARCDOCTYPE statement specifies the document type(s) used by the SAP external system archive.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax ARCDOCTYPE doc_type

Usage notesUse the ARCDOCTYPE statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCDOCTYPE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.ARCDOCTYPE corresponds to the Doc. type field on the Define Background Archive Parameters dialog.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST ARCDOCTYPE ARCHIVEENDJOB

Operand Descriptiondoc_type Specifies the name of the document type. doc_type is case

sensitive and can be up to 10 valid SAP characters in length.Note: If the SAPUSER statement is used, the doc_type default

value is the archiving operand of the SAP system user specified in the SAPUSER statement.

ARCFORMAT Statement: Specify SAP Archive Output Format

104

ARCFORMAT Statement: Specify SAP Archive Output Format

The ARCFORMAT statement specifies the SAP archive output format.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCFORMAT output_format

Usage notesYou can use the ARCFORMAT statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCFORMAT statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCFORMAT statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCFORMAT arcformat ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

Operand Descriptionoutput_format Specifies the archive output format. It is case sensitive and can

be up to 16 valid SAP characters in length. If output_format contains delimiters (such as spaces), enclose it in single quotes.

105

ARCHOSTLINK Statement: Specify SAP Archive Link RPC Host

The ARCHOSTLINK statement specifies the SAP archive link RPC host.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCHOSTLINK host

Usage notesYou can use the ARCHOSTLINK statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCHOSTLINK statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCHOSTLINK statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptionhost Specifies the archive link RPC host. It is case sensitive and can

be up to 32 valid SAP characters in length. If host contains delimiters (such as spaces), enclose it in single quotes.

ARCHOSTLINK Statement: Specify SAP Archive Link RPC Host

106

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCHOSTLINK rpchost ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

107

ARCINFO Statement: Specify the SAP Archive Link Information

The ARCINFO statement specifies the archive link information for the SAP external archive system.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax ARCINFO arcinfo

Usage notesUse the ARCINFO statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCINFO statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST ARCINFO INFENDJOB

Operand Descriptionarcinfo Specifies the archive link information. arcinfo is case sensitive

and can be up to three valid SAP characters in length.Note: If the SAPUSER statement is used, the arcinfo default

value is the archiving operand of the SAP system user specified in the SAPUSER statement.

ARCMODE Statement: Specify the SAP Archive Mode

108

ARCMODE Statement: Specify the SAP Archive Mode

The ARCMODE statement specifies the archive mode used by the SAP external archive system.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax ARCMODE PRINT|ARCHIVE|BOTH

Usage notesUse the ARCMODE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.Use the ARCMODE statement before the first ABAPNAME statement to set the default value for subsequent steps.ARCMODE corresponds to the SAPGUI Spool options, Archiving mode field on the Background Print Parameters dialog.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST ARCMODE PRINTENDJOB

Operand DescriptionPRINT Default. Specifies that spool output is to be printed.ARCHIVE Specifies that spool output is to be archived.BOTH Specifies that spool output is to be printed and archived.

109

ARCOBJNAME Statement: Identify Name of SAP Archiving Object

The ARCOBJNAME statement identifies the name of an archiving object defined on the SAP system.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within an SAPA_JOB workload object.

SyntaxARCOBJNAME ’object_name’

Usage notesARCOBJNAME is a required statement within an SAPA_JOB workload object.

ExampleIn this example, the archiving object is named BC_ARCHIVE.APPL DATESTSAPA_JOB DATEST AGENT SAPHTAGENT ARCMODE BOTH PRINTDEST LP01 ARCOBJNAME ‘BC_ARCHIVE’ ARCOBJVARIANT ‘BC_ARCVARIANT’ RUN DAILYENDJOB

Operand Descriptionobject_name Specifies the name of the archiving object. It is case sensitive

and can be up to 10 valid SAP characters in length.

ARCOBJTYPE Statement: Specify SAP External System Archive

110

ARCOBJTYPE Statement: Specify SAP External System Archive

The ARCOBJTYPE statement specifies the SAP external system archive.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax ARCOBJTYPE object_type

Usage notesUse the ARCOBJTYPE statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCOBJTYPE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.ARCOBJTYPE corresponds to the Obj. type field on the Define Background Archive Parameters dialog.

Example APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST ARCOBJTYPE ARCHIVEENDJOB

Operand Descriptionobject_type Specifies the type of external system archive object. object_type

is case sensitive and can be up to 10 valid SAP characters in length.Note: If the SAPUSER statement is used, the object_type

default value is the archiving operand of the SAP system user specified in the SAPUSER statement.

111

ARCOBJVARIANT Statement: Identify Name of SAP Archiving Object Variant

The ARCOBJVARIANT statement identifies the name of an archiving object variant defined on the SAP system.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within an SAPA_JOB workload object.

SyntaxARCOBJVARIANT ’object_variant’

Usage notesARCOBJVARIANT is a required statement within an SAPA_JOB workload object.

ExampleIn this example, the archiving object variant is named BC_ARCVARIANT.APPL DATESTSAPA_JOB DATEST AGENT SAPHTAGENT ARCMODE PRINT PRINTDEST LP01 ARCOBJNAME ‘BC_ARCHIVE’ ARCOBJVARIANT ‘BC_ARCVARIANT’ RUN DAILYENDJOB

Operand Descriptionobject_variant Specifies the name of the archive object variant. It is case

sensitive and can be up to 14 valid SAP characters in length.

ARCPATH Statement: Specify SAP Standard Archive Path

112

ARCPATH Statement: Specify SAP Standard Archive Path

The ARCPATH statement specifies the SAP standard archive path.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCPATH path

Usage notesYou can use the ARCPATH statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCPATH statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCPATH statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCPATH /export/home/archive ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

Operand Descriptionpath Specifies the standard archive path. It is case sensitive and can

be up to 70 valid SAP characters in length. If path contains delimiters (such as spaces), enclose it in single quotes.

113

ARCPRINTER Statement: Specify SAP Archive Target Printer

The ARCPRINTER statement specifies an SAP archive target printer.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCPRINTER printer

Usage notesYou can use the ARCPRINTER statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCPRINTER statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCPRINTER statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCPRINTER PRT1 ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

Operand Descriptionprinter Specifies the archive target printer. It is case sensitive and can

be up to 4 valid SAP characters in length. If printer contains delimiters (such as spaces), enclose it in single quotes

ARCPROTOCOL Statement: Specify SAP Archive Storage Connection Protocol

114

ARCPROTOCOL Statement: Specify SAP Archive Storage Connection Protocol

The ARCPROTOCOL statement specifies the SAP archive storage connection protocol.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCPROTOCAL protocol

Usage notesYou can use the ARCPROTOCOL statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCPROTOCOL statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCPROTOCOL statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptionprotocol Specifies the archive storage connection protocol. It is case

sensitive and can be up to eight valid SAP characters in length. If protocol contains delimiters (such as spaces), enclose it in single quotes.

115

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCPROTOCOL prtcl12 ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

ARCREPORT Statement: Specify SAP Archive Link Report Name

116

ARCREPORT Statement: Specify SAP Archive Link Report Name

The ARCREPORT statement specifies the SAP archive link report name.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCREPORT report_name

Usage notesYou can use the ARCREPORT statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCREPORT statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCREPORT statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptionreport_name Specifies the archive link report name. It is case sensitive and

can be up to 40 valid SAP characters in length. If report_name contains delimiters (such as spaces), enclose it in single quotes.

117

ExampleIn this example, the archive report name requires single quotes because of the space.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCREPORT ’Archive Report’ ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

ARCSERVICE Statement: Specify SAP Archive Link RPC Service/Destination

118

ARCSERVICE Statement: Specify SAP Archive Link RPC Service/Destination

The ARCSERVICE statement specifies the SAP archive link RPC service /destination.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCSERVICE service

Usage notesYou can use the ARCSERVICE statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCSERVICE statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCSERVICE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptionservice Specifies the archive link RPC service/destination. It is case

sensitive and can be up to 32 valid SAP characters in length. If service contains delimiters (such as spaces), enclose it in single quotes.

119

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCSERVICE rpcdest ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

ARCSTORAGE Statement: Specify SAP Archive Link Target Storage System

120

ARCSTORAGE Statement: Specify SAP Archive Link Target Storage System

The ARCSTORAGE statement specifies the SAP archive link target storage system.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCSTORAGE storage_system

Usage notesYou can use the ARCSTORAGE statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCSTORAGE statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCSTORAGE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptionstorage_system Specifies the archive link target storage system. It is case

sensitive and can be up to two valid SAP characters in length. If storage_system contains delimiters (such as spaces), enclose it in single quotes.

121

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCSTORAGE st ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

ARCTEXT Statement: Specify SAP Archive Link Text Information Field

122

ARCTEXT Statement: Specify SAP Archive Link Text Information Field

The ARCTEXT statement specifies the SAP archive link Text Information field.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCTEXT text_field

Usage notesYou can use the ARCTEXT statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCTEXT statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCTEXT statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptiontext_field Specifies the archive link Text Information field. It is case

sensitive and can be up to 40 valid SAP characters in length. If text_field contains delimiters (such as spaces), enclose it in single quotes.

123

ExampleIn this example, the archive text requires single quotes because of the space.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCTEXT ’Archive text’ ARCMODE ARCHIVE ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO inf ARCCLIENT 800 RUN DAILYENDJOB

ARCUSER Statement: Specify SAP Archive Data Element for User

124

ARCUSER Statement: Specify SAP Archive Data Element for User

The ARCUSER statement specifies the archive data element for user.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCUSER user

Usage notesYou can use the ARCUSER statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCUSER statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCUSER statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCUSER arcuser ARCMODE BOTH ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO 123 RUN DAILYENDJOB

Operand Descriptionuser Specifies the archive data element for user. It is case sensitive

and can be up to 12 valid SAP characters in length. If user contains delimiters (such as spaces), enclose it in single quotes.

125

ARCVERSION Statement: Specify SAP Archive Version Number

The ARCVERSION statement specifies the archive version number.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxARCVERSION version

Usage notesYou can use the ARCVERSION statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the ARCVERSION statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the ARCVERSION statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptionversion Specifies the archive version. It is case sensitive and can be up

to four valid SAP characters in length. If version contains delimiters (such as spaces), enclose it in single quotes.

ARCVERSION Statement: Specify SAP Archive Version Number

126

ExampleIn this example, the version number requires single quotes because of the period.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM ARCVERSION ’4.1’ ARCMODE BOTH ARCDOCTYPE ARCHIVE ARCOBJTYPE ARCHIVE ARCINFO 123 RUN DAILYENDJOB

127

ARGDEFAULTS Statement: Pass Default Arguments

The ARGDEFAULTS statement specifies whether to pass default arguments to Oracle Applications programs.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

Syntax ARGDEFAULTS Y|N

Usage notesUse ARGDEFAULTS to pass default values for parameters not specified in an ARGS or PROGARGS statement.ARGDEFAULTS can be defined in two places.• To set ARGDEFAULTS for a specific job, include it in the job definition.• To pass default arguments for all jobs run by an Agent, ask your System

Administrator to define oa.useArgDefaults=true in the Agent parameter file.This statement is optional for OA_JOB definitions.

Operand DescriptionY Pass default values for parameters.N Do not pass default values for parameters.

ARGDEFAULTS Statement: Pass Default Arguments

128

ExampleUsing ARGDEFAULTS with PROGARGSIn this example, each program has three arguments. ARGDEFAULTS is set to Y. Thus the Agent passes default values from Oracle Applications to arguments not defined in the PROGARGS statement.In the first program, the PROGARGS statement passes values for the first and third arguments. The Agent passes a default value for the second argument.In the second program, the PROGARGS statement passes values for the second argument. The Agent passes default values for the first and third arguments.APPL ACC011 AGENT CYBOA OA_JOB AOT2805.AP035 REQUESTSET XXEXTRACTS RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN ARGDEFAULTS Y PROGDATA 1 PROGARGS X45S,,X45G PROGDATA 2 PROGARGS ,X22F, ENDJOB

129

ARGS Statement: Pass Operands

Specifies an argument string of positional operands to pass to a batch file, script, command, or program. Use ARGS when defining jobs on a UNIX, OpenVMS, and Windows platform.

TypeApplication statement.

Syntax ARGS argument [argument] ...

Usage notesThe ARGS statement is used within the boundaries of the job definition. When you want to pass many arguments, note the following:

• You can use continuation characters, such as the hyphen (-).• The maximum message size is 4 KB.• To pass spaces in an operand, enclose the operand in double quotes. • Specify multiple arguments by separating them with blank spaces.• If you specify more than one ARGS statement, the second ARGS statement

within the job definition overrides the first, with the exception of a blank character string, which is ignored.

For more information about passing data between jobs and across platforms, see the Guide to Scheduling Workload for the appropriate Agent.

ExamplePassing positional operands to a Windows batch file or programARGS "C:\Pay Data\salary.dat" 341 749

When the program runs, the operands are set as follows:

Operand Descriptionargument The string to pass to the command. You can pass multiple strings as a single

operand by enclosing them in double quotes: “parm1 parm2”.

Argument Value Passed1 C:\Pay Data\salary.dat2 341

ARGS Statement: Pass Operands

130

Passing positional operands to a UNIX script or commandAARGS "user 1" 905-555-1212 749

When the command runs, the operands are set as follows:

3 749

Argument Value Passed1 user 12 905-555-12123 749

Argument Value Passed

131

ARGS Statement (Oracle Applications): Pass Arguments

The ARGS statement identifies argument strings to be passed to an Oracle Applications Single Request.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Single Requests only.

Syntax ARGS argument1[,argument2,argument3,...argument100]

Usage notesOnly put spaces after commas if they are part of the argument you want to pass. If you are not defining an argument in the job statement, but rather want its default argument to be used, hold its place with a comma but no space (see example).This statement is optional for OA_JOB Single Request definitions.Note: To pass default values for arguments not specified in an ARGS statement, set

the ARGDEFAULTS to Y.

ExamplePass argument valuesIn this example, the ARGS statement passes values for the first, third, and fifth arguments.ARGDEFAULTS is set to Y. The Agent passes default values to the second and fourth arguments.APPL ACC010 AGENT CYBOA OA_JOB AOL2205.AP034 PROGRAM XXCOFI RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’

Operand Descriptionargument Specifies a positional parameter of up to 240 characters. You can list up to

100 parameters, separated by commas.

Note: If your list of arguments is over the total maximum of 4 070 characters, split it into multiple ARGS statements. These multiple statements will later be concatenated using commas.

ARGS Statement (Oracle Applications): Pass Arguments

132

OAUSER SYSADMIN DESCRIPTION ‘CONFIRMED REQ 20040808 by TYB212’ ARGS X22F,,X56R143,,X23T ARGSDEFAULTS Y ENDJOB

133

AS400_JOB Statement: Identify the Name of AS400 Jobs

The AS400_JOB statement is used to identify the name of an AS400 job in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesBy default, the member name of the JCL library used is the same as the job name. To override this, use the MEMBER statement and specify the name of the member that contains the JCL for the job. The job name must match the name specified on the job card.To use AS400 jobs, you must load a workload object module. The APPLEND workload object module is CYBESOA4. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Also refer to the JOB statement usage notes.

ExampleIn this example, the INVENTORY application consists of a job MFGDATA that runs on the OS/400 Agent.APPL INVENTORYAS400_JOB MFGDATA RUN DAILY RELEASE MFGSORT AGENT AS401 CLPNAME MFGTEST.DATA AS400LIB PRODJOBSENDJOB

AS400FILE Statement: Identify OS/400 Source Files

134

AS400FILE Statement: Identify OS/400 Source Files

The AS400FILE statement is used only when defining jobs for the OS/400 Agent to identify the OS/400 source file and member that contain the CL source for the program to run. This statement is used when the job defined is a data base application. The AS400FILE statement can be used only within the boundaries of a job definition to apply to a single job.

TypeESP Workload Manager Application Statement

SyntaxAS400FILE filename.membername

Usage notesThe AS400FILE statement is mutually exclusive with the CLPNAME and COMMAND statements.

Example Specify source file and member containing CL source of programThe following is an example containing the AS400FILE statement.AS400_JOB MRGSORT RUN DAILY AS400FILE CLSRC.BACKUP AGENT AS401ENDJOB

The CL source of the program to run is contained in the BACKUP member of the CLSRC file.

Operand Descriptionfilename Identifies the source file containing the CL source for the program. The file

name must be a valid OS/400 file name.membername Identifies the member in the source file that contains the CL source for the

program. The member name must be a valid OS/400 library name. If you do not specify a library name, the default *FIRST is used.

135

AS400LIB Statement: Specify Library Name

The AS400LIB statement is used only when defining jobs for the OS/400 agent to specify the name of the library that contains the CL program named in the CLPNAME statement, or the source file named in the AS400FILE statement. The AS400LIB statement can be used within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition, to apply to the entire Application.

TypeESP Workload Manager Application Statement

SyntaxAS400LIB libraryname

Example Specify the library containing the CL programThe following is an example containing the AS400LIB statement:AS400_JOB MFGDATA RUN DAILY RELEASE MFGSORT AGENT AS401 CLPNAME MFGTEST.DATA AS400LIB PRODJOBSENDJOB

In this example, PRODJOBS is the name of the library containing the CL program MFGTEST.DATA.

Operand Descriptionlibraryname Specifies the name of the library containing the CL program or

source file. The library name can be any valid OS/400 library name.

AUX_AS Command: Start and Stop the Auxiliary Address Space

136

AUX_AS Command: Start and Stop the Auxiliary Address Space

The AUX_AS command is the equivalent of the z/OS system START and STOP commands.

Important: AUX_AS is for exceptional situations only. You may lose tracking data when you issue the AUX_AS command. Contact Cybermation support if you are using the AUX_AS command for the first time.

Important: Before you issue the AUX_AS command, quiesce the Auxiliary Address Space with the OPER ENCPARM QUIESCE command. If you do not quiesce the auxiliary address space, some active tasks may terminate abnormally when the AUX_AS command is issued.

TypeGeneral command.

AuthorityYou require OPER authority to issue the AUX_AS command.

SyntaxAUX_AS [START|CANCEL|BOUNCE]

The command can be issued either from the page mode, or from the operator's console.

Example - Stop auxiliary address space GESPAUX

Page mode commandOPER AUX_AS CANCEL

Operand DescriptionSTART Start the Auxiliary Address Space.CANCEL Stop the Auxiliary Address Space.BOUNCE Issue an AUX_AS CANCEL command followed by a

AUX_AS START command. The Auxiliary Address Space is stopped and then started. All data in the Auxiliary Address Space is lost.

137

Operator's commandF GESP,AUX_AS CANCEL

Example - Start auxiliary address space GESPAUX

Page mode commandOPER AUX_AS START

Operator's commandF GESP,AUX_AS START

Example - Stop and start auxiliary address space GESPAUX

Page mode commandOPER AUX_AS BOUNCE

Operator's commandF GESP,AUX_AS BOUNCE

BANNER Statement: Include SAP Cover Page

138

BBANNER Statement: Include SAP Cover Page

The BANNER statement specifies whether to include an SAP cover page. The SAP cover page contains information such as recipient name, department name, and format used.

ApplicabilityESP Business Agents for SAP, Version 2.2 and higher.

Syntax BANNER Y|N|D

Usage notesUse the BANNER statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the BANNER statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.BANNER corresponds to the SAPGUI Cover sheets, SAP cover page field on the Background Print Parameters dialog.

ExamplePrinting a cover pageAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST BANNER YENDJOB

Operand DescriptionY The cover page is printed.N No cover page is printed.D Default. Cover sheet output depends on the setting of the

selected output device.

139

BANNERPAGE Statement: Include SAP Cover Page with Report

The BANNERPAGE statement specifies whether to include an SAP cover page with the report output.

ApplicabilityESP Business Agents for SAP, Version 2.2 and higher.

Syntax BANNERPAGE Y|N

Usage notesUse the BANNERPAGE statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the BANNERPAGE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.BANNERPAGE corresponds to the SAPGUI Cover sheets, Selection cover page field on the Background Print Parameters dialog.

ExamplePrinting a report cover pageAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST BANNERPAGE YENDJOB

Operand DescriptionY The report cover page is printed.N Default. No report cover page is printed.

BDC_JOB Statement: Start a Batch Input Session Job Definition (SAP)

140

BDC_JOB Statement: Start a Batch Input Session Job Definition (SAP)

The BDC_JOB statement starts a Batch Input Session (BDC) job definition in an Application.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRefer to the JOB statement syntax.

Usage notesBI is the short form of BDC_JOB.To schedule BDC jobs, you must load the workload object module CYBESOBI. Load CYBESOBI with the WOBDEF command or with the WOBDEF initialization parameter.You must include the ABAPNAME statement within a BDC_JOB workload object.You may include the following BDC statements within a BDC_JOB workload object:• BDCERRATE• BDCEXTLOG• BDCPROCRATE• BDCSYSTEMYou may include most SAP statements in a BDC_JOB workload object. For a list of SAP statements, see “SAP_JOB Statement: Start an SAP Job Definition” on page 1114.Note: You may include only one ABAP (step) in a BDC job.Refer to the JOB statement usage notes.

141

ExampleIn this example, the BDC job BDCTEST runs the ABAP BDCABAP on the SAP system.APPL BDCTESTBDC_JOB BDCTEST AGENT SAPHTAGENT ABAPNAME BDCABAP RUN DAILYENDJOB

BDCERRRATE Statement: Specify the Maximum Acceptable Error Rate (SAP)

142

BDCERRRATE Statement: Specify the Maximum Acceptable Error Rate (SAP)

The BDCERRRATE statement specifies the maximum acceptable error rate within a Batch Input Session (BDC) job.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within a BDC_JOB workload object.

SyntaxBDCERRRATE percent

Usage notesBDCERRRATE is an optional statement within a BDC_JOB workload object.

ExampleIn this example, the maximum acceptable error rate is five percent. If more than five percent of transactions contain errors, the job fails.APPL BDCTESTBDC_JOB BDCTEST AGENT SAPHTAGENT BDCERRRATE 5 ABAPNAME BDCABAP RUN DAILYENDJOB

Operand Descriptionpercent Specifies the maximum acceptable error rate in percent. percent

is numeric with a range of 0 to 100.• 0—Job fails if any transaction contains an error (default)

• 5—Job fails if more than five percent of transactions contain errors

• 100—All errors are acceptable

143

BDCEXTLOG Statement: Generate Advanced Logging of the Batch Input Session (SAP)

The BDCEXTLOG statement specifies whether to generate advanced logging of the Batch Input Session (BDC) running on the SAP system.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within a BDC_JOB workload object.

SyntaxBDCEXTLOG Y|N

Usage notesBDCEXTLOG is an optional statement within a BDC_JOB workload object.

ExampleIn this example, advanced logging of the BDC is generated.APPL BDCTESTBDC_JOB BDCTEST AGENT SAPHTAGENT BDCEXTLOG Y ABAPNAME BDCABAP RUN DAILYENDJOB

Operand DescriptionY Advanced logging is generatedN Advanced logging is not generated (default)

BDCPROCRATE Statement: Specify Minimum Acceptable Process Rate (SAP)

144

BDCPROCRATE Statement: Specify Minimum Acceptable Process Rate (SAP)

The BDCPROCRATE statement specifies the minimum acceptable process rate within a Batch Input Session (BDC) job.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within a BDC_JOB workload object.

SyntaxBDCPROCRATE percent

Usage notesBDCPROCRATE is an optional statement within a BDC_JOB workload object.

ExampleIn this example, the minimum acceptable process rate is 90 percent. If less than 90 percent of transactions are processed, the job fails.APPL BDCTESTBDC_JOB BDCTEST AGENT SAPHTAGENT BDCPROCRATE 90 ABAPNAME BDCABAP RUN DAILYENDJOB

Operand Descriptionpercent Specifies the minimum acceptable process rate in percent. It is

numeric with a range of 0 to 100.• 0—no minimum processed transactions required (default)

• 90—job fails if less than 90 percent of transactions are processed

• 100—job fails if all transactions are not processed

145

BDCSYSTEM Statement: Specify Name of Background Server Processing the Batch Input Session (SAP)

The BDCSYSTEM statement specifies the name of the background server processing the Batch Input Session (BDC) running on the SAP system.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within a BDC_JOB workload object.

SyntaxBDCSYSTEM destination

Usage notesBDCSYSTEM is an optional statement within a BDC_JOB workload object.

ExampleAPPL BDCTEST BDC_JOB BDCTEST AGENT SAPHTAGENT BDCSYSTEM dest ABAPNAME BDCABAP RUN DAILYENDJOB

Operand Descriptiondestination Specifies the name of the background server. It is case sensitive

and can be up to 32 valid SAP characters in length. If destination contains delimiters (such as spaces), enclose it in single quotes.

BEAN Statement: Specify the JNDI Name of the Stateless Session Bean (J2EE)

146

BEAN Statement: Specify the JNDI Name of the Stateless Session Bean (J2EE)

The BEAN statement specifies the JNDI name of the Stateless Session Bean.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within an EJB_JOB workload object

SyntaxBEAN bean

Usage notesBEAN is a mandatory statement within an EJB_JOB workload object.

ExampleIn this example, the CYBJK.SB job uses CybEJBTestBean as the JNDI name of the Stateless Session Bean.APPL TESTSBEJB_JOB CYBJK.SB HOLD RUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(java.lang.String) VALUE(A23)ENDJOB

Operand Descriptionbean The JNDI name of the Stateless Session Bean. bean is case

sensitive and can be up to 1024 characters.

147

BKUPEVS Command: Back Up Event Data Set

Initiates the immediate backup of an Event data set.

TypeGeneral command.

AuthorityYou require OPER authority to issue the BKUPEVS command.

SyntaxBKUPEVS eventdsid

Usage notesThe BKUPEVS command schedules an immediate backup of an Event data set. The data set is backed up to a non-VSAM data set whose name must be defined by the BKUPDSNAME operand on an EVENTSET command or initialization parameter.

Related informationFor information on defining or altering an Event Data set, see the EVENTSET parameter in the ESP Workload Manager Installation and Configuration Guide.

Example Back up immediatelyIn the following example, EVENT1 is backed up immediately:BKUPEVS EVENT1

Operand Descriptioneventdsid Indicates the identifier of the Event data set using up to eight

characters.

BKUPHIST Command: Back Up History Data Set

148

BKUPHIST Command: Back Up History Data Set

Initiates the immediate backup of a history data set.

TypeGeneral command.

AuthorityYou require OPER authority to issue the BKUPHIST command.

SyntaxBKUPHIST histfid

Usage notesThe BKUPHIST command schedules an immediate backup of a history file (HISTFILE). The data set is backed up to a non-VSAM data set whose name must be defined by the BKUPDSNAME operand on a HISTFILE command or initialization parameter.

Related informationFor information on defining or altering a History data set, see the HISTFILE parameter in the ESP Workload Manager Installation and Configuration Guide.

Example Back up immediatelyIn the following example, HIST1 is backed up immediately:BKUPHIST HIST1

Operand Descriptionhistfid Indicates the identifier of the history recording data base using up

eight characters.

149

BKUPINDX Command: Back Up Index Data Base

Initiates the immediate backup of the Index data set, set the backup schedule, or display the next scheduled backup time.

TypeAuthorized oper command.

AuthorityYou require OPER authority to issue the BKUPINDX command.

SyntaxBKUPINDX|BKUPINDX ?|BKUPINDX schedule

Usage notesThe BKUPINDX command sets the time schedule for the regular Index data set backup. The backup is made to the data set specified on the INDEX initialization parameter identified by the BACKUPDATASET parameter. If a schedule time is omitted, an immediate backup takes place.The BKUPINDX command has to be issued only once because the schedule is checkpointed. It can be reissued at any time if schedule changes are needed.Information is lost on cold start of ESP.

Related informationFor information on defining the Index data set, see the ESP Workload Manager Installation and Configuration Guide.

Examples:Back up immediatelyIn the following example, the Index data set is backed up immediately:BKUPINDX

Operand DescriptionInitiates an immediate backup when you do not include any operand.

? Requests the time of the next scheduled backup be displayed.schedule Indicates the regular backup schedule.

BKUPINDX Command: Back Up Index Data Base

150

Display scheduled backup timeIn the following example, the next scheduled backup time of the Index data set is displayedBKUPINDX ?

Schedule backup at 6 am dailyIn the following example, the Index data set is scheduled for backup at 6am every day:BKUPINDX DAILY AT 6AM

151

BKUPJNDX Command: Back Up Job Index Data Base

Initiates the immediate backup of the job index data base, set the backup schedule, or display the time of the next scheduled backup time.

TypeAuthorized oper command.

AuthorityYou require OPER authority to issue the BKUPJNDX command.

SyntaxBKUPJNDX|BKUPJNDX ?|BKUPJNDX schedule

Usage notesThe BKUPJNDX command sets the time schedule for the Job Index data set backup. The backup is made to the data set identified by the BACKUPDATASET parameter on the JOBINDEX initialization parameter. If a schedule time is omitted, an immediate backup will take place.The BKUPJNDX command has to be issued only once because the schedule is checkpointed. It can be reissued at any time if schedule changes are needed.BKUPJNDX commands can be stored in ESP’s cold start initialization parameters.Information is lost on cold start of ESP.

Related informationFor information on defining the Job Index data set, see the ESP Workload Manager Installation and Configuration Guide.

Operand DescriptionInitiates an immediate backup when you do not include any operand.

? Requests that the time of the next scheduled backup be displayed.

schedule Indicates the regular backup schedule.

BKUPJNDX Command: Back Up Job Index Data Base

152

Examples Back up immediatelyIn the following example, the Job Index data set is backed up immediately:BKUPJNDX

Display scheduled backup timeIn the following example, the next scheduled backup time of the Job Index data set is displayedBKUPJNDX ?

Schedule backup at 6 am dailyIn the following example, the Job Index data set is scheduled for backup at 6 am every day:BKUPJNDX DAILY AT 6AM

153

BKUPUDEF Command: Back Up User Definition Data Set

Initiates the immediate backup of the User Definition data set or set a backup schedule.

TypeAuthorized oper command.

AuthorityYou require OPER authority to issue the BKUPUDEF command.

SyntaxBKUPUDEF|BKUPUDEF ?|BKUPUDEF schedule

Usage notesThe BKUPUDEF command sets the time schedule for the regular User Definition data set backup. The backup is made to the data set identified by the BACKUPDATSET parameter on the USERDEF initialization parameter. If a schedule time is omitted, an immediate backup takes place.The BKUPUDEF command has to be issued only once because the schedule is checkpointed. It can be reissued at any time if schedule changes are needed. If the system is down when a backup is to take place, the backup commences as soon as ESP is restarted.BKUPUDEF commands can be stored in ESP’s cold start initialization parameters.Information is lost on cold start of ESP.

Examples Back up immediatelyIn the following example, the User Definition data set is backed up immediately:BKUPUDEF

Operand DescriptionInitiates an immediate backup when you do not include any operand.

? Requests that the time of the next scheduled backup be displayed.

schedule Indicates the regular backup schedule.

BKUPUDEF Command: Back Up User Definition Data Set

154

Display scheduled backup timeIn the following example, the next scheduled backup time of the User definition data set is displayedBKUPUDEF ?

Schedule backup at 6 am dailyIn the following example, the User definition data set is scheduled for backup at 6 am every day:BKUPUDEF DAILY AT 6AM

155

BREAK Command: Insert Breaks

Requests section breaks at specified parts of a history report to produce blank lines, a new page or subtotals. A break makes the history report easier to read and analyze.

TypeReporting command.

SyntaxBREAK field length [SPACE n] [EJECT] [SUBTOTAL]

Usage notesUse the BREAK command to define at which points in the report you want to:• Force a new page• Print any number of blank lines• Produce a subtotal.You can specify several break elements in a break section. ESP subtotals only meaningful fields such as CPUTIME and DEXCP, but not JOBNO.

Related informationFor information on history reporting, see the ESP Workload Manager User’s Guide.

Operand Descriptionfield Indicates the name of a field where you want the break to occur.

This field must have been specified in a previous DISPLAY section.

length Indicates the number of characters of the display field to be checked. When a mismatch occurs within this number of characters, a break occurs.

SPACE n Indicates n blank lines are to be printed when a section break occurs.

EJECT Requests a new page be forced when a break occurs.SUBTOTAL Requests a subtotal be printed.

BREAK Command: Insert Breaks

156

Example Produce subtotal, start new page and print blank lineThe following BREAK command is used to produce a subtotal, start a new page and print a blank line: REPORTFROM 8AM YESTERDAYCRITERIA APPLSYS EQ PAYROLLDISPLAY JOBNAME JOBNO ACCOUNT CPUTIMESORT ACCOUNT JOBNAMEBREAK ACCOUNT 3 EJECT SUBTOTALBREAK JOBNAME 2 SPACE 1ENDR

In the above example:• When the first three characters of the account name change, a subtotal is printed

and a new page started

• When the first two characters of the job name change, one blank line is left.

157

BWIP_JOB Statement: Start a Business Warehouse InfoPackage Job Definition (SAP)

The BWIP_JOB statement starts a Business Warehouse InfoPackage (BWIP) job definition in an Application.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRefer to the JOB statement syntax.

Usage notesWI is the short form of BWIP_JOB.To schedule BWIP jobs, you must load the workload object module CYBESOWI. Load CYBESOWI with the WOBDEF command or with the WOBDEF initialization parameter.You must include the INFOPACK statement within a BWIP_JOB workload object.You may include the following SAP statements within a BWIP_JOB workload object:• RFCDEST• SAPCLIENT• SAPJOBNAME• SAPLANUGAGE• SAPUSERRefer to the JOB statement usage notes.

BWIP_JOB Statement: Start a Business Warehouse InfoPackage Job Definition (SAP)

158

ExampleIn this example, BWIP job BWIPTEST runs the InfoPackage ZPAK_6C7ZW2JAXS90AK71WD1CYIN on the SAP system.APPL BWIPTESTBWIP_JOB BWIPTEST AGENT SAPHTAGENT INFOPACK ‘ZPAK_6C7ZW2JAXS90AK71WD1CYIN’ RUN DAILYENDJOB

159

BWPC_JOB Statement: Start a Business Warehouse Process Chain Job Definition (SAP)

The BWPC_JOB statement starts a Business Warehouse Process Chain (BWPC) job definition in an Application.

ApplicabilityESP Business Agents for SAP Release 5 and higher.

SyntaxRefer to the JOB statement syntax.

Usage notesWC is the short form of BWPC_JOB.To schedule BWPC jobs, you must load the workload object module CYBESOWC. Load CYBESOWC with the WOBDEF command or with the WOBDEF initialization parameter.You must include the CHAIN statement within a BWIP_JOB workload object.You may include the following SAP statements within a BWIP_JOB workload object:• RFCDEST• SAPCLIENT• SAPLANGUAGE• SAPUSERRefer to the JOB statement usage notes.

BWPC_JOB Statement: Start a Business Warehouse Process Chain Job Definition (SAP)

160

ExampleIn this example, BWPC job BWPCTEST runs the Process Chain PC_7A3929SH on the SAP system.APPL BWPCTESTBWPC_JOB BWPCTEST AGENT SAPHTAGENT CHAIN ’PC_7A3929SH’ RUN DAILYENDJOB

161

CCALENDAR Command: Specify Calendars

Used to indicate one or two calendars to be used for processing, in addition to the SYSTEM calendar. It is normally used as an Event definition command.

TypeGeneral command.

SyntaxCALENDAR calendar1[,calendar2]

Usage notesYou can use the CALENDAR command to specify up to two additional calendars for an Event, so that you can schedule Events and jobs in terms that might be unique to your calendar.If you do not specify a calendar, ESP uses the calendars assigned by default to the group or user that owns the Event.ESP merges holiday definitions in all calendars associated with an Event. When special days or periods use the same name in different calendars, ESP uses the first definition it finds. ESP searches in this order:1. The first calendar you define for the Event, or first default calendar.2. The second calendar you define for the Event, or second default calendar.3. The SYSTEM calendar.You can also use the CALENDAR command in a batch job and in Page mode to specify a calendar. You can specify one calendar only.

Related informationFor information on setting special calendars, see the ESP Workload Manager User’s Guide.For information on using calendars and using calendar terms, see the ESP Workload Manager User’s Guide.For information on defining and deleting calendars, see the DEFCAL and DELCAL commands.

Operand Descriptioncalendar1 Indicates the name of a calendar. Cal1 is searched first for any

special day, period and holiday definitions.calendar2 Indicates the name of a calendar. Cal2 is searched second for any

special day, period and holiday definitions.

CALENDAR Command: Specify Calendars

162

Examples Specify calendar for an EventThe following CALENDAR command requests that a calendar be used for an Event:EVENT ID(CYBER.FISCAL_JOBS)CALENDAR FISCALSCHEDULE FIRST DAY OF FISCAL_MONTHINVOKE 'CYBER.PROCLIB.CNTL(FISCJOBS)'ENDDEF

In the above example, CYBER.FISCAL_JOBS looks at the FISCAL calendar first to determine what 'FISCAL_MONTH means, so ESP knows when to schedule the Event. If ESP does not find FISCAL_MONTH on the FISCAL calendar, ESP then looks at the SYSTEM calendar to see if FISCAL_MONTH is defined there.Note: If FISCAL_MONTH is not defined on either calendar, you receive Event

definition errors, meaning that ESP does not permit you to save an Event that contains invalid schedule criteria.

Search calendar for holidayIn the following example, the FISCAL calendar and the SYSTEM calendar are searched for holidays:CALENDAR FISCALLISTHOL -

163

CCCHK Statement: Specify Job Processing Based on Condition Codes

The CCCHK statement allows you to specify the action that is taken if a job produces a specified condition code. CCCHK• Sets the job to a given state (OK or FAILED)• Specifies whether further processing is doneYou could use CCCHK to immediately stop a failing job regardless of the COND operands in the JCL.

SyntaxCCCHK [JOB(jobmask)|JOB(-)] [STEP(stepname)] [PROC(procstepname)] [PROGRAM(progname)] RC(num)|RC(num1:num2)|RC(Sccc)|RC(Unnnn) [OK|FAIL] [CONTINUE|STOP|ASK]

Operand Description JOB(jobmask)|JOB(-) A string that matches a job name. You can use wildcard

characters to perform masking. If you omit this operand, CCCHK matches any job name.

STEP(stepname) A stepname within a job. If you omit this operand, CCCHK matches any step name.

PROC(procstepname) A procstepname within a cataloged procedure or instream procedure. If you omit this operand, CCCHK matches any label.

PROGRAM(progname) The name of the program being executed by the step, as found in the PGM operand on the EXEC statement of the job. If you omit this operand, CCCHK matches any program name.

RC(num) A condition code of num, where num is an integer between 0 and 4095 inclusive. This is not a user abend code.

RC(num1:num2) A condition code between num1 and num2 inclusive, where num1 and num2 are integers between 0 and 4095. Value num2 must be greater than or equal to num1. These are not user abend codes.

CCCHK Statement: Specify Job Processing Based on Condition Codes

164

Usage notes

Using CCCHK with CCFAILYou can control job condition code checking with the CCCHK or CCFAIL statement. CCCHK replaces CCFAIL.If CCCHK and CCFAIL are used together, both checks are performed. If either check indicates a failure, the job is considered a failure for reason CCFAIL. The CCFAIL step (named ESPCCFCK) is not added to any job that uses CCCHK.

RC(Sccc) A system abend code, such as S0C1 or SB37. The ccc must be three hexadecimal digits.

RC(Unnnn) A user abend code, such as U0001 or U0462. The nnnn must be four decimal digits, and cannot exceed 4095.

OK If the condition code is matched, consider the job as not failed.

FAIL If the condition code is matched, consider the job as failed. CONTINUE/STOP/ASK determines whether the job continues.

CONTINUE If the condition code is matched, the job continues with the next step, whether or not the job is considered as failed or not failed.

STOP If the condition code is matched, stop the job, flush it, and issue message 453I. This message indicates the job failed with a JCL error, although there actually is no JCL error.

ASK If the condition code is matched, display message 696A and prompt the operator with the following options for handling the condition code:

• C — FAIL and CONTINUE

• S — FAIL and STOP• O — OK and CONTINUEThe operands given in the operator prompt are documented earlier in this table.

Operand Description

165

Using multiple CCCHK statementsFor a single job, you can specify any number of CCCHK statements. When several CCCHK statements are active for a single job, their effect is cumulative (unlike the CCFAIL statement). For example, one CCCHK statement might indicate a particular action, and other statements might indicate some exceptional cases.

Understanding how CCCHK worksCCCHK initialization parameters and statements can detect specified condition codes from specific jobs, steps, procsteps or programs. For example, a CCCHK statement can detect a specified condition code whenever the IEBGENER program runs.

The statement search order and statement scopeWhen each step in a job or procedure ends and produces a condition code, CCCHK initialization parameters and statements are searched for a match in the following order:

1. CCCHK statements in a job definition (searched in the order they occur)A matched statement affects the job that the statement is in.

2. CCCHK statements in an Application definition (searched in the order they occur)A matched statement affects all jobs in the Application the statement is in.

3. CCCHK initialization parameters (searched in the order they occur)A matched statement affects all jobs and Applications in the ESP Workload Manager subsystem (including proxies in a master/proxy system)

Once the first match is found, all other statements are ignored and the matching CCCHK is processed for the step.

Understanding the OK and FAIL operandsIf the first matching CCCHK statement from any step indicates FAIL, a job is considered failed, even if a subsequent matching CCCHK for that step specifies OK.If the first matching CCCHK from any step indicates OK, the job is considered OK, even if a subsequent matching CCCHK for that step specifies FAIL. However, subsequent steps could still cause the job to be considered failed.

Understanding the CONTINUE, STOP, and ASK operandsIf a step abends and it has matching CCCHK statements then• If the first matching CCCHK specifies CONTINUE, the job proceeds as usual.

Subsequent steps are still subject to matching CCCHK statements and JCL COND parameters.

• If the first matching CCCHK specifies STOP, the job stops and is flushed, even if any steps include COND=EVEN or COND=ONLY.

CCCHK Statement: Specify Job Processing Based on Condition Codes

166

Setting ESPGROUP for CCCHK in a master/proxy environmentIn a master/proxy environment, CCCHK uses the ESPGROUP initialization parameter (also known as PLEXID). If you issue CCCHK in a master/proxy environment, specify the same ESPGROUP name for all ESP Workload Manager subsystems that are part of a tracking group.

Ignoring an abendYou can use CCCHK to ignore an abend. A history is maintained of each job step that had a completion code (not a condition code), and of matching CCCHK statements with OK specified. At the end of the job, ESP Workload Manager treats the job as successful if• No other failure conditions exist• All matching CCCHK initialization parameters or statements specified OK• There were no system completion codes of the form X22

This processing has no effect on how z/OS and JES handles a job that had a step abend. Step-level monitors still see an abend as before. Use the COND operands EVEN or ONLY to run subsequent steps. LJ, LTJ, LAP, and history reporting show the abend. Alert processing considers the job successful.

Memory required by the ASK operandThe ASK operand uses a temporary X’180’ byte work area for the operator prompt and reply. In the unlikely event that the memory allocation fails, ESP Workload Manager issues message 697E and processes the job as if you had issued CCCHK using the FAIL and STOP operands.

Related informationFor information on using ESP Workload Manager to insert trailer steps into JCL to check condition codes, see the ESP Workload Manager Advanced User’s Guide.

Examples Fail with condition code greater than 0In the following example, any job in the PAYROLL Application is considered to have failed if any step within any job produces a condition code greater than 0:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'CCCHK RC(1:4095) FAILJOB PAYJOB1

167

Global and local statementsIn the following example, any job in the PAYROLL Application is considered to have failed and stops processing immediately if a condition code of greater than zero is produced. A condition code of 8 for PAYJOB2 is considered to be acceptable and processing continues for PAYJOB2:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'CCCHK RC(1:4095) FAIL STOPJOB PAYJOB2 CCCHK RC(8) OK CONTINUE

Condition code by programIn the following example, any job in the PAYROLL Application is considered to have failed and stops processing immediately if a condition code of greater than 0 is produced. A condition code of 12 produced by program IEBGENER for job PAYJOB3 is acceptable, the job is not flagged as failed, and processing continues for this job:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'CCCHK RC(1:4095) FAIL STOPJOB PAYJOB3 CCCHK PROGRAM(IEBGENER) RC(12) OK CONTINUE

Condition code on stepIn the following example, any job in the PAYROLL Application is considered to have failed and stops processing immediately if a condition code of greater than 0 is produced.If step STEP01 receives a system B37 abend for job PAYJOB4 the job is flagged as failed and processing stops immediately. Note that any subsequent step with COND=EVEN or COND=ONLY is not executed.A condition code between 1 and 12 for job PAYJOB5 produced by step STEP01, procedure step STEP020 is acceptable and the job is not flagged as failed. But if step STEP04 produces a condition code of 8, PAYJOB5 should be flagged as failed and processing stops immediately:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'CCCHK RC(1:4095) FAIL STOPJOB PAYJOB4 CCCHK STEP(STEP01) RC(SB37) FAIL STOPJOB PAYJOB5 CCCHK STEP(STEP01) PROC(STEP020) RC(1:12) OK CONTINUE CCCHK STEP(STEP04) RC(8) FAIL STOP

CCCHK Statement: Specify Job Processing Based on Condition Codes

168

Operator handles condition code by programIn the following example, any step that runs program UTIL01 in the PAYROLL Application is considered to have failed if the condition code is 12 or greater.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'CCCHK PROGRAM(UTIL01) RC(12:4095) FAIL ASKJOB PAYJOB3

ASK is specified, so for each step producing condition code 12 or greater and matching the CCCHK statement, the operator is prompted for how to handle the job as follows:ESP696 CCCHK FAIL PAYJOB3 JOB13627 UPDATE.UTIL01 CC=0012=X’00C’ Reply: C=Fail/Continue,S=Fail/Stop,O=OK/Continue

169

CCEXIT Statement: Call Exit Program when Job Completes

The CCEXIT statement is used when defining jobs for the OS/400 agent to call an exit program when the job completes. The CCEXIT statement can be used within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition, to apply to the entire application.

SyntaxCCEXIT programname

Usage notesIf an exit program is called, the job is not marked complete until the exit program completes.

Example The following is an example job definition containing a CCEXIT statement:AS400_JOB MFGDATA RUN DAILY RELEASE MFGSORT AGENT AS401 CLPNAME MFGTEST.DATA AS400LIB PRODJOBS CCEXIT IVPEXITENDJOB

In this example, IVPEXIT is the name of the exit program called when the MFGDATA job is complete.

Operand Descriptionprogramname Specify any valid exit program name.

CCFAIL Statement: Identify Failures by Condition Code

170

CCFAIL Statement: Identify Failures by Condition Code

The CCFAIL statement is used to identify which condition codes should cause ESP to consider a job as failed and prevent successor jobs from being submitted. The CCFAIL statement can be used for all jobs within an Application or for specific jobs within an Application.

SyntaxCCFAIL (stepname,operator,value)

Usage notesYou can use the CCFAIL statement as a global option for all jobs in an Application or within the scope of a job statement for an individual job. A job specific CCFAIL statement overrides the global CCFAIL statement.Multiple condition codes can be specified by separating each (stepname, operator and value) with a blank. If the specified condition codes are met, the job is flagged and a message is sent to the operator’s console and to the user ID listed in the JES NOTIFY parameter, after the job has completed. ESP treats the job as an unsuccessful completion, and holds dependent jobs.

Operand Descriptionstepname Indicates a stepname. You must use the exact job or

PROC stepname. For procs, use stepname.procstepname. An asterisk represents any step.• stepname indicates the name of a step within the job.

It refers to the label field on the EXEC statement in the JCL.

• procstepname indicates a particular step within a cataloged or instream procedure. Specifically, it refers to the label on the EXEC statement inside a cataloged procedure or an instream procedure. This operand is optional. If this operand is missing, this statement matches with any procstepname.

operator Specify valid comparison operators as follows:>= or GE<= or LE> or GT< or LT= or EQ¬= or NE

value Specifies the value of the condition code for which you want to check.

171

When ESP submits a job, it adds a trailer step to the job that executes only if the condition codes specified for failure are not met. Otherwise, the trailer step does not execute and the job fails with a JOB FAILED – JCL ERROR condition. Steps after a bad condition code execute unless you have COND parameters in the JCL to bypass them.Note: The CCFAIL statement is limited by what you can do with the COND

parameter in JCL.

Related informationFor information on checking condition codes, see the CCCHK statement.Note: ESP can control condition code checking of jobs by using either the CCFAIL

or CCCHK statement. CCCHK was developed to replace CCFAIL and is not intended for use in combination with CCFAIL. If the two statements are used together, both sets of checks are performed, and if either indicates a failure, the job is considered a failure for reason CCFAIL. CCFAIL step (named ESPCCFCHK) is not inserted into any job that uses CCCHK.

For information on using ESP to insert trailer steps into JCL to check condition codes, see the ESP Workload Manager Advanced User’s Guide.

Examples Global statementIn the following example, any job in the PAYROLL Application is considered to have failed if any step within any job produces a condition code greater than four:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'CCFAIL (*,GT,4)JOB PAYJOB1

Condition code greater than 8 on stepIn the following example, PAYJOB1 is considered to have failed if STEP004 produces a condition code greater than 8:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 CCFAIL (STEP004,GT,8)

CCFAIL Statement: Identify Failures by Condition Code

172

Fail on procstepIn the following example, PAYJOB3 is considered to have failed if procstep STEPP within job step STEPJ produces a condition code greater than 0:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 CCFAIL (STEPJ.STEPP,GT,0)

Global and local statementsIn the following example, any job in the PAYROLL Application except PAYJOB4 is considered to have failed if any step produces a condition code greater than 8. PAYJOB4 is considered to have failed if STEP002 produces a condition code greater than 4:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'CCFAIL (*,GT,8)JOB PAYJOB4 CCFAIL (STEP002,GT,4)

Note: Any condition code for the other steps in PAYJOB4 is accepted as good, because a job-specific CCFAIL statement overrides a globally-placed CCFAIL statement.

Multiple step conditionsIn the following example, any job in the PAYROLL Application except PAYJOB5 is considered to have failed if any step produces a condition code greater than 8. PAYJOB5 is considered failed if any of the following occur.• STEP001 produces a condition code greater than 8• STEP002 produces a condition code greater than 4• STEP003 produces a condition code greater than 8:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'CCFAIL (*,GT,8)JOB PAYJOB5 CCFAIL (STEP001,GT,8) (STEP002,GT,4) (STEP003,GT,8)

Note: If you don’t want the locally placed CCFAIL statement to override the globally placed CCFAIL statement, specify each step and the appropriate CCFAIL statement for that step, as coded above.

173

CELLTRC Command: Trace Storage Cell Usage

Traces storage cell usage. This can be useful when diagnosing problems involving uncontrolled storage allocation.

TypeGeneral command.

AuthorityYou require OPER authority to issue the CELLTRC command.

SyntaxCELLTRC

Usage notesA snapshot data set must first be created. This data set contains the storage cell snapshots that are generated by the CELLTRC command. The following DCB attributes should be used:DSORG=PS,RECFM=VB,LRECL=137,BLKSIZE=6144

The following DD statement must be added to the ESP subsystem cataloged procedure://CELLTRC DD DISP=SHR,DSN=celltrc.dataset

Start the subsystem with the following command. Note that the @CELLTRC keyword must be the first parameter in the PARM string. Once activated, cell tracing remains active only during the current execution of ESP. To keep cell tracing active, the @CELLTRC keyword must be used each time ESP is started:S ESP,PARM='@CELLTRC,...'

The CELLTRC command causes the subsystem to generate a storage cell snapshot and place it in the cell trace data set that is named in the CELLTRC DD statement. It may be issued from a z/OS console or from Page mode.To deactivate cell tracing, restart the subsystem without using the @CELLTRC keyword.The storage cell snapshot consists of three sections: the cell pool header display, the cell display, and the cell summary.

CELLTRC Command: Trace Storage Cell Usage

174

The cell pool header display shows the available cell size and how many of each size are currently allocated. The COUNT field indicates how many cells of a particular size are allocated, while the ACTIVITY field shows the number of gets and frees done for this cell size:SIZE 8, COUNT 0, ACTIVITY 0SIZE 16, COUNT 17, ACTIVITY 42SIZE 32, COUNT 59, ACTIVITY 104SIZE 64, COUNT 31, ACTIVITY 85SIZE 128, COUNT 32, ACTIVITY 427

The cell display describes each individual cell that is presently allocated. Its size and requestor CSECT are shown, along with up to 64 bytes of its contents. Also shown is the CSECT that called the requestor CSECT. The offset within each CSECT from which the request was made is also shown:CELL SIZE 128, REQUESTED BY CYBXI000+0054, CALLED BY CYBXR003+0CA6 +0 00039F80 00000000 000076F3 00873C54 00000000 ... +20 00039FA0 00000000 00000000 003D2448 003D2450 ...

CELL SIZE 32, REQUESTED BY CYBXI003+0CF4, CALLED BY CYBJS107+0DB8 +0 003D2448 00000000 008876F3 00000000 00000000 ...

...

Cell summaryThe cell summary lists the number of cells that are currently allocated, but arranged by requestor’s base address and requesting address, and by the requestor’s caller’s base address and calling address. The following example shows that three cells of size 32 are currently allocated, having been requested by CYBXI003 at offset 0CF4 who was called by CYBJS107 at offset 0DB8. The base address of the CYBXI003 CSECT is at 02357708, and the request was made from address 023583FC:---- STORAGE ALLOCATED BY REQUESTOR'S ADDRESSADDR 0234574C, BASE 023456F8, COUNT 1, BYTES 128 - CYBXI000+0054ADDR 023583FC, BASE 02357708, COUNT 3, BYTES 32 - CYBXI003+0CF4

---- STORAGE ALLOCATED BY REQUESTOR'S CALLER'S ADDRESSADDR 02365E38, BASE 02365080, COUNT 3, BYTES 32 - CYBJS107+0DB8ADDR 02358C36, BASE 02357F90, COUNT 1, BYTES 128 - CYBXR003+0CA6

175

Example Trace storage cell usageIn the following example, storage cell usage is generated and placed in the cell trace data set named in the CELLTRC DD statement:CELLTRC

CHAIN Statement: Identify Name of Business Warehouse Process Chain on SAP System

176

CHAIN Statement: Identify Name of Business Warehouse Process Chain on SAP System

The CHAIN statement identifies the name of a Business Warehouse Process Chain (BWPC) on the SAP system.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within a BWPC_JOB workload object.

SyntaxCHAIN ’Process_Chain’ [Simulate(Y|N)]

Usage notesCHAIN is a required statement within a BWPC_JOB workload object.

ExamplesRunning Process ChainIn this example, BWPC job BWPCTEST runs the Process Chain PC_7A3929SH on the SAP system.APPL BWPCTESTBWPC_JOB BWPCTEST AGENT SAPHTAGENT CHAIN ’PC_7A3929SH’ RUN DAILYENDJOB

Operand DescriptionProcess_Chain Specifies the name of the Business Warehouse Process Chain. It

is case sensitive and can be up to 256 valid SAP characters in length.

Simulate • Y — Simulates the specified Process Chain on the SAP system

• N — Runs the specified Process Chain on the SAP system

177

Simulating Process ChainIn this example, BWPC job BWPCTEST simulates the Process Chain PC_7A3929SH on the SAP system.APPL BWPCTESTBWPC_JOB BWPCTEST AGENT SAPHTAGENT CHAIN ’PC_7A3929SH’ Simulate(Y) RUN DAILYENDJOB

CHECKEXC Statement: Check for Exclusion Character

178

CHECKEXC Statement: Check for Exclusion Character

The CHECKEXC statement is used to indicate that ESP should check the last non-blank character of every card image written to the internal reader. If the symbolic variable representing that last non-blank character is set to a “¬” (not sign), the card image is deleted. If the symbol variable is set to blank, null, or to any other string, the card image is not deleted. The CHECKEXC statement cannot be used in an ESP Procedure.

TypeSymbolic variable library statement.

SyntaxCHECKEXC

Usage notesEnter the CHECKEXC statement anywhere in a symbolic library data set. Multiple exclusion symbols can be used. Define the symbolic variable that is to represent the last non-blank character, either in a symbol library data set, or in an ESP Procedure. The value can be a blank character, null character or any other character string.Use the symbol in your JCL wherever you want to exclude a JCL statement.Reference the symbolic variable library and ESP Procedure (if you defined the symbolic variable in an ESP Procedure) in the Event that submits the JCL.To turn the feature off, specify NOCHECKEXC.Note: The recommended method for including and excluding JCL is to use

%INCLUDE IF and %EXCLUDE IF.

Related informationFor information on turning off the checking of the last non-blank character of every card image written to the internal reader, see the NOCHECKEXC statement.For information on selectively including JCL, see the %INCLUDE statement.For information on selectively excluding JCL, see the %EXCLUDE statement.

179

Examples When X is last character, exclude card imageIn the following example, when %X appears as the last non-blank character on any card image written to the internal reader, that card image is excluded:CHECKEXCX='¬'

The following example uses the exclusion symbol (defined above) in JCL://PAYJOB1 JOB …//STEP001 EXEC PGM=ABC //STEP002 EXEC PGM=DEF%X

In the above example, when ESP submits PAYJOB1, STEP002 is excluded.Set variable on specific daysThe following CHECKEXC statement indicates that ESP should check the last non-blank character of every card image written to the internal reader, and set the value of a symbolic variable on specific days: CHECKEXCZ=' '%INCLUDE DAY(MONDAY,THURSDAY)Z='¬'%ENDINCL

In the above example, on Mondays and Thursdays, the last non-blank character of a card image is set to “¬”, excluding that card image.The following is an example of using the exclusion symbol (defined above) in JCL://PAYJOB2 JOB …//STEP001 EXEC PGM=ABC%Z//STEP002 EXEC PGM=DEF//STEP003 EXEC PGM=GHI%Z

In the above example, when ESP submits PAYJOB2 it includes:• STEP002 each time• STEP001 and STEP003 each time except on Mondays and Thursdays, because

the value of Z is set to “¬” on those days.Exclude JCL using symbolic variable library and ESP ProcedureIn the following example, CHECKEXC is specified in a symbolic variable data set to indicate that ESP should check the last non-blank character of every card image written to the internal reader:CHECKEXC

CHECKEXC Statement: Check for Exclusion Character

180

The following IF/THEN/ELSE logic is specified in an ESP Procedure to set the value of the symbolic variable:IF TODAY('FIRST WORKDAY OF MONTH') THEN FWM='¬' ELSE FWM=' '

In the above example, the value of a symbolic variable called FWM is set to “¬” on the last workday of each month.The following example uses the exclusion symbol (defined above) in JCL://PAYJOB3 JOB …//STEP001 EXEC PGM=JKL//STEP002 EXEC PGM=MNO%FWM

In the above example, when ESP submits PAYJOB3 it includes:• STEP001 each time• STEP002 each time except on the first workday of each month, because the value

of FWM is set to “¬”.

181

CHILDMONITOR Statement: Enable Monitoring of Children Jobs (SAP)

The CHILDMONITOR statement specifies whether to monitor children jobs. Children jobs are jobs spawned by a parent job.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxCHILDMONITOR Y|N

Usage notesYou can use the CHILDMONITOR statement within the SAP_JOB, BWIP_JOB, and SAPA_JOB workload objects.The CHILDMONITOR statement overrides the default setting defined by the sap.job.children.monitor parameter in the Agent parameter file (agentparm.txt).

ExampleIn this example, children spawned by SAPTEST are monitored.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT CHILDMONITOR Y ABAPNAME ZCHILDJOB1 RUN DAILYENDJOB

Operand DescriptionY Enables monitoring of childrenN Disables monitoring of children

CHILDMONITOR Statement: Enable Monitoring of Children Jobs (Oracle Applications)

182

CHILDMONITOR Statement: Enable Monitoring of Children Jobs (Oracle Applications)

The CHILDMONITOR statement specifies whether the Agent monitors the children of Oracle Applications programs. Program children are programs that are released by the parent program.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

SyntaxCHILDMONITOR Y|N

Usage notesCHILDMONITOR can be defined in two places.• To set CHILDMONITOR for a specific job, include it in the job definition. When

used in a Request Set, CHILDMONITOR applies to all of the programs in the Request Set, and cannot be specified differently for each program.

• To set the default for all jobs run by an Agent, ask your System Administrator to define the oa.default.monChildren parameter in the Agent parameter file.

Note: The Agent can monitor a maximum of five children for each job.This statement is optional for OA job definitions.

ExampleSpecify not to monitor the children of a Single Request programAPPL ACC016 AGENT CYBOA OA_JOB BFM1805.XPO34 PROGRAM XXCOFI RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN CHILDMONITOR N ENDJOB

Operand DescriptionY Monitor children.N Do not monitor children.

183

CLASS Command: Manipulate Class Queues

Displays and manipulates class queues. When an Event is defined, it can be associated with a particular class. A class is a user-defined string of up to eight characters that can be used to group Events logically together. If a class name is omitted from an Event definition, the Event name prefix is used as the class name.

TypeGeneral command.

AuthorityYou require OPER authority to issue the CLASS command.

Syntax{CLASS|CL} classname [HOLD|RELEASE] [SUSPEND|RESUME] [EXEMPT|DEEXEMPT] [RESET|FLUSH] [IGNORE|PROCESS] [LIST]

Operand DescriptionHOLD Indicates Events in classes described by the class name are placed in a hold

queue at their scheduled time. RELEASE Indicates any Events held in class queues described by the class name are

released and placed on the overdue queue. A message is issued indicating how many Events were released in each class.

SUSPEND Indicates Events in classes described by the class name are bypassed at their scheduled execution time.

RESUME Indicates the SUSPEND restriction is removed for the classes described by the class string.

EXEMPT Indicates Events in classes described by the class name are exempt from class hold or suspend restrictions.

DEEXEMPT Removes the EXEMPT restriction.RESET Removes any restrictions from the specified class name.FLUSH Indicates any Events on the specified class hold queues are flushed and will

not execute. This does not affect future scheduled executions.

CLASS Command: Manipulate Class Queues

184

Usage notesThe CLASS command allows you to manipulate a group of Events.If the CLASS command is entered with no operands, the current list of restrictions is displayed, along with the names of any class hold queues and the number of Events in each. The class restriction lists and hold queues are checkpointed and are retained across warm starts. A cold start clears all the queues and class restriction lists.The scope of the CLASS command is that of the current system only, and not of any other systems sharing the same data sets. Issue the CLASS command on each system that you want to affect.Holding a class affects active Applications by preventing any further job submission until you release the class or exempt the associated Event.If you suspend a class associated with an active Application, the Application stops processing and does not continue when you resume the class.

Related informationFor information on starting an Event definition, see the EVENT command.For information on working with ESP Events, see the ESP Workload Manager User’s Guide.For information on putting ESP into a quiesced state, see the QUIESCE command.

Examples Display all classesIn the following example, all class queues are displayed:CLASS

Hold Events with PROD classIn the following example, all Events associated with the PROD class are held:CLASS PROD- HOLD LIST

Note: By specifying LIST (above) you will receive the following message:FOLLOWING CLASSES EXEMPT(E), HELD(H) SUSPENDED(S) IGNORED(I)PROD1(S), PROD2(S)

IGNORE Indicates Events in classes described by the class name are ignored at their scheduled execution time only on the ESP system that issued the CLASS command with the IGNORE operand.

PROCESS Indicates the IGNORE restriction is removed for the classes described by the class name.

LIST Displays any class hold queues for the specified classes. This is the default.

Operand Description

185

Hold Events except **PA classIn the following example, all Event classes are held, except for those Event classes with characters PA in positions three and four:CLASS - HOLD;CLASS **PA- EXEMPT

Resume PROD classIn the following example, all Events associated with the PROD class are resumed:CLASS PROD RESUME

Suspend all but PAY classIn the following example, all Event classes are suspended, except the Event classes associated with the PAY class: CLASS - SUSPEND;CLASS PAY EXEMPT LIST

Note: By specifying LIST (above), you receive the following message:FOLLOWING CLASSES EXEMPT(E), HELD(H) SUSPENDED(S) IGNORED(I)PAY(E), -(S)

Hold multiple classesIn the following example, all Event classes CLNT1 and CLNT2 are heldCLASS (CLNT1,CLNT2) HOLD

Flush all classesIn the following example, all class hold queues are flushed and do not execute. This does not affect future scheduled executions:CLASS - FLUSH

CLEANUP Command: Delete Data Sets That Will Be Allocated by a Restarted Job

186

CLEANUP Command: Delete Data Sets That Will Be Allocated by a Restarted Job

The CLEANUP command deletes the data sets that will be allocated by a restarted job. This prevents NOT CATLGD 2 and DUPLICATE NAME ON DASD errors.You issue the CLEANUP command in the command line of the ESP Encore Restart Action Summary screen.

TypeESP Encore command

SyntaxCLEANUP

Usage notesDuring the restart analysis of a job submitted in ESP Workload Manager, ESP Encore assumes that the job's JCL is the same as during the previous run. ESP Encore gets the names of the data sets created by each step from the EXH record for the job. The restart analysis prepares a set of actions to delete data sets that currently exist and that the job would create after the user resubmits the job. The CLEANUP command enables you to delete the data sets before resubmitting.Once cleanup is done, you see a revised Restart Action Summary screen.

187

clearspool Command: Clear Agent Spool files

Used on the Windows NT platform to clear the spool files the agent software creates during its normal operation. These spool files are not cleared automatically, and should be cleared periodically using the clearspool command. The clearspool command can be scheduled by creating an ESP Workload Manager application to run clearspool periodically, or it can be run manually by issuing the clearspool command from a Windows NT command line.

TypeGeneral Command

Entering CommandThe clearspool command can be issued via:• The Windows NT command line• A script or program.

Syntaxclearspool n [DEBUG]

Usage notesThe frequency for clearing the spool files will vary, depending on your installation. We recommend that you use ESP Workload Manager to schedule the clearing of the spool files regularly at a time that is convenient. ESP Workload Manager does not limit the size of the spool files. Spool files are limited in size by the available space on the file system on which they reside. If the file system in which a spool file resides reaches its maximum size, the agent cannot continue to run.The ESPAGENTDIR environment variable must have a value to run the clearspool command. There must be a valid AgentParm file in the directory specified by ESPAGENTDIR. Refer to the ESPmgr command. If the clearspool command is scheduled through the ESP Workload Manager, $ESPAGENTDIR is already set by the agent.

Operand Descriptionclearspool This command must be typed exactly as shown on the Windows NT

platform, which is case sensitive.n Specifies the maximum number of days a spool file is maintained. All

files older than n will be cleared.DEBUG OPTIONAL Clearspool displays some messages to the console as it is

working.

clearspool Command: Clear Agent Spool files

188

ExampleClearing spool files older than 5 daysclearspool 5

In this example, all files older than 5 days will be cleared.

189

CLPNAME Statement: Identify OS/400 Programs to Run

The CLPNAME statement is used only when defining jobs for the OS/400 Agent to identify the OS/400 program to run. It is used within the boundaries of the job definition.

TypeESP Application Statement

SyntaxCLPNAME programname

Usage notesThe CLPNAME statement is mutually exclusive with the AS400FILE and COMMAND statements.

Example This example of a job definition contains the CLPNAME statement:AS400_JOB MFGDATA RUN DAILY RELEASE MFGSORT AGENT AS401 CLPNAME MFGTEST.DATA AS400LIB PRODJOBSENDJOB

In this example, MFGTEST.DATA is the name of the OS/400 program to run.

Operand Descriptionprogramname Specify the name of the program to run.

CLRSYSMS Command: Clear System Messages

190

CLRSYSMS Command: Clear System Messages

Clears system message interceptions which were defined using the SYSMSGS command.

TypeGeneral command.

AuthorityYou require OPER authority to issue the CLRSYSMS command.

SyntaxCLRSYSMS ID(xxxx)

Related informationFor information on intercepting messages written to the system message data set, see the SYSMSGS command.For information on displaying information on all system messages that are currently being intercepted by ESP, see the LSYSMSGS command.

Examples Clear intercept 0022In the following example, a system message intercept whose identifier is 0022 is cleared:CLRSYSMS ID(0022)

Clear all system message interceptsIn the following example, all system message intercepts are cleared:CLRSYSMS ID(*)

Operand Description

ID(xxxx) Indicates an identifier consisting of four alphanumeric characters to clear a specific message intercept. To clear all system message intercepts, code ID(*).

191

CMDNAME Statement: Run Agent-Platform Commands

Identifies Agent-platform commands to run when defining jobs for the Agents running on Windows and UNIX platforms.

TypeApplication statement.

Syntax CMDNAME drive:\path\name

Usage notesUse the CMDNAME statement within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition to apply to the entire application.Encryption must be active on the Agent to use the CMDNAME statement.When running a binary file using the CMDNAME statement, you must include the USER statement in the job definition. The USER statement specifies the user ID under which the command runs.

UNIX-specific notesAll UNIX_JOB job definitions require a CMDNAME statement or a SCRIPTNAME statement. Use the SCRIPTNAME statement to run shell scripts and the CMDNAME statement to run binary files.

Operand Descriptiondrive:\path\name The full path and name of the command to run.

• For Windows — The maximum length of the command name is 255 characters. It must be a legal, executable Windows file name.

• For UNIX — The maximum length of the command name is 100 characters. It must be a valid, binary UNIX file.

CMDNAME Statement: Run Agent-Platform Commands

192

Windows-specific notesAll NT_JOB definitions require a CMDNAME statement.

Using spacesTo use a space in the path, include the full path within double quotes. For example:

CMDNAME "c:\Program Files\Microsoft Office\Office\Winword.exe"

ARGS d:\docs\status.doc

Issuing CommandsApplication commandsTo run Windows applications, such as ipconfig.exe, specify the command file on the CMDNAME statement. For example:

CMDNAME c:\winnt\system32\ipconfig.exe

Operating-system commandsTo run Windows operating-system commands, such as DIR or TYPE, invoke the command interpreter CMD.EXE, as follows:

CMDNAME c:\winnt\system32\cmd.exeARGS /c "dir c:\temp\"

You can run these executable file types using the CMDNAME statement:

What you can run through the AgentFor some GUI applications, if there is a command line interface, you can run the application by specifying the batch file name using the CMDNAME statement. For example, you can transfer files using the FTP DOS commands or send e-mail in a batch file using software such as BatMail.

ExceptionsYou can run other types of executable files from the Windows command line than those that are directly supported by the CMDNAME statement. (The executable files you can run are defined in the Windows system variable PATHEXT.) There are two ways to run those executable files using the Agent:

• Run the executable from a batch file (.bat) or command file (.cmd)

Type of file Extensions Binary files .exeBatch files .bat, .cmdCommand files .com

193

• Invoke the program’s interpreter with the CMDNAME statement and use the ARGS statement to pass the command as a parameter, as shown in the example “Run a Visual Basic script via the Windows Agent” on page 194.

Specifying a working directoryBy default, the Agent’s working directory is the directory where you install the Agent. If your executable file inputs or outputs to a different directory, or runs another executable file in a different directory, specify that directory. For example, if your batch file runs an executable file, you can:

• Specify the full path of the executable within the batch file:C:\Program files\esp\espcmd1.batC:\Program files\esp\espcmd2.batC:\payroll\data\pay.exe

• Use the Change Directory (cd) command to switch to the directory:cd C:\Program files\espespcmd1.batespcmd2.batcd C:\payroll\datapay.exe

If your batch file takes input and outputs information, use the cd command to switch to the directory where the input and output files reside. In this example, file ftptest.bat reads the ftp command from the file ftpscript.src. The batch file outputs to file ftp.out in the current working directory. cd d:\temp\scriptftp -n -i -s:ftpscript.src 131.50.30.28 >ftp.outuser guestverboselcd d:\temp\datacd /u1/guestget data1quit

If you run ftptest.bat from the command line, manually switch to the d:\temp\script directory before running the file. The Windows operating system knows the current working directory, so you do not need to include the cd d:\temp\script command in the batch file.If you run ftptest.bat using the Agent, however, the Agent does not know the working directory. Specify the cd d:\temp\script command in the batch file, or the ftp command will fail.

CMDNAME Statement: Run Agent-Platform Commands

194

ExamplesIdentifying a command to run within a jobThis is an example of the CMDNAME statement:CMDNAME c:\payroll\test\sort

In this example, sort is the name of the command and c:\payroll\test is the path.

Run a Visual Basic script via the Windows AgentAPPL WINJOBNT_JOB VBSCRIPT AGENT NT_NY RUN DAILY CMDNAME c:\winnt\system32\wscript.exe ARGS c:\programs\vbs\notify.vbsENDJOB

In this example, the Agent invokes the Visual Basic interpreter wscript.exe using the CMDNAME statement and passes the Visual Basic script notify.vbs as a parameter using the ARGS statement.

Run a command on a UNIX AgentIn this example, the job MFGRPT runs every Friday on Agent UNIX_NY. It runs the report command under the user ID, user1.

UNIX_JOB MFGRPT RUN FRIDAYS AGENT UNIX_NY CMDNAME /mfg/report USER user1ENDJOB

Redirect I/O and pipe output on a UNIX AgentIn this example, the Agent runs the UNIX command ps -ef|grep cybAgent and pipes output to the /tmp/log file.

To redirect I/O and pipe output from a command, invoke the shell interpreter in the CMDNAME statement and include the command in an ARGS statement, as follows:

SUN_JOB SUN30 RUN TODAY AGENT SUN30RD CMDNAME /usr/bin/ksh ARGS -c "ps -ef|grep cybAgent >>/tmp/log" USER user1ENDJOB

195

CMDPRFX Command: Specify Command Prefix

Allows you to substitute the string the “F stcname,” (where stcname is the started task name for ESP) with a single character. This allows you to enter a single character instead of specifying “F stcname,” when modify commands to ESP are entered from a system console.

TypeGeneral command.

AuthorityYou require OPER authority to issue the CMDPRFX command.

SyntaxCMDPRFX character 'F stcname,'

Usage notesDo not choose a z/OS command character, for example, C (Cancel), Z (Halt) or F (Modify), to represent the “F ESP,” string.

Related informationFor information on displaying whether command prefixing is in effect or not, see the LCMDPRFX command.

Example Substitute # for F ESPPRODIn the following example, # is substituted for “F ESPPROD,” when modify commands to ESP are entered from a system console:CMDPRFX # 'F ESPPROD,'

As a result of setting the command prefix to #, you can enter the following command from a system console to trigger an Event.# TRIGGER CYBER.PAYROLL ADD

Operand Description

character Indicates a single character, which is to be substituted for the “F stcname” string, where stcname is the name of your ESP started task.

COLUMNS Statement: Specify Line Width of List

196

COLUMNS Statement: Specify Line Width of List

The COLUMNS statement specifies the line width of the list.

ApplicabilityESP Business Agents for SAP, Version 2.2 and higher.

Syntax COLUMNS num

Usage notesUse the COLUMNS statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the COLUMNS statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.COLUMNS is a mandatory statement after a PRINTDEST statement. For more information, see “PRINTDEST Statement: Specify Print Destination (SAP)” on page 965.COLUMNS corresponds to the SAPGUI Background Print Parameters dialog, Print settings section, Report width field.

ExampleIn this example, the maximum line width of the list is defined as 251.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST COLUMNS 251ENDJOB

Operand Descriptionnum Specifies the line width of the list. num must be numeric.

Specify up to 255 columns.Note: The maximum line width of a list for viewing on the

screen is 255.

197

COM Command: Insert Comments

Adds any number of comments, anywhere in an Event between the EVENT command and the ENDDEF command. ESP Workload Manager ignores any comments when an Event is triggered.

TypeEvent definition command.

SyntaxCOM comment

Usage notesIf you have more than one comment, you must use COM at the beginning of each comment line.

Related informationFor information on starting an Event definition, see the EVENT command.For information on ending an Event definition, see the ENDDEF command.For information on working with ESP Events, see the ESP Workload Manager User’s Guide.

Example Indicate what Event is doingIn the following example, a comment is added to the Event indicating what the Event is doing (submitting jobs) and when the Event is to submit those jobs (Thursdays):EVENT ID(CYBER.PAYJOBS)COM THIS IS AN EVENT TO SUBMIT PAYROLL JOBS EVERY THURSDAYSCHEDULE 19:00 THURSDAYSSUBMIT 'PROD.JCL.CNTL(PAYJOB1)'SUBMIT 'PROD.JCL.CNTL(PAYJOB2)'ENDDEF

Operand Descriptioncomment Any string.

COMMAND Statement: Run OS/400 Commands

198

COMMAND Statement: Run OS/400 Commands

The COMMAND statement is used when defining jobs for the OS/400 Agent to run any valid OS/400 command. It is used within the boundaries of the job definition.

SyntaxCOMMAND OS/400commandsyntax

Usage notesThe COMMAND statement is mutually exclusive with the CLPNAME and AS400FILE statements.

Example This an example containing the COMMAND statement:AS400_JOB MFGDATA RUN DAILY RELEASE MFGSORT AGENT AS401 CLPNAME MFGTEST.DATA AS400LIB PRODJOBS CCEXIT IVPEXIT COMMAND SNDMSG MSG('MFGDATA Complete')+ TOMSGQ(QSYSOPR)ENDJOB

In this example, the command issued sends a message to the system operator message queue.

Operand DescriptionOS/400commandsyntax Specifies any valid OS/400 command to run.

199

CONNECT Command: Connect to Groups

Identifies which user belongs to which group.Note: CONNECT is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou require SPECIAL or CONNECTDEF authority to issue the CONNECT command in a non-SAF environment.

Syntax{CONNECT|CON} userid GROUP(groupname) [EXECUTE] [READ] [UPDATE]

Usage notesA user with an authority attribute of ANY has access to any Group. Such a user does not need to be connected to any Group.

Operand Descriptionuserid Indicates the name of the user to be connected to the group.groupname Indicates the name of the group to which the user is to be

connected.EXECUTE Indicates the user ID is permitted to trigger an Event; with

additional READ access, the user can control jobs in an Application created by an Event with the following restrictions: unable to insert jobs or resubmit a job with a different JCL library.

READ Indicates the user ID is permitted to display an Event, list the schedule and display the status of jobs the Event submits.

UPDATE Indicates the user ID is permitted to define or update an Event definition; with additional READ access, the user can control jobs in an Application created by an Event with no restrictions.

CONNECT Command: Connect to Groups

200

If you do not define a type of access, for example, READ, EXECUTE, or UPDATE, the user has unrestricted access to Events with the Group prefix.You can connect a user to more than one group. When you connect a user to more than one group, that user can use the GROUP command in Page mode to switch between his or her user ID and any group he or she can access. This is useful when using commands where a group prefix is required.When you display a group, ESP lists all the users connected to that group. When you display a user, ESP lists all the groups to which a user is connected. If there are any access restrictions to a group, they are listed in parenthesis. ESP uses the following abbreviations for access permissions: R (READ), X (EXECUTE), and U (UPDATE).

Related informationFor information on removing a user’s access from a Group prefix, see the DISCONN command.For information on listing a user definition, see the LISTUSER command.

Examples Connect user to group with full accessIn the following example, USER1 is connected to PROD. USER1 has full access to Events with the PROD prefix because READ, EXECUTE or UPDATE were not specified:CONNECT USER1 GROUP(PROD)

Connect user with trigger accessIn the following example, USER2 is connected to TEST. USER2 is permitted to trigger Events with the TEST prefix: CONNECT USER2 GROUP(TEST) EXECUTE

If READ access is given to USER2 in addition to EXECUTE access, USER2 is able to control jobs in an Application created by an Event, but unable to insert jobs or resubmit a job with a different JCL library.

201

CONNECTION_FACTORY Statement: Specify JNDI Name of Connection Factory (J2EE)

The CONNECTION_FACTORY statement specifies the JNDI name of the Connection Factory for JMS jobs. The Connection Factory contains all the bindings needed to look up the referenced Topic or Queue. JMS jobs use the Connection Factory to create a connection with the JMS Provider.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher • Used within the JMSP_JOB and JMSS_JOB workload objects

SyntaxCONNECTION_FACTORY factory

Usage notesCONNECTION_FACTORY is a mandatory statement within the JMSP_JOB and JMSS_JOB workload objects.

ExampleIn this example, the CYBJK.JP job uses the Connection Factory named ConnectionFactory.APPL TESTJPJMSP_JOB CYBJK.JP HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DESTNAME Queue TOPIC N MSGCLASS String JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 PARAMETER TYPE(java.lang.String) VALUE(’this is my message’)ENDJOB

Operand Descriptionfactory The Connection Factory needed to look up the referenced Topic

or Queue. factory is case sensitive and can be up to 1024 characters.

CONSOLE Command: Set Console

202

CONSOLE Command: Set Console

Used to set the owning or primary console. All general message traffic is directed to the owning console.

TypeGeneral command.

AuthorityYou require OPER authority to issue the CONSOLE command.

SyntaxCONSOLE [*|ucmid|0|name]

Usage notesA primary console must be active when the request issued, with the capability for both input and output. If no operands are specified, the current primary console information is displayed.If the CONSOLE command is not specified and:• If ESP Workload Manager was started from a real console, the primary console is

set to that console.• If ESP Workload Manager was not started from a real console, the primary

console is set to console ID 0 (console name INTERNAL).

Operand Description* Requests that the console issuing the command be made the primary

console. This is valid only if the CONSOLE command is issued dynamically from a real console. It is not valid if issued from the ESPPARM initialization data set or from an extended MCS console such as IPCS.

ucmid Indicates an eight-character hexadecimal console ID. The first character must be a number from zero to nine.

0 Indicates console ID 0 (console name INTERNAL). You can specify from one to eight zeros.

name Indicates the two-to-eight-character name of an active console in the ESP complex. You must not use the following reserved names: HC, INSTREAM, OPERLOG, SYSLOG, SYSIOSRS, and UNKNOWN.

203

Examples Set console two as primaryIn the following example, console two is set as the primary console:CONSOLE 2

Set issuing console as primaryIn the following example, the issuing console assumes the role of the primary console:CONSOLE *

Set BOSS as primaryIn the following example, a console named BOSS is set as the primary console:CONSOLE BOSS

COPY Command: Copy Job History Records

204

COPY Command: Copy Job History Records

Used to specify an output data set or file to receive all or subsets of the job history record read in from the input source. The COPY command is useful when you want to separate data in a history file into one or more files.

TypeReporting command.

SyntaxCOPY {DATASET(dsname)} {FILE(filename)} [SELECT|ALL|REJECT] [EXTEND]

Usage notesNo restriction exists on the number of COPY commands that can be included in a single report definition; records are copied in their original sequence.ESP writes to any format sequential data set. If a data set is new and you have not yet specified a record format for it, ESP uses the following default:• LRECL=4096• RECFM=VBS• BLKSIZE=6144

Operand Descriptiondsname Indicates the name of the output data set. This is mutually

exclusive with the filename option.filename Indicates the name of the file to which the data is to be written.

This is mutually exclusive with the dsname option.SELECT Indicates only records matching any selection criteria are copied.

If no CRITERIA section exists in the report definition, all records are copied.

ALL Indicates all records in the input files are copied to the output file.REJECT Indicates the copy is restricted to any records that fail to match any

selection criteria. If no criteria section exists, no records are copied.

EXTEND Indicates the data to be copied be added to the end of the output data set rather than to replace existing data.

205

Related informationFor information on history reporting, see the ESP Workload Manager User’s Guide.

Example Copy data into two filesIn the following example, records less than 12 weeks old when the request is made are copied the file DISK1. Records that are more than 12 weeks old when the request is made are copied to the file TAPE1:REPORTHISTFILE HIST1CRITERIA RDRON GT TODAY LESS 12 WEEKSCOPY SELECT FILE(DISK1)COPY REJECT FILE(TAPE1)

COPYJCL Statement: Generate Copy of JCL

206

COPYJCL Statement: Generate Copy of JCL

The COPYJCL statement is used to generate a copy of the JCL for every job ESP Workload Manager submits. When you use the COPYJCL statement you must specify the library that is to receive the copy, followed by either the JOBNAME or JOBID keyword. This working copy of the JCL can be used for job re-submission. ESP Workload Manager keeps track of where the job was submitted from and the JCL that was used.

SyntaxCOPYJCL {datasetname|NONE} [GENERATION(genno)] [JOBNAME|JOBID]

Usage notesYou can specify COPYJCL in the Event definition of any Event that submits jobs. This copy is written to a member of a PDS, providing a working copy of the JCL with, where applicable, all symbolic variables resolved and NET cards (for DJC/JES3) are included.You can also specify COPYJCL within an Application definition to identify one or more jobs for which you want to use COPYJCL. This gives you the advantage of using COPYJCL for specific jobs.The JOBNAME keyword requests that the member name used for storing the JCL for a job is the same as the job name. This is the default. Each submission of a particular job overwrites the previous copy of that job JCL.

Operand Descriptiondatasetname Indicates the name of an existing partitioned data set to which

you have update authority. This is the data set to which the JCL copy is made.

NONE Indicates no JCL copy is needed. This can only be used at the job level in an Application.

genno Indicates the name of an existing GDG and optional generation number. The generation number should be a zero or a negative number. GENERATION can be abbreviated to GEN.

JOBNAME Indicates the member name used for storing the JCL for a job is the same as the job name. This is the default.

JOBID Indicates the member name used for storing the JCL for a job is the JES job ID. It is in the form JOBnnnnn or Jnnnnnnn, where nnnnn or nnnnnnn is the job number. Refer to the job ID entry in the glossary.

207

Use the JOBID keyword when you want ESP Workload Manager to store the copy of the JCL by job number. ESP Workload Manager creates a member name in the form JOBnnnnn or Jnnnnnnn, where nnnnn or nnnnnnn is the job number. Refer to the JOBID entry in the glossary. The system assigns this number sequentially. A member is not overwritten until the corresponding job ID reoccurs.

Note: With either option (JOBNAME or JOBID), you can write the JCL to a PDS GDG (generation data group).

Related statementsFor information on working with ESP Events or identifying JCL, see the ESP Workload Manager User’s Guide.

Examples Copy all jobs to PDSIn the following example, ESP Workload Manager writes a copy of all submitted jobs within the PAYROLL Application to CYBER.COPYLIB.CNTL and stores the jobs by job name:EVENT ID(CYBER.PAYROLL)INVOKE 'CYBBS01.PROCLIB.CNTL(PAYROLL)'COPYJCL 'CYBER.COPYLIB.CNTL' JOBNAMEENDDEF

Copy all jobs except PAYJOB2In the following example, ESP Workload Manager writes a copy of all submitted jobs within the PAYROLL Application excluding PAYJOB2 to CYBER.COPYLIB.CNTL and stores the jobs by JES jobid:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'COPYJCL 'CYBER.COPYLIB.CNTL' JOBIDJOB PAYJOB1 RELEASE PAYJOB2JOB PAYJOB2 RELEASE PAYJOB3 COPYJCL NONE JOB PAYJOB3ENDJOBSELECT (PAYJOB1,PAYJOB2,PAYJOB3)

COPYJCL Statement: Generate Copy of JCL

208

Copy jobs to current generation and store by nameIn the following example, ESP Workload Manager writes a copy of all submitted jobs within the PAYROLL Application to the current generation of CYBER.COPYLIB.CNTL and stores the jobs by job name:EVENT ID(CYBER.PAYROLL)INVOKE 'CYBBS01.PROCLIB.CNTL(PAYROLL)'COPYJCL 'CYBER.COPYLIB.CNTL' GEN(0) JOBNAMEENDDEF

209

COREQ Statement: Specify Name of Co-Requisite

The COREQ statement is used to specify the names of any other job that is selected automatically whenever the specified job is selected. The specified job and all of its co-requisites are allowed to execute simultaneously.

SyntaxCOREQ {jobname} {jobname[,jobname]...} {ADD(jobname[,jobname]...)} {DROP(jobname[,jobname]...)}

Usage notesA COREQ statement overrides any previous COREQ statement for the same job unless the ADD keyword is specified. COREQ can be used with any job to name other jobs that must be selected for execution whenever this job is selected.The COREQ statement specifies jobs that are selected when the specified job is selected. It does not cause the COREQ jobs to inherit any of the relationships of the specified job. The appropriate relationships need to be specified using PREREQ, POSTREQ, AFTER, or RELEASE statements. The COREQ statement forces selection of the co-requisite jobs—no SELECT statement or RUN statement is required.

Related informationFor information on specifying job relationships, see the AFTER, RELEASE, PREREQ, and POSTREQ statements.For information on Applications, see the ESP Workload Manager User’s Guide.

Operand Descriptionjobname Indicates a job name in up to eight characters. Enclose multiple

job names in parentheses, separated by a blank or a comma.ADD Indicates the specified jobs be added to those currently defined

COREQs. If a previous COREQ statement was specified in the ESPPROC, the jobs is added to these as well.

DROP Indicates the specified jobs be dropped from those currently defined COREQs.

COREQ Statement: Specify Name of Co-Requisite

210

Examples Select PAYJOB2 when PAYJOB1 is selectedIn the following example, whenever PAYJOB1 is selected, ESP always selects PAYJOB2. No relationship exists between PAYJOB1 and PAYJOB2:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN MONDAY COREQ PAYJOB2JOB PAYJOB2ENDJOB

Select multiple coreqs on workdaysIn the following example, PAYJOB3, PAYJOB4, PAYJOB5 and PAYJOB6 are selected for submission and will run simultaneously on workdays:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 RUN WORKDAYS COREQ (PAYJOB4,PAYJOB5,PAYJOB6)JOB PAYJOB4JOB PAYJOB5JOB PAYJOB6ENDJOB

Add coreqsIn the following example, whenever PAYJOB7 is selected, ESP always selects PAYJOB8, PAYJOB9, PAYJOB10 and PAYJOB11:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB7 RUN WORKDAYS COREQ (PAYJOB8,PAYJOB9) COREQ ADD(PAYJOB10,PAYJOB11)JOB PAYJOB8JOB PAYJOB9JOB PAYJOB10JOB PAYJOB11ENDJOB

211

Run jobs simultaneouslyThe following COREQ and RELEASE statements are used to:• Indicate jobs that can run simultaneously• Indicate a relationship between jobs. APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB12 RUN DAILY RELEASE PAYJOB13JOB PAYJOB13 RUN FRIDAY COREQ (PAYJOB14,PAYJOB15,PAYJOB16)ENDJOB

In the above example:• PAYJOB12 runs every day • On Friday’s PAYJOB12, PAYJOB14, PAYJOB15 and PAYJOB16 run

simultaneously, because the COREQ jobs do not inherit any relationship to PAYJOB13

• PAYJOB13 runs after PAYJOB12 successfully completes.

CPROC Command: Display and Delete Cache Entries

212

CPROC Command: Display and Delete Cache Entries

The CPROC command is used to display and delete cache entries.

TypeGeneral command

SyntaxCPROC [APPLICATION(applname[.applgen])] [DSNAME(dsname)] [LIST[_|(JOB(name.qualifier)|ALL])|DELETE] [DETAILS]

Operand DescriptionAPPLICATION(applname.applgen)

Specifies an Application for the CPROC command to act on. You can specify the generation as absolute or relative. For example, PAYROLL.123 or PAYROLL.-2. The Application name and generation is required to display ESP Procedure statements.

DSNAME(dsname) Specifies the name of the data set from which the ESP Procedure was read. The CPROC command will act only on Applications generated from ESP Procedures included in the specified data set. If the data set is a PDS or a PDSE and you do not specify a member name, all members of the data set will be included.

LIST Displays cached information contained in all Applications or the Applications selected with the APPLICATON and DSNAME operands. The next three operands define what information is displayed.

_ (Nothing entered) Displays a concise list of cache entries.JOB(name.qualifier) Displays the statements of the specified job.ALL Displays the statements of the cached ESP Procedure.

Note: The text displayed differs from the original ESP Procedure:• Comment lines are omitted• Leading spaces are not included• Formatting of multi-line statements is not preserved• Statements used only for the generation of the Application

are omittedDELETE Deletes cached information contained in all Applications or the

Applications selected with the APPLICATON and DSNAME operands.

213

Usage notesWildcards are not accepted by the CPROC command.This command is useful only if caching is enabled. For details, see the PCACHE initialization parameter in the ESP Workload Manager Installation and Configuration Guide.To cache an individual Procedure, see the INVOKE command in this guide.

Examples:The following example displays all the statements of job MYJOB. The JOB is part of the third generation of Application MYAPP. The ESP procedure used to generate the Application MYAPP is in the data set CYBAPPL.MYAPPLS.CPROC APPLICATION(MYAPP.003) DSNAME(CYBAPPL.MYAPPLS) - LIST(JOB(MYJOB))

The following example displays all existing cache entries for the application. It lists some details, but does not list the jobs inside the application. If you include the application name (as in the previous example), the jobs are listed.CPROC APPLICATION(MYAPPL) LIST DETAILS

DETAILS Displays size and usage information about the cached entries.Operand Description

CPU Command: Define CPUs

214

CPU Command: Define CPUs

Used in conjunction with the NODE parameter, to define the resource topology of your network. The CPU command defines each CPU within a node.Note: You do not need a RESFILE if you do not use resources.

TypeGeneral command.

SyntaxCPU cpuname [ADD|DEL|LIST|SET]NODE(nodename) [ROUTEJCL('/*JOBPARM SYSAFF=...')] |AGENT(agentname)] [ORDER(nn)] [CURRENT] [ACTIVE|INACTIVE] [DEL[FORCE]] [SYSNAME(sysname)]

Operand Descriptioncpuname The name to identify this CPU. This must be a unique name within a

node. When used with the NODE operand, you may have the name correspond to, for example, an existing JES member name, but this is not mandatory. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used for masking the name with all parameters except ADD.

If you intend to use Agent workload balancing or route to an Agent based on resource availability, you use the CPU command to referto an Agent.

ADD Add this definition to the existing definitions.DEL Delete one or more existing definitions.LIST Display a list of one or more existing definitions.SET Modifies attributes of existing definitions.NODE(nodename) The node to which the CPU belongs.ROUTEJCL Insert a JOBPARM statement into the job JCL to route the job to the

appropriate z/OS system.

215

Usage notesThe CPU command is generally used at the initialization parameter level, and is used in conjunction with the NODE parameter to define the resource topology of your network.

Related informationFor information on defining the resource topology of your network, see the CPU, NODE, and RESFILE parameters in the ESP Workload Manager Installation and Configuration Guide.For information on Resources, see the ESP Workload Manager User’s Guide.

Examples Display all CPUsIn the following example, all CPUs defined as part of the resource topology are displayed:CPU - LIST

AGENT(agentname) Specify an ESP Agent that the CPU is associated with. The Agent name is the unique name specified for an Agent in the AGENTDEF data set. Use this operand when you want ESP Workload Manager to use Agent workload balancing or when you want to route to an Agent that has sufficient resources.

ORDER(nn) Specify a CPU search sequence. When ESP Workload Manager tries to schedule a job, it scans for resource availability by CPU, searching the CPUs in sequence defined by the ORDER value nn. If two CPUs have the necessary resources to execute a job, ESP schedules the job to the one with the lowest ORDER value.

CURRENT Overrides the ROUTE JCL operand. If you specify CURRENT, cpuname identifies the CPU executing the ESP Workload Manager subsystem that submits jobs. For the CPU command on which you code CURRENT, you don’t need to code ROUTE JCL.

ACTIVE Declare the CPU as active.INACTIVE Declare the CPU as inactive. ESP Workload Manager does not attempt

to schedule a job to that CPU while it is inactive.

DEL[FORCE] Delete the specified CPU. Specify FORCE only if you want to delete the last CPU on a node and it is active.

SYSNAME(sysname) The system name for a CPU; used for Workload Manager resource balancing.

Note: This operand is only relevant if the ESP Workload Manager High Performance Option (HPO) is installed.

Operand Description

CPU Command: Define CPUs

216

Deactivate and delete a CPUIn the following example, T1 is deactivated and then deletedCPU T1 SET INACTIVE

thenCPU T1 DEL FORCE

Define NODE and CPUIn the following example, a single node called TORONTO is defined, and a single CPU called T1 is defined as a member of the TORONTO node:NODE TORONTO ADDCPU T1 ADD NODE(TORONTO) CURRENT

Define NODE and CPU for WLM workload balancingThe following example defines two CPUs that belong to the Toronto node:NODE TORONTO ADD SYSPLEXCPU T1 ADD NODE(TORONTO) CURRENTCPU T2 ADD NODE(TORONTO)

All the CPUs that have the same NODE operand in the CPU initialization parameter are linked. If you have HPO installed, ESP Workload Manager can balance the workload among members belonging to one node if the SYSPLEX operand is coded in the NODE command or initialization parameter. Refer to the ESP Workload Manager High Performance Option in the ESP Workload Manager User’s Guide for information on how to use WLM load balancing.Define NODE and CPU for Agent workload balancingThe following example defines:• Three Windows NT cpus associated with Agents called AGwin1, AGwin2, and

AGwin3• Four UNIX cpus associated with Agents called AGunix1, AGunix2, AGunix3,

and AGunix4NODE WIN ADDNODE UNIX ADDCPU WIN1 ADD NODE(WIN)AGENT(AGwin1)CPU WIN2 ADD NODE(WIN)AGENT(AGwin2)CPU WIN3 ADD NODE(WIN)AGENT(AGwin3)CPU UNIX1 ADD NODE(UNIX)AGENT(AGunix1)CPU UNIX2 ADD NODE(UNIX)AGENT(AGunix2)CPU UNIX3 ADD NODE(UNIX)AGENT(AGunix3)CPU UNIX4 ADD NODE(UNIX)AGENT(AGunix4)

217

All the CPUs that have the same NODE operand in the CPU command or initialization parameter are linked. If you have HPO installed, ESP Workload Manager can balance the workload among agents belonging to one node. Refer to the ESP Workload Manager High Performance Option in the ESP Workload Manager User’s Guide for information on how to use Agent workload balancing.

CPU Statement: Specify Conditions to Monitor CPU Use Within CPU_MON

218

CPU Statement: Specify Conditions to Monitor CPU Use Within CPU_MON

The CPU statement specifies the conditions that a CPU_MON workload object will use to monitor CPU utilization for the machine on which the Agent is installed.

ApplicabilityESP System Agents, Release 6, used within a CPU_MON workload object. For more information, see “CPU_MON Statement: Monitor CPU Usage” on page 221.

SyntaxCPU [FROM(lower)] [TO(upper)] [NOCHANGE(percent)]

[CONTINUOUS(alert)[WITHIN|OUTSIDE] [AVAILABLE|USED]

Operand DescriptionFROM (lower) Defines the lower boundary of CPU utilization in percent. Used

with CONTINUOUS.TO (upper) Defines the upper boundary of CPU utilization in percent. Used

with CONTINUOUS.NOCHANGE (percent) Optional. Monitor will not trigger if the value change is within the

value in percent specified by this operand. NOCHANGE requires at least one of the operands FROM or TO.

CONTINUOUS (alert) Mandatory if CPU is specified in a CPU_MON job. A Workload Manager Alert is triggered when the specified CPU monitoring conditions occur. CONTINUOUS requires at least one of the operands FROM or TO.

• Specifying only FROM means that the monitoring takes place between the lower boundary and 100 percent.

• Specifying only TO means that the monitoring takes place between zero percent and the upper boundary.

• Specifying both means that the monitoring takes place between the lower and upper boundaries.

Note: alert cannot exceed four characters and must be specified previously using the ALERTDEF command. For more information on the ALERTDEF command, see the ESP System Agent Administrator’s Guide.

219

Usage notesOn UNIX, the CPU calculations are based on load averaging as displayed by the command top. You can scale the results returned to ESP Workload Manager with the parameter objmon.cpu.scalefactor. For more information, see “objmon.cpu.scalefactor=<nnn>” in the ESP System Agent Administrator’s Guide.

ExampleIn this example, a CPU monitor job CPU_MON CPU.STMNT is defined for the Agent R6AGENT. The operands used in this example are explained following the example syntax.CPU_MON CPU.STMNT AGENT R6AGENT RUN DAILY CPU FROM(20) TO(50) NOCHANGE(10) CONTINUOUS(al3) + OUTSIDE AVAILABLEENDJOB

In this example, the CPU statement within the CPU_MON job uses the following operands:• FROM(20)—The lower boundary of the search range for percent utilization of the

CPU where the Agent is installed.• TO(50)—The upper boundary of the search range for percent utilization of the

CPU where the Agent is installed.• NOCHANGE(10)—The NOCHANGE operand specifies a minimum threshold in

a change in percent (delta) of CPU utilization to monitor for. If the percent change is less than or equal to ± 10 percent, the CPU monitor job does not register a change.

• CONTINUOUS(a13)—If all of the monitoring conditions specified by the operands in the CPU statement occur, an Alert (a13) is issued.

WITHIN|OUTSIDE Optional.

• WITHIN—Default. Monitor triggers if the value is within the boundaries specified by FROM and TO operands.

• OUTSIDE—Monitor triggers if the value is outside the boundaries specified by FROM and TO operands.

AVAILABLE|USED Optional.

• AVAILABLE—Default. Monitor takes the available CPU capacity as the reading.

• USED—Monitor takes the used CPU capacity as the reading.

Operand Description

CPU Statement: Specify Conditions to Monitor CPU Use Within CPU_MON

220

• OUTSIDE—This operand specifies that the job will monitor for the specified condition outside the range specified by the FROM and TO operands. This means that the job is looking for CPU utilization between 0 and 20 percent and between 50 and 100 percent.

• AVAILABLE—The monitor job will take the reading of unused CPU capacity.

221

CPU_MON Statement: Monitor CPU Usage

Specifies the name of a workload object that monitors the CPU usage percentage, based upon load averages, of the machine where the Agent is installed.

TypeApplication statement.

ApplicabilityRelease 6 System Agents.

SyntaxRefer to the JOB statement syntax.

Usage notesUse the CPU job statement with a CPU_MON workload object. If you do not use a CPU statement, the CPU monitor will return the percentage of use only once. The CPU statement can be explicit, where you include it in the job, or it can be implicit, where you do not include it in the job.

• If the CPU statement is explicit, you can tailor the query using the operands that are part of the CPU statement.

• If the CPU statement is implicit, the job returns the values for CPU used and available at the time the AFM was received by the Agent.

For more information, see the CPU statement.To use CPU monitors, load the workload object module CYBESOCM with the WOBDEF command or with the WOBDEF initialization parameter.The CPU calculations are based on load averaging as displayed by the command top. On UNIX Agents, you can scale the results returned to ESP Workload Manager using the parameter objmon.cpu.scalefactor. For more information, see the ESP System Agent Administrator’s Guide.

Also refer to the JOB statement usage notes.

CPU_MON Statement: Monitor CPU Usage

222

ExamplesMonitors and reports CPU usageIn this example, the Agent sends a message to ESP Workload Manager including information on the status of CPU capacity, available and used.CM CPUMON1.STMNT AGENT R6AGENT RUN DAILYENDJOB

Continuously monitors and reports CPU usage within a rangeIn this example, the Agent sends messages to ESP Workload Manager. The messages include information on the CPU capacity that is used within the range specified by the FROM and TO operands. The CPU is monitored continuously. CPU_MON CPUMON2.STMNT AGENT R6AGENT CPU FROM(75) TO(100) CONTINUOUS(CPU) USED RUN DAILYENDJOB

223

CRITERIA Command: Specify Reporting Criteria

Specifies selection criteria when producing ESP history reports. You can specify several field, operator, and value groups.

TypeReporting command.

SyntaxCRITERIA field operator value

Usage notesYou can specify several criteria sections in a single report using multiple criteria commands. ESP selects a job if it satisfies any criteria section.You can specify several criteria elements on one criteria statement. To be selected, a job must satisfy all criteria.You can also use the 'OR' and 'AND' logical operators. If you want to compare a field to a null string, use a blank enclosed in single quotes, as in ' '.If you do not specify a CRITERIA section in your report, ESP selects all records that meet the time criteria.

Related informationFor information on history reporting, see the ESP Workload Manager User’s Guide.

Operand Descriptionfield Indicates a field name keyword (such as JOBNAME).

For a detailed list of the history reporting fields, see the ESP Workload Manager User’s Guide.

operator Indicates a comparison operator in either their letter or symbol form:LT or < LE or <= EQ NE or ¬= GT or > GE or >=

value Indicates the value against which comparisons should be made. Its format depends on the field type.

CRITERIA Command: Specify Reporting Criteria

224

Examples Select jobs belonging to PAYROLLIn the following example, jobs that belong to the PAYROLL Application are selected:CRITERIA APPLSYS EQ PAYROLL

Jobs belonging to PAYROLL or jobs starting with PIn the following example, jobs that belong to the PAYROLL Application, or jobs that start with P, are selected:CRITERIA APPLSYS EQ PAYROLLCRITERIA JOBNAME EQ P-

Jobs belonging to PAYROLL and jobs starting with PIn the following example, jobs that belong to the PAYROLL Application, and jobs that start with P, are selected:CRITERIA APPLSYS EQ PAYROLL JOBNAME EQ P-

Jobs completed since 9am todayIn the following example, jobs that have completed execution since 9 am today are selected:CRITERIA ENDT GT 09:00 TODAY

All of multiple criteriaIn the following example, jobs that meet all of the following criteria are selected:CRITERIA JOBNAME EQ XYZ- CPUTIME GT 11L00 TEXCP GT 0 - STATUS EQ COMPLETE

• Have names beginning 'XYZ'• Consume more than 11 seconds of CPU time• Perform I/O to tape• And that have completed processing.Any of multiple criteriaIn the following example, jobs that meet any of the following criteria are selected:CRITERIA TEXCP GT 0 OR DEXCP GT 10000 CRITERIA JOBNAME EQ ABC- OR JOBNAME EQ A*

• Have more than 10000 EXCPs to DASD devices• Perform I/O to tape • Have names beginning 'ABC' • Two-character names that begin with A.

225

All jobs submitted by ESP but not in ApplicationIn the following example, all jobs submitted by ESP that do not belong to an Application are selected:CRITERIA ESPSUB EQ 'YES' AND APPLSYS NE ' '

CRITPATH Command: Enable Critical Path Analysis

226

CRITPATH Command: Enable Critical Path Analysis

Enables or disables Critical Path analysis on this ESP system.

TypeAuthorized oper command.

AuthorityYou require OPER authority to issue the CRITPATH command.

SyntaxCRITPATH [DISABLE|ENABLE|ON]

Usage notesBy default, critical path analysis is turned on or enabled for all Applications that ESP generates. To control usage of critical path analysis, a CRITPATH initialization statement, a CRITPATH Application statement and a CRITPATH command are provided. The following chart summarizes how ESP handles critical path analysis based on various CRITPATH operand and statement settings:

Operand DescriptionDISABLE Disallows critical path analysis on this ESP system. Critical path

analysis cannot be used on this ESP system when disabled. ENABLE Allows critical path analysis on this system. Then specify

CRITPATH ON within the Applications where you want critical path analysis performed. This is the default.

ON Turn on critical path analysis for all Applications. It can be turned off within an Application using the CRITPATH OFF statement.

If the CRITPATH command or

initialization parameter is set to ...

And CRITPATH statement in the

Application is set to ...

Then critical path analysis is ...

DISABLE OFF Not calculatedDISABLE ON Not calculatedDISABLE Not specified Not calculatedENABLE OFF Not calculatedENABLE ON CalculatedENABLE Not specified Not calculatedON OFF Not calculated

227

If critical path analysis is activated by coding either CRITPATH ON in the initialization parameters, or CRITPATH ENABLE in the initialization parameters and CRITPATH ON in the Application, but no jobs are coded with the CRITICAL keyword, ESP calculates the path to the job that will finish last and identifies that path as the critical path.

Related informationFor information on critical path analysis, see the ESP Workload Manager User’s Guide.For information on specifying whether critical path analysis is to be performed for an Application, see the CRITPATH Application statement.For information on overriding historical elapsed time defaults, see the DURATION statement.

Examples Turn on critical path analysisIn the following example, critical path analysis is turned on for all Applications generated by ESP on this system. If required, critical path analysis can be turned off for specific Applications by coding CRITPATH OFF statement in the Application definition:CRITPATH ON

Enable critical path analysisIn the following example, critical path analysis is enabled for this ESP system. To turn on critical path analysis for an Application, code CRITPATH ON statement in the Application definition:CRITPATH ENABLE

Disable critical path analysisIn the following example, critical path analysis is disabled for this ESP system. To turn off critical path analysis for an Application, code CRITPATH OFF statement in the Application definition:CRITPATH DISABLE

ON ON CalculatedON Not specified Calculated

If the CRITPATH command or

initialization parameter is set to ...

And CRITPATH statement in the

Application is set to ...

Then critical path analysis is ...

CRITPATH Statement: Enable Critical Path Analysis

228

CRITPATH Statement: Enable Critical Path Analysis

Enables or disables Critical Path analysis on this ESP system.

TypeESP Workload Manager Application Statement.

SyntaxCRITPATH [OFF|ON]

Usage notesBy default, critical path analysis is turned on or enabled for all Applications that ESP generates. To control usage of critical path analysis, a CRITPATH initialization statement, a CRITPATH Application statement and a CRITPATH command are provided. The following chart summarizes how ESP handles critical path analysis based on various CRITPATH operand and statement settings:

Operand DescriptionOFF Turns critical path calculation off within an Application. ON Turns critical path calculation on within an Application.

Note: This operand has no effect unless the CRITPATH command or initialization parameter is set to ENABLE.

If the CRITPATH command or

initialization parameter is set to ...

And CRITPATH statement in the

Application is set to ...

Then critical path analysis is ...

DISABLE OFF Not calculatedDISABLE ON Not calculatedDISABLE Not specified Not calculatedENABLE OFF Not calculatedENABLE ON CalculatedENABLE Not specified Not calculatedON OFF Not calculatedON ON CalculatedON Not specified Calculated

229

If critical path analysis is activated by coding either CRITPATH ON in the initialization parameters, or CRITPATH ENABLE in the initialization parameters and CRITPATH ON in the Application, but no jobs are coded with the CRITICAL keyword, ESP calculates the path to the job that will finish last and identifies that path as the critical path.

Related informationFor information on critical path analysis, see the ESP Workload Manager User’s Guide.For information on specifying whether critical path analysis is to be performed for an Application, see the CRITPATH Application statement.For information on overriding historical elapsed time defaults, see the DURATION statement.

Examples Turn on critical path analysisIn the following example, critical path analysis is turned on for all Applications generated by ESP on this system. If required, critical path analysis can be turned off for specific Applications by coding CRITPATH OFF statement in the Application definition:CRITPATH ON

Enable critical path analysisIn the following example, critical path analysis is enabled for this ESP system. To turn on critical path analysis for an Application, code CRITPATH ON statement in the Application definition:CRITPATH ENABLE

Disable critical path analysisIn the following example, critical path analysis is disabled for this ESP system. To turn off critical path analysis for an Application, code CRITPATH OFF statement in the Application definition:CRITPATH DISABLE

CRYPTKEY Command: Defines and Stores Encryption Key

230

CRYPTKEY Command: Defines and Stores Encryption Key

Defines and securely stores an encryption key used for communication between ESP Workload Manager and Agents.

TypeAuthorized command.

ApplicabilityESP System Agents, Release 6.

AuthorityYou must have UPDATE authority with the PASSWORD Host security rule to delete or update an encryption key without supplying the old encryption key.

Syntax CRYPTKEY{DEFINE KEYNAME(name)KEY(key)(type)} {DELETE KEYNAME(name)KEY(key)(type)} {LIST [KEYNAME(name)][KEY(key)](type)} {UPDATE KEYNAME(name)KEY(key)OLDKEY(okey)(type)}

Operand DescriptionDEFINE Defines a new encryption key. DELETE Deletes an encryption key and removes the connection to the Agent.LIST Displays a list of encryption keys.UPDATE Updates an encryption key.KEYNAME(name) Specifies the encryption key. KEYNAME is required for DEFINE,

UPDATE, and DELETE and is optional for LIST. The maximum length for a KEYNAME is 16 characters.

KEY(key) Specifies the encryption key. KEY is required for DEFINE, DELETE, and UPDATE and ignored with LIST.

OLDKEY(okey) Specifies the encryption key. OLDKEY is required for UPDATE when you do not have UPDATE access to the Host security CRYPTKEY profile. OLDKEY is ignored with DEFINE, DELETE, and LIST.

231

Usage notesWhen you delete or change an encryption key, you must specify the correct old encryption key unless you have UPDATE authority for the Host security CRYPTKEY profile. If you supply the old encryption key, it must be correct, or the request will fail, even if you have UPDATE authority for the Host security CRYPTKEY profile.If you update an encryption key, make sure you use the LOADAGDF command, so ESP Workload Manager is aware of the change. See “LOADAGDF Command: Load Agent Definition” on page 802.

ExamplesExample 1This example shows type DES encryption.CRYPTKEY DEFINE KEYNAME(agntr6) KEY(X'0102030405060708') DES

Example 2This example shows type BLOWFISH encryption.CRYPTKEY DEFINE KEYNAME(agblf) KEY(X'12345678901234567890') BLOWFISH

type Specifies the type of encryption key. Specify either BLOWFISH or DES encryption key.

Note: A Blowfish encryption key has a maximum of 64 hexadecimal characters. A DES encryption key has a maximum of 16 hexadecimal characters. If you enter more than the maximum number characters, the key will be truncated.

Operand Description

CURLIB Statement: Specify Current Library (OS/400)

232

CURLIB Statement: Specify Current Library (OS/400)

The CURLIB statement is used only when defining jobs for the OS/400 Agent to specify the current library for the job. The CURLIB statement can be used within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition, to apply to the entire Application.

TypeESP Workload Manager Application Statement

SyntaxCURLIB library

Example This an example of a job definition containing a CURLIB statement:AS400_JOB MFGDATA RUN DAILY RELEASE MFGSORT AGENT AS401 CLPNAME MFGTEST.DATA CURLIB PAY1ENDJOB

In this example, PAY1 is the current library for the job.

Operand Descriptionlibrary Specifies the name of the current library for the job.

233

cybAgent Command: Controlling Agents

Used to control the Agent. Depending on the platform, this command can be used to start, shutdown and display the version of agent software running. On the NT platform, the cybAgent command is used to install or remove the agent as a service and to start the agent.It is issued from the command line of the platform where the agent is running.

TypeGeneral command

Syntax The cybAgent command has the following syntaxes:UNIX syntax

{nohup[(/binPath/)]cybAgent[-r]|-v] [/pathTo/workingDirectory][>/dev/null2>&1]&}

NT syntax

{(/binPath/)cybAgent {-A|-DEBUG|-INSTALL[SERVICE_NAME]|-REMOVE|-R]|-S|-V|-?} [/pathTo/workingDirectory]}

OS/400 syntax

cybAgent {SHUTDOWN|VERSION}

cybAgent Command: Controlling Agents

234

UNIX

NT

Operand Descriptionnohup Issued from the Bourne or Korn shell. Starts the agent in the

background. Must be used with the & operand./binPath/ Specifies the path to the directory containing the cybAgent

binary.cybAgent Starts the UNIX agent when issued by itself. This command is

case sensitive and must be typed as shown./pathTo/workingDirectory Specifies the path to a valid working directory where the agent

will run and create its files. >/dev/null2>&1 May be used with the nohup operand to prevents the creation of

the nohup.out file. & Starts the agent in the background when the command is issued

from the C Shell. Must be used with the nohup operand to start the agent in the background from the Bourne or Korn shells.

-r Refreshes the agent’s security.-v Displays the version of agent software currently running.

Operand Description/binPath/ Specifies the path to the directory containing the cybAgent

binary.cybAgent Performs one or more of the actions described below.-A Starts the agent as a service.-DEBUG Starts the agent as a console application for debugging. Valid if

only one agent is installed.-INSTALL Registers the agent as a Windows NT Service. This must be

performed before starting the NT agent.SERVICE_NAME Specifies the Service Display Name as provided in the

AgentParm file. Used with the Debug operand to start the named agent as a console application for debugging when multiple agents are installed.

-REMOVE De-registers the agent as a Service.

Note: If the agent service is running, it is stopped, then removed.

-R Refreshes the agent’s security.-S Instructs the agent to shut down after completing all the running

work. -v Displays the version of agent software currently running.

235

OS/400

Usage notesThis command is case sensitive when issued from a UNIX operating system. The command must be typed exactly as shown.Specifying the nohup operand for a UNIX agent creates a file named nohup.out in the current directory. This file is continually appended with all the information produced by the standard output and error for the cybAgent, making it valuable for troubleshooting. This log file grows over time and must be cleared periodically.

ExamplesStart the UNIX agentWhen issued by itself the cybAgent command starts the agent software.cybAgent

If no path is specified, the working directory will be the current directory. The agent’s working files will be created in this directory. Note: If the current directory does not contain an AgentParm file, the cybAgent will

not function properly.We recommend that you start the UNIX agent by issuing a command similar to the following:/cybermation/cybAgent /Agent/workload &

In this example, the full path to the cybAgent program is provided, along with the path to the directory where the agent’s working files are found. The agent is started in the background.Start the UNIX agent at startup in the background, with root authority:This is an example of two statements added to the /etc/initab file, which start the UNIX agent automatically at startup under run levels two, three and four: esp:234:waitesp:234:/cybermation/cybAgent /Agent/workload &

-? Provides help on the cybAgent command.

Operand DescriptioncybAgent Performs one or more of the actions described below.SHUTDOWN Instructs the agent to shut down after completing all the running

work. VERSION Displays the version of agent software currently running.

Operand Description

cybAgent Command: Controlling Agents

236

Start the NT agentThis is an example of how to start the Windows NT agent from the command prompt:/cybermation/cybAgent -INSTALLNET START CYBERMATION_SERVICE

Shutdown the OS/400 agentThis is an example of the CYBAGENT command that shuts down the agent upon completion of all workload currently running:CYBAGENT SHUTDOWN

Shutdown the NT agentThis is an example of the cybAgent command that shuts down the agent upon completion of all workload currently running:/cybermation/cybAgent -s

Display the version of the OS/400 agent softwareThis is an example of the CYBAGENT command that displays the version of agent software currently running.CYBAGENT VERSION

This is a typical response: 3/30/01 08:40:52 OS/400 AGENT VERSION V2R0M0 (C) COPYRIGHT CYBERMATION INC. 2001 ALL RIGHTS RESERVED.

237

DDAB Command: Display ABENDed Jobs

Displays all or selected jobs from the abended queue.

TypeGeneral command.

AuthorityYou require OPER authority to issue the DAB command.

SyntaxDAB [LEVEL(jobstring)] [LAST(minutes)|FROM(time)] [TIME] [DATE] [PROD]

Usage notesThe DAB command displays jobs from the abended queue. The size of the abended queue is set with the ABENDLIM command.The job name, job number and completion code fields are always displayed. Jobs are displayed in reverse chronological order; that is the most recently abended jobs are shown first. This command can be issued from a system console.

Operand Descriptionjobstring Indicates one or more job name prefixes to limit the display to a

particular group of jobs. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

minutes Indicates only jobs that abended in the last n minutes are to be displayed.

time Indicates only jobs that abended after that specified time are to be displayed. This must be a time in the past. The time and date can be specified in free format. If the time and date contain blanks or commas, enclose the whole string within quotes.

TIME Indicates the time of the abend is displayed together with the completion code.

DATE Indicates the date of the abend is displayed together with the completion code.

PROD Indicates an updated display of ABENDed jobs (meaning only those still in ABEND status). This keyword applies only to jobs in an Application.

DAB Command: Display ABENDed Jobs

238

Related informationFor information on displaying abended jobs using the CSF, see the ESP Workload Manager User’s Guide.For information on displaying or setting the abend queue size for jobs that ESP is tracking, see the ABENDLIM command.

Examples Display all abended jobsIn the following example, all abended jobs on the queue up to the limit set by the ABENDLIM command are displayed:DAB

Display jobs named PR- or PAY- that abended since 1 amIn the following example, jobs with names beginning with PR and PAY that have abended since 1:00 am, are displayed:DAB LEVEL(PR- PAY-) FROM(1AM) TIME

Display jobs that abended in the last hourIn the following example, jobs that have abended in the last 60 minutes are displayed. The time each job abended is also displayed:DAB LAST(60) TIME

Update list of abended jobsIn the following example, an updated display of ABENDed jobs is displayed, meaning only those jobs still in abend status:DAB PROD

239

DATA_OBJECT Statement: Set Data Repositories

DATA_OBJECT workload objects serve as a data repository. It is coded in an Application as any other workload object.Data can be stored in this object at generate time by coding one or more SETVAR statements within the JOB block. Data can also be stored, updated or deleted at run time, by sending an automation framework message to the object. All data is stored in the Application tracking record, so it is preserved across restarts.

SyntaxRefer to the JOB statement syntax. All operands are valid except TASK, LINK, MANUAL, EXTERNAL, and CONDITIONAL.

Usage NoteA DATA_OBJECT workload object is always conditional, unlike all other workload objects.To use DATA_OBJECT workload objects, you must load a workload object module. The DATA_OBJECT workload object module is CYBESODA. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Also refer to the JOB statement usage notes.

Related informationSee the SETVAR statement for defining data object variablesSee the WOBDATA statement for retrieving data object variablesSee the ESPmsg command for an alternative method for defining data object variables.

DATA_OBJECT Statement: Set Data Repositories

240

Example In the following example, a data object DATA1 is created including variable DAVAR1. The job SETVAR defines a second variable COUNT using ESP MGRMSG. The job JOB1 retrieves both of these variables using the WOBDATA statement. APPL DATAOBJJCLLIB CYBER.JCLLIBDATA_OBJECT DATA1 SETVAR DAVAR1='ABC'ENDJOBJOB SETVAR LINK PROCESS ESP MGRMSG . . . . DATA1/%ESPAPPL..%ESPAPGEN/MAIN ACTION - SET COUNT(12) RUN DAILY RELEASE JOB1ENDJOBJOB JOB1 VALUE = WOBDATA('DATA1','COUNT') VALUE2 = WOBDATA('DATA1','DAVAR1') SE 'Local COUNT = %VALUE' USER(*) SE 'Local Variable = %VALUE2' USER(*) RUN DAILYENDJOB

CSF shows the number of data object variables stored in the data object: Job Name Jobno Appl AGen PNode Jobqual Status

___ DATA1 1 DATAOBJ 1 ACTIVE 1 Item stored

A LISTAPPL (LAP) command displays the variables and their value.ESP ----------------------------------------------- , Row 1 of 19, Col 1 -COMMAND ===> ---------------------------------- TOP OF DATA--------------------------------LAP DATAOBJ.11 ALLAPPL DATAOBJ GEN 11 CREATED AT 09.43 ON THURSDAY JULY 12TH, 2001 BY EVENT CYBER.DATAOBJ DATA1, 2 Items stored Data Items: DAVAR1(ABC), COUNT(12)

ANTICIPATED END TIME: 09.45 ON THURSDAY JULY 12TH, 2001 SUCCESSORS: (NONE)

MRTN2 J54506, COMPLETED, CC 0 SETVAR, COMPLETED, CC 0 MRTN1, HC=0 SUBMISSION AT 09.46 ON THURSDAY JULY 12TH, 2001 ANTICIPATED END TIME: 09.46 ON THURSDAY JULY 12TH, 2001 PREDECESSORS: (NONE) SUCCESSORS: (NONE)

----- 1 ENTRY DISPLAYED

241

DATASET Statement: Specify JCL Libraries

The DATASET statement is used to specify the JCL library and optional member name to be used for a particular job. The DATASET statement must be placed within the scope of a JOB statement.

SyntaxDATASET 'dsname[(member)]'

Usage notesThe DATASET you specify applies only to this particular job. DATASET is used to identify the JCL library and optionally the member name to be used for a particular job. This overrides, for this job only, the default JCL library already named in a JCLLIB statement.

Related informationFor information on specifying different JCL libraries, see the ESP Workload Manager User’s Guide.

Examples Specify alternative JCL librariesIn the following example, when ESP submits jobs in the PAYROLL Application:• PAYJOB1 is submitted from 'CYBER.JCL.CNTL'• PAYJOB2 is submitted from 'CYBER.ALTJCL.CNTL':APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY RELEASE PAYJOB2JOB PAYJOB2 RUN DAILY DATASET 'CYBER.ALTJCL.CNTL'ENDJOB

Operand Description

dsname Indicates the name of the data set.

member If this is a PDS, it optionally specifies the member name. If the member name is omitted, the job name is the default.

DATASET Statement: Specify JCL Libraries

242

Specify alternative JCL library and memberIn the following example, when ESP submits jobs in the PAYROLL Application:• PAYJOB3 is submitted from 'CYBER.JCL.CNTL'• PAYJOB4 is submitted from member PAYJOB99 within data set

'CYBER.ALTJCL.CNTL':APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 RUN DAILY RELEASE PAYJOB4JOB PAYJOB4 RUN DAILY DATASET 'CYBER.ALTJCL.CNTL(PAYJOB99)'ENDJOB

Change JCL library on specific dateIn the following example, if today is February 21st, 2000, ESP submits PAYJOB5 from CYBER.ALTJCL.CNTL:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB5 RUN DAILY IF TODAY('FEB 21, 2000') THEN - DATASET 'CYBER.ALTJCL.CNTL'ENDJOB

Change JCL library for range of datesIn the following example, ESP submits PAYJOB6 from CYBER.ALTJCL.CNTL, from February 1st, 2000 up to and including, February 22nd, 2000:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB6 RUN DAILY IF DAYS_FROM(FEB 1,2000') GE 0 AND - DAYS_TO('FEB 22,2000') GE 0 THEN - DATASET 'CYBER.ALTJCL.CNTL'ENDJOB

243

DATEFORM Command: Set Date Format

Sets the date format used in schedule statements.

TypeGeneral command.

AuthorityYou require OPER authority to issue the DATEFORM command.

SyntaxDATEFORM [YMD|MDY|DMY]

Usage notesESP recognizes the date format xx/xx/xx. The DATEFORM command instructs ESP how to interpret this format. Only one of the date formats is valid at your installation. This is normally specified in the ESP initialization parameters.The DATEFORM command only affects dates in the format xx/xx/xx. You can still use terms like May 24, 1997 and 24MAY97 regardless of this setting.

Related informationFor information on setting the date format used in schedule statements, see the DATEFORM initialization parameter in the ESP Workload Manager Installation and Configuration Guide.For information on setting the date format used to customize the format of date fields when using ESP’s history reporting facility, see the ESP Workload Manager User’s Guide.

Operand DescriptionYMD Sets the date format to YY/MM/DD. This is the default.MDY Sets the date format to MM/DD/YY.DMY Sets the date format to DD/MM/YY.

DATEFORM Command: Set Date Format

244

Example Display the current date formatIn the following example, the current date format setting is displayed:DATEFORM

Set date format to Month/Day/YearIn the following example, a schedule statement 05/24/00 is interpreted as May 24, 2000:DATEFORM MDY

245

DB_JOB Statement: Identify the Name of Database Jobs

Identifies the name of a database job in an Application. Database jobs perform SQL updates and queries against a database, while using JDBC for database connectivity.

TypeApplication statement.

Applicability Release 6 System Agents.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use database jobs, load the workload object module CYBESODM with the WOBDEF initialization parameter.Use these job definition statements with a DB_JOB workload object.

In the agentparm.txt file, you must specify a JDBC driver in parameter jdbc.drivers. To specify multiple drivers, separate them with a colon (:). For example:jdbc.drivers=driver1:driver2

A JDBC to ODBC bridge is supplied with the JVM on the Windows platform, and it is referred to in the agentparm.txt file as:sun.jdbc.odbc.JdbcOdbcDriver

The short form of DB_JOB is DM.Also refer to the JOB statement usage notes.

Statement NotesDSN Mandatory.SQL Mandatory.DESTINATION Optional—default is the spool file.USER Mandatory—user ID required to work with a database.

Specify the associated password with the ESP Workload Manager PASSWORD command.

DB_JOB Statement: Identify the Name of Database Jobs

246

ExamplesQuerying of an Oracle databaseThis example queries an Oracle database. The IP address of the data set name is specified using hostname format. The QUERY statement illustrates how to pass an operand with spaces to the Oracle query by enclosing the operand within single quotes.DB_JOB DBJOB2.STMNT AGENT R6AGENT USER user1 DSN oracle:thin:@gemini:1527:cyb QUERY 'SELECT JOBNAME FROM TBTCO' RUN DAILYENDJOB

Querying an SQL database This example queries an Oracle database. The IP address of the data set name is specified using hostname format. The SQL statement illustrates how to pass complex criteria to SQL using both single and double quotes, and how to continue the statements to the next line using a continuation character (+).DB_JOB DBJOB2.STMNT AGENT R6AGENT USER sapr3 DSN oracle:thin:@gemini:1527:cyb SQL 'SELECT COUNT (*) FROM TBTCO WHERE JOBNAME LIKE ''SD%'' + AND ENDDATE = ''20030813''' RUN DAILYENDJOB

Querying a DB2 database This example queries a DB2 database. The IP address of the data set name is specified using dotted decimal format. The DESTINATION statement illustrates specifying a path that contains spaces using single quotes.DB_JOB DBJOB3.STMNT AGENT R6AGENT USER db2admin DSN db2://10.1.1.46:50000/sample SQL 'SELECT COUNT(*) FROM STAFF WHERE NAME LIKE ''L%''' DESTINATION 'c:\qatest\db job data\test14.bd2' RUN DAILYENDJOB

247

DEFAT Command: Define Authorization Table

The DEFAT command is used to define or alter an authorization table, limiting access to tracked job data. An authorization table provides a way to control access to job tracking data. Note: DEFAT is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou require SPECIAL authority to issue the DEFAT command.

SyntaxDEFAT tabname INCLUDE(jobname,authstring[,jobname,authstring]...) [EXCLUDE(jobname,authstring[,jobname,authstring]...) [ADD|REPLACE]

Operand Description

tabname Indicates the name of the authorization table in up to eight alphanumeric characters.

jobname Indicates a job name, in up to eight characters, which you use as the first half of a jobname/authstring pair. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

authstring Indicates a string of up to eight characters, which must match one of the fields identified with a job. The fields are defined in the AUTHSTR initialization parameter. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. It forms the second half of the jobname/authstring pair.

ADD Indicates this is a new authorization table definition. The definition fails if a definition with the same name already exists. This is the default.

REPLACE Indicates an authorization table is being replaced. This operand is necessary if an authorization table with the same name exists, and you want to change it.

DEFAT Command: Define Authorization Table

248

Usage notesThe authorization string may be any of the account number fields or a security user ID, as decided by the installation. To access job-tracking information, the name of the tracked job and the account number or user ID related to the job must have an exact match in the authorization table assigned to the user requesting the tracking data.A user is associated with an authorization table via the DEFUSER command.The INCLUDE section of the authorization table gives specific control over tracked job information. It does this by listing jobname/authstring pairs (any number can be specified in one DEFAT command). The user to whom an authorization table is assigned can access any of the jobs listed in the INCLUDE section of the table, provided the name and authstring of the job matches a jobname/authstring pair in the table.The EXCLUDE feature is useful when the INCLUDE section specifies a generic group of jobs by the use of asterisks or a hyphen. Specific jobs within such a group can be excluded with the EXCLUDE operand.

If you want to edit or change the authorization table, use the DEFAT command with the REPLACE operand.

Related informationFor information on associating an authorization table with a user, see the DEFUSER command.For information on specifying one of jobs related fields used to identify the ownership of a job, see the ESP Workload Manager Installation and Configuration Guide.

Examples Define job name and authorization stringIn the following example, the first job name is JOB1, and the authorization string that makes up the pair is PROD. PROD represent the user ID for the job and the AUTHSTR initialization parameter has been set to RACUSER. JOB2 is paired with the same authstring. JOB1 and JOB2 using account PROD are, therefore, accessible to users who have the authorization table AUTHTAB1 assigned to them:DEFAT AUTHTAB1 INCLUDE(JOB1,PROD,JOB2,PROD)

Set authorization string to account numberIn the following example, the authorization string is the first account number as defined by the AUTHSTR initialization parameter. Any job name beginning with the three characters ABC or XYZ, with an account number that begins with AC0, excluding AC02:DEFAT AUTHTAB2 INCLUDE(ABC-,AC0-,XYZ-,AC0-) EXCLUDE(-,AC02)

249

Define authorization tableThe following DEFAT command defines an authorization table:DEFAT AUTHTAB3 INCLUDE(JOB1,AC02,JOB2,ACO2)

The following table shows whether a user whose authorization table is AUTHTAB3 is allowed access to various jobname/account combinations:

Jobname Account AccessJOB1 AC02 ALLOWEDJOB2 AC02 ALLOWEDJOB1 ACO2A DISALLOWED

DEFAULT Command: Define Default Job Card Values

250

DEFAULT Command: Define Default Job Card Values

Defines default values for use on job card JCL submitted by ESP.Note: DEFAULT is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

Syntax{DEFAULT|DEFLT} {[USER{(userid|NONE)}]} {[GROUP{(racfgroupid|(NONE)}]} {[PASSWORD{(password)|(NONE)}]}

Usage notesThe DEFAULT command is not commonly used as the use of USER and PASSWORD on job cards is not very common.The DEFAULT command provides the ability to set defaults for jobs submitted by ESP. If any of these operands is already specified on a job card, it is not overridden.

Example Define default user ID, group and passwordIn the following example, the default user ID is RACUSER1, the default group is PAYROLL, and the default password is MYSECRET, on the job card for submitted JCL:DEFAULT USER(RACUSER1) GROUP(PAYROLL) PASSWORD(MYSECRET)

Operand Description

userid Indicates the user ID you want ESP to place as an operand of the USER keyword on the job card for JCL submitted by ESP.

racfgroupid Indicates the group name you want ESP to place as an operand of the GROUP keyword on the job card for JCL submitted by ESP.

password Indicates the password you want ESP to place as an operand of the PASSWORD keyword on the job card for JCL submitted by ESP.

NONE Use this if you want to nullify a previous setting. The corresponding operand on the job card is left unmodified.

251

DEFCAL Command: Define Calendars

Defines an ESP calendar. Use calendars to define scheduling terms that satisfy specific processing situations.

TypeGeneral command.

AuthorityYou require SPECIAL or CALENDARDEF authority in a non-SAF environment to issue the DEFCAL command. With SAF, you control access to calendars using the CALENDAR.calname resource.

Syntax{DEFCAL|DEFC} calname [OWNER(string)] [DEPARTMENT(deptid)] [LOGICAL|ABSOLUTE] [SHIFT(hh:mm)] [WEEKSTART(day)] [WORKDAYS(workday[,workday]...)]

Operand Description

calname Indicates the name of the calendar. Can be up to eight alphanumeric or national characters ($,#,@). The first character must be alphabetic.

string Indicates a user/group in up to eight characters. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. This controls who can alter or delete the calendar. It doesn’t control who can define holidays and special days for the calendar. This applies only if you are using ESP’s internal security.

deptid Indicates a department name of up to eight characters to which this calendar belongs.Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. This applies only if you are using ESP’s internal security.

LOGICAL/ABSOLUTE

Indicates a logical calendar or an absolute calendar. The default is ABSOLUTE (days begin at midnight). Note: Absolute calendars are recommended.

hh:mm Indicates the start time of a logical day. If specified, your logical day is shifted forward by the specified time.

day Indicates the first day of the week. This overrides the default specified in the ESP initialization parameters.

DEFCAL Command: Define Calendars

252

Usage notesWhen ESP is installed, a calendar called SYSTEM is defined. All Events have READ access to the SYSTEM calendar.Note: The SYSTEM calendar should contain only those scheduling entries that all

ESP users need.Once a calendar is defined, users that have access can define holidays, special days and special period entries to be placed in it.You can also define a calendar using ESP Workstation or ESP’s ISPF interface—Option M from the ESP Main Menu.

Related informationFor information on defining calendars, see the ESP Workload Manager User’s Guide.For information on using special calendars in an Event, see the ESP Workload Manager User’s Guide.For information on using calendars, see the ESP Workload Manager User’s Guide.For information on defining and deleting holidays, see the DEFHOL and DELHOL commands.For information on defining and deleting special days, see the DEFSPEC and DELSPEC commands.For information on altering the attributes of a calendar, see the ALTCAL command.For information on displaying information about calendars, see the LISTCAL command.For information on assigning default calendars to users in a SAF environment, see the ESP Workload Manager Security Guide.For information on assigning default calendars to users in a non-SAF environment, see the DEFUSER and DEFGROUP commands.

Examples Define the system calendarIn the following example, the system calendar is defined. The first day of the week, and the workdays are determined by the ESP initialization parameters:DEFCAL SYSTEM

workday Indicates which days are to be considered workdays. Separate each with a comma. This overrides the default specified in the ESP initialization parameters.

Operand Description

253

Define first day of week and workdaysIn the following example, CAL1 is defined. The first day of the week is Sunday and workdays are Monday through Friday, inclusive:DEFCAL CAL1 OWNER(CYBER) WEEKSTART(SUN) -WORKDAYS(MON,TUE,WED,THU,FRI)

DEFGROUP Command: Define Groups

254

DEFGROUP Command: Define Groups

Defines a group to ESP. Defining a group and connecting users to it allows you to manage and control access to and use of ESP at a group level.Note: DEFGROUP is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou require SPECIAL or CALENDARDEF authority in a non-SAF environment to issue the DEFGROUP command.

Syntax{DEFGROUP|DEFG} groupname EVENT(eventdsid) [DEPARTMENT(deptid)] [AUTH(OPER)] [UREAD] [RACID] [CALENDAR(cal1[,cal2]...)]

Operand Description

groupname Indicates a one to eight character group name.

eventdsid Indicates in up to eight characters the logical identifier of the Event data base used to store Events prefixed with the group name defined.

deptid Indicates a department name of up to eight characters to which this group belongs. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

OPER Indicates Events having this group name as a prefix can contain operator commands.

UREAD Indicates universal read access is available for any Event defined using this group prefix.

255

Usage notesThe default calendars are used by Events that have no explicit calendar specification. They are searched in the order specified. All Events automatically have access to the SYSTEM calendar, which is searched after the default calendars.A user with an authority attribute of ANY has access to any Group. Such a user does not need to be connected to any Group.ESP controls access to Events by the high level prefix under which the Event is stored. If a user saves an Event using an ESP user ID as the high level prefix, only that user and users with 'ANY' authority can access the Event. When any member of a group saves an Event using the ESP group name as the high level prefix, any member of that group and users with 'ANY' authority have access to the Event.You can also define and list a group using ESP’s ISPF interface—Option M from the ESP Main Menu.

Related informationFor information on defining and deleting users, see the DEFUSER/DELUSER commands.For information on deleting groups, see the DELGROUP command.For information on displaying information about a group, see the LISTGRP command.For information on altering a group definition, see the ALTGROUP command.For information on connecting and disconnecting users to and from groups, see the CONNECT and DISCONN commands.

Examples Define a group and assign an Event data setIn the following example, a group called PROD is defined and Event data set EVENT1 is assigned to the group. Events are processed under the groupname:DEFGROUP PROD EVENTSET(EVENT1) RACID

RACID Indicates the group name should be used for security attributes when ESP processes an Event rather than the ID of the defining user.

cal1 Indicates the name of the first default calendar for Events that start with the group prefix, up to eight characters.

cal2 Indicates the name of the second default calendar, up to eight characters.

Operand Description

DEFGROUP Command: Define Groups

256

Define a group and set a default calendarIn the following example, a group called PAYGRP is defined and Event data set EVENT2 is assigned to the group. PAYGRP’s default calendar is FISCAL:DEFGROUP PAYGRP EVENTSET(EVENT2) CALENDAR(FISCAL)

Define authority to issue operator commandsIn the following example, SCHED is defined as part of the PRODSUPP department. SCHED has the authority to issue ESP operator commands:DEFGROUP SCHED EVENTSET(EVENT1) DEPARTMENT(PRODSUPP) AUTH(OPER)

257

DEFHOL Command: Define Holidays

Defines a holiday.

TypeGeneral command.

AuthorityYou can define holidays only in the calendar defined as your first default calendar, or in calendars to which you have access. If you do not have any default calendars defined, the holiday is automatically stored in the SYSTEM calendar.

Syntax{DEFHOL|DEFH} holidayname START(starttime) END(endtime)|FOR(duration) [RETAIN{(2,days)|(x,units)}] [CALENDAR(calname)]

Operand Description

holidayname Indicates the name of a holiday. Can be up to 16 alphanumeric or national characters ($,#,@) or underscore.

starttime Indicates the starting time and date of the holiday. If the date specification contains separators, it should be enclosed in quotes. You have the option to specify UNTIL followed by a time and date specification, which tells ESP when the holiday ends. If you use UNTIL, you must enclose the entire specification in quotes.

endtime Indicates the time and date the holiday ends. It is mutually exclusive with the FOR operand, and with UNTIL or ENDING in the START operand. Specifying a combination of these terms produces unpredictable results.

duration Indicates the length of the holiday in hours.

x,units Indicates the number of days, weeks or years after each occurrence of the holiday that you want to remain on the system for reference. Specify 1-9999 for x. If you specify a number but no units, this value automatically defaults to days. This determines how long you can refer back to a holiday after it occurs.

calname Indicates the name of the calendar in which the holiday is to be defined, otherwise user ID defaults are used.

DEFHOL Command: Define Holidays

258

Usage notesThe duration of a holiday is 24 hours, unless you specify otherwise.You can define multiple holidays with the same name. However, if they are on the same calendar, each holiday must have a different starting date and time. If you are creating consecutive holidays, you may find it simpler to combine them into one holiday with duration set to the total duration of the separate holidays.You cannot define a holiday in a given calendar if there is a special day with the same name defined in that calendar or in the system calendar. However, if the special day is defined elsewhere, you can define a holiday with the same name as the special day. In that case, a warning appears in the audit log.In an Event definition, you can schedule based on holidays or use an ON command such as 'on holiday'. This allows you to bypass, delay or advance the schedule if it normally falls on a holiday or a particular day of the week.You can also define and list a holiday using the ESP Workload Manager ISPF interface—Option L from the ESP Main Menu.

ESP Workload Manager deletes a holiday after its retain count expires. It does this whenever an update is made to the calendar containing the holiday.For logical day processing, holidays should be defined in ABSOLUTE terms even if stored in a LOGICAL calendar.Note: You should not need to use logical calendars. Logical calendars can cause

unanticipated results. Cybermation recommends you use absolute calendars because of their ease of use, and because they can handle almost all scheduling requirements.

Related informationFor information on specifying holiday names in schedule criteria, see the ESP Workload Manager User’s Guide.For information on deleting holidays, see the DELHOL command.For information on defining and deleting special days and periods, see the DEFSPEC and DELSPEC commands.For information on displaying holiday information, see the LISTHOL command.For information on advancing, delaying, or ignoring Event processing, see the ON command.For information on displaying information about a calendar, see the LISTCAL command.

259

Examples Define Christmas for three yearsIn the following example, multiple holidays with the same name—CHRISTMAS are defined as 24 hour holidays in three successive years:DEFHOL CHRISTMAS START('25 DECEMBER 2000') FOR(24)DEFHOL CHRISTMAS START('25 DECEMBER 2001') FOR(24)DEFHOL CHRISTMAS START('25 DECEMBER 2002') FOR(24)

Define holiday with specific start and end timeIn the following example, NEW_YEARS is defined to start on December 31st until January 2nd at 00:00:DEFHOL NEW_YEARS START('31ST DEC 2000 UNTIL 2ND - JAN 2001')

Define holiday with 4 pm start timeIn the following example, DAYOFF is defined to start on January 5th, 2001 at 4 pm ending January 6th, 2001 at 4 pm. The definition of DAYOFF resides on MYCAL for six weeks after it occurs:DEFHOL DAYOFF START('4PM JAN 5, 2001') - END('4PM JAN 6, 2001') RETAIN(6,WEEKS) CALENDAR(MYCAL)

DEFPN Command: Define Pnodes

260

DEFPN Command: Define Pnodes

Defines a processing node (Pnode) to ESP Workload Manager. ESP Workload Manager tracks jobs through some Pnodes automatically. After a job passes through the output phase, you can identify additional (manual) Pnodes for the job. These processing phases may include bursting of output, distribution and so on.

TypeAuthorized command.

AuthorityThe PNODE.pnodename resource control the ability to use the PNODE command.

SyntaxDEFPN name [ADD|REPLACE] [SEQUENCE(seqno)] [OWNER(ownerid)

Usage notesAt installation time, the INPUT, EXEC and OUTPUT Pnodes are defined. ESP Workload Manager tracks jobs through these Pnodes automatically.A job does not need to complete a manual Pnode for a successor job to run. If you need to set up job dependencies with a manual phase of a job, consider using manual tasks in an ESP Application.

Operand Descriptionname Indicates the name of the Pnode, up to 16 characters.

ADD Indicates this is a new definition. The request fails if a definition with the same name already exists. ADD is the default.

REPLACE Replaces a current Pnode definition of same name.SEQUENCE(seqno) Indicates the relative sequence number used when displaying

queues. When a DQ or DN command is used, the Pnode queues are displayed according to their sequence numbers. The sequence numbers can be in the range 0 to 255.

OWNER(ownerid) The user IDs that can alter or delete this pnode definition. You can use wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) to perform masking. The default ownerid is the user ID that defined the pnode. This operand applies only if you are using ESP Workload Manager internal security.

261

Once you have defined the Pnode, authorized users can enter the POST command to post a job as having completed processing at a specific Pnode.

Related informationFor information on defining processing nodes (Pnodes), see the ESP Workload Manager Advanced User’s Guide.For information on deleting manual Pnodes, see the DELPN command.For information on displaying Pnode information, see the LISTPN command.For information on posting a job complete from a manual Pnode, see the POST command. For information on specifying the name of a Pnode through which a job has to pass before it can be marked complete, see the PNODES statement.

Examples Define job-tracking PnodesIn the following example, Pnodes that ESP uses to track jobs are defined. ESP automatically assigns sequence numbers:DEFPN INPUTDEFPN EXECDEFPN OUTPUT

Define a Pnode with a sequence numberIn the following example, BURSTER is defined. When the queue is displayed, the relative sequence number for this Pnode is 150.DEFPN BURSTER SEQ(150)

Define a Pnode with limited alter and delete access for usersOnly users with IDs beginning with SCH can alter or delete this entry.DEFPN BURSTER OWNER(SCH-)

Update a PnodeIn the following example the existing Pnode BURSTER is updated with a different sequence number:DEFPN BURSTER SEQ(100) REPLACE

Once a Pnode is defined (above), you can use that Pnode as a job requirement as follows:JOB PAYJOB1 PNODES BURSTER RUN DAILYENDJOB

DEFPN Command: Define Pnodes

262

To post PAYJOB1 complete from the BURSTER Pnode, authorized users can issue the following POST command:POST PAYJOB1 PNODE(BURSTER)

263

DEFPRINT Command: Define Logical Reports - DATASET Option

Defines a logical report name to which output is directed. It defines the characteristics of an auxiliary output device and associates the logical report name to it. Output can be directed to a sysout class, data set, or DD file.

TypeGeneral command.

SyntaxDEFPRINT repname DATASET('dsname[(member)]') [VOLUME(serial)] [UNIT(unitname)] [SPACE(primary,[secondary])TRACKS|BLOCKS|CYLINDERS] [EXTEND] [LRECL(length)] [RECFM{(V)|(F)}] [PAGELENGTH(lines)] [BLOCK(size)] [BLKSIZE(block)]

Operand Description

repname Indicates a one to eight character alphanumeric logical report name.

dsname Identifies the data set name to which the output is diverted. You should include a member name if you are diverting output to a PDS.

EXTEND Indicates the output should be added to the end of the data set. If you do not specify EXTEND, the data set is overwritten.

length Indicates the logical record length for each line of output. Specify the number of characters you want in each line.

V Indicates variable length records. This is the default. The line length is four bytes less than what you specified under 'LRECL'.

F Indicates fixed length records.

lines Indicates the number of lines on each page, including titles and footings.

size Indicates the size in bytes of a block allocation unit.

block Indicates the actual length of blocks on a data set. The limit is 32767 bytes.

DEFPRINT Command: Define Logical Reports - DATASET Option

264

Usage notesYou must use the ENDPRINT command to close each data file you opened with DEFPRINT.

Related informationFor information on ending a report print definition, see the ENDPRINT command.For information on directing output to a file, see the DEFPRINT command—File Option.For information on directing output to a sysout class, see the DEFPRINT command - SYSOUT Option. For information on requesting that a data type printout be directed to a data set, sysout class or DD file from Page mode, see the HARDCOPY command.For information on setting the default output environment for TITLE processing, see the SETPRINT command.For information on defining a title to be displayed at the top of the next and subsequent pages of printed data, see the TITLE command.

Examples Define a logical report nameIn the following example, CYBRPT1 is associated with a preallocated data set. Output is directed to ESP.MODEL.REPORT1:DEFPRINT CYBRPT1 DATASET('ESP.MODEL.REPORT1')

Define dynamically allocated reportIn the following example, ESP.MODEL.REPORT2 is dynamically allocated and assigned a logical identifier of CYBRPT2. Output is directed to ESP.MODEL.REPORT2:DEFPRINT CYBRPT2 DATASET('ESP.MODEL.REPORT2') - SPACE(2,1) TRACKS VOLUME(CYB001) - LRECL(150) RECFM(FBA) BLKSIZE(15000)

lines Indicates the number of lines on each page, including titles and footings.

size Indicates the size in bytes of a block allocation unit.

block Indicates the actual length of blocks on a data set. The limit is 32767 bytes.

Operand Description

265

DEFPRINT Command: Define Logical Reports - SYSOUT Option

Defines a logical report name to which output is directed. It defines the characteristics of an auxiliary output device and associates the logical report name to it. Output can be directed to a sysout class, data set, or DD file.

TypeGeneral command.

SyntaxDEFPRINT repname SYSOUT(class) [DEST(destcode)] [COPIES(n)] [FORM(type)] [LRECL(length)] [RECFM{(V)|(F)}] [PAGELENGTH(lines)] [UCS(char)] [SPIN]

Operand Description

repname Indicates a one to eight character alphanumeric logical report name.

class Indicates a one-character class number.

destcode Indicates a destination code of up to eight characters. If you do not specify 'DEST', the destination defaults to 'LOCAL'.

n Indicates the number of copies you want printed. The maximum is 240 copies.

type Indicates the type of the form you want to use for printing, using up to four characters.

length Indicates the logical record length for each line of output. Specify the number of characters you want in each line.

V Indicates variable length records. This is the default. The line length is four bytes less than what you specified under 'LRECL'.

F Indicates fixed length records.

lines Indicates the number of lines on each page, including titles and footings.

char Indicates the universal character set type you want to be used on the printer for this printout.

DEFPRINT Command: Define Logical Reports - SYSOUT Option

266

Usage notesYou must use the ENDPRINT command to close each data file you opened with DEFPRINT.

Related informationFor information on ending a report print definition, see the ENDPRINT command.For information on directing output to a file, see the DEFPRINT command - File Option.For information on directing output to a data set, see the DEFPRINT command - DATASET Option.For information on requesting that a data type printout be directed to a data set, sysout class or DD file from Page mode, see the HARDCOPY command.For information on setting the default output environment for TITLE processing, see the SETPRINT command.For information on defining a title to be displayed at the top of the next and subsequent pages of printed data, see the TITLE command.

Example Direct output to sysout class JIn the above example, output for report DEPT123 is directed to a sysout class of J:DEFPRINT DEPT123 SYSOUT(J)

SPIN Indicates the data should be made available for printing as soon as you enter the ENDPRINT command.

Operand Description

267

DEFPRINT Command: Define Output to File

Defines a logical report name to which output is directed. It defines the characteristics of an auxiliary output device and associates the logical report name to it. Output can be directed to a sysout class, data set, or DD file.

TypeGeneral command.

SyntaxDEFPRINT repname DDNAME(file) [EXTEND] [LRECL(length)] [RECFM{(V)|(F)}] [PAGELENGTH(lines)] [BLOCK(size)] [BLKSIZE(block)]

Usage notesYou must use the ENDPRINT command to close each data file you opened with DEFPRINT.

Operand Description

repname Indicates a one to eight character alphanumeric logical report name.

file Identifies the data set name to which the output is diverted. You should include a member name if you are diverting output to a PDS.

EXTEND Indicates the output should be added to the end of the data set. If you do not specify EXTEND, the data set is overwritten.

length Indicates the logical record length for each line of output. Specify the number of characters you want in each line.

V Indicates variable length records. This is the default. The line length is four bytes less than what you specified under 'LRECL'.

F Indicates fixed length records.

lines Indicates the number of lines on each page, including titles and footings.

size Indicates the size in bytes of a block allocation unit.

block Indicates the actual length of blocks on a data set. The limit is 32767 bytes.

DEFPRINT Command: Define Output to File

268

Related informationFor information on ending a report print definition, see the ENDPRINT command.For information on directing output to a file, see the DEFPRINT command - File Option.For information on directing output to a sysout class, see the DEFPRINT command - SYSOUT Option. For information on requesting that a data type printout be directed to a data set, sysout class or DD file from Page mode, see the HARDCOPY command.For information on setting the default output environment for TITLE processing, see the SETPRINT command.For information on defining a title to be displayed at the top of the next and subsequent pages of printed data, see the TITLE command.

Example Route report to a file with logical record length 133In the following example, output for report JR1RPT is routed to a file. The logical record length for each line of output written to RPTDD1 should be 133, in fixed length records:DEFPRINT JR1RPT DDNAME(RPTDD1) LRECL(133) RECFM(F)

269

DEFPRIO Command: Assign Default Priorities

Assigns a default priority to all jobs with no priority specified in their JCL for the purposes of modeling. Priorities can range from 1 to 15, with 15 being the highest.

TypeModeling command.

SyntaxDEFPRIO nn

Usage notesUse the DEFPRIO command to assign a default selection priority to all jobs without one. This is normally the default job priority defined on your system.Within a job class, the model processor selects jobs for execution in order of priority. A job with a higher priority is selected for execution sooner; jobs with the same priority are selected on a first-in first-out basis.This command only applies to modeling. It does not affect actual job execution.

Related informationFor information on ESP’s modeling feature, see Advanced Forecasting in the ESP Workload Manager Advanced User’s Guide.

Example Set default priorityIn the following example, a default priority of 12 is set for all jobs whose JCL does not already contain a priority statement:DEFPRIO 12

Operand Description

nn Indicates a default priority in the range 1-15. The highest priority is 15. If not specified, the default is 3.

DEFSIG Command: Define Signals

270

DEFSIG Command: Define Signals

Defines a signal. A signal can represent a manual task, such as the arrival of a tape, or an automated task, such as the successful completion of a job. Signals are commonly used with DJC/JES3 networks, which do not offer the flexibility of Applications.

TypeGeneral command.

SyntaxDEFSIG signalname [GEN(genno)]

Usage notesSignals cause an ESP Event to wait for a condition in addition to its schedule criteria before it executes. A signal may represent a manual task, such as the arrival of an input tape, or an automated task, such as the completion of a job.Signals are available only at the Event level. If you are using an Application and need to set up conditions at the job level for jobs in the Application, the best method is through tasks.

Related informationFor information on signal processing, see the ESP Workload Manager Advanced User’s Guide.For information on cycling a signal, see the SIGCYCLE command.For information on posting a generation of a signal, see the SIGPOST command.

For information on identifying that signal must be marked complete before execution of the Event, see the SIGWAIT command.For information on altering the numbers of generations of a signal, see the ALTSIG command.For information on displaying all generation of a signal, see the LISTSIG command.

Operand Description

signalname Indicates the name of the signal. A signal has a two-part name consisting of a prefix which is a group name (or user ID), followed by a description of up to 16 characters. If prefix is not specified, the current group prefix is used.

genno Indicates the number of generations of a signal to be stored. The default, if not specified, is 1.

271

For information on setting up job level conditions in Applications, see the ESP Workload Manager User’s Guide.

Examples Define seven generationsIn the following example, CYBER.DAILY_SIGNAL1 is defined with seven generations to be stored:DEFSIG CYBER.DAILY_SIGNAL1 GEN(7)

Use user prefixIn the following example, SIGNAL2 is defined using the current group/user prefix with five generations to be stored. If the current group prefix is TX5312, the signal name is TX5312.SIGNAL2:DEFSIG SIGNAL2 GEN(5)

DEFSPEC Command: Define Special Days

272

DEFSPEC Command: Define Special Days

Defines a special day or period.

TypeGeneral command.

AuthorityYou can only define special days in the calendar defined as your first default calendar, or in calendars to which you have access. If you do not have any default calendars defined, the special day is stored automatically in the SYSTEM calendar.

SyntaxDEFSPEC specname ON(date)|REPEAT('schedule') [CALENDAR(calname)] [USING(cal1[,cal2]...)] [RETAIN(x,units)]

Operand Description

specname Indicates a name for the special day you are defining, using up to 16 characters. The name may include the underscore, numerics, and national characters. Blanks are not allowed.

date Indicates the date and time on which the special day occurs, or specifies the beginning date and time of a single special period. You must specify at least two special periods of the same name so that ESP knows when the first period ends. If the date specification contains separators, it must be enclosed in quotes. ON is mutually exclusive with the REPEAT operand.

schedule Use this operand when specifying multiple special days or regular periods with the same name. It allows you to specify more occurrences of an existing special day or period definition without having to completely redefine them. Specify a valid schedule criteria, that defines when the special day or period should repeat itself (such as 'every 15th workday at 9 am', '6 times', 'until 15th June'). If you use separators, enclose the statement in quotes. REPEAT is mutually exclusive with the ON operand.

calname Indicates the calendar in which the special day or period is to be defined. This is the TARGET calendar on the ISPF panel.

cal1, cal2 Indicates up to two calendar names. The USING operand is used if you refer to a special day or period in the REPEAT operand. The calendars you specify with USING tell ESP where to find the special day or period definitions to which you are referring. This is the SOURCE calendar on the ISPF panel.

273

Usage notesYou cannot define a special day in a given calendar if there is a holiday with the same name defined in that calendar or in the system calendar. However, if the holiday is defined elsewhere, you can define a special day with the same name as the holiday. In that case, a warning appears in the audit log.If you define two special days with the same name, ESP Workload Manager treats the time between them as a special period.You cannot use ON and REPEAT together. You must, however, use one of these two options after specifying the required special day or period name.If you use the REPEAT operand without using the n TIMES operand, and without specifying either an UNTIL or ENDING date, ESP uses one year as a default. You can only use the n TIMES operand if you use REPEAT.Use the RETAIN operand to ensure that a special day definition remains on the system for more than the default of two days after the special day (or first day of a special period) has passed. For example, you probably want to ensure that any fiscal month definition remains on the system for at least one year, so you can refer to the '9TH FISCAL_MONTH OF FISCAL_YEAR'. Specify 'RETAIN(1,YEAR)' or 'RETAIN(365)' (if units are omitted, this defaults to days). If all payroll days need to be referred to for at least six months (180 days) after they pass, you would specify: 'RETAIN(180,DAYS)'. ESP deletes a special day after the retain count expires. It does this whenever an update is made to the calendar containing the special day.You can also define and list special days and periods using ESP’s ISPF interface—Option L from the ESP main menu.

Related informationFor information on specifying special days or periods in schedule criteria, see the ESP Workload Manager User’s Guide.For information on deleting special days or periods, see the DELSPEC command.For information on defining and deleting holidays, see the DEFHOL and DELHOL commands.For information on displaying special day and period information, see the LISTSPEC command.For information on displaying information about a calendar, see the LISTCAL command.

x, units Indicates the number of days, weeks or years after each occurrence of the special day or period that you want it to remain on the system for reference. The default is two days. If you specify a number but no units, this value automatically defaults to days.

Operand Description

DEFSPEC Command: Define Special Days

274

Examples Define special day in one calendar while referencing anotherIn the following example, YEAR_END is defined as the last workday of August of the current year, in the CAL2 calendar. CAL1 is used as a reference for workdays:DEFSPEC YEAR_END ON('LAST WORKDAY OF AUG') USING(CAL1) -CALENDAR(CAL2)

Define repeating special dayIn the following example, PAYROLL_DAY is defined and occurs every two weeks on Thursdays. The special day definition is to remain on the system for one year:DEFSPEC PAYROLL_DAY -REPEAT('THU EVERY 2 WEEKS UNTIL JAN3,1998') -RETAIN(365)

Define repeating special periodsIn the following example, 39 special periods called SESSION, which occur regularly, are defined every four weeks starting on 1st January. The special period definition is to remain on the system for one year:DEFSPEC SESSION REPEAT('39 TIMES EVERY 4 WEEKS STARTING - 1ST JAN') RETAIN(1 YEAR)

Define fiscal yearIn the following example, fiscal years starting May 1st are defined up to the year 2005 in the calendar ACCT1. Each fiscal year is retained on the system for two calendar years:DEFSPEC FISCAL_YEAR REPEAT ('1MAY YEARLY UNTIL 30APR2005') -CAL(ACCT1) RETAIN(2 YEARS)

275

DEFSYML Command: Define Symbolic Variable Library

Defines or alters a symbol library. This allows ESP to reference a collection of data sets using a logical identifier.

TypeGeneral command.

AuthorityYou require SPECIAL, SCHEDULER or CALENDARDEF authority to issue the DEFSYML command in non-SAF environments. With SAF, you control access to symbol libraries using the SYMLIB.symname resource.

SyntaxDEFSYML name [DATASET(dsn[,dsn]...)] [USERS(user[,user]...)] [ADD|REPLACE]

Operand Description

name Indicates the name of the symbol library. It can consist of up to eight alphanumeric characters, the first of which must be alphabetic.

dsn Indicates one or more data sets to be scanned when the symbol library set is referenced by an Event. The names should be the valid names of data sets. If a data set is a PDS, then each member containing symbols must be specified. Separate each with a blank or comma.

user Indicates one or more user or group prefixes or masks, to restrict access to the symbol library sets. Wildcard characters asterisk and hyphen (see “Overview” at the begining of this book) can be used to perform masking. If no user IDs are specified, access to the symbol library set is not restricted. This applies only if you are not using SAF.

ADD Indicates this is a new definition, and is not to replace an existing entry, if there is one. This is the default.

REPLACE Indicates this definition replaces an existing one.

DEFSYML Command: Define Symbolic Variable Library

276

Usage notesTo use a symbol library, use the SYMLIB command in an Event definition.Users can define their own variables and use built–in symbolic variables in JCL, command input, and in job definitions. A user can define and work with symbolic variables in either a symbolic variable library or an ESP Procedure.When symbolic variable libraries are used to store user-defined symbolic variables, the ability to use ESP’s IF-THEN-ELSE language construct is lost. If you want to use IF-THEN-ELSE type statements in combination with user-defined symbolic variables, you need to store those definitions in a member of a PDS and invoke that member from your Event or ESP Procedure.If you need to alter a symbol library definition, use the DEFSYML command with the replace option.

Related informationFor information on setting symbol libraries, see the ESP Workload Manager User’s Guide.For information on invoking user symbolic variables, see the ESP Workload Manager Advanced User’s Guide.For information on displaying information on symbol libraries, see the LISTSYML command.For information on deleting a symbol library, see the DELSYML command.For information on requesting the inclusion of one or more symbolic variable libraries, see the SYMLIB command.

Examples Define memberIn the following example, SYMSET1 is defined and consists of the member DATEPARM of the ESP.SYMLIB data set:DEFSYML SYMSET1 DA('ESP.SYMLIB(DATEPARM)')

Define data set and memberIn the following example, SYMSET2 is defined and consists of the sequential data set CYBER.PAYROLL.SYMBOLS and the member DATE of the PDS CYBER.COMMON.SYMBOLS:DEFSYML SYMSET2 DA('CYBER.PAYROLL.SYMBOLS', -'CYBER.COMMON.SYMBOLS(DATE)')

Replace current definitionIn the following example, the current SYMSET1 definition is replaced:DEFSYML SYMSET1 DA('ESP.SYMLIB(DATEPARM)') REPLACE

277

DEFTJ Command: Define Tracking for Jobs

Defines the tracking parameters for a job, either by full job name or job name prefix. The preferred method for defining tracked jobs is a Job Tracking Definition Table.

TypeGeneral command.

AuthorityYou require ALTER authority on the TJD.jobname resource to issue the DEFTJ command in a SAF environment.You require SCHEDULER authority or a matching ownership string to issue the DEFTJ command in a non-SAF environment.

SyntaxDEFTJ jobname MODEL(modelname) [TRACK|NOTRACK] [INDEX(indexcount)] [OWNER(ownerid)] [PREFIX]

Operand Description

jobname Indicates the job or job prefix to be defined. If a prefix is defined, the jobname should contain wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book.).

modelname Indicates the name of the tracking model to be associated with the jobs. This is required unless you specify NOTRACK. You can override this using the MODEL statement for a job in an Application.

TRACK Indicates you want the job to be tracked. This is the default.

NOTRACK Indicates you do not want the job tracked.

indexcount Indicates the number of ancestors of a job that are to remain on the job index data set. This defaults to the index count specified on the tracking model for the job.

ownerid Indicates an ownership string for the jobs. Wildcard characters asterisk and hyphen (see “Overview” at the begining of this book) can be used to perform masking. This applies if your are using ESP’s internal security.

PREFIX Indicates the entry being defined is a jobname prefix entry rather than a full jobname. Use this keyword if the jobname contains asterisks or a hyphen.

DEFTJ Command: Define Tracking for Jobs

278

Usage notesAll tracked jobs must be associated with a tracking model.As an alternative to using the DEFTJ command to tell ESP what to track, you can use a job tracking definition table (JTDT) to identify the characteristics of the jobs you want ESP to track. ESP can track jobs based on jobname, execution class, programmer name, account number, job type or the user ID associated with the jobs. Job tracking definition tables provide greater flexibility defining the properties of the jobs you want ESP to track and are therefore recommended.

Related informationFor information on job tracking definition tables, see the ESP Workload Manager Installation and Configuration Guide.For information on defining or altering a tracking model, see the DEFTM command.For information on displaying tracked jobs, see the LTJ and LJ commands.For information on changing characteristics of a tracked job, see the ALTTJ command.For information on deleting a tracked job definition, see the DELTJ command.

Example Define trackingThe following DEFTJ commands define what ESP will track:DEFTJ PAYJOB99 MODEL(PAYSPEC) INDEX(10)DEFTJ PAY- MODEL(PAYREG) PREFIXDEFTJ TEST- NOTRACKDEFTJ - MODEL(MODEL1) PREFIX

In the above example:• PAYJOB99 is associated with the PAYSPEC tracking model. Ten instances of

PAYJOB99 are retained on the job index file.• Jobs starting with PAY are associated with the PAYREG tracking model• Jobs starting with TEST are not tracked • All other jobs are associated with the MODEL1 tracking model.

279

DEFTM Command: Define Tracking Models

Defines or alters a job tracking model. A tracking model allows you to keep the tracking characteristics that apply to a job or group of jobs in one place. Each job you want ESP to track must have an associated tracking model.

TypeGeneral command.

AuthorityYou require SPECIAL authority to issue the DEFTM command in a non-SAF environment. With SAF, you control access to tracking models using the MODEL.modelname resource.

SyntaxDEFTM name [TRACK|NOTRACK] [PNODE(pnode[,pnode]...)] [ADD|REPLACE] [INDEX(10)|(indexcount)] [HISTFILE(histid)] [MONITOR(groupname)] [JOBSTARTEVENT(eventname)] [JOBENDEVENT(eventname)] [JOBFAILEVENT(eventname)] [JOBABENDEVENT(eventname)] [STEPENDEVENT(eventname)] [STEPFAILEVENT(eventname)] [STEPABENDEVENT(eventname)]

Operand Description

name Indicates the name of the tracking model, in up to eight characters.

TRACK Indicates you want jobs using this model tracked. This is the default.

NOTRACK Indicates jobs using this model are not tracked. This is normally specified in the job tracking definition table.

DEFTM Command: Define Tracking Models

280

PNODE(pnode) Indicates the name of a processing node through which a job has to pass before it can be considered complete. If more than one pnode is specified, the jobs must pass through the pnodes in the order specified. The pnode name can be followed by a parenthesized string containing a due-out time. This can be an actual time in the form 'HH.MM', or an elapsed time in the form '+HH.MM'. The pnodes INPUT, EXEC, and OUTPUT do not have to be specified unless using a due-out time. This is not commonly used with ESP Applications.

ADD Indicates this is a new definition. This is the default. The request fails if a definition with the same name already exists.

REPLACE Indicates the model is to be replaced. This operand must be used if a definition with the same name exists.

INDEX(indexcount) Indicates the number of ancestors of a job that are to remain on the job index data set. This value should be at least as large as the highest number of similarly named jobs to be active in the job queues at one time. The default is 10 jobs.

HISTFILE(histfid) Indicates the identifier of a job history recording data set (its logical name) that is to receive history data for jobs using this tracking model. This allows you to REPORT on the jobs.

MONITOR(groupname)

Indicates any job using this model should check for monitor points and should search Events with this ESP group prefix for a monitor Event. You can override this using the MONITOR statement for a job in an ESP Application.

JOBSTARTEVENT Indicates the name of the Event to be triggered whenever any job using this model starts.

JOBENDEVENT Indicates the name of the Event to be triggered whenever any job using this model ends (successfully or unsuccessfully).

JOBFAILEVENT Indicates the name of the Event to be triggered whenever any job using this model fails. This Event is triggered when a job abends or fails on condition codes.

JOBABENDEVENT Indicates the name of the Event to be triggered whenever any job using this model abends. This does not include condition code failures.

STEPENDEVENT Indicates the name of the Event to be triggered for each step end of any job using this model.

STEPFAILEVENT Indicates the name of the Event to be triggered for each failing step end of any job using this model. This includes abends and condition code failures.

STEPABENDEVENT Indicates the name of the Event to be triggered whenever a step abends for a job using this model. This does not include condition code failures.

Operand Description

281

Usage notesThe DEFTM command allows you to centralize the definition of tracking characteristics that can be assigned to one job, or a group of jobs. Jobs are normally associated with a tracking model using a job tracking definition table.A tracking model specifies:• A name for the model• The manual processing nodes (pnodes) through which a job passes• The number of ancestors of a job ESP should keep on the job index data set, job

monitor Events or the prefix of job monitor Events and the logical name of a history recording data set.

Related informationFor information on displaying the definition of tracking models, see the LTM com-mand.For information on deleting a tracking model definition, see the DELTM command.For information on tracking definition entries in a job tracking definition table, see the TRACKDEF statement.For information on using tracking models and job tracking definition tables, see the ESP Workload Manager Installation and Configuration Guide.For information on using job monitoring and alert processing, see the ESP Workload Manager User’s Guide.For information on deleting a tracked job definition, see the DELTJ command.

Examples:Define model, store no historyIn the following example, tracking model MODEL1 is defined and keeps the ten most recent executions (default) of each job associated with this tracking model on the job index data set. No history data is stored for jobs using this model:DEFTM MODEL1

Define model, keep three copies of job in index fileIn the following example, tracking model TESTJOBS is defined and keeps the three most recent executions of each job associated with this tracking model on the job index data set:DEFTM TESTJOBS INDEX(3)

DEFTM Command: Define Tracking Models

282

Define model, keep index and history copiesIn the following example, tracking model PRODJOBS is defined and keeps the ten most recent executions of each job associated with this tracking model on the job index data set. History data for jobs using this model are stored in the history file whose logical name is HIST1:DEFTM PRODJOBS INDEX(10) HISTFILE(HIST1)

Define model and monitor EventIn the following example, tracking model STEPMON is defined. History data for jobs using this tracking model are stored in the history file with logical name is HIST1. ESP triggers a monitor Event called CYBER.STEPEND at each end of step for jobs using this model:DEFTM STEPMON HISTFILE(HIST1) STEPENDEVENT(CYBER.STEPEND)

Replace current definitionIn the following example, tracking model MODEL1’s current definition is replaced with this new definition:DEFTM MODEL1 HISTFILE(HIST1) INDEX(5) REPLACE

Define multiple monitor EventsIn the following example, tracking model MODELSTC is defined. ESP triggers a monitor Event called CYBER.START_STC each time a started task using this model starts. ESP also triggers a monitor Event call CYBER.END_STC each time a started task using this model ends:DEFTM MODELSTC JOBSTARTEVENT(CYBER.START_STC) -JOBENDEVENT(CYBER.END_STC)

283

DEFUSER Command: Define Users

Defines a user to ESP. You must define each user to ESP before it can access and use ESP. Note: DEFUSER is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou require SPECIAL or USERDEF authority to issue the DEFUSER command in a non-SAF environment.

Syntax{DEFUSER|DEFU} userid EVENTSET(eventdsid) [GROUP{(USERID)|(groupname)|(PREFIX)}] [PASSWORD(password)] [HISTFILE(histfile)] [DEPARTMENT(deptid)] [AUTH( [OPER|NOOPER] [SPECIAL|NOSPECIAL] [ANY|NOANY] [SCHEDULER|NOSCHEDULER] [USERDEF|NOUSERDEF] [GROUPDEF|NOGROUPDEF] [CONNECTDEF|NOCONNECTDEF] [CALENDARDEF|NOCALENDARDEF])] [AUTHTAB(tabname)] [CALENDAR(cal1[,cal2]...)]

Operand Description

userid Indicates a one to eight character TSO user ID to be defined.

eventdsid Indicates, in up to eight characters, the logical identifier of the Event data base used to store Events prefixed with the user ID. Use EVENTSET(NONE) to prohibit a user from defining Events.

USERID Indicates the user ID is to be used as an Event name prefix. This is the default.

DEFUSER Command: Define Users

284

groupname Indicates the group which to use as the Event name prefix.

PREFIX Indicates the current TSO profile data set prefix is used as the Event name prefix.

password Indicates a password of up to eight characters which is to be associated with the user ID for accessing the ESP command through a batch job. This is required only if you are not using a host security package.

histfile Indicates the history file ID or mask, using up to eight characters. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. This controls access to the history files for reporting.

deptid Indicates a department name of up to eight characters to which this user belongs. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

SPECIAL Indicates the user can access commands relating to Administration.

OPER Indicates the user can issue operator commands.

ANY Indicates the user can define and access Events with any group prefix.

SCHEDULER Indicates the user can define pnodes, tracking models and job tracking parameters.

USERDEF Indicates the user can define other users within the same department, or department sub-group, provided they use the same Eventset. This user can define other users with equal or lesser authority. The DEPARTMENT keyword must be used with this keyword.

GROUPDEF Indicates the user can define other groups within the same department, or department sub-group, provided they use the same Eventset. This user can define groups with equal or less authority than his or her own group, but is not be able to use the RACID option, which is only available with the DEFGROUP command to a user with the SPECIAL attribute. The DEPARTMENT keyword must also be used with this keyword.

CONNECTDEF Indicates a user can connect any user to any group within the same department or department sub–group.

CALENDARDEF Indicates a user defines calendars and makes them available to other users within the same department or department sub–group.

NOSPECIAL Removes the SPECIAL attribute.

NOOPER Removes the OPER attribute.

Operand Description

285

Usage notesDefault calendars are used by Events that have no explicit calendar specification. They are searched in the order specified. All Events automatically have access to the system calendar, which is searched after the default calendars. A user has update access to the calendar listed as his first default calendar if that calendar does not have a department assigned, even though his user ID may not be included in the ownership string of the calendar. Authority attributes are independent of each other. For example, if you have SPECIAL authority, you do not automatically have any other authority attributes.When you delete a user, none of the Events the user defined will execute. Cybermation supplies a utility, CYBESU01, you can use to change the ownership of an Event.

You can also define users using ESP’s ISPF interface. Choose Option M from the ESP Main Menu.

Related informationFor information on calendars, see the CALENDAR command.For information on deleting a user, see the DELUSER command.For information on displaying a user, see the LISTUSER command.For information on changing a user’s definition, see the ALTUSER command.

NOANY Removes the ANY attribute.

NOSCHEDULER Removes the SCHEDULER attribute.

NOUSERDEF Removes the USERDEF attribute.

NOGROUPDEF Removes the GROUPDEF attribute.

NOCONNECTDEF Removes the CONNECTDEF attribute.

NOCALENDARDEF Removes the CALENDARDEF attribute.

NOUSERDEF Removes the USERDEF attribute.

tabname Indicates the name of the authorization table assigned to the user, up to eight characters.

cal1 Indicates the name of the first default calendar, up to eight characters.

cal2 Indicates the name of the second default calendar, up to eight characters.

Operand Description

DEFUSER Command: Define Users

286

Examples Define user and Event data baseIn the following example, CYBUSR1 is defined with no authority and Events for this user are stored in the Event data base with logical name EVENT1:DEFUSER CYBUSR1 EVENTSET(EVENT1)

Define user and authoritiesIn the following example, CYBUSR2 has been given the authority to do the following:• Access commands relating to Administration• Define and access Events with any group prefix• Issue operator commands• Define pnodes, tracking models and job tracking parameters:DEFUSER CYBUSR2 EVENTSET(EVENT1) -AUTH(SPECIAL,ANY,OPER,SCHEDULER)

Define user, authorities and Event data setIn the following example, CYBUSR3 is defined. The Event data set is EVENT1; the first default calendar is CAL1, access is allowed to the history file HIST1, and the user is allowed to define tracking models, job tracking parameters and processing nodes:DEFUSER CYBUSR3 EVENTSET(EVENT1) CALENDAR(CAL1) -HISTFILE(HIST1) AUTH(SCHEDULER)

Define limited authoritiesIn the following example, CYBUSR4 has been given the authority to do the following:• Define and administer any department that begins with the string MTS and is

therefore able to define other departmental sub-groups such as MTS1, MTS2, and so on.

• Define other groups and users within his own department or sub-group of departments because of the GROUPDEF and USERDEF keywords. The groups and users that CYBUSR4 defines can have the same or less authority, and must use the same Eventset, EVENT1.

• Define calendars, connect other users to groups and sub-groups that he has access:DEFUSER CYBUSR4 EVENTSET(EVENT1) DEPT(MTS-) - AUTH(GROUPDEF,USERDEF,CALENDARDEF,CONNECTDEF) - HISTFILE(HISTF1)

287

DELAT Command: Delete Authorization Tables

Deletes an authorization table. Note: DELAT is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou require SPECIAL authority to issue the DELAT command in a non-SAF environment.

SyntaxDELAT tabname

Related informationFor information on defining authorization tables, see the DEFAT command.

Example Delete authorization tableIn the following example, ATAB01 is deleted. A user that has been assigned ATAB01 will no longer be able to access job-tracking data:DELAT ATAB01

Operand Description

tabname Indicates the name of the authorization table to be deleted, which consists of up to eight characters.

DELAYINT Command: Delay Intervals

288

DELAYINT Command: Delay Intervals

Sets the interval for re-triggering an Event when required data sets are not available.

TypeGeneral command.

AuthorityYou require OPER authority to issue the DELAYINT command.

SyntaxDELAYINT [nn|5]

Usage notesIf an Event requires a data set that is not available at the trigger time because it is in use by another user, ESP tries again at the specified DELAYINT time to re-trigger the Event.The DELAYINT is normally specified as an initialization parameter.If the DELAYINT command is entered dynamically, for example from Page mode, it overrides the default initialization parameter setting until an IPL is performed.

Related informationFor information on the DELAYINT initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.

Examples Display the delay intervalIn the following example, ESP displays the interval for re-triggering an Event when required data sets are not available:OPER DELAYINT

Set retry for one minuteIn the following example, ESP retries in one minute if a required data set, for example JCL library, is not available at trigger time:OPER DELAYINT 1

Operand Description

nn Indicates a delay interval in minutes. Specify a value from 1 to 15 minutes. The default is 5.

289

DELAYSUB Statement: Delay Submissions

The DELAYSUB statement is used to specify a job for delayed submission relative to the scheduled time of the Event. If the Event is not scheduled the delayed submission time is relative to the time the Application is generated.

SyntaxDELAYSUB criteria

Usage notesUse the DELAYSUB statement within the scope of a JOB statement to request that a job not be submitted until a specified time, even though its predecessors have completed. This time parameter can request any date or time relative to the time the Application was schedule or generated.If you trigger an Event with a time/date in the past, ESP does not honor DELAYSUB statements, except those that use the term REALNOW.Although less commonly used, the DELAYSUB statement can be placed outside the scope of any JOB statements (globally) to delay all jobs that are placed after that globally placed DELAYSUB statement. Using this method sets a delayed submission time for all jobs within the Application, except for those specifying the DELAYSUB statement within the scope of the JOB statement. Jobs that have their delayed submission time set as a result of a globally placed DELAYSUB statement can have those delayed submission times reset only on a job by job basis, and not as a group.Jobs that are inserted into active Applications do not have delayed submission time associated with them. If you want to insert a job into an active Application and associate a delayed submission time with that job you will have to:1. Insert the job on hold using the IJ CSF line command2. Reset the job’s delayed submission time (Earliest submit time field)3. Release the job using the A CSF line command.

Related informationNote: The DELAYSUB and EARLYSUB statements perform the same function.For information on resetting time dependencies, see the ESP Workload Manager User’s Guide.For information on manipulating jobs within Application or subApplications, see the APPLJOB or AJ command.

Operand Description

criteria Schedule criteria that resolve to a single date and time when the Application builds.

DELAYSUB Statement: Delay Submissions

290

For information on specifying time dependencies, see the ESP Workload Manager User’s Guide.

Examples Delay until 9 pmIn the following example, PAYJOB1 has a delayed submission time of 9 pm relative to the time the PAYROLL Application is generated:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 DELAYSUB 9PM RUN WORKDAYSENDJOB

Delay based on day of weekThe following DELAYSUB statement sets the delayed submission time based on the day of the week:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB2 DELAYSUB 9PM IF TODAY('WEEKEND') THEN DELAYSUB 6PM RUN DAILYENDJOB

In the above example, PAYJOB2 has a delayed submission time of:• 9 pm on weekdays• 6 pm on weekends.Set multiple submission delaysIn the following example:• PAYJOB3 has a delayed submission time of 4pm• PAYJOB4 does not have a delayed submission time• PAYJOB5 & PAYJOB6 have delayed submission times of 7pm:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 DELAYSUB 4PM RELEASE PAYJOB4ENDJOB JOB PAYJOB4 RELEASE PAYJOB5ENDJOBDELAYSUB 7PM

291

JOB PAYJOB5 RELEASE PAYJOB6ENDJOBJOB PAYJOB6ENDJOBSELECT (PAYJOB3,PAYJOB4,PAYJOB5,PAYJOB6)

Delay 10 minutesThe following example sets the delayed submission to 10 minutes after the scheduled time of the Event:DELAYSUB NOW PLUS 10 MINUTES

Delay two workdaysThe following example sets the delayed submission time to 10pm two workdays from the scheduled time of the Event:DELAYSUB 10PM TODAY PLUS 2 WORKDAYS

Delay to 11pm last workday of month, otherwise 9pmThe following example sets the delayed submission time to 11 pm on the last workday of the month, and to 9 pm on all other days this job is submitted:IF TODAY('LAST WORKDAY OF MONTH') THEN - DELAYSUB 11PMELSE - DELAYSUB 9PM

DELCAL Command: Delete Calendars

292

DELCAL Command: Delete Calendars

Deletes a calendar and all the holidays and special days within it.

TypeGeneral command.

AuthorityYou require SPECIAL or CALENDARDEF authority in a non-SAF environment to issue the DELCAL command. With SAF, you control access to calendars using the CALENDAR.calname resource.

Syntax{DELCAL|DELC} calname

Usage notesOnly delete a calendar when you are sure no Event or Applications use schedule terms in the calendar.

Related informationFor information on calendars, see the ESP Workload Manager User’s Guide.For information on defining calendars, see the DEFCAL command.

Example Delete a calendarIn the following example, PAYCAL and its entire contents (holidays, special days, and special periods) are deleted:DELCAL PAYCAL

Operand Description

calname Indicates a one to eight character calendar name to be deleted.

293

DELETE Command: Delete Events (In Definition)

When used in an Event definition, DELETE is used to delete an Event at a scheduled time.

TypeEvent command.

Syntax{DELETE|DEL} criteria

Related informationFor information on working with ESP Events, see the ESP Workload Manager User's Guide.For information on deleting an Event outside an Event definition, see “DELETE Command: Delete Events (General)” on page 294.

Examples Delete Event at 10 am first day of yearIn the following example, an Event is deleted at 10 am on the first day of the year:DELETE 10AM FIRST DAY OF YEAR

Delete on specific dateIn the following example, an Event is deleted at 11 pm on March 2nd, 2004:DELETE 11PM MARCH 2,2004

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time.

DELETE Command: Delete Events (General)

294

DELETE Command: Delete Events (General)

Deletes an Event definition.

TypeGeneral command.

Syntax{DELETE|DEL} eventid

Usage notesThe specified Event is deleted at the time the command is entered, even if the Event is currently scheduled.

Related informationFor information on working with ESP Events, see the ESP Workload Manager User’s Guide.For information on displaying Events, see the LIST command.For information on scheduling a deletion of an Event, see “DELETE Command: Delete Events (In Definition)” on page 293.

Example Delete an EventIn the following example, CYBER.PAYROLL is deleted:DELETE CYBER.PAYROLL

Operand Description

eventid Indicates the name of an Event to be deleted. If no prefix is specified, your current GROUP prefix is used.

295

DELGROUP Command: Delete Groups

Deletes a group definition.Note: DELGROUP is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou require SPECIAL or GROUPDEF authority to issue the DELGROUP command.

Syntax{DELGROUP|DELG} groupname

Related informationFor information on defining groups, see the DEFGROUP command.For information on displaying information about a group, see the LISTGRP command.

Example Delete a GroupIn the following example, the ACCOUNTS group is deleted:DELGROUP ACCOUNTS

Operand Description

groupname Indicates the name of the group to be deleted.

DELHOL Command: Delete Holidays

296

DELHOL Command: Delete Holidays

Deletes a holiday definition.

TypeGeneral command.

AuthorityYou can delete only holidays defined in your first default calendar, or in calendars to which you have access.

Syntax{DELHOL|DELH} holidayname START(starttime) [CALENDAR(calname)]

Usage notesYou must delete one holiday at a time.The holiday name and start time must match an existing definition for the command to work. The time and date specification must be accurate to within one minute.If you do not specify a calendar name, the following calendars are searched in the order listed.1. The first default calendar as defined in your user ID entry.2. The second default calendar as defined in your user ID entry.3. The SYSTEM calendar.The first matching holiday entry found is deleted.Normally you do not need to delete holiday definitions. Holidays are automatically deleted after the retention period expires, as per the time period specified when the holiday was defined.

Operand Description

holidayname Indicates the 1 to 16 character name of the holiday

starttime Indicates the starting time and date of the holiday. If the date specification contains separators, it should be enclosed in quotes.

calname Indicates the name of the calendar in which the holiday is defined.

297

Related informationFor information on defining holidays, see the DEFHOL command.For information on displaying holiday information, see the LISTHOL command.

Example Delete a holidayIn the following example, TEMPORARY is deleted from the UCAL2 calendar:DELHOL TEMPORARY START('FEB 22,1998') CAL(UCAL2)

DELPN Command: Delete Pnodes

298

DELPN Command: Delete Pnodes

Deletes a pnode definition.

TypeGeneral command.

AuthorityYou require SCHEDULER authority in a non-SAF environment to issue the DELPN command. With SAF, you control access to pnodes using the PNODE.pnodename resource.

SyntaxDELPN pnode

Related informationFor information on defining processing nodes (pnodes), see the ESP Workload Manager Advanced User’s Guide.For information defining manual pnodes, see the DEFPN command.

Example Delete a pnodeIn the following example, the DISTRIB manual pnode is deleted:DELPN DISTRIB

Operand Description

pnode Indicates the name of the pnode being deleted.

299

DELSIG Command: Delete Signals

Deletes a signal.

TypeGeneral command.

AuthorityYou can delete only those signals beginning with a prefix to which you have access.

SyntaxDELSIG signalname

Related informationFor information on signal processing, see the ESP Workload Manager Advanced User’s Guide.For information on defining signals, see the DEFSIG command.For information on posting a generation of a signal, see the SIGPOST command.For information on altering the numbers of generations of a signal, see the ALTSIG command.For information on displaying all generations of a signal, see the LISTSIG command.

Examples Delete specific signalIn the following example, CYBER.SIGNAL1 is deleted:DELSIG CYBER.SIGNAL1

Delete signal in current group prefixIn the following example, SIGNAL2 is deleted. If, for example the current group prefix is PROD, then PROD.SIGNAL2 is deleted:DELSIG SIGNAL2

Operand Description

signalname Indicates the name of the signal. If the prefix is omitted, the current group or user prefix is used.

DELSPEC Command: Delete Special Days or Periods

300

DELSPEC Command: Delete Special Days or Periods

The DELSPEC command is used to delete a special day or period definition.

TypeGeneral command.

AuthorityYou can delete only special days or periods defined in your first default calendar, or calendars to which you have access.

SyntaxDELSPEC specname ON(date) [CALENDAR(calname)]

Usage notesYou must delete one special day at a time.The special day and start time must match an existing definition for the command to work. The time and date specification must be accurate to within one minute.If you do not specify a calendar name, the following calendars are searched in the order listed. The first matching special day/period entry found is deleted.1. The first default calendar as defined in your user ID entry.2. The second default calendar as defined in your user ID entry.3. The SYSTEM calendar.Normally you do not need to delete special days. Special days are automatically deleted after the retention period expires, as per the time period specified when the special day was defined.

Operand Description

specname Indicates a 1 to 16 character name of a special day or period.

date Indicates the starting time and date of the special day or period. If the date specification contains separators, it should be enclosed in quotes.

calname Indicates the name of the calendar in which the special day is to be deleted.

301

Related informationFor information on using special days, see the ESP Workload Manager User’s Guide.For information on defining special days or periods, see the DEFSPEC command.For information on displaying special day and period information, see the LISTSPEC command.

Example Delete specific instance of special dayIn the following example, PAYROLL_DAY, which falls on November 26th, 2001 is deleted:DELSPEC PAYROLL_DAY ON('26TH NOVEMBER 2001')

DELSYML Command: Delete Symbolic Variable Library

302

DELSYML Command: Delete Symbolic Variable Library

The DELSYML command is used to delete a symbol library.

TypeGeneral command.

AuthorityYou require SPECIAL, SCHEDULER or CALENDARDEF authority to issue the DELSYML command in non-SAF environments. With SAF, you control access to symbol libraries using the SYMLIB.symname resource.

SyntaxDELSYML name

Usage notesThe DELSYML command deletes the logical identifier of the symbol library.

Related informationFor information on displaying symbol libraries, see the LISTSYML command.For information on defining a symbol library, see the DEFSYML command.

Example Delete symbolic variable libraryIn the following example, USRSYMS is deleted. Note: Only the logical identifier (USRSYMS) is deleted and not the data sets

associated with the identifier when the symbolic library was defined:DELSYML USRSYMS

Operand Description

name Indicates the name of the symbolic variable library to be deleted.

303

DELTJ Command: Delete Tracked Job Definitions

The DELTJ command is used to delete tracked job definitions from the job index file.

TypeGeneral command.

AuthorityYou require ALTER authority on the TJD.jobname resource to issue the DELTJ command in a SAF environment.You require SCHEDULER authority or a matching ownership string to issue the DELTJ command in a non-SAF environment.

SyntaxDELTJ jobname [PREFIX]

Usage notesNormally you should not need to delete tracked job definitions.The preferred method for deleting and altering tracked job definitions is a Job Tracking Definition Table.

Related informationFor information on job tracking definition tables, see the ESP Workload Manager Installation and Configuration Guide.For information on changing characteristics of a tracked job, see the ALTTJ command.

Examples:Delete tracked job definitionIn the following example, PAYJOB99 is deleted from the job index file:DELTJ PAYJOB99

Operand Description

jobname Indicates the name of the job, or job prefix to delete. Only if a job prefix is deleted can the name contain asterisks and a hyphen.

PREFIX Indicates a prefix entry is being deleted. This applies only if you are not using a Job Tracking Definition Table.

DELTJ Command: Delete Tracked Job Definitions

304

Delete multiple tracked job definitionsIn the following example, any job whose name starts with the characters ABC is deleted from the job index file. Jobs with this prefix that are already tracked continue to be tracked as specific entries were built. These can be deleted individually if required. This example applies only if you are not using a Job Tracking Definition table:DELTJ ABC- PREFIX

305

DELTM Command: Delete Tracking Model Definitions

The DELTM command is used to delete a tracking model definition.

TypeGeneral command.

AuthorityYou require special authority to issue the DELTM command in a non-SAF environment. With SAF, you control access to tracking models using the MODEL.modelname resource.

SyntaxDELTM model

Usage notesCaution should be used when deleting tracking models. Tracking models contain tracking characteristics that may apply to a large number of jobs. If a tracking model is deleted, ESP no longer tracks all jobs associated with that tracking model.

Related informationFor information on displaying a tracking model, see the LTM command.For information on defining a tracking model, see the DEFTM command.For information on tracking definition entries in a Job Tracking Definition Table, see the TRACKDEF statement.For information on using tracking models, and Job Tracking Definition Tables, see the ESP Workload Manager Installation and Configuration Guide.

Example Delete tracking modelIn the following example, MODELTST is deleted:DELTM MODELTST

Operand Descriptionmodel Indicates the name of the tracking model to be deleted.

DELUSER Command: Delete Users

306

DELUSER Command: Delete Users

The DELUSER command is used to delete a user definition from ESP. Note: DELUSER is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou require SPECIAL or USERDEF authority to issue the DELUSER command in a non-SAF environment.

Syntax{DELUSER|DELU} userid

Related informationFor information on defining a user, see the DEFUSER command.For information on displaying a user, see the LISTUSER command.For information on changing a user’s definition, see the ALTUSER command.

Example Delete userIn the following example, CYBUSR9 is deleted and is no longer able to access ESP:DELUSER CYBUSR9

Operand Descriptionuserid Indicates the name of the user definition to be deleted.

307

DEQUEUE Statement: Remove Resource Names from Enqueue List

The DEQUEUE statement removes a resource name from the enqueue list.Note: The DEQUEUE statement uses resources implicitly. Therefore, a resource file (RESFILE) and the network topology must be defined before you can use it.

SyntaxDEQUEUE NAME(n1,n2,...)

Example The following example shows job NWN002 removing a specified enqueue of the resource named FRED. The enqueue is specified at the Application level and job NWN002 does not require it. APPL NWN00AJCLLIB 'CYBER.JCL.CNTL'ENQUEUE NAME(FRED) SHARED

JOB NWN001 RUN DAILYENDJOB

JOB NWN002 RUN DAILY DEQUEUE NAME(FRED)ENDJOB

JOB NWN003 RUN DAILYENDJOB

JOB NWN004 RUN DAILYENDJOB

Operand Descriptionn1 Specifies a resource name. The resource name must match exactly,

character for character, the name previously specified on an ENQUEUE statement (not case sensitive). If a match is not found, the DEQUEUE statement has no effect.

DESCRIPTION Statement: Describe an Oracle Applications Single Request

308

DESCRIPTION Statement: Describe an Oracle Applications Single Request

The DESCRIPTION statement can be used to add a description to an Oracle Applications Single Request.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Single Requests only.

SyntaxDESCRIPTION description

UsageThe description displays in the Oracle Applications Concurrent Manager.DESCRIPTION can be defined in two places.• To set DESCRIPTION for a specific job, include it in the job definition.• To set the default for all jobs run by an Agent, ask your System Administrator to

define the oa.default.desc parameter in the Agent parameter file.The short form DESC can be used in place of DESCRIPTION.This statement is optional for OA Program job definitions.

ExampleAdd a description to a Single RequestIn the following example, information on the history of a program is included in the description:APPL ACC09 AGENT CYBOA OA_JOB AOL1805.AP004 PROGRAM XXCOFI RUN DAILY

Operand Descriptiondescription Specifies a Single Request description. If you use delimiters,

such as spaces, the name must be enclosed in single quotes. Maximum 30 characters.

309

APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN DESCRIPTION ‘CONFIRMED REQ 20040808 by TYB212’ ENDJOB

DESELECT Statement: Deselect Jobs or SubApplications

310

DESELECT Statement: Deselect Jobs or SubApplications

The DESELECT statement is used to deselect a job or subApplication. Deselected jobs are not built as part of the Application. Use the DESELECT statement to handle exceptions to regular schedule criteria.

SyntaxDESELECT {jobname|(jobname[,jobname])} [JOB|SUBAPPL]

Usage notesYou can deselect a group of jobs using the SUBAPPL operand.You can use more than one DESELECT statement.The DESELECT statement identifies that a previously selected job should not be selected as part of the Application. You can us it only after a SELECT or RUN statement for the jobs involved.If the DESELECT statement is used for any job that has PREREQ, POSTREQ or COREQ specified, the jobs that these statements refer to are deselected automatically.Jobs that are specified as PREREQ, POSTREQ or COREQs cannot explicitly be deselected using a DESELECT statement.Jobs that are selected to run using a RUN statement can be deselected using a DESELECT statement. ESP allows multiple SELECT and DESELECT statements for the same job or subApplication.You should normally code your DESELECT statements after your SELECT statements since ESP processes the statements in the order specified.

Related informationFor information on selecting a job or subApplication for submission, see the SELECT statement.For information on selecting and deselecting jobs or subApplications for submission, see the ESP Workload Manager User’s Guide.

Operand Description

jobname Indicates a jobname. Enclose multiple jobnames in parentheses, separated by a blank or comma.

JOB Indicates a job is being deselected for submission. This is the default.SUBAPPL Indicates all jobs within a subApplication are being deselected for

submission.

311

Examples Select based on daysIn the following example, when the PAYROLL Application is generated, PAYJOB1 and PAYJOB2 are always selected, except on Fridays, when PAYJOB2 is deselected:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RELEASE PAYJOB2JOB PAYJOB2ENDJOBSELECT (PAYJOB1,PAYJOB2)IF TODAY('FRIDAY') THEN DESELECT PAYJOB2

Deselect first workday of monthIn the following example, when the PAYROLL Application is generated, ESP runs PAYJOB5 and PAYJOB6 daily, except on the first workday of the month, when both PAYJOB5 and PAYJOB6 are deselected. This is because a DESELECT statement is used for PAYJOB5, which has a POSTREQ of PAYJOB6:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB5 RUN DAILY POSTREQ PAYJOB6JOB PAYJOB6ENDJOBIF TODAY('FIRST WORKDAY OF MONTH') THEN DESELECT PAYJOB5

Select and deselect multiple jobsIn the following example:• The ACCPAY and BILLING subApplications are selected• PAYJOB10 and PAYJOB11 are selected• The BILLING subApplication is not selected on the last workday of the month• ACCJOB2 is not selected on Mondays:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB ACCJOB1 SUBAPPL ACCPAYENDJOBJOB ACCJOB2 SUBAPPL ACCPAYENDJOBJOB BILJOB1 SUBAPPL BILLING

DESELECT Statement: Deselect Jobs or SubApplications

312

ENDJOBJOB BILJOB4 SUBAPPL BILLINGENDJOBJOB PAYJOB10ENDJOBJOB PAYJOB11ENDJOBSELECT (ACCPAY,BILLING) SUBAPPLSELECT (PAYJOB10,PAYJOB11)IF TODAY('LAST WORKDAY OF MONTH') THEN DESELECT BILLING - SUBAPPLIF TODAY('MONDAY') THEN DESELECT ACCJOB2

Deselect two subApplications

The following example indicates two subApplications are not selected for submission:DESELECT (PREPJOBS,POSTJOBS) SUBAPPL

313

DEST Statement: Specify Output Destination File (J2EE)

For EJB jobs, the DEST statement specifies the output destination file of the response from the EJB. For JMS Subscribe jobs, the DEST statement specifies the output destination file of messages from the Queue or Topic.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within the EJB_JOB and JMSS_JOB workload objects

SyntaxDEST destination

Usage notesDEST is an optional statement within the EJB_JOB and JMSS_JOB workload objects.If the destination file is unspecified, the output is redirected to the spool file.

ExamplesEJB Job (Windows)In this example, the output from the EJB is saved in the file Makapt15.txt.APPL TESTSBEJB_JOB CYBJK.SB HOLD RUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(java.lang.String) VALUE(A23)ENDJOB

Operand Descriptiondestination The output destination file. destination is case sensitive and can

be up to 256 characters. If destination contains delimiters (such as spaces), enclose it in single quotes.

DEST Statement: Specify Output Destination File (J2EE)

314

EJB Job (UNIX)In this example, the output from the EJB is saved in the file outputfile.bean.APPL TESTSBEJB_JOB CYBJK.SB RUN DAILY AGENT CYBUNIX BEAN CybEJBTestBean METHOD sort INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 DEST /export/home/user1/outputfile.bean PARAMETER TYPE(java.lang.String) VALUE(quick)ENDJOB

JMS Subscribe Job (Windows)In this example, the messages from the Queue satisfying the filter criteria are saved in the file Makapt15.txt.APPL TESTJSJMSS_JOB CYBJK.JS HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DEST ’c:\Program Files\Dest\Common Files\System\ado\+ Makapt15.txt’ DESTNAME Queue continuous(a13) TOPIC N FILTER ’abc\s...\s[a-zA-Z]+\sFilter![\sa-z0-9]+’ JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001ENDJOB

315

JMS Subscribe Job (UNIX)In this example, the messages from the Topic satisfying the filter criteria are saved in the file outputfile.APPL TESTJSJMSS_JOB CYBJK.JS RUN DAILY AGENT CYBUNIX INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DEST /export/home/user1/outputfile DESTNAME Topic TOPIC Y FILTER ’abc\s...\s[a-zA-Z]+\sFilter![\sa-z0-9]+’ JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001ENDJOB

DESTINATION Statement: Specify Destination File Within DB_JOB

316

DESTINATION Statement: Specify Destination File Within DB_JOB

The DESTINATION statement specifies the destination file when using the DB_JOB workload object.

ApplicabilityESP System Agents, Release 6, used within a DB_JOB workload object. For more information, see “DB_JOB Statement: Identify the Name of Database Jobs” on page 245.

SyntaxDESTINATION Destinationfile

Usage notesDEST is the short form of DESTINATION.

ExamplesExample 1 (Windows)In this example, the destination is the file test14.bd2. As the complete path statement contains spaces, single quotes are used to enclose the path statement.DB_JOB DEST.STMNT AGENT R6AGENT USER db2admin DSN db2://10.1.1.46:50000/sample SQL 'SELECT COUNT(*) FROM STAFF WHERE NAME LIKE ''L%''' DEST 'c:\qatest\db job data\test14.bd2' RUN DAILYENDJOB

Operand DescriptionDestinationfile The default destination is a spool file. Specify the name of the file

including the path statement. If DESTINATION is an existing file, the output of the DB_JOB job will be added to the end of this file.

317

Example 2 (UNIX)DB_JOB DBTEST6AGENT R6AGENTUSER user1DSN oracle:thin:@gemini:1527:cybSQL 'SELECT JOBNAME, JOBCOUNT, STATUS, ENDDATE, JOBLOG +FROM TBTCO WHERE JOBNAME LIKE ''%%TEST%'''

DEST /export/home/qatest/db_job_data/test14.bd2RUN DAILY

ENDJOB

DESTNAME Statement: Specify JNDI Name of the Topic/Queue

318

DESTNAME Statement: Specify JNDI Name of the Topic/Queue

The DESTNAME statement specifies the JNDI name of the Topic or Queue. The job uses the JNDI name to specify the destination where messages are sent (JMS Publish) or received (JMS Subscribe).

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher • Used within the JMSP_JOB and JMSS_JOB workload objects

SyntaxDESTNAME destination [CONTINUOUS(alert_name)]

Usage notesDESTNAME is a mandatory statement within the JMSP_JOB and JMSS_JOB workload objects.

Operand Descriptiondestination The JNDI name of the Topic or Queue. destination is

case sensitive and can be up to 256 characters.CONTINUOUS(alert_name) The name of the ESP Workload Manager Alert. When

the Filter value is detected, the ESP System Agent invokes the Alert. If you specify an Alert, the job runs continuously. You must force the job to complete to end the monitoring. If no Alert is specified, the job completes when the Agent detects the filter value. The Agent ignores all messages that do no match the filter.

Note: The CONTINUOUS operand only applies to JMS Subscribe jobs (JMSS_JOB).

alert_name is alphanumeric and can be up to four characters. alert_name must start with an alphabetic character (aA-zZ).

319

ExamplesJMS Publish jobIn this example, the CYBJK.JP job publishes a simple message to the Queue named Queue.APPL TESTJPJMSP_JOB CYBJK.JP HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DESTNAME Queue TOPIC N MSGCLASS String JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 PARAMETER TYPE(java.lang.String) VALUE(’this is my message’)ENDJOB

JMS Subscribe jobIn this example, the CYBJK.JS job continuously monitors the Queue named Queue for messages matching the filter criteria. APPL TESTJSJMSS_JOB CYBJK.JS HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DEST ’c:\Program Files\Dest\Common Files\System\ado\+ Makapt15.txt’ DESTNAME Queue continuous(a13) TOPIC N FILTER ’abc\s...\s[a-zA-Z]+\sFilter![\sa-z0-9]+’ JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001ENDJOB

DFLTUSER Command: Define Default Users

320

DFLTUSER Command: Define Default Users

The DFLTUSER command is used to define the characteristics of an undefined user communicating with ESP for the first time. Note: DFLTUSER is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

AuthorityYou require SPECIAL authority to issue the DFLTUSER command.

SyntaxDFLTUSER {[NONE]} {[AUTH {(SPECIAL)|(OPER)|(ANY)}]} {[GROUP{(PREFIX)|(groupid)|(USERID)}]} {[EVENTID(evdb)]

Operand DescriptionNONE Indicates no unauthorized users may access the system.AUTH Indicates the attributes to be assigned to the user.SPECIAL Indicates the user is allowed full access to ESP, including holiday and special day

definitions as well as group and user definitions.OPER Indicates the user is allowed to issue ESP operator commands.ANY Indicates the user is allowed to access any Event, even though he is not

connected to the group in which the Event is defined.GROUP Indicates the default GROUP to which the user is assigned.PREFIX Indicates the TSO profile prefix should be used. This is the default if the GROUP

keyword is not specified.

groupid Indicates the group prefix of your choice, using up to eight characters.

USERID Indicates the user ID should be used as a group prefix for Events.

evdb Indicates the identifier of an Event data base, using up to eight characters. This Event data base contains the Events that the user defines, prefixed by his or her own user ID.

321

Usage notesThe GROUP keyword specifies the default GROUP to which the user is assigned. This command has to be reissued only when any specifications are to be modified.Related informationFor information on defining and deleting users to ESP, see the DEFUSER and DELUSER commands.

Example Define default userIn the following example, any user who is not defined to ESP has his user ID assigned as his ESP group prefix, and all his Event definitions are stored in the Event data base called EVENT1:DFLTUSER GROUP(USERID) EVENT(EVENT1)

DFPNODE Command: Set or Display Default Pnodes

322

DFPNODE Command: Set or Display Default Pnodes

The DFPNODE command is used to display or set the default pnode for the issuing system console or TSO session.

TypeGeneral command.

AuthorityYou require OPER authority to issue the DFPNODE command.

SyntaxDFPNODE [pnodename]

Usage notesThe DFPNODE command makes it easier for a TSO user or system console operator to POST a job from a pnode because the PNODE operand of the POST command is not needed. The PNODE operand on the POST command can still be used to override the default pnode.The default pnode is retained across sessions and IPLs until reset by another DFPNODE command.

Related informationFor information on posting a job complete from a manual pnode, see the POST command.For information on defining and deleting manual pnodes, see the DEFPN and DELPN commands.For information on defining processing nodes (pnodes), see the ESP Workload Manager Advanced User’s Guide.

Operand Descriptionpnodename Indicates the name of the default pnode. If this Operand is omitted, the

current default pnode is displayed.

323

Example Define default pnodeIn the following example, BURSTER is set as the default pnode for the issuing console or user ID:DFPNODE BURSTER

To post jobs from a default pnode, issue the POST command as follows:POST MYJOBPOST OTHERJOB)

DIRECTION Statement: Specify Transfer Direction Within FTP_JOB

324

DIRECTION Statement: Specify Transfer Direction Within FTP_JOB

The DIRECTION statement specifies the direction of files to be transferred in an FTP_JOB workload object.

ApplicabilityESP 6 System Agents, Release 6, used within an FTP_JOB workload object. For more information, see “FTP_JOB Statement: Identify the Name of FTP Jobs” on page 623.

SyntaxDIRECTION U|D

Usage notesDIRECTION is an alternative form of TRANSFERDIRECTION. Refer to “TRANSFERDIRECTION Statement: Specify Transfer Direction Within FTP_JOB” on page 1288.DIRECTION is a required statement within an FTP_JOB workload object. DIRECTION can be a global statement.

ExampleIn this example, the transfer direction is download (operand D).FTP_JOB FTPT17.UPLOAD AGENT R6AGENT USER test SERVERADDR hprsupp SERVERPORT 21 DIRECTION D FTPFORMAT A REMOTENAME /tmp LOCALFILENAME /export/home/qatest/ftpdata/text* RUN DAILY RELEASE FTPT18.UPLOADENDJOB

Note: For Windows examples, substitute a Windows path in the LOCALFILENAME statement.

Operand DescriptionU UploadD Download

325

DISABLE_RESTART Statement: Disable Restart Feature (PeopleSoft)

The DISABLE_RESTART statement specifies whether to disable a restart feature for previously failed jobs from the point where the job failed.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax DISABLE_RESTART YES|NO

Usage notesDR is the short form of DISABLE_RESTART.

Operand DescriptionYES Previously failed jobs will restart from the beginning. NO Default. Previously failed jobs will restart from where they

stopped. This feature only applies to certain PeopleSoft Process Types such as Application Engine.

DISCONN Command: Disconnect Users

326

DISCONN Command: Disconnect Users

The DISCONN command is used to remove the authority of a user to access a group prefix.

TypeGeneral command.

AuthorityYou require SPECIAL or CONNECTDEF authority to issue the DISCONN command in a non-SAF environment.

Syntax{DISCONN|DISCON} userid GROUP(groupname)

Usage notesThe DISCONN command applies only if your are using ESP’s internal security.It may be necessary to restrict a user’s access to a Group prefix. You may have to do this if, for example, the user moves out of that group to another area of your organization, or to another company.

Related informationFor information on connecting a user to a group, see the CONNECT command.For information on listing a user definition, see the LISTUSER command.

Example Disconnect user from groupIn the following example, FRED is disconnected from the BILLING group:DISCONN FRED GROUP(BILLING)

Operand Descriptionuserid Indicates the user ID to be disconnected.groupname Indicates the name of the group from which the user is being

disconnected.

327

DISK Statement: Specify Conditions to Monitor Disk Within DISK_MON

The DISK statement specifies the conditions that a DISK_MON workload object will use to monitor a specified disk (or logical partition).

ApplicabilityESP System Agents, Release 6, used within a DISK_MON workload object. For more information, see “DISK_MON Statement: Monitor Disk Space” on page 331.

SyntaxDISK drive [FORMAT(PERCENT|GB|MB|KB|B)]

[FROM(lower)] [TO(upper)] [NOCHANGE(percent)][CONTINUOUS [alert][WITHIN|OUTSIDE][AVAILABLE|USED]

Operand Descriptiondrive Required. Specifies the drive letter (including path) to the disk or

logical partition to be monitored. Up to 256 characters in length, case sensitive, any character.

FORMAT(PERCENT|GB|MB|KB|B)

Optional. Specifies the format of the unit of measure for storage space that the DISK statement will monitor (available or used as specified by the operands AVAILABLE|USED).

• PERCENT—percentage of disk space. Note: None of the values specified by FROM, TO, or NOCHANGE can be greater than 100.

• GB—Gigabytes• MB—Megabytes• KB—Kilobytes• B—Bytes (default)

FROM(lower) Defines the lower boundary of disk space monitored. Used with CONTINUOUS.

TO(upper) Defines the upper boundary of disk space monitored. Used with CONTINUOUS.

DISK Statement: Specify Conditions to Monitor Disk Within DISK_MON

328

NOCHANGE (value) Optional. Used with CONTINUOUS to provide a change value (a delta) that will enable the triggering of an Alert. Note: The Alert will only be triggered if the value occurs in the

range specified by the operands FROM and TO and if the value returned is outside of the delta specified by the last scanned amount.

This operand uses the same unit of measure as the operand FORMAT. For example, if KB (Kilobytes) is specified as the format, the NOCHANGE value is in Kilobytes.

CONTINUOUS [alert] A Workload Manager Alert is triggered when the specified disk monitoring conditions occur. CONTINUOUS requires a range specified by the FROM and TO operands.• If only FROM is specified, the range is between the lower limit

specified by the FROM operand and the maximum available.

• If only TO is specified, the range is between zero and the upper limit specified by the TO operand.

Note: The Alert value cannot exceed four characters and must be already defined using the ALERTDEF command. For more information on the ALERTDEF command, see the ESP System Agent Administrator’s Guide or your Workload Manager documentation.

WITHIN|OUTSIDE Optional.

• WITHIN—Default. Monitor triggers if the value is within the range specified for the CONTINUOUS operand.

• OUTSIDE—Monitor triggers if the value is outside the range specified for the CONTINUOUS operand.

AVAILABLE|USED Optional.

• AVAILABLE—Default. Monitor uses the available space as the reading.

• USED—Monitor uses the used space as the reading.

Operand Description

329

ExamplesExample 1 (UNIX)In this example, a local UNIX drive is monitored. The space available is monitored and the value is expressed in Megabytes.DISK_MON DM1.STMNT AGENT R6AGENT DISK /export/home FORMAT(MB) RUN DAILYENDJOB

Example 2 (UNIX)In this example, a local UNIX drive is continuously monitored. The space used is monitored and the value is expressed as a percentage. When the value for disk space used falls between 90 and 100 percent, an alert (DISK) is issued.DISK_MON DM2.STMNT AGENT R6AGENT DISK /export/home FORMAT(PERCENT) FROM(90) USED + CONTINUOUS(DISK) RUN DAILYENDJOB

Example 3 (Windows)In this example, the local Windows C drive is continuously monitored. The space used is monitored and the value is expressed as a percentage. When the value of disk space used falls below 16 percent or exceeds 95 percent, an alert (DISK) is issued.DISK_MON DM3.STMNT AGENT R6AGENT AFTER CHECK.PART7 DISK C FORMAT(PERCENT) FROM(16) TO(95) USED OUTSIDE + CONTINUOUS(DISK) RUN DAILYENDJOB

Example 4 (Windows)In this example, the local Windows C drive is monitored. The space available is monitored continuously in the format of Kilobytes. The first trigger of an alert takes place when the available space is in the range specified by the lower value (FROM) of 35000000 Kilobytes and the upper value (TO) of 36000000 Kilobytes. DISK_MON DM4.STMNT AGENT R6AGENT DISK C FORMAT(KB) FROM(35000000) TO(36000000) NOCHANGE(100)+ CONTINUOUS(disk) RUN DAILYENDJOB

DISK Statement: Specify Conditions to Monitor Disk Within DISK_MON

330

The following table shows four sequential scans:

Scan Scanned Amount (Kilobytes)

Does DISK_MON trigger occur?

1. 35018896 Yes. 2. 35018900 No. Comparing scan 2 to scan 1, the delta value is only

4 KB. This scanned amount will not be included in the next calculation.

3. 35018795 Yes. Comparing scan 3 to scan 1, the delta value is greater than 100 KB. The delta value of the next scan will be calculated using the scan 3 value of 35018795.

4. 36000001 No. The scanned amount is outside the range specified by the FROM and TO operands.

331

DISK_MON Statement: Monitor Disk Space

Specifies the name of a workload object that monitors disk space on a specified drive (or logical partition).

TypeApplication statement.

ApplicabilityRelease 6 System Agents.

SyntaxDISK_MON|HM jobname[.qualifier]

Usage notesThe statement DISK must be used with a DISK_MON workload object. For more information, see the DISK statement.To use disk monitors, load the workload object module CYBESOHM with the WOBDEF initialization parameter.Also refer to the JOB statement usage notes.

ExamplesMonitoring the local C driveDISK_MON DMTST1.PT AGENT R6AGENT DISK C RUN DAILYENDJOB

Operand Descriptionjobname Defines a job name of up to eight characters. qualifier Optional. The qualifier must immediately follow the job name with

a period separating the two operands. The qualifier can be eight characters.

DISK_MON Statement: Monitor Disk Space

332

Monitoring a local partitionDISK_MON DMTST1.PT AGENT R6AGENT DISK /export/home RUN DAILYENDJOB

333

DISPLAY Command: Display Reporting Fields

The DISPLAY command is used to specify which reporting fields you want to display when creating history reports.

TypeReporting command.

SyntaxDISPLAY field [length] ['title1'] ['title2']

Usage notesOnce the DISPLAY section is started, several field names can be entered one after another, along with optional lengths and titles, separated by a comma. The specified fields are placed on the report detail line in the order specified.If the length of the titles exceeds the length of the field, the column width adjusts to accommodate the titles.

Related informationFor information on history reporting including a list of valid fields, see the ESP Workload Manager User’s Guide.For information on beginning a report definition, see the REPORT command.

Operand Descriptionfield Indicates the name of a field to be displayed.length Indicates an optional length. This can be used to create more space

between columns. Fields are left justified, blanks are padded on the right to the length specified.

title1 Indicates a title, enclosed in quotes.title2 Indicates a second title, enclosed in quotes.

DISPLAY Command: Display Reporting Fields

334

Examples Specify list of fields to displayIn the following example, the following fields are displayed as part of a history report:• Application name (APPLSYS)• Job name (JOBNAME)• Job number (JOBNO)• Execution start time (EXECST)• Execution end time (ENDT).DISPLAY APPLSYS JOBNAME JOBNO EXECST ENDT

Specify fields and titlesIn the following example, the following fields are displayed as part of a history report:• Job name (JOBNAME)

• Time at which ESP read the job into the system (RDRON)• Date at job submission (RDRONDATE)• Tape EXCP count to five digits, with a title of TAPE EXCPS (TEXCP)• Disk EXCP count to six digits, with a title of DISK EXCPS (DEXCP).DISPLAY JOBNAME,RDRON,RDRONDATE,TEXCP 5 'TAPE' 'EXCPS' - DEXCP 6 'DISK' 'EXCPS'

Pad field with blanksIn the following example, the following fields are displayed as part of a history report:• Job name, padded on the right with blanks to a width of 15 (JOBNAME)• Completion code (CMPC).DISPLAY JOBNAME 15,CMPC

335

DISTRFOLDER Statement: Set Distribution Folder (PeopleSoft)

The DISTRFOLDER statement corresponds to the Distribution Detail>Folder Name field in the PeopleSoft user interface.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax DISTRFOLDER folder_name

ExampleIn this example, the value is set to GENERAL.PS DSFOLDER.TEST PROCESSTYPE 'Application Engine' OUTDESTTYPE WEB PROCESSNAME AEMINITEST OUTDESTFORMAT PTF PSOPRID VP1 RUNCONTROLID test SERVERNAME PSNT DISTRFOLDER GENERAL RUN DAILYENDJOB

Operand Descriptionfolder_name Specifies distribution folder that receives the output of a

PeopleSoft job. folder_name can be up to 18 characters.

DISTRLISTROLES Statement: Specify Distribution List of Roles (PeopleSoft)

336

DISTRLISTROLES Statement: Specify Distribution List of Roles (PeopleSoft)

The DISTRLISTROLES statement specifies a distribution list of roles for an output PeopleSoft report.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax DISTRLISTROLES role |'role,role[,role,...]'

Usage notesAn alternative to using this statement is to use operator IDs as specified by the statement DISTRLISTUSERS. See “DISTRLISTUSERS Statement: Specify Distribution List of Operator IDs (PeopleSoft)” on page 338.

ExamplesExample 1The roles of CLERK, BANK MANAGER, and EMPLOYEE are identified as roles on the distribution list for an output report. In this example, the output type is WEB and the output format is PDF.PS WEB.DSROLES2 AFTER CHECK.PART9 PROCESSTYPE Crystal PROCESSNAME XRFWIN OUTDESTTYPE WEB OUTDESTFORMAT PDF DISTRLISTROLES 'CLERK,BANK MANAGER,Employee' PSOPRID VP1 RUN DAILYENDJOB

Operand Descriptionrole A member of the distribution list. Separate each element in the

list by a comma. Enclose a list of roles in single quotes. If the role operand contains a space, enclose it in single quotes.Format is character, up to 256 characters in length for the entire list.

337

Example 2The role of BANK MANAGER is identified as a role on the distribution list for an output report. Because BANK MANAGER contains a space, it must be enclosed in single quotes. PS WEB.DSROLES2 AFTER CHECK.PART9 PROCESSTYPE Crystal PROCESSNAME XRFWIN OUTDESTTYPE WEB OUTDESTFORMAT PDF DISTRLISTROLES 'BANK MANAGER' PSOPRID VP1 RUN DAILYENDJOB

DISTRLISTUSERS Statement: Specify Distribution List of Operator IDs (PeopleSoft)

338

DISTRLISTUSERS Statement: Specify Distribution List of Operator IDs (PeopleSoft)

The DISTRLISTUSERS statement specifies a distribution list of operator IDs for an output PeopleSoft report.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax DISTRLISTUSERS oprid |'oprid,oprid[,oprid,...]'

Usage notesDISTRUSERS is the short form of DISTRLISTUSERS.By default, PeopleSoft sets the value of the operand to PSOPRID. If you do not want to specify a distribution list of users, you must include a DISTRLISTUSERS statement followed by either two single quotes or nothing. Having no distribution list of users may be useful if you specify distribution through roles as specified by the statement DISTRLISTROLES. See “DISTRLISTROLES Statement: Specify Distribution List of Roles (PeopleSoft)” on page 336. A distribution list may also be useful if you use an OUTDESTTYPE of Email (see “OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft)” on page 931) with the corresponding statement EMAILADDR (see “EMAILADDR Statement: Specify Email Addresses (PeopleSoft)” on page 406).

Operand Descriptionoprid A list of operator IDs (OPRID). You can specify more than one

ID. Separate each ID by a comma. Enclose a list of IDs in single quotes. If the list elements are not enclosed in quotes, any item after the first comma will cause an error (extraneous information).Format is character, up to 256 characters in length for the entire list.

339

ExamplesExample 1In this example, multiple operator IDs are identified as members of the distribution list. These members will receive an email containing the PDF output format of the Crystal report.PS EMAIL.DSROLES2 PROCESSTYPE Crystal PROCESSNAME XRFWIN OUTDESTTYPE Email OUTDESTFORMAT PDF PSOPRID VP3 RUNCONTROLID test DISTRLISTUSERS 'VP1,VP2' RUN DAILYENDJOB

Example 2Because DISTRLISTUSERS is set to no distribution list in this example, the output is sent to the email addresses identified in the statement EmailAddr.PS_JOB EMAIL.TEST2 EmailAddr 'jeff@cybermation.com;alex@cybermation.com' DISTRLISTUSERS EmailWebReport Y OUTDESTTYPE Web OUTDESTFORMAT PDF PSOPRID VP2 EmailSubject 'test report' EmailText 'test OUTDESTTYPE WEB with e-mail addresses' PROCESSNAME XRFWIN ProcessType Crystal RUN DAILYENDJOB

DJCDATA Statement: Introduce DJC

340

DJCDATA Statement: Introduce DJC

Used to introduce DJC (Dependent Job Control) or JES3 statements for a job.

SyntaxDJCDATA [ID(name)] [RS([op][n,]resname[,[op][n,]resname...])] [TC(t)] [HC(num)] [RL(jobname[,jobname]...)] [AB(jobname[,jobname]...)] [AF(jobname[,jobname]...)] [NC{(F)|(D)|(R)}] [AB{(F)|(D)|(R)}] [NR(netid,jobname[,netid,jobname]...)] [OH{(NO)|(YES)}] [LN{(R)|(N)|(C)}] [NRCMP{(HOLD|(NOHO)|(FLSH)}] [ABCMP{(NOKP)|(KEEP)}]

Operand Description

name Indicates the name of the jobnet containing this job. The name can be up to eight alphanumeric characters, the first of which must be alphabetic. This overrides the DJCNET setting.

op A logical operator indicating that the resource must be unavailable or that less than the indicated quantity (n) of the resource must be available. Use a negative quantity of a resource to indicate that a job provides a resource; use a not sign '¬' to indicate that the unavailability of a resource is required; use the less than sign (<) to indicate that less than the indicated quantity must be available. This operand requires DJC 3.6.0 and up.

n Used only with a quantum resource. This specifies the number of units of the specified resource that must be available for the job to be eligible for execution. It is separated from the resource name by a comma. The default is one.

resname Indicates the name of a resource that must exist before a job can become eligible for execution. The resource specified can be a real or abstract resource. A logical resource is specified without a count (n). A combination of quantum, either real or abstract, and logical resources can be specified, up to a maximum of 64.

TC(t) Indicates the number of tape drives required that must be online and available to the system for this job to be released. The range is up to 999. The TC operand applies to either 3420 (reel to reel) or 3480 (cartridge) tape drives, or applies indiscriminately, depending on a DJC installation parameter. This operand can be specified alone, without being part of a DJC jobnet.

341

HC(num) Indicates the number of immediate predecessor job completions required before this job can be released for execution. The range is up to 32,767. This count should not include any job referenced by the AFTER, POSTREQ, PREREQ or RELEASE statements in an ESP Procedure. In these cases, the count is adjusted automatically.

RL(jobname) Indicates the names of jobs in the specified jobnet that are successors to this job. Up to 50 names can be specified, separating each by a comma.

BF(jobname) Indicates the names of up to seven jobs already in the system before which this job must run. Separate each job name with a comma. BEFORE dynamically increments the hold count on the successor jobs. If a successor job is not in the system when this job is read in, the successor's hold count is not incriminated, and BEFORE is ignored. BEFORE can refer to any job, whether or not it is part of a dependent jobnet.

AF(jobname) Indicates the names of up to seven jobs already in the system after which this job must run. Separate each job name with a comma. AFTER dynamically increments the hold count on this job to correspond to the appropriate number of AFTER jobnames specified. If any predecessor job is not in the system when this job is read in, its AFTER count is ignored. AFTER can refer to any job, whether or not it is part of a dependent jobnet.

NC Indicates the action to be taken for this job when any predecessor terminates normally:• D—decrement the NHOLD count of this job. If the NHOLD count goes to

zero, this job becomes eligible for execution. This is the default.• F—flush this job from the system. The job is canceled, and any output is

printed. To any successor job, this appears as an abnormal termination.• R—retain this job in the system and do not decrement the NHOLD count.

This suspends the job and its successors from execution until either the predecessor job is resubmitted, or the operator decreases the NHOLD count.

AB • Indicates the action to be taken for this job when any predecessor terminates abnormally:

• R—retain this job in the system and do not decrement the NHOLD count. This suspends the job and its successors from execution until either the predecessor job is resubmitted, or the operator decreases the NHOLD count. This is the default.

• D—decrement the NHOLD count of this job. If the NHOLD count goes to zero, this job becomes eligible for execution.

• F—flush this job from the system. The job is cancelled, and any output is printed. To any successor job, this appears as an abnormal termination.

Operand Description

DJCDATA Statement: Introduce DJC

342

NR Indicates a net release. This job is a predecessor to a job in another jobnet.• netid specifies the NETID name of the successor job.• jobname identifies the name of the successor job.You can specify up to fourteen jobs in other jobnets, separating each netid-jobname pair with a comma.

Note: JES3 only supports one NETID per net release statement.OH Indicates whether the job is to be placed into dependent job operator hold:

• NO—specifies that the job is to be processed normally, without operator intervention. This is the default.

• YES—specifies that the job is placed in dependent job network operator hold. This prevents execution of this job until the operator explicitly releases it.

LN Indicates the disposition of a previous jobnet with the same name:• N—this is not the first job of a new jobnet and normal processing should

take place. This is the default.• R—this is the first job of a new jobnet. Any jobs already on the system that

are in a jobnet with the same NETID, are released.• C—this is the first job of a new jobnet. Any jobs already on the system that

are in a jobnet with the same NETID, are canceled.

ABCMP Indicates what action JES3 is to take if the job abnormally terminates:• NOKP—purge the DJC network if the job abnormally terminates and has not

been resubmitted by the time the other jobs in the network have completed. JES3 purges the network unless successor jobs or sub-networks are missing. This is the default.

• KEEP—keep the DJC network in the system until either the job is resubmitted and completes normally or the operator forces the network from the system.

This operand is for use only with JES3.

NRCMP Indicates that a network job, which completed normally is being resubmitted and that JES3 must erase all references to the job before the job re-enters the network. The actions for JES3 to take are:• HOLD—hold the job until the operator releases it. This is the default.• NOHO—allow the job to be scheduled as system resources become

available.• FLSH—flush the job from the system.This operand is only for use with JES3.

Operand Description

343

Syntax abbreviationsYou can use the following abbreviations:

Usage notesTo use this statement, you must have JES3 or Cybermation's DJC (Dependent Job Control) product installed.It is recommended that you use the job statement elements 'AFTER', 'RELEASE' or one of the requisite statements for job dependency purposes because the required NET card information is then automatically built for you. If 'DJCDATA' is specified, any operands used are merged with the NET card information automatically generated in the ESP Procedures, without being checked.The DJCDATA statement can only be used for a job in either a DJC jobnet or an ESP Application. If a job belongs to neither of these then use a job specific automatic variable to insert the required DJC operands.For a job defined in an ESP Application, you can use the RS operand to identify DJC resource requirements.

Related informationFor information on Dependent Job Control Card specifications, see the DJC User’s Guide.

Examples Request tape drives and release a jobThe following DJCDATA statement is used to request two tape drives and release a job in another network:JOB PAYJOB1 DJCDATA NETID(PAYNET) TC(2) NR(OTHERNET,PAYJOB99)ENDJOB

Abbreviation Description Abbreviation DescriptionID NETID AF AFTERRS RESOURCE NC NORMALTC TAPES AB ABNORMALHC NHOLD NR NETRELRL RELEASE OH OPHOLDBF BEFORE LN LASTNET

DJCDATA Statement: Introduce DJC

344

In the preceding example, PAYJOB1:• Is part of a net called 'PAYNET'• Requires two tape drives• Releases PAYJOB99, which belongs to a net called 'OTHERNET' after its

successful completion.Request multiple resourcesThe following DJCDATA statement is used to request two separate resources:JOB PAYJOB2 DJCDATA RS(1,CICS,1,SCRTAPES)ENDJOB

In the above example, PAYJOB2:• Requires one unit of a resource called CICS• Requires one unit of a resource call SCRTAPES.Wait until resource not availableIn the following example, PAYJOB3 waits until a resource called IMSUP is not available:JOB PAYJOB3 DJCDATA RS(¬IMSUP)ENDJOB

Run when less than five tapes availableIn the following example, PAYJOB4 runs only when the available number of units of a resource called SCRTAPES is less than five.JOB PAYJOB4 DJCDATA RS(<5,SCRTAPES)ENDJOBDefine job on operator holdIn the following example, PAYJOB5 is defined on operator hold:JOB PAYJOB5 DJCDATA OH(YES)ENDJOB

345

DJCNET Statement: Identify that Jobs are Controlled by DJC

Used to identify that jobs are controlled by DJC (Dependent Job Control) or by JES3. It also specifies the default network name for dependent jobs.

TypeDJC Network statement.

SyntaxDJCNET netid

Usage notesIn ESP you can define groups of related jobs as either a DJC orJES3 job network or an ESP Application. Applications provide more flexibility and are easier to work with.At the initiator stage, ESP submits networkjobs to the JESqueue when the Event is scheduled or triggered. Eachjob requires a NETcontrol statement in its JCL that identifies:• The specific networkto which it belongs• The dependent actions that are necessary (for example, the completion of a

predecessor job) before JES can initiate the job.The DJCNET statement allows you to specify the default net identifier for jobs in an ESP Procedure.Jobs defined using DJC or JES3 networks are not available for viewing or manipulation via the Consolidated Status Facility (CSF) or the Application status panels. The CSF and Application status panels are available only for jobs belonging to ESP Applications.Jobs defined using job networks are viewed and controlled using JES commands.

Operand Description

netid Indicates a job network identifier. The maximum length of the netid is eight characters. The first character cannot be a number. The netid applies unless:• You override the netid name with the DJCDATA statement at the

job level.• Another DJCNET statement with a different netid appears in the

same ESP Procedure.

DJCNET Statement: Identify that Jobs are Controlled by DJC

346

Related informationFor information on DJC, see the DJC User’s Guide.For infomation on using DJC or JES3 statements for a job, see the DJCDATA statement.

347

DN Command: Display Names

The DN command is used to display the names of jobs, TSO users and started tasks on the pnode queues.

TypeGeneral command.

AuthorityYou require OPER authority to issue the DN command.

SyntaxDN [QUEUE(pnodename[,pnodename]...)] [JOB[(jobname[,jobname]...)]] [TSU[(tsuname[,tsuname]...)]] [STC[(stcname[,stcname]...)]] [OVERDUE(mins)] [AT(time)] [TIME] [DATE] [COMPRESSED] [DUE] [SID]

Operand Description

pnodename Indicates the name or names of pnodes to be displayed. Several names can be specified, enclosed in parentheses and separated by a blank or comma. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

jobname Indicates the name or names of jobs to be displayed. Several names can be specified, if separated by a comma. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

tsuname Indicates the names of TSO users to be displayed. Several names can be specified if separated by a comma. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

stcname Indicates the names of started tasks to be displayed. Several names can be specified, if separated by a comma. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

DN Command: Display Names

348

Usage notesAs an alternative to using the DN command to display the names of jobs on the pnode queues, you can use the Consolidated Status Facility (CSF) for monitoring and controlling jobs in Applications.

Related informationFor information on displaying the number of jobs on each queue, see the DQ command.For information on defining processing nodes (pnodes), see the ESP Workload Manager Advanced User’s Guide.For information on posting a job complete from a manual pnode, see the POST command. For information on monitoring and controlling workload using the CSF, see the ESP Workload Manager User’s Guide.

Examples Display all pnode queuesIn the following example, all pnode queues are displayed:DN

Display all jobs in a pnodeIn the following example, all jobs on the execution pnode are displayed:DN QUEUE(EXEC) JOB(-)

mins Indicates an overdue amount. Jobs are displayed if they are overdue by the specified number of minutes. If OVERDUE is specified with no Operands, 0 is assumed.

AT(time) Used together with the DUE or OVERDUE keywords, requests a display of jobs that would be overdue if not complete at the specified time. The time can contain a free format date and time specification. It should be enclosed in quotes if it contains a blank or comma.

TIME Indicates the time the job entered the pnode queue is displayed.

DATE Indicates the date the job came into the pnode queue is displayed.

COMPRESSED Indicates the display is compressed to get as many entries on a line as possible. In addition, only the first eight characters of a pnode name are displayed.

DUE Indicates the dueout time for each job is displayed. Jobs that do not have a dueout time are marked as having no due time. To identify a job as having a dueout time, use the DUEOUT or LATESUB Application statements.

SID Indicates the system ID, where the JOB/STC/TSU was last posted from, be displayed.

Operand Description

349

Display certain jobs in a pnodeIn the following example, jobs with names that start with A or B in the INPUT queue are displayed. The date and time the jobs entered their respective queues are also shown:DN JOB(A-,B-) QUEUE(INPUT) DATE TIME

Display jobs overdue at 6amIn the following example, any job that would be more than ten minutes overdue if it does not complete by 6 am is displayed. The due time for each job is displayed as well as the jobname, number and pnode name:DN OVERDUE(10) AT(6AM) DUE

DO Statement: Identify Start of Set of Instructions

350

DO Statement: Identify Start of Set of Instructions

The DO statement is used to identify the start of a set of instructions.

TypeControl Language (CLANG) statement.

SyntaxDO

Usage notesThe DO statement is normally used in conjunction with THEN and ELSE statements. It groups instructions together, until an ENDDO statement is encountered.You do not require a DO statement if you have only one instruction. DO must follow immediately after THEN or ELSE, or begin the continuation line. Do not use a continuation character (– or +) on a DO statement.The DO statement does not have to be used in conjunction with a THEN or ELSE statement.

Related informationFor information on ending a set of instructions, see the ENDDO command.For information on using ESP’s Control Language, see the ESP Workload Manager User’s Guide.

Examples Defining set of instructionsIn the following example, on the last workday of the month, ESP:• Selects PAYJOB2• Sends a message to user CYB01.IF TODAY('LAST WORKDAY OF MONTH') THEN - DO SELECT PAYJOB2 SEND 'SUBMITTING MONTH END JOB' USER(CYB01) ENDDO

Calculate days from year end and trigger EventIn the following example, an ESP built-in function (DAYS_FROM) is used to calculate the number of days from January 1st. If the number of days from January 1st is greater than seven, ESP:• Resumes and then triggers an Event called CYBER.YECHEQUE• Sends a message to user CYB02.

351

IF DAYS_FROM('JAN') GT 7 THEN DO ESP RESUME CYBER.YECHEQUE ESP TRIGGER CYBER.YECHEQUE ADD SEND 'YEAR-END CHEQUES TRIGGERED' U(CYB02)ENDDO

Send multiple messagesIn the following example, when the PAYROLL Application is generated, PAYJOB3 is submitted and two messages are sent to user CYB03:APPL PAYROLLJCLLIB 'CYBBS01.JCLLIB.CNTL'JOB PAYJOB3 RUN DAILY DO SEND 'MESSAGE #1' U(CYB03) SEND 'MESSAGE #2' U(CYB03) ENDDOENDJOB

If condition true, then do ...In the following example, only one instruction is processed if the IF statement returns a true value. You can use DO and ENDDO to identify the start and end of the instruction:IF ACTIVE('CICS') THEN - DO SEND 'CICS IS ACTIVE' CN(01) ENDDO

Alternatively, you could use the following:IF ACTIVE('CICS') THEN - SEND 'CICS IS ACTIVE' CN(01)

DOCLIB Statement: Identify Job Documentation Library

352

DOCLIB Statement: Identify Job Documentation Library

The DOCLIB statement is used to identify the name of the job documentation library to be used throughout an ESP Application. Specifying a DOCLIB statement allows you to use control and user description information.

SyntaxDOCLIB dsname

Usage notesA job documentation entry is a member of a partitioned data set (PDS). Each entry consists of the following information:• Control information—information that ESP uses directly when processing a job,

such as the JCL library, job dependencies, and schedule frequency.• User description—other information you wish to store about a job. For example,

ABEND codes, messages, restart instructions, and so on.You can retrieve job documentation information by the Consolidated Status Facility (CSF), or the JOBINFO (JI) command.You can access job documentation information directly from CSF with the following commands. ESP retrieves the information from the data set identified by the DOCLIB statement in an ESP Application.• BD—browse job documentation• ED—edit job documentation.You can use the DOCLIB statement to specify the job documentation library you want used throughout the ESP Application. For any job, the documentation library member with the same name is accessed unless overridden with a DOCMEM keyword for the job.You can specify multiple DOCLIB statements throughout an ESP Application. Placement of the DOCLIB statements determines where ESP looks to obtain job documentation information. A DOCLIB statement applies to all jobs that follow it, until a new DOCLIB statement occurs.

Operand Description

dsname Indicates the name of the PDS where the job documentation resides.

353

Related informationFor information on using job documentation, see the ESP Workload Manager User’s Guide.For information on the JOBDOC ddname, see the EPS Workload Manager Installation and Configuration Guide.

Examples Specify one job documentation library for an ApplicationIn the following example, ESP retrieves job documentation information from 'CYBER.DOCLIB.CNTL' for all jobs in the PAYROLL Application:APPL PAYROLLJCLLIB 'CYBER.JCLLIB.CNTL'DOCLIB 'CYBER.DOCLIB.CNTL'JOB PAYJOB1JOB PAYJOB2JOB PAYJOB3ENDJOB

Specify multiple job documentation librariesIn the following example, ESP retrieves job documentation information for jobs in the PAYROLL Application as follows:• For PAYJOB4 and PAYJOB5, ESP looks in CYBER.DOCLIB.CNTL for job

documentation information• For PAYJOB6, ESP looks in CYBER.ALT.DOCLIB.CNTL for job

documentation information.APPL PAYROLLJCLLIB 'CYBER.JCLLIB.CNTL'DOCLIB 'CYBER.DOCLIB.CNTL'JOB PAYJOB4JOB PAYJOB5DOCLIB 'CYBER.ALT.DOCLIB.CNTL'JOB PAYJOB6ENDJOB

DQ Command: Display Pnode Queues

354

DQ Command: Display Pnode Queues

The DQ command is used to display the names of all or selected pnode queues, along with the number of jobs in each queue.

TypeGeneral command.

AuthorityYou require OPER authority to issue the DQ command.

SyntaxDQ [QUEUE(pnodename],pnodename]...)]

Usage notesAs an alternative to using the DQ command to display the pnode queues, you can use the Consolidated Status Facility (CSF) for monitoring and controlling jobs in Applications.

Related informationFor information on displaying the names of the jobs in each queue, see the DN command.For information on defining processing nodes (pnodes), see the ESP Workload Manager Advanced User’s Guide.For information on the CSF, see the ESP Workload Manager User’s Guide.

Examples Display all pnode queues and the number of jobsIn the following example, all pnode queues and the corresponding number of jobs in each of those pnode queues are displayed:DQ

Operand Description

pnodename Indicates the name or names of the pnode to be displayed. Several names can be specified, enclosed in parentheses and separated by a blank or comma. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

355

Display EXEC pnode and number of jobsIn the following example, the EXEC (execution) pnode is displayed, along with the number of jobs in this pnode queue:DQ QUEUE(EXEC)

Display multiple queuesIn the following example, the INPUT (input) and EXEC (execution) pnodes are displayed, along with the number of jobs in these pnode queues:DQ QUEUE(INPUT EXEC)

DROPNOTW Statement: Remove Entries from NOTWITH List

356

DROPNOTW Statement: Remove Entries from NOTWITH List

The DROPNOTW statement removes entries from the previously built NOTWITH list.

SyntaxDROPNOTW job1[.qual1][/appl1] (job1[.qual1][/appl1],job2[.qual2][/appl2])

Usage notesWhen the NOTWITH statement is specified outside the scope of a job, there may be one job in the Application that can run concurrently with the other jobs. The DROPNOTW statement can be used in the scope of the job that can run concurrently to allow it to run.

Example APPL NWN00AJCLLIB 'CYBER.JCL.CNTL'

JOB NWN001 RUN DAILY NOTWITH (NWN002,NWN003)ENDJOB

NOTWITH NWN001

JOB NWN002 RUN DAILYENDJOB

JOB NWN003 RUN DAILYENDJOB

JOB NWN004 RUN DAILY DROPNOTW NWN001ENDJOB

Operand Descriptionjob1 Specifies the matching entries, character for character, added by

preceding NOTWITH statements will be removed from the list.

357

DSN Statement: Specify Target Data Source Name (DSN) Within DB_JOB

The DSN statement specifies the target Data Source Name (DSN) for a DB_JOB workload object.

ApplicabilityESP System Agents, Release 6, used within a DB_JOB workload object. For more information, see “DB_JOB Statement: Identify the Name of Database Jobs” on page 245.

SyntaxDSN DataSourceName

Usage notesThe Data Source Name provides connectivity to a database through a JDBC driver. The DSN contains database name, directory, database driver, UserID, password, and other information. Once you create a DSN for a particular database, you can use the DSN in an Application to call information from the database.

ExamplesExample 1DB_JOB DBJOB1.STMNT AGENT R6AGENT USER sapr3 DSN oracle:thin:@gemini:1527:cyb QUERY 'SELECT JOBNAME FROM TBTCO' RUN DAILY RELEASE DBTEST2ENDJOB

Example 2DB_JOB DBJOB2.STMNT AGENT R6AGENT USER sapr3 DSN oracle:thin:@gemini:1527:cyb SQL 'SELECT COUNT (*) FROM TBTCO WHERE JOBNAME LIKE ''SD%'' + AND ENDDATE = ''20030813''' RUN DAILYENDJOB

Operand DescriptionDataSourceName The Java or Oracle database to be used.

DSN Statement: Specify Target Data Source Name (DSN) Within DB_JOB

358

Example 3 (UNIX)In this example, the data source is defined as an IP address followed by an IP port number.DB_JOB DBJOB3.STMNT AGENT R6AGENT USER db2admin DSN db2://10.1.1.46:50000/sample SQL 'SELECT COUNT(*) FROM STAFF WHERE NAME LIKE ''L%''' DESTINATION '/export/home/qatest/db job data/test14.bd2' RUN DAILYENDJOB

Example 4 (NT)DB_JOB DBJOB3.STMNT AGENT R6AGENT USER db2admin DSN db2://10.1.1.46:50000/sample SQL 'SELECT COUNT(*) FROM STAFF WHERE NAME LIKE ''L%''' DESTINATION 'c:\qatest\db job data\test14.bd2' RUN DAILYENDJOB

359

DSNAME Statement: Identify Data Sets for Data Set Triggers

The DSNAME statement is used in conjunction with the DSTRIG workload object, and is used to build a data set dependency at the job level into ESP Applications. This statement can:• Detect the creation, closure or renaming of a data set by a job, started task, or TSO

user. This is known as implicit data-set trigger.• Detect the successful receiving or sending of a data set through FTP• Detect the creation or update of a data set through an explicit data-set trigger. An

explicit data-set trigger is used when ESP Workload Manager needs to be explicitly notified of a data-set activity because no system SMF record exists to implicitly detect it.

SyntaxDSNAME dsname[(member)|(relgen)] { |{[FTP(RECEIVE|RECV) [RENAME]|[FTP(SEND)]}|EXPLICIT}

Note: Do not enter anything for the default: implicit data-set trigger. member is not available for implicit data-set triggers. relgen is available only for explicit data-set triggers.member and relgen are mutually exclusive.

Implicit data-set trigger

[JOBNAME(jobname)] [RENAME] [ANYCLOSE] [COUNT(n)] [USER(userid)]

FTP data-set trigger{[FTP(RECEIVE|RECV) [RENAME]|[FTP(SEND)]} [JOBNAME(jobname)] [ANYCLOSE] [COUNT(n)] [HOST(hostname)] [USER(userid)] [LOGON(logonid)]

Note: One or more of FTP, HOST, or LOGON is required to specify an FTP data-set trigger.

Explicit data-set triggerEXPLICIT [JOBNAME(jobname)] [COUNT(n)] [USER(userid)]

DSNAME Statement: Identify Data Sets for Data Set Triggers

360

Operand Description

dsname Indicates the full name or generic prefix of a data set. The data-set name should start with the high-level index, because the current TSO data-set prefix is not used.A generic prefix is specified by attaching a wildcard hyphen '-' to the end of the prefix. The use of quotation marks is optional. The wildcard hyphen must not immediately follow the period separating the qualifiers. If the wildcard hyphen is the last character on the line, it will be interpreted as a continuation character and not as a wildcard. There must be something else on the line if only a blank comment (/* */). The dsname of the DSNAME Application statement always refers to the local mainframe data set for both FTP(RECEIVE) and FTP(SEND).

member Specifies the PDS member name. See “Usage of member operand” on page 364.

relgen Specifies the relative generation data group (GDG). For example you can code:• (0) for the current generation• (+1) for the next generation• (-1) for the previous generationYou must code relgen in DSNAME and in the corresponding CYBESDT1 exactly the same, including leading zeros.

Note: you can also include the absolute generation in dsname. For example:CYB4.ENCXX.BACKO01A.G0027V00

Indicates that the data-set trigger is activated by the creation, closure or renaming of a data set by a job, started task or TSO user. This is known as an implicit data-set trigger.

FTP Indicates that the data-set trigger is activated following the successful completion of an FTP transfer.

Note: When using an FTP data-set trigger, either SMF record type 118 or 119 is examined, depending on the setting of the FTP initialization parameter. The SMF record type 119 is available only with z/OS.

RECEIVE Means that the FTP transfer is from the remote FTP partner to the local mainframe FTP partner. This is the default.

RECV Same as RECEIVE.

SEND Means that the FTP transfer is from a local mainframe FTP partner to the remote FTP partner.

EXPLICIT Indicates that this data-set trigger is an EXPLICIT data-set trigger.

Note: When using an EXPLICIT data-set trigger, only SMF record type 132 subtype 1 is examined.

361

Implicit data-set trigger

FTP data-set trigger

Operand DescriptionJOBNAME(jobname)

Indicates that the triggering will take place only when a specific job causes the data-set activity being considered by the DSNAME statement. jobname indicates the full name or generic prefix of a jobname. A generic prefix is signified by a trailing hyphen '-'. This can also be a TSO user ID.

RENAME Indicates the trigger should also occur if a data set is renamed to the dsname specified. The new data-set name becomes the triggering data-set name. When RENAME is specified for an FTP trigger, the trigger is activated on completion of an FTP rename command issued by the client to rename the data set to the specified dsname. Because dsname always refers to a local host data set, the remote FTP partner must be the client for an FTP trigger where RENAME is specified. Therefore, the RENAME and FTP(SEND) operands are mutually exclusive. RENAME is not allowed for an explicit data-set trigger.

ANYCLOSE Indicates the trigger should occur on any closure of the specified data set, rather than just the closure of a newly created data set. If you do not use this operand, the trigger occurs only if the specified data set is created. FTP triggers are unable to distinguish between data-set creation and data-set updates. Therefore, ANYCLOSE is assumed if not explicitly specified in an FTP trigger definition. ANYCLOSE is not allowed for an explicit data-set trigger.

COUNT(n) Indicates the Event is to be scheduled for every n triggers, where n is a number from 0 to 255. A value of 0 results in a schedule for each trigger, as does a value of one. It defaults to one.

USER(userid)

The USER operand allows restricting the activation of the data-set trigger to action originating from a specific userYou can use wildcard characters. The following example accepts any user whose user ID starts with abc:

USER(abc-)For implicit data-set triggers, userid refers to the mainframe user ID of the job task closing or renaming the data set.Because userid always refer to a local mainframe user ID, lower case characters are translated to uppercase.

Operand DescriptionJOBNAME(jobname)

Indicates that the triggering will take place only when a specific job causes the data-set activity being considered by the DSNAME statement. jobname indicates the full name or generic prefix of a jobname. A generic prefix is signified by a trailing hyphen '-'. This can also be a TSO user ID.

DSNAME Statement: Identify Data Sets for Data Set Triggers

362

ANYCLOSE Indicates the trigger should occur on any closure of the specified data set, rather than just the closure of a newly created data set. If you do not use this operand, the trigger occurs only if the specified data set is created. FTP triggers are unable to distinguish between data-set creation and data-set updates. Therefore, ANYCLOSE is assumed if not explicitly specified in an FTP trigger definition. ANYCLOSE is not allowed for an explicit data-set trigger.

COUNT(n) Indicates the Event is to be scheduled for every n triggers, where n is a number from 0 to 255. A value of 0 results in a schedule for each trigger, as does a value of one. It defaults to one.

HOST(hostname)

The HOST operand allows restricting the activation of the data-set trigger to transfers to or from a specific remote host. This is valid only within the context of an FTP trigger. If the FTP operand is omitted, FTP(RECEIVE) is assumed. hostname represents the name of the specified remote host. This is either a DNS host name or an IP address. The maximum length for a DNS host name is 100 characters.

USER(userid)

The USER operand allows restricting the activation of the data-set trigger to action originating from a specific userYou can use wildcard characters. The following example accepts any user whose user ID starts with abc:

USER(abc-)

For FTP data-set triggers, userid refers to the mainframe user ID of the local FTP partner’s job task, regardless of whether the local FTP partner is the client or the server.Because userid always refer to a local mainframe user ID, lower case characters are translated to uppercase.

Operand Description

363

Explicit data-set trigger

LOGON(logonid)

The LOGON operand allows restricting the activation of the data-set trigger to transfer to or from a specific user. Only valid within the context of an FTP trigger. If the FTP operand is omitted, FTP(RECEIVE) is assumed. logonid represents the user ID that the FTP client uses to logon to the FTP server.You can use wildcard characters. The following example accepts any user whose user ID starts with abc

LOGON(abc-)

If the FTP client is the remote partner, then logonid is the user ID of the local FTP partner. In this case, specifying LOGON(logonid) has the same effect as specifying USER(userid).If the FTP client is the local partner, then logonid is the user ID of the remote FTP partner.When logonid is a remote user ID, it may be case sensitive, as for example on UNIX hosts. Therefore logonid lower case characters are not translated to upper case.

Operand DescriptionJOBNAME(jobname)

Indicates that the triggering will take place only when a specific job causes the data-set activity being considered by the DSNAME statement. jobname indicates the full name or generic prefix of a jobname. A generic prefix is signified by a trailing hyphen '-'. This can also be a TSO user ID.

COUNT(n) Indicates the Event is to be scheduled for every n triggers, where n is a number from 0 to 255. A value of 0 results in a schedule for each trigger, as does a value of one. It defaults to one.

USER(userid)

The USER operand allows restricting the activation of the data-set trigger to action originating from a specific user.You can use wildcard characters. The following example accepts any user whose user ID starts with abc:

USER(abc-)

For explicit data-set triggers, userid refers to the mainframe user ID of the job or task closing or renaming the data set.Because userid always refer to a local mainframe user ID, lower case characters are translated to uppercase.

Operand Description

DSNAME Statement: Identify Data Sets for Data Set Triggers

364

Usage notesDSNAME is used within the scope of a z/OS data set trigger workload object to describe the triggering data set. If you use COUNT, the CSF STATUS field displays this value and the current count.Only one DSNAME statement is allowed per data-set trigger object.ESP Workload Manager does not complete a data set trigger object when the data set closes during the abnormal termination of a task or job step.You can use the JOB operand to restrict the trigger to a specific job, started task or TSO user ID.

Usage of member operandIf a PDS member name is specified, it may be use wildcards. For exampleDSNAME PDS.DATA.SET(MEMBER-) EXPLICIT

If a PDS member name is specified, the data-set name cannot be generic. The following is invalid:DSNAME PDS.DATA.S-(MEMBER1) EXPLICIT

Note: If the dsname operand of a DSNAME statement specifies a PDS without specifying a member name, then the creation or update of any member of that PDS will activate the data-set trigger.Note: PDS member names are not supported for implicit data-set triggers because when a PDS is allocated and opened without a member specification, there is no indication in the SMF record which members were created and updated.

SMF recordsType 14 records are generated by the system when a non-VSAM data set is closed, after it is opened for input. In such a case, the data set was only read by the opening program, but not updated. No data set triggering should take place, and therefore ESP Workload Manager ignores these records.Type 15 records are generated when a non-VSAM data set is closed, after having been opened for output. A new data set might have been created (DISP=NEW) or an existing data set might have been rewritten or updated (DISP=OLD or MOD).If ANYCLOSE was specified in the DSTRIG statement, the data set trigger object is completed when a type 15 record is detected by ESP Workload Manager. If ANYCLOSE was not specified, ESP Workload Manager checks to see if the type 15 record represents a new data set being created. If so, the data set trigger object is completed. If an existing data set was updated, the trigger does not take place.Type 15 records are also generated when end-of-volume (EOV) processing takes place. These records are ignored by ESP Workload Manager. ESP Workload Manager also ignores records pertaining to VIO or temporary data sets.

365

Type 18 records are generated when a data set is renamed.Type 64 records are generated when a VSAM data set is closed or when EOV processing takes place. As with type 15 records, EOV records are ignored. ESP Workload Manager also ignores TCLOSE records (CLOSE TYPE=T) and records not pertaining to the DATA component of a VSAM cluster. Type 118 or 119 records are generated following the reception, transmission, or renaming of a data set. These records supply information such as the ID address of the partner, the number of records generated, and error indicators. Type 119 is available only with z/OS. ESP Workload Manager monitors types 118 or 119 depending on the setting of the FTP initialization parameter.Type 132 subtype 1 records are generated by the CYBESDT1 utility for explicit data-set triggers.

Related informationFor information on data-set triggering, see the ESP Workload Manager User’s Guide.For information on data-set triggering at the Event level, see the DSTRIG command

For information on data-set triggering at the job level, see the DSTRIG statement.For information on Applications, see the ESP Workload Manager User’s Guide.

Examples Trigger on the closure of a new data setIn the following example, WAIT4.DLY is used to build a job-level dependency with the closure of a newly created data set called PROD.DAILY.ACCNTS:APPL PAYROLLJCLLIB 'CYB.JCL.CNTL'DSTRIG WAIT4.DLY DSNAME PROD.DAILY.ACCNTS RUN DAILY REL PAYJOB2JOB PAYJOB2 RUN DAILYENDJOB

DSNAME Statement: Identify Data Sets for Data Set Triggers

366

Trigger on any closure of a data setIn the following example, WAIT4.WKLY is used to build a job-level dependency with any closure of a data set called PROD.WEEKLY.ACCNTS:APPL PAYROLLJCLLIB 'CYB.JCL.CNTL'DSTRIG WAIT4.WKLY DSNAME PROD.WEEKLY.ACCNTS ANYCLOSE RUN DAILY REL PAYJOB4JOB PAYJOB4 RUN DAILYENDJOB

Trigger after every second closure of a data setIn the following example, the trigger occurs after every second closure of a data set:DSNAME CYBER.CYCLES COUNT(2)

Trigger when data set renamedIn the following example, the trigger occurs when a data set is renamed to SYS1.TEMP.DATA:DSNAME SYS1.TEMP.DATA RENAME

Trigger when a generation is createdIn the following example, quotation marks around the data set name are required because the wildcard hyphen is the last character on the line. The trigger occurs when a generation is created:DSNAME 'USER1.PAYROLL.G-'

Trigger when a generation is created by a specific jobIn the following example, quotation marks are not required because the wildcard hyphen is not the last character on the line. The trigger occurs when a generation is created by a specific job:DSNAME USER1.PAYROLL.G- JOB(ABC)

Use of the wildcard hyphenThe following example shows an invalid use of the wildcard hyphen:DSNAME CYBER.TEST.- ANYCLOSE

The following example shows the correct use of the wildcard hyphen:DSNAME CYBER.TEST- ANYCLOSE

The following examples show an invalid use of the wildcard hyphen. In these examples no other operands of the DSNAME statement are being used therefore the wildcard hyphen is being interpreted as a continuation character:

367

DSNAME CYBER.TEST.-

DSNAME CYBER.TEST-

FTP transfer triggered objectThis object sends a message to a user when an FTP transfer to data set CYBER.DATA.SET completes from logged on user aixuser on host AIXHOST to any local user with mainframe userid prefix CYB. Because both the USER and the LOGON operands are specified and they specify different user IDs, the FTP trigger criteria can only be satisfied if the local FTP partner is the client. DSTRIG ABCDSNAME CYBER.DATA.SET USER(CYB-) FTP(RECEIVE) HOST(AIXHOST) - LOGON (aixuser)SEND 'APPLICATION RECEIVED FROM CLIENT' USER(BP)RUN DAILYENDJOB

Explicit data-set trigger notification using batchIn this example, STEP1 creates or updates member MEMBER1 in the data set PDS.DATA.SET.If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set PDS.DATA.SET(MEMBER1) has been created or updated.//DSTRIG01 JOB ...//*//STEP1 EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//SYSUT1 DD DISP=SHR,DSN=SEQ.DATA.SET//SYSUT2 DD DISP=OLD,DSN=PDS.DATA.SET(MEMBER1)//*//STEP2 EXEC PGM=CYBESDT1,COND=(0,LT),// PARM='DSNAME(PDS.DATA.SET(MEMBER1)) SUBSYSTEM(ESPS)'//STEPLIB DD DISP=SHR,DSN=CYBER.SSCPLINK

This workload object sends a message to a user when the data set PDS.DATA.SET(MEMBER1) has been created or updated:DSTRIG ABCDSNAME PDS.DATA.SET(MEMBER1) EXPLICITSEND 'DATA SET MEMBER1 UPDATED' USER(BP)RUN DAILYENDJOB

Note: The data-set trigger, whether an Event or a workload object, must exist before you execute CYBESDT1.

DSTRDLY Command: Delay Data Set Triggers

368

DSTRDLY Command: Delay Data Set Triggers

The DSTRDLY command is used to delay data set triggered Events or data set trigger objects when data set activity occurs.

TypeGeneral command.

AuthorityYou require OPER authority to issue the DSTRDLY command.

SyntaxDSTRDLY [nn|0]

Usage notesData set triggered Events or data set trigger objects may trigger too soon after a data set has been closed. This operand causes a global delay of data set triggers. For example, a data set trigger may occur after a data set is created but prior to the data set being cataloged.This is normally coded as an ESP initialization parameter.To display what the data set trigger delay value is currently set to issue the DSTRDLY command with no operands.

Related informationFor information on data set triggering at the job level, see the DSTRIG or DSNAME statements.For information on data set triggering at the Event level, see the ESP Workload Manager User’s Guide.

Examples Display current delayIn the following example, issuing DSTRDLY with no operand displays the current data set trigger delay value:OPER DSTRDLY

The results are displayed as follows:DATASET TRIGGER DELAY VALUE CURRENTLY SET AT 0 SECONDS

Operand Descriptionnn Number of seconds to delay. The default is zero.

369

Set delay to 15 secondsIn the following example, data set triggered Events or data set trigger objects are delayed by 15 seconds:DSTRDLY 15

DSTREXCL Command: Exclude Data Set Triggers

370

DSTREXCL Command: Exclude Data Set Triggers

The DSTREXCL command is used to flag an entry in the Data set Trigger Exclude list as invalid. These entries are not actually deleted from the list. Entries flagged as inactive are converted to lowercase.

TypeGeneral command.

AuthorityYou require OPER authority to issue the DSTREXCL command.

SyntaxDSTREXCL {pgmname} [(pgmname[,pgmname]...)]

Usage notesThe Data set Trigger Exclude list consists of a list of programs that are not eligible for data set triggering. The DSTREXCL initialization parameter specifies these. Once this list has been built, you use the DSTREXCL command to flag an entry in the Data set Trigger Exclude list as invalid.

Related informationFor information on adding an entry to the Data set Trigger Exclude list, see the DSTREXCL initialization parameter in the ESP Workload Manager Installation and Configuration Guide.For information on displaying the Data set Trigger Exclude list, see the LDTREL command.

Example To exclude PGM999The following example flags a PGM999 entry in the Data set Trigger Exclude list as invalid. The command is issued from Page mode:DSTREXCL PGM999

In the above example, PGM999 is flagged as invalid. PGM999 is not actually deleted from the list—its entry is converted to lowercase as follows:DSTRIG exclude PGM=pgm999

Operand Description

pgmname Indicates the name of a program to be flagged as no longer part of the Data set Trigger Exclude list.

371

DSTRIG Command: Define Data Set Triggers - Event Level

The DSTRIG command is used to:• Trigger an Event automatically by the creation, closure or renaming of a data set

by a job, started task or TSO user. This is known as implicit data-set trigger.• Trigger an event based on the successful receiving or sending of a data set through

FTP• Trigger an event based on an explicit data-set trigger. An explicit data-set trigger

is used when ESP Workload Manager needs to be explicitly notified of a data-set activity because no system SMF record exists to implicitly detect it.

Triggering can be restricted to data sets created by a specific job or group of jobnames. Events can also be made to wait for triggers from activity in more than one data set. ESP Workload Manager accomplishes data set triggering by watching all SMF records generated by the system:• SMF record types 14, 15 and 64 are the record types that represent the closing of a

data set.• SMF record type 18 represents the renaming of a data set.• SMF record types 118 or 119 represent the reception, transmission, or renaming of

a data set via FTP. Record type 119 is available only with z/OS. ESP Workload Manager monitors types 118 or 119 depending on the setting of the FTP initialization parameter.

• SMF record type 132 subtype 1 are generated by the CYBESDT1 utility for explicit data-set triggers.

TypeGeneral command.

DSTRIG Command: Define Data Set Triggers - Event Level

372

SyntaxDSTRIG dsname[(member)|(relgen)] { |{[FTP(RECEIVE|RECV) [RENAME]|[FTP(SEND)]}|EXPLICIT}

Note: Do not enter anything for the default: implicit data-set trigger. member is not available for implicit data-set triggers. relgen is available only for explicit data-set triggers.

Implicit data-set trigger [JOBNAME(jobname)] [MULTIPLE] [PRIMED] [RENAME] [ANYCLOSE] [COUNT(n)] [CURRENT(n)] [USER(userid)]

FTP data-set trigger{[FTP(RECEIVE|RECV) [RENAME]|[FTP(SEND)]} [JOBNAME(jobname)] [MULTIPLE] [PRIMED] [ANYCLOSE] [COUNT(n)] [CURRENT(n)] [HOST(hostname)] [USER(userid)] [LOGON(logonid)]

Note: One or more of FTP, HOST, or LOGON is required to specify an FTP data-set trigger.

Explicit data-set triggerEXPLICIT [JOBNAME(jobname)] [MULTIPLE] [PRIMED] [COUNT(n)] [CURRENT(n)] [USER(userid)]

373

Operand Description

dsname Indicates the full name or generic prefix of a data set. The data-set name should start with the high-level index, because the current TSO data-set prefix is not used.A generic prefix is specified by attaching a wildcard hyphen '-' to the end of the prefix. The use of quotation marks is optional. The wildcard hyphen must not immediately follow the period separating the qualifiers. If the wildcard hyphen is the last character on the line, it will be interpreted as a continuation character and not as a wildcard. There must be something else on the line if only a blank comment (/* */). The dsname of the DSTRIG command always refers to the local mainframe data set for both FTP(RECEIVE) and FTP(SEND).

member Specifies the PDS member name. See “Usage of member operand” on page 379.

relgen Specifies the relative generation of the generation data group (GDG). For example you can code:• (0) for the current generation• (+1) for the next generation• (-1) for the previous generationYou must code relgen in DSTRIG and in the corresponding CYBESDT1 in exactly the same way, including leading zeros.

Note: Alternatively, you can include the absolute generation in dsname. For example:

CYB4.ENCXX.BACKO01A.G0027V00

Implicit data-set trigger. Indicates that the data-set trigger is activated by the creation, closure or renaming of a data set by a job, started task or TSO user.

FTP FTP data-set trigger. Indicates that the data-set trigger is activated following the successful completion of an FTP transfer.

Note: When using an FTP data-set trigger, either SMF record type 118 or 119 is examined, depending on the setting of the FTP initialization parameter. The SMF record type 119 is available only with z/OS.

RECEIVE | RECV Means that the FTP transfer is from the remote FTP partner to the local mainframe FTP partner.

DSTRIG Command: Define Data Set Triggers - Event Level

374

Implicit data-set trigger

SEND Means that the FTP transfer is from a local mainframe FTP partner to the remote FTP partner.

EXPLICIT Indicates that this data-set trigger is an EXPLICIT data-set trigger.

Note: When using an EXPLICIT data-set trigger, only SMF record type 132 subtype 1 is examined.

Operand Description

Operand DescriptionJOBNAME(jobname) Indicates that the triggering will take place only when a

specific job causes the data-set activity being considered by the DSTRIG command. jobname indicates the full name or generic prefix of a jobname. A generic prefix is signified by a trailing hyphen '-'. This can also be a TSO user ID.

MULTIPLE Indicates closure of at least one other data set is needed to trigger this Event. The Event does not execute until all specified data-set triggers are detected. MULTIPLE must be specified on each DSTRIG command for the required data sets.

PRIMED Indicates a data-set trigger was already detected for this data set. This operand is used only when redefining an Event, when one of the specified multiple data-set triggers is already detected.

RENAME Indicates the trigger should also occur if a data set is renamed to the dsname specified. The new data-set name becomes the triggering data-set name. When RENAME is specified for an FTP trigger, the trigger is activated on completion of an FTP rename command issued by the client to rename the data set to the specified dsname. Because dsname always refers to a local host data set, the remote FTP partner must be the client for an FTP trigger where RENAME is specified. Therefore, the RENAME and FTP(SEND) operands are mutually exclusive. RENAME is not allowed for an explicit data-set trigger.

375

FTP data-set trigger

ANYCLOSE Indicates the trigger should occur on any closure of the specified data set, rather than just the closure of a newly created data set. If you do not use this operand, an Event is triggered only if the specified data set is created. FTP triggers are unable to distinguish between data-set creation and data-set updates. Therefore, ANYCLOSE is assumed if not explicitly specified in an FTP trigger definition. ANYCLOSE is not allowed for an explicit data-set trigger.

COUNT(n) Indicates the Event is to be scheduled for every n triggers, where n is a number from 0 to 255. A value of 0 results in a schedule for each trigger, as does a value of one. It defaults to one.

CURRENT(n) Used with the COUNT operand, it optionally sets the initial trigger count. The value n can range from 0 to 255. It defaults to 0.

USER(userid) The USER operand allows restricting the activation of the data-set trigger to action originating from a specific userYou can use wildcard characters. The following example accepts any user whose user ID starts with abc:

USER(abc-)

For implicit data-set triggers, userid refers to the mainframe user ID of the job task closing or renaming the data set.Because userid always refer to a local mainframe user ID, lower case characters are translated to uppercase.

Operand Description

Operand DescriptionJOBNAME(jobname) Indicates that the triggering will take place only when a

specific job causes the data-set activity being considered by the DSTRIG command. jobname indicates the full name or generic prefix of a jobname. A generic prefix is signified by a trailing hyphen '-'. This can also be a TSO user ID.

MULTIPLE Indicates closure of at least one other data set is needed to trigger this Event. The Event does not execute until all specified data-set triggers are detected. MULTIPLE must be specified on each DSTRIG command for the required data sets.

DSTRIG Command: Define Data Set Triggers - Event Level

376

PRIMED Indicates a data-set trigger was already detected for this data set. This operand is used only when redefining an Event, when one of the specified multiple data-set triggers is already detected.

ANYCLOSE Indicates the trigger should occur on any closure of the specified data set, rather than just the closure of a newly created data set. If you do not use this operand, an Event is triggered only if the specified data set is created. FTP triggers are unable to distinguish between data-set creation and data-set updates. Therefore, ANYCLOSE is assumed if not explicitly specified in an FTP trigger definition. ANYCLOSE is not allowed for an explicit data-set trigger.

COUNT(n) Indicates the Event is to be scheduled for every n triggers, where n is a number from 0 to 255. A value of 0 results in a schedule for each trigger, as does a value of one. It defaults to one.

CURRENT(n) Used with the COUNT operand, it optionally sets the initial trigger count. The value n can range from 0 to 255. It defaults to 0.

HOST(hostname) The HOST operand allows restricting the activation of the data-set trigger to transfers to or from a specific remote host. This is valid only within the context of an FTP trigger. If the FTP operand is omitted, FTP(RECEIVE) is assumed. hostname represents the name of the specified remote host. This is either a DNS host name or an IP address. The maximum length for a DNS host name is 100 characters.

USER(userid) The USER operand allows restricting the activation of the data-set trigger to action originating from a specific userYou can use wildcard characters. The following example accepts any user whose user ID starts with abc:

USER(abc-)

For FTP data-set triggers, userid refers to the mainframe user ID of the local FTP partner’s job task, regardless of whether the local FTP partner is the client or the server.Because userid always refer to a local mainframe user ID, lower case characters are translated to uppercase.

Operand Description

377

Explicit data-set trigger

LOGON(logonid) The LOGON operand allows restricting the activation of the data-set trigger to transfer to or from a specific user. Only valid within the context of an FTP trigger. If the FTP operand is omitted, FTP(RECEIVE) is assumed. logonid represents the user ID that the FTP client uses to logon to the FTP server. You can use wildcard characters. The following example accepts any user whose user ID starts with abc:

LOGON(abc-)

If the FTP client is the remote partner, then logonid is the user ID of the local FTP partner. In this case, specifying LOGON(logonid) has the same effect as specifying USER(userid).If the FTP client is the local partner, then logonid is the user ID of the remote FTP partner.When logonid is a remote user ID, it may be case sensitive, as for example on UNIX hosts. Therefore logonid lower case characters are not translated to upper case.

Operand Description

Operand DescriptionJOBNAME(jobname) Indicates that the triggering will take place only when a

specific job causes the data-set activity being considered by the DSTRIG command. jobname indicates the full name or generic prefix of a jobname. A generic prefix is signified by a trailing hyphen '-'. This can also be a TSO user ID.

MULTIPLE Indicates closure of at least one other data set is needed to trigger this Event. The Event does not execute until all specified data-set triggers are detected. MULTIPLE must be specified on each DSTRIG command for the required data sets.

PRIMED Indicates a data-set trigger was already detected for this data set. This operand is used only when redefining an Event, when one of the specified multiple data-set triggers is already detected.

DSTRIG Command: Define Data Set Triggers - Event Level

378

Usage notesESP Workload Manager does not trigger a data-set triggered Event when the data set closes during an abnormal termination of a task or job step. Allocating a partitioned data set in ISPF or executing an IEFBR14 will also not satisfy a data-set triggered Event. The DSTRIG command is used to request that the Event is triggered on the creation or closure of a data set. The trigger actually occurs at the time the data set is closed. If multiple files in a step reference the data set, the trigger occurs only if the file being closed is the one that specifies DISP=NEW. When an Event needs more than one data-set closure to be eligible for execution, use the MULTIPLE operand on each corresponding DSTRIG command. Individual data-set closures are detected, but the Event does not execute until all other DSTRIG commands with the MULTIPLE operand also detect data-set closures.You can use the JOB operand to restrict the trigger to a specific job, started task or TSO user.

COUNT(n) Indicates the Event is to be scheduled for every n triggers, where n is a number from 0 to 255. A value of 0 results in a schedule for each trigger, as does a value of one. It defaults to one.

CURRENT(n)

Used with the COUNT operand, it optionally sets the initial trigger count. The value n can range from 0 to 255. It defaults to 0.

USER(userid)

The USER operand allows restricting the activation of the data-set trigger to action originating from a specific userYou can use wildcard characters. The following example accepts any user whose user ID starts with abc:

USER(abc-)

For explicit data-set triggers, userid refers to the mainframe user ID of the job or task closing or renaming the data set.Because userid always refer to a local mainframe user ID, lower case characters are translated to uppercase.

Operand Description

379

Explicit data-set triggerAn explicit data-set trigger consists of two parts:• The explicit data-set trigger notification utility program (CYBESDT1).• The parameter EXPLICIT in the DSTRIG command or in the DSNAME

statement.You invoke CYBESDT1 in a job, as an additional step, conditionally to the successful execution of the step manipulating a specified data set. This program writes an SMF record type 132 subtype 1.

Usage of member operandIf a PDS member name is specified, it may use wildcards. For example,DSTRIG PDS.DATA.SET(MEMBER-) EXPLICIT

If a PDS member name is specified, the data-set name cannot be generic. The following is invalid:DSTRIG PDS.DATA.S-(MEMBER1) EXPLICIT

Note: If the dsname operand of a DSTRIG command specifies a PDS without specifying a member name, then the creation or update of any member of that PDS will activate the data-set trigger.Note: PDS member names are not supported for implicit data-set triggers because when a PDS is allocated and opened without a member specification, there is no indication in the SMF record which members were created and updated.

SMF recordsType 14 records are generated by the system when a non-VSAM data set is closed, after it is opened for input. In such a case, the data set was only read by the opening program, but not updated. No data set triggering should take place, and therefore ESP Workload Manager ignores these records.Type 15 records are generated when a non-VSAM data set is closed, after having been opened for output. A new data set might have been created (DISP=NEW) or an existing data set might have been rewritten or updated (DISP=OLD or MOD).If ANYCLOSE was specified in the DSTRIG statement, the Event is triggered when ESP Workload Manager detects a type 15 record. If ANYCLOSE was not specified, ESP Workload Manager checks to see if the type 15 record represents a new data set being created. If so, the Event is triggered. If an existing data set was updated, the trigger does not take place.Type 15 records are also generated when end-of-volume (EOV) processing takes place. ESP Workload Manager ignores these records. ESP Workload Manager also ignores records pertaining to VIO or temporary data sets.Type 18 records are generated when a data set is renamed.

DSTRIG Command: Define Data Set Triggers - Event Level

380

Type 64 records are generated when a VSAM data set is closed or when EOV processing takes place. As with type 15 records, EOV records are ignored. ESP Workload Manager also ignores TCLOSE records (CLOSE TYPE=T) and records not pertaining to the DATA component of a VSAM cluster. Type 118 or 119 records are generated following the reception, transmission, or renaming of a data set via FTP. These records supply information such as the ID address of the partner, the number of records generated, and error indicators. Record type 119 is available only with z/OS. ESP Workload Manager monitors types 118 or 119 depending on the setting of the FTP initialization parameter.Type 132 subtype 1 records are generated for explicit data-set triggering to function.

Related informationFor information on data-set triggering, see the ESP Workload Manager User’s Guide.For information on displaying data-set triggered Events, see the LDXE command.For information on displaying data sets being checked for closure, creation, or renaming, see the LDTE command.

For information on data-set triggering at the job level, see the DSTRIG and DSNAME statements.

Examples Trigger on any closure of a data setIn the following example, any closure of PROD.PAYROLL.FILE123 automatically triggers this Event:EVENT ID(CYB.PAYDLY)DSTRIG PROD.PAYROLL.FILE123 ANYCLOSEINVOKE 'CYB.ESP.PROCS(PAYDLY)'ENDDEF

Trigger on the creation of a generation of a GDGIn the following example, when a generation of PROD.PAYROLL is created by PAYJOB1, this Event is automatically triggered:EVENT ID(CYB.PAYWKLY)DSTRIG PROD.PAYROLL.G- JOB(PAYJOB1)SUBMIT 'CYB.JCL.CNTL(PAYWKLY)'ENDDEF

Note: The Event is triggered when any data set with a name staring with PROD.PAYROLL.G is created by PAYJOB1 including generations of PROD.PAYROLL.

381

Trigger on multiple conditionsThe following Event triggers upon both closure of a specific data set and the creation of another data set:EVENT ID(CYB.PAYMTH)DSTRIG PROD.PAYROLL.FILE999 ANYCLOSE MULTIPLEDSTRIG PROD.PAYROLL.G- JOB(PAYJOB2) MULTIPLE INVOKE 'CYB.ESP.PROCS(PAYMTH)'ENDDEF

In the above example, coding MULTIPLE on each DSTRIG command indicates that this Event is not triggered until both of the following criteria have been met:• Any closure of PROD.PAYROLL.FILE999• PAYJOB2 creates a generation of PROD.PAYROLL.Note: The second criterion is met when any data set with a name staring with

PROD.PAYROLL.G is created by PAYJOB2 including generations of PROD.PAYROLL.

Trigger on every 255 closuresThe following Event triggers every 255 closures of a specific data set:EVENT ID(CYB.PAYBKUP)DSTRIG PROD.ESP.COPYJCL ANYCLOSE COUNT(255) INVOKE 'CYB.ESP.PROCS(PAYBKUP)'ENDDEF

Trigger when data set is renamedIn the following example, when a data set is renamed to CYB.ESP.DATA, this Event is automatically triggered:EVENT ID(CYB.PAYMTH) DSTRIG CYB.ESP.DATA RENAME INVOKE 'CYB.ESP.PROCS(PAYMTH)'ENDDEF

Trigger on closure by user IDIn the following example, when USERWK closes the CICS.WORLD.WIDE data set, the PROD.POST Event triggers. If, however, USERWK submits a job that closes the data set, ESP uses the job name, not the user ID to determine if the Event should trigger:EVENT ID(PROD.POST) DSTRIG CICS.WORLD.WIDE ANYCLOSE JOB(USERWK) INVOKE 'PROD.ESP.PROCS(POST)'ENDDEF

DSTRIG Command: Define Data Set Triggers - Event Level

382

FTP transfer triggered objectThis object sends a message to a user when an FTP transfer to data set CYBER.DATA.SET completes from logged-on user aixuser on host AIXHOST to any local user with mainframe user ID prefix CYB. Because both the USER and the LOGON operands are specified and they specify different user IDs, the FTP trigger criteria can only be satisfied if the local FTP partner is the client. EVENT ID(MYEVENT)DSTRIG CYBER.DATA.SET HOST(AIXHOST) LOGON(aixuser) USER(CYB-)SEND 'APPLICATION RECEIVED FROM CLIENT' USER (BP)ENDDEF

Explicit data-set trigger notification using batchIn this example, STEP1 creates or updates member MEMBER1 in the data set PDS.DATA.SET.If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set PDS.DATA.SET(MEMBER1) has been created or updated.//DSTRIG01 JOB ...//*//STEP1 EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//SYSUT1 DD DISP=SHR,DSN=SEQ.DATA.SET//SYSUT2 DD DISP=OLD,DSN=PDS.DATA.SET(MEMBER1)//*//STEP2 EXEC PGM=CYBESDT1,COND=(0,LT),// PARM='DSNAME(PDS.DATA.SET(MEMBER1)) SUBSYSTEM(ESPS)'//STEPLIB DD DISP=SHR,DSN=CYBER.SSCPLINK

The following example triggers MYEVENT when the data set PDS.DATA.SET(MEMBER1) is created or updated:EVENT ID(MYEVENT)DSTRIG PDS.DATA.SET(MEMBER1) EXPLICITSEND 'APPLICATION RECEIVED FROM CLIENT' USER (BP)ENDDEF

Note: The data-set trigger, whether an Event or a workload object, must exist before you execute CYBESDT1.

383

Use of relative generation for GDGsThe following example shows the use of relative generations://DF072151 JOB ...//STEP1 EXEC PGM=CYBESDT1,// PARM='DSN(CYB1.PAYROLL.PAY7215(0)) SUB(ESPX)'//STEPLIB DD DISP=SHR,DSN=CYB2.QA.VX10.SSCPLINK//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//*//STEP2 EXEC PGM=CYBESDT1,// PARM='DSN(CYB1.PAYROLL.PAY7215(-3)) SUB(ESPX)'//STEPLIB DD DISP=SHR,DSN=CYB2.QA.VX10.SSCPLINK//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY

The following Event will send the message:ESPX.MYEVENT TRIGGERED -3 CYB1.PAYROLL.PAY7215 CYB1.PAYROLL.PAY7215.G0027V00 ESP(USER)

assuming that the data set CYB1.PAYROLL.PAY7215.G0030V00 was the current generation at the time the DFO72151 job was executed. Because the data-set trigger specifies the generation -3, it is only satisfied by step 2.EVENT ID(ESPX.MYEVENT)SEND '%ESPEVENT TRIGGERED %ESPTRMEM %ESPTRGDG %ESPTRDSN'DSTRIG CYB1.PAYROLL.PAY7215(-3) EXPLICITENDDEF

Note: The data-set trigger, whether an Event or a workload object, must exist before you execute CYBESDT1.

DSTRIG Statement: Define Data-set Triggers - Job Level

384

DSTRIG Statement: Define Data-set Triggers - Job Level

The DSTRIG statement defines a workload object associated with a z/OS data set trigger and is used in conjunction with the DSNAME statement to build a data set dependency at the job level into ESP Applications.

Syntax{DSTRIG|DT} objectname[.qualifier]

Usage notesThe DSTRIG statement defines a workload object that represents a z/OS data set trigger. Use the DSNAME statement to identify the requirements of the data set trigger. When these requirements are met, ESP completes the data set trigger object. Only one DSNAME statement can be used per data set trigger workload object. A data set trigger object can have a time dependency, or a predecessor dependency, or it can be defined on hold. Each of these conditions prevents the data set object from completing. You can manipulate (for example holding and resetting the time) a data set trigger object before it becomes ready (the dependencies are met). Once it is ready, the only action you can take against it is to complete it.Also refer to the JOB statement usage notes.

Related informationFor information on data set triggering at the job level, see the DSNAME statement. For information on Application, see the ESP Workload Manager User's Guide. For information on data set triggering at the Event level, see the ESP Workload Manager User's Guide. For information on displaying data set triggers, see the LDXE command. For information on displaying data sets being checked for closure, creation, or renaming, see the LDTE command.

Examples The following example builds a job-level data set trigger dependency: APPL PAYROLLJCLLIB 'CYB.JCL.CNTL' DSTRIG WAIT4.DLY DSNAME PROD.DAILY.ACCNTS RUN DAILY

385

REL PAYJOB2ENDJOBJOB PAYJOB2 RUN DAILYENDJOB

In the above example, WAIT4.DLY is used to build a job-level dependency with the closure of a newly created data set—PROD.DAILY.ACCNTS.The following example indicates a conditional data set trigger object that does not need to complete for the Application to complete: DSTRIG FILEA CONDITIONAL RUN DAILY DSNAME CYBER.WEEKLYENDJOB

The following example indicates a time requirement for a data set trigger object. If the data set is created prior to 6 pm, INPUT.DATA is not completed: DSTRIG INPUT.DATA RUN DAILY DELAYSUB 6PM DSNAME CYBER.BILLINGENDJOB

DSTRST Command: Control Data Set Triggers

386

DSTRST Command: Control Data Set Triggers

The DSTRST command is used to control data set triggering activity.

TypeGeneral command.

AuthorityYou require OPER authority to issue the DSTRST command.

SyntaxDSTRST{[SUSPEND|RESUME]} {[QUIESCE|RESTART]} [LOG|NOLOG]

Usage notesTo display the status of data set triggering, issue the DSTRST command with no operands.

Related informationFor information on data set triggering at the job level, see the DSTRIG or DSNAME statements.

Operand DescriptionSUSPEND Suspends data set triggering. All data set triggers are ignored.RESUME Indicates data set trigger processing is resumed. This is the opposite

of SUSPEND.QUIESCE Indicates data set triggering is quiesced. Data set triggers are

detected but no action is taken until this command is issued with the RESTART operand.

RESTART Indicates data set triggering is restarted, and all detected triggers processed. This is the opposite of QUIESCE.

Note: You cannot use this operand if the CYBESUDI utility is running. Refer to the ESP Workload Manager System Programmer’s Guide about the CYBESUDI utility.

LOG Activates data set trigger logging. A message is placed in the audit log each time a data set is closed, and notifies you which Event is triggered.

NOLOG Deactivates data set trigger logging.

387

For information on data set triggering at the Event level, see the ESP Workload Manager User’s Guide.

Examples Display data set trigger optionsIn the following example, data set trigger options are displayed:OPER DSTRST

Reactivate data set trigger after suspensionIn the following example, data set triggering is reactivated following a suspension. Data set trigger logging is also activated:OPER DSTRST RESUME LOG

DUEOUT Statement: Indicate Due Out Times

388

DUEOUT Statement: Indicate Due Out Times

The DUEOUT statement is used to indicate a due out time for a job from one or more stages in processing (pnodes). If the job has not completed the specified stage in processing by the due out time, the status field shows OVERDUE in the Consolidated Status Facility (CSF) display of the job.Note: Dueout situations are not noticed by ESP Workload Manager until the specified

stage of processing has started. For example, if a job has a dueout of 3am for executing, and start to execute at 7am, the dueout will be noticed only at 7am.

SyntaxDUEOUT pnodename time

Usage notesThe DUEOUT statement cannot be used outside the scope of a job statement.If the pnode specified is not found in the job’s tracking model definition or, a pnode specified on the pnodes element, the due out time and pnode are added to the end of the pnode list for this job. The most common pnodes used for a job in an ESP Application are INPUT and EXEC. The time operand can request any time relative to the time the Application was generated or DJC network submitted.

Operand Description

pnodename Indicates a pnode for which you want to specify a due out time. The pnodes are as follows:• INPUT—indicates the time when a job should start• EXEC—indicates the time when a job should complete

successfully. For links, tasks, and data set trigger objects, EXEC represents the time when it should be marked complete.

• OUTPUT—indicates the time when the job should be posted through output, if you are tracking through output.

• Manual—indicates manually defined processing stages.

Note: The pnodes used with the DUEOUT statement differ from CSF pnodes.

time The time the job is due out of the specified processing stage. This can be specified in any format but must resolve to a single date and time when the Application builds.

389

The DUEOUT statement overrides or sets the time by which this job should be posted out of the pnode named. If not posted by this time, a message is sent to the operator and the job is listed in the overdue queue display (DN OVERDUE command).ESP can also send a message or trigger an Event when a job becomes overdue from the INPUT or EXEC processing nodes using a NOTIFY statement.The DUEOUT statement propagates dueout times upstream, meaning to all predecessors of the job where a DUEOUT statement is specified. These dueout times are set relative to the average elapsed times according to the information obtained from ESP’s history file. Dueout times are not propagated from one Pnode to another. For example, if only DUEOUT EXEC is coded for a job which has not yet been submitted and that job is late, it will not be flagged as overdue until it begins executing.

Related informationFor information on flagging a job as late for submission, see the LATESUB statement.For information providing notification on job status, see the ESP Workload Manager Advanced User’s Guide.

Examples Flag job overdue at 3amIn the following example, if PAYJOB1 has not successfully completed the execution phase by 3 am, ESP flags it as overdue and the CSF shows OVERDUE in the Status field for the job. The 3 am time is relative to the scheduled time of the Event. In this example, if the Event is scheduled at 2 am, but is held up until 4 am, PAYJOB1 is overdue when the Application builds:JOB PAYJOB1 DUEOUT EXEC 3AMENDJOB

Flag late two hours after scheduled time of EventIn the following example, if WAIT4.TAPE is not marked complete two hours after the scheduled time of the Event, it is flagged as overdue and the CSF shows OVERDUE in the Status field for this task:JOB WAIT4.TAPE TASK DUEOUT EXEC NOW PLUS 2 HOURSENDJOB

DUEOUT Statement: Indicate Due Out Times

390

Flag overdue 30 minutes after Event trigger timeIn the following example, if PAYJOB2 has not completed successfully 30 minutes after the trigger time of the corresponding Event, it is flagged as overdue and the CSF shows OVERDUE in the Status field for the job:JOB PAYJOB2 DUEOUT EXEC REALNOW PLUS 30 MINUTESENDJOB

Flag overdue and issue AlertThe following DUEOUT and ALERT statements indicate the time when a job is flagged as overdue, and that a message is sent to a user:JOB PAYJOB3 NOTIFY OVERDUE USER(CYB01) DUEOUT EXEC 7AMENDJOB

In this example, if PAYJOB3 is not successfully complete by 7 am (and has started executing):• It is flagged as overdue and the CSF shows OVERDUE in the Status field for the

job• A message indicating that PAYJOB3 is overdue is sent to CYB01.Flag overdue and trigger Alert EventThe following DUEOUT and ALERT statements indicate the time when jobs within an Application are flagged as overdue, and that an Alert Event is triggered:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'NOTIFY OVERDUE ALERT(LATE)JOB PAYJOB4 DUEOUT INPUT 7AM RUN DAILY RELEASE PAYJOB5JOB PAYJOB5 DUEOUT EXEC 11AM RUN DAILYENDJOB

In this example, a globally-placed NOTIFY statement and job specific DUEOUT statements are used to:• Indicate that if any job within the PAYROLL Application becomes overdue, it is

flagged as overdue and the CSF shows OVERDUE in the Status field for the job• Trigger an Alert Event associated with an identifier of LATE.

391

This technique is useful if you want to provide notification of job status on all jobs within an Application, as the DUEOUT statement is not available outside the scope of a job statement.

DURATION Statement: Specify Durations

392

DURATION Statement: Specify Durations

The DURATION statement is used to tell ESP what duration to use when calculating Critical Path.

SyntaxDURATION value

Usage notesSituations may arise where you want to override historical elapsed times. For example, on the last day of the month, a job on the critical path may run longer than normal. Or maybe no historical information exists for a job on the critical path, because this is the first run of the job. In these situations, you can override historical elapsed time defaults (that ESP would normally use when calculating Critical Path) by using the DURATION statement to specify an estimated duration for the job.

Related informationFor information on how to enable Critical Path analysis, see the CRITPATH command.For information on specifying Critical Path analysis on individual Applications, see the CRITPATH Application statement.For information on Critical Path analysis, see the ESP Workload Manager User’s Guide.

Example Set elapsed time to 120 minutesThe following example sets the elapsed time estimate for job A to 120 (minutes) on the last day of the month:JOB A RUN WORKDAYS IF TODAY('LAST DAY OF MONTH') THEN DURATION 120ENDJOB

Operand Descriptionvalue Indicates the elapsed time estimate, in minutes, for a job.

393

EEARLYSUB Statement: Specify Changed Job Submission Times

The EARLYSUB statement is used to specify a job for delayed (or early) submission relative to the scheduled time of the Event. If the Event is not scheduled, the delayed submission time is relative to the time the Application is generated.

SyntaxEARLYSUB criteria

Usage notesUse the EARLYSUB statement within the scope of a JOB statement to request that a job not be submitted until a specified time, even though its predecessors have completed. This time parameter can request any date or time relative to the time the Application was scheduled or generated.Although less commonly used, the EARLYSUB statement can be placed outside the scope of any JOB statements (globally) to delay all jobs that are placed after that globally placed EARLYSUB statement. Using this method sets a delayed submission time for all jobs within the Application, except for those specifying the EARLYSUB statement within the scope of the JOB statement. Jobs that have their delayed submission time set as a result of a globally placed EARLYSUB statement can have those delayed submission times reset only on a job by job basis, and not as a group.Jobs that are inserted into active Applications do not have delayed submission time associated with them. If you want to insert a job into an active Application and associate a delayed submission time with that job, you must:1. Insert the job on hold using the IJ CSF line command2. Reset the job’s delayed submission time (Earliest submit time field)3. Release the job using the A CSF line command.

LimitationIf you trigger an Event with a time/date in the past, ESP does not honor EARLYSUB statements, except those that use the term REALNOW.

Related informationNote: The DELAYSUB and EARLYSUB statements perform the same function.For information on resetting time dependencies, see the ESP Workload Manager User’s Guide.

Operand Descriptioncriteria Schedule criteria that resolves to single date and time.

EARLYSUB Statement: Specify Changed Job Submission Times

394

For information on manipulating jobs within Application or subApplications, see the APPLJOB or AJ command.For information on specifying time dependencies, see the ESP Workload Manager User’s Guide.

Examples Do not submit before 9 pmIn the following example, PAYJOB1 has an earliest submission time of 9 pm relative to the time the PAYROLL Application was generated:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 EARLYSUB 9PM RUN WORKDAYSENDJOB

Do not submit before 9 pm weekdays, 6 pm weekendsIn the following example, PAYJOB2 has an earliest submission time of:• 9 pm on weekdays• 6 pm on weekends.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB2 EARLYSUB 9PM IF TODAY('WEEKEND') THEN EARLYSUB 6PM RUN DAILYENDJOB

Specify different submission timesIn the following example, all jobs in the PAYROLL Application have a delayed submission time of 4 pm, with the exception of PAYJOB6 that has a delayed submission time of 7 pm:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'EARLYSUB 4PMJOB PAYJOB3 RELEASE PAYJOB4ENDJOB JOB PAYJOB4 RELEASE PAYJOB5ENDJOBJOB PAYJOB5 RELEASE PAYJOB6

395

ENDJOBJOB PAYJOB6 EARLYSUB 4PMENDJOBSELECT (PAYJOB3,PAYJOB4,PAYJOB5,PAYJOB6)

10 minutes after scheduled timeThe following example sets the earliest submission time to 10 minutes after the scheduled time of the Event:EARLYSUB NOW PLUS 10 MINUTES

10 minutes after trigger timeThe following example sets the earliest submission time to 10 minutes after the trigger time of the Event:EARLYSUB REALNOW PLUS 10 MINUTES

Two workdays after scheduled timeThe following example sets the earliest submission time to 10 pm two workdays from the scheduled time of the Event:EARLYSUB 10PM TODAY PLUS 2 WORKDAYS

11 pm last workday of monthThe following example sets the earliest submission time to 11 pm on the last workday of the month, and to 9 pm on all other days submitted:IF TODAY('LAST WORKDAY OF MONTH') THEN - EARLYSUB 11PMELSE - EARLYSUB 9PM

ECHO Command: Echo Data

396

ECHO Command: Echo Data

The ECHO command is used to echo data back to your terminal. You can use it to test the symbols produced by GENTIME commands, symbolic variables, ESP control language (CLANG) statements and ESP built-in functions. Issue the ECHO command from page/line mode or from an ESP Procedure for testing purposes prior to permanently storing symbolic variables.

TypeGeneral command.

SyntaxECHO 'character string'

Usage notesThe ECHO command cannot be issued from a system console.

Related informationFor information on generating customized date and time variables, see the GENTIME command.For information on symbolic variables, see the ESP Workload Manager Advanced User’s Guide.For information on ESP built-in functions and ESP’s control language (CLANG), see the ESP Workload Manager User’s Guide.

Examples Display symbols in GENTIME commandThe following ECHO command displays some of the symbols produced by a GENTIME command: GENTIME XX FIRST WORKDAY OF MONTH STARTING TODAYECHO '%XXMM %XXDD %XXYY'

In the above example, a set of date and time variables is generated with the prefix XX, corresponding to the first workday of the month. The values of three of these variables are then echoed back to your terminal.

Operand Descriptioncharacter string Any character string. Enclosed in quotes.

397

Test value returnedIn the following example, if today is the last workday of the month, the character string 'TRUE' is echoed, else the string 'FALSE' is echoed back to your terminal:IF TODAY('LAST WORKDAY OF MONTH') THEN ECHO 'TRUE'ELSE ECHO 'FALSE'

EICLASS Command: Control Event Initiator Classes

398

EICLASS Command: Control Event Initiator Classes

The EICLASS command is used to control Event Initiator (EI) class definition and manipulation. This allows different Events to have their own dedicated set of Event initiators and provides a means of prioritizing Event and workload submission for installations that trigger multiple Events at the same time.

TypeGeneral command.

AuthorityYou require OPER authority to issue the EICLASS command.

SyntaxEICLASS [DISPLAY|SET|DELETE] [CLASS(nnn)] [MPL(nn)]

Usage notesYou define and manipulate Event initiator classes via initialization parameters and commands. For each class, a dedicated set of Event initiators is defined. EICLASS commands issued from Page mode are not retained across recycles of ESP. To retain EICLASS settings across recycles, insert the EICLASS commands in your initialization parameters.For class 0, no explicit definition is required. If class 0 is not defined, it is created automatically with an MPL of 1.

Operand Description

DISPLAY Displays the specified EI class settings. If DISPLAY, SET or DELETE are not specified, this is the default. This keyword has an alias of LIST.

SET Alter the specified EI class settings.

DELETE Delete the specified EI class. All TDRs queued to the deleted class are moved to class 0.

CLASS Indicates the target EI class. nnn must be a number from 0 to 255. If DELETE is specified, nnn cannot be 0. If SET or DELETE is specified, CLASS must be specified.

MPL Indicates the maximum number of initiators to be defined for the specified class. nn is a value from 0 to 16. If SET is specified, MPL must be specified. If DISPLAY is specified, MPL is ignored.

399

The Event initiator class is specified via the EICLASS keyword on the EVENT statement. There is no panel support for the EICLASS keyword.SAF authorization controls the use of Event initiator classes. For any non-zero class specified on an Event, a SAF security check will occur. The requester must have READ access to the resource EVENTINITCLASS.nnn resource to use the Event initiator class nnn.All Application generation for an Event is routed through the specified EICLASS. If an Event initiator is not available and one cannot be created, the Event waits until an initiator of the required class becomes available. If an Event is triggered for which there is no defined class, it is routed through class 0.The Application Manager also makes use of Event initiator classes for workload submission. Optionally, JOBEND and STEPEND monitors can make use of Event initiator classes if USERMOD 36 is active. USERMOD 36 allows JOBEND and STEPEND monitor Events to honor non-zero Event initiator class requests.The EICLASS keyword is available on both the LISTSCH and EVENT commands.

Related informationFor information on Event streaming and the EICLASS initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.For information on Events, see the ESP Workload Manager User’s Guide.For information on defining Events, see the EVENT command.

For information on displaying scheduled Events, see the LISTSCH command.For information on setting usermods, see the USERMOD initialization parameter in the ESP Workload Manager Installation and Configuration Guide.

Examples Define class 5 with one initiatorIn the following example, one Event initiator is set to class 5:EICLASS SET CLASS(5) MPL(1)

Display EI class settingsThe following example displays the EI class settings:OPER EICLASS

EICLASS Command: Control Event Initiator Classes

400

Define multiple classesIn the following example:• One event initiator is set to class 0• One event initiator is set to class 5• One event initiator is set to class 10.EICLASS SET CLASS(0) MPL(1)EICLASS SET CLASS(5) MPL(1)EICLASS SET CLASS(10) MPL(1)

Set and use EI classIn the following example, CYBER.PAYROLL uses Event initiator 99, is scheduled at 8 pm each workday, and invokes the PAYROLL ESP Procedure:EICLASS SET CLASS(99) MPL(1)

The following Event definition specifies an Event initiator class:EVENT ID(CYBER.PAYROLL) EICLASS(99)SCHEDULE 8PM WORKDAYSINVOKE 'CYBER.PROCLIB.CNTL(PAYROLL)'ENDDEF

401

EJB_JOB Statement: Start an EJB Job Definition (J2EE)

The EJB_JOB statement starts an EJB job definition in an Application.

ApplicabilityESP System Agents, Release 6, Service Pack 2 or higher.

SyntaxRefer to the JOB statement syntax.

Usage notesSB is the short form of EJB_JOB.To schedule EJB jobs, you must load the workload object module CYBESOSB. Load CYBESOSB with the WOBDEF command (page 1332) or with the WOBDEF initialization parameter.You must include the following J2EE statements within an EJB_JOB workload object:• “BEAN Statement: Specify the JNDI Name of the Stateless Session Bean (J2EE)”

on page 146• “INITIAL_CONTEXT Statement: Specify Initial Context Factory (J2EE)” on

page 674• “LOCATION Statement: Specify the Service Provider URL (J2EE)” on page 810• “METHOD Statement: Specify EJB Method to be Invoked Remotely” on

page 838You may include the following J2EE statements within an EJB_JOB workload object:• “DEST Statement: Specify Output Destination File (J2EE)” on page 313• “JNDIUSER Statement: Specify JNDI User ID (J2EE)” on page 696• “PARAMETER Statement: Specify the Method/Message Parameters (J2EE)” on

page 938Refer to the JOB statement (page 697) usage notes.

EJB_JOB Statement: Start an EJB Job Definition (J2EE)

402

ExamplesWebLogicIn this example, the CYBJK.SB job remotely invokes the reverse method of the CybEJBTestBean Stateless Session Bean.APPL TESTSBEJB_JOB CYBJK.SB HOLD RUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(java.lang.String) VALUE(A23)ENDJOB

WebSphereIn this example, the CYBJK.SB job remotely invokes the sort method of the CybEJBTestBean Stateless Session Bean.APPL TESTSBEJB_JOB CYBJK.SB RUN DAILY AGENT CYBUNIX BEAN CybEJBTestBean METHOD sort INITIAL_CONTEXT + com.ibm.websphere.naming.WsnInitialContextFactory JNDIUSER cyberuser LOCATION iiop://100.10.31.66:2809 DEST /export/home/user1/output1.bean PARAMETER TYPE(java.lang.String) VALUE(quick)ENDJOB

403

EJECT Command: Advance Output to New Page

The EJECT command is used to advance the output listing to a new page and is only valid when the output is directed to a data set. If the output is routed to a terminal, the EJECT command is ignored.

TypeGeneral command.

SyntaxEJECT

Usage notesThe EJECT command can be used in batch and with the HARDCOPY and DEFPRINT commands.

Example Print Events on separate pagesIn the following example, two commands are issued in batch to list Events. The EJECT command is used to list the payroll Events (CYBER.PAY-) and the manufacturing Events (CYBER.MFG-) on separate pages://ESPCMD JOB CYB3000,CLASS=A,MSGCLASS=X//STEP001 EXEC PGM=ESP,PARM='SUBSYS(E510)',REGION=4M//STEPLIB DD DSN=CYB2.ESP510Q.SSCPLINK,DISP=SHR//SYSPRINT DD DSN=CYBER.COMMAND.OUTPUT,DISP=SHR//SYSIN DD *LIST LEVEL(CYBER.PAY-)EJECTLIST LEVEL(CYBER.MFG-)/*

ELSE Statement: Specify Alternate Actions

404

ELSE Statement: Specify Alternate Actions

The ELSE statement is used in conjunction with an IF statement when the expression that follows the IF statement returns a false value.

TypeControl Language (CLANG) statement.

SyntaxELSE action

Usage notesWhen you use an IF statement, the expression that follows it must return a true or false value. You can use any number of nested IF statements.The THEN statement is used in conjunction with an IF statement when the expression that follows the IF statement returns a true value.If multiple action statements must be processed, you must begin and end compound action statements with the DO and ENDDO language elements.

If you do not include an ELSE statement after an expression returning a false value, ESP passes control to the next line. If an ELSE statement continues to another line, use a line continuation character (– or +). If there is no continuation character, ESP ignores the ELSE statement.

Related informationFor information on conditionally processing an instruction or group of instructions, see the IF and THEN statements.For information on using ESP’s Control Language, see the ESP Workload Manager User’s Guide.For information on advanced usage of ESP’s Control Language, see the ESP Workload Manager Advanced User’s Guide.

Operand DescriptionELSE Can only be used when IF and THEN statements have already been

specified. Defines the action to be taken when evaluation of an IF statement returns a false value. To specify multiple actions you must use the DO and ENDDO statements.

action Indicates the action that should be taken.

405

Examples Process different actions depending on dayIn the following example, ESP determines if the actual day is equal to Monday. If the evaluation of this expression is true, ESP sends a message to user CYB01 indicating that today is Monday. If the evaluation of this expression is false, ESP sends a message to user CYB01 indicating what day it is:IF %ESPADAY = 'MONDAY' THEN - SEND 'TODAY IS MONDAY' U(CYB01)ELSE - SEND 'TODAY IS %ESPADAY' U(CYB01)

Set symbolic variable valueIn the following example, a user-defined symbolic variable called 'FINANCIAL_YEAR' consists of two, two–digit year numbers, and is set as follows:• If the scheduled month is January, February, March or April, use last year

followed by this year

• For any other month, use current year followed by next year.IF ESPSMM<5 THEN DO GENTIME LAST TODAY LESS 1 YEAR FINANCIAL_YEAR='%LASTYY%ESPSYY'ENDDOELSE DO GENTIME NEXT TODAY PLUS 1 YEAR FINANCIAL_YEAR='%ESPSYY%NEXTYY'ENDDO

EMAILADDR Statement: Specify Email Addresses (PeopleSoft)

406

EMAILADDR Statement: Specify Email Addresses (PeopleSoft)

The EMAILADDR statement specifies the email addresses of recipients on a distribution list as specifies by the output destination type.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax EMAILADDR address |'address;address[;address;...]'

Usage notesThe complete list can be up to 256 characters in length.The EMAILADDR statement is used with the OUTDESTTYPE statement when either Email or Web are specified. For more information on OUTDESTTYPE, see “OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft)” on page 931.

ExampleEMAILADDR 'jsmith@company1.com;djones@company1.com'

Operand Descriptionaddress The e-mail address of a recipient on a distribution list. Separate

each address by a semicolon. Enclose a list of addresses in single quotes.

407

EMAILADDR Statement: Email SAP Spool File Upon ABAP Completion/Failure

The EMAILADDR statement emails a copy of the SAP spool file to the specified addresses upon ABAP completion or failure.

ApplicabilityESP Business Agents for SAP, Release 4 and higher.

SyntaxEMAILADDR address |'address,address[,address,...]'

Usage notesYou can also use the SAPEMAILADDR statement for the output of a job. For more information, see “SAPEMAILADDR Statement: Email SAP Spool File Upon Job Completion/Failure” on page 1121.Use the EMAILADDR statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the EMAILADDR statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleIn this example, jsmith and djones will receive spool output for the ABAP BTCTEST.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST EMAILADDR 'jsmith@company1.com,djones@company1.com'ENDJOB

Operand Descriptionaddress The e-mail address of a recipient on a distribution list. Separate each address

in the list with a semicolon. Enclose a list of addresses in single quotes.address is case sensitive and can be up to 256 valid SAP characters. If a list is specified, it cannot exceed 256 characters.

EMAILLOG Statement: Email Job Logs (PeopleSoft)

408

EMAILLOG Statement: Email Job Logs (PeopleSoft)

The EMAILLOG statement specifies whether to email job logs to a recipient on a distribution list as specified by the output destination type.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax EMAILLOG YES|NO

Usage notesThe EMAILLOG statement is used with the OUTDESTTYPE statement when either Email or Web are specified. For more information on OUTDESTTYPE, see “OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft)” on page 931.

Operand DescriptionYES Job logs are emailed as specified by the output destination type.NO No jobs logs are emailed.

409

EMAILSUBJECT Statement: Include Email Subject (PeopleSoft)

The EMAILSUBJECT statement specifies the inclusion of the email subject sent with the email to a recipient on a distribution list as specified by the output destination type.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax EMAILSUBJECT text

Usage notesThe EMAILSUBJECT statement is used with the statement OUTDESTTYPE when either Email or Web are specified. For more information on OUTDESTTYPE, see “OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft)” on page 931.

ExampleEMAILSUBJECT 'PeopleSoft Report Status'

Operand Descriptiontext The text of the subject field. If the subject includes a space or a

delimiter (such as a comma), you must enclose the text in single quotes.text can be up to 256 characters.

EMAILTEXT Statement: Include Email Body Text (PeopleSoft)

410

EMAILTEXT Statement: Include Email Body Text (PeopleSoft)

The EMAILTEXT statement specifies the inclusion of the e-mail body text with the email sent to a recipient on a distribution list as specified by the output destination type.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax EmailText text

Usage notesThe EMAILTEXT statement is used with the OUTDESTTYPE statement when either Email or Web are specified. For more information on OUTDESTTYPE, see “OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft)” on page 931.

ExampleEmailText 'The report is available for distribution'

Operand Descriptiontext The text of the email body text. If the email body contains a

space or a delimiter (such as a comma), you must enclose the text in single quotes. text can be up to 1024 characters.

411

EMAILWEBREPORT Statement: Include Web Report (PeopleSoft)

The EMAILWEBREPORT statement specifies whether the Web report is sent to a recipient on a distribution list as specified by the output destination type.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax EMAILWEBREPORT YES|NO

Usage notesThe EMAILWEBREPORT statement is used with the OUTDESTTYPE statement when Web is specified (see “OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft)” on page 931). For EMAILWEBREPORT to work, you must also include an EMAILADDR statement to specify the email addresses that need to receive the report.

ExampleSince the flag for EMAILWEBREPORT is set to yes in this example, the output will be sent to the email addresses specified in the statement EMAILADDR.PS_JOB EMAIL.TEST2 EmailAddr 'jeff@cybermation.com;alex@cybermation.com' EmailWebReport YES OUTDESTTYPE Web OUTDESTFORMAT PDF PSOPRID VP2 EmailSubject 'test report' EmailText 'test OUTDESTTYPE WEB with e-mail addresses' PROCESSNAME XRFWIN ProcessType Crystal RUN DAILYENDJOB

Operand DescriptionYES Web report is emailed to the recipients specified by the

EMAILADDR statement.NO No Web report is emailed.

ENCLOG Command: Display Additional Information About the Most Recent ESP Encore Request

412

ENCLOG Command: Display Additional Information About the Most Recent ESP Encore Request

Note: You need ESP Encore 3.1 to use this command.The ENCLOG command displays additional information concerning the most recent execution-history and restart-analysis requests.

TypeESP Encore command

SyntaxENCLOG

Usage notesYou can enter the ENCLOG command on the command line of an ESP Encore panel (Step Summary, Restart Action Summary, and so on).The output format is listed in the following table:Note: Lock times are in format yyyymmdd-hhmmss.

If you type EDIT on the command line of the ENCLOG display, you can find text or save the data. For details, see “Using ESP Workload Manager Page mode” in the ESP Workload Manager User's Guide.

Output DescriptionTOKEN Unique token assigned to the CPEENQ lockQNAME z/OS ENQ queue nameRNAME z/OS ENQ resource nameSCOPE z/OS ENQ scopeCTLTYPE z/OS ENQ control typeREQTYPE z/OS ENQ request typeUSER Id of the user on whose behalf a lock was obtainedLOCKED Time at which a lock was obtainedLASTLOCK Time at which a CPEENQ lock record was last updated.[EXPIRY] Time at which a CPEENQ lock is scheduled to expire.[UNLOCKED] Time at which a CPEENQ was unlocked.

413

ExampleSample output from the ENCLOG command:Serialization-control information:

TOKEN(1005F20040715124337#3) CSF JOBNAME(PAYROLL1) APPLICATION(PAYAPP)

GENERATION(19) QNAME(ESPCSF) RNAME(C'PAYROLL1 PAYAPP',X'00000013')

SCOPE(SYSTEMS) CTLTYPE(E) REQTYPE(USE) USER(PROD) LOCKED(20040715-124337)

LASTLOCK(20040715-124337) EXPIRY(20040715-134337)

ENCPARM Command: List All ENCPARM Commands in Effect

414

ENCPARM Command: List All ENCPARM Commands in Effect

ENCPARM lists all the ENCPARM commands issued in the initialization parameters and from page mode that are in effect for the current operating environment. The command listing is numbered according to the order the commands were issued.

TypeESP Encore command

AuthorityYou require OPER authority to issue the ENCPARM command.

SyntaxENCPARM

ExampleThis example shows the ENCPARM command entered in the operator’s console and the system response. The ESP subsystem name is GESP.F GESP,ENCPARM GESP7171I DEFAULT ENCPARMS 649 1. CLEANUP RESTART(YES) 2. MODIFY COMPRESS(YES) 3. PURGE JOB(PURGE002) KEEP(6) 4. PURGE JOB(A) AGE(1) 5. PURGE JOB(DF4-) AGE(30) KEEP(3)

This example shows the ENCPARM command entered in the page mode and the system response.oper encparm

1. MODIFY COMPRESS(YES)

415

ENCPARM ABENDER Command: Specify a Program That Abends on Behalf of Another Program

Some job steps run a program that abends if a prior step ends with a specified completion code. You can issue ABENDER to have ESP Encore ignore the abend program step and restart on the step that caused the abend program step to run.

TypeESP Encore command

SyntaxENCPARM ABENDER program_name

Usage notesYou can specify only one program name in an ENCPARM ABENDER command. However, you can specify several ENCPARM ABENDER commands in the initialization parameters. ENCPARM ABENDER is usually coded in the ESP Workload Manager initialization parameter data set, but can be overridden within an ESP Procedure using the ENCPARM ABENDER command.

ExampleIn the following example, STEP3 executes when STEP2 ends with a completion code of 16. Program ABEND806 in STEP3 abends on behalf of STEP2 and causes the remainder of the job to be flushed.//...

//STEP1 EXEC PGM=P1//STEP2 EXEC PGM=P2//STEP3 EXEC PGM=ABEND806,COND(16,NE,STEP2)//STEP4 EXEC PGM=P3//...

The following ENCPARM ABENDER command can be issued to avoid restarting the job in STEP3, the abend step, and restart in STEP2:ABENDER ABEND806

Operand Descriptionprogram_name The name of the program that abends on behalf of another

program.

ENCPARM AUTOREST Command: Recover Data Sets Automatically For a Job Restart

416

ENCPARM AUTOREST Command: Recover Data Sets Automatically For a Job Restart

The ENCPARM AUTOREST initialization parameter controls automatic recovery of data sets during job restart.During a job restart, ESP Encore can automatically recover:• Missing data sets to avoid DATA SET NOT FOUND errors. • Data sets that are updated by an abending step.

If a step is updating a data set and that step abends, ESP Encore considers the content of the data set to be invalid. ESP Encore then looks for an earlier step that creates the data set. If it finds such a step, it deletes the data set so that the earlier step can recreate it.

TypeESP Encore command

SyntaxENCPARM AUTOREST [YES|ALWAYS|NO [TEMPONLY([YES|NO]) [NEWPASS(YES|NO)]]]

417

Operand DescriptionYES ESP Encore recovers data sets if it is able to do so, otherwise

the restart continues only if specific conditions are met (see below). To recover data sets, ESP Encore must run any steps preceding the FROMSTEP that recreate or update the data sets. If these steps have changed from the previous run and the changes are disallowed (see “Limits to JCL changes before restarting a job” in the ESP Encore User’s Guide), ESP Encore does not rerun earlier steps and does not recover the missing data sets.

If ESP Encore is unable to recover missing data sets, then

• The restart continues if there are no “DATA SET NOT FOUND” errors or ENCPARM FORCE YES is specified.

The ESP Encore step completes normally and the restart continues to run.

• The ESP Encore step fails and the restart job is flushed if there is a “DATA SET NOT FOUND” error and ENCPARM FORCE YES is not specified.

The ESP Encore step fails and the restart job is flushed.ALWAYS ESP Encore must always be able to recover data sets,

otherwise the restart is abandoned. To recover data sets, ESP Encore must run any steps preceding the FROMSTEP that recreate or update the missing data sets. If these steps have changed from the previous run and the changes are disallowed (see “Limits to JCL changes before restarting a job” in the ESP Encore User’s Guide), ESP Encore flushes the restart job and returns a condition code of 40.

NO ESP Encore does not perform automatic recovery of data sets. However, it predicts DATA SET NOT FOUND errors, unless the FORCE YES initialization parameter has been specified.

TEMPONLY(YES) ESP Encore performs automatic recovery of temporary data sets only. This operand is ignored when you specify ENCPARM AUTOREST NO.

TEMPONLY(NO) ESP Encore performs automatic recovery of both permanent and temporary data sets.

ENCPARM AUTOREST Command: Recover Data Sets Automatically For a Job Restart

418

Usage notesThe following chart shows the relation between the ENCPARM AUTOREST operands and the types of data sets that are restored:

NEWPASS(YES) ESP Encore performs automatic recovery of data sets created with DISP=(NEW,PASS). This operand is ignored when you specify ENCPARM AUTOREST NO. When you specify NEWPASS(YES), you must also specify TEMPONLY(YES).

NEWPASS(NO) ESP Encore does not perform automatic recovery of data sets created with DISP=(NEW,PASS).

Operand Description

AUTOREST TEMPONLY NEWPASS

RestoresPermanent

data sets

Restores&&

data sets

RestoresNEW, PASS

data setsNO YES, NO YES, NO No No NoYES, ALWAYS NO YES, NO Yes Yes YesYES, ALWAYS YES NO No Yes NoYES, ALWAYS YES YES No Yes Yes

419

ExampleENCPARM AUTOREST is issued in the following segment of a procedure.

JOB AUTOR027 ENCPARM AUTOREST YES TEMPONLY(YES) NEWPASS(YES) RUN DAILY ...ENDJOB

According to the preceding ENCPARM AUTOREST settings, ESP Encore will perform automatic recovery only of temporary data sets, including those created with DISP=(NEW,PASS).The following job AUTOR027 is run with the preceding ENCPARM AUTOREST.

//AUTOR027 JOB (CYB1000),...//*//STEP010 EXEC PGM=IEBGENER,COND=(0,NE)//...//SYSUT2 DD DSN=&&TEMP1A,DISP=(NEW,KEEP), // SPACE=(10,5),UNIT=SYSDA,// DCB=(LRECL=80,BLKSIZE=80,RECFM=FB)//*//STEP020 EXEC PGM=PATEST,COND=(0,NE)//...//SYSUT2 DD DSN=PA.TEST.REST1A,DISP=(NEW,CATLG,KEEP),// SPACE=(10,5),UNIT=TEST,// DCB=(LRECL=80,BLKSIZE=80,RECFM=FB)//*//STEP030 EXEC PGM=IEBGENER,COND=(0,NE)//...//SYSUT2 DD DSN=&&TEMP1B,DISP=(NEW,PASS),// SPACE=(10,5),UNIT=SYSDA,

// DCB=(LRECL=80,BLKSIZE=80,RECFM=FB)//*//STEP040 EXEC PGM=IEBGENER,COND=(0,NE)//...//SYSUT2 DD DSN=PA.ENCQA.REST1A,DISP=(NEW,PASS,DELETE),// ...//*

ENCPARM AUTOREST Command: Recover Data Sets Automatically For a Job Restart

420

//STEP050 EXEC PGM=IEBGENER,COND=(0,NE)//...//SYSUT2 DD DSN=PA.ENCQA.REST1B,DISP=(NEW,PASS,DELETE), // ...//*//STEP060 EXEC PGM=CONDCODE,PARM=99999,COND=(0,NE)//*//STEP070 EXEC PGM=IEBGENER,COND=(0,NE)...

Job AUTOR027 abends in step STEP060. ESP Encore restarts at STEP060, but, because of the settings of AUTOREST, ESP Encore first restores temporary data sets as follows:• Data sets &&TEMP1A and &&TEMP1B are restored by rerunning STEP010 and

STEP030. This is done because TEMPONLY is set to YES.• Data sets PA.ENCQA.REST1A and PA.ENCQA.REST1B are restored by

rerunning STEP030 and STEP040. This is done because NEWPASS is set to YES.

ESP Encore does not restore the permanent data set, PA.TEST.REST1A, in STEP020.

421

ENCPARM BACKOUT Command: Control Whether a Data Set is Backed Out Under ESP Encore

The BACKOUT command controls whether a data set is backed out during a job backout or restart based on specified criteria.These criteria are used when a full job backout is being done (TYPE BACKOUT), and when dynamically allocated data sets are being backed out during a restart.

TypeESP Encore command.

SyntaxENCPARM BACKOUT MOVED(YES|NO) GDGONLY(YES|NO) EXCLUDED(YES|NO)

Usage notesThe MOVED(YES) operand is useful when data sets are frequently migrated by a product such as HSM (Hierarchical storage management), and recalled to a volume other than the original.The MOVED(NO) operand is useful in installations where different jobs create and delete the same data sets. Note: Do not confuse this initialization parameter with the BACKOUT operand for

command ENCPARM TYPE.

Operand DescriptionMOVED(YES) Back out any data set, even if it has been moved to a

different volume from the one on which it was created originally.

MOVED(NO) Back out data sets that still reside on the volume on which they were originally created.

GDGONLY(YES) Back out GDG generations that were created by the job being backed out.

GDGONLY(NO) Back out any data set that was created by the job.EXCLUDED(YES) Back out data sets residing on excluded volumes (see the

VOLUME initialization parameter).EXCLUDED(NO) Do not back out data sets residing on excluded volumes

(see the VOLUME initialization parameter).

ENCPARM BACKOUT Command: Control Whether a Data Set is Backed Out Under ESP Encore

422

Examples

The MOVED operandThe following example shows that ESP Encore deletes all data sets, even if they have been moved to a different volume. This is useful when data sets are frequently migrated with HSM and recalled to a different volume. ENCPARM BACKOUT MOVED(YES)

The EXCLUDED operandThe following example shows that ESP Encore performs the back out function for all data sets (including data sets residing on volume PROD01).ENCPARM BACKOUT EXCLUDED(YES)

ENCPARM VOLUME EXCLUDE(PROD01)

423

ENCPARM CLEANUP Command: Delete Data Sets That Will Be Allocated By a Restart Job

The CLEANUP initialization parameter deletes the data sets that will be allocated by this job. This prevents NOT CATLGD 2 and DUPLICATE NAME ON DASD errors.

TypeESP Encore command

SyntaxENCPARM CLEANUP [INITIAL(YES|NO)] [RESTART(YES|NO)] [DYNALLOC(YES|NO])]

Usage notesDuring a restart from the ESP Encore ISPF interface or ESP Workstation interface, ESP Encore looks at the JCL of the previous run.During a batch restart, ESP Encore looks at the JCL to be restarted, not the JCL of the previous run.

Operand DescriptionINITIAL(YES) ESP Encore performs data set cleanup during the initial run

of the job.INITIAL(NO) ESP Encore does not perform data set cleanup during the

initial run of the job.RESTART(YES) ESP Encore performs data set cleanup when the job is

restarted.RESTART(NO) ESP Encore does not perform data set cleanup when the

job is restarted.DYNALLOC(YES) ESP Encore deletes any data set that was dynamically

allocated and created by the previous run of the job, when a job is being restarted.

DYNALLOC(NO) ESP Encore does not delete data sets that were dynamically allocated and created by the previous run of the job, when a job is being restarted.

ENCPARM CLEANUP Command: Delete Data Sets That Will Be Allocated By a Restart Job

424

ExampleThe following command indicates that ESP Encore deletes all data sets (including dynamically allocated data sets), that were created during the initial run or before a restart run. During a restart run, ESP Encore only deletes dynamically allocated data sets that were created by steps that are being restarted. ENCPARM CLEANUP INITIAL(YES) RESTART(YES) DYNALLOC(YES)

425

ENCPARM COMMENT Command: Insert a Comment in the ESP Encore Job Run Report

Note: You need ESP Encore 3.1 to use this command.The COMMENT command is ignored by ESP Encore but the comment is included in the “INITIALIZATION PARAMETERS” section of Encore job run report for a batch job. For details, see “ESP Encore job run report” in the ESP Encore User’s Guide.

TypeESP Encore command

SyntaxENCPARM COMMENT comment_text

Usage notesThere are two ways to create a comment in the SYSIN DD of the ESP Encore step in your JCL:• Type a space in column 1 and then “/*” before your comment and “*/” after your

comment.• Issue the COMMENT command.

Example//SYSIN DD * /* HERE IS THE FIRST COMMENT. NOTE THE SPACE IN COLUMN 1. */COMMENT HERE IS THE SECOND COMMENT.[other ESP Encore statements]...

Operand Descriptioncomment_text The comment. If the comment exceeds 64 characters, it is

truncated.

ENCPARM CONDCODE Command: Specify the Condition Codes That the ESP Encore Job Step Produces

426

ENCPARM CONDCODE Command: Specify the Condition Codes That the ESP Encore Job Step Produces

The CONDCODE initialization parameter is used to establish customized condition codes for the ESP Encore step. Normally, the ESP Encore step finishes with a condition code of zero, unless errors have been predicted. Your JCL may need to distinguish between a restart and an initial run. You can have the ESP Encore step produce a specified condition code for an initial run and a specified condition code for a restart run.

TypeESP Encore command

SyntaxENCPARM CONDCODE [INITIAL(n1|0)] [RESTART(n2|0)] [FAIL(CC|ABEND)]

ExampleThe following initialization parameter specifies that the ESP Encore step ends with RC=24 instead of 0 for initial runs and RC=48 instead of 0 for restarts. It also specifies that ESP Encore issues a user abend when a pre-substitution, non-zero condition code is predicted.ENCPARM CONDCODE INITIAL(24) RESTART(48) FAIL(ABEND)

Operand DescriptionINITIAL(n1|0) The completion code that the ESP Encore step issues when a job

is run as TYPE INITIAL and there are no errors detected or predicted.

RESTART(n2|0) The completion code that the ESP Encore step issues when a job is run as TYPE RESTART and there are no errors detected or predicted.

FAIL(CC) ESP Encore completes with the appropriate non-zero condition code when an error is predicted or when an environmental problem occurs (see “ESP Encore condition codes” in the ESP Encore User’s Guide). FAIL(CC) is the default operand.

FAIL(ABEND) ESP Encore issues a user abend with the same value as the appropriate non-zero condition code. For example, if ESP Encore predicts a DATA SET NOT FOUND error, it completes with a U0146 abend (see “ESP Encore condition codes” in the ESP Encore User’s Guide).

427

ENCPARM DELETE Command: Undo an ENCPARM Command

You can undo the effect of an ENCPARM command issued in the initialization parameters and from page mode by deleting the command from the current operating environment. You can still reissue the command.

TypeESP Encore command

AuthorityYou require OPER authority to issue the ENCPARM DELETE command.

SyntaxENCPARM DELETE(nn)

ExampleFirst, issue the ENCPARM command with no operand to get a list of the ENCPARM commands and the order in which they were issued. In this case, ENCPARM is entered in the operator’s console. The ESP subsystem name is GESP.F GESP,ENCPARM GESP7171I DEFAULT ENCPARMS 1. CLEANUP RESTART(YES) 2. MODIFY COMPRESS(YES) 3. PURGE JOB(PURGE002) KEEP(6) 4. PURGE JOB(A) AGE(1) 5. PURGE JOB(DF4-) AGE(30) KEEP(3)

Now, the “PURGE JOB(PURGE002) KEEP(6)” command is deleted (the third command issued): F GESP,ENCPARM DELETE(3)GESP7170I ENCPARM DELETED

Now, all the existing commands are listed again:

Operand Descriptionnn The order in which the command was issued, for example,

1 for the first command issued, 2 for the second, and so on. Issue the ENCPARM command with no operand to list all ENCPARM commands issued along with the order they were issued.

ENCPARM DELETE Command: Undo an ENCPARM Command

428

F GESP,ENCPARMGESP7171I DEFAULT ENCPARMS 1. CLEANUP RESTART(YES) 2. MODIFY COMPRESS(YES) 3. PURGE JOB(A) AGE(1) 4. PURGE JOB(DF4-) AGE(30) KEEP(3)

429

ENCPARM DIAG Command: Produce All Diagnostic Sections of the ESP Encore Job Run Report

Causes the diagnostic sections of the report to be printed. The PRINT initialization parameter or command can be used to select or deselect specific sections of the report.

TypeESP Encore command

SyntaxENCPARM DIAG [YES|NO]

Usage notesDIAG prints all the diagnostics sections of the ESP Encore job run report. You can print selected sections of the report by issuing the PRINT command. For details, see “ESP Encore job run report" in the ESP Encore User’s Guide.

ExampleThe following command produces all the diagnostics sections of the report, except the MULTIVOLUME section.ENCPARM DIAG YESENCPARM PRINT MULTIVOL(NO)

Operand DescriptionYES Produce all sections of the diagnostic report unless a later

PRINT initialization parameter is issued to disable specific sections.

NO Do not produce the diagnostic report unless a later PRINT initialization parameter is issued to produce selected sections of the report.

ENCPARM EXCLUDE Command: Specify a Step to Exclude From a Job Restart

430

ENCPARM EXCLUDE Command: Specify a Step to Exclude From a Job Restart

You can specify job steps and proc steps that are not run in a job restart.

TypeESP Encore command

SyntaxENCPARM EXCLUDE [job_step|job_step.proc_step]

Usage notesENCPARM EXCLUDE is added to the ESP Encore step automatically by ESP Workload Manager if you select a job in CSF and exclude job steps from the restart.If you submit a restart job outside of ESP Workload Manager, you can specify EXCLUDE and other ENCPARM commands in the SYSIN DD statement of the ESP Encore step.ESP Encore supports the ENCPARM EXCLUDE command for job resubmission only (that is, when the ENCPARM TYPE RESTART command is specified.)You must specify one ENCPARM EXCLUDE command for each step you want to exclude. You cannot use wildcard characters or specify more than one step per initialization parameter.You can use the ENCPARM EXCLUDE command to exclude any step except the step specified in the ENCPARM FROMSTEP command or, if no ENCPARM FROMSTEP command is coded, the step that ESP Encore chooses as the initial step.ENCPARM EXCLUDE command that specify steps that do not exist or are outside the list of steps defined by the ENCPARM FROMSTEP command and ENCPARM TOSTEP command are ignored.

ExampleThis example shows the portion of JCL that specifies that the steps of job AUTOR001 with a job JOB57025 are to be rerun from step STEP005 to step STEP070 with steps STEP030 and STEP050 excluded.

Operand Descriptionjob_step The job step is excluded from the run.job_step.proc_step The proc_step within the job step is excluded from the run.

431

//STEP000 EXEC QX10ENC//ENCPARMS DD *SUBSYS ESPM ESPGROUP(ESP)TYPE RESTARTJOBNAME AUTOR001JOBID JOB57025FROMSTEP STEP005TOSTEP STEP070EXCLUDE STEP030EXCLUDE STEP050

ENCPARM FORCE Command: Run a Job Even If ESP Encore Predicts Errors

432

ENCPARM FORCE Command: Run a Job Even If ESP Encore Predicts Errors

ENCPARM FORCE causes ESP Encore to continue with a job run, even when there are errors predicted.

TypeESP Encore command

SyntaxENCPARM FORCE [YES|NO]

ExampleThe following ENCPARM FORCE initialization parameter causes ESP Encore allow the job to run even though errors were predicted. ENCPARM FORCE YES

Operand DescriptionYES The job runs despite errors predicted by ESP Encore. It runs

until it fails on the first predicted error.NO The job does not run if errors are predicted by ESP Encore.

433

ENCPARM FROMSTEP Command: Specify a Step From Which a Job Is Restarted

FROMSTEP is required only for jobs that are submitted outside of the ESP Workload Manager. When the ESP Workload Manager submits the job, it builds this command from the input entered on the resubmission panels.

TypeESP Encore command

SyntaxENCPARM FROMSTEP [stepname|stepname.procstep]|[FIRSTSTEP]

Usage notesENCPARM FROMSTEP is automatically added to the ESP Encore step by ESP Workload Manager if you select a job in CSF and then select job steps to run for the restart. You must add the command manually when you submit batch restart JCL.

ExampleIn this example, the job is restarted from STEP01:// EXEC CYBRMENC//SYSIN DD *SUBSYS ESPTYPE RJOBID JOB01234FROMSTEP STEP01

Operand Descriptionstepname The name of the first job step that should execute during a

restart.stepname.procstep The name of the first job step and proc step that should

execute during a restart.FIRSTSTEP Restart the job at the first step.

The name of the first step is extracted from the EXH data set record for the job.

ENCPARM GDGADJ Command: Specify How ESP Encore Processes Relative Generations For a Job Restart

434

ENCPARM GDGADJ Command: Specify How ESP Encore Processes Relative Generations For a Job Restart

Sometimes a relative generation reference does not refer to the correct generation when a job is restarted. You can use GDGADJ to control whether ESP Encore uses absolute generation numbers or relative generation numbers for the restart.

TypeESP Encore command

SyntaxENCPARM GDGADJ [YES|NO] MOVED([YES|NO])

Operand DescriptionYES During a restart, ESP Encore replaces a relative generation

number in the JCL with the absolute generation number stored in the EXH record for the job being restarted.

Note: If new generations are created by other jobs before the restart, the absolute generation replacements may not be valid for the restart job.

ESP Encore does not modify absolute generation numbers in the JCL.

NO ESP Encore uses the relative and absolute GDG generations currently in the JCL.

MOVED(YES) ESP Encore replaces a relative generation number in the JCL with its absolute equivalent, even if the absolute generation was moved to another volume (which implies that it may have been deleted and then recreated by another job).

Use this operand only with ENCPARM GDGADJ YES

MOVED(NO) ESP Encore replaces a relative generation number in the JCL with its absolute equivalent only if the absolute generation was not moved to another volume (which may happen if it was deleted and then recreated by another job).

Use this operand only with ENCPARM GDGADJ YES

435

Example 1The following ENCPARM command causes ESP Encore to replace relative generation numbers with their absolute equivalent, even if the generation data set has been moved to a different volume. ENCPARM GDGADJ YES MOVED(YES)

Example 2The following JCL is run://TESTJOB1 JOB (TEST1000),'TEST',MSGCLASS=X,CLASS=A//*//STEPA EXEC PGM=IEFBR14//*//STEPB EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//SYSUT1 DD DSN=TCY.TEST.GDG(0),DISP=SHR//SYSUT2 DD DSN=TCY.TEST.NEW,// DISP=(NEW,CATLG),// SPACE=(TRK,1),UNIT=SYSDA,// DCB=(LRECL=80,BLKSIZE=80,RECFM=FB)//*//STEPC EXEC PGM=DJCDEC

1. STEPA issues RC=0.2. STEPB reads in TCY.TEST.GDG.G0002V00, catalogs TCY.TEST.NEW, and

issues RC=0.3. STEPC abends with completion code SB37.4. TESTJOB2 runs and creates TCY.TEST.GDG.G0003V00.5. TESTJOB1 is restarted from STEPB.Here are the results with various GDGADJ settings:

GDGADJ MOVED Generation of TCY.TEST.GDG read by ESP Encore in STEPB

YES NO G0002V00YES YES G0002V00NO NO/YES G0003V00

ENCPARM GDGADJ Command: Specify How ESP Encore Processes Relative Generations For a Job Restart

436

Example 3:

The following JCL is run://JOB1 JOB (TEST1000),'TEST',MSGCLASS=X,CLASS=A//*//STEPA EXEC PGM=IEFBR14//*//STEPB EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//SYSUT1 DD DUMMY,// DCB=(LRECL=80,BLKSIZE=80,RECFM=FB)//SYSUT2 DD DSN=TCY.TEST.GDG(+1),// DISP=(NEW,CATLG),// SPACE=(TRK,1),UNIT=3480,// DCB=PCY.GDGMODEL.DATA//*//STEPC EXEC PGM=DJCDEC

1. STEPA issues RC=0.2. STEPB catalogs TCY.TEST.GDG.G0002V00, and issues RC=0.3. STEPC abends with completion code SB37.4. JOB2 runs and creates TCY.TEST.GDG.G0003V00.5. JOB3 runs, uncatalogs and deletes TCY.TEST.GDG.G0002V00, and creates and

catalogs the same generation on another volume.6. JOB1 is restarted from STEPB.Here are the results with various GDGADJ settings:

GDGADJ MOVED Generation of TCY.TEST.GDG created by ESP Encore in

STEPBYES NO G0004V00YES YES G0002V00NO NO/YES G0004V00

437

ENCPARM HONORCC Command: Control ESP Encore Condition Code Checks of Previous Job Runs

The HONORCC initialization parameter specifies whether ESP Encore considers condition codes from the previous run when restarting a job.

TypeESP Encore command

SyntaxENCPARM HONORCC [ALL|NONE]

ExampleIn the following JCL, if STEP1 ends with condition code 0, STEP3 is bypassed, otherwise, STEP3 is run.//STEP1 EXEC PGM=P1...//STEP2 EXEC PGM=P2...//STEP3 EXEC PGM=P3,COND=(0,EQ,STEP1)...

However, if STEP1 ends with condition code 0 and STEP2 abends, the restart from STEP2 proceeds as follows:• STEP3 is run if you issue HONORCC NONE.

In this case, the check of the STEP1 condition code is not done.• STEP3 is bypassed if you issue HONORCC ALL.

In this case, ESP Encore considers the condition codes from the previous run, so the condition code test in STEP3 is true.

Operand DescriptionALL During a job restart, ESP Encore considers condition codes from

the previous run. These are used in any condition code test in the restart.

NONE During a job restart, ESP Encore does not consider condition codes from the previous run.

ENCPARM IGNOREDS Command: Specify Data Sets to Ignore on Job Restart

438

ENCPARM IGNOREDS Command: Specify Data Sets to Ignore on Job Restart

The ENCPARM IGNOREDS command specifies the data sets that ESP Encore ignores when deciding which data sets to delete or recreate.For these data sets:• No errors are predicted.• No cleanup is done.• No auto-restoring is performed.• No security checking is performed.• No adjustment of GDGs is done.

TypeESP Encore command

SyntaxENCPARM IGNOREDS [DSNAME(-|dsname)] [JOBNAME(-|jobname)] [DDNAME(-|ddname)] [PGMNAME(-|pgmname)]

Usage notesYou may include wildcard characters in the value of the DSNAME, JOBNAME, DDNAME, and PGMNAME operands:

Operand DescriptionDSNAME( - |dsname) The data sets to be ignored. The default is a hyphen (-),

which matches any data set name.JOBNAME( - | jobname) The jobs referencing the data sets that you want ESP

Encore to ignore. The default is a hyphen (-), which matches data sets referenced by any job name.

DDNAME( - |ddname) The DD names for the data sets that you want ESP Encore to ignore. The default is a hyphen (-), which matches data sets referenced by any DD name.

PGMNAME( - | pgmname) The executing programs referencing the data sets that you want ESP Encore to ignore. The default is a hyphen (-), which matches data sets referenced by any program.

439

• An asterisk matches a single character.• A hyphen matches a string of characters.You can only use hyphens in the last character of a value. If you do not specify a value, the default is a hyphen (-), which matches any value.You can issue as many ENCPARM IGNOREDS commands as you want. ESP Encore compares the value of each operand with the corresponding value in the job. If all values match, the corresponding data set is ignored.Once a data set name matches an ENCPARM IGNOREDS command, that data set name is ignored everywhere it occurs in the job.

Example 1The following ENCPARM command causes ESP Encore to ignore any data set specified in an IMSLOG DD statement. ENCPARM IGNOREDS DDNAME(IMSLOG)

Example 2The following ENCPARM initialization parameter causes ESP Encore to ignore any data set if the following conditions apply:• The data set is referenced in a step executing program PAY287.• The data set is specified in DD statement SYSUT1.ENCPARM IGNOREDS PGMNAME(PAY287) DDNAME(SYSUT1)

ENCPARM JOBID Command: Specify the Job ID of the Job That Is Being Restarted by ESP Encore

440

ENCPARM JOBID Command: Specify the Job ID of the Job That Is Being Restarted by ESP Encore

JOBID is required only for jobs that are submitted outside of ESP Workload Manager. When ESP Workload Manager submits a job, it builds this command from the input entered on the resubmission panels.

TypeESP Encore command

SyntaxENCPARM JOBID JOBnnnnn|Jnnnnnnn

Usage notesJOBID is automatically added to the ESP Encore step by ESP Workload Manager. The command must be added manually when a restart job is not submitted by ESP Workload Manager.

ExampleIn this example, job number 01234 is restarted.// EXEC CYBRMENC//SYSIN DD *SUBSYS ESPTYPE RJOBID JOB01234

Operand DescriptionJOBnnnnn|Jnnnnnnn The job ID where nnnnn or nnnnnnn is the job number.

441

ENCPARM JOBNAME Command: Specify a Job to Be Backed Out or Whose EXH Record Is to Be Dumped

TypeESP Encore command

SyntaxENCPARM JOBNAME jobname

Usage notesJOBNAME is not intended for restarts. It is used when manually backing out or dumping a job.

Example// EXEC CYBRMENC//SYSIN DD *SUBSYS ESPTYPE BACKOUTJOBNAME JOBAJOBID JOB01234

Operand Descriptionjobname The name of the job to be backed out or whose EXH

Record is to be dumped.

ENCPARM MODE Command: Specify How a Job Is Processed by ESP Encore

442

ENCPARM MODE Command: Specify How a Job Is Processed by ESP Encore

TypeESP Encore command.

AuthorityYou require OPER authority to issue the ENCPARM MODE command.

SyntaxENCPARM MODE [NORMAL|SCAN|NULL]

Usage notesNote: MODE SCAN will cause the job to be marked as FAILED on the ESP

Workload Manager scoreboard (CSF).The ESP Encore ENCPARM MODE SCAN command operates differently from the z/OS JCL parameter TYPRUN=SCAN. With TYPRUN=SCAN, the job does not execute, data sets are not allocated, and there are no conflicts with other jobs. The MODE SCAN command executes the job, but only the ESP Encore step runs; the rest of the steps are flushed. Also, data sets can become enqueued, so there may be conflicts with other jobs running concurrently. For MODE SCAN, ESP Encore removes COND=ONLY and COND=EVEN from all job steps so that only the ESP Encore step runs and the remainder of the steps are flushed. This is done in case the ESP Encore steps abends.The MODE NULL command is used in jobs submitted outside of ESP Workload Manager. Insert the following step at the beginning of a standalone job:

Operand DescriptionNORMAL The job is executed.SCAN ESP Encore analyses the job, produces a report, and then

flushes the remainder of the job. You can use SCAN to check for errors prior to job submission.

NULL NULL is for jobs run outside of ESP Workload Manager. ESP Encore performs data set cleanup and runs the job. ESP Encore does not track the job in the EXH data set.

443

...

//ENCORE EXEC CYBRMENC//ENCPARMS DD *MODE NULL

/*

...

When ENCPARM MODE NULL is specified, ESP Encore performs data set cleanup but it does not track the job in the EXH data set. ESP Encore checks the disposition of the first occurrence of each data set and performs the cleanup as follows:• If a data set appears with DISP=(NEW,CATLG) in its first occurrence, and that

data set is cataloged, ESP Encore uncatalogs and deletes it.• If a data set appears with DISP=(NEW,KEEP) in its first occurrence, and a DASD

volume is specified in the DD statement, and the data set exists on that volume, ESP Encore scratches that data set.

You do not need to specify a subsystem ID when you use ENCPARM MODE NULL (see the SUBSYS command in the ESP Workload Manager Reference Guide).Other ESP Encore initialization parameter and commands may be specified along with MODE NULL, for example://ENCORE EXEC CYBRMENC//ENCPARMS DD *MODE NULLVOLUME EXCLUDE(RESPAK)IGNOREDS DSN(SYS1.-)

ESP Encore still predicts errors when ENCPARM MODE NULL is used. Issue the ENCPARM FORCE YES command to override error predictions.

ENCPARM MODIFY Command: Modify the Internal Processing of ESP Encore

444

ENCPARM MODIFY Command: Modify the Internal Processing of ESP Encore

Important: This command should only be used by your ESP Encore system programmer because it can affect all users on your ESP Encore system.

TypeESP Encore command

AuthorityYou require OPER authority to issue the ENCPARM MODIFY command.

SyntaxENCPARM MODIFY COMPRESS(YES|NO) DSEXIT(module) GDGENQ(YES|NO) PACING(15|nnn) USECSI(YES|NO)

Operand DescriptionCOMPRESS(YES|NO) Determines whether each EXH record is compressed

when a job completes its execution. Compressing the records saves space, but it requires extra CPU cycles to expand the records for a potential restart.

DSEXIT(module) Specifies an optional exit routine that ESP Encore invokes during the processing of each data set in a job. This user-defined exit routine can make decisions regarding ESP Encore’s handling of each data set in a job. For example, you can use DSEXIT to support complex naming conventions that are not supported by ESP Workload Manager wildcard capability.

GDGENQ(YES|NO) Determines whether ESP Encore enqueues on the GDG version of the data set that will be used during the restart. If you specify NO, the restart job can fail due to interference of other jobs in the system at the same time.

445

Usage note

This command is for maintenance personnel rather than ESP Encore users.Your system must use the integrated catalog facility (ICF) for ESP Encore to use CSI. If your system does not use ICF, ESP Encore uses the IDCAMS catalog access.

Examples

The following example indicates that compression should be performed for records written to the EXH data set:ENCPARM MODIFY COMPRESS(YES)

The following example selects the CSI catalog access:

F ESP,ENCPARM MODIFY USECSI(YES)

PACING(15|nnn) The number of records collected and passed to the EXH data set. The default value is 15. You can increase this value to improve EXH file performance. This, however, increases the number of records that can be lost in case of system problems.

The number of records collected and written to the EXH data set at one time. Records are collected and written once every second.

If you specify PACING(0), PACING(15) is used.

You can increase the default value to improve EXH data set performance. However, this increases the number of records that can be lost in case of system problems. The default value of 15 allows a maximum throughput of 54,000 EXH data set slots per hour (15 records times 3600 seconds/hour). This capacity is sufficient for most installations. In large installations, where the EXH data set traffic is high, you should increase this operand.

USECSI(YES|NO) Determines whether ESP Encore uses CSI (Catalog Search Interface) to search the system catalog. If you specify NO, ESP Encore uses the IDCAMS catalog access.

You can use this operand only if you issue the command as a z/OS MODIFY command.

Operand Description

ENCPARM PREDICT Command: Specify the Error Types That ESP Encore Predicts

446

ENCPARM PREDICT Command: Specify the Error Types That ESP Encore Predicts

The ENCPARM PREDICT command controls what type of errors ESP Encore predicts. By default, ESP Encore predicts all errors.

TypeESP Encore command

SyntaxENCPARM PREDICT error-type([YES|NO]) [error-type([YES|NO])...] [BYPASS(nnn)] [PROG(program)] [NOPROG(program)]

Operand Descriptionerror-type(YES) This type of error is predicted by ESP Encore. See

“Error-types” on page 447 for the list of valid error-type values.

error-type(NO) Specifies that this type of error is not predicted by ESP Encore.

BYPASS(nnn) ESP Encore treats nnn as a special condition code and does not predict DSNOTFOUND or NOTCATLG2 errors for these steps.

Note: If ESP Encore knows that a job step never executes, you do not need to code the BYPASS operand to avoid DSNOTFOUND or NOTCATLG2 errors.

PROG(program) ESP Encore does not predict DSNOTFOUND errors for all job steps after the first step that runs program.

NOPROG(program) Reverses the previous setting of the PROG(program) operand. This is useful in situations where PROG(program) is the global default.

447

Error-typesThe error-type must be one of the following:

Examples

Example - NOTCAT2 and SPACEWhen you issue the following ENCPARM command, ESP Encore does not predict NOTCAT2 and SPACE parameter errors. ENCPARM PREDICT NOTCAT2(NO) SPACE(NO)

Note: ESP Encore still predicts all other errors.

Error Type DescriptionDCB The DCB attributes specified in the DCB parameter are

inconsistent.DSNOTFOUND The data set name cannot be found in the catalog.DUPNAME The data set name already exists on the specified volume.GDGDEF The GDG base is not defined.GDGGEN The specified GDG generation does not exist.NOTCAT2 The data set cannot be cataloged because it is already

cataloged.NOTDEL8 The data set cannot be deleted because it does not exist.NOTONVOLUME The requested data set is not on the volume specified in

the DD statement or in the catalog.NOTUNCAT2 The data set cannot be uncataloged because it is not

cataloged.PGMNOTFOUND The specified program cannot be found.RDNR The job cannot be restarted from the specified

FROMSTEP since that step contains the RD=NR parameter.

SECURITY A security violation has been detected.SPACE The SPACE parameter is missing for a new data set on

DASD.UNIT A UNIT parameter is missing for a new data set with

VOLUME specified.

ENCPARM PREDICT Command: Specify the Error Types That ESP Encore Predicts

448

Example - BYPASSSometimes you may code a COND parameter as follows so that a step is bypassed:...//STEP5 EXEC PGM=ABC,COND=(999,NE)//SYSUT1 DD DSN=PCY.DATA,DISP=SHR...

If data set PCY.DATA in the preceding example does not exist, ESP Encore predicts a “data set not found” error, even though the step will not run. To prevent the error prediction, do the following:• Code the following ESP Encore initialization parameter:PREDICT BYPASS(999)

Note: You can also change the COND parameter to avoid the error prediction problem. In the following example, COND=(999,NE) is changed to COND=(0,LE):

...//STEP5 EXEC PGM=ABC,COND=(0,LE)//SYSUT1 DD DSN=PCY.DATA,DISP=SHR...

Because a step cannot have a completion code of less than 0, ESP Encore knows that STEP1 in the preceding example never executes. In this case, ESP Encore does not predict a “data set not found” error.

Example – PROG

In the following JCL, STEP01 executes IDCAMS to define a data set that STEP02 references. As a result ESP Encore predicts a DSNOTFOUND error because ESP Encore does not see the IDCAMS control commands://STEP01 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A //SYSIN DD * DEFINE CLUSTER - (NAME(A.B.C) - VOL(volume)) ... //* //STEP02 EXEC PGM=MYPGM //DD1 DD DSN=A.B.C,DISP=SHR

449

To stop ESP Encore from predicting DATA SET NOT FOUND errors for all steps after STEP02 (the IDCAMS step), code the following ESP Encore initialization parameter:PREDICT PROG(IDCAMS)

Example – NOPROG

PROG(ABC) is issued at the beginning of the following Application definition, so it applies to all jobs in the Application. NOPROG(ABC) is issued within the job definition for job P2, so it applies to that job only. Job P1 and P2 run program ABC.JCLLIB ‘PA.JCL.CNTL’APPL PAYROLLOPTIONS RESTARTSTEPENCPARM PREDICT PROG(ABC)

JOB P1 RUN DAILYENDJOB

JOB P2 ENCPARM PREDICT NOPROG(ABC) RUN DAILYENDJOB

JOB P3 RUN DAILYENDJOB

In this case:• ESP Encore does not predict any DSNOTFOUND errors in job P1 for all steps

after the one that runs program ABC.• ESP Encore predicts all DSNOTFOUND errors in job P2, even though it runs

program ABC.• ESP Encore predicts all DSNOTFOUND errors in job P3 because it does not run

program ABC.

ENCPARM PREVTIME Command: Specify a Reader-On (RDRON) Time to Find a Job in the EXH Data Set

450

ENCPARM PREVTIME Command: Specify a Reader-On (RDRON) Time to Find a Job in the EXH Data Set

The ENCPARM PREVTIME command is used when ESP Encore cannot discriminate between two or more jobs with the same job name and job number on the EXH data set. ESP Encore uses job name and job number to search for jobs on the EXH data set (for example, to process a RESTART command). When a duplicate job name and job number is found, the selection cannot be made and processing terminates with a severe error. You can avoid this by issuing the ENCPARM PREVTIME command to specify the time of the job you want to process. ESP Encore uses the time as an additional criterion to distinguish among the candidate jobs on the EXH data set.

TypeESP Encore command

SyntaxENCPARM PREVTIME yyyymmddhhmm

Usage notesIf ESP Encore finds more than one EXH record for the same job name and job number, it looks at the job start time on each EXH data set record and selects the first job that started at or after the time specified in the PREVTIME command.If a job is resubmitted from the CSF and if the job's reader-on time is still in the ESP Workload Manager tracking data, the PREVTIME command is automatically generated by ESP Workload Manager.ESP Encore version 3.1 and above automatically omit PREVTIME in the case of internodal jobs (a job submitted by an ESP Workload Manager subsystem and executed by another ESP Workload Manager subsystem on a different JES node). This is because of complexities related to potential differences in JES versions and time zones.To determine the correct time to specify when you manually issue the PREVTIME command:

Operand Descriptionyyyy Yearmm Monthdd Dayhh Hourmm Minute

451

• Look in the job log of the selected job to determine when this job started. The time is given in the format hh.mm.ss.

If you submit a restart job with no PREVTIME command and there is more than one EXH index entry with a matching job name and number, the ESP Encore step fails with return code 68 and the following message is written to the ESP Encore job run report:============SEVERE ERROR============ THE ESP ENCORE EXECUTION HISTORY FILE CONTAINS x MATCHING INDEX ENTRIES FOR THE JOB YOU ARE TRYING TO RESTART. STATE THE JOB NAME AND THE JOB NUMBER, AND USE THE 'PREVTIME YYYYMMDDHHMM' COMMAND TO SELECT THE FIRST JOB THAT RAN AFTER A SPECIFIC DATE AND TIME.

ExampleAssume the following jobs are on the EXH data set:

The following command selects the first job (Time = 11:51:30):ENCPARM PREVTIME 200305011151

The following command selects the second job (Time = 11:51:24):ENCPARM PREVTIME 200305081151

ESP Encore searches on the time in ENCPARM PREVTIME minus 90 seconds, so the fact that ENCPARM PREVTIME does not include seconds is irrelevant. If ENCPARM PREVTIME is specified, ESP Encore selects the first job that started after ENCPARM PREVTIME - 90 seconds. In this example, if ENCPARM PREVTIME is not specified, the Encore step terminates with condition code 68.

Job Name Job Number Date Time (HH:MM:SS)ABC 12345 20030501 11:51:30ABC 12345 20030508 11:51:24

ENCPARM PRINT Command: Select Sections of the ESP Encore Job Run Report to Print

452

ENCPARM PRINT Command: Select Sections of the ESP Encore Job Run Report to Print

ESP Encore normally only prints the job run report sections that are relevant to the current run. However, you can print other report sections by issuing the ENCPARM PRINT command. For details, see "ESP Encore job run report" in the ESP Encore User’s Guide.

TypeESP Encore command

SyntaxENCPARM PRINT section-name([YES|NO]) section-name([YES|NO]) ...

Operand Descriptionsection-name(YES|NO) Specifies whether a section of the ESP Encore job run

report is produced. The possible values for section-name are:

Value Report section printedSUBSYS Subsystem Information sectionRESTART Job Restart Summary sectionSUMMARY Job Summary sectionACTIONS Action Summary sectionSIOTJFCB SIOT/JFCB sectionCATALOG Catalog sectionMULTIVOL Multivolume data sets sectionVTOC VTOC sectionUNIT Unit Names sectionERRORS Errors sectionACTION2 Dump of Action Table sectionSMF SMF Records sectionHISTORY History of Previous Job sectionEXHFILE EXH File Statistics section

453

Usage notesThe ENCPARM DIAG YES command enables all the options listed under the ENCPARM PRINT command.Some Job Run report sections are not controlled by ENCPARM PRINT:• The Introductory section, Parameter Summary section, and Initialization

Parameters section are always produced.• The Severe Error section is only produced when a severe error occurs. For

example, an ESP Encore condition code 44 (a job's EXH record is no longer in the EXH data set) causes the Severe Error section to be produced.

ExampleThe following command adds the HISTORY section to the ESP Encore report.ENCPARM PRINT HISTORY(YES)

ENCPARM PURGE Command: Configure Automatic Purge of ESP Encore Job History Records

454

ENCPARM PURGE Command: Configure Automatic Purge of ESP Encore Job History Records

ENCPARM PURGE can also be specified in the initialization parameter data set.The ENCPARM PURGE command sets conditions under which ESP Encore automatically purges records from the EXH data set before creating a new record. Regardless of whether you use ENCPARM PURGE, run the CYBRMPRG utility on a regular basis to maintain your EXH data set.Important: You can only enter the ENCPARM PURGE command in the

initialization parameters, or in page mode. If you enter it at the application level or job level, it is ignored.

Important: You can enter more than one ENCPARM PURGE command. The commands are kept in the same sequence as they are entered. The first ENCPARM PURGE command that matches the job name is executed. Once the match is found, the remaining ENCPARM PURGE commands are skipped. To achieve the desired results, enter ENCPARM PURGE commands in the order of the most specific to the most generic.

An ENCPARM PURGE command remains in effect only during the lifetime of the ESP Workload Manager's address space.

TypeESP Encore command

SyntaxENCPARM PURGE JOB(job-mask) [AGE(days)] [INCOMPLETEAGE(days)] [KEEP(number)] [INCOMPLETEKEEP(number)]

Operand DescriptionJOB(job-mask) Specifies a job name mask string that may contain

wildcard characters.AGE(days) Specifies the number of days that a complete job

group should be kept on the EXH data set if its name matches the mask.

INCOMPLETEAGE(days) Specifies the number of days that an incomplete job group should be kept on the EXH data set if its name matches the mask.

455

Usage notes

Job groupsA job group is composed of an initial job and all restarted jobs stemming from that initial job. A complete job group is one in which the most recent job has executed successfully, otherwise, it is an incomplete job group. The age of the most recent member of a job group determines the age of the whole job group.

Listing Jobs and default purge values• You can list the jobs in the index of an EXH data set by running the CYBRMLST

utility.• You can see what will be purged by running the CYBRMPRG utility with

TEST=Y.• You can list the default purge values that are stored on the EXH data set by

running the CYBRMQRY utility.

Setting the default automatic job purge valuesIf you do not specify values for the optional operands, ESP Encore use the default values taken from the EXH data set.• You can set the default purge values for the automatic job purge mechanism when

you allocate the EXH data set with the CYBRMALC utility.• You can change the default automatic job purge values with the CYBRMKEP

utility.

Automatic job purging

Important: The automatic purging of jobs takes place gradually as new jobs that match the purge initialization parameters are run.

KEEP(number) Specifies the maximum number of complete job groups that must remain in the EXH data set.

INCOMPLETEKEEP(number) Specifies the maximum number of incomplete job groups that must remain in the EXH data set.

Operand Description

ENCPARM PURGE Command: Configure Automatic Purge of ESP Encore Job History Records

456

A completed job group is purged when one of the following conditions occurs:• The most recent job in the group is older than AGE.• The completed job group is the oldest job group in the EXH data set and a new job

group is created that exceeds the KEEP limit.An incomplete job group is purged when one of the following conditions occurs:• The most recent job in the group is older than INCOMPLETEAGE. • The incomplete job group is the oldest job group in the EXH data set and a new

job group is created that exceeds the INCOMPLETEKEEP limit.The automatic purging of jobs takes place gradually as new jobs that match the purge command are run.

Purging jobs manuallyYou can immediately purge jobs from the EXH data set with the CYBRMPRG utility. Use the CYBRMPRG utility on a regular basis to maintain your EXH data set.

ExampleIn this example, the default purge criteria stored on the EXH data set are:AGE=3INCOMPLETEAGE=10KEEP=4INCOMPLETEKEEP=6

PURGE is used to modify the default purge values:ENCPARM PURGE JOB(A-) AGE(14)ENCPARM PURGE JOB(B-) INCOMPLETEAGE(12)ENCPARM PURGE JOB(-) AGE(4) INCOMPLETAGE(6) KEEP(3)INCOMPLETEKEEP(5)

The default purge values are modified as follows:

Jobs Purge valuesName starting with A AGE=14

INCOMPLETEAGE=10KEEP=4INCOMPLETEKEEP=6

Name starting with B AGE=3INCOMPLETEAGE=12KEEP=4INCOMPLETEKEEP=6

457

All other job names AGE=4INCOMPLETEAGE=6KEEP=3INCOMPLETEKEEP=5

Jobs Purge values

ENCPARM QUIESCE Command: Quiesce ESP Encore

458

ENCPARM QUIESCE Command: Quiesce ESP Encore

Quiescing ESP Encore:• Suspends ESP Encore operation.• Deallocates the EXH data set from the ESP Workload Manager subsystem address

space.• Stops the recording of tracking information to the EXH data set.Job tracking continues, but data is stored in the Auxiliary Address Space until the EXH data set is available again.Note: You must issue ENCPARM QUIESCE for the master and all proxies.

TypeESP Encore command

AuthorityYou require OPER authority to issue the ENCPARM QUIESCE command.

SyntaxENCPARM QUIESCE

Usage notesThe ENCPARM QUIESCE command is used in situations such as the following:• When you need exclusive control (DISP=OLD) of the EXH data set.• Before you issue the AUX_AS CANCEL command to stop the Auxiliary Address

Space or the AUX_AS BOUNCE command to stop and then start the Auxiliary Address Space.

ExampleThis example illustrates the effect of issuing the ENCPARM QUIESCE command.The ENCPARM STATUS command is issued to list the status of ESP Encore.oper encparm statusESP ENCORE COMPRESSING ACTIVE

The ENCPARM QUIESCE command is issued.oper encparm quiesceESP7103I OK

The ENCPARM STATUS command is issued again to list the status of ESP Encore after the quiesce.oper encparm statusESP ENCORE COMPRESSING QUIESCED

459

ENCPARM RESTART Command: Restart ESP Encore

Restarting ESP Encore:• Allocates the EXH data set to the ESP Workload Manager subsystem address

space.• Resumes the recording of tracking information to the EXH data set.• Drains tracking data that was accumulated in the Auxiliary Address Space and

writes the data to the EXH data set.Note: You must issue ENCPARM RESTART for the master and all proxies.

TypeESP Encore command

AuthorityYou require OPER authority to issue the ENCPARM RESTART command.

SyntaxENCPARM RESTART

Usage notesThe ENCPARM RESTART command is used in situations such as the following:• When you no longer need exclusive control (DISP=OLD) of the EXH data set.• After you issue the AUX_AS START or AUX_AS BOUNCE command to start

the Auxiliary Address Space.• After ESP Workload Manager or ESP Encore were quiesced because the EXH

data set was full

ExampleThis example illustrates the effect of issuing the ENCPARM RESTART command.The ENCPARM STATUS command is issued to list the status of ESP Encore.oper encparm statusESP ENCORE COMPRESSING QUIESCED

The ENCPARM RESTART command is issued.oper encparm restartESP7103I OK

ENCPARM RESTART Command: Restart ESP Encore

460

The ENCPARM STATUS command is issued again to list the status of ESP Encore after the restart.oper encparm statusESP ENCORE COMPRESSING ACTIVE

461

ENCPARM STATUS Command: List the Status of ESP Encore

TypeESP Encore command

AuthorityYou require OPER authority to issue the ENCPARM STATUS command.

SyntaxENCPARM STATUS

Exampleoper encparm statusESP ENCORE COMPRESSING QUIESCED

ENCPARM SUBSYS Command: Specify the Subsystem Identifier for a Job Processed by ESP Encore

462

ENCPARM SUBSYS Command: Specify the Subsystem Identifier for a Job Processed by ESP Encore

When you submit a job processed by ESP Encore, you can issue ENCPARM SUBSYS to specify the subsystem identifier of the ESP Workload Manager system under which the job has been submitted.One of the following criteria must be met for a match:• The ESPGROUP operand of the ENCPARM SUBSYS command must match the

ESPGROUP command setting in the ESP Workload Manager initialization parameter data set.

• The subname (subsystem name) operand of the ENCPARM SUBSYS command must match the SUBSYS command setting in the ESP Workload Manager initialization parameter data set.

TypeESP Encore command

SyntaxENCPARM SUBSYS subname [ESPGROUP(espgroup)| PLEXID(espgroup)| GROUPNAME(espgroup)]

Operand Descriptionsubname A subsystem name that ESP Encore uses to search for

an ESP Workload Manager subsystem. The search is successful if subname matches an ESP Workload Manager’s SUBSYS initialization parameter.

ESP Encore uses this identifier to specify the ESP Workload Manager subsystem with which the batch job is to communicate if:ESPGROUP is omitted.–or–The ESP Encore step cannot use the ESPGROUP to find a selectable ESP Workload Manager subsystem.

463

Usage notesThe ESP Encore step of a batch job uses the information provided on the SUBSYS statement to search for and select the ESP Workload Manager subsystem that stores the job's execution history data to the EXH data set.The ESP Encore step performs up to three searches in the following order:1. ESPGROUP2. The subsystem identifier3. The subsystem maskThe ESP Encore step uses only the SUBSYS parameters you provide and stops searching when a search is successful.If ESP Encore encounters an ESP Workload Manager subsystem that does not capture SMF data and does not have an active auxiliary address space, ESP Encore rejects it and continues searching. ESP Encore also rejects ESP Workload Manager subsystems whose JESNAME initialization parameter differs from the name of the JES subsystem executing the batch job.When ESPGROUP is specified, the ESP Encore step does not select any ESP subsystem if either of the following conditions apply:• Two or more ESP Workload Manager subsystems executing under the same JES

subsystem are selectable.• Two or more ESP Workload Manager subsystems have the same JESNAME

initialization parameter.When an ESP Workload Manager submits a job tracked by ESP Encore, it automatically adds a SUBSYS statement to the SYSIN of the ESP Encore step. The ESP Workload Manager SUBSYS initialization parameter is used to identify the subsystem and, if the ESP Workload Manager subsystem has no ESPGROUP initialization statement, the subsystem identifier is used for ESPGROUP.

ESPGROUP|PLEXID|GROUPNAME(espgroup)

A group name that ESP Encore uses to search for an ESP Workload Manager subsystem. The search is successful if espgroup matches an ESP Workload Manager’s ESPGROUP initialization parameter.

ESPGROUP, PLEXID, and GROUPNAME are synonymous, but ESPGROUP is preferred.

Operand Description

ENCPARM SUBSYS Command: Specify the Subsystem Identifier for a Job Processed by ESP Encore

464

For internodal jobs, the remote ESP Workload Manager tracks the job and passes tracking information back to the local ESP Workload Manager subsystem. The remote ESP Encore records the job's execution history in the remote EXH data set. The ESPGROUP of the local ESP Workload Manager that submits the job must match the ESPGROUP of the remote ESP Workload Manager, otherwise the ESP Encore step cannot select an ESP Workload Manager.For example, an ESP Workload Manager on SYSA with ESPGROUP "G1" submits a batch job that is routed to SYSB where it executes. The batch job's ESP Encore step searches for an ESP Workload Manager on SYSB with ESPGROUP "G1". To succeed, the ESP Encore step must find an ESP Workload Manager with:• The required ESPGROUP• SMFINT ON• The ability to update the EXH data set

ExamplesIn the following JCL, SUBSYS is automatically added to the ESP Encore step by ESP Workload Manager://STEP01 EXEC CYBRMENC//SYSIN DD *SUBSYS ESP ESPGROUP(PAYROLL)

If the SUBSYS ID is ESP, and the ESP Workload Manager ESPGROUP Initialization Parameter is GROUP1, the following SUBSYS command is added to the ESP Encore step automatically by ESP Workload Manager://STEP01 EXEC CYBRMENC//SYSIN DD *SUBSYS ESP ESPGROUP(GROUP1)

If a batch job is submitted manually, ESPGROUP may be omitted to force ESP Encore to choose the ESP Workload Manager that has the specified subsystem identifier.//STEP01 EXEC CYBRMENC//SYSIN DD *SUBSYS ESP

465

You can specify MATCH(mask) in manually-submitted batch jobs in one of the following ways:• Add a statement such as the following to the ESP Workload Manager ESPPARM

data set:ENCPARM SUBSYS subname MATCH(subname_mask)

The preceding statement applies to all jobs submitted by the ESP Workload Manager.

• In the job resubmission panel, type Y beside “Do you wish to enter ENCPARM statements?” and on the next panel, enter the SUBSYS statement in the following form:SUBSYS subname MATCH(subname_mask)

The preceding statement applies only to the job being submitted.

ENCPARM TAPESCR Command: Request a Tape Scratch From a TMS

466

ENCPARM TAPESCR Command: Request a Tape Scratch From a TMS

Specifies how ESP Encore scratches tape data sets. Note: This applies only if you use a tape management system.

TypeESP Encore command

SyntaxENCPARM TAPESCR PROG(pgmname)| COMMAND('command_text') CONSOLE(consname) CART(token)

Usage notes

PROG and COMMAND are mutually exclusive. CONSOLE and CART should only be specified if COMMAND is specified.

Operand DescriptionPROG(pgmname) The name of the tape management program that

ESP Encore calls to scratch the tape data set.COMMAND('command_text') The text of an operator command that ESP Encore

issues to scratch a tape data set. The maximum length of the command is 126 characters. If your command text is longer than 126 characters, use a tape scratch program and invoke it with TAPESCR PROG(progname)

CONSOLE(consname) The name of a console from which the command is issued. Specify CONSOLE only when you specify the COMMAND operand. ESP Encore does not issue an error if you specify CONSOLE without COMMAND.

CART(token) The response token that is associated with the command. Specify CART only when you specify the COMMAND operand. ESP Encore does not issue an error if you specify CART without COMMAND.

467

If no tape management system is installed, ESP Encore only uncatalogs the tape data set using the IDCAMS NOSCR command. However, if a tape management system is present, then ESP Encore also executes the interface program named in pgmname or issues the command in command_text.

Using symbolic variables in a tape scratch command

You can include the following symbolic variables in a tape scratch command. Symbolic variables are replaced by their assigned values before the command is issued.• &DSN - the name of a data set to be scratched• &VOL - the list of VOLSERs that store the data set• &EXPDT- data set expiry date• &RETPD - data set retention period• &TYPE - type of ESP Encore run. I-initial run, B-backout run, R-restart runKeep in mind the IBM length restriction of 126 characters for the longest operator command. If your installation uses very large multi-volume data sets, the VOLSER list substitution may exceed the legal operator command length. In this situation, use a tape scratch program and invoke it with TAPESCR PROG(progname).You can list the tape scratch command before and after the symbolic variable substitution processing by issuing command TRACE CYBRM577. Remove the TRACE CYBRM577 command for production, since it degrades performance.

Using a tape scratch program

A tape scratch program is attached, that is, it runs as an operating system subtask and its parameter list is in the standard z/OS subroutine parameter list format. The program in invoked in the AMODE (addressing mode) that was specified during its link-edit run.The following table describes the parameters passed by ESP Encore to any program specified in ENCPARM TAPESCR.

Parameter DescriptionDSN Data set name. It is up to 44 characters long.NUM_VOLS Number of volumes this data set is stored on. It is

a binary full word counter. The maximum is 255 volumes (the operating system limit).

VOL_SER Array of VOLSERs. Each array entry is 6 bytes long and contains a volume serial number in character format.

ENCPARM TAPESCR Command: Request a Tape Scratch From a TMS

468

The following is the z/OS standard parameter list format:

Example - Tape scratch program

In this example, ESP Encore invokes a program called MYTAPSCR whenever a tape data set should be scratched.

EXP_DT Data set expiry date. The date is in the Julian date format YYDDD. It is a 3 byte field. The first byte contains a binary representation of YY, the next two bytes contain the binary representation of DDD. For example YYDDD=99365 is stored as X'63016D'.

RETPD Data set retention period. The date is in the Julian date format YYDDD. It is a 3 byte field. The first byte contains a binary representation of YY, the next two bytes contain the binary representation of DDD.

FLAGS A two-byte field that encodes ESP Encore run type as follows: • X'8000' – initial run• X'4000' – restart run• X'2000' – backout run• X'1000' – cleanup run

Parameter Description

Register 1

DSNA(Parm1)

A(Parm6)

A(Parm5)

A(Parm4)

A(Parm3)

A(Parm2) NUM_VOLS

FLAGS

RETPD

EXP_DT

Array of VOLSERs

VOLSER1

VOLSER255

VOLSER2

469

ENCPARM TAPESCR PROG(MYTAPSCR)

In this example, TAPESCR PROG attaches the program MYTAPSCR, creating a system subtask. The parameter list described previously is passed to MYTAPSCR. The program is invoked in the AMODE that was specified during its link-edit run.

Example - Symbolic parameters in TAPESCR COMMAND

In this example, a TAPESCR initialization parameter issues a START command for a started task called SCRTAP. Parameters P1 and P2 are passed to the started task.TAPESCR COMMAND(‘S SCRTAP,P1=&DSN,P2=&VOL’)

Assuming symbolic parameter &DSN=TAP1 and &VOL=SER=(TAPE01,TAPE02), the command appears as follows after the values are substituted:S SCRTAP,P1=TAP1,P2=’TAPE01,TAPE02’

The started task that is invoked must have a matching definition of parameters://SCRTAP PROC P1='NODSN',P2='NOVOL'//STEP1 EXEC SCRTAP1,PARM=’&P1,&P2’

If the parameters do not match, you may see the following JCL card that will cause a JCL error. The started task will fail.//IEFPROC.IEFRDER DD …a list of your mismatched parameters…

Please note that in this example the parameters passed to the program SCRTAP1 come from the invocation line. The parameters from the invocation line (and also from the JCL PARM field) are in the varying string format as described in the IBM documentation:

In the example LL = 18 (binary halfword) followed by DATA = TAP1,TAPE01,TAPE02 in the character format. Note that the single quotes surrounding the list of parameter P2 are removed by the operating system, so program SCRTAP1 does not see them.

LL DATA

ENCPARM TOSTEP Command: Specify a Step To Which a Job Runs When It Is Restarted

470

ENCPARM TOSTEP Command: Specify a Step To Which a Job Runs When It Is Restarted

The TOSTEP command defines the last step to be executed when a range of steps is defined for a restart job.This command is required only for jobs that are submitted outside of the ESP Workload Manager. When the ESP Workload Manager submits the job, it builds this command from the input entered on the resubmission panels.

TypeESP Encore command

SyntaxENCPARM TOSTEP stepname|stepname.procstep

Usage notesTOSTEP is automatically added to the ESP Encore step by ESP Workload Manager. The command must be added manually when a restart job is not submitted by ESP Workload Manager.

ExampleIn this example the execution stops after STEP05 runs:...

//ENCSTEP EXEC CYBRMENC//SYSIN DD *SUBSYS ESP ESPGROUP(PAYROLL)TYPE RJOBID JOB01234FROMSTEP STEP01TOSTEP STEP05

...

Operand Descriptionstepname The name of the last job step that should execute during a

restart.stepname.procstep The name of the last job step and proc step that should

execute during a restart.

471

ENCPARM TRACE Command: Specify Modules to Be Traced

Specifies the name or prefix of one or more modules to be traced by ESP Encore.

TypeESP Encore command

SyntaxENCPARM TRACE (modulename1, modulename2 ...)[VERBOSE|NVERBOSE]

Usage notesThis ENCPARM command causes trace information to be printed amongst the normal reports produced by the ESP Encore step.Since tracing degrades performance, you should use it for diagnostics purposes only. Usually Cybermation support asks you to run a trace.

ExampleIn this example, ESP Encore produces trace information for module CYBRM574 and CYBRM402.TRACE (CYBRM574,CYBRM402)

In this example, verbose trace information for all ESP Encore modules is generated.TRACE CYBRM VERBOSE

Operand Descriptionmodule_name A module or a set of modules to be traced by ESP Encore. If the

name is less than eight characters long, all modules beginning with that prefix are traced. Parentheses are optional if only one module is traced.

VERBOSE Produce any additional trace messages for ESP Encore programs that have tracing enabled. Verbose tracing requires additional processing, so use it only if it is requested by Cybermation support.

NVERBOSE Disable verbose tracing. See the VERBOSE operand.

ENCPARM TYPE Command: Specify the Type of Processing That ESP Encore Does

472

ENCPARM TYPE Command: Specify the Type of Processing That ESP Encore Does

TypeESP Encore command.

SyntaxENCPARM TYPE [INITIAL|RESTART|BACKOUT|DUMP|PREVIOUS]

Usage notes

General notesYou code TYPE manually for jobs that are submitted outside of the ESP Workload Manager. When ESP Workload Manager submits the job, it builds this command from the input entered on the resubmission panels and adds it to the ESP Encore step.

Operand DescriptionINITIAL Run the job for the first time.RESTART Restart a job whose job number is specified by the JOBID

statement.BACKOUT Back out a job run. All of the data sets created by the initial

job are backed out (deleted). The ESP Encore step executes and the remainder of the job is flushed.

DUMP Produce a complete ESP Encore Job Run report for a job that has already executed. This operand is for diagnostic purposes. The ESP Encore step is the only step that executes.

PREVIOUS Restart the most recent run of the job with this job name found on the EXH data set. ESP Encore sets ENCPARM TYPE for a job run to:• INITIAL if the previous run of the job finished

normally or there was no previous run.• RESTART if the previous run of the job failed

(including failures defined by commands such as CCCHK and CCFAIL).

ESP Encore cannot determine whether the previous run belongs to the most recent Application name and Application generation number. See the usage notes following.

473

Type PREVIOUSBecause ESP Encore does not keep Application information, it cannot determine whether the previous run belongs to the most recent Application name and Application generation number.The example given in the following table shows that job PAY1 was run by two different Application generations, producing JOB00012 and JOB00034. A user restarted JOB00012 as JOB00056. So, the most recent job in the EXH data set was now JOB00056. However, the most recent job was not run by the most recent generation of Application PAYROLL, which is PAYROLL.2. In this case, to run the most recent job in the most recent Application generation, you must issue the JOBID command to specify JOB00034. Specifying ENCPARM JOBID converts ENCPARM TYPE PREVIOUS to ENCPARM TYPE RESTART.

Example - TYPE RESTARTTo restart a job manually, ESP Encore needs the job name and the job ID. The name of the job that submits the restart must be the same as the job you are restarting. You must specify the job ID by issuing the ENCPARM JOBID command. Code the following commands in your manually submitted JCL to restart a job:// EXEC CYBRMENC//ENCPARMS DD *SUBSYS ESPTYPE RESTARTJOBID JOB12345/*

Example - TYPE PREVIOUSTo restart the previous job manually, ESP Encore needs the job name only, not the job ID. The name of the job that submits the restart must be the same as the job you are restarting. Code the following commands in your manually submitted JCL to restart a job:// EXEC CYBRMENC//SYSIN DD *SUBSYS ESPTYPE PREVIOUS/*

If the ENCPARM JOBID command is provided, TYPE PREVIOUS gives the same results as TYPE RESTART.

Application.Generation Job JES Number Run On...PAYROLL.1 PAY1 JOB00012 Monday morningPAYROLL.2 PAY1 JOB00034 Monday afternoonPAYROLL.1 PAY1 JOB00056 Tuesday afternoon

ENCPARM VOLUME Command: Specify Data Set Processing Based on Volume Serial

474

ENCPARM VOLUME Command: Specify Data Set Processing Based on Volume Serial

The VOLUME command is used to:• Specify special processing options for selected volumes.

Selected volumes are either excluded from ESP Encore processing or included in ESP Encore processing.

• Specify the string the installation uses to identify a migrated data set.The operand MIGRATE applies installation-wide and it can only have a single value.

TypeESP Encore command

SyntaxENCPARM VOLUME EXCLUDE(excl-vol-list) INCLUDE(incl-vol-list) MIGRATE(MIGRAT|mig-vol)

Operand DescriptionEXCLUDE(excl-vol-list) A list of volume serial numbers that represent

volumes on which no maintenance should be done. ESP Encore does not delete any data set that resides on a volume in the list.The wildcard characters asterisk and hyphen can be used.

INCLUDE(incl-vol-list) A list of volume serial numbers that represent volumes on which maintenance should be done. INCLUDE overrides previous EXCLUDE operands.

475

ExampleIn this example, ESP Encore does not delete data sets from SYSRES or from any volume whose volume serial begins with PAY, except for PAY002. Any data set cataloged on ARCIVE is to be considered as migrated.ENCPARM VOLUME EXCLUDE(SYSRES,PAY-) MIGRATE(ARCIVE)ENCPARM VOLUME INCLUDE(PAY002)

MIGRATE(MIGRAT|mig-vol) The volume serial numbers that indicate that a data set has been migrated. The default value is MIGRAT.

Note: MIGRAT is the value used by the IBM data management software. Different values may be used by other vendors of data management software. Consult your system programmer to determine the correct value for your site.

Migrated data sets are indicated by MIGRATED in the Catalog section of the ESP Encore job run report (see “Diagnostic sections of the ESP Encore job run report” in the ESP Encore User’s Guide). Also, for these data sets, ESP Encore does not predict the following errors:• DATA SET ALREADY DELETED• DATA SET NOT YET EXPIRED, NOT

DELETED• PERMANENT DATA SET NOT ON

VOLUME

Operand Description

ENCPARM WARNING Command: Display Extra Warning Messages to Support Manual Restart Tasks

476

ENCPARM WARNING Command: Display Extra Warning Messages to Support Manual Restart Tasks

In some restart situations, you may need to do manual adjustments to data sets. For example, you may have to recreate a missing data set or adjust a data set that has DISP=MOD specified in the DD statement. You can have ESP Encore issue extra warning messages in the Restart Action Summary screen to remind you about the required adjustments. You can still restart a job when you see the extra warning messages.

TypeESP Encore command

SyntaxENCPARM WARNING GDGALL(YES|NO) MISSING(YES|NO) DISPMOD(YES|NO)

Operand DescriptionGDGALL(YES|NO) Determines whether ESP Encore issues a warning message

when a job is restarted and a generation is missing from a GDG concatenation that existed when the job first ran.

Note: The ENCPARM WARNING GDGALL(YES) command must be issued for the initial run and the restart run of a job. If it is not, then the initial run of the job does not keep track of the generations that were included in the original GDG concatenation.

Note: Jobs can still run if warning messages are issued for a missing GDG generation.

MISSING(YES|NO) Determines whether ESP Encore issues a warning message if a data set no longer exists and ESP Encore intends to cleanup the data set. The data set may have already been deleted by another job or user.

DISPMOD(YES|NO) Determines whether ESP Encore issues a warning message if a data set with DISP=MOD is specified in a job. These data sets may require special handling by the user before a restart. ESP Encore usually tries to auto-restore these data sets. If it cannot, then it issues the warning.

477

Examples

Example – Warning message for WARNING GDGALL(YES)WARNING: A CONCATENATED GDG GENERATION IS MISSING.THE MISSING GENERATION IS PA.TESTGDGB.G0017V00THIS GENERATION WAS PART OF A GDG CONCATENATION.

Example – Warning message for WARNING DISPMOD(YES)WARNING: A DISP=MOD DATA SET WAS MODIFIED BY THE JOB.THE DATA SET IS PA.TEST.DD4001 ON VOL003THIS DATA SET MIGHT NEED TO BE RECREATED BEFORE RESTARTING THISJOB.

Example – Warning message for WARNING MISSING(YES)WARNING: DATA SET PA.TEST.DD4001 IS MISSING.(THIS DATA SET HAS ALREADY BEEN CLEANED UP BY SOME OTHER JOB ORUSER.)

ENCREQ Command: List or Unlock Access-Serialization Locks

478

ENCREQ Command: List or Unlock Access-Serialization Locks

Note: You need ESP Encore 3.1 to use this command.The ENCREQ command lists or unlocks access-serialization locks. If a TSO or ESP Workstation session stops responding while it has exclusive access to a job and the access lock has not expired, you can use ENCREQ to release the lock and regain control of the session.

TypeESP Encore command.

AuthorityYou require OPER authority to issue the ENCREQ command.

AuthorityTo invoke the LISTLOCK and UNDOLOCK functions, a user must be authorized to submit the OPER command.

SyntaxENCREQ {LISTLOCK} {UNDOLOCK LOCKTOKEN|TOKEN(token) [JOBNAME(jobname)] [JOBID(jobid)] [APPLICATION (application_name.absolute_generation_number)] [PREVTIME(yyyymmddhhmm)]

Operand DescriptionLISTLOCK List all the access-serialization lock tokens that the ESP

Workload Manager currently holds on behalf of CSF or ESP Workstation users.

UNDOLOCK Release an access-serialization lock token. You must specify the lock token. You don’t need to specify JOBNAME, JOBID, and APPLICATION, but these can be useful in a trace.

479

LOCKTOKEN(token)|TOKEN(token)

LOCKTOKEN or TOKEN contains a string returned when the lock is applied. This operand is used to locate an item that is locked so that it can be unlocked.

The token of a locked item is available to:• The lock holder, for example, the ESPTSOI.• Users who have OPER authority and can therefore issue

the ENCREQ LISTLOCK command.• Users authorized to view the ESP Encore CPEENQLG

and ENCORELG audit logs, where the lock tokens are listed (see “ESP Encore audit logs CPEENQLG and ENCORELG” in the ESP Workload Manager System Programmer’s Guide.).

• Users authorized to view the ESP WSS TRACEMSG log.

JOBNAME(jobname|jobname.qualifier)

Job name.

JOBID(jobid) The jobid operand has the form Jnnnnnnn, where nnnnnnn is a JES job number, for example, JOBID(J0123456). JOBID must match a job's execution job number, which, in the case of an internodal job, may differ from the original job number.

APPLICATION(application_name.absolute_generation_number)

Application name and generation.

PREVTIME(date_and_time)

The job reader-on time, which is the date and time a job was read by the system. The date_and_time operand has the form yyyymmddhhmm (year, month, day, hour, and minute), for example, PREVTIME(200406040156). PREVTIME is earlier (occasionally very much earlier) than a job's start time. When ESP Encore searches for a job in the EXH data set, it tries to match a job's reader-on time in addition to the job name and job number. If PREVTIME is omitted, the ENCREQ command processor tries to obtain the reader-on time from the ATR (Application Tracking Record) or the JTR (Job Tracking Record).

The ENCREQ command processor discards the PREVTIME argument in the case of internodal jobs.

Operand Description

ENCREQ Command: List or Unlock Access-Serialization Locks

480

Usage notesWhen in page mode, you should first enter line mode via the @LINEMD command to ensure that the response is correctly displayed. You can exit from line mode by issuing the END command.

ENCREQ command responsesThe response to an ENCREQ command is message 4447I. The ENCREQ LIST command also produces message 4449I. Message 4447I may be replaced by error messages 7081E or 7082E if the ENCREQ command processor encounters a problem before or during a serialization-control operation.See the message descriptions following.

Message 4447I: Serialization-control informationENCREQ response message 4447I indicates if the current user has obtained or still holds an access-serialization lock (ENQ) for a scoreboard item. If the message includes “UNLOCKED”, the lock has been released.The items that can appear in message 4447I are as follows:Note: Lock times are in format yyyymmdd-hhmmss.

ENCREQ response field DescriptionTOKEN(token_value) A unique token assigned to the access-

serialization lock (ENQ), for example:

TOKEN(1002F20040530110836#15)

listid A text string identifying the scoreboard item covered by message 4447I. For the ENCREQ command, listid is “ENCREQ” followed by the job name, Application name, and generation number, for example:

ENCREQ JOBNAME(NWPNFJB)APPLICATION(PRNFJB) GENERATION(2)

QNAME(queue_name) The ENQ queue name. For the ENCREQ command, the value of queue_name is always ESPCSF. For example:

QNAME(ESPCSF)

The ESP TSO/ISPF interface also uses an ENQ queue name of ESPCSF when a user selects a job in CSF by entering the RX, RR, or R line commands.

481

RNAME(resource_name) The ENQ resource name. The value of resource_name is the concatenation of the job name, job qualifier, Application name, and Application generation number in hexadecimal format, for example:

RNAME(C'NWPNFJB PRNFJB',X'00000002')

The ESP TSO/ISPF interface also uses this concatenation when a user selects a job in CSF by entering the RX, RR, or R line commands.

SCOPE(scope_name) The ENQ scope. For the ENCREQ command, the value of scope_name is always SYSTEMS. For example:

SCOPE(SYSTEMS)

The ESP TSO/ISPF interface also uses an ENQ scope name of SYSTEMS when a user selects a job in CSF by entering the RX, RR, or R line commands.

CTLTYPE(control_type) The ENQ control type. For the ENCREQ command, the value of control_type is always E. For example:

CTLTYPE(E)

The ESP TSO/ISPF interface also uses an ENQ control_type of E when a user selects a job in CSF by entering the RX, RR, or R line commands.

REQTYPE(request_type) The ENQ request type. For the ENCREQ command, the value of request_type is always USE. For example:

REQTYPE(USE)

The ESP TSO/ISPF interface also uses an ENQ request_type of USE when a user selects a job in CSF by entering the RX, RR, or R line commands.

USER(userId) The user on whose behalf an access-serialization lock was obtained, for example:

USER(CYBABC1)

ENCREQ response field Description

ENCREQ Command: List or Unlock Access-Serialization Locks

482

Message 4449I: information on ENCREQ LISTLOCK commandMessage 4449I appears at the end of the response to an ENCREQ LISTLOCK command, after zero or more 4447I messages. The form for message 4449I is:ESP4449I ENQ'S displayed: 1

Message 7081E: error on ENCREQ commandThe form for message 7081E is:ESP7081E ENCREQ ERROR: Invalid Argument_name specification: Argument_value

For example, the response to an ENCREQ command containing a misspecified JOBID argument would include an error message such as:ESP7081E ENCREQ ERROR: Invalid JOBID specification: JOB1045X

Message 7082E: error on ENCREQ commandThe form for message 7082E is:ESP7082E ENCREQ ERROR: Variable_message

For example, the response to an ENCREQ ANALYZE command containing argument USER1 could include the following error message:CYB7082E ENCREQ ERROR: Keyword USER1 incompatible with ENCREQ ANALYZE

Example 1List the access-serialization lock tokens currently held by ESP Workload Manager:ENCREQ LISTLOCK

ESP4447I TOKEN(1005F20040720171901#5) ENCREQ JOBNAME(PAYROLL1) + APPLICATION(PAYROLL1) GENERATION(18) QNAME(ESPCSF) +

LOCKED(date_and_time) Time this lock was obtained, for example:

LOCKED(20040527-094500)

LASTLOCK(date_and_time) Time this lock was last updated, for example:

LASTLOCKED(20040527-094500)

[EXPIRY(date_and_time)] Time, if any, this lock is scheduled to expire, for example:

EXPIRY(20040527-104500)

[UNLOCKED(date_and_time)] Time, if any, at which this lock was released, for example:

UNLOCKED(20040527-101300)

ENCREQ response field Description

483

RNAME(C'PAYROLL1 PAYAPP',X'00000012') +

SCOPE(SYSTEMS) CTLTYPE(E) REQTYPE(USE) USER(PROD) LOCKED(20040720-171901) +

LASTLOCK(20040720-171901)

ESP4449I ENQ'S displayed: 1

Example 2Unlock a lock with token 1005F20040720171901#5 (note the unlock timestamp at the end of the output):ENCREQ UNDOLOCK TOKEN(1005F20040720171901#5)

ESP4447I TOKEN(1005F20040720171901#5) ENCREQ JOBNAME(PAYROLL1) + APPLICATION(PAYROLL1) GENERATION(18) QNAME(ESPCSF) +

RNAME(C'PAYROLL1 PAYROLL1',X'00000012') +

SCOPE(SYSTEMS) CTLTYPE(E) REQTYPE(USE) USER(PROD) LOCKED(20040720-171901) +

LASTLOCK(20040720-171901) UNLOCKED(20040720-180542)

ENCRYPT Command: Enable Encrypted Communications

484

ENCRYPT Command: Enable Encrypted Communications

The ENCRYPT command is used to enable encrypted communications between the ESP Agent and the ESP Manager using a globally defined encryption key. An ENCRYPT command applies to Agents subsequently defined until the next ENCRYPT command.

TypeAuthorized command

SyntaxENCRYPT KEY(key) [ALL|NOALL]

Usage notesIf you do not include an ENCRYPT initialization parameter in the AGENTDEF, encryption is not activated for the subsequently defined Agents. In this case, you can define encryption in the AGENT initialization parameter if the AGENTDEF to enable encrypted communications for the Agent.

Operand Descriptionkey Specifies the ENCRYPT key field.

The encryption key is enclosed in single quotes and prefaced with an X to signify the key is in hexadecimal format.The encryption key can have a maximum of 16 characters (8 bytes).

ALL Activates encryption using the defined encryption key for all subsequent Agents with the following exceptions:

• If the AGENT initialization parameter uses the NOENCRYPT operand, no encryption is performed

• If the AGENT initialization parameter uses the ENCRYPT operand with a key defined, encryption is performed with the key defined in the AGENT initialization parameter

NOALL Activates encryption using the defined encryption key on the subsequent Agents whose initialization parameter includes the ENCRYPT operand with no key defined. NOALL is the default.

485

The following table indicates which key is used:

Equivalent EXEC parameterThe following table indicates the equivalence between WSSPARM and EXEC for the definition of the workstation server started task. Refer to ESP Workload Manager Installation and Configuration Guide for details.

ExampleThe following is an example of a single ENCRYPT initialization parameter:ENCRYPT KEY(X'010203040506ABCD')

AGENT Initialization Parameter includes:

ENCRYPT Initialization Parameter withALL Operand NOALL Operand

Neither ENCRYPT or NOENCRYPT

Encryption using the key in ENCRYPT Initialization Parameter

No Encryption

NOENCRYPT No Encryption No EncryptionENCRYPT without key Encryption using the key

in ENCRYPT Initialization Parameter

Encryption using the key in ENCRYPT Initialization Parameter

ENCRYPT with key Encryption using the key in AGENT Initialization Parameter

Encryption using the key in AGENT Initialization Parameter

EXEC parameters WSSPARM parameters Description

ENCRYPT(key) | NOENCRYPT

ENCRYPT KEY(key) Enables a client to encrypt its first USER|LOGON command.

ENCRYPT Command: Enable Encrypted Communications

486

The following is a sample AGENTDEF using multiple ENCRYPT initialization parameters:MANAGER NAME(CM_CENTRAL) TCPIPENCRYPT KEY(X'010203030501ADDD') ALLMAPUSER JDOE TO(CYBJD01) AGENT(TORSUN1)AGENT TORSUN1 ADDRESS(xxx.xx.xx.xx) PORT(9999) UNIX ASCII +TCPIP PREFIXING NOENCRYPTAGENT TORNT1 ADDRESS(xxx.xx.xx.xx) PORT(9998) NT ASCII +TCPIP PREFIXING AGENT TORAS4001 ADDRESS(xxx.xx.xx.xx) PORT(9997) AS400 EBCDIC +TCPIP PREFIXING ENCRYPT(X'010203040506AFFC')ENCRYPT KEY(X'01010101010102CBBD')AGENT CHI_AS ADDRESS(CHIAS01) PORT(3001) AS400 EBCDIC TCPIP +PREFIXINGAGENT NYC_AS ADDRESS(CHIAS02) PORT(3002) AS400 EBCDIC TCPIP +PREFIXING ENCRYPTAGENT SFO_AS ADDRESS(CHIAS03) PORT(3003) AS400 EBCDIC TCPIP +PREFIXING ENCRYPT(X'010203040506DEEC')

The following table gives and explains what encryption is used:

AGENT Key Used ExplanationTORSUN1 No encryption Agent uses NOENCRYPT operand.TORNT1 010203030501ADDD Agent uses the global key defined in the first

ENCRYPT initialization parameter with ALL operand because neither ENCRYPT or NOENCRYPT are specified.

TORAS4001 010203040506AFFC Agent uses the key defined with its ENCRYPT operand.

CHI_AS No encryption Agent uses neither ENCRYPT or NOENCRYPT and the second ENCRYPT initialization parameter specifies NOALL by default.

NYC_AS 01010101010102CBBD Agent uses the global key defined in the second ENCRYPT initialization parameter with ALL operand because ENCRYPT is specified without a key.

SFO_AS 010203040506DEEC Agent uses the key defined with its ENCRYPT operand.

487

ENCTRACE Command: Trace ESP Encore Programs

Note: You need ESP Encore 3.1 to use this command.The ENCTRACE command controls tracing in:• The ESP Encore programs that support the ESP Encore ISPF panel interface and

execute in the user's TSO address space.• The ESP Encore programs that satisfy requests from the ESP Encore ISPF panel

interface, but run in the ESP Workload Manager address space.

TypeESP Encore command.

SyntaxENCTRACE {program_name}|LIST|NONE [VERBOSE|NVERBOSE]

Usage notesTSO users can enter ENCTRACE on the command line of a CSF view panel.The ENCTRACE command enables tracing in some or all of the ESP Encore programs involved in ESP Encore's ISPF panel interface. For programs that execute in a TSO user's address space, trace messages pop up over the current display in real time. To see trace messages for the programs that execute in the ESP Workload Manager address space, the user must enter ENCLOG on the command line of an ESP Encore panel.

ExamplesEnable tracing in the ESP Encore program CYBRM117:ENCTRACE CYBRM117

Operand Descriptionprogram_name The full or partial name of an ESP Encore program. A

maximum of four names can be defined.LIST Display the ENCTRACE list.NONE Clear the ENCTRACE list.VERBOSE Produce any additional trace messages for ESP Encore

programs that have tracing enabled. Verbose tracing requires additional processing, so use it only if it is requested by Cybermation support.

NVERBOSE Disable verbose tracing. See the VERBOSE operand.

ENCTRACE Command: Trace ESP Encore Programs

488

Enable tracing in ESP Encore programs whose names begin with “CYBRM11”:ENCTRACE CYBRM11

Display the ENCTRACE list:ENCTRACE

–or–ENCTRACE LIST

Clear the ENCTRACE list:ENCTRACE NONE

489

END Command: End ESP Sessions

The END command is used to end the ESP terminal session or batch execution.

TypeGeneral command.

SyntaxEND

Usage notesTo access ESP in Line mode, enter either of the following:• TSO ESP SUB(subsys)—from the ISPF command line, where subsys is the

ESP subsystem name• @LINEMD—from within Page mode.Enter F3 when you have finished with ESP in Line mode for that particular session.

Related informationFor information on accessing ESP as a program in TSO, see the ESP Workload Manager User’s Guide.

ExampleDisplay ESP data setsTo access ESP in Line mode, enter the following from the ISPF command line, where SUB specifies the ESP subsystem name: In the following example, system data sets allocated to ESP are displayed (LDSN): Command ===> TSO ESP SUB(E520)

In Line mode, enter ESP commands as required:--> LDSNCHECKPOINT: CYB2.ESP520.CKPT, ALT NONE USERDEF: CYB2.ESP520.USERDEF, BKUP NONE INDEX: CYB2.ESP520.INDEX, BKUP NONE JOBINDEX: CYB2.ESP520.JOBINDEX QUEUE: CYB2.ESP520.QUEUE, ALT NONE TRAKFILE: CYB2.ESP520.TRAKFILE EVENTSET: CYB2.ESP520.EVENT1 HISTFILE: CYB2.ESP520.HISTFILE APPLFILE: CYB2.ESP520.APPLFILE JTDT: CYB2.ESP520.PARMLIB(JOBDEF1) UPDT: CYB2.ESP520.PARMLIB(PROFILE) --> END

Press F3 to terminate this Line mode session.

ENDDEF Command: End Event Definitions

490

ENDDEF Command: End Event Definitions

The ENDDEF command is used to end an Event definition.

TypeEvent definition command.

SyntaxENDDEF

Usage notesIf the ENDDEF command is omitted when creating an Event, ESP adds this omitted command.

Related informationFor information on defining Events, see the EVENT command. For information on Events, see the ESP Workload Manager User’s Guide.

Example Event definitionIn the following example:• The definition begins with the EVENT command and the Event’s name• The SCHEDULE command tells ESP when to schedule the Event• The INVOKE invokes an ESP Procedure• The ENDDEF command indicates the end of the definition.EVENT ID(CYBER.PAYROLL)SCHEDULE DAILY AT 8AMINVOKE 'CYB.ESP.PROCS(PAYROLL)'ENDDEF

491

ENDDO Statement: Identify End of Action Statements

The ENDDO statement is used to identify the end of one or more action statements.

TypeControl Language (CLANG) statement.

SyntaxENDDO

Usage notesUse the ENDDO statement in conjunction with the DO statement to indicate the end of a set of action statements.

Related informationFor information on identifying the start of a set of compound action statements, see the DO statement.For information on using ESP’s Control Language, see the ESP Workload Manager User’s Guide.

Examples Send a message and invoke an applicationThe following DO and ENDDO statements are used to identify the start and end of a set of action statements:IF X = 'BILLING' THEN DO SEND 'BILLING JOB WILL RUN TODAY' CN(01) INVOKE 'CYBER.PROCLIB.CNTL(BILLING)'ENDDO

In the above example, if the value of a variable called X is equal to BILLING:• A message is sent to the console• The BILLING Application is invoked.

ENDDO Statement: Identify End of Action Statements

492

Delay submission time and mark lateIn the following example, if today is Monday, PAYJOB1’s submission is delayed to 4 pm, and its late submission time is set to 5 pm:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYS IF TODAY('MONDAY') THEN - DO DELAYSUB 4PM LATESUB 5PM ENDDOENDJOB

493

%ENDEXCL Statement: End Exclusion of JCL

The %ENDEXCL statement is used to end the exclusion of JCL or to end the exclusion of control statements from a symbolic variable library.

TypeESP control statement used in JCL and symbolic variable library statements.

Syntax%ENDEXCL

Usage notesThe %ENDEXCL statement must start in Column one. If you want to include a statement with the characters %ENDEXCL starting in column one, but to have it treated as data rather than a control statement, code %%ENDEXCL. The first percent sign is removed.Note: Before using the %ENDEXCL statement, check with your system

administrator to ensure no changes were made during your ESP installation that affect the way ESP recognizes these statements. For example, another product may make conflicting use of these terms, in which case your system administrator can change them.

Related informationFor information on selectively excluding JCL and DATA, see the %EXCLUDE statement.For information on selectively including JCL and DATA, see the %INCLUDE statement.

Examples End the exclusion of data on MondaysIn the following example, the symbol 'PARM' does not take on the value of 'ABC' on Mondays:%EXCLUDE DAY(MONDAY)PARM='ABC'%ENDEXCL

Exclude DD statement on MondaysIn the following example, the DD statement 'INPUT05' is excluded on Mondays:%EXCLUDE DAY(MONDAY)//INPUT05 DD DSN=CYBER.INPUT.DATA,DISP=SHR%ENDEXCL

ENDHC Command: End Output Data

494

ENDHC Command: End Output Data

The ENDHC command is used to stop routing of output as specified by a HARDCOPY command.

TypeGeneral command.

SyntaxENDHC

Usage notesThe ENDHC command is only available in Line mode or Page mode.When ESP encounters the ENDHC command, it stops writing output data to a data set, DD file or SYSOUT class.

Related informationFor information on routing command output, see the HARDCOPY command.

Example Routing command outputIn the following example:• The HARDCOPY command tells ESP to route command output to a member of a

PDS• Three GENTIME commands are issued to created customized date and time

variables• The ENDHC command indicates that ESP is to stop the routing of command

output.HARDCOPY DATASET(CYB.COMMAND.OUTPUT(DATA))GENTIME AA TODAYGENTIME BB TODAY PLUS 2 WORKDAYSGENTIME CC LAST WORKDAY OF MONTH STARTING TODAYENDHC

495

%ENDINCL Statement: End Inclusion of JCL

The %ENDINCL statement is used to end the inclusion of JCL or to end the inclusion of control statements from a symbolic variable library.

TypeESP control statement used in JCL and symbolic variable library statements.

Syntax%ENDINCL

Usage notesThe %ENDINCL statement must start in Column one. If you want to include a statement with the characters %ENDINCL starting in column one, but to have it treated as data rather than a control statement, code %%ENDINCL. The first percent sign is removed.Before using the %ENDINCL statement, check with your system administrator to ensure no changes were made during ESP installation that affect the way ESP recognizes these statements. For example, another product may make conflicting use of these terms, in which case your system administrator can change them.

Related informationFor information on selectively excluding JCL and DATA, see the %EXCLUDE statement.For information on selectively including JCL and DATA, see the %INCLUDE statement.

Examples End inclusion of data on MondaysIn the following example, the 'PARM' takes on the value of 'ABC' on Mondays:%INCLUDE DAY(MONDAY)PARM='ABC'%ENDINCL

End inclusion of DD statement on MondaysIn the following example, DD statement INPUT05 is included on Mondays:%INCLUDE DAY(MONDAY)//INPUT05 DD DSN=CYBER.INPUT.DATA,DISP=SHR%ENDINCL

ENDJOB Statement: End Job Definitions

496

ENDJOB Statement: End Job Definitions

Indicates the end of a job definition. You must use an ENDJOB statement after the last job definition and when defining statements at a global level between jobs.

TypeApplication statement.

SyntaxENDJOB

Usage notesThe scope of the JOB statement includes all statements up to an ENDJOB statement or up to the next JOB or other job statement (for example: NT_JOB, TEXT_MON, UNIX_MON). Cybermation recommends that you end each job definition with an ENDJOB statement. ESP Workload Manager processes scripts or commands based on where they are placed within an Application. It processes:

• Globally defined scripts or commands when the Application is generated and every time a job becomes eligible (that is, when all dependencies are met)

• Job-specific scripts or commands only when the job becomes eligibleNote: If a variable is defined within the boundaries of a job and used within a

conditional statement, errors might occur when other jobs run, because:• Conditional statements (IF, THEN, ELSE, DO, and ENDDO) are processed

when the Application is generated and every time a job becomes eligible, regardless of whether the conditional statements are inside or outside the boundaries of the job definition.

• Variable definitions are processed only when the job containing the variable executes.

Cybermation recommends that you define variables that are used within conditional statements outside the boundaries of a job.

497

Example APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY RELEASE PAYJOB2ENDJOBJOB PAYJOB2 RUN DAILYENDJOB

ENDMODEL Command: End Model Definitions

498

ENDMODEL Command: End Model Definitions

The ENDMODEL command is used to end the model definition mode and invokes the MODEL generation processor.

TypeModel command.

SyntaxENDMODEL

Related informationFor information on how ESP processes workload in your environment, see the ESP Workload Manager Advanced User’s Guide.For information on beginning the model process, see the MODEL command.

Example Model definitionIn the following example:• The DEFPRINT command directs output to a DD name• The MODEL command invokes the model processor • The MAXINITS and INIT commands define initiators• The MREPORT command selects the modeling report to be generated• The ENDMODEL command ends the model definition and invokes the MODEL

generation processor• The ENDPRINT command creates a report.DEFPRINT XREF DDNAME(MODEL1) MODEL CYBER.SAD - START('4PM TODAY ENDING 4PM TODAY PLUS 5 DAYS') MAXINITS 8 INIT START(1:8) CLASS(A,B,C,D) MREPORT XREF JR1 FROM('4PM TODAY ENDING 4PM TOMORROW') ENDMODELENDPRINT XREF

499

ENDPRINT Command: Close Report Data Files

The ENDPRINT command is used to close each of the report data files opened with the DEFPRINT command.

TypeGeneral command.

SyntaxENDPRINT reptname

Usage notesThe report name ended by the ENDPRINT command is assigned on the DEFPRINT command.

Related informationFor information on defining a report file, see the DEFPRINT command.

Example Model definitionIn the following example:• The DEFPRINT command directs output to a DD name• The MODEL command invokes the model processor • The MAXINITS and INIT commands define initiators• The MREPORT command selects the modeling report to be generated• The ENDMODEL command ends the model definition and invokes the MODEL

generation processor• The ENDPRINT command creates a report.DEFPRINT XREF DDNAME(MODEL1) MODEL CYBER.SAD - START('4PM TODAY ENDING 4PM TODAY PLUS 5 DAYS') MAXINITS 8 INIT START(1:8) CLASS(A,B,C,D) MREPORT XREF JR1 FROM('4PM TODAY ENDING 4PM TOMORROW') ENDMODELENDPRINT XREF

Operand Descriptionreptname A one to eight-alphanumeric character logical report name.

ENDPROC Command: Terminate an ESP Procedure

500

ENDPROC Command: Terminate an ESP Procedure

The ENDPROC command is used to terminate an ESP Procedure in an Event definition.

TypeEvent definition command.

SyntaxENDPROC

Usage noteThe ESP Procedure included in an Event must be enclosed between a PROC and an ENDPROC command.

Related informationFor information on defining Events, see the EVENT command. For information on Events, see the ESP Workload Manager User’s Guide.

Example EVENT ID(PROD.WITHPROC) SCHEDULE DAILY AT 6PM PROC APPL WITHPROC JCLLIB PROD.JCL JOB A RUN DAILY RELEASE JOB B ENDJOB JOB B RUN DAILY ENDJOB ENDPROCENDDEF

501

ENDR Command: End History Report Definitions

The ENDR command ends a history report definition and starts the report generation phase.

TypeReporting command.

SyntaxENDR

Related informationFor information on beginning a report definition, see the REPORT command.For information on history reports, see the ESP Workload Manager User's Guide.

Example History report definitionIn the following example:• The REPORT command invokes the report processor• The FROM, CRITERIA and DISPLAY report statements define the report• The ENDR command ends the report definition and initiates report generation.REPORTFROM 7AM YESTERDAYCRITERIA APPLSYS EQ PAYROLLDISPLAY JOBNAME JOBNO APPLSYS CMPCENDR

ENDTEMPL Statement: End Template Definitions

502

ENDTEMPL Statement: End Template Definitions

The ENDTEMPL statement is used to indicate the end of a template definition.

SyntaxENDTEMPL

Related informationFor information on working with templates, see the ESP Workload Manager Advanced User’s Guide.For information on defining templates, see the TEMPLATE statement.

Example Example templateIn the following example, the PAYROLL Application is defined using a template called PRTJOBS. The ENDTEMPL statement ends the PRTJOBS template definition:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'

TEMPLATE PRTJOBS (1,JOBNAME) JOB %JOBNAME RUN DAILY ENDJOBENDTEMPL

PRTJOBS PAYJOB1PRTJOBS PAYJOB2PRTJOBS PAYJOB3

503

ENQSELF Command: Specify Jobs Enqueue on Themselves

The ENQSELF command indicates every job in every ESP Application will have an enqueue on itself.ENQSELF can be coded as an initialization parameter.Note: The ENQSELF command and initialization parameter use resources implicitly.

Therefore, a resource file (RESFILE) and the topology must be defined before you can use it.

Note: Cybermation strongly recommends that you use resources rather than ENQSELF for this purpose.

AuthorityThe ENQSELF command requires OPER authority.

SyntaxENQSELF [ALWAYS|NOTALWAYS]

Usage notesSpecifying the NOTWITH statement within the scope of a job requires that the targeted job enqueue on itself. This occurs if either ENQSELF is set to ALWAYS or the targeted job has a NOTWITH statement. Thus setting ENQSELF to ALWAYS allows the use of unmatched NOTWITH statements. See the example below.

Operand DescriptionENQSELF Displays the status of ENQSELF. ALWAYS Specifies all jobs will enqueue on themselves. This is useful if you

are using the NOTWITH statement with numerous, small groups of jobs that are mutually exclusive.

NOTALWAYS Indicates only jobs with enqueues originating from the NOTWITH statement will automatically enqueue on their own names. When ENQSELF is coded as an initialization parameter, the NOTALWAYS operand becomes the default.

ENQSELF Command: Specify Jobs Enqueue on Themselves

504

Example APPL NWN00AJCLLIB 'CYBER.JCL.CNTL'

JOB NWN001 RUN WEEKDAYS NOTWITH NWN003ENDJOB

JOB NWN002 RUN WEEKDAYSENDJOB

JOB NWN003 RUN WEEKDAYSENDJOB

In the above example, job NWN003 has no NOTWITH statement, so it will execute at the same time as job NWN001 unless ENQSELF is set to ALWAYS. Otherwise, job NWN003 must have a NOTWITH NWN001 statement to be mutually exclusive with job NWN001. Command responsesThe following is the response from issuing the ENQSELF ALWAYS command in ESP pagemode: OPER ENQSELF ALWAYSESP1573I ENQSELF MODE IS ALWAYS

505

ENQUEUE Command: Display Enqueue Status

The ENQUEUE command displays the current enqueue status in the resource file.Note: The ENQUEUE command uses resources implicitly. Therefore, a resource file (RESFILE) and the network topology must be defined before you can use it.

AuthorityThe ENQUEUE command requires OPER authority.

SyntaxENQUEUE [nnn]

Usage notesFor each enqueue that matches nnn, ESP will produce a list of all outstanding requests showing the requesting job, the type of the request (exclusive or shared) and whether the enqueue is held by the job. Some jobs may be shown with requests generated by the ESP Resource Manager. This happens when a job has a generic request (one with wild cards) that matches a non-generic request by another job. Such a match will result in the generic enqueue being accompanied by a normal enqueue that the generic request implies.

Example APPL NWN00GJCLLIB 'CYBER.JCL.CNTL'

JOB NWN001 RUN DAILY ENQUEUE NAME(B-C) SHARED ENDJOB

JOB NWN002 RUN DAILY ENQUEUE NAME(BBC) EXCLUSIVEENDJOB

Operand Descriptionnnn Specifies a resource name; this is an optional operand. Displays the

current status of enqueues with name matching nnn. The use of wildcards is supported.

ENQUEUE Command: Display Enqueue Status

506

The previous ESP Application produced the following display from the ENQUEUE B- command:BBC (Gen) Held Shr NWN001, Appl NWN00G.1 Required Excl NWN002, Appl NWN00G.1

B-C Held Shr NWN001, Appl NWN00G.1

The display shows job NWN002 waiting behind a satisfied request of NWN001, that was generated by the ESP Resource Manager to reflect the match between NWN001’s enqueue on B-C and NWN002’s enqueue on BBC. Generated requests are shown with (Gen).

507

ENQUEUE Statement: Specify Resources to Enqueue

The ENQUEUE statement specifies a resource name that a job must enqueue on. This statement adds resources to the enqueue list. If the resource entry was already on the list, its type (shared or exclusive) will be set as specified.Note: You must define a resource file (RESFILE) and the topology before you can use the ENQUEUE statement.

SyntaxENQUEUE NAME(n1,n2,...) [SHARED|EXCLUSIVE][HOLD]

Usage notesIf one or more jobs request shared use of a resource, they are granted the use of that resource provided no other job has that same resource held exclusively.If a job requires exclusive use of a resource, it will be granted use of that resource provided the resource is not used by any other job.

Operand Descriptionn1 Specifies a resource name. A resource name can be up to 132

characters long and can contain wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) for shared enqueues only.

SHARED Requests shared use of the specified resource. This is the default.EXCLUSIVE Requests exclusive use of the specified resource.HOLD Hold the specified resource until the jobs affected by the

ENQUEUE statement run successfully. If you specify HOLD for one ENQUEUE used by a job, all resources used by the job are held.

ENQUEUE Statement: Specify Resources to Enqueue

508

ExampleThe following example shows job NWN001 requesting a shared enqueue on resource FRED. This resource is held until job NWN001 executes successfully.APPL NWN00AJCLLIB 'CYBER.JCL.CNTL'

JOB NWN001 RUN DAILY ENQUEUE NAME(FRED) SHARED HOLDENDJOB

JOB NWN002 RUN DAILYENDJOB

509

ENVAR Statement: Pass Environment Variables

Passes environment variables to a batch file, script, command, or program.

TypeApplication statement.

Syntax ENVAR [name=value] [HOME=path] [PWD=path] [STDIN=keyboard|path] [STDOUT=screen|path] [STDERR=screen|path]

Operand Descriptionname=value The name of the environment variable. It is equal to the value to

be assigned to the variable.

Note: If the resulting value requires spaces, such as a date, enclose the value in single quotes in the ENVAR statement. For example:ENVAR DATE='%ESPADATE'

Note: Specify multiple name and value pairs by using multiple ENVAR statements. There is no limit to the number of ENVAR statements that can be used.

HOME=path The fully-qualified name of the home directory to switch to before running the batch file, script, command, or program. Specify the path in the format:• For Windows: drive:\path\name• For UNIX: /diretory/file name

PWD=path Use within a UNIX_JOB to define a job for the UNIX Agent. The name of the Present Working Directory (PWD) to switch to before running a UNIX command or script.

Note: If the PWD is not specified, the command or script runs in the initial working directory specified by the oscomponent.initialworkingdirectory parameter in the agentparm.txt file. For more information on oscomponent.initialworkingdirectory, see the ESP System Agent Administrator’s Guide.

ENVAR Statement: Pass Environment Variables

510

Usage notesUse ENVAR within the boundaries of the job definition.Programs, commands, batch files, and scripts can access environment variables using the getenv() function. Specify variable names as follows for your environment:• For Windows batch files or programs to access environment variables, specify the

variable name with a leading and trailing percent sign (%). • For UNIX scripts or commands to access environment variables, specify the

variable name with a leading and trailing dollar sign ($). The ENVAR statement does not override Windows system variables. To reset Windows system-defined variables, set these variables in a batch file. For example, code the following to set variables TMP and TEMP in a batch file:set TMP=d:\spool

set TEMP=d:\agent\temp

If you use the ENVAR statement to pass multiple environment variables to batch file, script, command, or program, keep in mind that the maximum length of a message to an Agent is 4 KB.

STDIN=keyboard|path The fully-qualified standard input stream. Specify the path in the format:• For Windows jobs: drive:\path\name• For UNIX jobs: /diretory/file nameIf you do not specify STDIN, the standard input stream is the keyboard, which is the default.

STDOUT=screen|path Specifies the fully-qualified standard output stream. Specify the path in the format:• For Windows jobs: drive:\path\name• For UNIX jobs: /diretory/file nameIf you do not specify STDOUT, the standard output stream is the screen, which is the default.

STDERR=screen|path Specifies the fully-qualified standard error output stream. Specify the path in the format:• For Windows jobs: drive:\path\name• For UNIX job: /diretory/file nameIf you do not specify STDERR, the standard error output stream is the screen, which is the default.

Operand Description

511

ExamplesPassing Windows environment variables to a batch fileThis example includes two ENVAR statements that pass environment variables to a Windows batch file, a third ENVAR statement that passes a symbolic variable, and a fourth that defines the home directory:NT_JOB pay RUN DAILY CMDNAME c:\payroll\command1 AGENT NT_NY ENVAR A=B ENVAR C='X Y' ENVAR E=%ESPAPJOB ENVAR HOME=c:\export\u1ENDJOB

In this example, the command command1 can reference these variables:

Note: Unlike the first two environment variables, %ESPAPJOB is a built-in symbolic variable that passes the name of the job (from the JOB environment variable). For more information on using symbolic variables in Applications, see the ESP Workload Manager User’s Guide.

Passing UNIX environment variables to a scriptThis example includes two ENVAR statements that pass environment variables to a script, and a third that defines the Present Working Directory (PWD):

UNIX_JOB PAYROLL RUN DAILY SCRIPTNAME /home/scripts/pay AGENT UNIX_NY ENVAR NAME="user 1" ENVAR JOB=%ESPAPJOB ENVAR PWD=/usr/scripts/dailyrunENDJOB

Environment Variable Value Passed%A% B%C% 'X Y'%E% pay%HOME% c:\export\u1

ENVAR Statement: Pass Environment Variables

512

In this example, the script pay can reference these variables:

Note: If in the agentparm.txt initialization file, the parameter oscomponent.loginshell is set to true, the Agent invokes the user environment while running the script. To override the value of a shell variable that is already defined in the user login file, reassign a value to this variable in the script.

Environment Variable Value PassedNAME user 1JOB PAYROLL

Note: %ESPAPJOB is an ESP Workload Manager symbolic variable that passes the name of the job containing the variable. For more information on using symbolic variables in Applications, see the ESP Workload Manager User’s Guide.

PWD /usr/scripts/dailyrun

513

ESP Statement: Issue ESP Commands

The ESP statement is used to issue any ESP command from within an ESP Procedure.

SyntaxESP command

Usage notesAs part of an Application you may want to issue ESP commands. This is useful, for example, when you want to manipulate jobs, trigger Events, and perform displays.Use the ESP or ESPNOMSG statement in an Application to issue an ESP command. ESPNOMSG suppresses responses from the command.

Related informationFor information on issuing ESP commands and having the response from the command suppressed, see the ESPNOMSG statement.

Examples Trigger an EventIn the following example, the TRIGGER.EVENT link issues an ESP command to trigger an Event called CYBER.ACCTJOBS:JOB TRIGGER.EVENT LINK PROCESS RUN DAILY ESP TRIGGER CYBER.ACCTJOB ADDENDJOB

Operand Descriptioncommand Any valid ESP command.

ESP Statement: Issue ESP Commands

514

Complete Task when resource availableIn the following example, when a resource called 'CICS' becomes available, ESP issues an APPLJOB command to complete a task called WAIT4.CICS. After WAIT4.CICS completes PAYJOB1 is released:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB WAIT4.CICS TASK RUN ANY RELEASE PAYJOB1 RESOURCE (1,CICS) ESP AJ WAIT4.CICS COMPLETE APPL(WAIT4.0)ENDJOBJOB PAYJOB1 RUN ANYENDJOB

Insert a job and complete a TaskIn the following example, when PAYJOB1 successfully completes, an ESP command is issued to insert PAYJOB99 into the current generation of the BILLING Application:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY RELEASE INSERT.JOB JOB INSERT.JOB LINK PROCESS RUN DAILY ESP AJ PAYJOB99 INSERT APPL(BILLING.0) ENDJOB

515

ESPCOM Command: Control ESP Communications

Displays and controls ESP Workload Manager communications activity between the ESP Agents and ESP Workload Manager version 5.3 and higher.

TypeGeneral command.

AuthorityYou require OPER authority to issue the ESPCOM command.

SyntaxESPCOM

|[[LIST|QUIESCE|RESTART|FLUSH] DEST(dest_name)]

ExamplesList COMMQ attributesIn the following example, the COMMQ data set attributes are listed:OPER ESPCOM

CommQ data set name: CYBER.ESP.ESPCOMQ size: 1474560 bytes used: 320 bytes1 senders are defined, 0 of them quiesced

Operand DescriptionESPCOM Lists the attributes of the COMMQ checkpoint data set in use

when issued by itself.LIST Lists the attributes of the COMMQ checkpoint data set in use.

This is the default. When the DEST keyword is included, the status of the specified agents or DMs are also displayed.

QUIESCE Quiesces communication to the agents specified by the DEST keyword. The agents continue processing.

RESTART Restarts communication with the agents specified by the DEST keyword.

FLUSH Purges all pending messages for the agents specified by the DEST keyword.

DEST(dest_name) Specifies the agent names or DM names you want to view or manipulate. Wildcards may be used when specifying dest_name.

ESPCOM Command: Control ESP Communications

516

List COMMQ attributes using wildcardIn this example, the COMMQ data set attributes of all agents whose names begin with AIX will be listed:ESPCOM DEST(AIX-)

This is a typical response:CommQ data set name: CYB2.QA.V520.ESP.ESPCOMQ

size: 1474560 bytes

used: 42952 bytes

Destination name|status| last operation | sent |queued|address

AIXTCNP |active|Conn err 16.24.27 03 APR| 0| 0|111.111.30.144:81

AIXV3NP |active|Conn err 16.24.27 03 APR| 0| 0|111.111.25.12:806

47 senders are defined, 0 of them quiesced

Quiesce multiple agentsIn this example, all agents whose names begin with AIX will be quiesced:ESPCOM QUIESCE DEST(AIX-)

This is a typical response:ESP1519I Quiesce requested for two destinations

You can verify that the agents have been quiesced by issuing this command:OPER ESPCOM DEST(AIX-)

This is a typical response:CommQ data set name: CYB2.QA.V520.ESP.ESPCOMQ

size: 1474560 bytes

used: 42952 bytes

Destination name|status| last operation | sent |queued|address

AIXTCNP |quiet |Conn err 16.24.27 03 APR| 0| 0|111.111.30.144:81

AIXV3NP |quiet |Conn err 16.24.27 03 APR| 0| 0|111.111.25.12:806

47 senders are defined, 2 of them quiesced

Restart multiple agentsIn this example, all agents whose names begin with AIX will be quiesced:

ESPCOM DEST(AIX-) RESTART

This is a typical response:ESP1520I Restart requested for five destinations

You can verify that the agents have been restarted by issuing the following command:ESPCOM DEST(AIX-)

517

This is a typical response:CommQ data set name: CYB2.QA.V520.ESP.ESPCOMQ

size: 1474560 bytes

used: 51528 bytes

Destination name|status| last operation | sent |queued|address

AIXTCNP |active|Conn err 16.24.27 03 APR| 0| 0|111.111.30.144:81

AIXV3NP |active|Conn err 16.24.27 03 APR| 0| 0|111.111.25.12:806

47 senders are defined, 0 of them quiesced

Flush agent messagesIn this example, the message queues of all agents whose names begin with AIX are flushed.ESPCOM FLUSH DEST(AIX)

This is a typical response:

ESP1521I Queue, flush requested for 2 destinations.

ESPCTR Command: Control ESP Counters

518

ESPCTR Command: Control ESP Counters

Displays ESP Workload Manager internal activities relating to Events, Applications and jobs. These counters represent the activity for this ESP Workload Manager system only. No counts are shown for any proxy systems or any other remote ESP Workload Manager systems.

TypeAuthorized oper command.

AuthorityYou require OPER authority to issue the ESPCTR command.

SyntaxESPCTR [RESET]

Usage notesUse the ESPCTR command to display statistics on Applications completed or created, Events executed, and jobs submitted. These activities are measured in the following intervals: this year, this month, this day, since the last ESP start.An ESP cold start or the ESPCTR RESET command resets all the values to zero.

Related informationThe USE command displays the same information from the ESP Main Menu.

Example Display usage statisticsIn the following example:• APPCMP refers to the number of Applications completed• APPCRE refers to the number of Applications created

Operand DescriptionRESET Resets the following values to zero:

• APPCMP: number of Applications completed• APPCRE: number of Applications created• EVEXQ: number of Events executed• JOBSUB: number of jobs submitted by ESP Workload Manager

519

• EVEXQ refers to the number of Events executed• JOBSUB refers to the number of jobs submitted by ESP Workload ManagerOPER ESPCTR

APPCMP 499,499,13,143APPCRE 737,737,27,211EVXEQ 2220,2220,43,594JOBSUB 1190,1190,13,365

The statistics are listed in the following order (from left to right): this year, this month, this day, since last ESP start.Note: Entering USE from the ESP main menu produces the identical statistics to that

of the ESPCTR command (above), only formatted differently.ESP ---------------------------------- Usage ----------------- Row 1 to 4 of 4 Command ===> Scroll ===> PAGE

This This This Since Last

Activity Year Month Day ESP Start

------------------------------------------------------------------------------

Applications completed 499 499 13 143

Applications created 737 737 27 211

Events executed 2220 2220 43 594

Jobs submitted 1190 1190 13 365

******************************* Bottom of data ******************************

ESPmgr Command: Send Messages to ESP Manager (Recommended)

520

ESPmgr Command: Send Messages to ESP Manager (Recommended)

Sends a message to the ESP Workload Manager from the platform where the Agent is running. The message can be used to:• Perform an action• Notify the Manager of a change in state• Respond to a requestThe ESPmgr command can also be used within a program to report the completion of internal processing phases. For example, a long-running program can send intermediate status information to the ESP Workload Manager to be displayed on CSF. The command can also be used to perform many other functions such as release workload or request additional workload.

TypeGeneral Command

Entering CommandThe ESPmgr command can be issued via:• The command line• A script or program

SyntaxESPmgr "objectname verb subverb[(keyword)]"

The verb, subverb, and keywords and values differ depending on the verb used.

Operand Descriptionobjectname Indicates the fully qualified name of the jobs to which the command

refers; can be a symbolic variable.

Note: When a command is sending a message regarding itself to the ESP Workload Manager, it can use a period in place of the objectname.

verb Indicates the action to be taken. The possible values are: • “ACTION verb”, see page 521• “STATE Verb”, see page 525

subverb Further defines the action to be taken. keyword Modifies the verb /subverb combination.

521

Note: Refer to the specific sections for the verbs ACTION or STATE for more information.

ACTION verbThe ACTION verb is used to send requests to ESP Workload Manager to perform an action that is specified by the subverb. The following subverbs and associated keywords are valid with the ACTION verb.

Subverb DescriptionBYPASS Turns on the BYPASS indicator to bypass this job.DROPDEP Drops some or all dependencies for the job. DROPDEP may be modified

to drop only selected dependencies when used with data supplied with the keyword PRED.

PRED( )—Enclose the list of dependencies to be dropped, separated by blanks, in parentheses. Omitting the PRED keyword drops all dependencies.

DROPRES Drops some or all resources. DROPRES may be modified to drop only selected resources when used with data supplied with the keyword RESOURCE.

RESOURCE( )—Enclose the list of resources to be dropped, separated by blanks, in parentheses. Omitting the RESOURCE keyword drops all resources.

HOLD Places the specified job on hold.INSERT Inserts a new job in the application. See “INSERT subverb” on page 522

for the list of valid keywords available with the INSERT subverb.READY Places job in Ready state. Drops any dependencies, hold states, or delay

submit times.RELEASE Releases the job from a hold state.REQUEST Turns on the Requested indicator.RESET Resets an attribute, condition or state of a job. See “RESET subverb” on

page 524 for the list of valid keywords available with the RESET subverb.RESUB Schedule the job for resubmission. See “RESUB subverb” on page 525

for the list of valid keywords available with the RESUB subverb.SET variable(value) Sets the variable to the value specified.UNBYPASS Turns off the Bypass indicator. No longer bypass this job. UNREQUEST Turns off the Requested indicator.UNWAIT Do not wait for the completion of a previous generation of this object.

ESPmgr Command: Send Messages to ESP Manager (Recommended)

522

INSERT subverbThe following are the valid data keywords for use with the INSERT subverb.

Keyword DescriptionAbandonDependency( ) Time/date when dependencies are to be dropped.AbandonResource( ) Time/date when resource requirements are to be dropped.AbandonSubmission( ) Time/date when submission of the job is to be abandoned.Appl( ) Name of the application for an external job.Authstr( ) Authorization string associated with an external job.AverageCPU( ) Average CPU time used, in the form mmmss.AverageElapsed( ) Average elapsed time, in the form mmmss.Conditional Conditional job.Doclib( ) Name of the library containing documentation for the job.Docmem( ) Member name of documentation library entry.Dsname( ) Submit data set name.EarlySub( ) Earliest time that a job can be readied, in the form mmss.Espprocfile( ) Name of the library containing the job's definition (ESP

Workload Manager procedure file).External Refers to a job in another application.Hold Place job in manual hold condition.LateEnd( ) Time/date by which job should complete to avoid being

overdue.LateSub( ) Time/date by which the job should be submitted to avoid being

overdue.Manual Manually submitted z/OS job.Pred( ) Names of any predecessor jobs. There is no limit to the number

of jobs specified here. Job names are in the form nnnn.qqqq for a qualified job, or nnnn for a job without a qualifier. Separate names with blanks or commas.

Priority( ) Priority of the job. This is a number from 0-99. Applies only if using ESP resources.

Process Event processing is required. Applies to links.RelDelay( ) Minimum delay time in minutes to be added to a job after its last

dependency is met.Request Sets the Request attribute requiring the job to be explicitly

requested to run.

523

JOB TypeThe following are valid workload object types and their designations:

Resource( ) Resources the job requires to run. Operands are specified in the form nnn,rrrr where nnn is the numeric quantity, and rrrr is the name of the resource. A resource can be nullified by setting the quantity to 0. If quantity is omitted, the default is 1.Scheduled( )—Scheduled time an external job will match this job definition.

Scheduled( ) Scheduled time an external job will match this job definition.Statements( ) One or more statements that should run as part of the processing

when this job is readied. Separate each statement with a semicolon.

Tag( ) Specifies a tag for the job.Type( ) Job type. See “JOB Type”, see page 523 for the list of valid

workload object types and their designations.Subappl( ) Name of the subApplication to which the job belongs.Succ( ) Names of any successor objects. There is no limit to the number

of objects specified here. Object names are in the form nnn.qqq for a qualified object, or nnn for an object without a qualifier. Separate names with spaces or commas.

Keyword Description

Job Type DescriptionAGENT_MONITOR or AM Designates a workload object that monitors the status of an

Agent.APPLEND or AE Designates the last workload object of the Application.AIX_JOB or AX Designates a job for an AIX Agent.AS400_JOB or A4 Designates a job for an OS/400 Agent.DATA_OBJECT or DA Designates a data object.DSTRIG or DS Designates a data-set trigger.FILE_TRIGGER or FM Designates a file trigger on an Agent platform.HPUX_JOB or HJ Designates a job for an HPUX Agent.HP3K_JOB or H3 Designates a job for an HP3000 Agent.IRIX_JOB or IR Designates a job for an IRIX Agent.MPEIX_JOB or MP Designates a job for an MPEIX Agent.NCR_JOB or NC Designates a job for an NCR Agent.NT_JOB or NT Designates a job for a Windows NT Agent.OPENVMS_JOB or OV Designates a job for an OpenVMS Agent.

ESPmgr Command: Send Messages to ESP Manager (Recommended)

524

RESET subverbThe following are the valid data keywords for use with the INSERT subverb.

OS2_JOB or O2 Designates a job for an OS/2 Agent.PYRAMID_JOB or PJ Designates a job for a PYRAMID Agent.SAP_JOB or SP Designates a job for an R/3 ERP Systems Agent.SEQUENT_JOB or SQ Designates a job for an HPUX Agent.SUN_JOB or SJ Designates a job for a Solaris Agent.TANDEM_JOB or TA Designates a job for the Tandem NSK Agent.UNIX_JOB or UJ Designates a job for a generic UNIX Agent.

Job Type Description

Keyword DescriptionHold Places the job in manual hold condition.LateEnd( ) Time/date by which the job should complete to avoid being overdue.LateSub( ) Time/date by which the job should be submitted to avoid being overdue.Pred( ) Names of any predecessor objects. There is no limit to the number of

objects specified here. Job names are in the form nnnn.qqqq for a qualified job, or nnnn for an job without a qualifier. Separate names with blanks or commas.

Priority( ) Priority of the job. This is a number from 0-99. Applies only if using ESP resources.

Process Event processing is required. Applies to links.RelDelay( ) Minimum delay time in minutes to be added to a job after its last

dependency is met.Request Sets the Request attribute—the job must be explicitly requested to run.Resource( ) Resources the job requires to run. Operands are specified in the form

nnn,rrrr where nnn is the numeric quantity, and rrrr is the name of the resource. A resource can be nullified by setting the quantity to 0. If quantity is omitted, the default is 1.

Statements( ) One or more statements that should run as part of the processing when this job is readied. Separate each statement with a semicolon.

Succ( ) Names of any successor objects. There is no limit to the number of objects specified here. Object names are in the form nnn.qqq for a qualified object, or nnn for an object without a qualifier. Separate names with spaces or commas.

Tag( ) Tag for the job.

525

RESUB subverbThe following are the valid data keywords for use with the RESUB subverb.

STATE VerbTells the ESP Workload Manager to change the state of a job. The new state is supplied in the data field. The following are valid data keywords and data for the STATE verb:

Keyword DescriptionFrom( ) Restart point.Jobid( ) Identifier of original job being started.RestartParm( ) Operand string to pass to the restart processor.To( ) Last processing step to rerun.User1( ) User restart variable 1.User2( ) User restart variable 2.User3( ) User restart variable 3.User4( ) User restart variable 4.

Subverb DescriptionActivate Invokes the Activate subroutine of the ESP Workload Manager, after the

state of the job is modified. Do this if the state change could result in a job being readied.

Alert(alertcode|*) Specifies the name of the Alert. Must also supply a monitor point name using the MNPOINT Keyword. The alertcode identifier must have been previously specified using an ALERTDEF command. Alternatively, an asterisk can be used to trigger the same Event which invoked this ESP Procedure.

COMPLETE Changes the state to COMPLETE. All successor jobs are released. No further state messages are accepted. The job can be resubmitted if the application containing it is not yet complete.

Cmpc(code) Specifies the completion code for the job.EXEC Changes the state to EXEC. The anticipated successor state is FAILED or

COMPLETE.FAILED Changes the state to FAILED. The work began processing and may have

partially executed but failed. User action is required to correct the error before resubmission.

Intvrq Specifies that intervention is required for this job.Jobid(id) Indicates a fully qualified job ID in the form JobName/UserName/

JobNumber.Jobno(number) Sets the job number field of the job.

ESPmgr Command: Send Messages to ESP Manager (Recommended)

526

MNPoint(value) Supplies a value for the MNPOINT variable for the execution of an Alert.These monitor points are available:• Job start• Step end• Job end• Overdue• Purge• Post

NoActivate Specifies not to invoke the Activate subroutine for this state change.NoFailed Resets the job from Failed state.NoIntvrq Resets intervention required for a job to no intervention required.NoUpdateATR Specifies that the Application tracking record should not be updated to

disk as a result of this status change message.ProbRec(number) Attaches a problem record number to the object.READY Changes the state to READY. The job has been made ready to run. The

anticipated successor state is EXEC, FAIL, COMPLETE or SUBERROR.RUNNING Changes the state to RUNNING.SetEnd Sets the end time for the job from the timestamp of this message.SetStart Sets the start time for the job from the timestamp of this message.Status(status) Attaches a system status string to this job.SUBDELAY Changes the state to SUBDELAY. Use this when a temporary condition

prevents the initiation of a job. The job will be automatically retried based on a time interval. The next state will be either READY or SUBERROR.

Tag(tag) Identifies a new tag field for this job.User1( ) Assigns a value to ESP Workload Manager symbolic variable 1. Use with

ALERT( ).User2( ) Assigns a value to ESP Workload Manager symbolic variable 2. Use with

ALERT( ).User3( ) Assigns a value to ESP Workload Manager symbolic variable 3. Use with

ALERT( ).User4( ) Assigns a value to ESP Workload Manager symbolic variable 4. Use with

ALERT( ).UserStatus string Attaches a user status string to the object.

Subverb Description

527

Usage notesESP Agent version 2.0 and above for UNIX and Windows NT use the ESPmgr command to perform the same functions that the ESPmsg command performs on the previous OS/400 Agent. To ensure compatibility with previous Agent versions, the ESPmsg command is supported in version 2.0 of the OS/400 Agent. Users are encouraged to use ESPmgr instead, because it is the standard on all other Agent platforms.

ExamplesChanging the state and status of a jobESPmgr "joba/a3.32/main STATE RUNNING Status(Phase 1 Complete)"

In this example, the ESPmgr command changes the status of joba in generation 32 of a3 to a state of RUNNING and attaches a status of 'Phase 1 Complete'.Adding predecessors to a JobESPmgr "joby/payroll.56/main ACTION RESET Pred(job3,job4(U))"

In this example, job3 and job4 are added as predecessors to joby in generation 56 of payroll. Joby requests job4 as an unconditional predecessor, indicating that job4 should release joby even upon an unsuccessful termination.Placing a job on holdESPmgr "program1 ACTION HOLD"

In this example, ESPmgr tells ESP Workload Manager to place the job program1 on hold.

ESPmsg Command: Send Messages to ESP Manager

528

ESPmsg Command: Send Messages to ESP Manager

Sends a message to the ESP Workload Manager from the platform where the agent is running. The message can be used to:• Perform an action• Notify the Manager of a change in state• Respond to a requestThe ESPmsg command can also be used within a program to report the completion of internal processing phases. For example, a long-running program can send intermediate status information to the ESP Workload Manager to be displayed on CSF. The command can also be used to perform many other functions; such as release workload, or request additional workload.

TypeGeneral Command

Entering CommandThe ESPmsg command can be issued via:• The command line• A script or program

SyntaxESPmsg "objectname verb subverb[(keyword)]"

The verb, subverb, and keywords and values differ depending on the verb used.Note: Refer to the specific sections for the verbs ACTION or STATE for more

information.

Operand Descriptionobjectname Indicates the fully qualified name of the jobs to which the command

refers; can be a symbolic variable.

Note: When a command is sending a message regarding itself to the ESP Workload Manager, it can use a period in place of the objectname.

verb Indicates the action to be taken. The possible values are: • “ACTION verb”, see page 529• “STATE Verb”, see page 533

subverb Further defines the action to be taken. keyword Modifies the verb /subverb combination.

529

ACTION verbThe ACTION verb is used to send requests to ESP Workload Manager to perform an action that is specified by the subverb. The following subverbs and associated keywords are valid with the ACTION verb.

Subverb DescriptionBYPASS Turns on the BYPASS indicator to bypass this job.DROPDEP Drops some or all dependencies for the job. DROPDEP may be modified

to drop only selected dependencies when used with data supplied with the keyword PRED.

PRED( )—Enclose the list of dependencies to be dropped, separated by blanks, in parentheses. Omitting the PRED keyword drops all dependencies.

DROPRES Drops some or all resources. DROPRES may be modified to drop only selected resources when used with data supplied with the keyword RESOURCE.

RESOURCE( )—Enclose the list of resources to be dropped, separated by blanks, in parentheses. Omitting the RESOURCE keyword drops all resources.

HOLD Places the specified job on hold.INSERT Inserts a new job in the application. See “INSERT subverb” on page 530

for the list of valid keywords available with the INSERT subverb.READY Places job in Ready state. Drops any dependencies, hold states, or delay

submit times.RELEASE Releases the job from a hold state.REQUEST Turns on the Requested indicatorRESET Resets an attribute, condition or state of a job. See “RESET subverb” on

page 532 for the list of valid keywords available with the RESET subverb.RESUB Schedule the job for resubmission. See “RESUB subverb” on page 533

for the list of valid keywords available with the RESUB subverb.SET variable(value) Sets the variable to the value specified.UNBYPASS Turns off the Bypass indicator. No longer bypass this job. UNREQUEST Turns off the Requested indicator.UNWAIT Do not wait for the completion of a previous generation of this object.

ESPmsg Command: Send Messages to ESP Manager

530

INSERT subverbThe following are the valid data keywords for use with the INSERT subverb.

Keyword DescriptionAbandonDependency( ) Time/date when dependencies are to be dropped.AbandonResource( ) Time/date when resource requirements are to be dropped.AbandonSubmission( ) Time/date when submission of the job is to be abandoned.Appl( ) Name of the application for an external job.Authstr( ) Authorization string associated with an external job.AverageCPU( ) Average CPU time used, in the form mmmss.AverageElapsed( ) Average elapsed time, in the form mmmss.Conditional Conditional job.Doclib( ) Name of the library containing documentation for the job.Docmem( ) Member name of documentation library entry.Dsname( ) Submit data set name.EarlySub( ) Earliest time that a job can be readied, in the form mmss.Espprocfile( ) Name of the library containing the job's definition (ESP

Workload Manager procedure file).External Refers to a job in another application.Hold Place job in manual hold condition.LateEnd( ) Time/date by which job should complete to avoid being

overdue.LateSub( ) Time/date by which the job should be submitted to avoid being

overdue.Manual Manually submitted z/OS job.Pred( ) Names of any predecessor jobs. There is no limit to the number

of jobs specified here. Job names are in the form nnnn.qqqq for a qualified job, or nnnn for a job without a qualifier. Separate names with blanks or commas.

Priority( ) Priority of the job. This is a number from 0-99. Applies only if using ESP resources.

Process Event processing is required. Applies to links.RelDelay( ) Minimum delay time in minutes to be added to a job after its last

dependency is met.Request Sets the Request attribute requiring the job to be explicitly

requested to run.

531

JOB TypeThe following are valid workload object types and their designations:

Resource( ) Resources the job requires to run. Operands are specified in the form nnn,rrrr where nnn is the numeric quantity, and rrrr is the name of the resource. A resource can be nullified by setting the quantity to 0. If quantity is omitted, the default is 1.Scheduled( )—Scheduled time an external job will match this job definition.

Scheduled( ) Scheduled time an external job will match this job definition.Statements( ) One or more statements that should run as part of the processing

when this job is readied. Separate each statement with a semicolon.

Tag( ) Specifies a tag for the job.Type( ) Job type. See “JOB Type”, see page 531 for the list of valid

workload object types and their designations.Subappl( ) Name of the subApplication to which the job belongs.Succ( ) Names of any successor objects. There is no limit to the number

of objects specified here. Object names are in the form nnn.qqq for a qualified object, or nnn for an object without a qualifier. Separate names with spaces or commas.

Keyword Description

Job Type DescriptionAGENT_MONITOR or AM Designates a workload object that monitors the status of an

Agent.APPLEND or AE Designates the last workload object of the Application.AIX_JOB or AX Designates a job for an AIX Agent.AS400_JOB or A4 Designates a job for an OS/400 Agent.DATA_OBJECT or DA Designates a data object.DSTRIG or DS Designates a data-set trigger.FILE_TRIGGER or FM Designates a file trigger on an agent platform.HPUX_JOB or HJ Designates a job for an HPUX Agent.HP3K_JOB or H3 Designates a job for an HP3000 Agent.IRIX_JOB or IR Designates a job for an IRIX Agent.MPEIX_JOB or MP Designates a job for an MPEIX Agent.NCR_JOB or NC Designates a job for an NCR Agent.NT_JOB or NT Designates a job for a Windows NT Agent.OPENVMS_JOB or OV Designates a job for an OpenVMS Agent.

ESPmsg Command: Send Messages to ESP Manager

532

RESET subverbThe following are the valid data keywords for use with the INSERT subverb.

OS2_JOB or O2 Designates a job for an OS/2 Agent.PYRAMID_JOB or PJ Designates a job for a PYRAMID Agent.SAP_JOB or SP Designates a job for an R/3 ERP Systems Agent.SEQUENT_JOB or SQ Designates a job for an HPUX Agent.SUN_JOB or SJ Designates a job for a Solaris Agent.TANDEM_JOB or TA Designates a job for the Tandem NSK Agent.UNIX_JOB or UJ Designates a job for a generic UNIX Agent.

Job Type Description

Keyword DescriptionHold Places the job in manual hold condition.LateEnd( ) Time/date by which the job should complete to avoid being overdue.LateSub( ) Time/date by which the job should be submitted to avoid being overdue.Pred( ) Names of any predecessor objects. There is no limit to the number of

objects specified here. Job names are in the form nnnn.qqqq for a qualified job, or nnnn for an job without a qualifier. Separate names with blanks or commas.

Priority( ) Priority of the job. This is a number from 0-99. Applies only if using ESP resources.

Process Event processing is required. Applies to links.RelDelay( ) Minimum delay time in minutes to be added to a job after its last

dependency is met.Request Sets the Request attribute—the job must be explicitly requested to run.Resource( ) Resources the job requires to run. Operands are specified in the form

nnn,rrrr where nnn is the numeric quantity, and rrrr is the name of the resource. A resource can be nullified by setting the quantity to 0. If quantity is omitted, the default is 1.

Statements( ) One or more statements that should run as part of the processing when this job is readied. Separate each statement with a semicolon.

Succ( ) Names of any successor objects. There is no limit to the number of objects specified here. Object names are in the form nnn.qqq for a qualified object, or nnn for an object without a qualifier. Separate names with spaces or commas.

Tag( ) Tag for the job.

533

RESUB subverbThe following are the valid data keywords for use with the RESUB subverb.

STATE VerbTells the ESP Workload Manager to change the state of a job. The new state is supplied in the data field. The following are valid data keywords and data for the STATE verb:

Keyword DescriptionFrom( ) Restart point.Jobid( ) Identifier of original job being started.RestartParm( ) Operand string to pass to the restart processor.To( ) Last processing step to rerun.User1( ) User restart variable 1.User2( ) User restart variable 2.User3( ) User restart variable 3.User4( ) User restart variable 4.

Subverb DescriptionActivate Invokes the Activate subroutine of the ESP Workload Manager, after the

state of the job is modified. Do this if the state change could result in a job being readied.

Alert(alertcode|*) Specifies the name of the Alert. Must also supply a monitor point name using the MNPOINT Keyword. The alertcode identifier must have been previously specified using an ALERTDEF command. Alternatively, an asterisk can be used to trigger the same Event which invoked this ESP Procedure.

COMPLETE Changes the state to COMPLETE. All successor jobs are released. No further state messages are accepted. The job can be resubmitted if the application containing it is not yet complete.

Cmpc(code) Specifies the completion code for the job.EXEC Changes the state to EXEC. The anticipated successor state is FAILED or

COMPLETE.FAILED Changes the state to FAILED. The work began processing and may have

partially executed but failed. User action is required to correct the error before resubmission.

Intvrq Specifies that intervention is required for this job.Jobid(id) Indicates a fully qualified job ID in the form JobName/UserName/

JobNumber.Jobno(number) Sets the job number field of the job.

ESPmsg Command: Send Messages to ESP Manager

534

MNPoint(value) Supplies a value for the MNPOINT variable for the execution of an Alert.These monitor points are available:• Job start• Step end• Job end• Overdue• Purge• Post.

NoActivate Specifies not to invoke the Activate subroutine for this state change.NoFailed Resets the job from Failed state.NoIntvrq Resets intervention required for a job to no intervention required.NoUpdateATR Specifies that the Application tracking record should not be updated to

disk as a result of this status change message.ProbRec(number) Attaches a problem record number to the object.READY Changes the state to READY. The job has been made ready to run. The

anticipated successor state is EXEC, FAIL, COMPLETE or SUBERROR.RUNNING Changes the state to RUNNING.SetEnd Sets the end time for the job from the timestamp of this message.SetStart Sets the start time for the job from the timestamp of this message.Status(status) Attaches a system status string to this job.SUBDELAY Changes the state to SUBDELAY. Use this when a temporary condition

prevents the initiation of a job. The job will be automatically retried based on a time interval. The next state will be either READY or SUBERROR.

Tag(tag) Identifies a new tag field for this job.User1( ) Assigns a value to ESP Workload Manager symbolic variable 1. Use with

ALERT( )User2( ) Assigns a value to ESP Workload Manager symbolic variable 2. Use with

ALERT( )User3( ) Assigns a value to ESP Workload Manager symbolic variable 3. Use with

ALERT( )User4( ) Assigns a value to ESP Workload Manager symbolic variable 4. Use with

ALERT( )UserStatus string Attaches a user status string to the object.

Subverb Description

535

Usage notesESP Agent version 2.0 and above for UNIX and Windows NT use the ESPmgr command to perform the same functions that the ESPmsg command performs on the previous OS/400 agent. To ensure compatibility with previous agent versions, the ESPmsg command is supported in version 2.0 of the OS/400 agent. Users are encouraged to use ESPmgr instead, because it is the standard on all other agent platforms.

ExamplesChanging the state and status of a jobThis is an example of the ESPmsg command that changes the status of JOBA in generation 32 of APPL3 to a state of RUNNING and a status of Phase 1 Complete:ESPmsg "joba/a3.32/main STATE RUNNING Status(Phase 1 Complete)"

In this example, the ESPmsg command changes the status of joba in generation 32 of Application a3 to a state of RUNNING and a status of Phase 1 Complete.Adding predecessors to a jobESPmsg "joby/payroll.56/main ACTION RESET Pred(job3,job4(U))"

In this example, job3 and job4 are added as predecessors to joby in generation 56 of payroll. Joby requests job4 as an unconditional predecessor, indicating that job4 should release joby even upon an unsuccessful termination.Placing a job on holdThis is an example of the ESPmsg command that passes a message to the Manager to place the job program1 on hold.ESPmsg "program1 ACTION HOLD"

ESPNOMSG Statement: Suppress Responses

536

ESPNOMSG Statement: Suppress Responses

The ESPNOMSG statement is used to issue any ESP command from within an ESP Application and suppress responses from the command. Warnings and errors responses are not suppressed.

SyntaxESPNOMSG command

Usage notesWhen most commands execute, they issue some kind of response. This response is routed to the user who owns the Event. To reduce message clutter, the ESPNOMSG statement can by used to suppress responses, unless a severe error occurs.As part of an Application, you may want to issue ESP commands. This is useful, for example, when you want to manipulate jobs, trigger Events, and perform displays.Use the ESP or ESPNOMSG statement in an Application to issue an ESP command. ESPNOMSG suppresses responses from the command.

Related informationFor information on issuing ESP commands, see the ESP statement.

Examples Define a link to trigger an Event and suppress responseIn the following example, the TRIGGER.EVENT link issues an ESP command to trigger an Event called CYBER.ACCTJOB. The response from the ESP command (EVENT TRIGGERED) is suppressed as a result of specifying ESPNOMSG in front of the ESP TRIGGER command:JOB TRIGGER.EVENT LINK PROCESS RUN DAILY ESPNOMSG TRIGGER CYBER.ACCTJOB ADDENDJOB

Operand Descriptioncommand Any valid ESP command.

537

Complete a task when CICS becomes available and suppress responseIn the following example, when a resource called 'CICS' becomes available, ESP issues an APPLJOB command to complete a task called WAIT4.CICS. After WAIT4.CICS completes, PAYJOB1 is released. The response from the ESP command is suppressed as a result of specifying ESPNOMSG:APPL WAIT4JCLLIB 'CYBER.JCL.CNTL'JOB WAIT4.CICS TASK RUN ANY RELEASE PAYJOB1 RESOURCE (1,CICS) ESPNOMSG AJ WAIT4.CICS COMPLETE APPL(WAIT4.0)ENDJOBJOB PAYJOB1 RUN ANYENDJOB

Insert a job when PAYJOB1 completes and suppress responseIn the following example, when PAYJOB1 successfully completes, an ESP command is issued to insert PAYJOB99 into the current generation of the PAYROLL Application. The response from the ESP command is suppressed as a result of specifying ESPNOMSG:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY RELEASE INSERT.JOB JOB INSERT.JOB LINK PROCESS RUN DAILY ESPNOMSG AJ PAYJOB99 INSERT APPL(PAYROLL.0) ENDJOB

//*ESPSYMBOL Statement: Change Symbol Introducer

538

//*ESPSYMBOL Statement: Change Symbol Introducer

The //*ESPSYMBOL statement is used to change the symbol introducer character, normally the percent sign. The symbol introducer is the character that identifies symbolic variables to ESP. Using the //*ESPSYMBOL statement in JCL you can change the symbol introducer character to identify another character as the symbol introducer character. Additionally, changing the symbol introducer character allows you to use the percent sign in your JCL and not have ESP interpret the percent sign as the symbol introducer character.

TypeControl statement used in JCL.

Syntax//*ESPSYMBOL symbol

Usage notesPlace the character you want to use as the symbol introducer character in column 14, separated from the //*ESPSYMBOL statement by a single blank.If the symbol introducer character is changed, the change remains in effect: • For the rest of the job during Application process mode, meaning that other jobs

are not affected• Until ESP encounters another //*ESPSYMBOL statement.If an individual member contains multiple jobs, the change remains in effect for all jobs within that individual member.

Related informationFor information on changing the symbol introducer using an ESP initialization parameter, refer to the SYMBOL statement in the ESP Workload Manager Installation and Configuration Guide.

Operand Descriptionsymbol Any single alphanumeric or national character.

539

Examples Change symbol introducer to?In the following example, the symbol introducer character is changed from a % to a ?. Subsequent symbol variables reference the ? as the symbol introducer character, and therefore include STEP001 on Mondays://*ESPSYMBOL ?//PAYJOB1 JOB CYB,CLASS=A,MSGCLASS=0?INCLUDE DAY(MONDAY)//STEP001 EXEC PGM=PGM1,PARM='DATE=?ESPSYY?ESPSDDD'?ENDINCL

Change symbol introducer to # then resetIn the following example, the symbol introducer character is changed from a % to a #. Subsequent symbol variables reference the # as the symbol introducer character, and include STEP001 on last workday of the month. The symbol introducer character is then reset to a % to avoid JCL errors in later steps that refer to the % as the symbol introducer character://*ESPSYMBOL #//PAYJOB1 JOB CYB,CLASS=A,MSGCLASS=0#INCLUDE IF(TODAY('LAST WORKDAY OF MONTH'))//STEP001 EXEC PGM=PGM1,PARM='DATE=#ESPSYY#ESPSDDD'#ENDINCL//*ESPSYMBOL %//STEP02 EXEC PGM=PGM2,PARM='%ESPAHH%ESPAMN'

EVENT Command: Start Event Definition

540

EVENT Command: Start Event Definition

The first statement in an Event definition.

TypeEvent definition command.

SyntaxEVENT ID(eventid) [ADD|REPLACE] [CLASS(classname)] [SYSTEM(sysid)] [AUTODELETE] [HOLD(count)] [SUSPEND(count)] [MAXPEND(nn)] [OWNER(userid)] [USER(userid)] [INHERIT_TRIGGER_USER|ITU] [EICLASS(eiclassname)] [MAILBOX(box_name)]

Operand Descriptioneventid The name of the Event. The name format is gggg.dddd, or dddd alone with

gggg being the user/group prefix and dddd being the descriptive name. Both the prefix and the descriptive name should consist of alphanumeric characters, the first of which must be alphabetic. The descriptive name may also contain the underscore '_' as an alphabet extender. The prefix can be up to eight characters long, while the descriptive name has a maximum length of 16 characters.

ADD Indicates this is a new Event. If one already exists with the same name, the new definition is ignored. This is the default.

REPLACE Indicates this is a new Event. If one already exists with the same name, it is to be replaced.

classname Defines to which logical ESP class the Event will belong. If this is omitted, the Event name prefix is used as a class name (up to eight characters).

sysid Indicates the ID of the ESP system to execute the Event. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. If this operand is omitted, the current system is used. To specify that the Event may execute on any one of the systems available, use SYSTEM(-). If the Event invokes an Application, this should specify the ESP system identifier of the master.

541

AUTODELETE Indicates if any members of a PDS required for job submission is not found, (or in the case of PANVALET, is disabled), an error condition is not raised. This means that ESP continues to process the Event as long as at least one of the data sets required for submission of the job is available. However, if all the SUBMIT commands within an Event definition specify deleted or disabled members, then the Event is deleted from the schedule. This is not the default.

HOLD Indicates the Event is placed initially in the held state. Refer to the HOLD command – General.

SUSPEND Indicates the Event is placed initially in the suspended state. Refer to the SUSPEND command – General.

count Sets HOLD or SUSPEND count. If not specified, the default is 1.MAXPEND(nn) Indicates the maximum number of pending signals for the Event.OWNER(userid) Indicates the owner of the Event. If this operand is not specified, the last user

to modify the Event becomes the owner. Ownership in a SAF environment affects only which TSO user gets the failure messages.READ access to SETOWNER.userid is required to define an owner in a SAF system.

USER(userid ) Indicates an overriding RACF user ID for the Event. When the Event executes, that user ID supersedes the one in the Event prefix. READ access to RACID.userid is required to define a user ID.

INHERIT_ TRIGGER_USER

Indicates the user ID of the user triggering the Event should be used for job submission for manually triggered, DSTRIG, and global variable trigger Events. When the Event executes, it automatically takes on the security attributes of the user ID triggering the Event. This operand overrides any USER() value. This operand can be abbreviated to ITU.

EICLASS(eiclass name)

Indicates the Event initiator class, which allows prioritization of Events and workload submission. READ access to EVENTINITCLASS.nnn is required to use this operand.

MAILBOX(box_name)

Specifies the name of a mailbox that contains the destination for messages coming from the EVENT. Mailboxes must be defined in the MAILLIST data set. Refer to the MAILLIST data set section in the ESP Workload Manager Installation and Configuration Guide for information on the MAILLIST data set.

Operand Description

EVENT Command: Start Event Definition

542

Usage notesTo specify OWNER(userid), the user creating or updating the Event must have READ access to prefix.SETOWNER.userid in a SAF system. This is in addition to having UPDATE access to GROUP.groupname to create or update an Event. If either authority is missing, the define/update request fails. Browsing or editing generates the OWNER keyword if it was used when the Event was previously saved. The user may remove the operand and save the Event, in which case ownership reverts to the user’s own id.To specify USER(userid), the person attempting to create or update the Event must have READ access to prefix.RACID.userid in a SAF system. This is in addition to having UPDATE access to GROUP.groupname to create or update an Event. If either authority is missing, the definition or update request fails. Browsing or editing generates the USER keyword if it was used when the Event was previously saved. The user may remove the operand and save the Event, in which case the user ID reverts to the high level qualifier. If INHERIT_TRIGGER_USER is in effect for the Event, or at the system level (RACROUTE ITU operand), that user ID supersedes the one in the Event if the Event is a manually triggered, DSTRIG, and global variable trigger Event (as opposed to being a scheduled Event). The EVENTSAF user exit may override any ESP-selected user ID.It is possible to specify both OWNER and USER for the same Event, in which case the defining user must have:• UPDATE access to GROUP.groupname to create or update an Event• READ access to prefix.SETOWNER.userid• READ access to prefix.RACID.useridIf any one of those checks fails, the definition request fails.You can also define Events using ESP’s ISPF interface—Option E.2 from the ESP main menu.The mailbox feature enables ESP Workload Manager to send messages to all the TSO users and email addresses contained in a mailbox.You can specify a default mailbox in the PROFILE initialization parameter. That default mailbox is used if you do not specify a mailbox in the Event. If you do not define mailboxes in the PROFILE initialization parameter or in the EVENT, ESP Workload Manager sends the messages to the Event owner.To use the mailbox feature, you need to define the mailboxes in the MAILLIST data set and load that data set with the LOADNL command or initialization parameter. Refer to the ESP Workload Manager Installation and Configuration Guide for information on how to define mailboxes and the MAILLIST data set.

543

Related informationFor information on ending an Event definition, see “ENDDEF Command: End Event Definitions” on page 490.For information on deleting an Event definition, see “DELETE Command: Delete Events (General)” on page 294.For information on Events, see the ESP Workload Manager User’s Guide.For information on Event initiators, see the ESP Workload Manager Installation and Configuration GuideFor information on how to determine under which user ID ESP Workload Manager processes the Event, see How ESP Workload Manager determines the user for batch processing in the ESP Workload Manager Security Guide and “RACROUTE Command: Specify Events Processing” on page 1017.

Examples Create an Event to run an ApplicationIn the following example:• The EVENT command starts the Event definition.• The SCHEDULE and INVOKE Event statements define the Event.• The ENDDEF command ends the Event definition.EVENT ID(CYBER.PAY1) SCHEDULE 8AM DAILYINVOKE 'CYBER.ESP.PROCS(PAY1)'ENDDEF

Replace an existing Event and suspend itIn the following example:• The EVENT command starts the Event definition.• The REPLACE operand is needed to replace the Event definition when it is

updated, if one already exists with the same name.• The SUSPEND operand indicates that the Event is to be placed in a suspended

state. It does not execute until resumed.• The OWNER operand indicates that FRED is the owner of the Event.• The SCHEDULE and INVOKE Events statements define the Event.• The ENDDEF command ends the Event definition.EVENT ID(CYBER.PAY2) REPLACE SUSPEND OWNER(FRED)SCHEDULE 9AM DAILYINVOKE 'CYBER.ESP.PROCS(PAY2)'ENDDEF

EVENT Command: Start Event Definition

544

Execute on a specific systemIn the following example:• The EVENT command starts the Event definition.• The SYSTEM operand indicates the system where this Event is to execute.• The CLASS operand indicates to which logical group this Event belongs.• The ITU operand indicates that the user ID of the user triggering this Event should

be used for batch submission. This user ID applies only when the Event is manually triggered.

• The SCHEDULE and INVOKE Events statements define the Event.• The ENDDEF command ends the Event definition.EVENT ID(CYBER.PAY3) SYSTEM(E510) CLASS(PROD) ITUSCHEDULE 9AM DAILYINVOKE 'CYBER.ESP.PROCS(PAY2)'ENDDEF

Specify an initiator classIn the following example, an Event initiator class of 99 is assigned to CYBER.PAYROLL:EVENT ID(CYBER.PAYROLL) EICLASS(99)SCHEDULE 8PM WORKDAYSINVOKE 'CYBER.PROCLIB.CNTL'ENDDEF

Specify a mailboxIn the following example, all messages from the Event are sent to the recipients defined in the mailbox PAYROLL.EVENT ID(CYBER.PAYROLL) EICLASS(99) MAILBOX(PAYROLL)SCHEDULE 8PM WORKDAYSINVOKE 'CYBER.PROCLIB.CNTL'ENDDEF

545

EVENT Statement: Specify the SAP Event to Monitor or Trigger

The EVENT statement specifies the SAP event to monitor or trigger.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within an SAPE_JOB workload object.

SyntaxEVENT ’event_name’ TRIGGER|REGISTER [PARM(event_parameter)] [CONTINUOUS(alert_name)]

Usage notesEVENT is a mandatory statement within an SAPE_JOB workload object.

Operand Descriptionevent_name Specifies name of the SAP event to monitor or trigger. It can be

up to 32 valid SAP characters in length. It is mandatory.TRIGGER|REGISTER Specifies the action to perform.

• TRIGGER—trigger SAP event• REGISTER—monitor for SAP event

PARM(event_parameter) Specifies the name of the event parameter. It can be up to 64 valid SAP characters in length.

CONTINUOUS(alert_name) Specifies the name of the ESP Workload Manager alert to associate with this SAP event. When the SAP event is triggered (raised), the ESP Workload Manager alert will be triggered.

Note: The ALERT operand only applies to the monitoring of SAP events (REGISTER).

It is alphanumeric and can be up to four characters in length. It must start with a character.

EVENT Statement: Specify the SAP Event to Monitor or Trigger

546

ExamplesMonitor for SAP eventIn this example, the SAP event SAPEvent is monitored.APPL EMTESTSAPE_JOB EMTEST AGENT SAPHTAGENT EVENT ‘SAPEvent’ REGISTER PARM(2) RUN DAILYENDJOB

Trigger SAP eventIn this example, the SAP event SAPEvent is triggered.APPL EMTESTSAPE_JOB EMTEST AGENT SAPHTAGENT EVENT ‘SAPEvent’ TRIGGER PARM(2) RUN DAILYENDJOB

547

EVENTCATEGORY Statement: Specify Windows Event Category Within EVENTLOG_MON

The EVENTCATEGORY statement specifies the category of the Event as shown in the Windows Event Viewer.

ApplicabilityESP System Agent for Microsoft Windows, Release 6, used within an EVENTLOG_MON workload object. For more information, see “EVENTLOG_MON Statement: Monitor the Windows Event Log” on page 552.

SyntaxEVENTCATEGORY eventcategory

ExampleIn this example, the Event category of Disk is specified for the Event Log Application, Event type Information, and Event ID equal to 14. For the specified Application, the Event source is Norton AntiVirus. Note: The EVENTSOURCE statement requires single quotes because the text string

contains spaces.EVENTLOG_MON EVLOG.CATEG AGENT R6AGENT EVENTLOG APPLICATION EVENTTYPE INFO EVENTSOURCE 'Norton AntiVirus' EVENTCOMPUTER LLUSER EVENTCATEGORY Disk EVENTDESCRIPTION Norton EVENTID EQ 14 RUN DAILYENDJOB

Operand Descriptioneventcategory The format is case sensitive, any character, and up to 4078

characters in length.

EVENTCOMPUTER Statement: Specify Local Machine for Windows Event Log Within EVENTLOG_MON

548

EVENTCOMPUTER Statement: Specify Local Machine for Windows Event Log Within EVENTLOG_MON

The EVENTCOMPUTER statement specifies the name of the local machine that the Event Log applies to.

ApplicabilityESP System Agent for Microsoft Windows, Release 6, used within an EVENTLOG_MON workload object. For more information, see “EVENTLOG_MON Statement: Monitor the Windows Event Log” on page 552.

SyntaxEVENTCOMPUTER ComputerName

ExampleIn this example, the computer D9GBJG11 is monitored for an Event source of security.EVENTLOG_MON EVLOG.COMP AGENT R6AGENT EVENTLOG Security EVENTTYPE AUDITS EVENTSOURCE Security EVENTCOMPUTER D9GBJG11 EVENTCATEGORY 'System Event' EVENTID GT 0 RUN DAILYENDJOB

Operand DescriptionComputerName The format is case sensitive, any character, and 256 characters in

length.

549

EVENTDESCRIPTION Statement: Specify Windows Event Description Within EVENTLOG_MON

The EVENTDESCRIPTION statement specifies the description of the Event as shown in the Event Viewer.

ApplicabilityESP System Agent for Microsoft Windows, Release 6, used within an EVENTLOG_MON workload object. For more information, see “EVENTLOG_MON Statement: Monitor the Windows Event Log” on page 552.

SyntaxEVENTDESCRIPTION EventDescription

ExamplesExample 1In this example, the Event description must include the words conflict and state as indicated by the plus signs but must exclude the words deny, master, or browser as indicated by the minus sign. The plus sign is the default and its use is optional. EVENTLOG_MON EVLOG.DESCRIP1 AGENT R6AGENT EVENTLOG System EVENTTYPE Error EVENTDESCRIPTION '+conflict +state –deny –master –browser' RUN DAILYENDJOB

Example 2In this example, the Event description must include the words Normal shutdown. This example does not use the plus sign, and by default, the specified words are included in the search.

Operand DescriptionEventDescription The format is case sensitive, any character, and up to 4078

characters in length.

EVENTDESCRIPTION Statement: Specify Windows Event Description Within EVENTLOG_MON

550

EVENTLOG_MON ENLOG.DESCRIP2 AGENT R6AGENT EVENTLOG application EVENTTYPE info EVENTDESCRIPTION 'Normal shutdown' RUN DAILYENDJOB

551

EVENTID Statement: Specify Windows Event ID Within EVENTLOG_MON

The EVENTID statement specifies the Event ID.

ApplicabilityESP System Agent for Microsoft Windows, Release 6, used within an EVENTLOG_MON workload object. For more information, see “EVENTLOG_MON Statement: Monitor the Windows Event Log” on page 552.

SyntaxEVENTID [(operator)] [(id)]

ExampleIn this example, the Agent checks for an Event ID number less than 1. As a result, the job will return from the Application Log the first Application Event available that has Event ID equal to 0.EVENTLOG_MON EVLOG.EVIDT1 AGENT R6AGENT LOGNAME Application EVENTID LT 1 RUN DAILYENDJOB

Operand Descriptionoperator Comparison operators against the value of Event ID.

• EQ—equals the value• LT—less than the value• LE—less than or equal to the value• GT—greater than the value• GE—greater than or equal to the value

id Event ID which the specified operation is carried out on. Format is numeric, up to 10 digits.

EVENTLOG_MON Statement: Monitor the Windows Event Log

552

EVENTLOG_MON Statement: Monitor the Windows Event Log

Monitors the Windows Event Log on the local machine, where the Agent is running. This monitor returns the most recent event available or continuously monitors for events in a particular Windows Event Log.

TypeApplication statement.

ApplicabilityRelease 6 System Agents.

SyntaxRefer to the JOB statement syntax.

Usage notesWindows operating systems record events in three kinds of logs:• Application log—The application log contains events logged by applications or

programs. For example, a database program might record a file error in the application log.

• System log—The system log contains events logged by the Windows 2000 system components. For example, the failure of a driver or other system component to load during startup is recorded in the system log.

• Security log—The security log can record security events such as valid and invalid logon attempts, as well as events related to resource use, such as creating, opening, or deleting files.

For more information on Windows logs, select Start > Settings > Control Panel > Administrative Tools > Event Viewer. Select any of the three log categories and double click to view its property page.To use Windows Event Log monitors, load the workload object module CYBESOLM with the WOBDEF command or with the WOBDEF initialization parameter.

These job-definition statements are associated with the EVENTLOG_MON statement:• EVENTCATEGORY• EVENTCOMPUTER• EVENTDESCRIPTION

553

• EVENTID• EVENTLOG• EVENTSOURCE• EVENTTYPEThe short form of EVENTLOG_MON is LM.Also refer to the JOB statement usage notes.

ExamplesExample 1In this example, a system event log is monitored for an event type of WARN, event source of MrxSmb, and event category of None.LM EVENTLOG.TEST1 AGENT R6AGENT EVENTLOG System EVENTTYPE WARN EVENTSOURCE MrxSmb EVENTCATEGORY None RUN DAILYENDJOB

Example 2In this example, the event log for Applications is monitored continuously, and an Alert ELOG will be issued for all instances of an event type of INFO, where the event source is LLDSAPNT223, the event description contains the word started, and the event ID is less than or equal to 4000.EVENTLOG_MON EVENTLOG.TEST2 AGENT R6AGENT EVENTLOG Application CONTINUOUS(ELOG) EVENTTYPE info EVENTCATEGORY None EVENTSOURCE LLDSAPNT223 EVENTDESCRIPTION started EVENTID LE 4000 RUN DAILYENDJOB

EVENTOPT Command: Allow Write to Operator

554

EVENTOPT Command: Allow Write to Operator

Allow or disallow the issue of Write to Operator (WTO) operations from within an Event. EVENTOPT also allows or disallows the use of system commands from within an Event. EVENTOPT is normally used as an initialization parameter.

TypeGeneral command.

AuthorityYou require OPER authority to issue the EVENTOPT command.

SyntaxEVENTOPT [WTO|NOWTO] [VS|NOVS]

Usage notesThe EVENTOPT command supersedes the EVENTWTO command.If you specify no operands with the EVENTOPT command, the current status is displayed.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.

Operand DescriptionWTO Allows Write to Operator from within an Event. This is the defaultNOWTO Disallows Write to Operator from within an Event.VS Allows the use of z/OS commands from within an Event. This is the

default.NOVS Disallows the use of z/OS commands from within an Event.

555

Example Disallow WTOs and system commandsEVENTOPT NOWTO NOVS

EVENTSET Command: Define Event Data Set

556

EVENTSET Command: Define Event Data Set

Defines or alters the definition of an Event data set.

TypeGeneral command.

AuthorityYou require OPER authority to issue the EVENTSET command.

SyntaxEVENTSET eventdsid [DSNAME(dsname)] [NEWDSNAME(newdsname)] [BACKUPDSNAME(backupdsname)|NOBACKUPDSNAME] [SCANTIME(schedule)] [DEFINE|DELETE|OPEN|CLOSE|SET|FLUSH] [SHR|NOSHR] [JOURNAL|NOJOURNAL] [BUILDSCHED]

Operand Description

eventdsid Indicates a unique identifier of up to eight characters.dsname Indicates the name of a VSAM KSDS defined with the right attributes.newdsname Indicates a VSAM KSDS similar to the above.backupdsname Indicates a non-VSAM sequential data set.NOBACKUPDSNAME Used to remove the backupdsname, if already specified.schedule Indicates a time schedule using the same syntax as the ESP command

processor schedule statements. If the text string contains blanks or commas, it should be enclosed within quotes.

DEFINE Indicates a new Event data set is being defined. If not specified, DEFINE is the default.

DELETE Indicates the Event data set is deleted. The associated VSAM data set is not deleted—only the logical Event ID is deleted from ESP. The Event data set must be closed first. DELETE must be issued from a system console.

OPEN Indicates an Event data set is to be reopened.CLOSE Indicates an Event data set is to be closed and de-allocated from ESP.

557

Usage notesUse this command to define and initialize an Event data set. Use the DEFINE keyword along with DSNAME and SCANTIME operands. The identifier is the permanent name to be associated with that logical entity.When a user or group prefix is defined, an Event data set is assigned to it. The assignment is the logical identifier, rather than the actual data set name. This allows the data set name to be changed, or a new data set to be assigned at a later time.The Event data set is scanned at regular intervals to produce a schedule. This is normally done at 24 hour intervals. If the SCANTIME keyword is omitted, the default is '6 am daily'. If a backup data set is specified, the backup is performed automatically while the schedule scan is taking place.The OPEN and CLOSE options are used when external manipulation of the data set is necessary. For example, if the data set is to be renamed or restored from a backup, these steps should be followed:1. Issue the EVENTSET eventdsid CLOSE command.2. Rename the data set or perform any other necessary function.3. Issue the EVENTSET eventdsid OPEN command. If the data set has been

renamed or copied to another data set, you can specify a new name through the NEWDSNAME operand.

When ESP encounters an I/O error on an Event data set, it issues an error message and closes the data set. Remedial action can then take place. When the problem is corrected, the EVENTSET OPEN command causes ESP to resume operation with the data set.

SET Indicates an existing specification is changed without the need to open or close the data set.

FLUSH Indicates all prior schedule requests for Events on the deferred queue are flushed. Succeeding schedule requests are honored.

SHR Indicates the data set is to be shared.NOSHR Indicates the data set is not to be shared. This is the default.JOURNAL Indicates a record be written to SMF each time an Event is defined,

updated or deleted (refer to SMFREC initialization parameter).NOJOURNAL Indicates no records be written to SMF when the Event file is updated.

Use this keyword to cancel a previous JOURNAL request. This is the default.

BUILDSCHED Indicates the Time Driven Requests (TDRs) are built.

Operand Description

EVENTSET Command: Define Event Data Set

558

Any Events scheduled for execution while the corresponding data set is in the suspended state are queued for deferred execution. When the data set is available again, execution can resume. Activity on other data sets can proceed as normal.

Related informationFor information on the EVENTSET initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.For information on Events, see the ESP Workload Manager User’s Guide.

Examples Define shared Event data setIn the following example, a new shared Event data set called EVENT1 is defined. The actual VSAM data set name is ESP.EVENT1, and the backup data set is ESP.BACKUP.EVENT1, which is used every morning at 5:00 am. when EVENT1 is scanned:EVENTSET EVENT1 DEFINE DSNAME(ESP.EVENT1)-SCAN('5AM DAILY') BACKUP(ESP.BACKUP.EVENT1) SHR

Close and deallocate EventIn the following example, EVENT1 is closed and deallocated from ESP:OPER EVENTSET EVENT1 CLOSE

Write no records to SMFIn the following example, no recordsare written to SMF when the Event file is updated:OPER EVENTSET EVENT1 SET NOJOURNAL

559

EVENTSOURCE Statement: Specify Windows Event Source Within EVENTLOG_MON

The EVENTSOURCE statement specifies the source of the Event as displayed in the Event Viewer for the Event Log.

ApplicabilityESP System Agent for Microsoft Windows, Release 6, used within an EVENTLOG_MON workload object. For more information, see “EVENTLOG_MON Statement: Monitor the Windows Event Log” on page 552.

SyntaxEVENTSOURCE sourcename

ExampleIn this example, the Event source is Service Control Manager. Since this text contains spaces, single quotes are used.EVENTLOG_MON EVLOG.SOURCE AGENT R6AGENT EVENTLOG System EVENTTYPE ERROR EVENTSOURCE 'Service Control Manager' RUN DAILYENDJOB

Operand Descriptionsourcename The format is case sensitive, any character, and up to 256 characters

in length.

EVENTTYPE Statement: Specify Windows Event Type Within EVENTLOG_MON

560

EVENTTYPE Statement: Specify Windows Event Type Within EVENTLOG_MON

The EVENTTYPE statement specifies the Event type to monitor in the Event Log.

ApplicabilityESP System Agent for Microsoft Windows, Release 6, used within an EVENTLOG_MON workload object. For more information, see “EVENTLOG_MON Statement: Monitor the Windows Event Log” on page 552.

SyntaxEVENTTYPE type

ExamplesExample 1In this example, the Event type is INFO.EVENTLOG_MON EVLOG.INFOMON AGENT R6AGENT EVENTLOG Application EVENTTYPE INFO EVENTSOURCE Userenv EVENTCOMPUTER LLUSER EVENTCATEGORY None EVENTID EQ 1000 RUN DAILYENDJOB

Operand Descriptiontype • ERROR

• WARN• INFO• AUDITS (for Audit success)• AUDITF (for Audit failure)

561

Example 2In this example, the security log is monitored continuously for a successful audit of a security access attempt. The Event category is System Event, the term succeeded is excluded, but the words Audit and log are included in the Event description. EVENTLOG_MON EVENTMON.CONT2AGENT R6AGENTEVENTLOG Security CONTINUOUS(ELOG)EVENTTYPE AUDITSEVENTCATEGORY 'System Event'EVENTDESCRIPTION '-succeeded +Audit log'RUN DAILY

ENDJOB

%EXCLUDE Statement: Request Exclusion of JCL

562

%EXCLUDE Statement: Request Exclusion of JCL

The %EXCLUDE statement requests selective exclusion of JCL and DATA based on criteria such as time, date, day of the week and Event ID, or a combination of these operands. The %EXCLUDE statement is used to exclude portions of JCL or to exclude control statements from a symbolic variable library.

TypeESP control statement used in JCL and symbolic variable library statements.

Syntax%EXCLUDE [FROM(fromdate)] [TO(todate)] [DAY(dayofweek[,dayofweek]...)] [EVENT(eventid)] [IF(expression)] [COPYJCL]

Usage notesThe %EXCLUDE statement must start in Column one. If you want to use a statement with the characters %EXCLUDE starting in column one, but have it treated as data rather than a control statement, code %%EXCLUDE. The first percent sign is removed.

Operand Description

fromdate Indicates a time and date specification in any format that is valid in a schedule statement.

todate Indicates a time and date specification in any format that is valid in a schedule statement. If no time is specified, it does not include this day.

dayofweek Indicates a valid day of week name, which can be abbreviated to the first three characters. Several day of week names can be specified, separated by blanks or commas.

eventid Indicates a valid Event name, which can contain the prefix and descriptive name, or just the descriptive name of the Event. If the prefix is omitted, the prefix of the current Event is assumed. Several Event IDs can be specified, separated by blanks or commas.

expression Value of a logical expression.COPYJCL Indicates that the exclusion should apply to the copy of the JCL

written to a library as a result of the COPYJCL statement. Applies to JCL tailoring only, and not symbolic variable libraries.

563

The %EXCLUDE statement can be continued onto a second line by placing a '+' or '-' on the last non-blank character of the line. A '+' leading blanks from the next line, whereas a '-' does not. Only one continuation per statement is allowed.The scope of an %EXCLUDE statement excludes data until one of the following statements is encountered: • %EXCLUDE statement• %INCLUDE statement• %ENDEXCL statement• %ENDINCL statement.If no operands are specified, the data following the %EXCLUDE statement is always excluded.If you specify a FROM date but no TO date, a TO date of January 1st 2042 is assumed. Similarly, if you omit a FROM date, a date of January 1st 1900 is assumed.If no time is specified, 00:00 is assumed for the FROM and TO operands. The FROM and TO operands are based on the scheduled date.ESP decides what to exclude in the JCL when it submits the job.Note: Before using the %EXCLUDE statement, check with your system

administrator to ensure no changes were made during your ESP installation that affect the way ESP recognizes these statements. For example, another product may make conflicting use of these terms, in which case your system administrator can change them.

Related informationFor information on selectively including JCL and data, see the %INCLUDE state-ment.

For information on ending the selective exclusion of JCL and data, see the %ENDEXCL statement.For information on selectively excluding JCL, see the CHECKEXC statement.

%EXCLUDE Statement: Request Exclusion of JCL

564

Examples Exclude data on MondaysIn the following example, the value of PARM resolves to 'ABC' every day except Mondays:%EXCLUDE DAY(MONDAY)PARM='ABC'%ENDEXCL

Exclude DD statement on MondaysIn the following example, DD statement INPUT05 is excluded on Mondays if the Event that submitted the job is called CYBER.PAYROLL:%EXCLUDE DAY(MONDAY) EVENT(CYBER.PAYROLL)//INPUT05 DD DSN=CYBER.INPUT.DATA,DISP=SHR%ENDEXCL

Create modified copy of JCLIn the following example, ESP modifies a copy of the JCL that is written to the COPYJCL library to include a restart step on the job card:%EXCLUDE COPYJCL//PAYJOB1 JOB CYB,CLASS=A,MSGCLASS=S%INCLUDE COPYJCL//PAYJOB1 JOB CYB,CLASS=A,MSGCLASS=S,RESTART=STEP002%ENDINCL

Exclude specific stepsIn the following example:• STEP1 executes whenever ESP submits the job• STEP2 is excluded when the actual and scheduled dates are equal• STEP3 is excluded when the actual time is greater than 07.59.00 • STEP4 is excluded from May 1, 1997 to midnight May 4, 1997. This is based on

the scheduled date.• STEP5 is excluded if the actual hour is between 8 am and 2 pm and the scheduled

day is Wednesday.

565

//CYBERJOB JOB CYB999,'FRED',CLASS=A,MSGCLASS=S//STEP1 EXEC PGM=IEFBR14%EXCLUDE IF(ESPSDATE=ESPADATE)//STEP2 EXEC PGM=PGM1%EXCLUDE IF(ESPATIME GT 07.59.00)//STEP3 EXEC PGM=PGM2%EXCLUDE FROM('MAY 1,1997') TO('MAY 5,1997')//STEP4 EXEC PGM=PGM3%EXCLUDE IF(ESPAHH GE '08' AND ESPAHH LE '14' AND -TODAY('WED'))//STEP5 EXEC PGM=PGM4%ENDEXCL

Exclude if CYCLE_NUMBER is 9The following example requests exclusion if the value of CYCLE_NUMBER is equal to 9:%EXCLUDE IF(CYCLE_NUMBER=9)

Exclude at certain timeThe following example requests exclusion if the actual hour is greater than 09 and today is not Friday:%EXCLUDE IF(ESPAHH GT '09' AND TODAY('NOT FRIDAY'))

Exclude if started task activeThe following example requests exclusion if a started task called CICSPROD is active:%EXCLUDE IF(ACTIVE('CICSPROD'))

Exclude if last day of yearThe following example requests exclusion if today is the last day of the year:%EXCLUDE IF(TODAY('LAST DAY OF YEAR'))

EXIT Command: Establish User Exits

566

EXIT Command: Establish User Exits

Activates an ESP user exit.

Where definedMaster

Syntax EXIT {FUNCTION(exittype)} {MODULE(modulename)} [INIT] [TERM]

Operand Descriptionexittype Specifies the logical name of the exit point. Specify one of the

following:

• STARTUP• SHUTDOWN• WARMSTART• COLDSTART• DUEOUT• JOBPSWD• EVENTDEF• EVENTEXEC• JCLSCAN• USERSEND• VSCMD• EVENTSAF• JOBENDNOTIFY.

modulename Specifies the name of the load module to be invoked.INIT Indicates the EXIT will execute immediately upon initialization

or when submitted, as well as every time the specified function occurs.

Note: If both the INIT and TERM subparameters are used, enter them in the same command, separated by a comma.

567

Usage notesThe load module should be in a library that is accessible to the ESP subsystem. It should be re-entrant, or at least re-usable. If the same load module name is specified on more than one exit statement, the same physical load module is used. The load macro is issued only once. When the module is invoked because of the INIT option, the subfunction code CXDSFUNC in the common exit data area is set to CXDINIT (X'01').

The EXIT command is cumulative: if you issue it twice with different modules, both modules will get executed, in the order in which they have been defined.

Example • Two modules, ESPUSRX1 and ESPUXDUE, are loaded.• On loading ESPUXDUE, ESP invokes it for initialization. • After the parameter scan is complete, the module ESPUSRX1 is invoked by the

STARTUP exit. It is given a chance to terminate ESP processing. • If a cold start is performed, the module ESPUSRX1 is invoked again. • Each time a job is overdue, ESP invokes the module ESPUXDUE. EXIT FUNCTION(STARTUP) MOD(ESPUSRX1)EXIT FUNCT(COLDSTART) MOD(ESPUSRX1)EXIT FUNC(DUEOUT) MOD(ESPUXDUE) INIT

TERM Indicates the EXIT will execute when ESP is being shutdown, as well as every time the specified function occurs. During the shutdown the EXIT will execute whether the functional condition occurred or not.

Note: If both the INIT and TERM subparameters are used, enter them in the same command, separated by a comma.

Operand Description

EXIT Statement: Quit ESP Procedures

568

EXIT Statement: Quit ESP Procedures

The EXIT statement is used to quit from your current point in an ESP Procedure.

TypeControl Language (CLANG) statement.

SyntaxEXIT

Usage notesUse EXIT to quit from your current point in a Procedure. ESP continues to process pending requests up to the point at which you use EXIT. ESP also processes any action statements in the calling Event, or other ESP Procedures invoked in the same Event. ESP ignores EXIT statements within the scope of a JOB statement during Application generation. During Application processing, EXIT within the scope of a JOB statement causes ESP to process all statements up to the EXIT and submit the job.

Related informationFor information on quitting an entire process and the Event that invoked it, see the QUIT statement.For information on using ESP’s Control Language in Procedures, see the ESP Workload Manager User’s Guide.

Examples Invoke an alternative Procedure and exitIn the following example, if today is December 31, ESP invokes an alternative ESP Procedure called 'PROD.PROC.CNTL(YEPAY)' and then exits. On all other days that this Application is invoked, the regular ESP Procedure is invoked:PAYROLL:ESPPROCIF TODAY('DEC 31') THEN –DO INVOKE 'CYBER.PROC.CNTL(YEPAY)' EXITENDDO/* REGULAR PROCEDURE */

If CICS active, tell operator to shut it downIn the following example, if CICS is active on the current system, ESP jumps to the label called STOP. ESP issues the operator command, schedules re–execution in five minutes, and exits this Procedure.

569

If CICS is not active on the current system, ESP jumps to the label called GO and issues a command to trigger an Event:IF ACTIVE('CICS') THEN JUMPTO STOPELSE JUMPTO GOSTOP:VS 'F CICS,SHUTDOWN'REEXEC IN(5)EXITGO:VS 'F ESP,TRIGGER PROD.NIGHTLY'

If today is Christmas, exitIn the following example:• If today is CHRISTMAS, ESP quits the ESP Procedure and no instructions are

processed• If today is not CHRISTMAS but it is a holiday, ESP sends a message and exits the

Procedure at that point• If none of the above conditions are true, ESP sends a message indicating it will

continue processing.IF TODAY('CHRISTMAS') THEN QUITIF TODAY('HOLIDAY') THEN DO SEND 'NO WORK TODAY' U(BOSS) EXITENDDOSEND 'LET US CONTINUE PROCESSING' U(CYB01)

If today is Friday, exitIn the following example, if today is FRIDAY, ESP sends the message and exits the ESP Procedure at that point:IF ESPSDAY = 'FRIDAY' THEN DO SEND 'NO PROCESSING TODAY' U(USR01) EXITENDDO

Using EXIT and QUITIn the following example, when the PAYROLL Application is generated on a Monday:• PAYJOB1 is submitted• PAYJOB2 is not submitted and receives an error.

EXIT Statement: Quit ESP Procedures

570

APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYS RELEASE PAYJOB2 IF TODAY('MONDAY') THEN - EXITENDJOBJOB PAYJOB2 RUN WORKDAY IF TODAY('MONDAY') THEN - QUITENDJOB

The following is an example of the CSF display when the above Application is generated:ESP Consolidated Status: View PAYROLL -- Row 1 of 2, Col 1COMMAND ===> SCR ===> PAGE Jobname APPL PNODE STATUS___ PAYJOB1 PAYROLL COMPLETE COMPLETED AT 13.14 21 APR___ PAYJOB2 PAYROLL SUBERROR Submit Error, Quit

571

EXITCODE Statement: Identify Failures by Exit Code

Specifies exit codes that indicate the success or failure of a command. If EXITCODE is not specified, a command is considered to have completed successfully only when a return code of zero is issued.

TypeApplication statement

Syntax EXITCODE code [SUCCESS|FAILURE]

Usage notesUse the EXITCODE statement within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition to apply to the entire Application.To return a code other than 0, or to return a range of codes when a command completes successfully, you must specify the exit code as such in the job-definition statement. When specifying multiple exit codes, the most specific criteria should be entered first, followed by the ranges. (See the following example.)

ExampleUsing multiple EXITCODE statementsThis is an example of the EXITCODE statement:EXITCODE 19 FAILUREEXITCODE 0-9999 SUCCESS

In this example, an exit code of 19 is treated as a command failure. All other exit codes in the range from 0 to 9999 indicate a successful command completion.

Operand Descriptioncode A numeric code or range of codes, or an exit code string.SUCCESS Issue the code if the command completes successfully. The default

setting is 0=success. Any other number = failure. Mutually exclusive with FAILURE.

FAILURE Issue the code if the command does not complete successfully. Mutually exclusive with SUCCESS.

EXPECT Command: Expect Events to Execute

572

EXPECT Command: Expect Events to Execute

Identifies when an Event is expected to execute. Use this in Events without SCHEDULE statements if you want the Event’s activities reflected when creating scheduled activity reporting.

TypeEvent definition command.

SyntaxEXPECT criteria

Usage notesIf you want to display Events that do not have SCHEDULE commands, such as Events triggered by data set activity, you can use the EXPECT subcommand.If an Event has not triggered by the expected time, the Event continues to wait.If you trigger an Event containing an EXPECT command, with the REPLACE option, ESP calculates the next expected execution of the Event.

Related informationFor information on scheduling criteria, see the ESP Workload Manager User’s Guide.

For information on Events, see the ESP Workload Manager User’s Guide.

For information on creating schedule activity reports, see the ESP Workload Manager User’s Guide.For information on displaying the schedule, see the LISTSCH command.

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time.

573

Example Expect data set trigger Event at 10 amIn the following example, this Event does not have a SCHEDULE statement because it is triggered by data set activity and is not reflected in either a scheduled activity report or on a LISTSCH command. The EXPECT command ensures that CYBER.PAYJOB is reflected when scheduled activity reports are produced and when the schedule is listed:EVENT ID(CYBER.PAYJOB)EXPECT 10AM WORKDAYSDSTRIG CYB.INPUT.DATA ANYCLOSESUBMIT 'CYB.JCL.CNTL(PAYJOB1) ENDDEF

EXPEDITE Command: Define or Alter Expedite Policy

574

EXPEDITE Command: Define or Alter Expedite Policy

EXPEDITE is relevant only with the ESP Workload Manager High Performance Option (HPO).The EXPEDITE command is used to define or alter an Expedite Policy.An Expedite Policy specifies criteria that must be met for a job in an ESP Application to be automatically expedited. For information on the Expedite feature, see the ESP User’s Guide.The Expedite Policy specifies how a job’s job priority should be increased. The criteria are OVERDUE (the job’s job start or end time is overdue) and/or CRITICAL_PATH (the job is on the critical path). OVERDUE and CRITICAL_PATH are EXPEDITE command keywords.

TypeYou require OPER authority to issue the EXPEDITE command.

SyntaxThe syntax of the EXPEDITE command is:

EXPEDITE name [ADD|ALTER|DELETE|LIST|HELP] {[OVERDUE|NOOVERDUE]} {[CRITICAL_PATH|NOCRITICAL_PATH]} ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ {ALL|ANY} [CLASS(class)|NOCLASS] [PRIORITY(priority)|NOPRIORITY] [START|NOSTART] [PERFORM(pgn)|NOPERFORM] [SRVCLASS(srvclass)|NOSRVCLASS] [ESP_PRIORITY(nn)|NOESP_PRIORITY] ¯¯¯¯¯¯¯¯¯¯¯¯¯¯

Operand DescriptionEXPEDITE Lists all Expedite Policies.name Specifies a one to eight character Expedite Policy name. Each character must

be either alphanumeric, a national character ($ # @), or an underscore (_). It cannot be OFF.

ADD Requests that a new Expedite Policy be added.ALTER Requests an Expedite Policy be changed.DELETE Indicates an Expedite Policy will be deleted.

575

LIST Used to display an Expedite Policy. This is the default. You can specify an individual Expedite Policy name, or you can list all policies, for example:EXPEDITE nameorEXPEDITE

Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

HELP Displays the syntax of the EXPEDITE command.OVERDUE Specifies that, if a job under ESP’s control is overdue, and all other possible

expedite criteria are met, then it is eligible to be expedited. It is valid for the ADD and ALTER options, and ignored in the DELETE and LIST options.

NOOVERDUE Specifies that an overdue condition for a job in an ESP Application should not be used as a criterion to expedite a job. It is valid for the ALTER option, and ignored in the ADD, DELETE, and LIST options.

CRITICAL_ PATH

Specifies that, if a job in an ESP Application is on the critical path and all other possible expedite criteria are met, then it is eligible to be expedited. It is valid for the ADD and ALTER options and ignored in the DELETE and LIST options.

NOCRITICAL_ PATH

Specifies that presence on the critical path of a job in an ESP Application should not be considered a criterion for determining whether or not a job is eligible for expediting. It is valid for the ALTER option and ignored in the ADD, DELETE, and LIST options.

ALL Specifies a job in an ESP Application will be expedited if all the criteria specified in the Expedite Policy are met. If ALL or ANY are not specified in the ADD option, then ALL is the default. ALL is valid for the ADD and ALTER options and ignored in the DELETE and LIST options.

ANY Specifies a job in an ESP Application will be expedited if any criterion specified in the Expedite Policy is met. If ALL or ANY are not specified in the ADD option, then ALL is the default. ANY is valid for the ADD and ALTER options and ignored in the DELETE and LIST options.

CLASS(class) Specifies the class of a job waiting for execution should be changed if the job is expedited. It is valid for the ADD and ALTER options, and ignored in the DELETE and LIST options.

NOCLASS Specifies the class of a job in an ESP Application, waiting for execution, should not be changed if the job is eligible to be expedited. It is valid for the ALTER option and ignored in the ADD, DELETE, and LIST options.

Operand Description

EXPEDITE Command: Define or Alter Expedite Policy

576

PRIORITY(priority)

Specifies the priority of a job in an ESP Application, waiting for execution, should be changed if the job is expedited. It is valid for the ADD and ALTER options, and ignored in the DELETE and LIST options. The value of priority is within the range 1-15.

NOPRIORITY Specifies the priority of a job in an ESP Application, waiting for execution, should not be changed if the job is eligible to be expedited. It is valid for the ALTER option and ignored in the ADD, DELETE, and LIST options.

START Specifies that a job in an ESP Application, waiting for execution, should be unconditionally started (initiated) if it is expedited. The START option is only supported in OS/390 V2R4 or later for JES2 systems, and OS/390 V2R8 or later for JES3 systems. START requires the system be in IBM WLM goal mode, and the job must be in a WLM- managed job class queue. The job can be changed to a WLM-managed job class queue using the CLASS operand.

NOSTART Specifies that a job in an ESP Application, waiting for execution, should not be unconditionally started (initiated) if it is eligible to be expedited. It is valid for the ALTER option and ignored in the ADD, DELETE, and LIST options.

PERFORM(pgn) Specifies the performance group of a job, in an ESP Application, executing on a system in IBM WLM compatibility mode should be changed if the job is expedited. It is valid for the ADD and ALTER options and ignored in the DELETE and LIST options. If a job is on the local JES node and the Expedite Policy specifies both the PERFORM and the SRVCLASS operands, the job is assumed to also be on the local sysplex. An IBM WLM mode query is issued to determine if the system the job is on is in IBM WLM compatibility mode or IBM WLM goal mode:

• If the system is in compatibility mode, PERFORM is used. • If the system is in goal mode, SRVCLASS is used. If the job is on a remote JES node and the Expedite Policy specifies both the PERFORM and SRVCLASS operands, SRVCLASS is used.

NOPERFORM Specifies the performance group of a job in an ESP Application, executing on a system in IBM WLM compatibility mode, should not be changed if the job is eligible to be expedited. It is valid for the ALTER option and ignored in the ADD, DELETE, and LIST options.

Operand Description

577

SRVCLASS(srvclass)

Specifies that the service class of a job, in an ESP Application, executing on a system in IBM WLM goal mode should be changed if the job is expedited. It is valid for the ADD and ALTER options, and is ignored in the DELETE and LIST options. If a job is on the local JES node and the Expedite Policy specifies both the PERFORM and the SRVCLASS operands, the job is assumed to also be on the local sysplex. An IBM WLM mode query is issued to determine if the system the job is on is in IBM WLM compatibility mode or IBM WLM goal mode:

• If the system is in compatibility mode, PERFORM is used. • If the system is in goal mode, SRVCLASS is used. If the job is on a remote JES node and the Expedite Policy specifies both the PERFORM and SRVCLASS operands, SRVCLASS is used.

NOSRVCLASS Specifies the service class of a job in an ESP Application, executing on a system in WLM goal mode, should not be changed if the job is eligible to be expedited. It is valid for the ALTER option and ignored in the ADD, DELETE, and LIST options.

ESP_PRIORITY (nn)

This operand is used for a job that is not yet submitted. The variable is a number within the range 1-99.ESP_PRIORITY allows for a dynamic change to the ESP priority of a job waiting for ESP resources. This change in ESP priority may occur any time after the ESP Application has been generated and before the job is submitted. All changes of ESP priority are recorded in the audit log.It is valid for the ADD and ALTER options and ignored in the DELETE and LIST options.

NOESP_ PRIORITY

This operand is used for a job that is not yet submitted. Indicates ESP will not change the job ESP priority, as part of the Expedite Policy function. It is valid for the ALTER option and ignored in the ADD, DELETE, and LIST options.

Operand Description

EXPEDITE Command: Define or Alter Expedite Policy

578

Expedite ActionsThe methods of accelerating a job are known as Expedite Actions.The following Expedite Actions are available for submitted jobs that are not yet executing. In this case, the objective of a job expedite is to initiate the job as soon as possible or make it run as quickly as possible when it does start.

The following Expedite Actions are available for executing jobs. In this case, the objective of a job expedite is to increase the job’s job dispatching priority.

The following Expedite Action is available for a job that is not yet submitted.

Related informationFor information on the EXPEDITE initialization parameter, see the ESP Installation and Configuration Guide.

Examples:The following command defines an Expedite Policy, called POLICY_1, that specifies a job in an ESP Application associated with the Expedite Policy, be expedited if its start or end time is overdue. If the job is expedited while it is waiting for execution, its execution queue priority will be set to 15. If the job is expedited while the job is executing, its service class will be changed to JES_FAST.

Option Action1 Change the job JES execution class, specified by the EXPEDITE

CLASS(class) operand.2 Change (increase) the job priority on the JES execution queue, specified

by the EXPEDITE PRIORITY(priority) operand.3 Start the job immediately, specified by the EXPEDITE START operand.

Option Action1 Change the job service class, specified by the EXPEDITE

SRVCLASS(srvclass) operand. This requires the system be in IBM WLM goal mode.

2 Change the job performance group, specified by the EXPEDITE PERFORM(pgn) operand. This requires the system be in IBM WLM compatibility mode.

Option Action1 Change the ESP priority of a job waiting for ESP resources dynamically.

This is specified by the ESP_PRIORITY operand.

579

EXPEDITE POLICY_1 ADD OVERDUE PRIORITY(15) + SRVCLASS(JES_FAST)

If the following command is then issued after the previous one, a job in an ESP Application associated with Expedite Policy POLICY_1 will be expedited if its start time or end time is overdue and it is on the critical path. If the job is expedited while it is waiting for execution, its job class will be set to F. It will then be started (initiated), provided F is an IBM WLM-managed job class queue. If the job is expedited while the job is executing, its service class will be changed to JES_FAST.EXPEDITE POLICY_1 ALTER CRITICAL_PATH NOPRIORITY + CLASS(F) START

The following command has the same effect as issuing the previous two in succession:EXPEDITE POLICY_1 ADD OVERDUE CRITICAL_PATH +CLASS(F) START SRVCLASS(JES_FAST)

EXPEDITE Statement: Associate ESP Expedite Policy

580

EXPEDITE Statement: Associate ESP Expedite Policy

The EXPEDITE Application statement is used to associate an ESP Expedite policy with an ESP Application. When EXPEDITE is specified within the scope of a job in the Application, it designates the Expedite policy for that job only. When EXPEDITE is specified outside the scope of any job in the Application, it designates the default Expedite policy for that Application.

TypeHPO.

Security considerationYou must have authorization to use the EXPEDITE statement. For more information, see the SAF resource name EXPEDITE in the ESP Workload Manager Security Guide.

SyntaxEXPEDITE name|OFF

Usage notesFor more information related to the EXPEDITE statement, refer to the following:• EXPEDITE Initialization Parameter: Define an Expedite Policy in the Installation

and Configuration Guide• EXPEDITE Command: Define or Alter Expedite Policy in the Reference Guide

Examples For this example, the following Expedite policy definitions exist:EXPEDITE FAST ADD OVERDUE PRIORITY(15) SRVCLASS(FAST)EXPEDITE SUPER ADD OVERDUE START SRVCLASS(SUPER)

Example Application:APPL DAILYRUNJCLLIB 'DEPT01.JCLLIB'EXPEDITE FAST

JOB JOB001

Operand Descriptionname Specifies a 1-8 character Expedite policy name.

OFF Indicates no Expedite policy will be associated with the Application or with a job inside the Application.

581

DUEOUT EXEC REALNOW PLUS 10 MINUTES RELEASE JOB002 RUN DAILYENDJOBJOB JOB002 EXPEDITE OFF RELEASE JOB003 RUN DAILYENDJOBJOB JOB003 EXPEDITE SUPER RUN DAILYENDJOBJOB JOB004 EXPEDITE OFF RUN DAILYENDJOB

Job JOB001 is associated with Expedite policy FAST, and will be expedited if it has not completed successfully 10 minutes after the trigger time of the corresponding Event.Job JOB002 is not associated with any Expedite policy, and therefore cannot be expedited.Job JOB003 is associated with Expedite policy SUPER, but can only be expedited manually (for example, by the XP CSF line command) as it has no due-out specification and Expedite policy SUPER does not specify CRITICAL_PATH as a criterion.Job JOB004 is not associated with any Expedite policy, and therefore cannot be expedited. Note: The above example is intended primarily to illustrate the capabilities of the

EXPEDITE Application statement. Typically most Applications will have a single, global scope, EXPEDITE statement to govern all jobs in the Application.

EXPIRATION Statement: Specify Expiration of SAP Spool Request

582

EXPIRATION Statement: Specify Expiration of SAP Spool Request

The EXPIRATION statement specifies how many days a spool request is to remain in the spool system before the spool request is deleted.

ApplicabilityESP Business Agents for SAP, Version 2.2 and higher.

Syntax EXPIRATION days

Usage notesUse the EXPIRATION statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the EXPIRATION statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.EXPIRATION corresponds to the SAPGUI Spool options, Spool retention per field on the Background Print Parameters dialog.

ExampleIn this example, the spool request for ABAP BTCTEST is deleted from the spool system after three days.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST EXPIRATION 3ENDJOB

Operand Descriptiondays Specifies the number of days before the spool request is deleted.

Format is numeric and can be between 1 and 9.

Note: If you specify 9 days, the spool request is not deleted.

583

EXTMON Statement: Monitors a Workload Object on an External Scheduler

With the difference that it monitors a job run and monitored by an external scheduler, the EXTMON workload object operates the same way as the JOB workload object using the EXTERNAL operand. The external scheduler is ESP Espresso. Both schedulers communicate the status of externally referenced jobs to each other through an R5 Agent.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use the EXTMON feature, you must load the EXTMON workload object module. The EXTMON workload object module is CYBESOEX. This is loaded with the WOBDEF command or with the WOBDEF initialization parameter.You must also define the default Agent of the external ESP Espresso scheduler in your agent definition file and load that file using the LOADAGDF initialization parameter or command. The agent definition file uses:• The AGENT initialization parameter to specify the Agent name• The MANAGER initialization parameter to specify the name used by the Agent to

communicate with ESP Workload Manager. Refer to the AGENT initialization parameter in the “ESP Workload Manager Installation and Configuration Guide” for information about the AGENT initialization parameter and the agent definition file.The Agent’s AGENTPARM.TXT file must contain a communicationmanagerid for each scheduler it communicates with. The communicationmanagerid for ESP Workload Manager is the manager name defined in the MANAGER initialization parameter.You must specify an EXTSCHEDULER statement and an AGENT statement. These statements can be included:• In the EXTMON workload object definition if the statement applies only to the

object.

• In the Application containing the EXTMON workload object if the statement applies to every EXTMON workload object within that Application occurring after the EXTSCHEDULER statement.

Also refer to the JOB statement usage notes.

EXTMON Statement: Monitors a Workload Object on an External Scheduler

584

ExampleIn the following example:• The EXTMON statement is used to build a dependency between jobs running in

different schedulers. PAYJOB3 is submitted by ESP Espresso: • The AGENTPARM.TXT file of Agent AGENTR5 has

communicationmanagerid set to ESPRESSOMANAGER to identify the specific instance of ESP Espresso running the PAYJOB3 job.

• The Agent name defined in the ESP Workload Manager agent definition file is AGENTR5.

• PAYJOB4 is released when PAYJOB3 completes. If PAYJOB4 is not completed by 9 pm, it is flagged as overdue.

APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'EXTMON PAYJOB3 EXTSCHEDULER ESPRESSOMANAGER AGENT AGENTR5 RUN DAILY REL PAYJOB4ENDJOBJOB PAYJOB4 DUEOUT EXEC 9PM RUN DAILYENDJOB

The following example shows the relevant portion of the AGENTPARM.TXT file:## Communications#communication.managerid_1=ESPRESSOMANAGERcommunication.manageraddress_1=xxx.xx.xx.xxcommunication.managerport_1=7507communication.monitorobject_1=AGENTR5/AGENTMON.0/MAIN#communication.managerid_2=WORKLOADMANAGERcommunication.manageraddress_2=yyy.yy.yy.yycommunication.managerport_2=9999communication.monitorobject_2=AGENTR5/AGENTMON.0/MAIN

585

EXTSCHEDULER Statement: Name of External Scheduler

The EXTSCHEDULER statement specifies which scheduler runs a job referred to by an EXTMON statement.

SyntaxEXTSCHEDULER managername

ExampleEXTSCHEDULER ESPRESSOMANAGER

Operand Descriptionmanagername Specifies the name of the external scheduler running a

job referred by an EXTMON statement. managername is 16 characters long maximum. It must match one of the manager IDs in the Agent’s definition file.

FAILUREMSG Statement: Specify Failure Message for ABAP (SAP)

586

FFAILUREMSG Statement: Specify Failure Message for ABAP (SAP)

The FAILUREMSG statement specifies a string that, when found in the spool output of an SAP job step (ABAP), indicates the failure of the job.

ApplicabilityESP Business Agents for SAP, Release 4 and higher.

Syntax FAILUREMSG 'FailureMessageString'

ExampleIn this example, if the job is successful, Workload Manager will treat the job as failed if the string ’Internal problem’ is found in the ABAP spool output.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST FAILUREMSG 'Internal problem'ENDJOB

Operand DescriptionFailureMessageString The string that must match the SAP job output for the ABAP to

be considered failed. FailureMessageString is case sensitive and can be up to 128 valid SAP characters. FailureMessageString must be enclosed in single quotes.

587

FILE_TRIGGER Statement: Define File Triggers

Use in conjunction with the FILENAME statement to define a job associated with a distributed file trigger. This allows you to build a job that contains a dependency based on file activity, such as when the file is created, updated, or deleted. The FILE_TRIGGER statement has different levels of functionality for each version of an Agent and for each operating system. For a complete description of the FILE_TRIGGER for Agents other than R6 System Agents, see the ESP Agent User’s Guide for the relevant operating system.

TypeApplication statement.

SyntaxRefer to the JOB statement syntax.

Usage notesWithin the scope of a FILE_TRIGGER statement, you must use the FILENAME statement to describe the trigger.Also refer to the JOB statement usage notes. All JOB statement operands are valid except TASK, LINK, and MANUAL.For information on building a distributed file dependency, see the FILENAME statement.

Example Trigger when /usr/sched/data is updatedIn this example, WAIT4.DLY is used to build a job level dependency on when the file /usr/sched/data is updated:APPL PAYROLLJCLLIB 'CYB.ESP.JCL'FILE_TRIGGER WAIT4.DLY AGENT UNIX_NY FILENAME /usr/sched/data UPDATE RUN DAILY REL BJOB B RUN DAILYENDJOB

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

588

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

Specifies the name of the file to monitor for activity within a file-trigger job. FILENAME triggers the release of the job named in the FILE_TRIGGER statement. Specify FILENAME within the job definition (between the FILE_TRIGGER statement and its associated ENDJOB statement).

TypeApplication statement.

Syntax FILENAME filename{CREATE [OWNER(owner)][GROUP(group)] [NOCHANGE(min)]|[SIZE(integer {K|M]}] [CONTINUOUS(alertCode|*)] [RECURSIVE]}{DELETE [OWNER(owner)][GROUP(group)] [CONTINUOUS(alertCode|*)] [RECURSIVE]}{EXIST [OWNER(owner)][GROUP(group)] [RECURSIVE]}{EXPAND {SIZE(integer [K|M])|DELTA(integer [K|M])| PERCENT(integer)} [OWNER(owner)][GROUP(group)] [NOCHANGE(min)]|[CONTINUOUS(alertCode|*)] [RECURSIVE]}{NOTEXIST [OWNER(owner)][GROUP(group)] [RECURSIVE]}{SHRINK {SIZE(integer [K|M])|DELTA(integer [K|M])| PERCENT(integer)} [OWNER(owner)][GROUP(group)] [NOCHANGE(min)]|[CONTINUOUS(alertCode|*)] [RECURSIVE]}{UPDATE [OWNER(owner)][GROUP(group)] [NOCHANGE(min)]|[CONTINUOUS(alertCode)|*] [RECURSIVE]}

589

CREATE file-trigger typeA trigger occurs when the file is created. If the file name contains wildcards, the first matching file is selected. This table describes the CREATE file-trigger operands.

FILENAME operand Descriptionfilename The name of the file to monitor. The maximum length is 128

characters. You can use the asterisk (*) wildcard in the file name, for example:

FILENAME '/usr/data/*' CREATE

You cannot use a wildcard as a prefix or within the directory names in the file path.

When using a wildcard immediately after a forward slash (/), enclose the path in single quotation marks. This prevents part of the path from being recognized as a comment line. For example, this statement might not produce the desired results:

FILENAME /usr/data/* UPDATE

The /* characters are interpreted as the beginning of a comment, so ESP Workload Manager interprets the statement as follows:FILENAME /usr/data CREATE /* UPDATEInstead of monitoring for updates to all files in the /usr/data/ directory, the Agent monitors for the data file in the /usr/ directory. Also, since CREATE is the default file trigger type and UPDATE is considered part of the comment, the CREATE file trigger type is used instead of the intended UPDATE file trigger type.

CREATE file-trigger type operands

Description

OWNER(owner) The user ID that owns the file. If the file is not owned by this user ID, the file trigger waits until all specified criteria are satisfied, including the OWNER criteria.

Note: Applies only to UNIX Agents.GROUP(group) The group that owns the file. If the file is not owned by this

group, the file trigger waits until all specified criteria are satisfied, including the GROUP criteria.

Note: Applies only to UNIX Agents.

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

590

DELETE file-trigger typeThe trigger occurs when the file is deleted. This table describes the DELETE file-trigger type operands.

SIZE(integer[K|M]) The file trigger occurs when the file is the specified size, or bigger. The integer field specifies a size limitation on the file trigger. The integer value defaults to bytes. You can specify kilobytes (KB) or megabytes (MB) by appending K or M.

NOCHANGE(min) The number of minutes that the file modification time should be unchanged before triggering.

CONTINUOUS(alertCode|*) Triggers an ESP Workload Manager Alert when the file trigger occurs. The file-trigger job will not complete unless it is forced to complete.

Note: • If CONTINUOUS is specified, the file name must contain a

wildcard.• The alertCode value cannot exceed four characters and

must be specified previously using the ALERTDEF command.

• You can specify an asterisk to re-trigger the ESP Workload Manager Event that invoked the Application that owns the file-trigger job. When using the SIZE modifier with CONTINUOUS(*), however, if nothing changes between generations, the Event will re-trigger indefinitely.

RECURSIVE Monitor all subdirectories for the specified file name. For example, this FILENAME statement prompts the Agent to monitor for the creation of the pay file in the /usr/data/ directory and all /usr/data/ subdirectories.

FILENAME /usr/data/pay CREATE RESCURSIVE

For more information on the RECURSIVE operand, see “Using the RECURSIVE file-trigger type” on page 600.

CREATE file-trigger type operands

Description

DELETE file-trigger type operands

Description

OWNER(owner) The user ID that owns the file. If the file exists but is not owned by this user ID, the file trigger completes.Note: Applies only to UNIX Agents.

591

EXPAND file-trigger typeThe trigger occurs when the file size increases. If the file does not exist when the file trigger is set, the file-trigger job fails. This table describes the EXPAND file-trigger type operands.

GROUP(group) The group that owns the file. If the file exists, but is not owned by this group, the file trigger completes.Note: Applies only to UNIX Agents.

CONTINUOUS(alertCode|*) Triggers an ESP Workload Manager Alert when the file trigger occurs. You can specify the CONTINUOUS operand with DELETE only when you are using a wildcard(*) in the file name. For example:FILENAME /usr/data/pay* DELETE CONTINUOUS(INFO)The file trigger job completes when all monitored files are deleted.

Note: The alertCode value cannot exceed four characters and must be specified previously using the ALERTDEF command.

RECURSIVE Monitors all subdirectories for the specified file name. For example, this FILENAME statement prompts the Agent to monitor for the deletion of the pay file in the /usr/data/ directory and all /usr/data/ subdirectories.FILENAME /usr/data/pay DELETE RECURSIVE

For more information on the RECURSIVE operand, see “Using the RECURSIVE file-trigger type” on page 600.

DELETE file-trigger type operands

Description

EXPAND file-trigger type operands

Description

OWNER(owner) The user ID that owns the file. If the file is not owned by this user ID, the file trigger fails.

Note: Applies only to UNIX Agents.GROUP(group) The group that owns the file. If the file is not owned by this

group, the file trigger fails.

Note: Applies only to UNIX Agents.

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

592

SIZE(integer [K|M]) The file trigger occurs when the file is the specified size. Negative integer values are not valid. The integer field specifies a size limitation on the file trigger. The integer value defaults to bytes. You can specify kilobytes (KB) or megabytes (MB) by appending K or M.

DELTA(integer [K|M]) The file trigger occurs when the file size has expanded by the specified amount of bytes. Negative integer values are not valid. The integer field specifies a size limitation on the file trigger. The integer value defaults to bytes. You can specify kilobytes (KB) or megabytes (MB) by appending K or M.

PERCENT(integer) The file trigger occurs when the file size expands by the specified percentage.For example, if the file is 1000 bytes and the specified percentage is 90, the file trigger occurs when the file size expands to 1900 bytes (90 percent expansion) or more.

NOCHANGE(min) The number of minutes that the modification time should be unchanged before triggering.

CONTINUOUS(alertCode|*) Triggers an ESP Workload Manager Alert when the file trigger occurs. The file-trigger job will not complete unless it is forced complete.

• If CONTINUOUS is specified and the file name contains a wildcard, the Agent monitors all files that match the filename criteria when the file trigger is set. When the EXPAND criteria are satisfied for any of the selected files, the Agent sends a message to ESP Workload Manager and continues to monitor the files.

• The alertCode value cannot exceed four characters and must be specified previously using the ALERTDEF command.

• You can specify an asterisk to re-trigger the ESP Workload Manager Event that invoked the Application that owns the file-trigger job. When using the SIZE modifier with CONTINUOUS(*), however, if nothing changes between generations, the Event retriggers indefinitely.

RECURSIVE Monitors all subdirectories for the specified file name. For example, this FILENAME statement prompts the Agent to monitor for an increase in the size of the pay file in the /usr directory and all /usr subdirectories.

FILENAME /usr/pay EXPAND SIZE(4K) RECURSIVE

EXPAND file-trigger type operands

Description

593

EXIST file-trigger typeThe trigger occurs if the filename exists. If the file exists when the file trigger is set, the file-trigger job succeeds; otherwise, it fails.This table describes the EXIST file-trigger type operands.

NOTEXIST file-trigger typeThe trigger occurs if the filename does not exist. If the file exists when the file trigger is set, the file trigger fails; otherwise, it succeeds.

Note: Specifying NOCHANGE with the NOTEXIST verb does not influence the behavior of the trigger.

This table describes the NOTEXIST file-trigger type operands

EXIST file-trigger type operands

Description

OWNER(owner) The user ID that owns the file. If the file is not owned by this user ID, the file trigger fails.

Note: Applies only to UNIX Agents.GROUP(group) The group that owns the file. If the file is not owned by this

group, the file trigger fails.

Note: Applies only to UNIX Agents.RECURSIVE Checks all subdirectories for the specified file name. For

example, this FILENAME statement prompts the Agent to check if the pay file exists in the /usr directory and all /usr subdirectories.

FILENAME /usr/pay EXIST RECURSIVE

For more information on the RECURSIVE operand, see “Using the RECURSIVE file-trigger type” on page 600.

NOTEXIST file-trigger type operands

Description

OWNER(owner) The user ID that owns the file. If the file exists, but is not owned by this user ID, the file trigger completes.

Note: Applies only to UNIX Agents.GROUP(group) The group that owns the file. If the file is not owned by this

group, the file trigger completes.

Note: Applies only to UNIX Agents.

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

594

SHRINK file-trigger typeThe trigger occurs when the file size is decreased. If the file does not exist when the file trigger is set, the file-trigger job fails. This table describes the SHRINK file-trigger type operands.

RECURSIVE Check all subdirectories for the specified file name. For example, this FILENAME statement prompts the Agent to check whether the pay file exists in the /usr directory and all /usr subdirectories.

FILENAME /usr/pay NOTEXIST RECURSIVE

For more information on the RECURSIVE operand, see “Using the RECURSIVE file-trigger type” on page 600.

NOTEXIST file-trigger type operands

Description

SHRINK file-trigger type operands

Description

OWNER(owner) The user ID that owns the file. If the file exists, but is not owned by this user ID, the file trigger fails.

Note: Applies only to UNIX Agents.GROUP(group) The group that owns the file. If the file is not owned by this

group, the file trigger fails.

Note: Applies only to UNIX Agents.SIZE(integer [K|M]) The file trigger occurs when the file is the specified size, or

smaller. Negative integer values are not valid. The integer field specifies a size limitation on the file trigger. The integer value defaults to bytes. You can specify kilobytes (KB) or megabytes (MB) by appending K or M.

DELTA(integer [K|M]) The file trigger occurs when the file size changes by the specified amount of bytes. Negative integer values are not valid. The integer value defaults to bytes. The value specified cannot be greater than 99%.You can specify kilobytes (KB) or megabytes (MB) by appending K or M.

PERCENT(integer) The file trigger occurs when the file size shrinks by the specified percentage.For a complete example, see “Using SHRINK PERCENT” on page 602.

NOCHANGE(min) Number of minutes that the modification time should be unchanged before triggering.

595

UPDATE file-trigger typeThe trigger occurs when the file is updated. The UPDATE trigger is time sensitive. If the system time on the Manager and Agent are not synchronized, the trigger may not function as expected. • If the modification time-stamp is greater than the system time when the request

was first processed, the system time is used for comparison. For example:

The file modification time is 1400, the system time is at 1600, and no other options are specified.

• If the modification time is before 1400, the trigger is fired right away.• If the modification time is between 1400 and 1600, the trigger occurs only if

the file is modified after the modification time.• If the modification time is ahead of the system time, the trigger occurs only

if the file is modified after the system time.• If the CONTINUOUS modifier is specified with the UPDATE verb and a

wildcard is used, file selection occurs after each trigger. The first matching file with a modification time later than the last trigger time is selected.

CONTINUOUS(alertCode|*) Triggers an ESP Workload Manager Alert when the file trigger occurs. The file-trigger job will not complete until the monitored file reaches size 0.

Note: • The alertCode value cannot exceed four characters and

must be specified previously using the ALERTDEF command.

• Specify an asterisk to re-trigger the ESP Workload Manager Event that invoked the Application that owns the file-trigger job. If nothing changes between generations when the SIZE modifier is used with CONTINUOUS(*), the Event retriggers indefinitely.

RECURSIVE Monitors all subdirectories for the specified file name. For example, this FILENAME statement prompts the Agent to monitor for a decrease in the size of the pay file in the /usr directory and all /usr subdirectories.

FILENAME /usr/pay SHRINK SIZE(4K) RECURSIVE

For more information on the RECURSIVE operand, see “Using the RECURSIVE file-trigger type” on page 600.

SHRINK file-trigger type operands

Description

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

596

If a wildcard is specified with the CONTINUOUS and NOCHANGE operands, during the NOCHANGE interval another file (which also satisfies the trigger criteria) has its timestamp changed. Once the trigger interval lapses on the first file, the trigger monitors the second file for the duration of the NOCHANGE interval.This table describes the UPDATE file-trigger type operands.

UPDATE file-trigger type operands

Description

OWNER(owner) The user ID that owns the file. If the file is not owned by this user ID, the file trigger fails.

Note: Applies only to UNIX Agents.GROUP(group) The group that owns the file. If the file is not owned by this

group, the file trigger fails.

Note: Applies only to UNIX Agents.NOCHANGE(min) The number of minutes that the modification time should be

unchanged before triggering.CONTINUOUS(alertCode|*) Triggers an ESP Workload Manager Alert when the file trigger

occurs. The file-trigger object will not complete unless it is forced complete.If CONTINUOUS is specified and the file name contains a wildcard, the Agent monitors all files that match the filename criteria when the file trigger is set. When the UPDATE criteria are satisfied for any of the selected files, the Agent sends a message to ESP Workload Manager (indicating, for example, that the file size has changed or the file was updated) and continues to monitor the files.If the CONTINUOUS modifier is specified with NOCHANGE and a wildcard is used, all of the matching files must remain unchanged for the NOCHANGE interval.

Note: The alertCode value cannot exceed four characters and must be specified previously using the ALERTDEF command. Alternatively, you can specify an asterisk to retrigger the ESP Workload Manager Event that invoked the Application that owns the file-trigger job.

RECURSIVE Monitors all subdirectories for the specified file name. For example, this FILENAME statement prompts the Agent to monitor for updates to the pay file in the /usr directory and all /usr subdirectories.

FILENAME /usr/pay UPDATE RECURSIVE

For more information on the RECURSIVE operand, see “Using the RECURSIVE file-trigger type” on page 600.

597

Usage notesIf the path showing the location of the file contains spaces, put the entire path in single quotation marks, for example:

FILENAME 'c:\data files\pay.dat' CREATE

The default number of seconds the Agent waits between scans is 30 seconds. If the monitored file changes more than once between scans, the trigger occurs only once, or not at all. For example, if the Agent is monitoring for:

• Updates to a file, and the file is updated twice between scans, the trigger occurs only once.

• The creation of a file, and the file is created and deleted between scans, the trigger does not occur. (The file does not exist when the directory is scanned.)

To change the number of seconds between scans, change the value for the filemonplugin.sleepperiod parameter in the Agentparm.txt file, as described in the ESP System Agent Administrator’s Guide.

Using the CREATE file-trigger typeIf the file exists when the job is readied, the trigger occurs immediately. If the file does not exist when the job is readied, the trigger does not occur until the file is created.If the OWNER or GROUP modifier is specified, the file trigger occurs only when all specified criteria are satisfied, including the OWNER or GROUP criteria. This FILENAME statement prompts the Agent to monitor for the creation of a file named payroll, owned by JDOE:

FILENAME /usr/data/payroll CREATE OWNER(JDOE)

If the payroll file is created, but it is not owned by JDOE, the file trigger does not complete. It waits until all specified criteria are satisfied, including the OWNER criteria. If you change the owner of the file to JDOE, the file trigger completes.

Using the DELETE file-trigger typeIf the file does not exist when the job is readied, the file trigger occurs immediately. You can specify the CONTINUOUS parameter operand with DELETE only when you are using a wildcard (*) in the file name. For example, this statement specifies that when a file whose name begins with pay is deleted from the /usr/data/ directory, the Alert INFO is triggered.FILENAME /usr/data/pay* DELETE CONTINUOUS(INFO)

Using the EXIST file-trigger typeIf the file does not exist, the file-trigger job fails. If the filename value contains wildcards, the file with the most recent modification time is selected.

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

598

Using the EXPAND file-trigger typeIf the file does not exist when the file trigger is set, the file-trigger job fails. If filename contains wildcards, and more than one matching file exists, the file with the most current modification time is monitored for the duration of the trigger.Note: The only way to determine which file is being monitored is to view the debug

output.If the OWNER or GROUP modifier is specified, the file trigger occurs only when all specified criteria are satisfied, including the OWNER or GROUP criteria. If the OWNER or GROUP does not match, the file trigger fails.

If the SIZE modifier is specified, for example, EXPAND SIZE (n), the file specified by the filename value is monitored until its size increases to n or to more than n. If the file size at initial monitor time is equal to, or greater than n, the trigger completes.

If the SIZE(n) CONTINUOUS modifier is specified with the EXPAND file-trigger type and the file size is more than n, the trigger occurs, a message is sent to ESP Workload Manager, and the file continues to be monitored. For example, this table shows when the trigger will occur if EXPAND SIZE(10K) is set:

If the PERCENT modifier is specified with the EXPAND verb, and file size is 0, the trigger occurs when the file size increases.

If the DELTA modifier is specified with the EXPAND file-trigger type, the file specified by filename is monitored until it increases by n.

The file size when the Agent scans the Directory

Does the file trigger occur?

15 KB Yes. The file is bigger than 10 KB when the directory is first scanned. 15 KB becomes the new upper limit.

20 KB Yes. 20 KB exceeds the upper limit of 15K. 20 KB becomes the new upper limit.

35 KB Yes. 35 KB becomes the new upper limit. 30 KB No. The upper limit is now 35K. The size needs to

exceed 35 KB for the trigger to occur.40 KB Yes. 40 KB exceeds the upper limit of 35K.

40 KB becomes the new upper limit.45 KB Yes. 45 KB becomes the new upper limit.60 KB Yes. 60 KB becomes the new upper limit.50 KB No. The upper limit is now 60K. The size needs to

exceed 60 KB for the trigger to occur.65 KB Yes. 65 KB exceeds the upper limit of 60K.

65 KB becomes the new upper limit.

599

Deleting the monitored file causes the trigger to fail.

Using the NOTEXIST file-trigger typeIf the file does not exist, the file-trigger job completes successfully.If filename contains wildcards, the file with the most recent modification time is selected.

Using the SHRINK file-trigger typeIf the file does not exist when the file trigger is set, the file-trigger job fails.If filename contains wildcards, and more than one matching file exists, the file with the most current modification time is monitored for the duration of the trigger.If the OWNER or GROUP modifier is specified, the file trigger occurs only when all specified criteria are satisfied, including the OWNER or GROUP criteria. If the OWNER or GROUP does not match, the file trigger fails.

If the SIZE modifier is specified, for example, SHRINK SIZE (n), the file specified by the filename value is monitored until its size decreases to n or to less than n. If the file size at initial monitor time is equal to, or less than n, the trigger completes.

If filename contains wildcards, and more than one matching file exists, the file with the most current modification time is monitored for the duration of the trigger.Note: The only way to determine which file is being monitored is to view the debug

output.If the SIZE(n) modifier is specified with the SHRINK file-trigger type, and the file size is less than n, the trigger occurs, a message is sent to ESP Workload Manager, and the file continues to be monitored. The file continues to trigger on file-size reductions of value n until the file size is zero (0).If the DELTA modifier is specified with the SHRINK file-trigger type, the file specified by filename is monitored until it shrinks by n. If the file size at the time the trigger is set is less than n, the trigger will complete when the file reaches size 0. These examples show how to use the DELTA modifier.FILENAME /usr/data/test SHRINK DELTA(10K)

File "A" is 5 bytes.DELTA = 10

The trigger completes when file A reaches 0 bytes.If CONTINUOUS is also set, the Alert triggers, and 0 is then the upper limit of the file monitor. Therefore, this trigger completes. For example, consider this statement:FILENAME /usr/data/test SHRINK DELTA(10K) CONTINUOUS(ALERT)

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

600

where these conditions exist:• File A is 5 bytes• DELTA = 10• CONTINUOUS(ALERT)If the initial size of test is 25 KB, the trigger occurs when the file shrinks to 15 KB.This FILENAME statement uses the SHRINK, DELTA, and CONTINUOUS operands.FILENAME c:\data\test SHRINK DELTA(10K) CONTINUOUS(INFO)

If the initial size of file test is 25 KB, with the CONTINUOUS modifier set:

• When file test reaches 15 KB, the trigger occurs. The trigger continues to monitor test for shrinkage to 5 KB.

• When file test reaches 5 KB, the trigger occurs. The trigger continues to monitor test for shrinkage to 0 bytes.

• When file test reaches 0 bytes, the trigger completes.Deleting the file causes the trigger to fail.

When the SIZE modifier is specified with the SHRINK verb, for example, SHRINK SIZE (n), the file specified by filename is monitored until its size decreases to less than (n). If the file size at initial monitor time is less than (n), the trigger will complete.

Using the UPDATE file-trigger typeIf the file exists when the job is readied, the trigger occurs when the file is updated. If the file does not exist when the job is readied, the trigger fails. If the file exists when the job is readied and is then deleted without modification, the trigger fails.If the OWNER or GROUP modifier is specified, the file trigger occurs only when all specified criteria are satisfied, including the OWNER or GROUP criteria. If the OWNER or GROUP does not match, the file trigger fails.

If filename contains wildcards, the first matching file with a modification time later than the modification time-stamp will be selected.If the file trigger’s submission time is less than the system time, the modification time is compared against the file’s modification time. The trigger occurs if the file’s modification time is later than the modification time at scheduled monitoring intervals, and any other specified conditions are met.

Using the RECURSIVE file-trigger typeYou might need to monitor file activity in multiple directories. To code a statement for each directory can take a long time, as illustrated by this example:

601

APPL PAYROLLFILE_TRIGGER PAYDATA AGENT UNIX_NY FILENAME /usr/data/payroll UPDATE RUN DAILY RELEASE PAYRPTENDJOBFILE_TRIGGER PAYSALES AGENT UNIX_NY FILENAME /usr/data/sales/payroll UPDATE RUN DAILY RELEASE PAYRPTENDJOBFILE_TRIGGER PAYSUPT AGENT UNIX_NY FILENAME /usr/data/support/payroll UPDATE RUN DAILY RELEASE PAYRPTENDJOBFILE_TRIGGER PAYTRAIN AGENT UNIX_NY FILENAME /usr/data/training/payroll UPDATE RUN DAILY RELEASE PAYRPTENDJOB..ENDJOB

In this example, the payroll payroll.dat file is monitored for updates in the /usr/data/ directory and several /usr/data/ subdirectories. Alternatively, you can use the RECURSIVE modifier to monitor activity in those directories, as shown in this example.

FILE_TRIGGER PAYDATA AGENT UNIX_NY FILENAME /usr/data/payroll UPDATE RECURSIVE RUN DAILY RELEASE PAYRPTENDJOB

In this example, the payroll file also is monitored for updates in the /usr/data/ directory and all /usr/data/ subdirectories. The PAYRPT job is released only once, however, because the PAYDATA job completes as soon as the payroll file is updated in any one of the monitored directories.

You also can use a wildcard to identify the files that you want monitored, as shown in this example:

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

602

FILE_TRIGGER PAYDATA AGENT UNIX_NY FILENAME '/usr/data/*' UPDATE RECURSIVE RUN DAILY RELEASE PAYRPTENDJOB

In this example, the Agent monitors for updates to all files in the /usr/data/ directory and all /usr/data/ subdirectories.

Related InformationFor information on defining Alert definitions, see the ALERTDEF command. For information on defining a file trigger, see the FILE_TRIGGER statement.For detailed usage information on file triggers, see the ESP System Agent Guide to Scheduling Workload.

ExamplesUsing EXPAND SIZEAgent NT_NY monitors the file test in directory data for a file size increase of 1 byte or more. When that file size is reached, the PAYROLL.SORT job is triggered, and the PAYDATA job is released.FILE_TRIGGER PAYROLL.SORT AGENT NT_NY FILENAME /data/test EXPAND SIZE(1) RELEASE PAYDATA RUN DAILY ENDJOB

Using EXPAND DELTAAgent UNIX_TOR monitors the file record in directory credit. If the record file expands in size by two megabytes or more, the BANK.ACCOUNT job is triggered, and the PAYRPT job is released.FILE_TRIGGER BANK.ACCOUNT AGENT UNIX_TOR FILENAME /credit/record EXPAND DELTA(2M) RELEASE PAYRPT RUN DAILYENDJOB

Using SHRINK PERCENTAgent NT_TOR monitors file test in directory c:\amount. When the file shrinks in size by 65% or more, the ACCOUNT.SORT job is triggered, and the PAYDATA job is released.

603

FILE_TRIGGER ACCOUNT.SORT AGENT NT_TOR FILENAME c:\amount\test SHRINK PERCENT(65) RELEASE PAYDATA RUN DAILYENDJOB

Using EXISTAgent UNIX_TOR monitors for file money in directory c:\bank\account. If the file exists, the PAY.MORTGAGE job is triggered, and the PAYMTGE job is released.FILE_TRIGGER PAY.MORTGAGE AGENT NT_TOR FILENAME c:\bank\account\money EXIST RELEASE PAYMTGE RUN DAILYENDJOB

Using EXIST RECURSIVEAgent NT_TOR monitors for file money in directory c:\bank\account and all c:\bank\account subdirectories. If the file exists in any of the monitored directories, the PAY.MORTGAGE job is triggered, and the PAYDATA job is released.FILE_TRIGGER PAY.MORTGAGE AGENT NT_TOR FILENAME c:\bank\account\money EXIST RECURSIVE RELEASE PAYDATA RUN DAILYENDJOB

Using NOTEXISTAgent UNIX_NY checks for file vacation in directory /start/term/. If the file does not exist, the EMPLOYEE.RECORD job is triggered, and the PAYRPT job is released.FILE_TRIGGER EMPLOYEE.RECORD AGENT UNIX_NY FILENAME /start/term/vacation NOTEXIST RELEASE PAYRPT RUN DAILYENDJOB

Using EXPAND SIZE NOCHANGEAgent UNIX_CHI monitors file analysis in directory c:\research. If the file size expands to 1 byte or more and remains unchanged for 5 minutes or more, the PROCESS.STATUS job is triggered, and the PAYDATA job is released.

FILENAME Statement: Specify Files Monitored by FILE_TRIGGER

604

FILE_TRIGGER PROCESS.STATUS AGENT UNIX_CHI FILENAME /research/analysis EXPAND SIZE(1) NOCHANGE(5) RELEASE PAYDATA RUN DAILYENDJOB

Using SHRINK SIZEAgent UNIX-CHI monitors the file distribute in directory cash\items. If the file size shrinks to 1 KB or smaller, the BUSINESS.PLAN job is triggered, and the PAYDATA job is released.FILE_TRIGGER BUSINESS.PLAN AGENT UNIX_CHI FILENAME cash\items\distribute SHRINK SIZE(1K) RELEASE PAYDATA RUN DAILYENDJOB

Using SHRINK DELTAAgent NT_TOR monitors file cash in directory c:\cost. When the file shrinks by 10 bytes, the TRAVEL.EXPENSE job is triggered, and the PAYRPT job is released.FILE_TRIGGER TRAVEL.EXPENSE AGENT NT_TOR FILENAME c:\cost\cash SHRINK DELTA(10) RELEASE PAYRPT RUN DAILYENDJOB

Multiple file-trigger jobs monitor the same fileIn this example, two file-trigger jobs monitor the same file and trigger the same Event. The jobs are independent and do not relate to each other in any way.FILE_TRIGGER SURVEY1.ANALYSIS AGENT NT_TOR FILENAME c:\data\totals EXPAND DELTA(10k) CONTINUOUS(MGMT) RELEASE PAYRPT RUN DAILYENDJOB

FILE_TRIGGER SURVEY2.ANALYSIS AGENT NT_TOR FILENAME c:\data\totals SHRINK DELTA(10k) CONTINUOUS(MGMT) RELEASE PAYDATA RUN DAILYENDJOB

If the initial file size of totals (c:\data\totals) is 100 KB and it changes as follows: 80 KB, 90 KB, 110 KB, 50 KB, 60 KB, then the following triggers occur:

605

• Because of the EXPAND file-trigger type, when the file size changes from 90 KB to 110 KB, the first job issues the MGMT Alert once and releases the PAYRPT job.

• Because of the SHRINK file-trigger type, the second job issues the MGMT Alert twice and releases the PAYDATA job twice.The triggers occur when the file size shrinks from 100 KB to 80 KNB and then again when the file size shrinks from 80 KB to 50 KB.

FILTER Statement: Specify Filter for JMS Subscribe Jobs (J2EE)

606

FILTER Statement: Specify Filter for JMS Subscribe Jobs (J2EE)

The FILTER statement specifies the filter that the JMS Subscribe job uses to monitor the Topic or Queue.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within a JMSS_JOB workload object

SyntaxFILTER filter

Usage notesFILTER is an optional statement within a JMSS_JOB workload object.

Operand Descriptionfilter The filter for filtering messages from the Topic or Queue. filter

is case sensitive and can be up to 1024 characters. If filter contains delimiters (such as spaces), enclose it in single quotes.Use Regular Expression logic to construct the filter. If you specify an Alert, the job runs continuously, and the ESP System Agent issues an Alert each time a message matches the filter criteria. If you do not specify a filter, the ESP System Agent issues an Alert after each message is published to the Topic or Queue.If you do not specify an Alert, the job completes after the ESP System Agent detects the filter value. If you do not specify a filter, the job completes after the first message is published to the Topic or Queue.

Note: The ESP System Agent ignores all messages that do not match the filter.

607

ExampleIn this example, the CYBJK.JS job continuously monitors the Queue named Queue for messages matching the filter criteria. APPL TESTJSJMSS_JOB CYBJK.JS HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DEST ’c:\Program Files\Dest\Common Files\System\ado\+ Makapt15.txt’ DESTNAME Queue continuous(a13) TOPIC N FILTER ’abc\s...\s[a-zA-Z]+\sFilter![\sa-z0-9]+’ JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001ENDJOB

FLAGUNDEF Statement: Find Reference to Undefined Symbols

608

FLAGUNDEF Statement: Find Reference to Undefined Symbols

The FLAGUNDEF statement finds references to undefined symbols in a symbol library data set. It then checks subsequent symbol references and issues an error message if it finds any more undefined symbols.

SyntaxFLAGUNDEF

Usage notesThe FLAGUNDEF statement cannot be used in ESP Procedures.If ESP flags an undefined symbol while submitting a job, ESP:• Deletes the job and requests the user correct and resubmit the job• Identifies the job on the CSF with a PNODE of SUBERROR, and a status of

Submit Error, JCL missing.The FLAGUNDEF statement affects all subsequent symbol reference processing until an ALLOWUNDEF statement is encountered.If ESP encounters an undefined symbol, ESP processes undefined symbols without producing an error message, ALLOWUNDEF is the default.

Related informationFor information on turning off the flagging of undefined symbols, see the ALLOWUNDEF statement.For information on symbolic variables, see the ESP Workload Manager Advanced User’s Guide.

Examples Flag undefined symbolIn the following example, ESP flags 'X' as an undefined symbol because an ESP built-in symbolic variable (ESPADD) was typed incorrectly (EXXPADD):INTEGER XFLAGUNDEFX=%EXXPADD/7+1

609

Turn flagging on and offIn the following example, when ESP encounters these undefined symbols while submitting a job:• A=%BC results in an error message—flagging is on (FLAGUNDEF)• B takes on the value of %XY—flagging is off (ALLOWUNDEF):FLAGUNDEFA=%BCALLOWUNDEFB=%XY

FLOW Command: Identify Flow Chart

610

FLOW Command: Identify Flow Chart

The FLOW command is used in conjunction with the GENFLOW command to identify a flow chart by a name of up to seven characters. The FLOW command also identifies jobs and/or Applications to be exported.

TypeReporting command.

SyntaxFLOW name [APPL(applname)] [JOB(jobname)]

Usage notesThe following summarizes how to generate flowcharts with ESP and Timeline:1. Issue the GENFLOW command indicating the input and output data sets2. Issue the FLOW command to identify the flow chart3. Issue the GO command to indicate all specifications are complete and that the

copy process should proceed4. Use a PC file transfer program to send the data to a PC5. On the PC, use a file editor to edit the file6. Access Timeline to import, view and print flowcharts.

Related informationFor information on creating graphical representations of workload, see the ESP Workload Manager User’s Guide.For information on exporting data that describes an ESP Application in a format usable by MS Project, see the GENPROJ command.

Operand Descriptionname Indicates the name of the flow chart by a name of up to seven

characters.applname Indicates the name of an Application to be exported.jobname Indicates the name or names of jobs to be exported. Several names

can be specified, if separated by a comma. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

611

For information on exporting data that describes an ESP Application in a format usable by Timeline, see the GENFLOW command.For information on indicating that all specifications are complete and that the copy process should proceed, see the GO command.

Examples GENFLOW, FLOW and GO commandsIn the following example, ESP:• Exports the jobnames, start and end times for all jobs in the PAYROLL

Application• Identifies a flowchart called PAYROLL• Proceeds with the copy process.GENFLOW 'CYBER.SAD' 'CYBER.FLOW'FLOW PAYROLL APPL(PAYROLL)GO

Note: After the above is completed, transfer the file to a PC, edit that file and use Timeline to import, view and print the PAYROLL flowchart.

Export data to TimelineIn the following example, ESP:• Exports the jobnames, start and end times for jobs with PAY in the first three

positions, within the PAYROLL Application• Identifies a flowchart called PAYROLL• Proceeds with the copy process.GENFLOW 'CYBER.SAD' 'CYBER.FLOW'FLOW PAYROLL APPL(PAYROLL) JOB(PAY-)GO

FLOWDOC Command: Generate Reports

612

FLOWDOC Command: Generate Reports

The FLOWDOC command is used to generate generates reports detailing information about workload scheduled by ESP Workload Manager. The following outlines the information that is produced:• Application/subApplication names• Run dates• Calendars referenced• Job-level information:

• Whether the job is held or not• Tag field• Job type • Submission time (DELAYSUB/EARLYSUB if coded in the Application, else

Event submission time)• Job name• Hold count• Released jobs• Resource information• Scope information (look back/ahead times for manual or external jobs)• External job information (Application and job names)

TypeReporting command.

SyntaxFLOWDOC {PREFIX(event_prefix)EVENT(event_name) |APPL(appl_name)} {FROM('criteria') TO('criteria') |DATE('criteria')}

Operand DescriptionPREFIX(event_prefix)

Specifies the prefix of the Events used for selecting the content of the report. This operand is mandatory if you are selecting by event. You can use wildcards to select a range of Event prefix.

613

Usage notesBefore generating a report using the FLOWDOC command, you must:• Generate the ESP Workload Manager using the SADGEN command• Generate a VSAM data baseSelection by Events and by Applications are mutually exclusive.Selection by range of dates and by a specific date are mutually exclusive.

Related informationFor information on scheduled activity reporting, see the ESP Workload Manager User’s Guide.

Examples The following are examples of report generation jobs that could be used to produce ESP FLOWDOC reports.

Example 1 The following report-generation JCL could be used to produce a report detailing information about the PAYROLL Application starting today ending tomorrow://FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(PAYROLL) FROM('TODAY') TO('TOMORROW')

EVENT(event_name)

Specifies the name of the Events used for selecting the content of the report. This operand is mandatory if you are selecting by event. You can use wildcards to select a range of Event names.

APPL(appl_name)

Specifies the name of the Applications used for selecting the content of the report. You can use wildcards to select a range of Applications.

FROM('criteria')

Specifies the beginning of the period covered by the report if the report covers a range of dates.

TO('criteria') Specifies the end of the period covered by the report if the report covers a range of dates.

DATE('criteria')

Specifies the specific date covered by the report.

Operand Description

FLOWDOC Command: Generate Reports

614

Example 2The following report-generation JCL could be used to produce a report detailing information about an Application which is invoked by an Event called CYBER.PAYROLL on August 29th, 2003://FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC PREFIX(CYBER) NAME(PAYROLL) DATE('AUGUST 29, 2003')

Example 3The following report-generation JCL could be used to produce a report detailing information about the BILLING Application from 4 pm today until 4 pm two days from today://FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(BILLING) FROM('4PM TODAY') TO('4PM TODAY PLUS 2 DAYS')

Example 4The following report-generation JCL could be used to produce a report detailing information about the CLAIMS Application from Monday to Friday. Jobs in the CLAIMS Application that have varying run frequencies will be displayed on their respective day, for example, jobs coded as RUN MONDAY will be displayed on Mondays run date.//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(CLAIMS) DATE('MONDAY')FLOWDOC APPL(CLAIMS) DATE('TUESDAY')FLOWDOC APPL(CLAIMS) DATE('WEDNESDAY')FLOWDOC APPL(CLAIMS) DATE('THURSDAY')FLOWDOC APPL(CLAIMS) DATE('FRIDAY')

615

FOOTING Command: Print Footing Line

The FOOTING command is used to define a line to be displayed at the bottom of the page when output is directed to a data set. Use the FOOTING command when generating history or modeling reports, or issuing an ESP command. Up to seven title and footing lines can be active at any time.

TypeGeneral command, reporting command.

SyntaxFOOTING [n] [DELETE] ['footing string']

Usage notesThe following are built-in variables that you can use in a footing string:

Operand Description

n Indicates which footing line is being defined, or deleted. n can be a value from one to seven. The default is 1.

DELETE Indicates the specified footing line is to be deleted.

footing string Indicates the footing to be displayed. It should be enclosed within quotes. If the footing contains quotes, use two quotes in place of each imbedded quote.

Variable Description%CE Centers the operand within the output line.%DATE Full date, for example, SUNDAY 4th JANUARY 1998.%DAY Day of week name, for example, MONDAY.%DD Day of month number, from 01 to 31.%DDDD Julian day or day of year number. For example, 365 for last day.%DOW# Day of week number, for example, '1' for Sunday, '7' for Saturday,

regardless of calendar settings.%EVAL Returns the numeric value of an expression. An output-format

descriptor may follow the operand to request leading blanks or zeros.

%HH Hour, in 24-hour format, for example, 14.%LENGTH Returns the length of the operand.

FOOTING Command: Print Footing Line

616

Examples Print Payroll group EventsIn the following example, a footing 'Payroll Group Events' is defined to accompany the output from the LIST command, which requests a display of Events in the group called PAYROLL:FOOTING 'PAYROLL GROUP EVENTS'LIST ALL LEVEL(PAYROLL)

Print date, text and page numberIn the following example, the following are displayed at the bottom of each page:• The current date• PAYROLL JOBS, which is justified in the center of the page• The page number, which is justified on the right side of the page.The history report looks like this://HISTRPT JOB CYB3000,CLASS=A,MSGCLASS=X//STEP001 EXEC PGM=ESP,PARM='SUBSYS(E510)',REGION=4M//STEPLIB DD DSN=CYB2.ESP510Q.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSIN DD *REPORTFROM 7AM TODAY LESS 1 WEEKCRITERIA JOBNAME EQ PAY-;DISPLAY JOBNAME,JOBNO,EXECSDATE,ENDDATE,CMPCSORT JOBNAMEFOOTING '%DATE %CE(PAYROLL JOBS) %RJ(PAGE %PAGE)'ENDR

%MM Month number, for example, 01 if the month is January.%MMM First three characters of the month, foe example, JAN.%MM Minute of the hour.%MONTH Month name, for example, JANUARY.%PAGE The current page number.%RJ Justifies the operand on the right side of the output line.%SSS Seconds.%TIME Time, in 24-hour format, for example, 14.30.00.%YEAR Year, for example, 2001.%YY Last two characters of year, for example, 03.

Variable Description

617

Print text and page numberIn the following example, a footing CALENDARS is defined. The page number is to be justified on the right side of the page:FOOTING 'CALENDARS %RJ(PAGE %PAGE)'

FROM Command: Start Reporting From

618

FROM Command: Start Reporting From

The FROM command is used to indicate a time range for the history reporting. This allows you to limit your search based on the job submission time in the history file. You can use any valid schedule statement.

TypeReporting command.

SyntaxFROM starttime [TO(endtime)]

Usage notesThe FROM operand restricts history record extraction based on job submission time. If an end time is not specified, the current time is assumed.

Related informationFor information on reporting, see the ESP Workload Manager User’s Guide.

Examples Display all PAY jobs since 9 amIn the following example, all jobs with PAY in the first three positions run since 7 am this morning are displayed in this report:REPORTFROM 7AM TODAYCRITERIA JOBNAME EQ PAY;DISPLAY JOBNAME,JOBNO,EXECSDATE,ENDDATE,CMPCENDR

Specify rangeIn the following example, all jobs with PAY in the first three positions run between 8 am yesterday and 4 pm today are displayed in this report:

Operand Description

starttime Indicates a free format starting time. Use any valid schedule criteria that resolve to a single date and time.

endtime Indicates a free format, end time specification. (Defaults to now). Use any valid schedule criteria that resolve to a single date and time.

619

REPORTFROM 8AM YESTERDAY TO 4PM TODAYCRITERIA JOBNAME EQ PAY-;DISPLAY JOBNAME,JOBNO,ACCOUNT,RDRON,DEXCP,TEXCPENDR

From 8 am to 8 amThe following example limits a history file search from 8 am yesterday to 8 am today:FROM 8AM YESTERDAY TO 8AM TODAY

From Dec 29 to Jan 4The following example limits a history file search from December 29th, 2001 to January 4th, 2002:FROM DEC 29TH 2001 TO JAN 4TH 2002

For the last weekThe following example limits a history file search from 8 am one week ago to now:FROM 8AM TODAY LESS 1 WEEK

//* FROM Statement: Identify Initial Date for Temporary JCL

620

//* FROM Statement: Identify Initial Date for Temporary JCL

The //* FROM statement is used in combination with the TEMPLIB statement to indicate that temporary JCL for a job is to be used from a particular date. The TEMPLIB statement is used in an ESP Procedure to indicate a temporary or override JCL library.

TypeControl statement used in JCL.

Syntax//* FROM criteria

Usage notesThe //* FROM statement is used in a JCL library that was identified as a temporary JCL library using the TEMPLIB statement.A single blank separates the //* and the FROM.The //* FROM statement is only available in JCL and must start in card column one. It must be the first statement in the JCL. ESP checks the //* FROM date to determine whether the JCL should be used. If no time is specified, the start-of-day time is used (default midnight – 00.00).ESP compares the scheduled time and date of the Event to the criteria on the //* FROM statement to decide whether to use the JCL in the TEMPLIB for a job. If the //* FROM date and time has passed, ESP uses the JCL from the last defined JCLLIB in the Application.

Related informationFor information on further limiting the window in which temporary JCL is used, see the //* UNTIL statement.For information on specifying a temporary or override JCL library, see the TEMPLIB statement.

For information on tailoring JCL that ESP submits, see the ESP Workload Manager Advanced User’s Guide.

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time.

621

Examples Use temporary JCL from May 24In the following example, temporary JCL for PAYJOB1 is used from 9am on May 24, 2001: //* FROM 9AM MAY 24,2001//PAYJOB1 JOB CYB,CLASS=A,MSGCLASS=0

Note: If PAYJOB1 is submitted at 10 am, but the Event was scheduled at 8 am, ESP submits PAYJOB1 from the default JCL library (JCLLIB) not the temporary JCL library (TEMPLIB).

Use temporary JCL from midnight August 6In the following example, temporary JCL for PAYJOB2 is used from 00:00 (default) on August 6, 2002://* FROM AUGUST 6, 2002//PAYJOB2 JOB CYB,CLASS=A,MSGCLASS=0

Use temporary JCL from Nov 27 to Nov 30In the following example, temporary JCL for PAYJOB3 is used from 9 am on November 27, 2003 until 4 pm on November 30, 2003://* FROM 9AM NOVEMBER 27, 2003//* UNTIL 4PM NOVEMBER 30, 2003//PAYJOB3 JOB CYB,CLASS=A,MSGCLASS=0

FTP Command: Select SMF Record

622

FTP Command: Select SMF Record

The FTP command specifies if ESP Workload Manager monitors SMF record types 118 or 119 for FTP data-set triggering.

TypeAuthorized Oper command

SyntaxFTP SMF(118|119)

Operand DescriptionSMF(118) Specifies that ESP Workload Manager monitors SMF record type

118 for FTP data-set triggering. This is the default. SMF(119) Specifies that ESP Workload Manager monitors SMF record type

119 for FTP data-set triggering.

Note: SMF records type 119 are available only with z/OS.

623

FTP_JOB Statement: Identify the Name of FTP Jobs

Identifies the name of an FTP job in an Application. This job enables FTP operations on files specified in an FTP_JOB workload object. The output is directed to the spool file via an FTP server.

TypeApplication statement.

ApplicabilityRelease 6 System Agents.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use FTP jobs, load the workload object module CYBESOFT with the WOBDEF command or with the WOBDEF initialization parameter.

Related statementsUse these job-definition statements with an FTP_JOB workload object. They are all mandatory for an FTP_JOB workload object.• FTPFORMAT• LOCALFILENAME• REMOTEFILENAME• SERVERADDR• SERVERPORT • TRANSFERDIRECTION• USERNote: Because the USER statement requires the PASSWORD command, refer to

PASSWORD command.Also refer to the JOB statement usage notes.

FTP_JOB Statement: Identify the Name of FTP Jobs

624

ExamplesExample 1In this example, a file called textfile is downloaded and copied to a local machine. Both locations, local and remote, include a complete path statement. After the download is complete, the job FTPJOB2.DOWNLOAD is released for execution.FTP_JOB FTPTEST1.DOWNLOAD AGENT R6AGENT USER test SERVERADDR hpunix SERVERPORT 21 TRANSFERDIRECTION DOWNLOAD FTPFORMAT A REMOTEFILENAME /u1/qatest/ftpdata/textfile LOCALFILENAME /export/home⁄qatest⁄ftpdata⁄textfile RUN DAILY RELEASE FTPJOB2.DOWNLOADENDJOB

Example 2In this example, a file called textfile is uploaded and copied to a remote Windows machine. Both locations, local and remote, include a complete path statement. After the upload is complete, the job FTPJOB2.DOWNLOAD is released for execution. In this example, we use an R6 Windows System Agent as an FTP server. Its IP address is 111.11.22.333.FTP_JOB FTPTEST1.UPLOAD AGENT R6AGENT USER test SERVERADDR 111.11.22.333 SERVERPORT 123 TRANSFERDIRECTION UPLOAD FTPFORMAT A REMOTEFILENAME /C:/TEMP/textfile LOCALFILENAME /export/home/qatest⁄ftpdata⁄textfile RUN DAILY RELEASE FTPJOB2.DOWNLOADENDJOB

625

FTPFORMAT Statement: Specify FTP Format Within FTP_JOB

The FTPFORMAT statement specifies an ASCII, binary, or auto-detect transfer in an FTP_JOB workload object.

ApplicabilityESP System Agents, Release 6, used within an FTP_JOB workload object. For more information, see “FTP_JOB Statement: Identify the Name of FTP Jobs” on page 623.

SyntaxFTPFORMAT [A|B|U]

Usage notesFTPFORMAT is an alternative form of TRANSFERCODETYPE. Refer to “TRANSFERCODETYPE Statement: Specify FTP Format Within FTP_JOB” on page 1285.FTPFORMAT is a required statement within the FTP_JOB workload object. FTPFORMAT can be a global statement.

ExamplesExample 1 (UNIX)In this example, the FTP format is binary (operand B).FTP_JOB FTPTEST6.DOWNLOAD AGENT R6AGENT USER test SERVERADDR hpunix SERVERPORT 21 TRANSFERDIRECTION D FTPFORMAT B REMOTENAME /u1/qatest/ftpdata/ESPmgr LOCALNAME /export/home/qatest/ftpdata/transf.bin RELEASE FTPT17.UPLOAD RUN DAILY AFTER CHECK.PART1ENDJOB

Operand DescriptionA ASCIIB BinaryU Auto-detect

Note: You can only specify Auto-detect for uploads.

FTPFORMAT Statement: Specify FTP Format Within FTP_JOB

626

Example 2 (Windows)In this example, the FTP format is binary (operand B).FTP_JOB FTPTEST6.DOWNLOAD AGENT R6AGENT USER test SERVERADDR hpunix SERVERPORT 21 TRANSFERDIRECTION D FTPFORMAT B REMOTENAME /u1/qatest/ftpdata/ESPmgr LOCALNAME c:\qatest\ftpdata\transf.bin RELEASE FTPT17.UPLOAD RUN DAILY AFTER CHECK.PART1ENDJOB

627

GGENDOC Command: Generate Job Documentation

Use the GENDOC command to convert an existing job documentation library to a documentation library usable by ESP.

TypeGeneral command.

SyntaxGENDOC 'inputdataset' 'outputdataset' [LEVEL(memname[,memname]...)] [SNUM]

Usage NotesThe GENDOC command identifies the input data set, the members to be copied, and the output data set. It also lets you identify changes you want to make when the old job documentation is converted.There are two methods for converting documentation. The method you use depends on how you want to use your existing job documentation:• If want to use ESP to retrieve your existing job documentation in its present

format, you can insert a USERDESC label in each job documentation member.• If you want ESP to modify the data to allow retrieval of information by label

name, you can use the GENDOC command.

Operand Description

inputdataset Indicates the name of the input data set, enclosed in quotes, which must be a PDS.

outputdataset Indicates the name of an output PDS, enclosed in quotes. The record format or record length does not have to match that of the input data set.

memname Indicates strings that identify the members to be copied. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. If the LEVEL keyword is omitted, all members are copied.

SNUM Indicates the last eight characters of a fixed-length record should be discarded during the copy process.

GENDOC Command: Generate Job Documentation

628

Related informationFor information on identifying lines that are not to be copied to the output data set, see the REMOVE command.For information on altering or replacing lines in the output data set, or inserting lines at different locations, see the LABEL command.For information on indicating that all specifications are complete and that the copy process should proceed, see the GO command.For information on ESP’s job documentation facility, see the ESP Workload Manager User’s Guide.For information on displaying information from a job documentation library, see the JOBINFO command.For information on identifying a job documentation library in an Application, see the DOCLIB statement.

Examples Convert members beginning with JT and JVIn the following example, all members beginning with JT and JV are copied from JOBDOC.DATA to ESP.JOBDOC.DATA, suppressing any line numbers in the right-hand eight columns of each source member record:GENDOC 'JOBDOC.DATA' 'ESP.JOBDOC.DATA' LEVEL(JT-,JV SNUM

Remove comments, add labelsThe following GENDOC, REMOVE, LABEL and GO commands are used to convert existing job documentation:GENDOC 'JOBDOC.DATA' 'ESP.JOBDOC.DATA' LEV(A–,B–) SNUMREMOVE '**'LABEL 'SYSOUT REVIEW' 'SYSOUT_REVIEW' INLINELABEL 'STEP***' '@:' OVERLAYLABEL 'RESTART PROCEDURES' 'RESTART:' BEFOREGO

In the above example, ESP:• Copies all members beginning with A and B from the data set JOBDOC.DATA to

the data set ESP.JOBDOC.DATA, suppressing any line numbers in the right–hand eight columns of each source member record.

• Does not copy any lines containing **.• Replaces any lines starting with REVIEW with the character string

SYSOUT_REVIEW.

629

• Overlays the colon on any line beginning with STEP. The colon is positioned after the 3rd character following the string STEP.

• Places the label 'RESTART' on its own line before any line starting with the string 'RESTART PROCEDURES' with the copy process.

GENFLOW Command: Generate Flow Charts

630

GENFLOW Command: Generate Flow Charts

The GENFLOW command is used to export data that describes an ESP Application in a format usable by the PC-based project management software, Timeline. ESP uses information from a Scheduled Activity file and exports the jobname, start and end time fields.

TypeReporting command.

SyntaxGENFLOW 'inputdsn' 'outputdsn'

Usage NotesThe following summarizes how to generate flowcharts with ESP and Timeline:1. Issue the GENFLOW command indicating the input and output data sets2. Issue the FLOW command to identify the flowchart3. Issue the GO command to indicate all specifications are complete and that the

copy process should proceed4. Use a PC file transfer program to send the data to a PC

5. On the PC use a file editor to edit the file6. Access Timeline to import, view and print flowcharts.

Related informationFor information on identifying a flowchart, see the FLOW command.For information on indicating that all specifications are complete and that the copy process should proceed, see the GO command.For information on creating graphical representations of workload, see the ESP Workload Manager User’s Guide.For information on exporting data that describes an ESP Application in a format usable MS Project, see the GENPROJ command.

Operand Description

inputdsn Indicates the name of the scheduled activity data set, enclosed in quotes.

outputdsn Indicates the name of an output data set, enclosed in quotes. The output data set can be a sequential data set or a member of a PDS.

631

Example Export job names, start and end times to flowchartThe following GENFLOW, FLOW and GO commands are used to export data describing an ESP Application in a format usable by Timeline:GENFLOW 'ESP.DAILY.SADGEN' 'CYB.PC.TRANSFER'FLOW PAYROLL APPL(PAYROLL)GO

In the following example, ESP:• Exports the jobnames, start and end times of jobs in the PAYROLL Application• Identifies a flowchart called PAYROLL

• Proceeds with the copy process.Note: After the above is completed, transfer the file to a PC, edit that file and use

Timeline to import, view and print the PAYROLL flowchart.

GENPROJ Command: Generate Projects

632

GENPROJ Command: Generate Projects

The GENPROJ command is used to export data that describes an existing ESP Application in a format usable by the PC based project management software, MS Project. ESP exports the following fields:• jobname• subApplication name• start & end dates• duration• Late start & late end times• percent complete• tagNote: ESP Workstation is the preferred method for displaying and printing graphical

views of ESP Applications. The following shows an example of an ESP Workstation display:

TypeReporting command.

633

SyntaxGENPROJ applname[.gen|OLDEST] DATASET('outputdsn')

Usage notesThe Application used as input must be available on the APPLFILE (accessible via the LISTAPPL command). It can be in either an active or complete state.Information such as average or actual duration, starts date, end date, percent complete, late start time, late end time, etc. are exported and can be viewed.The file created by GENPROJ can be transferred to a PC and then imported into Microsoft Project for viewing or printing.The following summarizes how to generate flowcharts with ESP and MS Project:1. Issue the GENPROJ command indicating the name of an active Application, and

the output data set. The copy process should proceed.2. Use a PC file transfer program to send the data to a PC with an extension of.MPX.3. Access MS Project to view and print flowcharts. Note: CONVERT.EXE is no longer supported.

Related informationFor information on creating graphical representations of workload, see the ESP Work-load Manager User’s Guide.For information on exporting data that describes an ESP Application in a format usable by Timeline, see the GENFLOW command.

Operand Description

applname Indicates the name of the Application to be used as input. An absolute or relative generation number (gen) can also be specified as follows:• applname.0 indicates the most recent generation• applname.-n indicates the nth previous generation• applname.n indicates the absolute generation n

outputdsn Indicates the name of an output data set enclosed in quotes. The output data set can be a sequential data set or a member of a PDS. It can be VB or FB formats with an LRECL at least 72 bytes long. ESP does not write records longer than 72 bytes in length. ESP assigns the default attributes of RECFM= FB, LRECL= 80, BLKSIZE= 3120 to data sets that are allocated without DCB attributes.

OLDEST Indicates the oldest incomplete generation of the Application to be used as input. If all generations are complete, you can’t use OLDEST.

GENPROJ Command: Generate Projects

634

Examples Use current generationIn the following example, a file is generated called PAYROLL.FLOWCHRT that contains a description of the current generation of the PAYROLL Application. MS Project can then import this file.GENPROJ PAYROLL.0 DATASET('PAYROLL.FLOWCHRT')

Use oldest generationIn the following example, a file is generated called PAYROLL.FLOWCHRT that contains a description of the oldest incomplete generation of the PAYROLL Application. MS Project can then import this file.GENPROJ PAYROLL OLDEST DATASET('PAYROLL.FLOWCHRT')

635

GENTIME Command: Generate Times

The GENTIME command is used to customize date and time symbols for any scheduling criteria. It may be required to use date and time symbolic variables other than ESP’s built-in symbolic variables. Using the GENTIME command you create a set of customized date and time symbolic variables.

TypeESP Procedure statement, symbolic variable library statement.

SyntaxGENTIME prefix criteria

The prefixes 'ESPA' and 'ESPS' are reserved for ESP’s built–in symbols and cannot be used in the GENTIME command.You can test the symbols produced by a GENTIME command prior to storing the generated symbols permanently in a symbol library or ESP Procedure. Enter the following commands in Page mode or Line mode:• Enter the GENTIME command with your prefix and criteria.• Enter the ECHO command to send the symbols back to your terminal for display.Note: When you use a GENTIME command for testing or demonstration purposes,

the generated symbols are only temporary. They are lost when you exit from the ESP Main Menu.

When specifying the criteria in your GENTIME command via Page mode, it is advised to use 'STARTING' to establish effective time and get results consistent with your ESP Procedures.GENTIME variables are commonly used in JCL.

Operand Description

prefix Indicates a user-defined string of up to 55 characters that becomes the prefix for the symbols you generate with this statement.

criteria Schedule criteria that resolve to a single date and time.

GENTIME Command: Generate Times

636

The GENTIME command generates the following customized date and time symbolic variables:

You can use any of the variables you generate with the GENTIME command.

Related informationFor information on testing dates and times produced by the GENTIME command, see the ESP Workload Manager Advanced User’s Guide.

Variable Description

prefixDATE The Event date in full.• Example: Sunday 4th January 1998

prefixYY The last two digits of the year• Example: 98

prefixYEAR The Year.• Example: 1998

prefixMM The number of month.• Example: 01 for January

prefixMMM The first three characters of month.• Example: Jan

prefixMONTH The name of month.• Example: January

prefixDAY The name of the day of the week.• Example: Monday

prefixDD The number of actual day of month.• Example: 09

prefixDDD The Julian day, or the number day in the year.• Example: 365

PrefixDDQL The ordinal qualifier for the day.• Example: st, nd, rd or th

prefixDOW# The number of day in week as specified in a calendar.• Example: 1 for Sunday (ESP default)

prefixTIME The time in 24-hour format.• Example: 14.55.32

prefixHH The hour in 24-hour format.• Example: 14

prefixMN The minute of hour.• Example: 55

prefixSS The number of seconds past the minute.• Example: 32

637

Examples Next work dayIn the following example, a series of 14 customized date and time-based variables are generated that refer to the next workday. Each of the 14 variables is prefixed with 'NWD'. GENTIME NWD TODAY PLUS 1 WORKDAY

For example, if this GENTIME command was processed on February 18th, 2004:• %NWDMM resolves to 02• %NWDDD resolves to 049• %NWDYY resolves to 04• %NWDDOW# resolves to 4• %NWDDATE resolves to Wednesday February 18th, 2004.1st workday of monthIn the following example, a series of 14 customized date and time based variable are generated that refer to the first workday of the current month. Each of the 14 variables is prefixed with 'FWM'.GENTIME FWM FIRST WORKDAY OF MONTH STARTING TODAY

1st workday prior to 1 week agoIn the following example, the first GENTIME command generates a series of date and time variables that refer to one week ago. Each of the variables is prefixed with 'PWK'. This date is then used in the second GENTIME to generate another series of date and time variable that refer to a workday prior to one week ago. Each of these variables is prefixed with 'PWD'.The output from the first GENTIME command, in the following example, is used as input to another GENTIME command:GENTIME PWK TODAY LESS 1 WEEKGENTIME PWD %PWKDATE LESS 1 WORKDAYEstablish run frequency

The following GENTIME commands are used to establish a run frequency for a job in an Application:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'GENTIME AA LAST WORKDAY OF WEEK STA TODAY LESS 1 WEEKGENTIME BB LAST WORKDAY OF MONTH STA TODAY LESS 1 MONTHJOB PAYJOB1 IF TODAY('NOT LAST WORKDAY OF WEEK') AND - TODAY('LAST WORKDAY OF MONTH') THEN RUN TODAY IF TODAY('1ST FRI OF MONTH') AND %AADATE EQ %BBDATE THEN RUN TODAYENDJOB

GENTIME Command: Generate Times

638

In the above example:• If the last workday of the week is not the last workday of the month then run

PAYJOB1 today• If the last workday of the week is the last workday of the month then PAYJOB1 on

the 1ST Friday of the next month.

Other examplesHere are more examples using the GENTIME command.Seven days after today:In the following example generate seven days after today:GENTIME AA TODAY PLUS 7 DAYS

Two workdays prior to today:In the following example generate two workdays prior to todayGENTIME BB TODAY LESS 2 WORKDAYS

One week prior to today:In the following example generate one week prior to todayGENTIME CC TODAY LESS 1 WEEK

First workday of previous month:In the following example, generate first workday of previous monthGENTIME DD FIRST WORKDAY OF MONTH STARTING TODAY LESS 1 MONTH

Next day:In the following example, generate next dayGENTIME EE TODAY PLUS 1 DAY

Next workday:In the following example, generate next workdayGENTIME FF TODAY PLUS 1 WORKDAY

Two days after today:In the following example, generate two days after todayGENTIME GG TODAY PLUS 2 DAYS

639

GO Command: Indicate Completion

The GO command is used in conjunction with the GENDOC and GENFLOW commands. It indicates that the GENDOC or GENFLOW specification is complete and the copy process should begin.

TypeGeneral command, reporting command

SyntaxGO

Related informationFor information on ESP’s job documentation facility, see the ESP Workload Manager User’s Guide.For information on creating graphical representations of workload, see the ESP Workload Manager User’s Guide.

Examples Convert job documentationThe following GENDOC, REMOVE, LABEL and GO commands are used to convert existing job documentation:GENDOC 'JOBDOC.DATA' 'ESP.JOBDOC.DATA' LEV(A–,B–) SNUMREMOVE '**' LABEL 'RESTART PROCEDURES' 'RESTART:' BEFOREGO

In the above example, the GO command indicates that the GENDOC specification is complete and that the copy process should start.

Export data to TimelineThe following GENFLOW, FLOW and GO commands are used to export data describing an ESP Application in a format usable by Timeline:GENFLOW 'ESP.DAILY.SADGEN' 'CYB.PC.TRANSFER'FLOW PAYROLL APPL(PAYROLL)GO

In the above example, the GO command indicates that the GENFLOW specification is complete and that the copy process should start.

GROUP Command: Switch Groups Access

640

GROUP Command: Switch Groups Access

The GROUP command is used in Page mode to switch between a user’s user ID and any group (that is the high level prefix) the user can access. It is useful when using commands where a group prefix is required, such as TRIGGER.

TypeGeneral command

Syntax{GROUP|GR} [groupprefix] [USERID] [PREFIX]

Usage notesThe value of the group prefix is retained from session to session, until it is reset. The initial value is 'USERID'. The group prefix for Events is similar in concept to the TSO data set name prefix. If the GROUP command is entered without any operands, your current group prefix is displayed.The GROUP command can be used with or without the SAF interface.

Related informationIf you use GROUP with ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.For information on defining and deleting groups, see the DEFGROUP and DELGROUP commands.For information on displaying information about a group, see the LISTGRP command.

Operand Description

groupprefix Indicates up to eight characters to be the prefix for unqualified Event descriptive names. (You must be connected to the group specified.)

USERID Indicates the current TSO USERID is used to prefix unqualified Event names.

PREFIX Indicates the current TSO data set name prefix is used as the prefix for unqualified Event names.

641

Examples Display group prefixIn the following example, the current group prefix is displayed.GROUP

Switch user ID accessThe following GROUP command switches a user ID’s access to another group:GROUP PROD

In the above example, the default prefix is switched to PROD. To trigger an Event called PROD.PAYROLL, this user can issue the TRIGGER command without having to specify the group prefix, as follows:TRIGGER PAYROLL vs. TRIGGER PROD.PAYROLL

HARDCOPY Command: Divert Output to Data Set

642

HHARDCOPY Command: Divert Output to Data Set

The HARDCOPY command is used to request that a data type printout be diverted to a data set, sysout class or DD file. Each option is documented separately. The HARDCOPY command cannot be used in batch.

TypeGeneral command

Syntax{HARDCOPY|HCPY} DATASET('dsname[(member)]') [VOLUME(serial)] [UNIT(unitname)] [SPACE(primary[,secondary]){CYLINDERS}] {TRACKS}] {BLOCKS}] [EXTEND] [LRECL(length)] [RECFM{(V)|(F)}] [PAGELENGTH(lines)] [BLOCK(size)] [BLKSIZE(block)]

Operand Description

dsname Indicates the data set name, enclosed in quotes, to which the output should be diverted. You should include a member name if you are diverting output to a PDS.

serial Indicates the serial number (up to six characters) for the data set if you are specifying a new data set, or if you are using an existing data set that is not cataloged.

unitname Indicates the name of the output device type, using up to eight characters.

primary Indicates the primary allocation you want to assign, in parentheses. You must specify this if you are allocating CYLINDERS, TRACKS or BLOCKS.

secondary Indicates the secondary allocation you want to assign, in parentheses. If you use this operand you must use the appropriate keyword to specify whether you are allocating CYLINDERS, TRACKS or BLOCKS. If you are specifying primary and secondary allocation, specify one of these keywords after the secondary allocation specified. Do not use parentheses.

643

Usage notesUse this command in Pagemode when you want to direct output to a data set.

Related informationFor information on stopping the routing of output as specified by a HARDCOPY command, see the ENDHC command.

Examples Allocate tracksIn the following example, output is diverted to the PRINT1A.REPS data set, with a primary allocation of two tracks and a secondary allocation of one track, on the volume serial AX401B.HARDCOPY DATASET('PRINT1A.REPS') SPACE(2,1) TRACKS VOLUME(AX401B)

Divert output from LIST commandIn the following example, output produced by the LIST command is diverted to the CYB.HRDCPY data set.HARDCOPY DATASET('CYB.HRDCPY')L LEVEL(PROD-)ENDHC

EXTEND Indicates the output should be added to the end of the data set. If you do not specify EXTEND, the data set is overwritten.

length Indicates the logical record length for each line of output. Specify the number of characters you want in each line.

V Indicates variable length records. This is the default. The line length is four bytes less than what you specified under LRECL.

F Indicates fixed length records.

lines Indicates the number of lines on each page, including titles and footings.

size Indicates the size in bytes of a block allocation unit.

block Indicates the actual length of blocks on a data set. The limit is 32767 bytes.

Operand Description

HARDCOPY Command: Divert Output to DD File

644

HARDCOPY Command: Divert Output to DD File

The HARDCOPY command is used to request that a data type printout be diverted to a data set, sysout class or DD file. Each option is documented separately. The HARDCOPY command cannot be used in batch.

Syntax{HARDCOPY|HCPY} DDNAME(file) [EXTEND] [LRECL(length)] [RECFM{(V)|(F)}] [PAGELENGTH(lines)] [BLOCK(size)] [BLKSIZE(block)]

Usage notesUse this command in Page mode when you want to direct output to a DD name.

Related informationFor information on stopping the routing of outputs specified by a HARDCOPY command, see the ENDHC command.

Operand Description

file Indicates a file name using up to eight characters.

EXTEND Indicates that the output should be added to the end of the data set.

length Indicates the logical record length for each line of output. Specify the number of characters you want in each line.

V Indicates variable length records. This is the default. The line length is four bytes less than what you specified under 'LRECL'.

F Indicates fixed length records.

lines Indicates the number of lines on each page, including titles and footings.

size Indicates the size in bytes of a block allocation unit.

block Indicates the actual length of blocks on a data set. The limit is 32767 bytes.

645

Examples Specify record lengthIn the following example, output is diverted to the HISTREC1 file. The logical record length for each line of output should be 80, in fixed length records. All output is added to the end of the file.HARDCOPY DDNAME(HISTREC1) LRECL(80) RECFM(F) EXTEND

Divert output from LIST commandIn the following example, output produced by the LIST command is diverted to the HRDCPY file.HARDCOPY DDNAME(HRDCPY)L LEVEL(PROD-)ENDHC

HARDCOPY Command: Divert Output to Sysout Class

646

HARDCOPY Command: Divert Output to Sysout Class

The HARDCOPY command is used to request that a data type printout be diverted to a data set, sysout class or DD file. Each option is documented separately. The HARDCOPY command cannot be used in batch.

TypeGeneral command.

Syntax{HARDCOPY|HCPY} SYSOUT(class) [DEST(destcode)] [COPIES(n)] [FORM(type)] [LRECL(length)] [RECFM{(V)|(F)}] [PAGELENGTH(lines)] [UCS(char)] [SPIN]

Usage notesUse this command in Page mode when you want to direct output to SYSOUT.

Operand Description

class Indicates a one-character class number.

destcode Indicates a destination code of up to eight characters. If you do not specify 'DEST', the destination defaults to 'LOCAL'.

n Indicates the number of copies you want printed. The maximum is 240 copies.

type Indicates the type of form you want to use for printing, using up to four characters for the code.

length Indicates the logical record length for each line of output. Specify the number of characters you want in each line.

V Indicates variable length records. This is the default. The line length is four bytes less than what you have specified under 'LRECL'.

F Indicates fixed length records.

lines Indicates the number of lines on each page, including titles and footings.

char Indicates the universal character set type you want to be used on the printer for this printout.

SPIN Indicates that the data should be made available for printing as soon as you enter the ENDHC (end hardcopy) command.

647

Related informationFor information on stopping the routing of output as specified by a HARDCOPY command, see the ENDHC command.

Examples Specify destination and formIn the following example, output is diverted to SYSOUT class 1. The destination is RMT1 and the form is ANC8. The data is available as soon as the ENDHC command is specified.HARDCOPY SYSOUT(1) DEST(RMT1) FORM(ANC8) SPIN

Divert output of LIST commandIn the following example, output produced by the LIST command is stored under your user ID.HARDCOPY SYSOUT(S)L LEVEL(PROD-)ENDHC

HISTFILE Command: Include History Files in Report

648

HISTFILE Command: Include History Files in Report

The HISTFILE command is used as part of a report definition. HISTFILE specifies the identifiers of the HISTORY files to scan to generate a history report.

TypeReporting command

AuthorityYou may be restricted to history files to which you have access. This is controlled via your ESP administrator. In SAF environments access is specified in the User Profile Definition Table. In non-SAF environments access is specified via the DEFUSER command.

SyntaxHISTFILE hfid

Usage notesIf you omit this operand, all history files to which you are permitted access are scanned.

Related StatementsFor information on defining or altering the history file, see the HISTFILE command, or the HISTFILE initialization parameter in the ESP Workload Manager Installation and Configuration Guide.For information on defining or altering the history file, see the HISTFILE command in the ESP Workload Manager Installation and Configuration Guide.For information on history reporting, see the ESP Workload Manager User’s Guide.

For information on displaying history files, see the LISTHIST command.For information on working with history files, see the ESP Workload Manager System Programmer’s Guide.

Operand Description

hfid Indicates the history file identifier of up to eight characters. Several identifiers can be specified if enclosed in parentheses and separated by blanks or commas.

649

Examples Sample history report definitionIn the following example:• The REPORT command invokes the report processor• The HISTFILE command indicates that HIST1 is to be scanned• The FROM, CRITERIA and DISPLAY report statements define the report• The ENDR command ends the report definition and initiates report generation.REPORTHISTFILE HIST1FROM 7AM YESTERDAYCRITERIA APPLSYS EQ PAYROLLDISPLAY JOBNAME JOBNO APPLSYS CMPCENDR

Other examplesHere are more examples using the HISTFILE command.Indicates that history files with HIST in the first four positions are used:HISTFILE HIST-

Indicates that HIST1 and HIST2 are used:HISTFILE (HIST1,HIST2)

HISTFILE Command: Define or Alter History File

650

HISTFILE Command: Define or Alter History File

Used to define or alter the definition of an ESP history data set.

TypeGeneral command

AuthorityYou require OPER authority to issue the HISTFILE command.

SyntaxHISTFILE histfid [DSNAME(dsname)] [NEWDSNAME(newdsname)] [BACKUPDSNAME(backupdsname)|NOBACKUPDSNAME] [DEFINE|DELETE|OPEN|CLOSE|SET] [SHR|NOSHR] [JOURNAL|NOJOURNAL] [BACKUPTIME('schedule')|NOBACKUPTIME]

Operand Descriptionhistfid Indicates a unique identifier of up to eight characters.DSNAME(dsname) Indicates the name of a VSAM KSDS.NEWDSNAME(newdsname)

Indicates the name of a VSAM KSDS.

BACKUPDSNAME(backupdsname)

Indicates a non-VSAM sequential data set.

NOBACKUPDSNAME Used to remove the backupdsname, if already specified.DEFINE Indicates a new History file data base is being defined. If not

specified, DEFINE is assumed.DELETE Indicates a HISTFILE definition is to be deleted. The associated

VSAM data set is NOT deleted, only the logical HISTFILE ID is deleted.

OPEN Indicates a histfile is to be reopened.CLOSE Indicates a HISTFILE is to be closed and de-allocated.SET Indicates an existing specification is changed without the need to open

or close the data set.SHR Indicates the data set is to be shared.NOSHR Indicates the data set is not to be shared.

651

Usage notesThe HISTFILE command is used to define and initialize a job history data set. Use the DEFINE keyword along with the DSNAME Operand. The identifier (up to eight characters) is the name to be associated with that logical entity.When a tracking model is defined, a job history file ID can be specified. This identifies to which data set the history data is written. Use of the ID rather than the data set name allows the actual data set name to be changed without having to alter all references to it.The BACKUPTIME keyword specifies a time at which time the HISTFILE is automatically backed up to the BACKUPDSNAME data set.You can also backup a history file with the BKUPHIST command.

Related informationFor information on working with history files, see the ESP Workload Manager System Programmer’s Guide.For information on displaying history files, see the LISTHIST command.

Examples Define history fileIn the following example, a new history recording file called HISTF1 is defined. The actual data set used is ESP.HISTFILE, and its disposition is shared.HISTFILE HISTF1 DEFINE DSNAME(ESP.HISTFILE) SHR

Set journal optionIn the following example, records are written to SMF each time a history record is inserted, updated or deleted.HISTFILE HISTF1 SET JOURNAL

Close a history fileIn the following example, HIST1 is closed and de-allocated from ESP.HISTFILE HISTF1 CLOSE

JOURNAL Indicates a record be written to SMF each time a history record is inserted, updated or deleted.

NOJOURNAL Indicates no records be written to SMF when the HISTFILE is updated. Use this keyword to cancel a previous JOURNAL request.

BACKUPTIME('schedule')

Indicates a time schedule using the same syntax as ESP schedule statements. If the text string contains blanks or commas, it should be enclosed within quotes.

NOBACKUPTIME Used to remove the backuptime, if already specified.

Operand Description

HOLD Command: Hold Events

652

HOLD Command: Hold Events

The HOLD command is used to hold an Event from being processed by ESP. This increments the Event’s hold count. While the hold count is greater than zero, the Event’s execution is postponed until the hold count is decremented by the RELEASE command.

TypeGeneral command.

SyntaxHOLD eventid

Usage notesHolding an Event is different from suspending it.If the scheduled time for an Event comes up while it is in the suspended state, the Event execution is bypassed, and it is not considered overdue.If the Event is in a held state, it is placed in an overdue status. When the Event is finally released, the overdue count is checked to see whether execution should proceed. The Event is checked immediately for every occurrence missed while in the held state, up to the overdue limit count specified when the Event was defined.If an Event is in both a suspended and hold state when due for scheduling, the hold state is ignored, and the Event is considered suspended.The HOLD command is used in conjunction with the RELEASE command. (The SUSPEND command goes hand in hand with the RESUME command.)

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.For information on decrementing an Event’s hold count that was previously incremented via a HOLD command, see the RELEASE command.For information on bypassing and resuming an Event’s execution, see the SUSPEND and RESUME commands.

Operand Description

eventid Indicates a valid Event name. If the prefix is omitted the current prefix as set by the GROUP command is used.

653

Example Postpone execution of eventIn the following example, CYBER.PAYROLL is held, incrementing its hold count to one. To decrement the hold count, use the RELEASE command to make CYBER.PAYROLL eligible for execution.HOLD CYBER.PAYROLL

HOLD Command: Hold Events at Specific Time

654

HOLD Command: Hold Events at Specific Time

The HOLD command at the Event level is used to hold an Event from being processed by ESP at a particular time. When ESP encounters a HOLD command in an Event, it increments the Event’s hold count by one at the time and date specified in the command. While the hold count is greater than zero, the Event’s execution is postponed until the hold count is decremented by the RELEASE command.

TypeEvent definition command.

SyntaxHOLD criteria

Usage notesThe RELEASE command is used in conjunction with the HOLD command to make a previously postponed Event eligible for execution.If an Event is in both a suspended and a held state when due for scheduling, the Event is considered suspended.When the hold count of an Event is reduced to zero, the Event’s overdue count specified at definition time, on the SCHEDULE command, determines the number of times the Event should execute. The default overdue count is one. Issuing a HOLD command against an Event that invokes an Application takes effect on the next scheduled execution of that Event. An active Application that has a HOLD command issued against the Event that invokes it does not cause that Application to stop processing. Use the APPLJOB or AJ command to manipulate Applications and jobs belonging to Applications.If you are using a time zone on your HOLD command, you should use the same timezone on your RELEASE command. If the Event has a schedule statement, the same time zone should be used on the SCHEDULE, HOLD and RELEASE commands.Note: The RESUME command is used in conjunction with the SUSPEND command

to make a previously bypassed Event eligible for execution.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.For information on decrementing an Event’s hold count that was previously incremented via a HOLD command, see the RELEASE command.

Operand Descriptioncriteria Schedule criteria.

655

Examples Event definition exampleThe following is an example of an Event definition:EVENT ID(CYBER.PAYROLL) DSTRIG PAYROLL.INPUTHOLD DAILY AT 9AMRELEASE DAILY AT 11AMSUBMIT 'CYBER.JCL.CNTL(PAYJOB1)'ENDDEF

In the following example, HOLD and RELEASE commands are used to prevent PAYJOB1 from being submitted between 9 am and 11 am. If the PAYROLL.INPUT data set is created during 9 am and 11 am, the Event waits.The following is an example of the comments ESP adds to the Event if the PAYROLL.INPUT is created between 9 am and 11 am:EVENT ID(CYBER.PAYROLL) DSTRIG PAYROLL.INPUTHOLD DAILY AT 9AMRELEASE DAILY AT 11AMSUBMIT 'CYBER.JCL.CNTL(PAYJOB1)'/* FOLLOWING EXECUTIONS PENDING:/* DATASET TRIGGER BY JOB ACCJOB9 AT 09.15.00 ON THU FEB, 1998/* DSN PAYROLL.INPUTENDDEF

Prevent submission between 9 and 11In the following example, HOLD and RELEASE commands are used to prevent PAYJOB2 from being submitted between 9 am and 11 am on February 14 2004. EVENT ID(CYBER.PAYROLL) DSTRIG PAYROLL.INPUTHOLD 9AM FEB 14, 2004 ONCERELEASE 11AM FEB 14, 2004 ONCESUBMIT 'CYBER.JCL.CNTL(PAYJOB2)'ENDDEF

HPUX_JOB Statement: Identify the Name of HPUX Jobs

656

HPUX_JOB Statement: Identify the Name of HPUX Jobs

The HPUX_JOB statement is used to identify the name of an HPUX job in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use HPUX jobs, you must load a workload object module. The HPUX_JOB workload object module is CYBESOHP. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Refer to the JOB statement usage notes.

ExampleHPUX_JOB PAYDATA RUN DAILY RELEASE PAYRPT AGENT HPUX_NY SCRIPTNAME /usr/data/payENDJOB

657

IIF Statement: Process Instructions Conditionally

The IF statement is used to conditionally process an instruction or group of instructions depending on the evaluation of an expression. The IF statement is used in conjunction with the THEN and ELSE statements.

TypeControl Language (CLANG) statement.

SyntaxIF expression

Usage notesWhen you use an IF statement, the expression that follows it must return a true or false value. You can use any number of nested IF statements.The THEN statement is used in conjunction with an IF statement when the expression that follows the IF statement returns a true value.The ELSE statement is used in conjunction with an IF statement when the expression that follows the IF statement returns a false value.If a THEN or ELSE statement continues to another line, use a line continuation character (– or +). If there is no continuation character, ESP ignores the THEN or ELSE statements.You must begin and end compound action statements with DO and ENDDO language elements.When ESP encounters an IF statement that evaluates as false, ESP skips everything until an ELSE or ENDDO statement is encountered, this includes any symbolic variable declarations. Symbolic variable declarations coded within an IF statement block that evaluate as false will result in a variable not defined error message. If you want a symbolic variable to be available inside and outside an IF statement block, declare it outside.

Related StatementsFor information on using ESP’s Control Language, see the ESP Workload Manager User’s Guide and ESP Workload Manager Advanced User’s Guide.For more information on specifying conditional logic, see the THEN and ELSE statements.

Operand Descriptionexpression Indicates an expression that can be evaluated to return a true or false

value.

IF Statement: Process Instructions Conditionally

658

Examples Process different actionsIn the following example, ESP determines if the actual day is equal to Monday. If the evaluation of this expression is true, ESP sends a message indicating that today is Monday to USR01. If the evaluation of this expression is false, ESP sends a message to USR01 indicating what today is.IF %ESPADAY = 'MONDAY' THEN - SEND 'TODAY IS MONDAY' U(USR01)ELSE - SEND 'TODAY IS %ESPADAY' U(USR01)

Determine when job runsIn the following example, ESP determines if today is the first day of the month and TUESDAY, and if this condition is true then PAYJOB1 is selected to run.JOB PAYJOB1 IF TODAY('FIRST DAY OF MONTH') AND TODAY('TUESDAY') THEN - RUN TODAYENDJOB

Set symbolic variableIn the following example, a user defined symbolic variable called 'FINANCIAL_YEAR' which consists of two, two–digit year numbers, and is set as follows:• if the current month is January, February, March or April, use last year followed

by this year • for any other month, use current year followed by next year.IF ESPSMM<5 THEN DO GENTIME LAST TODAY LESS 1 YEAR FINANCIAL_YEAR='%LASTYY%ESPSYY'ENDDOELSE DO GENTIME NEXT TODAY PLUS 1 YEAR FINANCIAL_YEAR='%ESPSYY%NEXTYY'ENDDO

659

%INCLUDE Statement: Request Inclusion of JCL

The %INCLUDE statement requests selective inclusion of JCL and DATA based on criteria such as time, date, day of the week and Event ID, or a combination of these operands. The %INCLUDE statement is used to include portions of JCL or to include control statements from a symbolic variable library.

TypeESP control statement used in JCL and in symbolic variable library statement.

Syntax%INCLUDE [FROM(fromdate)] [TO(todate)] [DAY(dayofweek[,dayofweek]...)] [EVENT(eventid)] [IF(expression)] [COPYJCL]

Operand Descriptionfromdate Indicates a time and date specification in any format that is valid in a schedule

statement.todate Indicates a time and date specification in any format that is valid in a schedule

statement. dayofweek Indicates a valid day of week name, which can be abbreviated to the first three

characters. Several day of week names can be specified, separated by blanks or commas.

eventid Indicates a valid Event name, which can contain the prefix and descriptive name, or just the descriptive name of the Event. If the prefix is omitted, the prefix of the current Event is assumed. Several Event IDs can be specified, separated by blanks or commas.

expression Value of a logical expression.COPYJCL Specifies the inclusion should apply to the copy of the JCL written to a library

as a result of the COPYJCL statement. Note: Applies to JCL tailoring only, and not to symbolic variable libraries.

%INCLUDE Statement: Request Inclusion of JCL

660

Usage notesThe %INCLUDE statement cannot be used in an ESP Procedure.The %INCLUDE operand must start in Column 1. If you want to include a statement with the characters %INCLUDE starting in column 1, but to have it treated as data rather than a control statement, code %%INCLUDE. The first percent sign is removed.The %INCLUDE statement can be continued onto a second line by placing a '+' 'or' '-' on the last non-blank character of the line. A '+' strips leading blanks from the next line, whereas a '-' does not. Only one continuation per statement is allowed.The scope of an %INCLUDE statement includes data until one of the following statements is encountered: • %INCLUDE statement• %EXCLUDE statement• %ENDINCL statement

• %ENDEXCL statement.If no operands are specified, the data following the %INCLUDE statement is always included.If you specify a FROM date but no TO date, a TO date of January 1st 2042 is assumed. Similarly, if you omit a FROM date, a date of January 1st 1900 is assumed.If no time is specified, 00:00 is assumed for the FROM and TO operands. The FROM and TO operands are based on the scheduled date.ESP decides what to include in the JCL when it submits the job.Note: Before using the %INCLUDE statement, check with your system administrator

to ensure no changes were made during your ESP installation that affect the way ESP recognizes these statements. For example, another product may make conflicting use of these terms, in which case your system administrator can change them.

Related informationFor information on selectively excluding JCL and DATA, see the %EXCLUDE statement.For information on ending the selective inclusion of JCL and DATA, see the %ENDINCL statement.

661

Examples Include data on MondaysIn the following example, the value of PARM resolves to 'ABC' on Mondays.%INCLUDE DAY(MONDAY)PARM='ABC'%ENDINCL

Include DD Statement on MondaysIn the following example, the DD statement INPUT05 is included on Mondays.%INCLUDE DAY(MONDAY)//INPUT05 DD DSN=CYBER.INPUT.DATA,DISP=SHR%ENDINCL

Include different dataIn the following example, the value of DIVISION resolves to '123' on Monday, Wednesday or Friday and to '456' on Tuesday, Thursday or Saturday. These days refer to the scheduled days of the Event.%INCLUDE IF(TODAY('MON,WED,FRI'))DIVISION='123'%INCLUDE IF(TODAY('TUE,THU,SAT'))DIVISION='456'%ENDINCL

Include various stepsThe following %INCLUDE statements used in JCL request the inclusion of various steps://CYBERJOB JOB CYB999,CLASS=A,MSGCLASS=S//STEP1 EXEC PGM=IEFBR14%INCLUDE IF(ESPSDATE=ESPADATE)//STEP2 EXEC PGM=PGM1%INCLUDE IF(ESPATIME GT 07.59.00)//STEP3 EXEC PGM=PGM2%INCLUDE FROM('MAY 1,1997') TO('MAY 5,1997')//STEP4 EXEC PGM=PGM3%INCLUDE IF(ESPAHH GE '08' AND ESPAHH LE '14' AND -TODAY('WED'))//STEP5 EXEC PGM=PGM4%ENDINCL

In the following example:• STEP1 is included whenever ESP submits the job• STEP2 is included when the actual and scheduled date are equal• STEP3 is included when the actual time is greater than 07.59.00

%INCLUDE Statement: Request Inclusion of JCL

662

• STEP4 is included from May 1,1997 to midnight on May 4,1997. This is based on the scheduled date.

• STEP5 is included if the actual is between 8am and 2pm and the scheduled day is Wednesday.

Other examplesHere are more examples using the %INCLUDE statement.Request inclusion if the value of CYCLE_NUMBER is equal to 9:%INCLUDE IF(CYCLE_NUMBER=9)

Request inclusion if the actual hour is greater that 09 and today is not Friday:%INCLUDE IF(ESPAHH GT '09' AND TODAY('NOT FRIDAY'))

Request inclusion if a started task called CICSPROD is active:%INCLUDE IF(ACTIVE('CICSPROD'))

Request inclusion if today is the last day of the year:%INCLUDE IF (TODAY('LAST DAY OF YEAR'))

663

INET Command: Manipulate TCP/IP Attributes

The INET command is used to display and manipulate TCP/IP attributes.

AuthorityYou require OPER authority to issue the INET command.

SyntaxINET {DISPLAY} {ACTIVE} {CLOSE} {HOST_CACHE} {TCPIP} {TRACE} {BIND} {FLUSH HOST_CACHE} {HELP} {PURGE {ID socketid|TASK taskid}} {QUERY HOST hostname} {SET} {TRACE} SYSOUT(class) {CLOSE {RESET|SHUTDOWN}} {HOST_CACHE TTL(seconds)} {BIND {REUSEADDR|NOREUSEADDR}} {SPIN} {TRACE} {START}{TRACE} {STOP} {TRACE}

Operand DescriptionDISPLAY Displays a TCP/IP object. The following options are supported:

• INET DISPLAY ACTIVE• CLOSE• INET DISPLAY HOST_CACHE• INET DISPLAY TCPIP• INET DISPLAY TRACE• INET DISPLAY BIND

ACTIVE Display of all active TCP/IP sockets.CLOSE Displays the current TCP/IP close option.

(RESET or SHUTDOWN)HOST_CACHE Displays the ESP TCP/IP host cache entries. TCPIP Displays information on the current TCP/IP stack.TRACE Displays TCP/IP tracing facility.BIND Displays the current TCP/IP bind

INET Command: Manipulate TCP/IP Attributes

664

FLUSH HOST_CACHE

FLUSH HOST_CACHE flushes the ESP TCP/IP host cache. This is useful if a host cache entry has become invalid because of a modification to a host entry in the TCP/IP network’s Domain Name System (DNS) configuration.

HELP Displays all the INET command options.PURGE Purges a TCP/IP socket or all TCP/IP sockets running under a specified

task.ID Requests that an active socket be purged.

Note: This option is not supported if IBM’s IUCV is the TCP/IP stack.socketid Displays a list of currently active TCP/IP sockets.TASK Displays a list of currently active TCP/IP sockets and their respective

task IDs.taskid Displays a list of currently active TCP/IP sockets and their respective

task IDs.QUERY HOST hostname

Displays the TCP/IP address of a host. The short form is: INET Q H hostname.

SET Sets a TCP/IP object.SYSOUT(class) Indicates a print data set for the TRACE log SYSOUT.CLOSE This operand should only be used under the direction of Cybermation

technical support. It tells ESP and Workstation server how to close a TCP/IP connection, either gracefully (SHUTDOWN) or forcefully (RESET). The default is SHUTDOWN.

HOST_CACHE TTL Used to activate or de-activate ESP TCP/IP host caching, or to reset the time to live(TTL) interval. Seconds is the time to live value within the range 0-99999999. A value of zero(0) de-activates ESP TCP/IP host caching. This command can also be specified in the initialization parameters.

BIND {REUSEADDR|NOREUSEADDR}

Sets the TCP/IP bind option. If you use REUSEADDR, the TCP/IP bind will not fail if TCP/IP connection sockets are active using the requested TCP/IP port.

Note: If another listener socket is bound to the requested port, the TCP/IP bind always fails.

SPIN Spins a TCP/IP object. Currently the only supported option is:• INET SPIN TRACEThe TCP/IP trace sysout file is closed and deallocated. A new one is then immediately allocated and opened.

Operand Description

665

Usage NotesESP Agents and distributed manager hosts can be identified by either DNS host name or IP address. If you use the host name, ESP Workload Manager converts it to an IP address before connecting to the target Agent. By default, the GetHostByName lookup routine does the connection. ESP Workload Manager exploits the TCP/IP host caching mechanism to perform the host name to IP address lookups process. When activated the first time:• A lookup is done for a given host• A memory host cache entry is created• The GetHostByName lookup is performedESP Workload Manager maintains a memory cache of a host name and the corresponding IP address after the first DNS lookup. The cache is used for subsequent lookups, sparing the overhead of unnecessary DNS lookups.If you use frequently the same set of host names, activating ESP's host caching minimize the number of real DNS lookups.Host caching improves significantly ESP Workload Manager TCP/IP performance if:• Agent and distributed manager hosts are identified to ESP Workload Manager by

host names rather than IP dotted decimal address• Connections are frequent• TCP/IP name server resides on a different system from ESP Workload Manager

Examples:List INET optionsIn the following example, all of the INET command operands are displayed.INET HELP

Display TCP/IP socketsIn the following example, all active TCP/IP sockets are displayed.INET DISPLAY ACTIVE

START Starts a TCP/IP object. Currently the only supported option is:• INET START TRACEA TCP/IP trace sysout file is allocated and opened. Before the TCP/IP trace file can be started, it must be set to a sysout class by the INET SET TRACE SYSOUT(class) command.

STOP Stops a TCP/IP object. Currently the only supported option is:• INET STOP TRACEThe TCP/IP trace file is closed and de-allocated.

Operand Description

INET Command: Manipulate TCP/IP Attributes

666

Purge all socketsIn the following example, all TCP/IP sockets running under task ID 78E0 are purged.INET PURGE TASK 78E0

Activate host cachingThe following short form of the INET SET HOST_CACHE command activates ESP TCP/IP host caching and sets the time to live interval for each host cache entry to one hour:INET T HC TTL(3600)

Deactivate host cachingThe following short form of the INET SET HOST_CACHE command deactivates ESP TCP/IP host caching:INET T HC TTL(0)

667

INFOCOMM Command: Control InfoServ Transaction Servers

The INFOCOMM command is used to control transaction servers used in sending Infoserv requests. Transaction server identifiers are used on the INFOSERV command when issuing requests.

TypeGeneral command.

AuthorityYou require OPER authority to issue the INFOCOMM command.

SyntaxINFOCOMM {DEFINE|DISPLAY|DELETE} [serverid] [CLIENT(clientname)] [TPAPPL(applname)]

Usage notesFor each client defined to Infoserv you must define a transaction server that will transmit requests to Infoserv via the LU6.2 Communications Facility (TP Server).INFOCOMM definitions are normally stored in the ESP initialization parameter data set.

Operand DescriptionDEFINE Indicates a new server transaction be added.DISPLAY Indicates information on all (or specific) servers for the current

Application be displayed. Information displayed includes serverid, client name and TP Application name.

DELETE Indicates the deletion of a transaction server.serverid Indicates a logical server identifier of up to 25 characters. This

identifier is specified on the INFOSERV command when sending a request.

clientname Indicates a client name of up to eight characters for your Application. This client must be defined to Infoserv via the CLIDEF command.

applname Indicates a 1-44 character TP Application name of the Infoserv task to which this transaction server will send its requests. The applname is defined in the Infoserv TP parameter data set.

INFOCOMM Command: Control InfoServ Transaction Servers

668

Related informationFor information on ESP Workload Manager’s interface to IBM’s Information/Management product, see the Infoserv Installation and User’s Guide.For information on generating a request that is sent to Infoserv, see the INFOSERV command.For information on inter-system communication, see the TP Server Installation and User’s Guide.

Examples Define transaction serverIn the following example, a new transaction server called INFO1 is defined. The client name for this Application is ESP and must be defined to Infoserv using the CLIDEF command. The INFO1 transaction server will send requests to the INFOSERV_MAIN TP Application.INFOCOMM DEFINE INFO1 CLIENT(ESP) TPAPPL(INFOSERV_MAIN)

Display transaction serversIn the following example, all existing transaction servers are displayed.INFOCOMM DISPLAY

Delete transaction serverIn the following example, a transaction server called INFO1 is deleted.INFOCOMM DELETE INFO1

669

INFOMSG Command: Display Messages in Screen Body

The INFOMSG command is used to display informational, warning and error messages in the body of the screen. Normally these messages are displayed in the upper right corner of the screen with an alarm sound.

TypeGeneral command.

SyntaxINFOMSG SET|RESET [PREFIX('string')]

Usage notesThe INFOMSG command is valid only from within Page mode.If you exit from Page mode and re-enter, you need to re-issue the INFOMSG command.When the INFOMSG command is set, messages are within the screen text. You can have the messages prefixed with any string by specifying a string when issuing the INFOMSG command.

Operand DescriptionSET Indicates messages should be displayed within the body of the

screen. This includes the full message text and ESP message number.

PREFIX('string') Indicates displayed messages should be prefixed with a user specified string. PREFIX can be abbreviated to PR. This operand is optional.

RESET Indicates messages should be returned to their normal position in the upper right corner of the screen.

INFOMSG Command: Display Messages in Screen Body

670

Examples:When INFOMSG not setThe following is an example of what an informational message looks like when the INFOMSG command is not set:ESP ------------------------------------- NO MATCHING APPLICATIONS

COMMAND ===>

----------------------- TOP OF DATA ------------------

LAP PAYROLL OLDEST

In the above example, a request is made to display the oldest generation of the PAYROLL Application. An informational message indicates there are no matching Applications.When INFOMSG setThe following is an example of what an informational message looks like when the INFOMSG command is set:ESP ------------------------------- ROW 1 COLUMN 1 --

COMMAND ===>

----------------------- TOP OF DATA ------------------

INFOMSG SETLAP PAYROLL OLDESTESP1142W NO MATCHING APPLICATIONS DEFINED OR AUTHORIZED

In the above example, a request is made to display the oldest generation of the PAYROLL Application. An informational message indicates there are no matching Applications is displayed within the body of the screen. Reset messagesIn the following example, informational messages are displayed in the upper corner of the screen.INFOMSG RESET

Prefix messagesThe following INFOMSG command prefixes information messages:INFOMSG SET PREFIX(INFO_)

In the preceding example, informational messages are prefixed with INFO_.

671

INFOPACK Statement: Identify Name of Business Warehouse InfoPackage on SAP System

The INFOPACK statement identifies the name of a Business Warehouse InfoPackage (BWIP) on the SAP system.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within a BWIP_JOB workload object.

SyntaxINFOPACK ’InfoPackage’

Usage notesINFOPACK is a required statement within a BWIP_JOB workload object.

ExampleIn this example, BWIP job BWIPTEST runs the InfoPackage ZPAK_6C7ZW2JAXS90AK71WD1CYIN on the SAP system.APPL BWIPTESTBWIP_JOB BWIPTEST AGENT SAPHTAGENT INFOPACK ‘ZPAK_6C7ZW2JAXS90AK71WD1CYIN’ RUN DAILYENDJOB

Operand DescriptionInfoPackage Specifies the name of the Business Warehouse InfoPackage. It is

case sensitive and can be up to 30 valid SAP characters in length.

INIT Command: Manipulate Initiators

672

INIT Command: Manipulate Initiators

The INIT command is used to define and manipulate initiators in your model process similar to the way you manipulate initiators using JES. The INIT command is one of the components involved in defining your environment to produce modeling reports that forecast how ESP processes a group of jobs in your particular environment.

TypeModel command.

SyntaxINIT {START(initnum)} {SET(initnum)} {STOP(initnum)} [CLASS(classname)] [CPU(cpunumber)]

Usage notesUse the MAXINITS command to define the maximum number of initiators for the model. This should include initiators across all CPUs. A maximum of 999 initiators can exist for each model.

Operand DescriptionSTART Indicates the initiators in initnum is started on the specified CPU. If

the initiator is currently in a drained state, its status is changed to inactive. The INIT START command is ignored if the initiator is not currently in a drained state.

SET Indicates the classes of the initiators in initnum are reset to the specified classname. Any classes previously assigned to the initiators are replaced. The CPU that an initiator has been started on may not be altered with the SET keyword.

STOP Indicates the initiators in initnum is stopped. Any jobs running in the specified initiators is allowed to complete and the initiator status is changed to drained.

initnum Indicates a number, range of numbers, or list of numbers and ranges of numbers. Each number must be within the range 1-999.

classname Indicates up to eight character class names or list of class names assigned to this initiator. The first character must be alphabetic.

cpunumber Indicates a CPU number where the initiators are to be started. The valid range is 0-7 (up to eight CPUs supported). If not specified, the default is 0. The CPU keyword should only be specified with the START keyword.

673

Initially, the number of initiators you specify on the MAXINITS command are in a drained state. At any time during modeling, you can manipulate initiators on any CPU.Use INIT START, SET and STOP to start, alter and drain initiators any time during the model process.

Related informationFor information on defining the maximum number of initiators, see the MAXINITS command.For information on how ESP processes workload in your environment, see the ESP Workload Manager Advanced User’s Guide.For information on beginning and ending the model process, see the MODEL and ENDMODEL commands.

Example Define initiatorsIn the following example:• Initiators 1 to 10 are started and set to classes A, B and C• Initiators 11 to 15 are started and set to class D and E• Initiators 16 to 20 are started and set to class FMAXINITS 20INIT START(1:10) CLASS(A,B,C)INIT START(11:15) CLASS(D,E)INIT START(16:20) CLASS(F)

Note: Any time during the model process you can manipulate initiators similar to the way initiators are manipulated in your environment using the START, SET and STOP operands of the INIT command. For example, if required, initiators 16 to 20 could be drained by issuing the following command:

INIT STOP(16:20)

INITIAL_CONTEXT Statement: Specify Initial Context Factory (J2EE)

674

INITIAL_CONTEXT Statement: Specify Initial Context Factory (J2EE)

The INITIAL_CONTEXT statement specifies the Initial Context Factory to use when creating the initial context. The initial context is required within the JNDI framework. The Initial Context Factory is provided by a specific provider of the naming and directory service. The factory is responsible for acquiring an arbitrary initial context that the application can use.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within the EJB_JOB, JMSP_JOB, and JMSS_JOB workload objects

SyntaxINITIAL_CONTEXT factory

Usage notesINITIAL_CONTEXT is a mandatory statement within the EJB_JOB, JMSP_JOB, and JMSS_JOB workload objects.

ExamplesWebLogicIn this example, the CYBJK.SB job uses weblogic.jndi.WLInitialContextFactory as the Initial Context Factory.APPL TESTSBEJB_JOB CYBJK.SB HOLD RUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(java.lang.String) VALUE(A23)ENDJOB

Operand Descriptionfactory The Initial Context Factory to use when creating the initial

context. factory is case sensitive and can be up to 1024 characters.

675

WebSphereIn this example, the CYBJK.SB job uses com.ibm.websphere.naming.WsnInitialContextFactory as the Initial Context Factory.APPL TESTSBEJB_JOB CYBJK.SB HOLD RUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT + com.ibm.websphere.naming.WsnInitialContextFactory JNDIUSER cyberuser LOCATION iiop://100.10.31.66:2809 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(java.lang.String) VALUE(A23)ENDJOB

INPUT Command: Request Input from Data Sets

676

INPUT Command: Request Input from Data Sets

The INPUT command is used to request that ESP read in other records from a data set other than an active history file. Use any VSAM, KSDS, ESDS or non-VSAM sequential data set as input. The data records must be of the exact same format as the ESP history file records.

TypeReporting command.

SyntaxINPUT {DATASET(dsname)} {FILE(filename)}

Usage notesThis option is most useful when used with files created as a result of the COPY reporting command or when the ESP subsystem is down. The INPUT command does not require the presence of the subsystem.Specify any number of INPUT commands—they may be intermixed with HISTFILE statements. The data sets are processed in the order of their respective INPUT statements.

Related informationFor information on history reporting, see the ESP Workload Manager User’s Guide.

Operand Descriptiondsname Indicates the name of the input data set. This is mutually exclusive

with the FILE option.filename Indicates the name of the input file name. This is mutually exclusive

with the DATASET option.

677

Example History report definitionIn the following example, the INPUT command is used to request that ESP read history records from CYBER.ESP.HISTORY1 instead of the active history file.REPORTINPUT DATASET(CYBER.ESP.HISTORY1)FROM 7AM YESTERDAYCRITERIA APPLSYS EQ PAYROLLDISPLAY JOBNAME JOBNO APPLSYS CMPCENDR

INPUTDS Statement: Extract Tape Information

678

INPUTDS Statement: Extract Tape Information

The INPUTDS statement is used to extract tape volume serial information during a scheduled activity data set generation run. ESP references the tape management catalog when it generates the scheduled activity data set.

SyntaxINPUTDS dsname(genno)

Usage notesESP can generate a data set using this extracted information and feed the data set into the TMS or CA1 tape pull program.To use the INPUTDS statement to generate a data set to use as input to the TMS or CA1 tape pull program, take the following steps:1. Use the INPUTDS statement in the ESP Application, identifying the tape data sets

associated with each job2. Generate a scheduled activity data set using the SADGEN command in a batch

job3. Use the LSAR subcommand specifying TAPEPULL(dsname), where dsname is

the pre–allocated PDS to store tape data set information4. Re–initialize the TAPEPULL data set before you generate the scheduled activity

data set5. Use this PDS as input to the TMS or CA1 tape pull program.

Related StatementsFor information on extracting tape information, see the ESP Workload Manager User’s Guide.

Operand Descriptiondsname Indicates the name of tape input data set.genno Indicates a relative generation number. This must be zero or a negative

number.

679

Example Indicate tape data setsIn the following example, two input data sets are identified as follows:• For PAYJOB1, -1 generation of 'PROD.PAY.ACCT' is identified as it’s input data

set.• For PAYJOB2, the current generation of 'PROD.PAY.BACKUP' is identified as

it’s input data set.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY RELEASE PAYJOB2 INPUTDS PROD.PAY.ACCT(-1)ENDJOBJOB PAYJOB2 RUN DAILY INPUTDS PROD.PAY.BACKUP(0)ENDJOB

INTEGER Statement: Define Integer Variables

680

INTEGER Statement: Define Integer Variables

The INTEGER statement is used to define an integer variable before its first assignment statement.

SyntaxINTEGER varname[,varname...]

Usage notesUse integer symbols if you want to assign arithmetic values or expressions to them, and manipulate them as numbers, such as A=2+2 and NUMBER=999. You must first use an INTEGER statement to define an integer symbol before you can assign a value to it.An integer variable differs from a character variable in the way the value is stored. When you assign a string to an integer variable, the string must consist of a valid arithmetic expression. The expression is evaluated and the result stored as a full word binary number.If you assign a character string to an integer variable, ESP evaluates the character string as if it were an arithmetic expression and then stores the result as an integer.If you want an INTEGER variable to be available inside and outside an IF block, then declare it outside of the block.An integer assigned a value within the scope of a JOB statement is available only for that job in Application process mode. In Application generation mode, an integer has the value assigned to it by the last executed assignment statement.ESP's built-in symbolic variables, ESPA and ESPS, are not available in Page mode, and can not be assigned to integer variables in Page mode.

Related informationFor information on working with user defined symbolic variables, see the ESP Workload Manager Advanced User's Guide.

Operand Descriptionvarname Indicates the name of the variable to be defined. A list of variable

names can be specified, separating each with a comma or space.

681

Examples:Define x=2In the following example, variable X is defined as an integer variable and assigned the value of 2.INTEGER XX=2

Define calculationIn the following example, variable A is defined as an integer variable and assigned the value of 125. INTEGER AA=5*25

Assign current day of week numberIn the following example, variable B is defined as an integer variable and assigned the value of the current day of the week number. If, for example, today is Thursday, B is assigned a value of 5.INTEGER BB=%ESPADOW#

Assign current day of year numberIn the following example, variables C and D are first defined as integer variables. D is assigned the current day of year number. C is then given a value that resolves to the week of year number.Note: %ESPSDDD represents a number but is stored in character format. To work

with this as a number, you must first assign it to an integer variable.INTEGER C,DD=%ESPSDDDC=(%D-1)/7+1

Define variable outside IF blockIn the following example, defining the integer outside the IF block makes it available inside and outside the block.INTEGER E,FE=222F=444IF TODAY('MONDAY') THEN PARM=%E ELSE PARM=%F

INVOKE Command: Invoke ESP Procedures

682

INVOKE Command: Invoke ESP Procedures

The INVOKE command is used to invoke an ESP Procedure. The INVOKE command can be used as part of an Event definition, or from within an ESP Procedure to invoke another ESP Procedure.

TypeEvent definition command, ESP Procedure command.

SyntaxINVOKE 'dataset(member)' [CACHE|NOCACHE]

Usage notesTo invoke an ESP Procedure from an Event, you must first create the Procedure and then define the Event to invoke that Procedure.ESP allows multiple INVOKE commands within an Event or ESP Procedure. However, an Event can only generate one Application. To invoke more than one Application requires one Event per Application.

Related informationFor information on invoking an ESP Procedure from an Event, see the ESP Workload Manager User’s Guide.For information on invoking an ESP Procedure from another ESP Procedure, see the ESP Workload Manager User’s Guide.

Operand Descriptiondataset Indicates the name of the data set that contains the ESP Procedure. The

data set and member must be enclosed in quotes.member Indicates the name of the member that contains the ESP Procedure you

want invoked.CACHE Specifies that the ESP Procedure will be cached if caching is enabled

with the PCACHE command or initialization parameter.NOCACHE Specifies that the ESP Procedure will not be cached.

683

Examples:Every weekday at 10 pmIn the following example, the PAYJOBS ESP Procedure is invoked every weekday at 10 pm.EVENT ID(CYBER.PAYROLL)SCHEDULE 10PM WEEKDAYSINVOKE 'CYBER.PROCS.CNTL(PAYJOBS)'ENDDEF

Invoke another procedureIn the following example, every time the PAYROLL Application is invoked, the DATES ESP Procedure is also invoked. The DATES ESP Procedure contains built-in or user-defined symbolic variables required by the jobs in the PAYROLL Application. The DATES ESP Procedure will be cached if caching is enabled with the PCACHE command or initialization parameter.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'INVOKE 'CYBER.SYMBOLS.CNTL(DATES)' CACHEJOB PAYJOB1 RUN WORKDAYS REL PAYJOB2JOB PAYJOB2 RUN WORKDAYSENDJOB

IP_MON Statement: Monitor IP Addresses or Ports

684

IP_MON Statement: Monitor IP Addresses or Ports

Monitors the status of an IP address or a port on a specified IP address.

TypeApplication statement.

ApplicabilityRelease 6 System Agents.

SyntaxRefer to the JOB statement syntax.

Usage notesTo monitor remote IP addresses through the Agent, the Agent must run as root. If it runs as a user without root privileges, the job will show complete but with the message "Ping (ip address) insufficient privilege" in the status field and transmitter.log.

These job-definition statements are associated with the IP_MON statement. They are shown in the examples that follow.• IPADDRESS• IPPORT• STATUSTo use IP monitors, load the workload object module CYBESOIM with the WOBDEF command or with the WOBDEF initialization parameter.The short form of IP_MON is IM.Also refer to the JOB statement usage notes.

ExampleThis example uses IP_MON to find out if an Agent is running at the IP address 10.1.2.20 and input port number 9401. This job completes if the Agent is running.IP_MON IP1 IPADDRESS 10.1.2.20 IPPORT 9401 STATUS RUNNING NOW RUN DAILY AGENT WINR6ENDJOB

685

IPADDRESS Statement: Specify IP Address for IP_Monitor Within IP_MON

The IPADDRESS statement specifies the IP address that will be monitored by an IP_Monitor workload object.

ApplicabilityESP System Agents, Release 6, used within an IP_MON workload object. For more information, see “IP_MON Statement: Monitor IP Addresses or Ports” on page 684.

SyntaxIPADDRESS IPAddress

ExampleIP_MON IM.STMNT AGENT R6AGENT IPADDRESS APPARCL STATUS STOPPED WAIT RUN DAILYENDJOB

Operand DescriptionIPAddress Enter the DNS name or dotted decimal IP address. The format is

case sensitive, any character, up to 100 characters long.

IPPORT Statement: Specify IP Port for IP_Monitor Within IP_MON

686

IPPORT Statement: Specify IP Port for IP_Monitor Within IP_MON

The IPPORT statement specifies the IP port for an IP address (in the form of an IPADDRESS statement) that will be monitored by an IP_Monitor workload object.

ApplicabilityESP System Agents, Release 6, used within an IP_MON workload object. For more information, see “IP_MON Statement: Monitor IP Addresses or Ports” on page 684.

SyntaxIPPORT IPport

ExampleIP_MON IM.STMNT AGENT R6AGENT IPADDRESS localhost IPPORT 5800 STATUS RUNNING NOW RUN DAILYENDJOB

Operand DescriptionIPport Optional. Enter the port number for the IP address specified in the

IPADDRESS statement. The Agent will attempt to connect to this port. The format is numeric, up to five digits.

Note: If this statement is used and the value zero or no value is entered, the Agent will use Ping for monitoring.

687

JJCLLIB Statement: Identify JCL Library

The JCLLIB statement is used to identify the JCL library you want to use for all jobs following this statement. When ESP encounters a JOB statement, it uses the JCL member in the JCLLIB with the same name as the job. You can use the MEMBER statement to override this action.

SyntaxJCLLIB 'dsname'

Usage notesThis statement can be used to specify the JCL library you want to use throughout the ESP Application unless it is explicitly overridden for a particular job with the DATASET statement. This means that you only have to specify the JCL library once for each Application. Unless the member name is explicitly overridden with the MEMBER statement, the member name is assumed to be the same as the jobname.

Related informationFor information on identifying JCL libraries, see the ESP Workload Manager User’s Guide.For information on specifying a temporary or override JCL library, see the TEMPLIB statement.For information on specifying an optional JCL library for an individual job, see the DATASET statement.For information on specifying the member name in which ESP finds a job’s execution JCL, see the MEMBER statement.

Operand Descriptiondsname Indicates the name of the data set where the JCL resides. The data set

name must be enclosed in quotes.

JCLLIB Statement: Identify JCL Library

688

Examples Specify JCL libraryIn the following example, ESP submits all jobs in the PAYROLL Application from CYBER.JCL.CNTL.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY REL PAYJOB2JOB PAYJOB2 RUN DAILYENDJOB

Specify multiple JCL libraries In the following example:• ESP uses the default JCL library CYBER.JCL.CNTL to submit PAYJOB3’s

execution JCL from member PAYJOB99• ESP uses CYBER.ALTJCL.CNTL to submit PAYJOB4’s execution JCL.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 RUN DAILY REL PAYJOB4 MEMBER PAYJOB99JOB PAYJOB4 RUN DAILY DATASET 'CYBER.ALTJCL.CNTL'ENDJOB

Specify PANVALET libraryIn the following example, ESP will submit all jobs in the PAYROLL Application from a PANVALET library called PROD.ESP.JOBS.APPL PAYROLLJCLLIB PAN-PROD.ESP.JOBSJOB PAYJOB1 RUN DAILY REL PAYJOB2JOB PAYJOB2 RUN DAILYENDJOB

689

Different libraries for jobsIn the following example, ESP submits PAYJOB1 and PAYJOB2 from CYBER.JCL.LIB1. ESP submits PAYJOB3 from CYBER.JCL.LIB2.APPL PAYROLLJCLLIB 'CYBER.JCL.LIB1'JOB PAYJOB1 RUN DAILYENDJOBJOB PAYJOB2 RUN DAILYENDJOBJCLLIB 'CYBER.JCL.LIB2'JOB PAYJOB3 RUN DAILYENDJOB

JESCOMCH Command: Specify Command Prefixes

690

JESCOMCH Command: Specify Command Prefixes

The JESCOMCH command is used to specify the character used to prefix JES commands. Normally this is specified as an initialization parameter.

TypeGeneral command.

AuthorityYou require OPER authority to issue the JESCOMCH command.

SyntaxJESCOMCH character

Usage notesUse this command if your installation uses a character other than the dollar symbol to prefix JES commands. Use single quotes to enclose the chosen prefix if it is a punctuation character.

Related informationFor information on specifying a character used to prefix JES commands at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.

Example Prefix with #In the following example, the number sign is used to prefix JES commands.JESCOMCH '#'

Operand Descriptioncharacter Indicates the character used as a JES command prefix. If a punctuation

character (such as a semi-colon) is used, it must be enclosed in quotes. The default character is $.

691

JESTYPE Command: Specify JES Type

The JESTYPE command is used to specify the type of JES used by your installation. Normally this is specified as an initialization parameter.

TypeGeneral command.

AuthorityYou require OPER authority to issue the JESTYPE command.

SyntaxJESTYPE [2|3] [DJC|NODJC]

Usage notesThis command enables ESP to detect differences in processing requirements for the JES3 subsystems compared with JES2. You may use the NODJC operand to have existing DJC networks converted to Applications without the need to modify individual ESP Procedures.

Related informationFor information on specifying the type of JES used by your installation at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.

Example Specify JES 3In the following example, JES3 is the subsystem in use.JESTYPE 3

Operand Description2 Indicates JES2 is in use. This is the default.3 Indicates JES3 is in use.DJC Indicates normal processing for DJC networks.NODJC Indicates existing DJC networks should be processed as Applications.

JMSP_JOB Statement: Start a JMS Publish Job Definition (J2EE)

692

JMSP_JOB Statement: Start a JMS Publish Job Definition (J2EE)

The JMSP_JOB statement starts a JMS Publish job definition in an Application.

ApplicabilityESP System Agents, Release 6, Service Pack 2 or higher.

SyntaxRefer to the JOB statement syntax.

Usage notesJP is the short form of JMSP_JOB.To schedule JMS Publish jobs, you must load the workload object module CYBESOJP. Load CYBESOJP with the WOBDEF command (page 1332) or with the WOBDEF initialization parameter.You must include the following J2EE statements within a JMSP_JOB workload object:• “CONNECTION_FACTORY Statement: Specify JNDI Name of Connection

Factory (J2EE)” on page 201• “DESTNAME Statement: Specify JNDI Name of the Topic/Queue” on page 318• “INITIAL_CONTEXT Statement: Specify Initial Context Factory (J2EE)” on

page 674• “LOCATION Statement: Specify the Service Provider URL (J2EE)” on page 810• “MSGCLASS Statement: Specify the Java Class of the JMS Message (J2EE)” on

page 867• “TOPIC Statement: Publish/Subscribe to a Topic/Queue (J2EE)” on page 1259You may include the following J2EE statements within a JMSP_JOB workload object:• “JNDIUSER Statement: Specify JNDI User ID (J2EE)” on page 696• “PARAMETER Statement: Specify the Method/Message Parameters (J2EE)” on

page 938Refer to the JOB statement (page 697) usage notes.

693

ExamplesPublish to a QueueIn this example, the CYBJK.JP job publishes a simple message to the Queue named Queue.APPL TESTJPJMSP_JOB CYBJK.JP HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DESTNAME Queue TOPIC N MSGCLASS String JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 PARAMETER TYPE(java.lang.String) VALUE(’this is my message’)ENDJOB

Publish to a TopicIn this example, the CYBJK.JP job publishes a simple message to the Topic named Topic.APPL TESTJPJMSP_JOB CYBJK.JP HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT + com.ibm.websphere.naming.WsnInitialContextFactory CONNECTION_FACTORY ConnectionFactory DESTNAME Topic TOPIC Y MSGCLASS String JNDIUSER cyberuser LOCATION iiop://100.10.31.66:2809 PARAMETER TYPE(java.lang.String) VALUE(’this is my message’)ENDJOB

JMSS_JOB Statement: Start a JMS Subscribe Job Definition (J2EE)

694

JMSS_JOB Statement: Start a JMS Subscribe Job Definition (J2EE)

The JMSS_JOB statement starts a JMS Subscribe job definition in an Application.

ApplicabilityESP System Agents, Release 6, Service Pack 2 or higher.

SyntaxRefer to the JOB statement syntax.

Usage notesJS is the short form of JMSS_JOB.To schedule JMS Subscribe jobs, you must load the workload object module CYBESOJS. Load CYBESOJS with the WOBDEF command (page 1332) or with the WOBDEF initialization parameter.You must include the following J2EE statements within a JMSS_JOB workload object:• “CONNECTION_FACTORY Statement: Specify JNDI Name of Connection

Factory (J2EE)” on page 201• “DESTNAME Statement: Specify JNDI Name of the Topic/Queue” on page 318• “INITIAL_CONTEXT Statement: Specify Initial Context Factory (J2EE)” on

page 674• “LOCATION Statement: Specify the Service Provider URL (J2EE)” on page 810• “TOPIC Statement: Publish/Subscribe to a Topic/Queue (J2EE)” on page 1259You may include the following J2EE statement within a JMSS_JOB workload object:• “DEST Statement: Specify Output Destination File (J2EE)” on page 313• “FILTER Statement: Specify Filter for JMS Subscribe Jobs (J2EE)” on page 606• “JNDIUSER Statement: Specify JNDI User ID (J2EE)” on page 696Refer to the JOB statement (page 697) usage notes.

695

ExamplesContinuously monitoring QueueIn this example, the CYBJK.JS job continuously monitors the Queue named Queue for messages matching the filter criteria. The consumed messages from the Queue are stored in the file Makapt15.txt.APPL TESTJSJMSS_JOB CYBJK.JS HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DEST ’c:\Program Files\Dest\Common Files\System\ado\+ Makapt15.txt’ DESTNAME Queue continuous(a13) TOPIC N FILTER ’abc\s...\s[a-zA-Z]+\sFilter![\sa-z0-9]+’ JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001ENDJOB

Monitoring TopicIn this example, the CYBJK.JS job monitors the Topic named Topic for messages matching the filter criteria. The consumed messages from the Topic are stored in the file outputfile.APPL TESTJSJMSS_JOB CYBJK.JS RUN DAILY AGENT CYBUNIX INITIAL_CONTEXT + com.ibm.websphere.naming.WsnInitialContextFactory CONNECTION_FACTORY ConnectionFactory DEST /export/home/user1/outputfile DESTNAME Topic TOPIC Y FILTER ’abc\s...\s[a-zA-Z]+\sFilter![\sa-z0-9]+’ JNDIUSER cyberuser LOCATION iiop://100.10.31.66:7001ENDJOB

JNDIUSER Statement: Specify JNDI User ID (J2EE)

696

JNDIUSER Statement: Specify JNDI User ID (J2EE)

The JNDIUSER statement specifies the JNDI user ID for J2EE jobs. This user ID refers to the Application Server within the JNDI framework. If specified, this authentication information is supplied when creating the initial context.Note: Every user ID used in a job definition must have a corresponding user ID/

password pair defined using the PASSWORD command.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within the EJB_JOB, JMSP_JOB, and JMSS_JOB workload objects

SyntaxJNDIUSER userid

Usage notesJNDIUSER is an optional statement within the EJB_JOB, JMSP_JOB, and JMSS_JOB workload objects.JUSER is the short form of JNDIUSER.

ExampleIn this example, the CYBJK.SB job uses the cyberuser JNDI user ID.APPL TESTSBEJB_JOB CYBJK.SB HOLD RUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(java.lang.String) VALUE(A23)ENDJOB

Operand Descriptionuserid The JNDI user ID. userid is case sensitive and can be up to 128

characters.

697

JOB Statement: Identify the Name of Jobs

The JOB statement is used to identify the name of a job in an Application. The JOB statement must be used before identifying other job requirements such as predecessor and successor relationships and run frequencies.

TypeESP Application Statement

SyntaxThe syntax also applies to other workload objects. See “Statement names for distributed workload” on page 702 for the list of statements names.JOB|prefix_JOB|prefix_MON jobname[.qualifier] [[TASK|NOTASK]|[LINK|NOLINK]| [MANUAL|NOMANUAL]|[EXTERNAL|NOEXTERNAL]] [[REQUEST|NOREQUEST]|[NODE|NONODE]] [INHERIT|NOINHERIT] [CONDITIONAL|NOCONDITIONAL] [HOLD|NOHOLD] [CRITICAL|NOTCRITICAL] [DOCMEM(docmember)] [LONGNAME(longname)]

TASK [OWNER(Applowner|manager)]

LINK [OWNER(Applowner|manager)] [PROCESS|NOPROCESS]

MANUAL [AUTHSTR(string)] [SCOPE(hh.mm,hh.mm)]

EXTERNAL [AUTHSTR(string)] [SCOPE(hh.mm,hh.mm)] [APPLID(applname)] [SCHEDULED('criteria')]

Operand DescriptionJOB Specifies an ESP Workload Manager job that runs on the

mainframe. For other types of workload, substitute the statement name corresponding to the workload object you want. See “Statement names for distributed workload” on page 702 for the list of statement names.

prefix_JOBprefix_MON

Specifies a valid job type. Use the prefix to differentiate jobs for agent platforms. See the Usage Notes for a list of the valid agent job types.

JOB Statement: Identify the Name of Jobs

698

jobname Indicates a job name of up to eight characters.qualifier Indicates a job qualifier of up to eight characters. Follows the

jobname and a period.TASK|NOTASK TASK—Indicates this is a task that requires manual

completion. ESP Workload Manager does not submit JCL for a TASK. NOTASK—Indicates this is not a task that requires manual completion. This is the default.See “TASK” on page 700 for the operands that apply to TASK.

LINK|NOLINK LINK—Indicates this is a workload object that completes immediately. ESP Workload Manager does not try to submit JCL for a LINK. NOLINK—Indicates that this workload object is not a LINK. This is the default.See “LINK” on page 700 for the operands that apply to LINK.

MANUAL|NOMANUAL MANUAL—Indicates that the job is submitted, outside an Application. This includes jobs submitted directly by an Event. NOMANUAL—Indicates that the job is being submitted within an Application. This is the default.See “MANUAL” on page 701 for the operands that apply to MANUAL.

EXTERNAL|NOEXTERNAL EXTERNAL—Indicates the job is submitted by another ESP Workload Manager application. Used to build inter-application dependencies. NOEXTERNAL—Indicates the job is not submitted by another ESP Workload Manager application. This is the default.See “EXTERNAL” on page 701 for the operands that apply to EXTERNAL.

REQUEST|NOREQUEST REQUEST—Indicates this job will run only if it is requested. NOREQUEST—Indicates this job will always run. This is the default.

NODE |NONODE NODE—Indicates the job is a node for inheriting job relationships. No relationships pass through a node. A relationship between a predecessor and a successor to the node exists only when ESP Workload Manager selects the node. Inherited relationships among the node and its successors still exist.NONODE—Indicates the job is not a node for inheriting job relationships. This is the default.

Operand Description

699

INHERIT|NOINHERIT INHERIT—Indicates the job relationships should be inherited.This is the default.NOINHERIT—Indicates the job relationships should not be inherited.

CONDITIONAL|NOCONDITIONAL

CONDITIONAL—Indicates the job may or may not execute. The application this job belongs to is considered complete when all NOCONDITIONAL jobs are complete.NOCONDITIONAL—Indicates the job must complete in order for the application to be considered complete. This is the default.

HOLD|NOHOLD HOLD—Indicates the job is to be placed on manual hold when ESP Workload Manager generates the application. You can release a job from manual hold using the CSF or the APPLJOB (AJ) command. NOHOLD—Indicates the job is not to be placed on manual hold when ESP Workload Manager generates the application. This is the default.

CRITICAL|NOTCRITICAL CRITICAL—Indicates the job represents a critical point in the application. The longest path to this job, in terms of execution time (based on history) is identified as the critical path.NOTCRITICAL—Indicates the job does not represent a critical point in the application. This is the default.

DOCMEM(docmember) Indicates the job documentation member with a name other than the job name should be referenced. The default is to reference a member name the same as the job name.

LONGNAME(longname) Specifies a character string associated with a workload object. This character string can be displayed in CSF, used in reports, and used in CLANG through the %ESPLONGNAME variable. The maximum length of LONGNAME is 64 characters. It is case-sensitive and you can include any valid character including blanks. If you include blanks, you must enclose the string in single quotes. If you include single quotes in the string, you must double them. For example: LONGNAME('Peter''s job')

Note: The LONGNAME operand is valid with all workload object statements except for JOB.

Operand Description

JOB Statement: Identify the Name of Jobs

700

TASKUse TASK only with the JOB statement

LINKUse LINK only with the JOB statement

Operand DescriptionOWNER(applowner|manager) Indicates the name of the owning ESP Workload Manager for

Links and Tasks. Specify a valid ESP Workload Manager name, up to 16 alphanumeric characters in length, where the first character must be alphabetic. If you do not specify OWNER, the owning ESP Workload Manager of the application is the default. The owning ESP Workload Manager is the only one with authority to update the status of a workload object.

Operand DescriptionOWNER(applowner|manager) Indicates the name of the owning ESP Workload Manager for

Links and Tasks. Specify a valid ESP Workload Manager name, up to 16 alphanumeric characters in length, where the first character must be alphabetic. If you do not specify OWNER, the owning ESP Workload Manager of the application is the default. The owning ESP Workload Manager is the only one with authority to update the status of a workload object.

PROCESS|NOPROCESS PROCESS—Executes:• ESP Commands• z/OS Commands• CLANG• Built-in Functionswithin a LINK.NOPROCESS—Bypasses:• ESP Commands• z/OS Commands• CLANG• Built-in Functionswithin a LINK. This is the default.

701

MANUAL

EXTERNAL

Operand DescriptionAUTHSTR(string) Specifies an authorization string as defined by the AUTHSTR

initialization parameter. Can only be used with the EXTERNAL and MANUAL keywords.

SCOPE(hh.mm,hh.mm) Specifies the number of hours ESP Workload Manager is to do a backward and/or forward search in the JOBINDEX data set for a job. The first parameter indicates how far back the ESP Workload Manager should look; the second parameter indicates how far ahead it should look. This parameter can be a maximum of 12 characters. SCOPE can be used with the EXTERNAL and MANUAL keywords for jobs in its home application.

Operand DescriptionAUTHSTR(string) Specifies an authorization string as defined by the AUTHSTR

initialization parameter. Can only be used with the EXTERNAL and MANUAL keywords.

SCOPE(hh.mm,hh.mm) Specifies the number of hours ESP Workload Manager is to do a backward and/or forward search in the JOBINDEX data set for a job. The first parameter indicates how far back the ESP Workload Manager should look; the second parameter indicates how far ahead it should look. This parameter can be a maximum of 12 characters. SCOPE can be used with the EXTERNAL and MANUAL keywords for jobs in its home application.

APPLID(applname) Indicates the name of the Application that submits the job.SCHEDULED('criteria') Specifies a scheduled time or range for the scheduled time of

the event that submits the job or the trigger time issued for non-scheduled events.To specify a range, specify criteria as follows:

criteria UNTIL criteria

JOB Statement: Identify the Name of Jobs

702

Statement names for distributed workload

Statement Name Module Name DescriptionAGENT_MONITOR or AM

CYBESOAM Agent monitor.

AIX_JOB or AX CYBESOAX AIX Agent.APPLEND or AE CYBESOAE APPLEND (End of Application).AS400_JOB or A4 CYBESOA4 OS/400 Agent.CPU_MON or CM CYBESOCM CPU monitor Agent.DATA_OBJECT or DA

CYBESODA Data Object.

DB_JOB or DM CYBESODM Database job Agent (Perform SQL updates and queries against a database).

DISK_MON or HM CYBESOHM Disk monitor Agent.DSTRIG or DT CYBESODT Data-set Trigger.EVENTLOG_MON or LM

CYBESOLM Windows event monitor Agent.

EXTMON or EX CYBESOEX EXTMON (Monitor a job controlled on an external scheduler, for example ESP Espresso).

FILE_TRIGGER or FM

CYBESOFM File trigger.

FTP_JOB or FT CYBESOFT FTP job Agent (Perform FTP file operations).HPUX_JOB or HP CYBESOHP HP-UX Agent.IP_MON or IM CYBESOIM IP address or port monitor Agent.LINUX_JOB or LJ CYBESOLJ Linux Agent.NCR_JOB or NC CYBESONC NCR Agent.NT_JOB or NT CYBESONT Windows NT Agent.OA_JOB CYBESOOA Oracle Applications Agent.OPENVMS_JOB or OV

CYBESOOV OpenVMS Agent.

PROCESS_MON or PM

CYBESOPM Process monitor Agent.

PS_JOB or PS CYBESOPS PeopleSoft Agent.SAP_JOB or SP CYBESOSP R/3 ERP Systems Agent.SEQUENT_JOB or SQ

CYBESOSQ IBM DYNIX/ptx (SEQUENT) Agent.

703

Usage notesThe JOB statement begins a job definition. The ENDJOB statement or another JOB statement ends a job definition. You must use an ENDJOB statement after defining all of your jobs.ESP Workload Manager processes commands based on where they are placed within an Application as follows:• ESP Workload Manager processes commands outside the scope of JOB

statements when the Application is generated and every time a job becomes eligible (this means that all the dependencies are met)

• ESP Workload Manager processes commands within the scope of a JOB statement only when the job becomes eligible ((this means that all the dependencies are met).

Statements placed within the scope of the job are referred to as job-specific statements, whereas statements placed outside the scope of a job statement are referred to as global statements.You can define jobs in any order. ESP Workload Manager submits the jobs based on how you define the job relationships. By default, the member name of the JCL library used is the same as the jobname. To override this, use the MEMBER statement and specify the name of the member that contains the JCL for the job. The jobname must match the name specified on the job card.A NOINHERIT job that is not selected blocks any dependency chain passing through it. Thus, any job released either directly or indirectly by such a job is independent of any ancestors of the blocking job.A NOINHERIT job that is selected does not allow a dependency chain to emanate from it. In other words, such a job releases any selected immediate successors, but does not pursue dependency chains through any successors not selected.You need to code an AGENT statement for distributed workload objects.

SERVICE_MON or SM

CYBESOSM Windows service monitor Agent.

SUN_JOB or SJ CYBESOSJ SOLARIS Agent.TANDEM_JOB or TA

CYBESOTA TANDEM NSK Agent.

TEXT_MON or TM CYBESOTM text file monitor Agent.UNIX_JOB or UJ CYBESOUJ Generic UNIX—supports LINUX, TRU64 UNIX,

and UNIX System Services.

Statement Name Module Name Description

JOB Statement: Identify the Name of Jobs

704

Examples:Define an ESP Workload Manager jobIn this example, the JOB statement is used to identify PAYJOB1 as part of the PAYROLL Application.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILYENDJOB

Define an agent jobIn this example, the INVENTORY application consists of a job MFGDATA that runs on the OS/400 Agent.APPL INVENTORYAS400_JOB MFGDATA RUN DAILY RELEASE MFGSORT AGENT AS401 CLPNAME MFGTEST.DATA AS400LIB PRODJOBSENDJOB

Specify a long job nameThe following example uses a long job name.NT_JOB myntjob LONGNAME('This is John''s window NT job') RUN DAILY AGENT AGwin1 CMDNAME C:\myjob.exeENDJOB

Define an on request jobIn the following example, PAYJOB2 is defined as an on-request job.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY REL PAYJOB2ENDJOBJOB PAYJOB2 REQUEST RUN DAILYENDJOB

705

Define a manual taskIn the following example, BALANCE.RPT represents a manual task and must be marked complete. APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB BALANCE.RPT TASK RUN DAILYENDJOB

Define external and qualified jobs

In the following example:• PAYJOB3 is defined as submitted by another ESP Application. The EXTERNAL

parameter is used to build a dependency between jobs from different Applications • PAYJOB4 is a qualified job. The sub-string of an ESP built-in symbolic variable is

used to comprise the jobname. For example, if this Application was scheduled on Wednesday, PAYJOB4’s jobname resolves to PAYJOB4.WED. If PAYJOB4 is not completed by 9 pm, it is flagged as overdue.

APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 EXTERNAL APPLID(EXTAPPL) RUN DAILY REL PAYJOB4.%ESPSDAY(1:3)ENDJOBJOB PAYJOB4.%ESPSDAY(1:3) DUEOUT EXEC 9PM RUN DAILYENDJOB

Define a conditional jobIn the following example, PAYJOB6 is defined as a conditional job that is submitted only if PAYJOB5 terminates abnormally.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB5 RUN DAILY REL (PAYJOB6(A))ENDJOBJOB PAYJOB6 CONDITIONAL RUN DAILYENDJOB

Define job conditional on previous job completionIn the following example, PAYJOB7 is submitted by another ESP Application. On the last workday of the month, ESP ensures PAYJOB7 from the previous day completed.

JOB Statement: Identify the Name of Jobs

706

PAYJOB8 waits until this dependency is met. The RUN statement for PAYJOB7 reflects the day on which you want ESP to check if the dependency is satisfied.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB7 EXTERNAL SCHEDULED('YESTERDAY') RUN LAST WORKDAY OF MONTH REL PAYJOB8ENDJOBJOB PAYJOB8 RUN LAST WORKDAY OF MONTHENDJOB

Define a critical jobIn the following example, PAYJOB4 is identified as the critical point in the PAYROLL Application. ESP calculates the longest path to this job based on historical execution times and identifies this path as the critical path.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'CRITPATH ONJOB PAYJOB1 RUN DAILY REL (PAYJOB2,PAYJOB3)ENDJOBJOB PAYJOB2 RUN DAILY REL PAYJOB4ENDJOBJOB PAYJOB3 RUN DAILY REL PAYJOB4ENDJOBJOB PAYJOB4 CRITICAL RUN DAILYENDJOB

Define a job with a link to ownerThe following example defines a Distributed Manager as the owning Manager of this Link:JOB A LINK OWNER(DMCHI)

707

More examples using the job statementIndicates that a message is sent when critical jobs within the Application have completed successfully.JOB CRITICAL.POINT LINK PROCESS AFTER (PAYJOB1,PAYJOB2,PAYJOB3) RUN DAILY SEND 'CRITICAL JOBS COMPLETED AT %ESPATIME' USER(CYB01)ENDJOB

Indicates a manually submitted job. ESP looks back 24 hours to see if the job has completed successfully. If its has not, ESP waits until it doesJOB PAYJOB1 MANUAL SCOPE(-24) RUN DAILY REL PAYJOB2ENDJOB

Indicates this job is submitted as part of the BILLING Application. ESP posts PAYJOB1 complete, when today’s scheduled run of PAYJOB1 completes successfully in the BILLING Application. If PAYJOB1 has already completed successfully when this Application is generated, ESP marks PAYJOB1 complete at generation time:JOB PAYJOB1 EXTERNAL SCHEDULED('TODAY') APPLID(BILLING) RUN DAILY REL PAYJOB2ENDJOB

Indicates you wish to reference a job documentation member with a name other than the jobname:JOB PAYJOB1 DOCMEM(SPECIAL) RUN DAILYENDJOB

JOBATTR Statement: Change Job Attributes

708

JOBATTR Statement: Change Job Attributes

The JOBATTR statement is used to change a job’s attributes within the scope of a JOB statement or in job documentation.

SyntaxJOBATTR [EXTERNAL|NOEXTERNAL] [MANUAL|NOMANUAL] [LINK|NOLINK] [TASK|NOTASK] [REQUEST|NOREQUEST] [PROCESS|NOPROCESS] [CONDITIONAL|NOCONDITIONAL] [HOLD|NOHOLD] [INHERIT|NOINHERIT] [NODE|NONODE] [SCHEDULED('criteria')] [SCOPE(hh.mm,hh.mm)] [AUTHSTR(authstring)] [APPLID(applname)]

Usage notesYou may want to define a job with different attributes in special situations. For example, on a particular day you may want to define a job on hold, whereas on other days you do not want the job defined on hold. Instead of defining the job multiple times with job qualifiers or using IF logic around a JOB statement, you can use the JOBATTR statement.Using JOBATTR statements in conjunction with IF logic, allows jobs to have cumulative job attributes. For example, if a job is a conditional job on Mondays, and a request job on the first workday of the month, combining JOBATTR statements with IF logic provides for a cumulative effect when Monday is also the first workday of the month; the job is a conditional request job.

Related informationFor information on identifying the names of jobs in an Application, see the JOB statement.For information on Applications, see the ESP Workload Manager User’s Guide.

Operand Descriptionattributes Indicates the attributes of the job you want to change. You can specify

more than one attribute by separating them with a comma or space. The attributes are listed above. For more information on the job attributes listed above see the JOB statement.

709

Examples Change attributes on MondayIn the following example, PAYJOB1’s attributes are changed to define the job on hold every Monday. APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 IF TODAY('MONDAY') THEN JOBATTR HOLD RUN DAILYENDJOB

Multiple attributesIn the following example:• PAYJOB2 runs daily• On Fridays, PAYJOB2 has an attribute of HOLD

• On the last workday of the month, PAYJOB2 has an attribute of REQUEST.When the last workday of the month is a Friday, PAYJOB2 has attributes of HOLD and REQUEST.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB2 IF TODAY('FRIDAY') THEN JOBATTR HOLD IF TODAY('LAST WORKDAY OF MONTH') THEN JOBATTR REQUEST RUN DAILYENDJOB

External job scheduled yesterdayIn the following example, PAYJOB3 uses the JOBATTR statement to define the job as an External job on Sundays. On Sunday, ESP looks back to the previous day (YESTERDAY) to see if PAYJOB3 completed successfully. If it has, PAYJOB3 is marked complete when the Application is built, otherwise it waits for PAYJOB3 to complete.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 IF TODAY('SUNDAY') THEN + JOBATTR EXTERNAL SCHEDULED('YESTERDAY') RUN SATURDAY SUNDAY REL PAYJOB4JOB PAYJOB4 RUN SUNDAYENDJOB

JOBATTR Statement: Change Job Attributes

710

Critical except last day of monthIn the following example, PAYJOB1’s attributes are changed on the last workday of the month such that critical path analysis is performed every day except the last workday of the month.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 CRITICAL RUN WORKDAYS IF TODAY('LAST WORKDAY OF MONTH') THEN JOBATTR NOTCRITICALENDJOB

711

JOBCLASS Statement: Assign Job Class to a Job

The JOBCLASS statement assigns a job class value to a job. When this statement is specified, the Agent will interpret the job class against the job classes defined in the agentparm.txt file. For each defined job class, there are a specified number of initiators. Thus, job classes allow for manual load balancing against system resources.

ApplicabilityESP System Agents, Release 6.

SyntaxJOBCLASS jobclass

Usage notes

Global or Local definitionYou can define JOBCLASS globally. The JOBCLASS statement in the job definition will override the global statement in an Application.

Agent ParametersTwo Agent parameters in the agentparm.txt file are associated with the JOBCLASS statement.

Initiators for each JOBCLASS statementYou must specify the number of initiators for job classes in the agentparm.txt file. For example, in the example below, there are three specified job classes. As there is also a default job class in the agentparm.txt file, you would require the following agentparm.txt entries.

initiators.class_1=Default,1000initiators.class_2=JOBCLASS1,20initiators.class_3=JOBCLASS2,500initiators.class_4=FILEM,1000

Operand Descriptionjobclass Assigns job class value to job. Format is alphanumeric text, up to

128 characters in length.

JOBCLASS Statement: Assign Job Class to a Job

712

Alternate method of defining job classIf there is no JOBCLASS statement in the job, you can use a parameter to automatically assign a job class based on the combination of verbs and subverbs that appear in an AFM. Refer to the listing of Agent parameters in the ESP System Agent Administrator’s Guide for the parameter 'initiators.afmjobclassmap_N= <verb>,<subverb>,<JobClass>'

ExampleIn this example, the first instance of the job class (JOBCLASS1) is a global definition in the Application that is overridden by local job class statements (JOBCLASS2 and FILEM).APPL JOBCLASS.TESTAGENT R6AGENTJOBCLASS JOBCLASS1

FTP_JOB TRNSF1 USER user1 . . RUN DAILYENDJOB

FTP_JOB TRNSF2 USER user1 . . RUN DAILYENDJOB

UNIX_JOB PAYDATA JOBCLASS JOBCLASS2 SCRIPTNAME /export/home/payroll/data RUN DAILYENDJOB

FILE_TRIGGER PAYDATA.TRIGGER JOBCLASS FILEM FILENAME /export/home/data/payroll UPDATE RUN DAILYENDJOB

Note: For a Windows example, substitute the NT_JOB statement for the UNIX_JOB statement and a Windows path in the SCRIPNAME and FILENAME statements.

713

JOBCOPY Statement: Copy an Existing SAP Job

The JOBCOPY statement copies an existing SAP job with all of its attributes.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within an SAP_JOB workload object.

SyntaxJOBCOPY JOBCOUNT(count) [TARGETJOBNAME(name)] [STEPNUM(step)]

Usage notesJOBCOPY is an optional statement within the SAP_JOB workload object.

ExampleIn this example, the job SAPTEST with job count 458131 is copied to SAPTEST2.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT JOBCOPY JOBCOUNT(00458131) TARGETJOBNAME(SAPTEST2) ABAPNAME BTCTEST RUN DAILYENDJOB

Operand DescriptionJOBCOUNT(count) Specifies the ID of the job to be copied. It is numeric, up to eight

digits in length.TARGETJOBNAME(name) Specifies the name of the target job. If unspecified, the target job

will have the same name as the source job. It can be up to 32 valid SAP characters in length.

STEPNUM(step) Specifies the number of the first step to start copying job data from. It is numeric with a range of 1 to the highest step number. If step is 0 or 1, all steps are copied.

JOBD Statement: Specify Jobs Description (OS/400)

714

JOBD Statement: Specify Jobs Description (OS/400)

The JOBD statement is used only when defining jobs for the OS/400 agent to specify the OS/400 job description for the program submitted. The JOBD statement can be used within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition, to apply to the entire application.

TypeESP Workload Manager Application Statement

SyntaxJOBD libraryname.descriptionname

Example Specify library name and description of the OS/400 jobThis an example of a JOBD statement:JOBD CYB1.DFTJOBD

In this example, the job description is DFTJOBD in library CYB1.

Operand Descriptionlibraryname Specifies the name of the library containing the specified job

description.The library name must be a valid OS/400 library namedescriptionname Specifies the name of the job description for the program submitted.

The job description name must be a valid OS/400 job description name.

715

JOBENQ Command: Manipulate Enqueue List

The JOBENQ command manipulates the enqueue list of a specified job in a generated Application.

AuthorityThe JOBENQ command is a page mode command that does not require OPER authority.

SyntaxJOBENQ JOB(job.qual) APPL(applname.generation) +{ENQUEUE|DEQUEUE}(nnn) [SHARED|EXCLUSIVE]

Operand DescriptionENQUEUE(nnn) Adds or modifies the enqueue for the name nnn to the job’s list or

sets its type to shared or exclusive.DEQUEUE(nnn) Removes the enqueue for the name nnn from the job’s list.SHARED Requests shared use of the specified resource. This is the default.EXCLUSIVE Requests exclusive use of the specified resource.

JOBINFO Command: Display Job Documentation

716

JOBINFO Command: Display Job Documentation

The JOBINFO command is used to display job documentation. You can display all information for a job or display selected information as identified by fields and labels.

Type General command.

AuthorityYou require OPER authority to issue the JOBINFO command.

Syntax{JOBINFO|JI} {jobname} {jobid } [ABENDS[(abid[,abid]...)]] [AFTER] [CCFAIL] [COREQ] [DATASET] [DJCDATA] [DUEOUT] [FUNCTION] [HISTFILE] [INPUTDS] [MEMBER] [MESSAGES[(msgid[,msgid]...)]] [MODEL] [OPERDATA] [PNODES] [POSTREQ] [PREREQ] [PROGRAMMER] [RELEASE] [FIELD(field[,field...])] [ALL]

Operand Descriptionjobname Indicates the name of the job for which you want to display information (the

PDS member name).jobid Indicates the JES jobid of the job for which you want to display information.abid Displays information concerning the specified ABEND codes. If ABENDS

is specified without operands, all possible ABEND codes for the job are displayed.

717

Usage notesUse the JOBINFO command at any time to display job information in any amount of detail. You can request a display of one field only, such as FUNCTION, or any combination of available keywords. Separate fields with a comma or a space. You must specify the word FIELD for retrieving user-defined fields. The information displayed comes directly from the job documentation library. If any overrides were specified, for example in an ESP Procedure, this is not reflected in the display that is generated.

AFTER Displays names of jobs that are predecessors to this job, and release this job for processing.

CCFAIL Displays condition codes that should cause a job to fail.COREQ Displays names of other jobs that are automatically selected and can run

concurrently with this job.DATASET Displays the JCL library used for the job.DJCDATA Displays ESP/DJC net control statements for this job.DUEOUT Displays due out times from pnodes.FUNCTION Indicates the function of the job.HISTFILE Displays the name of the history-recording file for the job.INPUTDS Displays the tape data sets required for the job.MEMBER Indicates the member name in which ESP finds the job’s execution JCL. The

default is member name equal to jobname.msgid Displays information concerning all specified message IDs. If MESSAGES

is specified without operands, all possible messages for the job are displayed.

MODEL Displays the name of the tracking model for the job.OPERDATA Displays a string of operator data (for example a title).PNODES Displays names of the pnodes specified for the job.POSTREQ Displays the names of jobs that are automatically selected and executed

following execution of this job.PREREQ Displays the names of jobs that are automatically selected and executed

before execution of this job.PROGRAMMER Displays the programmer name.RELEASE Displays the names of jobs that are successors to this job, and which this job

releases for processing.field Displays information contained in user-defined fields. Up to 50 fields can be

requested separated by a comma.ALL Displays all job documentation information for this job. This is the default.

Operand Description

JOBINFO Command: Display Job Documentation

718

Although you can specify multiple fields, ESP can only display data on a particular field if you have coded it in your job documentation member.If no optional fields are specified, all job documentation information on the job is displayed. There are two versions of the command.• If JOBINFO is specified from a system console or from ESP’s line or Page mode

preceded by OPER, information is retrieved from the JOBDOC libraries identified in the started task Procedure.

• If JOBINFO is specified from a TSO terminal without being preceded with OPER, the JOBDOC libraries allocated in your LOGON Procedure or CLIST are used.

Using the CSF to retrieve job documentation information (BD or ED), you cannot select individual fields, as with the JOBINFO command.The following table summarizes where and how you can retrieve job documentation information:

Related informationFor information on job documentation, see the ESP Workload Manager User’s Guide.For information on specifying a job documentation library in an ESP Application, see the DOCLIB statement.

Origin Command Retrieved fromConsolidated Status Facility

BD or ED Library specified in the ESP Application.

Page mode or line mode JOBINFO DOCLIB in ESP Application or JOBDOC DD allocated to your TSO session

Page mode or line mode OPER JOBINFO JOBDOC DD allocated to the ESP started task.

Operator console F ESP,JOBINFO JOBDOC DD allocated to the ESP started task.

719

Examples All job documentation from JobIn the following example, all job documentation information for PAYJOB1 is displayed.JOBINFO PAYJOB1

Function, due out time and ABEND infoIn the following example, information on the function, due out time and the specific ABEND (SB37) information for job PAYJOB2 is displayed.JOBINFO PAYJOB2 FUNCTION DUEOUT ABENDS(SB37)

User defined fieldIn the following example, information about a user defined field is requested.JOBINFO PAYJOB3 FIELD(PAGER)

Messages and user-defined fieldsIn the following example, information about for PAYJOB4 on two specific messages and two user-defined fields is requested.JI PAYJOB4 MESSAGES(Z001,X446) FIELD(SEVERITY,PAGER)

JOBMAP Command: List Job Mapping Information

720

JOBMAP Command: List Job Mapping Information

The JOBMAP command is used in conjunction with the MAPGEN command to produce a list containing detailed information about jobs in Applications, including their relationships to one another.

Type Reporting command.

SyntaxJOBMAP DSN(dsname) [APPL(appl_id)] [JOBINDEX] [APPLINDEX] [RESINDEX] [NODISPLAY(list)]

Suppressed fieldsThe NODISPLAY operand lists fields that are not to be displayed, as follows:

Operand DescriptionDSN(dsname) Indicates the name of the map data set created by the MAPGEN command.APPL(appl_id) Indicates the name of the Application for which the information is to be

produced. If this operand is omitted, jobs from all Applications are selected.

JOBINDEX Produces an index of jobs after the job information pages.APPLINDEX Produces an index of Application after the job information pages.RESINDEX Produces an index of resources after the job information pages.NODISPLAY(list) Indicates certain information is to be suppressed on the output. This is a

list of values. The possible values and the data suppressed are listed below.

Value Information SuppressedEVENT Event nameCALENDAR Calendar namesJCLDS JCL data set and member nameSCOPE Scope (externals and manuals only)CLASS Job class

721

Usage notesSince the JOBMAP command uses the job mapping data set as input, you can report only on jobs contained in that data set.Special index pages to the primary report are produced only if the JOBINDEX, APPLINDEX or RESINDEX operands are specified on the JOBMAP command.The job information pages contain the following for each job in the schedule:• Job name• Application name• Job type (job, request, manual, external, etc.)• Scheduled time• Event name• Calendar names• JCL data set and member name• Indication if the JCL data set is a JCLLIB or TEMPLIB• Scope (externals and manuals only)• Job class• Programmer name• Tape drives and mounts (both cartridge and reel)• Elapsed execution time• CPU time• Hold count

PGMER Programmer nameTAPES Tape drives and mounts (both cartridge and reel)ELAPSED Elapsed execution timeCPU CPU timeHOLDCOUNT Hold countPRED List of predecessor jobsSUCC List of successor jobsRESOURCE List of resourcesPROC ESP Procedure data set and member nameTAG Tag

Value Information Suppressed

JOBMAP Command: List Job Mapping Information

722

• List of predecessor jobs• List of successor jobs• List of resources• ESP Procedure data set and member name• Tag.

Related informationFor information on creating a job mapping data set, see the MAPGEN command.For information on producing a job descendent tree report, see the JOBTREE command.

Examples Produce job map reportJOBMAP DSN('CYBER.MAPGEN')

In the following example, a job map report is produced and information is obtained from the CYBER.MAPGEN job mapping data set.The following is a sample of the information produced by the above JOBMAP command:JOB NAME APPL NAME TYPE SCHEDULING-------- --------- ---- -------------PAYJOB1 APPL1 JOB SCHEDULED: DAILY QUALIFIER: EVENT: CYBER.PAYROLL CALENDAR(S): SYSTEM JCL:

CYBER.JCL(PAYJOB1) SCOPE: CLASS: PROGRAMMER: FRED TAPES: REEL DRIVES: 0 REEL MOUNTS: 0 CART DRIVES: 0 CART MOUNTS: 0 ELAPSED: 0H 0M 0S

Suppress certain informationIn the following example, a job map report is produced. Run time information, tape data and CPU time information are suppressed. Information for this job map is obtained from the CYBER.MAPGEN job mapping data set:JOBMAP DSN('CYBER.MAPGEN') NODISPLAY (ELAPSED, TAPES, CPU)

723

Produce job map, job index and application indexIn the following example, a job map, job index and Application index reports are produced for the PAYROLL Application. Information is obtained from the CYBER.MAPGEN job mapping data set.JOBMAP DSN('CYBER.MAPGEN') APPL(PAYROLL) JOBINDEX APPLINDEX

The following is a sample of the job index page produced by the above JOBMAP command: JOB INDEX PAGE

JOB NAME APPL NAME PAGE -------- --------- ---- PAYJOB1 PAYROLL 1 PAYJOB2 PAYROLL 2 PAYJOB3 PAYROLL 2

END OF LIST

The following is a sample of the Application index page produced by the above JOBMAP command: APPLICATION INDEX PAGE

APPL NAME JOB NAME PAGE --------- -------- ---- PAYROLL PAYJOB1 1 PAYJOB2 2 PAYJOB3 2

END OF LIST

JOBNAME Statement: Specify Jobs Name (OS/400)

724

JOBNAME Statement: Specify Jobs Name (OS/400)

The JOBNAME statement is used only when defining jobs for the OS/400 agent to specify a name for the OS/400 job. This is the name displayed in the job queue or on the Work with Active Jobs display. It is used within the boundaries of the job definition.

TypeESP Workload Manager Application Statement

SyntaxJOBNAME jobname

Usage notesIf you do not specify a job name, the name defaults to the name specified in the CLPNAME statement. If you do not specify a CLPNAME, the name defaults to the job name in the ESP Workload Manager procedure.

Example Specifying an OS/400 job nameThis is an example of a JOBNAME statement:JOBNAME TEST1

In this example, TEST1 is the job name that appears in the Work with Active Jobs display of the ESP Workload Manager.

Operand Descriptionjobname Specifies the OS/400 job name description.

725

JOBQ Statement: Specify Job Queues (OS/400)

The JOBQ statement is used only when defining jobs for the OS/400 agent to identify the OS/400 job queue for the submitted program. The JOBQ statement can be used within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition, to apply to the entire application.

TypeESP Workload Manager Application Statement

SyntaxJOBQ libraryname.jobqueuename

Example Define the library and job queue names of an OS/400 jobThis an example of a JOBQ statement:JOBQ QBASE.JOBQUEUE

In this example, the job queue is JOBQUEUE in library QBASE.

Operand Descriptionlibraryname Specifies the name of the library containing the job queue; must be a

valid OS/400 library name.jobqueuename Specifies the name of the job queue for the submitted program; must

be a valid OS/400 job queue name.

JOBRES Command: Set Job Resources

726

JOBRES Command: Set Job Resources

The JOBRES command is used to add new resource requirements and change existing resource requirements for a job. This is done after the Application has been generated. Once the Application is generated, you can issue the JOBRES command at any time, including when the job is already waiting for resources (RESWAIT state).

Type General command.

SyntaxJOBRES JOB(name.qual) APPLICATION(name.gen) RESOURCE(n1,res1,n2,res2,…)

Usage notesJOBRES does not add or subtract from the original resource quantity specified-it strictly sets the new quantity.You can drop a resource requirement by specifying (0,resname).Resources not specified in the JOBRES command remain unchanged.

Example Set Data Base and tape requirementsThe following example sets the data base and tape requirements for MYJOB.Q1JOBRES JOB(myjob.q1) APPLICATION(cyber.22) -RESOURCE(1,db2tab1,3,t3480)

Operand Descriptionname.qual Indicates the name and the qualifier of the job that requires resource

modifications. name.gen Indicates the name and generation number of the Application in which

the job resides.n1,res1 Used to specify the quantity and resource name that will be set.

727

JOBTREE Command: Produce Job Descendant Tree

The JOBTREE command is used in conjunction with the MAPGEN command to produce a job-descendent tree from the job-mapping data set.

Type Reporting command.

SyntaxJOBTREE DSN(dsname) JOB(job_id[.qualifier]) [APPL(appl_id)]

Usage notesSince the JOBTREE command uses the job mapping data set as input, you can only report on jobs contained in that data set.

Related informationFor information on creating a job mapping data set, see the MAPGEN command.For information on producing a job map report, see the JOBMAP command.

Operand DescriptionDSN(dsname) Indicates a fully qualified data set name of the map data set created

by the MAPGEN command.JOB(job_id [.qualifier])

Indicates the name and optionally the job qualifier of the job for which the information is produced.

APPL(appl_id) Indicates the name of the Application for which the information is to be produced. If this operand is omitted, jobs from all Applications are examined for a match. If the job is in more than one Application, ESP uses the first instance it finds.

JOBTREE Command: Produce Job Descendant Tree

728

Examples Single job in single applicationIn the following example, a job map for PAYJOB1 in the PAYROLL Application is produced. The information is obtained from the CYBER.MAPGEN job mapping data set.JOBTREE DSN('CYBER.MAPGEN') JOB(PAYJOB1) APPL(PAYROLL)

The following provides a sample of the information produced by the above JOBTREE command: JOB DESCENDENT TREE

PAYJOB1 PAYROLL

PAYJOB2 PAYROLL

PAYJOB3 PAYROLL

In the above example, PAYJOB1 releases PAYJOB2 and PAYJOB3.

Qualified job in specified applicationIn the following example, a job map for PAYJOB.RUN1 in the PAYROLL Application is produced. The information is obtained from the CYBER.MAPGEN job mapping data set.JOBTREE DSN('CYBER.MAPGEN') JOB(PAYJOB.RUN1) APPL(PAYROLL)

Single jobIn the following example, a job map for PAYJOB2 is produced. Information is obtained from the CYBER.MAPGEN job mapping data set.JOBTREE DSN('CYBER.MAPGEN') JOB(PAYJOB2)

Single job in multiple applicationsIn the following example, a job map for PAYJOB3 in the PAYROLL and BILLING Applications is produced. The information is obtained from the CYBER.MAPGEN job mapping data set.JOBTREE DSN('CYBER.MAPGEN') JOB(PAYJOB3) APPL(PAYROLL)JOBTREE DSN('CYBER.MAPGEN') JOB(PAYJOB3) APPL(BILLING)

729

JTPEXCL Command: Exclude Programs from Status

The JTPEXCL command is used to provide a means to exclude a named program from affecting the job tracking completion status of the job. Normally this command is coded, with the ADD option, as an ESP initialization parameter.

Type General command

AuthorityYou require OPER authority to issue the JTPEXCL command.

SyntaxJTPEXCL [pgmname] (pgmname[,pgmname]...) [ADD|DELETE]

Usage notesSometimes the last step in a job executes regardless (COND=EVEN) of the execution of other steps in the job. This step normally performs some cleanup activity. The JTPEXCL command allows you to exclude the name of the program this last step executes from affecting the job tracking completion status of the job.Use the JTPEXCL command with no operands to display the programs excluded from job tracking status.

Related informationFor information on excluding programs from affecting job completion status at the initialization parameter level, see the JTPEXCL command in the ESP Workload Manager Installation and Configuration Guide.

Operand Descriptionpgmname Indicates a valid program name.ADD Indicates new information is to be added to the specification for

program exclusion. This is the default.DELETE Delete excluded programs from a previous JTPEXCL definition.

JTPEXCL Command: Exclude Programs from Status

730

Examples Display excluded programsIn the following example, all excluded programs are displayed.JTPEXCL

Exclude CLEANUPIn the following example, CLEANUP is excluded from affecting the job tracking completion status of the job.JTPEXCL CLEANUP

Delete previously defined exclusionIn the following example, CLEANUP is deleted and no longer affects the job tracking completion status of the job.JTPEXCL CLEANUP DELETE

731

JUMPTO Statement: Jump to Next Label

The JUMPTO statement is used to cause a forward search within an ESP Procedure to find the next label of the name given in the JUMPTO statement. Use the JUMPTO statement to skip over whole sections of an ESP Procedure. You can use a JUMPTO statement with or without an IF statement.

TypeControl Language (CLANG) statement.

SyntaxJUMPTO labelname

Usage notesThe JUMPTO statement is often used with IF-THEN-ELSE statements. JUMPTO allows you to skip whole processing sections of a Procedure under certain conditions. Labels used in conjunction with JUMPTO statements can be up to 16 characters. The first character must be an alphabetic character and you must type a colon after the last character.

Related informationFor information on ESP’s Control Language (CLANG) and ESP Procedures, see the ESP Workload Manager User’s Guide.

Examples Jump if last workday of yearIn the following example, if today is the last workday of the fiscal year ESP jumps to the LSTWDYR label and selects PAYJOB1 and PAYJOB2; otherwise PAYJOB99 is selected:IF TODAY('LAST WORKDAY OF FISCALYR') THEN JUMPTO LSTWDYRSELECT PAYJOB99EXITLSTWDYR:SELECT (PAYJOB1,PAYJOB2)

Operand Descriptionlabelname Indicates a valid label name consisting of up to 16 alphanumeric

characters.

JUMPTO Statement: Jump to Next Label

732

Jump and exit if MondayIn the following example, if today is:• Monday, ESP jumps to the MONDAY label, invokes the SPECIAL ESP

Procedure, and then exits.• Not Monday, ESP jumps to the NOT_MONDAY label, invokes the REGULAR

ESP Procedure, and then exits.APPL FREDJCLLIB 'CYBBS01.JCLLIB.CNTL'IF TODAY('MONDAY') THEN JUMPTO MONDAYIF TODAY('NOT MONDAY') THEN JUMPTO NOT_MONDAYMONDAY: INVOKE 'CYBER.PROCLIB.CNTL(SPECIAL)'EXITNOT_MONDAY: INVOKE 'CYBER.PROCLIB.CNTL(REGULAR)'EXIT

Jump if started task activeIn the following example, if the CICS started task is active, ESP jumps to the STOP label and issues the shutdown command, schedules a re-execution of the Event in five minutes, and exits. If CICS is not active ESP jumps to the GO label and issues a command to trigger the PROD.PAYROLL Event.IF ACTIVE('CICS') THEN JUMPTO STOP ELSE JUMPTO GOSTOP:VS 'F CICS,SHUTDOWN'REEXEC INfiveEXITGO:VS 'F ESP,TRIGGER PROD.PAYROLL'

733

Jump based on job nameIn the following example, this common ESP Procedure is invoked as a result of a job monitor Event. If CICS1, CICS2 or CICS3 abend, a generic job monitor Event is automatically triggered, and invokes this ESP Procedure. ESP jumps to the appropriate label (based on the jobname, represented by %MNJOB), triggers an Event, and exits.JUMPTO %MNJOBCICS1:ESP TRIGGER PROD.CICS1BKUPEXITCICS2:ESP TRIGGER PROD.CICS2BKUPEXITCICS3:ESP TRIGGER PROD,CICS3BKUPEXIT

LABEL Command: Label Documentation Library

734

LLABEL Command: Label Documentation Library

The LABEL command is used in conjunction with the GENDOC, REMOVE and GO commands when converting a non-ESP job documentation library to a documentation library usable by ESP. The LABEL command alters or replaces lines in the output data set, or inserts lines at different locations in the output data set.

Type General command.

SyntaxLABEL 'source_string' 'target_string' {BEFORE} {AFTER} {REPLACE} {OVERLAY} {INLINE} {ANY}

Operand Descriptionsource_string Indicates a string to be scanned. It can contain the '*' wildcard character. If the

ANY keyword is not used, the source string is expected to be the first non-blank character data on the line.

target_string Indicates a new string. If the target string contains the character '@', the '@' is replaced by the actual source string. If the source string is specified with wildcard characters, the wildcard characters are replaced with the actual characters found.

BEFORE Indicates the target string is placed on a line of its own just ahead of the line containing the source string.

AFTER Indicates the target string is placed on a line of its own just after the line containing the source string.

REPLACE Indicates the line containing the source string is deleted and a line containing just the target string is inserted instead.

OVERLAY Indicates the target string overlay the source string in the record. The target string is moved to the line being copied, starting at the same column as the source string. If the target string is longer than the source string, data following the source string may be overlaid.

INLINE Indicates the target string be used to replace the source string. If the strings are of unequal length, subsequent data is shifted left or right.

ANY Indicates the source string can be located anywhere on an input line. The default is to look for the source string as the first non-blank data on a line.

735

Usage notesThe GENDOC command identifies the input data set, members to be copied, and the output data set. It also lets you identify changes you want to make when the old documentation converts. Use the REMOVE, LABEL, and GO commands in conjunction with the GENDOC command to customize the conversion of non-ESP job documentation to ESP job documentation.

Related informationFor information on converting existing job documentation, see the GENDOC command.For information on identifying lines that are not to be copied to the output data set during the conversion, see the REMOVE command.For information on indicating that all specifications are complete and that the copy process should proceed, see the GO command.For information on job documentation, see the ESP Workload Manager User’s Guide.For information on displaying job documentation information, see the JOBINFO command, or the ESP Workload Manager User’s Guide.For information on identifying a job documentation library in an Application, see the DOCLIB statement.

Example GENDOC, REMOVE, LABEL and GO commandsThis example shows using commands GENDOC, REMOVE, LABEL, and GO to convert existing job documentation.In the following example, ESP:• Copies all members beginning with A and B from the data set JOBDOC.DATA to

the data set ESP.JOBDOC.DATA, suppressing any line numbers in the right–hand eight columns of each source member record.

• Does not copy any lines containing '**'.• Replace any lines starting with SYSOUT REVIEW’ with the character string

SYSOUT_REVIEW.• Overlays the semicolon on any line beginning with STEP. The semicolon is

positioned after the 3rd character following the string STEP.• Places the label RESTART: on its own line before any line starting with the string

RESTART PROCEDURES.• Proceeds with the copy process.

LABEL Command: Label Documentation Library

736

GENDOC JOBDOC.DATA ESP.JOBDOC.DATA LEV(A–,B–) SNUMREMOVE '**'LABEL 'SYSOUT REVIEW' 'SYSOUT_REVIEW' INLINELABEL 'STEP***' '@:' OVERLAYLABEL 'RESTART PROCEDURES' 'RESTART:' BEFOREGO

737

LANGUAGE Statement: Specify Language for ABAP (SAP)

The LANGUAGE statement specifies the language used for the ABAP started by the SAP_JOB.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax LANGUAGE language

Usage notesUse the LANGUAGE statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the LANGUAGE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.LANGUAGE corresponds to the SAPGUI ABAP program Language field on the Create Step dialog.

ExampleIn this example, English will be the language used when ABAP BTCTEST runs.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST LANGUAGE EENDJOB

Operand Descriptionlanguage Specifies an alphabetic character representing a valid language

for SAP System V4.5/4.6.Examples: E=English, D=German, R=Russian

Note: The SAP system default logon language is the default.

LATESUB Statement: Specify Late Submission

738

LATESUB Statement: Specify Late Submission

The LATESUB statement indicates a late submission time for a job. This is the latest acceptable submission time before the job is flagged as overdue.

SyntaxLATESUB criteria

Usage notesESP can provide notification when a job’s late submission time is exceeded. For example, you may want to send a message, or trigger an Event. From the CSF, you can filter on overdue jobs.The LATESUB statement can be used for any type of workload object and must be placed within the scope of a job statement (all statements up to an ENDJOB statement or the next JOB statement).The LATESUB time for a link or task represents the time when all of its dependencies should be met, as there is no actual job submission.The LATESUB statement’s date and time criteria are relative to the scheduled time of the Event.LATESUB does not force the submission of a job when its late submission time is exceeded. To force submission of a job regardless of dependencies use the ABANDON DEPENDENCIES statement. To bypass a job after a specified time and submit successor jobs, use the ABANDON SUBMISSION statement.To identify that a job has not started or finished by a specific time, use the DUEOUT statement.The LATESUB statement propagates dueout times upstream, for example, to all predecessors of the job where a LATESUB statement is specified. These dueout times are set relative to the average elapsed times according to the information obtained from ESP’s history file.

Related informationFor information on providing notification on job status, see the NOTIFY statement.For information on triggering an Event based on a job exceeding its late submission time, see the ESP Workload Manager Advanced User’s Guide.

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time.

739

Examples Flag overdue at 22:00In the following example, job A is flagged as overdue if ESP has not submitted the job by 22:00:JOB A RUN DAILY LATESUB 22:00ENDJOB

Flag overdue at 6 pm except MondayIn the following example, job A is flagged as overdue if ESP has not submitted it by 6 pm every day except on Monday, when the late submission time is 4 pm:JOB A RUN DAILY IF TODAY('MONDAY') THEN LATESUB 4PM ELSE LATESUB 6PMENDJOB

Flag link process overdueIn the following example, job SET.INITS is flagged as overdue if its dependencies are not satisfied by 4 pm:JOB SET.INITS LINK PROCESS RUN DAILY LATESUB 4PM VS '$SI1-5'ENDJOB

When event misses scheduled timeIn the following example, an Event (CYBER.TEST) missed its scheduled execution time due to system problems. When the Event was triggered at 11 pm, job A was submitted and flagged as overdue in the CSF.EVENT ID(CYBER.TEST) SCHEDULE 9PM DAILYINVOKE 'CYBBS01.PROCLIB.CNTL(TEST)'ENDDEF

The following job has a late submission time of 10 pm:JOB A RUN DAILY LATESUB 10PMENDJOB

LATESUB Statement: Specify Late Submission

740

The following CSF display shows the status of a job flagged as overdue:ESP Consolidated Status: View TEST Row 1 of 2, Col 1COMMAND ===> SCR ===> PAGE Jobname APPL GEN STATUS___ A TEST 8 SUBMITTED OVERDUE

Flag the job as overdue if it is not submitted 10 minutes after the scheduled execution time of the Event:LATESUB NOW PLUS 10 MINUTES

Flag the job as overdue if it is not submitted by 7am tomorrow:LATESUB 7AM TOMORROW

Flag the job as overdue if it is not submitted two hours after the Event is triggered:LATESUB REALNOW PLUS 2 HOURS

741

LAX Command: List External Jobs

The LAX command is used to display external jobs in active Applications.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LAX command.

SyntaxLAX

Usage notesUse the EXTERNAL keyword as part of a JOB statement to tell ESP the job is part of another Application. This allows you to establish relationships between jobs in different Applications.

Related informationFor information on Applications, see the ESP Workload Manager User’s Guide.For information on posting external or manual jobs complete, see the APPL statement or the ESP Workload Manager Advanced User’s Guide.

Examples Sample ApplicationsThe following is an example of an Application containing an external job that runs as part of another Application:APPL BILLING JCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB99 EXTERNAL RUN WORKDAYS REL BILJOB1JOB BILJOB1 RUN WORKDAYSENDJOB

The following is an example of the Application where the External job (above) actually runs:APPL PAYROLL JCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB99 RUN WORKDAYSENDJOB

LAX Command: List External Jobs

742

The following LAX command displays External jobs in active Applications:LAX BILLING.28: PAYJOB99--- 1 APPLS DISPLAYED

In the above example, the LAX command displays the name of the External job and the Application that job belongs to.

743

LCMDPRFX Command: List Commands Prefixing

The LCMDPRFX command is used to display whether command prefixing is in effect or not. If command prefixing is in effect, LCMDPRFX displays the character to be substituted for the “F stcname,” (where stcname is the started task name for ESP) string when issuing modify commands to ESP from a system console.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LCMDPRFX command.

SyntaxLCMDPRFX

Related informationFor information on substituting a character for the “F ESP,” string, see the CMDPRFX command.

Example Display character substitutionThe following LCMDPRFX displays the character that is substituted for the “F ESP,” string:OPER LCMDPRFX'#' 'F ESP,'

In the above example, the number sign (#) was previously set as the character to be substituted for the “F ESP,” string when issuing modify commands to ESP from a system console.

LDSN Command: List Data Sets

744

LDSN Command: List Data Sets

The LDSN command is used to produce a display of the current system data sets allocated to ESP.

TypeGeneral command.

SyntaxLDSN

Related informationFor information on defining ESP data sets, see the ESP Workload Manager Installation and Configuration Guide.

Example Sample display In the following example, current system data sets allocated to ESP are displayed:LDSNCHECKPOINT: CYBER.ESP510.CKPT, ALT NONE USERDEF: CYBER.ESP510.USERDEF, BKUP NONE INDEX: CYBER.ESP510.INDEX, BKUP NONE JOBINDEX: CYBER.ESP510.JOBINDEX, BKUP CYBER.ESP510.BKUP.JOBINDEX QUEUE: CYBER.ESP510.QUEUE, ALT NONE TRAKFILE: CYBER.ESP510.TRAKFILE EVENTSET: CYBER.ESP510.EVENT1 HISTFILE: CYBER.ESP510.HISTFILE APPLFILE: CYBER.ESP510.APPLFILE JTDT: CYBER.ESP510.PARMLIB(JOBDEF1) UPDT: CYBER.ESP510.PARMLIB(PROFILE)

745

LDSTCELL Command: List Data-Set-Trigger Cells

The LDSTCELL command is used to display data-set-trigger cell (DSTCELL) information, including the number in use and the maximum number used.

TypeGeneral command.

SyntaxLDSTCELL

Usage notesData-set-trigger cells are used during processing of the DSTRIG command.

Related informationFor information on defining data-set-trigger cells, see the DSTRIG initialization parameter in the ESP Workload Manager Installation and Configuration Guide.

Example Sample listingIn the following example, data-set-trigger cells information is displayedPOOLSZ-MAXSIZE-CURRUSE-MAXUSED-GETMAINS-OVERFLOW

5 15 8 12 4 0

LDTE Command: List Data Set Triggers

746

LDTE Command: List Data Set Triggers

The LDTE command is used to list data sets being checked for data set activity as specified by the DSTRIG command in an Event definition or by the DSNAME statement within a DSTRIG workload object in an Application.

TypeGeneral command.

SyntaxLDTE

Related informationFor information on data set triggering at the Event level, see the ESP Workload Manager User’s Guide.For information on data set triggering at the job level, see the ESP Workload Manager User’s Guide.For information on displaying data sets being checked for closure, creation or renaming, see the LDXE command.

Example Sample displayIn the following example, data sets checked for data set activity are displayed:LDTETHE FOLLOWING DATASET(S) ARE BEING CHECKED FOR DATASET TRIGGERSCYBER.PAYROLL.DATA CREATE-CLOSEUSER.INPUT.CYCLE ANYCLOSE2 DATASET TRIGGERS FOUND

747

LDTREL Command: List Data Set Trigger Excludes

The LDTREL command is used to display the entries from the Data set Trigger Exclude list.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LDTREL command.

SyntaxLDTREL

Usage notesThe Data set Trigger Exclude list consists of a list of programs that are not eligible for data set triggering. The DSTREXCL initialization parameter specifies these. Use the DSTREXCL command to flag an entry in the Data set Trigger Exclude list as invalid.

Related informationFor information on flagging an entry in the Data set Trigger Exclude list as invalid, see the DSTREXCL command.For information on adding an entry to the Data set Trigger Exclude list at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.

Example Sample displayIn the following example, USRPGM is not eligible for data set triggering:LDTREL DSTRIG exclude PGM=USRPGM

LDXE Command: List Objects Awaiting Triggers

748

LDXE Command: List Objects Awaiting Triggers

The LDXE command is used to list data set names and the corresponding Events or Applications waiting for data set activity. Data set trigger requirements are identified by the DSTRIG command in an Event definition or by the DSNAME statement in an Application.

TypeGeneral command.

SyntaxLDXE

Related informationFor information on data set triggering at the Event level, see the ESP Workload Manager User’s Guide.For information on data set triggering at the job level, see the ESP Workload Manager User’s Guide.For information on displaying data set triggered Events, see the LDTE command.

Example Sample displayIn the following example, data sets that are checked for closures, creation, or renames are displayed:LDXEEVENT/APPL (WOB)--------DATASETPAYROLL.1 (WAIT4.DS) CYBER.PAYROLL.DATA,ANYCLOSECYBER.CYCLES USER.INPUT.CYCLE

749

LIBL Statement: Specify Library Name (OS/400)

The LIBL statement is used only when defining jobs for the OS/400 agent to specify the name of the library or libraries to add to the user’s library list for this job. The LIBL statement is used within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition, to apply to the entire application. Multiple LIBL statements are supported within a job definition.

TypeESP Workload Manager Application Statement

SyntaxLIBL {name|(name[ name2 ...])}

Usage notesLIBL specifies the initial user part of the library list that is used to search for operating system object names that were specified without a library qualifier. The library names passed to the OS/400 SBMJOB command define the INLLIBL parameter of the SBMJOB command. The INLLIBL parameter in the SBMJOB command will override the Job Description's INLLIBL parameter that is defined by the JOBD statement in the ESP Workload Manager job definition.If LIBL is not defined but USER is defined within the job definition the following will occur:• The agent uses the USER default library list.• The agent uses *SYSVAL instead of the default *CURRENT, as the INLLIBL

parameter in SBMJOB command, if the User Profile does not specify the JOBD parameter. (The default JOBD parameter of the OS/400 User Profile is QGPL/QDFTJOBD.)

• The agent uses the INLLIBL parameter from the Job Description (JOBD) instead of the default *CURRENT as the INLLIBL parameter in SBMJOB command if the User Profile has a specific JOBD parameter.

• The agent uses the User Profile’s CURLIB parameter instead of the default *CURRENT, as the CURLIB parameter in the SBMJOB command.

Operand Descriptionname The name of each library you want to add to the library list. Add a

space between each library name. No more than 25 libraries can be specified. The libraries are searched in the same order as they are listed.

LIBL Statement: Specify Library Name (OS/400)

750

ExamplesAdd a library to the library list of an OS/400 jobLIBL PAYROLL

In this example, the library PAYROLL is added to the library list.Add more than one library to the library list of an OS/400 jobLIBL (PAYROLL FINANCE)

In this example, the libraries PAYROLL and FINANCE are added to the library list.

751

LIBSUB Command: Submit JCL from Librarian Data Set

The LIBSUB command is used to submit JCL from a Librarian data set to the internal reader.

TypeEvent definition command.

SyntaxLIBSUB 'dsname[(member)]'

Usage notesSeveral LIBSUB commands may be specified in a single Event. The input data are effectively concatenated together, so that data from several data sets can be joined together to form one or more jobs. In the same Event, you can also use the SUBMIT command, as well as submitting from ROSCOE and PANVALET data sets.To submit Librarian jobs as part of an Application, prefix the Librarian data set with LIB- on the JCLLIB statement, as follows:APPL PAYROLLJCLLIB LIB-LIB01A.DATAJOB PAYJOB1 RUN DAILYENDJOB

Related informationFor information on submitting JCL from an Event, see the ESP Workload Manager User’s Guide.For information on identifying a JCL library, see the JCLLIB statement.

Operand Descriptiondsname Indicates a valid LIBRARIAN data set name. You do not have to

specify “LIB-” as a data set identifier, because using the LIBSUB command implies the use of a LIBRARIAN data set.

member Indicates a member name, which can consist of up to eight characters if specified.

LIBSUB Command: Submit JCL from Librarian Data Set

752

Example Event definition that submits JCL from a LIBRARIAN data setIn the following example, PRODCNTL is submitted at 9 am on the first Monday of the month from the LIBRARIAN data set LIB01A.DATA:EVENT ID(CYBER.ONELIBJOB)SCHEDULE 9AM FIRST MONDAY OF MONTHLIBSUB 'LIB01A.DATA(PRODCNTL)'ENDDEF

753

LINES Statement: Specify Number of Lines per List Page (SAP)

The LINES statement specifies the number of lines per list page.

ApplicabilityESP Business Agents for SAP, Version 2.2 and higher.

Syntax LINES num

Usage notesUse the LINES statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the LINES statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.LINES corresponds to the SAPGUI Print settings, Report page, Rows field on the Background Print Parameters dialog.

ExampleIn this example, the report will print fifteen lines per list page.

APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST LINES 15ENDJOB

Operand Descriptionnum The length of the list is determined by its content. You can use 0

or blank only when viewing the list online. You can not use 0 or blank to format a list to be printed. num must be numeric. You can specify up to 486 lines.

LINUX_JOB Statement: Identify the Name of LINUX Jobs

754

LINUX_JOB Statement: Identify the Name of LINUX Jobs

The LINUX_JOB statement is used to identify the name of a LINUX job in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use LINUX jobs, you must load a workload object module. The LINUX_JOB workload object module is CYBESOLJ. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Refer to the JOB statement usage notes.

Examples:Define an Agent jobLINUX_JOB PAYDATA RUN DAILY RELEASE PAYRPT AGENT LINUX_NY SCRIPTNAME /usr/data/payENDJOB

755

LIST Command: List Event Information

The LIST command is used to display Event information.

TypeGeneral command.

SyntaxThe syntax of the LIST command by LEVEL is:{LIST|L} [LEVEL{(groupprefix)|(levelname)}] [ALL] [SYSTEM] [CLASS(classname)] [TIMESEQ] [PRINT(dsname)] [MOD]

The syntax of the LIST command by EVENT is: {LIST|L} EVENT(eventid) [ALL] [PRINT(dsname)] [MOD]

Operand Description

groupprefix Indicates the current group prefix.

levelname Enter up to 24 characters in the level name. All Events whose names begin with the specified string are displayed. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking anywhere but in the prefix.

ALL Indicates all available information on the Events is displayed. If this operand is omitted, the display is limited to the next execution time. The information displayed with the ALL option is enough to redefine the Event in its entirety.

SYSTEM Indicates the ID of the ESP system that is to execute the Event is included in the display.

classname Indicates the display is restricted to Events with the specified class name.

TIMESEQ Indicates the Event names are to be displayed in execution time sequence order rather than alphanumeric collating sequence.

eventid Indicates the name of a specific Event to be displayed.

LIST Command: List Event Information

756

Usage notesWhen issuing the LIST command from Page mode, that is under the ISPF interface, you must use the abbreviated form of the LIST command (L). An asterisk indicates that any character in the asterisk location acts as a match.A hyphen indicates that any character in that or subsequent character positions is considered a match.If the level name contains a period, the part to the left of the period indicates the prefix (group or userid), while the part to the right indicates the descriptive name.If a prefix is specified, it cannot contain asterisks or a hyphen. If the level name does not contain a period, it is assumed to be a prefix if:• It contains eight characters or less, and• It does not contain either asterisks or a hyphen.Otherwise it is assumed to be a descriptive name.The PRINT operand of the LIST command is useful when changes are required for multiple Events. The following summarizes how to accomplish this:• Issue the LIST command with the PRINT operand for the desired group of Events • Edit the data set as required• Issue the LOAD command to re-load the edited Events.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide. For information on loading ESP commands from a data set, see the LOAD command.

Examples List event namesIn the following example, the names and next execution times of all Events defined to the PROD group prefix are displayed:L LEVEL(PROD)

dsname Indicates the name of a data set to receive the output. The record format of the data set is preserved. ESP can write fixed, variable or undefined records, blocked or unblocked

MOD Indicates the data set receiving output is appended to.

Operand Description

757

Write results to a data setIn the following example, the complete definitions of all Events defined to the PROD group prefix are written to the ESP.EVENTS data set:L LEVEL(PROD) ALL PRINT('ESP.EVENTS')

List event namesIn the following example, the names of all Events beginning with BKUP defined to the CYBER group prefix are displayed:LIST LEVEL(CYBER.BKUP-)

Note: The above LIST command is not abbreviated as it is issued from a batch job.List specific events for my group prefixIn the following example, all Events that start with my current group prefix, followed by 'A' and any number of characters are displayed:L LEVEL(A-)

List events in time sequenceIn the following example, the execution time and system ID of all Events defined to the PROD group prefix whose names have a PR in character positions three and four are displayed in execution time sequence:L LEVEL(PROD.**PR-) TIMESEQ SYS

List specific eventIn the following example, all available information for CYBER.PAYROLL is displayed:L EVENT(CYBER.PAYROLL) ALL

LISTAPPL Command: List Applications

758

LISTAPPL Command: List Applications

The LISTAPPL command is used to display Application information. The short form of this command name is LAP.

TypeGeneral command.

Syntax{LISTAPPL|LAP} applname[.gen] [STATUS|ALL|JOBS|JOB(jobname[,jobname]...)] [COMPLETE|INCOMPLETE] [PREDECESSORS] [SUCCESSORS] [CRITPATH|NOTCRITPATH] [SUBAPPL(subapplname)] [OLDEST] [DUMP]

Operand Description

applname The applname operand can contain wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book.) An absolute or relative generation number can also be specified with a specific applname as follows:• applname.0—displays the most recent generation of Application.• applname.-n—displays the nth previous generation of the Application.• applname.n—displays the absolute generation n of the Application.

STATUS Displays the status of each Application, without detailing the jobnames.

ALL Displays information about each job. This includes successor and predecessor information for each job, as well as resource information.

JOBS Displays the names of each job in an Application. The display is divided into two sections: jobs that have completed and jobs that have yet to complete.

JOB(jobname) Displays in a structured view each job or qualified job you have specified.COMPLETE Omission of the COMPLETE keyword results in a display of Applications

that still have active or incomplete jobs, unless an absolute or relative generation number is specified. The COMPLETE keyword requests that completed Applications are also included in the display.

INCOMPLETE Displays all incomplete Applications. This is the default if not specified.

759

Usage notesThe LISTAPPL command displays information from the APPLFILE.The LISTAPPL command displays anticipated end times for all jobs in an Application.When critical path analysis is turned on the LISTAPPL command:• Displays all jobs on the critical path with a label of CRITICAL PATH• Displays the job in the Application that is coded with the CRITICAL keyword

with a label of CRITICAL• Displays all jobs that are not on the critical path.The LISTAPPL command cannot be issued from a system console.Use the LAP command with the ALL keyword to give a structured view of an active Application or with other keywords to give a summary of active or completed Applications. You can limit the display to specific generations of an Application and to specific jobs within an Application.

Related informationFor information on displaying active Applications from the CSF, see the ESP Workload Manager User’s Guide.For information on manipulation jobs in active Applications, see the APPLJOB or AJ command.For information on critical path analysis, see the ESP Workload Manager User’s Guide.

PREDECESSORS Displays the names of any predecessors for each complete job. The PREDECESSORS operand is used in conjunction with the ALL operand.

SUCCESSORS Displays the names of any successors for each complete job. The SUCCESSORS operand is used in conjunction with the ALL operand.

CRITPATH Displays all jobs on the critical path if critical path analysis is turned on. NOTCRITPATH Displays all jobs not on the critical path if critical path analysis is turned

on. SUBAPPL(subapplname)

Display is limited to the subApplication specified.

OLDEST Requests a display of the oldest incomplete generation of an Application.

DUMP Displays in hexadecimal format Application record information for problem diagnosis.

Operand Description

LISTAPPL Command: List Applications

760

Examples List active generationIn the following example, a structured view of the PAYROLL Application is displayed:LAP PAYROLL.0 ALL

List previous generationIn the following example, the status of the -1 generation of the PAYROLL Application is displayed:LAP PAYROLL.-1 ALL

List all generationsIn the following example, all complete and incomplete generations of the PAYROLL Application are displayed:LAP PAYROLL COMPLETE

List specific jobIn the following example, a structured view of PAYJOB1 within the PAYROLL Application is displayed:LAP PAYROLL.0 JOB(PAYJOB1)

List subapplicationIn the following example, a structured view of the PAYROLL subApplication within the FINANCE Application is displayed:LAP FINANCE.0 SUBAPPL(PAYROLL) ALL

List specific jobsIn the following example, a structured view of PAYJOB1, PAYJOB2, and PAYJOB3 within the oldest incomplete generation of the PAYROLL Application are displayed:LAP PAYROLL JOB(PAYJOB1,PAYJOB2,PAYJOB3) OLDEST

List predecessors and successorsIn the following example, the predecessors and successors of each job in the -2 generation of the PAYROLL Application, and whether those predecessors or successors are complete, are displayed:List each jobLAP PAYROLL.-2 ALL PRED SUCC

List each jobIn the following example, a summary of complete and incomplete jobs within the PAYROLL Application is displayed:LAP PAYROLL.0 JOBS

761

Sample list, no critical path analysisThe following is an example of the display produced by the LAP command (LAP PAYROLL.105 ALL) with critical path analysis turned off:APPL PAYROLL GEN 105 CREATED AT 13.04 ON WEDNESDAY JANUARY 28TH, 2004 BY EVENT CYBER.PAYROLL PAYJOB1, HC=0 SUBMISSION AT 21.00 ON WEDNESDAY JANUARY 28TH, 2004 ANTICIPATED END TIME: 21.00 ON WEDNESDAY JANUARY 28TH, 2004 PREDECESSORS: (NONE) SUCCESSORS: PAYJOB2, PAYJOB3 PAYJOB2, HC=1 ANTICIPATED END TIME: 21.00 ON WEDNESDAY JANUARY 28TH, 2004 PREDECESSORS: PAYJOB1 SUCCESSORS: PAYJOB4 PAYJOB3, HC=1 ANTICIPATED END TIME: 21.00 ON WEDNESDAY JANUARY 28TH, 2004 PREDECESSORS: PAYJOB1 SUCCESSORS: PAYJOB4 PAYJOB4, HC=2 ANTICIPATED END TIME: 21.00 ON WEDNESDAY JANUARY 28TH, 2004 PREDECESSORS: PAYJOB2, PAYJOB3 SUCCESSORS: (NONE)

Sample list with critical pathThe following is an example of the display produced by the LAP command with critical path analysis turned on:APPL PAYROLL GEN 105 CREATED AT 13.04 ON WEDNESDAY JANUARY 28TH, 1998 BY EVENT CYBER.PAYROLL PAYJOB1, HC=0 SUBMISSION AT 21.00 ON WEDNESDAY JANUARY 28TH, 2004 ANTICIPATED END TIME: 21.00 ON WEDNESDAY JANUARY 28TH, 2004 - CRITICAL PATH PREDECESSORS: (NONE) SUCCESSORS: PAYJOB2, PAYJOB3 PAYJOB2, HC=1 ANTICIPATED END TIME: 21.00 ON WEDNESDAY JANUARY 28TH, 2004 PREDECESSORS: PAYJOB1 SUCCESSORS: PAYJOB4 PAYJOB3, HC=1 ANTICIPATED END TIME: 21.00 ON WEDNESDAY JANUARY 28TH, 2004 - CRITICAL PATH PREDECESSORS: PAYJOB1 SUCCESSORS: PAYJOB4

LISTAPPL Command: List Applications

762

PAYJOB4, HC=2 ANTICIPATED END TIME: 21.00 ON WEDNESDAY JANUARY 28TH, 2004 - CRITICAL PREDECESSORS: PAYJOB2, PAYJOB3 SUCCESSORS: (NONE)

In the above example, a structured view of the PAYROLL Application is displayed. Jobs on the critical path are displayed with the CRITICAL PATH label, and the critically identified job in the Application is displayed with the CRITICAL label.

763

LISTAPTF Command: List Application File

The LISTAPTF command is used to display information on the current status of the Application file.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTAPTF command.

SyntaxLISTAPTF

Usage notesThe information displayed includes data set name, date and time formatted, and current allocation status.

Related informationFor information on defining ESP data sets, see the ESP Workload Manager Installation and Configuration Guide.

Example List current statusIn the following example, information on the current status of the Application file is displayed.OPER LISTAPTFDATASET CYB2.ESP510.APPLFILE FORMATTED AT 17.33.55 ON MONDAY NOVEMBER 17TH, 2003 3600 SLOTS TOTAL, 3464 AVAILABLE, NEXT IS 928

LISTAT Command: List Authorization Tables

764

LISTAT Command: List Authorization Tables

The LISTAT command is used to display the contents of an authorization table.Note: LISTAT is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

SyntaxLISTAT tabname [DECOMPILE]

Usage notesAn authorization table provides a way of controlling access to job tracking data. For instance, you may not want to allow one customer to view job-tracking information for another customer’s jobs. The use of an authorization table means that access to data for tracked jobs depends on the jobname and on an authorization string.The DEFAT command is used to define or alter an authorization table, limiting access to tracked job data. An authorization table provides a way of controlling access to job tracking data.

Related informationFor information on defining or altering an authorization table, see the DEFAT command.

Operand Descriptiontabname Indicates the name of the authorization table you want displayed. The

name consists of up to eight characters. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

DECOMPILE Indicates you want the authorization table to be displayed in the same way in which it was defined. The DECOMPILE option generates a DEFAT (define authorization table) command you could feed directly back into ESP.

765

Examples List tableIn the following example, the contents of an authorization table are displayed.LISTAT AUTHTAB1JOB AUTH TABLE: AUTHTAB1DEFINED AT 11.30 ON FRI 2JAN99 BY CYBBP01INCLUDE: ABC-,ACO-, XYZ-,ACO-EXCLUDE: -,AC02

List in way definedIn the following example, AUTHTAB1 is displayed the same way in which it was defined:LISTAT AUTHTAB1 DECOMPILE

LISTCAL Command: List Calendars

766

LISTCAL Command: List Calendars

The LISTCAL command is used to display information about a calendar.

TypeGeneral command.

Syntax{LISTCAL|LCAL} calname

Usage notesAfter you have defined a calendar, and those users with update access have defined their scheduling terms in the calendar, you or any other user may want to review information about the calendar.Like the users who defined their scheduling terms in the calendar, you may need to review the calendar information for troubleshooting and maintenance. Other users who automatically have read access to the calendar may find it useful to review the calendar information before using it in an Event.If you do not specify a calendar name, the most recently retrieved calendars are displayed. A set of calendars is retrieved as a result of a LISTHOL, LISTSPEC, EVENT, CALENDAR, or prior LISTCAL command. If no calendars were previously retrieved, you are prompted to enter a calendar name.

Related informationFor information on defining and deleting holidays, see the DEFHOL and DELHOL commands.For information on defining and deleting special days, see the DEFSPEC and DELSPEC commands.For information on altering the attributes of a calendar, see the ALTCAL command.For information on defining calendars, see the ESP Workload Manager User’s Guide or the DEFCAL command.For information on using special calendars in an Event, the ESP Workload Manager User’s Guide.For information on using calendars, see the ESP Workload Manager User’s Guide.

Operand Descriptioncalname Indicates a name or generic level of the calendar or calendars

displayed. It can be up to eight characters long. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

767

Examples Sample listIn the following example, the contents of the SYSTEM calendar are displayed.LISTCAL SYSTEMCALENDAR NAME: SYSTEMDEPARTMENT: NONEDEFINED: AT 15.42 ON THU 23RD SEP 1993 BY CYBSM04OWNER: USR01WORKDAYS: MON TUE WED THU FRIWEEK STARTS: MONSIZE: 280 BYTESHOLIDAYS: CHRISTMAS, NEW_YEARS, CHRISTMAS, NEW_YEARSSPECIAL DAYS: INVENTORY_DAY(1)

List specific calendarsIn the following example, the contents of all calendars with PAY in the first three positions are displayed:LISTCAL PAY-

LISTCKPT Command: List Checkpoints

768

LISTCKPT Command: List Checkpoints

The LISTCKPT command lists statistics for the checkpoint data set.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTCKPT command.

Syntax LISTCKPT

Usage notesThe information displayed by this command includes the Checkpoint data set name, the maximum size available, and the current usage.

Related informationFor information on defining ESP data sets, see the ESP Workload Manager Installation and Configuration Guide.

Example Sample listOPER LISTCKPTPRIMARY CHECKPOINT CYB2.ESP510.CKPTMAX CHECKPOINT SIZE 737280HIGHEST ADDRESS USED 323232 BYTES IMBEDDED FREE SPACE

In the above example, statistics on the Checkpoint data set are displayed.

769

LISTEVS Command: List Event Data Sets

The LISTEVS command is used to display the status of any or all of the Event data sets.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTEVS command.

SyntaxLISTEVS [eventdb]

Usage notesIf an Event data set is closed when the LISTEVS command is issued, the status is displayed as follows:****DATASET IS IN SUSPENDED STATE

Related informationFor information on defining ESP data sets, see the ESP Workload Manager Installation and Configuration Guide.

Examples Sample listIn the following example, the status of the EVENT1 data set is displayed:LISTEVSEVENTSET EVENT1, DSN=CYB2.ESP510.EVENT1 SHR NOJRNLNEXT SCAN AT 06.00 ON WEDNESDAY JANUARY 28TH, 1998BACKUP DATASET CYB2.ESP510.BACKUP.EVENT1

List all event data setsIn the following example, all Event data sets are displayed:LISTEVS

Operand Descriptioneventdb Indicates the logical name of an Event data set. If this operand is

omitted, all the Event data sets are displayed.

LISTEVS Command: List Event Data Sets

770

List specific data setIn the following example, the status of the EVENT1 data set is displayed:LISTEVS EVENT1

771

LISTGRP Command: List Groups

The LISTGRP command is used to display information on your current group or any other group to which you are connected. Note: LISTGRP is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

Syntax{LISTGRP|LG} [groupname]

Usage notesThe information displayed by this command includes the group attributes and the names of the users who are connected to the group.

Related informationFor information on defining and deleting groups, see the DEFGROUP and DELGROUP commands.For information on altering a group definition, see the ALTGROUP command.

Examples List current groupIn the following example, a group name is omitted and your current group is displayed:LISTGRP

List specific groupIn the following example, GROUP1 is displayed:LISTGRP GROUP1

Operand Descriptiongroupname Indicates the logical name of the group definition to be displayed.

Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. If the group name is omitted, your current group is displayed.

LISTGRP Command: List Groups

772

List multiple groupsIn the following example, all groups beginning with PAY are displayed:LISTGRP PAY-

List all groupsIn the following example, all groups are displayed:LISTGRP -

773

LISTHIST Command: List History Files

The LISTHIST command is used to display the status of any or all of the history files.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTHIST command.

SyntaxLISTHIST [histfid]

Related informationFor information on defining ESP data sets, see the ESP Workload Manager Installation and Configuration Guide.

Examples Sample listIn the following example, the status of the HIST1 history file is displayed:OPER LISTHISTHISTFILE HIST1, DSN=CYB2.ESP510.HISTFILE SHR NOJRNLNO BACKUP TIME SETNO BACKUP DATASET

List specific history fileIn the following example, the HIST1 history file is displayed:LISTHIST HIST1

List multiple history filesIn the following example, all history files with HIST in the first four positions are displayed:LISTHIST HIST-

Operand Descriptionhistfid Indicates the logical name of a HISTFILE using up to eight

characters. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. If this Operand is omitted, all the history files are displayed.

LISTHOL Command: List Holidays

774

LISTHOL Command: List Holidays

The LISTHOL command is used to list previously defined holidays.

TypeGeneral command.

Syntax{LISTHOL|LH} name [GROUP(groupname)] [CALENDAR(calname)] [FROM(fromdate)] [TO(todate)]

Usage notesIf no group name or calendar name is specified, the most recently retrieved set of calendars is displayed. If no calendars were retrieved in the current command session, the default calendars for the current group are displayed. A start and/or end date can be specified to restrict the displayed holidays to a specific time period. Holidays are displayed in time sequence order within each calendar.The display can be restricted to holidays containing a specified character string. The first operand specifies a holiday name or generic holiday name. If you want all holidays to be displayed but need to use another operand, specify a hyphen ('-') as the first operand.

Operand Description

name Indicates a full or generic name. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. If this operand is omitted, all holidays are displayed. Code “-” if you are using any other operands and want all the holidays to be displayed.

groupname Indicates holidays from the default calendars of the specified group are displayed.

calname Indicates the name of the calendar to be searched. This operand is mutually exclusive with the GROUP operand.

fromdate Indicates a start date for the holidays to be displayed. Only holidays that fall on or after this date are displayed. If no year is specified, ESP uses the current year.

todate Indicates an ending date for the holidays to be displayed. Only holidays that fall on or before this date is displayed. If no year is specified, ESP uses the current year.

775

To specify a date, use any format ESP recognizes. If the date contains any blanks or commas, enclose the string in quotes.

Related informationFor information on defining and deleting holidays, see the DEFHOL and DELHOL commands.

Examples List all holidaysIn the following example, a holiday name is omitted and the defined holidays in your default calendar are displayed:LISTHOL

List holidays to specific dateIn the following example, all holidays in the CAL1 and the SYSTEM calendar up to the end of September are displayed:LISTHOL - CALENDAR(CAL1) TO(SEPT30TH)

List specific holidaysIn the following example, all the holidays in the year 2001 that begin with N and have W in position three of the name are displayed. The calendars to be searched are the default calendars for the PAYROLL group.LISTHOL N*W- GROUP(PAYROLL) FROM('1JAN2001') TO('31JAN2001')

Sample listIn the following example, holidays defined on the SYSTEM calendar are displayed:CALENDAR SYSTEM NEW_YEARS 00.00 ON THU 1ST JAN 04 TO 00.00 ON FRI 2ND JAN 04 VICTORIA_DAY 00.00 ON MON 18TH MAY 04 TO 00.00 ON TUE 19TH MAY 04 MEMORIAL_DAY 00.00 ON MON 25TH MAY 04 TO 00.00 ON TUE 26TH MAY 04 XMAS 00.00 ON FRI 25TH DEC 04 TO 00.00 ON SAT 26TH DEC 04 ---- 5 HOLIDAYS DISPLAYED ----

LISTJTML Command: List Tracking Models

776

LISTJTML Command: List Tracking Models

The LISTJTML command is used to list internal tracking model data.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTJTML command.

SyntaxLISTJTML

Usage notesThe DEFTM command defines a tracking model and allows you to centralize the definition of tracking characteristics, which can be assigned to one job, or a group of jobs. Jobs are normally associated with a tracking model in a job tracking definition table.

Related informationFor information on displaying the definition of tracking models, see the LTM command.For information on defining and deleting a tracking model, see the DEFTM and DELTM commands.

Example Sample listIn the following example, tracking model data is displayed:OPER LISTJTML1 TRACKING MODEL BUFFER5398 MODELS LOCATED IN INCORE BUFFERS88 MODELS LOCATED VIA READ TO JOBINDEX

777

LISTPN Command: List Pnodes

The LISTPN command is used to display the definition of one or more pnode entries. A pnode represents a stage a job goes through during processing.

TypeGeneral command.

Syntax{LISTPN|LPN} name

Usage notesThe INPUT, EXEC, and OUTPUT pnodes are normally defined when installing ESP. Any data defined using the DEFPN command is displayed.

Related informationFor information on defining and deleting manual pnodes, see the DEFPN and DELPN commands.For information on defining processing nodes (pnodes), see the ESP Workload Manager Advanced User’s Guide.

Examples List specific pnodeIn the following example, the EXEC pnode is displayed:LISTPN EXEC

Sample listThe following is an example of the display produced by the LISTPN command:LISTPN -P-NODE - DISTRIB DEFINED AT 10.23 ON WED 28JAN04 BY CYBBS01HISTFILE - NONE, OWNER(CYBBS01), SEQUENCE(140)P-NODE - EXEC DEFINED AT 15.47 ON MON 24NOV03 BY CYBBP01HISTFILE - NONE, OWNER(CYBBP01), SEQUENCE(120)P-NODE - INPUT DEFINED AT 15.47 ON MON 24NOV03 BY CYBBP01HISTFILE - NONE, OWNER(CYBBP01), SEQUENCE(110)P-NODE - OUTPUT DEFINED AT 15.47 ON MON 24NOV03 BY CYBBP01HISTFILE - NONE, OWNER(CYBBP01), SEQUENCE(130)

Operand Descriptionname Indicates the name of the pnode entry to be displayed. Wildcard

characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

LISTQ Command: List Queue Data Set

778

LISTQ Command: List Queue Data Set

The LISTQ command is used to display information about the current status of the QUEUE data set.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTQ command.

SyntaxLISTQ

Usage notesThe information displayed by this command includes the time the QUEUE data set was formatted, the amount of space allocated and the amount of space used, and the MINHOLD, MINDORM, and MAXDORM values.

Related informationFor information on defining ESP data sets see, the ESP Workload Manager Installation and Configuration Guide.

Example Sample listIn the following example, the current status of the QUEUE data set is displayed:OPER LISTQQUEUE DATASET CYB2.ESP510.QUEUEFORMATTED AT 12.33.25 ON MONDAY NOVEMBER 17TH, 1997MAXIMUM SIZE 737280 BYTESHIGHEST ADDRESS USED 72160, 6112 BYTES IMBEDDED FREE SPACEMINHOLD 100, MINDORM 100, MAXDORM 100

779

LISTROOT Command: Save List of Waiting Jobs for Rerun into Data Set

The LISTROOT command saves to a data set a list of waiting jobs (jobs that have not been readied or completed yet) in an Application. At any time after all the waiting jobs have run, you can rerun them by issuing the RERUNM command and specifying the data set in the RDSNAME operand. For example, you may want to issue the LISTROOT command when you backup a database. If you later restore the database from the backup, you can issue the RERUNM command to rerun all the jobs that ran after the backup.

TypeGeneral command.

SyntaxLISTROOT APPLICATION(appl_name[.gen]) RDSNAME(dsname) [EXPAND]

Usage notesYou can save the waiting root jobs or the waiting root jobs and the “tree” of waiting jobs dependent on each waiting root job. For example, assume that all the jobs in the following schedule are waiting to run.

Operand Descriptionappl_name Application name.gen Generation number of the Application.

• Positive–Absolute generation number• 0–Current generation (default)• Negative–Relative to the current generation

RDSNAME(dsname) Name of the data set where the list of jobs is written.EXPAND Requests that all jobs be listed individually rather than implied by their

root jobs. For information on root jobs, see “RERUNM Command: Rerun Multiple Jobs” on page 1051.

LISTROOT Command: Save List of Waiting Jobs for Rerun into Data Set

780

If you issue LISTROOT with the EXPAND operand, all the waiting jobs in the preceding schedule are stored. If a job has already run, it is not stored. So, if JOBH was released manually and ran, it is not stored by LISTROOT.If you issue LISTROOT without the EXPAND operand, only the waiting root jobs are stored. In the case of the preceding schedule, “JOBA+” and “JOBF+” are stored.Note: If you run LISTROOT without the EXPAND operand, the RERUNM

command will rerun all jobs dependent on the root jobs listed in the data set created by LISTROOT. This may cause a problem if a job that is dependent on the root job had already run when the list of waiting jobs was created. You may not want that job to be rerun.

Related informationFor information on rerunning multiple jobs, see the RERUNM command.For information on Encore, see the ESP Encore User’s Guide.

Example In the following example, the first command saves the list of waiting jobs in generation 3 of the PAYROLL Application. The list of waiting jobs is saved in data set PA.RERUN.JOBLST01.LISTROOT APPLICATION(PAYROLL.3) RDSNAME(PA.RERUN.JOBLST01)

At some point in time after the waiting jobs have run, the RERUNM command is issued to rerun the jobs listed in PA.RERUN.JOBLST01.RERUNM APPLICATION(PAYROLL.3) RDSNAME(PA.RERUN.JOBLST01)

JOBA

JOBD

JOBE

JOBB

JOBC

JOBF

JOBH

JOBG

Root Job Root Job

781

LISTSADL Command: List SADLINKs

The LISTSADL command is used to display the current SADLINKs defined.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTSADL command.

SyntaxLISTSADL

Usage notesThe SADLINK command identifies an external SADGEN file with an internal identifier. Each time ESP initializes, or in response to a SADLOAD command, the contents of the SADGEN file are read and necessary information retained in a main-storage resident look-up table. To request that the look-up table be used to resolve external linkages, specify the correct SADLINK identifier on the RESOLVE statement in an ESP Procedure.

Related informationFor information on scheduled activity reporting, see the ESP Workload Manager User’s Guide.For information on generating a data set that is used in the creation of scheduled activity reports, see the SADGEN command.For information on identifying an external scheduled activity data set, see the SADLINK command.For information on refreshing an in-core table containing scheduled activity data set, see the SADLOAD command.For information on resolving dependencies through a scheduled activity data set, see the RESOLVE command.

Example List SADLINKsIn the following example, all currently defined SADLINKs are displayed:LISTSADL

LISTSCH Command: List Schedules

782

LISTSCH Command: List Schedules

The LISTSCH command is used to display the Event names and times of the current schedule cycle (normally 24 hours). These elements include the names and execution times of all the Events in the schedule, and the overdue, held, or deferred queues.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTSCH command.

Syntax{LISTSCH|LSCH} [FROM(starttime)] [TO(endtime)] [LEVEL(levelname)] [MAXENTRY{(200)|(count)}] [DEFERRED(eventdsid)] [HELD(class)] [OVERDUE] [SUSPENDED] [DATE] [FLUSHED] [NONSCHED]

Operand Description

starttime Indicates a valid start time. This may include a date. If the specification includes blanks or commas, place it within quotes.

endtime Indicates the end time and can include a date. If the specification includes blanks or commas, place it within quotes.

levelname Indicates a generic Event name specification. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

count Indicates a number from 1 to 1000. It specifies the maximum number of entries to be displayed. This prevents a WTO buffer shortage when output is directed to a console.

eventdsid Indicates the identifier of an Event data set whose deferred queue is to be displayed.

class Indicates the name of a held class.

OVERDUE Indicates entries from the OVERDUE queue are displayed.

SUSPENDED Indicates all suspended Events are displayed.

783

Usage notesThe MAXENTRY keyword is only available with the console version of the LISTSCH command.Display portions of the schedule by using the FROM and TO keywords. The display can also be restricted to various Event names.The LISTSCH command does not display the names or submission times for individual jobs within Events. To display the schedule for jobs refer to scheduled activity reporting.The LISTSCH command displays all Events that contain scheduling criteria, whether or not they are scheduled. This does not include the SCHEDULE statement. For example, if you want to display Events that are triggered by data set activity, you can use the EXPECT command when you define these Events. Use the NONSCHED keyword on LISTSCH to include expected Events in the display.The LISTSCH command displays Events from the current time up to the next scheduled scan, which is normally at 6 am. Events triggered with the ADD option are displayed on a LISTSCH command, even if the trigger time is past the next scan time.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.For information on defining schedule criteria for an Event, see the SCHEDULE command.For information on telling ESP when an Event is expected to execute, see the EXPECT command.For information on displaying the next scheduled executions of an Event, see the NEXT command.

DATE Indicates the date is included in the display as well as the time.

FLUSHED Indicates entries that have been flushed from deferred queue should be displayed. This Operand is only valid with the DEFERRED keyword. Flushed entries remain in the deferred queue only while the system is quiesced. As soon as the system is restarted, the entries are removed from the queue.

NONSCHED Indicates all Events that contain scheduling criteria will be displayed, whether or not they are scheduled. This does not include the SCHEDULE statement but does include the EXPECT, HOLD, RELEASE, SUSPEND, and RESUME statements.

Operand Description

LISTSCH Command: List Schedules

784

Examples Sample listIn the following example, all entries on the current schedule are displayed:LISTSCH15.00.00 PROD.PAYROLL 15.00.00 PROD.BILLING15.30.00 PROD.CLAIMS 16.00.00 USER01.TEST17.45.00 CYBER.LIFE70 19.15.00 TEST.INVENTORY 20.00.00 CYBBS01.FRED 06.00.00 SCAN EVENT1

List dateIn the following example, all Events are displayed, and the date is included in the display. This is useful when you trigger Events for a time/date beyond the next scan time.LISTSCH DATE

List specific eventsIn the following example, Event names beginning with PAY in group GROUP1 are displayed:LISTSCH LEVEL(GROUP1.PAY-)

List held eventsIn the following example, Events that are held in class ABC are displayed:LISTSCH HELD(ABC)

List deferred eventsIn the following example, the names of Events deferred by the unavailability of the Eventset with ID EVENT1 are displayed:LISTSCH DEFERRED(EVENT1)

List events in time rangeIn the following example, all Events with scheduling criteria, that belong to the PROD group, with times between 8 pm and 11 pm, are displayed:LISTSCH LEVEL(PROD) FROM(8PM) TO(11PM) NONSCHED

785

LISTSIG Command: List Signals

The LISTSIG command is used to display all generations of a signal.

TypeGeneral command.

Syntax{LISTSIG|LSIG} signalname [ALL] [PENDING]

Usage notesSignals cause an ESP Event to wait for a condition in addition to its schedule criteria before it executes. A signal may represent a manual task, such as the arrival of an input tape, or an automated task, such as the completion of a job. Signals are only available at the Event level. If you are using an Application and need to set up conditions at the job level for jobs in the Application, the best method is through tasks.

Related informationFor information on signals, see the ESP Workload Manager Advanced User’s Guide.For information on using tasks to set up conditions at the job level, see the ESP Workload Manager User’s Guide.For information on defining and deleting signals, see the DEFSIG and DELSIG commands.For information on instructing an Event to wait for the posting of a signal, see the SIGWAIT command.For information on posting a signal, see the SIGPOST command.

Operand Descriptionsignalname Indicates the name of the signal. If a prefix is not specified, the

current group or user is used. Wildcard characters asterisk and hyphen (see “Overview” at the begining of this book) can be used to perform masking.

ALL Displays all information about signals. If ALL is not specified and the signal name contains an asterisk or a hyphen, only summary information is displayed.

PENDING Display only signals with pending Events.

LISTSIG Command: List Signals

786

For information on resetting the generation number of a signal, see the SIGCYCLE command.For information on changing the generation number of a signal, see the ALTSIG command.

Examples List specific signalIn the following example, information about all generations of CYBER.SIGNAL99 is displayed:LSIG CYBER.SIGNAL99 ALL

List specific signalsIn the following example, summary information for all signals starting with the prefix CYBER is displayed:LSIG CYBER-

List pending signalsIn the following example, summary information for all signals starting with CYBER that have pending Events is displayed:LSIG CYBER.- PENDING

787

LISTSPEC Command: List Special Days

The LISTSPEC command is used to list special days and periods.

TypeGeneral command.

Syntax{LISTSPEC|LS} name [GROUP(groupname)] [CALENDAR(calname)] [FROM(fromdate)] [TO(todate)] [COMPRESS] [RETAIN]

Usage notesIf no group name or calendar name is specified, the most recently retrieved set of calendars is displayed. If no calendars were retrieved in the current command session, the default calendars for the current group are displayed.

Operand Description

name Indicates a full or generic name of a special day/period.Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. If this operand is omitted, all special days/periods are displayed. Code a hyphen if you are using any other operands and want all special days/periods displayed.

groupname Indicates special days/periods from the default calendars of the specified group are displayed.

calname Indicates the name of the calendar to search. This operand is mutually exclusive with the GROUP operand.

fromdate Indicates a start date for the special days displayed. Only special days/periods that fall on or after this date are displayed.

todate Indicates an ending date for the special days/periods displayed. Only special days/periods on or before this date are displayed.

COMPRESS Indicates a compact display is used. Several date and time entries for each special day are placed on a display line rather than the usual one entry per line. The number of entries per line depends on the terminal screen width, or the output data set logical record length

RETAIN Indicates the display include the length of time the special day/period is retained (if retained).

LISTSPEC Command: List Special Days

788

A start and/or end date can be specified to restrict the displayed special days/periods to a specific time period. Special days/periods are displayed in time sequence order within each calendar.The display can be restricted to special days/periods containing a specified character string. The first operand specifies a special day/period name or generic name. If you want all special days/periods to be displayed but need to use another operand, specify a hyphen as the first operand.To specify a date, use any format that ESP recognizes. If the date contains any blanks or commas, enclose the string in quotes.

Related informationFor information on specifying special days or periods in schedule criteria, see the ESP Workload Manager User’s Guide.For information on defining and deleting special days or periods, see the DEFSPEC and DELSPEC commands.

Examples List all special daysIn the following example, all the currently defined special days and periods from the most recently retrieved set of calendars or default calendars are displayed:LISTSPEC or LS

List on specific calendarIn the example, all currently defined special days and periods on the PAYROLL calendar are displayed:LS - CALENDAR(PAYROLL)

List for a given yearIn the following example, all special days or periods in 2002 that begin with P and have Y in position three of the name are displayed. The calendars to be searched are the default calendars for the PAYROLL group.LISTSPEC P*Y- GR(PAYROLL) FROM('1JAN2002') - TO('31DEC2002')

789

Sample listIn the following example, special days and periods defined on the SYSTEM calendar are displayed:CALENDAR SYSTEM FISCAL_YEAR_END 00.00 ON WEDNESDAY SEPTEMBER 30TH, 1998 ---- 1 DATE LISTED ---- INVENTORY_DAY 00.00 ON FRIDAY FEBRUARY 6TH, 1998 00.00 ON FRIDAY MARCH 6TH, 1998 00.00 ON TUESDAY APRIL 7TH, 1998 ---- 3 DATES LISTED ---- PAYDAY 00.00 ON FRIDAY JANUARY 30TH, 1998 00.00 ON FRIDAY FEBRUARY 20TH, 1998 00.00 ON FRIDAY FEBRUARY 27TH, 1998 ---- 3 DATES LISTED ---- ---- 3 SPECIAL DAYS DISPLAYED ----

LISTSYML Command: List Symbol Libraries

790

LISTSYML Command: List Symbol Libraries

The LISTSYML command is used to display information on the symbol libraries to which you have access.

TypeGeneral command.

Syntax{LISTSYML|LSL} symlib

Usage notesThe information displayed includes the names of the data sets comprising the symbol library set and user IDs or user ID masks with permitted read access to the symbols.

Related informationFor information on setting symbol libraries, see the ESP Workload Manager User’s Guide.For information on invoking user symbolic variables, see the ESP Workload Manager Advanced User’s Guide.For information on defining and deleting a symbol library, see the DEFSYML and DELSYML commands.

Examples List symbol libraryIn the following example, the attributes of the SYM1 symbol library are displayed:LISTSYML SYM1

List all symbol librariesIn the following example, the attributes of all symbol libraries to which you have access are displayed:LSL -

Operand Description

symlib Indicates the name of a symbol library set defined using the DEFSYML command. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

791

Sample listIn the following example, the attributes of the PAYSYM symbol library are displayed:SYMLIB PAYSYM DEFINED BY USER01 AT 15.17 ON WEDNESDAY JANUARY 28TH, 2002DATASETS: 'CYBER.SYMBOLS.CNTL(DATES)'USERS: USER01

LISTTRAK Command: List Tracking Files

792

LISTTRAK Command: List Tracking Files

The LISTTRAK command is used to display information about the current status of the job tracking file

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTTRAK command.

SyntaxLISTTRAK

Usage notesThe information displayed by this command includes when the data set was formatted and the current allocation status including the number of free slots.

Example Sample listIn the following example, information about the current status of the job tracking file is displayed:OPER LISTTRAKTRAKFILE CYB2.ESP510.TRAKFILEFORMATTED AT 17.33.37 ON MONDAY NOVEMBER 17TH, 19979896 SLOTS TOTAL, 8127 AVAILABLE, NEXT IS 6979

793

LISTUSER Command: List User Definitions

The LISTUSER command is used to display user definitions. The information displayed includes authority attributes, default calendars, Eventset, and Histfile access, and the names of the groups to which the user is connected.Note: LISTUSER is applicable only when using ESP Workload Manager internal

security. Cybermation recommends that you use SAF security instead of ESP Workload Manager internal security. If you need to use ESP Workload Manager Internal security, consult the older ESP Workload Manager Administrator’s Guide version 5.3.

TypeGeneral command.

Syntax{LISTUSER|LU} userid

Related informationFor information on calendars, see the CALENDAR command.For information on defining and deleting users, see the DEFUSER and DELUSER commands.For information on changing a user’s definition, see the ALTUSER command.

Operand Descriptionuserid Indicates the name of the user definition to be displayed. Wildcard

characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. If the user ID is not specified, your user ID definition is displayed.

LISTUSER Command: List User Definitions

794

Examples List all usersIn the following example, all users are displayed:LU -

List your user definitionIn the following example, your user definition is displayed:LU

List specific userIn the following example, USER1 is displayed:LU USER1

List multiple usersIn the following example, all users whose IDs begin with PROD are displayed:LISTUSER PROD-

795

LISTXMEZ Command: List Cross-Memory Elements

The LISTXMEZ command is used to display cross memory tracking elements. A cross-memory element (XME) is used to pass job and data set information between address spaces and ESP systems.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LISTXMEZ command.

SyntaxLISTXMEZ

Example Sample listIn the following example, the cross-memory tracking elements are displayed:OPER LISTXMEZCKPT SPACE USED BY JOB TRACKING XMES 824MAX ALLOWED: NO LIMIT0 XMES FOR A TOTAL OF 0(X'00000000') BYTESQUEUE SPACE USED BY JOB TRACKING XMES 0MAX ALLOWED: 128000 (DEFAULT)0 XMES FOR A TOTAL OF 0(X'00000000') BYTES

LJ Command: List Jobs

796

LJ Command: List Jobs

The LJ command is used to display the status of a job being tracked by ESP.

TypeGeneral command.

SyntaxLJ jobname [ANCESTOR(genno)] [ALL] [STEPS] [SUBMIT] [PNODE] [STATUS] [DUEOUT] [INFODATA] [EXTENDED|X]

Operand Description

jobname Indicates the name or JES job number of the job to be displayed. If the ID is all numeric, it is assumed to be a job number, otherwise it is treated as a jobname. A job name and job number can be specified together, with the job number enclosed in parentheses, immediately following the job name.

genno Indicates the ancestor generation number, with zero the most recent job, 1 or -1 the previous job and so on. This operand is ignored whenever a job number is specified. This operand defaults to zero if a job name is used and no generation number is specified.

ALL Indicates all the information for the job is displayed. This is the same as specifying STEPS, SUBMIT, PNODE, and INFODATA. This is the default.

STEPS Indicates step statistics are to be displayed for the job.

SUBMIT Indicates submission information, including JCL source data set, Event name, data set trigger name if any, etc., is displayed. This information is available only if ESP submitted the job.

PNODE Displays the PNODEs for each job.

STATUS Displays the current status of the job.

DUEOUT Displays pnode due out times for the job.

INFODATA Displays the Information Management record number associated with this job if one was generated using the Information Management interface.

797

Usage notesESP can track the progress of all or selected jobs, even those it did not schedule. ESP provides real time information for each job step, including such information as stepname, completion code, CPU time, elapsed time, and number of tape mounts. You can request ESP to track jobs, started tasks (STCs), TSO users (TSUs), and system messages. ESP must be set up to track jobs in an ESP Application.The LJ command displays information from ESP’s tracking file (TRAKFILE). The amount of data stored on this file depends on its size. ESP re-uses slots in the TRAKFILE as required.

Related informationFor information on displaying job level information from the CSF, see the ESP Workload Manager User’s Guide.For information on displaying tracked jobs, see the LTJ command.For information on job tracking, see the ESP Workload Manager Installation and Configuration Guide.

Examples List specific jobIn the following example, the status of PAYJOB1 is displayed:LJ PAYJOB1 STATUS

List job by JES numberIn the following example, a job whose JES job number is 1234 is displayed:LJ 1234

List job by Information Management recordThe following LJ command displays a jobs Information Management record.In the following example, PAYJOB2’s Information Management record is displayed:LJ PAYJOB2 INFODATA

List step-level statisticsThe following LJ command displays step-level statistics.In the following example, step level statistics are displayed for PAYJOB2:LJ PAYJOB2 STEPS

EXTENDED or X Displays more detailed date and time information.Operand Description

LJ Command: List Jobs

798

List second ancestorIn the following example, the second ancestor or -2 generation of PAYJOB3 is displayed:LJ PAYJOB3 ALL AN(2)

Sample listingIn the following example, detailed date and time information is displayed for PAYJOB4 using the EXTENDED or X operand of the LJ command.LJ PAYJOB4 XPAYJOB4 J08324, IN OUTPUT QUEUE SINCE 16.01.03 28JAN, CC 0SUBMITTED BY ESP AT 16.01.03 ON WED 28JAN, EVENT CYBER.PAYROLLJCL FROM CYBER.JCL.CNTL(PAYJOB4)PROGRAMMER USR01, ACCOUNT CYB3000JOB IS IN APPL PAYROLL

STEPNAME-PROCSTEP-PROGNAME--EXCP-#T-S-N-CPU-TIME-SUNITS-REGION—CMPCS1 IEFBR14 0 0 0 0 0:00.02 168 4K 0

PNODE----OUT------DATE--QTIME-POST_BY--SYS-INPUT 16.01.02 28JAN 0 SYSAEXEC 16.01.03 28JAN 1 SYSTEM SYSAOUTPUT * 10M54

799

LMOD Command: Display Module Level

The LMOD command is usually issued at the request of Cybermation Product Support Services, to determine at what level the module is at (PTF level).

TypeGeneral command.

SyntaxLMOD modulename

Usage notesIf you precede the LMOD command with OPER, ESP Workload Manager looks in the subsystem address. If you do not precede the LMOD command with OPER, ESP Workload Manager looks in the client space.

ExamplesThe following two examples show the LMOD command and ESP Workload Manager response:LMOD CYBES011Module CYBES011 found at address 09EA8B70 in load module ESPLoad module ESP is at address 09E62000, entry point is 89E62000Module eyecatcher: CYBES011 11.37 14JAN02 -SU00322Load module found in STEPLIB CYB2.SYSPLX10.SSCPLINK

OPER LMOD CYBES011Module CYBES011 found at address 09E93380 in load module - CYBJS000Load module CYBJS000 is at address 09E00000, entry point is - 89E00000Module eyecatcher: CYBES011 11.37 14JAN02 -SU00322Load module found in STEPLIB CYB2.SYSPLX10.SSCPLINK

Operand Descriptionmodulename Specifies the name of the module you want to know about.

LOAD Command: Load Commands

800

LOAD Command: Load Commands

The LOAD command is used to load a series of ESP commands for execution. Enter your commands into a PDS or sequential data set and issue the LOAD command from Page mode to process these ESP commands. Note: The LOAD command cannot be used in ESP’s initialization parameters.

TypeGeneral command.

SyntaxLOAD 'dsname[(member)]'

Usage notesOne use of the LOAD command is to load Event definitions from a data set. Several Event definitions can be included in one data set or member.The LOAD command is useful when you have a number of repetitious commands to execute (for example, setting up holidays, defining users, reporting.)

Examples SampleThe following is an example of a PDS member - CYBER.ESP.DATA(CMDS). which contains ESP commands:SMFSTATSLDSNLIST LEVEL(PROD)

To process the above ESP commands, issue the LOAD command from Page mode as follows:LOAD 'CYBER.ESP.DATA(CMDS)'

Operand Descriptiondsname Indicates a valid data set name. The current user prefix is added if the

data set name is not enclosed within quotes. A member name can be included within the data set specification. The input data set can be sequential, partitioned or VSAM ESDS. All record formats are supported.

801

The following is an example of the display produced by issuing the above LOAD command:SMFSTATSESP SUBSYSTEM INITIALIZED AT 10.11.59 ON THURSDAY DECEMBER 18TH, 20031490750 ENTRIES TO SMFWTM, 583358 BY BRANCH ENTRY AND 907392 BY SVC168304 ENTRIES TO ESP PHASE 29562 JOB STARTS, 304 STC STARTS, 933 TSU STARTS, 20969 STEP ENDS

LDSNCHECKPOINT: CYB2.ESP510.CKPT, ALT NONE USERDEF: CYB2.ESP510.USERDEF, BKUP NONE INDEX: CYB2.ESP510.INDEX, BKUP NONE JOBINDEX: CYB2.ESP510.JOBINDEX, BKUP CYB2.ESP510.BKUP.JOBINDEX QUEUE: CYB2.ESP510.QUEUE, ALT NONE TRAKFILE: CYB2.ESP510.TRAKFILE EVENTSET: CYB2.ESP510.EVENT1 HISTFILE: CYB2.ESP510.HISTFILE APPLFILE: CYB2.ESP510.APPLFILE JTDT: CYB2.ESP510.PARMLIB(JOBDEF1) UPDT: CYB2.ESP510.PARMLIB(PROFILE)

LIST LEVEL(PROD)PROD.PAYROLL NEXT DUE AT 20.00.00 ON THU JAN 29TH,2004PROD.BILLING NEXT DUE AT 09.00.00 ON THU JAN 29TH,2004

LOADAGDF Command: Load Agent Definition

802

LOADAGDF Command: Load Agent Definition

The LOADAGDF command is used to load the agent definition.

TypeOper command.

AuthorityYou require OPER authority to issue the LOADAGDF command.

SyntaxLOADAGDF 'dsname[(member)]' [TEST]

Usage notesThe LOADAGDF command is used in the ESP Workload Manager initialization parameters to load the agent definition each time it initializes.You can issue the LOADAGDF command from page mode to dynamically pick up changes made to the agent definition member.

Example The following command loads the agent definition file from page mode: OPER LOADAGDF 'CYBER.ESPPARM(AGENTDEF)'

Operand Descriptiondsname Specifies a sequential data set or a member of a partitioned data set. Must have

LRECL=80.TEST Indicates that all syntax and logical checks are to be performed, but that the table is

not to be loaded.

803

LOADJTDT Command: Load Job Tracking Definition Table

The LOADJTDT command is used to load the job tracking definition table into the system. ESP uses this table to determine what it needs to track.

TypeOper command.

AuthorityYou require OPER authority to issue the LOADJTDT command.

SyntaxLOADJTDT 'dsname[(member)]'

Usage notesNormally the job tracking table is loaded when ESP initializes.You can replace the currently active job tracking definition table with a new table at any time by reissuing the LOADJTDT command with the data set name that contains the new table.If more than one copy of ESP uses the same job tracking definition table, you need to issue the LOADJTDT command for each ESP system.The job tracking definition table is used for any job that ESP encounters and overrides any other tracking definitions.The job tracking definition table overrides any other tracking definitions in the system, such as those defined with the DEFTJ command.

Related informationFor information on job tracking definition tables, see the ESP Workload Manager Installation and Configuration Guide.For information on tracking definition entries in a job tracking definition table, see the TRACKDEF statement.For information on defining wildcard characters used in a job tracking definition table, see the WILDCARD statement.

Operand Descriptiondsname Name of sequential data set or PDS member containing the job

tracking definition table.

LOADJTDT Command: Load Job Tracking Definition Table

804

Example Load tableIn the following example, JOBDEF1 is loaded from CYBER.PARMLIB.OPER LOADJTDT 'CYBER.PARMLIB(JOBDEF1)'

805

LOADNL Command: Load MAILLIST Data Set

The LOADNL initialization parameter loads the MAILLIST data set.

TypeOper command.

Where definedMaster and proxy.

SyntaxLOADNL [data_set_name(member)] [TEST]

Operand Descriptiondata_set_name(member)

Specifies the name of the MAILLIST data set. If you want to reload the data set that is already loaded, you do not need to specify the data set name. If the data set is sequential, omit the member name.

TEST Verifies that the data set is valid but does not load it. If you code TEST, you must specify the data-set name.

LOADSCHF Command: Load Schedule File

806

LOADSCHF Command: Load Schedule File

The LOADSCHF command is used to copy schedule information from a sequential workfile to a VSAM file that can be viewed from the CSF.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LOADSCHF command.

SyntaxLOADSCHF

Usage notesThe LOADSCHF command allows you to see future, scheduled workload from the CSF. This is not a common practice.The LOADSCHF command loads the schedule workfile into core and copies it into the VSAM schedule file, both of which are identified by the SCHDFILE initialization parameter. The schedule workfile must be a scheduled activity data set. Information contained in the workfile is merged with old information. The file must be seeded with Events that are scheduled to execute by the SADGEN command, in a batch job, prior to loading.

Related informationFor information on the CSF, see the ESP Workload Manager User’s Guide.For information on purging information from the SCHDFILE, see the PURGSCHF command.For information on generating a scheduled activity data set, see the SADGEN command.

Example Load scheduleThe following LOADSCHF command loads schedule information:In the following example, schedule information is loaded from a sequential workfile to a VSAM file so that it can be viewed from the CSF.OPER LOADSCHF

807

LOADUPDT Command: Load User Profile Definition Table

The LOADUPDT command is used to load the User Profile Definition Table from a data set. The User Profile Definition Table contains one or more PROFILE statements. User Profile Definition Tables are required only if the SAF interface is being used.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LOADUPDT command.

SyntaxLOADUPDT 'dsname[(member)]'

Usage notesYou can issue the command in the ESP initialization data set, or once ESP is active you can issue the command from your console. Once you have loaded the table, ESP refers to the table, not to the data set. ESP always refers to the currently loaded table.The User Profile Definition Tables needs to be loaded after making changes.If you are running more than one ESP system, you need to load the User Profile Definition Table on each system.

Related informationFor information on identifying the Event prefix and the EVENTSET that ESP uses to store the Event, see the PROFILE statement.For information on using SAF, see the ESP Workload Manager Security Guide.

Example Load tableIn the following example, PROFILE is loaded from CYBER.PARMLIB.LOADUPDT 'CYBER.PARMLIB(PROFILE)'

Operand Descriptiondsname Indicates the fully qualified data set name, and can include a member

name. The data set can be any fixed or variable length file with a record length of 80 or greater.

LOCALFILENAME Statement: Specify Local Filenames Within FTP_JOB

808

LOCALFILENAME Statement: Specify Local Filenames Within FTP_JOB

The LOCALFILENAME statement specifies the local files to be transferred when using the FTP_JOB statement.

ApplicabilityESP System Agents, Release 6, used within an FTP_JOB workload object. For more information, see “FTP_JOB Statement: Identify the Name of FTP Jobs” on page 623.

SyntaxLOCALFILENAME filename

Usage notesLOCALFILENAME is a required statement within the FTP_JOB workload object.LOCALNAME is the short form of LOCALFILENAME.

ExamplesExample 1In this example, a single file is downloaded.FTP_JOB FTPTEST5.DOWNLOAD AGENT R6AGENT USER test SERVERADDR hprsupp SERVERPORT 21 TRANSFERDIRECTION D FTPFORMAT A REMOTENAME /u1/qatest/ftpdata/textfile LOCALNAME '/export/home/qatest/ftpdata/Folder/textfile' RUN DAILYENDJOB

Operand Descriptionfilename Use the full path statement. The format is case sensitive, any

character, up to 256 characters in length.

809

Example 2 In this example, multiple local files are downloaded. Note that the number of entries listed in the statements REMOTEFILENAME and LOCALFILENAME must match. Single quotes enclose both lists to accommodate the line continuation character (+).FTP_JOB FTPT14.DOWNLOADAGENT R6AGENTAFTER CHECK.PART1USER testSERVERADDR hprsuppSERVERPORT 21TRANSFERDIRECTION DFTPFORMAT AREMOTENAME '/u1/qatest/scripts/echo;+/u1/qatest/scripts/echo1;+/u1/qatest/scripts/echo2'

LOCALNAME '/export/home/qatest/ftpdata/echo;+/export/home⁄qatest/ftpdata/echo_1;+/export/home/qatest/ftpdata/echo_2'

RUN DAILYENDJOB

Example 3If a wildcard is used in a local file name for upload, the remote file name (the source) must refer to a directory. In this example, the remote file name is specified as the directory /tmp.FTP_JOB FTPT17.UPLOADAGENT R6AGENTAFTER CHECK.PART1USER testSERVERADDR hprsuppSERVERPORT 21TRANSFER UFTPFORMAT AREMOTENAME /tmpLOCALFILENAME /export/home/qatest/ftpdata/text*RUN DAILYRELEASE FTPT18.UPLOAD

ENDJOB

Note: For Windows examples, substitute a Windows path in the LOCALFILENAME statement.

LOCATION Statement: Specify the Service Provider URL (J2EE)

810

LOCATION Statement: Specify the Service Provider URL (J2EE)

The LOCATION statement specifies the URL of the Service Provider using dotted decimal notation or DNS name.The Service Provider implements a context or initial context. This context can be plugged in dynamically to the JNDI architecture used by the JNDI client.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within the EJB_JOB, JMSP_JOB, and JMSS_JOB workload objects

SyntaxLOCATION location

Usage notesLOCATION is a mandatory statement within the EJB_JOB, JMSP_JOB, and JMSS_JOB workload objects.

Operand Descriptionlocation The URL of the Service Provider using dotted decimal notation

or DNS name. location is case sensitive and can be up to 1024 characters.

WebLogicThe Service Provider URL has the following form:t3://<IP address of the WebLogic Application Server>:<ORB Port, 7001 by default>

WebSphereThe Service Provider URL has the following form:iiop://<IP address of the WebSphere Application Server>:<ORB Port, 2809 by default>

811

ExamplesWebLogicIn this example, the CYBJK.SB job uses t3://100.10.31.66:7001 as the Service Provider URL. APPL TESTSBEJB_JOB CYBJK.SB HOLD RUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(java.lang.String) VALUE(A23)ENDJOB

WebSphereIn this example, the CYBJK.SB job uses iiop://100.10.31.66:2809 as the Service Provider URL. APPL TESTSBEJB_JOB CYBJK.SB HOLD RUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT + com.ibm.websphere.naming.WsnInitialContextFactory JNDIUSER cyberuser LOCATION iiop://100.10.31.66:2809 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(java.lang.String) VALUE(A23)ENDJOB

LOGPRT Command: Display Event Log

812

LOGPRT Command: Display Event Log

The LOGPRT command is used to display Event log data collected in the trace data sets during a specified time period.

TypeGeneral command.

AuthorityYou require special authority to issue the LOGPRT command in a non-SAF environment.

SyntaxLOGPRT DSN(dsname[,dsname]...) [FROM(schedule)]

Usage notesThis command is not normally used, as the same information is stored in ESP’s audit log. Immediately before using the LOGPRT command, issue the TRACE WRITE, TRACE CLOSE, and TRACE OPEN operator commands to ensure that the LOGPRT command accesses all current trace data. Trace data set information is displayed via the TRACE STATUS operator command.

Related informationFor information on printing a trace data set, see the TRACEPRT command.

Example Display time rangeIn the following example, information logged between 6 pm the previous day and 5 am this morning in CYB.ESP.TRACE1 data set is displayed. LOGPRT DSN('CYB.ESP.TRACE1') FROM('6PM YESTERDAY -UNTIL 5AM TODAY')

Operand Descriptiondsname Indicates the names of the trace data sets to access for Event log

information. Separate data set names with a comma.

schedule Indicates schedule criteria. The keyword UNTIL can be used to restrict the time range. If UNTIL is not used, the current time is used as the end time.

813

LSAR Command: List Scheduled Activity Report

The LSAR command is used to extract data from a scheduled activity data set to produce a standard scheduled activity report.

TypeGeneral command.

SyntaxLSAR DSN(dsname) [JOB(jobname[,jobname]...)] [GROUP(groupname)] [NET(netid)] [APPL(application)] [JCL(jcldsn)] [FROM(schedule)] [TO(schedule)] [TIMESEQ] [STATUS] [TAPEPULL(tapeds)] [PROJECTED]

Operand Description

dsname Indicates the name of the scheduled activity data set that contains scheduled activity information, enclosed in quotes.

Note: The scheduled activity data set is generated using the SADGEN command.

jobname Indicates the name of the jobs for which you want to display a scheduled activity report.Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. If this operand is omitted, then data on all scheduled jobs is generated.

groupname Indicates an ESP group name prefix for which you want to generate a scheduled activity report. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

netid Indicates the identifier for an ESP/DJC or JES3 job network. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

application Indicates the name of an Application for which you want to display a scheduled activity report. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

LSAR Command: List Scheduled Activity Report

814

Usage notesSince the LSAR command uses information from a scheduled activity data set, you can only display information that was written to that data set using the SADGEN command.If you do not use the FROM keyword, the starting time for the scheduled activity report defaults to NOW. If you do not use either ENDING or UNTIL with the FROM keyword, and you do not specify TO, then the scheduled activity report contains all data stored in the scheduled activity data set as generated by the SADGEN command.You may only generate a scheduled activity report on a group to which you have access. If you want a report on all scheduled jobs, then you do not need to use any of these selection keywords. Use the STATUS keyword to obtain a scheduled versus actual report (for example, after the SADUPD command) or use the TAPEPULL keyword if you are using the tapepull facility.The DSN operand must be the first operand after the LSAR command.

jcldsn Indicates the name of a JCL data set. It cannot be enclosed in quotes. Only jobs whose JCL that resides in this data set are included in the scheduled activity report.

schedule Indicates a valid schedule statement. If the statement contains separators then it must be enclosed in quotes. The keywords ENDING or UNTIL can be used to restrict the time range selected.

TIMESEQ Indicates the display of scheduled activity should be sorted in ascending time sequence according to the schedule time for the job. If this keyword is omitted, the display is sorted in alphabetical sequence by jobname. If more than one occurrence of a job is scheduled, the jobnames are sorted by time sequence within a jobname category.

STATUS Indicates an updated status display is required instead of the regular schedule display. This gives the status of all the jobs in the schedule, as well as time and percentage of schedule still remaining. Actual start and end times, completion code and rerun indicators are also displayed. This can only be used after the SADUPD command has generated updated information.

tapeds Indicates the name of a preallocated PDS used to store tape data set information. A member is created for each job, which can then be used as input to the TMS or CA1, tapepull program. This operand is used in conjunction with the INPUTDS Application statement.

PROJECTED Creates a Projected vs. Actual report. This report shows projected start/end times based on MODEL processing and actual start/end times. Prior to running this report, a model must be run to update the projected times in the SADGEN data set, and the SADUPD command must be used to update the SADGEN data set with actual run information.

Operand Description

815

To produce scheduled activity reports online, use option S - Schedule Activity from the ESP Main Menu.

Related informationFor information on scheduled activity reporting, see the ESP Workload Manager User’s Guide.For information on modeling, see the ESP Workload Manager Advanced User’s Guide.For information on generating scheduled activity data set, see the SADGEN command.For information on updating a scheduled activity data set with actual information, see the SADUPD command.

Examples Sample JCLThe following is an example of JCL that could be used to produce a schedule activity report://jobname JOB …//STEP1 EXEC PGM=ESP,PARM='SUBSYS(E510)'//STEPLIB DD DSN=CYB2.ESP510Q.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*,DCB=LRECL=255//SYSIN DD *LSAR DSN('CYBER.SAD') /*

In the above example, the LSAR command is run in batch to produce a scheduled activity report. The DCB=LRECCL=255 is required to accommodate the width of the report including the Agent name.Note: Before running this job, ensure the scheduled activity data set contains

schedule activity information. To generate a scheduled activity data set, use the SADGEN command in batch only. You may combine the SADGEN and LSAR commands in the same job by running a step for each command.

12-hour periodIn the following example, a report is produced on activity scheduled in the 12-hour period starting at 8 pm tonight using the CYBER.SAD scheduled activity data set. The display is restricted to jobnames beginning with the characters PAY, and is presented in scheduled time sequence.LSAR DSN('CYBER.SAD') JOB(PAY-) - FROM('8PM TODAY UNTIL 8AM TOMORROW') TIMESEQ

LSAR Command: List Scheduled Activity Report

816

Now until 2:30In the following example, scheduled activity information on all jobs scheduled for submission from NOW until 2:30 am tomorrow morning is produced. The display is presented in jobname sequence, by default. Data is extracted from the CYBER.SAD data set.LSAR DSN('CYBER.SAD') TO('2:30AM TOMORROW')

Display StatusIn the following example, a status display of scheduled activity information as stored in the CYBER.SAD scheduled activity data set is produced. This data set must have been updated using the SADUPD command.LSAR DSN('CYBER.SAD') STATUS

Projected and actual start and end timesIn the following example, a Projected vs. Actual report is produced using information stored in the CYBER.SAD scheduled data set. LSAR DSN('CYBER.SAD') PROJECTED

Display status of applicationIn the following example, a status display on scheduled activity information for the PAYROLL Application is produced.

LSAR DSN('CYBER.SAD') APPL(PAYROLL)

Jobs in JCL data setIn the following example, a status display on scheduled activity information for jobs residing in PROD.BACKUP.JCL is produced.LSAR DSN('CYBER.SAD') JCL(PROD.BACKUP.JCL)

817

LSYS Command: List System

The LSYS command is used to display information about the current ESP system and can optionally provide information about other systems sharing the same QUEUE data set.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LSYS command.

SyntaxLSYS [sysid]

Usage notesThe type of information this command displays includes the CPU model, CPU serial, the system ID on which ESP is running, the checkpoint data set name, and the time of the last access to the QUEUE data set.

Related informationFor information on defining ESP data sets, see the ESP Workload Manager Installation and Configuration Guide.List current systemIn the following example, information about the current ESP system is displayed:OPER LSYSSYS: E510, SMF ID SYSA, CPU SERIAL 003655, MODEL 9672 LAST QUEUE ACCESS AT 21.42.32 ON THURSDAY JANUARY 29TH, 1998 CHECKPOINT DATASET CYB2.ESP510.CKPT

Operand Descriptionsysid Indicates the ESP system identifier you want to display information

about. The ESP system identifier is specified using the SYSID initialization parameter. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. If this field is omitted, information about the current system is displayed.

LSYS Command: List System

818

List specific systemIn the following example, information about the E510 system is displayedLSYS E510

List multiple systemsIn the following example, information about ESP systems with ESP in the first three positions is displayedLSYS ESP-

819

LSYSMSGS Command: List System Messages

The LSYSMSGS command displays information on all the system messages that are currently being intercepted by ESP.

TypeGeneral command.

AuthorityYou require OPER authority to issue the LSYSMSGS command.

SyntaxLSYSMSGS

Related informationFor information on intercepting system messages written to the system message data set, see the SYSMSGS command.For information on clearing system messages, see the CLRSYSMS command.

Example Sample listingIn the following example, information on all the system messages intercepted by ESP is displayed.OPER LSYSMSGS'IEF142I' ID(0001),NAME(PAYJOB1),EVENT(CYBER.PAYSTEP)'NOT CATLGD' ID(0002),COL(50:60),WTO,JOBNAME,CANCEL'IEF253I' ID(0010),DESC(2),NAME(A-),EVENT(CYBER.CAN), CANCEL

LTCELL Command: List Tracking Cells

820

LTCELL Command: List Tracking Cells

The LTCELL command is used to display tracking cell (TCELL) information, including the size and current usage of each cell.

TypeGeneral command.

SyntaxLTCELL

Usage notesTCELLs are required to pass job start, step end, job end, and job purge information to the ESP subsystem.

Related informationFor information on defining tracking storage cells, see the TCELL initialization parameter in the ESP Workload Manager Installation and Configuration Guide.

Example Sample listingIn the following example, tracking cell information is displayedCELSIZE-POOLSZ-MAXSIZE-CURRUSE-MAXUSED-GETMAINS-OVERFLOW

104 100 5100 0 53 0 0168 100 5100 0 28 0 0208 100 100 0 31 0 0

821

LTJ Command: List Tracked Jobs

The LTJ command is used to display the definition for a tracked job or group of tracked jobs as stored in the job index file.

TypeGeneral command.

SyntaxLTJ jobname [PREFIX] [OWNER(ownerid)] [MODEL(modelname)] [INDEX]

Usage notesThe LTJ command displays the tracking characteristics of a job, as defined in the job tracking definition table or through the DEFTJ command, rather than the tracking data on a particular submission of a job.

Operand Descriptionjobname Indicates the name of the job or jobs to be displayed. Wildcard

characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

PREFIX Indicates the prefix entries are displayed rather than job definitions. This is not applicable if you are using job tracking definition tables.

ownerid Displays only jobs with ownership strings equal to or superseding the specified ownership string. It consists of up to eight alphanumeric characters. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. This is not applicable if you are using job tracking definition tables.

modelname Displays only jobs having a matching track model name. The model name can consist of up to eight alphanumeric characters. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

INDEX Indicates a display of the index for the job is generated. The job number, submission date and time, current status and completion code of each indexed job is listed.

LTJ Command: List Tracked Jobs

822

Related informationFor information on displaying job level information from the CSF, see the ESP Workload Manager User’s Guide.For information on displaying the status of a job being tracked by ESP, see the LJ command.

Examples List job statusIn the following example, the tracking status of PAYJOB1 is displayed.LTJ PAYJOB1

Use specific tracking modelsIn the following example, all jobs using tracking models with names beginning with PROD are displayed.LTJ - MODEL(PROD-)

List job with indexIn the following example, the job index information for the job PAYJOB1 is displayed. The last n submissions of the job are displayed, where n is limited by the index count, which was already defined for the job.LTJ PAYJOB1 INDEX

Sample listIn the following example, a display of the index for PAYJOB1 is generated. LTJ PAYJOB1 INDEXJOB PAYJOB1, MODEL MODEL1, OWNER NONE, 10 JOBS INDEXED, 10 MAX J08720 ON RDR AT 20.00 THU 29JAN98, ENDED, CC 0, 0.0 MINS_EXEC, 0:00 CPU J08719 ON RDR AT 20.00 THU 29JAN98, ENDED, CC 0, 0.0 MINS_EXEC, 0:00 CPU J08717 ON RDR AT 20.00 THU 29JAN98, ENDED, CC 0, 0.0 MINS_EXEC, 0:00 CPU J08673 ON RDR AT 18.00 THU 29JAN98, ENDED, CC 0, 0.0 MINS_EXEC, 0:00 CPU J08630 ON RDR AT 16.01 THU 29JAN98, ENDED, CC S806, 0.0 MINS_EXEC, 0:00 CPU J08474 ON RDR AT 08.00 THU 29JAN98, ENDED, CC 0, 0.0 MINS_EXEC, 0:00 CPU J08414 ON RDR AT 20.00 WED 28JAN98, ENDED, CC 0, 0.0 MINS_EXEC, 0:00 CPU J08408 ON RDR AT 20.00 WED 28JAN98, ENDED, CC 0, 0.0 MINS_EXEC, 0:00 CPU J08365 ON RDR AT 18.00 WED 28JAN98, ENDED, CC 0, 0.0 MINS_EXEC, 0:00 CPU J08364 ON RDR AT 18.00 WED 28JAN98, ENDED, CC 0, 0.0 MINS_EXEC, 0:00 CPU

823

LTM Command: List Tracking Models

The LTM command is used to display the definition of one or more tracking models.

TypeGeneral command.

SyntaxLTM name

Usage notesThe DEFTM command allows you to centralize the definition of tracking characteristics that can be assigned to one job, or a group of jobs. Jobs are normally associated with a tracking model via a job tracking definition table.Any data defined through the DEFTM command is displayed. The field NOPRINTDATA of the display is reserved for future use.

Related informationFor information on defining/altering and deleting a tracking model, see the DEFTM and DELTM commands.For information on job tracking definition tables, see the ESP Workload Manager Installation and Configuration Guide.

Examples List specific modelIn the following example, the definition for the MODEL1 tracking model is displayed.LTM MODEL1

List all tracking modelsIn the following example, all tracking models are displayed.LTM -

Operand Descriptionname Indicates the name of the tracking model to be displayed.Wildcard

characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

LTZONE Command: List Time Zones

824

LTZONE Command: List Time Zones

The LTZONE command is used to display the current time zone settings.

TypeGeneral command.

SyntaxLTZONE

Related informationFor information on defining ESP data sets, see the ESP Workload Manager Installation and Configuration Guide.For information on defining time zones, see the TIMEZONE initialization parameter in the ESP Workload Manager Installation and Configuration Guide.

Example Sample listIn the following example, the current time zone settings are displayedLTZONECODE--ZONE------OFFSET ! CODE--ZONE------OFFSET ! CODE--ZONE------OFFSET

0 LOCAL 5.00W ! 1 UTC 0.00E ! 2 GMT 0.00E

3 Z 0.00E ! 5 EST 5.00W ! 6 CST 6.00W

7 MST 7.00W ! 8 PST 8.00W ! 9 AST 4.00W

10 EDT 4.00W ! 11 CDT 5.00W ! 12 MDT 6.00W

13 PDT 7.00W ! 14 ADT 3.00W ! 16 EASTERN 5.00W

17 CENTRAL 6.00W ! 18 MOUNTAIN 7.00W ! 19 PACIFIC 8.00W

20 ATLANTIC 4.00W ! 21 NFNDLAND 3.30W

825

MMAILBOX Command: List Mailboxes

The MAILBOX command lists how mailboxes are set.

TypeOper command

SyntaxMAILBOX box_name

Usage noteRefer to the MAILLIST data set section in the ESP Workload Manager Installation and Configuration Guide for information on the MAILLIST data set.

ExampleThe following is an example of output from the MAILBOX command:oper mailbox -PAY Message size limit 300 lines TSO user PAYXX01 sysid SYSA TSO user PAYXX04 sysid SYSA TSO user PAYXX09 sysid SYSC TSO user PAYXX16 sysid SYSD TSO user PAYXX18 sysid SYSB e-mail payroll@user.comPAY_A Message size limit 300 lines TSO user PAYXX06 sysid SYSA TSO user PAYXX11 sysid SYSC TSO user PAYXX16 sysid SYSD e-mail payroll@user.comPAY_NULL Message size limit 300 lines

Operand Descriptionbox_name Specifies the name of the mailbox to be listed. You can use

wildcards characters. If you omit this operand, all mailboxes are listed.

MANAGER Command: Describe the ESP Workload Manager Subsystem Controlling the ESP Agents

826

MANAGER Command: Describe the ESP Workload Manager Subsystem Controlling the ESP Agents

The MANAGER command describes the ESP Workload Manager subsystem controlling the ESP Agents following its specification.

TypeAuthorized command.

SyntaxMANAGER [NAME(mgrname)] [TCPIP[(ipaddress)]] [APPC]

ExamplesThe following is an example of the MANAGER command:MANAGER NAME(CM_CENTRAL) TCPIP

Operand DescriptionNAME(mgrname)

Specifies the name of the ESP Manager. mgrname has 16 characters maximum. Optional.

TCPIP(ipaddress) Indicates the network protocol used for communications and determines the TCP/IP address of the ESP Workload Manager master subsystem broadcast by the MGRADDR command. You can optionally specify a TCP/IP address. If you do not specify a TCP/IP address, ESP Workload Manager uses the address returned by the GETHOSTID command.

Note: If the TCP/IP address specified is invalid on the current subsystem, ESP Workload Manager does not issue the GETHOSTID command and cannot communicate with the Agent.

Note: Most Agents use TCP/IP.APPC Indicates the network protocol used for communications. APPC

is used for backward compatibility, mostly with previous generation OS/400 Agents.

827

The following example sets the manager name CM_ESP with two different TCP/IP addresses, depending of the host subsystem.IF SYSNAME='SYSA' THEN DOMANAGER NAME(CM_ESP) TCPIP(10.1.15.1)ENDDOELSE IF SYSNAME='SYSC' THEN DOMANAGER NAME(CM_ESP) TCPIP(10.1.15.3)ENDDO

MAPGEN Command: Create Job Mapping Data Sets

828

MAPGEN Command: Create Job Mapping Data Sets

The MAPGEN command is used to create a job mapping data set that can then be used by the JOBMAP and JOBTREE commands to produce detailed job level information.

TypeReporting command.

SyntaxMAPGEN DATASET(dsname) EVENT(prefix.name)

The MAPGEN command is available only as a batch job step.Events may be scheduled or may require manual or data set triggers. There is no need for these Events to have been executed previously as history data is not required for the jobs. If history data is available, this historical information is incorporated into the job mapping report.

Related informationFor information on producing a job map report, see the JOBMAP command.For information on producing a job descendent tree report, see the JOBTREE command.

Operand DescriptionDATASET(dsname) Indicates a fully qualified data set name. This data set must

be sequential, preallocated and should specify the following DCB attributes:• RECFM=VBS• LRECL=32756• BLKSIZE=16384• BLKSIZE=27998—for 3390 devices

EVENT(prefix.name) Indicates an Event name and may contain wildcards.

829

Examples For multiple EventsIn the example, a job mapping data set for all jobs invoked by Events whose descriptive name begins with PAY is generated. //jobname JOB ...//STEP1 EXEC PGM=IEFBR14//MAPGEN DD DSN=MY.MAPGEN,DISP=(,CATLG),// UNIT=SYSDA,SPACE=(TRK,(40,20)),// DCB=(DSORG=PS,RECFM=VBS,LRECL=32756,// BLKSIZE=16384)//STEP2 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=A//SYSIN DD *MAPGEN DATASET('CYBER.MAPGEN') EVENT(CYBER.PAY-)/*

Note: The MAPGEN command must be executed through the ESP subsystem started task Procedure with a special parm (PARM='SAR' or PARM='SAD').

Generates a job mapping data set for all jobs for events in group CYBER:MAPGEN DATASET('CYBER.MAPGEN') EVENT(CYBER.-)

Generates a job mapping data set for all jobs invoked by an Event with a descriptive name of PAYROLL and a group CYBER:MAPGEN DATASET('CYBER.MAPGEN') EVENT(CYBER.PAYROLL)

MAPUSER Command: Map User IDs to SAF

830

MAPUSER Command: Map User IDs to SAF

The MAPUSER command is used to map a non-SAF user ID to a valid SAF user ID in the Agent Definition File. It is part of the encrypted message read by the ESP Manager for authentication purposes. MAPUSER can also be used as an OPER command in ESP to show the current mapping status.

TypeGeneral command.

AuthorityYou require OPER authority to issue the MAPUSER command.

SyntaxMAPUSER user TO(central_manager_userid) AGENT(agentname)

ExampleIn the following example, the Manager is instructed to use CYBJD01 for security checks when it sees the user ID jdoe, from Agent hp_toronto:MAPUSER jdoe TO(CYBJD01) AGENT(hp_toronto)

Operand Description

user Indicates the server user ID to be mapped. The user operand is case sensitive and supports wildcards. It has a maximum length of 32 alpha/numeric characters.

central manager userid

Indicates the SAF user ID to which name combination should map.

agentname Indicates the name of the Agent the user ID came from.

831

MAXCXME Command: Set Maximum Space – Checkpoint file

The MAXCXME command sets the maximum amount of space, in bytes, to be used for XMEs in the Checkpoint file. MAXCXME may be coded as an initialization parameter.

AuthorityYou require OPER authority to issue the MAXCXME command.

SyntaxMAXCXME [size|128000]

Usage notesIf a value of zero is specified, this indicates that no limit is to be applied to the amount of space used by XMEs in the checkpoint file. XMEs are added to the file until it becomes full. At that point, no more XMEs are added to the file until sufficient space becomes available. No proactive indication of this state is given, but the use of the LISTXMEZ command immediately indicates the situation.If the checkpoint file fills up (due to a problem), be aware that you will start losing tracking data, as the TCELLS overflow, unless preventive action is taken.

Operand Descriptionsize A number from zero to 9999999, providing a size in bytes. The

default is 128000.

MAXINITS Command: Define Maximum Initiators

832

MAXINITS Command: Define Maximum Initiators

The MAXINITS command is used to define the maximum number of initiators available on all systems in your model process. The MAXINITS command is one of the components involved in defining your environment to produce modeling reports which forecast how ESP processes groups of jobs in your particular environment.

TypeModel command

SyntaxMAXINITS initnum [SERVERS(servernum)]

.

Usage notesUse the MAXINITS command to define the maximum number of initiators for the model. This should include initiators across all CPUs. A maximum of 999 initiators can exist for each model.All initiators specified by the MAXINITS command is defined to the MODEL processor in the drained state. Each initiator must be started by the INIT command as required.Use INIT START, SET and STOP to start, alter and drain initiators any time during the model process.Server initiators are transparent to the user. They are internal initiators used to schedule ESP links and tasks. By default, there are 20 of these initiators available at any one time.There is no need to specify the SERVERS keyword unless your installation schedules a large number of manual Task or Link jobs at the same time. Because these are 'dummy' jobs requiring no system resources, they can be scheduled as soon as their predecessors complete. An increase in the number of server initiators allows more of these dummy jobs to be scheduled at the same time, increasing throughput.

Related informationFor information on how ESP processes workload in your environment, see Advanced Forecasting in the ESP Workload Manager Advanced User’s Guide.

Operand Description

initnum Indicates the maximum number of initiators available on all CPUs. Up to 999 initiators may be specified.

servernum Indicates the maximum number of dummy initiators in the range 1-99 to service ESP Links and Tasks. If not specified, the default is 20. The SERVERS keyword should not be used unless required.

833

Examples Set for multiple classesIn the following example:• The maximum number of initiators available during the model process is 20• Initiators 1 to 10 are started and set to classes A, B, and C• Initiators 11 to 15 are started and set to class D and E• Initiators 16 to 20 are started and set to class F.MAXINITS 20INIT START(1:10) CLASS(A,B,C)INIT START(11:15) CLASS(D,E)INIT START(16:20) CLASS(F)

Note: Any time during the model process you can manipulate initiators similar to the way initiators are manipulated in your environment using the START, SET and STOP operands of the INIT command. For example, if required, initiators 16 to 20 can be drained by issuing the following command:

INIT STOP(16:20)

Set Links and TasksIn the following example, 100 initiators are available during the model process to schedule regular jobs; 50 server initiators are available to schedule ESP links and tasks.MAXINITS 100 SERVERS(50)

MAXQXME Command: Set Maximum Space – Queue file

834

MAXQXME Command: Set Maximum Space – Queue file

The MAXQXME command sets the maximum amount of space, in bytes, to be used for XMEs in the Queue file. MAXQXME may be coded as an initialization parameter.

AuthorityYou require OPER authority to issue the MAXQXME command.

SyntaxMAXQXME [size|128000]

Usage notesA value of zero is allowed, but is converted to the default of 128000 without any indication this has occurred. When an attempt to store an XME fails because the limit is reached, messages 1132W and 1133W are issued and no more XMEs are added to the file until the condition is corrected. The messages are issued once each time the overflow condition occurs. When another XME is successfully added to the file, the next failure causes the messages to be issued again.

Operand Descriptionsize A number from zero to 9999999, providing a size in bytes. The default

is 128000.

835

MCS Command: Control MCS Extended Console

The MCS command controls the ESP Workload Manager MCS (Multiple Console Support) extended console facility. This facility, when active, retrieves responses to system commands issued by ESP Workload Manager and writes those responses to the master job log.

TypeOper command.

SyntaxMCS [ACTIVATE [NAME(consname)] [KEY(conskey)] [DEACTIVATE|STATUS]

Usage notesYou can use the console key name obtained with the z/OS command DISPLAY CONSOLES,KEY to identify extended MCS consoles.

ExamplesThe following example displays the ESP Workload Manager extended MCS console status:OPER MCS

The following example deactivates the ESP Workload Manager extended MCS console from a console:F ESPS,MCS DEACTIVATE

Operand DescriptionACTIVATE Activates ESP Workload Manager extended MCS console facility.NAME(consname)

Specifies the console name. The console name is 8 characters maximum. If omitted, the console name default to the value specified in the SYSID initialization parameter. If the SYSID initialization parameter is omitted, the current SMF system identifier is used.

KEY(conskey)

Specifies the console key name. The console key name is eight characters long. If omitted, the default is ESP.

DEACTIVATE Deactivates ESP Workload Manager extended MCS console facility.

STATUS Displays the status of ESP Workload Manager extended MCS console facility.

MEMBER Statement: Specify Members Name

836

MEMBER Statement: Specify Members Name

The MEMBER statement is used to specify the member name where ESP finds a job’s execution JCL. The default member name is equal to the job name.

SyntaxMEMBER membername

Usage notesWhen ESP encounters a JOB statement for a job, it uses the JCL member in the JCLLIB with the same name as the job. Use the MEMBER statement to override this action.The name on the JOB statement must match the job name on the job card in the JCL member.

Related informationFor information on identifying a JCL library, see the JCLLIB statement.For information on specifying an optional JCL library for an individual job, see the DATASET statement.

Examples Specify single memberIn the following example, ESP submits PAYJOB1’s execution JCL from member PAYJOB99:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 MEMBER PAYJOB99 RUN WORKDAYSENDJOB

Specify multiple librariesIn the following example:• ESP uses the default JCL library CYBER .JCL.CNTL to submit PAYJOB2’s

execution JCL from member PAYJOB99• ESP uses CYBER.ALTJCL.CNTL to submit PAYJOB3’s execution JCL.

Operand Descriptionmembername Indicates a member name in up to eight characters.

837

The following JCLLIB, MEMBER and DATASET statements are used to specify different JCL libraries and members:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB2 RUN DAILY REL PAYJOB3 MEMBER PAYJOB99JOB PAYJOB3 RUN DAILY DATASET 'CYBER.ALTJCL.CNTL'ENDJOB

Specify multiple membersIn the following example:• ESP uses the default library of CYBER.JCL.CNTL to submit PAYJOB4’s

execution JCL from member BACKUP• ESP uses library CYBER.ALTJCL.CNTL to submit PAYJOB5’s execution JCL• ESP uses library CYBER.ALTJCL.CNTL to submit PAYJOB6’s execution JCL

from member BACKUP.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB4 RUN DAILY REL PAYJOB5 MEMBER BACKUPJOB PAYJOB5 RUN DAILY REL PAYJOB6 DATASET 'CYBER.ALTJCL.CNTL' JOB PAYJOB6 RUN DAILY DATASET 'CYBER.ALTJCL.CNTL' MEMBER BACKUPENDJOB

METHOD Statement: Specify EJB Method to be Invoked Remotely

838

METHOD Statement: Specify EJB Method to be Invoked Remotely

The METHOD statement specifies the EJB Method to be invoked remotely.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within an EJB_JOB workload object

SyntaxMETHOD method

Usage notesMETHOD is a mandatory statement within an EJB_JOB workload object.

ExampleIn this example, the CYBJK.SB job remotely invokes the reverse method. The reverse method has one parameter. The parameter is a java.lang.String object with the value A23.APPL TESTSBEJB_JOB CYBJK.SB HOLDRUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(java.lang.String) VALUE(A23)ENDJOB

Operand Descriptionmethod The EJB Method to be invoked remotely. method is case

sensitive and can be up to 1024 characters.

839

MGRADDR Command: Specify Manager’s Address

The MGRADDR command is used to notify one or more Agents of the ESP Manager’s address, so the Agent knows to which Agent receiver to connect. The address is always sent automatically.

AuthorityYou require OPER authority to issue the MGRADDR command.

SyntaxMGRADDR {AGENT} {AGENT(agents)} {AGENT(agents) PORT(port)} {DISPLAY} {HELP} {LIST}

Usage notesThe MGRADDR command is useful if the ESP master is stopped on one system and started on another because the TCP/IP address changes.Tells the agent to respond to messages from the ESP Workload Manager on a new TCP/IP address and port. You can issue the MGRADDR command from the new master only. Use this when: • You move the ESP Workload Manager to a new master• You want the agent to take direction from a different ESP Workload Manager

Operand DescriptionAGENT Used to send notification to all Agents.(agents) Indicates the unique name of the Agent, as defined in the Agent

definition file. Wildcard character hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

(port) Used to tell an Agent to which Agent receiver port number to connect.

DISPLAY Displays the local ESP Manager's address and home TCP/IP address. (They are the same if the TCPIP operand is specified in the MANAGER parameter of the Agent definition file).

HELP Displays MGRADDR command options.LIST Displays the local ESP Manager's address and home TCP/IP address.

(They are the same if the TCPIP operand is specified in the MANAGER parameter of the Agent definition file).

MGRADDR Command: Specify Manager’s Address

840

This is a temporary change, until the next time the agent is restarted. If you need to make the change permanent, use the MGRADDR initialization parameter. See the ESP Workload Manager Installation and Configuration Guide for details about the MGRADDR initialization parameter.Note: You can also issue the AGENTMSG command with the MGRADDR verb

from the original master or from the new master.

Examples Displaying the manager addressTo display the local ESP Manager’s address and home TCP/IP address, enter one of the following:• MGRADDR• MGRADDR DISPLAY• MGRADDR LISTNotify all agentsIn the following example, notification is sent to all Agents:MGRADDR AGENT

or MGRADDR AGENT(-)

Notify multiple agentsIn the following example, notification is sent to Agents with name prefix CYB:MGRADDR AGENT(CYB-)

Specify port numberIn the following example, notification is sent to Agent CYBAIX, to tell it to connect to Agent receiver TCP/IP port 5451:MGRADDR AGENT(CYBAIX) PORT(5451)

841

MGRMSG Command: Send Messages to Manager

The MGRMSG command is used to request actions to be performed, by the Manager, on workload objects, and report object state changes.

TypeAutomation Framework Message used from an ESP Procedure, page mode, or line mode.

AuthorityYou must have the appropriate access (READ or UPDATE) to an Application before performing the requested action.

SyntaxMGRMSG (date|.|*} {time|.} {to|.} {from|.} objectname verb subverb(data)

ACTION BYPASS DROPDEP [Pred (predname) [...]] DROPRES [Resource (resname) [...]] HOLD INSERT AbandonDependency(date time) AbandonSubmission(date time) Authstr(authstring) AverageCPU(avgcputime) AverageElapsed(avgelapsedtime) appl(applname) Conditional Doclib(libname) Docmem(membername) Dsname(dsname) EarlySub(time) Espprocfile(libname) External Hold LateEnd(date time) LateSub(date time) Manual

MGRMSG Command: Send Messages to Manager

842

Pred(objname [...]) Priority(priority) Process RelDelay(time) Request Resource([number],resname[,...]) Scheduled(time) Statements(statements) Subappl(subapplname) Succ(objname [...]) Tag(tag) Type(JOB|LINK|TASK|objclassname) READY RELEASE REQUEST RESET AbandonDependency(date time) AbandonSubmission(date time) Authstr(authstring) AverageCPU(avgcputime) AverageElapsed(avgelapsedtime) Conditional Doclib(libname) Docmem(membername) Dsname(dsname) EarlySub(time) Espprocfile(libname) Hold LateEnd(date time) LateSub(date time) Pred(objname [...]) Priority(priority) Process RelDelay(time) Request Resource([number],resname[,...]) Statements(statements) Succ(objname [...]) Tag(tag) RESUB From(restartpoint) Jobid(jobid) RestartParm(string) To(laststep) User1(var1) User2(var2) User3(var3)

843

User4(var4) UNBYPASS UNREQUEST UNWAIT UPDATE_SCBD

RESPONSE

STATE Active Alert(*|alertname) Cmpc(code) Failed Intvrq Jobno(jobno) MNPoint(mnpoint) NoActivate NoFailed NoIntvrq NoUpdateATR SetEnd SetStart Status(sysstatus) Tag(tag)

Operand Descriptiondate Indicates the date the message is sent. The format of the date is

YYYYMMDD. If omitted, a period or asterisk should be used as a placeholder. An asterisk is interpreted as the current date and time, and will cause the next field to be ignored.

time Indicates the time the message is sent. If omitted, a period should be used as a placeholder. The format of the time is HHMM[SS[TH]][{+|-}hhmm]. Where HH is the current hour in 24-hour format, MM is minutes into the hour, SS and TH are seconds and hundredths of seconds. The time may immediately be followed by a time zone. A time zone is specified with a minus sign indicating a time zone EAST of the Prime Meridian, and a plus sign indicates a time zone that is WEST.

to Indicates the network address of the destination, as seen from the sender.from Indicates the address of the sender.

MGRMSG Command: Send Messages to Manager

844

The verb, subverb and data keywords and values differ depending on the verb used.Note: Refer to the specific sections for the keywords, ACTION, RESPONSE, or STATE for more information.

ACTION verbRequests some action be applied to a workload object, such as Hold or Release. The verb modifier indicates the actual action.

objectname Indicates the name of the object to which this message refers. In the case of ESP Applications, the object name is in the form, oooo[.qqqq]/aaaaa.ggggg/fffff. Where oooo is the object name, qqqq is the optional qualifier, aaaaa is the Application name, ggggg is the generation number of the Application and fffff is the appl file name. Currently, there is only one appl file, and its name is MAIN. This field uniquely identifies this object across the entire system management scope.

verb Indicates the intent of the message. Verbs define large areas of action. The possible values are:• “ACTION verb”, on this page• “RESPONSE verb”, see page 849• “STATE verb”, see page 850

subverb Further defines the action to be taken.data Modifies the keyword/verb/subverb combination.

Operand Description

Subverb DescriptionBYPASS Turns on the BYPASS indicator for the object.DROPDEP[Pred (predname) ...]

Drops some or all predecessor dependencies for the object. Variable data consists of the keyword Pred, followed by a list of object names in parentheses. Blanks or commas can separate object names. If this keyword is omitted, all dependencies will be dropped.

DROPRES[Resource (resname) ...]

Drops some or all resources. Variable data consists of the keyword Resource, followed by a list of resource names in parentheses. Blanks or commas can separate resource names. If this keyword is omitted, all resource requirements will be dropped.

HOLD Turns on the HOLD flag for the object.INSERT Insert a new job in the Application. See the “INSERT subverb”

on page 845 for the valid data keywords to use with the INSERT subverb.

845

INSERT subverbInsert a new job in the Application.

RESET Requests one or more of the objects properties be modified. See the “RESET subverb” on page 847 for the valid data keywords to use with the RESET subverb.

READY Requests the object be immediately placed in the READY state. Any dependencies, hold states or delay submit times are dropped.

RELEASE Indicates the object can have the HOLD attribute removed. This may cause a change of state for the object.

REQUEST Turns on the REQUESTED indicator of an object.RESUB Requests the object be scheduled for re-execution. See the

“RESUB subverb” on page 849 for the valid data keywords to use with the RESUB subverb.

UNBYPASS Turns off the BYPASS indicator of an object.UNREQUEST Turns off the REQUESTED indicator of an object.UNWAIT Removes the ancestor wait attribute of the object.UPDATE_ SCBD Causes the Update_SCBE method of the object to be invoked.

Variable data is object implementation defined.

Subverb Description

Keyword DescriptionAbandonDependency(date time)

Time/Date when dependencies are to be dropped.

AbandonSubmission(date time)

Time/Date when submission of the object to execution is to be abandoned.

Authstr(authstring) Specifies the authorization string that is associated with an external object.

AverageCPU(avgcputime) Average CPU time consumed, in the form mmmss.AverageElapsed(avgelapsedtime)

Average elapsed time in the form mmmss.

Appl(applname) Specifies the name of an application for an external object.Conditional Indicates this is a conditional job.Doclib(libname) Specifies the name of the library containing documentation for

the object.Docmem(membername) Member name of documentation library entry.Dsname(dsname) Submit data set name.

MGRMSG Command: Send Messages to Manager

846

EarlySub(time) Time before when object should not be readied.Espprocfile(libname) Specifies the name of the library containing the objects

definition (ESP Procedure file).External Indicates object refers to an object in another application.Hold Requests the object be placed in a manual hold condition.LateEnd(date time) Time/Date when an object should complete to avoid becoming

overdue.LateSub(date time) Time/Date when an object should start to avoid becoming

overdue.Manual Indicates this object is a manually submitted z/OS job.Pred(objname [...]) Specifies the names of any predecessor objects. There is no limit

to the number of objects specified here. The object names are in the form nnnn.qqqq for a qualified object, or nnnn for an object without a qualifier. Object names can be separated by blanks or commas.

Priority(priority) Specifies the priority the workload object is to have. This is a number from 0 – 99.

Process Indicates whether Event processing is required for tasks or links.RelDelay(time) Specifies a minimum delay time to be added to a job after its last

dependency has been met.Request Indicates the object has the REQUEST attribute. To run, it has

to be explicitly requested.Resource([number],resname[,...])

Specifies resources the object requires to be eligible for execution. Operands are specified in the form nnnn,rrrr where nnnn is a numeric quantity and rrrr is the name of a resource. A resource requirement can be nullified by setting the quantity to zero. The quantity can be omitted, in which case it defaults to one. For example, Resource(CICS01,2,TAPES,3,SCRATCH,DBTABLE1) requests one unit of CICS01 and DBTABLE1, two units of TAPES and three units of SCRATCH.

Scheduled(time) This indicates the scheduled time an external object must possess to match this object definition.

Keyword Description

847

RESET subverbRequests one or more of the objects properties be modified.

Statements(statements) Specifies one or more statements that should be executed as part of the processing of the Event/Procedure that is invoked when this object is readied. Separate each statement with a semicolon. These statements will be executed after all procedure statements have been processed. An object need not be defined in the ESP Procedure. For example, to specify an Agent name and exit code, specify Statements(Agent AIX01;EXITCODE0-5 SUCCESS).

Subappl(subapplname) Specifies the name of the subappl to which the object belongs.Succ(objname [...]) Specifies the names of any successor objects. There is no limit

to the number of objects specified here. The object names are in the form nnnn.qqqq for a qualified object, or nnnn for an object without a qualifier. Blanks or commas can separate object names.

Tag(tag) Specifies a tag for the object.Type(JOB|LINK|TASK|objclassname)

Specifies the object type. This should be JOB, LINK, TASK, or the long or short name of a workload object class.

Keyword Description

Keyword DescriptionAbandonDependency(date time)

Time/Date when dependencies are to be dropped.

AbandonSubmission(date time)

Time/Date when submission of the object to execution is to be abandoned.

Authstr(authstring) Specifies the authorization string that is associated with an external object.

AverageCPU(avgcputime) Average CPU time consumed, in the form mmmss.AverageElapsed(avgelapsedtime)

Average elapsed time in the form mmmss.

Conditional Indicates this is a conditional job.Doclib(libname) Specifies the name of the library containing documentation for

the object.Docmem(membername) Member name of documentation library entry.Dsname(dsname) Submit data set name.EarlySub(time) Time before when object should not be readied.

MGRMSG Command: Send Messages to Manager

848

Espprocfile(libname) Specifies the name of the library containing the objects definition (ESP Procedure file).

Hold Requests the object be placed in a manual hold condition.LateEnd(date time) Time/Date when an object should complete to avoid becoming

overdue.LateSub(date time) Time/Date when an object should start to avoid becoming

overdue.Pred(objname [...]) Specifies the names of any predecessor objects. There is no limit

to the number of objects specified here. The object names are in the form nnnn.qqqq for a qualified object, or nnnn for an object without a qualifier. Object names can be separated by blanks or commas.

Priority(priority) Specifies the priority the workload object is to have. This is a number from 0 – 99.

Process Indicates whether Event processing is required for tasks or links.RelDelay(time) Specifies a minimum delay time to be added to a job after its last

dependency has been met.Request Indicates the object has the REQUEST attribute. To run, it has

to be explicitly requested.Resource([number],resname[,...])

Specifies resources the object requires to be eligible for execution. Operands are specified in the form nnnn,rrrr where nnnn is a numeric quantity and rrrr is the name of a resource. A resource requirement can be nullified by setting the quantity to zero. The quantity can be omitted, in which case it defaults to one. For example, Resource(CICS01,2,TAPES,3,SCRATCH,DBTABLE1) requests one unit of CICS01 and DBTABLE1, two units of TAPES and three units of SCRATCH.

Statements(statements) Specifies one or more statements that should be executed as part of the processing of the Event/Procedure that is invoked when this object is readied. Separate each statement with a semicolon. These statements will be executed after all procedure statements have been processed. An object need not be defined in the ESP Procedure. For example, to specify an Agent name and exit code, specify Statements(Agent AIX01;EXITCODE0-5 SUCCESS).

Keyword Description

849

RESUB subverbRequests the object be scheduled for re-execution.

RESPONSE verbIndicates a response is being made for a request sent to an agent. It does not indicate a change of state for the object.

Note: Response messages have no predefined variable data. They are generated as a response to an inquiry originated by the Application Manager or a workload object implementation package.

Succ(objname [...]) Specifies the names of any successor objects. There is no limit to the number of objects specified here. The object names are in the form nnnn.qqqq for a qualified object, or nnnn for an object without a qualifier. Blanks or commas can separate object names.

Tag(tag) Specifies a tag for the object.

Keyword Description

Keyword DescriptionFrom(restartpoint) Restart point.Jobid(jobid) Identifier of original job being restarted.RestartParm(string) Operand string to be passed to the restart processor.To(laststep) Last processing step to be rerun.User1(var1) User restart variable 1.User2(var2) User restart variable 2.User3(var3 User restart variable 3.User4(var4) User restart variable 4.

MGRMSG Command: Send Messages to Manager

850

STATE verbIndicates a change of state for the object. The new object state is supplied in the data keyword field.

Keyword DescriptionActive Indicates after the state of the object has been modified, the

Activate subroutine of the APPL Manager should be invoked. This should be specified if the state change would be expected to cause one or more objects to become eligible to be readied.

Alert(*|alertname) Indicates the name of an Alert to be invoked. Specifying “*” causes the Event that created the Application to be invoked as a monitor Event. If this keyword is specified, also supply a monitor point name via the MNPOINT keyword.

Cmpc(code) Specifies the completion code for the object.Failed Indicates the FAILED condition should be set.Intvrq Indicates intervention is required for the object.Jobno(jobno) Sets the job number field of the object.MNPoint(mnpoint) Supplies a value for the MNPOINT variable for the execution of

an Alert.NoActivate Indicates the Activate subroutine of the APPL Manager should

not be invoked for this state change.NoFailed Resets the FAILED indicator for an object.NoIntvrq Turns off the intervention required condition for an object.NoUpdateATR Indicates the Application tracking record should not be updated

to disk as a result of this state change message.SetEnd Requests the end time for the object be set from the time-stamp

of this message.SetStart Requests the start time of the object be set from the time field of

this message.Status(sysstatus) Specifies a system status string that should be attached to this

object.Tag(tag) Identifies a new tag field for this object.

851

Examples Automation Framework messages (AFMs)The following are examples of AFMs generated by the MGRMSG command: 19941102 102322-0500 AIX01 APPLMGR@PROD UJ1/AIXAPPL01.1/MAIN+

RUN . Data(…

19941102 1023 APPLMGR@PROD AIX01 UJ1/AIXAPPL01.1/MAIN STATE+ Complete CMPC(0)

MGRMSG using ACTION verbThe following are examples of MGRMSG commands, which request an ACTION be performed:Note: The fields in the message are case sensitive. The Manager converts the object name and verb to uppercase, but all other fields are left in their original case.MGRMSG * . applmgr aix01 JOB2/APPL1.5/MAIN ACTION HOLD

MGRMSG * . applmgr aix01 JOB2/APPL1.5/MAIN ACTION RESUB

MGRMSG * . applmgr aix01 JOB2/APPL1.5/MAIN ACTION DROPDEP + Pred(JOB2)

MGRMSG * . applmgr . JOB5/APPLA.5/MAIN ACTION INSERT Type(Job)+ Hold Pred(JOB2,JOB3.A) Earlysub(21.00 Today) Tag(STREAM1)

MGRMSG* . applmgr . JOB2/APPLA.4/MAIN ACTION RESET Pred(JOB1) +AbandonSubmission(6pm)

MODEL Command: Start Model Process

852

MODEL Command: Start Model Process

The MODEL command is used to activate the model processor. The model processor updates the projected start and end times for jobs in the scheduled activity data set. In additional to activating the model processor, the MODEL command indicates the start of the model period.

TypeModel command.

SyntaxMODEL 'dsname' [START('schedule')] [NOCLASS]

Usage notesYou cannot activate the model processor through ISPF panels or through an ESP Procedure. Modeling is normally done in batch.The START keyword defines the timeframe used to extract records from the scheduled activity data set. Only jobs within the timeframe are used in the MODEL generation.

Operand Descriptiondsname Indicates the data set name of scheduled activity data set, enclosed

in quotes, to be used for MODEL processing.schedule Indicates the start of the model period. If the statement contains

separators, it must be enclosed in quotes. The start period defaults to 'now' (current time/date) if not specified. If no end time is specified, the default is the start time plus 12 hours.

NOCLASS Specifies class processing is bypassed for this model. Initiator classes are not required when starting initiators and if specified, are ignored. The NOCLASS option distorts your modeling output. Jobs are selected for execution by any available initiator regardless of their class. This could result in major discrepancies between the forecast and actual completion times of your workload. This option should be used only in cases where an installation uses homogeneous initiator classes or where you are interested only in a Scheduled Jobs Cross-Reference (JR1) report.

853

After entering the MODEL command from Line mode or Page mode, the ESP MODEL processor is activated and you can enter MODEL commands. Model processor activation is indicated by:• The MODEL --> prompt from line mode• Or the MODEL MODE prompt in the upper left corner of the screen from Page

mode.

Related informationFor information on ending the model process, see the ENDMODEL command.For information on how ESP processes workload in your environment, see the ESP Workload Manager Advanced User’s Guide.

Examples Jobs in the next 12 hoursIn the following example, jobs scheduled between now and now plus 12 hours (default) are used in the MODEL generation.MODEL 'CYBER.SAD'

Specific time rangeIn the following example, only jobs scheduled between 6 am today and 6 am tomorrow are used in the MODEL generation.MODEL 'CYBER.SAD' START('6AM TODAY ENDING 6AM TOMORROW')

Bypass class processingThe following MODEL command activates the model processor and indicates the start of the model period and that class processing be bypassed:MODEL 'CYBER.SAD' START('8AM TODAY ENDING 8PM TODAY') NOCLASS

In the above example, only jobs scheduled between 8 am today and 8 pm today are used in the MODEL generation. Job classes are ignored. This is useful for generating a Scheduled Jobs Cross-Reference (JR1) report to see job relationships.Sample model definitionIn the following example:• The DEFPRINT command directs output to a DD name• The MODEL command invokes the model processor • The MAXINITS and INIT commands define initiators• The MREPORT command selects the modeling report to be generated• The ENDMODEL command ends the process• The ENDPRINT command creates a report.

MODEL Command: Start Model Process

854

DEFPRINT XREF DDNAME(MODEL1) MODEL 'CYBER.SAD' - START('4PM TODAY ENDING 4PM TODAY PLUS 5 DAYS') MAXINITS 8 INIT START(1:8) CLASS(A,B,C,D) MREPORT RPT1 JR1 FROM('4PM TODAY ENDING 4PM TOMORROW') ENDMODELENDPRINT RPT1

855

MODEL Statement: Specify Tracking Models

The MODEL statement is used to specify the name of the tracking model to be used for this job.

SyntaxMODEL modelname

Usage notesThe MODEL statement overrides the tracking model specified in the job tracking definition table, for a job.

Related informationFor information on displaying the definition of tracking models, see the LTM command.For information on defining and deleting a tracking model definition, see the DEFTM and DELTM commands.For information on tracking definition entries in a job tracking definition table, see the TRACKDEF statement.For information on using tracking models, see the ESP Workload Manager Installation and Configuration Guide.For information on job tracking definition tables, see the ESP Workload Manager Installation and Configuration Guide.

Example Specify modelIn the following example, ESP uses tracking model ALTMODL for PAYJOB2 regardless of the entry in the job tracking definition table.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY REL PAYJOB2JOB PAYJOB2 RUN FRIDAY MODEL ALTMODLENDJOB

Operand Description

modelname Indicates a tracking model name in up to eight characters.

MONITOR Statement: Identify Prefix of Job Monitor

856

MONITOR Statement: Identify Prefix of Job Monitor

The MONITOR statement is used to identify the prefix of your job monitor Event when you define your job in an Application. This prefix must be your user ID or a group to which you have access. The job monitor Event must use a specific naming convention.

TypeESP Application statement.

SyntaxMONITOR groupname

Usage notesWhen jobs are submitted, ESP detects that a specific monitor Event or a monitor group exists for the job. A monitor group acts as a high level index to point ESP to high-level Event prefixes. ESP uses the monitor group specified in an Application, tracking model, or job documentation. ESP then searches and locates the monitor Event. The identifier of the monitor Event must match the appropriate job and group combination. A monitor Event states the monitoring requirements, including monitor point and ESP action. Specifying a MONITOR group within an Application does not override generic job monitor Events defined using a tracking model.The MONITOR statement can be used at a global level within an Application or at the job level for a specific job. The MONITOR statement can not be used for jobs defined as EXTERNAL or MANUAL in an Application. If you need to monitor an EXTERNAL job, code the MONITOR statement in the Application where the job is submitted, for example, the home Application. If you need to monitor a MANUAL job, you must identify the MONITOR group in a tracking model, using the DEFTM command.

Related informationFor information on job monitoring, see the ESP Workload Manager Advanced User’s Guide.For information on specifying a monitor group or generic job monitor Event, within a tracking model definition, see the DEFTM command.

Operand Descriptiongroupname Indicates an ESP Event group name prefix in up to eight characters.

857

Examples Identify group prefix for specific jobThe following MONITOR statement identifies a monitor group prefix:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN MONDAY MONITOR PRODENDJOB

In the above example, PROD is identified as the monitor group for PAYJOB1. ESP searches for Events with the PROD prefix that conform to the following naming convention:PROD.PAYJOB1_monitorpoint

Therefore, if a job end job monitor Event is defined for PAYJOB1, triggers the following Event when PAYJOB1 ends.PROD.PAYJOB1_JOBEND

Note: The same results can be achieved by identifying the monitor group within a tracking model definition instead of within an Application. The following is an example of the tracking model definition command:

DEFTM MODEL1 MONITOR(PROD) HISTFILE(HIST1) INDEX(5)

Identify group for entire applicationIn the following example, CYBER is identified as the monitor group for all jobs within the PAYROLL Application. ESP searches for Events with the CYBER prefix. Therefore, if a step end monitor Event is defined for PAYJOB4, ESP triggers CYBER.PAYJOB4_STEPEND after every step within PAYJOB4 ends.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'MONITOR CYBERJOB PAYJOB2 REL PAYJOB3JOB PAYJOB3 REL PAYJOB4JOB PAYJOB4ENDJOBSELECT (PAYJOB2,PAYJOB3,PAYJOB4)

MONITORDELAY Statement: Delay Monitoring Children for Oracle Applications Programs

858

MONITORDELAY Statement: Delay Monitoring Children for Oracle Applications Programs

The MONITORDELAY statement tells the Agent to wait a specified number of seconds after a parent completes before monitoring for children. Program children are programs that are released by the parent program.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

SyntaxMONITORDELAY nnnnnn

Usage notesMONITORDELAY can be defined in two places.• To set MONITORDELAY for a specific job, include it in the job definition. When

used in a Request Set, MONITORDELAY applies to all of the programs in the Request Set, and cannot be specified differently for each program.

• To set the default for all jobs run by an Agent, ask your System Administrator to define the oa.default.monChildrenDelay parameter in the Agent parameter file.

Note: The Agent can monitor a maximum of five children for each job.The MONITORDELAY statement automatically monitors children, so you do not need to specify CHILDMONITOR Y. Even CHILDMONITOR N is overridden by the MONITORDELAY statement.This statement is optional for OA job definitions.

ExampleDelay monitoring children by 60 secondsAPPL ACC017 AGENT CYBOA OA_JOB ERL1303.AQ030 PROGRAM XXCOFI RUN DAILY

Operand Descriptionnnnnnn Specify the number of seconds to wait after a parent program

completes before checking its children. Maximum six digits.

859

APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN MONITORDELAY 60 ENDJOB

MREPORT Command: Select Model Reports

860

MREPORT Command: Select Model Reports

The MREPORT command is used to select the reports containing the modeling output and specify the time range for each report.

TypeModel command.

SyntaxMREPORT repname {JR1|JR2} {ER1|ER2} {RR1|RR2} [FROM('schedule')] [CPU(cpunumber)] [JOBS(jobname[,jobname]...)] [LONGNAME(long_name_width)] [NOJOBNAME]

Operand Descriptionrepname Indicates a one to eight alphanumeric character logical report

name as defined by the DEFPRINT command.JR1 Generates a Scheduled Jobs Cross Reference report. Can also

be specified as JOB_REPORT_1.JR2 Generates a Projected End Time report. Can also be specified

as JOB_REPORT_2.ER1 Generates a Job Exception report. Can also be specified as

EXCEPTION_REPORT_1.ER2 Generates a Dueout Exception report. Can also be specified as

EXCEPTION_REPORT_2.RR1 Generates the Resource Utilization On Systems report. Can

also be specified as RESOURCE_REPORT_1.RR2 Generates the Resource Utilization By Job report. Can also be

specified as RESOURCE_REPORT_2.schedule Indicates a valid schedule statement. If the statement contains

separators, it must be enclosed in quotes. The keywords ENDING or UNTIL can be used to restrict the time range selected. An EVERY keyword can also be specified to control the reporting increment. If the FROM keyword is not specified, the default is “now every two minutes until 6 am tomorrow”.

861

Usage notesThe recommended data width for all reports is 133 with a record format of FBA.

Related informationFor information on how ESP processes workload in your environment, see the ESP Workload Manager Advanced User's Guide.

cpunumber Indicates the CPU number for which the report is generated. The valid range is 0-7 (up to eight CPUs supported). If not specified, all CPUs are reported on. The CPU keyword is used only when a RESOURCE_REPORT_1 (RR1) report is requested.

jobname Indicates a one to eight alphanumeric jobname or list of jobnames to be included in the report. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. The JOBS keyword should be used only if you wish to limit a report to certain jobnames or job prefixes. All jobs are reported on by default if the JOBS keyword is not specified.

LONGNAME(long_name_width)

Specifies the width in characters of long name fields in the report. You must specify a width between 12 and 64 characters. If the actual job name exceeds the width you specify, the long job name is truncated in the report.

If you omit the LONGNAME operand or specify LONGNAME(0) or LONGNAME(00), no long names are printed.

If you set the LONGNAME width to a high value, each job in the report may need two lines to report all the information. In this case, the first line contains the job name, job qualifier, and long name. The rest of the job information is indented and printed on the second line. The headings are also printed on two lines. Each heading is positioned over the appropriate information.

NOJOBNAME Disable printing of short job names and their qualifiers. If you omit NOJOBNAME, job names and qualifiers are printed.

Operand Description

MREPORT Command: Select Model Reports

862

Examples Resource utilization by system In the following example, generation of the Resource Utilization by System Report (RR1) is requested. The report is generated at 5-minute intervals.MREPORT CYBER1 RESOURCE_REPORT_1 -FROM('6AM TODAY EVERY 5 MINUTES ENDING 6AM TOMORROW')

Resource utilization by jobIn the following example, generation of the Resource Utilization by Job (RR2) is requested. Only LOCAL resources defined to CPU3 will appear on the report. The report is generated at 2-minute intervals (default).MREPORT OUTDSN RR2 FROM('8:15 JAN1 TO 9:15 JAN2') CPU(3)

Sample definitionIn the following example:

• The DEFPRINT command directs output to a DD name• The MODEL command invokes the model processor • The MAXINITS and INIT commands define initiators• The MREPORT command selects the modeling report to be generated• The ENDMODEL command ends the process• The ENDPRINT command creates a report.DEFPRINT XREF DDNAME(MODEL1) MODEL 'CYBER.SAD' - START('4PM TODAY ENDING 4PM TODAY PLUS 5 DAYS') MAXINITS 8 INIT START(1:8) CLASS(A,B,C,D) MREPORT RPT1 JR1 FROM('4PM TODAY ENDING 4PM - TOMORROW') ENDMODELENDPRINT RPT1

Model report showing LONGNAME operandIn the following example, the long and short job names are reported. The LONGNAME operand sets the field width to 30 characters. If the actual long name for job AGNO103 is more than 30 characters, the name is truncated in the report.MREPORT RPT01 JR1 LONGNAME(30) +FROM('06:00AM TODAY ENDING 6AM TOMORROW PLUS 5 DAYS')

863

PA2.JR1.REPORT Columns,00001,00072 ===> Scroll ===> CSR ***************************** Top of Data ******************************1WEEKLY PROJECTED END TIMES

SCHEDULED JOBS CROSS REFERENCE FROM 06.

JOBNAME JOB QUAL LONG JOBNAME APP NAME NET NAME TIME -------- -------- ------------------------------ -------- -------- ---- JOBFIRST MLTEST1 15.0 GVT0021 GVT002D 10.3 DF10962 10.4 AGN0100 AGN010 12.0 AGN0101 AGN010 12.0 AGN0102 AGN010 12.0 AGN0103 DAILY CUSTOMER ACCOUNT TRANSAC AGN010 12.0

Model report showing LONGNAME and NOJOBNAME operandsIn the following example, the long job names are reported, but the short job names are not.The LONGNAME operand sets the report width to 1 character. Since the valid range for the width is 12 to 64 characters, the width is automatically reset to 12. Since the actual long name for one of the jobs in Application AGNO10 is more than 12 characters, the name is truncated in the report.The NOJOBNAME operand disables the printing of short job names and their qualifiers.MREPORT RPT02 JR2 LONGNAME(01) NOJOBNAME +FROM('06:00AM TODAY ENDING 6AM TOMORROW PLUS 5 DAYS')

MREPORT Command: Select Model Reports

864

PA2.JR2.REPORT Columns,00001,00072 ===> Scroll ===>,CSR ***************************** Top of Data ******************************1WEEKLY RESOURCE UTILIZATION BY SYSTEM

PROJECTED END TIME REPORT FROM 06.00

LONG JOBNAME APP NAME NET NAME PROJECTED END EXECUTION DUEOUT ------------ -------- -------- -------------- ----------------

MLTEST1 15.01 09/07/04 MLTEST1 15.01 09/07/04 MLTEST1 15.01 09/07/04 MLTEST1 15.01 09/07/04 DFTEST 15.30 09/07/04 AGN010 12.05 09/08/04 AGN010 12.05 09/08/04 AGN010 12.05 09/08/04 DAILY CUSTOM AGN010 12.05 09/08/04 AGN010 12.05 09/08/04

865

MSG Command: Set Messages

The MSG command is used to add or delete routing or descriptor codes to an ESP message or range of ESP messages. It can also change the message type.

TypeGeneral command.

AuthorityYou require OPER authority to issue the MSG command.

SyntaxMSG {(id[,id]...)} {(id1:id2)} [ROUTE(codes)] [DESC(codes)] [DELROUTE(codes)] [DELDESC(codes)] [TYPE(I|W|E|S)]

Operand Description

id Indicates a number in the range 26 to 9998. A list of numbers can be specified, enclosed in parentheses and separated by blanks or commas.

id1:id2 Indicates two numbers each in the range 26 to 9998, separated by a colon, which specify a range of message IDs. A list of ranges can be specified, enclosed in parentheses and separated by blanks or commas.

codes Indicates a number, range of numbers or list of numbers and ranges of numbers. Each number must be within the range 0-16.

ROUTE Indicates one or more routing codes are added when the message is issued.

DESC Indicates one or more descriptor codes are added when issuing the messages.

DELROUTE Indicates one or more routing codes are deleted from those normally used for the message.

DELDESC Indicates one or more descriptor codes are deleted from those normally used for the message.

TYPE Indicates the new message type:• I informational message• W warning message• E error message• S severe error message

MSG Command: Set Messages

866

Usage notesWhen a message is about to be issued, the routing and descriptor codes are modified according to the above specification. The routing and descriptor codes for the message class, as set by the MSGTYPE command, are also set. The order of Application is:1. DELROUTE and DELDESC from message type (MSGTYPE command).2. ROUTE and DESC from message type (MSGTYPE command).3. DELROUTE and DELDESC from individual message modifier (MSG

command).4. ROUTE and DESC from individual message modifier (MSG command).

Related informationFor information on adding or deleting routing or descriptor codes to groups of messages, see the MSGTYPE command.

Example MSG and MSGTYPE exampleIn the following example, messages 500 to 550 are informational messages, and messages 551 to 559 are warning messages.MSGTYPE INFORMATION ROUTE (1:3,10,12)MSGTYPE WARNING ROUTE (1:3,8,10,12) DESC(1)MSG (500:510,525) DESC(2)MSG 530 TYPE(W) DELDESC(1)

After these commands are entered:• All informational messages have routing codes 1,2,3,10 and 12 added.• Warning messages have routing codes 1,2,3,8,10 and 12 added along with

descriptor code 1.• Messages 500 to 510 and 525 would also have descriptor code 2 added, although

they remain informational messages.Message 530 is converted to a warning message, and has the warning message routing and descriptor codes added. However, the descriptor code 1 is deleted for message 530.

867

MSGCLASS Statement: Specify the Java Class of the JMS Message (J2EE)

The MSGCLASS statement specifies the Java class of the JMS Message.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within a JMSP_JOB workload object

SyntaxMSGCLASS package.class

Usage notesMSGCLASS is a mandatory statement within an JMSP_JOB workload object.

Examplesjava.lang.String message classIn this example, the CYBJK.JP job has a message class of java.lang.String. The message is a java.lang.String object. Since the message contains spaces, it is enclosed in single quotes.APPL TESTJPJMSP_JOB CYBJK.JP HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DESTNAME Queue TOPIC N MSGCLASS String JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 PARAMETER TYPE(java.lang.String) VALUE(’this is my message’)ENDJOB

Operand Descriptionpackage.class The Java class of the JMS Message. package.class is case

sensitive and can be up to 1024 characters.

Note: If the Java package is unspecified, java.lang is used.

MSGCLASS Statement: Specify the Java Class of the JMS Message (J2EE)

868

Integer message classIn this example, the CYBJK.JP job has a message class of Integer. The message is a java.lang.String object with value 10.APPL TESTJPJMSP_JOB CYBJK.JP HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DESTNAME Queue TOPIC N MSGCLASS Integer JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 PARAMETER TYPE(java.lang.String) VALUE(10)ENDJOB

869

MSGLIMIT Statement: Limit Console Message Number

The MSGLIMIT statement is used to allow you to limit the number of console messages generated by an Event. MSGLIMIT can be used to suppress excess messages or to cancel Events that exceed a certain limit.

SyntaxMSGLIMIT [n1[,n2] [LIST][OFF]

Usage notesIf a Procedure contains a MSGLIMIT statement then its value overrides the default value set by an operator command or initialization parameter. MSGLIMIT applies to the Event that invokes the ESP Procedure.

Examples Display message limit settingsMSGLIMIT -

In the above example, the current message limit settings are displayed.Set the message limit settingMSGLIMIT 100

In the above example, the message limit is set to 100. When an Event exceeds 100 messages, the Event is cancelled.Suppress messages or cancel an EventMSGLIMIT 40,100

In the above example, any message beyond the first 40 from an Event is suppressed. However, if the total number of messages (including the suppressed ones) exceeds 100, the Event is cancelled.

Operand Descriptionn1 When specified on its own, this causes ESP to cancel an Event once it

exceeds this number of messages.N2 Entering two operands on MSGLIMIT causes excess messages to be

suppressed while allowing the Event to continue. Any message beyond the first n1 from the Event is suppressed. However, if the total number of messages exceeds n2, the Event is canceled.

LIST Displays MSGLIMIT settings.OFF Inactivates the message limits.

MSGQLEN Statement: Limit Number of Messages

870

MSGQLEN Statement: Limit Number of Messages

The MSGQLEN statement sets the maximum number of messages stored by an AGENT_MONITOR workload object. It is used in conjunction with the AGENT_MONITOR statement.

TypeESP Workload Manager Application Statement

SyntaxMSQGQLEN max

Example In the following example, AGENT_MONITOR TORONTO will perform status checks on Agent CYBNT1. The status checks will occur every 5 minutes and the object will store 10 messages.APPL AGENTMON

AGENT_MONITOR TORONTO STATINTV 5 MSGQLEN 10 AGENT CYBNT1ENDJOB

Operand DescriptionMSGQLEN max Sets the maximum number of messages the object will store. Once

the maximum is reached, the oldest message will be dropped. The default is 5.

871

MSGTYPE Command: Set Messages from Type

The MSGTYPE command is used to add or delete routing or descriptor codes to groups of ESP messages based on their message type.

TypeGeneral command.

AuthorityYou require OPER authority to issue the MSG command.

SyntaxMSGTYPE {INFO|I} {WARNING|W} {ERROR|E} {SEVERE|S} [ROUTE(codes)] [DESC(codes)] [DELROUTE(codes)] [DELDESC(codes)]

Operand DescriptionINFO Indicates an informational message.WARNING Indicates a warning message.ERROR Indicates an error message.SEVERE Indicates a severe error message.codes Indicates a number, range of numbers or list of numbers and ranges of

numbers. Each number must be within the range 0-16.ROUTE Indicates one or more routing codes are added when the message is issued.DESC Indicates one or more descriptor codes are added when issuing the messages.DELROUTE Indicates one or more routing codes are deleted from those normally used for

the message.DELDESC Indicates one or more descriptor codes are deleted from those normally used

for the message.

MSGTYPE Command: Set Messages from Type

872

Usage notesWhen a message is to be issued, the message type indicator is used to locate the message type attributes. Any message type attributes are combined with the attributes of the message itself to form the final attributes. The order of Application of attributes when both MSG and MSGTYPE apply to a message is:1. DELROUTE and DELDESC from message type (MSGTYPE command).2. ROUTE and DESC from message type (MSGTYPE command).3. DELROUTE and DELDESC from individual message modifier (MSG

command).4. ROUTE and DESC from individual message modifier (MSG command).

Related informationFor information on adding or deleting routing or descriptor codes to a message or range of messages, see the MSG command.

Examples MSG and MSGTYPE commandsIn the following example, messages 500 to 550 are informational messages, and messages 551 to 559 are warning messages.The following are examples of MSG and MSGTYPE commands:MSGTYPE INFORMATION ROUTE (1:3,10,12)MSGTYPE WARNING ROUTE (1:3,8,10,12) DESC(1)MSG (500:510,525) DESC(2)MSG 530 TYPE(W) DELDESC(1)

After these commands are entered:• All informational messages have routing codes 1,2,3,10, and 12 added.• Warning messages have routing codes 1,2,3,8,10 and 12 added along with

descriptor code 1.• Messages 500 to 510 and 525 would also have descriptor code 2 added, although

they remain informational messages.• Message 530 is converted to a warning message, and has the warning message

routing and descriptor codes added. However, the descriptor code 1 is deleted for message 530.

Add routing codesIn the following example, informational messages will have routing codes 1,2,5, and 6 and descriptor code 2. If you want to reset any prior setting, specify zero as the first routing or descriptor code.MSGTYPE I ROUTE(1,2,5)MSGTYPE I ROUTE(6) DESC(2)

873

Reset routing and descriptor codesIn the following example, previous routing and descriptor code settings are reset before adding the new values.MSGTYPE I ROUTE(0,6) DESC(0,2)

NCR_JOB Statement: Identify the Name of NCR Jobs

874

NNCR_JOB Statement: Identify the Name of NCR Jobs

The NCR_JOB statement is used to identify the name of an NCR job in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use NCR jobs, you must load a workload object module. The NCR_JOB workload object module is CYBESONC. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Refer to the JOB statement usage notes.

ExampleNCR_JOB payroll SCRIPTNAME payroll2.payscrpt RUN DAILYENDJOB

In the above example, the job statement specifies an NCR job. The script called payroll2.payscrpt runs daily.

875

NETAUTH Command: Control Authorization Profiles

The NETAUTH command controls authorization profiles for remote hosts that are allowed to connect to the local NDS network.

TypeGeneral command.

SyntaxNETAUTH [ADD HOST(host)|DELETE HOST(host)|HELP|LIST]

Usage notesYou must set the AUTHENTICATE operand of the NETWORK initialization parameter before your installation can restrict connection by remote hosts according to the authorization profiles set in the NETAUTH initialization parameter or command.

Example The following example deletes access to the local NDS network to hosts with the TCP/IP address 134.4.10.1.F ESPM,NETAUTH DELETE HOST(134.4.10.1)

Operand DescriptionADD Defines a new network authorization profile.HOST(host) Specifies the TCP/IP address (dotted decimal format or DNS name)

that is authorized to connect to the local NDS network.DELETE Deletes the network authorization profile corresponding to the

specified host.HELP Displays NETAUTH command options.LIST Lists the network authorization profiles.

NETDEST Command: NDS Destination Profile

876

NETDEST Command: NDS Destination Profile

The NETDEST command defines a Network Delivery Service (NDS) destination profile. Each network destination is uniquely identified by a network node and specifies its host attributes.An ESP Workload Manager subsystem accepts inbound or outbound NDS connection requests only if you have coded the two following criteria:• A NETNODE initialization parameter in the local ESP Workload Manager

LOADNET initialization data set to define itself as a local network node• A NETDEST ADD initialization parameter in the local ESP Workload Manager

LOADNET initialization data set to define the network destination as a remote network node. You can also issue the NETDEST ADD command dynamically.

TypeOper command.

SyntaxNETDEST [ADD|ALTER|DELETE|HELP|LIST]

ADD NETNODE(netnode) [HOST(host)] [SYSPLEX(sysplex) [SYSNAME(sysname)|SYSTEM(sysname)] [XCFGROUP(xcfgroup)[XCFMEMBER(xcfmember)]]] [JESNODE(jesnode)[JESMEMBER(jesmember)]] [SYSID(sysid)]

ALTER NETNODE(netnode) [HOST(host)|NOHOST] [SYSPLEX(sysplex)|NOSYSPLEX] [SYSNAME(sysname)|SYSTEM(sysname)|NOSYSNAME|NOSYSTEM] [XCFGROUP(xcfgroup)|NOXCFGROUP] [XCFMEMBER(xcfmember)|NOXCFMEMBER] [JESNODE(jesnode)|NOJESNODE] [JESMEMBER(jesmember)|NOJESMEMBER] [SYSID(sysid)|NOSYSID]

DELETE NETNODE(netnode)

877

LIST [NETNODE(netnode)] [HOST(host)] [SYSPLEX(sysplex)] [SYSNAME(sysname)|SYSTEM(sysname)] [XCFGROUP(xcfgroup)] [XCFMEMBER(xcfmember)] [JESNODE(jesnode)] [JESMEMBER(jesmember)] [SYSID(sysid)]

Operand DescriptionADD Creates a new network destination profile. See “ADD” below for the

applicable operands.ALTER Alters an existing network destination profile. See “ALTER” on

page 878 for the applicable operands.DELETE Deletes an existing network destination profile. See “DELETE” on

page 879 for the applicable operands.HELP Displays the NETDEST command options.LIST Displays network destination profiles. See “LIST” on page 879 for

the applicable operands

NETDEST Command: NDS Destination Profile

878

ADD

ALTER

Operand DescriptionNETNODE(netnode) Specifies the name of the network node. The netnode value has a

maximum of 16 characters. It is an arbitrary value.HOST(host) Specifies the DNS host name or the dot decimal IP address of the

remote network node. SYSPLEX(sysplex) Specifies the sysplex name of a remote ESP Workload Manager

subsystem.SYSNAME(sysname)SYSTEM(sysname)

Specifies the name of a remote ESP Workload Manager subsystem.

XCFGROUP(xcfgroup) Specifies the XCF group name of a remote ESP Workload Manager subsystem.

XCFMEMBER(xcfmember) Specifies the XCF member name of a remote ESP Workload Manager subsystem.

JESNODE(jesmode) Specifies the JES/NJE node name of a remote network node.JESMEMBER(jesmember) Specifies the JES/MAS member name of a remote network node. SYSID(sysid) Specifies the system identifier of a remote ESP Workload

Manager subsystem. It corresponds to the SYSID initialization parameter of the remote subsystem.

Operand DescriptionNETNODE(netnode) Specifies the name of the network node to be altered. HOST(host) Specifies the DNS host name or the dot decimal IP address of the

remote network node.NOHOST Removes the specified host from the network destination profile.SYSPLEX(sysplex) Specifies the sysplex name of a remote ESP Workload Manager

subsystem.NOSYSPLEX Removes the specified sysplex from the network destination

profile.SYSNAME(sysname)SYSTEM(sysname)

Specifies the name of a remote ESP Workload Manager subsystem. SYSNAME and SYSTEM are aliases.

NOSYSNAMENOSYSTEM

Removes the specified system from the network destination profile.

XCFGROUP(xcfgroup) Specifies the XCF group name of a remote ESP Workload Manager subsystem.

NOXCFGROUP Removes the specified XCF group from the network destination profile.

879

DELETE

LIST

XCFMEMBER(xcfmember) Specifies the XCF member name of a remote ESP Workload Manager subsystem.

NOXCFMEMBER Removes the specified XCF member from the network destination profile.

JESNODE(jesmode) Specifies the JES/NJE node name of a remote network node.NOJESNODE Removes the specified JES/NJE node from the network

destination profile.JESMEMBER(jesmember) Specifies the JES/MAS member name of a remote network node.NOJESMEMBER Removes the specified JES/MAS member from the network

destination profile.SYSID(sysid) Specifies the subsystem identifier of a remote ESP Workload

Manager subsystem. It corresponds to the SYSID initialization parameter of the remote subsystem.

NOSYSID Removes the specified subsystem from the network destination profile.

Operand DescriptionNETNODE(netnode) Specifies the name of the network node to be deleted.

Operand DescriptionNETNODE(netnode) Specifies the name of the network node to be listed. HOST(host) Specifies the DNS host name or the dot decimal IP address of the

remote network node. SYSPLEX(sysplex) Specifies the sysplex name of a remote ESP Workload Manager

subsystem.SYSNAME(sysname)SYSTEM(sysname)

Specifies the name of a remote ESP Workload Manager subsystem. SYSNAME and SYSTEM are aliases.

XCFGROUP(xcfgroup) Specifies the XCF group name of a remote ESP Workload Manager subsystem.

XCFMEMBER(xcfmember) Specifies the XCF member name of a remote ESP Workload Manager subsystem.

JESNODE(jesmode) Specifies the JES/NJE node name of a remote network node. JESMEMBER(jesmember) Specifies the JES/MAS member name of a remote network node. SYSID(sysid) Specifies the system identifier of a remote ESP Workload

Manager subsystem. It corresponds to the SYSID initialization parameter of the remote subsystem.

Operand Description

NETDEST Command: NDS Destination Profile

880

Usage notesYou must define a network destination profile with at least one of the following host attribute specifications:• HOST(host)• SYSPLEX(sysplex)• JESNODE(jesnode)• SYSID(sysid)You must respect the following dependencies in a network destination profile:• SYSNAME(sysname) cannot be specified unless SYSPLEX(sysplex) is also

specified.• XCFGROUP(xcfgroup) cannot be specified unless a SYSPLEX(sysplex) is also

specified.• XCFMEMBER(xcfmember) cannot be specified unless XCFGROUP(xcfgroup) is

also specified.• JESMEMBER(jesmember) cannot be specified unless JESNODE(jesnode) is also

specified.If a remote ESP Workload Manager master subsystem does not always execute on the same system within its sysplex, its NETDEST specification in the local LOADNET initialization file must not specify any of the following system specific destination specification operands:• HOST(host) • SYSNAME(sysname) • XCFMEMBER(xcfmember) • JESMEMBER(jesmember)If any host attribute specifications for a remote network node in a NETDEST command do not correspond to the actual host attributes of the network node, an NDS connection request to that network node will be rejected.

Examples The example below illustrates a group of LOADNET initialization parameters:NETNODE ESPM_CHICAGONETDEST NETNODE(ESPM_NEWYORK) SYSPLEX(NEWYORK) JESNODE(NYC)+SYSID(ESPM_NYC)NETDEST NETNODE(ESPM_TORONTO) SYSPLEX(TORONTO) JESNODE(TOR)+SYSID(ESPM_TOR)NETWORK START CONNECTION HOST(NEWYORK) PORT(2300)NETWORK START CONNECTION HOST(TORONTO) PORT(2300)

881

• The NETNODE initialization parameter defines ESPM_CHICAGO as the local network node name.

• The first NETDEST initialization parameter defines remote network node ESPM_NEWYORK. The sysplex name of its host system is NEWYORK, the JES node name of its host system is NYC and its subsystem identifier is ESPM_NYC.

• The second NETDEST initialization parameter defines remote network node ESPM_TORONTO. The sysplex name of its host system is TORONTO, the JES node name of its host system is TOR and its subsystem identifier is ESPM_TOR.

• The first NETWORK START CONNECTION initialization parameter starts a connection to remote network node ESPM_NEWYORK. Its DNS host name is NEWYORK on TCP port 2300.

• The second NETWORK START CONNECTION initialization parameter starts a connection to remote network node ESPM_TORONTO. Its DNS host name is TORONTO on TCP port 2300.

NETWORK Command: Control NDS

882

NETWORK Command: Control NDS

The NETWORK command controls Network Delivery Services (NDS)

TypeGeneral command.

SyntaxNETWORK DISPLAY|HELP|?|QUEUE|SET|START|STOP

DISPLAY {CONNECTIONS [DETAIL] |LISTENERS |LOCAL |PENDING |SERVICES }

HELP|? DISPLAY|HELP|?|QUEUE|SET|START|STOP

QUEUE {DISPLAY [NETNODE(netnode)|HOST(host)] [SYSPLEX(sysplex)] [SYSNAME(sysname)|SYSTEM(sysname)] [XCFGROUP|(xcfgroup)] [XCFMEMBER|(xcfmember)] [JESNODE(jesnode)] [JESMEMBER|(jesmember)] [SYSID(sysid)] [SERVICE(service)] |SPACE [FREE] ] |FLUSH IDENTIFIER(identifier) }

SET CONNECTIONS [AUTHENTICATE|NOAUTHENTICATE] [BUFFERSIZE[(buffersize)] [KEEPALIVE(keepalive)|NOKEEPALIVE] [RETRY(retry)|NORETRY]

START {CONNECTION HOST(host) PORT(cport) [RETRY(seconds)|NORETRY] |LISTENER PORT(lport) |SERVICE service }

883

STOP {CONNECTION {ALL |IDENTIFIER(id) |NETNODE(netnode) |HOST(host) } |LISTENER PORT(lport) |PENDING {ALL|HOST(host) [PORT(cport)]} |SERVICE service }

DISPLAY operand

Operand DescriptionDISPLAY Displays information about Network Delivery Services (NDS). See

“DISPLAY operand” below for the operands associated with DISPLAY.

HELP|?

Provides syntax information about the NETWORK command. See “HELP|? operand” on page 885 for the operands associated with HELP.

QUEUE Provides information about or flushes messages in an output queue on the NETQUEUE data set. See “QUEUE operand” on page 885 for the operands associated with QUEUE.

SET Sets attributes for Network Delivery Services (NDS). See “SET operand” on page 887 for the operands associated with SET.

START Starts a Network Delivery Services (NDS) activity. See “START operand” on page 888 for the operands associated with START.

STOP Stops a Network Delivery Services (NDS) activity. See “STOP operand” on page 889 for the operands associated with STOP.

Operand DescriptionCONNECTIONS Displays the active NDS connections.DETAIL Displays detailed information about the host attributes of

the remote NDS partner.LISTENERS Displays the active NDS listeners.LOCAL Displays local host information on the current NDS network

node.

NETWORK Command: Control NDS

884

Examples NETWORK DISPLAY CONNECTIONSActive Network Connections TCP transmitter ... 101.3.15.1:1220->133.41.15.4:3327 TCP receiver ...... 101.3.15.1:1220<-133.41.15.4:3328 Id=0, NetNode=NEWYORK_SYSA TCP transmitter ... 101.3.15.1:1220->129.10.1.1:3124 TCP receiver ...... 101.3.15.1:1220<-129.10.1.1:3135 Id=0, NetNode=TORONTO_SYSA

NETWORK DISPLAY LISTENERSESP3219I TCP listener active on port 1220

NETWORK DISPLAY LOCALLocal Host Data, NetNode=CHICAGO TCP listener active on port 1220 SysPlex=CHICAGO, SysName=SYSA, XcfGroup=ESP, XcfMember=ESP_MASTER, JesNode=CHICAGO, JesMember=SYSA, JesSubsys=JES2, Smfid=SYSA, Asid=0074, Job=ESPM, Jobid=STC57197, Sysid=ESPM, TimeZone=4W, ESP master

NETWORK DISPLAY PENDING Expiry Interval Partner 0:26 0:30 101.11.15.1:1220

NETWORK DISPLAY SERVICESService StatusTRACKING Receiving

PENDING Displays pending NDS connects.

Note: Pending NDS connects are connections that are not yet successful and that have been set or started with an active RETRY operand. A NORETRY operand in the NETWORK START CONNECTION command overrides a RETRY operand in the NETWORK SET CONNECTIONS command.

SERVICES Displays active NDS services.

Operand Description

885

HELP|? operand

Examples NETWORK HELP STARTNET{WORK} S{TART} Command OptionsS{TART} C{ON{NECT{ION}}} H{OST}(host) P{ORT}(port) - {R{ETRY}(10-3600)|N{ORETRY}}S{TART} L{ISTEN{ER}} P{ORT}(port)S{TART} S{ERV{ICE}} service

QUEUE operand

Operand DescriptionDISPLAY Displays NETWORK DISPLAY options.HELP|? Displays NETWORK HELP options.QUEUE Displays NETWORK QUEUE options.SET Displays NETWORK SET options.START Displays NETWORK START options.STOP Displays NETWORK STOP options.

Operand DescriptionDISPLAY Displays the queue backlog information for the

NETQUEUE data set or its space usage information. The information can be restricted using the other operands in this table.

NETNODE(netnode) Specifies the target network node that the output queue backlog information display will be restricted to.

HOST(host) Specifies the TCP/IP address (dotted decimal format or DNS name) of the host that the output queue backlog information display will be restricted to.

SYSPLEX(sysplex) Specifies the target sysplex that the output queue backlog information display will be restricted to.

SYSNAME(sysname) Specifies the target system that the output queue backlog information display will be restricted to.

SYSTEM(sysname) Specifies the target system that the output queue backlog information display will be restricted to.

NETWORK Command: Control NDS

886

Examples NETWORK QUEUE DISPLAYInput: Service=TRACKING, Backlog=0Id=0: NetNode=CHICAGO_SYSA, SysPlex=CHICAGO, XcfGroup=ESP, JesNode=CHICAGO, Sysid=ESPMSYSA, Service=TRACKING, Backlog=27

NETWORK QUEUE DISPLAY SPACEName=NETQUEUE, Date=2003/07/21, Time=12:09:56, Alet=0101001C, Origin=00000000,Size=000C0000, Used=000011D8, HighMark=0000BFA0, Free=000BFE28

NETWORK QUEUE FLUSH IDENTIFIER(0)Id=0: 27 messages flushed, NetNode=CHICAGO_SYSA,SysPlex=CHICAGO, XcfGroup=ESP, JesNode=CHICAGO, Sysid=SYSA, Service=TRACKING

XCFGROUP(xcfgroup)

Specifies the target XCF group that the output queue backlog information display will be restricted to.

XCFMEMBER(xcfmember)

Specifies the target XCF member that the output queue backlog information display will be restricted to.

JESNODE(jesnode) Specifies the target JES node that the output queue backlog information display will be restricted to.

JESMEMBER(jesmember)

Specifies the target JES member that the output queue backlog information display will be restricted to.

SYSID(sysid) Specifies the target system identifier that the output queue backlog information display will be restricted to.

SERVICE(service) Specifies the target network service that the output queue backlog information display will be restricted to.

SPACE Displays the NETQUEUE data set space information.FREE Displays the free areas in the NETQUEUE data set.FLUSH Flushes all backlogged messages in an output queue on the

NETQUEUE data set.IDENTIFIER(identifier)

Specifies the numeric identifier of the NETQUEUE data set output queue whose backlog will be flushed.

Note: You can determine the identifier with the NETWORK QUEUE DISPLAY command.

Operand Description

887

SET operand

Operand DescriptionCONNECTIONS Sets attributes for Network Delivery Services (NDS)

connections.AUTHENTICATE Specifies that a connection to or from a remote NDS

network node is accepted only if the network node host name or TCP/IP address has been defined in an NDS authorization profile. Refer to the NETAUTH command or initialization parameter for defining NDS authorization profiles.

NOAUTHENTICATE Specifies that connections to or from a remote NDS network node are accepted. NDS authorization profiles are ignored.

BUFFERSIZE[(buffersize)]

Specifies the buffer size in bytes for data transmitted from remote NDS network nodes. The range is from 1 to 1048576. The buffersize values are rounded as follow:• 1 to 511—512• 513 to 1023—1024• 1025 to 2047—2048• 2049 and above—rounded up to the next 4K value

Note: During the establishment of the connection, the remote NDS network node may negotiate the data buffer sizes downward.

KEEPALIVE(keepalive)

Specifies an interval between 30 and 14400 seconds. When a NDS connection is idle for a duration equal to the specified interval, a query is sent to the remote network node. If the remote network node does not answer the query, the connection is assumed to have been severed and the local network closes its half of the connection.

NOKEEPALIVE Specifies that no queries are sent to the remote network node regardless of the duration of idle periods.

RETRY(retry) Specifies an interval between 10 and 3600 seconds. If an NDS connection is not successfully established, the local network node will retry establishing the connection after the specified interval. These attempts will continue until the connection is successfully established or a NETWORK STOP PENDING is issued.

Note: The NETWORK START CONNECTION command or initialization parameter can override this operand.

NETWORK Command: Control NDS

888

Usage notesIf no NETWORK SET CONNECTIONS initialization parameter is used and no NETWORK SET CONNECTIONS commands have been issued, the following default is in effect:NETWORK SET CONNECTIONS NOAUTHENTICATE BUFFERSIZE(4096)- NOKEEPALIVE NORETRY

If you change the NOAUTHENTICATE operand of the NETWORK SET CONNECTIONS command to AUTHENTICATE, all connections whose remote hosts are not defined in an NDS network authorization profile become unauthorized and are terminated. You can create an NDS network authorization profile with the NETAUTH command or initialization parameter.

START operand

NORETRY Specifies that an unsuccessful NDS connection will not be retried.

Note: The NETWORK START CONNECTION command or initialization parameter can override this operand.

Operand Description

Operand DescriptionCONNECTION Starts an NDS connection.HOST(host) Specifies the TCP/IP address (dotted decimal format or

DNS name) of the target NDS network host.PORT(cport) Specifies the TCP/IP port number of the target NDS

network host.RETRY(seconds) Specifies an interval between 10 and 3600 seconds. If an

NDS connection is not successfully established, the local network node will retry establishing the connection after the specified interval. These attempts will continue until the connection is successfully established or a NETWORK STOP PENDING is issued.

Note: This initialization parameter overrides NETWORK SET CONNECTIONS command or initialization parameter RETRY and NORETRY operands.

889

Examples NETWORK START CCONNECTIONS HOST(133.41.15.4) PORT(1220)TCP connection started Partner=133.41.15.4:1220, BufSize=4096, NoRetry

NETWORK START LISTENER PORT(1220)ESP3222I TCP listener started on port 1220

NETWORK START SERVICE TRACKINGESP3251I Network TRACKING service started

STOP operand

NORETRY Specifies that an unsuccessful NDS connection will not be retried.

Note: This initialization parameter overrides NETWORK SET CONNECTIONS command or initialization parameter RETRY and NORETRY operands.

LISTENER Starts an NDS listener.PORT(lport) Specifies the TCP/IP port number of the listener.SERVICE service Starts an NDS service. The following values are accepted:

• ROUTING—for remote ESP Encore requests (ESP Encore 3.1 and higher)

• TRACKING—for internodal job tracking

Operand Description

Operand DescriptionCONNECTIONS Stops one or all NDS connections.ALL Specifies that all NDS connections will be stopped.IDENTIFIER(id) Specifies the numeric identifier of the NDS connection that

will be stopped.

Note: You can determine the identifier with the NETWORK QUEUE DISPLAY command.

NETNODE(netnode) Specifies the remote NDS network node whose connection will be stopped.

HOST(host) Specifies the remote NDS host name or TCP/IP address whose connection will be stopped.

LISTENER Stops an NDS listener.

NETWORK Command: Control NDS

890

Examples MODIFY ESPM,NETWORK STOP CONNECTIONS NETNODE(NEWYORK_SYSA)N531_3241I NET STOP CONNECTIONSTCP connection stopped TCP transmitter ... 101.3.15.1:1220->133.41.15.4:3327 TCP receiver ...... 101.3.15.1:1220<-133.41.15.4:3328 Id=0, NetNode=NEWYORK_SYSA

NETWORK STOP LISTENER PORT(1220)ESP3223I TCP listener on port 1220 stopped

NETWORK STOP PENDING HOST(132.40.21.3)ESP3235I Pending connect to 132.40.21.3 stopped

NETWORK STOP SERVICE TRACKINGESP3252I Network TRACKING service stopped

PORT(lport) Specifies the TCP/IP port number of the listener that will be stopped.

PENDING Stops one or all pending NDS connections.

Note: Pending NDS connects are connections that are not yet successful and that have been set or started with an active RETRY operand. A NORETRY operand in the NETWORK START CONNECTION command overrides a RETRY operand in the NETWORK SET CONNECTIONS command.

ALL Specifies that all pending NDS connections will be stopped.HOST(host) Specifies the TCP/IP address (dotted decimal format or

DNS name) of the NDS network host whose pending connections will be stopped.

PORT(cport) Specifies the TCP/IP port number of the NDS network host whose pending connections will be stopped. The HOST operand is required when the PORT operand is used.

SERVICE service Stops an NDS service. The following values are accepted:• ROUTING—for remote ESP Encore requests (ESP

Encore 3.1 and higher)• TRACKING—for internodal job tracking

Operand Description

891

NEXT Command: Display Next Execution of Events

The NEXT command allows you to display the next scheduled executions of an Event. The NEXT command lets you specify the number of execution times you want to test, up to a maximum of 99. As long as your Event contains at least one SCHEDULE or EXPECT command, ESP computes the execution times and dates for the number of executions you specify.

TypeGeneral command.

SyntaxNEXT [count] eventid

Usage notesThe NEXT command simulates the schedule commands in an Event to compute the next n execution times. The use of the HOLD, RELEASE, SUSPEND, and RESUME commands affects the display.If an Event is suspended at the time of display, with no scheduled resume, ESP issues a message and no scheduled executions are displayed.

Related informationFor information on testing schedule criteria before using in an Event, see the TEST command.

Operand Description

count Indicates a number from 1 to 99, specifying the number of execution times you want to be displayed. The default is one.

eventid Indicates the name of an Event.

NEXT Command: Display Next Execution of Events

892

Examples Next five executionsIn the following example, the next five executions of CYBER.PAYROLL are displayed.NEXT 5 CYBER.PAYROLLSCHED AT 21.00.00 ON MONDAY FEBRUARY 2ND, 1999SCHED AT 21.00.00 ON TUESDAY FEBRUARY 3RD, 1999SCHED AT 21.00.00 ON WEDNESDAY FEBRUARY 4TH, 1999SCHED AT 21.00.00 ON THURSDAY FEBRUARY 5TH, 1999SCHED AT 21.00.00 ON FRIDAY FEBRUARY 6TH, 1999

Show Scheduled up to SuspendedIn the following example, the Event is suspended after February 22nd, 1998, with no scheduled resumption.ESP2494W NEXT PROCESSING ENDED AFTER 200 SUSPENDED SCHEDULESNEXT 10 CYBER.PAYROLLSCHED AT 17.00.00 ON WEDNESDAY FEBRUARY 18TH, 2004SCHED AT 17.00.00 ON THURSDAY FEBRUARY 19TH, 2004SCHED AT 17.00.00 ON FRIDAY FEBRUARY 20TH, 2004SCHED AT 17.00.00 ON SATURDAY FEBRUARY 21ST, 2004SCHED AT 17.00.00 ON SUNDAY FEBRUARY 22ND, 2004

Next five executions - one is heldThe following is an example of the output produced by the NEXT command:NEXT 5 CYBER.PAYROLLSCHED AT 17.00.00 ON WEDNESDAY FEBRUARY 18TH, 2004SCHED AT 17.00.00 ON THURSDAY FEBRUARY 19TH, 2004SCHED AT 17.00.00 ON FRIDAY FEBRUARY 20TH, 2004SCHED AT 17.00.00 ON SATURDAY FEBRUARY 21ST, 2004 HOLD(1)SCHED AT 17.00.00 ON SUNDAY FEBRUARY 22ND, 2004

In the above example, the Event is held at the time of execution and release prior to the next execution.

893

NJETOL Command: Set NJE tolerance

The NJETOL command sets or displays the tolerance for the time difference between the ESP Workload Manager time of submission and the reader-on time of a remote JES3 system on an NJE connection.Note: Jobs will stay in input submitted if held in the queue longer than the tolerance

set by NJETOL.

AuthorityYou must have OPER authority to issue the NJETOL command.

SyntaxNJETOL [time_before|500,time_after|500]

Usage notesIf you issue NJETOL without operands, the current tolerances are displayed.When using inter-system tracking, ESP Workload Manager must use the JES3 reader on time. A tolerance factor may be required to allow for a time difference between the ESP Workload Manager time of submission and the JES3 assigned reader on time at the JES3 execution node.This command is applicable regardless of the means of inter-system tracking (for example, NJE or LU6.2), but applies only to inter-nodal data received from a JES3 system.You shouldn’t increase the NJE tolerance past a ten minute window as this increases the chances of indiscriminate matches.

ExampleIn this example, the NJE tolerance is set to 30 seconds before or after the ESP Workload Manager submission time:NJETOL 3000,3000

Operand Descriptiontime_before|500 The look-back limit in hundredths of a second. The JES3 reader

on time can be time_before hundredths of a second before the ESP Workload Manager time of submission.

time_after|500 The look-ahead limit in hundredths of a second. The JES3 reader on time can be time_after hundredths of a second after the ESP Workload Manager time of submission.

NOCHECKEXC Statement: Do not Check Last Not Blank Character

894

NOCHECKEXC Statement: Do not Check Last Not Blank Character

The NOCHECKEXC statement is used to indicate that ESP should not check the last non-blank character of every card image written to the internal reader. The NOCHECKEXC statement cannot be used in an ESP Procedure.

TypeSymbolic variable library statement.

SyntaxNOCHECKEXC

Usage notesThe NOCHECKEXC statement is used in conjunction with the CHECKEXC statement which checks the last non-blank character of card images written to the internal reader. If the last character is a ¬ (not sign), the card image is deleted. NOCHECKEXC turns off the CHECKEXC feature. The default is NOCHECKEXC.

Related StatementsFor information on turning on the checking of the last non-blank character of every card image written to the internal reader, see the CHECKEXC statement.For information on selectively including JCL, see the %INCLUDE statement.For information on selectively excluding JCL, see the %EXCLUDE statement.

Example Turn off CHECKEXCIn the following example, coding NOCHECKEXC cancels, or turns off the CHECKEXC feature.NOCHECKEXC

895

NODE Command: Define System Nodes

The NODE command is used, together with the CPU command, to define the resource topology of your environment. The NODE command defines each system node.Note: You need a RESFILE only if you use resources.

TypeGeneral command.

SyntaxNODE name [ADD|DEL|LIST|SET] [ROUTEJCL('/* XEQ nnn')] [ACTIVE|INACTIVE] [SYSPLEX|NOSYSPLEX]

Operand Descriptionname Indicates the name to identify this NODE. This may correspond to

an existing JES node name or SMF ID or a group of Agents. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking with all operands except ADD.

ADD Indicates this is a new definition.DEL Deletes one or more existing definitions.LIST Displays list of one or more existing definitions. This is the

default.SET Modifies attributes of existing definitions.ROUTEJCL Indicates a JCL image that, when inserted into a job JCL, causes

the job to be routed to the appropriate node.ACTIVE Indicates a node be considered active. This is the default.INACTIVE Indicates a node be considered inactive. ESP Workload Manager

will not attempt to schedule a job to that node while it is inactive.SYSPLEX Indicates that this node belongs to the sysplex where ESP

Workload Manager is running. This operand is required for resources defined with the WLM operand. You use this operand when you want ESP Workload Manager to use WLM workload balancing.This operand is available only if the ESP Workload Manager High Performance Option (HPO) is installed.

NOSYSPLEX Indicates that this node does not belong to the sysplex where ESP Workload Manager is running. This is the default.

NODE Command: Define System Nodes

896

Usage notesFor information on defining the resource topology of your environment see the CPU, NODE, and RESFILE initialization parameter in the ESP Workload Manager Installation and Configuration Guide.You also need to define CPU after defining NODE.It is recommended that you use the CPU and NODE names that JES knows.

Related informationFor information on defining the resource topology of your network, see the CPU, NODE, and RESFILE operands in the ESP Workload Manager Installation and Configuration Guide.For information on Resources, see the ESP Workload Manager User’s Guide.Display all nodesIn the following example, all nodes defined as part of the resource topology are displayed:NODE - LIST

Define NODE and CPUIn the following example, a single node called TORONTO is defined, and a single CPU called T1 is defined as a member of the TORONTO node:NODE TORONTO ADDCPU T1 ADD NODE(TORONTO) CURRENT

Define NODE and CPU for WLM workload balancingThe following example defines two CPUs that belong to the Toronto nodeNODE TORONTO ADD SYSPLEXCPU T1 ADD NODE(TORONTO) CURRENTCPU T2 ADD NODE(TORONTO)

All the CPUs that have the same NODE operand in the CPU initialization parameter are linked. If you have HPO installed, ESP Workload Manager can balance the workload among the members belonging to one node, if the SYSPLEX operand is coded in the NODE command or initialization parameter. Refer to the ESP Workload Manager High Performance Option in the ESP Workload Manager User’s Guide for information on how to use WLM load balancing.Define NODE and CPU for Agent workload balancingThe following example defines:• 3 Windows NT cpus associated with Agents called AGwin1, AGwin2, and

AGwin3• 4 UNIX cpus associated with Agents called AGunix1, AGunix2, AGunix3, and

AGunix4

897

NODE WIN ADDNODE UNIX ADDCPU WIN1 ADD NODE(WIN)AGENT(AGwin1)CPU WIN2 ADD NODE(WIN)AGENT(AGwin2)CPU WIN3 ADD NODE(WIN)AGENT(AGwin3)CPU UNIX1 ADD NODE(UNIX)AGENT(AGunix1)CPU UNIX2 ADD NODE(UNIX)AGENT(AGunix2)CPU UNIX3 ADD NODE(UNIX)AGENT(AGunix3)CPU UNIX4 ADD NODE(UNIX)AGENT(AGunix4)

All the CPUs that have the same NODE operand in the CPU command or initialization parameter are linked. If you have HPO installed, ESP Workload Manager can balance the workload among the agents belonging to one node. Refer to the ESP Workload Manager High Performance Option in the ESP Workload Manager User’s Guide for information on how to use Agent workload balancing.

NORUN Statement: Do not Select Jobs

898

NORUN Statement: Do not Select Jobs

The NORUN statement is used to handle exceptions to a job’s regular schedule criteria. The NORUN statement tells ESP when not to select a job for submission.

SyntaxNORUN criteria

Usage notesThe NORUN statement is equivalent to: IF TODAY('schedule criteria') THEN DESELECT job.Multiple NORUN statements are allowed.Use the RUN statement to cause a job to be scheduled. When both RUN and NORUN statements are encountered, ESP uses the last one that applies. Therefore, you should normally specify RUN statements before NORUN statements.If a NORUN statement is used without a RUN statement for a job, the job is scheduled each time the Event executes except when the NORUN schedule criteria is satisfied.The NORUN statement can not be used in conjunction with the following scheduling terms: EVERY, UNTIL, ENDING, TOMORROW, YESTERDAY, and STARTING.The NORUN statement must be used within the scope of a JOB statement.

Related informationFor information on Applications, see the ESP Workload Manager User’s Guide.For information on specifying schedule criteria, see the ESP Workload Manager User’s Guide.For information on selecting jobs for submission, see the RUN, SELECT, POSTREQ, PREREQ and COREQ statements.

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time.

899

Examples First workday of monthIn the following example, PAYJOB1 is scheduled for submission on workdays, except on the first workday of the month.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYS NORUN FIRST WORKDAY OF MONTHENDJOB

First and last workdayIn the following PAYJOB2 is scheduled for submission every day, except on the first and last workday of each month.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB2 RUN DAILY NORUN FIRST WORKDAY OF MONTH NORUN LAST WORKDAY OF MONTHENDJOB

Except WednesdaysIn the following PAYJOB3 is scheduled for submission every time the Event invoking this Application executes, except on Wednesdays.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 NORUN WEDNESDAYENDJOB

If first workday of month is FridayIn the following example, PAYJOB4 is scheduled for submission on workdays. If today is the first Friday of the month and the first workday of the month, the job is not selected for submission.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB4 RUN WORKDAYS IF TODAY('FIRST FRI OF MONTH') AND - TODAY('FIRST WORKDAY OF MONTH') THEN NORUN TODAYENDJOB

NORUN Statement: Do not Select Jobs

900

First or last Friday of monthIn the following example, PAYJOB5 is scheduled for submission on Fridays. If today is the first Friday of the month, or the last Friday of the month, the job is not selected for submission.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB5 RUN FRIDAY NORUN FIRST FRIDAY OF MONTH NORUN LAST FRIDAY OF MONTHENDJOB

HolidayIndicates that a job is not selected for a submission on holidays:NORUN HOLIDAY

Multiple daysIndicates that a job is not selected for submission on the 3rd, 13th and the 23rd day of each month:NORUN 3RD 13TH 23RD DAY OF MONTH

First day at fiscalIndicates that a job is not selected for submission on the 1st day of the fiscal year:NORUN 1ST DAY OF FISCAL YEAR

Do not runIndicates that a job is not selected for submission, for example, the job is turned off:NORUN ANY

901

NOSCHED Command: Do Not Schedule Events

The NOSCHED command is used to specify when a scheduled Event should not execute.

TypeEvent definition command.

SyntaxNOSCHED criteria

Usage notesIn addition to a SCHEDULE command, use any number of NOSCHED commands to specify when an Event should not execute.Use the same time on your NOSCHED statement as on your SCHEDULE statement. If no time is specified on the NOSCHED statement, the default is 00:00. For example, if you say SCHEDULE 5PM, you should use NOSCHED 5PM.The NEXT command which lists the next execution times of an Event, reflects NOSCHED commands.

Related informationFor information on specifying schedule criteria, see the ESP Workload Manager User’s Guide.For information on specifying when an Event should execute, see the SCHEDULE command.For information on specifying when a job should not be scheduled, see the NORUN statement.

Examples Last workday of monthIn the following example, CYBER.PAYROLL is scheduled to execute every day at 5pm, except on the last workday of the month.EVENT ID(CYBER.PAYROLL)SCHEDULE 5PM DAILYNOSCHED 5PM LAST WORKDAY OF MONTHINVOKE 'CYBER.JCL.CNTL(PAYROLL)'ENDDEF

Operand Descriptioncriteria Schedule criteria

NOSCHED Command: Do Not Schedule Events

902

Specific orderIn the following example, CYBER.PAYROLL is scheduled to execute every day at 5pm, except on February 14th, 1998.EVENT ID(CYBER.PAYJOB)SCHEDULE 5PM DAILYNOSCHED 5PM FEBRUARY 14, 1998 ONCESUBMIT 'CYBER.JCL.CNTL(PAYJOB1)'ENDDEF

903

NOTIFY Statement: Notify Users or Consoles

The NOTIFY statement is used to notify users or consoles, or trigger an Event when one or more of the following conditions are met: SUBMIT, JOBSTART, RESUB, OVERDUE, ABEND, FAILURE, and JOBEND. The NOTIFY statement is available only for jobs belonging to Applications.

SyntaxNOTIFY [SUBMIT] [JOBSTART] [RESUB] [OVERDUE] [PREMEND] [ABEND] [FAILURE] [JOBEND] [USERS(userid[,userid]...)] [SYSTEM(name)] [ROUTE(rcode[,rcode]...)] [DESC(dcode[,dcode]...)] [ALERT(alertid)] [MAILBOX(box_name)]

Operand DescriptionSUBMIT Indicates notification should take place at job submit time. Issues message

4166 at SUBERROR.JOBSTART Indicates notification should take place at job start time.RESUB Indicates notification should take place when a job resubmitted through ESP

ends.OVERDUE Indicates notification should take place when a job becomes overdue from

any processing node or when a job execution time is longer than the time specified in the MAXRUNTIME symbolic variable.

PREMEND Indicates notification should take place when a job execution time is shorter than the time specified in the MINRUNTIME symbolic variable.

ABEND Indicates notification should take place when a job ABENDs. This excludes condition code failures.

FAILURE Indicates notification should take place when a job fails. This includes condition codes failures caused by either the CCCHK or CCFAIL statements. Issues message 4166 at SUBERROR.

NOTIFY Statement: Notify Users or Consoles

904

Usage notesThe Alert feature enables ESP Workload Manager to trigger an Event for all jobs, or only specific jobs, in an ESP Application.

To use the Alert feature, you need to take these three steps:1. Use the NOTIFY statement in an ESP Application to identify when to trigger the

Alert.2. Define the Alert with the ALERTDEF command.3. Define the Event triggered by the Alert.Alerts can be defined dynamically, for example, via Page mode, but are not retained across recycles of ESP. To ensure that alert definitions are retained across recycles of ESP Workload Manager, insert the appropriate ALERTDEF commands in the ESP Workload Manager initialization parameters.

JOBEND Indicates notification should take place when a job ends. This includes any job end (successful or unsuccessful). This Operand can also be specified as END.

USERS(userid) Indicates up to three TSO user IDs to receive notification.SYSTEM(name) Indicates the name of a sysplex member. This is not the ESP system name—it

is the name by which z/OS knows the member of the sysplex. Can be used to route a NOTIFY command in a sysplex environment to wherever the user is logged on. Use an asterisk to indicate the message goes wherever ESP is running.

ROUTE(rcode) Indicates route code value between 1 and 128 to receive notification. Separate each route code with a comma.

DESC(dcode) Indicates descriptor code value between 1 and 16 to receive notification. Separate each descriptor code with a comma.

ALERT(alertid) Specifies the four-character alert ID of the alert to be triggered when the specified conditions are met. The Event associated with the logical alert identifier is triggered. This logical identifier must have been previously specified using an ALERTDEF command. Alternatively, if you code ALERT(*), the Event that invoked the ESP Procedure containing the NOTIFY statement is triggered.

MAILBOX(box_name)

Specifies the name of a mailbox that contains the destination for messages coming from the NOTIFY command. Mailboxes must be defined in the MAILLIST data set. Mailbox names can have a maximum of 128 characters. Refer to the MAILLIST data set section in the ESP Workload Manager Installation and Configuration Guide for information on the MAILLIST data set.

Operand Description

905

Up to two global NOTIFY statements can be used. The NOTIFY statement can be used within the scope of a job statement in which case all global NOTIFY statements are overridden. Up to two NOTIFYstatements can be used within the scope of a job statement. For tasks and links, only NOTIFY SUBMIT applies.The mailbox feature enables ESP Workload Manager to send messages to all the TSO users and email addresses contained in a mailbox.To use the mailbox feature, you need to define the mailboxes in the MAILLIST data set and load that data set with the LOADNL command or initialization parameter. Refer to the ESP Workload Manager Installation and Configuration Guide for information on how to define mailboxes and the MAILLIST data set.

Related informationFor information on triggering Events automatically when workload reaches a particular stage in processing, see the ESP Workload Manager Advanced User’s Guide.

For information on defining and displaying alert definitions, see the ALERTDEF command.

Examples Notify when job startsIn the following example, when each job within the PAYROLL Application starts, users CYB01 and CYB02 receive notification:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'NOTIFY JOBSTART USERS(CYB01,CYB02)JOB PAYJOB1 REL PAYJOB2ENDJOBJOB PAYJOB2 REL PAYJOB3ENDJOBJOB PAYJOB3ENDJOBSELECT (PAYJOB1,PAYJOB2,PAYJOB3)

The notification is a pre-formatted message that looks like this:JOB PAYJOB1(J09368) STARTED AT 02.15.01 ON 01 FEB 98, APPL PAYROLL

NOTIFY Statement: Notify Users or Consoles

906

On ABENDIn the following example, if PAYJOB4 abends, notification is sent to user CYB01 and all consoles with route code 2. Descriptor code 2 is used to highlight the message:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB4 NOTIFY ABEND USERS(CYB01) ROUTE(2) DESC(2) RUN WORKDAYSENDJOB

Multiple notificationsIn the following example, notification is sent to user CYB01 for any job in the PAYROLL Application that abends, except for PAYJOB5, where notification is sent to user CYB02.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'NOTIFY ABEND USERS(CYB01)JOB PAYJOB5 NOTIFY ABEND USERS(CYB02) RUN WORKDAYS REL PAYJOB6ENDJOBJOB PAYJOB6 RUN WORKDAYSENDJOB

Trigger alertIn the following example, if any job within the PAYROLL Application abends, an alert Event associated with the INFO identifier is triggered.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'NOTIFY ABEND ALERT(INFO)JOB PAYJOB7 REL PAYJOB8ENDJOBJOB PAYJOB8ENDJOBSELECT (PAYJOB7,PAYJOB8)

Note: The INFO identifier is defined using the ALERTDEF command.

907

Trigger alert EventIn the following example, if any job within the PAYROLL Application becomes overdue, an alert Event associated with the LATE identifier is triggered.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'NOTIFY OVERDUE ALERT(LATE)JOB PAYJOB9 RUN WORKDAYS REL PAYJOB10ENDJOBJOB PAYJOB10 RUN WORKDAYSENDJOB

On start and endIn the following example, when each job within the PAYROLL Application starts and ends, user CYB01 receives notification.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'NOTIFY JOBSTART JOBEND USERS(CYB01)JOB PAYJOB11 RUN WORKDAYS REL PAYJOB12ENDJOBJOB PAYJOB12 RUN WORKDAYSENDJOB

Test reason for triggerIn the following example, this Application should be marked complete if a task called WAIT4.TAPE has not been marked complete by 7 pm. The ESP Procedure tests the MNJOB (monitor jobname) variable to see if ESP is invoking the Procedure due to the triggering of an Event or due to the ALERT keyword:• If MNJOB is a null string, ESP generates the Application• Otherwise, the ESP Procedure is being invoked by the Alert. ESP verifies the

monitor point and the name of the overdue job, and completes the Application./*Check invocationIF MNJOB NE " THEN DO IF MNPOINT='OVERDUE' AND MNJOB='WAIT4' AND MNQUAL='TAPE' THEN + ESP AJ ALL COMPLETE APPL(%MNAPPL..%MNAPPLGEN) EXITENDDO/*Regular processingAPPL TAPEJOBS

NOTIFY Statement: Notify Users or Consoles

908

JCLLIB 'CYBER.JCL.CNTL'NOTIFY OVERDUE ALERT(*)JOB WAIT4.TAPE TASK DUEOUT EXEC 7PM RUN DAILYRELEASE NEXTJOBENDJOBJOB NEXTJOB RUN DAILYENDJOB

Distributed workload objectThe user CYBUSER will be notified when the UNIX job CYBUSER1D is submitted, starts and ends, and if the job is overdue or fails.APPL TESTMANJCLLIB 'CYBUSER.JCL'JOB CYBUSER1D AGENT TORONTO SCRIPTNAME /usr/home/cybuser1d NOTIFY SUBMIT START END FAIL OVERDUE USER(CYBUSER) RUN DAILY DUEOUT 5PMENDJOB

Manual job with notifications using a mailboxWhen you submit manually job CYBER1M, the user CYBUSER will be notified when the job is submitted, starts and ends, and if the job is overdue or fails. The notification messages are sent to the recipients defined in the mailbox PAYROLL.APPL TESTMANJCLLIB 'CYBUSER.JCL'JOB CYBUSER1M MANUAL NOTIFY SUBMIT START END FAIL OVERDUE USER(CYBUSER)- MAILBOX(PAYROLL) DUEOUT EXEC

9AM RUN DAILYENDJOB

909

NOTWITH Statement: Specify Mutually Exclusive Jobs

The NOTWITH statement specifies jobs that are mutually exclusive with the current job. Consider the following guidelines before using NOTWITH:• Use ENQUEUE (versus NOTWITH) when you know which resource the jobs

require.• Use NOTWITH when you know that jobs cannot run together, but you do not

know why.Note: The NOTWITH and ENQUEUE statements use resources. Therefore, a

resource file (RESFILE) and the topology must be defined before you can use them.

SyntaxNOTWITH job1[.qual1][/appl1]| (job1[.qual1][/appl1],job2[.qual2][/appl2])

Usage notesThe NOTWITH feature uses ESP ENQUEUE to request certain explicitly specified jobs not be executed concurrently. The NOTWITH statement is used to inform ESP Workload Manager the job currently being defined is mutually exclusive with job1.qual1 in appl1 (or with a list of such jobs).

Examples: NOTWITH uses ESP ENQUEUEs for each specified job. NOTWITH will build a shared enqueue request in the following form:ESPENQ_JOB(job1.qual1)_APPL(appl.-)

The NOTWITH statement will set a flag informing ESP Workload Manager to generate an enqueue on the job itself (the job that has the NOTWITH). For example,APPL TESTJOB MYJOBNOTWITH BILLSJOB.-/* */ENDJOB

Operand Descriptionjob Specifies a job name. The job name can have a qualifier. The

Application name can be omitted; if omitted, it means any Application. Job name, qualifier, and Application name can contain wildcards.NOTWITH JOB1 means JOB1 that has no qualifier. NOTWITH JOB1.- means JOB1 with any qualifier.

NOTWITH Statement: Specify Mutually Exclusive Jobs

910

Note: The /* */ at the end of the third line prevent the hyphen to be interpreted as a continuation character.

This will result in JOB MYJOB having two enqueues:ESPENQ_JOB(MYJOB.)_APPL(TEST.21)ExclusiveESPENQ_JOB(BILLSJOB.-)_APPL(-.-)Shared

If job BILLSJOB.qual has a NOTWITH statement or ENQSELF is set to ALWAYS, job BILLSJOB.qual in BILLSAPPL.10 enqueues on itself it will have at least the following enqueue:ESPENQ_JOB(BILLSJOB.qual)_APPL(BILLSAPPL.10)Exclusive

This together with job MYJOB’s shared enqueue will prevent the two jobs from running together.

Examples of ESP ENQUEUES with NOTWITHAPPL NWN00CJCLLIB ‘CYBER.JCL.CNTL’

JOB NWN001 RUN WEEKDAYS NOTWITH NWN003ENDJOB

JOB NWN002 RUN WEEKDAYSENDJOB

JOB NWN003 RUN WEEKDAYS NOTWITH NWN001ENDJOB

The above ESP Application produced the following display from the ENQUEUE command. The ENQUEUE command displays the current enqueue status in the resource file. For more information, see the ENQUEUE Command in ESP Workload Manager Reference Guide Volume 1. ESPENQ_JOB(NWN001.)_APPL(-.-) Required Shr NWN003, Appl NWN00C.1ESPENQ_JOB(NWN001.)_APPL(NWN00C.1) Held Excl NWN001, Appl NWN00C.1 (Gen) Required Shr NWN003, Appl NWN00C.1ESPENQ_JOB(NWN003.)_APPL(NWN00C.1) (Gen) Held Shr NWN001, Appl NWN00C.1 Required Excl NWN003, Appl NWN00C.1

In the above display, job NWN001 has an exclusive enqueue on itself and has a shared enqueue on job NWN003. Job NWN003 requests an exclusive enqueue on itself and a shared enqueue on job NWN001. This prevents the jobs from running together.

911

In the following example, job NWN003 has no NOTWITH statement so it will execute at the same time as job NWN001. Job NWN003 must have a NOTWITH NWN001 statement to be mutually exclusive with job NWN001, unless ENQSELF is set to ALLWAYS.APPL NWN00DJCLLIB ‘CYBER.JCL.CNTL’

JOB NWN001 RUN WEEKDAYS NOTWITH NWN003ENDJOB

JOB NWN002 RUN WEEKDAYS ENDJOB

JOB NWN003 RUN WEEKDAYS ENDJOB

You may use unmatched NOTWITH statements in combination with the ENQSELF command. For more information, see the ENQSELF Command in ESP Workload Manager Reference Guide Volume 1.

NT_JOB Statement: Identify the Name of Windows Jobs

912

NT_JOB Statement: Identify the Name of Windows Jobs

Identifies the start of a unit of work within the Application. It defines the start of a job that runs on a Windows machine and defines the name of the job.

TypeApplication statement.

SyntaxRefer to the JOB statement syntax.

Usage notesThe NT_JOB statement defines the beginning of a Windows job definition. The ENDJOB statement, or another JOB or NT_JOB statement, signifies the end of a job definition.

Refer to the JOB statement usage notes.

ExampleThe PAYROLL Application contains job PAYDATA, which runs on Agent NT_NY.APPL PAYROLL

NT_JOB PAYDATA RUN DAILY RELEASE PAYRPT AGENT NT_NY CMDNAME c:\data\pay.cmdENDJOB

913

NTRCLASS Command: No Track Class

The NTRCLASS command specifies a job execution class to exclude from tracking. This turns off the collection of SMF records type 26 and 30 for the specified class.

TypeOPER command.

Where definedTracking ESP Workload Manager subsystem.

SyntaxNTRCLASS class

RestrictionsOnly one NTRCLASS command can be active. If you issue more than one, the last command is used.

Usage noteThis option is to be used with caution. If it is turned on you can change class but there are no explicit operands to turn it off. To turn it off, you must issue the command with a class value that does not exist. # is the only character accepted by NTRCLASS that cannot represent a class. To turn NTRCLASS off you can issue: NTRCLASS #

Note: The effect of the NTRCLASS option remains active even when ESP Workload Manager is restarted. If you re-IPL the system, the NTRCLASS initialization parameter in the initialization parameter data set becomes active. If you do not code any NTRCLASS initialization parameter, no class will be excluded.

ExampleNTRCLASS Z

Operand Descriptionclass Specifies the class of jobs to exclude from tracking. It is one

alphanumeric character.

NULLPSWD Command: Specify Password

914

NULLPSWD Command: Specify Password

The NULLPSWD command specifies a password to be compared to the PASSWORD parameter of a JOB card.

TypeAuthorized oper command.

SyntaxNULLPSWD password

Usage notesThe following table indicates whether the submission of a job will succeed or fail assuming that the job can be run only by a user with the password ABC:

Operand Descriptionpassword Specifies the password to be compared to the PASSWORD

parameter of a JOB card. It is eight characters maximum.

User password PASSWORD parameter in

JOB card

NULLPSWD Command

Result

ABC ABC Ignored succeedABC Omitted Ignored succeedABC XYZ XYZ succeedABC XYZ xxx (Not XYZ) fail

915

OOA_JOB Statement: Start an Oracle Applications Job Definition

The OA_JOB statement starts an Oracle Applications job definition.

SyntaxRefer to the JOB statement syntax.

UsageTo schedule Oracle Applications jobs, you must load the workload object module CYBESOOA. Load CYBESOOA with the WOBDEF command or with the WOBDEF initialization parameter.The following statements are mandatory:• OA_USER• RESPNAME• APPLDISPLNAME or APPLSHORTNAME• PROGRAM or REQUESTSET• RUN• ENDJOBNote: To avoid having to define OA_USER and RESPNAME for every Application,

you can ask your System Administrator to define default values in the Agent parameter file.

You can include the following OA statements within an OA_JOB workload object. For more information on a particular statement, see the entry for that statement in this reference guide.

All OA_JOBs Single Requests Only Request Sets OnlyOA_USER PROGRAM REQUESTSETRESPNAME DESCRIPTION PROGDATAAPPLDISPLNAME ARGS PROGARGSAPPLSHORTNAME PROGSAVEOUTPUTARGDEFAULTS PROGPRINTERSAVEOUTPUT PROGPRINTSTYLEPRINTER PROGPRINTCOPIESPRINTSTYLEPRINTCOPIESCHILDMONITOR

OA_JOB Statement: Start an Oracle Applications Job Definition

916

ExamplesOracle Applications Single RequestIn this example, the OA_Job AOL1806.AP034 runs the Single Request XXCOFI on the Oracle Applications system.APPL ACC01 AGENT CYBOA OA_JOB AOL1806.AP034 PROGRAM XXCOFI RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN ENDJOB

Oracle Applications Request SetIn this example, the OA_Job AOL405.AP035 runs the Request Set DATA10 on the Oracle Applications system.APPL ACC02 AGENT CYBOA OA_JOB AOL405.AP035 REQUESTSET DATA10 RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN ENDJOB

MONITORDELAYAll OA_JOBs Single Requests Only Request Sets Only

917

OAUSER Statement: Identify an Oracle Applications User Name

The OAUSER statement identifies the Oracle Applications user name.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

SyntaxOAUSER name

Usage notesOAUSER can be defined in two places.• To set OAUSER for a specific job, define it in the job definition.• To set the default for all jobs run by an Agent, ask your System Administrator to

define the oa.default.user property in the Agent parameter file.OAUSER is mandatory, and must be defined in at least one of the two places.

ExamplesIdentify an Oracle Applications user nameIn the following example, the user name for the Application Object Library Oracle Applications application is SYSADMIN.APPL ACC06 AGENT CYBOA OA_JOB AOL1807.AP034 PROGRAM XXCOFI RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN ENDJOB

Operand Descriptionname The name must match an existing Oracle Applications user name.

Characters are case-sensitive. Maximum 100 characters.

ON Command: Specify Actions Based on Type of Day

918

ON Command: Specify Actions Based on Type of Day

The ON command is used in conjunction with the SCHEDULE command to advance, delay or ignore Event processing if the Event falls on a holiday, weekday, weekend, or particular day of the week.

TypeEvent definition command.

SyntaxON type {ADVANCE} {DELAY} {IGNORE} [n DAYS] [n WEEKDAYS]

Usage notesYou must use the keyword HOLIDAY, which includes all holidays in the calendars associated with the Event. You cannot use a specific holiday name, such as CHRISTMAS.

Operand Descriptiontype Indicates a type of day. This can be any of the following:

• HOLIDAY—Installation defined holidays. The LISTHOL command is used to display the holidays currently defined by the installation.

• WEEKDAY—Any day of the week except Saturday and Sunday.• WEEKEND—A Saturday or Sunday.• dayname—The name of a single day of the week, for example, Saturday,

Monday.ADVANCE Indicates the Event is to be advanced (for example, run earlier) by a specified

number of days or weekdays.DELAY Indicates the Event is to be delayed (for example, run later) by a specified

number of days or weekdays.IGNORE Specifies if the Event falls on one of the specified days, it is to be bypassed.n Indicates the number of days or weekdays the Event is to be advanced or

delayed.DAYS Indicates n equals the number of days for the schedule to be advanced or delayed.

This includes Saturdays and Sundays.WEEKDAYS Indicates n equals the number of weekdays for the schedule to be advanced or

delayed. This excludes Saturdays and Sundays.

919

Your scheduling criteria for Event execution may create conflicts. For example, if you want the Event to execute on the second day of every month, but it cannot run on a weekend, tell ESP to either:• Advance the Event (run it sooner than usual) by any number of days or weekdays• Delay the event (run it later than usual) by any number of days or weekdays• Ignore the Event (do not run it at all).If the processing of an ON command results in an Event time earlier than the previous execution of the Event, that schedule time is ignored. An ON statement affects only the scheduling of an Event through a SCHEDULE statement. SUSPEND, RESUME, HOLD and RELEASE are not subject to ON condition testing.Use the NEXT command to display the next execution times of an Event. Changes due to an ON statement are reflected.

Related informationFor information on Events, see Processing ESP Events in the ESP Workload Manager User’s Guide.For information on scheduling criteria, see Schedule Criteria in the ESP Workload Manager User’s Guide.For information on specifying when a scheduled Event should not execute, see the NOSCHED command.

Examples Delay on holidayThe following is an example of a scheduled Event definition that delays the Event execution on a specific day. In the following example, CYBER.PAYROLL is scheduled at 6 am every 14 days. When a particular Monday falls on a holiday, the Event is delayed by one day. If the next day is also a holiday, the Event is delayed again until it falls on a day that is not a holiday. However, to calculate the next Event time, 14 days are added to the original Monday, even though it was a holiday.EVENT ID(CYBER.PAYROLL)SCHEDULE MONDAY AT 6AM EVERY 14 DAYSON HOLIDAY DELAY 1 DAYINVOKE 'CYBER.PROCLIB.CNTL(PAYROLL)'ENDDEF

ON Command: Specify Actions Based on Type of Day

920

Advance on holidayIn the following example, CYBER.PAYROLL is schedule at 4 pm on the 15th day of the month. On holidays, the Event is advanced 1 day. EVENT ID(CYBER.PAYROLL)SCHEDULE 4PM 15TH DAY OF MONTHON HOLIDAY ADVANCE 1 DAYINVOKE 'CYBER.PROCLIB.CNTL(PAYROLL)'ENDDEF

Ignore on holidayIn the following example, CYBER.PAYROLL is scheduled on the first day of the month. On holidays the Event is bypassed.EVENT ID(CYBER.PAYROLL)SCHEDULE FIRST DAY OF THE MONTHON HOLIDAY IGNOREINVOKE 'CYBER.PROCLIB.CNTL(PAYROLL)'ENDDEF

Delay one week on holidayIn the following example, CYBER.PAYROLL is scheduled at 8 am on the first day of the month. On holidays, the Event is delayed 7 days.EVENT ID(CYBER.PAYROLL)SCHEDULE 8AM FIRST DAY OF MONTHON HOLIDAY DELAY 7 DAYSINVOKE 'CYBER.PROCLIB.CNTL(PAYROLL)'ENDDEF

Delay one weekday on holidayThe following is an example of a scheduled Event definition that delays the Event execution on holidays: EVENT ID(CYBER.PAYROLL)SCHEDULE 4PM 15TH DAY OF MONTHON HOLIDAY DELAY 1 WEEKDAYINVOKE 'CYBER.PROCLIB.CNTL(PAYROLL)'ENDDEF

In the above example, CYBER.PAYROLL is scheduled at 4 pm on the 15th day of the month. On holidays, the Event is delayed 1 weekday.

921

OPENVMS_JOB Statement: Identify the Name of OPENVMS Jobs

The OPENVMS_JOB statement is used to identify the name of an OPENVMS job in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use OPENVMS jobs, you must load a workload object module. The OPENVMS_JOB workload object module is CYBESOOV. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Refer to the JOB statement usage notes.

Examples:The following is an example of an OpenVMS JOB statement using the full JOB statement:OPENVMS_JOB payroll2.paypgm

The following is an example of an OpenVMS JOB statement using the abbreviated syntax:OV payroll2.paypgm

In both examples, the OPENVMS_JOB statement identifies the workload object as an OpenVMS job called payroll2.paypgm.

OPTIONS Statement: Override Default Options

922

OPTIONS Statement: Override Default Options

The OPTIONS statement is used to override the default processing options for jobs belonging to Applications.

SyntaxOPTIONS [INHERIT|NOINHERIT] [GENNET|NOGENNET] [MANUALSUBMIT|NOMANUALSUBMIT| [TRACKMANUAL|NOTRACKMANUAL] [AUTOVARS|NOAUTOVARS] [RESTARTSTEP|NORESTARTSTEP] [DUEOUTPROPAGATION|NODUEOUTPROPAGATION]

Operand DescriptionINHERIT Indicates job relationships are inherited. This is the default.NOINHERIT Indicates job relationships are not inherited.GENNET Indicates DJC/JES3 NET control cards are generated for jobs in

a DJCNET. This is not applicable to ESP Applications. This is the default.

NOGENNET Indicates DJC/JES3 NET control cards are not generated for jobs in a network. This can be used if the jobs you are submitting already have NET control cards.

MANUALSUBMIT Indicates jobs are manually submitted.NOMANUALSUBMIT Indicates jobs will not be manually submitted. This is the

default.TRACKMANUAL Indicates jobs are tracked manually.NOTRACKMANUAL Indicates jobs are not tracked manually.AUTOVARS Indicates ESP allows the use of the automatic variable insertion

feature. This is the default.NOAUTOVARS Indicates ESP does not allow the use of the automatic variable

insertion feature.RESTARTSTEP Indicates a restart step is added to each job in an Application as

identified by the ERMSTEP initialization parameter.

Note: This operand applies only if you have ESP Encore installed.

923

Usage notesThe OPTIONS statement is normally used before your job definitions. OPTIONS RESTARTSTEP/NORESTARTSTEP is available at the job level as well as the subApplication level for jobs in an Application.You can use different keywords on a JOB statement to override the MANUALSUBMIT/NOMANUALSUBMIT and the INHERIT/NOINHERIT options.It is not necessary to specify NOGENNET for jobs defined in an Application.If the OPTIONS statement is omitted, due out times will be propagated to a job predecessor in the Application if USERMOD 33 is not set and not propagated if USERMOD 33 is set.If the DUEOUTPROPAGATION or NODUEOUTPROPAGATION operands are specified, the USERMOD 33 setting is ignored.

Related informationFor information on Applications, see the ESP Workload Manager User’s Guide.For information on overriding inherited relationships, see the Advanced Use of ESP Procedures chapter in the ESP Workload Manager Advanced User’s Guide.For information on using the automatic variable insertion feature, see the Tailoring JCL chapter of the ESP Workload Manager Advanced User’s Guide.For information on adding a restart step, see the Tailoring JCL chapter of the ESP Workload Manager Advanced User’s Guide.For information on rerunning/restarting jobs belonging to Applications, see the ESP Encore User’s Guide.

NORESTARTSTEP Indicates a restart step is not added to each job in an Application. This is the default.

Note: This operand applies only if you have ESP Encore installed.

DUEOUTPROPAGATION Specifies that due out times will be propagated to a job predecessor in the Application. This is the default if USERMOD 33 is not set.

NODUEOUTPROPAGATION Specifies that due out times will not be propagated to a job predecessor in the Application. This is the default if USERMOD 33 is set.

Operand Description

OPTIONS Statement: Override Default Options

924

Examples In the following example, the OPTIONS RESTARTSTEP statement is used to add a restart step to each job in the PAYROLL Application, except for PAYJOB3.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'OPTIONS RESTARTSTEPJOB PAYJOB1 RUN DAILY REL PAYJOB2JOB PAYJOB2 RUN DAILY REL PAYJOB3JOB PAYJOB3 RUN DAILY OPTIONS NORESTARTSTEPENDJOB

Do not inherit relationshipsIn the following example, the OPTIONS NOINHERIT statement is used to indicate that successors to a job are not to inherit job relationships and that relationships among a job and its successors exist only if there is a definition stating the relationship. If it is not Friday, no relationship exists between PAYJOB4 and PAYJOB6.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'OPTIONS NOINHERITJOB PAYJOB4 RUN DAILY REL PAYJOB5 JOB PAYJOB5 RUN FRIDAY REL PAYJOB6JOB PAYJOB6 RUN DAILY ENDJOB

Add a restart step to subApplicationIn the following example, the OPTIONS RESTARTSTEP statement is used at the subApplication level to add a restart step to each job in the PAYABLE subApplication.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL' JOB RECJOB1 SUBAPPL RECEIVE RUN DAILY REL RECJOB2JOB RECJOB2

925

SUBAPPL RECEIVE RUN DAILYENDJOBOPTIONS RESTARTSTEP JOB PAYJOB1 SUBAPPL PAYABLE REL PAYJOB2 RUN DAILY JOB PAYJOB2 SUBAPPL PAYABLE RUN DAILYENDJOB

Manually submitted jobsIn the following example, the OPTIONS MANUALSUBMIT statement is used to identify each job in the PAYROLL Application as manually submitted. This is useful when another product is submitting work and you want to monitor this work through the CSF.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'OPTIONS MANUALSUBMITJOB PAYJOB6 RUN DAILY REL PAYJOB7JOB PAYJOB7 RUN DAILY REL PAYJOB8JOB PAYJOB8 RUN DAILY ENDJOB

OTHERS Statement: Specify Additional Parameters (OS/400)

926

OTHERS Statement: Specify Additional Parameters (OS/400)

The OTHERS statement is used only when defining jobs for the OS/400 agent to specify additional parameters to be passed to the OS/400 SBMJOB command. The OTHERS statement can be used within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition, to apply to the entire application.

TypeESP Workload Manager Application Statement

SyntaxOTHERS Keyword(value)

Usage notesAll keyword and value combinations specified with the OTHERS statement are passed to the SBMJOB command. No validity checking takes place on what is entered.The agent uses the user’s default output queue if the USER statement is used in a job definition and if the OTHERS statement does not include the SBMJOB OUTQ( ) command keyword and value to define the output queue for the job.

ExampleDefine the printer and output queue for an OS/400 jobOTHERS PRTDEV(*JOBD) OUTQ(*JOBD)

In the above example, printer and output queue information is taken from the job description.

Operand DescriptionKeyword (value) Specifies any valid SBMJOB command keyword and value

combination. Multiple combinations can be specified.

927

OUTDESTFORMAT Statement: Specify Output Destination Format (PeopleSoft)

The OUTDESTFORMAT statement specifies the output destination format in a job definition.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

SyntaxOUTDESTFORMAT format

Operand Descriptionformat A listing of all output destination formats can be found in the

table PSXLATITEM. The format can be specified by field number or field name. The length is up to eight characters.

Field Number

Field Name

Description

0123456789101112131415161718

AnyNonePDFCSVHPHTMLPWKSXLSDOCPSRPTRTFSPFTXTOTHERDefaultXMLDAT

Any (None)Acrobat (*.pdf)Comma delimited (*.csv)HP Format (*.lis)HTML Documents (*.htm)Line printer format (*.lis)Lotus 1-2-3 filesMicrosoft Excel Files (*.xls)Microsoft Word (*.doc)Postscript (*.lis)Crystal Report (*.rpt)Rich Text File (*.rtf)SQR Portable Format (*.spf)Text Files (*.txt)OtherDefaultXML Format (*.xml)Data Mover Data File (*.dat)

OUTDESTFORMAT Statement: Specify Output Destination Format (PeopleSoft)

928

Usage notesThe format operand can also be specified as a default in the agentparm.txt file as follows:ps.default.outDestFormat=<format>

Note: The value in the job definition will override the value specified in the agentparm.txt file.

ExampleIn this example, an output destination type of file is specified with the file format of text.PS_JOB PAYREPRT RUN FRIDAYS AGENT PS_NY OUTDESTTYPE FILE OUTDESTFORMAT TXT PROCESSNAME program_name PROCESSTYPE 'Application Engine' RUNCONTROLID PS_ALLENDJOB

929

OUTDESTPATH Statement: Specify Path of Output (PeopleSoft)

The OUTDESTPATH specifies the path of the output.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

SyntaxOUTDESTPATH file_path|printer_path

Usage notesThe OUTDESTPATH statement is used only when OUTDESTTYPE of FILE or PRINTER is specified as an output destination type in the job-definition statement (see “OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft)” on page 931). If you do not specify the file_path or the printer_path, the output will be directed as follows:• For FILE, the output will go to the PeopleSoft log/output directory.• For PRINTER, the output will be directed to lpt1.

Note: This printer must be set up on the PeopleSoft side. You can overwrite it by specifying a value for the ps.default.printer parameter in the agentparm.txt file.

Operand Descriptionfile_path The path statement to the output directory and the output file

name. Enclose the file_path in single quotes. The file_path can be up to 127 characters in length.

printer_path The network location of the printer including the printer server and shared printer name. Enclose the printer_path in single quotes. The printer_path can be up to 127 characters in length.

OUTDESTPATH Statement: Specify Path of Output (PeopleSoft)

930

ExamplesExample of file_pathFILE is specified for the output destination type.PS_JOB DSTYPE.FILE AGENT PS_NY RUN FRIDAYS PROCESSNAME XRFWIN PROCESSTYPE 'SQR Report' OUTDESTTYPE FILE OUTDESTFORMAT PDF OUTDESTPATH '/export/home/PSoutput/report1.pdf' RUNCONTROLID test PSOPRID VP1ENDJOB

Note: For a Windows NT example, substitute a Windows path in the OUTDESTPATH statement.

Example of printer_pathPRINTER is specified for an output destination type.PS_JOB DSTYPE.PRINTER AGENT PS_NY RUN FRIDAYS PROCESSNAME XRFWIN PROCESSTYPE 'SQR Report' OUTDESTTYPE PRINTER OUTDESTFORMAT PS OUTDESTPATH '\\CYBERMATION\PRINTER1' RUNCONTROLID test PSOPRID VP1ENDJOB

931

OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft)

The OUTDESTTYPE statement specifies the output destination format in a job definition.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

SyntaxOUTDESTFORMAT type

Usage notesThe type operand can also be specified as a default in the agentparm.txt file as follows:ps.default.outDestType=<type>

Note: The value in the job definition will override the value specified in the agentparm.txt file.

Operand Descriptiontype A listing of all output destination formats can be found in the

table PSXLATITEM. The type can be specified by field number or field name.

Field Number

Field Name (short form)

01234567

ANY (A)NONE (N)FILE (F)PRINTER (P)WINDOW (WI)EMAIL (E)WEB (WE)DEFAULT (D)

OUTDESTTYPE Statement: Specify Output Destination Format (PeopleSoft)

932

ExamplesExample of EMAIL output destinationAn output destination type of EMAIL is specified with the file format of PDF.PS_JOB SEND.EMAIL PROCESSNAME XRFWIN PROCESSTYPE Crystal OUTDESTTYPE EMAIL OUTDESTFORMAT PDF PSOPRID VP2 RUN DAILYENDJOB

Example of PRINTER output destinationAn output destination type of PRINTER is specified.PS_JOB DSTYPE.PRINTER PROCESSTYPE 'SQR Report' PROCESSNAME XRFWIN OUTDESTFORMAT PS OUTDESTTYPE PRINTER OUTDESTPATH \\CYBERMATION\PRINTER1 RUN DAILYENDJOB

933

PPANSUB Command: Submit JCL From Panvalet

The PANSUB command is used to submit JCL from a Panvalet data set to the internal reader.

TypeEvent definition command.

SyntaxPANSUB dsname[(member)] [MEMBER(member)]

Usage NotesSeveral PANSUB commands may be specified in a single Event. The input data are effectively concatenated together, so that data from several data sets can be joined to form one or more jobs.In the same Event you can also use the SUBMIT command, and submit JCL from ROSCOE and LIBRARIAN data sets.To submit JCL from a PANVALET library as part of an Application, use PAN- as a prefix for your data set name on the JCLLIB statement.

Related informationFor information on submitting JCL from an Event, see the ESP Workload Manager User’s Guide.

Examples Sample Event definitionIn the following example, PAYJOB1 is submitted from PANVALET data set PANDS.DATA.EVENT ID(CYBER.PANJOB1)SCHEDULE 9AM FIRST MONDAY OF MONTHPANSUB PANDS.DATA(PAYJOB1)ENDDEF

Operand Descriptiondsname Indicates a valid PANVALET data set name. You do not have to

specify PAN- as a data set identifier because using the PANSUB command implies the use of a PANVALET data set.

member Indicates a member name, which can consists of up to eight characters if specified as part of the data set name or up to ten characters as a operand of the MEMBER keyword.

PANSUB Command: Submit JCL From Panvalet

934

Specific memberIn the following example, LONGJOB999 is submitted from PANVALET data set CYB.JCL. Using the MEMBER keyword allows names up to 10 characters.EVENT ID(CYBER.PANJOB2)SCHEDULE 7PM LAST WORKDAY OF MONTHPANSUB CYB.JCL MEMBER(LONGJOB999)ENDDEF

935

PARAM Statement: Specify Additional Parameters (OS/400)

The PARAM statement is used only when defining jobs for the OS/400 Agent to specify additional parameters to be passed to an OS/400 program. It is used within the boundaries of a job definition. You can specify multiple PARAM statements within an Application.

TypeESP Application Statement

SyntaxPARAM {value|(value[value2...])}

ExamplePass multiple parameters to an OS/400 programThe following is an example containing the PARAM statement:APPL INVENTORYAS400_JOB MFGDATA RUN DAILY RELEASE MFGSORT AGENT AS401 CLPNAME MFGTEST.DATA AS400LIB PRODJOBS PARAM 'ABC' '1' 'P'ENDJOB

In this example, three parameters are passed to the OS/400 program: ABC, 1, and P.

Operand Descriptionvalue Specifies the value of a parameter. You can specify multiple values

with a single PARAM statement by enclosing each value in single quotes and separating the values with a space.

PARAM Statement: Define InfoPackage Data Selection Criteria (SAP)

936

PARAM Statement: Define InfoPackage Data Selection Criteria (SAP)

The PARAM statement defines the data selection criteria of a Business Warehouse InfoPackage (BWIP) on the SAP system.

ApplicabilityESP Business Agents for SAP, Release 5, Service Pack 1 and higher, used within a BWIP_JOB workload object.

SyntaxPARAM FieldName, {ObjectName|""}, {Sign|""}, {Operation|""}, {LowValue|""}, {HighValue|""}

Usage notesYou can use multiple PARAM statements to retrieve the required data.Note: All operands are positional.

Operand DescriptionFieldName Specifies the Business Warehouse InfoPackage Technical

Name. FieldName is case-sensitive and can be up to 30 valid SAP characters. Field Name is mandatory.

ObjectName Specifies the Business Warehouse InfoPackage InfoObject. ObjectName is case-sensitive and can be up to 30 valid SAP characters. If no value is assigned to ObjectName, use two double quotation marks ("") as a place holder.

Sign Specifies the Business Warehouse InfoPackage Sign. Sign is one of either I (Include) or E (Exclude). If no value is assigned to Sign, use two double quotation marks ("") as a place holder.

Operation Specifies the Business Warehouse InfoPackage Operation. Operation is one of either BT (between) or EQ (equal). If no value is assigned to Operation, use two double quotation marks ("") as a place holder.

LowValue Specifies the Business Warehouse InfoPackage From Value. If no value is assigned to LowValue, use two double quotation marks ("") as a place holder.

HighValue Specifies the Business Warehouse InfoPackage To Value. If no value is assigned to HighValue, use two double quotation marks ("") as a place holder.

937

The fields on the PARAM statement correspond to the fields on the SAP Administrator Workbench RSA1 transaction.Separate the values for Sign, Operation, Low Value, or High Value with a comma.

ExampleIn this example, the data selection criteria for the FieldNames (SAP InfoObjects) /BIC/IO_CMAT, CALDAY, /BIC/ IO_CCUST, and /BIC/IO_CSREP are defined for InfoPackage ZPAK_42RRVI7G0PA005H00BV0ZJV9I on the SAP system. For the /BIC/IO_CMAT and CALDAY FieldNames, values are provided for each operand.For the /BIC/IO_CCUST FieldName, double quotation marks are used as place markers for Object Name, Sign, Operation, and Low Value. For the /BIC/IO_CSREP FieldName, double quotation marks are used as place markers for Object Name, Sign, Operation, Low Value, and HighValue.ABWIP_JOB IP05 AGENT SAPHTNTAGENT SAPJOBNAME IP05 INFOPACK 'ZPAK_42RRVI7G0PA005H00BV0ZJV9I' RFCDEST bw2 RUN DAILY PARAM /BIC/IO_CMAT, IO_CMAT, I, BT, MAT001, MAT002 PARAM CALDAY, 0CALDAY, I, BT, 20010101, 20050101 PARAM /BIC/IO_CCUST, "", "", "", CUST001,CUST003 PARAM /BIC/IO_CSREP, "", "", "", "", ""ENDJOB

PARAMETER Statement: Specify the Method/Message Parameters (J2EE)

938

PARAMETER Statement: Specify the Method/MessageParameters (J2EE)

For EJB jobs, the PARAMETER statement specifies the parameters of the EJB Method to be invoked remotely. For JMS Publish jobs, the PARAMETER statement specifies the parameters of the Java class of the Message.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within the EJB_JOB and JMSP_JOB workload objects

SyntaxPARAMETER TYPE(package.class) VALUE(value)

Usage notesPARAMETER is an optional statement within the EJB_JOB and JMSP_JOB workload objects.To specify multiple parameters, use multiple PARAMETER statements. Order is important. If the Method contains three parameters, specify the first parameter in the first statement, the second parameter in the second statement, and the third parameter in the third statement. The job fails if the parameters are listed in the wrong order.

Operand DescriptionTYPE(package.class) The Java class of a Method parameter or a Message

constructor parameter. package.class is case sensitive and can be up to 1024 characters. package.class is mandatory.

Note: Referenced Java classes must have a constructor that accepts java.lang.String as a parameter. If a package is unspecified, java.lang is used.

VALUE(value) The java.lang.String parameter value of the constructor. value is case sensitive and can be up to 1024 characters. If value contains delimiters (such as spaces), enclose it in single quotes.

939

ExamplesEJB jobIn this example, the CYBJK.SB job remotely invokes the reverse method. The reverse method has one parameter, a java.lang.String object with the value A23.APPL TESTSBEJB_JOB CYBJK.SB HOLD RUN DAILY AGENT CYBNT BEAN CybEJBTestBean METHOD reverse INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 DEST ’c:\Program Files\Common Files\System\ado\Makapt15.txt’ PARAMETER TYPE(String) VALUE(A23)ENDJOB

JMS Publish jobIn this example, the CYBJK.JP job publishes a simple message to the Queue named Queue. The parameter is a java.lang.String object. Since the message contains spaces, it is enclosed in single quotes. APPL TESTJPJMSP_JOB CYBJK.JP HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DESTNAME Queue TOPIC N MSGCLASS String JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 PARAMETER TYPE(String) VALUE(’this is my message’)ENDJOB

PASSWORD Command: Define Agent User IDs and Passwords

940

PASSWORD Command: Define Agent User IDs and Passwords

The PASSWORD command is used to define and securely store a user ID/password pair. Passwords defined using the PASSWORD command are encrypted and stored in a data set for later use. All jobs using virtual agents will require a password to login to Telnet.When a USER statement is coded in an OpenVMS_JOB, Tandem_JOB, SAP_JOB, or NT_JOB definition without a PASSWORD statement, a search takes place for an entry matching the specified user ID with a type of OpenVMS_JOB, Tandem_Job, SAP_JOB, or NT_Job and a qualifier equal to the Agent name specified in the ESP procedure. This search returns a password that most closely matches these parameters. If there are no matching entries, an entry with no type or qualifier is returned.

TypeGeneral Command

AuthorityYou need to have UPDATE authority with the PASSWORD SAF rule to delete or update a password without supplying the old password.

Syntax PASSWORD{DEFINE USER(user)PASSWORD(password)[QUAL(qual)] [TYPE(type)]}| {DELETE USER(user) PASSWORD(password) QUAL(qual) TYPE(type)}| {LIST [USER(user)][QUAL(qual)][TYPE(type)]}| {UPDATE USER(user)PASSWORD(password)OLDPW(opassword) QUAL(qual)TYPE(type)}

Operand DescriptionDEFINE Defines a new user ID/password pair. DELETE Deletes a user ID/password entry.LIST Displays a list of user IDs that have pre-defined passwords.UPDATE Updates a user ID's password.

USER(user) Specifies the user ID. USER is required for DEFINE, UPDATE and DELETE and optional for LIST. Wildcards can only be used to specify USER when used with LIST. The value specified is case sensitive in the UNIX environment

941

Usage noteFor deleting or changing a password, the correct old password is required unless the user issuing the PASSWORD command has UPDATE authority for the SAF PASSWORD profile.Users with UPDATE authority for the SAF PASSWORD profile supplying the old password must specify the correct password or their request will fail.

ExampleExample of the PASSWORD commandThis an example of the PASSWORD command:PASSWORD USER(jdoe) PASSWORD(A2B3C) TYPE(OpenVMS_JOB)

In this example, the password defined as A2B3C is to be used by jobs using the user ID jdoe on any OpenVMS Agent.

PASSWORD(password) Specifies the password. PASSWORD is required for DEFINE, DELETE, and UPDATE and ignored with LIST. The value specified is case sensitive in the UNIX environment.

OLDPW(opassword) Specifies the old password. OLDPW is required for UPDATE if the user does not have UPDATE access to the SAF password profile. OLDPW is ignored with DEFINE, DELETE, and LIST. The value specified is case sensitive in the UNIX environment.

TYPE(type) Specifies the type of user ID. TYPE is used when searching for a password. It is required with UPDATE and DELETE (if the type was specified with DEFINE) and is optional with DEFINE and LIST. The value specified is case sensitive in the UNIX environment. Wildcards can only be used to specify TYPE when used with LIST.

Note: The OpenVMS job type is OpenVMS_JOB, the Tandem job type is Tandem_JOB, the SAP job is SAP_JOB, and the NT job type is NT_JOB. If this value is omitted, the user ID will not have a specified type.

QUAL(qual) Specifies the name of the agent to which the user ID/password apply. QUAL is required with UPDATE and DELETE (if the type was specified with DEFINE) and is optional with DEFINE and LIST. The value specified is case sensitive in the UNIX environment. Wildcards can only be used to specify QUAL when used with LIST.

Operand Description

PASSWORD Statement: Specify Passwords

942

PASSWORD Statement: Specify Passwords

The PASSWORD statement is used only when defining agent jobs to specify the password of the user ID under which the job is run. It can be used within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition, to apply to the entire application.

TypeESP Workload Manager Application Statement

SyntaxPASSWORD password

ExampleDefines PASSWORD in an JAVA agent jobThis is an example containing the PASSWORD statement:APPL INVENTORYJAVA_JOB MFGDATA RUN DAILY AGENT NT401 USER JOHNDOE PASSWORD CRIMSONENDJOB

In this example, MFGDATA job runs under the user JOHNDOE whose password is CRIMSON.

Operand Descriptionpassword Specifies the password of the user ID to use when running the job.

943

PCACHE Command: Use Procedure Caching

The PCACHE command specifies if ESP Workload Manager uses ESP Procedure caching and the size of the cache. ESP Procedure caching can improve CPU usage and processing speed for ESP Procedures that include a large number of jobs.

TypeOper command

SyntaxPCACHE _|ENABLE|OFF|DISABLE|ON SIZE(32|size)

Examples:This example turns caching on except for ESP Procedures that include an INVOKE statement with the NOCACHE operand.OPER PCACHE ON

This example, issued immediately after the previous example, displays the settings of the cache:OPER PCACHE

Procedure caching is on,used unless INVOKE specifies NOCACHEMax size 32768 KBUsed 0 KB

Operand Description_ Displays the settings of the cache including the amount used.ENABLE Allows the use of caching for ESP Procedures that include an

INVOKE command with the CACHE operand.OFF|DISABLE

Disallow the use of caching.

ON Turns on caching for all ESP Procedures except if they specify NOCACHE.

SIZE(size) Sets the size of the cache. The value is between zero and 1,000 MB. A value of zero clears the cache. If you enter a value larger than 1,000MB, it is reduced to 1,000MB. The default is 32 MB.

PNODES Statement: Specify User-Defined Pnodes

944

PNODES Statement: Specify User-Defined Pnodes

The PNODES statement is used to specify the names of any user-defined Processing nodes through which the job must pass before it can be marked as complete. Note: The Application Manager submits successor jobs to those identified with the

PNODES statement when the predecessors successfully complete.

SyntaxPNODES {pnode} {(pnode[,pnode])}

Usage notesThis element is used to define any additional user-defined processing nodes for a job, overriding the pnodes specified in the job’s tracking model. The pnodes represent post-execution phases, they cannot be used for pre-processing.A job does not need to complete any manual phases for a successor job to run. If you need to set up job dependencies with a manual phase of a job, consider using tasks in an ESP Application.Once you define the pnode name, authorized users can simply type the POST command to post a job as complete at a specific pnode.CSF PNODES fields, such as INPUT, EXEC, COMPLETE, and FAIL apply only to jobs in an ESP Application and do not include post–execution phases.Once a pnode is defined, all users have read access to it.

Related informationFor information on defining processing nodes (pnodes), see the ESP Workload Manager Advanced User’s Guide.For information on defining and deleting manual pnodes, see the DEFPN and DELPN commands.For information on displaying pnode information, see the LISTPN command.For information on posting a job complete from a manual pnode, see the POST command. For information on specifying the name of a pnode when defining a tracking model, see the DEFTM command.

Operand Descriptionpnode Indicates a pnode name in up to eight characters. Enclose multiple

pnode names in parentheses, separated by a blank or comma.

945

For information on using a TASK workload object to identify manual processing points in an Application, see the ESP Workload Manager User’s Guide.

Examples Specific pnodeIn the following example, PAYJOB1 must be posted out of the BALANCE pnode before the Tracking Manager considers it complete. PAYJOB2 is released when PAYJOB1 completes; it does not wait for PAYJOB1 to be posted from the BALANCE pnode.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYS REL PAYJOB2 PNODES BALANCEJOB PAYJOB2 RUN WORKDAYSENDJOB

Similar results could be accomplished using a TASK workload object to represent a manual process (the balancing of a report) and is coded as follows:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYS REL BALANCE.RPTJOB BALANCE.RPT TASK RUN WORKDAYS REL PAYJOB2JOB PAYJOB2 RUN WORKDAYSENDJOB

In the above example, when the report produced by PAYJOB1 is balanced, a user completes BALANCE.RPT using the APPLJOB (AJ) command, or via the CSF. PAYJOB2 is then released.

PNODES Statement: Specify User-Defined Pnodes

946

Multiple pnodesIn the following example, PAYJOB3 must be posted out of the BURSTER and DISTRIB pnodes before the Tracking Manager considers it complete. PAYJOB4 is released when PAYJOB3 completes; it does not wait for PAYJOB3 to be posted from these manual pnodes.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 RUN WORKDAYS REL PAYJOB4 PNODES (BURSTER,DISTRIB)JOB PAYJOB4 RUN WORKDAYSENDJOB

947

POST Command: Post Job Complete

The POST command is used to post a job complete from a manually defined pnode as defined in an Application using the PNODES statement.

TypeGeneral command.

AuthorityYou require OPER authority to issue the POST command.

SyntaxPOST {job(jobnumber)} [PNODE(pnodename)] [FORCE|PURGE]

Usage notesA job does not need to complete any manual phases for a successor job to run. If you need to set up job dependencies with a manual phase of a job, consider using tasks in an ESP Application.Once you have defined the pnode name, authorized users can simply type the POST command to post a job as complete at a specific pnode.

Operand Descriptionjob|jobnumber Indicates the name or number of the job to be posted. If a job number

is specified, it should consist of numeric digits only. To uniquely identify a job, both a job name and job number can be specified. In this format, the job number is enclosed in parentheses immediately following the job name. There should be no intervening blanks or commas.

pnodename Indicates the name of the pnode on which the job completed processing. The job must currently be queued to that pnode unless FORCE or PURGE is also specified. If this operand is omitted, the default pnode for the console or user is used. The default pnode is specified by the DFPNODE command.

FORCE Indicates the job is posted as complete at a pnode, even though it is not currently queued to that pnode.

PURGE Indicates the job is removed from any pnode queue and is marked as complete.

POST Command: Post Job Complete

948

Related informationFor information on defining processing nodes (pnodes), see the ESP Workload Manager Advanced User’s Guide.For information on displaying job on PNODE queues, see the DN command.

Examples Sample definition and commandThe following PNODES statement specifies a user defined processing node:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYS PNODES BALANCEENDJOB

In the above example, PAYJOB1 must be posted out of the BALANCE pnode before it is considered complete. To display the BALANCE pnode issue the following command:DN QUEUE(BALANCE) BALANCE: PAYJOB1 09812

Issue the POST command, using one of the following methods, to complete PAYJOB1 from the BALANCE pnode:POST PAYJOB1 PNODE(BALANCE)

orPOST 9812 PNODE(BALANCE)

orPOST PAYJOB1(9812) PNODE(BALANCE)

or DFPNODE BALANCE - sets the default pnodePOST PAYJOB1

949

POSTREQ Statement: Specify Jobs to Run After

The POSTREQ statement is used to specify the names of any other jobs that must run after this job executes. ESP automatically selects the jobs for submission whenever this job is selected for processing.

TypeESP Application statement.

SyntaxPOSTREQ {jobname} {(jobname{(A)|(U)|(N)[,jobname(A)|(U)|(N]...})} {ADD(jobname{(A)|(U)|(N)[,jobname(A)|(U)|(N]...})} {DROP(jobname{(A)|(U)|(N)[,jobname(A)|(U)|(N]...})}

Usage notesPOSTREQ can be used with any job to name other jobs that should be selected after this job completes (default is successful completion). POSTREQ dynamically creates dependencies between this job and the jobs you specify as postrequisites. This POSTREQ statement automatically forces selection of the postrequisite jobs--no SELECT statement or RUN statement needs to be specified for them. Completion of a job decrements the hold count on each postrequisite job.A POSTREQ statement in an ESP Procedure overrides any previous POSTREQ statement for the same job unless the ADD keyword is specified.

Operand Description

jobname Indicates a jobname in up to eight characters and may include a quali-fier in up to eight characters. Enclose multiple job names in parenthe-ses, separated by a blank or a comma.

ADD Indicates the specified jobs be added to those currently defined as POSTREQs for the job.

DROP Indicates the specified jobs be dropped from those currently defined as POSTREQs.

A Indicates the specified jobs are released on abnormal termination, including condition code failures, of a predecessor.

U Indicates the specified jobs are released on any termination of a prede-cessor.

N Indicates the specified jobs are released on normal termination of a predecessor. This is the default.

POSTREQ Statement: Specify Jobs to Run After

950

The termination operands (A,U,N) are available only for jobs in an Application. For jobs in a DJC jobnet, use the ABNORMAL and NORMAL operands as documented in the DJC User’s Guide.Job definition for POSTREQ jobs are required only if you need to specify requirements for these jobs.

Related informationFor information on specifying job relationships, see the AFTER, RELEASE, PREREQ, and POSTREQ statements.For information on Applications, see the ESP Workload Manager User’s Guide.

Examples Using POSTREQ to identify job relationshipsAPPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYS POSTREQ PAYJOB2 ENDJOB

In the above example, PAYJOB2 is automatically selected for submission and runs after PAYJOB1 successfully completes. Using POSTREQ to identify job relationships APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 RUN WORKDAYS POSTREQ (PAYJOB4,PAYJOB5,PAYJOB6)JOB PAYJOB4JOB PAYJOB5JOB PAYJOB6ENDJOB

In the above example, PAYJOB4, PAYJOB5 and PAYJOB6 are automatically selected for submission and runs after PAYJOB3 successfully completes.Using POSTREQ to identify job relationships APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB7 RUN DAILY POSTREQ (PAYJOB8(A))JOB PAYJOB8ENDJOB

951

In the above example, PAYJOB8 is automatically selected for submission and runs after the abnormal termination of PAYJOB7. If PAYJOB7 completes successfully, PAYJOB8 is not eligible for submission.Using POSTREQ and CLANG statements to identify job relationshipsAPPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB9 RUN WORKDAYS POSTREQ (PAYJOB10,PAYJOB11) IF TODAY('FRIDAY') THEN POSTREQ ADD(PAYJOB12,PAYJOB13)JOB PAYJOB10JOB PAYJOB11JOB PAYJOB12JOB PAYJOB13ENDJOB

In the above example:• PAYJOB10 and PAYJOB11 are automatically selected for submission and run

after PAYJOB9 successfully completes• PAYJOB12 and PAYJOB13 are automatically selected for submission on Fridays

and run after PAYJOB9 successfully completesUsing POSTREQ ADD statements to indicate job relationshipsAPPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB14 RUN DAILY POSTREQ ADD(PAYJOB15) POSTREQ ADD(PAYJOB16)ENDJOB

In the above example, PAYJOB15, and PAYJOB16 are automatically selected for submission and run after PAYJOB14 successfully completes. Using POSTREQ and PREREQ statements to simplify job relationshipsAPPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB LINKIT LINK PROCESS RUN DAILY PREREQ (PAYJOB17,PAYJOB18,PAYJOB19) POSTREQ (PAYJOB20,PAYJOB21,PAYJOB22)ENDJOB

In the above example, a link represents the completion of the first three jobs, and releases the second group of three jobs.

POSTREQ Statement: Specify Jobs to Run After

952

Using POSTREQ to identify job relationships for qualified jobsThe following POSTREQ statement identifies job relationships for qualified jobs within an Application:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB23.RUN1 RUN DAILY POSTREQ PAYJOB23.RUN2ENDJOB

In the above example, PAYJOB23.RUN2 is automatically selected for submission and runs after PAYJOB23.RUN1 successfully completes.

953

PREALLOC Command: Pre-allocate Data Sets

The PREALLOC command is used to pre-allocate a data set.

TypeGeneral Command

AuthorityOPER authority is required to issue the PREALLOC command.

SyntaxPREALLOC [dataset] [ALLOC|UNALLOC]

Usage notesESP bypasses dynamic allocation for each pre-allocated data set when access to the data set is needed.Use one PREALLOC command for each data set you wish to pre-allocate.This command can be issued as a command with no operands to display the current pre-allocation list of data sets, and with the UNALLOC operand to restore a previously allocated data set to non-preallocated status.

Related informationFor information on defining ESP data sets, see the ESP Workload Manager Installation and Configuration Guide.Display Current Preallocation listThe following PREALLOC command displays the current pre-allocation list:OPER PREALLOC

In the above example, the current pre-allocation list is displayed.Preallocates a data setThe following PREALLOC command pre-allocates a data set:OPER PREALLOC CYBER.JCL.CNTL ALLOC

Operand Description

dsname Indicates the data set name.ALLOC Indicates the data set be allocated. This is the defaultUNALLOC Indicates a previously allocated data set be restored to non-preallo-

cated status.

PREALLOC Command: Pre-allocate Data Sets

954

In the above example, CYBER.JCL.CNTL is pre-allocated for used by ESP.Unallocates a data setThe following PREALLOC command unallocates a data set:OPER PREALLOC CYBER.ESP.PROCS UNALLOC

In the above example, CYBER.ESP.PROCS is unallocated from ESP.

955

PREREQ Statement: Specify Jobs to Run Before

The PREREQ statement is used to specify the names of any other jobs that must complete before this job can execute. ESP automatically selects the jobs for submission whenever this job is selected for processing.

TypeESP Application statement.

SyntaxPREREQ {jobname} {(jobname{(A)|(U)|(N)[,jobname(A)|(U)|(N]...})} {ADD(jobname{(A)|(U)|(N)[,jobname(A)|(U)|(N]...})} {DROP(jobname{(A)|(U)|(N)[,jobname(A)|(U)|(N]...})}

Usage notesPREREQs can be used with any job to name other jobs that should be selected before this job is allowed to execute. PREREQs dynamically create dependencies between this job and the jobs you specify as prerequisites. This PREREQ statement automatically forces selection of the prerequisite jobs, no SELECT or RUN statement needs to be specified for them. A PREREQ statement in an ESP Procedure overrides any previous PREREQ statement for the same job unless the ADD keyword is specified.

Operand Descriptionjobname Indicates a jobname in up to eight characters and may include a

qualifier in up to eight characters. Enclose multiple job names in parentheses, separated by a blank or a comma.

ADD Indicates the specified jobs be added to those currently defined as PREREQs.

DROP Indicates the specified jobs be dropped from those currently defined PREREQs.

A Indicates the specified jobs release the job you are defining on abnormal termination, including condition code failures.

U Indicates the specified jobs release the job you are defining on any termination.

N Indicates the specified jobs released the job you are defining on normal termination. This is the default.

PREREQ Statement: Specify Jobs to Run Before

956

The termination operands (A,U,N) are available only for jobs in an Application. For jobs in a DJC jobnet, use the ABNORMAL and NORMAL operands as documented in the DJC User’s Guide.Job definitions for PREREQ jobs are required only if you need to specify requirements for these jobs.

Related informationFor information on specifying job relationships, see the AFTER, RELEASE, COREQ, and POSTREQ statements.For information on deselecting jobs for submission, see the NORUN and DESELECT statements.For information on Applications, see the ESP Workload Manager User’s Guide.

Examples Identifies job relationships within an ApplicationIn the following example, PAYJOB1 is automatically selected for submission and runs before PAYJOB2.APPL PAYROLLJCLLIB 'CYBER.JCL.' JOB PAYJOB2 RUN WORKDAYS PREREQ PAYJOB1ENDJOB

Identifies job relationships within an ApplicationIn the following example, PAYJOB3, PAYJOB4, and PAYJOB5 are automatically selected for submission and run before PAYJOB6.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3JOB PAYJOB4JOB PAYJOB5JOB PAYJOB6 RUN WORKDAYS PREREQ (PAYJOB3,PAYJOB4,PAYJOB5)ENDJOB

957

Identifies job relationships within an ApplicationIn the following example, PAYJOB7 is automatically selected for submission and runs before PAYJOB8. PAYJOB8 runs whether PAYJOB7 completes successfully or not.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB7JOB PAYJOB8 RUN WORKDAYS PREREQ (PAYJOB7(U))ENDJOB

Identifies job relationships within an ApplicationIn the following example:• PAYJOB9 and PAYJOB10 are automatically selected for submission and run

before PAYJOB13.• PAYJOB12 and PAYJOB13 are automatically selected for submission on

Mondays and run before PAYJOB13.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB9JOB PAYJOB10JOB PAYJOB11JOB PAYJOB12JOB PAYJOB13 RUN WORKDAYS PREREQ (PAYJOB9,PAYJOB10) IF TODAY('MONDAY') THEN PREREQ ADD(PAYJOB11,PAYJOB12)ENDJOB

Identifies job relationships within an ApplicationIn the following example, PAYJOB15 and PAYJOB16 are automatically selected for submission and run before PAYJOB14.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL' JOB PAYJOB14 RUN WORKDAYS PREREQ ADD(PAYJOB15) PREREQ ADD(PAYJOB16)ENDJOB

PREREQ Statement: Specify Jobs to Run Before

958

Identifies job relationships within an ApplicationIn the following example, a link represents the completion of the first three jobs, and releases the second group of three jobs.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL' JOB LINKIT LINK PROCESS RUN WORKDAYS PREREQ (PAYJOB17,PAYJOB18,PAYJOB19) POSTREQ (PAYJOB20,PAYJOB21,PAYJOB22)ENDJOB

Identifies job relationships for qualified jobs within an ApplicationIn the following example, PAYJOB23.RUN1 is automatically selected for submission and runs before PAYJOB23.RUN2.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL' JOB PAYJOB23.RUN2 RUN WORKDAYS PREREQ PAYJOB23.RUN1ENDJOB

959

PRINTCOPIES Statement (SAP): Specify Number of Copies for SAP Report

The PRINTCOPIES statement specifies the number of copies for any report associated with the ABAP started by the SAP_JOB.

ApplicabilityESP Business Agents for SAP, Version 1 and higher.

Syntax PRINTCOPIES nnn

Usage notesUse the PRINTCOPIES statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTCOPIES statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.PRINTCOPIES corresponds to the SAPGUI Number of copies field on the Background Print Parameters dialog.

ExampleIn this example, three copies from the ABAP BTCTEST are printed.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST PRINTCOPIES 3ENDJOB

Operand Descriptionnnn Specifies the number of print copies for the ABAP that the job

starts. The default value is 1.nnn is numeric. You can specify up to 255 copies.

PRINTCOPIES Statement (Oracle Applications): Specify Number of Copies

960

PRINTCOPIES Statement (Oracle Applications): SpecifyNumber of Copies

The PRINTCOPIES statement specifies the number of copies to print for an Oracle Applications Request Set or Single Request.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

Syntax PRINTCOPIES nnnnnn

Tip: In Oracle Applications, the number of copies to be printed is specified as a request definition option, and is found in the Copies column of the Upon Completion dialog.

Usage notesPRINTCOPIES can be defined in two places.• To set PRINTCOPIES for a specific job, include it in the job definition.

Note: To set a copy number for a specific program within a job, use the PROGPRINTCOPIES statement.

• To set the default for all jobs run by an Agent, ask your System Administrator to define the oa.default.printCopies parameter in the Agent parameter file.

This statement is optional for OA_JOB definitions.

ExamplePrint three copiesIn this example, three copies are printed.APPL ACC015 AGENT CYBOA OA_JOB TTT1805.TT034 RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN

Operand Descriptionnnnnnn Specifies the number of copies to be printed. Maximum six

digits.

961

PROGRAM XXCOFI PRINTER Q_DEVELOPMENT PRINTSTYLE PORTRAIT PRINTCOPIES 3 ENDJOB

PRINTCOVER Statement: Specify SAP Cover Page Text

962

PRINTCOVER Statement: Specify SAP Cover Page Text

The PRINTCOVER statement specifies the text on an SAP cover page.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTCOVER cover_text

Usage notesYou can use the PRINTCOVER statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTCOVER statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTCOVER statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleIn this example, the cover page text requires single quotes because of the spaces.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 PRINTCOPIES 2 PRINTCOVER ‘Cover page text’ RUN DAILYENDJOB

Operand Descriptioncover_text Specifies the cover page text. It is case sensitive and can be up

to 68 valid SAP characters in length. If cover_text contains delimiters (such as spaces), enclose it in single quotes.

963

PRINTDATASET Statement: Specify Data Set Name for SAP Print Spool

The PRINTDATASET statement specifies the data set name for the SAP print spool.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTDATASET data_set

Usage notesYou can use the PRINTDATASET statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTDATASET statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTDATASET statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 LINES 65 COLUMNS 80 PRINTDATASET LIST1S PRINTCOPIES 1 RUN DAILYENDJOB

Operand Descriptiondata_set Specifies the print spool data set name. It is case sensitive and

can be up to six valid SAP characters in length. If data_set contains delimiters (such as spaces), enclose it in single quotes.

PRINTDEPARTMENT Statement: Specify Department Name (SAP)

964

PRINTDEPARTMENT Statement: Specify Department Name (SAP)

The PRINTDEPARTMENT statement specifies the department name to be printed.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTDEPARTMENT department

Usage notesYou can use the PRINTDEPARTMENT statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTDEPARTMENT statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTDEPARTMENT statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 PRINTDEPARTMENT ‘Department1’ RUN DAILYENDJOB

Operand Descriptiondepartment Specifies the name of the department. It is case sensitive and can

be up to 12 valid SAP characters in length. If department contains delimiters (such as spaces), enclose it in single quotes.

965

PRINTDEST Statement: Specify Print Destination (SAP)

The PRINTDEST statement specifies the print destination for an ABAP.

ApplicabilityESP Business Agents for SAP, Version 1 and higher.

Syntax PRINTDEST destination

Usage notesUse the PRINTDEST statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTDEST statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.PRINTDEST corresponds to the SAPGUI Output device field on the Background Print Parameters dialog.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST PRINTDEST dev1 LINES 65 COLUMNS 60ENDJOB

Operand Descriptiondestination Specifies the required authorization string. destination is case

sensitive and can be up to four valid SAP characters in length.

PRINTER Statement: Specify Printer

966

PRINTER Statement: Specify Printer

The PRINTER statement specifies the name of a printer to be used by Oracle Applications.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

Syntax PRINTER name

Tip: In Oracle Applications, the printer name is specified as a request definition option, and is found in the Printer column of the Upon Completion dialog.

Usage notesPRINTER can be defined in two places.• To set PRINTER for a specific job, include it in the job definition.

Note: To specify a printer for a specific program within a Request Set, use the PROGPRINTER statement.

• To set the default for all jobs run by an Agent, ask your System Administrator to define the oa.default.printer property in the Agent parameter file.

This statement is optional for OA_JOB definitions.

ExampleSpecify a printer nameIn this example, the printer is named Q_DEVELOPMENT.APPL ACC013 AGENT CYBOA OA_JOB WOL1205.WP024 RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN

Operand Descriptionname The name must match the name of a printer that Oracle

Applications can print to. Characters are case-sensitive. If you use delimiters, such as spaces, the name must be enclosed in single quotes. Maximum 30 characters.

967

PROGRAM XXCOFI PRINTER Q_DEVELOPMENT PRINTSTYLE PORTRAIT PRINTCOPIES 3 ENDJOB

PRINTFOOTER Statement: Print Footer on SAP Report

968

PRINTFOOTER Statement: Print Footer on SAP Report

The PRINTFOOTER statement specifies whether to print a footer on a SAP report.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTFOOTER Y|N

Usage notesYou can use the PRINTFOOTER statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTFOOTER statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTFOOTER statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleIn this example, the footer is printed on the SAP report.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 PRINTCOPIES 2 PRINTFOOTER Y RUN DAILYENDJOB

Operand DescriptionY Footer is printedN Footer is not printed

969

PRINTFORMAT Statement: Specify Output Format for SAP Report

The PRINTFORMAT statement specifies an output format for an SAP report.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTFORMAT format

Usage notesYou can use the PRINTFORMAT statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTFORMAT statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTFORMAT statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleIn this example, the SAP report uses the output format X_65_80.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 PRINTFORMAT X_65_80 RUN DAILYENDJOB

Operand Descriptionformat Specifies output format. It is case sensitive and can be up to 16

valid SAP characters in length. If format contains delimiters (such as spaces), enclose it in single quotes.

PRINTHOSTPAGE Statement: Print Host Page (SAP)

970

PRINTHOSTPAGE Statement: Print Host Page (SAP)

The PRINTHOSTPAGE statement specifies whether to print a host page.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTHOSTPAGE Y|N|D

Usage notesYou can use the PRINTHOSTPAGE statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTHOSTPAGE statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTHOSTPAGE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleIn this example, the host page is printed.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 PRINTHOSTPAGE Y RUN DAILYENDJOB

Operand DescriptionY Prints host pageN Does not print host pageD Uses SAP default

971

PRINTIMMED Statement: Specify Immediate Print After Job Completion (SAP)

The PRINTIMMED statement specifies whether the job prints immediately when the job completes.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax PRINTIMMED YES|NO

Usage notesUse the PRINTIMMED statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTIMMED statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.PRINTIMMED corresponds to the SAPGUI Spool options, Print immediately field on the Background Print Parameters dialog.

ExampleIn this example, the job prints immediately following job completion.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST PRINTIMMED YESENDJOB

Operand DescriptionYES Job prints immediately after completion.NO Default. The job output remains on spool.

PRINTNEWSPOOL Statement: Create New Spool Request (SAP)

972

PRINTNEWSPOOL Statement: Create New Spool Request (SAP)

The PRINTNEWSPOOL statement specifies whether to create a new spool request or append the spool request to an existing spool request with similar attributes (if any).

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTNEWSPOOL Y|N

Usage notesYou can use the PRINTNEWSPOOL statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTNEWSPOOL statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTNEWSPOOL statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleIn this example, the spool request is appended to an existing spool request.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 PRINTNEWSPOOL N RUN DAILYENDJOB

Operand DescriptionY Creates new spool requestN Appends spool request to an existing spool request

973

PRINTPRIORITY Statement: Specify the Priority of the SAP Spool Request

The PRINTPRIORITY statement specifies the priority of the SAP spool request.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTPRIORITY priority

Usage notesYou can use the PRINTPRIORITY statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTPRIORITY statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTPRIORITY statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

Operand Descriptionpriority Specifies the priority of the spool request. It is numeric with a

range of 1 to 9.

• 1 highest priority• 5 default priority• 9 lowest priority

PRINTPRIORITY Statement: Specify the Priority of the SAP Spool Request

974

ExampleIn this example, the spool request is set to the highest priority.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 PRINTPRIORITY 1 RUN DAILYENDJOB

975

PRINTPW Statement: Specify SAP Authorization String for Viewing Print Spool List

The PRINTPW statement specifies the SAP authorization string for viewing the print spool list.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax PRINTPW auth_string

Usage notesUse the PRINTPW statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTPW statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.PRINTPW corresponds to the SAPGUI Authorization field on the Background Print Parameters dialog.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST PRINTPW authstringENDJOB

Operand Descriptionauth_string Specifies the required authorization string. auth_string is case

sensitive and can be up to 12 valid SAP characters in length.

PRINTREL Statement: Specify Deletion of Spool Request (SAP)

976

PRINTREL Statement: Specify Deletion of Spool Request (SAP)

The PRINTREL statement specifies whether the spool request associated with the ABAP is deleted after printing.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax PRINTREL YES|NO

Usage notesUse the PRINTREL statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTREL statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.PRINTREL corresponds to the SAPGUI Spool options, Delete after output field on the Background Print Parameters dialog.

ExampleIn this example, the spool request for ABAP BTCTEST is deleted after printing.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST PRINTREL YESENDJOB

Operand DescriptionYES The spool request is deleted after printing.NO Default. The spool request is not deleted after printing.

977

PRINTREQTYPE Statement: Specify Print Request Type (SAP)

The PRINTREQTYPE statement specifies the print request type.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTREQTYPE request_type

Usage notesYou can use the PRINTREQTYPE statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTREQTYPE statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTREQTYPE statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 PRINTREQTYPE prtreq12 RUN DAILYENDJOB

Operand Descriptionrequest_type Specifies the print request type. It is case sensitive and can be up

to 12 valid SAP characters in length. If request_type contains delimiters (such as spaces), enclose it in single quotes.

PRINTSPOOLNAME Statement: Specify Name of SAP Print Spool

978

PRINTSPOOLNAME Statement: Specify Name of SAP Print Spool

The PRINTSPOOLNAME statement specifies the name of the SAP print spool.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPRINTSPOOLNAME spool_name

Usage notesYou can use the PRINTSPOOLNAME statement within the following SAP workload objects:• SAP_JOB• BDC_JOB• SAPA_JOBUse the PRINTSPOOLNAME statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the PRINTSPOOLNAME statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExamplesAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME RSPARAM PRINTDEST LP01 PRINTSPOOLNAME prtspool12 RUN DAILYENDJOB

Operand Descriptionspool_name Specifies the name of the print spool. It is case sensitive and can

be up to 12 valid SAP characters in length. If spool_name contains delimiters (such as spaces), enclose it in single quotes.

979

PRINTSTYLE Statement: Specify Print Style

The PRINTSTYLE statement specifies an Oracle Applications print style.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

Syntax PRINTSTYLE style

Tip: In Oracle Applications, the print style is specified as a request definition option, and is found in the Style field of the Upon Completion dialog.

Usage notesPRINTSTYLE can be defined in two places.• To set PRINTSTYLE for a specific job, include it in the job definition.

Note: To set a printer for a specific program within a Request Set, use the PROGPRINTSTYLE statement.

• To set the default for all jobs run by an Agent, ask your System Administrator to define the oa.default.printStyle parameter in the Agent parameter file.

This statement is optional for OA_JOB definitions.

ExampleSpecify a print styleIn this example, the print style is specified as PORTRAIT.APPL ACC014 AGENT CYBOA OA_JOB CFG2005.XF004 RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN

Operand Descriptionstyle The name must match the name of an Oracle Applications print

style. If you use delimiters, such as spaces, the name must be enclosed in single quotes. Maximum 30 characters.

PRINTSTYLE Statement: Specify Print Style

980

PROGRAM XXCOFI PRINTER Q_DEVELOPMENT PRINTSTYLE PORTRAIT PRINTCOPIES 3 ENDJOB

981

PRIORITY Statement: Specify Relative Priorities

The PRIORITY statement is used in conjunction with ESP resources to specify the relative priority of a workload object within an ESP group, unless USERMOD 56 is turned on. The maximum value is 99, while the minimum priority value is zero. The default is zero.

TypeESP Application statement

SyntaxPRIORITY n

Usage notesThe PRIORITY statement allows you to prioritize jobs within an ESP group. ESP uses the PRIORITY statement when two or more jobs within the same ESP group require the same resource at the same time. In this case, ESP queues the higher priority job ahead of the lower priority job. The queuing sequence of jobs in other groups is not affected.The ESP group name is determined by the Event prefix (for example, first part of the Event identifier). For example:• CYBER.nnn identifies a job belonging to the CYBER group• PROD.nnn identifies jobs in the PROD group.

For instance, a job that is assigned a priority in a group called CYBER is only compared to other jobs in the CYBER group, and not to jobs in another group called PROD.The PRIORITY statement applies only to renewable and depletable resources.Note: If you want a job’s priority to override its group’s priority, you can disable the

group check by using the USERMOD 56 initialization parameter. For details about this parameter, see the ESP Workload Manager Installation and Configuration Guide.

Related informationFor information on resources, see the ESP Workload Manager User’s GuideFor information on requesting resources, see the RESOURCE statement.

Operand Descriptionn Indicates a number between 0 and 99. The higher the number, the

higher the priority of the job associated with it. The default is zero.

PRIORITY Statement: Specify Relative Priorities

982

Example Prioritize jobs within same ESP groupIn the following example, PAYJOB2 has a priority of 99 and is queued ahead of PAYJOB3, which has a priority of nine. Both jobs belong to the same ESP group and both jobs require one unit of the CICS resource.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY REL (PAYJOB2,PAYJOB3)JOB PAYJOB2 PRIORITY 99 RUN DAILY RESOURCE (1,CICS)JOB PAYJOB3 PRIORITY 9 RUN DAILY RESOURCE (1,CICS)ENDJOB

983

PROC Command: Introduce an ESP Procedure

The PROC command is used to begin the definition of an ESP Procedure in an Event definition.

TypeEvent definition command.

SyntaxPROC

Usage noteThe ESP Procedure included in an Event must be enclosed between the PROC and ENDPROC commands.

Related informationFor information on defining Events, see the EVENT command. For information on Events, see the User’s Guide.

Example EVENT ID(PROD.WITHPROC) SCHEDULE DAILY AT 6PM PROC APPL WITHPROC JCLLIB PROD.JCL JOB A RUN DAILY RELEASE JOB B ENDJOB JOB B RUN DAILY ENDJOB ENDPROCENDDEF

PROCESS Statement: Specify Process Within PROCESS_MON

984

PROCESS Statement: Specify Process Within PROCESS_MON

The PROCESS statement specifies the name of the process that is monitored as part of a PROCESS_MON workload object.

ApplicabilityESP System Agents, Release 6, used within a PROCESS_MON workload object. For more information, see “PROCESS_MON Statement: Monitor Process Execution” on page 986.

SyntaxPROCESS processname

ExamplesExample 1 (UNIX)PROCESS_MON PROCESS.FAIL AGENT R6AGENT PROCESS cybAgent STATUS RUNNING NOW RUN DAILYENDJOB

Example 2 (UNIX)If you have more than one Agent running in the system, you need to specify the PID of the Agent you want to monitor.PROCESS_MON PRPATH.SUCCESS AGENT R6AGENT PROCESS 2568 STATUS RUNNING NOW RUN DAILYENDJOB

Operand Descriptionprocessname The format is case sensitive, any character, up to 256 characters in

length.

• On UNIX, you can specify processname using a PID or a process name.

• On Windows, you can specify processname using a full path or a process name.

985

Example 3 (Windows)PROCESS_MON PROCESS.FAIL AGENT R6AGENT PROCESS cybAgent.exe STATUS RUNNING NOW RUN DAILYENDJOB

Example 4 (Windows)If you have more than one Agent running in the system, you need to specify the full path. Note that since the text string contains spaces, it is enclosed in single quotes.PROCESS_MON PRPATH.SUCCESS AGENT R6AGENT PROCESS 'c:\Program files\cybermation\ESP System Agent R6\+ cybAgent.exe' STATUS RUNNING NOW RUN DAILYENDJOB

PROCESS_MON Statement: Monitor Process Execution

986

PROCESS_MON Statement: Monitor Process Execution

Monitors for processes running on a local machine.

TypeApplication statement.

ApplicabilityRelease 6 System Agents

SyntaxRefer to the JOB statement syntax.

Usage notesTo use process monitors, load the workload object module CYBESOPM with the WOBDEF command or with the WOBDEF initialization parameter.Two job-definition statements are associated with the PROCESS_MON statement.• PROCESS• STATUSThe short form of PROCESS_MON is PM.Also refer to the JOB statement usage notes.

987

ExamplesMonitors for the Agent processPROCESS_MON PROCESS1.STMNT AGENT R6AGENT PROCESS cybAgent.exe STATUS RUNNING NOW RUN DAILYENDJOB

Monitors for the Agent process, full path specified In this example, the monitored process is cybAgent.exe. When the STATUS statement conditions are met (process is RUNNING and report status NOW), the jobs listed in the RELEASE statement are released for execution.

Note: If there are spaces in the path, enclose the path in single quotes.PROCESS_MON PROCESS2.STMNT AFTER CHECK.PART3 PROCESS 'c:\Program files\cybermation\ESP System Agent R6\+ cybAgent.exe' STATUS RUNNING NOW RELEASE (PRPATH.JOB1, PRPATH.JOB2) RUN DAILYENDJOB

PROCESSMONITOR Statement: Specify the SAP Process Status to Monitor

988

PROCESSMONITOR Statement: Specify the SAP Process Status to Monitor

The PROCESSMONITOR statement specifies the SAP process status to monitor.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within an SAPM_JOB workload object.

SyntaxPROCESSMONITOR STATUS(WAITING|RUNNING|STOPPED) [USER(user)] [CLIENT(client)] [CONTINUOUS(alert_name) [TYPE(DIA|UPD|ENQ|BGD|SPO|UP2)]

Operand DescriptionSTATUS Specifies the SAP process status to monitor.

• WAITING

• RUNNING• STOPPEDNote: If you specify WAITING, the CLIENT and USER

operands do not apply. The STATUS operand is mandatory.

USER(user) Specifies an SAP user name. When a process matches the specified process status, the job the process runs is checked for a match to this user. It is case sensitive and can be up to 12 valid SAP characters in length. This operand cannot contain delimiters.

CLIENT(client) Specifies the client monitored for the specified process. It is numeric and can be up to three digits.

989

Usage notesPROCESSMONITOR is a mandatory statement within an SAPM_JOB workload object.

ExampleIn this example, the Process Monitor job PMTEST continuously monitors for running background jobs.APPL PMTESTSAPM_JOB PMTEST AGENT SAPHTAGENT PROCESSMONITOR USER(user14) CLIENT(800) CONTINUOUS(alt1) + STATUS(RUNNING) TYPE(BGD) RUN DAILYENDJOB

CONTINUOUS(alert_name) Specifies the ESP Workload Manager alert to associate with this monitor. When the specified process type and status are detected, the ESP Workload Manager alert is triggered. If alert_name is specified, notification messages are sent continuously until the Process Monitor job is cancelled. Otherwise, ESP Workload Manager will be notified once and the Process Monitor job marked complete. It is alphanumeric and can be up to four characters in length. alert_name must start with a character.

TYPE Specifies the SAP business process type to monitor.

• DIA—dialog• UPD—update• ENQ—lock

• BGD—background• SPO—spool• UP2—update2

Operand Description

PROCESSNAME Statement: Specify PeopleSoft Report to Run Within PS_JOB

990

PROCESSNAME Statement: Specify PeopleSoft Report to Run Within PS_JOB

The PROCESSNAME statement specifies the name of the PeopleSoft report to be run. PROCESSNAME is a required statement within a PS_JOB job definition.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax PROCESSNAME processname

Usage notesAll PS_JOB job definitions require a PROCESSNAME statement.

ExampleIn this example, job PAYREPRT runs every Friday on Agent PS_NY. PAYREPRT runs the payroll report.PS_JOB PAYREPRT RUN FRIDAYS AGENT PS_NY PROCESSNAME payroll PROCESSTYPE 'Application Engine' RUNCONTROLID PS_ALLENDJOB

Operand Descriptionprocessname All valid process names are stored in PeopleSoft in the

PS_PRCSDEFN table. The length is up to 12 characters.

991

PROCESSTYPE Statement: Specify PeopleSoft Report Type Within PS_JOB

The PROCESSTYPE statement specifies the type of PeopleSoft report to run. PROCESSTYPE is a required statement within a PS_JOB job definition.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax PROCESSTYPE type

Usage notesAll PeopleSoft job definitions require a PROCESSTYPE statement. There is no default. The list of process types can be obtained from the table PS_PRCSTYPDEFN.

ExampleIn this example, AEMINTEST is output as a report type of Application Engine.PS_JOB PAYROLL RUN DAILY AGENT PS_TOR PROCESSNAME AEMINTEST PROCESSTYPE 'Application Engine' RUNCONTROLID PS_ALLENDJOB

Operand Descriptiontype The report type. The format is character, up to 32 characters in

length. type must be enclosed by single quotes if the string contains a space. Supported types include:• SQR• COBOL• Application Engine• Crystal reports• n/Vision

PROGARGS Statement: Pass Arguments

992

PROGARGS Statement: Pass Arguments

The PROGARGS statement specifies argument strings to be passed to an Oracle Applications Request Set program.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Request Sets only.

Syntax PROGARGS argument1[,argument2,argument3,...argument100]

Usage notesPROGARGS applies to a single program in a Request Set.Do not put any spaces between commas when leaving an argument unspecified (see example).To pass default values for arguments not specified in an PROGARGS statement, define ARGDEFAULTS Y.This statement is optional for OA_JOB Request Set definitions.

ExamplesDefining arguments in an OA_JOB Request SetIn this example, ARGDEFAULTS is set to Y. The first PROGARGS statement passes a value for the second argument, and the Agent passes defaults for all others. The second PROGARGS statement passes values for the first, third, and fifth arguments, and the Agent passes defaults for all others.APPL ACC019 AGENT CYBOA OA_JOB AOL1805.AP035 REQUESTSET ‘EXTRACTS’ RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’

Operand Descriptionargument Specifies a positional parameter of up to 240 characters. You can list up to

100 parameters, separated by commas.

Note: If your list of parameters is over the total maximum of 4 070 characters, split it into multiple PROGARGS statements. These multiple statements will later be concatenated using commas.

993

OAUSER SYSADMIN ARGDEFAULTS Y PROGDATA 1 PROGARGS ,X45S PROGDATA 2 PROGARGS X22F,,X56R143,,X23T ENDJOB

Passing date argumentsIn this example, five arguments are passed to the first Program in the Request Set. For readability, the arguments are put into three PROGARGS statements, which will be concatenated using commas.OA_JOB TEST.PROGARGS APPLDISPLNAME 'Customer Intelligence' REQSET FNDRSSUB1587 OAUSER SYSADMIN RESPNAME 'System Administrator' PROGDATA PROGARGS 2004/10/04 00:00:00 PROGARGS 2004/10/04 00:00:00 PROGARGS N,LIFE_CYCLE,1468 ARGDEFAULTS N RUN DAILYENDJOB

PROGDATA Statement: Identify an Oracle Program

994

PROGDATA Statement: Identify an Oracle Program

The PROGDATA statement identifies a program in an Oracle Applications Request Set by order number.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Request Sets only.

Syntax PROGDATA nnnnnn

Usage notesUse PROGDATA to identify programs for the purpose of changing pre-set statement values. The five program-specific statements that can be used after a PROGDATA statement are:• PROGARGS• PROGPRINTER• PROGPRINTSTYLE• PROGPRINTCOPIES• PROGSAVEOUTPUTThe PROGDATA statement is optional for an OA_JOB Request Set. Note that the program-specific statements cannot be used unless preceded by a PROGDATA statement.

ExampleUse PROGDATA in a Request Set definitionIn the following example, PRINTCOPIES sets the default number of copies to be printed for all programs to one. In PROGDATA 1, the first PROGPRINTCOPIES statement overrides this default with five. PROGDATA 2 is set to seven and PROGDATA 4 is set to two. PROGDATA 3 is not defined in this example, so the default number of copies—one—is used.

Operand Descriptionnnnnnn Specifies the order number of a program in an Oracle Applications Request

Set. If no number is specified, the first program is treated as number one, and subsequent programs are treated as having the previous program number plus one.

995

APPL ACC018 AGENT CYBOA OA_JOB NOV805.APL35 REQUESTSET ‘XX EXTRACTS’ RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN PRINTER Q8 PRINTCOPIES 1 PRINTSTYLE LANDSCAPE PROGDATA PROGPRINTCOPIES 5 PROGDATA PROGPRINTCOPIES 7 PROGDATA 4 PROGPRINTCOPIES 2 ENDJOB

PROGPRINTCOPIES Statement: Specify Number of Copies

996

PROGPRINTCOPIES Statement: Specify Number of Copies

The PROGPRINTCOPIES statement specifies the number of copies to print for an Oracle Applications Request Set program.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Request Sets only.

Syntax PROGPRINTCOPIES nnnnnn

Tip: In Oracle Applications, the number of copies to be printed is specified as a request definition option, and is found in the Copies column of the Upon Completion dialog.

Usage notesPROGPRINTCOPIES applies to a single program in a Request Set. It overrides the PRINTCOPIES statement. Place PROGPRINTCOPIES after a PROGDATA statement. The short form PROGCOPIES can be used in place of PROGPRINTCOPIES.This statement is optional for programs within OA_JOB Request Set definitions.

ExamplePrint a different number of copies for different programsIn this example, five copies are printed for Oracle Applications program 1 and eight for program 2.APPL ACC23 AGENT CYBOA OA_JOB AOL1805.AP035 REQUESTSET ‘XX EXTRACTS’ RUN DAILY APPLDISPLNAME ‘Oracle Bill of Materials’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN ARGDEFAULTS N PROGDATA 1

Operand Descriptionnnnnnn Specifies the number of copies to be printed. Maximum six

digits.

997

PROGARGS ,12345,2,,3223,2,,1 PROGPRINTER Q_DEVELOPMENT PROGPRINTSTYLE PORTRAIT PROGPRINTCOPIES 5 PROGSAVEOUTPUT YES PROGDATA 2 PROGARGS 12345,,,,1,1755,,-1,, PROGPRINTER Q_DEVELOPMENT PROGPRINTSTYLE PORTRAIT PROGPRINTCOPIES 8 PROGSAVEOUTPUT YES ENDJOB

PROGPRINTER Statement: Specify Printer

998

PROGPRINTER Statement: Specify Printer

The PROGPRINTER statement specifies the name of a printer to be used by an Oracle Applications Request Set program.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Request Sets only.

Syntax PROGPRINTER name

Tip: In Oracle Applications, the printer name is specified as a request definition option, and is found in the Printer column of the Upon Completion dialog.

Usage notesPROGPRINTER applies to a single program in a Request Set. It overrides the PRINTER statement. Place PROGPRINTER after the PROGDATA statement. This statement is optional for OA_JOB Request Set definitions.

ExampleSpecify a printer for a program in a Request SetIn this example, the PRINTER statement sets the default printer for this Request Set to Q_8. The first program has a PROGPRINTER statement, so its output is sent to the Q_DEVELOPMENT printer. The second program does not have a PROGPRINTER statement, so its output is sent to the Q_8 printer.APPL ACC021 AGENT CYBOA OA_JOB AOL1805.AP035 REQUESTSET ‘EXTRACTS’ RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN PRINTER Q_8 PROGDATA 1

Operand Descriptionname The name must match the name of a printer that Oracle

Applications can print to. Characters are case-sensitive. If you use delimiters, such as spaces, the name must be enclosed in single quotes. Maximum 30 characters.

999

PROGARGS ,12345,2,,3223,2,,1 PROGPRINTER Q_DEVELOPMENT PROGPRINTSTYLE PORTRAIT PROGPRINTCOPIES 5 PROGSAVEOUTPUT YES PROGDATA 2 PROGARGS 12345,,,,1,1755,,-1,, PROGPRINTSTYLE PORTRAIT PROGPRINTCOPIES 8 PROGSAVEOUTPUT YES ENDJOB

PROGPRINTSTYLE Statement: Specify Print Style

1000

PROGPRINTSTYLE Statement: Specify Print Style

The PROGPRINTSTYLE statement specifies an Oracle Applications print style to be used by an Oracle Applications Request Set program.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Request Sets only.

Syntax PROGPRINTSTYLE style

Tip: In Oracle Applications, the print style is specified as a request definition option, and is found in the Style field of the Upon Completion dialog.

Usage notesPROGPRINTSTYLE applies to a single program in a Request Set. It overrides the PRINTSTYLE statement. Place PROGPRINTSTYLE after a PROGDATA statement. This statement is optional for OA_JOB Request Set definitions.

ExampleSpecify a print style for a program in a Request SetIn this example, the PRINTSTYLE statement sets the default printer for this Request Set to LANDSCAPE. The first program has a PROGPRINTSTYLE statement, so it uses the PORTRAIT print style. The second program does not have a PROGPRINTSTYLE statement, so it uses the default LANDSCAPE style.APPL ACC022 AGENT CYBOA OA_JOB AOL1805.AP035 REQUESTSET ‘XX EXTRACTS’ RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN PRINTERSTYLE LANDSCAPE PROGDATA 1 PROGARGS ,12345,2,,3223,2,,1

Operand Descriptionstyle The name must match the name of an Oracle Applications print

style. If you use delimiters, such as spaces, the name must be enclosed in single quotes. Maximum 30 characters.

1001

PROGPRINTER Q_DEVELOPMENT PROGPRINTSTYLE PORTRAIT PROGPRINTCOPIES 5 PROGSAVEOUTPUT YES PROGDATA 2 PROGARGS 12345,,,,1,1755,,-1,, PROGPRINTER Q_DEVELOPMENT PROGPRINTCOPIES 8 PROGSAVEOUTPUT YES ENDJOB

PROGRAM Statement: Identify an Oracle Applications Single Request Program

1002

PROGRAM Statement: Identify an Oracle Applications Single Request Program

The PROGRAM statement identifies the short name of an Oracle Applications Single Request program.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Single Requests only.

SyntaxPROGRAM name

Tip: In Oracle Applications, the program short name is part of the Single Request definition, and is found in the Short Name field of the Concurrent Programs dialog.

UsageUse OA_JOB Single Requests to run single program requests.This statement is mandatory for OA_JOB Single Request definitions.

ExampleIdentify an Oracle Applications Single Request programIn the following example, XXCOFI identifies an Oracle Applications program short name.APPL ACC04 AGENT CYBOA OA_JOB AOL1806.AP034 PROGRAM XXCOFI RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN ENDJOB

Operand Descriptionname The name must match an existing Oracle Applications Single

Request program short name. Characters are case-sensitive. If you use delimiters, such as spaces, the name must be enclosed in single quotes. Maximum 30 characters.

1003

PROGSAVEOUTPUT Statement: Save Output

The PROGSAVEOUTPUT statement specifies whether to save output from an Oracle Applications Request Set program execution.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Request Sets only.

Syntax PROGSAVEOUTPUT Y|N

Usage notesPROGSAVEOUTPUT applies to a single program in a Request Set. It overrides the SAVEOUTPUT statement. Place PROGSAVEOUTPUT after the PROGDATA statement. This statement is optional for OA_JOB Request Set definitions.

ExampleSave output for only one Oracle Applications program in a Request SetIn the following example, the PROGSAVEOUTPUT statement is defined as Y for the first program and N for the second. When the job executes, an output file is created by Oracle Applications and is saved for program 1, but not for program 2.APPL ACC020 AGENT CYBOA OA_JOB AOL1805.AP035 REQUESTSET ‘XX EXTRACTS’ RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN PROGDATA 1 PROGARGS ,12345,2,,3223,2,,1

Operand DescriptionY Save output.N Do not save output.

PROGSAVEOUTPUT Statement: Save Output

1004

PROGSAVEOUTPUT YES PROGDATA 2 PROGARGS 12345,,,,1,1755,,-1,, PROGSAVEOUTPUT N ENDJOB

1005

PS_JOB Statement: Identify the Name of PeopleSoft Jobs

The PS_JOB statement is used to identify the name of a PeopleSoft job in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use PeopleSoft jobs, you must load a workload object module. The PS_JOB workload object module is CYBESOPS. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.The following statements are used with a PS_JOB workload object:• ARGS • DISTRFOLDER • DISTRLISTROLES • DISTRLISTUSERS • DISABLE_RESTART • EMAILADDR • EMAILLOG • EMAILSUBJECT • EMAILTEXT • EMAILWEBREPORT • OUTDESTFORMAT • OUTDESTPATH • OUTDESTTYPE • PROCESSNAME • PROCESSTYPE • PSOPRID • RUNCONTROLID • SERVERNAME • SKIPPARMUPDATES • TIMEZONERefer to the JOB statement usage notes.

PS_JOB Statement: Identify the Name of PeopleSoft Jobs

1006

Examples:PS_JOB PAYDATARUN DAILYRELEASE PAYRPTAGENT PS_NYPROCESSNAME PSQUERYPROCESSTYPE 'Application Engine'RUNCONTROLID PS_ALL

ENDJOB

Note: You can use the short form PS in place of the PS_JOB statement.

1007

PSOPRID Statement: Specify Operator ID (PeopleSoft)

The PSOPRID statement specifies the operator ID under whose authority the reports are run.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax PSOPRID ID

Usage notesThe operator ID is validated against the corresponding value in the PeopleSoft database. PSOPRID must be specified in either the job definition or in the agentparm.txt as follows:ps.default.oprId=<ID>

Note: The value in the job definition will override the default value specified in the agentparm.txt file. If you specify this value in the agentparm.txt file, you do not need to specify the value in a job.

ExamplePS_JOB DDAUDIT RUN DAILY PROCESSNAME DDAUDIT PSOPRID VP1 PROCESSTYPE 'SQR Report' RUNCONTROLID TEST OUTDESTTYPE FILE OUTDESTFORMAT TXTENDJOB

Operand DescriptionID When ID is specified, Workload Manager will supply the

corresponding password from its password facility. The length is up to 32 characters.

Note: On Windows, the password for this ID cannot be specified in a job definition. If you use the job definition statement PSOPRID in a job, you must use the PASSWORD command to specify and store a user ID/password pair. For more information, refer to the PASSWORD command in the ESP Business Agent Administration Guide.

PURGSCHF Command: Purge Schedule Information

1008

PURGSCHF Command: Purge Schedule Information

The PURGSCHF command is used to purge completed schedule information from the SCHDFILE. This affects what a user sees on the CSF. Information should be purged regularly to prevent space problems.

TypeGeneral command

AuthorityYou require OPER authority to issue the PURGSCHF command.

SyntaxPURGSCHF criteria

Usage notesThe PURGSCHF command does not use any calendar, not even the system calendar, when resolving schedule criteria. If you need to purge schedule information based on a calendar term, such as workdays, use the GENTIME command to generate an actual date, and use the generated symbolic as part of the PURGSCHF command.

Related informationFor information on the Consolidated Status Facility, see the ESP Workload Manager User’s Guide.

Examples Purge when information is older than one weekIn the following example, information older than one week is purged from the SCHDFILE.OPER PURGSCHF TODAY LESS 1 WEEK

Purge when information is older than 36 hoursIn the following example, information older than 36 hours is purged from the SCHDFILE.OPER PURGSCHF NOW LESS 36 HOURS

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time in the past.

1009

Generate date in conjunction with GENTIMEIn the following example, the GENTIME command is used to generate the actual date. The customized date is then used as part of the PURGSCHF command to purge information from the previous two workdays.GENTIME XX TODAY LESS 2 WORKDAYSESP OPER PURGSCHF %XXDATE

Note: The above commands reside in an ESP Procedure and are invoked by an ESP Event.

Purge when information is older than the current timeIn the following example, information older than the current time is purged.OPER PURGSCHF NOW

PUTINOUTBOX Statement: Save Outgoing Documents to SAPoffice Outbox

1010

PUTINOUTBOX Statement: Save Outgoing Documents to SAPoffice Outbox

The PUTINOUTBOX statement specifies whether to save outgoing documents to the SAPoffice outbox of the SAP user associated with the job.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxPUTINOUTBOX Y|N

Usage notesYou can use the PUTINOUTBOX statement within the SAP_JOB and BDC_JOB workload objects.

ExampleIn this example, outgoing mail is sent to the SAPoffice outbox of the SAP user J01Prod.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RECIPIENTTYPE SU SPOOLRECIPIENT CYBERMATION PUTINOUTBOX Y ABAPNAME RSPARAM RUN DAILYENDJOB

Operand DescriptionY Sends outgoing documents to the outbox of the SAP userN Does not send outgoing documents to the outbox of the SAP

user

1011

QQUERY Statement: Specify SQL Statement Within DB_JOB

The QUERY statement specifies the SQL statement to be executed in a DB_JOB workload object. For more information, see “DB_JOB Statement: Identify the Name of Database Jobs” on page 245.

ApplicabilityESP System Agents, Release 6, used within a DB_JOB workload object. For more information, see “DB_JOB Statement: Identify the Name of Database Jobs” on page 245.

SyntaxQUERY SQLQuery

Usage notesQUERY is an alternative form of SQL. Refer to “SQL Statement: Specify SQL Statement Within DB_JOB” on page 1198. To use the QUERY statement, you must have knowledge of how to construct an SQL query.Note: There is no spool file created if CREATE, DELETE, UPDATE, INSERT, or

DROP are used in the DB_JOB.

ExamplesExample 1DB_JOB DBJOB1.STMNT AGENT R6AGENT USER sapr3 DSN oracle:thin:@gamax:1527:cyb QUERY 'SELECT JOBNAME FROM TBTCO' RUN DAILY RELEASE DBTEST2ENDJOB

Operand DescriptionSQLQuery The query can contain any SQL statement including SELECT,

DELETE, UPDATE, or INSERT.

QUERY Statement: Specify SQL Statement Within DB_JOB

1012

Example 2DB_JOB DBJOB2.STMNT AGENT R6AGENT USER user1 DSN oracle:thin:@gamax:1527:cyb QUERY 'SELECT COUNT (*) FROM TBTCO WHERE + JOBNAME LIKE ''SD%'' AND ENDDATE = ''20030813''' RUN DAILYENDJOB

Example 3DB_JOB DBJOB3.STMNT AGENT R6AGENT USER db2admin DSN db2://10.1.1.46:50000/sample QUERY 'SELECT COUNT(*) FROM STAFF WHERE NAME LIKE ''L%''' DESTINATION '/export/home/qatest/db_job_data/test14.bd2' RUN DAILYENDJOB

Note: For a Windows example, substitute a Windows path in the DESTINATION statement.

1013

QUIESCE Command: Put ESP in a Quiesced State

The QUIESCE command is used to put ESP into a quiesced state. While ESP is in a quiesced state Event scheduling and Application processing are quiesced. Jobs that are running when ESP is quiesced continue to run. No new jobs are submitted.

TypeGeneral command.

AuthorityYou require OPER authority to issue the QUIESCE command

SyntaxQUIESCE

Usage notesIf ESP is being restarted, you can bring it up in a quiesced state by using the QUIESCE option on the start command.

Related informationFor information on taking ESP out of the quiesced state, see the RESTART command.

Example Quiesces Event scheduling and Application processingThe following QUIESCE command quiesces Event scheduling and Application processing:OPER QUIESCE

In the above example, ESP is quiesced, which is displayed using the STATUS command as follows:OPER STATUSESP1977I ESP RELEASE 5.1.0.000 STATUSESP1978I EVENT SCHEDULING QUIESCEDESP1979I DATASET TRIGGERING ACTIVE

In the above example, ESP is in a quiesced state as noted by the ESP1978I message—EVENT SCHEDULING QUIESCED.

QUIT Statement: Quit Procedures

1014

QUIT Statement: Quit Procedures

The QUIT statement is used to quit an ESP Procedure and the Event that invoked it.

TypeControl Language (CLANG) statement.

SyntaxQUIT

Usage notesUse QUIT to quit a process. If you use QUIT, ESP does not process any pending requests from this or any other Procedure invoked by the same Event.ESP ignores QUIT statements within the scope of a JOB statement during Application generation. During Application processing, QUIT within the scope of a JOB statement causes ESP not to process any statements for the job and ESP does not submit the job.

Related StatementsFor information on quitting from your current point in a procedure, see the EXIT statement.For information on using ESP’s Control Language in Procedures, see the ESP Workload Manager User’s Guide.

Examples Display differences between using EXIT and QUITThe following procedure shows the differences between using EXIT and QUIT:IF TODAY('CHRISTMAS') THEN QUITIF TODAY('HOLIDAY') THEN DO SEND 'NO WORK TODAY' U(USER01) EXITENDDOSEND 'LET US CONTINUE PROCESSING' U(USER02)

In the above example:• If today is CHRISTMAS, ESP quits the ESP Procedure and no instructions are

processed• If today is not CHRISTMAS, but it is a holiday, ESP sends a message and exits

the Procedure at that point• If none of the above conditions is true, ESP sends a message indicating that

processing will continue.

1015

Shows differences using EXIT and QUIT within job statement scopeThe following procedure shows the differences between using EXIT and QUIT within the scope of the job statement:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYS RELEASE PAYJOB2 IF TODAY('TUESDAY') THEN - EXIT SEND 'TODAY IS NOT MONDAY' U(USR01)ENDJOBJOB PAYJOB2 RUN WORKDAY IF TODAY('MONDAY') THEN - QUITENDJOB

In the above example, when the PAYROLL Application is generated on a Monday:• PAYJOB1 is submitted, and a message is issued if it isn’t Monday• PAYJOB2 is not submitted and receives an error.The following is an example of the CSF display after PAYJOB1 completes on Monday:ESP Consolidated Status:View PAYROLL--Row 1 of 2,COMMAND ===> SCR ===> PAGE Jobname APPL PNODE STATUS__ PAYJOB1 PAYROLL COMPLETE COMPLETED AT 13.14 21 APR___PAYJOB2 PAYROLL SUBERROR Submit Error, Quit

QUPDATE Command: Force JES Status and Pnode Queue Information

1016

QUPDATE Command: Force JES Status and Pnode Queue Information

The QUPDATE command is used to force ESP to do a JES status and update pnode queue information.

TypeGeneral command.

AuthorityYou require OPER authority to issue the QUPDATE command.

SyntaxQUPDATE

Usage notesThe QUPDATE command allows any job flushed from the system to be recognized. ESP automatically posts these jobs through the EXEC and OUTPUT processing nodes and marks each as a JCL ERROR.

Related informationFor information on displaying pnode information, see the LISTPN command.

Example Update pnode queue informationIn the following example, ESP does a JES status and automatically posts any flushed jobs through the EXEC and OUTPUT pnodes.OPER QUPDATE

1017

RRACROUTE Command: Specify Events Processing

The RACROUTE command is used to specify how an Event is processed for security purposes. You specify whether ESP should issue a SAF RACINIT prior to executing Events, and how the user ID associated with the Event is determined. The RACROUTE command must be set to ON in environments using the System Authorization Facility (SAF). RACROUTE is normally coded as an initialization parameter.

TypeAuthorized OPER command.

AuthorityYou require OPER authority to issue the RACROUTE command.

SyntaxRACROUTE [ON|OFF] [ITU|NOITU]

Usage notesThe ITU option affects Events only when the TRIGGER command is issued.

Operand DescriptionON Specifies that ESP Workload Manager should issue a SAF RACINIT

before executing Events.OFF Specifies that ESP Workload Manager should not issue a SAF

RACINIT before executing Events. ESP Workload Manager processes Events under its own user ID. This is the default.

ITU Specifies Inherit Trigger User—All manually triggered, DSTRIG, and global variable trigger Events use the triggering user ID.

NOITU Specifies No Inherit Trigger User—ESP Workload Manager processes Events under the user ID specified in the Event prefix. This is the default.

RACROUTE Command: Specify Events Processing

1018

RACROUTE values at startupThe RACROUTE values (ON or OFF, and ITU or NOITU) issued in initialization parameters or commands are checkpointed. This means that they remain in effect until explicitly countermanded.

ITU and NOITU operandsRefer to How ESP Workload Manager determines the user for batch processing in the ESP Workload Manager Security Guide for an explanation on how to determine under which user ID ESP Workload Manager processes the Event.By default, ESP Workload Manager uses the Event prefix of the Event triggering the procedure as user ID to run production jobs.Specifying the USER operand in the EVENT command overrides the default. In that case ESP Workload Manager uses the user ID you specify.Specifying ITU at the initialization parameter level or INHERIT_TRIGGER_USER at the Event level overrides the default and the USER operand. It results in using the triggering user ID if the event is a manually triggered, DSTRIG, or global variable trigger Event. You can override both ITU and NOITU:• With actions by security system exit routines such as EVENTSAF (or JES exits)• With parameters in the JCLThe following table illustrates the logic determining which user ID ESP Workload Manager processes the Event with RACROUTE ON.

Cold Start withRACROUTE Initialization Parameter

Warm Start withRACROUTE Initialization Parameter

Defined Not Defined Defined Not DefinedUses the RACROUTE Initialization Parameters.

Uses defaults:

RACROUTE OFF NOITU

Uses the RACROUTE Initialization Parameters.

Uses checkpointed values.

Sequence Description Result ConditionDefault Uses Event Prefix.1st Override USER operand in

EVENT definition.Uses USER operand value.

2nd Override ITU in initialization parameter or INHERIT_TRIGGER_USER in EVENT definition.

Uses triggering user ID Manually triggered, DSTRIG, or global variable trigger Event.

1019

The logic is totally independent of what the underlying security package is.Note: Cybermation recommends that you use explicit operands and that you do not rely on the defaults. The logic may be activated inadvertently resulting in behavior different from what you expect. The possible causes to investigate are:

• Multiple RACROUTE initialization parameters• Checkpointed values originating from dynamic commands and carried over

during a warm start. You can only rectify this situation by issuing a RACROUTE command with the correct operands or by initiating a warm start with a RACROUTE initialization parameter with the correct operands.

Triggering user ID identityThe following table define the identity of the triggering user ID depending of the type of Event:

Related informationFor information on the System Authorization Facility (SAF), see the ESP Workload Manager Security Guide.For information on using RACROUTE at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.

Example Specify how Events are processedIn the following example, ESP issues a SAF RACINIT before executing Events and processes Events under the user ID specified in the Event prefix. Even if NOITU is the default, it is specified to avoid ambiguities. OPER RACROUTE ON NOITU

3rd Override Exit routines. Uses user ID specified in exit routine.

4th Override Parameters in the JCL. Uses user ID specified in the JCL.

Sequence Description Result Condition

Type of Event Identity of user IDManually-triggered Event. User that triggered the Event.Implicit-data-set trigger. User or task that modified the data set.FTP-data-set trigger. User associated with the local FTP partner.Explicit-data-set trigger. User or task that submitted the CYBESDT1 utility.Global-variable-table trigger. User that modified the global-variable-table.

RANGE Statement: Specify Search Range Within TEXT_MON

1020

RANGE Statement: Specify Search Range Within TEXT_MON

The RANGE statement specifies the range a TEXT_MON job will search for a text string using a search boundary type of line, regular expression, or date and time.

ApplicabilityESP System Agents, Release 6, used within a TEXT_MON workload object. For more information, see “TEXT_MON Statement: Monitor Content of Text File” on page 1242.

SyntaxRANGE [LINE|REGEX|DATETIME] FROM(lower)TO(upper)

Usage notesRANGE is an alternative form of SEARCHRANGE. Refer to “SEARCHRANGE Statement: Specify Search Range Within TEXT_MON” on page 1144.While most searches require you to specify both FROM and TO operands, you must specify at least one of them. If you only specify FROM, the search range is from the lower limit specified by the FROM operand to the end of the file. If you only specify TO, the search range is from the beginning of the file to the upper limit specified by the TO operand.If you use the CONTINUOUS operand in the TEXTSTRING statement, you cannot use the TO operand in the RANGE statement.

Operand DescriptionLINE Search for the text string in the line boundaries defined by the upper

and lower line boundaries. If LINE is specified, the search boundaries FROM and TO are numeric.

REGEX Search for a text string within boundaries defined by a regular expression. If REGEX is specified, the search boundaries FROM and TO are regular expressions.

DATETIME Search for a text string within boundaries defined by a specified date and time. If DATETIME is specified, the job statement TIMEFORMAT must be used.

FROM (lower) Specifies the start of the range to be searched.TO (upper) Specifies the end of the range to be searched.

1021

ExamplesExample 1 (NT)In this example, the LINE operand is specified. If you use the CONTINUOUS operand, do not use a TO operand.TEXT_MON SRCHRNGE.STMNT1 AGENT R6AGENT TEXTSTRING 'ERROR MESSAGE' EXIST CONT(A123) TEXTFILE 'c:\cybermation\logfile' RANGE LINE FROM(143) RUN DAILYENDJOB

Example 2 (NT)In this example, the DATETIME operand is specified. The DATETIME operand requires that the TIMEFORMAT statement be specified.TEXT_MON SRCHRNGE.STMNT2 AGENT R6AGENT TEXTFILE 'c:\program files\cybermation\esp system agent + r6\log\transmitter.log' TEXTSTRING NTAGR6 EXIST RANGE DATETIME+ FROM(10:00:00)+ TO(09:20:59) TIMEFORMAT 'HH:mm:ss' TIMEPOS(12) RUN DAILYENDJOB

Example 3 (NT)In this example, the operand REGEX is specified in the RANGE statement. The FROM and TO operands contain the regular expressions that are evaluated.TEXT_MON SRCHRNGE.STMNT3 AGENT R6AGENT TEXTFILE 'c:\program files\cybermation\esp system agent + r6\agentparm.txt' TEXTSTRING archive EXIST RANGE REGEX FROM(ESP) TO(service) RUN DAILYENDJOB

RANGE Statement: Specify Search Range Within TEXT_MON

1022

Example 4 (NT)Because back slashes are interpreted as an escape sequence, the two back slashes in the text stringC:\\Program Files

must each be preceded by a back slash, giving four back slashes in the TEXTSTRING statement below.TEXT_MON SRCHRNGE.STMNT4 AGENT R6AGENT TEXTFILE 'c:\program files\cybermation\esp system agent + r6\agentparm.txt' TEXTSTRING 'C:\\\\Program Files' EXIST RANGE LINE FROM(1) TO(200) RUN DAILYENDJOB

Example 5 (UNIX)TM SRCHRNGE.STMNT5 AGENT R6AGENT TEXTFILE '/export/home/cybermation/agent/log/transmitter.log' TEXTSTRING NTAGR6 EXIST RANGE DATETIME+ FROM('Thu Aug 28 00:00:00.000 EDT 2003')+ TO('Thu Aug 28 23:59:59.999 EDT 2003') TIMEFORMAT 'EEE MMM dd HH:mm:ss.SSS zzz yyyy' TIMEPOS(1) RUN DAILYENDJOB

Example 6 (UNIX)In this example, the FROM operand specifies the word agent at the beginning of the line (using the \A). TEXT_MON SRCHRNGE.STMNT6 AGENT R6AGENT TEXTFILE '/export/home/cybermation/espsystemagent+ agentparm.txt' TEXTSTRING \.0/MAIN$ EXIST RANGE REGEX FROM(\Aagent) TO(level=2\Z) RUN DAILYENDJOB

1023

Example 7 (UNIX)In this example, the search is for the string

# Runner plugin parameters

which is evaluated as a regular expression (operand REGEX in the RANGE statement).TEXT_MON SRCHRNGE.STMNT7 AGENT R6AGENT TEXTFILE '/export/home/cybermation/agentparm.txt' TEXTSTRING \A\W\sRunner EXIST RANGE REGEX FROM(ESP) TO(service) RUN DAILYENDJOB

The criteria \A, \W, and the word \sRunner are evaluated as follows:• \A means match only at the beginning of the line.• \W means match a non-word character• \sRunner means look for a white space before the word Runner.

Example 8 (UNIX)In this example, the operand CONTINUOUS in the TEXTSTRING statement prevents the use of the TO operand in the RANGE statement. When the text string agent is found, as specified by the operand EXIST, an Alert text will be issued.TEXT_MON SRCHRNGE.STMNT8 AGENT R6AGENT TEXTFILE '/export/home/cybermation/logfiles/test' TEXTSTRING agent EXIST CONTINUOUS(text) RANGE LINE FROM(1) RUN DAILYENDJOB

RECIPIENT Statement: Specify Recipient Name for SAP Cover Page

1024

RECIPIENT Statement: Specify Recipient Name for SAP Cover Page

The RECIPIENT statement specifies the spool request recipient’s name to appear on the SAP cover page.

ApplicabilityESP Business Agents for SAP, Version 2.2 and higher.

Syntax RECIPIENT username

Usage notesUse the RECIPIENT statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the RECIPIENT statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.RECIPIENT corresponds to the SAPGUI Cover sheets options, Recipient field on the Background Print Parameters dialog.

ExampleIn this example, the SAP cover page states that the recipient’s name is IndyFinney.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST RECIPIENT IndyFinneyENDJOB

Operand Descriptionusername The user name to appear as recipient on the SAP cover page.

username is case sensitive and can be up to 12 valid SAP characters in length.Note: The default value for the name of the recipient is the

current user name.

1025

RECIPIENTBCC Statement: Blind Carbon Copy the SAP Spool

The RECIPIENTBCC statement specifies whether to blind carbon copy the SAP spool.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRECIPIENTBCC Y|N

Usage notesYou can use the RECIPIENTBCC statement within the SAP_JOB and BDC_JOB workload objects.If you use a RECIPIENTCC statement and a RECIPIENTBCC statement in a job, only one statement can be set to Y.

ExampleIn this example, the spool file will be blind carbon copied to the users on the payroll distribution list.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RECIPIENTTYPE INT RECIPIENTBCC Y SPOOLRECIPIENT payroll@company1.com ABAPNAME BTCTEST RUN DAILYENDJOB

Operand DescriptionY Spool recipients receive a blind carbon copy of the spoolN Spool recipients do not receive a blind carbon copy of the spool

(default)

RECIPIENTCC Statement: Carbon Copy the SAP Spool

1026

RECIPIENTCC Statement: Carbon Copy the SAP Spool

The RECIPIENTCC statement specifies whether to carbon copy the SAP spool.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRECIPIENTCC Y|N

Usage notesYou can use the RECIPIENTCC statement within the SAP_JOB and BDC_JOB workload objects.If you use a RECIPIENTCC statement and a RECIPIENTBCC statement in a job, only one statement can be set to Y.

ExampleIn this example, the spool file will be carbon copied to the users on the payroll distribution list.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RECIPIENTTYPE INT RECIPIENTCC Y SPOOLRECIPIENT payroll@company1.com ABAPNAME BTCTEST RUN DAILYENDJOB

Operand DescriptionY Spool recipients receive a carbon copy of the SAP spoolN Spool recipients do not receive a carbon copy of the SAP spool

(default)

1027

RECIPIENTEXPRESS Statement: Send SAP Spool Using Express Delivery

The RECIPIENTEXPRESS statement specifies whether to send the SAP spool using express delivery.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRECIPIENTEXPRESS Y|N

Usage notesYou can use the RECIPIENTEXPRESS statement within the SAP_JOB and BDC_JOB workload objects.The RECIIENTEXPRESS statement applies to the recipient types SAPoffice distribution list (DLI) and SAP user (SU). For more information on recipient types, see “RECIPIENTTYPE Statement: Specify Recipient Type for SAP Spool” on page 1030.

ExampleIn this example, assuming J01Prod is logged onto the SAP system, J01Prod receives a message that the spool has been sent.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RECIPIENTTYPE SU RECIPIENTEXPRESS Y SPOOLRECIPIENT J01Prod ABAPNAME BTCTEST RUN DAILYENDJOB

Operand DescriptionY The spool is sent using express delivery. Recipients receive a

message instantly if they are logged into SAP.N The spool is not sent using express delivery (default)

RECIPIENTFORWARD Statement: Allows Forwarding of SAP Spool

1028

RECIPIENTFORWARD Statement: Allows Forwarding of SAP Spool

The RECIPIENTFORWARD statement specifies whether to allow forwarding of the SAP spool.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRECIPIENTFORWARD Y|N

Usage notesYou can use the RECIPIENTFORWARD statement within the SAP_JOB and BDC_JOB workload objects.The RECIIENTFORWARD statement applies to the recipient types SAPoffice distribution list (DLI) and SAP user (SU). For more information on recipient types, see “RECIPIENTTYPE Statement: Specify Recipient Type for SAP Spool” on page 1030.

ExampleIn this example, the SAP user J01Prod can forward the spool file.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RECIPIENTTYPE SU RECIPIENTFORWARD Y SPOOLRECIPIENT J01Prod ABAPNAME BTCTEST RUN DAILYENDJOB

Operand DescriptionY Spool recipients can forward the spoolN Spool recipients cannot forward the spool

1029

RECIPIENTPRINT Statement: Allow Printing of SAP Spool

The RECIPIENTPRINT statement specifies whether to allow printing of the SAP spool.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRECIPIENTPRINT Y|N

Usage notesYou can use the RECIPIENTPRINT statement within the SAP_JOB and BDC_JOB workload objects.The RECIPIENTPRINT statement applies to the recipient types SAPoffice distribution list (DLI) and SAP user (SU). For more information on recipient types, see “RECIPIENTTYPE Statement: Specify Recipient Type for SAP Spool” on page 1030.

ExampleIn this example, the SAP user J01Prod can print the spool file.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RECIPIENTTYPE SU RECIPIENTPRINT Y SPOOLRECIPIENT J01Prod ABAPNAME BTCTEST RUN DAILYENDJOB

Operand DescriptionY Spool recipients can print the spoolN Spool recipients cannot print the spool

RECIPIENTTYPE Statement: Specify Recipient Type for SAP Spool

1030

RECIPIENTTYPE Statement: Specify Recipient Type for SAP Spool

The RECIPIENTTYPE statement specifies the recipient type for SAP spool.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRECIPIENTTYPE SU|DLI|INT

Usage notesYou can use the RECIPIENTTYPE statement within the SAP_JOB and BDC_JOB workload objects.

ExampleIn this example, the SAP user J01Prod receives the spool upon job completion.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RECIPIENTTYPE SU SPOOLRECIPIENT J01Prod ABAPNAME BTCTEST RUN DAILYENDJOB

Operand DescriptionSU SAP user.DLI SAPoffice distribution list.INT Email address. You can also use the operand MAIL.

1031

REEXEC Statement: Re-Execute Procedures

The REEXEC statement requests re-execution of an ESP Procedure at a specific time or after a certain time interval. The Event that invoked the ESP Procedure containing the REEXEC statement is scheduled for re-execution.

SyntaxREEXEC {AT('time')|IN(interval)} [DELAY|ADDITIONAL] [MAXIMUM(count)|NOMAXIMUM]

Usage notesSymbolic variable %ESPREEXEC# indicates the number of times a Procedure was re-executed. %ESPREEXEC# is initially set to zero and has a maximum value of 255. When the Procedure is re-executed the number of times specified in MAXIMUM, message ESP0409E MAXIMUM VALUE HAS BEEN REACHED is issued.If you code REEXEC within the scope of a JOB statement in an Application, ESP Workload Manager re–executes only the code associated with that job. ESP Workload Manager maintains a separate ESPREEXEC# for each job.Note: If you want to control the number of times that the REEXEC is processed, you

should use the %ESPREEXEC# symbolic variable as a counter. You shouldn’t use the MAXIMUM(count) operand as a counter; it is intended to prevent “run away” situations. If you use the MAXIMUM(count) operand as a counter and it reaches the upper limit, you get an error message indicating something exceptional happened that must be handled.

Operand DescriptionAT(‘time’) The point in time at which the ESP Procedure is restarted.

Specify schedule criteria in quotes that resolve to a single date and/or time. If no time is implied, the start time of a day is used.

IN(interval) The time interval in minutes before the ESP Procedure is restarted.

DELAY Indicates that when the Procedure is re-executed, job submission is delayed until the conditional processing is true. All other functions are executed.

ADDITIONAL Indicates that additional job submission will take place with every re-execution.

MAXIMUM(count) The maximum number of times the Event is re-executed. Valid values are between 1 and 255.

NOMAXIMUM The Event can be re-executed an unlimited number of times.

REEXEC Statement: Re-Execute Procedures

1032

Related informationFor information on re-executing an ESP Procedure, see the ESP Workload Manager User’s Guide.

Examples Using REEXEC with the ACTIVE function to check started task statusIn the following example:• If CICS is active, ESP sends a message to console id 01 and re–executes the

Procedure in five minutes.• If CICS is not active, ESP submits the CICSBKUP from PROD.JCL.CNTL.IF ACTIVE('CICS') THEN DO SEND 'CICS IS DUE TO COME DOWN' CN(01) REEXEC IN(5)ENDDOELSE SUBMIT 'PROD.JCL.CNTL(CICSBKUP)'

Using REEXEC with JOBONQ to check for specific jobIn the following example:• If RMTJOB is on the input queue on hold, ESP releases the job.• If RMTJOB is not on the input queue on hold, ESP checks the number of re–

executions. If the number of re–executions is less than five, ESP re–executes the Procedure in 30 minutes. Otherwise, ESP sends a message.

INTEGER COUNTCOUNT=JOBONQ('RMTJOB','X','IH')IF COUNT=1 THEN VS '$AJ%XJOBNO1'ELSE DOIF ESPREEXEC#<5 THEN REEXEC IN(30)ELSE SEND 'I GIVE UP ON RMTJOB' U(USER01)ENDDO

Delaying job submissionIn the following example, PAYJOB2 is delayed for five hours after PAYJOB1 completes.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY RELEASE PAYJOB2JOB PAYJOB2 RUN DAILY IF %ESPREEXEC#=0 THEN REEXEC AT('REALNOW PLUS 5 HOURS')ENDJOB

1033

Re-executing a procedure in five minutesREEXEC IN(5)

Re-executing a procedure at start of the next workdayREEXEC AT('TODAY PLUS 1 WORKDAY')

Re-executing a procedure in six hoursREEXEC AT('REALNOW PLUS 6 HOURS')

Re-executing a procedure in five minutes for a maximum of five timesREEXEC IN(5) MAXIMUM(5)

Re-executing a procedure in one minute for an unlimited number of timesREEXEC IN(1) NOMAXIMUM

RELCOUNT Statement: Specify Hold Counts

1034

RELCOUNT Statement: Specify Hold Counts

The RELCOUNT statement is used to specify the hold count when a job becomes eligible for submission. By default, ESP does not consider a job eligible for submission until its hold count is zero.

SyntaxRELCOUNT n

Usage notesIf RELCOUNT is not specified, a job is not eligible for execution until all predecessors are complete (that is, its hold count is reduced to zero).

Related informationFor information on Applications, see the ESP Workload Manager User’s and Advanced User’s Guides.

Examples Specify when a job is elegible for submissionIn the following example, when ESP builds the Application, PAYJOB3 has a hold count of two. By specifying a RELCOUNT of one for PAYJOB3, ESP releases this job when its hold count becomes one. ESP releases PAYJOB3 when either PAYJOB1 or PAYJOB2 completes successfully.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY REL PAYJOB3JOB PAYJOB2 RUN DAILY REL PAYJOB3JOB PAYJOB3 RUN DAILY RELCOUNT 1ENDJOB

Operand Descriptionn Indicates a positive integer representing the number of outstanding

predecessors before this job is eligible for execution.

1035

Specify when a job is elegible for submissionIn the following example, when ESP builds the Application, PAYJOB8 has a hold count of four. By specifying a RELCOUNT of three for PAYJOB8, ESP releases this job when its hold count becomes three. This means ESP releases PAYJOB8 when any one of its predecessors completes successfully.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB4 RUN DAILY JOB PAYJOB5 RUN DAILYJOB PAYJOB6 RUN DAILYJOB PAYJOB7 RUN DAILY JOB PAYJOB8 AFTER(PAYJOB4,PAYJOB5,PAYJOB6,PAYJOB7) RUN DAILY RELCOUNT 3ENDJOB

Specifies when a job is eligible for submissionIn the following example, when ESP builds the Application, PAYJOB1 has a hold count of two. By specifying a RELCOUNT of one for PAYJOB1, ESP releases this job when either data set trigger object completes.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'DSTRIG FILEA RUN DAILY RELEASE PAYJOB1 DSNAME CYBER.ESP.FILEADSTRIG FILEB RUN DAILY RELEASE PAYJOB1 DSNAME CYBER.ESP.FILEBJOB PAYJOB1 RUN DAILY RELCOUNT 1ENDJOB

RELDELAY Statement: Delay Jobs Submission

1036

RELDELAY Statement: Delay Jobs Submission

The RELDELAY statement is used to delay job submission at the time that a job becomes eligible for submission. The RELDELAY statement uses minutes as its unit of measure. You can delay job submission up to 255 minutes.

SyntaxRELDELAY nnn

Usage notesWhen a job becomes eligible for submission, ESP delays submission by the number of minutes specified by the RELDELAY statement for the job. If a job requires ESP resources, the RELDELAY takes effect before the check for resource availability.At the time a job is delayed for submission, the status field on the CSF indicates the resolved time and date of the RELDELAY statement, for example, the number of minutes after the delayed job becomes eligible for submission. You can reset this resolved time and date using the APPLJOB (AJ) command or the CSF to reset the earliest submit time.

Related informationFor information on Applications, see the ESP Workload Manager User’s Guide.For information on delaying the submission of a job relative to the time the Event is scheduled or triggered, see the DELAYSUB statement.For information on monitoring and manipulating jobs from the CSF, see the ESP Workload Manager User’s Guide.For information on manipulating jobs within Applications or subApplications, see the APPLJOB or AJ command.If you need to delay more than 255 minutes, use the REEXEC statement.

Operand Descriptionnnn Indicates a positive integer representing the number of minutes to

delay submission. The maximum value allowed is 255; the default is zero.

1037

Delays specific job submissionIn the following example, when PAYJOB1 completes successfully, PAYJOB2 becomes eligible for submission and the RELDELAY statement delays the submission of PAYJOB2 by five minutes.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY REL PAYJOB2JOB PAYJOB2 RUN DAILY RELDELAY 5ENDJOB

Note: At the time PAYJOB2 is delayed for submission, the status field on the CSF indicates the resolved time and date of the RELDELAY statement, for example, five minutes after PAYJOB2 becomes eligible for submission, as follows:

E510 Consolidated Status: View PAYROLL - Row 1 of 3, Col 1COMMAND ===> SCR ===> PAGE Jobname APPL GEN PNODE HC STATUS___ PAYJOB1 PAYROLL 131 COMPLETE 0 COMPLETED AT 21.54 03 FEB___ PAYJOB2 PAYROLL 131 WAITING 0 WAITING UNTIL 21.59 03 FEB

Delay a LINKIn the following example, a LINK (FRED), which is normally marked complete by ESP as soon as its dependencies are met, is delayed by two minutes after becoming eligible for submission, that is, after PAYJOB3 completes successfully.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 RUN DAILY REL FREDJOB FRED LINK PROCESS RUN DAILY SEND 'LINKS CAN USE THE RELDELAY STATEMENT TOO' (USR01) RELDELAY 2 REL PAYJOB4JOB PAYJOB4 RUN DAILYENDJOB

RELEASE Command - Event Level: Decrement Hold Counts

1038

RELEASE Command - Event Level: Decrement Hold Counts

When used in an Event definition, the RELEASE command decrements the hold count associated with the Event at a specified time. When the hold count reaches zero, the Event is eligible for execution. It is used in conjunction with the HOLD command.

TypeEvent definition command.

SyntaxRELEASE criteria

Usage notesThe RELEASE command is used in conjunction with the HOLD.command to make a previously postponed Event eligible for execution.ESP processes any pending actions. For example, if an Event missed its scheduled time while on hold, ESP processes the Event based on the OVERDUE count on the Event’s SCHEDULE statement.If you are using a time zone on your RELEASE command, it should match the timezone on your HOLD command. If the Event has a schedule statement, the same time zone should be used on the SCHEDULE, HOLD, and RELEASE commands.Note: The SUSPEND command is used in conjunction with the RESUME command

to make a previously bypassed Event eligible for execution.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.For information on holding an Event, see the HOLD command.For information on releasing a held Event outside of an Event definition, see the RELEASE Command—General.For information on overdue Events, see the SCHEDULE command.

Operand Description

criteria Schedule criteria.

1039

Examples Prevent PAYJOB from being submitted between specific timesIn the following example, HOLD and RELEASE commands are used to prevent PAYJOB1 from being submitted between 9 am and 11 am. EVENT ID(CYBER.PAYROLL) DSTRIG PAYROLL.INPUTHOLD DAILY AT 9AMRELEASE DAILY AT 11AMSUBMIT 'CYBER.JCL.CNTL(PAYJOB1)'ENDDEF.

Prevent PAYJOB from being submitted between specific times on last day of monthIn the following example, HOLD and RELEASE commands are used to prevent PAYJOB2 from being submitted between 5 pm and 9 pm on the last day of the month.EVENT ID(CYBER.PAYROLL)SCHEDULE 6PM DAILY HOLD 5PM LAST DAY OF MONTHRELEASE 9PM LAST DAY OF MONTHSUBMIT 'CYBER.JCL.CNTL(PAYJOB2)'ENDDEF

Prevent PAYJOB from being submitted between specific times on specific workdayIn the following example, HOLD and RELEASE commands are used to prevent PAYJOB3 from being submitted between 7:59 and 10:01 on February 13, 1998 only.EVENT ID(CYBER.PAYROLL)SCHEDULE 8AM WORKDAYSHOLD 7:59 FEB 13,1998 ONCERELEASE 10:01 FEB 13,1998 ONCESUBMIT 'CYBER.JCL.CNTL(PAYJOB3)'ENDDEF

RELEASE Command - General: Decrement Hold Counts

1040

RELEASE Command - General: Decrement Hold Counts

The RELEASE command decrements the hold count associated with an Event. It is used in conjunction with the HOLD command.

TypeGeneral command.

SyntaxRELEASE eventid

Usage notesESP processes any pending actions. For example, if an Event missed its scheduled time while on hold, ESP processes the Event based on the OVERDUE count on the Event’s SCHEDULE statement.The specified Event has its HOLD count decremented immediately.The RELEASE command is used in conjunction with the HOLD command to make a previously postponed Event eligible for execution.Note: The SUSPEND command is used in conjunction with the RESUME command

to make a previously bypassed Event eligible for execution.

Related informationFor information on overdue Events, see the SCHEDULE command.For information on Events, see the ESP Workload Manager User’s Guide.For information on holding an Event, see the HOLD command.For information on using RELEASE within an Event, see the RELEASE Command—Event Level.

Example Releases an EventIn the following example, CYBER.PAYROLL was previously held and is now eligible for execution if the hold count was one. Otherwise, the hold count was decrement by one.RELEASE CYBER.PAYROLL

Operand Descriptioneventid Indicates a valid Event name. If no prefix is specified, ESP uses the

current prefix, set by the GROUP command.

1041

RELEASE Statement: Identify Successors

Identifies a successor to a job. The successor is released upon completion of this job.

TypeApplication statement.

SyntaxRELEASE {jobname}

{(jobname[(A)|(U)|(N)][,jobname[(A)|(U)|(N)]...])}{ADD(jobname[(A)|(U)|(N)][,jobname[(A)|(U)|(N)]...])}{DROP(jobname[(A)|(U)|(N)][,jobname[(A)|(U)|(N)]...])}

Usage notesThe RELEASE statement increases the hold count of any successor jobs that you name, assuming this job and the successor jobs are selected for execution.The termination operands (A,U,N) are available only for jobs in an Application. For jobs in JES3 or DJC jobnets, the ABNORMAL and NORMAL operands as documented in the JES3 or DJC User’s Guide can be used instead of the A and N options to release jobs.

Related informationFor information on other ways of specifying predecessor and successor relationships, see the AFTER, PREREQ, and POSTREQ statements.For information on specifying job relationships and selecting jobs for submission, see the ESP Workload Manager User’s Guide.

Operand Descriptionjobname The job to release. Job names can be up to eight characters and can have an

optional qualifier with eight characters also. Enclose multiple job names in parentheses, separated by a blank or a comma.

ADD The jobs to add to those currently defined RELEASE statements. DROP The jobs to drop from those currently defined RELEASE statements.

A Releases the specified jobs on abnormal termination, including condition code failures, of a predecessor.

U Releases the specified jobs on any termination of a predecessor.N Releases the specified jobs on normal termination of a predecessor. This is the

default.

RELEASE Statement: Identify Successors

1042

Examples Release PAYJOB2 upon successful completion of PAYJOB1In this example, PAYJOB2 is defined as a successor to PAYJOB1 and is eligible for submission upon the successful completion of PAYJOB1.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'UNIX_JOB PAYJOB1 AGENT UNIX_NY SCRIPTNAME /pay/data/payrpt RUN WORKDAYS RELEASE PAYJOB2JOB PAYJOB2 RUN WORKDAYSENDJOB

Release multiple jobs upon completion of PAYJOB3In this example, PAYJOB4, PAYJOB5, and PAYJOB6 are defined as successors to PAYJOB3 and are eligible for submission upon the successful completion of PAYJOB3.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 RUN WORKDAYS RELEASE (PAYJOB4,PAYJOB5,PAYJOB6)JOB PAYJOB4 RUN WORKDAYSJOB PAYJOB5 RUN WORKDAYSJOB PAYJOB6 RUN FRIDAYSENDJOB

Release PAYJOB8 upon abnormal termination of PAYJOB7In this example, PAYJOB8 is defined as a conditional successor to PAYJOB7 and is eligible for submission upon the abnormal termination of PAYJOB7. If PAYJOB7 completes successfully, PAYJOB8 is not eligible for submission.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB7 RUN WORKDAYS RELEASE (PAYJOB8(A))JOB PAYJOB8 CONDITIONAL RUN WORKDAYSENDJOB

1043

Release PAYJOB10 when PAYJOB9 completes, successfully or notIn this example, PAYJOB10 is defined as a conditional successor to PAYJOB9 and is eligible for submission after PAYJOB9 completes, successfully or not.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB9 RUN WORKDAYS RELEASE (PAYJOB10(U))JOB PAYJOB10 CONDITIONAL RUN WORKDAYSENDJOB

Release multiple jobs after PAYJOB11 is completeIn these examples, PAYJOB12 and PAYJOB13 are submitted after the successful completion of PAYJOB11.Example 1APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB11 RUN WORKDAYS RELEASE ADD(PAYJOB12) RELEASE ADD(PAYJOB13) JOB PAYJOB12 RUN WORKDAYSJOB PAYJOB13 RUN WORKDAYSENDJOB

Example 2APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB11 RUN DAILY RELEASE PAYJOB12 RELEASE ADD(PAYJOB13)ENDJOBJOB PAYJOB12 RUN DAILYJOB PAYJOB13 RUN DAILYENDJOB

REMOTEFILENAME Statement: Specify Remote Filename Within FTP_JOB

1044

REMOTEFILENAME Statement: Specify Remote Filename Within FTP_JOB

The REMOTEFILENAME statement specifies the remote files to be transferred when using the FTP_JOB statement.

ApplicabilityESP System Agents, Release 6, used within an FTP_JOB workload object. For more information, see “FTP_JOB Statement: Identify the Name of FTP Jobs” on page 623.

SyntaxREMOTEFILENAME filename

Usage notesREMOTENAME is the short form of REMOTEFILENAME.REMOTEFILENAME is a required statement within an FTP_JOB workload object. On UNIX, if you want to use a Windows file as a remote file, you need to use a forward slash in the path statement. For example:REMOTEFILENAME /C:/TEMP/textfile

ExamplesExample 1In this example, a single file is downloaded.FTP_JOB FTPTEST5.DOWNLOAD AGENT R6AGENT USER test SERVERADDR hprsupp SERVERPORT 21 TRANSFERDIRECTION D FTPFORMAT A REMOTENAME /u1/qatest/ftpdata/textfile LOCALNAME /export/home/qatest/ftpdata/textfile_dn RUN DAILYENDJOB

Operand Descriptionfilename Use a full path statement. The format is case sensitive, any

character, up to 256 characters in length.

1045

Example 2 In this example, multiple local files are downloaded. Note that the number of entries listed in the statements REMOTEFILENAME and LOCALFILENAME must match. Single quotes enclose both lists to accommodate the line continuation character (+).FTP_JOB FTPT14.DOWNLOAD AGENT R6AGENT AFTER CHECK.PART1 USER test SERVERADDR hprsupp SERVERPORT 21 TRANSFERDIRECTION D FTPFORMAT A REMOTENAME '/u1/qatest/scripts/echo;+ /u1/qatest/scripts/echo1;+ /u1/qatest/scripts/echo2' LOCALNAME '/export/home/qatest/ftpdata/echo;+ /export/home/qatest/ftpdata/echo_1;+ /export/home/qatest/ftpdata/echo_2' RUN DAILYENDJOB

Example 3If a wildcard is used for the remote file name, the corresponding local file name (the target) must refer to a directory. In this example, the directory is WC.FTP_JOB FTPT13.DN AGENT R6AGENT AFTER CHECK.PART1 USER test SERVERADDR hpunsup SERVERPORT 21 TRANSFERDIRECTION D FTPFORMAT A REMOTENAME /u1/qatest/scripts/r* LOCALNAME /export/home/qatest/ftpdata/WC RUN DAILYENDJOB

REMOTEFILENAME Statement: Specify Remote Filename Within FTP_JOB

1046

Example 4In this example, a file called textfile is uploaded and copied to a remote Windows machine. Both locations include a complete path statement. After the upload is complete, the job FTPJOB2.DOWNLOAD is released for execution. In this example, we use an R6 window Agent as an FTP server. Its IP address is 111.11.22.333.FTP_JOB FTPTEST1.DOWNLOAD AGENT R6AGENT USER test SERVERADDR 111.11.22.333 SERVERPORT 123 TRANSFERDIRECTION U TRANSFERCODETYPE A REMOTEFILENAME /C:/TEMP/textfile LOCALFILENAME /export/home/qatest/ftpdata/textfile RUN DAILY RELEASE FTPJOB2.DOWNLOADENDJOB

Note: For Windows examples, substitute a Windows path in the LOCALFILENAME statement.

1047

REMOVE Command: Identify Lines to be Removed

The REMOVE command is used in conjunction with the GENDOC, LABEL and GO commands when converting an existing job documentation library to a documentation library usable by ESP. The REMOVE command identifies lines that are not to be copied to the output data set.

Type General command.

SyntaxREMOVE 'string'

Usage notesThe GENDOC command identifies the input data set, members to be copied, and the output data set. It also lets you identify changes you want to make when the old documentation converts. Use REMOVE, LABEL, and GO in conjunction with the GENDOC command to customize the conversion of existing job documentation to ESP job documentation.

Related informationFor information on converting existing job documentation, see the GENDOC command.For information on altering or replacing lines in the output data set during the conversion, see the LABEL command.For information on indicating that all specifications are complete and that the copy process should proceed, see the GO command.For information on job documentation, see the ESP Workload Manager User’s Guide.

Operand Descriptionstring Indicates any character string enclosed in quotes.

REMOVE Command: Identify Lines to be Removed

1048

Example Used to convert existing job documentationThe following GENDOC, REMOVE, LABEL, and GO commands are used to convert existing job documentation:GENDOC 'JOBDOC.DATA' 'ESP.JOBDOC.DATA' LEV(A–,B–) SNUMREMOVE '**'LABEL 'SYSOUT REVIEW' 'SYSOUT_REVIEW' INLINELABEL 'STEP***' '@:' OVERLAYLABEL 'RESTART PROCEDURES' 'RESTART:' BEFOREGO

In the above example, ESP will:• Copies all members beginning with A and B from the data set JOBDOC.DATA to

the data set ESP.JOBDOC.DATA, suppressing any line numbers in the right–hand eight columns of each source member record.

• Does not copy any lines containing “**”.

• Replaces any lines starting with SYSOUT REVIEW with the character string SYSOUT_REVIEW.

• Overlays the semicolon on any line beginning with STEP. The semicolon is positioned after the third character following the string STEP.

• Places the label RESTART: on its own line before any line starting with the string RESTART PROCEDURES.

• Proceed with the copy process.

1049

REPORT Command: Begin Report Definition

The REPORT command is used to begin a report definition.

TypeReporting command.

SyntaxREPORT

Usage notesThe ENDR command must end the report definition. For more information, see the ENDR command.

Related informationFor more information on ending a report definition see the ENDR command.

Example 7 am yesterdayIn the following example:• The REPORT command invokes the report processor• The FROM, CRITERIA, and DISPLAY report statements define the report• The ENDR command ends the report definition and initiates report generation.REPORTFROM 7AM YESTERDAYCRITERIA APPLSYS EQ PAYROLLDISPLAY JOBNAME JOBNO APPLSYS CMPCENDR

REQUESTSET Statement: Identify an Oracle Applications Request Set

1050

REQUESTSET Statement: Identify an Oracle Applications Request Set

The REQUESTSET statement identifies the short name of an Oracle Applications Request Set.

ApplicabilityESP Business Agent for Oracle E-Business Suite, OA_JOB Request Sets only.

SyntaxREQUESTSET name

Tip: In Oracle Applications, the Request Set short name is part of the Request Set definition, and is found in the Set Code field of the Request Set dialog.

UsageUse OA_JOB Request Sets to run multiple program requests.The short form REQSET can be used in place of REQUESTSET.This statement is mandatory for OA_JOB Request Set definitions.

ExamplesIdentify an OA_JOB Request SetIn the following example, the name DATA10 is used to identify an OA_JOB Request Set:APPL ACC03 AGENT CYBOA OA_JOB AOL405.AP035 REQUESTSET DATA10 RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN ENDJOB

Operand Descriptionname The name must match an existing Oracle Applications Request

Set short name. Characters are case-sensitive. If you use delimiters, such as spaces, the name must be enclosed in single quotes. Maximum 30 characters.

1051

RERUNM Command: Rerun Multiple Jobs

The RERUNM command reruns multiple jobs. The command resets specified jobs to the state before they ran. Application Manager schedules a rerun for them as their dependencies are satisfied. You can use RERUNM to do the following:• Specify multiple jobs or specify a data set that contains the list of jobs to rerun.• Rerun a chain of successive jobs by specifying the root job of the chain.• Generate a list of jobs selected for rerun (simulate).• Request ESP Encore restart from the first step for z/OS jobs (requires ESP Encore

3.1).• Specify USER variables for rerun.• Specify variables for ESP Encore restart.

TypeGeneral command.

SyntaxRERUNM APPLICATION(appl_name[.gen]) {ROOTJOBS(name.qual[+],...) | RDSNAME(dsname)} [NOPROMPT|SIMULATE] [RESTART[(YES|NO)] [RPARMS('restart_parm_string')] [GPARMS('general_parm_string')]

Operand Descriptionappl_name Application name.gen Generation number of the Application.

• Positive–Absolute generation number• 0–Current generation (default)• Negative–Relative to the current generation

RERUNM Command: Rerun Multiple Jobs

1052

ROOTJOBS(name.qual[+],...) A list of jobs to rerun. For each job, specify the job name (name)and optional qualifier (qual).• You can specify a root job by appending a ‘+’ to the job

name. The root job and all the dependant jobs will be rerun.

• Both the name and qualifier accept wildcards. Use an asterisk (*) to represent any single character and a hyphen (-) to represent any suffix.

Note: ESP Workload Manager matches wildcards separately for job name and qualifier. For example, ROOTJOBS(A-) matches any job name starting with ‘A’ that has no qualifier. ROOTJOBS(A-.-) matches any job name starting with ‘A’ with or without a qualifier.

• To specify multiple jobs, separate them by commas.RDSNAME(dsname) Name of the data set that contains the list of jobs to be rerun.

Some or all of these jobs may be root jobs for other dependent jobs. The RERUNM command reruns the dependent jobs too.

The data set has the following syntax:• Each line of the data set can contain a single job name or

a list of job names in brackets.• The syntax of the job name is the same as the value of

ROOTJOBS (see above).• To continue a bracketed list on the next line, add a

hyphen (-) or plus sign (+) at the end of the line.

Note: The root job suffix (+) will be interpreted as a continuation sign if it is the last character on the line. To prevent this, place a comma at the end of the line.

The data set has the following limitations:• For data sets with 80 byte records, the positions 73–80

are ignored.• The data set can contain any number of bracketed lists.• A single list cannot be longer than 32K.

You can use the LISTROOT command to prepare the data set. For information on the LISTROOT command, see “LISTROOT Command: Save List of Waiting Jobs for Rerun into Data Set” on page 779.

Operand Description

1053

Usage notesThis command resets jobs for a rerun. If a specified job did not run the first time, the job will not be reset or rerun. To generate a list of jobs selected for rerun, specify the SIMULATE operand. If you rerun jobs that contain RELDELAY statements, ESP Workload Manager ignores them on rerun.

Note: If you specify a root job with a ‘+’ suffix either in the ROOTJOBS operand or in the data set in the RDSNAME operand, the RERUNM command reruns all jobs dependent on the root job. This may cause a problem if a job that is dependent on the root job had already run prior to the root job running. You may not want that job to be rerun.

Related informationFor information on preparing the data set for rerun, see the LISTROOT command.For information on ESP Encore, see the ESP Encore User’s Guide.

NOPROMPT Requests immediate execution of the command without confirmation.

SIMULATE Generates list of jobs selected for rerun. Does not rerun the jobs.

Note: Before rerunning multiple jobs, Cybermation recommends you use this operand to verify the list of jobs to be rerun.

RESTART[(YES|NO)] Requests ESP Encore restart or a simple resubmission.• YES–Requests ESP Encore restart from the first step of

z/OS jobs (default). Requires ESP Encore 3.1.• No–Requests a simple resubmission. Equivalent to

omitting the RESTART keyword.RPARMS('restart_parm_string') Specifies variables for ESP Encore restart. You can specify

up to 12 ESP Encore (ENCPARM) commands. For each command, append a number (1-9, A, B, C) after ENCPARM. For example:

RPARMS(‘ENCPARM1(“CLEANUP RESTART(YES)”)’)

GPARMS('general_parm_string') Specifies USER variables for rerun. You can specify up to four variables. For each variable, append a number (1-4) after USER. For example:

GPARMS(‘USER1(AA) USER2(BB)’)

Operand Description

RERUNM Command: Rerun Multiple Jobs

1054

ExamplesNote: These examples assume all specified jobs are reset and rerun. To generate a list

of jobs selected for rerun, specify the SIMULATE operand.

Rerun a stream of jobsIn this example, job PAYJOB5 and its successors are reset and rerun in generation 3 of Application PAYROLL. The example also requests an ESP Encore restart, asks ESP Encore to perform data set cleanup during the rerun, and specifies two USER variables for the rerun. RERUNM APPLICATION(PAYROLL.3) ROOTJOBS(PAYJOB5+) -RESTART(Yes) RPARMS(‘ENCPARM1(“CLEANUP RESTART(YES)”)’) -GPARMS(‘USER1(AA) USER2(BB)’)

Rerun multiple jobs from listIn this example, jobs PAYJOB5 and PAYJOB6 are reset and rerun in generation 3 of Application PAYROLL. RERUNM APPLICATION(PAYROLL.3) ROOTJOBS(PAYJOB5, PAYJOB6)

Rerun multiple jobs from data setIn the following example, jobs listed in data set PA.RERUN.JOBLST01 are reset and rerun in the current generation of Application PAYROLL. The current generation is used because gen (the Application generation number) is 0.RERUNM APPLICATION(PAYROLL.0) RDSNAME(PA.RERUN.JOBLST01)

1055

RESDEF Command: Define Resources

The RESDEF command is used to define, display, delete, or update resources.

TypeAuthorized command

AuthorityYou control access to resources using the RESOURCE.resname resource.

SyntaxRESDEF name [ADD|DEL|LIST|SET] [ENTERPRISE|NODAL|GLOBAL|LOCAL] [THRESHOLD|RENEWABLE|DEPLETABLE] [OWNERS|WAITERS] [NODE(xxx)][CPU(xxx)] [MAX(n)][AVAIL(0)] [DEVICE(xxxxx)|WLM(duration) |MONITOR(CPU) POLL(xx HOURS|xx MINUTES|xx SECONDS)] [GRAVITY|NOGRAVITY] [COMMENT(comment)] [FORCE]

Operand Descriptionname Indicates the resource name using up to 44 alphanumeric characters,

the first of which must be alphabetic or national.The resource name must not end with a period or use two consecutive periods. (When using the LIST, DEL, or SET operands, wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.)

ADD Indicates you are defining a new resource.DEL Deletes one or more existing resource definitions.LIST Displays a list of one or more existing resource

definitions.SET Modifies attributes of a resource definition. Resource type and

scope cannot be modified.ENTERPRISE Indicates the resource is equally available across the entire

enterprise.

RESDEF Command: Define Resources

1056

NODAL|GLOBAL Indicates one resource counter is available for each node. This maintains one resource pool for each node. NODAL and GLOBAL are aliases of each other.

Note: NODAL is preferred since NODAL|GLOBAL defines the scope of the resource as a node in the resource topology.

LOCAL Indicates one resource counter is maintained for each z/OS image.THRESHOLD Defines a threshold resource type.RENEWABLE Defines a renewable resource type.DEPLETABLE Defines a depletable resource type.OWNERS Displays jobs that are currently executing and holding a resource.

This is used with LIST.WAITERS Displays jobs waiting for a resource. This is used with LIST.NODE(xxx) Refers to the node name defined when the system topology was

specified. Limits LIST or SET to a specific node.CPU(xxx) Refers to the CPU name defined when the system topology was

specified. Limits LIST or SET to a specific CPU.MAX(n) Sets maximum counter value for resource you are defining. AVAIL(n) Sets available value for resource you are defining. DEVICE (xxxxx) Indicates either the IBM generic or esoteric device name that ESP is

to monitor.WLM(duration) Specifies that ESP Workload Manager obtains the number of unused

CPU service units over the specified period from IBM WLM. The number of unused CPU service units is obtained before a job using the resource is submitted and is used for WLM workload balancing. The following three period durations are supported:• SUM60—the unused CPU service units are summed over the

last 60 seconds.

• SUM180—the unused CPU service units are summed over the last 180 seconds.

• SUM600—the unused CPU service units are summed over the last 600 seconds.

The WLM operand is relevant only if the ESP Workload Manager High Performance Option (HPO) is installed. If you use the WLM operand without HPO installed, the WLM operand is ignored. Refer to the ESP Workload Manager High Performance Option in the ESP Workload Manager User’s Guide for information on how to use WLM workload balancing.

Operand Description

1057

Usage notes - defining a resourceBefore you use the resources feature, a data set called the RESFILE needs to be defined and identified in the ESP initialization parameters. CPU and NODE definitions are also required. The RESFILE is used to store the following information:• System topology• Resource definitions• Allocation of resources for example, jobs that have resources allocated to them

and jobs waiting to allocate resources.When you define a resource, you need to• Name the resource• Use the ADD keyword to indicate you are defining a new resource• Indicate the scope of the resource—local, global, or enterprise

MONITOR(CPU) Specifies that the system asks all Agents to provide the percentage of availability of the CPUs they control at the frequency specified by the POLL operand.

The MONITOR operand is relevant only if the ESP Workload Manager High Performance Option (HPO) is installed. If you use the MONITOR operand without HPO installed, the MONITOR operand is ignored. Refer to the ESP Workload Manager High Performance Option in the ESP Workload Manager User’s Guide for information on how to use Agent workload balancing.

POLL(xx HOURS|xx MINUTES|xx SECONDS)

Specifies how often the system asks all Agents to provide the percentage of availability of the CPUs they control. xx is a number with a maximum corresponding to 24 hours. If POLL specifies 0, it means that the system does not ask Agents to provide the percentage of availability of the CPUs they control. ESP Workload Manager automatically increases the percentage of availability of the CPUs immediately when a job completes.The POLL operand is relevant only if the ESP Workload Manager High Performance Option (HPO) is installed. If you use the POLL operand without HPO installed, the POLL operand is ignored.

GRAVITY Indicates jobs are to be routed to other nodes on which the resource is available.

NOGRAVITY Indicates jobs are not to be routed to other nodes on which a resource is available.

COMMENT (comment) Used to add additional information about a particular resource.FORCE Used in conjunction with the DEL operand to delete a resource

regardless of whether it is in use or not.

Operand Description

RESDEF Command: Define Resources

1058

• Indicate the type of resource—renewable, depletable, or threshold• Indicate if the resource represents a real device• Indicate the CPU to which the resource applies• Indicate whether the resource has gravity• Specify the quantities of the resource—available and maximum.

Resources with WLM operandYou must define a WLM resource as LOCAL RENEWABLE. To fully benefit from this resource type in a multi JES node sysplex environment, you must specify GRAVITY in the resource definition.To determine the MAX count, refer to the CPU capacity table in the MVS planning: Workload Management IBM manual. Choose a number of service units per second for your CPU model and multiply it by either 60, 180, or 600 for SUM60, SUM180, or SUM600 respectively. You can use the result or any higher number. If your installation has CPUs of different models, use the RESDEF SET command to adjust the counts on individual CPUs.You can determine the quantity of the WLM resource required by jobs using either the CPU service units or the CPU time shares (percentage) of jobs in the entire workload. You can calculate these numbers based on ESP Workload Manager history reports with the SUNITS field selected. You can also use other performance and reporting tools. It is important that you understand that the resource represents the rate at which service units are consumed (over the last 60, 180, or 600 seconds), and not the total amount used by a job. Reports usually show the total amount.ESP Workload Manager selects to route a job to one of the available systems based on the WLM resources requested by a job and other requested resources.IBM WLM feedback is a measurement of recent but past activity; therefore, it is not a precise prediction of a CPU load by the time ESP Workload Manager submits a job. The real value of a WLM resource is the number of unused service units. This number can be different from the number of service units available for a job if that job service class is higher than the service class of the currently executing workload.The workload is balanced between all the CPUs that include the same NODE operand in the CPU command or initialization parameter representing that CPU. The node is defined with the NODE command or initialization parameter (it must include a SYSPLEX operand).

Resources with MONITOR(CPU) operandYou must define a MONITOR(CPU) resource as LOCAL RENEWABLE. To fully benefit from this resource type in an environment with CPUs associated with ESP Agents, you must specify GRAVITY on the resource definition.

1059

The system asks all Agents to provide the percentage of availability of the CPUs they control. This is done at the frequency specified by the POLL operand for CPUs where the corresponding CPU initialization parameter includes an AGENT operand. You can limit the scope of the resource you define by using the NODE and CPU operands.ESP Workload Manager selects to route a job to one of the available systems based on the MONITOR(CPU) resources requested by a job and other requested resources.The workload is balanced between all the CPUs that include the same NODE operand in the CPU command or initialization parameter representing that CPU. The node is defined with the NODE command or initialization parameter.

Examples Resource definitions are stored in the RESFILE. If ESP Workload Manager is started with the RESFORM option, information stored in the RESFILE is lost. A useful technique to ensure that system topology and resource definitions are not lost on a reformat (RESFORM) of the RESFILE, is to code the following in your ESP initialization parameters:IF RESFORM THEN DO NODE TORONTO ADD ROUTEJCL('/*XEQ TORONTO') CPU T1 ADD NODE(TORONTO) ROUTEJCL('/*JOBPARM SYSAFF=T1') ORDER(1) CURRENT CPU T2 ADD NODE(TORONTO) ROUTEJCL('/*JOBPARM SYSAFF=T2') ORDER(2) CPU T3 ADD NODE(TORONTO) ROUTEJCL('/*JOBPARM SYSAFF=T3') ORDER(3) RESDEF T3480 ADD LOCAL RENEWABLE MAX(5) CPU(T1) RESDEF CICSUP ADD NODAL THRESHOLD AVAIL(0) RESDEF DB2TAB1 ADD NODAL RENEWABLE AVAIL(3) ENDDO

If you are using the resource feature extensively and have a large number of resources defined, it may not be desirable to code all your resource definitions in the ESP Workload Manager initialization parameters. An alternative method is to store your resource definitions in a data set and issue the LOAD command to process the RESDEF commands, in the event the RESFILE is reformatted.Note: The LOAD command cannot be used in the ESP Workload Manager

initialization parameters.Usage notes-resource countsYou can specify maximum and available counts for a resource. For depletable and threshold resources, there is only one quantity. You can specify either maximum (MAX) or available (AVAIL). For renewable resources, there are maximum and available quantities. Maximum is the total quantity of the resource; available is the current quantity.You cannot modify the AVAIL count independently of the MAX count for renewable resources when USERMOD 75 is activated.

RESDEF Command: Define Resources

1060

When setting a renewable resource: • Setting the MAX count automatically adjusts the AVAIL count.• Setting the AVAIL count has no effect on the MAX count.The following is an example of the display produced when a resource is listed and what happens when the MAX and AVAIL counts are manipulated:RESDEF CICS LISTResource CICS Local RenewableTORONTO MVSA Max=2 Avail=2

RESDEF CICS SET MAX(4)Resource CICS Local RenewableTORONTO MVSA Max=4 Avail=4

RESDEF CICS SET AVAIL(6)Resource CICS Local RenewableTORONTO MVSA Max=4 Avail=6

The following is an example of the display produced when a resource is listed and what happens when the AVAIL count is changed for a threshold resource:RESDEF DAYSHIFT LISTResource DAYSHIFT Local ThresholdTORONTO MVSA Avail=1

RESDEF DAYSHIFT SET AVAIL(2)Resource DAYSHIFT Local ThresholdTORONTO MVSA Avail=2

Usage notes - Real resourcesReal resources are intended to work in a single CPU environment, as there is no capability to be aware of the status of devices on any CPU other than the one where the master ESP Workload Manager is running. Therefore real resources should be defined as LOCAL and RENEWABLE, using the MAX operand to identify the number of devices being made available to ESP submitted jobs, as follows:RESDEF T3480 ADD LOCAL RENEWABLE MAX(5) DEVICE(3480)

The following is an example of the display produced when listing the above resource:RESDEF T3480 LISTResource T3480 Local RenewableTORONTO MVSA Max=5 Avail=5 Real=5

ESP Workload Manager ensures there are sufficient online, unallocated devices available to satisfy the resource requirements for the current job.For example, if job PAYJOB1 requires three units of a real resource called T3480, and ESP Workload Manager sees three available, but only two devices are actually online and unallocated, ESP Workload Manager waits for resources and PAYJOB1 goes into a RESWAIT state.

1061

Related informationFor information on requesting resources, see the RESOURCE statement.For information on specifying default resources, see the RESDFLT command.For information on resources, see the ESP Workload Manager User’s Guide.

ExamplesDisplaying resource definitionsIn the following example, all existing resource definitions are displayed:RESDEF - LIST

Defining a renewable resourceIn the following example, IMS is a local, renewable resource with a quantity of three. IMS resides on the TOR1 z/OS image and is used to represent access to an IMS region. The maximum number of jobs requiring one unit of the IMS resource that can run concurrently is three.RESDEF IMS ADD LOCAL RENEWABLE MAX(3) CPU(TOR1)

Defining a global threshold resourceIn the following example, NITESHFT is a global, threshold resource with a quantity of one. NITESHFT represents a time period when specific jobs can run. The NITESHFT resource can be manipulated, using the SET operand at the appropriate times to ensure night shift jobs run between 1 am and 8 am for example.RESDEF NITESHFT ADD NODAL THRESHOLD AVAIL(1)

Defining a local threshold resourceIn the following example, PAYJOB1 is a local, threshold resource with a quantity of 0. PAYJOB1 is used to represent the completion of a job. The PAYJOB1 resource can be manipulated, using the SET operand after the successful completion of PAYJOB1 to allow successor jobs to be submitted.RESDEF PAYJOB1 ADD LOCAL THRESHOLD AVAIL(0)

Defining a real resourceIn the following example, T3480 is a local, renewable resource representing 3480 cartridge drives. The number of tape drives currently on-line and not allocated is compared with ESP’s internal counters to determine when jobs that require the T3480 resource are eligible for submission. RESDEF T3480 ADD LOCAL RENEWABLE DEVICE(3480)

RESDEF Command: Define Resources

1062

Defining a local renewable resourceIn the following example, CICS is a local, renewable resource with a quantity of one. CICS resides on the TOR2 z/OS image and is used to represent access to a CICS region. The GRAVITY attribute indicates that the CICS resource is available to jobs on other nodes. If a job on another node requires the CICS resource, the appropriate routing information is inserted into the requesting job JCL per the system topology statements.RESDEF CICS ADD LOCAL RENEWABLE MAX(1) CPU(TOR2) GRAVITY

Defining a default resourceIn the following example:• The RESDFLT initialization parameter or command indicates ESP should make

default resource assignments for scratch tapes.RESDFLT SCRATCH(SCRTAPES)

• The RESDEF command defines a global, depletable resource with a quantity of 500. ESP uses historical information to assign scratch tape resource requirements to each job in an Application.

RESDEF SCRTAPES ADD NODAL DEPLETABLE AVAIL(500)

Note: Once default resources are turned on, every Application generated by ESP uses default resources. To drop a default resource, code the following:

RESOURCE (0,SCRTAPES)

Modifying attributes of an existing thresholdIn the following example, the available quantity of the LOWPRIO resource is set to one:RESDEF LOWPRIO SET AVAIL(1)

Modifying attributes of an existing depletable sourceIn the following example, the available quantity of the SCRTAPES resource is set to 550:RESDEF SCRTAPES SET AVAIL(550)

Modifying attributes of an existing renewable sourceIn the following example, the quantity of the CICSUP resource is set to two:RESDEF CICSUP SET MAX(2)

Deleting a resourceIn the following example, the COCONUT resource is deleted:RESDEF COCONUT DELETE

1063

Displaying a specific resourceIn the following example, jobs using, and jobs waiting for, the DBASE resource are displayed:RESDEF DBASE LIST OWNERS WAITERS

Define RESDEF for WLM workload balancingThe following example creates the RESMAIN resource and specifies that ESP Workload Manager will receive the status of every CPU in the TORONTO node every 180 seconds.RESDEF RESMAIN ADD NODE(TORONTO) LOCAL RENEWABLE GRAVITY + MAX(100) WLM(SUM180)

If you have HPO installed and the SYSPLEX operand is coded in the NODE command or initialization parameter, ESP Workload Manager can balance the workload between cpus belonging to one node. Refer to the ESP Workload Manager High Performance Option in the ESP Workload Manager User’s Guide for information on how to use WLM workload balancing.Define RESDEF for Agent workload balancingThe following example creates the RESWIN resource and specifies that ESP Workload Manager will receive the status of every CPU in the WIN node every five minutes.RESDEF RESWIN ADD NODE(WIN) LOCAL RENEWABLE GRAVITY MAX(100)+ MONITOR(CPU) POLL(5 MINUTES)

ESP Workload Manager can balance the workload between cpus belonging to one node. Refer to the ESP Workload Manager High Performance Option in the ESP Workload Manager User’s Guide for information on how to use Agent workload balancing.

RESDFLT Command: Identify Default Resources

1064

RESDFLT Command: Identify Default Resources

The RESDFLT command is used to identify the default resources you want to use. ESP can make default resource assignments automatically for the following: number of tape drives needed, number of scratch tapes needed, percentage of CPU absorption, total CPU time used, total elapsed time used, and total print lines generated.

TypeGeneral command.

AuthorityYou require OPER authority to issue the RESDFLT command.

SyntaxRESDFLT [LIST] [CARTRIDGE(cart)] [SCRATCHCART(scratch)] [CPUABSORPTION(cpuabs)] [CPUTIME(cputime)] [ELAPSEDTIME(elapsed)] [PRINTLINES(prlines)]

Operand DescriptionLIST Displays the current default resources.cart Indicates the name of a cartridge tape resource. It should be a global renewable

resource and should identify a device name. ESP requests a value equal to the average tape drive high water mark for a job, for example, the average of the maximum number of tape drives required by the job at any one moment in time. Resource names are restricted to eight characters.

scratch Indicates the name of a scratch tape resource. It should be defined as a depletable resource. This resource should be adjusted to the number of scratch tapes made available to ESP jobs. Resource names are restricted to eight characters.

cpuabs Indicates a resource that reflects CPU absorption. When ESP submits a job, it looks at the average CPU absorption, calculated as CPU time divided by elapsed time and expressed as a percentage. It then assigns that many units of the named resource. For example, if a job uses 10% of the CPU when it executes, ESP requests 10 units of the CPU absorption resource. This resource should be defined as a local renewable resource. Assign a value equal to the maximum CPU utilization you want for ESP submitted jobs. For example, if you want ESP to submit jobs that only use up to 80 percent of the CPU, set this value to 80. Resource names are restricted to eight characters.

1065

Usage notesThe RESDFLT command is normally stored as an ESP initialization parameter, otherwise it disappears with each restart of ESP.Once you have identified the default resources your installation requires, use the RESDEF command to specify the resource type—renewable, depletable, or threshold, and the scope of the resource—local, global, or enterprise.You can use one or more default resources.The information used to assign default resources is based on information contained in the Job Index file. ESP bases the default resource levels it assigns on an average of the samples found in this file. The number of samples depends on the index count specified when the Job Tracking Model was defined. Only information from normal job completions, and not from abends, is used. The information is updated each time a new generation of an Application is created.Once default resources are turned on, every Application generated by ESP uses default resources. To drop a default resource, request zero unit of the resource. For example:RESOURCE (0,SCRTAPES)

Related informationFor information on requesting resources, see the RESOURCE statement.For information on defining resource, see the RESDEF command.

cputime Indicates the name of a resource that represents the total CPU time used by a job, expressed in seconds. This is normally a threshold local resource. You can use it to limit the execution of jobs that require more than a certain threshold of CPU time. Resource names are restricted to eight characters.

elapsed Indicates the name of a resource that represents total elapsed time used by a job, expressed in minutes. This is normally a threshold local resource. You can use it to prevent submission of jobs that require more than a certain threshold of elapsed time. For example, if you are scheduling a shutdown of a certain z/OS system, you can set the maximum availability of the resource to the number of minutes before the scheduled shutdown. ESP does not submit a job that can, on average, complete prior to the scheduled shutdown time. This value can be adjusted down automatically, as the scheduled time draws closer, through an automation program or through an ESP Event. Resource names are restricted to eight characters.

prlines Indicates the name of a resource that represents the total print lines generated by a job. This is normally a global threshold or depletable resource. You can use it to limit submission of jobs that require more than a certain quantity of spool space. This is determined by the spool size in your installation. Resource names are restricted to eight characters.

Operand Description

RESDFLT Command: Identify Default Resources

1066

For information on specifying default resource at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.For information on resources, see the ESP Workload Manager User’s Guide.

Examples Display default resourceIn the following example, all default resources are displayed.OPER RESDFLT LIST

OPER RESDFLT SCRATCH(SCRTAPES) ELAPSEDTIME(ELAPSE)

Define default resourceIn the following example:• The RESDFLT initialization parameter or command indicates ESP should make

default resource assignments for scratch tapes. • The RESDEF command defines a global, depletable resource with a quantity of

500. • ESP uses historical information to assign scratch tape resource requirements to

each job in an Application. ESP automatically decrements the SCRTAPES resource as jobs run. RESDFLT SCRATCH(SCRTAPES)

RESDEF SCRTAPES ADD GLOBAL DEPLETABLE AVAIL(500)

Note: Once default resources are turned on, all Applications generated by ESP use default resources. To drop the SCRTAPES default resource, code the following:

RESOURCE (0,SCRTAPES)

After creating more scratch tapes, use the following command to set the new count:RESDEF SCRTAPES SET AVAIL(750)

Alter specific default resource nameIn the following example, the name previously assigned to this default resource is changed to BLANKTAP.OPER RESDFLT SCRATCH(BLANKTAP)

Defines a default resourceThe following RESDFLT and RESDEF commands define a default resource:RESDFLT ELAPSEDTIME(ELAPSE)

RESDEF ELAPSE ADD LOCAL THRESHOLD AVAIL(60)

1067

In the preceding example:• The RESDFLT initialization parameter or command indicates ESP should make

default resource assignments for elapsed time used by a job.• The RESDEF command defines a local, threshold resource with a quantity of 60. • ESP uses historical information to prevent submission of jobs that require more

than a certain threshold of elapsed time.The following is an example of a recursive ESP Procedure that could be used to notify users of a system shutdown and prevent long-running jobs from starting using the ELAPSE default resource defined above:/* PASS NUMBER OF MINUTES TO SHUTDOWN USING USER1/* PARAMETER WHEN TRIGGERING THE EVENT /*/* SEND MESSAGE, DECREMENT TIME AND RE–TRIGGER EVENT IN/* 1 MINUTE IF TIME >= 0/*INTEGER TIMETIME=USER1SEND 'SYSTEM COMING DOWN IN %TIME MINUTES' USER(CYB01)ESP RESDEF ELAPSE SET AVAIL(%TIME)TIME=TIME–1IF TIME>=0 THEN ESP TRIGGER OPER.SHUTDOWN +USER1('%TIME') AT('NOW PLUS 1 MINUTE')

RESOLVE Statement: Resolve External Job Dependencies

1068

RESOLVE Statement: Resolve External Job Dependencies

The RESOLVE statement is used to instruct ESP to look at a scheduled activity data set to resolve an External job dependency. Note: ESP automatically selects the job if it is found.

SyntaxRESOLVE identifier

Usage notesESP can use a scheduled activity data set (SADGEN data set) to resolve external dependencies. If ESP finds the job is scheduled, it selects the External job as part of the Application. Otherwise, it doesn’t select the External job.The SADLINK statement gives an external SADGEN data set an internal identifier. Each time ESP initializes, or in response to a SADLOAD command, the contents of the SADGEN data set is read and necessary information retained in a table in main storage. You can request that the look-up table be used to resolve External job dependencies by specifying the correct SADLINK identifier on the RESOLVE statement in an Application.A more commonly used method to control the resolution of External jobs is to use the EXTERNAL and SCHEDULED operands on the JOB statement, as this provides the most control for synchronizing Applications.

Related informationFor information on identifying an external scheduled activity data set, see the SADLINK command.

For information on refreshing an in-core table containing a scheduled activity data set, see the SADLOAD command.For information on displaying current SADLINK, see the LISTSADL command.For information on building inter-Application dependencies, see the EXTERNAL statement.

Operand Descriptionidentifier Indicates a one to eight character internal identifier of a scheduled

activity data set. This corresponds to the SADLINK initialization parameter.

1069

Example Resolve external dependencyIn the following example, the RESOLVE statement instructs ESP to look at the scheduled activity data, with the identifier SADDLY, to see if PAYJOBX is scheduled. If PAYJOBX is found, ESP selects PAYJOBX as part of the Application. Otherwise, it doesn’t select the External job.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'RESOLVE SADDLYJOB PAYJOBX EXTERNAL REL PAYJOB1 JOB PAYJOB1 REL PAYJOB2 RUN DAILYJOB PAYJOB3 RUN DAILYENDJOB

RESOURCE Statement: Identify Resources

1070

RESOURCE Statement: Identify Resources

The RESOURCE statement is used to identify resources required by individual jobs or multiple jobs in an Application, and for any other type of workload object except links. The resource information defined to a job is used for scheduling and during MODEL pro-cessing.

SyntaxRESOURCE {resname|(reslist)} {ADD(reslist)} {DROP(reslist} {HOLD|NOHOLD}

where reslist is[quantity1,|1,]resname1{,[quantity2,|1,]resname2...}

Operand Descriptionquantity1,quantity2...

The number of units of the resource required by the job or Application.

resnameresname1,resname2...

A valid resource name.

ADD Add a resource requirement in addition to the existing resource requirements.

DROP Drop a resource requirement.HOLD Hold the specified resource until the jobs affected by the

RESOURCE statement run successfully. If you specify HOLD for one RESOURCE used by a job, all resources used by the job are held.

NOHOLD Removes the hold on the specified resource. You could use this within a JOB/ENDJOB statement pair to remove a resource hold applied at the Application level. The hold would be removed for that job only.

1071

Usage notes

Dropping default resourcesOnce default resources are turned on, every Application generated by ESP uses default resources. Do not use the DROP operand to drop ESP default resource requirements. To drop a default resource, request zero units of the resource. For example:RESOURCE (0,SCRTAPES)

Overriding resources versus adding resourcesUnless you include the ADD operand, a RESOURCE statement overrides all preceding resource specifications, including the default resource specification.

Specifying resources for single jobs and multiple jobs To specify resource information for a job in an Application, add a RESOURCE statement between the JOB and ENDJOB statements. The RESOURCE statement affects only that job.To specify resource information for a group of jobs within an Application definition, add a RESOURCE statement immediately before the JOB statement of the first job in the group. This RESOURCE statement affects all subsequent jobs in the Application. If there are other jobs after the last job in your group, code another RESOURCE statement immediately after the ENDJOB statement of the last job in your group. This second statement must reverse the effect of the first one. For example, if the first statement is RESOURCE (2,CICS), code RESOURCE DROP(CICS) for the second statement. If the first statement is RESOURCE (2, DB2) HOLD, you could code RESOURCE (2,DB2) NOHOLD or RESOURCE DROP(DB2).Jobs inserted into an Application after it is generated do not inherit any resource requirements.

Related informationYou can use the ABSORB statement to reserve a quantity of resources for jobs that require a large resource count.For information on specifying the relative priority of jobs within an ESP group, see the PRIORITY statement.For information on specifying default resources, see the RESDFLT command.For information on defining resources, see the RESDEF command.For information on resources, see the ESP Workload Manager User’s Guide.

RESOURCE Statement: Identify Resources

1072

Examples Identify a resource requirement for a jobIn the following example:• PAYJOB2 requires one unit of resource IMS. Note that the default quantity is 1.• PAYJOB3 requires two units of resource T3480 and four units of resource

SCRATCH.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB2 RUN WORKDAYS REL PAYJOB3 RESOURCE (IMS)JOB PAYJOB3 RUN WORKDAYS RESOURCE (2,T3480,4,SCRATCH)ENDJOB

Identify a resource requirement for a group of jobsIn the following example, jobs PAYJOB2 and PAYJOB3 require one unit of a resource CICS. These jobs hold the CICS resource until they run successfully. The last RESOURCE statement drops the CICS resource requirement.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYS REL PAYJOB3ENDJOBRESOURCE (1,CICS) HOLDJOB PAYJOB2 RUN WORKDAYSJOB PAYJOB3 RUN WORKDAYSENDJOBRESOURCE DROP(CICS)JOB PAYJOB4 RUN WORKDAYSENDJOB

Identify resource requirements on specific daysIn the following example, PAYJOB4 requires one unit of a resource called NITESHFT, except on Fridays when resource requirements for PAYJOB4 are dropped.

1073

APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB4 RUN WORKDAYS REL PAYJOB5 RESOURCE (1,NITESHFT) IF TODAY('FRIDAY') THEN RESOURCE DROP(NITESHFT)ENDJOB

Add a resource requirement to the default resource for an ApplicationIn the following example, the RESOURCE statement instructs ESP to add one unit of resource CICS to the default resource for any job within the PAYROLL Application. APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'RESOURCE ADD(CICS)JOB PAYJOB5 RUN WORKDAYS REL PAYJOB6JOB PAYJOB6 RUN WORKDAYS REL PAYJOB7JOB PAYJOB7 RUN WORKDAYENDJOB

Drop a default resource for an ApplicationIn the following example, the RESOURCE statement instructs ESP not to assign the default resource called ELAPSED for any job within the PAYROLL Application. APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'RESOURCE (0,ELAPSED)JOB PAYJOB5 RUN WORKDAYS REL PAYJOB6JOB PAYJOB6 RUN WORKDAYS REL PAYJOB7JOB PAYJOB7 RUN WORKDAYENDJOB

Drop a default resource and identify a resource requirementIn the following example, the RESOURCE statement instructs ESP not to assign the default resource called ELAPSED to PAYJOB8. PAYJOB8 requests one unit of a resource called LOWPRIO.

RESOURCE Statement: Identify Resources

1074

APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB8 RUN WORKDAYS RESOURCE (0,ELAPSED,1,LOWPRIO) ENDJOB

Using an inverse resource request to replenish a depletable resourceIn the following example, job A requests one unit of the scratch tape depletable resource.JOB A RESOURCE (1,SCRATCH)ENDJOB

Job B has an inverse resource request, so it executes when the scratch tape count drops to zero.JOB B RESOURCE (¬SCRATCH)ENDJOB

Using an inverse resource request to replenish a renewable resourceIn the following example, job A requests one unit of renewable resource DB2.JOB A RESOURCE (1,DB2)ENDJOB

Job B has an inverse resource request, so it executes when the available DB2 resource drops to zero and the maximum value (as defined in the RESDEF command) is set to zero.JOB B RESOURCE (¬DB2)ENDJOB

1075

RESPNAME Statement: Identify an Oracle ApplicationsResponsibility Name

The RESPNAME statement identifies an Oracle Applications responsibility name.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

SyntaxRESPNAME name

Usage notesRESPNAME can be defined in two places.• To set RESPNAME for a specific job, include it in the job definition.• To set the default for all jobs run by an Agent, ask your System Administrator to

define the oa.default.responsibility property in the Agent parameter file.RESPNAME is mandatory, and must be defined in at least one of the two places.

Examples Identify an Oracle Applications responsibility name in an OA_JOB definitionIn the following example, the responsibility name for the BIS Oracle Applications application is Business Intelligence Super User, Progress S&L.APPL ACC05 AGENT CYBOA OA_JOB OAUSER.RESPON AFTER CHECK.REQSET1 REQUESTSET FNDRSSUB1310 OAUSER SYSADMIN RESPNAME 'Business Intelligence Super User, Progress S&L' APPLSHORTNAME BIS RUN DAILYENDJOB

Operand Descriptionname The name must match an existing Oracle Applications

responsibility name. Characters are case-sensitive. If you use delimiters, such as spaces, the name must be enclosed in single quotes. Maximum 100 characters.

RESREFR Command: Refresh Devices List

1076

RESREFR Command: Refresh Devices List

The RESREFR command is used in conjunction with real resources, for example tape devices, to refresh the device list if tape devices are added or deleted dynamically.

Type General command.

AuthorityYou require OPER authority to issue the RESREFR command.

SyntaxRESREFR

Usage notesRESREFR refreshes resource status, alleviating problems with jobs going into a RESWAIT status when resources are available. For example, if a job is waiting for a tape drive, and a tape drive is varied online, ESP does not see this, RESREFR refreshes the device list so that jobs do not unnecessarily wait.

Related informationFor information on defining resources, see the RESDEF command.For information on resources, see the ESP Workload Manager User’s Guide.

Example Refreshes resource statusIn the following example, the device list is refreshed with any dynamically added or deleted tape devices. Any jobs waiting for an available resource have their RESWAIT status refreshed.OPER RESREFR

Note: Automate the process by which resource status is refreshed by defining an Event at regular intervals to issue the RESREFR command, as follows:

EVENT ID(CYBER.RESOURCE_REFRESH)SCHEDULE EVERY 10 MINUTESVS 'F ESP,RESREFR'ENDDEF

1077

RESTART Command: Restart Events Scheduling/ApplicationProcessing

The RESTART command is used to take ESP out of the quiesced state, restarting Event scheduling and Application processing.

TypeGeneral command.

AuthorityYou require OPER authority to issue the RESTART command.

SyntaxRESTART

Usage notesUse the RESTART command after ESP has been quiesced using the QUIESCE command or the QUIESCE start-up option.When Event scheduling is restarted, ESP acts as if it was down for the entire time it was in the quiesced state. That is, Events scheduled to execute while ESP was quiesced are considered to be overdue. The overdue operand of each overdue Event is examined to determine whether it should be executed or bypassed.

Related informationFor information on putting ESP into a quiesced state, see the QUIESCE command.For information on displaying the current ESP processing status, see the STATUS command.

Example Restart Event scheduling and Application processingIn the following example, Event scheduling and Application processing are active as noted by the ESP1978I message—EVENT SCHEDULING ACTIVE.OPER RESTART

In the above example, ESP is restarted, which is displayed using the STATUS command as follows:OPER STATUSESP1977I ESP RELEASE 5.1.0.000 STATUSESP1978I EVENT SCHEDULING ACTIVEESP1979I DATASET TRIGGERING ACTIVE

RESTORE Command: Restore ESP Data Sets

1078

RESTORE Command: Restore ESP Data Sets

The RESTORE command is used to restore the Event, History, Userdef, Index, and Job index data sets. The RESTORE command restores an ESP data set from the backup copy of its most current state using journalled SMF entries.

TypeGeneral command.

SyntaxRESTORE {EVENTSET(dsname)} {INDEX(dsname)} {USERDEF(dsname)} {JOBINDEX(dsname)} {HISTFILE(dsname)} BACKUP(bkupdsname) SMFID(smfno) [NEWDSNAME(newdsn)] [FROMTIME(schedule)]

Operand Description EVENTSET Indicates the name of an Event data set.INDEX Indicates the name of the Index data set.USERDEF Indicates the name of the User Definition data set.JOBINDEX Indicates the name of the Job Index data set.HISTFILE Indicates the name of a History data set.dsname Indicates the data set name of file to be restored.bkupdsname Indicates the data set name of most current backup from which

the file is to be restored.smfno Indicates the record number used for journalling updates to

SMF file. This corresponds to your SMFREC initialization parameter.

newdsn Indicates an optional data set name of an existing empty VSAM file where the data set is restored. This data set must have the same attributes as dsname.

schedule Any valid schedule statement. If the statement contains separators, it must be enclosed in quotes. If specified, this time is used instead of the backup file time.

1079

Usage notesThis command can be used only if you are journalling updates to the file you wish to restore.

Related informationFor information on restoring ESP data sets, see the ESP Workload Manager Installation and Configuration Guide.

Example Restore ESP data setIn the following example, the restore processor merges all of the history file updates with the last HISTFILE backup and produces a new, up-to-date version of the history file.//RESTORE JOB …//STEP01 EXEC PGM=ESP,PARM='SUBSYS(ESPM)'//STEPLIB DD DSN=CYB2.ESP510.SSCPLINK,DISP=SHR //SYSPRINT DD SYSOUT=*//JOURNAL DD DSN=SYS1.SMF.BACKUP(0),DISP=SHR// DD DSN=SYS1.SMF.BACKUP(-1),DISP=SHR//SYSIN DD *UTIL RESTORE HISTFILE('CYB2.ESP510.HISTFILE') + NEWDSNAME('CYB2.ESP510.NEW.HISTFILE') + BACKUP('CYB2.ESP510.BACKUP.HISTFILE') +SMFID(240)/*

RESUME Command - Event Level: Decrement Suspend Counts

1080

RESUME Command - Event Level: Decrement Suspend Counts

When used in an Event definition, the RESUME command is used to decrement the suspend count associated with an Event at a particular time. When the suspend count reaches zero, the Event is eligible for execution.

Type Event definition command.

SyntaxRESUME criteria

The RESUME command is used in conjunction with the SUSPEND command to make a previously bypassed Event eligible for execution.The RELEASE command is used in conjunction with the HOLD command to make a previously postponed Event eligible for execution.If you are using a time zone on your SUSPEND command, you should use the same time zone on your RESUME command. If the Event has a schedule statement, the same time zone should be used on the SCHEDULE, SUSPEND, and RESUME commands.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.

For information on suspending an Event’s execution, see the SUSPEND command.For information on decrementing an Event’s hold count, see the RELEASE command.Prevent PAYJOB1 from submission between specific timesIn the following example, SUSPEND and RESUME commands are used to prevent PAYJOB1 from being submitted between 9 am and 11 am. If a data set trigger happens between these times, ESP ignores it. EVENT ID(CYBER.PAYROLL) DSTRIG PAYROLL.INPUTSUSPEND DAILY AT 9AMRESUME DAILY AT 11AMSUBMIT 'CYBER.JCL.CNTL(PAYJOB1)'ENDDEF

Operand Descriptioncriteria Schedule criteria.

1081

Send a message between specific time on workdaysIn the following example, SUSPEND and RESUME commands are used to send a message between 8 am and 4 pm on workdays. EVENT ID(CYBER.TIMEMSG)SCHEDULE WORKDAYS HOURLY ROUND STARTING TODAYSEND 'THE TIME IS %ESPATIME' U(CYB01) SUSPEND 16:01 WORKDAYSRESUME 7:59 WORKDAYSENDDEF

RESUME Command - General: Decrement Suspend Counts

1082

RESUME Command - General: Decrement Suspend Counts

The RESUME command is used to decrement the suspend count associated with an Event. When the suspend count reaches zero, the Event is eligible for execution.

TypeGeneral command.

SyntaxRESUME eventid

Usage notesThe specified Event has its SUSPEND count decremented immediately.The SUSPEND command is used in conjunction with the RESUME command to make a previously bypassed Event eligible for execution.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.For information on suspending an Event’s execution, see the SUSPEND command.For information on decrementing an Event’s hold count, see the RELEASE command.

Example Resume EventIn the following example, CYBER.PAYROLL was previously suspended and is now eligible for execution, if the suspend count was at one. Otherwise, the suspend count was decrement by one.RESUME CYBER.PAYROLL

Operand Descriptioneventid Indicates a valid Event name. If no prefix is specified, the prefix as set

by the GROUP command is used.

1083

REXXOFF Statement: Turn Off REXX Processing

The REXXOFF statement is used to turn REXX processing off.

TypeCLANG statement.

SyntaxREXXOFF

Usage notesTo add REXX expressions to ESP, you must turn REXX on and off using CLANG. CLANG is always present as the primary command language in ESP.

Related informationFor information on turning REXX processing on, see the REXXON statement.For information on using REXX with ESP, see the ESP Workload Manager Advanced User’s Guide.

Example Toggle REXX processing on/offIn the following example, REXX is turned on from ESP to generate an Application consisting of 10 sequential jobs, and then REXX is turned off.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'REXXON GENDO I=1 TO 10 "JOB PAYJOB"I " RUN ANY" IF I <> 10 THEN " RELEASE PAYJOB"I+1 "ENDJOB"ENDREXXOFF

REXXON Statement: Turn On REXX Processing

1084

REXXON Statement: Turn On REXX Processing

The REXXON statement is used to turn REXX processing on by invoking the REXX interpreter. When ESP encounters a REXXON statement, it reads the REXX procedural statements until it encounters a REXXOFF statement.

TypeCLANG statement.

SyntaxREXXON [GEN|NOGEN] [PROC|NOPROC]

Usage notesTo add REXX expressions to ESP, you must turn REXX on and off using CLANG. CLANG is always present as the primary command language in ESP.You can activate REXX processing at either the generation or processing stages of an Application. To invoke or suppress REXX processing at either the generation or processing stage of an Application, enter the GEN or PROC keywords after the REXXON statement as follows:• Type REXXON GEN PROC or REXXON to turn on REXX in the generation and

processing stages of an Application. • Type REXXON GEN to turn on REXX in the generation stage only. • Type REXXON PROC to turn on REXX in the processing stage only.

Operand DescriptionGEN Indicates that REXX processing is active during Application

generation mode. This is the default. Use this option if you are using REXX to generate your Application.

NOGEN Indicates that REXX processing is not active during Application generation mode.

PROC Indicates that REXX processing is active during Application process mode. This is the default. Use this option if you are using REXX to process you Application.

NOPROC Indicates that REXX processing is not active during Application process mode.

1085

Related informationFor information on using REXX with ESP, see the ESP Workload Manager Advanced User’s Guide.For information on turning REXX processing off, see the REXXOFF statement.

Examples Turn REXX processing onIn the following example, REXX is turned on from ESP to send a message back to your terminal and then turned off again.REXXON SAY 'THIS IS REXX SPEAKING'REXXOFF

Turn REXX processing on and returns information about a jobIn the following example, ESP turns on REXX to return information about a job currently on the CSF. REXXONNUM=JOBONCSF('PAYJOB1','X')SAY 'THERE ARE' NUM 'OCCURENCES OF JOB' JOBNAME()DO I=1 TO NUM SAY JOBNAME() 'IS IN APPL' XAPPL.IENDREXXOFF

Turns REXX processing on to generate an ApplicationIn the following example, REXX is turned on from ESP to generate an Application consisting of 10 sequential jobs.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'REXXON GENDO I=1 TO 10 "JOB PAYJOB"I "RUN ANY" IF I <> 10 THEN "RELEASE PAYJOB"I+1 "ENDJOB"ENDREXXOFF

REXXON Statement: Turn On REXX Processing

1086

Turns REXX processing on and defines special daysIn the following example, REXX is turned on from ESP to read each line of a data set containing dates and then issue the DEPSPEC command for the specified dates.REXXON"ALLOCX DA('CYB01.DATES') F(MYINDD) SH"if rc \= 0 then do "REEXEC IN(1)" "EXIT" endaddress MVS "EXECIO * DISKR MYINDD (STEM LINE. FINIS"do i=1 to line.0 Date=line.i "ESP DEFSPEC PAY_DAY ON("Date") CAL(PAYROLL)"endFREEX FILE(MYINDD)"REXXOFF

1087

RFCDEST Statement: Specify SAP Destination

The RFCDEST statement specifies the SAP destination as specified in the connection properties file.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax RFCDEST destination

Usage notesUse the RFCDEST statement within the boundaries of the job definition.

ExampleIn this example, the job will run at SAP destination CTR3.APPL SAPTESTSAP_JOB SAPTEST RFCDEST CTR3 AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST RECIPIENT IndyFinneyENDJOB

Operand Descriptiondestination Specifies destination specified in the connection properties file

during installation. destination is case sensitive and can be up to 20 valid SAP characters in length.

ROSSUB Command: Submit JCL

1088

ROSSUB Command: Submit JCL

The ROSSUB command is used to submit JCL from a ROSCOE data set to the internal reader.

Type Event definition command.

SyntaxROSSUB dsname

Usage notesThe ROSSUB command submits JCL from a ROSCOE data set into the internal reader. Several ROSCOE commands may be specified in a single Event. The input data are effectively concatenated together, so that data from several data sets can be joined to form one or more jobs. In the same Event you can also use the ESP SUBMIT command and submit JCL from LIBRARIAN and PANVALET data sets.You can also use the ROSSUB command in an ESP Procedure.

Related informationFor information on submitting JCL from an Event see, Processing ESP Events in the ESP Workload Manager User’s Guide.

ExampleData set submission at specific time and day of a monthIn the following example a ROSCOE data set is submitted at 9 am on the first Monday of the month.EVENT ID(CYBER.ROSJOBS)SCHEDULE 9AM FIRST MONDAY OF MONTHROSSUB RDS.JOBSENDDEF

Operand Descriptiondsname Indicates a valid ROSCOE data set name. You do not

have to specify ROS- as a data set identifier because using the ROSSUB command implies the use of a ROSCOE data set. If you omit the ROSCOE prefix from the data set name, ESP uses the ROSCOE prefix of the user defining the Event.

1089

ROUTE Statement: Insert Route Statements

The ROUTE statement is used to insert a /*ROUTE statement in a job’s JCL. This routes a job to a different node for execution.

TypeESP Application statement.

SyntaxROUTE XEQ (nodename)

Usage notesIf you use the ROUTE statement to route a job to another JES node, you should ensure there is tracking data being sent between the two nodes. Check with your ESP system administrator before using this feature.Another method for routing jobs to other nodes is to use ESP Resources. Using this feature, ESP automatically inserts the appropriate routing information to ensure jobs are routed to the required JES node.

Related informationFor information on routing jobs to other JES nodes, see the ESP Workload Manager Advanced User’s Guide.For information on routing jobs to other JES nodes using ESP Resources, see the ESP Workload Manager User’s Guide.For information on inter-system tracking, see the TP Server Installation and User’s Guide.

Operand Descriptionnodename Indicates a one to eight character JES node name to which this job is

routed for execution.

ROUTE Statement: Insert Route Statements

1090

Example Routes job to another JES node In the following example, ESP adds a /*ROUTE card to the JCL it submits for PAYJOB2 to route it to NODE2.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RUN DAILY REL PAYJOB3JOB PAYJOB2 RUN DAILY REL PAYJOB3 ROUTE XEQ(NODE2)JOB PAYJOB3 RUN DAILY RELCOUNT 1ENDJOB

1091

ROUTING Command: Route Proxies Subsystem Requests

Instructs the connected ESP Workload Manager subsystem where to process subsystem requests. Displays the current routing status.

TypeHAO or HPO command.

SyntaxROUTING [LOCAL|MASTER|STATUS|HELP]

Usage notesWhen an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to the ESP Workload Manager master, the ROUTING command is not meaningful, as the LOCAL and MASTER options mean the same thing.However, when an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to an ESP Workload Manager proxy, entering ROUTING LOCAL instructs the proxy to process subsystem requests. Subsystem requests are usually ESP Workload Manager commands. If you enter ROUTING MASTER, this instructs the ESP Workload Manager proxy to route subsystem requests to the ESP Workload Manager master.When an ESP Workload Manager client is connected to the local ESP Workload Manager proxy, subsystem requests can only be forwarded to the master if an active XCF ROUTING connection exists between the local proxy and the master.Routing is local by default. However, your system programmer may have changed the default in the ISPF interface. It does not matter which system in the sysplex the ESP Workload Manager master is running on, the ESP Workload Manager proxy always knows, through its XCF group member State Awareness capabilities, where the ESP Workload Manager master is, and how to access it.

Operand DescriptionLOCAL Instructs the connected ESP Workload Manager subsystem to

process subsystem requests itself.MASTER Instructs the connected ESP Workload Manager subsystem to

route subsystem requests to the master.STATUS Displays the current ROUTING status of the client. This is the

defaultHELP Displays the ROUTING command options.

ROUTING Command: Route Proxies Subsystem Requests

1092

Note: For more information on routing and the XCF ROUTING SERVICE initialization parameter, see the topic Making the ESP Workload Manager Subsystem Available from ISPF in the chapter Set Up the ESP Workload Manager Started Tasks in the ESP Workload Manager Installation and Configuration Guide.

Examples The following example instructs the connected ESP Workload Manager subsystem to route subsystem requests to the ESP Workload Manager master:ROUTING MASTER

The following example instructs the connected ESP Workload Manager subsystem to process subsystem requests itself:ROUTING LOCAL

1093

RUN Statement: Identify Schedule Frequency

Defines the schedule frequency for a job. You can have multiple RUN statements for the same job.

TypeApplication statement.

SyntaxRUN {criteria | REF expression}

Usage notes

Using RUN statementsThe RUN statement is equivalent to the following:IF TODAY('criteria') THEN SELECT job

For ESP Workload Manager to select a job for submission, a RUN, SELECT, PREREQ, POSTREQ, or COREQ statement is required.The RUN statement cannot be used in conjunction with these scheduling terms: EVERY, UNTIL, ENDING, TOMORROW, YESTERDAY, and STARTING. The schedule criteria must resolve to a single date and time when the Application builds.If a job has a time dependency for submission, you must use either an EARLYSUB or a DELAYSUB statement. The statement RUN 5PM DAILY is not valid.Use the NORUN statement to cause a job not to be scheduled. When both RUN and NORUN statements for a job are encountered, the last one that applies overrides. Normally, the NORUN statement should follow a RUN statement.RUN statements are used within the scope of a JOB statement. You can look at a job definition and see the schedule frequency for the job. Many criteria can be handled with RUN statements without the need for using IF TODAY type logic.

Using RUN REF statementsUse RUN REF to establish the scheduling criteria of a job relative to other jobs instead of declaring the scheduling criteria explicitly.

Operand Descriptioncriteria The schedule criteria must resolve to a single date and time when the

Application builds. Refer to the ESP Workload Manager User’s Guide for information about how to define valid criteria.

expression The RUN REF expression can include simple or qualified job names and any valid CLANG terms, such as variable names or function references, for example, the TODAY() function.

RUN Statement: Identify Schedule Frequency

1094

RUN REF defers processing until after the following occurs:• The ESP Procedure has been completely read.• RESOLVE processing has been performed.However, RUN REF processes before INHERIT processing.The reference string can be complex, using nested expressions with AND, OR and NOT. Circular references will be detected and cause the Application not to be generated.RUN REF can be used to reference the scheduling criteria for any job, either in the same Application or across Applications.

Handling references across ApplicationsRUN REF can refer to a job defined as external within the current Application. If this job has explicit selection statements (RUN or SELECT), then the reference will be resolved based on those. Otherwise, ESP Workload Manager will have to find out whether the external job is in the SADGEN file. This is done via RESOLVE processing, using SADGEN data.To reference a job where scheduling criteria is in another Application, you must:• run a SADGEN report• issue the SADLINK command unless the SADLINK parameter is specified in the

initialization parameters• issue the SADLOAD command• specify RESOLVE in the Application containing the RUN REF statement• define jobs as EXTERNAL in the Application containing the RUN REF

statement.Cybermation recommends that you use the SCHEDULED statement, for example, SCHEDULED ('TODAY'), to select the specific job you want. RESOLVE will find any instance of the job in the SADGEN file unless you narrow the scope of the search with the SCHEDULED statement. An alternative is to run SADGEN more often, for a more limited time range.

1095

Related informationFor information on Applications, see the ESP Workload Manager User’s Guide.For information on specifying schedule criteria, see the ESP Workload Manager User’s Guide.For information on selecting jobs for submission, see the SELECT, POSTREQ, PREREQ, and COREQ statements. For information on deselecting jobs for submission, see the NORUN and DESELECT statements.For information on handling references across Applications:• Resolving External dependencies in the ESP Workload Manager Advanced User’s

Guide.• SADGEN (page 1102), SADLINK (page 1106), and SADLOAD (page 1108)

commands• RESOLVE statement on page 1068

• ESP Workload Manager User’s Guide, specifically the reference to the SADGEN command

Examples Scheduling a Windows job for submissionSchedules PAYJOB1 running on a Windows Agent for submission on workdays.APPL PAYROLLNT_JOB PAYJOB1 AGENT NT_NY CMDNAME c:\pay\data\payrpt.exe RUN WORKDAYSENDJOB

Scheduling multiple UNIX jobs for submissionSchedules PAYJOB2 for submission every day and PAYJOB3 for submission on Fridays.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'UNIX_JOB PAYJOB2 AGENT UNIX_NY RUN DAILY SCRIPTNAME /pay/data/payjob REL PAYJOB3ENDJOB

RUN Statement: Identify Schedule Frequency

1096

NT_JOB PAYJOB3 AGENT NT_NY RUN FRIDAY CMDNAME c:\padatpayrpt.ext ENDJOB

Scheduling a job for submission on Mondays, not first workday of monthSchedules PAYJOB5 for submission on Mondays, except if Monday is the first workday of the month.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB5 RUN MONDAY NORUN 1ST WORKDAY OF MONTHENDJOB

Scheduling a job for submission if today is the last workday of the month, not last workday of weekSchedules PAYJOB6 for submission if today is the last workday of the month, but not if it is the last workday of the week.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB6 IF TODAY('LAST WORKDAY OF MONTH') AND - TODAY('NOT LAST WORKDAY OF WEEK') THEN RUN TODAYENDJOB

Scheduling a job for submission on the 5th day of each monthSchedules PAYJOB7 for submission on the 5th day of each month. If the 5th day of the month is not a workday, schedules PAYJOB7 for submission on the first workday after the 5th day of the month.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB7 RUN 5TH DAY OF MONTH PLUS 0 WORKDAYSENDJOB

Scheduling a job for submission every 14 days after January 1st, 2000, except holidaysSchedules PAYJOB8 for submission every 14 days, after January 1st, 2000, except if it is a holiday.

1097

APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB8 INTEGER X X=DAYS_FROM('JANUARY 1,2000') IF X//14*14=X THEN DO RUN TODAY NORUN HOLIDAY ENDDOENDJOB

Scheduling a job for submission last day of the month if not SundaySchedules PAYJOB9 for submission on the last day of the month, if the last day of the month is not the last Sunday of the month. If the last day of the month is the last Sunday of the month, then PAYJOB9 is selected for submission on the last Saturday of the month.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'GENTIME A LAST DAY OF MONTH STARTING TODAYGENTIME B LAST SUN OF MONTH STARTING TODAYGENTIME C LAST SAT OF MONTH STARTING TODAYJOB PAYJOB9 IF %ADATE NE %BDATE THEN - RUN %ADATE ELSE - RUN %CDATEENDJOB

Scheduling a job for submission if an external job runsJob A runs only if the external job B runs. The RESOLVE statement points ESP Workload Manager to the SADGEN data set loaded by the SADLOAD command. ESP Workload Manager refers to job B of Application AP2 in the SADGEN data set and uses the information in that Application for selecting job A. APPL AP1RESOLVE SAD01JOB A RUN REF B …ENDJOBJOB B EXTERNAL APPL(AP2)ENDJOB

RUN Statement: Identify Schedule Frequency

1098

Scheduling a job for submission if one of two other jobs run and if today is the last workday of the monthJob B runs only if job A or job C are running, and if today is the last workday of the month.APPL AP1JOB A RUN 1st WORKDAY OF EACH WEEK …ENDJOBJOB B RUN REF (A OR C) AND TODAY('LAST WORKDAY OF MONTH') …ENDJOBJOB C RUN 3RD - LAST WORKDAY OF EACH WEEK …ENDJOB

Scheduling a jobs for submission if external jobs are run todayJobs X, Y, and Z run only if jobs JOB1, JOB2, and JOB3 run today. JOB1, JOB2, and JOB3 are part of other Applications. Note, the SCHEDULED ('TODAY') statement selects only today’s jobs even if SADGEN is issued for a time range longer than a day.APPL ABCRESOLVE SADXYZJCLLIB 'CYBER.JCL'

JOB XRUN REF JOB1RELEASE Y

ENDJOB

JOB YRUN REF JOB2RELEASE Z

ENDJOB

JOB ZRUN REF JOB3

ENDJOB

JOB1 EXTERNAL SCHEDULED('TODAY')JOB2 EXTERNAL SCHEDULED('TODAY')JOB3 EXTERNAL SCHEDULED('TODAY')

1099

Scheduling a job for submission if two external jobs run with one of these jobs being dependent on an external jobJob A in AP1 refers to job B in AP2. Job B in AP2 refers in turn to job C in AP3. The RUN REF statement in AP1 will be evaluated as if job C in AP3 was selected. It is necessary for job A to reference job C directly; thus, job A in AP1 has a direct reference to job C in AP3 because indirect reference through job B in AP2 cannot be evaluated correctly based on SADGEN data.APPL AP1RESOLVE SAD01JOB A RUN REF B AND C …ENDJOBJOB B EXTERNALJOB C EXTERNAL

APPL AP2RESOLVE SAD01JOB B RUN REF C AND D …ENDJOBJOB C EXTERNALJOB D RUN 1ST WEEK OF MONTH …ENDJOB

APPL AP3JOB C RUN FRIDAY …ENDJOB

RUNCONTROLID Statement: Identify PeopleSoft Run Parameters

1100

RUNCONTROLID Statement: Identify PeopleSoft Run Parameters

The RUNCONTROLID identifies a set of PeopleSoft run parameters for a given PeopleSoft process.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax RUNCONTROLID ID

Usage notesRUNCONTROLID must be specified in either the job definition or in the agentparm.txt file. The value in the job definition will override the value specified in the agentparm.txt file:ps.default.runCntlId=<ID>

ExamplesSpecifying the Run Control ID.In this example, PS_ALL is the Run Control ID.PS_JOB PAYROLL RUN DAILY AGENT PS_TOR PROCESSNAME PSQUERY PROCESSTYPE 'Application Engine' RUNCONTROLID PS_ALLENDJOB

Operand DescriptionID The value assigned to the Run Control ID. ID can be up to 30

characters in length. If the ID includes spaces, the ID must be enclosed in single quotes.In PeopleSoft, some processes spawn children using the CreateProcessRequest PeopleCode function. PeopleSoft may mark the parent process as a successful completion even if one or more of its children fail. If you want the Agent to check the status of children when determining the completion status of the parent, add ".*" to the end of the Run Control ID, for example, RunControlID PS_ALL.*.

1101

Checking children statusIn this example, PAYDATA completes successfully if process AEMINITEST and all of its children complete successfully.PS_JOB PAYDATA AGENT PS_AGENT PROCESSNAME AEMINITEST PROCESSTYPE 'Application Engine' PSOPRID VP1 RUNCONTROLID HDL8010.* RUN DAILYENDJOB

SADGEN Command: Create Data Set for Reports

1102

SSADGEN Command: Create Data Set for Reports

The SADGEN command is used to generate a data set, which is used in the creation of scheduled activity reports. It must be executed through the ESP subsystem started task Procedure with a special parm (PARM='SAR’ or PARM='SAD'). This command is available only in batch.

TypeReporting command.

SyntaxSADGEN DATASET(sardb) [FROM(schedule)] [TO(schedule)] [LOGICALDAYSTART(starttime)] [CARRYOVER(codsn)] [EVENTSET(evdb)] [LEVEL(prefix)] [CLASS(classname[,classname]...)] [THRESH(mins)] [TRACE] [JCLOUT(jcldsn)] [JOBCLASS(jobclass)] [MSGCLASS(msgclass)] [RMGRDATA('string'[,'string']...)] [NOHIST] [EXTERNAL]

Operand Descriptionsardb Indicates the name of the data set to store scheduled activity information.schedule Indicates valid schedule criteria. If the statement contains separators then it must

be enclosed in quotes. The keywords ENDING or UNTIL can be used to restrict the time range selected. Defaults are from now to 6 am tomorrow. You cannot specify a time in the past; you can only specify a time in the future. The start time for a SADGEN run is the later of the start time specified in the SADGEN command and the time at which the command is processed.

starttime Indicates a valid schedule statement. If the statement contains separators, it must be enclosed in quotes. The LOGICALDAYSTART keyword specifies the start time of your logical processing day; it should match the one specified on your calendar. This keyword is not required unless you use logical day processing.

codsn Indicates the name of a previously scheduled activity data set (data set name or DD name) whose outstanding jobs are to be merged with the sardb data set.

1103

Usage notesTo generate data used for scheduled activity reporting, ESP must simulate all the Events and ESP Procedures it is to execute in a specified period. ESP does this by executing the ESP subsystem started task procedure in batch with a special parameter (PARM='SAR' or PARM='SAD'). The output that ESP generates by this simulation forms a scheduled activity data set.The default space requirement for the SADGEN data set is 10 primary cylinders and 5 secondary cylinders. To change these defaults, specify SADGEN(p,s) where p is the number of primary cylinders and s, the number of secondary cylinders. For example:PARM='SAD(25,10)' results in SPACE=(CYL,(25,10)).

If a primary quantity only is coded, the secondary defaults to 5. For example:PARM=’SAD(50)’ results in SPACE=(CYL,(50,5)).

evdb Indicates the name of one or more Event data bases that should be scanned to generate scheduled activity data. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. The default is to scan all existing Event data sets.

prefix Indicates an Event group prefix. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

classname Indicates one or more ESP Event class names. Separate each with a comma. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

mins Indicates a threshold in minutes. Any Event that executes more frequently than this threshold interval is not simulated. The default is 120.

TRACE Displays all the commands that ESP simulates to create the scheduled activity data base.

jcldsn Indicates the name of a sequential data set where the JCL for each job generated by the SADGEN is stored.

jobclass Indicates a one-character alphanumeric jobclass to be assigned to each job written to the JCLOUT data set.

msgclass Indicates a one-character alphanumeric msgclass to be assigned to each job written to the JCLOUT data set.

string Indicates a quoted string or list of strings that is inserted as the first step to each job written to the JCLOUT data set.

NOHIST Indicates job history data is not retrieved when creating the scheduled activity data set. This keyword should be specified only if you are not using ESP’s job tracking facility.

EXTERNAL Adds an extra entry on the SADGEN data set for each external job found within the specified scheduling criteria.

Operand Description

SADGEN Command: Create Data Set for Reports

1104

ESP does not reflect an Event in the scheduled activity data set unless it contains either a SCHEDULE or EXPECT command.You can also create multiple schedule activity data sets. You may want to generate separate data sets on scheduled activity for the next day or for the next week, or you may want different data sets for different production groups.When a scheduled activity data set is generated, it contains a record for each job that is submitted within the time range you have specified. If a time range is not specified, the default provided is from “NOW” to “6AM TOMORROW”. Data is stored in alphabetical sequence by job name and is displayed using the LSAR command.A sequential data set must be allocated before using the SADGEN command to write data to it.The scheduled activity data set may be used for reporting, modeling, or to resolve External dependencies.Use of the EVENTSET, LEVEL, and CLASS keywords, allows you to select and control the scheduled activity data you want to be stored. The THRESH option allows you to change the frequency of Events to be simulated. The TRACE option is used to verify all of the functions that each Event or ESP Procedure performs when it is scheduled.

Related informationFor information on scheduled activity reporting, see the ESP Workload Manager User’s Guide.For information on modeling, see the ESP Workload Manager Advanced User’s Guide.For information on extracting data from the scheduled activity data set, see the LSAR command.For information on updating a scheduled activity data set with actual information, see the SADUPD command.For information on resolving dependencies through a scheduled activity data set, see the RESOLVE command.For information on identifying an external scheduled activity data set, see the SADLINK command.For information on refreshing an in-core table containing scheduled activity data set, see the SADLOAD command.

1105

Examples Sample JCL to produce a scheduled activity data set//jobname JOB …//STEP1 EXEC ESP,PARM='SAR' //SYSPRINT DD SYSOUT=*//SYSIN DD *SADGEN DATASET('CYBER.SAD') - FROM('8AM TODAY') TO('8AM TOMORROW')/*

In the above example, the SADGEN command generates a scheduled activity data set. CYBER.SAD contains information on all Events scheduled or expected to execute between 8 am today and 8 am tomorrow.//jobname JOB …//STEP1 EXEC ESP,PARM='SAR' //SYSPRINT DD SYSOUT=*//SYSIN DD *SADGEN DATASET('CYBER.SAD') - FROM('8AM TODAY') TO('8AM PLUS 1 WEEK') -EVENTSET(EVENT1) -LEVEL(PROD-)/*

In the above example, the SADGEN command scans the EVENT1 Event data set to generate a scheduled activity data set. CYBER.SAD contains information on all Events beginning with PROD, which are scheduled or expected to execute between 8 am today and 8 am next week.//jobname JOB …//STEP1 EXEC ESP,PARM='SAR' //SYSPRINT DD SYSOUT=*//SYSIN DD *SADGEN DATASET('CYBER.SAD') - FROM('8AM TODAY') TO('8AM TOMORROW') -THRESH(60)/*

In the above example, the SADGEN command generates a scheduled activity data set. CYBER.SAD contains information on Events that are scheduled between 8 am today and 8 am tomorrow. Events that are scheduled more frequently than once an hour are not included.

SADLINK Command: Assign Scheduled Activity Data Sets

1106

SADLINK Command: Assign Scheduled Activity Data Sets

The SADLINK command is used to assign an identifier to a scheduled activity data set for resolving External job dependencies. Normally the SADLINK command is used as an initialization parameter.

TypeGeneral command.

AuthorityYou require OPER authority to issue the SADLINK command.

SyntaxSADLINK identifier DATASET(dsname) [GROUP(groupname)]

Usage notesThe SADLINK command assigns an identifier to a SADGEN data set (schedule activity data set). Each time ESP initializes, or in response to a SADLOAD command, the contents of the SADGEN data set are read and information stored in a main-storage table. To request this table be used to resolve External job dependencies, specify the SADLINK identifier on the RESOLVE statement in an Application.

Related informationFor information on generating a scheduled activity data set, see the SADGEN command.For information on identifying a scheduled activity data set at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.For information on refreshing an in-core table containing scheduled activity data set, see the SADLOAD command.

Operand Descriptionidentifier Indicates an internal identifier of a scheduled activity data set. Up to

eight alphanumeric characters are allowed.dsname Indicates the name of a sequential data set used for storing scheduled

activity data.groupname Indicates the owning group. Any user who has either operator authority

or update access to the owning group can issue a SADLOAD command to refresh the in-core table. This applies only if you are using ESP’s internal security.

1107

For information on resolving dependencies through a scheduled activity data set, see the RESOLVE command.For information on displaying current SADLINK, see the LISTSADL command.

Examples No owning group is specifiedIn the following example, CYBER.SAD is assigned an internal identifier of SAD1. No owning group is specified.SADLINK SAD1 DATASET(CYBER.SAD)

Owning group is specifiedIn the following example, CYBER.SAD is assigned an internal identifier of SAD2. PROD is identified as the owning group.SADLINK SAD2 DATASET(CYBER.SAD) GROUP(PROD)

SADLOAD Command: Refresh Tables

1108

SADLOAD Command: Refresh Tables

The SADLOAD command is used to refresh a table containing scheduled activity data set (SADGEN data set) information. It should be used whenever there is an update to the SADGEN data set. You can automatically issue the SADLOAD command in batch following the generation of the SADGEN data set.

TypeGeneral command.

AuthorityYou require OPER authority to issue the SADLOAD command. user with update access to the owning group (as specified in a SADLINK command) is also authorized.

SyntaxSADLOAD identifier

Usage notesThe SADLOAD command causes the contents of the specified SADGEN data set to be read and the necessary information stored in a table in main-storage. You can request that the look-up table be used to resolve External job dependencies by specifying the correct SADLINK identifier on the RESOLVE statement in an ESP Procedure. The SADLOAD command should be issued whenever the SADGEN data set is updated.

Related informationFor information generating a scheduled activity data set, see the SADGEN command.

For information on identifying an external scheduled activity data set, see the SADLINK command.For information on resolving dependencies through a scheduled activity data set, see the RESOLVE command.For information on displaying current SADLINK, see the LISTSADL command.

Operand Description

identifier Indicates the internal identifier of a scheduled activity data file (SADGEN data set), as identified by a SADLINK command.

1109

Examples Refresh in core tableIn the following example, the in-core table containing scheduled activity information is refreshed.OPER SADLOAD SAD1

Execute between 8 am today and 8 am tomorrowIn the following example, the SADGEN command generates a scheduled activity data set CYBER.SAD. It contains information on all Events that are scheduled or expected to execute between 8 am today and 8 am tomorrow. STEP2 defines an automatic SADLOAD command that occurs whenever the ESP command processor executes.//jobname JOB …//STEP1 EXEC ESPM,PARM='SAR' //SYSPRINT DD SYSOUT=*//SYSIN DD * SADGEN DATASET('CYBER.ESP.SADGEN') - FROM('6AM TODAY') - TO('5:59PM TODAY PLUS 7 DAYS') - EVENTSET(-) LEVEL(-) THRESH(30)//STEP2 EXEC PGM=ESP,PARM='SUBSYS(ESPM)',// COND=(0,NE)//STEPLIB DD DISP=SHR,DSN=CYBER.ESP.SSCPLINK//SYSPRINT DD SYSOUT=*//SYSIN DD * SADLOAD SAD1/*

SADUPD Command: Update Scheduled Activities

1110

SADUPD Command: Update Scheduled Activities

The SADUPD command is used to update a scheduled activity data setwith actual information. It must be executed through the ESP subsystem started task Procedure with a special parm (PARM='SAR' or PARM='SAD').

TypeGeneral command.

SyntaxSADUPD [DATASET(sardb)]

Usage notesNote that unlike the SADGEN command, only the DATASET keyword is required for SADUPD. The updated scheduled activity data set can be displayed using the STATUS keyword on the LSAR command.The scheduled activity update feature provides you with actual start and end times for jobs.

Related informationFor information on extracting data from the scheduled activity data set, see the LSAR command.For information on scheduled activity reporting, see the ESP Workload Manager User’s Guide.For information generating a scheduled activity data set, see the SADGEN command.

Example Update scheduled activity data setIn the following example, the scheduled activity information in CYBER.SAD is updated. The name of the ESP started task is ESP.//jobname JOB …//STEP1 EXEC ESP,PARM='SAR' //SYSPRINT DD SYSOUT=*//SYSIN DD *SADUPD DATASET(CYBER.SAD)

Operand Description

sardb Indicates the name of a scheduled activity data set previously created using the SADGEN command. It does not need to be enclosed in quotes.

1111

SAFOPTS Command: Control Processing Options

The SAFOPTS command is used to control processing options for the SAF interface. This statement is normally included in the initialization parameter data set.

Type General command.

AuthorityYou require OPER authority to issue the SAFOPTS command.

SyntaxSAFOPTS [DSALLOC|NODSALLOC] [MVSCMD|NOMVSCMD] [UTOKEN|NOUTOKEN] [SIM3RDPARTY|NOSIM3RDPARTY] [MSGSUPP|NOMSGSUPP] [OPERCMDS|NOOPERCMDS]

Operand DescriptionDSALLOC Indicates ESP is to perform a SAF resource check before dynamically

allocating any data set. If the requestor does not have at least read access to the DSALLOC.dsname resource, where dsname is the name of the data set ESP is allocating, the allocation fails. When ESP allocates the data set on behalf of an Event, ESP uses the Event’s prefix for the resource check. Otherwise, it uses its own user ID for the resource check.

NO DSALLOC Indicates ESP is not to perform a SAF resource check prior to dynamically allocating any data set. This is the default.

MVSCMD Indicates ESP is to use the MVSCMD.cmdstring resource when verifying an Event’s authority to execute an z/OS command.

NOMVSCMD Indicates ESP is to use the OPER resource instead of the MVSCMD.cmdstring resource. This is the default.

UTOKEN Indicates ESP performs a Third Party RACHECK using a SAF user token. When a client makes a request, the host system performs a SAF TOKEN EXTRACT in the client’s environment and passes the token to ESP (the server) for verification. RACF 1.9 or higher supports SAF user tokens. If you are using a different security product, ensure it supports SAF TOKEN EXTRACT and Third Party RACHECK.

NOUTOKEN Indicates ESP performs a Third Party RACHECK on the user ID of the client. This is the default.

SAFOPTS Command: Control Processing Options

1112

Usage notesYou can use the SAFOPTS command to display the current SAF options. An example is shown below.

Related informationFor information on the System Authorization Facility (SAF), see the ESP Workload Manager Security Guide.For information on identifying the SAF resource class at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.For information on defining SAF options at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.

Examples Display SAF optionsIn the following example, the current SAF options and the name of the SAF resource class are displayed.OPER SAFOPTS

SAF Options: NoMsgSupp NoDsAlloc NoMvsCmd NoUToken NoSim3rdParty NoOperCmdsSAF Class: DSNR, Prefix ESP

SIM3RD PARTY Indicates ESP simulates Third Party RACHECK processing since the host security product does not support Third Party RACHECK. Do not specify this option together with the UTOKEN option.

NOSIM3RD PARTY

Indicates ESP uses normal Third Party RACHECK processing. This is the default.

MSGSUPP Indicates ESP suppresses violation messages when performing a RACHECK. If a violation occurs, the security system product tracks it internally.

NOMSGSUPP Indicates ESP issue violation messages. This is the default. We recommend you use this option during testing.

OPERCMDS Indicates ESP is to use the OPERCMD.cmdname resource, rather than the more general OPER resource, when verifying a user’s authority to execute an ESP operator command.

NOOPER CMDS Indicates ESP use the OPER resource instead of the OPERCMD.cmdname resource. This is the default.

Operand Description

1113

Turns on message suppressionIn the following example, ESP suppresses violation messages when performing a RACHECK.OPER SAFOPTS MSGSUPP

SAP_JOB Statement: Start an SAP Job Definition

1114

SAP_JOB Statement: Start an SAP Job Definition

The SAP_JOB statement starts an SAP job definition in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesSP is the short form of SAP_JOB.To schedule SAP jobs, you must load the workload object module CYBESOSP. Load CYBESOSP with the WOBDEF command or with the WOBDEF initialization parameter.You must include the following statements within an SAP_JOB workload object:• ABAPNAME• AGENT• ENDJOB• RUNAs of Release 5, you may include the following SAP statements within an SAP_JOB workload object:

Spool Print Archive OtherEMAILADDR BANNER ARCCLIENT CHILDMONITOREXPIRATION BANNERPAGE ARCCONNECT JOBCOPYFAILUREMSG COLUMNS ARCDATE LANGUAGEPUTINOUTBOX LINES ARCDOCCLASS RELEASERECIPIENTBCC PRINTCOPIES ARCDOCTYPE RFCDESTRECIPIENTCC PRINTCOVER ARCFORMAT SAPCLIENTRECIPIENTEXPRESS PRINTDATASET ARCHOSTLINK SAPJOBCLASSRECIPIENTFORWARD PRINTDEPARTMENT ARCINFO SAPJOBNAMERECIPIENTPRINT PRINTDEST ARCMODE SAPLANGUAGERECIPIENTTYPE PRINTFOOTER ARCOBJTYPE SAPTARGETSYSTEMSAPEMAILADDR PRINTFORMAT ARCPATH SAPUSERSAPFAILUREMSG PRINTHOSTPAGE ARCPRINTER STARTMODESAPSUCCESSMSG PRINTIMMED ARCPROTOCOL STEPUSERSPOOLRECIPIENT PRINTNEWSPOOL ARCREPORT VARIANTSUCCESSMSG PRINTPRIORITY ARCSERVICE WEBPOSTING

PRINTPW ARCSTORAGE

1115

Refer to the JOB statement usage notes.

ExampleIn this example, the SAP job SAPTEST runs the ABAP BTCTEST on the SAP system.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT ABAPNAME BTCTEST RUN DAILYENDJOB

PRINTREL ARCTEXTPRINTREQTYPE ARCUSERPRINTSPOOLNAME ARCVERSIONRECIPIENT

Spool Print Archive Other

SAPA_JOB Statement: Start an SAP Data Archiving Job Definition

1116

SAPA_JOB Statement: Start an SAP Data Archiving Job Definition

The SAPA_JOB statement starts an SAP Data Archiving job definition in an Application.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRefer to the JOB statement syntax.

Usage notesSA is the short form of SAPA_JOB.To schedule Data Archiving jobs, you must load the workload object module CYBESOSA. Load CYBESOSA with the WOBDEF command or with the WOBDEF initialization parameter.You must include the following statements within an SAPA_JOB workload object:• ARCMODE• ARCOBJNAME• ARCOBJVARIANT• PRINTDESTNote: If you set the archiving mode to ‘ARCHIVE’ or ‘BOTH’ in the ARCMODE

statement, the ARCDOCTYPE, ARCINFO, and ARCOBJTYPE statements are also required.

You may include the following SAP statements within an SAPA_JOB workload object:• CHILDMONITOR• RFCDEST• SAPCLIENT• SAPLANUGAGE• SAPTARGETSYSTEM• SAPUSERYou may include any print and archiving statement in an SAPA_JOB workload object that you can include within an SAP_JOB workload object. For a list of SAP print and archiving statements, see “SAP_JOB Statement: Start an SAP Job Definition” on page 1114.

1117

Refer to the JOB statement usage notes.

ExampleIn this example, the Data Archiving job DATEST uses the archiving object BC_ARCHIVE and the archiving object variant BC_ARCVARIANT defined on the SAP system.APPL DATESTSAPA_JOB DATEST AGENT SAPHTAGENT ARCMODE PRINT PRINTDEST LP01 ARCOBJNAME ‘BC_ARCHIVE’ ARCOBJVARIANT ‘BC_ARCVARIANT’ RUN DAILYENDJOB

SAPCLIENT Statement: Specify SAP Client

1118

SAPCLIENT Statement: Specify SAP Client

The SAPCLIENT statement specifies the SAP client within the SAP System.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax SAPCLIENT client_number

Usage notesUse the SAPCLIENT statement within the boundaries of the job definition. The SAPCLIENT Statement can be specified at both the Agent parameter file and WOB level. When the SAPCLIENT Statement is specified at both the Agent parameter and WOB level, the WOB level SAPCLENT Statement overrides the Agent Parameter SAPCLIENT Statement.SAPCLIENT corresponds to the General data, Target server field on the Define Background Job dialog.

ExampleAPPL SAPTESTSAP_JOB SAPTEST SAPCLIENT 850 AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TESTENDJOB

Operand Descriptionclient_number Specifies a numeric string up to 3 digits in length that identifies

the client within the SAP system.

1119

SAPE_JOB Statement: Start an SAP Event Monitor Job Definition

The SAPE_JOB statement starts an SAP Event Monitor job definition in an Application.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRefer to the JOB statement syntax.

Usage notesBE is the short form of SAPE_JOB.To schedule Event Monitor jobs, you must load the workload object module CYBESOBE. Load CYBESOBE with the WOBDEF command or with the WOBDEF initialization parameter.You must include the EVENT statement within an SAPE_JOB workload object.You may include the following SAP statements within an SAPE_JOB workload object:• RFCDEST• SAPCLIENT• SAPLANGUAGE• SAPUSERRefer to the JOB statement usage notes.

ExamplesMonitor for SAP eventIn this example, the SAP event SAPEvent is monitored.APPL EMTESTSAPE_JOB EMTEST AGENT SAPHTAGENT EVENT ‘SAPEvent’ REGISTER RUN DAILYENDJOB

SAPE_JOB Statement: Start an SAP Event Monitor Job Definition

1120

Trigger SAP eventIn this example, the SAP event SAPEvent is triggered.APPL EMTESTSAPE_JOB EMTEST AGENT SAPHTAGENT EVENT ‘SAPEvent’ TRIGGER RUN DAILYENDJOB

1121

SAPEMAILADDR Statement: Email SAP Spool File Upon Job Completion/Failure

The SAPEMAILADDR statement emails a copy of the SAP spool file to the specified addresses upon job completion or failure.

ApplicabilityESP Business Agents for SAP, Release 4 and higher.

SyntaxSAPEMAILADDR address |'address,address[,address,...]'

Usage notesYou can also use the EMAILADDR statement for the output of an ABAP. For more information, see “EMAILADDR Statement: Email SAP Spool File Upon ABAP Completion/Failure” on page 407.Use the SAPEMAILADDR statement within the boundaries of the job definition. .SAPEMAILADDR corresponds to the General data, Spool list recipient button on the Define Background Job dialog.

ExampleIn this example, jsmith and djones will receive spool output for the SAP job SAPTEST.APPL SAPTESTSAP_JOB SAPTEST SAPEMAILADDR 'jsmith@company1.com,djones@company1.com' AGENT SAPHTAGENT SAPUSER J01PRO RUN DAILY ABAPNAME BTCTEST VARIANT TESTENDJOB

Operand Descriptionaddress The e-mail address of a recipient on a distribution list. Separate

each address in the list with a semicolon. Enclose a list of addresses in single quotes. address is case sensitive and can be up to 256 valid SAP characters. If a list is specified, it cannot exceed 256 characters.

SAPFAILUREMSG Statement: Specify Failure Message for SAP Job

1122

SAPFAILUREMSG Statement: Specify Failure Message for SAP Job

The SAPFAILUREMSG statement specifies a string that, when found in the condition output of an SAP job, indicates the failure of the job.

ApplicabilityESP Business Agents for SAP, Release 4 and higher.

Syntax SAPFAILUREMSG 'FailureMessageString'

Usage notesExample

In this example, Workload Manager will treat the job as failed if the string ’Internal problem’ is found in the SAP job log or the SAP spool output.APPL SAPTESTSAP_JOB SAPTEST SAPFAILUREMSG 'Internal problem' AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TESTENDJOB

Operand DescriptionFailureMessageString The string that must match the SAP job output for the job to be

considered failed. FailureMessageString is case sensitive and can be up to 128 valid SAP characters in length. FailureMessageString must be enclosed in single quotes.

1123

SAPJOBCLASS Statement: Specify SAP Job Class

The SAPJOBCLASS statement specifies the SAP system job class the job will run under.

ApplicabilityESP Business Agents for SAP, Release 4 and higher.

Syntax SAPJOBCLASS class

Usage notesThe SAP job class can be updated after the job has been submitted. For more information, see the WSF command in the ESP Workload Manager Operator’s Guide.SAPJOBCLASS corresponds to the General data, Job class field on the Define Background Job dialog.

ExampleAPPL SAPTESTSAP_JOB SAPTEST SAPJOBCLASS C AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TESTENDJOB

Operand Descriptionclass Valid SAP job class as specified in the SAP system. class must

be only one alphabetic character.

SAPJOBNAME Statement: Specify SAP Job Name

1124

SAPJOBNAME Statement: Specify SAP Job Name

The SAPJOBNAME statement specifies the SAP job name that identifies the workload to the SAP system.

ApplicabilityESP Business Agents for SAP, Version 1 and higher.

Syntax SAPJOBNAME job_name

Usage notesIf the SAPJOBNAME statement is not specified, the default is the name specified in the SAP_JOB statement.Use the SAPJOBNAME statement within the boundaries of the job definition. SAPJOBNAME corresponds to the General data, Job name field on the Define Background Job dialog.

ExamplesExample 1In this example, prodrun1 is the direct specification of the SAPJOBNAME statement. Single quotes are not required because the SAP job name prodrun1 contains no blanks or delimiters.APPL SAPTESTSAP_JOB SAPTEST SAPJOBNAME prodrun1 AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TESTENDJOB

Operand Descriptionjob_name The SAP job name used for the SAP workload. job_name is any

valid SAP character string up to 32 characters in length. job_name supports special characters, blanks, and spaces. If job_name contains embedded blanks or other characters ESP recognizes as delimiters (comma, semi-colon, quotes), job_name must be enclosed in single quotes. Any embedded single quote must be duplicated.

1125

Example 2In this example, Today’s Work is the direct specification of the SAPJOBNAME statement. The SAP job name Today’s Work requires single quotes enclosing the job name because it contains both a space and a single quote.APPL SAPTESTSAP_JOB SAPTEST SAPJOBNAME 'Today''s Work' AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TESTENDJOB

SAPLANGUAGE Statement: Specify SAP Language for Login

1126

SAPLANGUAGE Statement: Specify SAP Language for Login

The SAPLANGUAGE statement specifies the language used to log on to an SAP system.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax SAPLANGUAGE language

Usage notesUse the SAPLANGUAGE statement within the boundaries of the job definition.SAPLANGUAGE corresponds to the SAPGUI ABAP program Variant field on the Create Step dialog.

ExampleIn this example, English will be used when SAPTEST runs.APPL SAPTEST SAP_JOB SAPTEST SAPLANGUAGE EN AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TESTENDJOB

Operand Descriptionlanguage Specifies an alphabetic character representing a valid language

for SAP V4.5/4.6. language is case sensitive and can be up to two characters in length.Examples:EN=English, D=German, R=Russian

Note: The default is the SAP system language.

1127

SAPM_JOB Statement: Start an SAP Process Monitor Job Definition

The SAPM_JOB statement starts an SAP Process Monitor job definition in an Application.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxRefer to the JOB statement syntax.

Usage notesSL is the short form of SAPM_JOB.To schedule Process Monitor jobs, you must load the workload object module CYBESOSL. Load CYBESOSL with the WOBDEF command or with the WOBDEF initialization parameter.You must include the PROCESSMONITOR statement within an SAPM_JOB workload object.You may include the following SAP statements within an SAPM_JOB workload object:• ABAPNAME• RFCDEST• SAPCLIENT• SAPLANGUAGE• SAPTARGETSYSTEM• SAPUSERRefer to the JOB statement usage notes.

SAPM_JOB Statement: Start an SAP Process Monitor Job Definition

1128

ExampleIn this example, the Process Monitor job PMTEST monitors for the SAP process status Running.APPL PMTESTSAPM_JOB PMTEST AGENT SAPHTAGENT PROCESSMONITOR STATUS(RUNNING) RUN DAILYENDJOB

1129

SAPSUCCESSMSG Statement: Specify Success Message for SAP Job

The SAPSUCCESSMSG statement specifies a string that, when found in the spool output of an SAP job, indicates the success of the job.

ApplicabilityESP Business Agents for SAP, Version 4 and higher.

Syntax SAPSUCCESSMSG 'SuccessMessageString'

ExampleIn this example, if the SAP job SAPTEST fails, Workload Manager will treat the job as successful if the string Program Selections is found in the SAP job log.APPL SAPTESTSAP_JOB SAPTEST SAPSUCCESSMSG 'Program Selections' AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TESTENDJOB

Operand DescriptionSuccessMessageString The string that must match the SAP job spool output for the job

to be considered successful. SuccessMessageString is case sensitive and can be up to 128 valid SAP characters in length. SuccessMessageString must be enclosed in single quotes.

SAPTARGETSYSTEM Statement: Specify SAP Application Server

1130

SAPTARGETSYSTEM Statement: Specify SAP Application Server

The SAPTARGETSYSTEM specifies the name of the SAP System application server where the SAP job is to run.

ApplicabilityESP Business Agents for SAP, Version 1 and higher.

Syntax SAPTARGETSYSTEM application_server

Usage notesIf the SAPTARGETSYSTEM statement is not defined, the SAP system will select an application server based on available resourcesUse the SAPTARGETSYSTEM statement within the boundaries of the job definition.

ExampleIn this example, ABAPNAME BTCTEST will run at SAP system tst005 regardless of destination properties file entries. See also “RFCDEST Statement: Specify SAP Destination” on page 1087.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER J01PROD RUN DAILY ABAPNAME BTCTEST VARIANT TEST SAPTARGETSYSTEM tst005ENDJOB

Operand Descriptionapplication_server Specifies the host machine within the SAP system architecture

that is capable of running SAP system workload. application_server is case sensitive and accepts any valid SAP characters.

1131

SAPUSER Statement: Specify RFC Logon for SAP System User

The SAPUSER statement specifies the RFC logon for the SAP system user under which the ABAP runs. When the SAPUSER statement is used, it overrides the SAP user specified in the destination properties file.

ApplicabilityESP Business Agents for SAP, Version 1 and higher.

Syntax SAPUSER username

Usage notesIf an SAP system user is not specified using the SAPUSER statement, the ABAP started by the job will run with the authority of the SAP user defined in the Agent Parameter file of the Agent. You can override this behavior with the STEPUSER statement. For more information on STEPUSER, see “STEPUSER Statement: Specify User for ABAP Program (SAP)” on page 1208.If you do not specify the SAPUSER statement in the Workload Object (WOB), you must define the SAPUSER and SAPPASSWORD parameters in the RFC destination properties file. The SAPUSER destination properties parameter is jco.client.user. The SAPPASSWORD destination properties parameter is jco.client.passwd. For more information on the destination properties file, see “ESP Business Agent for SAP Solutions, Administrator’s Guide”.If you specify the SAPUSER statement in the job definition, you must define SAPPASSWORD by using the PASSWORD command. For more information on the PASSWORD command, see “PASSWORD Command” on page 172.

SAPUSER corresponds to the SAPGUI User field on the Create Step dialog.

Operand Descriptionusername Specifies the name of the user under which to run the job.

username is case sensitive and can be up to 32 valid SAP characters in length.

SAPUSER Statement: Specify RFC Logon for SAP System User

1132

ExamplesExample 1In this example, because STEPUSER is not specified in the ABAP definition, BTCTEST will run under the authority of user ID USERXXX01.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT SAPUSER USERXX01 RUN DAILY ABAPNAME BTCTEST VARIANT TEST SAPTARGETSYSTEM tst005ENDJOB

Example 2In this example, there is no SAPUSER or STEPUSER statement. The job will run under the authority of the default user ID specified in destination properties file.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RUN DAILY ABAPNAME BTCTEST VARIANT TEST SAPTARGETSYSTEM tst005ENDJOB

1133

SAVEOUTPUT Statement: Save Output

The SAVEOUTPUT statement specifies whether to save the output from an Oracle Applications Request Set or Single Request execution.

ApplicabilityESP Business Agent for Oracle E-Business Suite.

Syntax SAVEOUTPUT Y|N

Usage notesSAVEOUTPUT can be defined in two places.• To set SAVEOUTPUT for a specific job, include it in the job definition.• To set the default for all jobs run by an Agent, ask your System Administrator to

define the oa.default.saveOp parameter in the Agent parameter file.This statement is optional for OA_JOB definitions.

ExampleSave outputIn the following example, the SAVEOUTPUT statement is set to Y.APPL ACC012 AGENT CYBOA OA_JOB ARF2325.LO04 PROGRAM XXCOFI RUN DAILY APPLDISPLNAME ‘Application Object Library’ RESPNAME ‘System Administrator’ OAUSER SYSADMIN SAVEOUTPUT Y ENDJOB

Operand DescriptionY Save output.N Do not save output.

SCAN Command: Scan JCL Data Set

1134

SCAN Command: Scan JCL Data Set

The SCAN command is used to scan a JCL data set or member for valid ESP control statement syntax. It can check what ESP submits at any time in the future. It can also place a working copy of a job’s JCL into a work data set.

TypeGeneral command.

SyntaxSCAN {dsname|*} EVENT(eventid) [PRINT(printdsn)] [TRJOB(trjobname)] [TRDSN(trdsname)] [SCHED(schedtime)] [JOB(jobname)] [SYMBOL(symchar)] [SYMLIB(sdsn[,sdsn]...)] [TRUNIT(truname)] [TRVOL(trvolser)] [USER(userid)] [GROUP(groupname)] [CALENDARS(cal1[,cal2]...)] [COPYJCL] [TRUSR(userid)] [FTPIP(ipaddress)] [FTPUSR(logonid)] [FTPCS(cs)] [FTPBC(bytecount)] [FTPFMT(ftpformat)] [FTPMD(ftpmode)] [TRMEM(member)]

Operand Descriptiondsname Indicates the data set containing the JCL to be scanned.* Indicates that input is to come from the SYSIN file.EVENT(eventid) Indicates the name of the Event for the job.PRINT(printdsn) Indicates the data set to which the JCL is copied. This data set cannot be a

PDS.

1135

TRJOB(trjobname) Indicates a jobname for a simulated data set trigger. The jobname is that of the job creating the data set. The trjobname operand is passed to the ESPTRJOB symbolic variable.

TRDSN(trdsname) Indicates the name of a data set that causes a data set trigger. The trdsname operand is passed to the ESPTRDSN symbolic variable.

SCHED(schedtime) Indicates the schedule time for the job. This can be any time specification valid on a SCHEDULE statement. If it contains separator characters (comma or blanks), enclose it in quotes.

JOB(jobname) Indicates the name of the job to be displayed, if the data set contains a concatenation of multiple jobs.

SYMBOL(symchar) Indicates a one-byte symbol-introducer character. It defaults to %.SYMLIB(sdsn[sdsn] …)

Indicates the name or names of data sets to be read for the purposes of symbolic variable generation.

TRUNIT(truname) Indicates the generic device type on which the data set is created causing a data set trigger. The truname operand is passed to the ESPTRUNI symbolic variable.

TRVOL(trvolser) Indicates the volume serial of the device on which the data set is created causing a data set trigger. The trvolser operand is passed to the ESPTRVOL symbolic variable.

USER(userid) Indicates the name of the defining user for this Event that is passed to the ESPUSER symbolic variable. Represents the value for setting the data set trigger symbolic variable %ESPTRUSR. The userid has a maximum length of eight characters.

GROUP(groupname) Indicates the current group name that is passed to the ESPGROUP symbolic variable.

CALENDARS(cal1[,cal2] …)

Indicates any required calendars to be retrieved for this Event scan.

COPYJCL Indicates that the scan includes any JCL that is generated to the COPYJCL data set (for example, any JCL generated by %INCLUDE/EXCLUDE logic).

TRUSR(userid) Sets the data set trigger symbolic variable %ESPTRUSR to value userid. The userid has a maximum length of eight characters.

FTPIP(ipaddress) Sets the FTP trigger symbolic variable %ESPFTPIP to value ipaddress. FTPUSR(logonid) Sets the FTP trigger symbolic variable %ESPFTPUSR to value logonid.

The logonid has a maximum length of eight characters.FTPCS(cs) Sets the FTP trigger symbolic variable %ESPFTPCS to value cs.

Permissible values are C and S.FTPBC(bytecount) Sets the FTP trigger symbolic variable %ESPFTPBC to value bytecount.

Operand Description

SCAN Command: Scan JCL Data Set

1136

Usage notesThe SCAN command is used to:• Scan a data set or member to check any imbedded ESP control statements.• Retrieve a working copy of a previously submitted job.• Generate a working copy of a job to be submitted.Once a JCL data set contains ESP control statements, that data set cannot be submitted other than through ESP. This is because the ESP control statements cause a JCL error. In case of ESP being unavailable, use the SCAN command in batch, to generate a valid copy of the JCL and write the output to a data set. That data set can then be submitted through other means after resolving symbols.

ExampleThe following SCAN command allows you to:• Search for ESP control statements within data sets and member of a PDS• Retrieve a working copy of a job that you want to submit• Write the output from the working copies of the jobs to a data set.SCAN 'CYBER.JCL.CNTL(PAYJOB1)' EVENT(CYBER.PAYROLL) –SCHED('24 MAY 2001') SYMLIB('ESP.SYMBOLS(MYSYM)')

In the above example:• CYBER.JCL.CNTL(PAYJOB1) tells ESP where it can find the JCL for MYJOB• EVENT(CYBER.PAYROLL) is the Event that submits the job

FTPFMT(ftpformat) Sets the FTP trigger symbolic variable %ESPFTPFMT to value ftpformat. Permissible values are A, E, and I.

FTPMD(ftpmode) Sets the FTP trigger symbolic variable %ESPFTPMD to value ftpmode. Permissible values are B, C, and S.

TRMEM(member) Sets the FTP trigger symbolic variable %ESPTRMEM to value member.If the TRMEM(member) parameter is specified, the %ESPTRMEM symbolic variable will be set to that member name, regardless of whether or not the TRDSN(dsname) operand includes a PDS member name.If the TRMEM(member) operand is omitted, but the TRDSN(dsname) operand specifies a PDS member name, meaning TRDSN(dsname(member)), the %ESPTRMEM symbolic variable will be set to that member name.If the TRMEM operand is omitted and the TRDSN(dsname) keyword does not specify a PDS member name, the %ESPTRMEM symbolic variable will be set to null.

Operand Description

1137

• SCHED('24TH MAY 2001') is the schedule criteria• SYMLIB ('ESP.SYMBOLS(MYSYM)') contains symbol definitions for the job.Note: If ESP is down, you must run the SCAN command in batch. If ESP is up, you

can use any mode.

SCHEDULE Command: Define Schedules

1138

SCHEDULE Command: Define Schedules

The SCHEDULE command is used to define schedule criteria for an Event, which generally includes a time and a frequency.

TypeEvent definition command.

Syntax{SCHEDULE|SCHED|SCH} criteria [OVERDUE{(count)}] [ONCE]

Usage notesSpecify as many SCHEDULE commands as you need for an Event. The Event is executed at each time and date included in each schedule statement except for any criteria specified on a NOSCHED command. If any times and dates from two or more separate schedule statements coincide, the Event is executed only once at that time.An Event is considered to be overdue when something prevents it from executing at its scheduled time. The following reasons can make an Event overdue:• A system outage• The Event is on hold• The Event’s class is on hold• Unavailability of Event initiator• ESP being placed in the quiesced state• The Event data set being suspended at the scheduled execution time.The overdue count, set by the OVERDUE operand, specifies how many overdue occurrences of an Event are to be scheduled when normal scheduling is resumed. The default setting for the overdue count is one. If a count of zero is set, the Event is bypassed and executes at its next scheduled time.

Operand Description

criteria Schedule criteria.

count Indicates an overdue count, a number from 0 to 10. Indicates how many overdue occurrences of an Event are to be scheduled when an Event misses its scheduled times, perhaps after a system outage. The default is ONE.

ONCE Indicates the specified schedule is executed only once.

1139

Specify ONCE to request that the schedule statement is executed once only and is then deleted. If, at that point, no more schedule elements exist and no data set triggers are defined for the Event, the entire Event is scheduled for deletion 24 hours later.

Related informationFor information on specifying schedule criteria, see the ESP Workload Manager User’s Guide.For information on defining when an Event will execute, see the ESP Workload Manager User’s Guide.For information on specifying when an Event should not execute, see the NOSCHED command.

Examples At 4 pm on workdaysIn the following example, CYBER.PAYROLL is scheduled for execution at 4 pm workdays. EVENT ID(CYBER.PAYROLL)SCHEDULE 4PM WORKDAYSINVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

At 4 pm weekdays and 2 pm on weekendsIn the following example, CYBER.PAYROLL is scheduled for execution at 4 pm weekdays and 2 pm on weekends. EVENT ID(CYBER.PAYROLL)SCHEDULE 4PM WEEKDAYSSCHEDULE 2PM WEEKENDSINVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

At 8 am on workdays except 8 am on last workday of monthIn the following example, CYBER.PAYROLL is scheduled for execution 8 am workdays, except at 8 am on the last workday of the month. EVENT ID(CYBER.PAYROLL)SCHEDULE 8AM WORKDAYSNOSCHED 8AM LAST WORKDAY OF MONTHINVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

SCHEDULE Command: Define Schedules

1140

At 9 am from the second day to the last day of a monthIn the following example, CYBER.PAYROLL is scheduled for execution at 9 am from the second day of the month to the last day of the month. EVENT ID(CYBER.PAYROLL)SCHEDULE 9AM 2ND-LAST DAY OF MONTHINVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

At 10 am workdaysIn the following example, CYBER.CMDS is scheduled for execution 10 am workdays. If CYBER.CMDS misses its schedule execution time it does not execute. EVENT ID(CYBER.CMDS)SCHEDULE 10AM WORKDAYS OVERDUE(0)INVOKE 'CYBER.PROCS.CNTL(CMDS)'ENDDEF

Executed weekdays every four hours starting at 8 amIn the following example, CYBER.PAYROLL is scheduled for execution on weekdays every four hours starting at 8 am.EVENT ID(CYBER.PAYROLL)SCHEDULE EVERY 4 HOURS ROUND STARTING 8AM WEEKDAYSINVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

At 8 am only on February 21st, 2004In the following example, CYBER.PAYROLL is scheduled at 8 am only on February 21st, 2004. The Event is scheduled for automatic deletion 24 hours after this time.EVENT ID(CYBER.PAYROLL)SCHEDULE 8AM FEB21,2004 ONCEINVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

At 10 pm on Fridays and on last workday of monthIn the following example, CYBER.PAYROLL is scheduled for execution at 10 pm on Fridays and on the last workday of the month. When the last workday of the month is a Friday, the Event executes only once.EVENT ID(CYBER.PAYROLL)SCHEDULE 10PM FRIDAYSCHEDULE 10PM LAST WORKDAY OF MONTHINVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

1141

SCRIPTNAME Statement: Specify UNIX Shell Script to Run

The SCRIPTNAME statement specifies the UNIX shell script to run. You can use SCRIPTNAME within the boundaries of the job definition, or you can use SCRIPTNAME globally.Note: UNIX systems are case sensitive. The specified path and script name must

match the path and script name on the UNIX system, or the job will fail.For information on running binary programs, see “CMDNAME Statement: Run Agent-Platform Commands” on page 191.

ApplicabilityESP System Agent for UNIX, Release 6.

SyntaxSCRIPTNAME /path/name

Usage notesAll UNIX job definitions require a SCRIPTNAME statement or a CMDNAME statement. Use the SCRIPTNAME statement to run shell scripts and the CMDNAME statement to run binary files. When you use the Agent to run a script that calls a second script, you must provide the fully qualified path of the called script.To run a UNIX script, the Agent uses, in the following order, the shell specified in:1. An accompanying SHELL statement (if specified)2. The first line of the script (if the SHELL statement is unspecified)3. The oscomponent.defaultshell operand in the agentparm.txt file (if unspecified in

the SHELL statement and in the script)4. The user default shell defined in the user profile (if unspecified in all of the

previous three locations)Note: You must also define the shell with the oscomponent.validshell parameter in

the agentparm.txt file, or set the oscomponent.checkvalidshell parameter to false.

Operand Description/path/name The full path and name of the script to run.

Note: The maximum length for the script name is 100 bytes. It must be a valid executable UNIX file written in a valid scripting language.

SCRIPTNAME Statement: Specify UNIX Shell Script to Run

1142

For more information on the oscomponent.defaultshell, oscomponent.validshell, and oscomponent.checkvalidshell parameters, see the “Listing of Agent Parameters” of the ESP System Agent for UNIX Operating Systems Release 6 Administrator’s Guide. For more information on the SHELL statement, see “SHELL Statement: Specify UNIX Shell to Run Script” on page 1171 of this guide.

ExamplesRun a script using the AgentIn this example, the sort script is run by Agent UNIX_LA. The SHELL statement is unspecified, so the shell is picked up from either the first line of the script, the agentparm.txt file, or the user default shell in the user profile.UNIX_JOB MFGSORT RUN DAILY RELEASE MFGRPT AGENT UNIX_LA SCRIPTNAME /mfg/test/sortENDJOB

Specify a shell to run the scriptIn this example, the SHELL statement is used to specify the shell to run the script. The UNIX_LA Agent uses the C shell to run the sort script.UNIX_JOB MFGSORT RUN DAILY RELEASE MFGRPT AGENT UNIX_LA SCRIPTNAME /mfg/test/sort SHELL /bin/cshENDJOB

Run a Perl scriptTo run a Perl script using the Agent, you need to perform the following steps.1. Add the path of the Perl interpreter to the oscomponent.validshell parameter in the

agentparm.txt file, as shown in the following example:oscomponent.validshell=/usr/bin/sh,/bin/csh,/bin/ksh,

/usr/local/bin/perl,/usr/local/bin/bash

Note: If the oscomponent.checkvalidshell parameter is set to false, you do not need to perform the first step.

2. Specify the name of the script using the SCRIPTNAME statement in the job definition, as follows:

1143

SUN_JOB SUN30 RUN TODAY AGENT SUN30RD SCRIPTNAME /bin/cmd1.pl ARGS Hello world USER guest ENDJOB

3. Specify the path of the Perl interpreter in the first line of the script, as shown in the following example:Perl Script cmd1.pl #!/usr/local/bin/perl print " $0 @ARGV\n"; while (( $var, $value) = each %ENV) { print "$var = $value\n"; } $live=$ENV{pick}; print " user variable pick = $live\n";

Note: As an alternative to specifying the path of the interpreter in the script, you can specify the path in the job definition, using the SHELL statement, as follows:SUN_JOB SUN30 RUN TODAY AGENT SUN30RD SCRIPTNAME /bin/cmd1.pl SHELL /usr/local/bin/perl ARGS Hello world USER guestENDJOB

Note: For more information on the SHELL statement, see “SHELL Statement: Specify UNIX Shell to Run Script” on page 1171.

SEARCHRANGE Statement: Specify Search Range Within TEXT_MON

1144

SEARCHRANGE Statement: Specify Search Range WithinTEXT_MON

The SEARCHRANGE statement specifies the range a TEXT_MON job will search for a text string using a search boundary type of line, regular expression, or date and time.

ApplicabilityESP System Agents, Release 6, used within a TEXT_MON workload object. For more information, see “TEXT_MON Statement: Monitor Content of Text File” on page 1242.

SyntaxSEARCHRANGE [LINE|REGEX|DATETIME] FROM(lower)TO(upper)

Usage notesSEARCHRANGE is an alternative form of RANGE. Refer to “RANGE Statement: Specify Search Range Within TEXT_MON” on page 1020.While most searches require you to specify both FROM and TO operands, you must specify at least one of them. If you only specify FROM, the search range is from the lower limit specified by the FROM operand to the end of the file. If you only specify TO, the search range is from the beginning of the file to the upper limit specified by the TO operand.If you use the CONTINUOUS operand in the TEXTSTRING statement, you cannot use the TO operand in the SEARCHRANGE statement.

Operand DescriptionLINE Search for the text string in the line boundaries defined by the upper

and lower line boundaries. If LINE is specified, the search boundaries FROM and TO are numeric.

REGEX Search for a text string within boundaries defined by a regular expression. If REGEX is specified, the search boundaries FROM and TO are regular expressions.

DATETIME Search for a text string within boundaries defined by a specified date and time. If DATETIME is specified, the job statement TIMEFORMAT must be used.

FROM (lower) Specifies the start of the range to be searched.TO (upper) Specifies the end of the range to be searched.

1145

ExamplesExample 1 (NT)In this example, the LINE operand is specified. If you use the CONTINUOUS operand, do not use a TO operand.TEXT_MON SRCHRNGE.STMNT1 AGENT R6AGENT TEXTSTRING 'ERROR MESSAGE' EXIST CONT(A123) TEXTFILE 'c:\cybermation\logfile' SEARCHRANGE LINE FROM(143) RUN DAILYENDJOB

Example 2 (NT)In this example, the DATETIME operand is specified. The DATETIME operand requires that the TIMEFORMAT statement be specified.TEXT_MON SRCHRNGE.STMNT2 AGENT R6AGENT TEXTFILE 'c:\program files\cybermation\esp system agent + r6\log\transmitter.log' TEXTSTRING NTAGR6 EXIST SEARCHRANGE DATETIME+ FROM(10:00:00)+ TO(09:20:59) TIMEFORMAT 'HH:mm:ss' TIMEPOS(12) RUN DAILYENDJOB

Example 3 (NT)In this example, the operand REGEX is specified in the SEARCHRANGE statement. The FROM and TO operands contain the regular expressions that are evaluated.TEXT_MON SRCHRNGE.STMNT3 AGENT R6AGENT TEXTFILE 'c:\program files\cybermation\esp system agent + r6\agentparm.txt' TEXTSTRING archive EXIST SEARCHRANGE REGEX FROM(ESP) TO(service) RUN DAILYENDJOB

SEARCHRANGE Statement: Specify Search Range Within TEXT_MON

1146

Example 4 (NT)Because back slashes are interpreted as an escape sequence, the two back slashes in the text stringC:\\Program Files

must each be preceded by a back slash, giving four back slashes in the TEXTSTRING statement below.TEXT_MON SRCHRNGE.STMNT4 AGENT R6AGENT TEXTFILE 'c:\program files\cybermation\esp system agent + r6\agentparm.txt' TEXTSTRING 'C:\\\\Program Files' EXIST SEARCHRANGE LINE FROM(1) TO(200) RUN DAILYENDJOB

Example 5 (UNIX)TM SRCHRNGE.STMNT5 AGENT R6AGENT TEXTFILE '/export/home/cybermation/agent/log/transmitter.log' TEXTSTRING NTAGR6 EXIST SEARCHRANGE DATETIME+ FROM('Thu Aug 28 00:00:00.000 EDT 2003')+ TO('Thu Aug 28 23:59:59.999 EDT 2003') TIMEFORMAT 'EEE MMM dd HH:mm:ss.SSS zzz yyyy' TIMEPOS(1) RUN DAILYENDJOB

Example 6 (UNIX)In this example, the FROM operand specifies the word agent at the beginning of the line (using the \A). TEXT_MON SRCHRNGE.STMNT6 AGENT R6AGENT TEXTFILE '/export/home/cybermation/espsystemagent+ agentparm.txt' TEXTSTRING \.0/MAIN$ EXIST SEARCHRANGE REGEX FROM(\Aagent) TO(level=2\Z) RUN DAILYENDJOB

1147

Example 7 (UNIX)In this example, the search is for the string

# Runner plugin parameters

which is evaluated as a regular expression (operand REGEX in the SEARCHRANGE statement).TEXT_MON SRCHRNGE.STMNT7 AGENT R6AGENT TEXTFILE '/export/home/cybermation/agentparm.txt' TEXTSTRING \A\W\sRunner EXIST SEARCHRANGE REGEX FROM(ESP) TO(service) RUN DAILYENDJOB

The criteria \A, \W, and the word \sRunner are evaluated as follows:• \A means match only at the beginning of the line.• \W means match a non-word character• \sRunner means look for a white space before the word Runner.

Example 8 (UNIX)In this example, the operand CONTINUOUS in the TEXTSTRING statement prevents the use of the TO operand in the SEARCHRANGE statement. When the text string agent is found, as specified by the operand EXIST, an Alert text will be issued.TEXT_MON SRCHRNGE.STMNT8 AGENT R6AGENT TEXTFILE '/export/home/cybermation/logfiles/test' TEXTSTRING agent EXIST CONTINUOUS(text) SEARCHRANGE LINE FROM(1) RUN DAILYENDJOB

SECURE Statement: Secure Symbols

1148

SECURE Statement: Secure Symbols

The SECURE statement is used to secure any symbol.

TypeSymbolic variable library statement.

SyntaxSECURE variable

Usage notesA secured symbol is one that contains sensitive data, such as a password, and consequently requires additional security. ESP exerts control over secured symbols based on how ESP processes the symbol.These are some of the controls that ESP exerts on secured symbols:• ESP only produces the assigned values for JCL submitted to the internal reader• ESP does not produce the assigned values when writing JCL to a COPYJCL

library• SEND or VS subcommands do not produce the assigned values• You cannot assign a secured symbol to another symbol, for example, a secured

symbol cannot appear to the right of the equal sign in an assignment statement.

Related informationFor information on defining symbolic libraries, see the DEFSYML command.

Example How to identify a secured symbolIn the following example, ESP resolves the symbolic %PASSWORD only when it encounters the symbol in JCL it submits to the internal reader.PASSWORD='OPEN'SECURE PASSWORD

Note: These statements are coded in a symbolic variable library.

Operand Descriptionvariable Indicates the name of the secured symbolic variable.

1149

SELECT Statement: Select Jobs or SubApplications

The SELECT statement is used to identify that a job or subApplication should be selected as part of an Application.

TypeESP Application statement.

SyntaxSELECT {jobname|(jobname[,jobname])} [JOB|SUBAPPL]

Usage notesThe SELECT statement must be used after you have defined your job. If the SELECT statement is used for any job that has COREQ, POSTREQ, or PREREQ specified, the jobs that these statements refer to are selected automatically.Differentiate between whether or not you want to select a job or subApplication using the JOB or SUBAPPL keywords. JOB is the default.Selecting a subApplication allows you to select a group of jobs with one statement instead of selecting each job individually.You cannot select a job and a subApplication using the same SELECT statement.RUN statements are used within the scope of a JOB statement. This allows you to look at a job definition and see the schedule frequency for the job. Many criteria can be handled with RUN statements without the need for using IF TODAY type logic.SELECT statements allow you to easily see all the jobs with the same criteria. Changing the criteria for these jobs requires a change to a single SELECT statement.

Related informationFor information on Applications, see the ESP Workload Manager User’s Guide.For information on selecting jobs for submission, see the RUN, POSTREQ, PREREQ, and COREQ statements. For information on deselecting jobs for submission, see the DESELECT statement.

Operand Description

jobname Indicates a jobname. Enclose multiple jobnames in parentheses, separated by a blank or comma.

JOB Indicates a job is selected for submission. This is the default.SUBAPPL Indicates all jobs within a subApplication are being selected for

submission.

SELECT Statement: Select Jobs or SubApplications

1150

Examples Selects multiple jobs for submissionIn the following example, PAYJOB1 and PAYJOB2 are selected for submission whenever the PAYROLL Application is invoked.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 REL PAYJOB2JOB PAYJOB2 ENDJOBSELECT (PAYJOB1,PAYJOB2)

Selects multiple jobs for submission on specific daysIn the following example, PAYJOB3 and PAYJOB4 are selected for submission on workdays.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB3 REL PAYJOB4JOB PAYJOB4 ENDJOBIF TODAY('WORKDAY') THEN SELECT (PAYJOB3,PAYJOB4)

Selects a sub-Application for submissionIn the following example, the PREPJOBS subApplication is selected for submission whenever the PAYROLL Application is invoked.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'SUBAPPL PREPJOBSJOB PAYJOB5 REL PAYJOB6JOB PAYJOB6 REL PAYJOB7JOB PAYJOB7 REL PAYJOB8JOB PAYJOB8 ENDJOBSELECT PREPJOBS SUBAPPL

1151

Selects multiple jobs for submission on specific daysIn the following example:• PAYJOB5 is selected for submission on workdays• PAYJOB6 is selected for submission on Wednesdays• PAYJOB7 is selected for submission on Fridays.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB5 REL PAYJOB6JOB PAYJOB6 REL PAYJOB7JOB PAYJOB7 ENDJOBIF TODAY('WORKDAYS') THEN SELECT PAYJOB5 IF TODAY('WEDNESDAY') THEN SELECT PAYJOB6 IF TODAY('FRIDAY') THEN SELECT PAYJOB7

Select/Deselect sub-ApplicationThe following statements are used to:• Select subApplications • Select a job within an Application• Deselect a subApplication • Deselect a job within an Application.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB ACCJOB1 SUBAPPL ACCPAYENDJOBJOB ACCJOB2 SUBAPPL ACCPAYENDJOBJOB BILJOB1 SUBAPPL BILLINGENDJOBJOB BILJOB4 SUBAPPL BILLINGENDJOBJOB PAYJOB10 ENDJOBSELECT (ACCPAY,BILLING) SUBAPPLSELECT PAYJOB10IF TODAY('LAST WORKDAY OF MONTH') THEN DESELECT BILLING SUBAPPLIF TODAY('MONDAY') THEN DESELECT ACCJOB2

SELECT Statement: Select Jobs or SubApplications

1152

In the above example:• The ACCPAY and BILLING subApplications are selected• PAYJOB10 is selected• The BILLING subApplication is not selected on the last workday of the month• ACCJOB2 is not selected on Mondays.Select multiple jobs on specific daysIn the following example, PAYJOB8 and PAYJOB9 are selected for submission on workdays. On the first workday of the month, PAYJOB9 is deselected for submission.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB8 REL PAYJOB9JOB PAYJOB9ENDJOBIF TODAY('WORKDAYS') THEN SELECT (PAYJOB8,PAYJOB9) IF TODAY('1ST WORKDAY OF MONTH') THEN DESELECT PAYJOB9

1153

SEND Command: Send Messages

The SEND command is used to send a message to yourself, another user, a group of users, or an operator console. By default, messages are sent now if a user is logged on. If a user is not logged on, messages can be queued to the broadcast data set until the user logs on.

TypeEvent definition command.

Syntax{SEND|SE} 'message text' [USER{(*)|(userid[,userid]...)}] [CN(console)] [OPER(routing code)] [ROSPFX(rospfx[,rospfx]...)] [NONDEL] [NOW] [SYSTEM(name)] [DESCRIPTOR(descriptor code)

Operand Description

'message text' Indicates a message to be transmitted, enclosed within quotes. If the message contains imbedded quotes, they should be doubled up. The message can be up to 124 characters.

* Indicates the message is to be sent to the current user ID. This is the default. USER can be abbreviated to U.

userid Indicates one or more TSO user IDs to whom the message is sent. If a list of user IDs is specified, separate each one with a blank or comma.

console Indicates the UCM ID or the console name of the console that is to receive the message.

routing code Indicates the MCS routing code for a message to be sent to one or more operator consoles. Value between 1 and 32.

rospfx Indicates one or more ROSCOE users, identified by ROSCOE prefix, to whom the message is sent. If a list of prefixes is specified, separate each one with a blank or comma.

NONDEL Indicates the message is marked as non-roll-deletable, if it is transmitted to a console.

SEND Command: Send Messages

1154

Usage notesYou can include several SEND commands in an Event.A SEND command can also be issued from an ESP Procedure.The SEND command, by default, goes to the system the Event was defined on. You should check the system a user is logged on to before assuming the Event definition system is the same as where you want to send a message.

Related informationFor information on sending messages, see the ESP Workload Manager User’s Guide.

Examples Send message to specific userIn the following example, USR01 is sent a message at 8 am everyday, indicating the current time (represented by the %ESPATIME symbolic variable):EVENT ID(CYBER.MESSAGE)SCHEDULE 8AM DAILYSEND 'THE TIME IS %ESPATIME' USER(USR01)ENDDEF

Send message to a consoleIn the following example, a non-roll-deletable message is sent to console 01, indicating that a CICS region has ended:EVENT ID(CYBER.CICS_JOBEND)SEND 'CICS ENDED' CN(01) NONDELENDDEF

NOW Indicates the message be sent now if the user is logged on. If the user is not logged on, the message is not queued to the broadcast data set.

name Indicates the name of a SYSPLEX member. This is not the ESP system name, it’s the name by which z/OS knows the member of the SYSPLEX. Can be used to route a SEND command in a SYSPLEX environment to wherever the user is logged on. Use an asterisk to indicate the message goes wherever ESP is running.

descriptor code Indicates descriptor code value between 1 and 16 to receive notification. Separate each descriptor code with a comma. The alias DESC or D may be used. NONDELETABLE is accepted and is the same as DESCRIPTOR (11).

Operand Description

1155

Send message when Application starts and completesIn the following example, two messages are sent to USR01, the first when the PAYROLL Application starts and the second when it ends:APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB START.APPL LINK PROCESS RUN DAILY REL PAYJOB1 SEND '%ESPAPPL..%ESPAPGEN STARTED AT %ESPATIME' USER(USR01)JOB PAYJOB1 RUN DAILY REL PAYJOB2JOB PAYJOB2 RUN DAILY REL END.APPLJOB END.APPL LINK PROCESS RUN DAILY SEND '%ESPAPPL..%ESPAPGEN COMPLETED AT %ESPATIME' USER(USR01)ENDJOB

Indicates if user is logged onIndicates the message is sent now if the user is logged on. If the user is not logged on the message is not queued to the broadcast data set:SEND 'SCHEDULING IS EASY WITH ESP' USER(CYB01) NOW

Indicates if user is in a SYSPLEX environmentIndicates the message is sent to a user in a SYSPLEX environment:SEND 'SCHEDULING IS EASY WITH ESP' USER(CYB01) - SYSTEM(SYSA)

Indicates if multiple users are logged onIndicates a message is sent to two users. If either user is not logged on the message is queued to the broadcast data set, until the user logs on:SEND 'SCHEDULING IS EASY WITH ESP' U(CYB01,CYB02)

Specify descriptor codesThe following example sends a message to routing code 2, with descriptor code 2:SEND 'SCHEDULING IS EASY WITH ESP' OPER(2) DESC(2)

SEQUENT_JOB Statement: Identify the Name of Sequent Jobs

1156

SEQUENT_JOB Statement: Identify the Name of Sequent Jobs

The SEQUENT_JOB statement is used to identify the name of a Sequent job in an Application. Note: Sequent replace the former DYNIX/ptx operating system.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use Sequent jobs, you must load a workload object module. The SEQUENT_JOB workload object module is CYBESOSQ. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Refer to the JOB statement usage notes.

Examples:

Example 1 Example 1 shows a DYNIX/ptx job statement using the full job statement:SEQUENT_JOB payroll2.payscrpt

In the above example, the job statement identifies this workload object as a Sequent script called payroll2.payscrpt.

Example 2Example 2 shows a DYNIX/ptx job statement using the abbreviated syntax:SQ payroll2.payscrpt

In the above example, the job statement identifies that this workload object is a Sequent script called payroll2.payscrpt.

1157

SERVERADDR Statement: Specify FTP Server Name Within FTP_JOB

The SERVERADDR statement specifies the name of the FTP server when using the FTP_JOB statement.

ApplicabilityESP System Agents, Release 6, used within an FTP_JOB workload object. For more information, see “FTP_JOB Statement: Identify the Name of FTP Jobs” on page 623.

SyntaxSERVERADDR serveraddress

Usage notesSERVERADDR is a required statement within an FTP_JOB workload object. SERVERADDR can be a global statement.

ExamplesExample 1 (UNIX)FT FTPT1A AGENT R6AGENT USER lmla SERVERADDR hpsupport SERVERPORT 21 TRANSFERDIRECTION D TRANSFERCODETYPE A REMOTENAME /u1/qatest/ftpdata/textfile LOCALNAME /export/home/qatest/test1 RUN DAILYENDJOB

Operand Descriptionserveraddress The format is case sensitive, up to 100 characters in length.

SERVERADDR Statement: Specify FTP Server Name Within FTP_JOB

1158

Example 2 (Windows)FT FTPT1AAGENT R6AGENTUSER lmlaSERVERADDR 130.10.10.100SERVERPORT 21TRANSFERDIRECTION DTRANSFERCODETYPE AREMOTENAME /u1/qatest/ftpdata/textfileLOCALNAME c:\qatestRUN DAILY

ENDJOB

1159

SERVERPORT Statement: Specify FTP Server Port Number Within FTP_JOB

The SERVERPORT statement specifies the FTP server port number.

ApplicabilityESP System Agents, Release 6, used within the FTP_JOB workload object. For more information, see “FTP_JOB Statement: Identify the Name of FTP Jobs” on page 623.

SyntaxSERVERPORT serverport

Usage notesSERVERPORT is an optional statement within an FTP_JOB workload object. SERVERPORT can be a global statement.

ExamplesExample 1 (UNIX)FTP_JOB FTPTEST7.DOWNLOAD AGENT R6AGENT USER test SERVERADDR 13.50.30.100 SERVERPORT 21 TRANSFERDIRECTION D FTPFORMAT A REMOTENAME /export/home/qatest/ftpdata/textfile1 LOCALNAME '/export/home/qatest/ftpdata/folder/textfile1' RUN DAILY AFTER CHECK.PART1ENDJOB

Operand Descriptionserverport The operand must be numerical, with a maximum of five digits.

SERVERPORT Statement: Specify FTP Server Port Number Within FTP_JOB

1160

Example 2 (Windows)FTP_JOB FTPTEST7.DOWNLOADAGENT R6AGENTUSER testSERVERADDR 13.50.30.100SERVERPORT 23TRANSFERDIRECTION DFTPFORMAT AREMOTENAME c:\qatest\ftpdata\textfile1LOCALNAME 'c:\qatest\ftpdata\D folder\textfile1'RUN DAILYAFTER CHECK.PART1

ENDJOB

1161

SERVICE_MON Statement: Monitor Windows Services

Monitors Windows Services names and statuses on a local Windows Agent against specified criteria.

TypeApplication statement.

ApplicabilityRelease 6 System Agents.

SyntaxRefer to the JOB statement syntax.

Usage notesUse these statements in a SERVICE_MON workload object:• SERVICENAME (Mandatory)• STATUS (Mandatory. All STATUS operands apply for a SERVICE_MON

workload object).To use Windows Services monitors, you must load the workload object module CYBESOSM with the WOBDEF command or with the WOBDEF initialization parameter.The short form of SERVICE_MON is SM.Also refer to the JOB statement usage notes.

ExampleMonitors the ESPEspresso service for a status of CONTINUE_PENDINGSERVICE_MON STATUS1.STMNT AGENT R6AGENT SERVICENAME ESPEspresso STATUS CONTINUE_PENDING WAIT RUN DAILYENDJOB

SERVICENAME Statement: Specify Windows Service Name Within SERVICE_MON

1162

SERVICENAME Statement: Specify Windows Service Name Within SERVICE_MON

The SERVICENAME statement specifies the name of a service on a local Windows machine that will be monitored by a SERVICE_MON workload object.

ApplicabilityESP System Agents, Release 6, used within a SERVICE_MON workload object. For more information, see “SERVICE_MON Statement: Monitor Windows Services” on page 1161.

SyntaxSERVICENAME servicename

Usage notesSERVICE is the short form of SERVICENAME.

ExamplesExample 1In this example, the service ESPEspresso is monitored for a status of CONTINUE_PENDING.SERVICE_MON STATUS1.STMNT AGENT R6AGENT SERVICENAME ESPEspresso STATUS CONTINUE_PENDING WAIT RUN DAILYENDJOB

Example 2In this example, the service ESPEspresso is monitored for a status of PAUSE_PENDING.SERVICE_MON STATUS2.STMNT AGENT R6AGENT SERVICENAME ESPEspresso STATUS PAUSE_PENDING WAIT RUN DAILYENDJOB

Operand Descriptionservicename The format is case sensitive, any character, and up to 256 characters

in length.

1163

SET Command: Set Environment Variables

The SET command is used to set an environment variable.

TypeOPER command.

AuthorityYou require OPER authority to issue the SET command.

SyntaxSET [name=[value]]

Usage notesEverything after the equal sign is the value, including blanks.

Examples Suspend TSO session for 20 seconds.The following is an example of the SET command used to suspend a TSO session for 20 seconds:OPER SET QUERY_TIME_OUT=20

Delete a variableTo delete a variable, issue the SET command with a null value. OPER SET name=

Operand DescriptionSET The SET command without operands lists the pool. name Name is an arbitrary character string. When used with SET it

displays one variable.value Value is an arbitrary character string. For example, it may be used

to represent a time interval in seconds.

SETPRINT Command: Set Default Output

1164

SETPRINT Command: Set Default Output

The SETPRINT command is used to set the default output environment for TITLE processing.

TypeGeneral command.

SyntaxSETPRINT repname

Related informationFor information on defining titles, see the TITLE command.For information on defining a logical report name, see the DEFPRINT command.

Example Set title for reportIn the following example, the titles are set for the CYBPRT1 report.SETPRINT CYBRPT1TITLE 1 'CYBERMATION INC.'TITLE 2 'DATA CENTER OPERATIONS REPORT'

Operand Descriptionrepname Indicates a one to eight alphanumeric logical report name, as

identified by a DEFPRINT command.

1165

SETVAR Command: Define Variables

The SETVAR statement is used to define variables in a data object. Data can be stored in this data object at generate time by coding one or more SETVAR statements within the JOB block. Data can also be stored, updated or deleted at run time, by sending an automation framework message to the object. All data is stored in the Application tracking record, so it is preserved across restarts.

SyntaxSETVAR varname = {'textvalue'|{numvalue}

Related informationRefer to the DATA_OBJECT Command in the ESP Workload Manager Reference Guide Volume 1.

Example To create a variable within a DATA_OBJECTIssue a SETVAR statement with the name of the variable and its value. DATA_OBJECT DATA2 SETVAR Var1='This is a value' SETVAR Var2='Testing' SETVAR Var3=42ENDJOB

Operand Descriptionvarname Indicates the name of the value. text value Indicates a character string. numvalue Indicates a numeric value.

SETWIDTH Command: Set Output Width

1166

SETWIDTH Command: Set Output Width

The SETWIDTH command is used to set the width of output.

TypeGeneral command.

SyntaxSETWIDTH nnn

Usage notesYou can use this command to format output, for example, when issuing display commands from Page mode.If you set the width in Page mode, it is reset when you exit from ESP.

Related informationFor information on setting column width in a History report, see the DISPLAY command.

Examples Indicate column width of reportIn the following example, the history report produced by this series of reporting commands is 80 columns.REPORTSETWIDTH 80FROM 8AM TODAYCRITERIA APPLSYS EQ PAYROLLDISPLAY JOBNAME JOBNO EXECST CMPCENDR

Set column widthIn the following example, the width of output produced by an LSAR command is set to 132 columns. SETWIDTH 132LSAR DSNAME('CYBER.SADFILE')

Operand Descriptionnnn Indicates the column width of a report. The default is 80.

1167

SHADGOAL Command: Instruct Shadow Manager

SHADGOAL is only relevant if you have the ESP Workload Manager High Availability Option (HAO) installed.The SHADGOAL command is used to instruct a shadow manager of the actions to take when an ESP master terminates. SHADGOAL is issued only via the z/OS MODIFY command to a shadow manager.The SHADGOAL syntax varies in the initialization parameter and the z/OS MODIFY command. For information on the SHADGOAL Initialization Parameter, see the ESP Workload Manager Installation and Configuration Guide.

SyntaxSHADGOAL [LIST|HELP] [MASTER(FAIL|LEAVE|QUIESCE)] [AFTER(seconds)] [WARN] [COMMAND('command text') [TAKEOVER|TRIGGER(event)] [DELETE MASTER(FAIL|LEAVE|QUIESCE)]

Operand DescriptionLIST Requests a display of the shadow manager’s shadow goals.HELP Requests a display of the SHADGOAL command options.MASTER Specifies that a shadow goal is to be defined.FAIL Specifies the shadow goal being defined applies to the ESP

master terminating abnormally and entering an XCF failed state.

LEAVE Specifies the shadow goal being defined applies to the ESP master leaving the XCF group and entering an XCF undefined state when it terminates.

QUIESCE Specifies the shadow goal being defined applies to the ESP master entering an XCF quiesced state when it terminates.

AFTER Specifies a time in seconds to wait after the ESP master terminates, before executing the actions specified in the shadow goal. The default is zero if AFTER is not specified.

seconds Specifies the number of seconds to wait after the ESP master terminates, before executing the shadow goal actions. It must be a number within the range 0-86400.

WARN Specifies that warning message 4397 be issued when the shadow goal is executed.

SHADGOAL Command: Instruct Shadow Manager

1168

Usage notesOnce a Shadow-enabled ESP becomes the active master in the XCF group, all shadow goals for that Shadow-enabled ESP are deleted and the SHADGOAL command ceases to be available for that master.

Related informationFor more information on Shadow Goal, see the ESP Workload Manager User’s Guide.

Examples The following example specifies that 180 seconds (three minutes) after the ESPmaster terminates and enters an XCF quiesced state, the shadow manager issues warning message #4397 and issues z/OS command “S ESPM”.SHADGOAL MASTER(QUIESCE) AFTER(180) WARN +COMMAND('S ESPM')

The following example specifies that 300 seconds (five minutes) after the ESP master abnormally terminates, the shadow manager issues warning message #4397 and takes over as the ESP master.SHADGOAL MASTER(FAIL) AFTER(300) WARN TAKEOVER

The following example specifies the shadow goal for the LEAVE option is deleted immediately.SHADGOAL DELETE MASTER(LEAVE)

COMMAND Specifies an z/OS command to be issued when the shadow goal is executed.

command text Specifies the z/OS command to be issued when the shadow goal is executed.

TAKEOVER Specifies the shadow manager should take over as the ESP master when the shadow goal is executed.

TRIGGER Specifies the shadow manager should take over as the ESP master and trigger an event when the shadow goal is executed.

event Specifies the ESP event to be triggered after the shadow manager has taken over as the ESP master.

DELETE MASTER(FAIL)

Specifies the shadow goal policy for the FAIL option is deleted immediately.

DELETE MASTER (LEAVE)

Specifies the shadow goal policy for the LEAVE option is deleted immediately.

DELETE MASTER (QUIESCE)

Specifies the shadow goal policy for the QUIESCE option is deleted immediately.

Operand Description

1169

SHADOW Command: Control and Display Shadow Manager

The SHADOW command is used to control and display an shadow manager.

TypeOPER command.

AuthorityYou require OPER authority to issue the SHADOW command.

SyntaxSHADOW STATUS [ASSUMEPRIMARY|TAKEOVER] [SHUTDOWN|SHUTDOWN RELINQUISH[(member)]] [SHUTDOWN HOLD[(hold_interval)]]

Usage notesWhen it is determined that a hardware or software problem exists on the ESP master, ensure the ESP master is completely down before issuing the SHADOW ASSUMEPRIMARY or TAKEOVER command.

Related informationFor information on shadow manager, see the ESP Workload Manager User’s Guide.

Operand DescriptionSTATUS Displays the status of the XCF group.ASSUMEPRIMARY|TAKEOVER

Indicates the shadow manager should immediately take over the duty of ESP master.

SHUTDOWN Indicates to shutdown the ESP master or shadow manager. The shutdown will occur against the XCF member it was issued against.

SHUTDOWN RELINQUISH[(member)]

Indicates the ESP master should shutdown and the shadow manager specified should take over immediately. This overrides any existing Shadow Goal. The optional member operand specifies the XCF member name of a shadow manager in the XCF group.

HOLD[(hold_interval)] Indicates the ESP master should shutdown, and the shadow manager should wait x amount of minutes before it takes over. The hold_interval operand is optional as the default amount of time before shadow manager takes over is five minutes. This overrides any existing time defined in a Shadow Goal.

SHADOW Command: Control and Display Shadow Manager

1170

Examples Display the XCF group The following SHADOW command displays the status of the XCF group:OPER SHADOW STATUS

Immediate take over as the ESP masterThe following command instructs the shadow manager to immediately take over the duty of the ESP master:OPER SHADOW ASSUMEPRIMARY

Time delay take over as the ESP masterThe following command instructs the ESP master to shutdown and the shadow manager wait five minutes before it takes over: OPER SHADOW SHUTDOWN HOLD

The following command instructs the ESP master to shutdown and the shadow manager wait 15 minutes before it takes over: OPER SHADOW SHUTDOWN HOLD(15)

1171

SHELL Statement: Specify UNIX Shell to Run Script

The SHELL statement specifies the shell used to run the script named in the SCRIPTNAME statement. You can specify SHELL within the boundaries of the job definition, or you can specify SHELL globally. The SHELL statement is optional. If you do not specify SHELL, the Agent picks up the shell from the first line of the script, from the agentparm.txt file, or from the user profile.A shell is a program that provides an environment for users to interact with the system. Shell programs are files that contain a series of user commands that are grouped, using logic provided by the shell, to accomplish a desired task. Different shells provide different facilities and have different characteristics. Certain functions are specific to certain shells and may be incompatible with other shells.

Applicability ESP System Agent for Unix, Version 2.0 and higher.

SyntaxSHELL shellname

Usage notesTo run a UNIX script, the Agent uses, in the following order, the shell specified in:1. The SHELL statement (if used)2. The first line of the script (if the SHELL statement is unspecified)3. The oscomponent.defaultshell parameter in the agentparm.txt file (if unspecified

in the SHELL statement and in the script)4. The user default shell defined in the user profile (if unspecified in all of the

previous three locations)Note: You must define all shells that you want the Agent to use with the

oscomponent.validshell parameter in the agentparm.txt file, or set the oscomponent.checkvalidshell parameter to false.

Operand Descriptionshellname The name of the shell. You can specify the following UNIX

shells:• /bin/ksh (Korn shell)• /bin/sh (Bourne shell)• /bin/bash (Bourne again shell)• /bin/csh (C shell)• /usr/local/bin/perl (Perl shell)

SHELL Statement: Specify UNIX Shell to Run Script

1172

For more information on the oscomponent.defaultshell and oscomponent.validshell parameters, see the “Listing of Agent Parameters” of the ESP System Agent for UNIX Operating Systems Release 6 Administrator’s Guide.

ExampleSpecify a shell to run the scriptIn this example, the C shell is used to run the sort script.UNIX_JOB MFGSORT RUN DAILY RELEASE MFGRPT AGENT UNIX_LA SCRIPTNAME /mfg/test/sort SHELL /bin/cshENDJOB

1173

SIGCYCLE Command: Cycle Signals

The SIGCYCLE command is used to cycle a signal, it creates a new current generation.

TypeGeneral command.

SyntaxSIGCYCLE signalname

Usage notesSignals cause an ESP Event to wait for a condition in addition to its schedule criteria before it executes. A signal may represent a manual task, such as the arrival of an input tape, or an automated task, such as the completion of a job.Each signal has a generation number. ESP does not automatically reset the generation number of a signal after a signal posts. A cycling process resets the signal. Cycling increments the generation number to the next higher number. If the maximum number of generations already exists, ESP deletes the oldest generation. The signal definition statement specifies the maximum number of generations. You can view this information using the LISTSIG subcommand.

The SIGCYCLE command can be used in an Event. It can also be used in Page mode, an ESP Procedure, or batch.

Related informationFor information on defining and deleting signals, see the DEFSIG and DELSIG commands.For information on posting a generation of a signal, see the SIGPOST command.For information on displaying all generation of a signal, see the LISTSIG command.For information on signal processing, see the ESP Workload Manager Advanced User’s Guide.

Operand Descriptionsignalname Indicates the name of the signal. If the prefix is not specified, the

current group or user prefix is used. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

SIGCYCLE Command: Cycle Signals

1174

Examples Creates new generation of a signalIn the following example, the next generation of TESTSIG is cycled. If the current group prefix is CYBER, ESP cycles the CYBER.TESTSIG signal.SIGCYCLE TESTSIG

Creates new generation of a signal at a specific timeIn the following example, a new generation of CYBER.SIGNAL1 is created at 8 pm each workday.EVENT ID(CYBER.PAYROLL)SCHEDULE 8PM WORKDAYSSIGCYCLE CYBER.SIGNAL1ENDDEF

1175

SIGPOST Command: Post Complete Signal Generations

The SIGPOST command is used to post a generation of a signal complete.

TypeGeneral command.

SyntaxSIGPOST signalname [GEN(genno)]

Usage notes ESP does not automatically reset a signal’s generation number when it posts the current generation. To reset the signal, use the SIGCYCLE command.The SIGPOST command can be used in an Event, or issued from Page mode, an ESP Procedure, or batch.

Related informationFor information on resetting the generation number of a signal, see the SIGCYCLE command.For information on signal processing, see the ESP Workload Manager Advanced User’s Guide.For information on defining and deleting signals, see the DEFSIG and DELSIG commands.For information on identifying that a signal must be marked complete before execution of an Event, see the SIGWAIT command.For information on displaying all generation of a signal, see the LISTSIG command.

Operand Descriptionsignalname Indicates the name of the signal. If the prefix is omitted, the current

group or user prefix is used.genno Indicates the generation, either relative or absolute, of the signal to be

marked complete. A relative number must be zero or negative. If not specified, default is GEN(0), the current generation.

SIGPOST Command: Post Complete Signal Generations

1176

Examples Post complete signalIn the following example, the current generation of CYBER.SIGNAL1 is posted complete.SIGPOST CYBER.SIGNAL1

Posting signal - relative generationIn the following example, the -1 relative generation of CYBER.SIGNAL2 is posted complete.SIGPOST CYBER.SIGNAL2 GEN(-1)

Posting signal - absolute generationIn the following example, generation 123 of CYBER.SIGNAL3 is posted complete.SIGPOST CYBER.SIGNAL3 GEN(123)

Posting current generationIn the following example, the group prefix is set to CYBER, and the current generation on CYBER.MYSIGNAL is posted complete.GROUP CYBERSIGPOST MYSIGNAL

Posting signal for EventIn the following example, the -1 relative generation of CYBER.SIGNAL5 is posted complete at 10 pm on workdays.EVENT ID(CYBER.PAYROLL5)SCHEDULE 10PM WORKDAYSSIGPOST CYBER.SIGNAL5 GEN(-1)ENDDEF

1177

SIGWAIT Command: Identify Signal Conditions

The SIGWAIT command is used to identify a signal that must be marked complete before execution of the Event.

TypeEvent definition command.

SyntaxSIGWAIT signalname [GEN(genno)]

Usage notesTo instruct an Event to wait for posting of a signal, insert the SIGWAIT command in the scheduled Event. You can use more than one SIGWAIT command if the Event is to wait for posting of different signals or different generations of the same signal.The SIGWAIT command can be used only in conjunction with a SCHEDULE statement. The Event waits until both the schedule criteria and signal conditions are satisfied before execution.

Related informationFor information on signal processing, see the ESP Workload Manager Advanced User’s Guide.For information on defining and deleting signals, see the DEFSIG and DELSIG commands.

For information on posting a generation of a signal, see the SIGPOST command.For information on resetting the generation number of a signal, see the SIGCYCLE command.For information on altering the numbers of generations of a signal, see the ALTSIG command.For information on displaying all generations of a signal, see the LISTSIG command.For information on specifying the maximum number of pending signals for an Event, see the EVENT command—MAXPEND operand.

Operand Descriptionsignalname Indicates the name of the signal. If the prefix is not specified the

current group prefix is used.genno Indicates an absolute or relative generation number of a signal. The

default is zero (current generation).

SIGWAIT Command: Identify Signal Conditions

1178

ExampleIdentifies signal which must be marked completeIn the following example, CYBER.PAYROLL does not execute until PROD.DATA is posted complete and the schedule criteria are satisfied.EVENT ID(CYBER.PAYROLL)SCHEDULE 8PM WORKDAYSSIGWAIT PROD.DATA GEN(0)INVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

1179

SIMULATE Command: Simulate Event Functions

The SIMULATE command is used to simulate the functions of an Event.

TypeGeneral command.

SyntaxSIMULATE EVENT(eventid) [SCHED(schedtime)] [PRINT(printdsn)] [JCLDS] [COPYJCL] [ROOTJOB(job1[,job2]...)] [JOB(jobname)] [TRJOB(trigger_jobname)] [TRDSN(trigger_dsname)] [TRVOL(trigger_volume)] [TRUNIT(trigger_unit)] [USER(user_id)] [GROUP(group_id)] [PASSWORD(password)] [SYMLIB(sym_dsn1[,sym_dsn2]...)] [RTYPE(run_type)] [WOB(module1[,module2]...)] [VARS(variable_list)] [SYMBOL(sym_char)] [USER1(user_data1)] [USER2(user_data2)] [USER3(user_data3)] [USER4(user_data4)] [NOLISTPROC] [JCLSCAN(exit_module)] [NOREXX] [NOTSELECTED] [INHERIT] [TRUSR(userid)] [FTPIP(ipaddress)] [FTPUSR(logonid)] [FTPCS(cs)] [FTPBC(bytecount)] [FTPFMT(ftpformat)] [FTPMD(ftpmode)] [TRMEM(member)]

SIMULATE Command: Simulate Event Functions

1180

Operand DescriptionEVENT(eventid) Indicates the name of the Event for which you want to simulate

processing.SCHED(schedtime) Indicates the schedule time to be used for the simulation. This

can be any time specification valid on a SCHEDULE command that resolves to a time and date. If it contains separator characters (commas or blanks), enclose it within quotes. The default is the next scheduled time.

PRINT(printdsn) Indicates the data set to which the JCL is copied. You can specify an asterisk to view the JCL at your terminal.

JCLDS Displays the JCL libraries used for each job. This includes libraries and members identified by JCLLIB, TEMPLIB, DATASET and MEMBER statements in an ESP Procedure.

COPYJCL Requests a simulation of what is written to the COPYJCL library.

ROOTJOB(job1[,job2]...)

Indicates the names of jobs to which you want to restrict the simulation. Specifying jobname+ includes jobname in the simulation plus its successors.

JOB(jobname) Indicates the name of the job being rerun.TRJOB(trigger_jobname) Indicates the job that caused the triggering action.TRDSN(trigger_dsname) Indicates the name of the data set that caused the triggering

action.TRVOL(trigger_volume) Indicates the volume serial number of the data set that caused

the triggering action.TRUNIT(trigger_unit) Indicates the unit name of the data set that caused the triggering

action.USER(user_id) Indicates the user ID under which to simulate the Event.GROUP(group_id) Indicates the group value under which to simulate the Event.PASSWORD(password) Indicates the password value under which to simulate the Event.SYMLIB(sym_dsn1[,sym_dsn2]...)

Indicates a list of data set names of symbol libraries to be used.

RTYPE(run_type)WOB(module1[,module2]...)

Generates a workload object module directory for use in the simulation. If not specified, the directory belonging to the subsystem is used.

1181

VARS(variable_list) Provides a list of variable names and values, for example, varname(value). These variables can include monitor and signal variables. The maximum length of the text in the list is 255 characters.

SYMBOL(sym_char) Indicates a symbol substitution character to be used.USER1(user_data1)Also applies to USER2 to USER4.

Indicates the USER variables passed to the Event. Each variable can be up to 68 characters.

NOLISTPROC Indicates the text of any invoked Procedure is not listed. If this operand is omitted, the text of the Procedure is listed. If an error is detected, the error messages are always listed.

JCLSCAN(exit_module) Defines the name of the module used as the JCLSCAN exit module. If this operand is omitted, no JCLSCAN exit processing is performed for simulated job submissions.

NOREXX Indicates all input text between a REXXON and a REXXOFF statement is ignored. If this operand is omitted, the in-line REXX code is interpreted by REXX.

NOTSELECTED Indicates a list is to be produced of all jobs not selected, for any reason. If this operand is omitted, no list is produced for jobs that were not selected.

INHERIT Indicates if a successor was inherited, the inherited relationships are identified in the output report. If this operand is omitted, no indication is made for jobs that are inherited.

TRUSR(userid) Sets the data set trigger symbolic variable %ESPTRUSR to value userid. The userid has a maximum length of eight characters.

FTPIP(ipaddress) Sets the FTP trigger symbolic variable %ESPFTPIP to value ipaddress.

FTPUSR(logonid) Sets the FTP trigger symbolic variable %ESPFTPUSR to value logonid. The logonid has a maximum length of eight characters.

FTPCS(cs) Sets the FTP trigger symbolic variable %ESPFTPCS to value cs. Permissible values are C and S.

FTPBC(bytecount) Sets the FTP trigger symbolic variable %ESPFTPBC to value bytecount.

FTPFMT(ftpformat) Sets the FTP trigger symbolic variable %ESPFTPFMT to value ftpformat. Permissible values are A, E, and I.

FTPMD(ftpmode) Sets the FTP trigger symbolic variable %ESPFTPMD to value ftpmode. Permissible values are B, C, and S.

Operand Description

SIMULATE Command: Simulate Event Functions

1182

Usage notesFor the Event you select, the SIMULATE command tells you which jobs ESP submits, any messages it sends, how it substitutes symbolic variables, and so on. The SIMULATE command is particularly useful with ESP Procedures because you can use it to see how the complex and conditional components of your Procedure run at a particular date and time. ESP also displays error messages if it encounters problems, such as syntax errors or successor loops in an Application. You can simulate an Event for a day on which it is not normally scheduled; ESP simulates what would happen if the Event was triggered on that particular day.Use the SIMULATE command to emulate the functions of any Event. If you use SIMULATE with no operands, the next scheduled occurrence of the Event is simulated. If no scheduled time exists for an Event, ESP will assume 'NOW'. Use the SCHED operand to specify any valid schedule criteria to be used for the simulation. This allows you to find out what happens if the Event executes on any particular date.Using the PRINT operand with SIMULATE requests that a copy of the JCL, which would be used at the time you are simulating, is made to a data set of your choice. The generated JCL has any symbols appropriately substituted. If you are using ESP’s JCL Tailoring facility, any %INCLUDE and %EXCLUDE statements are resolved. This means that you are able to see the JCL to be used at different times. You can also simulate Events using ESP’s ISPF interface—Option E.3—from the ESP Main Menu.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.

TRMEM(member) Sets the FTP trigger symbolic variable %ESPTRMEM to value member.If the TRMEM(member) parameter is specified, the %ESPTRMEM symbolic variable will be set to that member name, regardless of whether or not the TRDSN(dsname) operand includes a PDS member name.If the TRMEM(member) operand is omitted, but the TRDSN(dsname) operand specifies a PDS member name, meaning TRDSN(dsname(member)), the %ESPTRMEM symbolic variable will be set to that member name.If the TRMEM operand is omitted and the TRDSN(dsname) keyword does not specify a PDS member name, the %ESPTRMEM symbolic variable will be set to null.

Operand Description

1183

Examples Simulate for last workday of the monthIn the following example, the functions that CYBER.PAYROLL performs on the last workday of the month are simulated.SIMULATE EVENT(CYBER.PAYROLL) -SCHED('LAST WORKDAY OF MONTH')

Tomorrows Event functions are simulatedIn the following example, the functions that CYBER.PAYROLL1 performs on the next day are simulated. The simulation is restricted to job A and job D and its successors.SIMULATE EVENT(CYBER.PAYROLL1) SCHED('TOMORROW') - ROOTJOB(A,D+)

Simulates Event functions performed on MondayIn the following example, the functions that CYBER.PAYROLL2 performs on Monday, when the USER1 field is set to PAYJOB1 are simulated.

SIMULATE EVENT(CYBER.PAYROLL2) SCHED('MON') - USER1('PAYJOB1')

Simulates an Event and displays JCL libraries usedSimulates an Event and displays the JCL libraries used for each job:SIMULATE EVENT(CYBER.PAYROLL) JCLDS

Module name used as JCLSCAN exit moduleSimulates an Event. The name of the module used as the JCLSCAN exit module:SIMULATE EVENT(CYBER.PAYROLL) JCLSCAN(CHECKJCL)

Text between REXXON and REXXOFF is ignored

Simulates an Event. All input text between a REXXON and REXXOFF statement is ignored:SIMULATE EVENT(CYBER.PAYROLL) NOREXX

Inherited relationships are identified if successor was inherited

Simulates an Event. If a successor was inherited, the inherited relationships are identi-fied:SIMULATE EVENT(CYBER.PAYROLL) INHERIT

Simulates a job monitor Event Simulates a job monitor Event and identifies monitor variables used by the Event: SIMULATE EVENT(CYBER.PAYJOB1_JOBEND)-VARS(MNJOB(PAYJOB1),MNAPPL(PAYROLL))

SIMULATE Command: Simulate Event Functions

1184

Passes a USER variable to the EventSimulates an Event and passes a USER variable to the Event:SIMULATE EVENT(CYBER.PAYROLL) USER1('PAYJOB1')

Simulates an Event for the last day of the monthSimulates an Event for the last day of the month. The output is sent to your terminal:SIMULATE EVENT(CYBER.PAYROLL) SCHED('LAST DAY OF MONTH') PRINT(*)

Simulation of Event without text of any invoked ESP ProcedureThe following is an ISPF example, it requests that during simulation of an Event, the text of any invoked ESP Procedure is not listed:ESP -------------------- SIMULATE EVENT EXECUTION -------- ESP ADDITIONAL OPTIONSCOMMAND ===>DISPLAY PROCEDURE ===> N (blank, N or Y)SIMULATE DATASET TRIGGER ===> (blank, N or Y)SIMULATE SIGNALS ===> (blank, N or Y)SIMULATE MONITOR EVENT ===> (blank, N or Y)JCLSCAN EXIT NAME ===> (blank or name)SUPPRESS REXX ===> (blank, N or Y)SHOW NOT SELECTED ===> (blank, N or Y)SHOW INHERITANCE ===> (blank, N or Y)

Display shown when ESP Procedure text is not listed The following is an example of the display produced when the ESP Procedure text is not listed:ESP ----------------------- EVENT CYBER.PAYROLL ---------- ESPCOMMAND ===>INVOKE CYBER.PROCLIB(PAYROLL)SIMULATION OF EVENT CYBER.PAYROLL AT 07.39.26 ON MONDAY MAY 30TH, 1997JOBS: PAYJOB1, PAYJOB992 JOBS SELECTED FOR SUBMISSION

JOB TYPE-JOBNAME--HC-RELEASESJOB PAYJOB1 0 (NONE)REQUEST PAYJOB99 0 (NONE)TASK PAYJOB2 0 (NONE)MAN SUB PAYJOB3 0 (NONE)LINK PAYJOB4 0 (NONE)EXTERNAL PAYJOB5 0 (NONE)

1185

Simulation of data set triggered EventThe following is an ISPF example, it illustrates the simulation of a data set triggered Event:ESP -------------------- SIMULATE EVENT EXECUTION -------- ESP ADDITIONAL OPTIONSCOMMAND ===>DISPLAY PROCEDURE ===> (blank, N or Y)SIMULATE DATASET TRIGGER ===> Y (blank, N or Y)SIMULATE SIGNALS ===> (blank, N or Y)SIMULATE MONITOR EVENT ===> (blank, N or Y)JCLSCAN EXIT NAME ===> (blank or name)SUPPRESS REXX ===> (blank, N or Y)SHOW NOT SELECTED ===> (blank, N or Y)SHOW INHERITANCE ===> (blank, N or Y)

Entering Y in the above panel presents you with the following panel, where you can specify the data set name, the triggering job name, volume serial or unit that caused the triggering action, as follows:ESP ---------------------- SIMULATE EVENT EXECUTION ------ ESP DATASET TRIGGER OPTIONSCOMMAND ===>DATASET NAME ===> CYBER.TEST.DATATRIGGERING JOB NAME ===>VOLUME SERIAL ===>UNIT ===>

The following is an example of the display produced when data set name field is entered:ESP ----------------------- EVENT CYBER.PAYROLL ---------- ESPCOMMAND ===>INVOKE CYBER.PROCLIB(PAYROLL)APPL PAYROLLJCLLIB 'CYBER.JCLLIB'JOB PAYJOB1 RUN DAILY RELEASE PAYJOB2JOB PAYJOB2 RUN DAILYENDJOBSIMULATION OF EVENT CYBER.PAYROLL AT 07.39.26 ON MONDAY MAY 30TH, 1997JOBS: PAYJOB1, PAYJOB22 JOB SELECTED FOR SUBMISSIONJOB TYPE-JOBNAME--HC-RELEASESJOB PAYJOB1 0 (PAYJOB1)JOB PAYJOB2 1 (NONE)

SIMULATE Command: Simulate Event Functions

1186

Note: You are not testing if this Event is triggered by this data set, you are testing the Event as if it was triggered by the data set name you specify. ESP resolves symbolic variables based on this name.

1187

SKIPPARMUPDATES Statement: Control Updates to Job Parameters (PeopleSoft)

The SKIPPARMUPDATES statement sets the value of the SKIPPARMUPDATES parameter. The SKIPPARMUPDATE parameter is associated with the data in the PeopleSoft database table PS_PRCSDEFN and controls updates to job parameters.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax SKIPPARMUPDATES YES|NO

Usage notesThe recommended use for this parameter is for those cases where some bind variables in the table PS_PRCSDEFN may be unresolved. If you specify YES in the SKIPPARMUPDATES statement, the parameters in PS_PRCSDEFN will be ignored.If you specify YES in this statement, you can use the ARGS statement to pass any additional PS job arguments values. See “AGENTMSG Command: Send Messages to Agent” on page 41.

ExampleExample 1PS TEST.PSJOB PROCESSTYPE nVision-Report PROCESSNAME NVSRUN OUTDESTTYPE FILE OUTDESTFORMAT XLS OUTDESTPATH c:\test\testnv.xls SKIPPARMUPDATES Yes Args -NRNVARIABLE -NBUAUS01 -NHLhttp://10.1.1.40/psp/ps+ /EMPLOYEE/ERP/c/REPORT_BOOKS.IC_RUN_DRILLDOWN.GBL?Action=A RUN DAILYENDJOB

Operand DescriptionYES The Agent will not update job parameters with data in the table

PS_PRCSDEFN. NO Default. The Agent will update job parameters with data in the

table PS_PRCSDEFN.

SKIPPARMUPDATES Statement: Control Updates to Job Parameters (PeopleSoft)

1188

Example 2PS_JOB SKIPPARM.REPORT ARGS -ORIENTL "SHARE" SKIPPARMUPDATES YES RUNCONTROLID test PSOPRID VP1 OUTDESTTYPE WEB OUTDESTFORMAT PDF PROCESSTYPE Crystal PROCESSNAME 'OMC3220-' RUN DAILYENDJOB

Example 3PS_JOB SKIPPARM.test2 RUNCONTROLID sample PROCESSTYPE Crystal PROCESSNAME 'OMC3220-' SKIPPARMUPDATES N PSOPRID VP2 RUN DAILYENDJOB

1189

SMFSTATS Command: Display SMF Status

The SMFSTATS command is used to display SMF statistics. The display includes the number of job starts, started task starts, TSO user starts, and step ends since the ESP subsystem initialized.

TypeGeneral command.

SyntaxSMFSTATS

Example SMFSTATS command displayIn the following example, since ESP initialized there were:• 70 job starts• 2 started task starts• 12 TSO user starts• 194 step ends.SMFSTATSESP SUBSYSTEM INITIALIZED AT 11.35.47 ON SATURDAY FEBRUARY 7TH, 199818959 ENTRIES TO SMFWTM, 8328 BY BRANCH ENTRY AND 10631 BY SVC1904 ENTRIES TO ESP PHASE 270 JOB STARTS, 2 STC STARTS, 12 TSU STARTS, 194 STEP ENDS

SNDESPMSG Command: Send Messages to ESP Manager

1190

SNDESPMSG Command: Send Messages to ESP Manager

The Send ESP Message (SNDESPMSG) command is used to send messages to the user status field in CSF. It is issued from the platform where the agent is running. You use this command to send a status message.

Entering CommandThe SNDESPMSG command is issued via:• the command line• a script or program.

SyntaxSENDESPMSG MESSAGE('message text')

ExampleSend Message to CSF User Status FieldTo send a message to the user status field in CSF, type the following:SNDESPMSG MESSAGE('JOBA completed successfully')

Operand DescriptionMESSAGE('message text') Free-format message text. The message must be enclosed within

single quotes and parenthesis as shown.

1191

SORT Command: Specify Ascending/Descending Sort Sequence

The SORT command is used to specify an ascending or descending sort sequence for any of the entries specified by the DISPLAY command in an ESP history report.

TypeReporting command.

SyntaxSORT field {A|D}

Usage notesSeveral sort fields can be specified, one after the other, separated by a blank.

Related informationFor information on history reporting, see the ESP Workload Manager User’s Guide.For information on specifying fields to display on your history report, see the DISPLAY command.

Examples Specifies fields to be sorted in sequence of ascending DASD EXCP countsIn the following example, history data is sorted by decreasing use of CPU time (CPUTIME). If two or more jobs have matching CPU times, they are displayed in sequence of ascending DASD EXCP counts (DEXCP).REPORTFROM 8AM YESTERDAYCRITERIA APPLSYS EQ PAYROLLDISPLAY JOBNAME CPUTIME DEXCP EXECSTSORT CPUTIME D DEXCPENDR

Operand Descriptionfield Indicates the name of a field.A Indicates sorting in ascending sequence. This is the default.D Indicates sorting in descending sequence.

SORT Command: Specify Ascending/Descending Sort Sequence

1192

Specifies fields to be sorted in ascending execution queue timeIn the following example, history data is sorted by ascending jobname (JOBNAME). If two or more jobs have the same name, they are displayed in sequence of ascending execution queue time (EXECQT).REPORTFROM 8AM YESTERDAYCRITERIA APPLSYS EQ PAYROLLDISPLAY JOBNAME JOBNO INPUTQT EXECQTSORT JOBNAME EXECQTEND

1193

SPACE Command: Space Output

The SPACE command is used to space output by one or more lines to make the output easier to read.

TypeGeneral command.

SyntaxSPACE [count]

Usage notesThe SPACE command can be used in Page mode or in batch.

Example Insert spaces in output listingIn the following example, four blank lines are inserted between the special day listing (LISTSPEC) and the holiday display (LISTHOL).LISTSPECSPACE 4LISTHOL

Operand Descriptioncount Indicates the number of lines to be advanced. The default is one.

SPINLOG Command: Spin Audit Log

1194

SPINLOG Command: Spin Audit Log

The SPINLOG command is used to spin a selected log to a sysout class. Starting with ESP Workload Manager version 5.3, there is an automatic spinlog that is set with the AUDITLOG initialization parameter.

TypeGeneral command.

AuthorityYou require OPER authority to issue the SPINLOG command.

SyntaxSPINLOG [AUDITLOG|ENCORELG|CPEENQLG]

Usage notesAn ENCPARM SPINLOG command with no operands acts upon the ESP Workload Manager audit log.The sysout class, and optionally the form number for spinning the audit log, is identified by the AUDITLOG initialization parameter.

Related informationFor information on setting the print characteristics of ESP’s audit log, see the AUDITLOG parameter in the ESP Workload Manager Installation and Configuration Guide.

Example Display produced by SPINLOGIn the following example, 262 records are spun to sysout class E.OPER SPINLOGESP1023I Auditlog dataset spun with 262 records to sysout class E

Operand DescriptionAUDITLOG Spin the ESP audit logENCORELG Spin the log of RQEN (ENCREQ) IARsCPEENQLG Spin the log of RQEN (CPEENQ) IARs

1195

SPOOLRECIPIENT Statement: Specify SAP Spool Recipient

The SPOOLRECIPIENT statement specifies the recipient for the SAP spool. The recipient receives the spool upon job completion or failure.

ApplicabilityESP Business Agents for SAP, Release 5 and higher.

SyntaxSPOOLRECIPIENT recipient

Usage notesYou can use the SPOOLRECIPIENT statement within the SAP_JOB and BDC_JOB workload objects.

ExamplesSpecifying e-mail addressIn this example, jsmith@company1.com receives the spool upon job completion.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RECIPIENTTYPE MAIL SPOOLRECIPIENT jsmith@company1.com ABAPNAME RSPARAM RUN DAILYENDJOB

Operand Descriptionrecipient Specifies the SAP user, SAPoffice distribution list, or email

address to receive the spool.

Hint: To specify multiple recipients, use multiple SPOOLRECIPIENT statements or define a distribution list in SAP and use the DLI recipient type. For more information on specifying recipient types, see “RECIPIENTTYPE Statement: Specify Recipient Type for SAP Spool” on page 1030. It is case sensitive and can be up to 240 valid SAP characters in length. If recipient contains delimiters (such as spaces), enclose it in quotes.

SPOOLRECIPIENT Statement: Specify SAP Spool Recipient

1196

Specifying SAP userIn this example, the SAP user J01Prod receives the spool upon job completion.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RECIPIENTTYPE SU SPOOLRECIPIENT J01Prod ABAPNAME BTCTEST RUN DAILYENDJOB

Specifying SAPoffice distribution listIn this example, the users on the payroll distribution list receive the spool upon job completion.APPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT RECIPIENTTYPE DLI SPOOLRECIPIENT payroll ABAPNAME BTCTEST RUN DAILYENDJOB

1197

SPUSER Command: Identify Initial Users

The SPUSER command is used to identify the initial user who must access ESP to perform the user and group definitions. The SPUSER command is meaningful only in non-SAF environments.

TypeGeneral command.

AuthorityYou require OPER authority to issue the SPUSER command.

SyntaxSPUSER userid

Usage notesThis SPUSER command is normally stored in the ESP cold initialization parameter data set.In a non-SAF environment, you need a DEFUSER statement in CYBESINI prior to the DEFCAL statement.

Related informationFor information on defining an initial user to ESP at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.

Example Identifies initial userIn the following example, USR01 is identified as the initial user. USR01 has access to ESP to define users.OPER SPUSER USR01

Operand Descriptionuserid Indicates the TSO user ID of the initial user.

SQL Statement: Specify SQL Statement Within DB_JOB

1198

SQL Statement: Specify SQL Statement Within DB_JOB

The SQL statement specifies the SQL statement to be executed in a DB_JOB workload object. For more information, see “DB_JOB Statement: Identify the Name of Database Jobs” on page 245.

ApplicabilityESP System Agents, Release 6, used within a DB_JOB workload object. For more information, see “DB_JOB Statement: Identify the Name of Database Jobs” on page 245.

SyntaxSQL SQLQuery

Usage notesSQL is an alternative form of QUERY. Refer to “QUERY Statement: Specify SQL Statement Within DB_JOB” on page 1011.To use the SQL statement, you must have knowledge of how to construct an SQL query.Note: There is no spool file created if CREATE, DELETE, UPDATE, INSERT, or

DROP are used in the DB_JOB.

ExamplesExample 1DB_JOB DBJOB1.STMNT AGENT R6AGENT USER sapr3 DSN oracle:thin:@gamax:1527:cyb SQL 'SELECT JOBNAME FROM TBTCO' RUN DAILY RELEASE DBTEST2ENDJOB

Operand DescriptionSQLQuery The query can contain any SQL statement including SELECT,

DELETE, UPDATE, or INSERT.

1199

Example 2DB_JOB DBJOB2.STMNT AGENT R6AGENT USER user1 DSN oracle:thin:@gamax:1527:cyb SQL 'SELECT COUNT (*) FROM TBTCO WHERE JOBNAME LIKE ''SD%'' + AND ENDDATE = ''20030813''' RUN DAILYENDJOB

Example 3DB_JOB DBJOB3.STMNT AGENT R6AGENT USER db2admin DSN db2://10.1.1.46:50000/sample SQL 'SELECT COUNT(*) FROM STAFF WHERE NAME LIKE ''L%''' DESTINATION '/export/home/qatest/db_job_data/test14.bd2' RUN DAILYENDJOB

Note: For a Windows example, substitute a Windows path in the DESTINATION statement.

STARTMODE Statement: Specify Startmode for Readied Job (SAP)

1200

STARTMODE Statement: Specify Startmode for Readied Job (SAP)

The STARTMODE statement specifies the action to take when the job is readied on the SAP system.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax STARTMODE N|I|A

Usage notesUse the STARTMODE statement within the boundaries of the job definition.

ExampleIn this example, the job is released immediately.APPL SAPTEST SAP_JOB SAPTEST AGENT SAPHTAGENT STARTMODE I RUN DAILY ABAPNAME BTCTEST VARIANT TEST SAPTARGETSYSTEM tst005ENDJOB

Operand DescriptionN Default. Specifies the SAP job is defined but not released.

Note: The startmode of N requires a manual process to release the job. Use the WSA or WSI line commands either in CSF or through the SAPGUI to submit STARTMODE N. When the job is released, the Agent detects the change of status and displays it in the CSF.

For more information on the W command, see “Issuing Commands to Use Workload Manager Features” on page 132.

I Specifies the SAP job is defined and is released immediately. If no free background processing is available, the job is not released and stays in the Scheduled SAP job state.

A Specifies the SAP job is defined and released as soon as possible.

1201

STATINTV Statement: Set Status Check Interval

The STATINTV statement sets the time interval between Agent status checks. It is used in conjunction with the AGENT_MONITOR statement.

TypeESP Workload Manager Application Statement

SyntaxSTATINTV mins

Example In the following example, AGENT_MONITOR TORONTO will perform status checks on Agent CYBNT1. The status checks will occur every 5 minutes and the object will store 10 messages.APPL AGENTMON

AGENT_MONITOR TORONTO STATINTV 5 MSGQLEN 10 AGENT CYBNT1ENDJOB

Operand DescriptionSTATINTV mins Sets the time interval in minutes that will pass between Agent status

checks. The default is 0. This indicates no checks will be performed.

STATUS Command: Display Processing Status

1202

STATUS Command: Display Processing Status

The STATUS command is used to display the current ESP processing status.

TypeGeneral command.

AuthorityYou require OPER authority to issue the STATUS command.

Syntax{STATUS|ST}

Usage notesThe STATUS command displays the following information:• The current ESP release number.• Whether ESP is quiesced or active.• Whether data set triggering is suspended or active.• The names of any suspended Event data sets.

Example Display produced by STATUS commandIn the following example, the current release of ESP is 5.1.0, ESP is active, data set triggering is active, and there are not suspended Event data sets.OPER STATUSESP1977I ESP RELEASE 5.1.0.000 STATUSESP1978I EVENT SCHEDULING ACTIVEESP1979I DATASET TRIGGERING ACTIVE

1203

STATUS Statement: Specify Status of Process (PROCESS_MON), Service (SERVICE_MON), or IP Address and Port (IP_MON)

The STATUS statement specifies the status of an item that can be a process, service, or IP address/port that is monitored.

ApplicabilityESP System Agents, Release 6, used within any of the following workload objects:• “IP_MON Statement: Monitor IP Addresses or Ports” on page 684• “PROCESS_MON Statement: Monitor Process Execution” on page 986• “SERVICE_MON Statement: Monitor Windows Services” on page 1161

(Windows only)Note: Unless otherwise specified, each operand listed under Syntax below applies to

all workload objects listed above.

SyntaxSTATUS [(RUNNING|STOPPED|CONTINUE_PENDING|PAUSE_PENDING|PAUSED| START_PENDING|STOP_PENDING|EXISTS|NOTEXISTS)][(NOW|WAIT)]

Usage notesOn UNIX, you can only specify the RUNNING, STOPPED, NOW, and WAIT operands.

Operand DescriptionRUNNING The monitored item is running.STOPPED The monitored item is stopped.CONTINUE_PENDING For SERVICE_MON only. The monitored item is in continue

pending state.PAUSE_PENDING For SERVICE_MON only. The monitored item is in pause pending

state.START_PENDING For SERVICE_MON only. The monitored item is starting.STOP_PENDING For SERVICE_MON only. The monitored item is stopping.EXISTS For SERVICE_MON only. The monitored item exists. NOTEXISTS For SERVICE_MON only. The monitored item does not exist.NOW Return status immediately.WAIT Wait for process to reach the specified status.

STATUS Statement: Specify Status of Process (PROCESS_MON), Service (SERVICE_MON), or IP Address and Port(IP_MON)

1204

Examples

PROCESS_MON statement examplesExample 1PROCESS_MON completes successfully if process Bayuser is not running.PROCESS_MON PROCESS.STOPPED AGENT R6AGENT PROCESS Bayuser STATUS STOPPED NOW RUN DAILYENDJOB

Example 2Process monitor completes successfully after the process nlnotes is started and running.PROCESS_MON NLNOTES.SUCCESS AGENT R6AGENT PROCESS nlnotes STATUS RUNNING WAIT RUN DAILYENDJOB

Example 3In this example, the monitored process is cybAgent.exe. When the STATUS statement conditions are met (process is RUNNING NOW), the jobs listed in the RELEASE statement will be released for execution. Note: If there are spaces in the path, use single quotes.PROCESS_MON PROCESS2.STMNT AGENT R6AGENT PROCESS 'c:\Program files\cybermation\ESP System Agent R6\+ cybAgent.exe' STATUS RUNNING NOW RELEASE (PRPATH.JOB1, PRPATH.JOB2) RUN DAILYENDJOB

Note: For a UNIX example, substitute a UNIX path in the PROCESS statement.

1205

IP_MON statement exampleIn this example, the job checks to see if the server with this IP address and port is RUNNING NOW.IP_MON IPMON.STMNT RUN DAILY AGENT R6AGENT IPADDRESS 111.11.11.111 IPPORT 22 STATUS RUNNING NOWENDJOB

SERVICE_MON statement example (Windows)In this example, the service ESPEspresso is monitored until (operand WAIT) a status of RUNNING occurs.SERVICE_MON STATUS1.STMNT AGENT R6AGENT SERVICENAME ESPEspresso STATUS RUNNING WAIT RUN DAILYENDJOB

STEPEND Statement: Release Resources at End of Step

1206

STEPEND Statement: Release Resources at End of Step

The STEPEND statement is used to release resources back to the resource pool at job step-end. You may release part or all of the resources back to the resource pool. The STEPEND statement is coded within the scope of the job statement. You can have more than one STEPEND statement in one job.

TypeESP Application statement.

SyntaxSTEPEND STEPNAME(stepname) PROCSTEP(procstep) –

RELRES(n1,resname1,n2,resname2, …)

Resource typesStep-level resource release is available for renewable resources only.Note: Step-level resource release only works if USERMOD 11 is off. When

USERMOD 11 is on, the Application Manager does not get step-end notification.

Examples Releasing one unit of a resourceThe following example shows releasing one unit of a resource after STEP1, PROCA:APPL ONEJCLLIB 'CYBER.JCLLIB.CNTL'JOB JOBA RUN DAILY RESOURCE (6,T3480) STEPEND STEPNAME(STEP1) PROCSTEP(PROCA) - RELRES(1,T3480)ENDJOB

Operand Descriptionstepname Indicates the name of the job step.procstep Indicates the name of the proc step.n1,resname Indicates the quantity and name of the resource to be released.

1207

Releasing two more units of the same resourceThe following example shows releasing two more units of the same resource later in the same job:APPL ONEJCLLIB 'CYBER.JCLLIB.CNTL'JOB JOBA RUN DAILY RESOURCE (5,T3480) STEPEND STEPNAME(STEP3) PROCSTEP(PROCB) - RELRES(2,T3480)ENDJOB

Ensure the stepnames and procsteps you specify match your JCL exactly. You can release resources by specifying just a procstep and not a stepname, if that is how your JCL is tailored.

STEPUSER Statement: Specify User for ABAP Program (SAP)

1208

STEPUSER Statement: Specify User for ABAP Program (SAP)

The STEPUSER statement specifies the user under whose authorization the ABAP program runs.

ApplicabilityESP Business Agents for SAP, Version 2.0 and higher.

Syntax STEPUSER user_name

Usage notesUse the STEPUSER statement before the first ABAPNAME statement to set the default value for subsequent steps.If the SAPUSER statement has been specified at the job level, STEPUSER will override that specification. For more information on the SAPUSER statement, see “SAPUSER Statement: Specify RFC Logon for SAP System User” on page 1131.Use the STEPUSER statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleIn this example, ABAP BTCTEST will run under the authority of user ID USER14. APPL SAPTEST SAP_JOB SAPTEST AGENT SAPHTAGENT STARTMODE I RUN DAILY ABAPNAME BTCTEST STEPUSER user14 VARIANT TEST SAPTARGETSYSTEM tst005ENDJOB

Operand Descriptionuser_name Specifies the name of the user under whose authorization the

ABAP program runs. user_name can be up to 16 valid SAP characters in length.

1209

subAgent Command: Start in Debug Mode

The subAgent command is used to start the agent for Windows NT in debug mode. It is issued from the command prompt of Windows NT.

TypeGeneral command

Syntax subAgent -debug

Usage notesDo the following to start the agent in debug mode:1. Click Start, Programs, Command Prompt.2. Enter the following command:

subAgent -debug

Operand Description/binPath/ applies to NT Agents only. Specifies the path to the directory

containing the cybAgent binary.-debug Starts the agent in debug mode.

SUBAPPL Statement: Identify SubApplications

1210

SUBAPPL Statement: Identify SubApplications

The SUBAPPL statement is used to identify the logical name of a subApplication within an Application. Choose a subApplication name different than that of any jobname within the Application.

SyntaxSUBAPPL subapplid [WAIT|NOWAIT]

Usage notesYou may choose to use a subApplication to:• Break up a large Application into smaller groups of jobs• Combine smaller Applications into one common Application and use

subApplications to group related jobs together. This may alleviate the need for establishing inter-Application relationships, that is, EXTERNAL jobs.

Using a subApplication allows you to:• Display and manipulate all jobs in a subApplication using a single command.• Select or deselect all jobs in a subApplication using a single command.• Use the CSF to filter based on the subApplication.• Control concurrent processing of different generations of the same

subApplication.• Report on subApplications.You can use the SUBAPPL statement at a global level or at a job level. A job level setting overrides a global setting.

Operand Descriptionsubapplid Indicates a subApplication identifier up to eight-character long.

Characters must be either alphanumeric, a national character ($ # @), or an underscore (_). The first character cannot be numeric. The name of the subApplication must be different from any job within the Application.

WAIT Indicates concurrent processing of different generations of the same subApplication is not permitted. ESP ensures that a subApplication waits for the previous generation of the same subApplication to complete. This can be specified at the Application or the sub-Application level.

NOWAIT Indicates concurrent processing of different generations of the same subApplication is permitted. This is the default.

1211

You can select jobs within a subApplication by selecting each job or the subApplication.

Related informationFor information on Applications and subApplications, see the ESP Workload Manager User’s Guide.For information on manipulating subApplications using the CSF, see the ESP Workload Manager User’s Guide. For information on reporting on subApplications, see the ESP Workload Manager User’s Guide.For information on selecting or deselecting entire subApplications, see the SELECT and DESELECT statements.For information on manipulating jobs within Applications and sub-Applications, see the APPLJOB or AJ command.

Examples Identify sub-ApplicationIn the following example, MYJOB is identified as belonging to the PREPJOBS subApplication.JOB MYJOB SUBAPPL PREPJOBSENDJOB

SUBAPPL statements identify a subApplicationIn the following example:• PAYJOB1 and PAYJOB2 are grouped together into the ACCTPAY

subApplication. Each generation of the ACCTPAY subApplication must wait for the previous generation to complete.

• RECJOB1 and RECJOB2 are grouped together into the ACCTREC subApplication. Different generations of the ACCTREV subApplication can process at the same time.

APPL PAYROLLJCLLIB 'CYB.PROD.JCL'JOB PAYJOB1 SUBAPPL ACCTPAY WAITJOB PAYJOB2 SUBAPPL ACCTPAY JOB RECJOB1 SUBAPPL ACCTREC JOB RECJOB2 SUBAPPL ACCTREC ENDJOBSELECT (ACCTPAY,ACCTREC) SUBAPPL

SUBAPPL Statement: Identify SubApplications

1212

SUBAPPL statements identify a subApplicationIn the following example:• PAYJOB1 and PAYJOB2 are grouped together into the ACCTPAY

subApplication. Different generations of the ACCTPAY subApplication can process at the same time.

• BILLJOB1 and BILLJOB2 are grouped together into the BILLING subApplication. Different generations of the BILLING subApplication can process at the same time.

APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'

SUBAPPL ACCTPAY WAITJOB PAYJOB1JOB PAYJOB2ENDJOBSUBAPPL BILLINGJOB BILLJOB1JOB BILLJOB2ENDJOB

SUBAPPL statements identify jobs for subApplicationsIn the following example:• REGJOB1 and REGJOB2 are grouped together into the REGULAR

subApplication• SPECJOB1 and SPECJOB2 are grouped together into the SPECIAL

subApplication. Each job in the SPECIAL subApplication is identified as on request jobs, for example, they may or may not run.

• PAYJOB1 and PAYJOB99 do not belong to a subApplication. • PAYJOB1 has a delayed submission time of 10 pm.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 DELAYSUB 10PM RUN DAILY REL (REGJOB1,SPECJOB1)ENDJOBJOB REGJOB1 SUBAPPL REGULAR RUN DAILY REL REGJOB2ENDJOBJOB REGJOB2 SUBAPPL REGULAR

1213

RUN DAILY REL PAYJOB99ENDJOBJOB SPECJOB1 REQUEST SUBAPPL SPECIAL RUN DAILY REL SPECJOB2ENDJOBJOB SPECJOB2 REQUEST SUBAPPL SPECIAL RUN DAILY REL PAYJOB99ENDJOBJOB PAYJOB99 RUN DAILYENDJOB

Note: If this Application is triggered early in the day, it provides the opportunity to request jobs within the SPECIAL subApplication prior to 10 pm.

Invokes four separate members each containing a subApplicationIn the following example, the PAYROLL Application consists of: • An APPL statement identifying the name of the Application• A JCLLIB statement telling ESP where to find each job’s execution JCL • Four INVOKE statements identifying the subApplications comprising the

PAYROLL Application.APPL PAYROLLJCLLIB 'CYBER.JCLLIB.CNTL'INVOKE 'CYBER.PROCS.CNTL(ACCPAY)'INVOKE 'CYBER.PROCS.CNTL(ACCREC)'INVOKE 'CYBER.PROCS.CNTL(BILLING)'INVOKE 'CYBER.PROCS.CNTL(REPORTS)'

The following are examples of the invoked members: SUBAPPL ACCPAYJOB ACCJOB1…JOB ACCJOB99

SUBAPPL ACCRECJOB RECJOB1…JOB RECJOB99

SUBAPPL Statement: Identify SubApplications

1214

SUBAPPL BILLINGJOB BILJOB1…JOB BILJOB99

SUBAPPL REPORTSJOB RPTJOB1…JOB RPTJOB99

Note: This method of subApplication organization is not required, but may provide an option when an Application contains many subApplications, with each subApplication containing many jobs.

1215

SUBMIT Command: Submit JCL Into Internal Reader

The SUBMIT command is used to submit JCL into the internal reader.

TypeEvent definition command.

Syntax{SUBMIT|SUB} 'dsname[(member)]' [GENERATION(genno)] [LEVEL{(levelname[,levelname]...)|(*)}]

Usage notesA single Event can submit more than one job. If there are relationships between the jobs you are submitting, you must use an Application, not an Event to submit them.The SUBMIT command may also be issued from an ESP Procedure.Multiple members of a PDS may be submitted with one SUBMIT command. Specify member names in full or by generic level. You can also request all members of a PDS be submitted by specifying “LEVEL(*)”. Note that when using the LEVEL keyword, members of the PDS are read in alphabetical sequence by member name.A data set (including a PDS) that is part of a GDG can also be used as a source for JCL. Use the GENERATION keyword to specify the relative generation number. This number must be zero or negative.

Related informationFor information on submitting JCL from an Event, see the ESP Workload Manager User’s Guide.

Operand Descriptiondsname Indicates a valid data set name. The current user prefix is added if the

data set name is not enclosed within quotes. You can include a member name within the data set specification.

genno Indicates a generation number for a generation data group (GDG). It must be zero or a negative number.

levelname Indicates a one to eight character string, or an asterisk. A list of level names, separated by blanks or commas, can be specified.

* Indicates all members are to be submitted, in alphabetical sequence, by member name.

SUBMIT Command: Submit JCL Into Internal Reader

1216

Examples 9 am on the first Monday of the monthIn the following example, PAYJOB1 is submitted at 9 am on the first Monday of the month from CYBER.JCL.CNTL.EVENT ID(CYBER.PAYJOB1)SCHEDULE 9AM FIRST MONDAY OF MONTHSUBMIT 'CYBER.JCL.CNTL(PAYJOB1)'ENDDEF

10 am on the last day of the monthIn the following example, PAYJOB2 and PAYJOB3 are submitted at 10 am on the last day of the month from CYBER.JCL.CNTL.EVENT ID(CYBER.PAYJOBS)SCHEDULE 10AM LAST DAY OF MONTHSUBMIT 'CYBER.JCL.CNTL(PAYJOB2)'SUBMIT 'CYBER.JCL.CNTL(PAYJOB3)'ENDDEF

8 pm on MondaysIn the following example, all members of CYBER.JCL.CNTL are submitted at 8 pm Mondays.EVENT ID(CYBER.ALLJOBS)SCHEDULE 8PM MONDAYSUBMIT 'CYBER.JCL.CNTL' LEVEL(*)ENDDEF

All members that start with A or BP are submitted at 9 pm on MondaysIn the following example, all members that start with A or BP are submitted at 9 pm on Mondays from CYBER.JCL.CNTL.EVENT ID(CYBER.ALLJOBS)SCHEDULE 9PM MONDAYSUBMIT 'CYBER.JCL.CNTL' LEVEL(A-,BP-)ENDDEF

Used with a built in function in an ESP Procedure to submit JCLIn the following example, if today is not the last day of the month, ESP submits PAYJOB4 from CYB.JCL.CNTL.IF TODAY('NOT LAST DAY OF MONTH') THEN - SUBMIT 'CYBER.JCL.CNTL(PAYJOB4)'

1217

SUCCESSMSG Statement: Specify Success Message for ABAP(SAP)

The SUCCESSMSG statement specifies a string that, when found in the condition output of an SAP step (ABAP), indicates the success of the ABAP.

ApplicabilityESP Business Agents for SAP, Release 4 and higher.

Syntax SUCCESSMSG 'SuccessMessageString'

Usage notesUse the SUCCESSMSG statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the SUCCESSMSG statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.

ExampleIn this example, even if the SAP job fails (return code value ’E’), Workload Manager will treat the step (ABAP BTCTEST) as successful if the string ’Program Selections’ is found in the ABAP spool output.APPL SAPTEST SAP_JOB SAPTEST AGENT SAPHTAGENT STARTMODE I RUN DAILY ABAPNAME BTCTEST STEPUSER user14 VARIANT TEST SUCCESSMSG 'Program Selections'ENDJOB

Operand DescriptionSuccessMessageString The string that must match the SAP ABAP output for the step to

be considered successful. SuccessMessageString is case sensitive and can be up to 128 valid SAP characters. SuccessMessageString must be enclosed in single quotes.

SUN_JOB Statement: Identify the Name of SUN Jobs

1218

SUN_JOB Statement: Identify the Name of SUN Jobs

The SUN_JOB statement is used to identify the name of a SUN job in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use ASUNIX jobs, you must load a workload object module. The SUN_JOB workload object module is CYBESOSJ. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Refer to the JOB statement usage notes.

Example:SUN_JOB PAYDATA RUN DAILY RELEASE PAYRPT AGENT SUNX_NY SCRIPTNAME /usr/data/payENDJOB

1219

SUSPEND Command - Event Level: Suspend Events

When used in an Event definition, the SUSPEND command increments the suspend count of the Event. While the suspend count is greater than zero, Event execution is bypassed.

TypeEvent definition command.

SyntaxSUSPEND criteria

Usage notesThe RESUME command is used in conjunction with the SUSPEND command to make a previously bypassed Event eligible for execution.If you are using a time zone on your SUSPEND command, you should use the same time zone on your RESUME command. If the Event has a schedule statement, the same time zone should be used on the SCHEDULE, SUSPEND, and RESUME commands.Note: The RELEASE command is used in conjunction with the HOLD command to

make a previously postponed Event eligible for execution.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.For information on holding or releasing an Event’s execution, see the HOLD and RELEASE commands.For information on decrementing an Event’s suspend count that was previously incremented using the SUSPEND command, see the RESUME command.

Operand Description

criteria Schedule criteria that resolve to a single date and time.

SUSPEND Command - Event Level: Suspend Events

1220

Examples Prevent submission between 9 am and 11 amIn the following example, SUSPEND and RESUME commands are used to prevent PAYJOB1 from being submitted between 9 am and 11 am. If the data set trigger happens between these times, ESP ignores it. EVENT ID(CYBER.PAYROLL1) DSTRIG PAYROLL.INPUTSUSPEND DAILY AT 9AMRESUME DAILY AT 11AMSUBMIT 'CYBER.JCL.CNTL(PAYJOB1)'ENDDEF

Suspend Event each workdayIn the following example, SUSPEND and RESUME commands are used to limit the sending of a message to each hour between 8 am and 4 pm on workdays. EVENT ID(CYBER.TIMEMSG)SCHEDULE WORKDAYS HOURLY ROUND STARTING TODAYSEND 'THE TIME IS %ESPATIME' U(CYB01) SUSPEND 16:01 WORKDAYSRESUME 7:59 WORKDAYSENDDEF

Suspend Event once

In the following example, SUSPEND and RESUME commands are used to bypass the Event between 8 pm and 10 pm Pacific Standard Time, on March 2, 1998 only.EVENT ID(CYBER.PAYROLL2)SCHEDULE 9PM PST WORKDAYS SUSPEND 8PM PST MARCH 2,1998 ONCE RESUME 10PM PST MARCH 2,1998 ONCE SUBMIT 'CYBER.JCL.CNTL(PAYJOB2)'ENDDEF

1221

SUSPEND Command - General: Suspend Events

When used outside an Event definition, the SUSPEND command increments the suspend count associated with an Event. When the suspend count is greater than zero, event execution is bypassed.

TypeGeneral command.

SyntaxSUSPEND eventid

Usage notesThe specified Event has its SUSPEND count incremented immediately.The RESUME command is used in conjunction with the SUSPEND command to make a previously bypassed Event eligible for execution.The RELEASE command is used in conjunction with the HOLD command to make a previously postponed Event eligible for execution.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.For information on incrementing on holding or releasing an Event’s execution, see the HOLD and RELEASE commands.

For information on decrementing an Event’s suspend count that was previously incremented using the SUSPEND command, see the RESUME command.

ExampleIn the following example, CYBER.PAYROLL is suspended and not eligible for execution.SUSPEND CYBER.PAYROLL

Operand Description

eventid Indicates a valid Event name. If no prefix is specified, the current prefix as set by the GROUP command is used.

SYMLIB Command: Request Inclusions

1222

SYMLIB Command: Request Inclusions

The SYMLIB command is used to request the inclusion of one or more symbolic variable libraries

Type Event definition command.

Syntax{SYMLIB|SYM} {symname} {symname[,symname]...}

Usage notesThe SYMLIB command requests the inclusion of any number of symbolic variable libraries as defined with the DEFSYML command. A symbolic variable library is a collection of sequential data sets or members or partitioned data sets. Each Event can request one or more symbol libraries.If the same symbol is defined in more than one symbol library referenced in an Event, the last value of the symbol is used.

Related informationFor information on setting symbol libraries, see the ESP Workload Manager User’s Guide.For information on invoking user symbolic variables, see the ESP Workload Manager Advanced User’s Guide.For information on defining a symbol library, see the DEFSYML command.For information on displaying information about symbol libraries, see the LISTSYML command.

Operand Descriptionsymname Indicates the name of an existing SYMLIB of up to eight characters.

You can specify several names by enclosing the list within parentheses and separating each item with a blank or comma.

1223

Examples References a symbolic variable libraryIn the following example, when ESP processes CYBER.PAYROLL1, it opens the data set associated with DATES and uses this information to perform symbolic variable substitution. EVENT ID(CYBER.PAYROLL1) SYMLIB DATES INVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

Note: These same results can be accomplished by invoking an ESP Procedure that stores symbolic variables, as follows:

EVENT ID(CYBER.PAYROLL1)INVOKE 'CYBER.PROCS.CNTL(PAYROLL)'INVOKE 'CYBER.SYMBOLS.CNTL(DATES)'ENDDEF

References two symbolic variable librariesIn the following example, when ESP processes CYBER.PAYROLL2, it opens the data sets associated with MDATES and PDATES and uses this information to perform symbolic variable substitution.EVENT ID(CYBER.PAYROLL2) SYMLIB MDATES PDATES INVOKE 'CYBER.PROCS.CNTL(PAYROLL)'ENDDEF

SYSMSGS Command: Intercept Messages

1224

SYSMSGS Command: Intercept Messages

ESP Workload Manager can intercept any message while it is being written to the JES system message dataset belonging to an individual JOB STC or TSU.The JES system message dataset constitutes the jobs log, containing JES messages about the job's processing, allocations, job/step statistics, and dataset disposition. The JES system message dataset (JESYSMSG) is subject to installation parameters that can effect content and creation.ESP Workload Manager does not intercept data written to other JES data sets, the data sets belonging to the operating system (for example, SYSLOG), or console messages.Use ESP Workload Manager to cancel a job, fail a job, trigger an Event, or issue a WTO message when a specific message is intercepted.

AuthorityYou require OPER authority to issue the SYSMSGS command.

SyntaxSYSMSGS ['text] [DISABLE|ENABLE|IGNORE] [CANCEL|CCFAIL|JCLERROR|WARN] [TSU] [STC] [ID(xxxx)] [COL(nn[:nn])] [NAME(jobname[,jobname]...) [EVENT(eventid)] [COUNT(m)] [ROUTE(rcode)] [DESC(dcode)] [JOBNAME] [WTO] [COMPRESS]

Operand Descriptiontext Indicates the part of the message text that defines the message you want

intercepted. This can be a message identifier, a prefix or any part of the message text. This operand must not be specified if the DISABLE, ENABLE, or IGNORE keywords are specified. However, it must be specified if these keywords are not specified. The maximum length of this field is 32 bytes.

DISABLE Temporarily suspends an existing entry for the specified message ID and prevents its interception. Note that the ID operand must be specified and no other operand may be specified, including the message text.

1225

ENABLE Re-enables a suspended entry for the specified message ID. Note that the ID operand must be specified and no other operand may be specified, including the message text.

IGNORE Invalidates and deletes an existing entry for the specified message ID and prevents its interception. Note that the ID operand must be specified and no other operand may be specified, including the message text.

CANCEL Indicates interception of this message text should generate a z/OS cancellation of the job (system abend code 222).

CCFAIL Indicates interception of this message should cause a condition code failure.

JCLERROR Indicates interception of this message should cause a JCL error.

WARN Indicates ESP generates a warning message when this message is intercepted. The messages are displayed when an LTJ command is issued for the job that issued the message. Note that no action takes place with this option, only a warning message is issued.

TSU Indicates interception of this message should only occur for time sharing users (TSUs).

STC Indicates interception of this message should only occur for started tasks (STCs).

ID(xxxx) Indicates an identifier consisting of four alphanumeric characters. You can assign an ID when you define SYSMSGS, else ESP assigns the next available sequential number. The identifier controls the order of search when ESP is tracking system messages. It must be used with DISABLE, ENABLE, and IGNORE.

nn Indicates a column or range of columns where the specified message text should begin. The default is column one.

jobname Indicates up to four jobnames (or jobname strings), thus limiting the system message interception for a particular job, or set of jobs.

eventid Indicates the Event to be triggered when the system message is intercepted. EVENT can be abbreviated as EV.

m Indicates the Event is to be scheduled for every m interceptions of the system message, where m is a number from 0 to 255. A value of zero results in a schedule for each interception, as does a value of one. It defaults to one.

rcode Indicates the routing code that identifies the console to which this message should be sent. If it is omitted, the default routing code is two.

dcode Indicates the descriptor code that is to apply to this message. If it is omitted, the default descriptor code is six. Use DESC(2) for a non-deletable message.

JOBNAME Indicates the job name should be embedded within the message when it is rebroadcast on the console.

WTO Indicates the message should be rebroadcast as a WTO message.

Operand Description

SYSMSGS Command: Intercept Messages

1226

Usage notesThis command causes failure of a job or the triggering of an Event, through the interception of pre-defined message ID or message text. The message can be issued from a console or from an authorized terminal, and routed to any specified console. Ensure that the 'SYSMSGS' operand is first specified with the TRACKOPT command or ESP initialization parameter. If TRACKOPT SYSMSGS is not specified, system messages are not intercepted.The message text must not be specified for the DISABLE, ENABLE or IGNORE operands. These operands require that the ID operand also be specified and no other operands are allowed. SYSMSGS must be specified on the system that does the tracking. If ESP is tracking on the master, enter this on the master. If ESP is tracking on the proxy, enter this on the proxy. TRACKOPT SYSMSGS must also be specified on the tracking system.When the SYSMSGS command is first used to identify message interception, it takes effect immediately. Use the ENABLE operand only after a SYSMSGS ID has been disabled.

Related informationFor information on clearing system message interceptions, see the CLRSYSMS command.For information on displaying information on all system messages that are currently intercepted by ESP, see the LSYSMSGS command.

Examples In the following example, whenever a NOT CATLGD system message is generated starting anywhere between columns 50 and 60, cancel the job and embed the jobname when the message is rebroadcast as a WTO.SYSMSGS 'NOT CATLGD' COL(50:60) CANCEL WTO JOBNAME

In the following example, whenever an IEF142I system message is generated for PAYJOB1, trigger Event CYBER.PAYSTEP.SYSMSGS 'IEF142I' NAME(PAYJOB1) EVENT(CYBER.PAYSTEP)

Intercept system messages - multiple conditionsIn the following example, whenever an IEF253I system message is generated for jobs with two character names beginning with J or K, cancel the job and trigger Event CYBER.CAN. Highlight the message using descriptor code two. Assign an ID of 0010 to this system message interception.SYSMSGS 'IEF253I' ID(0010) NAME(J-,K-) CANCEL - EV(CYBER.CAN) DESC(2)

COMPRESS Indicates extra blanks are to be removed from the text.Operand Description

1227

Ignore system message interceptionIn the following example, all message system interception processing for system message ID 0023 is ignored.SYSMSGS IGNORE ID(0023)

Disable message interceptionIn the following example, all system message interception processing for system message ID 0002 is disabled.SYSMSGS DISABLE ID(0002)

Enable message interceptionIn the following example, all system message interception processing for system message ID 0002 is enabled.SYSMSGS ENABLE ID(0002)

System message interception - warningIn the following example, whenever 99 IEC161I system messages have been generated for jobnames beginning with UT, a warning message is issued.SYSMSGS 'IEC161I' NAME(UT-) WARN COUNT(99)

TAG Statement: Tag Jobs

1228

TTAG Statement: Tag Jobs

The TAG statement is used to tag jobs in an Application with a character string up to 16 characters in length. The TAG statement can be job specific or can apply to all jobs in an Application.

SyntaxTAG 'string'

Usage notesUsing the TAG statement allows you to:• Filter jobs with a common characteristic using the CSF• Pass information to JCL using the %ESPAPTAG symbolic variable.

Related informationFor information on Applications, see the ESP Workload Manager User’s Guide.For information on the CSF, see the ESP Workload Manager User’s Guide.

Examples In the following example, PAYJOB1 is tagged with the character string CRITICAL JOB.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 TAG 'CRITICAL JOB' RUN WORKDAYSENDJOB

Operand Descriptionstring Indicates a character string in up to 16 characters. If the string

contains separator characters (comma or blanks), enclose it within quotes. This string may contain ESP symbolic variables.

1229

In the following example, a symbolic variable is used to tag all jobs in the PAYROLL Application with the three-character day of the week name (for example, MON for Monday).APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'TAG '%ESPSDAY(1:3)'JOB PAYJOB2 RUN WORKDAYS REL PAYJOB3JOB PAYJOB3 RUN WORKDAYS REL PAYJOB4JOB PAYJOB4 RUN WORKDAYSENDJOB

Associates a character string with a jobJOB PAYJOB5 TAG IMPORTANTENDJOB

Associates a character string with a jobJOB PAYJOB6 TAG 'TIME 18:00'ENDJOB

Associates a character string with a jobJOB PAYJOB7 TAG 'DIVISION 123'ENDJOB

TANDEM_JOB Statement: Identify the Name of Tandem Jobs

1230

TANDEM_JOB Statement: Identify the Name of Tandem Jobs

The TANDEM_JOB statement is used to identify the name of a Tandem job in an Application.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use Tandem jobs, you must load a workload object module. The TANDEM_JOB workload object module is CYBESOTA. This may be loaded with the WOBDEF command or with the WOBDEF initialization parameter.Refer to the JOB statement usage notes.

Example:The following is an example of an Tandem JOB statement:Tandem_JOB payroll2.paypgm

1231

TAPETRAK Command: Tape usage count control

The TAPETRAK command permits ESP Workload Manager to determine which tape devices should be included in a job’s tape-device-usage count by determining the largest number of tape devices used in any one single step. The average tape-device-usage count for a job is recorded in the ESP Workload Manager history file and used by ESP Workload Manager to estimate a job's tape-device requirements when tape devices are defined as a default resource. If a job's estimated tape-device requirements are not met, ESP Workload Manager puts the job into a resource wait, and only proceeds with job submission when the tape-device requirements are met.You can use the TAPETRAK command to include or exclude any tape device, real or virtual. If you use a tape management system such as IBM VTS (Virtual Tape System) where ESP Workload Manager can detect automatically the virtual devices, you can use the REAL or NOVIRTUAL operand to exclude all virtual devices. If you use a tape management system such as StorageTek's VSM (Virtual Storage System) where ESP Workload Manager cannot detect automatically the virtual devices, you must use the EXCLUDE operand to exclude any devices.Note: Tape devices also means cartridge devices.

TypeOPER command.

AuthorityOPER authority.

SyntaxTAPETRAK [ALL|REAL|NOVIRTUAL|LIST|HELP] [EXCLUDE(X'nnnn'[:X'nnnn'] …)|NOEXCLUDE]

Note: In page and line mode, the only operands available are LIST and HELP.

Operand DescriptionALL Specifies that all tapes (both real and virtual) are to be included in

a job step’s tape-device-usage count. This is the initial default.REAL Specifies that real tape devices are to be included in, and virtual

tape devices are to be excluded from, a job step’s tape-device-usage count.

NOVIRTUAL Specifies that real tape devices are to be included in, and virtual tape devices are to be excluded from, a job step’s tape-device-usage count.

Note: NOVIRTUAL is an alias of REAL.

TAPETRAK Command: Tape usage count control

1232

Usage notesTAPETRAK may also be specified as an initialization parameter.The TAPETRAK command is only valid for tracking ESP Workload Manager subsystems, that is an ESP Workload Manager subsystem that specifies SMFINT ON in the ESPPARM member of the initialization parameter data set, or defaults to SMFINT ON.You may issue the TAPETRAK command from TSO/ISPF page mode or from an ESP Workload Manager line mode interface if you want to use only the LIST and HELP operands. To use all other operands, you must issue TAPETRAK as a z/OS MODIFY command.When you issue the TAPETRAK HELP command in TSO/ISPF page mode or from ESP Workload Manager line mode interface, ESP Workload Manager displays only the TAPETRAK command options available for that source.You may use the EXCLUDE operand to exclude any device. However, it is only meaningful when you specify tape devices.

LIST Requests a display of ESP Workload Manager current tape tracking status. This is the default when TAPETRAK is issued without operands.

HELP Displays the TAPETRAK command options.EXCLUDE Specifies the device numbers of the tape devices that must be

excluded from a job tape-device-usage count.You can exclude:

• Single devices: X'nnnn'• Ranges of devices: X'nnnn':X'nnnn'Separate the device addresses or the range of device addresses with a space.

Note: If you enter multiple TAPETRAK EXCLUDE commands, ESP Workload Manager will validate only the last command. To exclude multiple devices at the same time, you must specify them in one single command.

NOEXCLUDE Specifies that no tape devices are to be explicitly excluded from a job tape-device-usage count. Use this operand to reverse a previous TAPETRAK command containing the EXCLUDE operand.

Operand Description

1233

If EXCLUDE tape device number ranges overlap, they will be merged.For example:F ESP,TAPETRAK EXCLUDE(X'580':X'58B' X'584':X'58F')

will be treated as F ESP,TAPETRAK EXCLUDE(X'580':X'58F').

When you issue an LJ command, you see the number of tape devices used by a tracked job in the #T field of the display.

Related InformationSee the “Using real devices” section of the ESP Workload Manager User’s Guide for information about specifying tape drive resources.

Examples Your installation with IBM VTS wants to exclude virtual tape devices from a job step's tape-device-usage count. Issue the following command:F ESP,TAPETRAK REAL

Your installation with StorageTek's VSM wants to exclude virtual tape devices from a job step's tape usage count. Their virtual tape device numbers are 0580-058F and 0780-078F. Issue the following command:F ESP,TAPETRAK EXCLUDE(X'580':X'58F' X'780':X'78F')

To display the current ESP Workload Manager tape tracking status, issue the following command:OPER TAPETRAK

TEMPLATE Statement: Set Templates

1234

TEMPLATE Statement: Set Templates

The TEMPLATE statement is used to name a template and identify any operands and variables available during template processing.

SyntaxTEMPLATE name ([posct] [parms...]) [LOCALVARIABLES|GLOBALVARIABLES]

Usage notesOnce you use the TEMPLATE statement, specify the statements you want to process each time the template is used. End the template with the ENDTEMPL statement. To use a template, specify its name and identify the operands you are passing to it.Template processing involves the expansion of a template so that ESP can perform substitution. For example, if a template is used to define an Application consisting of five jobs, the template is expanded five times. During the expansion of the template, ESP substitutes the appropriate values as per the template definition statements, to generate the Application.Templates provide a simplified method of entering data when there is a high degree of repetition and are useful for defining similar jobs and using other repetitive code. Templates allow you to use and enforce standards and reduce maintenance.Templates are available any where CLANG is available:• Page mode• Line mode• ESP initialization parameters• ESP Procedures.Templates are available for use at any time while the same command environment is active (for example, Page mode, ESP Event.)

Operand DescriptionTEMPLATE Indicates the beginning of the template definition.name Indicates the name the template.posct Indicates the number of positional operands. Positional operands

must be passed to the template in the order specified.parms Indicates any positional, keyword, or keyword(value) operands.LOCALVARIABLES

Defines variables to be used only with the body of the template.

GLOBAL VARIABLES

Defines variables to be used within or outside the body of the template. This is the default.

1235

Multiple templates can be used within the input stream (for example, Application definition).

Related statementsFor information on working with templates, see the ESP Workload Manager Advanced User’s Guide.

Examples For information on ending a template definition, see the ENDTEMPL statement.Defines similar jobs in an ApplicationThe following template is used to define similar jobs in an Application: APPL PAYROLLJCLLIB 'CYBBP01.TESTJOBS.CNTL'TEMPLATE ACCPAY (1,JOBNAME) JOB %JOBNAME SUBAPPL ACCPAY RUN DAILY TAG 'CRITICAL' ENDJOBENDTEMPLACCPAY ACCJOB1ACCPAY ACCJOB2ACCPAY ACCJOB3

The TEMPLATE statement indicates:• The name of the template is ACCPAY• One positional operand called JOBNAME is available for substitution during

template processing.• During the expansion of the template ESP substitutes the appropriate value for

JOBNAME as follows: • ACCJOB1 runs daily, belongs to the ACCPAY subApplication and has a tag of

CRITICAL associated with it• ACCJOB 2 runs daily, belongs to the ACCPAY subApplication and has a tag of

CRITICAL associated with it• ACCJOB3 runs daily, belongs to the ACCPAY subApplication and has a tag of

CRITICAL associated with it.Example of a TEMPLATE definitionThe following is an example of a TEMPLATE definition:TEMPLATE ANYHOL (3,NAME,DATE,YEAR) DEFHOL %NAME START(%DATE %YEAR)ENDTEMPL

TEMPLATE Statement: Set Templates

1236

In the above example, three positional operands are defined and must be passed to the template in the specified order—NAME, DATE, and YEAR. The following is an example of passing data to the template:ANYHOL XMAS DECEMBER25 2005

In the above example, NAME has the value XMAS, DATE has the value DECEMBER25, and YEAR has the value 2005.Template definition for holidayThe following is an example of a TEMPLATE definition:TEMPLATE ANYHOL (1,NAME,DATE()) DEFHOL %NAME START(%DATE) ENDTEMPL

In the above example, one positional operand is identified and must be passed to the template in the specified order. This represents the name of a holiday. The DATE can be specified using any scheduling term ESP recognizes.The following is an example of passing data to the template:ANYHOL XMAS DATE(DECEMBER 25,2005)

In the above example, NAME has the value XMAS and DATE has the value DECEMBER 25, 2005.Template definition for similar jobsThe following template is used to define similar jobs in an Application: APPL PAYROLLJCLLIB 'CYBER.JCLLIB.CNTL'TEMPLATE PAY (1 JOBNAME FREQ(DAILY) NEXT()) JOB %JOBNAME IF FREQ NE "" THEN RUN %FREQ IF NEXT NE " " THEN RELEASE (%NEXT) TAG PJOB ENDJOBENDTEMPLPAY PAYJOB1 NEXT(PAYJOB2,PAYJOB3)PAY PAYJOB2 NEXT(PAYJOB4)PAY PAYJOB3 FREQ(WEEKDAYS) NEXT(PAYJOB4)PAY PAYJOB4 NEXT(PAYJOB5)PAY PAYJOB5 FREQ(LAST WORKDAY OF MONTH)

1237

In the preceding example, the TEMPLATE statement indicates:• The name of the template is PAY.• One positional operand is available for substitution during template processing.

This represents the jobname.• The FREQ variable has the value DAILY.• The NEXT variable is set to null, but can be passed to the template.During the expansion of the template, ESP substitutes the appropriate value as follows: • PAYJOB1 runs daily and releases PAYJOB2 and PAYJOB3• PAYJOB2 runs daily and releases PAYJOB4• PAYJOB3 runs Wednesdays and releases PAYJOB4• PAYJOB4 runs daily and releases PAYJOB5• PAYJOB5 runs on the last workday of the month and has no successors.Example of a TEMPLATE definitionThe following is an example of a TEMPLATE definition:TEMPLATE REGJOB (1,NAME,RUN(),NORUN(),REL()) JOB %JOB IF RUN NE " THEN RUN %RUN IF NORUN NE '' THEN NORUN %NORUN IF REL NE '' THEN RELEASE %REL ENDJOBENDTEMPL

The following is an example of passing data to the template:REGJOB PAYJOB1 RUN(LAST DAY OF MONTH) REL(PAYJOB2)REGJOB PAYJOB2 RUN(WORKDAYS) NORUN(FRIDAY) REL(PAYJOB3)REGJOB PAYJOB3 RUN(WED)

• As a result of the first statement: NAME has the value PAYJOB1, RUN has the value LAST DAY OF MONTH, and REL has the value PAYJOB2.

• As a result of the second statement: NAME has the value PAYJOB2, RUN has the value WORKDAYS, NORUN has the value FRIDAY, and REL has the value PAYJOB3.

• As a result of the third statement: NAME has the value PAYJOB3 and RUN has the value WED.

TEMPLIB Statement: Identify Temporary JCL Library

1238

TEMPLIB Statement: Identify Temporary JCL Library

The TEMPLIB statement is used to identify the temporary or override JCL library you want to use as the default for all jobs following this statement. ESP uses JCL from this library for job submission if it exists. Otherwise it uses JCL from the most recent JCLLIB statement.

SyntaxTEMPLIB dsname [JOBNAME|USEMEM]

Usage notesThis statement identifies the temporary JCL library to be used as the default for all jobs following this statement. If a MEMBER statement is not coded for a job or if the JOBNAME operand is not coded in the TEMPLIB statement, the member name is assumed to be the same as the job name. If a temporary library is specified, and the job exists in this library, ESP submits the job from the library. Otherwise, ESP uses the JCL library from the most recent JCLLIB statement. The //* UNTIL and //* FROM statements can be used to control the use of temporary JCL.When using TEMPLIB for a job, it is not necessary to have the job in the JCLLIB if it exists in the TEMPLIB.ESP does not automatically delete the job from TEMPLIB when it completes.

Related informationFor information on identifying JCL libraries, see the ESP Workload Manager User’s Guide.For information on specifying a JCL library, see the JCLLIB statement.For information on specifying an optional JCL library for an individual job, see the DATASET statement.For information on specifying the member name in which ESP will find a job’s execution JCL, see the MEMBER statement.For information on limiting the window in which temporary JCL is used, see the //* FROM and //* UNTIL statements.

Operand Descriptiondsname Indicates the name of the data set where the override JCL resides.JOBNAME Requests that the data set given in dsname be searched for a

member with the same name as the application job being submitted. If the job has a MEMBER statement, it is ignored. This parameter has no effect outside of an application.

USEMEM Indicates that a MEMBER statement will be honoured with this TEMPLIB data set. This is the default.

1239

Examples Identify an override JCL libraryIn the following example, ESP uses JCL for PAYJOB1 between December 31st, 2005 at 9 am and January 5th, 2006 at 5 pm, if it exists in CYBER.OVERRIDE.CNTL. Otherwise ESP uses JCL from CYBER.JCL.CNTL.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'TEMPLIB 'CYBER.OVERRIDE.CNTL'JOB PAYJOB1 RUN WORKDAYSENDJOB

Note: To limit the window in which ESP uses temporary JCL, use the //* FROM and/or //* UNTIL statements as follows:

//* FROM 9AM DECEMBER 31,2005//* UNTIL 5PM JANUARY 4TH, 2006//PAYJOB1 JOB CYB,CLASS=A,MSGCLASS=0

Ensure JCL from appropriate scheduled dateIn the following example, ESP uses JCL for PAYJOB2 if it exists in the temporary JCL library. The name of the temporary library consists of two symbolic variables: %ESPSYY is the two-digit scheduled year; %ESPSDDD is the three-digit Julian day. Each day ESP uses a different TEMPLIB.For example, if the scheduled execution date of the Event that invokes this Application is January 1st, 1999, ESP uses the temporary JCL if it exists in CYBER.OVERRIDE.99001. Otherwise, it uses JCL from CYBER.JCL.CNTL.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'TEMPLIB 'CYBER.OVERRIDE.%ESPSYY%ESPSDDD'JOB PAYJOB2 RUN WORKDAYSENDJOB

Ignore MEMBER statement for TEMPLIBIn the following example, ESP Workload Manager first searches for member PAYJOB2 from the temporary library CYBER.OVERRIDE.CNTL. If the member is not found, ESP Workload Manager uses member PAY1 from the regular library CYBER.JCL.CNTL.APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'TEMPLIB 'CYBER.OVERRIDE.CNTL' JOBNAMEJOB PAYJOB2 MEMBER PAY1 RUN WORKDAYSENDJOB

TEST Command: Test Schedule Criteria

1240

TEST Command: Test Schedule Criteria

The TEST command is used to test schedule criteria, prior to actually using them. This tests any date or schedule specification. ESP responds with the actual date and time. If you specify a number in parentheses after the TEST commands, ESP displays as many subsequent dates and times as you indicated.

TypeGeneral command.

SyntaxTEST [(n)] criteria

Usage notesYou can also test schedule criteria using ESP’s ISPF interface—Option E.4—from the ESP Main Menu.

Related informationFor information on testing schedule criteria, see the ESP Workload Manager User’s Guide.

Examples Tests schedule criteriaThe following TEST command tests schedule criteria:TEST (5) LAST WORKDAY OF MONTH

In the above example, the last workday in each of the next five months are displayed, as follows:00.00.00 FRIDAY FEBRUARY 27TH, 1998, DAY 05800.00.00 TUESDAY MARCH 31ST, 1998, DAY 09000.00.00 THURSDAY APRIL 30TH, 1998, DAY 12000.00.00 FRIDAY MAY 29TH, 1998, DAY 14900.00.00 TUESDAY JUNE 30TH, 1998, DAY 181

Tests the next 10 workdaysTEST (10) WORKDAYS

Operand Descriptionn Indicates how many times the schedule criteria are to be cycled. The

default is one.criteria Indicates criteria.

1241

Tests last workday of the yearTEST LAST WORKDAY OF YEAR

Tests first workday of each month starting in November for the next yearTEST (12) 6PM FIRST WORKDAY OF MONTH STARTING NOVEMBER

Tests the next five holidaysTEST (5) HOLIDAY

Tests the 3rd Saturday in MayTEST 3RD SATURDAY OF MAY

TEXT_MON Statement: Monitor Content of Text File

1242

TEXT_MON Statement: Monitor Content of Text File

Monitors the contents of a text file to search for a text string. Based upon the specified operands, TEXT_MON controls the execution of a job. A typical application of this statement would be to monitor for an error message in a log file after execution of a script.

TypeApplication statement.

ApplicabilityRelease 6 System Agents.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use text file monitors, load the workload object module CYBESOTM with the WOBDEF command or with the WOBDEF initialization parameter.Use these job-definition statements with a TEXT_MON workload object:• SEARCHRANGE (Mandatory)• TEXTFILE (Mandatory)• TEXTSTRING (Mandatory)• TIMEFORMAT (Optional unless the operand DATETIME is specified within a

SEARCHRANGE statement)The short form of TEXT_MON is TM.Also refer to the JOB statement usage notes.

ExamplesThis example job monitors the file c:\program files\cybermation\esp system agent r6\agentparm.txt for the string log.level= exists. The search for the string starts at line 1.TEXT_MON TEXTMON1.ALL AGENT R6AGENT TEXTFILE 'c:\program files\cybermation\esp system agent + r6\agentparm.txt' TEXTSTRING log.level= EXIST SEARCHRANGE LINE FROM(1) RUN DAILYENDJOB

1243

This example monitors the file agentparm.txt for the string log.level=5. The search for the string starts at line 1 and ends at line 20.TEXT_MON TEXTMON2.ALL AGENT R6AGENT TEXTFILE agentparm.txt TEXTSTRING log.level=5 EXIST SEARCHRANGE LINE FROM(1) TO(20) RUN DAILYENDJOB

This example monitors the file c:\program files\cybermation\esp system agent r6\agentparm.txt for the string log.maxsize=10240. The search for the string starts at line 1. If the string is found, the jobs TMTEST2 and TMTEST3 are released.TM TEXTMON3.ALL AGENT R6AGENT TEXTFILE 'c:\program files\cybermation\esp system agent + r6\agentparm.txt' TEXTSTRING log.maxsize=10240 SEARCHRANGE LINE FROM(1) RELEASE (TMTEST2, TMTEST3) RUN DAILYENDJOB

TEXTFILE Statement: Specify Text File Name and Location for Text Search Within TEXT_MON

1244

TEXTFILE Statement: Specify Text File Name and Location for Text Search Within TEXT_MON

The TEXTFILE statement specifies the name and location (path) of the text file that is searched for a text string in a TEXT_MON workload object.

ApplicabilityESP System Agents, Release 6, used within a TEXT_MON workload object. For more information, see “TEXT_MON Statement: Monitor Content of Text File” on page 1242.

SyntaxTEXTFILE filename

ExamplesExample 1 (Windows)In this example, the filename is enclosed in single quotes because the path contains spaces.

TEXT_MON TEXTFILE1.STMNT AGENT R6AGENT TEXTSTRING 'ERROR MESSAGE' EXIST CONT(A123) TEXTFILE 'c:\program files\cybermation\logfile' SEARCHRANGE LINE FROM(1234) TO(1876) RUN DAILYENDJOB

Operand Descriptionfilename The format is case sensitive, any character, and up to 256 characters

in length. If filename contains spaces (for example, in a Windows path statement), enclose the entire statement in single quotes. For example:'C:\Program Files\Cybermation\R6 Agent'

1245

Example 2 (UNIX)TM TEXTFILE2.STMNTAGENT R6AGENTTEXTFILE '/export/home/cybermation/agentdir +/log/transmitter.log'

TEXTSTRING NTAGR6 EXISTSEARCHRANGE DATETIME +FROM(10:00:00) +TO(15:20:59)

TIMEFORMAT 'HH:mm:ss' TIMEPOS(12)RUN DAILYRELEASE (JOB1.MONDAY, JOB2.TUESDAY)

ENDJOB

TEXTSTRING Statement: Specify Text String to Search for Within TEXT_MON

1246

TEXTSTRING Statement: Specify Text String to Search for Within TEXT_MON

The TEXTSTRING statement specifies what text to look for in a TEXT_MON workload object.

ApplicabilityESP System Agents, Release 6, used within a TEXT_MON workload object. For more information, see “TEXT_MON Statement: Monitor Content of Text File” on page 1242.

SyntaxTEXTSTRING textstring [EXIST|NOTEXIST] [CONTINUOUS(alertname)]

Usage notes

CONTINUOUS modeThe TEXT_MON job searches the entire file specified by TEXTFILE. When the job finds the first match to the text string, the job completes. If CONTINUOUS is specified, the job resumes the search from the first line following the last line of the file from the previous search. In other words, the search takes place in the lines added to the file after the first match was found.

Operand Descriptiontextstring The format is case sensitive, any character, and up to 1022

characters in length.EXIST Default. Monitor a specified text file to see if a text string exists. If

the text string exists, the job completes.NOTEXIST Monitor a specified text file to see if a text string does not exist. If

the text string does not exist, the job completes.CONTINUOUS (alertname)

If EXIST is specified, the job will continue to monitor a specified file for the existence of a text string. If the specified text string is found, an Alert is issued to trigger a workload object. The format is any character and up to four characters in length.

Note: alertname can be an asterisk meaning that it will trigger the workload object again.

1247

Escape sequencesTo be evaluated as escape sequences, the following 12 characters must be proceeded with back slashes. See the second example shown on page 1247.

For more information on regular expressions, refer to “Interpretation of the regular expression for Example 3” on page 1248.

ExamplesExample 1This example shows a search of the text file DATA SOURCE NAME for the text string 'EVENT ""COMPUTER() '. If this string is found (as specified by the operand EXISTS), the alert A123 is issued. The spaces in the values for TEXTFILE and TEXTSTRING require that a single quote is placed at the start and end of each value.APPL TEXT.STRING1AGENT CYBR6USER JEFFJOBCLASS BATEXT_MON TEXT.STRING1 TEXTSTRING 'EVENT ""COMPUTER() 'EXIST CONT(A123) TEXTFILE 'DATA SOURCE NAME' SEARCHRANGE LINE FROM (123) TO (876) RUN DAILYENDJOB

Example 2In this example, because the TEXTSTRING contains escape sequences, back slashes must precede the special characters asterisk (*), period (.), and zed (Z). The required text string is a wild card search for the text string "=jars*.* that must appear at the end of the line (\Z).TM TEXT.STRING2 AGENT R6AGENT TEXTFILE '/export/home/cybermation/agentdir + /agentparm.txt' TEXTSTRING '=jars/\*\.\*\Z '<-- Find line ended by =jars*.* SEARCHRANGE LINE FROM(1) TO(110) RUN DAILYENDJOB

\ – back slash [ – opening bracket * – asterisk| – vertical bar { – opening brace + – plus sign( – opening parenthesis ^ – caret (circumflex) ? – question mark) – closing parenthesis $ – dollar sign . – period

TEXTSTRING Statement: Specify Text String to Search for Within TEXT_MON

1248

Example 3In this example, the text string is a regular expression, as indicated by the operand REGEX in the SEARCHRANGE statement.TEXT_MON TMTEST21 AGENT R6AGENT TEXTFILE '/export/home/cybermation/agentdir/agentparm.txt' TEXTSTRING '^\w{4,10}\.' Exist SEARCHRANGE REGEX FROM(\A\W\sE) RELEASE TMTEST22.FAIL RUN DAILYENDJOB

Interpretation of the regular expression for Example 3• ^ or \A — match only at the beginning of string (line)• \Z or $ — match only at the end of string• \w — a word character [a-zA-Z0-9]• \W — a non-word character • \s — a whitespace character• {4,10} — match at least 4 times but not more than 10 times

To illustrate the last item (4, 10), consider the syntax:TEXTSTRING 'b1{1,3}c'

Evaluating this expression yields the following conditions:• The line contains the text b1.• Numeric 1 should exist at least once, but not more than three times.• The specified text string must be followed by the letter c.

Note: For Windows examples, substitute a Windows path in the TEXTFILE statement.

1249

THEN Statement: Specify Actions

The THEN statement is used in conjunction with an IF statement when the expression that follows the IF statement returns a true value.

TypeControl Language (CLANG) statement.

SyntaxTHEN action-statement

Usage notesWhen you use an IF statement, the expression that follows it must return a true or false value. The THEN statement is used in conjunction with an IF statement when the expression that follows the IF statement returns a true value. When a true value is returned by the IF statement, ESP processes the statements following the THEN statement.If multiple statements are required to be processed, you must begin and end compound action statements with DO and ENDDO language elements.If a THEN statement continues to another line, use a line continuation character (– or +). If there is no continuation character, ESP ignores the THEN statement. The ELSE statement is used in conjunction with an IF statement when the expression that follows the IF statement returns a false value.

Related statementsFor information on using ESP’s Control Language, see the ESP Workload Manager User’s Guide.For information on conditional processing, see the IF, ELSE, and DO statements.

Operand DescriptionTHEN Can only be used when the IF statement is already specified.

Defines the action to be taken when evaluation of an IF statement returns a true value. To specify multiple actions, use the DO and ENDDO statements.

action-statement

Indicates the action to be taken.

THEN Statement: Specify Actions

1250

Examples Process different statementsIn the following example, ESP determines if the actual day is equal to Monday. If the evaluation of this expression is true, ESP sends a message indicating that today is Monday to CYB01. If the evaluation of this expression is false, ESP sends a message to CYB01 indicating what today is.IF %ESPADAY = 'MONDAY' THEN - SEND 'TODAY IS MONDAY' U(CYB01)ELSE - SEND 'TODAY IS %ESPADAY' U(CYB01)

Determine when a job runsIn the following example, ESP determines if today is the 15th day of the month and TUESDAY, and if so PAYJOB1 is selected to run.JOB PAYJOB1 IF TODAY('15TH DAY OF MONTH') AND TODAY('TUESDAY') THEN - RUN TODAYENDJOB

Set the value of a user defined symbolic variableIn the following example, a user-defined symbolic variable called FINANCIAL_YEAR, which consists of two, two–digit year numbers, is set as follows:• If the current month is January, February, March or April, use last year followed

by this year • For any other month, use current year followed by next year.IF ESPSMM<5 THEN DO GENTIME LAST TODAY LESS 1 YEAR FINANCIAL_YEAR='%LASTYY%ESPSYY'ENDDOELSE DO GENTIME NEXT TODAY PLUS 1 YEAR FINANCIAL_YEAR='%ESPSYY%NEXTYY'ENDDO

1251

TIME Command: Set Start Time

The TIME command is used to set the start time of a model sub-period. This allows you to change environmental factors in the modeling period at specified times.

TypeModel command.

SyntaxTIME criteria

Usage notesA TIME command remains in effect until another TIME command is issued or until the end of the modeling period is reached. Any number of TIME commands can be issued for a modeling period. If not specified, the default is the start time specified on the MODEL command.

Related informationFor information on beginning and ending the model process, see the MODEL and ENDMODEL commands.For information on modeling, see the ESP Workload Manager Advanced User’s Guide.

Example Set start time of a model sub-periodIn the following example, an initiator class is set at 2 am.TIME 02:00 INIT SET(15) CLASS(X)

Operand Descriptioncriteria Indicates any valid schedule criteria that denote the start of the sub-

period. If the statement contains separators then it must be enclosed in quotes. The time is relative to the period specified on the MODEL command.

TIMEFORMAT Statement: Specify Time Format for Searching Log File Within TEXT_MON

1252

TIMEFORMAT Statement: Specify Time Format for Searching Log File Within TEXT_MON

The TIMEFORMAT statement specifies the mask that is used to search a log file with a time stamp.

ApplicabilityESP System Agents, Release 6, used when a DATETIME operand is specified in a SEARCHRANGE statement within a TEXT_MON workload object. For more information, see “TEXT_MON Statement: Monitor Content of Text File” on page 1242.

SyntaxTIMEFORMAT (timeformat) [TIMEPOS (timepos)]

Operand Descriptiontimeformat The upper and lower boundaries of the time format

expressed as a time pattern. “Time format pattern characters” on page 1253 lists the characters you can use to build a time format pattern.timeformat is case sensitive, any character, and up to 256 characters in length.

TIMEPOS (timepos) This operand defines the first column of the time stamp in the log file. The format is numeric, up to five digits.

1253

Usage notesTo specify the time format, construct a time pattern string that is used as a mask for searching the particular time stamp you want to find. In this pattern, all ASCII letters are reserved as pattern letters.

Time format pattern charactersThe following table shows the symbols you can use to build a time format pattern. Examples are shown in “Examples of time format patterns” on page 1254.

Time Format Pattern CharactersCharacter Definition Type Example

G Era designator Text ADy Year Number 2000M Month in year Text & Number July 07d Day in month Number 10h Hour in am/pm

(1 to 12)Number 12

H Hour in day (0 to 23) Number 0m Minute in hour Number 30s Second in minute Number 55S Millisecond Number 978E Day in week Text TuesdayD Day in year Number 189F Day of week in month Number 2 (2nd Wednesday July)w Week in year Number 27W Week in month Number 2a am/pm marker Text PMk Hour in day (1 to 24) Number 24K Hour in am/pm

(0 to 11)Number 0

z Time zone Text EST—Eastern Standard Time

' Escape for test Delimiter'' Single quote Literal '

TIMEFORMAT Statement: Specify Time Format for Searching Log File Within TEXT_MON

1254

Examples

Examples of time format patternsIn these samples, the baseline is July 10, 2000 at 12:08 PM, Eastern Standard Time.

TIMEFORMAT for FROM and TO operandsIn this example, the operand TIMEFORMAT provides the time pattern format that is applied to the values specified by the FROM and TO operands of the SEARCHRANGE statement.TEXT_MON TIMEFMT.STMNT RGAGENT TEXTFILE '/export/home/cybermation/agentdir+ /log/transmitter.log' TEXTSTRING NTAGR6 EXIST SEARCHRANGE DATETIME+ FROM('Tue Aug 26 00:00:00.000 EST 2003')+ TO('Tue Aug 26 23:59:59.999 EST 2003') TIMEFORMAT 'EEE MMM dd HH:mm:ss.SSS zzz yyyy' TIMEPOS(1) RUN DAILYENDJOB

The values for the TIMEFORMAT operand are as follows:• EEE—day of the week• MMM—month in the year• dd—day in the month• HH:mm:ss.SSS—hours, minutes, seconds, and milliseconds.• zzz—time zone• yyyy—yearNote: For a WIndows example, substitute a Windows path in the TEXTFILE

statement.

Format Pattern Result"yyyy.MM.dd G 'at' hh:mm:ss z" 2000.07.10 AD at 12:08:56 EST"EEE, MMM d, ''yy" Wed, July 10, '97"h:mm a" 12:08 PM"hh 'o''clock' a, zzzz" 12 o'clock PM, EST"K:mm a, z" 12:08 PM, EST"yyyyy.MMMMM.dd GGG hh:mm aaa" 2000.July.10 AD 12:08 PM

1255

TIMEZONE Statement: Specify Time Zone (PeopleSoft)

The TIMEZONE statement specifies a time zone other than the current one.

ApplicabilityESP Business Agents for PeopleSoft, Release 2 and higher.

Syntax TIMEZONE timezone

Usage notesLook up time zone settings in PeopleSoft.

ExampleFor Central time in the Continental United States:TIMEZONE CST

Operand Descriptiontimezone The length is up to nine characters.

TITLE Command: Define Titles

1256

TITLE Command: Define Titles

The TITLE command is used to define a title to be displayed at the top of the next and subsequent pages of printed data. It also skips to the top of the next page.

TypeGeneral command.

SyntaxTITLE n [SET] [DELETE] ['title string'}

Usage notesUp to seven title and footing lines can be active at any time. If you specify Title 1 and Title 3, a blank line is placed between the two title lines you specify. If neither SET nor DELETE is specified, an immediate page eject occurs.The following are built-in variables which you can use in a title string:

Operand Descriptionn Indicates which title line you are defining; the range is 1-7. The default is one.SET Indicates the title for subsequent pages is to be set. An immediate page eject does

not occur.DELETE Indicates the specified title line is to be deleted.title string Indicates the title to be displayed. It should be enclosed within quotes. If you want

to use quotes in the title line itself, double them up.

Operand Description%CE Centers the Operand within the output line.%DATE Full date, for example, SUNDAY 4th JANUARY 2004.%DAY Day of week name, for example, MONDAY.%DD Day of month number, for example, from 01 to 31.%DDDD Julian day or day of year number. For example, or example, 365 for last day.%DOW# Day of week number, for example, 1 for Sunday, 7 for Saturday, regardless

of calendar settings.%EVAL Returns the numeric value of an expression. An output-format descriptor

may follow the operand to request leading blanks or zeros.%HH Hour, in 24-hour format, for example, 14.

1257

Related informationFor information on reporting, see the ESP Workload Manager User’s Guide.

Examples Used in a history reportIn the following example, a title is associated with this history report.REPORTTITLE '%CE(PAYROLL APPLICATION REPORT FOR %DATE)'FROM 7AM TODAY LESS 2 DAYSCRITERIA APPLSYS EQ PAYROLLDISPLAY APPLSYS,JOBNAME,JOBNO,RDRONDATEENDR

Used in a modelling reportIn the following example, two titles are associated with this model report.DEFPRINT REPORT1 DATASET('ESP.MODEL.REPORT1')TITLE 1 '%CE(CYBERMATION INC.)'TITLE 2 '%CE(DATA CENTER OPERATIONS)'

%LENGTH Returns the length of the Operand.%MM Month number, for example, 01 if the month is January.%MMM first three characters of the month, for example, JAN.%MM Minute of the hour.%MONTH Month name, for example, JANUARY.%PAGE The current page number.%RJ Justifies the operand on the right side of the output line.%SSS Seconds.%TIME Time, in 24-hour format, for example, 14.30.00.%YEAR Year, for example, 1999%YY Last two characters of year, for example, 99.

Operand Description

TITLE Command: Define Titles

1258

Used in a batch jobIn the following example, a title is associated with the output produced by an ESP command.//ESPCOMND JOB …//STEP001 EXEC PGM=ESP,PARM='SUBSYS(E510)',REGION=4M//STEPLIB DD DSN=CYB2.ESP510Q.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSIN DD *TITLE '%CE(ESP DATASETS)'LDSN/*

Deletes title 3 from this point onTITLE 3 DELETE

Defines a title without generating a page breakTITLE 4 SET 'QUARTERY RESULTS'

1259

TOPIC Statement: Publish/Subscribe to a Topic/Queue (J2EE)

For JMS Publish jobs, The TOPIC statement specifies whether the Agent publishes to a Topic or a Queue.For JMS Subscribe jobs, The TOPIC statement specifies whether the Agent subscribes to a Topic or a Queue.

Applicability• ESP System Agents, Release 6, Service Pack 2 or higher• Used within the JMSP_JOB and JMSS_JOB workload objects

SyntaxTOPIC Y|N

Usage notesTOPIC is a mandatory statement within the JMSP_JOB and JMSS_JOB workload objects.

ExamplesPublish to a QueueIn this example, the CYBJK.JP job publishes a simple message to a Queue named Queue.APPL TESTJPJMSP_JOB CYBJK.JP HOLD RUN DAILY AGENT CYBNT INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DESTNAME Queue TOPIC N MSGCLASS String JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001 PARAMETER TYPE(java.lang.String) VALUE(’this is my message’)ENDJOB

Operand DescriptionY Agent publishes/subscribes to a Topic.N Agent publishes/subscribes to a Queue.

TOPIC Statement: Publish/Subscribe to a Topic/Queue (J2EE)

1260

Monitoring TopicIn this example, the CYBJK.JS job monitors the Topic named Topic for messages matching the filter criteria. The consumed messages from the Topic are stored in the file outputfile.APPL TESTJSJMSS_JOB CYBJK.JS RUN DAILY AGENT CYBUNIX INITIAL_CONTEXT weblogic.jndi.WLInitialContextFactory CONNECTION_FACTORY ConnectionFactory DEST /export/home/user1/outputfile DESTNAME Topic TOPIC Y FILTER ’abc\s...\s[a-zA-Z]+\sFilter![\sa-z0-9]+’ JNDIUSER cyberuser LOCATION t3://100.10.31.66:7001ENDJOB

1261

TPAPPL Command: Interaction with Remote Partner Application

The TPAPPL command manages interactions with remote partner Applications.

TypeTP Server command

SyntaxTPAPPL applname {DISPLAY} {START} {STOP} {ADDCONV} {DELCONV} {SHOWHELD} {DELHELD} {SUSPEND} {RESUME} {RELEASE} [LUNAME(luname)] [LOGMODE(logonmode)] [TRAN(transID)] [DEFER]

Operand Descriptionapplname Indicates the name of the remote Application.DISPLAY Displays the current status of the connection, including all

conversations.START Establishes a connection to the specified Application.STOP Terminates the connection.ADDCONV Adds a conversation with the remote Application.DELCONV Deletes an existing conversation.SHOWHELD Displays any held transactions.DELHELD Deletes any held transactions.SUSPEND Temporarily suspends interaction with the remote Application.RESUME Resumes activity on a suspended connection.RELEASE Releases any held transactions.luname Indicates the name of the VTAM LU. If omitted, defaults to

blanks. Used only with the START keyword.

TPAPPL Command: Interaction with Remote Partner Application

1262

Example1: Initiating a TP Server connectionThe following example shows a connection being requested with the TP Application ESP_MONTREAL, whose LU name is ESPMTL. The logon mode will default to the value specified on the LOCAPPL initialization statement.TPAPPL ESP_MONTREAL START LUNAME(ESPMTL)

Example 2: Displaying held transactionsThe following example shows a display of how many transactions are being held for TP Application ESP_MONTREAL.TPAPPL ESP_MONTREAL SHOWHELD

Example 3: Releasing held transactionsThe following example shows releasing all held transactions for the TP Application ESP_TORONTO.TPAPPL ESP_TORONTO RELEASE

Example 4: Stopping a connection The following example shows stopping a connection with the TP Application ESP_TORONTO.TPAPPL ESP_TORONTO STOP

logonmode Indicates the logon mode for this Application. If omitted, defaults to blanks. Used only with the START keyword.

transID Indicates the name of the transaction ID. If omitted, defaults to blanks. Used only with the RELEASE, DELHELD and SHOWHELD keywords.

DEFER Performs the specified operation in deferred mode

Operand Description

1263

TPDISP Command: Display System Status

The TPDISP command displays the system status.

TypeTP Server command

SyntaxTPDISP

ExampleThe following is example output from TPDISP:APPLICATION NAME: ESPPROD_ASTATE: NORMALVTAM LU NAME: ESPTP1DEFAULT LOGON MODE: TP62APPLICATIONS: ESPPROD_B ESPPROD_DLOCAL TRANSACTIONS: INTER_SYSTEM_JOB_TRACKING TP_SERVICES_CONTROL------------ CHECKPOINT INFORMATION -----------CHECKPOINT DSNAME: CYB.TP.CKPTCHECKPOINT SIZE: 1474560 BYTESCHECKPOINT USED: 720 BYTESQUEUED APPLICATIONS: NONE

Operand DescriptionTPDISP The following information is displayed:

• The VTAM LU name.• The number of bytes available in the checkpoint data set.• The number of bytes used in the checkpoint data set.• The Applications connected to this server.• The transaction handlers registered.

TPRETRY Command: Interval to Retry Contacting an LU

1264

TPRETRY Command: Interval to Retry Contacting an LU

The TPRETRY command sets and displays the interval at which attempts will be made to contact an LU that is down.

TypeTP Server command

SyntaxTPRETRY applname [INTERVAL(nn)]

ExampleTPRETRY ESP_TORONTO INTERVAL(10)

Operand Descriptionapplname Indicates the name of the remote Application.nn Indicates the desired interval in minutes. If not specified, the

current value is displayed.

1265

TPSTART Command: Reopen VTAM ACB

The TPSTART command requests the TP Server to reopen its VTAM Application control block (ACB.)

TypeTP Server command

SyntaxTPSTART

Operand DescriptionTPSTART Command name entered as shown.

TPTERM Command: Terminate Communication

1266

TPTERM Command: Terminate Communication

The TPTERM command requests the termination of all communications and then re-establishes the connections.

TypeTP Server command

SyntaxTPTERM

Operand DescriptionTPTERM Command name entered as shown.

1267

TPTIME Command: I/O Timeout

The TPTIME command specifies the lost I/O time interval.

TypeTP Server command

SyntaxTPTIME nn

MessageESP message number 1498W is issued when the time interval is exceeded.TP I/O to Application xxxx has been outstanding for nn minutes.The following is the message explanation:The TPTIME command has been used to set a TP Server I/O timeout warning message. An I/O request to the named Application has exceeded the specified threshold.

Operand Descriptionnn Indicates the time in minutes after an I/O from which no response

has been received.

TPTRAN Command: Issue Control Commands

1268

TPTRAN Command: Issue Control Commands

The TPTRAN command issues control commands for specific transactions.

TypeTP Server command

SyntaxTPTRAN transID STOP|START [MOD(modulename)]

ExampleThe following command stops the TP_SERVICES_CONTROL transaction:OPER TPTRAN TP_SERVICES_CONTROL STOP

As result of the command, the system issues the following messages:QX10M_422I CONTROL TRANSACTION TERMINATINGQX10M_418I CONTROL TRANSACTION HANDLER TERMINATEDCYBTP002 - STOPPING THE TP SERVERQX10M_1420I APPLICATION ESP_NOSM NOT ACTIVE - CONNECTION DEFERRED

You can use the following command to restart the TP_SERVICES_CONTROL transaction:OPER TPTRAN TP_SERVICES_CONTROL START

Note: :You can display the system status with the TPDISP command.

Operand DescriptiontransID Indicates the ID of the transaction to be affected. This is the name

defined in the LOCAL TRANSACTIONS field of the system status displayed with the TPDISP command.

STOP Stops the associated transaction handler.START Starts the associated transaction handler.modulename Indicates the name of the transaction processing module to be

loaded. It must reside in a library that is in LINKLIST, or in a JOBLIB or STEPLIB concatenation

1269

TRACE Command: Activate Trace Facility

The TRACE command is used to activate the trace facility and allows trace options to be set.

TypeGeneral command.

AuthorityYou require OPER authority to issue the TRACE command.

SyntaxTRACE [SET(id[:id])] [RESET(id[:id])] [SWITCH|CLOSE|OPEN|STATUS|WRITE] [REUSE]

Operand DescriptionSET(id) Indicates one or more record identifiers you want to trace. You can

specify a list of identifiers and a range of identifiers.RESET(id) Indicates one or more record identifiers you no longer want to trace.SWITCH Requests the data set currently in use for the trace facility be freed.

The next trace data set is activated automatically. With this option, data sets are activated in the sequence in which they were first defined. Once the last data set in the sequence is closed, the first trace data set to be defined is used.

CLOSE Requests the closure of the trace data set currently in use, but prevents switching to the next trace data set. The buffers defined using TRACEDEF automatically continue to hold trace data in core until a TRACE OPEN command is issued.

OPEN Requests opening of the trace data set most recently active. This is used after TRACE CLOSE is issued to reactivate the same trace data set.

REUSE Indicates the data set currently in use for the trace facility be checkpointed so that subsequent writes to it begin at the checkpoint rather than at the start of the data set.

WRITE Writes to the trace data set to clear any buffered data.

TRACE Command: Activate Trace Facility

1270

Usage notesTRACE is useful as a problem-solving tool. On occasion Cybermation Technical Support personnel may ask you to SET a specific trace record ID to provide information to help with trouble shooting.If you wish to capture only records relating to Event processing (that is, type 601), use the ESPPARM AUDITLOG ddname in the ESP started task procedure or the AUDITLOG initialization parameter. This allows the use of a pre-allocated SYSOUT for Event activity and eliminates the need to use the TRACEDEF and TRACE commands.

Related informationFor information on displaying Event log data collected in the trace data set, see the LOGPRT command.For information on printing trace data, see the TRACEPRT command.

Examples Activates the trace facilityIn the following example, a trace is activated and specifies that record IDs 602 through 604, and 607 should be traced.OPER TRACE SET(602:604,607)

Checkpoints the data set currently used for the trace facilityIn the following example, the current data set used for the trace facility is checkpointed before switching to the next trace data set. When the current trace data set is later reused, records are written starting at the checkpoint.OPER TRACE SWITCH REUSE

Turns off the trace facility for specific recordsIn the following example, the trace is turned off for record Ids 602 through 604.OPER TRACE RESET(602:604)

Write out buffered data and close the trace data setIn the following example, prior to printing the trace data set, the buffered data is written out and the trace data set is closed.OPER TRACE WRITEOPER TRACE CLOSE

STATUS Displays information indicating where the trace facility is active. Display includes how many records were written since trace was activated, the current trace data sets in use, and which data set is currently active.

1271

TRACEDEF Command: Identify Data Sets

The TRACEDEF command is used to identify the data sets to be used to record information collected by the TRACE facility.

TypeGeneral command.

AuthorityYou require OPER authority to issue the TRACEDEF command.

SyntaxTRACEDEF DSN(dsname[,dsname]...) [BUF(size,count)]

Usage notesBefore using the TRACE facility, you must allocate one or more trace data sets. You must identify these data sets to ESP with the TRACEDEF command.You do not have to specify any DCB attributes when you initially allocate the data sets, because ESP does this automatically. Trace data sets use: DCB=(RECFM=VB,LRECL=4096,BLKSIZE=4100). The buffers you define continue to hold trace data until each one becomes full. At this point, the data is written automatically to the trace data set and another buffer is used.

Related informationFor information on defining a trace data set at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.For information on activating the trace facility, see the TRACE command.

Operand Descriptiondsname Indicates the name of one or more data sets to be used as trace data

sets. Separate data set names with a blank or comma. Specifying multiple trace data sets allows you to use the SWITCH operand with TRACE to free up one trace data set and switch to another.

size, count Indicates the buffers you want to use for the trace data sets you define. Size specifies the buffer size and count identifies how many buffers are required. This defaults to (4096,4)—(four buffers, each one 4096 bytes).

TRACEDEF Command: Identify Data Sets

1272

Example Define two trace data setsIn the following example, two trace data sets that each have three 23400 byte buffers are defined.TRACEDEF DSN('ESPCYB.TRACE1', 'ESPCYB.TRACE2') BUF(23400,3)

1273

TRACEPRT Command: Print Trace Data

The TRACEPRT command is used to print trace data.

TypeGeneral command.

AuthorityYou require OPER authority to issue the TRACEPRT command.

SyntaxTRACEPRT DSN(dsn[,dsn]) [FROM(criteria)] [SELECT(id[:id])] [APPL(appl[,appl...])] [JOB(job[,job...])]

Usage notesIssue the TRACEPRT command in batch or from Page mode, after collecting trace data from a TRACE command.

Note: For Cybermation diagnostic purposes, the contents of the raw trace data set are required.

Related informationFor information on using the TRACE command, see the TRACE command.

Operand Descriptiondsn Indicates the name of one or more trace data sets.criteria Indicates any valid schedule criteria that represent a time range.id Indicates a trace ID to print. Ranges are supported.appl Allows selection by Application name. Wildcards are supported.job Allows selection by jobname. Wildcards are supported.

TRACEPRT Command: Print Trace Data

1274

Examples Prints a trace data setIn the following example, CYBER.TRACE1 is printed from 6 am yesterday to 6 am today.TRACEPRT DSN('CYBER.TRACE1') FROM('6AM YESTERDAY UNTIL 6AM TODAY')

Prints trace data set based on ApplicationIn the following example, trace data set information for the PAYROLL Application is printed.TRACEPRT DSN('CYBER.TRACE1') APPL(PAYROLL)

Prints a range of trace IDsIn the following example, trace IDs 601 to 603 are printed.TRACEPRT DSN('CYBER.TRACE1') SELECT(601:603)

1275

TRACKDEF Command: Specify Tracking Definitions

The TRACKDEF command is used to specify tracking definitions in a Job Tracking Definition Table.

TypeGeneral command

ApplicabilityJob Tracking Definition Table.

SyntaxTRACKDEF [NAME(string)] [JOB] [STC] [TSU] [RACID(string)] [PGMR(string)] [CLASS(classid)] [ACCOUNT1(string)] [ACCOUNT2(string)] [ACCOUNT3(string)] [ACCOUNT4(string)] [NOTRACK] [MODEL(modelname)]

Operand DescriptionNAME(string) Indicates a one to eight character jobname to be matched on. Wildcard

characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. NAME can also be specified as JOBNAME.

JOB/STC/TSU Indicate jobs, started tasks or TSO users be tracked. If these keywords are not used, the TRACKDEF entry is not specific and all will apply.

RACID(string) Indicates the security system user ID associated with the job.CLASS(classid) Indicates the job’s execution class. This can be up to eight characters in a

JES3 environment.ACCOUNT1 Indicates the job’s first account number. Only the first eight characters are

checked.ACCOUNT2 Indicates the job’s second account number.ACCOUNT3 Indicates the job’s third account number.ACCOUNT4 Indicates the job’s fourth account number.

TRACKDEF Command: Specify Tracking Definitions

1276

Usage notesA job tracking definition table identifies the characteristics of the jobs you want ESP to track. ESP can track jobs based on jobname, execution class, programmer name, account number, job type, or the user ID associated with the job.Job tracking definition tables allow the following:

• You can define your own wildcard characters in the table. These characters give you great flexibility in defining the property of the job you want ESP to use as the job tracking parameter.

• You are not restricted to a job name or prefix when defining the tracking parameter. Instead, you can choose from a larger set of properties of the job when defining the parameter. For example, you can choose the job’s execution class, or the name of the programmer.

A job tracking definition table consists of a set of ESP WILDCARD and TRACKDEF commands, respectively, in a sequential data set or in a member of a PDS. The use of WILDCARD is optional.The order of the TRACKDEF commands is important. When tracking data is received for a job, ESP scans the TRACKDEF entries in sequence until a match is found. ESP then takes the action specified by that entry. The entry can identify whether the job is to be tracked or not. If the job is to be tracked, the default tracking model for the job is specified. If no matching entry is found, the job is not tracked.To track STCs or TSUs, you must identify these are to be tracked using the TRACKOPT command or ESP initialization parameter. You can use TRACKDEF commands to identify which STCs or TSUs to track.You can also test a job tracking definition table using ESP’s ISPF interface - Option M.4 from the ESP Main Menu.

PGMR(string) Indicates the programmer name field associated with the job. All 20 character positions can be checked.

NOTRACK Indicates a job matching the TRACKDEF entry not be tracked.MODEL Indicates the name of the tracking model to be associated with a job,

started task or TSO user. If neither NOTRACK or MODEL is specified, NOTRACK is assumed. The MODEL keyword must be used if a job is to be tracked. You can override this using the MODEL statement for a job in an Application.

Operand Description

1277

Related informationFor information on job tracking definition tables, see the ESP Workload Manager Installation and Configuration Guide.For information on loading job tracking definition tables (JTDT), see the LOADJTDT command.For information on defining wildcard characters used in a job tracking definition table, see the WILDCARD command.

For information on defining a tracking model, see the DEFTM command.For information on displaying the status of tracked jobs, see the LJ command.For information on specifying tracking options, see the TRACKOPT command.

Examples: Track all jobsIn the following example, all jobs are tracked using tracking model MODEL1.TRACKDEF NAME(-) MODEL(MODEL1)

Track jobs by nameIn the following example:• The first tracking definition command indicates ESP uses tracking model

PRODJOBS to track all jobs that start with the letter J.• The second command indicates ESP uses tracking model TESTJOBS to track all

jobs that start with the letter U.TRACKDEF JOB NAME(J–) MODEL(PRODJOBS)TRACKDEF JOB NAME(U–) MODEL(TESTJOBS)

TRACKDEF Command: Specify Tracking Definitions

1278

Track jobs based on different conditionsNote: The following is an example of a job tracking definition table:

The sample job-tracking-definition table contains three WILDCARD commands and nine TRACKDEF commands. Note: ESP Workload Manager processes its content line by line in the order they are written. When a condition is satisfied, the processing stop. For example, if a job is named CYBJOBAB and a first account of CYB3000, it will track that job with the model CYBMODEL because the condition on line 5 was the first condition satisfied.Explanations of the commands are as follows:

Line

123

456789101112

/******************************************************//*JOB TRACKING DEFINITION TABLE*//******************************************************/WILDCARD # 0-9/*NUMERICS*/WILDCARD $ A-Z/*ALPHABETICS*/WILDCARD + 0-9A-Z/*ALPHANUMERIC*/

TRACKDEF JOB NAME(DUMMYJOB) NOTRACKTRACKDEF JOB NAME(CYBJOB-) MODEL(CYBMODEL)TRACKDEF JOB NAME($$$$####) MODEL(PRODJOBS)TRACKDEF JOB NAME($$#####-) MODEL(NAME(1:2),MODEL)TRACKDEF ACCOUNT1(CYB3000) MODEL(TESTJOBS)TRACKDEF RACID(CYBFM-) MODEL(DEMOMDL)TRACKDEF JOB CLASS(G) MODEL(MODELG)TRACKDEF JOB NAME(-) MODEL(MODEL1)TRACKDEF STC NAME(-) MODEL(MODEL1)

Line Explanation1 The first wildcard character # matches all numeric characters2 The $ wildcard character matches the alphabetic characters, A through Z,

inclusive3 The + wildcard character matches the alphanumeric characters, A through Z,

inclusive, and the digits 0 through 9, inclusive4 Does not track a job called DUMMYJOB.5 Uses model CYBMODEL to track jobs whose names begin with CYBJOB.6 Uses tracking model PRODJOBS to track jobs whose names consist of four

alphabetic characters followed by four numeric characters.

1279

Track class T jobs, regardless of jobname are tracked, using the tracking model MODEL1TRACKDEF NAME(-) CLASS(T) MODEL(MODEL1)

Track all P jobs using the tracking model PRODTRACKDEF CLASS(P) MODEL(PROD)

Track all started tasks starting with the prefix CICS using the model JOBMONTRACKDEF STC NAME(CICS-) MODEL(JOBMON)

Track all jobs submitted by ESPTRACKDEF MODEL(DEFAULT)

Track all jobs regardless of jobnameTRACKDEF JOB NAME(-) MODEL(NAME(1:2),MODEL)

This example tracks all jobs whose names begin with two alphabetic characters followed by five numeric characters. ESP Workload Manager derives the name of the tracking model it uses by concatenating the first two characters of the job name with the string MODEL. For example, tracking model DXMODEL tracks job DX123245Do not track jobs with a programmer name field starting with CYBEDTRACKDEF PGMR(CYBED-) NOTRACK

Track jobs starting with X using the model XSYSTRACKDEF JOB NAME(X-) MODEL(XSYS)

7 Tracks all jobs whose names begin with two alphabetic characters followed by five numeric characters. ESP Workload Manager derives the name of the tracking model it uses by concatenating the first two characters of the job name with the string MODEL. For example, tracking model DXMODEL tracks job DX123245.

8 Uses tracking model TESTJOBS to track jobs where the first account number is CYB3000.

9 Uses tracking model DEMOMDL to track jobs owned by user ID that begins with CYBFM.

10 Uses tracking model MODELG to track class G jobs.11 and 12

Will track all other jobs and started tasks using model MODEL1.

Line Explanation

TRACKING Command: Enable/Disable ESP Tracking Facility

1280

TRACKING Command: Enable/Disable ESP Tracking Facility

The TRACKING command is used to enable or disable the ESP tracking facility.

TypeGeneral command.

AuthorityYou require OPER authority to issue the TRACKING command

SyntaxTRACKING [COLLECT|NOCOLLECT] [STORE|NOSTORE] [LOG|NOLOG]

Usage notesIf no options are specified, the current tracking settings are displayed (the NOLOG field of the display is reserved for future use). If an option is specified, it is added to the current tracking settings.The COLLECT and STORE options should be active if you wish to perform normal tracking functions.The COLLECT and NOCOLLECT keywords control the collection of SMF data that is used by the tracking processor to update the TRAKFILE and the History data sets. When NOCOLLECT is specified, SMF data is not captured and the tracking is lost.

Operand DescriptionCOLLECT Indicates SMF recording is activated. SMF tracking data is stored in

the TRAKFILE and the History data sets is updated (unless NOSTORE is specified).

NOCOLLECT Indicates SMF recording is deactivated. No SMF data is collected, no tracking data is written to the TRAKFILE and the History data sets is NOT updated.

STORE Indicates tracking data from SMF be stored in the TRAKFILE and the History data sets be updated.

NOSTORE Indicates the tracking processor be quiesced. No tracking data is written to the TRAKFILE and the History data set is not updated. The data is temporarily buffered to the checkpoint data set until STORE is requested.

LOG Reserved for future use.NOLOG Reserved for future use.

1281

The NOSTORE keyword can be used to quiesce the tracking processor temporarily. All tracking functions including Job Monitoring are suspended when NOSTORE is specified. This is useful when you need to perform maintenance on an ESP History File. Tracking data is buffered to the checkpoint data set until STORE is requested. When STORE is specified to bring the tracking processor out of quiesced state, any data that was buffered is written to the TRAKFILE and the History data sets is updated. Note: The tracking processor should not be left in the NOSTORE mode for long

periods of time as the checkpoint data set could fill up causing tracking data to be lost.

Related informationFor information on tracking, see the ESP Workload Manager Installation and Configura-tion Guide.

Examples Displays tracking settingsIn the following example, current tracking settings are displayed.OPER TRACKING

Displays tracking optionsIn the following example, SMF recording is activated. SMF tracking data is collected and stored in the TRAKFILE and the History data set is updated.OPER TRACKING COLLECT STORE

Quiesces the tracking processorIn the following example, the tracking processor is quiesced.OPER TRACKING NOSTORE

TRACKOPT Command: Set Various Tracking Options

1282

TRACKOPT Command: Set Various Tracking Options

Displays or sets any of seven tracking option alternatives.

TypeGeneral command.

AuthorityYou require OPER authority to issue the TRACKOPT command.

SyntaxTRACKOPT | TRACKOPT {[STC|NOSTC] [TSU|NOTSU] [SYSMSGS|NOSYSMSGS] [MASTER|SLAVE] [JAT|NOJAT] [TRACK_PURGE|NOTRACK_PURGE] [POST_OLDEST|NOPOST_OLDEST]}

Note: Entering TRACKOPT with no operands displays the current tracking options.Note: Entering TRACKOPT with any operands retains the current setting for any option without one of its two alternatives selected. This is the default.

Operands DescriptionSTC Indicates started tasks should be tracked.NOSTC Indicates tracking of started tasks should not occur.TSU Indicates TSO users should be tracked.NOTSU Indicates tracking of TSO users should not occur.SYSMSGS Indicates system messages should be intercepted.NOSYSMSGS Indicates interception of system messages should not occur.MASTER Indicates this as the MASTER system for Application processing.PROXY Indicates this as a PROXY system.JAT Indicates a Job Authorization Table is to be used. This only applies if you

are using ESP’s internal security.NOJAT Indicates Job Authorization Tables are not used. This only applies if you

are using ESP’s internal security.TRACK_PURGE Indicates jobs are tracked through the OUTPUT pnode.NOTRACK_PURGE Indicates jobs are not tracked through the OUTPUT pnode.POST_OLDEST Indicates External and Manual jobs are posted complete in the oldest

active generation of an Application.

1283

Usage notesIf no options are specified, the current tracking options are displayed. If an option is specified, it replaces the current setting for that tracking option.TRACKOPT should be specified on each system in a multi-access spool environment. It is normally specified as an ESP initialization parameter.The MASTER and PROXY keywords apply only to Application processing. One system should be identified as the MASTER system and any other systems should be identified as PROXY systems. All Events that create Applications should be scheduled on the MASTER system.TRACKOPT is normally specified as an initialization parameter. If you use the TRACKOPT command, options specified in the initialization parameters are overridden. The information is saved in the checkpoint data set, which means that it is retained across IPLs. However, for a cold start, any information specified in the initialization parameters is used.When an EXTERNAL or MANUAL job completes and multiple generations of an Application exist, ESP must decide which generation of the Application to post the job complete in. Use the POST_OLDEST or NOPOST_OLDEST keywords to control this.Most installations do not need to track jobs through to purge. If this is the case, TRACKOPT NOTRACK_PURGE should be specified. This allows data to be stored on ESP’s TRAKFILE for a longer period of time.

Related informationFor information on setting tracking options at the initialization parameter level, see the ESP Workload Manager Installation and Configuration Guide.For information on setting up tracking, see the ESP Workload Manager Installation and Configuration Guide.

Examples Displays tracking optionsIn the following example, current tracking options are displayed.OPER TRACKOPT

Following is an example response from the OPER TRACKOPT command.TRACKING OPTIONS: NOSTC NOTSU NOSYSMSGS MASTER NOTRACK_PURGE NOPOST_OLDEST

NOPOST_OLDEST Indicates External and Manual jobs are posted complete in all generations of an Application.

Operands Description

TRACKOPT Command: Set Various Tracking Options

1284

Sets tracking optionsIn the following example, started tasks and system messages are trackedOPER TRACKOPT STC SYSMSGS

Based on the initial settings in the first example, the response would be:

TRACKING OPTIONS: STC NOTSU SYSMSGS MASTER NOTRACK_PURGE NOPOST_OLDEST

Tracking of started tasks is turned offIn the following example, the tracking of started tasks is turned off.OPER TRACKOPT NOSTC

Based on the previous settings, the response would be:

TRACKING OPTIONS: NOSTC NOTSU SYSMSGS MASTER NOTRACK_PURGE NOPOST_OLDEST

1285

TRANSFERCODETYPE Statement: Specify FTP Format Within FTP_JOB

The TRANSFERCODETYPE statement specifies an ASCII, binary, or auto-detect transfer in an FTP_JOB workload object.

ApplicabilityESP System Agents, Release 6, used within an FTP_JOB workload object. For more information, see “FTP_JOB Statement: Identify the Name of FTP Jobs” on page 623.

SyntaxTRANSFERCODETYPE [A|B|U]

Usage notesTRANSFERCODETYPE is an alternative form of FTPFORMAT. Refer to “FTPFORMAT Statement: Specify FTP Format Within FTP_JOB” on page 625. TRANSFERCODETYPE is a required statement within the FTP_JOB workload object. TRANSFERCODETYPE can be a global statement.

ExamplesExample 1 (UNIX)In this example, the FTP format is binary (operand B).FTP_JOB FTPTEST6.DOWNLOAD AGENT R6AGENT USER test SERVERADDR hpunix SERVERPORT 21 TRANSFERDIRECTION D TRANSFERCODETYPE B REMOTENAME /u1/qatest/ftpdata/ESPmgr

Operand DescriptionA ASCIIB BinaryU Auto-detect

Note: You can only specify Auto-detect for uploads.

TRANSFERCODETYPE Statement: Specify FTP Format Within FTP_JOB

1286

LOCALNAME /export/home/qatest/ftpdata/transf.bin RELEASE FTPT17.UPLOAD RUN DAILY AFTER CHECK.PART1ENDJOB

1287

Example 2 (Windows)In this example, the FTP format is binary (operand B).FTP_JOB FTPTEST6.DOWNLOAD AGENT R6AGENT USER test SERVERADDR hpunix SERVERPORT 21 TRANSFERDIRECTION D TRANSFERCODETYPE B REMOTENAME /u1/qatest/ftpdata/ESPmgr LOCALNAME c:\qatest\ftpdata\transf.bin RELEASE FTPT17.UPLOAD RUN DAILY AFTER CHECK.PART1ENDJOB

TRANSFERDIRECTION Statement: Specify Transfer Direction Within FTP_JOB

1288

TRANSFERDIRECTION Statement: Specify Transfer Direction Within FTP_JOB

The TRANSFERDIRECTION statement specifies the direction of files to be transferred in an FTP_JOB workload object.

ApplicabilityESP 6 System Agents, Release 6, used within an FTP_JOB workload object. For more information, see “FTP_JOB Statement: Identify the Name of FTP Jobs” on page 623.

SyntaxTRANSFERDIRECTION U|D

Usage notesTRANSFERDIRECTION is an alternative form of DIRECTION. Refer to “DIRECTION Statement: Specify Transfer Direction Within FTP_JOB” on page 324.TRANSFERDIRECTION is a required statement within an FTP_JOB workload object. TRANSFERDIRECTION can be a global statement.

ExampleIn this example, the transfer direction is download (operand D).FTP_JOB FTPT17.UPLOAD AGENT R6AGENT USER test SERVERADDR hprsupp SERVERPORT 21 TRANSFERDIRECTION D FTPFORMAT A REMOTENAME /tmp LOCALFILENAME /export/home/qatest/ftpdata/text* RUN DAILY RELEASE FTPT18.UPLOADENDJOB

Note: For Windows examples, substitute a Windows path in the LOCALFILENAME statement.

Operand DescriptionU UploadD Download

1289

TRDFLT Command: Specify Installation Default

The TRDFLT command specifies an installation-default to be used when an Event is triggered manually.

TypeGeneral command.

AuthorityYou require OPER authority to issue the TRDFLT command.

SyntaxTRDFLT {ADD} {REPLACE}

Usage notesThe option you specify on the TRDFLT command applies until the next time ESP initializes. This command is normally specified as an ESP initialization parameter. You can override the TRDFLT setting when you use the TRIGGER command for an Event.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.For information of triggering Events, see the TRIGGER command.

Example In the following example, the installation default for manually triggered Events is set to ADD, for example, Events are triggered in addition to their regularly scheduled execution unless the REPLACE option is specified on the TRIGGER command.TRDFLT ADD

Operand DescriptionADD Indicates a manual trigger of an Event should be performed in

addition to the next scheduled execution.REPLACE Indicates a manual trigger replaces the next scheduled execution for

an Event. This is the normal default.

TRIGGER Command: Trigger Events Execution

1290

TRIGGER Command: Trigger Events Execution

The TRIGGER command is used to trigger the execution of an Event. The Event execution either replaces the next scheduled execution (that is, brings forward the next execution), or it can be a temporary addition to the schedule.

TypeGeneral Command

AuthorityTRIGGER can be issued either as an ESP operator (OPER) command or as an ESP general sub-command.

Syntax{TRIGGER|TR} eventid [REPLACE|ADD] [AT(trigtime)] [NOXEQ] [SYSTEM(sysid)] [FORCE|SATISFY] [USER1('userinfo')] [USER2('userinfo')] [USER3('userinfo')] [USER4('userinfo')] [HOLD] [ROOT(jobname...)] [UPPERCASE|UPPER | CASESENSITIVE|CS]

Operand Description

eventid Indicates the name of the Event to be triggered. If prefix is not specified, your current group prefix is used.

REPLACE Indicates this execution is to replace only the next scheduled execution of the Event. The TRDFLT initialization parameter sets the default.

ADD Indicates this execution is to be made in addition to the normal schedule. The normal schedule is not changed. The TRDFLT initialization parameter sets the default.

trigtime Indicates a time, and optionally a date, at which the trigger is to occur. If you use blanks or commas, enclose the string in quotes. If this operand is omitted, the current time is used. If this operand specifies a time/date in the past, the Event is triggered now.

NOXEQ Bypasses execution of the next scheduled Event.

1291

Usage notesWhen using the ADD option, the Event is scheduled for execution as if a SCHEDULE statement is being processed. The REPLACE option brings forward the next scheduled activity for that Event. If the next statement in the Event is a HOLD statement, it is processed by the TRIGGER, rather than by an execution of the Event. Before issuing a TRIGGER REPLACE, you should be aware of the next action to be processed for that Event. A TRIGGER ADD always causes the execution of an Event.Use the AT keyword to specify a future time and date for the trigger to occur. If the REPLACE option is used, the trigger replaces the next scheduled execution on or after the specified time. The ADD option results in an additional execution.The NOXEQ option is used to suppress an already scheduled Event execution. You can only bypass execution of the next scheduled Event. Use the LISTSCH command to display the schedule if you are unsure.

If you wish to re-trigger an Event that has already executed, you can use a trigger time in the past. Variables are resolved and jobs are selected based on this past date.

sysid Indicates the ID of the system on which you want the Event to execute.

FORCE Trigger Event ignoring any signals.

SATISFY Trigger Event satisfying any signals.

userinfo Indicates up to 68 characters of user data enclosed in single quotes.

HOLD Can be used to place an Application on hold when the Event being triggered generates an Application. No activity will take place in the Application until it is released using the APPLJOB command or CSF.

ROOT Indicates one or more jobnames belonging to the Application generated by this Event. This requests that only those jobs specified are to be submitted. Each jobname specification can be an individual jobname or can include a plus sign (+) to indicate that this job and all successors are to be selected. ESP builds the named jobs as part of the Application regardless of their frequency. Any successors of the named jobs will only be included if their other selection criteria (in terms of date and time) are satisfied.

UPPERCASE|CASESENSITIVE

Used to turn case translation on or off. UPPERCASE enables the translation, CASESENSITIVE disables it. UPPERCASE is the default. The following aliases may be used: CS for CASESENSITIVE and UPPER for UPPERCASE.

Note: When this operand is used to enforce case sensitivity it applies only to the operands that make up the trigger command. For example, if userinfo is specified and needs to be in lower case or mixed case, use CASESENSITIVE. CASESENSITIVE does not apply to any other statements or commands processed within the event or the procedure.

Operand Description

TRIGGER Command: Trigger Events Execution

1292

Triggering an Event for a time in the past does not honor DELAYSUB or EARLYSUB statements coded in an Application, unless REALNOW is used in the schedule criteria, for example, DELAYSUB REALNOW PLUS 10 MINUTES.The USER1-USER4 fields can be used to pass user data to the Event (and consequently any ESPPROC the Event invokes) being triggered. This user data replaces the %USER1-%USER4 variables, respectively, when they are encountered.Use the ROOT operand if you wish to build an Application of certain jobs. This is useful if you wish only to run, or rerun, part of an Application.If you trigger an Event manually, the SYSTEM identifier in the Event is ignored. To trigger an Event on a particular system, use the SYSTEM operand on the TRIGGER command.You can also trigger Events using ESP’s ISPF interface—Option E.3 from the ESP Main Menu.

Related informationFor information on Events, see the ESP Workload Manager User’s Guide.

Examples Triggers an EventIn the following example, the TRIGGER command brings forward the next scheduled execution of CYBER.PAYROLL for immediate execution assuming the TRDFLT initialization parameter is set to REPLACE.TRIGGER CYBER.PAYROLL

Triggers an Event at a specific timeIn the following example, the TRIGGER command brings forward the next scheduled execution of CYBER.PAYROLL and schedules it for 3 pm today.TRIGGER CYBER.PAYROLL AT('3PM TODAY')

Triggers an additional execution of an Event at a specific timeIn the following example, the TRIGGER command triggers an additional execution of CYBER.PAYROLL and schedules it for 9 am on JULY 1ST. TRIGGER CYBER.PAYROLL AT('9AM JULY 1ST') ADD

Suppresses an Event’s executionIn the following example, the TRIGGER command suppresses the execution of CYBER.PAYROLL. TRIGGER CYBER.PAYROLL NOXEQ

1293

Triggers an Event and passes user dataIn the following example, the TRIGGER command brings forward the next scheduled execution of CYBER.PAYROLL and passes user data, in this case a jobname, to an ESP Procedure invoked by this Event.TRIGGER CYBER.PAYROLL USER1('PAYJOB99')

Triggers an Event at a specific time to build an Application containing certain jobsIn the following example, the TRIGGER command brings forward the next scheduled execution of CYBER.PAYROLL and schedules it for 4 pm today. The Application invoked by this Event is built with jobs PAYJOB1, PAYJOB6, and PAYJOB6’s successors.TRIGGER CYBER.PAYROLL AT('4PM TODAY') REPLACE - ROOT(PAYJOB1,PAYJOB6+)

Triggers an Event for a time in the pastIn the following example, CYBER.PAYROLL is triggered as if it were yesterday. The Application invoked by this Event is built with jobs PAYJOB1, PAYJOB3, PAYJOB5, and PAYJOB5’s successors.Note: Any date-specific symbolic variables resolve to yesterday’s date. TRIGGER CYBER.PAYROLL AT('YESTERDAY') ADD - ROOT(PAYJOB1,PAYJOB3,PAYJOB5+)

Triggers an Event on a specific systemIn the following example, CYBER.PAYROLL executes on system ESPM. TRIGGER CYBER.PAYROLL SYSTEM(ESPM)

TRYJOIN Command: Join XCF Groups

1294

TRYJOIN Command: Join XCF Groups

The TRYJOIN command is used when an ESP subsystem could not join its XCF group when it was started.This occurs when, from within ESP, an ESP subsystem is started with a conflicting member name. For example, another active XCF member with the same name already exists.

Type General command.

AuthorityYou require OPER authority to issue the TRYJOIN command.

SyntaxTRYJOIN MEMBER(member)

MessageUpon successful initialization into the XCF group, the following message is issued:MESSAGE: 4303IESP xxxx has joined XCF group yyyy as member zzzz

Operand Descriptionmember Indicates the member name under which ESP joins the XCF group. It

can be up to 16 alphanumeric or national characters. It must not be specified as MISSING.This overrides the MEMBER operand in the SYSPLEX statement.

1295

UUNALLOC Command: Unallocate Data Sets

The UNALLOC command is used to unallocate a data set from ESP.Note: The UNALLOC command is only intended for use with non-operational data

sets. Operational data sets like the TRAKFILE and APPLFILE are opened for write when ESP Workload Manager starts and remain allocated until ESP Workload Manager is brought down.

TypeGeneral command.

AuthorityYou require OPER authority to issue the UNALLOC command.

SyntaxUNALLOC dsname

Usage notesThis command may be required when ESP won’t let go of a data set. This sometimes happens when a user uses some REXX code and does not free the file.

Related informationFor information on unallocating data sets preallocated with the PREALLOC command, see the PREALLOC command.

Example Unallocates a data set from ESPIn the following example, SYS3.ESP.TESTPROC is unallocated from ESP.OPER UNALLOC 'SYS3.ESP.TESTPROC'

Operand Descriptiondsname Indicates the data set name to be unallocated.

UNIX_JOB Statement: Identify the Name of UNIX Jobs

1296

UNIX_JOB Statement: Identify the Name of UNIX Jobs

Identifies the start of a UNIX job within an Application. UNIX_JOB defines the start of a job that runs on a UNIX machine and defines the name of the job. UNIX_JOB is a generic workload object that you can use with any UNIX operating system.

TypeApplication statement.

SyntaxRefer to the JOB statement syntax.

Usage notesTo use UNIX jobs, load the workload object module CYBESOUJ with the WOBDEF command, or with the WOBDEF initialization parameter.The short form of UNIX_JOB is UJ.The UNIX_JOB statement defines the beginning of a UNIX job definition. The ENDJOB statement, or another JOB or UNIX_JOB statement, signifies the end of a job definition.

You can define jobs in any order. ESP Workload Manager submits the jobs based on how you define job relationships.Refer to the JOB statement usage notes.

ExampleDefine an Agent jobIn this example, the UNIX job PAYDATA runs on a UNIX Agent, UNIX_NY. The UNIX Agent runs on UNIX operating system.

UNIX_JOB PAYDATA RUN DAILY RELEASE PAYRPT AGENT UNIX_NY SCRIPTNAME /usr/data/payENDJOB

1297

//* UNTIL Statement: Specify Limit Date for TEMPLIB

The //* UNTIL statement is used in combination with the TEMPLIB statement to indicate that temporary JCL for a job is to be used until a particular date. The TEMPLIB statement is used in an ESP Procedure to indicate a temporary/override JCL library.

TypeESP control statement used in JCL.

Syntax//* UNTIL criteria

Usage notesThe //* UNTIL statement is used in a JCL library that has been identified as a temporary JCL library using the TEMPLIB statement.A single blank separates //* and UNTIL.The //* UNTIL statement is only available in JCL and must start in card column 1 and must be the first statement in the JCL. ESP checks the UNTIL date to determine whether the JCL should be used. If no time is specified, the start-of-day time is used (default 00:00).ESP compares the scheduled time and date of the Event to the criteria on the //* UNTIL statement to decide whether or not it uses the JCL in the TEMPLIB for a job. If the //* UNTIL date and time has passed ESP uses the JCL from the last defined JCLLIB in the Application.

Related informationFor information on further limiting the window in which temporary JCL is used, see the //* FROM statement.For information on specifying a temporary/override JCL library, see the TEMPLIB statement.

Operand Descriptioncriteria Schedule criteria that resolve to a single date and time.

//* UNTIL Statement: Specify Limit Date for TEMPLIB

1298

Examples Limit usage - time and dateIn the following example, temporary JCL for PAYJOB1 is used until 9 am on May 24, 2004.//* UNTIL 9AM MAY 24,2004//PAYJOB1 JOB CYB,CLASS=A,MSGCLASS=0

Limit usage - dateIn the following example, temporary JCL for PAYJOB2 is used until 00:00 (default) on August 6, 2004.//* UNTIL AUGUST 6, 2004//PAYJOB2 JOB CYB,CLASS=A,MSGCLASS=O

Limit usage - range of datesIn the following example, temporary JCL for PAYJOB3 is used from 9 am on November 27, 2004 up to, but not including, 4 pm on November 30, 2004.//* FROM 9AM NOVEMBER 27, 2004//* UNTIL 4PM NOVEMBER 30, 2004//PAYJOB3 JOB CYB,CLASS=A,MSGCLASS=0

1299

USE Command: Display Event Statistics

The USE command is used to display statistics relating to Events, Applications and jobs. These statistics represent the activity for this ESP system only. No counts are shown for any ESP Workload Manager proxy systems or any other remote ESP Workload Manager systems.

TypeESP Main Menu command.

SyntaxUSE

Usage notesEnter the USE command from the ESP main menu or the ESPCTR command from Page mode to display ESP internal activity. Both commands produce the same results but the formatting of those results is different.Use the USE command to displays statistics on Applications completed, Applications created, Events executed and jobs submitted. These activities are measured on the following intervals: this year, this month, this day, and since last ESP start. These counters are reset with an ESP cold start or with the ESPCTR command.

Related informationThe ESPCTR command displays the same information from the page mode. ESPCTR can also reset the following counters:• APPCMP: number of Applications completed• APPCRE: number of Applications created• EVEXQ: number of Events executed• JOBSUB: number of jobs submitted by ESP Workload Manager

USE Command: Display Event Statistics

1300

Example Display ESP internal activities This This This Since Last

Activity Year Month Day ESP Start

------------------------------------------------------Applicationscompleted 499 499 13 143

Applicationscreated 737 737 27 211

Eventsexecuted 2220 2220 43 594

Jobssubmitted 1190 1190 13 365

1301

USER Command: Identify Users as Valid ESP User

The USER command is used to identify you as a valid ESP user when invoking ESP in batch. This command is not necessary if you are using a security product.

TypeGeneral command.

SyntaxUSER userid/password

Usage notesWhen your user ID was defined, a password was assigned to it. The PASSWORD command is used to change your password.

Related informationFor information on altering the ESP password associated with your user ID, see the PASSWORD command.

Example Identifies a valid ESP userIn the following example, USER01 is identified as a valid ESP user.//JOB1 JOB …...//S1 EXEC PGM=ESP,REGION=4000K//SYSPRINT DD SYSOUT=*//SYSIN DD *USER USER01/APPLES

Operand Descriptionuserid Indicates your user ID.password Indicates your current ESP password.

USER Statement: Define User IDs

1302

USER Statement: Define User IDs

Specifies the user ID under which to run the Agent job.

TypeApplication statement.

Authority You require READ access to the AGENTUSR.userid.agentname resource in an SAF environment.

SyntaxUSER [domain\] userID

Usage notesUse the USER statement within the boundaries of a job definition to apply to a single job, or outside the boundaries of the job definition to apply to the entire Application.

Considerations for OS/400 AgentsThe OS/400 Agent defaults to using the user’s default library list if the USER statement is used in a job definition, and no libraries have been specified with the LIBL statement.If the USER statement is used in a OS/400 Agent job definition and if the OTHER statement does not include the SBMJOB command keyword and value combination OUTQ( ), the Agent defaults to the user’s default output queue.

Considerations for Windows Agents

ESP Workload Manager user ID and passwordTo run a job under a Windows user ID and password, you must define user ID and password pairs using the ESP Workload Manager PASSWORD command.

Operand Descriptiondomain Optional. For an NT_JOB workload object, you can specify a user ID

in a specific DOMAIN by providing the DOMAIN name with the user ID.

Note: This option is only for an NT_JOB workload object.userID The user ID to use when running the job; must be a valid user ID.

1303

Special Windows rightsTo run a job on Windows, the Agent also requires special rights from the operating system.

To verify that the Agent has the required special rights:1. On the Windows desktop, click Start > Programs > Administrative Tools > User

Manager.2. Click Policies on the menu bar.3. Click User Rights on the drop down menu.4. Refer to the Show Advanced User Rights option on the bottom left corner of the

User Rights Policy window.5. Select Act as Part of the Operating System.If the user ID that the Agent is installed with is listed in the Grant To list, then the Agent has the special rights. If the user ID is not listed, have your Security Administrator grant the rights.

Considerations for UNIX AgentsThe USER statement is required with the CMDNAME statement (when running a binary file). It is optional with the SCRIPTNAME statement.

If you use the Agent Security File to restrict the running of workload to specific users, use the USER statement in your job definitions to define the user IDs under which you want the jobs run.

If you run the Agent as root and specify a USER statement in the job definition, the Agent can run the command or script with the user’s environment and permissions. The environment is passed unchanged, as if the Agent logged in as the specified user.

If you run the Agent as root, then by default the parameter oscomponent.initialworking directory is set to the Agent directory. You should grant OTHER execution permission for the Agent directory and the root home directory, or you will get an error message indicating that permission is denied when attempting to run a script or command.

Note: For more information on running a script or binary file under a specific user’s account, see the ESP System Agent Guide to Scheduling Workload.

Related informationThe USER statement requires the PASSWORD command. Refer to the PASSWORD command for information on how to manage passwords.

USER Statement: Define User IDs

1304

ExamplesAS400 AgentAPPL INVENTRY AS400_JOB MFGDATA RUN DAILY AGENT AS401 USER JOHNDOE RELEASE MFGSORTENDJOB

Windows NT AgentAPPL PAYROLLNT_JOB PAY RUN DAILY AGENT NT401 USER JOHNDOE CMDNAME c:\payroll\sort.exeENDJOB

UNIX AgentAPPL PAYROLLUNIX_JOB MFTEST RUN DAILY AGENT UNIX_LA SCIPTNAME /mfg/test1.ksh USER JOHNDOEENDJOB

operandUNIX_JOB PAYROLL.SORTUNIX_TOR/home/////ENDJOB

1305

USERMOD Command: Define User Modifications

The USERMOD command is used to define the ESP user modifications to be implemented.

TypeGeneral command

AuthorityYou require OPER authority to issue the USERMOD command.

SyntaxUSERMOD [SET(usermodid[:usermodid])] [RESET(usermodid[:usermodid])] [LIST]

Usage notesUser modification status is preserved across a restart of ESP, but not an IPL.You can specify both SET and RESET in the same USERMOD statement. In this case, SET is processed before RESET.USERMODs are normally set in the ESP initialization parameters.

Related informationFor information on activating the usermods available with ESP, see the ESP Workload Manager Installation and Configuration Guide.

Examples Displays USERMODsIn the following example, active USERMODs are displayed.OPER USERMOD LIST

Turns on a USERMODIn the following example, USERMOD 33 is activated.OPER USERMOD SET(33)

Operand Descriptionusermodid Indicates a number, list of numbers, or range of numbers from 1-255.SET Turn on the usermod.RESET Turn off the usermod.LIST List the active usermods.

USERMOD Command: Define User Modifications

1306

Turns on two USERMODsIn the following example, USERMODs 33 and 36 are activated.OPER USERMOD SET(33,36)

Turns on a range of USERMODsIn the following example, USERMODs 33, 34, 35, and 36 are activated.OPER USERMOD SET(33:36)

Turns off a USERMODIn the following example, USERMOD 33 is deactivated. OPER USERMOD RESET(33)

Activates user modificationsIn the following example, USERMODs 1, 5-7, 18, and 22-27 are activated.OPER USERMOD SET(1,5:7,18,22:27)

Activates and deactivates user modificationsThe following USERMOD command activates and deactivates user modifications:OPER USERMOD SET(5:9) RESET(7)

In the above example, because SET is processed before RESET, the results of the above example are as follows: • USERMODs 5-9 are activated• USERMOD 7 is deactivated.

1307

VVARIANT Statement: Specify Variant Name (SAP)

The VARIANT statement specifies the name of the variant and is mandatory if the ABAP program requires it.

ApplicabilityESP Business Agents for SAP, Version 1 and higher.

Syntax VARIANT variant

Usage notesUse the VARIANT statement before the first ABAPNAME statement to set the default value for subsequent steps.Use the VARIANT statement within the boundaries of the step definition (between two ABAPNAME statements or between an ABAPNAME statement and ENDJOB statement) to define the value for that step.VARIANT corresponds to the SAPGUI ABAP program Variant field on the Create Step dialog.

ExampleIn this example, the variant named TEST will be used with ABAP BTCTEST.APPL SAPTEST SAP_JOB SAPTEST AGENT SAPHTAGENT STARTMODE I RUN DAILY ABAPNAME BTCTEST STEPUSER USER14 VARIANT TEST SUCCESSMSG 'Program Selections'ENDJOB

Operand Descriptionvariant Specifies the name of the variant. variant is case sensitive and

can be up to 14 valid SAP characters in length.

VDEL Command: Delete Global Variables

1308

VDEL Command: Delete Global Variables

The VDEL command is used to delete a global variable.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVDEL (vname1[,vname2]…[,vnamen]) TABLE(tablename)

ExampleIn the following example two global variables V1 and V2 are deleted from the global variable table named MYTABLE.VDEL (V1,V2) TABLE(MYTABLE)

Operand Descriptionvname Specifies the name of the global variable. The maximum length of

the global variable name is 64 characters.tablename Specifies the name of the global variable table. The maximum

length of the global variable table name is eight characters.

1309

VGET Command: Retrieve Global Variables

The VGET command is used to retrieve global variables from a global variable table.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVGET (vname1[,vname2]…[,vnamen]) TABLE(tablename) REXX|CLANG

Usage Notes: All retrieved global variables are considered as character variables. If a global variable is numeric and you anticipate doing calculations with that global variable, you must declare it as an integer before using the VGET command.

ExampleIn the following example, we store two global variables V1 and V2 in the global variable table named MYTABLE. We retrieve those global variables in a second procedure.Procedure 1:INTEGER V1V1=2V2='TORONTO'VPUT(V1,V2) TABLE(MYTABLE) CLANG

Operand Descriptionvname Specifies the name of the global variable. The maximum length of

the global variable name is 64 characters.tablename Specifies the name of the global variable table. The maximum

length of the global variable table name is eight characters.REXX Indicates the global variable is stored in the REXX format.CLANG Indicates the global variable is stored in the CLANG format.

VGET Command: Retrieve Global Variables

1310

Procedure 2: INTEGER V1VGET (V1,V2) TABLE(MYTABLE) CLANGV3=%V1*2SE 'V2 = %V2 AND V3 = %V3' U(*)

Result of procedure 2

V2 = TORONTO AND V3 = 4

1311

VINCR Command: Increment Numeric Global Variables

The VINCR command is used to increment numeric global variables by one. If the variables do not exist, they are created with a value of one.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVINCR (vname1[,vname2]…[,vnamen]) TABLE(tablename) REXX|CLANG

Example In the following example, we store a global variable V1 equal to 15, then we increment V1 and create another global variable V2 equal to one. INTEGER V1V1 = 15VPUT (V1) TABLE(MYTABLE) CLANGVINCR (V1,V2) TABLE(MYTABLE) CLANG

Operand Descriptionvname Specifies the name of the global variable. The maximum length of the

global variable name is 64 characters.tablename Specifies the name of the global variable table. The maximum length

of the global variable table name is eight characters.REXX Indicates the global variable is stored in the REXX format.CLANG Indicates the global variable is stored in the CLANG format.

VPUT Command: Store Global Variables

1312

VPUT Command: Store Global Variables

The VPUT command is used to store one or more variables in a global variable table.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVPUT (vname1[,vname2]…[,vnamen]) TABLE(tablename) REXX|CLANG

Usage noteVPUT will fail if the variables are not previously defined.

Example In the following example two CLANG variables are defined are stored in the global variable table named MYTABLE: V1 = 'ONE'V2 = 'TWO'VPUT (V1,V2) TABLE(MYTABLE) CLANG

Operand Descriptionvname Specifies the name of the global variable. The maximum length

of the global variable name is 64 characters. A value must be associated with the variable name. The maximum length of the value is 255 characters.

tablename Specifies the name of the global variable table. The maximum length of the global variable table name is eight characters.

REXX Indicates the global variable is stored in the REXX format.CLANG Indicates the global variable is stored in the CLANG format.

1313

VS Command: Issue Commands to the Operating System

The VS command is used to issue a command to the operating system.

TypeGeneral command.

AuthorityYou require OPER authority to issue the VS command. Some commands may have been restricted by your security system or by a user exit.

SyntaxVS 'commandtext' [CS] [CONSNAME(consname)|[CONSID(consid)|UCMID(consid)]]

Usage notesYou can use VS to issue operation system command such as JES commands and z/OS commands, including ESP Workload Manager operator commands. Multiple VS commands are allowed in an Event. VS commands can be issued from an ESP Procedure. z/OS preserves lower case characters in strings enclosed in single quotes. When the CS operand is present, the VS command follows this rule.

Operand Descriptioncommandtext Indicates the text of the command, enclosed within quotes. If the text

contains embedded quotes, they should be doubled up.CS Requests case-sensitive processing of commandtext.CONSNAME(consname)

The name of the console to send the command response to. You must specify an existing console name.

CONSID(consid)|UCMID(consid)

The ID of the console to send the command response to. UCMID is an alias of CONSID. You must specify an existing console ID.

VS Command: Issue Commands to the Operating System

1314

If you do not specify CONSNAME or CONSID in the VS command:• If MCS is active (either by default or as a result of the OPER MCS ACTIVATE

command), the command is issued to the extended MCS console for the local ESP Workload Manager subsystem. The MCS console then retrieves the command response and sends it back to the user.

• If MCS is not active (as a result of the OPER MCS DEACTIVATE command), the command is issued to console name INTERNAL (console ID 0). The response does not come back to the issuer.

If you specify CONSNAME or CONSID in the VS command, the VS command is issued to that console. The response does not come back to the issuer. The VS command and response are not listed in the SYSLOG data set.

Related informationFor information on issuing operating system commands, see the ESP Workload Manager User’s Guide.

Examples Issue a JES2 commandIn the following example, initiators 1 through 10 are started at 6 am daily.EVENT ID(CYBER.INIT_START)SCHEDULE 6AM DAILYVS '$SI1-10'ENDDEF

Start a started taskIn the following example, IMS10 is started at 6 am daily.EVENT ID(CYBER.START_IMS)SCHEDULE 6AM DAILYVS 'S IMS10'ENDDEF

Trigger an EventIn the following example, a VS command is placed within a job definition to trigger CYBER.BACKUPS.JOB MORE.WORK LINK PROCESS RUN DAILY VS 'F ESPM,TRIGGER CYBER.BACKUPS'ENDDEF

Shut down a started taskIn the following example, CICS is shut down at 6 am daily.

1315

EVENT ID(CYBER.START_IMS)SCHEDULE 6AM DAILYVS 'F CICS,CSMT SHU,Y'ENDDEF

Specify a console to send the command response toThe response to the following command is sent to a console named SYSACON3:VS 'D A' CONSNAME(SYSACON3)

The response to the following command is sent to a console with an ID of hexadecimal 80:VS 'D A' CONSID(X'80')

VSET Command: Set Global Variables

1316

VSET Command: Set Global Variables

The VSET command is used to create a new global variable or change the value of an existing global variable. This change may be conditional to the old value being equal to a specified value.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVSET vname value TABLE(tablname) [OLDVAL(ovalue)

ExampleIn the following example the value of the global variable V1 in the global variable table named MYTABLE is set to TORONTO if the value of V1 is equal to CHICAGO.VSET V1 TORONTO TABLE(MYTABLE) OLDVAL(CHICAGO)

Operand Descriptionvname Specifies the name of the global variable. The maximum length of

the variable name is 64 characters.value Indicates the new value of the global variable. The maximum

length of the value is 200 characters. tablname Specifies the name of the global variable table. The maximum

length of the global variable table name is eight characters.ovalue Indicates the old value of the global variable.

1317

VTDEFINE Command: Define Global Variable Tables

The VTDEFINE command is used to create a new global variable table.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVTDEFINE tablename

Example In the following example a global variable table named MYTABLE is created:VTDEFINE MYTABLE

Operand Descriptiontablename Specifies the name of the global variable table. The maximum

length of the global variable global variable table name is eight characters.

VTDELETE Command: Delete Global Variable Tables

1318

VTDELETE Command: Delete Global Variable Tables

The VTDELETE command is used to delete an existing global variable table.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVTDELETE tablename

ExampleThe following example deletes the global variable table named MYTABLE. VTDELETE MYTABLE

Operand Descriptiontablename Specifies the name of the global variable table. The maximum length

of the global variable table name is eight characters.

1319

VTLIST Command: List Global Variable Tables

The VTLIST command is used to display the global variable tables.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVTLIST [tablename|tablename-spec] [CONCISE|VERBOSE|DUMP][TRIGGERS[(Idlist)]] [VARS[(namelist)]]

Operand Descriptiontablename Specifies the name of the global variable table. The maximum

length of the global variable table name is eight characters.tablename-spec Indicates a number of global variable tables by listing them or

by using masking. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking.

CONCISE Indicates the list is displayed in its short form. Only global variable and global variable trigger information is displayed.

VERBOSE Indicates the list is displayed in its long form. Includes statistical information about the table and its variables. This is the default.

DUMP Indicates the dump is to be displayed.TRIGGERS(Idlist) Indicates the list will include only the global variable triggers

with IDs included in Idlist. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. This is an optional operand. If you don’t specify Idlist, all the global variable triggers will be displayed.

VTLIST Command: List Global Variable Tables

1320

ExampleThe following example displays global variable tables, in verbose format, for all global variable tables with a name starting with my.vtlist my-

Global Variable Table MYNEXTT Created at 11.26.42 on TUESDAY MAY 29TH, 2001 by CYBER01 Last update at 11.26.42 on TUESDAY MAY 29TH, 2001 Currently 1 variable, table size 352PARM3='moretext'Global Variable Table MYTABLE Created at 11.26.28 on TUESDAY MAY 29TH, 2001 by CYBER01 Last update at 11.26.28 on TUESDAY MAY 29TH, 2001 Currently 2 variables, table size 392ABC='1'PARM1='text'VTRIG ID(MYTR) DefinedBy(CYBUSER) Var(V1) Event(CYBEVT.ABC)

VARS(namelist) Indicates the list will include only the global variables with names included in namelist. Wildcard characters asterisk and hyphen (see “Overview” at the beginning of this book) can be used to perform masking. This is an optional operand. If you don’t specify namelist, all the global variables will be displayed.

Operand Description

1321

VTRDEF Command: Define Global Variable Triggers

The variable trigger will trigger an event when a global variable from a global variable table is changed. This change can happen through a VSET, VPUT, or a VINCR command resulting in the specified global variable changing.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVTRDEF[ID(id)] VARIABLE(vname) TABLE(tablename) EVENT(eventname) [WHEN('target string')]

Usage NotesESP Workload Manager will assign a sequential numeric ID to a global variable trigger if you do not assign one with the VTRDEF command or if the ID you specified contains invalid characters. Use the VTLIST command or the ESP Workload Manager response to the VTRDEF command to verify a trigger has the name you intended.

Operand Descriptionid Identifies the variable trigger. Can be up to four alphabetic,

numeric or national characters. If you do not specify an ID, ESP Workload Manager will assign a sequential numeric ID. Definitions with an ID longer than four characters will be rejected.

vname Specifies the name of the global variable. The maximum length of the global variable name is 64 characters. This is the global variable that will trigger the event if it is changed to match the criteria in the target string, where specified.

tablename Specifies the name of the global variable table. The maximum length of the global variable table name is eight characters.

eventname Indicates the Event name to be triggered when the global variable changes.

target string Indicates the value the global variable changes to. When the value changes to what is specified in this string, the Event is triggered.

VTRDEF Command: Define Global Variable Triggers

1322

Examples:In the following example Event CYBER.MINE will only be triggered if the value of ABC changes to YES. If it changes to anything else, the Event will not be triggered.VTRDEF VARIABLE(ABC) TABLE(XYZ) EVENT(CYBER.MINE) WHEN('YES')

In this second example the event CYBER.MYEVENT is triggered when the global variable VT1 of the global variable table named MYTABLE changes.VTRDEF ID(TR07) VARIABLE(VT1) TABLE(MYTABLE) + EVENT(CYBER.MYEVENT)

Variables passed when event is triggeredThe following variables are available to an Event triggered by the change of a designated global variable:

Variable DescriptionESPVTVARIABLE Specifies the name of the modified global variable.ESPVTTABLE Specifies the name of the global variable table containing

the modified global variable.ESPVTOLDVALUE Specifies the value of the modified global variable prior

to modification.ESPVTVALUE Specifies the value of the modified global variable after

the modification.ESPVTUSER Specifies the user who made the modification.

1323

VTRDEL Command: Delete Global Variable Triggers

The VTRDEL command is used to delete a global variable trigger.

TypeGeneral Command.

Authority Security can be set with the following SAF rule:VARTABLE.tablename controls the user’s access to one or more global variable table, where tablename is the name of a global variable table.

SyntaxVTRDEL ID(id) TABLE(tablename)

Usage notes It is important to note if you delete a global variable that a trigger is monitoring, you delete the trigger also.

ExampleIn the following example the global variable trigger TR07 is deleted from the global variable table named MYTABLE.VTRDEL ID(TR07) TABLE(MYTABLE)

Operand Descriptionid Indicates the trigger ID. The maximum length of the ID is four

characters. Use the VTLIST command to find the ID for a global variable trigger.

tablename Specifies the name of the global variable table. The maximum length of the global variable table name is eight characters.

WEBPOSTING Statement: Post SAP Job Log and Spool on Web

1324

WWEBPOSTING Statement: Post SAP Job Log and Spool on Web

The WEBPOSTING statement specifies whether to post the SAP job log and spool on the web.

ApplicabilityESP Business Agents for SAP, Release 5 and higher, used within an SAP_JOB workload object.

SyntaxWEBPOSTING Y|N

Usage notesWEBPOSTING is an optional statement within an SAP_JOB workload object.

ExampleAPPL SAPTESTSAP_JOB SAPTEST AGENT SAPHTAGENT WEBPOSTING Y ABAPNAME BTCTEST RUN DAILYENDJOB

Operand DescriptionY Posts SAP job log and spool on the webN Does not post SAP job log and spool on the web

1325

WILDCARD Command: Define Wildcards for JTDT

The WILDCARD command is used to define wildcard characters for use in defining tracked jobs. These characters are in addition to the asterisk * and hyphen - wildcard characters.

TypeGeneral command

ApplicabilityJob Tracking Definition Table.

SyntaxWILDCARD char string

Usage notesThe wildcard character can be any printable character, with the exception of the comma, blank, left or right parentheses, semicolon or quote. A hyphen between two characters indicates a range of valid characters, starting with the character on the left and extending through the EBCDIC sequence to the character on the right, inclusive.Use of the WILDCARD command is optional. It can be used when you have strict naming standards for jobs.

Related informationFor information on tracking definition entries in a job tracking definition table, see the TRACKDEF command.For information on job tracking definition tables, see the ESP Workload Manager Installation and Configuration Guide.For information on loading job tracking definition tables (JTDT), see the LOADJTDT command.

Operand Descriptionchar Wildcard character.string Consists of a string containing all the valid characters that the

wildcard can match.

WILDCARD Command: Define Wildcards for JTDT

1326

Examples The following is an example of a job tracking definition table:WILDCARD # 0–9 /* NUMERICS */WILDCARD $ A–Z /* ALPHABETICS */WILDCARD + 0–9A–Z /* ALPHANUMERIC */TRACKDEF JOB NAME(DUMMYJOB) NOTRACKTRACKDEF JOB NAME(PAY–) MODEL(PAYMODEL)TRACKDEF JOB NAME($$$$####) MODEL(PRODJOBS)

In the above example:• The first wildcard character # matches all numeric characters• The $ wildcard character matches the alphabetic characters, A through Z,

inclusive• The + wildcard character matches the alphanumeric characters, A through Z,

inclusive, and the digits 0 through 9, inclusive

• The first tracking definition statement indicates ESP does not track a job called DUMMYJOB.

• The second tracking definition statement indicates ESP uses model PAYMODEL to track jobs where names begin with PAY.

• The third tracking definition statement indicates ESP uses tracking model PRODJOBS to track jobs whose names consist of four alphabetic characters followed by four numeric characters.

1327

WLM Command: Display Service Policies

The WLM command is used to display the active IBM WLM service policy on the local z/OS system.

TypeGeneral command

SyntaxWLM {DISPLAY|D} [STATUS|ST] [SYSTEM|SYS|S]

Related informationFor more information on XCF Services, see the ESP Workload Manager User’s Guide.

Examples The following is a sample response from the WLM DISPLAY STATUS command:WLM D ST

WLM System Status Local system name.............:SYSA System mode.................:Goal Active service policy.......:POLICY_A Activation time.............:1999/06/04 14:52:01 Service definition..........:CYBWLMA0 Definition time..... .......:1999/06/04 14:51:32 OPT parmlib member..........:IEAOPT00 Remote system name........... :SYSC System mode.................:GOAL

Operand DescriptionSTATUS Displays WLM definitions about the local system in the sysplex, and

a list of remote systems in the sysplex and their WLM modes (goal or compatibility).

SYSTEM Displays resource/capacity information on all goal mode systems in the sysplex.

WLM Command: Display Service Policies

1328

The following is a sample response from the WLM DISPLAY SYSTEM command:WLM D S

Sysplex SYSAPLEX Goal Mode Systems System name...................:SYSA Online CPUs.................:2 CPU SU per second capacity..:1934 Free CSA bytes..............:3468503 Free ECSA bytes.............:47925543 Resource constrained........:No System name...................:SYSC Online CPUs.................:2 CPU SU per second capacity..:1934 Free CSA bytes..............:3558560 Free ECSA bytes.............:60581635 Resource constrained........:No

1329

WOBCMD Command: Run Job-specific Commands

Runs job-specific commands, including the WSF command.

TypeGeneral command.

SyntaxWOBCMD APPLICATION(applname.applgen) JOB(jobname.qualifier) COMMAND(command)

ExamplesIn this example, the WSF command is used to retrieve spool file data for the job check.date that was run in the third generation of the Application unagtest.

WOBCMD APPL(unagtest.3) JOB(check.date) COMMAND(WSF)

When entering the WOBCMD command from CSF, type ESP before the command:

Retrieving Spool File DataWhen a job that runs under the control of an Agent completes, the Agent writes output to a spool file. You can use the WOB Spool File (WSF) command to view this output from the host (that is, the machine on which Workload Manager is running). You can enter the command:

• In CSF (Refer to ESP Workload Manager User’s Guide or ESP Workload Manager Operator’s Guide)

• Via the WOBCMD command

Operand Descriptionjobname.qualifier Specifies the job for which you want to retrieve spool file data.applname.applgen Specifies the Application in which the identified job is run.command Specifies the command to run. To retrieve spool file data, run the WSF

command.

WOBCMD Command: Run Job-specific Commands

1330

Using the WSF command to retrieve spool file data

Entering the WSF command via the WOBCMD commandYou can enter the WOBCMD command from:

• Page mode• Line mode• CSF• The system consoleWhen entering the WOBCMD command from CSF, type ESP before the command:

ESP WOBCMD APPL(unagtest.3) JOB(check.date) COMMAND(WSF)

As shown in this example, specify the Application name and job name to identify the job for which you want to view output.

1331

WOBDATA Statement: Retrieve Data From Data Object

The WOBDATA statement retrieves variables from the data object.

SyntaxVAR = WOBDATA('object','variable')

Usage notes Data can be retrieved, at process time, by using the WOBDATA CLANG function. The WOBDATA function returns a null value at any other time. for example in generate or simulate mode. Data can be retrieved from a Data_Object in another APPL as well. Data can be retrieved from a completed APPL as long as the ATR has not been overwritten.

Related informationRefer to the DATA_OBJECT and ESPmgr commands in ESP Workload Manager Reference Guide Volume 1. Refer to the SETVAR command.

Example Assigning to ABC the value of the variable VAR1 retrieved from theData Object DATA2. ABC = WOBDATA('DATA2','VAR1')

Operand Descriptionobject Is the name of the data object. This can be a simple job name

(Example: DATA1) or a fully qualified name including qualifier, APPL name and generation. (Example: DATA1.A/APPL.23.) Relative generations are also acceptable.

variable Is the name of the variable as stored in the data object. Both variable name and value are case sensitive. If a variable that does not exist is requested, a null value is returned.

WOBDEF Command: Define Workload Objects

1332

WOBDEF Command: Define Workload Objects

The WOBDEF command is used to display or load the modules that ESP Workload Manager requires to add support for agent jobs and other special workload objects in its applications. The workload object will not work if its corresponding module is not loaded.

TypeAuthorized OPER Command

SyntaxWOBDEF LOAD(module1[{ |,} module2 ...])|DISPLAY

Usage Notes:The WOBDEF command is normally included in the ESP Workload Manager initialization parameters to load the Agent Definition each time ESP initializes.You can use the WOBDEF command to dynamically load new modules while ESP Workload Manager is active, but not to load an updated version of a module already loaded. ESP Workload Manager must be re-initialized to activate the updated module.Issuing the WOBDEF command loads the module until the next restart. The initialization parameter loads it at the next startup.The following table shows the valid workload object types, the corresponding module names and their description:

Operand Descriptionmodule Specifies the name of the ESP Workload Manager module required

to support a specific type of workload. When listing more than one module, they must be delimited by a comma or space.

DISPLAY Lists the currently loaded workload object support modules.

Workload object Type Module Name Module DescriptionAGENT_MONITOR or AM CYBESOAM Agent monitor.AIX_JOB or AX CYBESOAX AIX Agent.APPLEND or AE CYBESOAE APPLEND (End of Application).AS400_JOB or A4 CYBESOA4 OS/400 Agent.CPU_MON or CM CYBESOCM CPU monitor Agent.DATA_OBJECT or DA CYBESODA Data Object.DB_JOB or DM CYBESODM Database job Agent (Perform SQL

updates and queries against a database).

1333

ExamplesDynamically load two agent modulesThis command loads the extension required to support the generic UNIX agent and the agent for OS/400:WOBDEF LOAD(CYBESOUJ CYBESOA4)

Display modules currently loadedThis command displays the modules currently loaded in ESP Workload Manager:WOBDEF DISPLAY

DISK_MON or HM CYBESOHM Disk monitor Agent.DSTRIG or DT CYBESODT Data-set Trigger.EVENTLOG_MON or LM CYBESOLM Windows event monitor Agent.EXTMON or EX CYBESOEX EXTMON (Monitor a job controlled

on an external scheduler, for example ESP Espresso).

FILE_TRIGGER or FM CYBESOFM File trigger.FTP_JOB or FT CYBESOFT FTP job Agent (Perform FTP file

operations).HPUX_JOB or HP CYBESOHP HP-UX Agent.IP_MON or IM CYBESOIM IP address or port monitor Agent.LINUX_JOB or LJ CYBESOLJ Linux Agent.NCR_JOB or NC CYBESONC NCR Agent.NT_JOB or NT CYBESONT Windows NT Agent.OPENVMS_JOB or OV CYBESOOV OpenVMS Agent. PROCESS_MON or PM CYBESOPM Process monitor Agent.PS_JOB or PS CYBESOPS PeopleSoft Agent.SAP_JOB or SP CYBESOSP R/3 ERP Systems Agent.SEQUENT_JOB or SQ CYBESOSQ IBM DYNIX/ptx (SEQUENT)

Agent. SERVICE_MON or SM CYBESOSM Windows service monitor Agent.SUN_JOB or SJ CYBESOSJ SOLARIS Agent.TANDEM_JOB or TA CYBESOTA TANDEM NSK Agent.TEXT_MON or TM CYBESOTM text file monitor Agent.UNIX_JOB or UJ CYBESOUJ Generic UNIX—supports LINUX,

TRU64 UNIX, and UNIX System Services.

Workload object Type Module Name Module Description

WORKMGR Command: Define Enclave support

1334

WORKMGR Command: Define Enclave support

The WORKMGR command connects ESP Workload Manager to IBM z/OS Workload Manager. The WORKMGR command may also be defined as an initialization parameter. Note: Issuing WORKMGR command without any operand displays the current

setting of WORKMGR.

TypeOPER command.

AuthorityYou require OPER authority to issue the WORKMGR command.

SyntaxWORKMGR SUBSYSTEM_TYPE|SST(subsystemtype)SUBSYSTEM_NAME|SSN(subsystemname) ENCLAVES|NOENCLAVES

Examples The following example uses the full statement syntax:OPER WORKMGR SST(ESP) SSN(P520) ENCLAVES

Once ESP Workload Manager is connected to IBM z/OS Workload Manager, all enclaves run under the defined subsystem type and name.Disable/enable EnclavesOnce you have defined the subsystem type and the subsystem name, you can disable and enable enclaves from ESP page mode by entering the following commands:OPER WORKMGR NOENCLAVES

Operand Descriptionsubsystemtype Subsystemtype specifies the type of subsystem. The default is

ESP. It is not recommended to override this default. ESP does not permit subsystem types like CICS and IMS. Other IBM subsystems are also not permitted.

subsystemname Subsystemname specifies the name of the ESP subsystem. This is an eight-character field. The default is the ESP subsystem ID, determined by the SUBSYS parameter in the initialization parameter data set.

ENCLAVES Indicates support for enclaves is enabled.NOENCLAVES Indicates support for enclaves is disabled.

1335

OPER WORKMGR ENCLAVES

Displaying EnclavesThe following command displays the current setting of WORKMGR:OPER WORKMGR

ESP4430I Connected to WLM, SST=ESP, SSN=P520, Enclave support enabled

XCF DELETE Command: Remove Members

1336

XXCF DELETE Command: Remove Members

The XCF DELETE command is used to remove quiesced or failed XCF members from the XCF group.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {DELETE|DEL} {MEMBER|M} member

Examples Displaying the member to Delete. The following display shows XCF member QS10S2 as quiesced:XCF DISPLAY GROUP

Group=QS10 Member=QS10M3 Interval=60 TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusQS10 QS10M1 SYSC 0056 QS10 QS10 Shadow ActiveQS10 QS10M3 SYSA 009B QS10SHAD QS10 Master ActiveQS10 QS10M5 SYSC 0041 QS10SMC QS10 Shadow ActiveQS10 QS10S SYSA 009F QS10S QS1S Proxy ActiveQS10 QS10S2 SYSC 0046 QS10S2 QS12 Proxy Quiesced

Operand Descriptionmember Indicates the name of the ESP member you want to delete from the

XCF group.

1337

Issuing the DELETE commandThe following example shows removing XCF member QS10S2:XCF DELETE MEMBER QS10S2

ESP4234I XCF member QS10S2 deleted, Group=QS10

Confirming the member is deletedThe following display shows the XCF group with the quiesced member removed:XCF DISPLAY GROUP

Group=QS10 Member=QS10M3 Interval=60 TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusQS10 QS10M1 SYSC 0056 QS10 QS10 Shadow ActiveQS10 QS10M3 SYSA 009B QS10SHAD QS10 Master ActiveQS10 QS10M5 SYSC 0041 QS10SMC QS10 Shadow ActiveQS10 QS10S SYSA 009F QS10S QS1S Proxy Active

XCF DISPLAY Command: View XCF Attributes

1338

XCF DISPLAY Command: View XCF Attributes

The XCF DISPLAY command is used to view system attributes of your XCF group.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {DISPLAY|D} {ACTIVE|A} {GROUP|G} {SERVICE|S} {SYSTEM|SYS} {TRACE|TR}

Operand DescriptionACTIVE Displays the active XCF service listener on the ESP master and the

connection. GROUP Displays the status of your XCF group and its members.SERVICE Displays the status of the XCF Services in the group. SYSTEM Displays all systems in the sysplex.TRACE Displays the status of the Trace log.

1339

Examples Display ActiveThe following example shows the short form of the DISPLAY ACTIVE command when entered from the ESP master:XCF D A

Group=QS10, Member=QS10MPartner Service Status ConnectionListener DSTRIG ActiveListener ROUTING ActiveListener SCOREBD ActiveListener TRACKING ActiveQS10S DSTRIG Active 1,49QS10S ROUTING Active 3,50QS10S SCOREBD Active 6,51QS10S TRACKING Active 7,52QS10S2 DSTRIG Active 2,48QS10S2 ROUTING Active 4,49QS10S2 SCOREBD Active 5,50QS10S2 TRACKING Active 8,51

This is an example of the DISPLAY ACTIVE command when entered from an ESP Workload Manager proxy:XCF D A

Group=QS10, Member=QS10SPartner Service Status ConnectionQS10M3 DSTRIG Active 49,1QS10M3 ROUTING Active 50,3QS10M3 SCOREBD Active 51,6QS10M3 TRACKING Active 52,7

XCF DISPLAY Command: View XCF Attributes

1340

Display GroupThe following example shows the short form of the DISPLAY GROUP command when entered from the ESP Workload Manager master:XCF D G

Group=QS10 Member=QS10M3 Interval=60 TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusQS10 QS10M1 SYSC 0056 QS10 QS10 Master ActiveQS10 QS10M3 SYSA 009B QS10SHAD QS10 Shadow ActiveQS10 QS10M5 SYSC 0041 QS10SMC QS10 Shadow ActiveQS10 QS10S SYSA 009F QS10S QS1S Proxy ActiveQS10 QS10S2 SYSC 0046 QS10S2 QS12 Proxy Active

This is an example of the DISPLAY GROUP command when entered from an ESP Workload Manager proxy:XCF D G

Group=QS10 Member=QS10S Interval=45 TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusQS10 QS10M1 SYSC 0056 QS10 QS10 Master ActiveQS10 QS10M3 SYSA 009B QS10SHAD QS10 Shadow ActiveQS10 QS10M5 SYSC 0041 QS10SMC QS10 Shadow ActiveQS10 QS10S SYSA 009F QS10S QS1S Proxy ActiveQS10 QS10S2 SYSC 0046 QS10S2 QS12 Proxy Active

Display ServiceThe following example shows the short form of the DISPLAY SERVICE command when entered from the ESP master: XCF D S

Service Status Group Member SuspDSTRIG Active QS10 QS10M 120ROUTING Active QS10 QS10M 120SCOREBD Active QS10 QS10M 120TRACKING Active QS10 QS10M 120

1341

This is an example of the DISPLAY SERVICE command when entered from an ESP Workload Manager proxy:XCF D S

Service Status Group Member SuspDSTRIG Active QS10 QS10S 120ROUTING Active QS10 QS10S 100SCOREBD Active QS10 QS10S 120TRACKING Active QS10 QS10S 100

Display SystemThe following example shows the short form of the DISPLAY SYSTEM command:XCF D SYS

Sysplex=SYSAPLEX, System=SYSASystem Status IntervalSYSA Active 85SYSC Active 85

Display TraceThe following example shows the short form of the DISPLAY TRACE command:XCF D TR

ESP4263I XCF TRACE active, sysout class X

XCF FORCE Command: Terminate Active Members

1342

XCF FORCE Command: Terminate Active Members

The XCF FORCE command is used to terminate an active ESP XCF member abnormally with code S00C.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF FORCE {MEMBER|M} member

Examples Show active membersThe following display shows member D522 as active:XCF DISPLAY GROUP

Group=D520, Member=D521, TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusD520 D521 SYSA 0081 D521 D521 Master ActiveD520 D522 SYSA 007D D522 D522 Proxy Active

Remove XCF memberThe following example shows removing XCF member D522:XCF FORCE MEMBER D522

ESP4232I XCF member D522 forced, Group=D520

Operand Descriptionmember Indicates the name of the ESP member you want to terminate.

1343

Show XCF group with forced memberThe following display shows the XCF group with the forced member:XCF DISPLAY GROUP

Group=D520, Member=D521, TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusD520 D521 SYSA 0081 D521 D521 Master ActiveD520 D522 SYSA 007D D522 D522 Proxy Failed

Remove forced member from a groupThis example shows using the DELETE command to remove the forced member (D522) from the group:XCF DELETE MEMBER D522

ESP4234I XCF member D522 deleted, Group=D520

Displays remaining members of a groupThe following display shows the remaining members in the group:XCF DISPLAY GROUP

Group=D520, Member=D521, TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusD520 D521 SYSA 0081 D521 D521 Master Active

XCF HELP Command: List XCF Commands

1344

XCF HELP Command: List XCF Commands

The XCF HELP command is used to display the list of ESP XCF commands available.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {HELP|H|?}

Example HELP commandThe following display is the response from the XCF HELP command:XCF Command Options

DELETE|DEL MEMBER|MEM|M member

DISPLAY|D ACTIVITY|ACTIVE|ACT|A

DISPLAY|D GROUPS|GROUP|GR|G

DISPLAY|D SERVICES|SERVICE|SERV|S

DISPLAY|D SYSTEMS|SYSTEM|SYS

DISPLAY|D TRACE|TR

FORCE MEMBER|MEM|M member

HELP|H|?

PURGE|PG CONNECTION|CON connection

PURGE|PG SERVICE|SERV|S service

RESTART|RES|RS|SPIN|SP TRACE|TR

SET|T INTERVAL|INT interval

SET|T MEMBER|MEM|M member MASTER|M

SET|T SERVICE|SERV|S service SUSPEND|S(seconds)

1345

SET|T TERMOPT|TO LEAVE|L|QUIESCE|Q

SET|T TRACE|TR SYSOUT|S(class)

START|S SERVICE|SERV|S service

START|S TRACE|TR

STOP|P GROUP|GR|G

STOP|P MEMBER|MEM|M(member)

STOP|P SERVICE|SERV|S service

STOP|P TRACE|TR

VERIFY|VER MEMBER|MEM|M member

XCF PURGE Command: Terminate and Restart XCF Services

1346

XCF PURGE Command: Terminate and Restart XCF Services

The XCF PURGE command is used to terminate and restart an ESP XCF Service.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {PURGE|PG} {SERVICE|SERV|S} service {CONNECTION|CON} connection

Examples Displaying the XCF groupThe following display shows the status of the XCF group:XCF DISPLAY ACTIVE

Group=D520, Member=D521Partner Service Status ConnectionListener TRACKING ActiveListener DSTRIG ActiveD522 TRACKING Active 6,10D522 DSTRIG Active 7,11

Operand DescriptionSERVICE Used to specify a service function in the XCF group.service Indicates the name of the ESP XCF service you want to terminate

and restart.CONNECTION Used to specify a connection number of the listener.connection Indicates the connection number of the listener on the master ESP.

1347

Purging a Service The following example shows purging an ESP XCF service:XCF PURGE SERVICE TRACKING

ESP4221I Listener and 1 connection purged, Service=TRACKING, Group=D520, Member=D521

Display status after Service was purgedThe following display shows the status of the XCF group after the TRACKING Service has been purged. Note how the TRACKING Service has been restarted with a new connection.XCF DISPLAY ACTIVE

Group=D520, Member=D521Partner Service Status ConnectionListener DSTRIG ActiveListener TRACKING ActiveD522 DSTRIG Active 7,11D522 TRACKING Active 8,12

Purging a connectionThe following example shows purging a connection:XCF PURGE CONNECTION 3

ESP4225I Connection 3 purged

XCF SET MEMBER Command: Instruct Shadow Manager

1348

XCF SET MEMBER Command: Instruct Shadow Manager

The XCF SET MEMBER command is used to manually instruct a shadow manager to take over as the ESP master. This may be used when there are no Shadow Goals defined in your initialization parameters. It is valid only on a shadow manager.

TypeHAO.

SyntaxXCF {SET|T} {MEMBER|MEM|M} member MASTER|M

Related informationFor more information, see the Shadow Manager topic in the chapter ESP Workload Manager High Availability Option in the ESP Workload Manager User’s Guide.

ExampleIn this example, the ESP Workload Manager master (ESPM) is stopped or terminated abnormally and the shadow manager (ESPS) takes over.XCF SET MEMBER ESPS MASTER

Operand DescriptionMEMBER member Name of the target shadow manager you want to control the workload.MASTER Sets the specified member as the ESP Workload Manager master to take

over the workload.

1349

XCF SET SERVICE Command: Specify Fixed Intervals

.The XCF SET SERVICE command specifies a time interval after which a service starts after being suspended. XCF SET SERVICE may be defined in the initialization parameters. For more information, see the ESP Workload Manager Installation and Configuration Guide.

SyntaxXCF {SET|T} {SERVICE|SERV|S} [TRACKING] SUSPEND(time) [DSTRIG] [ROUTING] [SCOREBD]

Usage notesWhile an XCF Service is suspended, it is possible to issue the XCF STOP and XCF START commands manually. If a manual command is issued on a suspended XCF Service, it will not be automatically resumed.

Related informationFor more information about all the XCF Services, see the ESP Workload Manager User’s Guide.

Operand DescriptionSUSPEND time Specifies a suspend time in seconds within the range 0-3600. The default

suspend time for an XCF Service is 120 seconds (two minutes). A value of zero means - when an XCF Service is suspended, it will be for an indefinite period of time, until it is manually started or stopped with an XCF START SERVICE or XCF STOP SERVICE command.

TRACKING Enables job tracking records to be transmitted to the ESP Workload Manager master from an ESP Workload Manager proxy via XCF.

DSTRIG Enables data-set triggering records to be transmitted to the ESP Workload Manager master from an ESP Workload Manager proxy via XCF.

ROUTING Enables ESP Workload Manager user to connect to an ESP Workload Manager proxy on any system in the sysplex, and have the ability to route ESP Workload Manager commands to the ESP Workload Manager master.

Note: This is available only with HAO or HPO.SCOREBD Enables ESP Workload Manager users connected to an ESP Workload

Manager proxy on any system in the sysplex, the ability to view the ESP Workload Manager scoreboard and receive subsequent scoreboard updates.

Note: This is available only with HAO or HPO.

XCF SET TERMOPT Command: Preset Groups Termination

1350

XCF SET TERMOPT Command: Preset Groups Termination

The XCF SET TERMOPT command is used to preset what status the XCF member will have in the XCF group when it terminates normally.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Work

SyntaxXCF {SET|T} {TERMOPT|TO} {LEAVE|L} {QUIESCE|Q}

Operand Description

TERMOPT Used to preset what status the XCF member has when it terminates normally. Entered from the ESP XCF member you are logged on to or previously defined in the initialization parameters of the SYSPLEX Statement.

LEAVE This is the default for an XCFLOCAL configuration. It tells the XCF member to enter a LEAVE state when it terminates normally from the XCF group. LEAVE means a member goes into an undefined state and no record of its existence is maintained by XCF.If QUIESCE and LEAVE are omitted and the local system (z/OS image) is a member of a sysplex (for example, uses a coupling data set), QUIESCE is the default. If the local z/OS system is not a member of a sysplex (for example, IEASYSnn member specifies PLEXCFG=XCFLOCAL), LEAVE takes effect unconditionally.

QUIESCE This is the default for a sysplex configuration. It tells the XCF member to enter a Quiesced state when it terminates normally. A Quiesced XCF member is disassociated from XCF Services, but XCF retains a record of its existence. Quiesced members of an ESP XCF group are included in the response to the ESP subcommand XCF DISPLAY GROUP.

1351

Related informationFor more information on the SYSPLEX initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.For more information on ESP and XCF, see the ESP Workload Manager User’s Guide.

Examples SET TERMOPT commandThe following example shows setting an XCF member to terminate with a Quiesced state using the short form of the SET TERMOPT command:XCF T TO Q

ESP4242I XCF TERMOPT set to QUIESCE, Group=D520, Member=D521

TERMOPT in the SYSPLEX statementThe following example shows setting an XCF member to terminate with a Quiesced state using the TERMOPT operand in the SYSPLEX initialization parameter:SYSPLEX GROUP(D520) MEMBER(D521) TERMOPT(QUIESCE)

XCF SET TRACE Command: Define Sysout Classes

1352

XCF SET TRACE Command: Define Sysout Classes

The XCF SET TRACE command is used to define a sysout class for trace data output. XCF SET TRACE can be coded in the initialization parameter data set or entered on the fly when trace data is required. It is recommended to put it in your initialization parameter data set.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {SET|T} {TRACE|TR} {SYSOUT|S}(class)

Related informationFor more information about the XCF Trace facility, see the ESP Workload Manager User’s Guide.

Example Set trace data The following example shows the short form of the SET TRACE command to set trace data to a sysout class of X:XCF T TR S(X)

Operand Description(class) Indicates an output class for sysout.

1353

XCF SPIN TRACE Command: Spool Trace Data

The XCF SPIN TRACE command is used to spool trace data from the current trace file to output, and start a new trace file. This command is used when the trace file is started upon initialization of the ESP subsystem and kept running for the duration of the subsystem session.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {RESTART|RES|RS|SPIN|SP} {TRACE|TR}

Related informationFor more information about the XCF Trace facility, see the ESP Workload Manager User’s Guide.

Example Short form of SPIN TRACEThe following example shows the short form of the SPIN TRACE command:XCF SP TR

Operand DescriptionSPIN Used to send trace data to output and start a new trace file.TRACE Indicates XCF Trace facility.

XCF START SERVICE Command: Restart XCF Services

1354

XCF START SERVICE Command: Restart XCF Services

The XCF START SERVICE command is used to restart an XCF Service dynamically after it has been stopped.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {START|S} {SERVICE|SERV|S} [TRACKING] [DSTRIG] [ROUTING] [SCORED]

Usage notesXCF Services are registered and activated via the XCF START SERVICE xxxx command in the initialization parameter data set. To enable the XCF connection, the XCF START SERVICE xxxx commands must be coded in the initialization parameter data set.

Related informationFor more information on XCF Services, see the ESP Workload Manager User’s Guide.

Operand DescriptionXCF START Enables the XCF connection for the XCF Service specified.

1355

XCF START TRACE Command: Initialize/Activate Trace Files

The XCF START TRACE command is used to initialize and activate the XCF Trace file. The XCF START TRACE command can be used after the XCF SET TRACE command in the initialization parameter data set if you want to start the trace file upon initialization of the ESP subsystem. Otherwise, the XCF START TRACE command is entered on the fly when you need to capture data.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {START|S} {TRACE|TR}

Related informationFor more information about the XCF Trace facility, see the ESP Workload Manager User’s Guide.

Example Short form of the START TRACE commandThe following example shows the short form of the START TRACE command:XCF S TR

Operand DescriptionTRACE Indicates XCF Trace facility.

XCF STOP GROUP Command: Stop All XCF Group Members

1356

XCF STOP GROUP Command: Stop All XCF Group Members

The XCF STOP GROUP command is used to stop all the ESP XCF members in the XCF group.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {STOP|P} {GROUP|G}

Operand DescriptionGROUP Indicates the XCF group from which the command was issued.

1357

XCF STOP MEMBER Command: Stop XCF Members

The XCF STOP MEMBER command is used to stop an ESP XCF Member.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {STOP|P} {MEMBER|M} member

Example The following example shows the short form of the XCF STOP MEMBER command:XCF P M D523ESP4231E XCF member D523 stopped, Group=D520

Operand Descriptionmember Indicates the name of the ESP subsystem you are targeting.

XCF STOP SERVICE Command: Stop XCF Services

1358

XCF STOP SERVICE Command: Stop XCF Services

The XCF STOP SERVICE command is used to stop an ESP XCF Service.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {STOP|P} {SERVICE|SERV|S} service

Related informationFor more information on XCF Services, see the ESP Workload Manager User’s Guide.

Example Short form of the STOP SERVICE commandThe following example shows the short form of the XCF STOP SERVICE command:XCF P S TRACKING

ESP4220I XCF service TRACKING stopped, Group=D520, Member=D521

Operand Descriptionservice Indicates the name of the Service you want to stop.

1359

XCF STOP TRACE Command: Stop Trace File

The XCF STOP TRACE command is used to stop the trace file after data has been captured and to spool the captured data to the preset sysout class specified by the XCF SET TRACE command.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {STOP|P} {TRACE|TR}

Related informationFor more information about the XCF Trace facility, see the ESP Workload Manager User’s Guide.

Example Short form of the STOP TRACE commandThe following example shows the short form of the XCF STOP TRACE command:XCF P TR

Operand DescriptionTRACE Indicates XCF Trace facility.

XCF VERIFY Command: Verify Two XCF Members

1360

XCF VERIFY Command: Verify Two XCF Members

The XCF VERIFY command is used to verify that two ESP XCF members have the same view of what their connections are. VERIFY is typically used after a PURGE command has been executed on a Service or a Connection.

TypeESP XCF command.

Entering commandsAll ESP XCF commands may be issued via:• ESP page mode, option G from the ESP main menu• ESP line mode• z/OS MODIFY command• ESP Workstation.

SyntaxXCF {VERIFY|VER} {MEMBER|M} member

Example Short form of the VERIFY commandThe following example shows the short form of the XCF VERIFY command:XCF VER M D522

ESP4243I Verify request transmitted to XCF member D522, Group=D520.

Operand Descriptionmember Indicates the name of the ESP subsystem you are targeting.

1361

XMITMDL Command: Identify Tracking Models to Transmit

The XMITMDL command tells ESP which tracking models are to be transmitted, and to which node.

TypeGeneral command.

AuthorityYou require OPER authority to issue the XMITMDL command.

SyntaxXMITMDL [LIST |ADD MODEL(modelname[,modelname]...) {[NETNODE(netnode[,netnode]...)] [NODE(nodeid[,nodeid]...)] } |DELETE {[MODEL(modelname[,modelname]...)] [NETNODE(netnode[,netnode]...)] [NODE(nodeid[,nodeid]...)] } ]

Operand DescriptionLIST Lists specifications of transmitted tracking data. This is the default.ADD Adds specifications to the list of transmitted tracking data.DELETE Deletes specifications to the list of transmitted tracking data.MODEL(modelname)

Specifies the name of tracking model, associated with the jobs, for which data is to be transmitted. Wildcard characters can be used to signify a group of tracking models. Multiple tracking models can be specified.

NETNODE(netnode)

Specifies a destination network node for the internodal tracking model and indicates that the internodal tracking model is managed by Network Delivery Services (NDS). The specified destinations must correspond to the NETNODE operand of a NETDEST initialization parameter in the LOADNET initialization data set.

NODE(nodeid)

For NJE, this is the logical identifier of each node to receive tracking data (as identified on the ISCXMTR statement); for LU6.2, this is the application name of the target TP Server. Multiple nodes can be specified.

Note: NODE is invalid if ISCOPT NETWORK is coded in your initialization parameters.

XMITMDL Command: Identify Tracking Models to Transmit

1362

Usage notesXMITMDL must be issued from a master ESP Workload Manager system.

Examples

ListTo display cross-system tracking models:OPER XMITMDL LIST

AddTo identify that all tracking data for model XSYS be sent to ESP_SYSTEM_A, where this is the application name of the target TP Server, specify:XMITMDL ADD MODEL(XSYS) NODE(ESP_SYSTEM_A)

To identify that tracking data for tracking models whose names begin with the characters PR or SYS be sent to the node with the logical identifier of N2 (where NJE is used for internodal tracking):XMITMDL ADD MODEL(PR-,SYS-) NODE(N2)

To identify that all tracking data be sent to the node with the logical identifier N1 (where NJE is used for internodal tracking):XMITMDL ADD MODEL(-) NODE(N1)

To identify that data for the tracking model XSYSTEMS be sent to the node ESPM_CHICAGO using NDS.XMITMDL ADD MODEL(XSYSTEMS) NETNODE(ESPM_CHICAGO)

To identify that data for the tracking model XSYSTEMS and tracking models with names beginning with abc be sent to the nodes master1, master2, master3, and master4 using NDS.XMITMDL ADD MODEL(XSYSTEMS,abc-) + NETNODE(master1,master2,master3,master4)

Delete (using the previous example as a base)To remove tracking model ABCDE.XMITMDL DELETE MODEL(ABCDE)

To remove node master4 from receiving tracking information from model XSYSTEMS. Note that the model XSYSTEMS is not deleted. It would be deleted if master4 was the last node associated with XSYSTEMS.XMITMDL DELETE MODEL(XSYSTEMS) NETNODE(master4)

Note: In this specific case, do not use XMITMDL DELETE NETNODE(master4) because it would also remove node master4 from receiving tracking information from models with names beginning with abc.

Index

1363

Symbols%ENDEXCL ............................................ 493%ENDINCL ............................................. 495%EXCLUDE ............................................ 562%INCLUDE ............................................. 659//* FROM ................................................ 620//* UNTIL.............................................. 1297//*ESPSYMBOL ....................................... 538

AABANDON DEPENDENCIES ....................... 14ABANDON RESOURCES ............................ 16ABANDON SUBMISSION ........................... 18ABAP (SAP)

specify failure message for ..................... 586ABAPNAME .............................................. 21ABENDLIM .............................. 23, 779, 1051ABSORB ................................................... 25action statements, identify end of ................. 491actions

based on type of day, specify .................. 918specify ............................................. 1249

activate trace facility ............................... 1269activating user modifications ..................... 1305ADJUST .................................................... 26adjust run time ............................................ 26advance output to new page......................... 403AFTER...................................................... 28Agent

controlling .......................................... 233defining and manipulating receivers ........... 48display definition ................................... 35display version..................................... 233flush messages ..................................... 515hold messages ........................................ 35install ................................................. 233Manager address, specify for Agent receiver .....

839password for user ID to run job ............... 942purge messages ...................................... 35quiesce ............................................... 515restart............................................35, 515shutdown .............................................. 35starting and stopping ............................. 233

AGENT command ....................................... 32Agent related commands

AGENT ................................................ 35AGENTRCV.......................................... 48

Agent Security File.................................. 1303AGENT statement ....................................... 38AGENT_MONITOR .................................... 40AGENTDEF data set .................................... 33AGENTMSG .............................................. 41agentparm.txt file .................................... 1141AIX_JOB................................................... 51ALERTDEF ............................................... 52Allow Write to Operator ............................. 554ALLOWUNDEF.......................................... 54ALTCAL ................................................... 55ALTCAL, Alter Calendar Definition ............... 55alter calendar definitions .............................. 55alter Events ................................................ 57alter groups ................................................ 60alter job tracking data .................................. 63alter signals................................................ 62alter user definitions .................................... 65ALTEVENT ............................................... 57ALTGROUP............................................... 60ALTGROUP, Alter Group ............................. 60ALTSIG .................................................... 62ALTTJ ...................................................... 63ALTTJ, Alter Job Tracking Data .................... 63AMNOTIFY ............................................... 68APPL 69, 74, 96, 182, 308, 858, 917, 960, 966,

979, 996, 998, 1000, 1002, 1050, 1075APPLDISPLNAME...................................... 74APPLEND ................................................. 75

perform processing automatically at end of Application ............................ 75

Application file, displaying ......................... 763Applications

defining jobsstart ......................................912, 1296

identifying report type ........................... 991job naming ........................................ 1296naming a job........................................ 912processing options .................................. 69resource requirements ......................... 1070simplifying.......................................... 600stopping processing ............................ 1013terminology definition ............................... 4

APPLINS................................................... 77APPLJOB(AJ) .......................................80, 82

Index

1364

ARCDATE ...............................................100ARCDOCCLASS .......................................101ARCDOCTYPE statement ................... 103, 107ARCFORMAT ..........................................104archive

specifying document type ............... 103, 107specifying mode....................................108

ARCHOSTLINK........................................105ARCMODE ..............................................108ARCOBJNAME.........................................109ARCOBJTYPE ..........................................110ARCOBJVARIANT....................................111ARCPATH ...............................................112ARCPRINTER ..........................................113ARCPROTOCOL .......................................114ARCREPORT ...........................................116ARCSERVICE ..........................................118ARCSTORAGE .........................................120ARCTEXT................................................122ARCUSER................................................124ARCVERSION ..........................................125ARGDEFAULTS .......................................127ARGS .............................................. 129, 131AS400_JOB ..............................................133AS400FILE ..............................................134AS400LIB ................................................135assign

default priority .....................................269job class to a job ...................................711scheduled activity data sets ...................1106

associate ESP expedite policy ......................580asterisk wildcard

in file names ........................................589authorization tables

deleting ...............................................287displaying............................................764

AUX_AS..................................................136

Bback up

Event data set .......................................147history data set .....................................148index data base .....................................149job index data base ................................151

back up user definition data set ....................153BANNERPAGE .........................................139batch file

running executable files within ................193BDC_JOB ................................................140BDCERRRATE .........................................142BDCEXTLOG ...........................................143BDCPROCRATE .......................................144

BDCSYSTEM ...........................................145BEAN......................................................146begin report definition ..............................1049BKUPEVS................................................147BKUPHIST...............................................148BKUPINDX..............................................149BKUPJNDX..............................................151BKUPUDEF .............................................153BREAK....................................................155BWIP

define data selection criteria ...................936BWIP_JOB ...............................................157BWPC_JOB ..............................................159bypass job submission ..................................18bypassing

a job ............................................... 80, 82a sub-Application.............................. 80, 82Event execution ..................................1290

CCALENDAR .............................................161calendar

specify ................................................161calendars, displaying ..................................766call exit program when job completes ............169card image, do not check last non-blank character ..

894CCCHK ...................................................163CCEXIT...................................................169CCFAIL ...................................................170CELLTRC ................................................173CHAIN ....................................................176change

job attributes ........................................708symbol introducer .................................538

check for exclusion character .......................178CHECKEXC .............................................178CHILDMONITOR ............................. 181, 182children, monitoring (Oracle Apps) ...............182children, monitoring delay (Oracle Apps) .......858CLASS ....................................................183CLEANUP................................................186clear

Agent spoolfiles....................................187system messages ...................................190

clearspool.................................................187close report data files .................................499CLPNAME ...............................................189CLRSYSMS..............................................190CMDNAME..............................................191CMDPRFX ...............................................195COLUMNS...............................................196

1365

COM .......................................................197COMMAND .............................................198command

terminology definition ...............................4ABENDLIM..........................23, 779, 1051ADJUST................................................26AGENT........................................... 32, 35AGENTRCV ..........................................48ALTCAL ...............................................55ALTEVENT ...........................................57ALTGROUP ..........................................60ALTSIG ................................................62ALTTJ ..................................................63ALTUSER .............................................65APPLINS ..............................................77APPLJOB(AJ) .................................. 80, 82AUX_AS .............................................136BKUPEVS ...........................................147BKUPHIST ..........................................148BKUPINDX .........................................149BKUPJNDX .........................................151BKUPUDEF.........................................153BREAK...............................................155CALENDAR ........................................161CELLTRC ...........................................173CLASS................................................183CLEANUP ...........................................186clearspool ............................................187CLRSYSMS .........................................190CMDPRFX ..........................................195COM ..................................................197CONNECT ..........................................199CONSOLE ...........................................202COPY .................................................204CPROC ...............................................212CPU ...................................................214CRITERIA...........................................223CRITPATH ..........................................226CRYPTKEY.........................................230cybAgent .............................................233DATEFORM ........................................243DEFAT ...............................................247DEFAULT ...........................................250DEFCAL .............................................251DEFGROUP.........................................254DEFHOL .............................................257DEFPN ...............................................260DEFPRINT ...........................263, 265, 267DEFPRIO ............................................269DEFSIG ..............................................270DEFSPEC ............................................272DEFSYML...........................................275

DEFTJ ................................................277DEFTM...............................................279DEFUSER ...........................................283DELAT ...............................................287DELAYINT .........................................288DELCAL .............................................292DELETE ..................................... 293, 294DELGROUP ........................................295DELHOL.............................................296DELPN ...............................................298DELSIG ..............................................299DELSPEC............................................300DELSYML ..........................................302DELTJ ................................................303DELTM...............................................305DELUSER ...........................................306DFLTUSER .........................................320DFPNODE...........................................322DISCONN ...........................................326DISPLAY ............................................333DN .....................................................347DQ .....................................................354DSTREXCL .........................................370DSTRIG ..............................................371DSTRST..............................................386ECHO .................................................396EICLASS ............................................398EJECT ................................................403ENCLOG.............................................412ENCPARM ..........................................414ENCPARM ABENDER ..........................415ENCPARM AUTOREST ........................416ENCPARM BACKOUT..........................421ENCPARM CLEANUP ..........................423ENCPARM COMMENT .........................425ENCPARM CONDCODE .......................426ENCPARM DELETE .............................427ENCPARM DIAG .................................429ENCPARM EXCLUDE ..........................430ENCPARM FORCE...............................432ENCPARM FROMSTEP.........................433ENCPARM GDGADJ ............................434ENCPARM HONORCC .........................437ENCPARM IGNOREDS .........................438ENCPARM JOBID ................................440ENCPARM JOBNAME ..........................441ENCPARM MODE................................442ENCPARM MODIFY ............................444ENCPARM PREDICT............................446ENCPARM PREVTIME .........................450ENCPARM PRINT ................................452ENCPARM PURGE...............................454

1366

ENCPARM QUIESCE............................458ENCPARM RESTART ...........................459ENCPARM STATUS .............................461ENCPARM SUBSYS .............................462ENCPARM TAPESCR ...........................466ENCPARM TOSTEP .............................470ENCPARM TRACE...............................471ENCPARM TYPE .................................472ENCPARM VOLUME............................474ENCPARM WARNING..........................476ENCREQ .............................................478ENCRYPT ...........................................484ENCTRACE.........................................487END ...................................................489ENDDEF .............................................490ENDHC...............................................494ENDMODEL........................................498ENDPRINT..........................................499ENDR .................................................501ENQSELF ...........................................503ENQUEUE ..........................................505ESPCOM .............................................515ESPCTR ..............................................518ESPmgr ...............................................520ESPmsg...............................................528EVENT ...............................................540EVENTOPT .........................................554EVENTSET .........................................556EXIT ..................................................566EXPECT .............................................572EXPEDITE ..........................................574FLOW.................................................610FLOWDOC ..........................................612FOOTING ...........................................615FROM.................................................618FTP ....................................................622GENDOC ............................................627GENFLOW ..........................................630GENPROJ ...........................................632GENTIME ...........................................635GO .....................................................639GROUP...............................................640HARDCOPY .........................642, 644, 646HISTFILE ................................... 648, 650HOLD......................................... 652, 654INET ..................................................663INFOCOMM ........................................667INFOMSG ...........................................669INIT ...................................................672INPUT ................................................676INVOKE .............................................682JESCOMCH .........................................690

JESTYPE ............................................691JOBENQ .............................................715JOBINFO ............................................716JOBMAP .............................................720JOBRES ..............................................726JOBTREE............................................727JTPEXCL ............................................729LABEL ...............................................734LAP....................................................758LAX ...................................................741LCMDPRFX ........................................743LDSN .................................................744LDSTCELL .........................................745LDTE .................................................746LDTREL .............................................747LDXE .................................................748LIBSUB ..............................................751LIST...................................................755LISTAPPL ...........................................758LISTAPTF ...........................................763LISTAT ..............................................764LISTCAL ............................................766LISTCKPT ..........................................768LISTEVS.............................................769LISTGRP ............................................771LISTHIST ...........................................773LISTHOL ............................................774LISTJTML...........................................776LISTPN...............................................777LISTQ ................................................778LISTROOT ..........................................779LISTSADL ..........................................781LISTSCH ............................................782LISTSIG .............................................785LISTSPEC ...........................................787LISTSYML ..........................................790LISTTRAK ..........................................792LISTUSER ..........................................793LISTXMEZ..........................................795LJ ......................................................796LMOD ................................................799LOAD.................................................800LOADAGDF ........................................802LOADJTDT .........................................803LOADNL ............................................805LOADSCHF.........................................806LOADUPDT ........................................807LOGPRT .............................................812LSAR .................................................813LSYS..................................................817LSYSMSGS .........................................819LTCELL..............................................820

1367

LTJ ....................................................821LTM ...................................................823LTZONE .............................................824MAILBOX...........................................825MANAGER .........................................826MAPGEN ............................................828MAPUSER ..........................................830MAXCXME .........................................831MAXINITS ..........................................832MAXQXME .........................................834MCS ...................................................835MGRADDR .........................................839MGRMSG ...........................................841MODEL ..............................................852MREPORT ..........................................860MSG...................................................865MSGTYPE...........................................871NETAUTH ..........................................875NETDEST ...........................................876NETWORK..........................................882NEXT .................................................891NJETOL ..............................................893NODE.................................................895NOSCHED ..........................................901NTRCLASS .........................................913NULLPSWD ........................................914ON .....................................................918PANSUB .............................................933PASSWORD ........................................940PCACHE .............................................943POST..................................................947PREALLOC .........................................953PURGSCHF .......................................1008QUIESCE ..........................................1013QUPDATE.........................................1016RACROUTE ......................................1017RELEASE ............................... 1038, 1040REMOVE ..........................................1047REPORT ...........................................1049RERUNM ..........................................1051RESDEF............................................1055RESDFLT..........................................1064RESREFR..........................................1076RESTART .........................................1077RESTORE .........................................1078RESUME................................. 1080, 1082ROSSUB ...........................................1088ROUTING .........................................1091SADGEN...........................................1102SADLINK .........................................1106SADLOAD ........................................1108SADUPD ...........................................1110

SAFOPTS ..........................................1111SCAN ...............................................1134SCHEDULE .......................................1138SEND ...............................................1153SET ..................................................1163SETPRINT ........................................1164SETVAR ...........................................1165SETWIDTH .......................................1166SHADGOAL ......................................1167SHADOW..........................................1169SIGCYCLE ........................................1173SIGPOST ..........................................1175SIGWAIT ..........................................1177SIMULATE .......................................1179SMFSTATS .......................................1189SNDESPMSG.....................................1190SORT ...............................................1191SPACE..............................................1193SPINLOG ..........................................1194SPUSER............................................1197STATUS ...........................................1202subAgent ...........................................1209SUBMIT ...........................................1215SUSPEND ............................... 1219, 1221SYMLIB ...........................................1222SYSMSGS .........................................1224TAPETRAK.......................................1231TEST ................................................1240TIME................................................1251TITLE...............................................1256TPAPPL ............................................1261TPDISP.............................................1263TPRETRY .........................................1264TPSTART..........................................1265TPTERM ...........................................1266TPTIME ............................................1267TPTRAN ...........................................1268TRACE .............................................1269TRACEDEF .......................................1271TRACEPRT .......................................1273TRACKDEF.......................................1275TRACKING .......................................1280TRACKOPT.......................................1282TRDFLT ...........................................1289TRIGGER..........................................1290TRYJOIN ..........................................1294UNALLOC ........................................1295USE..................................................1299USER ...............................................1301USERMOD ........................................1305VDEL ...............................................1308VGET ...............................................1309

1368

VINCR..............................................1311VPUT ...............................................1312VS....................................................1313VSET................................................1316VTDEFINE ........................................1317VTDELETE .......................................1318VTLIST ............................................1319VTRDEF ...........................................1321VTRDEL ...........................................1323WILDCARD ......................................1325WLM ................................................1327WOBCMD .........................................1329WOBDEF ..........................................1332WORKMGR.......................................1334XMITMDL ........................................1361

command outputdata set ...............................................642file .....................................................644sysout .................................................646

command prefixspecify for JES commands ......................690specify single character for .....................195

commandsENDPROC...........................................500PROC .................................................983

commentsESP Procedure..........................................2

COMMQ, list attributes ..............................515completing

a job ............................................... 80, 82a sub-Application .............................. 80, 82

condition codesfailures, identifying ...............................170

condition codes, checking............................170conditional processing ................................657CONNECT ...............................................199connect

interval .............................................1264to Group ..............................................199

CONNECTION_FACTORY .........................201CONSOLE................................................202console, setting primary ..............................202continuation character, ESP Procedure...............1control

authorization profiles.............................875data set triggers ....................................386ESP communications .............................515ESP Counters .......................................518Event initiator classes ............................398InfoServ ..............................................667MCS extended console ...........................835NDS ...................................................882

processing options...............................1111updates to job parameters (PeopleSoft) ...1187

control and display shadow manager ...........1169controlling

Agents ................................................233Applications...........................................80jobs and subApplications ..........................82

conventions used in this guide..........................6converting

DJC networks .......................................691job documentation libraries............. 627, 734

COPY ......................................................204copy job history record ...............................204COPYJCL ................................................206COREQ....................................................209co-requisite job .........................................209co-requisite job, selection of ........................209CPROC ............................................ 212, 622CPU ................................................ 214, 218CPU statement

specify conditions to monitorCPU use within CPU_MON...................218

CPU_MON ...............................................221create data set for reports ..........................1102creating a job mapping data set ....................828CRITERIA ...............................................223CRITPATH....................................... 226, 228CRYPTKEY .............................................230CSF

purging data .......................................1008update user status................................1190

CURLIB...................................................232cybAgent..................................................233cycle signals ...........................................1173

Ddata set

identifying .........................................1271identifying for data set triggers................359save list of waiting jobs for rerun.............779

data set names in ESP Procedure ......................2data set triggering

at Event level ............................... 360, 371controlling ...........................................386delaying ..............................................368displaying data set trigger objects ............748displaying data set triggered Events .........748displaying excluded programs .................747DSNAME statement usage ......................359excluding programs ...............................370listing data sets.....................................746

1369

data setsdisplaying............................................744job mapping .........................................828preallocating ........................................953restoring............................................1078trace .................................................1271

DATA_OBJECT ........................................239DATASET ................................................241date and time variables ...............................635DATEFORM .............................................243DB_JOB...................................................245

specify target data source name (DSN)......357SQL statement, specify ........................1198

DB_JOB statementspecify destination file ...........................316

deactivating user modifications ..................1305deallocating a data set ..............................1295debug mode, starting Windows NT agent .....1209decrement

hold counts .............................. 1038, 1040suspend counts ...................................1080

decrement suspend counts .........................1082DEFAT ....................................................247DEFAULT................................................250default resources......................................1064DEFCAL ..................................................251DEFGROUP .............................................254DEFHOL..................................................257define

Agent user IDs and passwords .................940alert......................................................52an ESP Agent to ESP Workload Manager ....32authorization table ................................247BWIP data selection criteria....................936calendar ..............................................251CPU ...................................................214data-set triggers

Event level .......................................371Job Level .........................................384

default job card values ...........................250default users ........................................320enclave support...................................1334Event data set .......................................556file triggers ..........................................587global variable tables ...........................1317global variable triggers ........................1321integer variables ...................................680logical reports

DATASET option...............................263SYSOUT option.................................265

maximum initiators ...............................832monitoring workload objects .....................40

output to file ........................................267resources ...........................................1055schedules...........................................1138signal..................................................270special day...........................................272symbolic variable library ........................275sysout classes .....................................1352system nodes ........................................895tracking for job.....................................277tracking model .....................................279user ....................................................283user IDs ............................................1302user modifications ...............................1305variables ...........................................1165workload objects.................................1332

define and store encryption key ....................230define or alter

expedite policy .....................................574history file ...........................................650

defininga footing..............................................615a title ................................................1256authorization table ................................247date and time variables ..........................635group prefixes ......................................275groups.................................................254history file ...........................................650holidays ..............................................257initial user to ESP ...............................1197Pnodes .......................................... 66, 260resources ...........................................1055special days and periods .........................788symbol libraries ....................................275symbolic library sets..............................275tracked jobs .......................................1275users ...................................................283

DEFPN ....................................................260DEFPRINT ...............................................267

DATASET option .................................263SYSOUT option....................................265

DEFPRIO .................................................269DEFSIG ...................................................270DEFSPEC.................................................272DEFSYML ...............................................275DEFTJ .....................................................277DEFTM....................................................279DEFUSER ................................................283DELAT ....................................................287delay

data set trigger .....................................368interval ...............................................288jobs submission ..................................1036

1370

delayingjob submission....................................1036submission...........................................289

DELAYINT ..............................................288DELAYSUB .............................................289DELCAL..................................................292DELETE .......................................... 293, 294delete

authorization table ................................287calendar ..............................................292Event (General) ....................................294Event (In definition) ..............................293global variable tables ...........................1318global variable triggers ........................1323global variables ..................................1308groups.................................................295holidays ..............................................296Pnodes ................................................298signals ................................................299special days or periods ...........................300symbolic variable library ........................302tracked job definitions ...........................303tracking model definitions ......................305users ...................................................306

deletinga signal ...............................................299a special day or period ...........................300Events.................................................294resources ...........................................1055tracked job definition.............................303tracking model......................................305

DELGROUP .............................................295DELHOL..................................................296DELPN ....................................................298DELSIG ...................................................299DELSPEC ................................................300DELSYML ...............................................302DELTJ .....................................................303DELTM ...................................................305DELUSER ................................................306DEQUEUE ...............................................307DESC ......................................................308describe the ESP Workload Manager

subsystem controlling the ESP Agents .........826DESCRIPTION .........................................308DESELECT ..............................................310deselect jobs or subApplications ...................310DEST ......................................................313DESTINATION .........................................316destination system, specifying ....................1087DESTNAME .............................................318detect condition codes ................................163

DFLTUSER ..............................................320DFPNODE................................................322diagnostic tracing ....................................1269DIRECTION .............................................324disable restart feature (PeopleSoft) ...............325DISABLE_RESTART.................................325DISCONN ................................................326Disconnecting a user from a group ................326DISK .......................................................327DISK statement

specifyconditions to monitor

disk within DISK_MON...............327DISK_MON..............................................331DISPLAY.................................................333display

enqueue status ......................................505Event log .............................................812event statistics....................................1299job documentation.................................716messages in screen body.........................669module level ........................................799names .................................................347next execution of Events ........................891Pnode queues .......................................354reporting fields .....................................333service policies...................................1327SMF status.........................................1189system status ......................................1263width, setting .....................................1166

display and delete cache entries ....................212displaying

Application file usage ............................763Applications.........................................758calendars .............................................766cross-memory elements ..........................795current ESP status ...............................1202current schedule....................................782current status of the Application ..............763data set names ......................................744data set triggers ....................................746ESP data sets........................................744ESP system information .........................817Event data set .......................................769Event definitions...................................755excluded programs for data set triggering ..747external jobs ........................................741fields in History Report..........................333groups.................................................771history file ...........................................773holidays ..............................................774job documentation information ................716

1371

job statistics.........................................796job tracking file ....................................792module level ........................................799names of Events....................................756next execution times ...................... 756, 891Pnodes ................................................777QUEUE data set....................................778queues ........................................ 347, 354resources ...........................................1055SADLINKs ..........................................781scheduled activity report ........................813signals ................................................785subApplications ....................................758symbol libraries ....................................790system messages ...................................819TCP/IP attributes ..................................663time zone settings .................................824tracked job definition.............................821tracking cell information ................ 745, 820tracking models ....................................823TRAKFILE ..........................................792user definitions .....................................793user modifications ...............................1305

DISPLNAME ..............................................74DISTRFOLDER.........................................335DISTRLISTROLES ....................................336DISTRLISTUSERS ....................................338divert output

to data sheet .........................................642to DD file ............................................644to sysout class ......................................646

DJC specifications .....................................340DJCDATA................................................340DJCNET ..................................................345DN ..........................................................347DO

ending.................................................491statement .............................................350

DOCLIB ..................................................352documentation conversion .........................1047documentation library, non-ESP , lines to be

removed...............................................1047DQ ..........................................................354DROPNOTW ............................................356dropping

dependencies ..........................................14resources ...............................................16submit time dependency ...........................18

DSN ........................................................357DSNAME .................................................359DSTCELLs, displaying ...............................745DSTRDLY................................................368

DSTREXCL..............................................370DSTRIG........................................... 371, 384DSTRST ..................................................386due out time job submission.........................738DUEOUT .................................................388DURATION..............................................392durations

specify ................................................392

Eearly submission time .................................393EARLYSUB .............................................393ECHO......................................................396echo data ..................................................396echoing character strings .............................396EICLASS .................................................398EJB_JOB..................................................401EJECT .....................................................403ELSE.......................................................404ELSE statement

specify alternate actions .........................404email

job logs (PeopleSoft) .............................408SAP spool file upon

ABAP completion/failure ......................407job completion/failure ........................1121

specifying, job level ..............................407specifying, step level ................ 406, 407

email addresses (PeopleSoft)specify ................................................406

EMAILADDR ................................... 406, 407EMAILADDR statement, step level .... 406, 407EMAILLOG..............................................408EMAILSUBJECT ......................................409EMAILTEXT ............................................410EMAILWEBREPORT.................................411enable

critical path analysis ...................... 226, 228encrypted communications......................484

enable/disable ESP tracking facility ............1280enabling user modifications .......................1305ENCLOG .................................................412ENCPARM ...............................................414

ABENDER ..........................................415AUTOREST .........................................416BACKOUT ..........................................421CLEANUP...........................................423COMMENT .........................................425CONDCODE ........................................426DELETE .............................................427DIAG..................................................429EXCLUDE...........................................430

1372

FORCE ...............................................432FROMSTEP .........................................433GDGADJ .............................................434HONORCC ..........................................437IGNOREDS .........................................438JOBID ................................................440JOBNAME ..........................................441MODE ................................................442MODIFY .............................................444PREDICT ............................................446PREVTIME .........................................450PRINT ................................................452PURGE ...............................................454QUIESCE ............................................458RESTART ...........................................459STATUS .............................................461SUBSYS .............................................462TAPESCR ...........................................466TOSTEP ..............................................470TRACE ...............................................471TYPE..................................................472VOLUME ............................................474WARNING ..........................................476

ENCREQ..................................................478ENCRYPT ................................................484ENCTRACE .............................................487END ........................................................489end

ESP session .........................................489Event definition ....................................490exclusion of JCL ...................................493history report definitions ........................501inclusion of JCL ...................................495job definitions ......................................496model definitions ..................................498output data...........................................494template definitions ...............................502

ENDDEF..................................................490ENDDO ...................................................491ENDEXCL ...............................................493ENDHC ...................................................494ENDINCL ................................................495ending

a model definition .................................498an Event definition ................................490line mode ............................................489

ENDJOB ..................................................496ENDMODEL ............................................498ENDPRINT ..............................................499ENDPROC, End ESP Procedure in an Event ...500ENDR......................................................501ENDTEMPL .............................................502

ENQSELF ................................................503ENQUEUE ....................................... 505, 507enqueue

specify resources that job enqueues on ......507ENVAR ...................................................509error messages ........................................1181ESP .........................................................513ESP Procedure

comments ................................................2continuing a line .......................................1data set names ..........................................2indentation...............................................2invoking ..............................................682

ESP tracking definition table .......................803ESPCOM..................................................515ESPCTR...................................................518espmgr .....................................................520espmsg.....................................................528ESPNOMSG .............................................536ESPSYMBOL ...........................................538establish user exits .....................................566EVENT ............................................ 540, 545Event

do not execute (NOSCHED command) ......901manually-triggered Event , specify installation

default ............................................1289prefix for job monitor, identifying............856specify when not to execute ....................901

Event data set............................................769Event definition commands

ENDPROC...........................................500PROC .................................................983

Event processingspecify ..............................................1017

EVENTCATEGORY ..................................547EVENTCOMPUTER ..................................548EVENTDESCRIPTION...............................549EVENTID ................................................551EVENTLOG_MON ....................................552

specify location of logs (local machine) ....548EVENTOPT..............................................554Events

altering schedule...................................918default for triggering ...........................1289definition

commandNOSCHED ..............................901ROSSUB...............................1088

displaying ........................................755deleting ...............................................294displaying............................................755displaying next scheduled execution .........891

1373

displaying schedule ...............................782expected time .......................................572holding ...............................................652initiator classes.....................................398log, displaying......................................812messages, limiting.................................869overdue .............................................1138resuming ...........................................1082scheduled deletion.................................293scheduled hold......................................654scheduled release of ............................1038scheduled resume ................................1080scheduled suspension ...........................1219scheduling exception .............................901simulating..........................................1179stopping processing .............................1013suspending .........................................1221terminology definition ...............................4triggering ..........................................1290

EVENTSET ..............................................556EVENTSET, displaying ..............................769EVENTSOURCE .......................................559EVENTTYPE statement ..............................560EXCLUDE ...............................................562exclude

data set triggers ....................................370program from status...............................729

excludingJCL ....................................................562programs from tracking ..........................729

EXIT ............................................... 566, 568Exit Codes, specifying ................................571EXITCODE ..............................................571exitcodes

failures, identifying ...............................571exiting from a Procedure .............................568EXPECT ..................................................572Expect Event to Execute .............................572EXPEDITE ....................................... 574, 580

actions ................................................578command .............................................574

EXPIRATION ...........................................582external job

dependencies ......................................1068displaying............................................741

EXTMON.................................................583extract tape information ..............................678EXTSCHEDULER .....................................585

FFAILUREMSG ..........................................586

filerecursive monitoring..............................600running executable files using CMDNAME192

file monitoring ..........................................588file name ..................................................589FILE_TRIGGER

specify files to be monitored (FILENAME)588FileMon ...................................................588FILENAME ..............................................588FILTER ...................................................606find reference to undefined symbols ..............608fixed intervals

specify using XCF SET SERVICE command .....1349

FLAGUNDEF ...........................................608FLOW .....................................................610flow charting

MS Project...........................................632timeline....................................... 610, 630

FLOWDOC...............................................612FOOTING ................................................615force JES status and Pnode queue information .........

1016formatting output .......................................403frequency of job ......................................1093FROM ............................................. 618, 620FTP .........................................................622FTP format

specify within FTP_JOB............... 625, 1285FTP server

specify address (name) within FTP_JOB .1157FTP server port number

specify within FTP_JOB.......................1159FTP_JOB .................................................623

remote filename, specify ......................1044specify FTP format................................625specify FTP format for .........................1285specify FTP server address (name) .........1157specify FTP server port number .............1159specify local file name ...........................808transfer direction, specify ............. 324, 1288

FTPFORMAT ...........................................625

GGENDOC .................................................627generate

copy of jcl ...........................................206flow chart ............................................630job documentation.................................627project ................................................632reports ................................................612times ..................................................635

1374

GENFLOW...............................................630GENPROJ ................................................632GENTIME

command .............................................635variables..............................................636

global variable tableVDEL ...............................................1308VGET ...............................................1309VINCR..............................................1311VPUT ...............................................1312VSET................................................1316VTDEFINE ........................................1317VTDELETE .......................................1318VTLIST ............................................1319VTRDEF ...........................................1321VTRDEL ...........................................1323

GO ..........................................................639GROUP....................................................640group definition, initial user identifying.......1197group prefix, setting ...................................640groups

defining ..............................................254definitions ...........................................771deleting ...............................................295displaying............................................771

HHARDCOPY

command ..............................642, 644, 646file option............................................644sysout option........................................646

HISTFILEcommand ..................................... 648, 650displaying............................................773

history filealtering ...............................................650backing up ...........................................651defining ..............................................650displaying............................................773

history reportending.................................................501fields displayed ....................................333input data set........................................676specifying history file ............................648specifying sort order ............................1191time range ...........................................618

HOLD.............................................. 652, 654hold

an Event ..............................................652Event at specific time ............................654

hold countsspecify ..............................................1034

holdinga job ............................................... 80, 82a sub-Application.............................. 80, 82Events.................................................652

holding Events ..........................................654holidays

defining ..............................................257displaying............................................774multiple ..............................................259processing, Events ................................918

HPUX_JOB ..............................................656

II/O timeout .............................................1267identify

flow chart ............................................610signal conditions.................................1177start of set of instructions .......................350subApplications ..................................1210successors .........................................1041temporary JCL library..........................1238that jobs are controlled by DJC................345the name of

AIX jobs............................................51AS400 jobs.......................................133database jobs.....................................245FTP jobs ..........................................623HPUX jobs .......................................656jobs ................................................697LINUX jobs......................................754NCR Jobs.........................................874OPENVMS jobs.................................921PeopleSoft jobs ................................1005Sequent jobs ...................................1156SUN jobs .......................................1218Tandem jobs ...................................1230UNIX jobs......................................1296Windows NT jobs...............................912

tracking models to transmit ...................1361users as valid ESP user ........................1301where job runs ........................................38Windows NT command to run .................191

identify and set Applications69, 74, 96, 182, 308, 858, 917, 960, 966, 979, 996, 998, 1000, 1002, 1050, 1075

IF ...........................................................657INCLUDE ................................................659include

email body text (PeopleSoft) ...................410email subject (PeopleSoft) ......................409history files in report .............................648SAP cover page with report ....................139

1375

web report (PeopleSoft) .........................411including JCL ...........................................659increment numeric global variables .............1311indicate

completion ...........................................639due out times........................................388

INET .......................................................663INFOCOMM .............................................667INFOCOMM command

control InfoServ transaction servers .........667INFOMSG ................................................669INFOPACK ..............................................671InfoPackage

define data selection criteria ...................936Infoserv requests, sending ...........................667inheriting relationships, simulating .............1179INIT ........................................................672initial users, identifying ............................1197INITIAL_CONTEXT..................................674initialization parameter, terminology definition ...4Initialization parameters, defining agent

receivers ..................................................48initialize/activate trace files .......................1355initiator classes, Events...............................398initiators

controlling for modeling.........................672maximum for modeling ..........................832

INPUT .....................................................676input data set,tape processing.......................678INPUTDS .................................................678insert

break ..................................................155command and statement ...........................77comment .............................................197route statement ...................................1089

insertinga job ............................................... 80, 82a job with a time dependency ....................93

instruct shadow manager ...........................1348INTEGER.................................................680interaction with remote partner Application ..1261intercept messages ...................................1224interval to retry contacting an LU ...............1264introduce DJC ...........................................340INVOKE ..................................................682invoke ESP Procedure.................................682invoking an ESP Procedure..........................682IP address

specify for IP_Monitor within IP_MON job ...................................................685

IP portspecify for IP_Monitor within IP_MON

job ...................................................686IP_MON statement.....................................684IP_MONITOR

specify IP address .................................685specify IP port. .....................................686

IPADDRESS .............................................685IPPORT statement .....................................686issue

command to operating system................1313control command ................................1268ESP command ......................................513

JJ2EE

EJB job definition .................................401EJB Method to be invoked remotely .........838filter for JMS Subscribe jobs...................606Initial Context Factory ...........................674Java class of JMS Message .....................867JMS Publish job definition......................692JMS Subscribe job definition ..................694JNDI name of Connection Factory............201JNDI name of Stateless Session Bean .......146JNDI user ID........................................696Method/Message parameters ...................938ouput destination file .............................313publish/subscribe to Topic/Queue ..........1259Service Provider URL ............................810Topic/Queue ........................................318

JCLchanging symbol introducer ....................538copy of submitted .................................206initial date for temporary JCL library

(TEMPLIB) .......................................620library, identifying ................................687library, time limit for override...............1297member name .......................................836override library, time limit for...............1297scan exit, simulating ............................1179scanning ............................................1134specify limit date for TEMPLIB.............1297submitting from a Librarian data set .........751submitting from a Panvalet data set ..........933submitting from an Event .....................1215submitting from ROSCOE data set .........1088tailoring

excluding JCL ...................................562including JCL....................................659

temporary use.....................................1297

1376

JCL libraryidentifying ...........................................687override ............................................1238specify in DATASET statement ...............241specifying ............................................241temporary ..........................................1238temporary use.......................................620

JCL, specify member name for job execution JCL.......................................................836

JCLLIB ....................................................687JES

changing command character ..................690issuing command from an Event ............1313specify type, see also initialization parameter

JESTYPE ..........................................691status of a job, displaying .........................85

JES3 statement ..........................................340JESCOMCH..............................................690JESTYPE .................................................691JMSP_JOB ...............................................692JMSS_JOB ...............................................694JNDIUSER ...............................................696JOB.........................................................697

specify JCL library and optional member name ................................................241

jobadding libraries.....................................749attributes, changing ...............................708bypassing ........................................ 80, 82change state .........................................528change submission times ........................393completing ....................................... 80, 82controlling ....................................... 80, 82co-requisite ..........................................209co-requisite, automatic selection ..............209co-requisite, name of .............................209data set dependency...............................359defining

command to run .................................198current library....................................232programs to run..................................189where agent runs ..................................38which report to run..............................990Windows NT command to run ................191

delayrelease...........................................1036

deselecting................................... 310, 898displaying

statistics...........................................796documentation

converting to ESP format ......................627displaying ........................................716

library .............................................352library, converting..................... 734, 1047

documentation libary, converting non-ESP, lines to be removed ...........................1047

documentation library, identifying ...........352dropping dependencies ....................... 80, 82due out times........................................388early submission time ............................393eligible for submission, specify hold

count ..............................................1034end of job ............................................496execution class, excluding

from tracking .....................................913hold count .........................................1034holding ........................................... 80, 82identifying

predecessors......................................955report type........................................991successors ........................................949

inheritingdependencies.....................................922

inserting .......................................... 80, 82inserting with a time dependency ...............93late submission time ..............................738listing details .......................................720mapping

data set............................................828successor reports ................................727usage ..............................................720

model, specify ......................................855monitor Events, simulating ...................1179monitoring, group prefix ........................856mutually exclusive, specify .....................909naming ...................................... 912, 1296notification ..........................................903overdue ...............................................388perform action on..................................528post requisites ......................................949predecessors, specify ...............................28prefix of job monitor event, identifying.....856prerequisites ........................................955processing options.................................922queue, specifying ..................................725readying .......................................... 80, 82releasing ......................................... 80, 82releasing successors ............................1041requesting........................................ 80, 82rerunning multiple...............................1051resetting times .................................. 80, 82resource requirements ..........................1070resources to enqueue on .........................507restart step ...........................................922

1377

restarting ......................................... 80, 82resubmitting ..................................... 80, 82routing to another node ........................1089running at a destination ........................1087schedule criteria .................................1149scheduling exceptions ............................898selecting............................................1149specify exit program ..............................169specify jobs to run after job executes ........949specify late submission time ...................738specifying

description........................................714name for job queue..............................724SAP job name..................................1124

starting a unit of work.................. 912, 1296successor information ............................727tagging..............................................1228tracking.............................................1275tracking definitions, specify ..................1275tracking, excluding programs ..................729triggering release ..................................588unbypassing ..................................... 80, 82unrequesting .................................... 80, 82unwaiting ........................................ 80, 82

job tracking definition tableentries...............................................1275loading................................................803wildcards ...........................................1325

JOBATTR ................................................708JOBCLASS...............................................711JOBCOPY ................................................713JOBD ......................................................714JOBENQ ..................................................715JOBINFO .................................................716JOBMAP..................................................720JOBNAME ...............................................724JOBQ ......................................................725JOBRES...................................................726jobs

description for OS/400 job ......................714enqueue on themselves ...........................503handle exceptions to schedule criteia

(NORUN statement) ............................898OS/400 job, name of ..............................724OS/400 queues .....................................725specify do not select ..............................898that must complete before a particular job

executes ............................................955JOBTREE.................................................727join XCF groups ......................................1294JTPEXCL .................................................729jump to next label ......................................731

JUMPTO ..................................................731

LLABEL ....................................................734label documentation library .........................734LANGUAGE.............................................737language

specify for SAP ABAP...........................737LAP ........................................................758late submission time ...................................738late submission, specify for job ....................738LATESUB ................................................738LAX ........................................................741LCMDPRFX .............................................743LDSN ......................................................744LDSTCELL ..............................................745LDTE ......................................................746LDTREL ..................................................747LDXE ......................................................748LIBL .......................................................749Librarian data set

ESP Procedure..........................................2submitting JCL .....................................751

librarydefining current job library .....................232specifying the OS/400 library ..................135

LIBSUB ...................................................751limit

console message number ........................869number of messages ..............................870

limiting Event messages..............................869line mode, ending ......................................489LINES .....................................................753LINUX_JOB .............................................754LIST........................................................755list

Application file ....................................763Applications.........................................758authorization tables ...............................764calendars .............................................766checkpoints ..........................................768command prefixing................................743cross-memory elements ..........................795data set trigger excludes .........................747data set triggers ....................................746data sets ..............................................744data-set-trigger cells ..............................745Event data sets .....................................769Event information .................................755external jobs ........................................741global variable tables...........................1319groups.................................................771

1378

history files .........................................773holidays ..............................................774job mapping information ........................720jobs ....................................................796mailboxes ............................................825objects awaiting triggers ........................748Pnodes ................................................777queue data set.......................................778SADLINKs ..........................................781scheduled activity report ........................813schedules .............................................782signals ................................................785special days .........................................787symbol libraries ....................................790system ................................................817system messages ...................................819time zones ...........................................824tracked jobs .........................................821tracking cells........................................820tracking files ........................................792tracking models ............................ 776, 823user definitions .....................................793XCF command....................................1344

List width (SAP), specify width of ................196LISTAPPL................................................758LISTAPTF................................................763LISTAT ...................................................764LISTCAL .................................................766LISTCKPT ...............................................768LISTEVS .................................................769LISTGRP .................................................771LISTHIST ................................................773LISTHOL .................................................774LISTJTML ...............................................776LISTPN ...................................................777LISTQ .....................................................778LISTROOT ...............................................779LISTSADL ...............................................781LISTSCH .................................................782LISTSIG ..................................................785LISTSPEC ................................................787LISTSYML...............................................790LISTTRAK ...............................................792LISTUSER ...............................................793LISTXMEZ ..............................................795LJ ...........................................................796LOAD......................................................800load

Agent definition....................................802job tracking definition table ....................803MAILLIST data set ...............................805schedule file ........................................806

user profile definition table.....................807LOADAGDF.............................................802loading

ESP command ......................................800job tracking definition table ....................803schedule file ........................................806user profile definition table.....................807

LOADJTDT ..............................................803LOADNL .................................................805LOADSCHF .............................................806LOADUPDT .............................................807local filenames, specify within FTP_JOB .......808LOCALFILENAME ...................................808LOCATION ..............................................810log file, time format for searching

(TEXT_MON) .....................................1252LOGPRT ..................................................812lost I/O time interval. ...............................1267LSAR ......................................................813LSYS............................................... 799, 817LSYSMSGS..............................................819LTCELL ..................................................820LTJ .........................................................821LTM........................................................823LTZONE ..................................................824

MMAILBOX ...............................................825MANAGER ..............................................826Manager

specify address for Agent .......................839manipulate

Class Queues........................................183enqueue list .........................................715initiators .............................................672TCP/IP Attributes .................................663

map user IDs to SAF ..................................830MAPGEN .................................................828MAPUSER ...............................................830masking, job tracking definition table ..........1325MAXCXME..............................................831maximum length of file name .......................589MAXINITS...............................................832MAXQXME..............................................834MCS........................................................835MEMBER.................................................836member name, JCL library...........................836member name, specify to find job JCL ...........836messages

customizing .........................................871customizing for ESP ..............................865displaying in Page mode.........................669

1379

error .................................................1181intercepting system .............................1224Sending .............................................1153sending to ESP Workload Manager...........520

METHOD.................................................838MGRADDR ..............................................839MGRMSG ................................................841MODEL ........................................... 852, 855modeling

ending definition...................................498reports ................................................860starting definition .................................852

module level, displaying .............................799MONITOR ...............................................856monitor

a workload object on an external scheduler ...............................583

content of text file...............................1242disk space ............................................331IP addresses or ports..............................684process execution ..................................986the Windows Event log ..........................552use of CPU ..........................................221Windows services ...............................1161

MONITORDELAY.....................................858monitoring children (Oracle Apps) ................858monitoring children, delay (Oracle Apps) .......858MREPORT ...............................................860MS project file ..........................................632MSG........................................................865MSGCLASS .............................................867MSGLIMIT ..............................................869MSGQLEN ...............................................870MSGTYPE ...............................................871

Nname of external scheduler ..........................585NCR_JOB ................................................874NDS destination profile ..............................876NETAUTH ...............................................875NETDEST ................................................876NETWORK ..............................................882NEXT ......................................................891NJETOL...................................................893no track class ............................................913NOCHECKEXC.........................................894NODE......................................................895non-blank character, do not check last in card

image ....................................................894NORUN ...................................................898NOSCHED ...............................................901NOTIFY...................................................903

notifyusers or consoles...................................903when Agent becomes inactive....................68

NOTWITH ...............................................909NT_JOB...................................................912NT_JOB statement .....................................912NTRCLASS ..............................................913NULLPSWD .............................................914numeric variables ......................................680

OOA_JOB ..................................................915OAUSER..................................................917ON ..........................................................918OPENVMS_JOB........................................921operand, terminology definition........................4operating system command, issuing.............1313OPTIONS.................................................922Oracle Applications....................................308

Application field.....................................74arguments, defaults ...............................127arguments, passing ................................131Concurrent Programs ...........................1002monitoring children ...............................182monitoring children, delay ......................858saving output ........................... 1003, 1133Set Code field ....................................1050Short Name field.................................1002short name, request set .........................1050statements

APPLDISPLNAME ..............................74ARGDEFAULTS ...............................127ARGS.............................................131CHILDMONITOR..............................182DISPLNAME......................................74MONITORDELAY.............................858OA_JOB..........................................915OAUSER.........................................917PRINTCOPIES..................................960PRINTER ........................................966PRINTSTYLE...................................979PROGARGS.....................................992PROGCOPIES...................................996PROGDATA.....................................994PROGPRINTCOPIES..........................996PROGPRINTER ................................998PROGPRINTSTYLE.........................1000PROGRAM ....................................1002PROGSAVEOUTPUT .......................1003REQUESTSET ................................1050RESPNAME...................................1075SAVEOUTPUT ...............................1133

1380

Upon Completion ..960, 966, 979, 998, 1000OS/400

additional parameters, specify ......... 926, 935job name displayed in job queue ..............724programs to run, identifying....................189source files, identifying..........................134specify current library............................232specify library name for CL program ........135specify library to add to user’s list for job .749specify name of job ...............................724specify source file named in AS400FILE

statement ..........................................135OS/400 job

specify description for (JOBD statement) ..714OS/400, specify job queues..........................725OTHERS ..................................................926OUTDESTFORMAT statement.....................927OUTDESTPATH statement..........................929OUTDESTTYPE statement ..........................931output spacing .........................................1193overdue

Events...............................................1138jobs ....................................................388

overridedefault options......................................922JCL library ........................................1238

overview ......................................................1

Ppage mode, display.....................................669PANSUB..................................................933Panvalet data set

ESP Procedures ........................................2submitting ...........................................933

PARAM (OS/400) ......................................935PARAM (SAP) ..........................................936PARAM (SAP) statement ............................936PARAMETER ...........................................938pass operands ............................................129passing environment variables......................509PASSWORD ..................................... 940, 942password

compare to PASSWORD parameter of JOB card, specify ......................................914

specify user ID for Agent job ..................942path, including spaces in .............................192path, using an asterisk in .............................589PCACHE..................................................943PeopleSoft

email addresses, specify .........................406operator ID, specify.............................1007output destination format, specify .... 927, 931

output path, specify ...............................929report to run within PS_JOB ...................990report type within PS_JOB .....................991run parameters....................................1100specify distribution list of operator IDs .....338specify distribution list of roles ...............336time zone...........................................1255

Perl script, running ..................................1142Pnode

user-defined .........................................944PNODES ..................................................944Pnodes

assigning to a job ..................................944displaying............................................777setting defaults .....................................322specifying the name...............................260

positional parameters, specifying for UNIX and Windows NT............................129

POST.......................................................947post

complete signal generations ..................1175job complete ........................................947requisite jobs .......................................949

postinga job from a pnode ................................947a Signal .............................................1175

postponing job submission.........................1036POSTREQ ................................................949PREALLOC..............................................953pre-allocate data sets ..................................953predecessors

identifying .............................................28optional.............................................1034

prefix for ESP console command ..................743PREREQ ..................................................955prerequisite jobs ........................................955preset groups termination ..........................1350print

footing line ..........................................615SAP job, immediately after completion .....971specify line width .................................196specifying authorization string ................975spool recipient....................................1024trace data...........................................1273

PRINTCOPIES .................................. 959, 960PRINTCOVER ..........................................962PRINTDATASET ......................................963PRINTDEPARTMENT ...............................964PRINTDEST .............................................965PRINTER .................................................966PRINTFOOTER ........................................968PRINTFORMAT........................................969

1381

PRINTIMMED ..........................................971PRINTIMMED statement ..........................1024printing trace data ....................................1273PRINTNEWSPOOL....................................972PRINTPRIORITY ......................................973PRINTPW statement...................................975PRINTREL ...............................................976PRINTREQTYPE.......................................977PRINTSPOOLNAME .................................978PRINTSTYLE ...........................................979PRIORITY ...............................................981priority

of workload object in group ....................981PROC, Introduce an ESP Procedure in an Event

Definition ..............................................983Procedure

exiting from .........................................568terminology definition ...............................5

PROCESS ................................................984process instructions conditionally .................657Process, monitored .....................................984PROCESS_MON .......................................986

specify process to be monitored ...............984PROCESSMONITOR .................................988PROCESSNAME .......................................990PROCESSTYPE ........................................991produce job descendant tree .........................727PROGARGS .............................................992PROGCOPIES...........................................996PROGDATA .............................................994PROGPRINTCOPIES .................................996PROGPRINTER ........................................998PROGPRINTSTYLE ................................1000PROGRAM.............................................1002programs

specify exit program in a job ...................169specifying library containing...................135

PROGSAVEOUTPUT...............................1003PS_JOB .................................................1005PSOPRID ...............................................1007purge schedule information........................1008purging CSF information...........................1008PURGSCHF ............................................1008put ESP in a quiesced state ........................1013PUTINOUTBOX......................................1010

QQUERY .................................................1011QUEUE data set, displaying.........................778QUIESCE ...............................................1013QUIT.....................................................1014quit ESP Procedures ......................... 568, 1014

quotation marksputting spaces in

path................................................192single..................................................589using with ARGS statement ....................129with asterisk wildcard ............................589

QUPDATE .............................................1016

RRACROUTE ...........................................1017RANGE statement

see SEARCHRANGE statementreadying

a job ............................................... 80, 82a sub-Application.............................. 80, 82

real resources, refreshing ..........................1076RECIPIENTBCC .....................................1025RECIPIENTCC .......................................1026RECIPIENTEXPRESS ..............................1027RECIPIENTFORWARD............................1028RECIPIENTPRINT ..................................1029RECIPIENTTYPE....................................1030recursive file monitoring .............................600re-establish the connection ........................1266REEXEC ................................................1031re-execute Procedures ...............................1031re-executing ESP Procedures .....................1031refresh

devices list ........................................1076tables ................................................1108

RELCOUNT ...........................................1034RELCOUNT statement

specify hold counts for submission eligible jobs.....................................1034

RELDELAY ...........................................1036RELEASE .................................... 1038, 1040release resources at end of step ..................1206releasing

a job ............................................... 80, 82a sub-Application.............................. 80, 82Event ................................................1038Event for processing ............................1040

remote Applications .................................1261REMOTEFILENAME ...............................1044REMOVE ...............................................1047remove

entries from NOTWITH list ....................356members............................................1336resource names from enqueue list.............307

removingjob dependencies.....................................85lines in job.........................................1047

1382

reopen VTAM ACB..................................1265REPORT ................................................1049report

identifying type ....................................991specifying which to run ..........................990

reportingselection criteria ...................................223

reporting, scheduled activity ........................813request

exclusion of JCL ...................................562inclusion of JCL ...................................659inclusions ..........................................1222

request input from data set ..........................676requesting

a job ............................................... 80, 82a sub-Application .............................. 80, 82

REQUESTSET ........................................1050RERUNM...............................................1051RESDEF ................................................1055RESDFLT ..............................................1064reserving resources ......................................25resetting times of a job ........................... 80, 82RESOLVE ..............................................1068resolve external job dependencies ...............1068RESOURCE............................................1070resource

default, identify ..................................1064that job enqueues on ..............................507

resourcesdefault ..............................................1064defining ............................................1055deleting .............................................1055displaying..........................................1055identifying .........................................1070job priority ..........................................981job requirements .................................1070refreshing ..........................................1076reserving for a job ...................................25setting...............................................1055

RESPNAME ...........................................1075RESREFR ..............................................1076RESTART ..............................................1077restart

Events scheduling/Application processing .......................................1077

XCF services......................................1354restarting

Event proccessing ...............................1077TP Server ..........................................1265

RESTORE ..............................................1078restore ESP data sets ................................1078restrictions

file name .............................................589RESUME ..................................... 1080, 1082resuming an Event ......................... 1080, 1082retrieve

data from data object ...........................1331global variables ..................................1309

REXX processingending...............................................1083starting .............................................1084

REXXOFF..............................................1083REXXON ...............................................1084RFCDEST ..............................................1087ROSCOE data sets,submitting JCL from ......1088ROSSUB ................................................1088ROUTE..................................................1089route proxies subsystem requests ................1091ROUTING ..............................................1091routing jobs to another node ......................1089RUN......................................................1093run

ABAP steps within an SAP job ..................21job-specific command ..........................1329OS/400 command ..................................198

RUNCONTROLID ...................................1100

SSADGEN ....................................... 612, 1102SADLINK ..............................................1106SADLINKs, displaying ...............................781SADLOAD .............................................1108SADUPD................................................1110SAF security options ................................1111SAFOPTS...............................................1111SAP

ABAP, specify failure message for ...........586advanced logging of Batch Input Session...143application server, specify ....................1130archive, data element for user..................124archive, document type ..........................103archive, link archiving date.....................100archive, link document class ...................101archive, link information ........................107archive, link report name ........................116archive, link RPC host ...........................105archive, link RPC service/destination .......118archive, link target storage system ...........120archive, link Text Information field ..........122archive, output format............................104archive, specify the mode .......................108archive, storage connection protocal .........114archive, target printer ............................113archive, version number .........................125

1383

archiving object ....................................109archiving object variant..........................111authorization string for viewing print

spool list ...........................................975background server processing of Batch Input

Session .............................................145Batch Input Session (BDC) job definition ..140blind carbon copy spool .......................1025Business Warehouse InfoPackage.............671Business Warehouse InfoPackage job

definition .........................................157Business Warehouse Process Chain ..........176Business Warehouse Process Chain job

definition ..........................................159carbon copy spool ...............................1026client ................................................1118copy an existing job ..............................713cover page text .....................................962Data Archiving job definition ................1116deletion of spool request, specify .............976destination .........................................1087Event Monitor job definition .................1119event to monitor or trigger ......................545express delivery of spool ......................1027external system archive ..........................110forwarding of spool .............................1028InfoPackage data selection criteria ...........936job class ............................................1123job definition .....................................1114job, specify failure message for .............1122language for ABAP ...............................737language for login ...............................1126list, specify line width ...........................196maximum acceptable error rate ................142minimum acceptable process rate .............144monitor process status............................988monitoring of children jobs .....................181number of lines per list page ...................753output format for report..........................969post job log and spool on web ...............1324print department name ...........................964print destination....................................965print footer on report .............................968print immediately after job completion......971print new spool request ..........................972print request type ..................................977print spool data set name ........................963print spool name ...................................978printing of spool .................................1029Process Monitor job definition ..............1127recipient name for SAP cover page.........1024recipient type of spool .........................1030

report, specify number of copies ..............959RFC logon for SAP system user .............1131save outgoing documents to outbox ........1010spool recipient....................................1195spool request priority .............................973spool request, specify expiration of ..........582standard archive path .............................112startmode for readied job, specify ..........1200success message for ABAP ...................1217success message for SAP job.................1129user for ABAP program (SAP) ..............1208variant name, specify ...........................1307

SAP_JOB ...............................................1114SAPA_JOB.............................................1116SAPCLIENT ...........................................1118SAPE_JOB .............................................1119SAPEMAILADDR ...................................1121SAPEMAILADDR, job level........................407SAPFAILUREMSG ..................................1122SAPJOBCLASS.......................................1123SAPJOBNAME statement, step level ...........1124SAPLANGUAGE statement,

job level, description..............................1126SAPM_JOB ............................................1127SAPSUCCESSMSG..................................1129SAPTARGETSYSTEM .............................1130SAPUSER ..............................................1131SAVEOUTPUT .......................................1133SCAN ....................................................1134scan JCL data set .....................................1134SCHEDULE............................................1138schedule

frequency ..........................................1093schedule criteria

Events...............................................1138jobs ..................................................1149subApplications ..................................1149testing...............................................1240

scheduled activity data setcreating .............................................1102internal identifier ................................1106loading..............................................1108updating ............................................1110

scheduled activity report, displaying .............813scheduled Events, displaying .......................782script

naming the .........................................1141Perl ..................................................1142running with a specific shell .................1171

SCRIPTNAME ........................................1141

1384

SCRIPTNAME statementidentifying

the shell script to run.........................1141search range within TEXT_MON ...... 1020, 1144SEARCHRANGE.....................................1144SECURE ................................................1148securing symbols .....................................1148security

Agent Security File .............................1303security options, SAF ...............................1111SELECT.................................................1149select

jobs or subApplications ........................1149model reports .......................................860SMF record ..........................................622

SEND ....................................................1153send messages

to Agent ................................................41to ESP Manager ....................................520to ESP manager ..................................1190to manager ...........................................841

Sending a message ...................................1153SEQUENT_JOB ......................................1156SERVERADDR .......................................1157SERVERPORT ........................................1159SERVICE_MON ......................................1161SERVICENAME......................................1162SET.......................................................1163set

abend queue size ......................... 779, 1051an environment variable .......................1163console ...............................................202data repositories ...................................239date format ..........................................243default output .....................................1164distribution folder (PeopleSoft) ...............335global variables ..................................1316job resources ........................................726maximum space – checkpoint file.............831maximum space – queue file ...................834messages .............................................865messages from type ...............................871NJE tolerance .......................................893output width.......................................1166start time ...........................................1251status check interval ............................1201templates ...........................................1234various tracking options .......................1282

set abend queue size .....................................23set or display default Pnodes........................322SETPRINT .............................................1164

settinga group prefix.......................................640resources ...........................................1055tracking options ..................................1282

SETVAR ................................................1165SETWIDTH ............................................1166SHADGOAL...........................................1167SHADOW ..............................................1169SHELL ..................................................1171SIGCYCLE.............................................1173signals

cycling ..............................................1173deleting ...............................................299displaying............................................785posting ..............................................1175waiting on .........................................1177

SIGPOST ...............................................1175SIGWAIT...............................................1177SIMULATE ............................................1179simulate Event functions ...........................1179simulating

an Event ............................................1179inheriting relationships ........................1179job monitor Events ..............................1179USER variables ..................................1179

SKIPPARMUPDATES..............................1187skipping procedure code..............................731SMF recording, controlling........................1280SMF records, data set triggers ......................379SMF statistics .........................................1189SMFSTATS ............................................1189SNDESPMSG .........................................1190SORT ....................................................1191SORT command

specify ascending/descending sort sequence .........................................1191

sorting report data....................................1191SPACE ..................................................1193spacing output .........................................1193special days, defining .................................272SPINLOG...............................................1194spool files, clearing ....................................187spool trace data .......................................1353SPOOLRECIPIENT..................................1195SPUSER.................................................1197SQL ......................................................1198SQL statement within DB_JOB, specify .......1011start

Event definition ....................................540model process ......................................852reporting from ......................................618

STARTMODE.........................................1200

1385

statement%ENDEXCL ........................................493%ENDINCL .........................................495%EXCLUDE ........................................562%INCLUDE .........................................659//* FROM ............................................620//* UNTIL .........................................1297//*ESPSYMBOL ...................................538terminology definition ...............................5ABANDON DEPENDENCIES...................14ABANDON RESOURCES ........................16ABANDON SUBMISSION .......................18ABAPNAME..........................................21AGENT.................................................38AIX_JOB ..............................................51AMNOTIFY...........................................68APPL....................................................69APPLDISPLNAME .................................74APPLEND .............................................75ARCDATE ..........................................100ARCDOCCLASS ..................................101ARCDOCTYPE ............................ 103, 107ARCFORMAT......................................104ARCHOSTLINK ...................................105ARCMODE..........................................108ARCOBJNAME ....................................109ARCOBJTYPE .....................................110ARCOBJVARIANT...............................111ARCPATH...........................................112ARCPRINTER......................................113ARCPROTOCOL ..................................114ARCREPORT.......................................116ARCSERVICE......................................118ARCSTORAGE ....................................120ARCTEXT ...........................................122ARCUSER ...........................................124ARCVERSION .....................................125ARGDEFAULTS ..................................127ARGS ......................................... 129, 131AS400_JOB .........................................133AS400FILE..........................................134AS400LIB ...........................................135BANNER ............................................138BANNERPAGE ....................................139BDC_JOB............................................140BDCERRRATE ....................................142BDCEXTLOG ......................................143BDCPROCRATE ..................................144BDCSYSTEM ......................................145BEAN .................................................146BWIP_JOB ..........................................157BWPC_JOB .........................................159

CCCHK...............................................163CCEXIT ..............................................169CCFAIL ..............................................170CHAIN ...............................................176CHECKEXC ........................................178CHILDMONITOR......................... 181, 182CLPNAME ..........................................189CMDNAME .........................................191COLUMNS ..........................................196COMMAND.........................................198CONNECTION_FACTORY ....................201COPYJCL............................................206COREQ...............................................209CPU ...................................................218CPU_MON ..........................................221CRITPATH ..........................................228CURLIB..............................................232DATA_OBJECT ...................................239DATASET ...........................................241DELAYSUB ........................................289DEQUEUE ..........................................307DESC .................................................308DESCRIPTION.....................................308DESELECT .........................................310DEST..................................................313DESTINATION ....................................316DESTNAME ........................................318DIRECTION ........................................324DISABLE_RESTART ............................325DISK ..................................................327DISK_MON .........................................331DISTRFOLDER....................................335DISTRLISTROLES ...............................336DISTRLISTUSERS ...............................338DJCDATA ...........................................340DJCNET..............................................345DO .....................................................350DOCLIB..............................................352DROPNOTW .......................................356DSN ...................................................357DSNAME ............................................359DSTRIG ..............................................384DUEOUT ............................................388DURATION .........................................392EARLYSUB.........................................393EJB_JOB.............................................401ELSE ..................................................404EMAILADDR .............................. 406, 407EMAILLOG .........................................408EMAILSUBJECT..................................409EMAILTEXT .......................................410EMAILWEBREPORT ............................411

1386

ENDDO ..............................................491ENDJOB .............................................496ENDTEMPL ........................................502ENQUEUE ..........................................507ENVAR...............................................509ESP ....................................................513ESPNOMSG ........................................536EVENT ...............................................545EVENTCATEGORY..............................547EVENTCOMPUTER..............................548EVENTDESCRIPTION ..........................549EVENTID............................................551EVENTLOG_MON ...............................552EVENTSOURCE ..................................559EVENTTYPE .......................................560EXIT ..................................................568EXITCODE .........................................571EXPEDITE ..........................................580EXPIRATION ......................................582EXTMON ............................................583EXTSCHEDULER ................................585FAILUREMSG .....................................586FILENAME .........................................588FILTER...............................................606FLAGUNDEF.......................................608FTP_JOB.............................................623FTPFORMAT.......................................625HPUX_JOB .........................................656IF.......................................................657INFOPACK .........................................671INITIAL_CONTEXT .............................674INPUTDS ............................................678INTEGER ............................................680IP_MON..............................................684IPADDRESS ........................................685IPPORT ..............................................686JCLLIB ...............................................687JMSP_JOB ..........................................692JMSS_JOB ..........................................694JNDIUSER ..........................................696JOB ....................................................697JOBATTR ...........................................708JOBCLASS ..........................................711JOBCOPY ...........................................713JOBD..................................................714JOBNAME ..........................................724JOBQ..................................................725JUMPTO .............................................731LANGUAGE ........................................737LATESUB ...........................................738LIBL ..................................................749LINES ................................................753

LINUX_JOB ........................................754LOCALFILENAME...............................808LOCATION .........................................810MEMBER............................................836METHOD ............................................838MODEL ..............................................855MONITOR...........................................856MONITORDELAY................................858MSGCLASS.........................................867MSGLIMIT..........................................869MSGQLEN ..........................................870NCR_JOB............................................874NOCHECKEXC....................................894NORUN ..............................................898NOTIFY..............................................903NOTWITH...........................................909NT_JOB ..............................................912OA_JOB..............................................915OAUSER.............................................917OPENVMS_JOB ...................................921OPTIONS ............................................922OTHERS .............................................926OUTDESTFORMAT..............................927OUTDESTPATH...................................929OUTDESTTYPE ...................................931PARAM ..............................................935PARAM (SAP) .....................................936PARAMETER ......................................938PASSWORD ........................................942PNODES .............................................944POSTREQ ...........................................949PREREQ .............................................955PRINTCOPIES ............................. 959, 960PRINTCOVER .....................................962PRINTDATASET..................................963PRINTDEPARTMENT...........................964PRINTDEST ........................................965PRINTER ............................................966PRINTFOOTER....................................968PRINTFORMAT ...................................969PRINTIMMED ........................... 971, 1024PRINTNEWSPOOL...............................972PRINTPRIORITY .................................973PRINTPW ...........................................975PRINTREL ..........................................976PRINTREQTYPE..................................977PRINTSPOOLNAME.............................978PRINTSTYLE ......................................979PRIORITY...........................................981PROCESS............................................984PROCESS_MON...................................986PROCESSMONITOR.............................988

1387

PROCESSNAME ..................................990PROCESSTYPE....................................991PROGARGS ........................................992PROGCOPIES ......................................996PROGDATA ........................................994PROGPRINTCOPIES ............................996PROGPRINTER....................................998PROGPRINTSTYLE............................1000PROGRAM ........................................1002PROGSAVEOUTPUT ..........................1003PS_JOB.............................................1005PSOPRID ..........................................1007PUTINOUTBOX.................................1010QUERY.............................................1011QUIT ................................................1014RANGE, see SEARCHRANGERECIPIENTBCC.................................1025RECIPIENTCC...................................1026RECIPIENTEXPRESS .........................1027RECIPIENTFORWARD .......................1028RECIPIENTPRINT..............................1029RECIPIENTTYPE ...............................1030REEXEC ...........................................1031RELCOUNT ......................................1034RELDELAY.......................................1036REMOTEFILENAME ..........................1044REQUESTSET ...................................1050RESOLVE .........................................1068RESOURCE .......................................1070RESPNAME ......................................1075REXXOFF .........................................1083REXXON ..........................................1084RFCDEST .........................................1087ROUTE .............................................1089RUN .................................................1093RUNCONTROLID ..............................1100SAP_JOB ..........................................1114SAPA_JOB ........................................1116SAPCLIENT ......................................1118SAPE_JOB ........................................1119SAPEMAILADDR ..............................1121SAPEMAILADDR, job level ...................407SAPFAILUREMSG .............................1122SAPJOBCLASS ..................................1123SAPJOBNAME, step level ....................1124SAPLANGUAGE, job level ..................1126SAPM_JOB .......................................1127SAPSUCCESSMSG.............................1129SAPTARGETSYSTEM ........................1130SAPUSER .........................................1131SAVEOUTPUT...................................1133SCRIPTNAME ...................................1141

SEARCHRANGE ................................1144SECURE ...........................................1148SELECT............................................1149SEQUENT_JOB..................................1156SERVERADDR ..................................1157SERVERPORT ...................................1159SERVICE_MON .................................1161SERVICENAME.................................1162SHELL..............................................1171SKIPPARMUPDATES .........................1187SPOOLRECIPIENT.............................1195SQL..................................................1198STARTMODE ....................................1200STATINV..........................................1201STATUS ...........................................1203STEPEND .........................................1206STEPUSER ........................................1208SUBAPPL .........................................1210SUCCESSMSG...................................1217SUN_JOB..........................................1218TAG .................................................1228TANDEM_JOB ..................................1230TEMPLATE .......................................1234TEMPLIB ..........................................1238TEXT_MON ......................................1242TEXTFILE ........................................1244TEXTSTRING....................................1246THEN ...............................................1249TIMEFORMAT ..................................1252TIMEZONE .......................................1255TOPIC ..............................................1259TRANSFERCODETYPE ......................1285TRANSFERDIRECTION......................1288UNIX_JOB ........................................1296USER ...............................................1302VARIANT .........................................1307WEBPOSTING ...................................1324WOBDATA .......................................1331

StatementsAFTER .................................................28

statementsEMAILADDR, step level............ 406, 407NT_JOB ..............................................912UNIX_JOB ........................................1296

STATINV...............................................1201STATUS ...................................... 1202, 1203status

IP address and port (IP_MON) ..............1203process (PROCESS_MON) ...................1203service (SERVICE_MON) ....................1203

STDERR ..................................................510STDIN .....................................................510

1388

STDOUT..................................................510STEPEND ..............................................1206STEPUSER.............................................1208stop

all XCF group members .......................1356trace file............................................1359XCF members ....................................1357XCF services......................................1358

stopping, Event processing ........................1013storage cells, tracing ..................................173store global variables................................1312subAgent ................................................1209SUBAPPL ..............................................1210subApplications

deselecting...........................................310displaying............................................758identifying .........................................1210schedule criteria .................................1149

submission time, late ..................................738submission, delaying ..................................289submission, late, specify for job ...................738SUBMIT ................................................1215submit

JCL ..................................................1088JCL from Librarian data set ....................751JCL from Panvalet ................................933JCL into internal reader........................1215job without resource dependencies .............16

submitting JCL from an Event ....................1215SUCCESSMSG .......................................1217successors, releasing ................................1041SUN_JOB...............................................1218supress responses .......................................536SUSPEND .................................... 1219, 1221suspend Events .............................. 1219, 1221suspending, an Event ...................... 1219, 1221switch group access....................................640symbolic variable libraries

defining ..............................................275deleting ...............................................302displaying............................................790including in an Event ...........................1222

symbolic variablesallowing undefined ..................................54changing introducer character in JCL........538excluding data ......................................178footing string .......................................615integers ...............................................680title string..........................................1256

SYMLIB ................................................1222syntax conventions .........................................6SYSMSGS ..............................................1224

system identifier, displaying ........................817system messages

displaying............................................819intercepting........................................1224

TTAG ......................................................1228tag jobs ..................................................1228TANDEM_JOB .......................................1230tape

pull list ...............................................678usage count control .............................1231

TAPETRAK............................................1231TCELLs, displaying ...................................820TCP/IP attributes

address................................................839displaying............................................663setting.................................................663

TEMPLATE............................................1234templates

ending.................................................502starting .............................................1234

TEMPLIB...............................................1238temporary JCL, limiting use.......................1297terminate

active members...................................1342communication ...................................1266

terminate and restart XCF services ..............1346termination of conversations ......................1266TEST.....................................................1240testing, schedule criteria ...........................1240text file, name and location for

text search within TEXT_MON................1244text string, search for within TEXT_MON ....1246TEXT_MON ...........................................1242

search range, specify ................. 1020, 1144TEXTFILE .............................................1244TEXTSTRING ........................................1246THEN ....................................................1249TIME.....................................................1251time dependency

late submission time ..............................738time format for searching log file

within TEXT_MON ...............................1252time period for modeling ...........................1251time zone (PeopleSoft)..............................1255time zones

displaying............................................824TIMEFORMAT .......................................1252timeline ...................................................630TIMEZONE ............................................1255TITLE ...................................................1256

1389

titles, defining .........................................1256TOPIC ...................................................1259TPAPPL.................................................1261TPDISP..................................................1263TPRETRY ..............................................1264TPSTART ..............................................1265TPTERM................................................1266TPTIME.................................................1267TPTRAN ................................................1268TRACE ..................................................1269trace

data setsdisplaying ........................................812identifying......................................1271

data, printing......................................1273storage cell usage..................................173

TRACEDEF ............................................1271TRACEPRT ............................................1273TRACKDEF ...........................................1275tracked job definitions, displaying ................821TRACKING ............................................1280tracking

enabling and disabling .........................1280exclude from ........................................913excluding programs ...............................729models

cross-system tracking.........................1361defining ...........................................279deleting ...........................................305displaying ........................................823displaying buffers ...............................776overriding definition ............................855replacing..........................................279

models, specify.....................................855setting options ....................................1282

tracking definitions, specify.......................1275TRACKOPT ...........................................1282TRAKFILE, displaying ...............................792transaction

handlerstarting ..........................................1268stopping.........................................1268

processing module...............................1268servers ................................................667

TRANSFERCODETYPE ...........................1285TRANSFERDIRECTION ..........................1288TRDFLT ................................................1289TRIGGER ..............................................1290trigger default .........................................1289triggering an Event ..................................1290TRYJOIN ...............................................1294turn off

flagging of undefined symbols...................54REXX processing................................1083

turn on REXX processing ..........................1084

UUNALLOC .............................................1295unallocating a data set ..............................1295unbypassing

a job ............................................... 80, 82a sub-Application.............................. 80, 82

undefined symbols .....................................608undefined symbols, allowing..........................54unit of work. See jobUNIX

shell script to run, specify ....................1141shell to run script, specify ....................1171

UNIX_JOB .............................................1296UNIX_JOB statement ...............................1296unrequesting

a job ............................................... 80, 82a sub-Application.............................. 80, 82

unwaiting a sub-Application .................... 80, 82update scheduled activities ........................1110updating

queues ..............................................1016scheduled activity dataset .....................1110

usage of ESP, displaying ...........................1299USE ......................................................1299use Procedure caching ................................943USER .......................................... 1301, 1302user

defining ..............................................283definitions, displaying ...........................793deleting ...............................................306ID, specifying password .........................942modifications .....................................1305password, specifying .............................942profile definition table, loading ...............807

user definition, initial user identifying .........1197USER variables, simulating .......................1179USERMOD.............................................1305USERMOD 56, affect on priority ..................981

VVARIANT ..............................................1307VDEL ....................................................1308verify two XCF members ..........................1360VGET ....................................................1309view XCF attributes .................................1338VINCR ..................................................1311VPUT ....................................................1312

1390

VS ........................................................1313VSET ....................................................1316VTDEFINE.............................................1317VTDELETE ............................................1318VTLIST .................................................1319VTRDEF ................................................1321VTRDEL................................................1323

WWEBPOSTING........................................1324WILDCARD ...........................................1325WILDCARD command

Define Wildcards for JTDT .....................1325wildcard, asterisk

in file names ........................................589Windows Event

category within EVENTLOG_MON..........547description within EVENTLOG_MON ......549ID within EVENTLOG_MON, specify ......551source within EVENTLOG_MON ............559type within EVENTLOG_MON ...............560

Windows Event log, specify local machine (EVENTLOG_MON)................................548

Windows service name, specify within SERVICE_MON ...................................1162

WLM.....................................................1327WOBCMD..............................................1329WOBDATA ............................................1331WOBDEF ...............................................1332work with active jobs .................................724workdays, specifying ..................................251workload object, terminology definition.............5WORKMGR ...........................................1334

XXCF command

DELETE ...........................................1336DISPLAY ..........................................1338FORCE .............................................1342HELP................................................1344PURGE .............................................1346SET SERVICE ...................................1349SET TERMOPT ..................................1350SET TRACE ......................................1352SPIN TRACE .....................................1353START SERVICE ...............................1354START TRACE ..................................1355STOP GROUP ....................................1356STOP MEMBER .................................1357STOP SERVICE .................................1358STOP TRACE ....................................1359

VERIFY ............................................1360XCF DELETE .........................................1336XCF DISPLAY........................................1338XCF FORCE ...........................................1342XCF HELP .............................................1344XCF PURGE...........................................1346XCF SET MEMBER.................................1348XCF SET SERVICE .................................1349

specify fixed intervals..........................1349XCF SET TERMOPT................................1350XCF SET TRACE ....................................1352XCF SPIN TRACE...................................1353XCF START SERVICE.............................1354XCF START TRACE................................1355XCF STOP GROUP..................................1356XCF STOP MEMBER...............................1357XCF STOP SERVICE ...............................1358XCF STOP TRACE ..................................1359XCF VERIFY..........................................1360XMEs, displaying ......................................795XMITMDL .............................................1361

Zz/OS command, issuing from an Event .........1313