Scheduler Operational Environment - Nordic TWS conference

Scheduler Operational Environment (Early-Release) – Version 2.1.02Installation and User GuideCopyright IBM 2008 Page 1

1 Scheduler Operational Environment......................................................................81.1 Introduction....................................................................................................81.1.1 Early release and forthcoming features..................................................81.2 Version support..............................................................................................81.2.1 Small Product Enhancements ................................................................91.3 Language support.........................................................................................101.4 Change History ............................................................................................111.5 General features ...........................................................................................121.5.1 Command language .............................................................................121.5.2 Output files...........................................................................................141.5.3 Batch loader .........................................................................................141.5.4 Mass Update.........................................................................................151.5.5 Segment Processing Exits....................................................................151.6 TWS Program Interface Concepts ...............................................................151.6.1 Data Sources and Structures ................................................................151.6.2 Requests ...............................................................................................172 Installation............................................................................................................182.1 Installation libraries .....................................................................................182.2 Getting the software onto the mainframe.....................................................182.3 Receiving the file .........................................................................................192.4 Performing setup..........................................................................................192.5 Use of EQQYPARM....................................................................................232.6 REXX compilation.......................................................................................243 General usage.......................................................................................................253.1 In Batch........................................................................................................253.2 Online...........................................................................................................253.3 From other REXX programs........................................................................263.4 Specifying the subsystem.............................................................................263.5 Syntax ..........................................................................................................263.5.1 Comparators.........................................................................................273.5.2 Dates and Times...................................................................................283.5.3 Termination, line numbers and continuation .......................................283.5.4 Comments ............................................................................................293.5.5 Resource names ...................................................................................294 Command statement reference.............................................................................314.1 BACKUP – TWS TSO Command...............................................................314.2 BULKDISC – TWS TSO Command...........................................................314.3 DELETE – Delete object from database or plan .........................................314.3.1 Return Code .........................................................................................314.3.2 DELETE AD – Application Definition ...............................................324.3.3 DELETE AWSCL – All Workstations Closed....................................324.3.4 DELETE CL – Calendar......................................................................324.3.5 DELETE CPOC – Current Plan Occurrence .......................................324.3.6 DELETE CPOP – Current Plan Operation ..........................................324.3.7 DELETE CPPRE – Current Plan Predecessor.....................................324.3.8 DELETE CPSR – Current Plan Operation Special Resource..............324.3.9 DELETE CPSUC – Current Plan Successor .......................................334.3.10 DELETE ETT – Event Trigger............................................................334.3.11 DELETE IVL – Current Plan Workstation Interval ............................334.3.12 DELETE JCLV – JCL Variable Table ................................................33Copyright IBM 2008 Page 2

4.3.13 DELETE JL – Job Log ........................................................................334.3.14 DELETE JS – Current Plan JCL..........................................................344.3.15 DELETE LTOC – Long Term Plan Occurrence .................................344.3.16 DELETE LTPRE – Long Term Plan Predecessor...............................344.3.17 DELETE OI – Operator Instruction.....................................................354.3.18 DELETE PR – Period ..........................................................................354.3.19 DELETE SR – Special Resource.........................................................354.3.20 DELETE WS – Workstation................................................................354.4 EXECUTE – Commit updates to the Current Plan......................................354.4.1 Return Code .........................................................................................364.5 JSUACT – TWS TSO Command ................................................................364.6 INIT – Initialize communication with TWS................................................364.6.1 Return code ..........................................................................................364.6.2 INIT subsystem....................................................................................374.7 INSERT – Add objects into the plan ...........................................................384.7.1 Return Code .........................................................................................394.7.2 INSERT CPOC – Current Plan Occurrence ........................................394.7.3 INSERT CPOP – Current Plan Operation ...........................................404.7.4 INSERT CPPRE – Current Plan Predecessor......................................414.7.5 INSERT CPSAI – Current Plan System Automation Info ..................414.7.6 INSERT CPSR – Current Plan Operation Special Resource...............414.7.7 INSERT CPSUC – Current Plan Successor.........................................424.7.8 INSERT IVL – Current Plan Workstation Interval .............................424.7.9 INSERT JCLPREP – JCL Preparation ................................................424.7.10 INSERT JCLV – JCL Variable Table .................................................424.7.11 INSERT LTOC – Long Term Plan Occurrence ..................................434.7.12 INSERT LTPRE – Long Term Plan Predecessor................................434.8 LIST – Find objects in the Database and Plans ...........................................444.8.1 Return Code .........................................................................................444.8.2 MATCHTYP Argument ......................................................................454.8.3 SAVELIST Argument .........................................................................454.8.4 TAG Argument ....................................................................................464.8.5 LIST ADCOM/ADKEY – Application ID/Application Key ..............464.8.6 LIST AWSCL – All Workstations Closed...........................................474.8.7 LIST CLCOM - Calendar ....................................................................474.8.8 LIST CPOC – Current Plan Occurrence..............................................474.8.9 LIST CPOPCOM – Current Plan Operation........................................484.8.10 LIST CPOPSRU – Current Plan Operation SR Usage ........................494.8.11 LIST CPWSCOM – Current Plan Workstation...................................494.8.12 LIST CSRCOM – Current Plan Special Resource ..............................494.8.13 LIST ETT – Event Triggers.................................................................494.8.14 LIST JCLVCOM – JCL Variable tables..............................................494.8.15 LIST JSCOM – Current Plan JCL .......................................................504.8.16 LIST LTOCCOM – Long Term Plan Occurrence...............................504.8.17 LIST OICOM – Operator Instructions.................................................504.8.18 LIST PRCOM – Period........................................................................504.8.19 LIST SRCOM – Special Resource ......................................................504.8.20 LIST WSCOM – Workstation .............................................................514.9 LISTSTAT – List Status of Current Plan Objects .......................................524.9.1 Return Codes........................................................................................53Copyright IBM 2008 Page 3

4.10 MODIFY – Modify objects in the plans......................................................544.10.1 Return Code .........................................................................................554.10.2 MODIFY CPEXT – Current Plan Extended Operation Info ...............554.10.3 MODIFY CPOC – Current Plan Occurrence.......................................554.10.4 MODIFY CPOP – Current Plan Operation .........................................564.10.5 MODIFY CPSAI – Current Plan System Automation Info.................574.10.6 MODIFY CPWS – Current Plan Workstation.....................................584.10.7 MODIFY CSR – Current Plan Special Resource ................................594.10.8 MODIFY IVL – Current Plan Workstation Info .................................594.10.9 MODIFY LTOC – Long Term Plan Occurrence.................................604.11 OPINFO – TWS TSO Command ................................................................604.12 OPSTAT – TWS TSO Command................................................................604.13 OPTIONS – Define run time options/PIF request .......................................61ACTION ..............................................................................................................61ADOICHK ...........................................................................................................61ADVALFROM ....................................................................................................61ADVERS..............................................................................................................61ARGUMENT.......................................................................................................62CHECK................................................................................................................62COMMIT .............................................................................................................62COMEND ............................................................................................................62COMSTART........................................................................................................62CONTENTION....................................................................................................63CPDEPR ..............................................................................................................63DATE...................................................................................................................64DATA ..................................................................................................................64DELAY ................................................................................................................65DELAYCMD.......................................................................................................65DELETE ..............................................................................................................65DELFILE .............................................................................................................65DURSEC..............................................................................................................66DURUNIT............................................................................................................66EQQYLTOP ........................................................................................................67EXECUTE ...........................................................................................................67EXIT ....................................................................................................................67EXITUSE.............................................................................................................68EXPAND .............................................................................................................68FASTPATH .........................................................................................................68FIELDSEP ...........................................................................................................69FILESPEC............................................................................................................69FIRST...................................................................................................................69HIGHRC ..............................................................................................................70INPUT..................................................................................................................70LABELSEP..........................................................................................................70LAST....................................................................................................................70LOADER .............................................................................................................71LTDEPR ..............................................................................................................71OUTMASK..........................................................................................................71MEMORY............................................................................................................71MSGLEVEL ........................................................................................................72Copyright IBM 2008 Page 4

OPMSG................................................................................................................72PGMPIF ...............................................................................................................72PGMSTOR...........................................................................................................72PGMWAIT ..........................................................................................................72POSTPROC .........................................................................................................73RECONNECT......................................................................................................73REPORT ..............................................................................................................73RETMSG .............................................................................................................73RETMSGID .........................................................................................................73RUNSTAT ...........................................................................................................74SENDDATA........................................................................................................74SENDLOADER...................................................................................................74SELECT...............................................................................................................74SEVERITY ..........................................................................................................75SILENT................................................................................................................75SPE.......................................................................................................................75SHOWDFLT........................................................................................................75STOPRC ..............................................................................................................75STRIP...................................................................................................................76SUBSYS ..............................................................................................................76SUFFIX................................................................................................................76SUPMSG..............................................................................................................77SYSID..................................................................................................................77TIME....................................................................................................................78TRACE ................................................................................................................78TRACKERS.........................................................................................................79VERADGRD .......................................................................................................79VERSION ............................................................................................................79VERSRWSN........................................................................................................804.13.1 OPTIONS keyword abbreviation.........................................................804.14 OUTPUT – Define output record ...............................................................814.14.1 Specifying Output Destinations ...........................................................824.14.2 Additional fields...................................................................................834.15 REPLACE – PIF request .............................................................................834.16 RESET – PIF request ...................................................................................834.16.1 Return Codes........................................................................................834.17 SELECT – Retrieve a record or common segment......................................844.17.1 Return Codes........................................................................................854.17.2 TAG Argument ....................................................................................854.17.3 SELECT AD/ADCOM – Application Definition................................864.17.4 SELECT AWSCL – All Workstations Closed ....................................864.17.5 SELECT CL/CLCOM - Calendar........................................................864.17.6 SELECT CPOC – Current Plan Occurrence........................................874.17.7 SELECT CPOP/CPOPCOM – Current Plan Operation ......................884.17.8 SELECT CPWS/CPWSCOM – Current Plan Workstation.................884.17.9 SELECT CSR/CSRCOM – Current Plan Special Resource................894.17.10 SELECT ETT – Event Trigger ........................................................894.17.11 SELECT JCLPREP – JCL Preparation............................................894.17.12 SELECT JCLPREPA – JCL Preparation simulation.......................894.17.13 SELECT JCLV/JCLVCOM – JCL Variable Table .........................89Copyright IBM 2008 Page 5

4.17.14 SELECT JL/JLCOM – Job Log.......................................................904.17.15 SELECT JS/JSCOM – Current Plan JCL ........................................904.17.16 SELECT LTOC/LTOCCOM – Long Term Plan Occurrence .........904.17.17 SELECT OI/OICOM – Operator Instructions .................................904.17.18 SELECT PR/PRCOM - Period ........................................................904.17.19 SELECT SR/SRCOM – Special Resource ......................................914.17.20 SELECT WS/WSCOM - Workstation.............................................914.18 SETMAX – Manipulate the maximum return code.....................................924.19 SETSEV – Set message severity..................................................................924.20 SHOW – Show diagnostic information .......................................................934.21 SRSTAT – TWS TSO Command................................................................934.22 TERM – Terminate TWS session................................................................934.23 WSSTAT – TWS TSO Command...............................................................944.24 Using TWS TSO Commands within SOE...................................................945 Batch loader .........................................................................................................955.1 Modes of operation ......................................................................................955.1.1 OPTIONS ACTION.............................................................................955.1.2 Batch Loader ACTION........................................................................965.2 Masking........................................................................................................965.3 Batch Loader syntax enhancements.............................................................975.3.1 SETDEFAULT different behavior ......................................................985.3.2 Keyword abbreviation..........................................................................985.4 AD – Application definition record .............................................................995.4.1 Record structure ...................................................................................995.4.2 Automatic dependencies ......................................................................995.4.3 Submitting Batch Loader direct to the Current Plan..........................1005.4.4 Standard Batch Loader statements.....................................................1005.5 ETT – Event Trigger Record .....................................................................1015.5.1 Record Structure ................................................................................1015.5.2 ETTSTART statement .......................................................................1016 Writing user Segment Processing Exits.............................................................1036.1 Building the exit switch point....................................................................1046.2 Writing an Segment Processing Exit REXX Module................................1057 Writing your own SOEEXECs ..........................................................................1077.1 Passing Arguments.....................................................................................1077.1.1 Passing the subsystem........................................................................1077.1.2 Passing functional arguments ............................................................1078 Performance Tuning...........................................................................................1098.1 Record processing......................................................................................1098.1.1 LIST/SELECT Common Segment vs Record ...................................1098.1.2 OUTPUT and FILESPEC..................................................................1109 Translating output to ISPF tables.......................................................................1119.1 ISPF Loader Streamed Object Notation ....................................................11110 Appendix A - Resource reference..................................................................11210.1 Alternate resource names...........................................................................11210.2 OUTPUT definition reference ...................................................................11210.3 Additional fields.........................................................................................11310.3.1 Reserved fields...................................................................................11310.3.2 Composite fields ................................................................................11310.3.3 Raw and untranslated fields...............................................................113Copyright IBM 2008 Page 6

11 Appenix B - SOE Programming functions ....................................................11411.1 Function reference .....................................................................................11411.1.1 EQQYXFLD – Read/Write fields in ILSON records........................11411.1.2 EQQYXQRY – Find current context in TWS dialogs.......................11411.1.3 EQQYXRAW – Access raw PIF data structures...............................11411.1.4 EQQYXSYS – Find subsystem information .....................................11411.2 EQQYXQRY Process and Object reference..............................................11412 Appendix C - Messages and Codes ...............................................................11512.1 Severities and Return Codes ......................................................................11512.2 Message Grouping .....................................................................................11512.3 Messages ....................................................................................................117Copyright IBM 2008 Page 7

1 Scheduler Operational Environment1.1 IntroductionThe Scheduler Operational Environment (SOE) is a REXX based tool set to give easyaccess to the features of the Tivoli Workload Scheduler for z/OS Program Interface(PIF) for Scheduling Teams and Operators. It gives you full access to all the PIFcommands in an easy to use syntax, as well as a Batch Loader feature for all elementsof the database. There are also extended PIF commands that can perform morecomplex functions from a single statement, such as determining the status of elements,and access to the TWS TSO commands from within the same command stream.SOE handles all the complicated elements of communication blocks and dataexchange, allowing you to talk to TWS without specialized knowledge of memorymanipulation or data definitions, allowing you to integrate TWS with yourOperational Environment with minimum effort.It can be called stand-alone as a simple utility, or the main entry point (EQQYXTOP)can be called from within your own REXX routines, passing commands and receivingoutput via files or the REXX stack.SOE works as a session based interface to TWS, sending a sequence of commands toa specified TWS subsystem. It will only communicate with one controller at once,but can communicate with multiple subsystems in a single run, opening and closingcommunication in turn.1.1.1 Early release and forthcoming featuresThe version of SOE you are currently using is an early release of the planned eventualproduct. The code and functions provided in this release are fully tested supportedand stable, the product has been released before ALL of the eventually plannedfeatures are available, allowing you to take advantage of the new PIF capabilities assoon as possible.This guide will make references to planned future features to give you indication ofwhat additional features will be arriving in later releases to help you plan the sort ofexploitation of SOE you may want to develop, and to avoid spending time developingyour own features or requesting enhancements that are already in the plan. Currentlyunavailable features will have limited documentation and a note indicating that it isnot yet available.1.2 Version supportSOE will support from versions 8.1 to 8.3 of TWS.You define to SOE what version of TWS to operate with and it will only allow actionsapplicable to that release to be performed, and it will only generate output compatiblewith that release. It does this by maintaining an internal reference table that it loads atstartup.Copyright IBM 2008 Page 8

You can specify the version to load by appending the version to the subsystem namewith a hyphen when you call EQQYXTOP e.g. SUBSYS=’OPCA-8.1’. Otherwise SOEwill load support for the highest version available.You can change version during a session with the OPTIONS VERSION statement, whichwill cause the internal reference table to be reloaded. This would allow you toperform some complex actions, for example, performing some 8.3 specific actionswith an 8.3 controller, and then later generating some 8.2 compatible output withinthe same session.OPTIONS SUBSYS allows you to load a specific options member for each subsystemyou operate, in which you can code an OPTIONS VERSION statement to make versionsupport easy to manage.Note: The version support for SOE is generally in line with the currently supportedversions of TWS, however the architecture is capable of being extended to supportolder versions. If you have specific requirements please contact your IBMrepresentative for assistance in contacting the TWS Development team to discussthese requirements and a possible services engagement.1.2.1 Small Product EnhancementsFor some versions of TWS there are new features added via PTF as Small ProductEnhancements (SPEs). Some SPEs can alter the structure of data within TWS andBatch Loader. Support for these features can be turned on selectively.Supported additional features added at version 8.2 –• WLM – WLM Scheduling Environment integration.• PEND – ACTIVE/PENDING support added to BCIT and BATCH LOADER.Note that this SPE only requires enabling for version 8.2 if you are operatingin EQQYLTOP compatibility mode. If you are not operating in this modethen ADSTAT is a valid Batch Loader keyword for all version of TWSsupported by SOE.• SA – System Automation Integration.Supported additional features added at version 8.3 -• VIWS – Virtual Workstations.There is also an SOE specific SPE that works with any version, but makes SOEgenerate output that is no longer compatible with EQQYLTOP.• LOAD – Batch Loader enhancements added via SOE. These add new fieldsinto the batch loader for AD and OI that are not understood by EQQYLTOP.With this SPE activated any Batch Loader generated by SOE may fail ifpassed as input to EQQYLTOP. See #Batch Loader syntax enhancements formore details.To turn on a SPE delivered feature, use OPTIONS SPE –e.g. OPTIONS SPE(WLM=Y,PEND=Y)Copyright IBM 2008 Page 9

1.3 Language supportThough the command syntax is in English, output messages can be displayed inalternate languages.The list of supported languages is –• EN – EnglishThough only English is supplied at present, there is capability built in for multilanguagesupport. Other language files will be provided in later releases.The language can be selected by the LANG symbolic parameter in the JCL.Copyright IBM 2008 Page 10

1.4 Change HistoryVersion Comments2.1.00 First widely available release. Before this version SOE was released asa tactical solution for some customers2.1.01 OPTIONS keywords rationalized –• OPTIONS DATA became OPTIONS SENDDATA• OPTIONS LOADER became OPTIONS SENDLOADER• OPTIONS DATAFILE became OPTIONS DATA• OPTIONS LOADFILE became OPTIONS LOADERThis made the usage of OPTIONS DATA and OPTIONS LOADER consistentwith OUTPUT DATA and OUTPUT LOADER. Any usage of OPTIONS DATA,LOADER, DATAFILE and LOADFILE prior to this version will needreviewing.Automatic SELECT for Application Groups enabled. Prior to thisversion Application Groups had to be selected explicitly.A new library SAMPJCL included in the distribution.Validation improved for –• OPTIONS FIELDSEP• OPTIONS LABELSEPCopyright IBM 2008 Page 11

Version Comments2.1.02 New TAG argument added to LIST and SELECT statements to allowoutput to be correlated with each command.Any keyword whose name ends with OPNO can now specify FIRST orLAST as operation number to pick up the FIRST and LAST operations,which default to 1 and 255 respectively, but can be overridden byOPTIONS FIRST/LAST statements.OPTIONS FIELDSEP and LABELSEP can now specify NONE.Numeric fields are now presented padded with leading zeroes to ensureconsistent alignment in output files. Operation numbers are padded to 3digits, all other numbers are padded to 8.New OUTPUT LABEL feature allows labels in the DATA output to beswitched on and off for the whole record.New function EQQYXSRT externalized to allow any code to call a keystring sort.The default for OPTIONS ACTION has been formalized to ADD. Beforethis release it was undocumented, but set to UPDATE. This could lead toaccidental update when a user was expecting an object rewrite if theywere unaware that SOE had a different default behavior to traditionalBatch Loader. The default of ADD is the most fail safe option. Userscan set their own site default by using OPTIONS ACTION in their sitedefault member.Message continuation lines now have the message ID included.Performance improvements with record processing for large extracts.Batch Loader implemented for –• ETT – Event Trigger1.5 General features1.5.1 Command languageThe SOE command language is a combination of native PIF requests, extended PIFrequests, TWS TSO commands and SOE internal commands to set options and outputfiles. The syntax uses the same conventions for all commands, which is easy to learnand easy to use.Commands can be passed into SOE by many routes. It will read commands from thefollowing input streams (in this order).• EQQOPTS – The EQQOPTS DD statement is intended to contain your sitedefaults for SOE. There are some predefined OPTIONS members that setCopyright IBM 2008 Page 12

options for different styles of use e.g. OPTDEFLT for default behavior orOPTEASY for easy extract features enabled. You cannot use an alternate DDname for EQQOPT.• EQQSUB - This DD statement is not read by default, but can be used tocontain subsystem specific options. The name of the EQQSUB DD is set bythe OPTIONS SUBSYS() statement, SUBSYS options will not beprocessed unless this statement appears within the EQQOPT DD statements.This will cause SOE to read a second site OPTIONS member after EQQOPTS,the member in the JCL being pointed to a different set for each subsystem byusing the &SUBSYS symbolic parameter, allowing Site OPTIONS to beoverridden by subsystem.• The ARG= symbolic parameter in the JCL. This only passes keywords for anOPTIONS statement. When calling EQQYXTOP from within your own REXXprogram, the keywords are from word 2 onwards of the input argument, thefirst word must always be the TWS controller subsystem ID. There are someimmediate OPTIONS which can ONLY be specified as an argument, these takeeffect as SOE starts and are not valid in OPTIONS statements elsewhere. Thisallows Site and Subsystems to be overridden at SOE startup in the programcall or JCL.• EQQFILE - This DD statement contains the default file specifications for allof your output files. By default this DD statement points to a member in thePARM library called FILENONE which contains no OUTPUT definition, themember name is passed using the FILESPEC symbolic parameter. There is asupplied member called FILEALL which will output all possible fields. TheDD name for this input source is called EQQFILE by default, but an alternatename can be specified with the OPTIONS FILESPEC() statementspecified in any of the previous input sources.• External data queue. If data is detected on the external data queue (stack) itwill be read as command input. It will only read what is in the external dataqueue at the time it starts reading, any lines added during the processing of thecommands will not be read at this stage.• INPUT - This DD statement is intended to contain the commands for thespecific session you are running. The DD name for this input source is calledINPUT by default when executed in the foreground and SYSIN by default inbatch, but an alternate name can be specified with the OPTIONSINPUT() statement specified in any of the preceding input sources.• Post Processing - If the OPTIONS POSTPROC(YES) is set, any further content ofthe external data queue will be processed at this point. The queue will beprocessed until it is empty, so any additional lines created whilst processingthe queue will also be read.Though there are many different streams through which you can specify commandinput, these are intended to let you separate your statements into standardized andreusable blocks. You can specify all your command input in one simple single streamif you wish, making it simple to see exactly what you are asking SOE to do in oneplace.Note: Each input stream is parsed in its entirety before any statement within it isexecuted, so any OPTIONS statement that has an impact on syntax will not take effectCopyright IBM 2008 Page 13

until the start of the next input stream. It is recommended that any syntax options bespecified in the OPTIONS, SUBSYS or ARG steams.Warning: If EQQYXTOP is being executed in foreground mode (rather than batch),then a command source will not be read if it is referring to the SYSIN DD statement,as this could lead to the program stalling if SYSIN is left allocated to the terminal.1.5.2 Output filesBy default the output files are generated in ISPF Loader Streamed Output Notation(ILSON). This notation allows the output to be easily imported into ISPF tables usingthe EQQILSON utility (the utility is not yet available). This notation also allows youto easily read and update the records from within your own programs without havingto know much about the record structure, by using the EQQYXFLD function.The OUTPUT statement is used to define what records you wish to extract, and inwhat format. This statement also defines where the output will be sent.EXIT processing can also be used to alter the format, content and destination of theoutput, as well as determine whether individual records are written.1.5.3 Batch loaderSOE can extract all TWS database objects and Current Plan JCL into a Batch Loaderformat. This format can be made compatible with EQQYLTOP for ApplicationDefinitions and Operator instructions (see OPTIONS EQQYLTOP), and uses similarconstructs for all other objects. This Batch Loader can then also be used as inputcommands to SOE to recreate these objects within TWS.OUTPUT statements and Segment Processing Exits can be used to influence whatkeywords appear in Batch Loader statements generated from the database. TheSegment Processing Exit can also be used as a form of mass update by writing a oneto create modified Batch Loader statements to perform specific changes from theobjects in the database selected as the result of a LIST.You can interchange Batch Loader and Command Language in the same step, in anysequence you like, the only consideration being you cannot place CommandLanguage statements within the scope of Batch Loader statements for an individualTWS object.Command Language statements can cause Batch Loader statements to be generatedthat have been modified by EXIT processing. These Batch Loader statements can beoutput to the external data queue to be executed at the end of the step by specifyingOPTIONS POSTPROC(YES). This means you can extract an object from the TWSdatabase and reload it into the database, adjusted for your development lifecycle, in asingle step.Copyright IBM 2008 Page 14

1.5.4 Mass UpdateAs well as identifying individual elements to update using Batch Loader in thetraditional manner, you can use Batch Loader syntax to perform mass updates byusing a LIST command to identify elements to be updated, and Batch Loader syntax tomodify the elements found in the preceding list. This allows simple mass changes orcopies to be used without having to write Segment Processing Exits.This is done by using the SAVELIST keyword on a LIST command to save the itemsidentified by the LIST arguments to a named list. Then using the same name you canuse SAVELIST to determine which objects the Batch Loader statements apply to.A simple example would look like this -LIST ADCOM ADID(PAY1*) OWNER(PAYROLL) SAVELIST(MYLIST)OPTIONS OUTMASK(Y)ADSTART ACTION(COPY) SAVELIST(MYLIST) NEW_ADID(PAY2*) OWNER(NEWPAY)Which would find every application whose name starts with PAY1 belonging toPAYROLL and store that in a list called MYLIST. It will then create a copy of eachitem on the list with a name starting with PAY2, by masking the output field, and anew owner ID of NEWPAY.1.5.5 Segment Processing ExitsSOE can be extended by writing Segment Processing Exits. These can be called aftera data record is created, but before data and any batch loader statements are written.The exits can update any field within a record, influence whether the record is written,as data, batch loader or both. The exits can also influence the destination of DATA andLOADER records dynamically.The exits also have the ability to alter options FIELDSEP, LABELSEP, EXIT, EXITUSEand ARG for all subsequent records.1.6 TWS Program Interface ConceptsTo be able to use SOE effectively, it helps if you understand the basic concepts of theTWS Program Interface (PIF) and data structure.1.6.1 Data Sources and StructuresThe use of the TWS PIF is all about reading and writing data from TWS. The datacan come from one of 3 places –• The Database• The Current Plan (including JCL)• The Long Term Plan (including JCL)Despite the different sources, the data follows the same basic rules, wherever youobtain it from.Copyright IBM 2008 Page 15

Each entity in TWS is represented by a single record, so an Application is one record,an ETT rule is one record, and a Calendar is one record. The record will be formattedinto one or more Segments.A Segment is a subdivision of a record for a particular type of information. In somecases there will only be one segment of a particular type in a record, in others theremay be several. So for example in an Application there is ONE common segment(ADCOM) and there may be several run cycle segments (ADRUN) and severaloperation segments (ADOP). The operations may have several special resources(ADSR) and so on.The TWS record structure is hierarchical, this means that the segments are ordered inparent child relationships. So an operation’s child segments follow their parentoperation segment and precede the next operation segment.Every multi segment object always begins with a Common Segment which definesthe key and high level information about the object. The easiest way to visualize whatis in the Common Segment is to think about what information appears in the nonscrollable portion of the first panel you see when you browse an object.ADCOM -+- Common segment|+- ADRUN –+- Run Cycle(s)| || +- ADRULE - Rule|+- ADOP -+- Operation(s)|+- ADDEP – Dependency(ies)|+- ADSR – Special resource(s)|+- ADEXT – Extended name|+- ADSAI – System AutomationThe relationships of the AD RecordIn the preceding example you can see the logical layout of the AD record (anApplication or Jobstream). So an AD record could be a sequence of segments likethis –ADCOM ADRUN ADRULE ADRUN ADRULE ADOP ADOP ADDEP ADSR ADSR ADOP ADDEPWhen the program interface retrieves a record it presents a header which lists eachsegment name and the offset to where the segment starts. SOE automaticallyprocesses the header and decodes each segment in turn. Allowing you to decidewhich segments can be processed. If you have decided to use a Segment ProcessingExit, then the exit will be automatically called for every segment you have referencedby an OUTPUT statement.Copyright IBM 2008 Page 16

1.6.2 RequestsA command within the TWS PIF is known as a request. At a high level there are 11different types of PIF request –Request Read/Write Acts upon PurposeDELETE WRITE Database and Deletes thingsPlansEXECUTE WRITE Current Plan Commits updates to the CurrentPlanINITStarts a session with a controllerINSERT WRITE Database and Creates a new record or segmentPlansLIST READ Database and Searches for recordsPlansMODIFY WRITE Plans Updates records in the plansOPTIONSSets session optionsREPLACE WRITE Database Updates records in the databaseRESET Current Plan Abandons updates to the CurrentPlanSELECT READ Database and Reads a single recordTERMPlansTerminates a session with acontrollerINIT and TERM are done for you automatically, so you don’t need to be concernedabout those, though you can do your own INIT and TERM requests many times in anSOE session to talk to different controllers.For the requests that directly read or write data, you must specify enough of an itemkey to uniquely identify a single object, with the exception of LIST. The LISTstatement is used to find records, from the returned LIST you can derive the uniquekey for every object found, which you could then take an action against, e.g. SELECT,DELETE, MODIFY.LIST requests are always performed against the Common Segment. However SELECTcan be performed against the entire record, to retrieve all the segments, or just thecommon segment.The requests that write data work in one of two styles –• Database updates are performed by creating the whole record in storage beforesending it to TWS. Database updates are handled in SOE by Batch Loaderconstructs.• Plan updates are performed by using keywords with the MODIFY or INSERTinstructions to alter the values of fields within the object. Plan updates arehandled in SOE by commands.For more information about PIF Requests see IBM Tivoli Workload Scheduler forz/OS Programming Interfaces (SH32-1266-03).Copyright IBM 2008 Page 17

2 Installation2.1 Installation librariesSOE, once installed, is a set of libraries containing REXX source code, JCL,Parameters and samples.TWS.SOE.JCLTWS.SOE.PARMTWS.SOE.REXXTWS.SOE.SOEEXECTWS.SOE.SAMPJCLContains the SOE catalogued procedures.Contains the input and output specifications, messages andlanguage file. It is recommended that this library be storedon fast DASD or cached as the input specification is readevery time SOE starts.Contains the source code for all the REXX routines used bySOE.Contains REXX programs that call SOEContains sample jobs that use SOEThe installation process is designed to create and load these datasets using a commondataset prefix (e.g. TWS.SOE). Though it is possible to install to completelyunrelated dataset names, it is not recommended.Before beginning the installation process it is recommended you decide upon aninstallation prefix.There is another library called TWS.SOE.SETUP, from which these libraries arecreated.This library is for installation and customization of SOE and plays no part in the usageof the product.2.2 Getting the software onto the mainframeSOE is packaged as a binary file that you will have obtained either via a CD,download or eMail attachments. The file is called setup.v1r0m0.ibmdist. (wherev1r0m0 will reflect the current version of SOE).This file needs to be transferred to your mainframe, from a PC, using whateveravailable file transfer mechanism you use at your site for PC to mainframe filetransfer.The install process will create a set of libraries. It is recommended that you select acommon prefix for these libraries, for example TWS.SOE. When you transfer thesetup.v1r0m0.ibmdist file it is also recommended you use this same installationprefix for the transferred dataset. So if you decide upon TWS.SOE as yourinstallation prefix, then it is recommended that you transfer thesetup.v1r0m0.ibmdist file to TWS.SOE.SETUP.V1R0M0.IBMDIST. This willidentify the file as the IBM distributed file, and the relevant version of SOE.The file must be transferred with the following attributes –• Binary - no ASCII/EBCDIC translation.Copyright IBM 2008 Page 18

• Record length 80 bytes.• Record format Fixed Blocked.• No CR/LF – don’t strip carriage return and linefeed characters from the end ofeach record.2.3 Receiving the fileThe setup file you have transferred to the mainframe contains a PDS in transmittedform. To receive this file use the receive command. You can do this from PDFoption 3.4 by typing RECEIVE INDSN(/) as a line command against the transmittedsetup file.Menu Options View Utilities Compilers Help------------------------------------------------------------------------------DSLIST - Data Sets Matching TWS.SOERow 1 of1Command ===> Scroll ===>CSRCommand - Enter "/" to select actionMessageVolume-------------------------------------------------------------------------------RECEIVE INDSN(/)E.SETUP.V1R0M0.IBMDISTTWSV83***************************** End of Data Set list****************************The received file should have a similar name without the .V1R0M0.IBMDISTextension. e.g. TWS.SOE.SETUP. To supply the name enter the dataset name asfollows when prompted.INMR901I Dataset TWS.SOE.SETUP from EQQTWSZ on TWS1INMR154I The incoming data set is a 'DATA LIBRARY'.INMR906A Enter restore parameters or 'DELETE' or 'END' +da(‘tws.soe.setup’)2.4 Performing setupYou can run the SOE setup process by executing the SETUP library from PDF option3.4 by entering EX as a line command against the SETUP dataset.Menu Options View Utilities Compilers Help------------------------------------------------------------------------------DSLIST - Data Sets Matching TWS.SOE Row 1 of 2Command ===>Scroll ===> CSRCommand - Enter "/" to select action Message Volume-------------------------------------------------------------------------------EX TWS.SOE.SETUP TWSV83TWS.SOE.SETUP.V1R1M0.IBMDISTTWSV83***************************** End of Data Set list ****************************This will start a SETUP dialog which will allow you to easily create your product JCLprocedures, customization and configuration.The setup dialog will perform the following actions –Copyright IBM 2008 Page 19

• Load Software. This will create and populate the SOE software libraries.• Configure JCL and PARMs. This will customize the SOE JCL procedures inline with your dataset names, and create some initial OPTIONS members.• Create members per subsystem. This will create EQQYPARM andsubsystem options for up to 9 of your TWS subsystems.Copyright IBM 2008 Page 20

------------------------- TWS SOE Install and Configure ----------------------Command ===> Scroll ===>CSREnter/change data below and press ENTER to execute or END to exit.Actions (Y/N): Y Load software Y Configure JCL and PARMsY Create members per subsystem+Prefix (PFX) ===>TWS.SOE_______________________________________________More:Required software librariesREXX library ===>&PFX..REXX_____________________________________________PARM library ===>&PFX..PARM_____________________________________________JCL library ===>&PFX..JCL______________________________________________Optional software librariesSOEEXEC library ===>&PFX..SOEEXEC__________________________________________SAMPJCL library ===>&PFX..SAMPJCL__________________________________________EQQMLIB concatenationEQQMLIB ===>TWS.V8R2M0.SEQQMSG0____________________________________===>_______________________________________________________===>_______________________________________________________SYSPROC concatenationSYSPROC ===>&PFX..REXX_____________________________________________===>_______________________________________________________===>_______________________________________________________STEPLIB concatenationSTEPLIB ===>&PFX..&SUBSYS..LOAD____________________________________===>_______________________________________________________===>_______________________________________________________TWS informationEQQYPARM member ===>&PFX..PARM(EQQY&SUBSYS.)_______________________________SUBSYS member ===>&PFX..PARM(OPTS&SUBSYS.)_______________________________Subsystem informationSUBSYS Version Server LU Name HIGHDATE CWBASEe.g. OPCA 8.3 MYNET.LUNAME 711231 00OPCA 8.3___ _________________ 711231 00OPCC 8.2___ _________________ ______ ______ ______ _________________ ______ ______ ______ _________________ ______ ______ ______ _________________ ______ ______ ______ _________________ ______ ______ ______ _________________ ______ ______ ______ _________________ ______ ______ ______ _________________ ______ __Copyright IBM 2008 Page 21

The Install and Configure utility is a scrollable panel that lets you alter the defaultvalues for various aspects of the SOE configuration. On first execution for aparticular user all of the Actions will all default to Y, any subsequent runs of thisutility each Action will be left blank forcing you to explicitly choose each process.This reduces the risk of accidental overwriting of an existing installation.The Prefix is automatically set to be the same as the prefix of the SETUP library.You can override this to create an entirely separate set of install libraries. This willallow for multiple instances of SOE software to be created and configured. This willform a JCL symbolic parameter of &PFX in all SOE JCL procedures. You can alsoreference this symbolic parameter in any dataset names declared in this panel. This ishow they will appear in the JCL procedure, making a more flexible configuration.The Setup process will automatically create and load both the “Required softwarelibraries” and the “Optional software libraries”. By default it will name theselibraries as &PFX..REXX, &PFX..PARM, &PFX..JCL and &PFX..SAMPJCL. Youcan override any of these names prior to creation, e.g. &PFX..REXX.V8R1M0, andthe setup program will create, populate and reference these libraries.Datasets in the EQQMLIB concatenation, SYSPROC concatenation or STEPLIBconcatenation will NOT be created by the setup program, unless they are one of the 4datasets already referenced in the Required or Optional software libraries.There is a second symbolic parameter of &SUBSYS which can be used in any preexistingTWS controller specific datasets. The SOE software libraries cannotreference this parameter, other than within member names.The install process will create and populate all the required software datasets, if youdo not want optional libraries creating, blank out the relevant fields.There are 3 concatenations you can define –• EQQMLIB – This should match the concatenation you use for your TWSconfiguration.• SYSPROC – By default this will include the SOE REXX library. It isrecommended you include an alternate library preceding the SOE library toseparate user written code from supplied code.• STEPLIB – This concatenation is needed if your TWS load libraries are notlink listed, or there is a possibility that you may be accessing more than oneversion of TWS from the same machine. If you do not want a STEPLIB,blank out all fields in this concatenation and no STEPLIB will be entered inJCL.The TWS information section specifies where to store any EQQYPARM orsubsystem specific OPTIONS members. If you want a unique member for eachsubsystem then you should use &SUBSYS as part of the member name. If you do notrequire either EQQYPARM or SUBSYS DD statements in your JCL then blank outthe relevant fields.Copyright IBM 2008 Page 22

The Subsystem Information section allows you to specify characteristics of up to 9TWS controllers. This information is used to create the EQQYPARM and SUBSYSmembers. All the information is optional, if not entered defaults will be used. Thepossible values you can enter for each subsystem are –• Version. This is used to control what features are available within SOE. If notspecified the highest version available to SOE will be assumed.• LU name. This is used in EQQYPARM settings to communicate via the TWSserver task.• HIGHDATE. This is needed if you have specified non default values in yourINTFOPTS option when configuring TWS. This is used in EQQYPARMsettings.• CWBASE. This is needed if you have specified non default values in yourINTFOPTS option when configuring TWS. This is used in EQQYPARMsettings.Once you have entered all the values you need for configuration pressing Enter willstart the Install or Configure process. Pressing End (PF3) will terminate withoutperforming any updates. All values entered are stored in your profile for subsequentexecutions of @SETUP.Notes:1. EQQYPARM members are only created when both an EQQYPARM membername is specified and “Configure JCL and PARMs” is set to Y. SUBSYSmembers are only created when both a SUBSYS member name is specifiedand “Configure JCL and PARMs” is set to Y.2. The SAMPJCL library contains sample SOE jobs to perform some native SOEcapabilities and demonstrate use of some SOEEXECs. The JCL is notcustomized for your installation. Before submission you will need to removethe leading comment line, update the job card to your installation standardsand update or remove the JCLLIB state to ensure the EQQYXJCL procedurecan be found when the job is submitted.2.5 Use of EQQYPARMSome initialization options for the TWS program interface can be specified on anINIT statement contain within a member referred to by the EQQYPARM DDstatement. Some of these parameters can ONLY be specified within EQQYPARM,for example CWBASE and HIGHDATE if you have altered the default data settings in theINTFOPTS statement.The SOE installation process will assist you in the generation of EQQYPARMmembers, but for more information, refer to IBM Tivoli Workload Scheduler for z/OSCustomisation and Tuning (SH32-1265-03) for more information.Copyright IBM 2008 Page 23

2.6 REXX compilationSOE can be compiled for performance, but it is not required. If you decide to takethis option, ensure that the library containing the compiled version is substituted forthe source version wherever needed.Ensure the exit point module (EQQYXU00) is updated and a recompile is performedwhenever new exits are added to your installation.It is recommended that you include a user REXX library ahead of the supplied SOEREXX and SOEEXEC libraries to store your own version of exit moduleEQQYXU00 and any exits or SOEEXECs you write.Copyright IBM 2008 Page 24

3 General usage3.1 In BatchThe standard JCL procedure EQQYXJCL can be used to run SOE in batch. Thefollowing symbolic parameters can be specified –• ARGS - Additional OPTIONS or your own command parameters.• CMD - REXX entry point to use (default EQQYXTOP).• FILESPEC – File specification member name (default FILENONE)• LANG – Language for messages (default EN)• OPTS - OPTIONS member to use (default OPTDEFLT)• PFX – Prefix for SOE installation datasets• REG - REGION to allocate (default 4M)• REF – Reference member to use (default REFERNCE)• SUBSYS – TWS subsystem to communicate with (default *).• TWSPFX - Prefix for TWS datasets (default TWS.V8R3M0)//PIFSTEP EXEC EQQYXJCL,// SUBSYS=OPCA,// FILESPEC=FILEALL,// ARGS=’SELECT(Y) LOADER(Y)’//SYSIN DD*LIST ADCOM ADID(ABC*)This example will use SOE to list every application whose name begins with ABC. Itwill then automatically SELECT each application and generate full Batch Loader foreach one.3.2 OnlineSOE is primarily designed for use in Batch, but is capable from being used fromwithin an online TSO session, either inside or outside of the TWS dialogs.To use SOE from within a TSO session you must ensure the following files areallocated before execution –• EQQMLIB – TWS message library, if SOE is being executed fromwithin TWS dialogs then this will already have been allocated.• EQQMLOG – TWS message log.• EQQLANG – SOE language file. This should have the relevantlanguage member from the SOE PARM library allocated to it e.g.EQQLANG.• EQQREF – SOE reference information. This should have theREFERNCE member from the SOE PARM library allocated to it.The following files can be optionally allocated before starting SOE –• EQQOPTS – SOE options.• EQQFILE – SOE file OUTPUT definitionsSOE can then be called as a function from within REXX with the syntax –Copyright IBM 2008 Page 25

RC = EQQYXTOP( )When executed within TSO the INPUT stream is read from a file called INPUT. SOEwill not read from a file called SYSIN to avoid the risk of stalling if SYSIN was leftallocated to the terminal, which is the default position of SYSIN in the foreground.3.3 From other REXX programsSOE is designed to easily interact with other REXX programs, which themselves canbe used in Batch or Online. SOE is delivered with some pre-built SOEEXECs to giveyou an example of the sort of processes that can be performed.For more information on running SOE from other REXX programs see Writing yourown SOEEXECs3.4 Specifying the subsystemThe SUBSYS parameter is a required parameter for both Batch and Online. It is thesubsystem name used when initializing communication with TWS. SOE will generatean INIT statement automatically when it encounters a command that requirescommunication with the TWS PIF. Note that some OPTIONS keywords requirecommunication with the TWS PIF.If you want to communicate with more than one TWS subsystem in an SOE sessionthen you can explicitly initialize your own connection to TWS using an INITstatement before any other statement that requires the TWS PIF.SUBSYS is a required positional parameter, so even if you are specifying the subsystemexplicitly using INIT statements, you must provide a value. The default inEQQYXJCL and EQQYXTSO is set to * for this purpose.The SUBSYS parameter can also be used to specify the default version to load at startup.See Version support for more details.3.5 SyntaxThe general syntax for all SOE commands is as follows –COMMAND [RESOURCE] KEYWORD(value) KEYWORD(value)• Certain PIF commands require a resource, for these commands this willalways be the second word of the command statement.• Command keywords that have values are specified with the value containedwithin parentheses. There must not be a space between the keyword and theopening parenthesis as this will be interpreted as a separate keyword.• Keywords and their values can be separated from other keywords and theirvalues by commas and/or spaces.Copyright IBM 2008 Page 26

• If a keyword value needs to contain parentheses then the value must becontained within single quotes inside the keyword parenthesese.g. KEYWORD(‘my.value(member)’), otherwise containing quotes areoptional.• Containing quotes will not be passed through to the underlying process.• If containing quotes are used you must specify two consecutive single quotesto represent a single quote in the underlying process.• A single quote at the start of a value will be considered to be a containingquote, and a terminating quote will be needed at the end of the value.• Double quotes are always passed through to the underlying process.3.5.1 ComparatorsIf comparators are required for a particular keyword, for example when using theLIST command, they are specified in the form –KEYWORD-COMPARATOR(value)e.g. VALFROM-GE(060124)If no comparator is specified, EQ is assumed. If the PIF command does not supportcomparators, they are ignored.Valid comparators are –• EQ – Equals• NE – Not equal to• LT – Less than• GT – Greater than• LE – Less than or equal to• GE – Greater than or equal toNOTE: The native PIF convention for specifying comparators is to specify thecomparator on the end of the field, and the comparison works counter intuitivelye.g. VALFROM=060124

3.5.2 Dates and TimesSome keywords will allow dates, times, or datetimes to be entered. If you want to usethe current date, time or datetime you can enter = instead as the only content of thekeyword.Restrictions: These restrictions apply to the use of = for dates and times -• The = notation can only be used for fields whose value is specifically a date,time or datetime. You cannot use it for any other type of field, DESCR(=) isnot a date or time short form, VALFROM(=) is. DESCR(=) will result in thedescription being set to a single equals sign.• The = cannot form a part of the data e.g. IA(060124=) is not allowed, IA(=)is.• Do NOT use = for field values in conjunction with native PIF comparators e.g.IA(=

Any record length other than 80 bytes is used for input, then SOE will not considerline numbers to be set.For compatibility with EQQYCAIN and EQQYLTOP batch loader format you can setOPTIONS EQQYLTOP(Y) which will ignore anything beyond column 72 and consider72 as the continuation column, connecting the following line from column 1.Use of termination characters such as ; or . will be rejected by SOE.Individual sub-segments for Batch Loader statements do not have to start on a newline, only the xxSTART statement needs to start on a new line.e.g. ADSTART ADID(MYAPPL) ADOP OPNO(001) JOBN(MYJOB)3.5.4 CommentsComments are started with /* and terminated with */.Comments can span multiple lines, or be included anywhere within a statement.e.g./* -----------------------------------------------+| This is a multi line comment |+------------------------------------------------*/COMMAND RESOURCE KEYWORD(VAL) /* TAIL COMMENT */COMMAND RESOURCE /* EMBEDDED COMMENT */ KEYWORD(VAL)Warning: The comment start characters override all other directives, so if you wantto include /* within one of your statements, then you must alter the comment startcharacter using the OPTIONS COMSTART statement (see OPTIONS – Define run timeoptions/PIF request) and similarly with OPTIONS COMEND for using something otherthan */ to end a comment.3.5.5 Resource namesOne of the most important parts of understanding the TWS PIF is getting to knowwhat resources you need, since the resource names are not always obvious from themodern name of the object. For example the resource needed to retrieve a Jobstreamis AD, which is derived from the old name of Application Description.In addition, sometimes you have to use a different resource name when using LIST tothe one you must use when using SELECT.For example you would LIST ADCOM to find a list of Jobstreams, but then you wouldneed to SELECT AD to retrieve each Jobstream in full.SOE allows alternate, more obvious names to be used instead. So you can now LISTJOBSTREAM to get a list of Jobstreams and then SELECT JOBSTREAM to retrieve a fullindividual definition. If you want to retrieve just the common segment of a Jobstreamyou can still SELECT ADCOM just as before.Copyright IBM 2008 Page 29

A full list of available aliases for each PIF command is listed in Appendix A.1:Alternate resource namesCopyright IBM 2008 Page 30

4 Command statement referenceThis section lists all the commands that SOE supports, with the exception of BatchLoader statements. Those are listed in the chapter - Batch loader. Full details of TSOcommands are documented within the Managing the Workload manual.4.1 BACKUP – TWS TSO CommandBACKUP The BACKUP statement can be used to initiate a backup of either the Current Plan orthe JCL repository.See Using TWS TSO Commands within SOE for more information.4.2 BULKDISC – TWS TSO CommandBULKDISC The BULKDISC statement can be used to initiate a bulk discovery request.See Using TWS TSO Commands within SOE for more information.4.3 DELETE – Delete object from database or planDELETE The DELETE request deletes a record or record segment. If you delete a record thearguments identify the particular record to be deleted. If you want to delete only someinformation in an occurrence (for example, one of the operations in an occurrence),you must first use a MODIFY request to identify the occurrence before you use theDELETE request for the operation. Similarly, if you want to delete a special resourcespecification for an operation, you must use a MODIFY request to identify theoccurrence and then use a MODIFY request to identify the operation, before using aDELETE for the special resource.To delete an interval of a current plan workstation you must precede the DELETE IVLwith a MODIFY CPWS to identify the workstation.To delete the extended name of an operation you must use the MODIFY request.If the DELETE request has been used to modify information in the current plan, a laterEXECUTE request must be made for the modification to actually take effect, SOE willdo this for you automatically if OPTIONS EXECUTE(AUTO) is set (default).4.3.1 Return Code• 0 - The request was successful.• 4 - The record; AD, AWSCL, CL, ETT, JCLV, JS, OI, PR, SR, or WS iscurrently being updated by another user. The record is not deleted.Copyright IBM 2008 Page 31

• 8 - The request was unsuccessful. An error message has been written to themessage log data set.4.3.2 DELETE AD – Application DefinitionArg Name DescriptionADID Application description IDGROUP Authority group nameGROUPDEF Group definition IDOWNER Owner IDPRIORITY PrioritySTATUS Status: P=Pending A=ActiveNote: Tivoli Workload Scheduler for z/OS assumes application type A, if you do notspecify the TYPE argument name.4.3.3 DELETE AWSCL – All Workstations ClosedArg Name DescriptionDATE Date workstations are closed YYMMDD4.3.4 DELETE CL – CalendarArg Name DescriptionCALENDAR Calendar ID4.3.5 DELETE CPOC – Current Plan OccurrenceArg Name DescriptionADID Application description IDIAInput arrival date and time YYMMDDHHMM4.3.6 DELETE CPOP – Current Plan OperationArg Name DescriptionOPNO Operation number4.3.7 DELETE CPPRE – Current Plan PredecessorArg Name DescriptionPREADID Predecessor application IDPREIA Predecessor input arrival date and time YYMMDDHHMMPREOPNO Predecessor operation number4.3.8 DELETE CPSR – Current Plan Operation Special ResourceArg Name DescriptionRESNAME Special Resource nameCopyright IBM 2008 Page 32

4.3.9 DELETE CPSUC – Current Plan SuccessorArg NameSUCADIDSUCIASUCOPNODescriptionSuccessor application IDSuccessor input arrival date and time YYMMDDHHMMSuccessor operation numberNote: When deleting an internal successor, only specify SUCOPNO. All three argumentsmust be specified to delete an external successor.4.3.10 DELETE ETT – Event TriggerArg Name DescriptionADID Associated application IDETTNAME Name of triggerETTTYPE Type of trigger,• J = Job• R = special resource4.3.11 DELETE IVL – Current Plan Workstation IntervalAn interval can have information originating from the workstation description,indicator CPIVLDP in segment CPIVL is set to Y, or else to N. If an interval ischanged or created via the dialog or the program interface, the indicator CPIVLMODin CPIVL is set to Y, or else to N. DELETE IVL only affects modifications. Intervalswith CPIVLDP=Y remain after a DELETE, the interval is reset to the daily planningvalues and CPIVLMOD is set to N. Intervals with CPIVLDP=N are fully deleted.Arg NameFROMDescriptionInterval start date and time YYMMDDHHMM4.3.12 DELETE JCLV – JCL Variable TableArg Name DescriptionJCLVTAB JCL variable table ID4.3.13 DELETE JL – Job LogArg Name DescriptionADID Application IDIAInput arrival date and time YYMMDDHHMMJOBNAME z/OS Job nameOPNO Operation numberWSNAME Workstation nameCopyright IBM 2008 Page 33

4.3.14 DELETE JS – Current Plan JCLArg Name DescriptionADID Application IDIAInput arrival date and time YYMMDDHHMMJOBNAME z/OS Job nameOPNO Operation numberWSNAME Workstation name4.3.15 DELETE LTOC – Long Term Plan OccurrenceArg Name DescriptionADID Application description IDIAD Input arrival date YYMMDDIATInput arrival time HHMM4.3.16 DELETE LTPRE – Long Term Plan PredecessorArg Name DescriptionADID Application description IDIAD Input arrival date YYMMDDIATInput arrival time HHMMPREADID Predecessor application IDPREIAD Predecessor input arrival date YYMMDDPREIAT Predecessor input arrival time HHMMNote: DELETE LTPRE is used only to delete external predecessors. No support isprovided in the long-term plan for internal dependencies.Copyright IBM 2008 Page 34

4.3.17 DELETE OI – Operator InstructionArg Name DescriptionADID Application description IDOPNO Operation number4.3.18 DELETE PR – PeriodArg Name DescriptionPERIOD Period namePRTYPE Period type4.3.19 DELETE SR – Special ResourceArg Name DescriptionRESGROUP Special resource groupRESHIPER DLF resource indicatorRESNAME Special resource name4.3.20 DELETE WS – WorkstationArg Name DescriptionWSNAME Workstation nameWSREP Workstation reporting attributeWSTWS Fault tolerant workstation, Y or NWSTYPE Workstation typeWSWAIT WAIT workstation, Y or N4.4 EXECUTE – Commit updates to the Current PlanEXECUTE [MCPBLK]The EXECUTE request causes an update of the current plan after one or more modify,insert, or delete current plan requests are completed. If you are changing more thanone current plan occurrence or current plan workstation before an EXECUTE request,you must complete all changes to one occurrence or workstation before changinganother. If you do not complete all changes to one occurrence or workstation amessage is issued and all modifications since the last EXECUTE request are reset.For changes to current plan resources, CSR, no EXECUTE is required.An EXECUTE request will be performed automatically by SOE just before terminationif updates to the Current Plan were detected and OPTIONS EXECUTE(AUTO) has beenspecified (default).Note: The resource can only be MCPBLK and is therefore optional. Any keywords,other than MCPBLK, specified on an EXECUTE statement will be ignored.Copyright IBM 2008 Page 35

4.4.1 Return Code• 0 - The request was successful.• 8 - The request was unsuccessful. An error message has been writtento the message log data set.4.5 JSUACT – TWS TSO CommandJSUACT The JSUACT statement can be used to activate or inactivate job submission.See Using TWS TSO Commands within SOE for more information.4.6 INIT – Initialize communication with TWSINIT The INIT request identifies the Tivoli Workload Scheduler for z/OS subsystemrequired and initializes the communication session between this subsystem and SOE.Through the parameter file EQQYPARM, the user might override the subsystemname specified in the INIT request, and set an LU name, a TRACE level, and theDATINT flag.The parameter file can be a sequential file, or a PDS allocated as://EQQYPARM DD DISP=SHR,DSN=OPCESA.SYS1.CNTL(YPARM)If you do not specify and INIT request SOE will automatically execute one prior toany other PIF requests. It will also generate a TERM request ahead of your INITrequest, if you make an INIT request to a new subsystem while a session is alreadyestablished.An automatic INIT request will only specify the subsystem to connect to, if you codean INIT request yourself you can specify additional arguments.4.6.1 Return code• 0 - The request was successful. A program interface session has beensuccessfully started. The address of the communication block has been placedin the parameter list.• 8 - The request was unsuccessful. Check the message log, SYSLOG, andEQQDUMP data sets for error information.Copyright IBM 2008 Page 36

4.6.2 INIT subsystemArg NameLUNAMEMLOGDDNDescriptionThis argument allows the user to specify a server or controller LUname for the program interface session to communicate through.This argument identifies a message log that messages are written to,rather than the default message log, EQQMLOG.REMHOSTREMPORTEach INIT request requires its own message log. If you make morethan one INIT request before a TERM request, or if PIF is invoked bya program or started task that is already using EQQMLOG, specifyMLOGDDN for each additional INIT request. If MLOGDDN is notspecified, and EQQMLOG is already in use, message EQQZ038E iswritten to the SYSLOG and the INIT request fails.The server host name for the program interface TCP/IP session.REMHOST and LUNAME are mutually exclusive.The server port number for the program interface TCP/IP session.REMPORT and LUNAME are mutually exclusive.Copyright IBM 2008 Page 37

4.7 INSERT – Add objects into the planINSERT ALIAS()The INSERT request in SOE is only used to add occurrences to the Current Plan andLong Term Plan. The PIF facility to update the database is handled by Batch Loaderwithin SOE.When inserting a new occurrence, the input arrival date and time and deadline dateand time can be provided in the arguments. If the input arrival is not provided wheninserting a current plan occurrence, the current date and time is used (that is, the dateand time at which the occurrence is inserted). However, if an occurrence alreadyexists with this application ID and input arrival date and time, the next availableminute in which no occurrence of this application exists will be used. You mustsupply an input arrival date and time if you are inserting an occurrence in the LTP.If arguments are not provided for the deadline, these defaults are observed by TivoliWorkload Scheduler for z/OS:• If the occurrence is being added to the current plan and the input arrival isprovided, the deadline from the first run cycle is used if a run cycle exists. Ifthere are no run cycles or the input arrival is not provided, the deadline is setto the input arrival time plus 8 hours.• When the occurrence is being added to the long-term plan, the deadline is setto the input arrival plus 8 hours.By default, external dependencies of the occurrence are not resolved when it is addedto the LTP or Current Plan. If resolution of external dependencies is required, anOPTIONS LTDEPR or CPDEPR request must be used to specify this.• To insert the extended name of an operation you must use the MODIFYrequest.• To insert new information into an existing LTP or Current Plan occurrence,you use the arguments to provide all the necessary information. For example,you can insert a new operation into an existing current plan occurrence. Butthe actual occurrence to which the information is to be added must have beenidentified by a previous MODIFY or INSERT request. Similarly, you can insertnew information for an existing current plan operation, provided that theoperation has been identified. This means you must first use a MODIFY requestto identify the occurrence and then use a MODIFY request to identify theoperation, before inserting a predecessor (CPPRE), successor (CPSUC), orspecial resource (CPSR).Once identified, the SOE maintains a current occurrence and currentoperation.If you want to insert a new interval into a current plan workstation you mustfirst identify the workstation with a MODIFY CPWS request.If the INSERT request has been used to modify information in the current plan, a laterEXECUTE request must be made for the modification to actually take effect, SOE willdo this for you automatically if OPTIONS EXECUTE(AUTO) is set (default).Copyright IBM 2008 Page 38

4.7.1 Return Code• 0 - The request was successful.• 4 - One or more of the dependencies, specified by the application descriptionof the INSERT LTOC request, was not set up because no applicable predecessoroccurrence exists. This return code could also result from an INSERT requestfor any of LTPRE, CPOP, CPOC, CPPRE, and CPSR, if the dependency wasnot set up.• 8 - The request was unsuccessful. An error message has been written to themessage log data set.4.7.2 INSERT CPOC – Current Plan OccurrenceArg Name DescriptionADID Application description ID as stored in the databaseALIAS Application description ID to use on the Current PlanDEADLINE Deadline date and time YYMMDDHHMMDESC Descriptive textERRCODE Error codeGROUP Authority groupGROUPDEF Group definition IDIAInput arrival date and time YYMMDDHHMMJCLVTAB JCL variable tableODESC Descriptive text of ownerOWNER Owner IDPRIORITY PriorityNotes:1. A DEADLINE argument is accepted also when no IA argument isspecified. If the Tivoli Workload Scheduler selected IA is later than theDEADLINE argument value, the argument value is ignored. Thedefault, IA plus 8 hours, is used instead.2. If you specify 24.00 as the IA time, it is converted to 00.00 of thefollowing day. In fact, the valid input arrival times are 00.00 through23.59.3. If you specify as deadline 00.00, it is converted to 24.00 of the previousday. In fact, the valid deadline times are 00.01 through 24.00.Copyright IBM 2008 Page 39

4.7.3 INSERT CPOP – Current Plan OperationArg NameAECAJRASUBCLATECLNTYPECSCRIPTDEADWTODESCDURATIONEDUREXPJCLFORMHRCJCLASSJOBCRTJOBNAMEJOBPOLMONITOROPDLOPIAOPNOPSUSER1USER2USERERUTRESTASTATUSTIMEDEPUSERDATAUSRSYSWSNAMEWLMSCLSDescriptionAutomatic error completionAutomatic job hold/releaseAutomatic job submissionCancel if lateData Set cleanup typeUses centralized scriptIssue deadline WTODescriptive textEstimated duration in 100th of a second (mutually exclusive withEDUR)Estimated duration HHMM (mutually exclusive with DURATION)Expanded JCL optionForm number or blanksHighest successful return codeJob classCritical job.• P=Critical path target• W=Eligible for WLM assistance• N=Not eligible for WLM assistanceJob nameWorkload monitor late job policy.• ‘ ’ (blank) = use default• L = Long duration• D = Deadline• S = Latest start time• C = Conditional modeOperation monitored by an external product, Y or NOperation deadline date and time YYMMDDHHMM or blankOperation input arrival date and time YYMMDDHHMM or blankOperation numberParallel servers requiredResource 1 requiredResource 2 requiredReroutable operationRestartable operationOperation statusTime-dependent jobData stored in operation user fieldUser sysout supportWorkstation nameWLM service classCopyright IBM 2008 Page 40

4.7.4 INSERT CPPRE – Current Plan PredecessorArg NamePREADIDPREIAPREOPNOTRPTTIMEDescriptionPredecessor Application IDPredecessor Input Arrival date and time YYMMDDHHMMPredecessor Operation numberTransport time HHMMNote: When CPPRE is needed to insert an internal dependency, PREADIDand PREIA should not be used.4.7.5 INSERT CPSAI – Current Plan System Automation InfoArg Name DescriptionAUTFUNC System Automation automated function (for operation). It must be analphanumeric value, uppercase format. The first character cannot benumeric.COMMETXT System Automation command text. It must be set and cannot be blankCOMPINFO System Automation completion informationSECELEM System Automation security elementNotes:1. The occurrence and operation to which the system automation informationrefers are identified, respectively, by INSERT/MODIFY CPOC andINSERT/MODIFY CPOP sequences2. You can only use INSERT CPSAI for an operation that runs on an automationworkstation.4.7.6 INSERT CPSR – Current Plan Operation Special ResourceArg Name DescriptionONCOMPL Availability to set on complete• Y - Available• N - Unavailable• R - Reset availability to defaultONERROR Keep on error, Y or NQUANTITY Quantity required. Specify 0 to allocate the total quantity of thespecial resource. The value 0 is the same as blank in the dialogs.RESNAME Special resource nameRESUSAGE Special resource usage, S or XCopyright IBM 2008 Page 41

4.7.7 INSERT CPSUC – Current Plan SuccessorArg Name DescriptionSUCADID Successor Application IDSUCIA Successor Input arrival date and time YYMMDDHHMMSUCOPNO Operation numberNote: When CPSUC is needed to insert an internal dependency, SUCADIDand SUCIA should not be used.4.7.8 INSERT IVL – Current Plan Workstation IntervalAn interval can have information originating from the workstation description,indicator CPIVLDP in segment CPIVL is set to Y, or otherwise to N. If an interval ischanged via the dialog or the program interface then the indicator CPIVLMOD is Y,or otherwise NINSERT IVL can insert an interval spanning existing intervals with CPIVLMOD=N.The inserted interval will be converted to several intervals as required by dailyplanning. Other requests following the INSERT must take this possible split intoaccount; each request is handled fully before the next request.Arg NameFROMPSCAPR1CAPR2CAPTODescriptionInterval start date/time YYMMDDHHMMParallel server capacityResource 1 capacityResource 2 capacityInterval end date and time YYMMDDHHMM4.7.9 INSERT JCLPREP – JCL PreparationArg Name DescriptionADID Application IDIAInput arrival date and time YYMMDDHHMMOPNO Integer Operation number4.7.10 INSERT JCLV – JCL Variable TableArg Name DescriptionJCLVTAB JCL variable table IDCopyright IBM 2008 Page 42

4.7.11 INSERT LTOC – Long Term Plan OccurrenceArg Name DescriptionADID Application IDDEADLINE Deadline date and time YYMMDDHHMMERRCODE Error codeGROUPDEF Group definition IDIAD Run date YYMMDDIATInput arrival time HHMMJCLVTAB JCL variable tablePRIORITY Priority4.7.12 INSERT LTPRE – Long Term Plan PredecessorArg NameADIDIADIATPREADIDPREIADPREIATDescriptionApplication IDRun date YYMMDDInput arrival time HHMMPredecessor Application IDPredecessor Run date YYMMDDPredecessor Input arrival time HHMMNote: INSERT LTPRE is used only to insert external predecessors. No support isprovided in the long-term plan for internal dependencies.Copyright IBM 2008 Page 43

4.8 LIST – Find objects in the Database and PlansLIST VALID() SAVELIST()The LIST request retrieves a list of records of a selected type.When you use the LIST request, the resulting list consists only of the commonsegments of the records. If you want to retrieve a complete record, you must use theSELECT request. SOE can automatically perform SELECT requests for each item listedby specifying OPTIONS SELECT(Y).When retrieving current plan occurrences and operations, the default is to retrieve allmatching objects except those in deleted status. When STATUS is provided as anargument, the specified selection overrides the default processing.Argument names specify field names of the record to be tested to determine if therecord should be included in the list.Notes:1. Because the first blank or comparison-operator symbol ends the argumentvalue, you cannot search for fields that contain imbedded blanks orcomparison-operator symbols.2. Generic search arguments, * and %, cannot be used in the year part (YY) ofdate arguments.3. When you want to use a comparison operator (such as , or ≠) in anargument, and the argument contains an IA value that includes a date and time,supply the full value as the argument value. The comparison operator canfollow this value.4. The values of PIF arguments as dates depend on the PIF base year, which isdefined by the PIFCWB keyword on the INTFOPTS statement, or theCWBASE keyword of the INIT statement. The value of the VALTO argumentfor default high date depends on the PIFHD keyword of the INTFOPTSstatement or the HIGHDATE keyword of the INIT statement.5. The Tivoli Workload Scheduler for z/OS Program Interface requires that theCommon Segment be used in LIST requests. SOE will allow the record to bespecified instead, and will translate this internally to the common segmentbefore passing the request to the PIF.4.8.1 Return Code• 0 - The request was successful.• 4 - The request was unsuccessful, for one of these reasons:i. The requestor is not authorized to read the records.ii. No records meet the criteria specified by the arguments.• 8 - The request was unsuccessful. An error message has been written tothe message log data set.Copyright IBM 2008 Page 44

4.8.2 MATCHTYP ArgumentWith argument MATCHTYP specified, characters * and % are treated as normalcharacters instead of as generic matching characters, and blank as a normal characterinstead of ending the selection value.MATCHTYP EXA, PFX, and SFX affect:• The STATUS argument of the CPOPCOM segment• The ETTNAME argument of the ETT segment• The RESNAME argument of the SRCOM and CSRCOM segments.The argument can have the following values –• EXA – Exact match• PFX – Treat as a prefix match• SFX – Treat as a suffix matchNotes:1. If MATCHTYP has the EXA value specified, then a record is selectedonly if the value in the record is exactly the same as the argumentvalue.2. If MATCHTYP has the PFX value specified, then a record is selectedonly if the start value in the record is the same as the argument value.3. If MATCHTYP has the SFX value specified, then a record is selectedonly if the end value in the record is the same as the argument value.4.8.3 SAVELIST ArgumentThe SAVELIST argument can be used on a LIST command for any resource to save thelist of objects that were found for input to Batch Loader commands to identify theobjects to update.e.g.OPTIONS OUTMASK(Y)LIST ADCOM OWNER(ABC*) SAVELIST(ABCOWNED)ADSTART SAVELIST(ABC*) OWNER(XYZ*)This will find all Applications with an Owner ID starting with ABC and feed that listinto Batch Loader command ADSTART to change the Owner ID to start with XYZ.Copyright IBM 2008 Page 45

4.8.4 TAG ArgumentThe TAG argument can be used on a LIST command for any resource to create anadditional output field called TAG which will be available in any segment generatedby the command. This allows for the output from multiple LIST commands to becorrelated back to the originating command.e.g.OUTPUT ADCOM FIELDS(TAG,ADID)LIST ADCOM ADID(ABC*) TAG(ABCAPPS)LIST ADCOM OWNER(ABC*) TAG(ABCOWNED)In this example the command will perform 2 LIST requests, one for Applications withnames beginning ABC, the other for Applications with Owner beginning ABC. Thereturned records will list the TAG and the ADID. By checking the TAG you will be ableto determine which LIST request each record came from.Note: Any SELECT statements generated from a LIST statement using OPTIONSSELECT(Y) will automatically be passed the same TAG argument.4.8.5 LIST ADCOM/ADKEY – Application ID/Application KeyArg Name DescriptionADID Application description IDGROUP Authority group nameGROUPDEF Group definition IDMONITOR • Y=application with at least one operation monitored by anexternal product• N=application with no operation monitored by an externalproductOWNER Owner IDPRIORITY PrioritySTATUS Status:• P=Pending• A= ActiveTYPE Application type:• A=Application (default if TYPE not specified)• G=GroupVALID Valid-on date YYMMDD. The Valid-on date is used to find anapplication valid on a specific date. SOE uses this to generate thecorrect combination of VALFROM and VALTO.VALFROMVALTOe.g. VALID(081125) will find the version of an Application valid onthe 25 th of November 2008.Valid-from date YYMMDDValid-to date YYMMDDCopyright IBM 2008 Page 46

4.8.6 LIST AWSCL – All Workstations ClosedArg Name DescriptionDATE Date YYMMDD4.8.7 LIST CLCOM - CalendarArg Name DescriptionCALENDAR Calendar ID4.8.8 LIST CPOC – Current Plan OccurrenceArg Name DescriptionADID Application description IDGROUP Authority groupGROUPDEF Group definition IDIAInput arrival date and time YYMMDDHHMMMCPADDED Add by Modify Current Plan operation, Y or NMONITOR • Y=occurrence with at least one operation monitored by anexternal product• N=occurrence with no operation monitored by an externalproductOWNER Owner IDPRIORITY PriorityRERUN Rerun requested, Y or NSTATUS Occurrence statusNote: By default, occurrences in deleted status are not retrieved when the STATUSargument is not supplied. If you do not provide the STATUS argument, the request isprocessed as STATUS-NE(D).Copyright IBM 2008 Page 47

4.8.9 LIST CPOPCOM – Current Plan OperationArg Name DescriptionADID Application description IDCLNSTAT Data Set cleanup statusCLNTYPE Data Set cleanup typeERRCODE Error codeEXPJCL Expanded JCL optionEXTNAME Operation extended nameEXTSE Scheduling Environment nameGROUP Authority groupIAInput arrival date and time of the occurrence YYMMDDHHMMJOBCRT Critical job:• P=Critical path target• W=Eligible for WLM assistance• N=Not eligible for WLM assistanceJOBNAME Job nameJOBPOL Workload monitor late job policy.• ‘ ’ (blank) = default• L = Long duration• D = Deadline• S = Latest start time• C = Conditional modeMONITOR • Y=operation monitored by an external product• N=operation not monitored by an external productOPNO Operation numberOWNER Owner IDPRIORITY PrioritySTATUS Operation statusUSRSYS User sysout supportWAITSE Waiting for Scheduling Environment, N or YWLMSCLS WLM service classWSNAME Workstation nameWAITFORW Started on WAIT workstation, Y or NNote: By default, operations in deleted status are not retrieved when the STATUSargument is not supplied. If you do not provide the STATUS argument, the request isprocessed as STATUS-NE(D).Copyright IBM 2008 Page 48

4.8.10 LIST CPOPSRU – Current Plan Operation SR UsageArg Name DescriptionLISTTYPE INUSE or WAITQRESNAME Special resource nameNotes:1. Both arguments are required. The argument value specified forRESNAME is the name of the special resource for which the In-Uselist or Wait Queue is to be retrieved.2. Generic characters are not supported. It is processed as ifMATCHTYP(EXA) was specified; exact match is required for recordselection. The argument MATCHTYP is NOT supported.4.8.11 LIST CPWSCOM – Current Plan WorkstationArg Name DescriptionWSAUTO Automation Workstation, Y or NWSNAME Workstation nameWSREP Workstation reporting attributeWSTWS Fault-tolerant workstation, Y or NWSTYPE Workstation typeWSWAIT WAIT Workstation, Y or N4.8.12 LIST CSRCOM – Current Plan Special ResourceArg Name DescriptionRESALCS If any operation is currently allocating the resource shared, Y or NRESAVAIL Whether or not the resource is available, Y or NRESGROUP Resource group nameRESHIPER Whether or not it is a DLF control resource, Y or NRESNAME Resource nameRESWAIT Whether or not any operation is waiting for the resourceNote: All the arguments are optional. The argument MATCHTYP is supported.4.8.13 LIST ETT – Event TriggersArg Name DescriptionADID Associated application IDETTNAME Name of triggerETTTYPE Type of trigger4.8.14 LIST JCLVCOM – JCL Variable tablesArg Name DescriptionJCLVTAB JCL Variable Table IDCopyright IBM 2008 Page 49

4.8.15 LIST JSCOM – Current Plan JCLArg NameADIDIAJOBNAMEOPNOWSNAMEDescriptionApplication IDInput arrival date and time YYMMDDHHMMz/OS job nameOperation numberWorkstation nameNote: The resource code JSCOM retrieves JCL records from the JCL repositorydata set and not from a JCL library. But a SELECT request tries to get JCLrecords from a JCL library if they are not found in the JCL repository data set.4.8.16 LIST LTOCCOM – Long Term Plan OccurrenceArg Name DescriptionADID Application IDGROUP Authority groupGROUPDEF Group definitionIAD Run date YYMMDDIATInput arrival time HHMMOWNER Owner ID4.8.17 LIST OICOM – Operator InstructionsArg Name DescriptionADID Application IDOPNO Operation number4.8.18 LIST PRCOM – PeriodArg Name DescriptionPERIOD Period namePRTYPE Period type4.8.19 LIST SRCOM – Special ResourceArg Name DescriptionRESGROUP Special resource group IDRESHIPER DLF resource indicatorRESNAME Special resource nameCopyright IBM 2008 Page 50

4.8.20 LIST WSCOM – WorkstationArg Name DescriptionWSAUTO Automation workstation, Y or NWSNAME Workstation nameWSREP Workstation reporting attributeWSTWS Fault-tolerant workstation, Y or NWSTYPE Workstation typeWSWAIT WAIT Workstation, Y or NCopyright IBM 2008 Page 51

4.9 LISTSTAT – List Status of Current Plan ObjectsLISTSTAT [POLICY()]The LISTSTAT request will LIST items and set a return code based on their status.This is similar to the Batch Command Interface Tool (BCIT) command of LISTSTAT,but supports more resources. The return codes for the BCIT supported resources arethe same for SOE.Note that LISTSTAT performs an LIST request to find the relevant elements withinTWS. If the LIST request returns multiple records the command will end RC=8.The arguments for LISTSTAT are the same as the arguments for the related LISTrequest for the same resource with the exception of POLICY which is used to set thereturn code policy for the request.If you want to set your own Return Code policy you can add the POLICY keyword tothe LISTSTAT command. The POLICY keyword allows you to set specific return codesfor groups of status values, and set a return code for anything that does not match anyof your listed statuses.POLICY(=,=,…,=,)If you omit to supply a catch all return code then you will get RC=99 when no matchoccurs. The return code must be a non-negative whole number.For example –LISTSTAT CPOPCOM ADID(TWSCDAILYPLAN) OPNO(010) IA(0805281200)POLICY(AR*=10,SW=20,C=30,40)Would return 10 if the status was A, R or *, it would return 20 if the status was S orW, it would return 30 if the status was C and return 40 if any other status wasencountered.Another use of this would be to use the POLICY to separate acceptable fromunacceptable conditions.For example –LISTSTAT CPOPCOM ADID(TWSCDAILYPLAN) OPNO(010) IA(0805281200)POLICY(C=0,20)This example will end with return code zero if the operation is complete, but return 20if it is not.Note 1: SOE will return 4 if the item being listed is not found, 8 if more than oneitem is found, 12 if you have made a syntax error and 16 if an initialization erroroccurs. It is recommended, that you avoid using these return codes in your POLICY ifyou need to distinguish those errors from your return codes.Note 2: If you run multiple LISTSTAT commands in one session, the highest returncode will be returned.Copyright IBM 2008 Page 52

Note 3: If any command other than LISTSTAT breaches the OPTIONS STOPRC setting,the LISTSTAT return code will not be returned.Note 4: The LISTSTAT command itself will only ever complete with return codes 0, 4,8 or 12. The actual return code for the status is returned as SOE terminates.Note 5: The SETMAX command has no impact on the return code set by LISTSTAT.Supported resources for LISTSTAT are –• CPOC – Occurrences in the Current Plan• CPOPCOM –Operations in the Current Plan• CPWSCOM –Workstations in the Current Plan.• CSRCOM – Special Resources in the Current Plan.4.9.1 Return Codes• 4 Resource not found or user ID has no RACF authorization to read theresource.• 8 More than one record identified.• 12 SOE Syntax error• 31 Occurrence status C (completed)• 32 Occurrence status D (deleted)• 33 Occurrence status E (ended in error)• 34 Occurrence status P (processor pending)• 35 Occurrence status S (started)• 36 Occurrence status U (undecided)• 37 Occurrence status W (no started operations)• 40 Operation status *• 41 Operation status A (waiting for input to arrive)• 42 Operation status R (ready)• 43 Operation status S (started)• 44 Operation status C (completed)• 45 Operation status D (deleted)• 46 Operation status I (interrupted)• 47 Operation status E (ended in error)• 48 Operation status W (waiting for a predecessor)Copyright IBM 2008 Page 53

• 49 Operation status U (undecided)• 50 Operations status X (excluded)• 60 Workstation status A (active)• 61 Workstation status O (offline)• 62 Workstation status F (failed)• 63 FT Workstation status L (linked FTA)• 64 FT Workstation status U (unlinked FTA)• 70 Special resource available• 71 Special resource unavailable• 99 Unexpected status returned4.10 MODIFY – Modify objects in the plansMODIFY The MODIFY request modifies one or more fields in an LTP or Current Plan record.The arguments can be used both to identify the record to be modified, and to providenew values for this record. Or, the arguments can be used just to identify a record, andlater requests can be used to perform particular actions. For example, with a MODIFYrequest, you can identify a particular current plan occurrence record. Then, with laterINSERT requests, you can insert new operation records for that occurrence.The MODIFY request can be used to modify information in the current plan. Requeststhat cause a modification of the current plan, except CSR requests, require a laterEXECUTE request for the modification to actually take effect.With the arguments described here, you specify the names and values of fields, eitherto identify a particular record, or provide updated information for a record.Note: The values of PIF arguments as dates depend on the PIF base year, which isdefined by the PIFCWB keyword on the INTFOPTS statement, or the CWBASEkeyword of the INIT statement. The value of the VALTO argument for default highdate depends on the PIFHD keyword of the INTFOPTS statement or the HIGHDATEkeyword of the INIT statement.Copyright IBM 2008 Page 54

4.10.1 Return Code• 0 - The request was successful.• 4 - The MODIFY CPOP request might end with return code 4 if the operationinput arrival value specified in the request is earlier than the occurrence. If thishappens, run the EXECUTE request for the modification to be enforced.• 8 - The request was unsuccessful. An error message has been written to themessage log data set.4.10.2 MODIFY CPEXT – Current Plan Extended OperationInfoArg Name DescriptionEXTNAME Operation extended name. To delete the operation extended name,enter blank.EXTSE Scheduling Environment name. Special characters are allowed. Todelete the SE name, enter blank.4.10.3 MODIFY CPOC – Current Plan OccurrenceWhen you are modifying an existing current plan occurrence, the ADID and IAarguments identify the occurrence to be modified. All remaining arguments providethe information used to modify the occurrence. The only valid values for the STATUSargument are W (Waiting) and C (Complete).Arg Name DescriptionADID Application description IDALLMON • Y=all operations of occurrence monitored by an externalproduct• N=all operations of occurrence not monitored by an externalproductDEADLINE Deadline date and time YYMMDDHHMMERRCODE Error codeGROUPDEF Group definition IDIAInput arrival date and time YYMMDDHHMMIANEW New input arrival date and time YYMMDDHHMMJCLVTAB JCL variable tablePRIORITY PrioritySTATUS Occurrence statusCopyright IBM 2008 Page 55

4.10.4 MODIFY CPOP – Current Plan OperationWhen you are modifying an existing current plan operation, the OPNO argument isrequired to identify the operation to be modified. All remaining arguments areoptional and provide the information used to modify the operation. If you are inserting,modifying, or deleting a predecessor connection or special resource specification forthe operation, the MODIFY CPOP request is required only to identify the operation thatwill be referred to in the following INSERT, MODIFY, or DELETE request. Then, only theOPNO argument is required.Note: Always identify an occurrence with a MODIFY CPOC request before a MODIFYCPOP request.Arg NameAECAJRASUBCLATECLNTYPEDEADWTODESCDURATIONEDURERRCODEEXPJCLFORMHRCJCLASSJOBCRTJOBNAMEJOBPOLDescriptionAutomatic error completionAutomatic job hold/releaseAutomatic job submissionCancel if lateData Set cleanup typeIssue deadline WTOOperation descriptive textEstimated duration in 100th of secondEstimated duration HHMMError codeNote: You cannot change the error code if the operation runs on afault tolerant workstation and is in error statusExpanded JCL optionForm number or blanksHighest successful return codeJob classCritical job:• P=Critical path target• W=Eligible for WLM assistance• N=Not eligible for WLM assistanceJob nameWorkload monitor late job policy:• ‘ ’ (blank) = default• L = Long duration• D = Deadline• S = Latest start time• C = Conditional modeMONITOR • Y=Operation monitored by an external product• N=Operation not monitored by an external productCopyright IBM 2008 Page 56

Arg NameOPCMDOPDLOPIAOPNOPSUSER1USER2USERERUTRESTASTATUSTIMEDEPUSERDATAUSRSYSWLMSCLSWSNAMEDescriptionOperation command:• EX = Execute operation• MH = Hold operation• MR = Release operation• NP = NOP operation• PN = Prompt reply no• PY = Prompt reply yes• UN = Un-NOP operationOperation deadline date and time or blank YYMMDDHHMMOperation input arrival date and time or blank YYMMDDHHMMOperation numberParallel servers requiredResource 1 requiredResource 2 requiredReroutable operationRestartable operationOperation statusTime-dependent jobData stored in operation user fieldUser sysout supportWLM service classWorkstation name4.10.5 MODIFY CPSAI – Current Plan System Automation InfoArg Name DescriptionAUTFUNC Automation automated function (for operation).COMMETXT System Automation command text.COMPINFO Automation completion informationSECELEM System Automation security elementNotes:• The occurrence and operation to which the system automationinformation refers are identified, respectively, by the INSERT or MODIFYCPOC ADID IA and INSERT or MODIFY CPOP OPNO sequences.• You can use MODIFY CPSAI only if the operation runs on an automationworkstation.Copyright IBM 2008 Page 57

4.10.6 MODIFY CPWS – Current Plan WorkstationWhen you are modifying a current plan workstation, the WSNAME argument is required;it identifies the workstation. The remaining arguments contain the modifiedinformation.Arg Name DescriptionALTWS When the workstation is set to failed or offline then anotherworkstation can be specified for rerouting. Specify ALTWS ifoperations should be rerouted; if ALTWS is not supplied then norerouting takes place.PSC Control on parallel serverR1C Control on resource 1R2C Control on resource 2STARTACT Action to be taken on current plan operations that have a status ofstarted when the workstation status is set to failed or offline. Valuesare restart (R), set to error (E), or leave operation as is (L).STATUSWSLNKWSNAMEWSREPNote: If the STARTACT argument is omitted when a workstation isset to failed or offline then no action is performed on the operations,as though STARTACT L was specified.New status of active (A), failed (F), or offline (O).Note: The status failed is valid only for non-fault tolerantworkstations.L=Workstation Linked (only FTW) U=Workstation Unlinked (onlyFTW) Blank=For non-fault tolerant WSWorkstation nameWorkstation reporting attributeCopyright IBM 2008 Page 58

4.10.7 MODIFY CSR – Current Plan Special ResourceMODIFY CSR takes as selection argument the resource name in the RESNAME argument.This argument is required. The resource name must be padded to the full length of 44characters. It is processed as if MATCHTYP(EXA) was specified and an exact match isrequired for record selection. Alternatively, the common segment CSRCOM can begiven as the selection argument. Remaining arguments are optional and containmodifications.Arg Name DescriptionDEFAVAIL Default availability, N or YDEFQTY Default quantity, 1 to 999999MAXLIMIT Maximum usage limit. From 0 (no limit) to 999999.MAXTYPE Type of action when maximum usage limit is reached: Y|N|RONCOMPL Action on complete Y|N|RONERROR Action on error, F, FX, FS, K, or blankQUANTITY Override quantity, numeric 1 to 999999, or 0 to indicate that there isno overriding quantity.RESAVAIL Override availability, N, Y, or blank to indicate there is no overridingavailabilityRESDEVIA Deviation, -999999 to 999999.RESNAME Resource nameUSEDFOR Used for C, P, B, or NNote: MATCHTYP is NOT supported.4.10.8 MODIFY IVL – Current Plan Workstation InfoWhen you are modifying a workstation open interval, the FROM argument is requiredto identify the interval to be modified. All remaining arguments are optional andprovide the information used to modify the open interval.Note: Always identify a workstation with a MODIFY CPWS request before a MODIFYIVL request.Arg NameALTWSFROMPSCAPR1CAPR2CAPDescriptionWorkstation to take over if this one fails or is set offlineInterval start date and time YYMMDDHHMMParallel server capacityResource 1 capacityResource 2 capacityCopyright IBM 2008 Page 59

4.10.9 MODIFY LTOC – Long Term Plan OccurrenceWhen you are modifying an existing LTP occurrence, the ADID, IAD, and IATarguments identify the occurrence to be modified. All remaining arguments providethe information used to modify the occurrence.Arg NameADIDDEADLINEERRCODEGROUPDEFIADIATJCLVTABPRIORITYDescriptionApplication description IDDeadline date and time YYMMDDHHMMError codeGroup definition IDInput arrival date YYMMDDInput arrival time HHMMJCL variable tablePriority4.11 OPINFO – TWS TSO CommandOPINFO The OPINFO statement can be used to update the User Field of an operation in thecurrent plan.See Using TWS TSO Commands within SOE for more information.4.12 OPSTAT – TWS TSO CommandOPSTAT The OPSTAT statement can be used to set the status of an operation in the currentplan.See Using TWS TSO Commands within SOE for more information.Copyright IBM 2008 Page 60

4.13 OPTIONS – Define run time options/PIF requestOPTIONS The OPTIONS statement has no resource. For SOE it can be used to set both SOEoptions and TWS options. The following keywords are available –ACTIONDetermines the operating mode for Batch Loader. See Modes of operation for details.ADOICHKDetermines whether AD/OI consistency checks are to be made every time anapplication is deleted or modified. Consistency checks involve looking in theapplication description data base for matches for all the operator instructions in theapplication. Any operator instructions without a match are deleted. The checks aremade immediately after the application description PIF action has completed with azero return code -• Y - Consistency checks are performed whenever an application descriptionrecord is deleted or replaced using the PIF.• N - Consistency checks are not performed. (default).ADVALFROMHow to set ADVALFROM in generated Batch Loader –• A – Asis, list VALFROM as it is defined in TWS database (default)• N – New, list VALFROM with today’s date.• ymmdd – A specific date to use as VALFROM for any generated batch loader e.g.ADVALFROM(060124).ADVERSApplication version support –• Y – When applications are deleted the VALTO and VALFROM field of anyother existing versions of the same application are adjusted to providecontinuous validity periods (default)• N – When applications are deleted the VALTO and VALFROM field of anyother existing versions of the same application are not altered.Note: Applications being updated by Batch Loader automatically calculate and adjustthe VALTO and VALFROM fields regardless of the setting of ADVERS.Copyright IBM 2008 Page 61

ARGUMENTData to pass to a Segment Processing Exit. If you are using the EXIT keyword, thiscan be used to pass additional information to drive the exit. The ARGUMENT canalso be updated by the exit itself, allowing data to be passed from one record to thenext.CHECKWhether to check the existence for workstations with applications when processingbatch loader –• Y – Yes, cause load to fail if workstations do not exist (default).• N – No, create applications regardless.COMMITNumber of output records to hold in storage before committing to disk (default 1000).Note that the value specified by commit is the maximum total across all output files.SOE will divide the commit total you enter by the number of files open and commiteach file when that total is reached. So if you specify COMMIT(1000) and have twooutput files, they will each commit after 500 records.The external data queue does not count as an output file and will not be affected byCOMMIT, neither will it influence the calculation.COMENDComment end character (default */). You can alter the character used to end acomment block, but it will only take effect from the start of the next command inputsource (see Command language).COMSTARTComment start character (default /*). You can alter the character used to start acomment block, but it will only take effect from the start of the next command inputstream (see Command language).Copyright IBM 2008 Page 62

CONTENTIONWhat to do in event of contention within TWS. The parameter has 2 arguments –1. Delay – the number of seconds to delay before retry (default 30).2. Retries – the number of reattempts to make (default 10).e.g. CONTENTION(10,5) will wait 10 seconds before retrying up to 5 times.CONTENTION(0,0) will disable the contention retry feature.There is a 3 rd optional positional parameter you can specify if you are using analternate program to perform the delay. The third parameter can be used to specifythe delay period directly in the format supported by the alternate delay program.For example if the alternate delay program had a format of HHMMSSTT, then a delayof 1 minute, with 2 retries would be specified CONTENTION(60,2,00010000).The first two arguments are still required for diagnostic messages.CPDEPRAutomatic resolution of external dependencies when inserting new current planoccurrences –• Y - Add successor and predecessor dependencies.• N - Do not add any dependencies (default).• P - Add predecessor dependencies.• S - Add successor dependencies.Copyright IBM 2008 Page 63

DATEWhen using the = symbol to represent a DATE or TIME within SOE it will by defaultuse the date and time that SOE started instead of the = sign. SOE maintains a staticinternal date to allow you to generate multiple statements with a “current date” that isconsistent across all statements, regardless of whether the date changes duringexecution.OPTIONS DATE allows you to set an explicit current DATE to use instead of = or anyother function that requires the current date within SOE.The format of the date can either be ccyymmdd or yymmdd. If yymmdd is used thecentury is calculated using TWS HIGHDATE and CWBASE settings.e.g.OPTIONS DATE(070124) TIME(1600)INSERT CPOC ADID(MYAPPL1) IA(=)INSERT CPOC ADID(MYAPPL2) IA(=)INSERT CPOC ADID(MYAPPL3) IA(=)INSERT CPOC ADID(MYAPPL4) IA(=)INSERT CPOC ADID(MYAPPL5) IA(=)INSERT CPOC ADID(MYAPPL6) IA(=)Will result in all 6 occurrences having an IA of 0701241600You can also use OPTIONS DATE to set the internal SOE date to be relative to thecurrent datee.g.OPTIONS DATE(+1) sets the date SOE will use as current to tomorrow’s dateOPTIONS DATE(-1) sets the date SOE will use as current to yesterday’s dateYou can reset the internal SOE date to the current date by using –OPTIONS DATE(RESET).DATAFile Destination to override value specified on the OUTPUT DATA keyword (seeOUTPUT – Define output record).Note: OPTIONS DATA will cause output to be written for all segments referenced byOUTPUT statements, regardless of whether they originally had a DATA keyword.Copyright IBM 2008 Page 64

DELAYSpecifies a number of seconds to pause after issuing any update command to the TWSPIF (default 0). This is specifically to reduce the impact mass updates may havelocking out other users by providing gaps in processing.Note that the command and return code will not be reported in the output until thedelay has completed.If you are using your own module to provide the WAIT functionality, then you canspecify the delay as a second argument in the parameter format for your WAITmodule e.g. DELAY(5,00000500). The first argument is still required for messages.DELAYCMDPIF commands to consider as update commands to perform a delay after (defaultDELETE EXECUTE INSERT REPLACE).Note that MODIFY is not considered an update command for the purposes of DELAYsince it does not actually commit to TWS until the EXECUTE command.DELETEWhether to delete any records that have been processed by a SELECT statement –• Y – Yes, DELETE the SELECTed record.• N – No, do not DELETE the SELECTed record (default)• D – Defer, generate DELETE statements for each SELECTed record and outputthem to the DELFILE output destination for later processing.DELFILEFile Destination to write deferred DELETE statements to.Copyright IBM 2008 Page 65

DURSECThis argument lets you decide the duration format of Insert and Replace Action ofAD/WS record. You can also specify this option request in the INIT statement of theEQQYPARM file. ADOPDUR and WSOPDUR fields contain duration value inminutes. APOPDURI and WSOPDURI fields contain duration value in hundredths ofa second. If DURSEC is not specified, Adopur/Wsopdur value will be used.• Y - Adopduri/Wsopduri will be always used.• N - The field Adopduri/Wsopduri will be checked to have the same value ofthe field Adopdur/Wsopdur when the field Adopduri/Wsopduri is rounded upto a number of minutes. If this happens, it means that no change occurred andthe field Adopduri/Wsopduri will be used. If the Adopduri/Wsopduri value isdifferent from the Adopdur/Wsopdur one, it means that the user changedduration value in Adopdur/Wsopdur and this field will be used.DURUNITBatch Loader option to state what unit durations are specified in –• MINUTES (default)• SECONDSCopyright IBM 2008 Page 66

EQQYLTOPRestrict batch loader output and input continuation rules to EQQYLTOPcompatibility.• N – No, do not restrict processing• Y – Yes, restrict processingThis is to allow output generated by SOE to be processed by EQQYLTOP and BatchLoader written to EQQYLTOP rules to be processed the same way.When set to Y, SOE will apply the following restrictions –• Any input beyond column 72 will be ignored.• A non blank character in column 72 will force an abuttal continuation.• Batch Loader keywords not supported by EQQYLTOP for the relevant releasewill not be generated.Note: There are some Batch Loader keywords that are not supported by someversions of EQQYLTOP, even though the underlying version of TWS has the relevantdata structure. With EQQYLTOP compatibility turned off SOE will generate allkeywords appropriate for the data structures within the version of TWS being used,regardless of whether EQQYLTOP would have supported it at that version, as SOEwill process these keywords in batch loader against any release of TWS for which thedata is appropriate.e.g. ADSTAT will be output in Batch Loader statements for any version of TWS ifEQQYLTOP is set to N. If it is set to Y then ADSTAT will only be generated forversion 8.3 and above, or version 8.2 with OPTIONS SPE(PEND=Y) set inside SOE.EXECUTEAutomatically performs an EXECUTE before termination• MANUAL – All EXECUTE statements must be explicitly coded• AUTO – If Current Plan INSERT or MODIFY statements have taken place,without an intervening EXECUTE or RESET, then an EXECUTE will beperformed automatically before the TERM statement is actioned.EXITName of the Segment Processing Exit to run during extraction. The Exit Name iscase sensitive and does not have to conform to member name conventions, as the exitname is translated into a program call by the EQQYXU00 REXX program.Note: EXITUSE must also be set to see the exit have any impact on data outputcontent.Copyright IBM 2008 Page 67

EXITUSEWhat to do with the data record returned from a Segment Processing Exit –• Y – Use for both DATA and LOADER output.• D – Use only for DATA output.• L – Use only for LOADER output.• N – None, use unmodified output from TWS for DATA and LOADER output(default).EXPANDWhether to generate LIST statements for any database elements that may be requiredby a SELECTed database element.• Y – Yes• N – No (default)• F - FullYES will LIST all items that are absolutely required by the object to function correctly.For example, an Application that is part of a Group needs the Group Definition, if it isan event triggered application it needs the ETT rule, any workstations, calendars orperiods are also needed.FULL will LIST the items covered by YES but will also LIST extra items not required tomake the individual object work, but are referenced by it. These extra items include –• Applications referenced as external predecessors.Note: Applications LISTed by the EXPAND option will use the keyword of VALID(=)to only LIST the versions valid on the day of execution. The DATE option can be usedto influence this.FASTPATHFASTPATH can make the search for operations considerably faster when you wantonly to retrieve computer and printer operations.• Y - Tivoli Workload Scheduler for z/OS searches the current plan forcomputer or printer operations matching the job name search argument. It thenselects all operations in the occurrences that contain these computer or printeroperations (that is, even operations at general workstations), and retrievesthese operations based on the remaining search arguments that you havespecified.• N all operations are retrieved that match the search argument criteria that youhave specified (default)Copyright IBM 2008 Page 68

FIELDSEPThe Field Separator character, is used to separate fields in the DATA output. This canbe either a direct single character reference, e.g. FIELDSEP(,) would use a comma toseparate fields, or you can specify a hex value either as a two byte notation, or twobytes suffixed with x, e.g. FIELDSEP(00) or FIELDSEP(00x)For safe parsing of your data ensure that you use a value that you are sure will not beencountered in any data you may be extracting (default 00x).Field Separators can be turned off by FIELDSEP(NONE).WARNING: If you intent to use EXIT or the EQQYXFLD function, ensure you do notuse the same value for FIELDSEP (default “00”x) and LABELSEP (default =), andNONE must not be used. If this happens, when an EXIT is called, it will be not usedand EXIT reset to blank.FILESPECDD name to read File Specification from.FIRSTSets the default logical first operation within an application for any process that needsa logical start point.FIRST([,LINK][,ALL])Where• - The number of the operation to be considered the logical startpoint of the application.• LINK – Instructs SOE to create an automatic ADDEP statement to link to thefirst operation for any operation that does not have a predecessor.• ALL – In conjunction with LINK instructs SOE to create automatic ADDEPstatements to link to the first operation for all operations, including ones withpredecessors already defined.Note: ALL has no effect if LINK is not also specified.Copyright IBM 2008 Page 69

HIGHRCHighest acceptable return code. Anything up to this return code will not affect thehighest return code of the job. Note that any return codes set before the HIGHRCoption is processed WILL affect the job highest return code.Available values are 0, 4 or 8 (default 0).INPUTDD statement to use for input statements (default SYSIN for Batch, INPUT for TSO).You can name a specific DD statement for SOE to read for the main command stream,or you can specify INPUT(-OFF-) to prevent SOE from attempting to read an INPUTstream from a file, so it only reads from the External Data Queue.LABELSEPThe Label Separator character, is used to separate field Labels from Values in theDATA output. This can be either a direct character reference, e.g. LABELSEP(=) woulduse = to separate field labels and values or you can specify a hex value either as a twobyte notation, or two bytes suffixed with x,, e.g. FIELDSEP(01) or FIELDSEP(01x).Label separators can be turned off by LABELSEP(NONE).WARNING: If you intent to use EXIT or the EQQYXFLD function, ensure you do notuse the same value for FIELDSEP (default “00”x) and LABELSEP (default =), andNONE must not be used. If this happens, when the EXIT is called, it will be not usedand reset to blank.LASTSets the default logical last operation within an application for any process that needsa logical end point.LAST([,LINK][,ALL])Where• - The number of the operation to be considered the logical endpoint of the application.• LINK – Instructs SOE to create an automatic ADDEP statement to link to thelast operation for any operation that does not have a succecessor.• ALL – In conjunction with LINK instructs SOE to create automatic ADDEPstatements to link to the last operation for all operations, including ones withsuccecessors already defined.Note: ALL has no effect if LINK is not also specified.Copyright IBM 2008 Page 70

LOADERFile Destination to override value specified on the OUTPUT LOADER keyword (seeOUTPUT – Define output record).Note: OPTIONS LOADER will cause output to be written for all segments referenced byOUTPUT statements, regardless of whether they originally had a LOADER keyword.LTDEPRAutomatic resolution of external dependencies when inserting new LTP occurrences.• Y - Yes.• N - No (default).OUTMASKTells SOE to treat % and * as masking characters for updating fields within BatchLoader statements.• N – Do not use masking for updates (default)• Y – Use masking for updatesRegardless of this setting, masks can still be used in key fields to identify records.MEMORYTells SOE how to manage its storage, you should only use this option if you arehaving problems running SOE in the storage specified in the REGION parameter inthe JCL. SOE does attempt to be efficient in memory usage, but in some cases,freeing storage will be at the expense of speed.• F – Fast, SOE will not take steps to free data objects (default).• S – Small, SOE will DROP internal data structures in an attempt to reduceoverall storage. Note this may increase run time.Unless you are processing large amounts of input statements or data, neither optionwill have any noticeable effect.Copyright IBM 2008 Page 71

MSGLEVELDetermines what level of messages to issue -1. Only show commands from user input on data queue or SYSIN, or commandsthat have not completed successfully (default)2. Also show commands generated from user input, such as SELECTs fromLISTs.3. Also show commands from FILESPEC source4. Also show commands from OPTIONS, SUBSYS and arg source5. Show system generated commands INIT, TERM and OPTIONS RETMSGalong with commands generated as part of composite commands.There are two special message levels –• -1 which only lists Fatal and Critical errors. When invoked with the SILENTimmediate option this will suppress SOE startup messages.• 0 which will ONLY list commands that have not completed successfully. Anycommand that issues a return code higher than HIGHRC is considered to beunsuccessful for this purpose. Startup and termination messages will be issued.OPMSGWhether to issue messages with a severity of O to Operator Console –• Y – Yes• N – No (default)PGMPIFProgram to use to call TWS PIF (default EQQYCOM). This option may be used tomanage calls to different versions of TWS from the same LPAR by providingspecifically named versions of EQQYCOM for each version.PGMSTORProgram to use for storage allocation (default EQQSTOR).PGMWAITProgram to use to wait for contention retry (default EQQRETWM).Copyright IBM 2008 Page 72

POSTPROCOnce all initial command statements on the external data queue and in the INPUTsource (usually SYSIN), have been processed, SOE will normally terminate.If you dynamically generate more command statements into the External Data Queueduring execution, for example Batch Loader, this option can be used to make SOEprocess those extra statements.• Y – Yes, process external data queue until it is empty.• N – No, ignore any new entries on the external data queue (default).Note that if during the processing of the additional commands in the external dataqueue, any more are generated, these will also be processed unless you reset thePOSTPROC option. This could lead to a looping condition.RECONNECTDetermines whether to reattempt a INIT request if it fails with return code 8. Thisallows an SOE program to wait until a subsystem is available, using the OPTIONSCONTENTION retry characteristics if repeat and delay.• Y – Re attempt a failed INIT request in line with OPTIONS CONTENTIONsettings.• N – Do not attempt to retry a failed INIT request (default).Note: This option will only reattempt connection failure of an INIT statement. Ifcommunication fails with any other PIF request SOE will terminate with errors, as itwould be unable to determine the appropriate statement to safely reattempt restartfrom.REPORTSets the report width for output messages in SYSTSPRT (default 80).RETMSGRestricted option. Handled internally by SOE, not permitted with SOE commandstream.RETMSGIDRestricted option. Handled internally by SOE, not permitted with SOE commandstream.Copyright IBM 2008 Page 73

RUNSTATNot yet available in this release.What to do with run cycle status within generated batch loader• S- Suspend – Set the in and out of effect dates to your Low date e.g. 720101.• A – Activate – Put any run cycles that are out of effect at the low date backinto effect, setting your high date as the out of effect date e.g. 711231.• L – Leave – Do nothing with run cycle in and out of effect dates (default).SENDDATAWhether to send TWS data information to files specified on the OUTPUT DATAkeyword (see OUTPUT – Define output record).• Y – Yes, write data output (default)• N – No, do not write data outputNote: No output will be written if no output destinations have been specified.SENDLOADERWhether to send Batch Loader information to files specified on the OUTPUT LOADERkeyword (see OUTPUT – Define output record).• Y – Yes, write data output (default)• N – No, do not write data outputNote: No output will be written if no output destinations have been specified.SELECTWhether to automatically generate SELECT statements for any items that are LISTed.• Y – Yes, automatically generate SELECT statements.• N – No, do not generate SELECT statements (default).Copyright IBM 2008 Page 74

SEVERITYList of message severities to display. Certain message severities within SOE can besuppressed, so that they are not listed in the output. These severities are – A –Advisory, O – Operator, W – Warning and E – Error. This keyword instructs SOEwhich of these severities to dispay (default AOWE).Note that if you suppress W or E then any return codes set by them will also beignored.SILENTSets a special message level of -1 from the start of SOE that prevents all messagesexcept Fatal and Critical from being issued. This option is intended to allow SOE tobe called from with REXX programs that form part of ISPF dialogs without disruptingthe panel flow unnecessarily.Note: This is an immediate option and only valid when specified as an argument toSOE.SPEIndicate whether support for certain Small Product Enhancements (SPEs) should beconsidered. Each SPE is listed in the format spename=Y or spename=N.e.g. SPE(WLM=Y,SA=N).The presence of an SPE name alone is the same as coding =Y.e.g. SPE(WLM,SA=N).See Small Product Enhancements for lists of valid SPEs.SHOWDFLTWhether to create batch loader keywords for fields with default values• Y – Yes, output fields with default values (default)• N – No, don’t output fields with default valuesSTOPRCReturn code to cause processing to stop. By default SOE will stop processing when itencounters a return code of 12. You can cause subsequent command statements to beprevented from processing by specifying STOPRC(4) or STOPRC(8). You also resetthis code to 12 by STOPRC(12) (default).Note: This does not impact any return codes set by the LISTSTAT command, but if theSTOPRC limit has been breached by another command after a LISTSTAT command, theLISTSTAT exit code will not be set.Copyright IBM 2008 Page 75

STRIPWhether to strip blanks and leading zeroes from DATA and LOADER output –• Y – Strip blanks and leading zeroes.• N – Return data as extracted from TWS (default)e.g.OPTIONS STRIP(N) produces – ADID(MYAPPL )OPTIONS STRIP(Y) produces – ADID(MYAPPL)SUBSYSSOE can read subsystem specific OPTIONS statements after it has read the defaultoptions from the OPTIONS input source.Use the SUBSYS keyword to specify a DD statement to read the subsystem specificoptions from (default ).Note that this keyword is only effective on OPTIONS statements contained within theOPTIONS input source (see Command language)SUFFIXHow to handle the SUFFIX Batch Loader keyword• DISABLE – The SUFFIX keyword has no effect.• FAIL – If adding the SUFFIX to the name of the object exceeds the allowedlength, the process will fail (default)• IGNORE - If adding the SUFFIX to the name of the object exceeds theallowed length, the SUFFIX is ignored.• OVERLAY - If adding the SUFFIX to the name of the object exceeds theallowed length, the SUFFIX is overlayed over the rightmost portion of thefield.• TRUNCATE - If adding the SUFFIX to the name of the object exceeds theallowed length, the suffix is added to the end of the field and truncated to fitthe field width.Copyright IBM 2008 Page 76

SUPMSGSUPMSG lets you prevent a message from being written to the message log. You canprevent more than one message from being written to message log by issuing multipleOPTIONS requests with the SUPMSG argument specified.The argument to SUPMSG is formed by MSG followed by the message identifier. Toobtain the message identifier, remove the Tivoli Workload Scheduler for z/OS prefix(EQQ) from the beginning of the message and the severity indicator from the end ofthe message.e.g. to prevent message EQQW002E from being written to the message log, specifyan argument value of MSGW002.Warning: If SUPMSG is used to suppress SOE messages prefixed with EQQB thenthis will also prevent the resulting return code for the message being set.e.g. OPTIONS SUPMSG(MSGB103) will prevent SOE from issuing RC=4 if you specifyan output file in an OUTPUT statement that is not allocated and then attempt to write toit.SYSIDSYSID lets you set the field with which to look up LPAR specific values in lookuptables such as OPTIONS TRACKERS.The valid values are –• SYSNAME – The name of the system as specified in the SYSNAMEstatement in SYS1.PARMLIB.• SMFID – The System Management Facility Identifier• JESNODE – The JES Node nameCopyright IBM 2008 Page 77

TIMEWhen using the = symbol to represent a DATE or TIME within SOE it will by defaultuse the date and time that SOE started instead of the = sign. SOE maintains a staticinternal time to allow you to generate multiple statements with a “current time” that isconsistent across all statements, regardless of whether the time changes duringexecution.OPTIONS TIME allows you to set an explicit current TIME to use instead of = or anyother function that requires the current time within SOE.The format of the time must be hhmm.e.g.OPTIONS DATE(070124) TIME(1600)INSERT CPOC ADID(MYAPPL1) IA(=)INSERT CPOC ADID(MYAPPL2) IA(=)INSERT CPOC ADID(MYAPPL3) IA(=)INSERT CPOC ADID(MYAPPL4) IA(=)INSERT CPOC ADID(MYAPPL5) IA(=)INSERT CPOC ADID(MYAPPL6) IA(=)Will result in all 6 occurrences having an IA of 0701241600You can reset the internal SOE time to the current time by using –OPTIONS TIME(RESET).TRACEThe TRACE keyword will cause SOE to list detailed TWS Program Interfaceinformation to help you debug any difficulties you may be having. The availablelevels are –0. No tracing (default).1. Lists PIF commands as they are issued2. Lists segments as they are encountered3. List control structures and full DATA_AREA listing for SELECT statementsAll TRACE messages are easily identifiable by >> at the beginning of the message text.Copyright IBM 2008 Page 78

TRACKERSThe TRACKERS keyword allows you define a lookup table to allow the TWS TSOcommands to know which tracker subsystem to send events to for a combination ofController and JES Node.+------

VERSRWSNThe special resource description, SR, has fields representing workstations, the fullworkstation names or generic names; field SRDWSNAME of segment SRDWS fordefault connected workstations, field SRIWSNAME of segment SRIWS forworkstations connected to an interval. VERSRWSN controls the verification of thesefields when a new special resource is created or an existing one is replaced.• F - The workstation fields are verified against the workstation description file.Each workstation field in the resource description must match at least one ofthe workstation descriptions.• Y Same as for F except that the workstation value is accepted if the resourcedescription already has this workstation name. It could be an update withoutany change to the workstation names.• N - No check is made to verify that the workstation description exists (default).4.13.1 OPTIONS keyword abbreviationAs OPTIONS can be specified as arguments to EQQYXTOP, the keywords can beabbreviated to their shortest unique form to keep the options string short for use inJCL.e.g. BLANKUSE(Y) can be abbreviated to B(Y), VALFROM(A) can be abbreviated toVA(A).The OPTIONS statement is the ONLY SOE statement that supports such abbreviation.For performance reasons, keywords for all other commands must be specified in full.Copyright IBM 2008 Page 80

4.14 OUTPUT – Define output recordOUTPUT [KEYS(field1,field2,…)][FIELDS(field3,field4,…)][LABEL(YES|NO|NOFIELD|NOSEGMENT)][DATA(*|=|)][LOADER(*|=|)]The KEYS keyword specifies a list of key fields to be output for the record, the FIELDSkeyword specifies a list of non-key fields for the record. SOE draws no distinctionbetween fields specified in KEYS or LIST when creating the output record, thedistinction in only made if you are going to load the output file into ISPF usingEQQILSON.Segment names can be defined in the following manner –[=|*]Where –• The Segment name is the name of the TWS segment for which you want todefine output (required).• The Alias is an alternate name to use as the record label in the output(optional).• * is a special case of alias that suppresses the segment label in the output(optional).Fields can be defined in the following manner –[+|-][.][=|*|]Where –• + or – is used to indicate that this field is to be used as the sort sequence if therecord is to be loaded into ISPF using EQQILSON. If + or – is specified foruse with EQQYXTOP it will have no impact on the output, so the sameFILESPEC member can be used by EQQYXTOP and EQQILSON to ensurethe data is written from TWS in the same way it will be loaded into ISPF(optional).• TWS segment name is optional, it is only needed if you want to reference afield from a parent segment. You should only reference segments that areparents to the current segment, values from other segments may not beavailable (optional).• The TWS field name should be the name as documented in the IBM TivoliWorkload Scheduler for z/OS Programming Interfaces (SH32-1266-03)Appendix A (required)• The alias is an alternate field label to use in the output record (optional).• * is a special case of alias that suppresses the field label in the output(optional).• If a numeric length is specified instead of an alias this suppresses the fieldlabel and generates a fixed width field.For valid segment names see Appendix A.2: OUTPUT definition reference.Copyright IBM 2008 Page 81

The LABEL keyword determines what happens with field and segment labels –• YES – Labels will appear at Field and Segment level (unless * is used).• NO – No labels will appear.• NOFIELD – No field labels will appear, but the segment will be labeled.• NOSEGMENT – No segment label will appear, but the fields will be labeled.The DATA keyword specifies the Output Destination for Data records generated forthis segment. See Specifying Output Destinations. If no DATA Output Destination isspecified for this segment and OPTIONS DATA is not specified then no Data recordswill be written for this segment. If OPTIONS DATA is specified, the DATA keyword ofOUTPUT is ignored and all Data Records are sent to the destination specified in DATA.The LOADER keyword specifies the Output Destination for Batch Loader generated forthis segment. See Specifying Output Destinations. If no LOADER Output Destinationis specified for this segment and OPTIONS LOADER is not specified then no BatchLoader statement will be written for this segment. If OPTIONS LOADER is specified,the LOADER keyword of OUTPUT is ignored and all Batch Loader is sent to thedestination specified in LOADER.Note: You can have multiple OUTPUT statements for the same segment, only thekeywords specified will have any effect. If a keyword is NOT specified in an OUTPUTstatement, the values of the keyword from a previous OUTPUT statement for the samesegment will still apply. So you can specify fields and output destination in onestatement and then divert subsequent output to an alternate destination with a laterstatement without having to respecify all the fields.OUTPUT ADCOM FIELDS(ADID,ADDESC) DATA(OUTBL)OUTPUT ADCOM DATA(MYOUT)Example of multiple OUTPUT statements for the same segmentIn this example the ADCOM file will contain fields ADID and ADDESC and be sentto MYOUT. This technique allows you to have standard file definitions and overridethe output destination without re-specifying all the fields.4.14.1 Specifying Output DestinationsOutput Destinations tell SOE where to send output records. The destinations can beeither a DD statement, or *.An output destination of * will cause the output to be written to the external dataqueue.An output destination of = will cause the output to be written to the same destinationas its parent record.Many different segments can be written to the same output destination.Copyright IBM 2008 Page 82

If a DD statement is named, and this DD statement is NOT allocated, then the firstcommand to need the DD statement will issue a warning message (setting return code4), and the output destination will be suppressed.4.14.2 Additional fieldsAs well as the fields specific for each segment there are some additional fieldsavailable for each OUTPUT segment –• KEY – The fully qualified key of the segment• TYPE – The type of segment e.g. ADOP• PARENT_KEY – The fully qualified key of the parent segment• PARENT_TYPE – The type of the parent segment e.g. ADCOM• TAG – The data passed into the LIST or SELECT statement in the TAG keyword.This allows output from multiple LIST or SELECT commands to be correlatedback to the originating command by tagging each output record.One single level of a key is formed from the segment type followed by a hex 00 andthen each key field separated by hex 00. So a single level of a key for an Applicationcalled MYAPPL with a status of Active that is valid to 31 st December 2071 wouldhave a single level key of –ADCOM 00x MYAPPL 00x A 00x 711231A fully qualified key is a sequence of single keys separated by hex 01, to uniquelyidentify a segment within an object within the database. So operation 010 within thepreviously mentioned MYAPPL would be –ADCOM 00x MYAPPL 00x A 00x 711231 01x ADOP 00x 0104.15 REPLACE – PIF requestThe REPLACE request is performed by SOE using the Batch Loader functionality tobuild records before writing them to the database.Since the REPLACE request needs a fully formed record to be built in storage it doesnot have a direct command line equivalent in SOE.4.16 RESET – PIF requestRESET [MCPBLK]The RESET request deletes the current Modify Current Plan (MCP) block. Thiseffectively cancels a series of MODIFY current plan requests that have been collected inan MCP block, if it is performed before an EXECUTE request.4.16.1 Return Codes• 0 - The request was successful.• 8 - The request was unsuccessful. An error message has been written to themessage log data set.Copyright IBM 2008 Page 83

4.17 SELECT – Retrieve a record or common segmentSELECT The SELECT request retrieves a record by specifying field names and values inarguments, which identify the record you want to retrieve.The SELECT statement is used to retrieve an individual record from within the TWSdatabase or plans that match your specified criteria. A SELECT request MUST haveenough arguments to identify only one single record, if the arguments could apply tomore than one record the SELECT will fail RC=8 with the message -EQQY708E A SELECT REQUEST WITH MORE THAN ONE RECORD SELECTED,RESOURCE IS ADSELECT statements can be automatically generated from LIST requests by using -OPTIONS SELECT(Y)DELETE statements can be automatically generated from records processed by SELECTrequests by using -OPTIONS DELETE(Y) or OPTIONS DELETE(D)LIST statements can be automatically generated for other objects referred to by theobject retrieved by the SELECT statement, or objects that may refer to it by using –OPTIONS EXPAND(Y)When you retrieve a record using SELECT, you can get the complete record rather thanjust the common segment that is available from a LIST request, e.g. SELECT AD willretrieve the entire AD record, whereas SELECT ADCOM will retrieve only the commonsegment.For records that have the ability to retrieve multiple or single segments the followingdocumentation will use the convention Record/Common in the sub headingse.g. SELECT AD/ADCOM – Application DefinitionNotes:1. The SELECT JS and SELECT JSCOM requests try to retrieve JCL fromthe JCL repository. If no JCL is found, it is retrieved from the JCLlibrary or through the job-library-read exit, EQQUX002. The full keyis required, that is, the application ID, the input arrival time, and theoperation number. You might need to precede the SELECT JS requestby a LIST CPOPCOM request to get the key values.2. LIST JSCOM requests try to retrieve JCL only from the JCL repository.3. SELECT CPOPSRU can be issued for list elements only, from a listcreated by LIST CPOPSRU.Copyright IBM 2008 Page 84

4. The values of PIF arguments as dates depend on the PIF base year,which is defined by the PIFCWB keyword on the INTFOPTSstatement, or the CWBASE keyword of the INIT statement. The valueof the VALTO argument for default high date depends on the PIFHDkeyword of the INTFOPTS statement or the HIGHDATE keyword ofthe INIT statement.5. CPST (current plan status) is only one record; therefore, selectarguments are not required.4.17.1 Return Codes• 0 - The request was successful.• 4 - The request was unsuccessful. No records meet the criteriaspecified by the arguments.• 6 - You are not authorized to read the record. You specified a uniquekey in the SELECT request; the record exists, but you do not haveauthority to read it.• 8 - The request was unsuccessful. An error message has been writtento the message log data set. This can occur if more than one record inthe database satisfies the field values specified by your arguments.For example, you want to select an application description recordwith the ID APPL1, and there are two such application descriptionsin the database with different validity dates. Your arguments mustspecify both the application ID and the valid-from date to uniquelyidentify the record.4.17.2 TAG ArgumentThe TAG argument can be used on a SELECT command for any resource to create anadditional output field called TAG which will be available in any segment generatedby the command. This allows for the output from multiple SELECT commands to becorrelated back to the originating command.e.g.OUTPUT ADCOM FIELDS(TAG,ADID,ADFROM,ADSTAT)SELECT ADCOM ADID(ABC123) VALID(=) TAG(TODAY)OPTIONS DATE(+1)SELECT ADCOM ADID(ABC123) VALID(=) TAG(TOMORROW)In this example, the returned records will be marked with TODAY and TOMORROWin the TAG field depending on which LIST statement they came from.Note: Any SELECT statements generated from a LIST statement using OPTIONSSELECT(Y) will automatically be passed the same TAG argument.Copyright IBM 2008 Page 85

4.17.3 SELECT AD/ADCOM – Application DefinitionArg Name DescriptionADID Application description IDGROUP Authority group nameGROUPDEF Group definition IDMONITOR • Y=application with at least one operation monitored by anexternal product• N=application with no operation monitored by an externalproductOWNER Owner IDPRIORITY PrioritySTATUS Status:• P=Pending• A=ActiveTYPE Application type:• A=Application (default)• G=GroupVALFROM Valid-from date YYMMDDVALTO Valid-to date YYMMDDNote: Tivoli Workload Scheduler for z/OS assumes application type A if you do notspecify the AD argument name TYPE.4.17.4 SELECT AWSCL – All Workstations ClosedArg Name DescriptionDATE Date YYMMDD4.17.5 SELECT CL/CLCOM - CalendarArg Name DescriptionCALENDAR Calender IDNote: If the name of the default calendar is specified in the EQQYPARM INITstatement, SELECT CL without the CALENDAR argument will return the defaultcalendar. Otherwise CALENDAR is a required argument.Copyright IBM 2008 Page 86

4.17.6 SELECT CPOC – Current Plan OccurrenceArg Name DescriptionADID Application descriptionGROUP Authority groupGROUPDEF Group definition IDIAInput arrival date and time YYMMDDHHMMMCPADDED Manually added to the Current Plan, Y or NMONITOR • Y=occurrence with at least one operation monitored by anexternal product• N=occurrence with no operation monitored by an externalproductOWNER Owner IDPRIORITY PriorityRERUN Rerun requested, Y or NSTATUS Occurrence statusCopyright IBM 2008 Page 87

4.17.7 SELECT CPOP/CPOPCOM – Current Plan OperationArg Name DescriptionADID Application description IDCLNSTAT Data Set cleanup statusCLNTYPE Data Set cleanup typeERRCODE Error codeEXPJCL Expanded JCL optionEXTNAME Operation extended nameEXTSE Scheduling Environment nameGROUP Authority groupIAInput arrival date and time YYMMDDHHMMJOBCRT Critical job:• P=Critical path target• W=Eligible for WLM assistance• N=Not eligible for WLM assistanceJOBNAME Job nameJOBPOL Workload monitor late job policy:• ‘ ’ (blank) = default• L = Long duration• D = Deadline• S = Latest start time• C = Conditional modeMONITOR • Y=operation monitored by an external product• N=operation not monitored by an external productOPNO Operation numberOWNER Owner IDPRIORITY PrioritySTATUS Operation statusUSRSYS User sysout supportWAITNAME Waiting for Scheduling Environment, Y or NWLMSCLS WLM service classWSNAME Workstation nameWAITFORW Started on WAIT workstation, Y or N4.17.8 SELECT CPWS/CPWSCOM – Current Plan WorkstationArg Name DescriptionWSAUTO Automation workstation, Y or NWSNAME Workstation nameWSREP Workstation reporting attributeWSTWS Fault-tolerant workstation, Y or NWSTYPE Workstation typeWSWAIT WAIT Workstation, Y or NCopyright IBM 2008 Page 88

4.17.9 SELECT CSR/CSRCOM – Current Plan SpecialResourceArg Name DescriptionRESALCS Whether or not any operation is currently allocating the resourceshared, Y or NRESAVAIL Whether or not the resource is available, Y or NRESGROUP Resource group nameRESHIPER Whether or not it is a DLF control resource, Y or NRESNAME Resource nameRESWAIT Whether or not any operation is waiting for the resource4.17.10 SELECT ETT – Event TriggerArg Name DescriptionADID Associated application IDETTNAME Name of triggerETTTYPE Type of trigger:• J = Job• R = Special Resource4.17.11 SELECT JCLPREP – JCL PreparationArg Name DescriptionADID Application IDIAInput arrival date and time YYMMDDHHMMOPNO Operation number4.17.12 SELECT JCLPREPA – JCL Preparation simulationArg Name DescriptionADID Application IDIAInput arrival date and time YYMMDDHHMMOPNO Operation numberSIMTIME Simulated time CCYYMMDDHHMM. CCYY can have the values1984 to 2071SIMTYPE Simulation type“FULL” or “PARTIAL”4.17.13 SELECT JCLV/JCLVCOM – JCL Variable TableArg Name DescriptionJCLVTAB JCL Variable Table IDCopyright IBM 2008 Page 89

4.17.14 SELECT JL/JLCOM – Job LogArg Name DescriptionADID Application IDIAInput arrival date and time YYMMDDHHMMJOBNAME z/OS Job nameOPNO Operation numberWSNAME Workstation name4.17.15 SELECT JS/JSCOM – Current Plan JCLArg Name DescriptionADID Application IDIAInput arrival date and time YYMMDDHHMMJOBNAME z/OS Job nameOPNO Operation numberWSNAME Workstation name4.17.16 SELECT LTOC/LTOCCOM – Long Term PlanOccurrenceArg Name DescriptionADID Application IDGROUP Authority groupGROUPDEF Group definition IDIAD Input arrival date YYMMDDIATInput arrival time HHMMOWNER Owner ID4.17.17 SELECT OI/OICOM – Operator InstructionsArg Name DescriptionADID Application IDOPNO Operation numberVALTO Valid-to date and time YYMMDDHHMM4.17.18 SELECT PR/PRCOM - PeriodArg Name DescriptionPERIOD Period namePRTYPE Period typeCopyright IBM 2008 Page 90

4.17.19 SELECT SR/SRCOM – Special ResourceArg Name DescriptionRESGROUP Special resource groupRESHIPER DLF resource indicatorRESNAME Special resource name4.17.20 SELECT WS/WSCOM - WorkstationArg Name DescriptionWSAUTO Automation workstation, Y or NWSNAME Workstation nameWSREP Workstation reporting attributeWSTWS Fault-tolerant workstation, Y or NWSTYPE Workstation typeWSWAIT WAIT workstation, Y or NCopyright IBM 2008 Page 91

4.18 SETMAX – Manipulate the maximum return codeThe SETMAX command can be used to alter the maximum return code at any point inthe SOE command sequence.SETMAX POLICY(=,=,…,=,)The command will take the current maximum return code and look for a match on theleft hand side of each expression (in_rc), if it finds a match it will set the maximumreturn code to the right hand side of the expression (out_rc).If no match is found it, will set the return code to the specified “catch all” return code.If you omit to supply a catch all return code and there is no match, the return code willremain unchanged.For example –05/28 12.55.11 EQQB200I LIST CPOPCOM ADID(TWSCDAILYPLAN) OPNO(010)IA(0805281300)05/28 12.55.12 EQQB299I Statement completed - RC=405/28 12.55.13 EQQB200I SETMAX POLICY(0=4,4=0)05/28 12.55.13 EQQB122A Maximum return code 4 changed to 005/28 12.55.13 EQQB299I Statement completed - RC=0In this instance, the result of a LIST statement is reversed. If something is found,ordinarily you would get RC=0 and if not found you would get RC=4. The SETMAXstatement reverses that, so you can have a situation where the “good outcome” is forsomething to not be there (RC=0) and the “bad outcome” is if it is found (RC=4).Another use of this would be to consolidate unexpected return codes –SETMAX POLICY(0=0,4=4,8=8,12=12,16=16,20)SOE will only every return 0, 4, 8, 12 and 16, but the IBM TWS for z/OS ProgramInterface could return other higher return codes (e.g. RC=700 for an uninitialisedsession). In this example return codes 0, 4, 8, 12 and 16 remain unchanged, but if anyother return code is encountered it is set to 20.Note: SETMAX will not affect any return codes set by the LISTSTAT command.LISTSTAT has its own POLICY keyword to handle manipulation of the4.19 SETSEV – Set message severitySETSEV The SETSEV command changes the severity of an individual message in SOE to allowdifferent return code processing to take place.Enter the message ID you wish to change with the new severity.e.g. SETSEV EQQB114W will change the severity of EQQB114E to a new severity of W.Copyright IBM 2008 Page 92

4.20 SHOW – Show diagnostic informationSHOW OPTIONS|SYSINFOThis command shows diagnostic information to help you understand what informationSOE is operating with.You can show the following information -• OPTIONS - all the SOE options currently in effect. This will not show TWSPIF options.• SYSINFO – Shows information about the LPAR on which SOE is executing.4.21 SRSTAT – TWS TSO CommandSRSTAT ‘’ The SRSTAT statement can be used to set the status of a special resource in thecurrent plan.You can specify the SUBSYS explicitly with the SUBSYS keyword, otherwise SOEwill target the command at the same subsystem it is currently communicating with.See Using TWS TSO Commands within SOE for more information.4.22 TERM – Terminate TWS sessionTERMThe TERM request terminates the program interface session and performs thiscleanup processing:• FREEMAIN of storage• Close data sets v Detach subtasks• Termination of the Tivoli Workload Scheduler for z/OS session.SOE will automatically perform any necessary TERM requests before SOE terminates.If you want to communicate with more than one subsystem during an SOE programone session must be terminated before initializing a new one. You can do this byspecifying a TERM command before the INIT to another subsystem, but SOE willautomatically generate a TERM session if one is needed before performing a new INIT.Copyright IBM 2008 Page 93

4.23 WSSTAT – TWS TSO CommandWSSTAT The WSSTAT statement can be used to set the status of a workstation in the currentplan.See Using TWS TSO Commands within SOE for more information.4.24 Using TWS TSO Commands within SOETWS TSO commands can be specified almost exactly the same as the normal TWSTSO command of the same name. The only difference being that you do not have tospecify SUBSYS. If you omit SUBSYS from your command, then SOE will addSUBSYS for the subsystem you are currently communicating with. The SUBSYSkeyword cannot be abbreviated within SOE.Note: TWS TSO commands are asynchronous, they generate an event to perform theaction. Successful completion of the command only indicates successful generationof the event, it does not mean the action has completed.For more information about the relevant TSO command see IBM Tivoli WorkloadScheduler for z/OS Managing the Workload (SH32-1263-03).Copyright IBM 2008 Page 94

5 Batch loaderThe Batch Loader function of SOE uses a set of statements to define or modifyobjects within the TWS database. Batch loader can be freely intermingled with otherSOE commands BUT no other SOE commands must intervene within a set of BatchLoader statements for a single TWS database object.5.1 Modes of operationThe Batch Loader processing supports several modes of operation, that can bespecified either using the ACTION keyword of an OPTIONS statement or within theACTION keyword of individual Batch Loader statements. There are differentbehaviors available at the different levels5.1.1 OPTIONS ACTIONThe following values are valid for OPTIONS ACTION statement –• ADD - The entire content of the object must be specified within Batch Loaderstatements and cannot exist already within the database (default).• COPY – An object and segments within can be identified for updating usingkey fields (or SAVELIST), and then ONLY the fields that require changingneed to be specified. If new values for key fields are given a new object willbe created in the database, the original object will also remain in the databaseon completion. If an object matching the name given by new key fieldsalready exists the COPY will fail.• REPLACE - The entire content of the object must be specified within BatchLoader statements and but can exist already within the database and will bereplaced if an object already exists with the same name and type. If an objecthad been selected for replacing but given a new name for output, the originalobject will be deleted from the database on completion.• UPDATE – An object and segments within can be identified for updating usingkey fields (or SAVELIST), and then ONLY the fields that require changingneed to be specified. If the object does not already exist UPDATE will functionlike ADD. If new values for key fields are given a new object will be created inthe database, the original object will be deleted from the database oncompletion.Copyright IBM 2008 Page 95

5.1.2 Batch Loader ACTIONThe following values are valid for ACTION within batch loader statements -• ADD – The statement is defining an object or part of an object to be stored inthe database.• DELETE – The segment will be removed from the object. DELETE is not validfor primary batch loader statements (e.g. ADSTART, CLSTART), objectsthemselves must be deleted by the DELETE command, not ACTION(DELETE)within batch loader statements. DELETE is only valid in conjunction withOPTIONS ACTION(COPY) or OPTIONS ACTION(UPDATE).• SUBMIT – When an Application is created using ACTION(EXECUTE), instead ofbeing stored in the Database it is inserted into the Current Plan withoutupdating the database (only valid for ADSTART). Any occurrence created usingthis option will be Valid for all dates.• SETDEFAULT – If you specify SETDEFAULT, the remaining keyword values thatyou specify on the statement become default values for all statements of thesame type that follow. No database element is updated. Keywords that you donot specify are assigned their standard defaults. See SETDEFAULT differentbehavior for more information about how SETDEFAULT works within SOE.5.2 MaskingMasking can be used to update the content of existing fields using the % and *characters. The % character is used as a place holder for single character, the * isused to indicate any number of characters at the end of the mask. Using the *anywhere but the end of the mask will cause the character to be treated as a literalasterisk.e.g. A workstation NOVO with a description of “New workstation” could be modified-WSSTART WSNAME(NOVO) DESCR(“NEW *”) results in “NEW workstation”WSSTART WSNAME(NOVO) DESCR(“%%% CPU”) results in “New CPU”Note: By default the masking facility is turned off, to prevent accidental changes ifyou have % or * in any of your database fields. It is turned on using OPTIONSOUTMASK(Y).Copyright IBM 2008 Page 96

5.3 Batch Loader syntax enhancementsBy default, with a few exceptions, SOE supports the same format of batch loader thatEQQYLTOP supports. However it also has some syntax enhancements to make thebatch loader function easier to use.Some of these enhancements are automatically available and require no OPTIONS to beset to exploit them or stop them -• Quoting – SOE does not require values within keywords to be quoted, but itwill support quoting if used.• Only primary batch loader statements that, e.g. ADSTART, CLSTART, arerequired to appear at the beginning of a new line.Continuation rules have been amended to be able to use the full width of the inputdataset, whatever the width may be, but to process batch loader generated underEQQYLTOP syntax rules you can set OPTIONS EQQYLTOP(Y) to forceEQQYLTOP compliance.With EQQYLTOP compliance enabled, anything beyond column 72 is ignored, andany line that ends with a character in column 72 is continued directly from column 1of the following line. With EQQYLTOP compliance disabled (default) the end of oneline is joined to the next line with trailing and leading spaces ignored and just a singlespace between the joined lines. This is because SOE has no single keyword that mustbe broken over more than one line, so the column 72 continuation can be relaxed.SOE provides a new Small Product Enhancement, to alter the Batch Loader keywordsfor existing EQQYLTOP to either add new functionality, or make continuationsimpler. With OPTIONS SPE(LOAD) enabled, the following keyword changes areactivated -• ADRUN SEQ – Enables a specific run cycle to be identified for update, ratherthan having to respecify every ADRUN statement.• ADDEP SEQ – Enables a specific dependency to be identified for update,rather than having to respecify every ADDEP statement.• ADDEP PRINT – Allows the LTP Print option to be set.• ADSAI CT1-4 and CI – Allows COMMTEXT to be specified as four separatestrings (CT1 – CT4), exactly like it is on the panels, also allows the whole ofCOMPINFO to be specified on a single line by use of a shorter keyword (CI).This enhancement allows for a more readable syntax.The original syntax for ADSAI would break keyword values across multiple lines, thetext in this example is meaningless, used just to show the flow of full keywords.ADOPSAICOMMTEXT(‘AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD’)AUTFUNC(AFAFAFAF) SECELEM(SESESESE)COMPINFO(‘CICICICICICICICICICICICICICICICICICICICICICICICICICICICICICICICI’)The LOAD SPE would present the same values in this format, which is easier to readand follows the layout used for entering the information through the product dialogs.Copyright IBM 2008 Page 97

ADOPSAICT1(AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA)CT2(BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB)CT3(CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC)CT4(DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD)AUTFUNC(AFAFAFAF) SECELEM(SESESESE)CI(CICICICICICICICICICICICICICICICICICICICICICICICICICICICICICICICI)COMMTEXT and COMPINFO are still supported with the LOAD SPE enabled, butif continuation is needed then EQQYLTOP compliance must also be enabled.5.3.1 SETDEFAULT different behaviorThere is one element of EQQYLTOP syntax that is not directly compatible with SOE.That is the ability to SETDEFAULT for a segment without first providing a SETDEFAULTfor the record itself.e.g. In EQQYLTOP the following would set the default workstation to CPU1 and usethat default in the remaining statements –ADOP ACTION(SETDEFAULT) DURATION(10)ADSTART ADID(NEWAPPL)ADOP WSID(CPU1) OPNO(001) JOBN(JOB1)ADOP WSID(CPU1) OPNO(002) JOBN(JOB2)SOE however uses object based structures throughout the syntax, so to do the samething in SOE you would need to add an ADSTART statement ahead of the ADOPstatement to ensure the structures are coherent.ADSTART ACTION(SETDEFAULT)ADOP ACTION(SETDEFAULT) DURATION(10)ADSTART ADID(NEWAPPL)ADOP WSID(CPU1) OPNO(001) JOBN(JOB1)ADOP WSID(CPU1) OPNO(002) JOBN(JOB2)Note that all statements within a SETDEFAULT structure can only specify theSETDEFAULT ACTION, if ACTION is not specified for child batch loader statements thenSETDEFAULT is assumed.5.3.2 Keyword abbreviationUnder SOE Batch Loader keywords cannot be abbreviated, all keywords must bespecified in full.Copyright IBM 2008 Page 98

5.4 AD – Application definition record5.4.1 Record structureThe AD record is a multi segment record –ADCOM -+- Common segment|+= ADRUN =+= Run Cycle(s)| || +- ADRULE – Rule (1 per ADRUN)|+= ADOP =+= Operation(s)|+= ADDEP – Dependency(ies)|+= ADSR – Special resource(s)|+- ADEXT – Extended name (1 per ADOP)|+- ADSAI – System Automation (1 per ADOP)The relationships of the AD Record5.4.2 Automatic dependenciesBatch loader can create automatic dependencies within an application using theOPTIONS ADDEP keyword and the ADOP AUTOPRED/AUTOSUCC statements.Precedence: When deciding whether an automatic dependency when ALL is notspecified the following dependencies are assessed in this order –• ADOP and ADDEP statements created explicitly by the user• AUTOSUCC keywords• AUTOPRED keywords• OPTIONS LAST• OPTIONS FIRSTNote: Automatic dependencies can ONLY addressed to specific operations by theoperation number, not by using Jobname or Workstation name. When consideringwhether an operation already has a predecessor or successor SOE only acknowledgesthem from a statement that uses the operation number. It is therefore recommendedthat any manual dependencies made in conjunction with automatic dependenciesshould be performed using PREOPNO to ensure the desired result is achieved. It shouldalso be noted that when using OPTIONS UPDATE or OPTIONS COPY that existingdependencies not specified in the control statements are not considered whengenerating automatic dependencies.Copyright IBM 2008 Page 99

5.4.3 Submitting Batch Loader direct to the Current PlanWithin SOE it is possible to use Batch Loader statements to create an occurrencedirectly in the Current Plan without creating the application in the database. This isdone by using ACTION(SUBMIT) on the ADSTART statement.If OPTIONS ACTION(ADD) or OPTIONS ACTION(REPLACE) is used only the statementsin Batch Loader will be used to build the occurrence in the plan. If OPTIONSACTION(COPY) or OPTIONS ACTION(UPDATE) is used any existing application withthe same name in the database will be used as a model with the Batch Loaderstatements making amendments to the version being added to the Current Plan, thedatabase remains unchanged.The ADSTART and subsequent segments will perform the equivalent of an INSERTCPOC, so the Batch Loader must be followed by an EXECUTE MCPBLK to commit theoccurrence to the plan. Unless you have specified OPTIONS EXECUTE(MANUAL) thiswill happen automatically before SOE terminates your session with TWS.It is possible to follow the Batch Loader statements with MODIFY or INSERT statementsto amend the newly created occurrence before it is committed to the current plan withan EXECUTE statement. This makes it possible to INSERT predecessors or successorsbetween the occurrence being created and specific occurrences already in the plan.e.g.OPTIONS ADDEP(AUTO)ADSTART ACTION(SETDEFAULT)ADOP DURATION(1)ADSTART ACTION(SUBMIT) ADID(DYNAMAPPL) DESCR('DEMONSTRATE SUBMIT')OWNER(TWS) ODESCR('TWS INFRASTRUCTURE') PRIORITY(5)ADOP WSID(CPU1) OPNO(1) JOBN(JOB1) DESCR('FIRST JOB')ADOP WSID(CPU1) OPNO(10) JOBN(JOB2) DESCR('SECOND JOB')ADOP WSID(CPU1) OPNO(20) JOBN(JOB3) DESCR('THIRD JOB')ADOP WSID(CPU1) OPNO(30) JOBN(JOB4) DESCR('FOURTH JOB')ADOP WSID(CPU1) OPNO(255) JOBN(JOB5) DESCR('LAST JOB')MODIFY CPOP OPNO(1)INSERT CPPRE PREADID(PLANNEDAPPL) PREIA(0803081200) PREOPNO(030)EXECUTE MCPBLKNote: The entire object must be specified in Batch Loader before any INSERT orMODIFY statements can be used to alter it. Batch Loader statements (e.g. ADSTARTand ADOP) cannot be interleaved with Current Plan commands (e.g. MODIFY andINSERT).5.4.4 Standard Batch Loader statementsRefer to the Managing the Workload Manual for the complete syntax of the standardbatch loader statementsCopyright IBM 2008 Page 100

5.5 ETT – Event Trigger Record5.5.1 Record StructureThe ETT record is a single segment structure.5.5.2 ETTSTART statementThe ETTSTART statement defines an entire Event Trigger Record. A statementbegins with ETTSTART and can be followed by the following additional arguments.Argument Reqd PurposeACTION See Batch Loader ACTIONETTNAME Y Specifis the name of a job or a special resource, up to 44characters.You can also use the global search characters (* and %) tospecify a generic name.ETTTYPE Y Specifies the type of event that you want to cause a dynamicupdate of the Current Plan. Required.• J - A job reader event is the triggering event.• R - A special resource availability event is the triggeringevent.ADID Y Specifies the name of an application defined in the applicationdescription (AD) database that you want adding to the CurrentPlan when the event occurs.ASAvailability status switch indicator. Only valid withETTTYPE(R). Indicates if ETT should add an occurrence only ifthere is a true availability status switch for a special resourcefrom status Available=N to Available=Y, or if ETT should addan occurrence each time the availability status is set toAvailable=Y (regardless of the previous status of the specialresource).DRFor ETTTYPE(J) this field must have the value N or blank.• Y - ETT adds an occurrence only when there is a trueavailability status switch from status Available=N toAvailable=Y.• N - ETT adds an occurrence each time the availabilitystatus is set to available=yes.Specifies the dependency resolution, which determines ifexternal dependencies should be added when occurrences areadded to the Current Plan.• Y - External dependencies should be added.• N - External dependencies should NOT be added.• P - Add only predecessor dependencies.• S - Add only successor dependencies.Copyright IBM 2008 Page 101

Argument Reqd PurposeJRSpecifies job-name replace, which is only valid withETTTYPE(J). This determines if the job name of the firstoperation in the associated application should be replaced withthe triggering job.• Y - The name of the first operation is replaced by the jobname of the triggering job.• N - The application is added unchanged.Copyright IBM 2008 Page 102

6 Writing user Segment Processing ExitsSOE has an exit point that gives access to each data segment after the fields have beenextracted and formed into the output record, but before it is written to the outputdestination or any batch loader is written.The exit point allows you to write Segment Processing Exits (SPEX) to examine, oralter the content of individual fields, remove fields, alter the output destination andwhether or not the record is written, both for data and batch loader output.The exit point EQQYXU00 is designed as a switch point, the OPTIONS EXITstatement will name the exit to be used and EQQYXU00 will call the relevant userwritten Segment Processing Exit.Warning: A segment processing exit is executed for each segment processed. Whenprocessing very large amounts of data ensure that you are only using OUTPUTstatements for segments you really need, and consider whether processing could beperformed more effectively by post processing the output files.Copyright IBM 2008 Page 103

6.1 Building the exit switch pointTake a copy of EQQYXU00 into a higher library in the REXX concatenation. Thebeginning and end of EQQYXU00 should not be changed, but the SELECT constructin the middle is where you can specify your own Segment Processing Exit names andthe REXX modules they should call./* REXX *//*====================================================================+| MODULE : EQQUXU00 || PURPOSE : USER EXIT SWITCH MODULE || || HISTORY============================================================|| |+====================================================================*//*====================================================================+| Decode input record (NOT FOR USER UPDATE) |+====================================================================*/PARSE ARG x.CALLPARSE ARG 1 x.FIELDSEP 2 x.LABELSEP 3 .@ = x.FIELDSEPPARSE VAR x.Call 3 x.RC (@) ,x.EXIT (@) x.ARGUMENT (@) x.EXITUSE (@) ,x.SENDDATA (@) x.DATA (@) ,x.SENDLOAD (@) x.LOADER (@) ,x.SEGID (@) x.SEGKEY (@) x.SEGNUM (@) ,x.DATAADDR (@) x.SEGADDR (@) x.SEGLEN (@) ,x.RECORD/*====================================================================+| Decide what exit to use (USER UPDATE ALLOWED HERE) |+====================================================================*/SELECTWHEN x.EXIT = "DATA_LOAD" THENx.RETURN = x.CALLWHEN x.EXIT = "EXIT_NULL" THENx.RETURN = EXITNULL(x.CALL)OTHERWISEDOx.RETURN = "NOT_FOUND"ENDEND/*====================================================================+| Return the result (NOT FOR USER UPDATE) |+====================================================================*/RETURN x.RETURNThe variable x.EXIT contains the name of the Segment Processing Exit beingrequested. The name can be any valid string, it does not have to be the name of theREXX module it is calling as the SELECT construct can translate the user friendlyname to the exit module name.The variable x.CALL contains the data block to be passed to the exit for processing,the variable x.RETURN should be set with the results of the exit.So if you have an exit name called LIFE_CYCLE and you want it to call a membercalled LIFECYCL then code the following line as the action for the WHEN clause –x.EXIT = LIFECYCL(x.CALL)Copyright IBM 2008 Page 104

It is technically possible to use INTERPRET to allow the exit module names to bepassed directly through the agent.INTERPRET “x.EXIT = “||x.EXIT||”(x.CALL)”Though this lowers maintenance, as new modules become instantly useable as exits, itdoes stop the possibility of using the REXX compiler to increase performance of SOE,if you have the compiler available. You will also have to add sophisticated errortrapping as syntax errors could be introduced into the REXX code by allowingarguments to become executable.6.2 Writing an Segment Processing Exit REXX ModuleA SPEX REXX module follows a model format, which can be seen in moduleEXITNULL./* REXX *//*====================================================================+| MODULE : EXITNULL || PURPOSE : NULL USER EXIT TO USE AS MODEL || || HISTORY============================================================|| |+====================================================================*//*====================================================================+| Decode record for manipulation |+====================================================================*/CALL DECODE ARG(1)/*====================================================================+| User processing |+====================================================================*/SAY "@@" x.SEGID x.SEGKEY x.DATAADDR x.SEGADDR x.SEGLEN x.SEGNUMSAY ">>" STORAGE(x.DATAADDR,8)SAY "

@ = x.FIELDSEPx.CALL = x.FIELDSEP||x.LABELSEP||x.RC||@||,x.EXIT||@||x.ARGUMENT||@||x.EXITUSE||@||,x.SENDDATA||@||x.DATA||@||,x.SENDLOAD||@||x.LOADER||@||,x.SEGID||@||x.SEGKEY||@||x.SEGNUM||@||,x.DATAADDR||@||x.SEGADDR||@||x.SEGLEN||@||,x.RECORDRETURNA SOE Exit module should always begin with CALL DECODE ARG(1) and end withCALL REBUILD followed by RETURN x.CALL. Then the supplied DECODE and REBUILDprocedures must be included in your REXX code.The DECODE procedure will take the argument passed to the exit and create an exitstem containing the following variables -Variable Modifiable Purposex.ARGUMENT Y The argument to be passed to the exit from OPTIONSARGUMENTx.CALLAll of the data passed to the exit when it was called.x.DATAADDRThe Address of the Data Area returned byEQQYCOMx.DATA Y The output destination for any data outputx.EXIT Y The name of the exit as set by OPTIONS EXITx.EXITUSE Y What to do with the returned data record as set byOPTIONS EXITUSEx.FIELDSEP Y The field separator character as set by OPTIONSFIELDSEPx.LABELSEP Y The label separator character as set by OPTIONSLABELSEPx.LOADER Y The output destination for any batch loader outputx.RECORD Y The segment record in ILSON formatx.SEGADDRx.SEGIDx.SEGKEYx.SEGLENx.SEGNUMThe address of the segment being processedThe segment type of the segment being processed.The key of the segment being processedThe length of the segment being processedThe sequence number of the segment beingprocessed within the recordx.SENDDATA Y Whether to output data as set by OPTIONS DATAx.SENDLOAD Y Whether to output batch loader as set by OPTIONSLOADERVariables marked as modifiable can be changed within the exit and have impact in theremainder of EQQYXTOP. Any OPTIONS values changed will effect any subsequentactions within EQQYXTOP.Note: OPTIONS ARGUMENT can be used to pass information into the exit from thecalling program by setting the x.ARGUMENT variable. The x.ARGUMENT variable canalso be used by the exit to communicate from one segment to the next.Copyright IBM 2008 Page 106

7 Writing your own SOEEXECsSOE is designed to be extendible by writing SOEEXECs. These SOEEXECprograms can call SOE to perform specific operational functions. SOE is deliveredwith an SOEEXEC library containing pre-built examples. An SOEEXEC is simply aREXX program that calls SOE, following a few simple rules.This section describes the techniques that can be used to write your own SOEEXECsand the considerations that must be made for use in Batch or Online.7.1 Passing ArgumentsThough you can pass arguments in any way you wish, there are guidelines you canfollow for writing you own SOEEXECs to enable you to use the provided SOE JCLand functions more easily.7.1.1 Passing the subsystemThe first word passed to your program should always be the TWS subsystem name,this can then be passed directly into SOE when you call it.If you are designing your SOEEXEC to be run from within the TWS dialogs then youcan take advantage of the information contained within TWS dialog variables usingthe supplied EQQYXSYS function.IF SYSVAR(SYSENV) = "FORE" THENPARSE VALUE EQQYXSYS() WITH argSUBSYS argLUThis will store the subsystem name in variable argSUBSYS and the server LUNamein argLU. If no server is used for the current dialog connection then argLU willcontain *.If an LU is used then you can use this information to create an explicit INIT statementat the head of the control cards you pass to SOE.IF argLU "*" THENQUEUE "INIT" argSUBSYS "LUNAME("||argLU||")"If your SOEEXEC is also to be executed from batch then you must ensure thatargSUBSYS can be passed as the first argument, or a placeholder when executedwithin TWS dialogs. In batch the LU can be specified via an TWS INIT statement onthe EQQYPARM DD statement.7.1.2 Passing functional argumentsWhatever function you are performing with your SOEEXEC, you will most likelyneed some information as to what elements within TWS to perform the action withe.g. Application Names, Input Arrival etc.You should ensure that this information is passed into your REXX program asarguments following the subsystem.Copyright IBM 2008 Page 107

If your program is designed to be called from within TWS as a Primary commandthen you can use the EQQYXQRY function to gain information about the context ofthe panel the command is being executed from.EQQYXQRY will return at least two words –1. PROCESS - The process being performed, which will be a PIF action, such asMODIFY or SELECT, or UNKNOWN if this panel is not really connected toan action or not supported by EQQYXQRY.2. OBJECT - The PIF resource for the record or segment being dealt with, suchas AD or CPOP.The remaining words returned will differ depending on the type of OBJECT beingretrieved. The details of the PROCESS, OBJECT and other fields returned can befound in EQQYXQRY Process and Object Reference in the Appendix.A suggested standard approach is to allow the final argument in your list be one that isoptional and not required for your function, this can then be used to pass diagnosticarguments into SOE should you need to for debugging.e.g.PARSE ARG argSUBSYS argADID argDIAGIF argDIAG = “” THEN argDIAG = “SILENT”QUEUE “LIST ADCOM ADID(“||argCPOPADI||”)”RC = EQQYXTOP(argSUBSYS argDIAG)When called normally nothing will be passed into argDIAG but you could call theroutine with extra diagnostics to aid problem resolution.Copyright IBM 2008 Page 108

8 Performance TuningSOE has many different ways to do things. Each method has different implicationsfor ease of use and performance, the balance of which may change depending on thevolume of records to which it is being directed.SOE is designed to give you access to TWS data as easily as possible, the defaultOPTIONS are focused around ease of use, not necessarily speed of execution, thoughfor small simple processes there will be no noticeable difference.This chapter will outline the areas of SOE that can have an impact on performanceand recommendations for running as efficiently as possible when you want to runlarge scale processes.8.1 Record processingRecord processing within SOE and SOEEXECs can account for a significant part ofthe processing time. There are considerations you can make within SOE to reduce theamount of record processing being performed. When processing a small number ofrecords these differences are not noticeable, but over thousands of records there couldbe noticeable savings in run time to be made.8.1.1 LIST/SELECT Common Segment vs RecordFor a record type that can have more than one segment it is possible to retrieve eitherthe whole record, or just the common segment. For large or complex records thedifference between retrieving the Common Segment over the Entire Record could benoticeable when retrieving thousands of records, so if all the information you need isin the Common Segment then ensure you use the Common Segment as the resourcewhen executing a SELECT command.If the SELECT statements are being generated as a result of a LIST statement usingOPTIONS SELECT(Y) and ONLY the Common Segment is needed then a LISTstatement may suffice to extract the data you need. Setting OPTIONS SELECT(N)(default) will not only result in smaller records being retrieved it will avoid extrarequests to TWS for each identified object.Note: If you need to produce Batch Loader output, this is ONLY produced as a resultof a SELECT command and needs the full record to be retrieved.Copyright IBM 2008 Page 109

8.1.2 OUTPUT and FILESPECThe OUTPUT statement determines which segments and which fields are to beextracted.When a record is retrieved from TWS using the SELECT statement the entire record isretrieved and the header is processed to identify each segment. The segment is thenprocessed only if there is a reference to it. Coding only OUTPUT statements for thesegments that you need will reduce processing.Record processing involves extracting every field in the segment, creating a dataoutput record for the segment, running a Segment Processing Exit (if requested) andgenerating Batch Loader. Some of this processing will be avoided if you only codeOUTPUT statements for the fields you require data from.The FILESPEC symbolic parameter in the JCL allows you to call predefined OUTPUTstatement members. The member FILEALL contains definitions of every field forevery segment. It is recommended this member only be used when you need toextract entire objects, for purposes such as Batch Loader generation.Copyright IBM 2008 Page 110

9 Translating output to ISPF tables9.1 ISPF Loader Streamed Object NotationISPF Loader Streamed Object Notation (ILSON) is a way of exporting data fromprograms in a form that is easily converted into ISPF table structure.A utility will be provided in a future release to create and load tables directly fromSOE output.Copyright IBM 2008 Page 111

10 Appendix A - Resource reference10.1 Alternate resource namesThe following alternate resource names can be used as alternatives to increase theclarity of the command syntax.ActionDELETEResourceADAlternatesADCOM APPLICATION APPL SCHEDULE SCHED JOBSTREAMDELETE CL CLCOM CAL CALENDARDELETE CPOC OCCURENCE OCCDELETE CPOP CPOPCOM OPERATION OPDELETE CPPRE PRED PREDECESSORDELETE ETT TRIGGERDELETE JCLV JCLVCOM TABLEDELETE JS JSCOM JCLDELETE OI OICOM INSTRUCTION TEXTDELETE PR PRCOM PERIODDELETE SR SRCOM RESOURCEDELETE WS WSCOM WORKSTATIONINSERT CPOC OCCURENCE OCCINSERT CPOP CPOPCOM OPERATION OPINSERT CPPRE PRED PREDECESSORLIST ADCOM AD APPLICATION APPL SCHEDULE SCHED JOBSTREAMLIST CLCOM CL CAL CALENDARLIST CPOC OCCURENCE OCCLIST CPOPCOM CPOP OPERATION OPLIST CPWSCOM CPWSLIST ETT TRIGGERLIST JCLVCOM JCLV TABLELIST JSCOM JS JCLLIST OICOM OI INSTRUCTION TEXTLIST PRCOM PR PERIODLIST SRCOM SR RESOURCELIST WSCOM WS WORKSTATIONMODIFY CPOC OCCURENCE OCCMODIFY CPOP OPERATION OPMODIFY IVL INTERVALSELECT AD APPLICATION APPL SCHEDULE SCHED JOBSTREAMSELECT CL CALENDAR CALSELECT CPOC OCCURENCE OCCSELECT CPOP OPERATION OPSELECT ETT TRIGGERSELECT JCLV TABLESELECT JS JCLSELECT OI INSTRUCTION TEXTSELECT PR PERIODSELECT SR RESOURCESELECT WS WORKSTATION10.2 OUTPUT definition referenceCopyright IBM 2008 Page 112

10.3 Additional fields10.3.1 Reserved fieldsAny areas of records marked as RESERVED in the Program Interface Record Formattables in Appendix A of the Programming Interface manual are also available to SOE.The field names for these fields are composed of RSVD and a 3 digit offset e.g.RSVD023 for ADCOM.These fields do not appear in the FILEALL member10.3.2 Composite fieldsSome fields are composed from smaller fieldse.g. ADOPWSINFO is composed from ADOPWSISET, ADOPWSTYPE,ADOPWSREP, and ADOPWSSUBT.Composite fields are listed in the FILEALL member, but are commented out.10.3.3 Raw and untranslated fieldsSome fields are not translated into their absolute form by SOE, and output inHexadecimal format, such as Last User Timestamps e.g. ADLUTS.These fields are listed in the FILEALL member, but are commented out.Copyright IBM 2008 Page 113

11 Appenix B - SOE Programming functions11.1 Function reference11.1.1 EQQYXFLD – Read/Write fields in ILSON records11.1.2 EQQYXQRY – Find current context in TWS dialogs11.1.3 EQQYXRAW – Access raw PIF data structures11.1.4 EQQYXSYS – Find subsystem information11.2 EQQYXQRY Process and Object referenceProcess Object FieldsSELECT CPOP CPOPADI CPOPIA CPOPNOMODIFY CPOP CPOPADI CPOPIA CPOPNOCopyright IBM 2008 Page 114

12 Appendix C - Messages and Codes12.1 Severities and Return CodesSOE messages can appear with a variety of severities, each with corresponding returncodes. Severities of A, O, W and E can be suppressed using OPTIONS SEVERITY.The OPTIONS MSGLEVEL feature can also be used to influence the amount of messagesissued.Value Code Explanation0 I Information messages that cannot be excluded by the SEVERITYoption0 A Advisory messages that can be excluded by the SEVERITY option0 O Advisory messages that may also be routed to the Operator Consoleby use of the OPMSG option. These can be excluded by theSEVERITY option.4 W Warning messages that can be excluded by the SEVERITY option8 E Error messages that can be excluded by the SEVERITY option12 F Fatal messages that cannot be excluded by the SEVERITY message16 C Critical initialization processing error – always in EnglishWith the exception of a few Critical messages, all message text is provided in anexternal file, so message text and severity can be customized to meet your site’sspecific requirements, though you will have to repeat this customization when youupgrade SOE.12.2 Message GroupingWithin the SOE message log (SYSTSPRT), messages are grouped by the command towhich they belong. A message group will always start with an EQQB200I messageand terminate with an EQQB299I message. The 200I listing the command and the299I indicating the return code.By default not all commands will appear on the SOE message log. Only commandsdirectly entered into SOE, and commands that have failed will appear. The behaviorcan be changed by use of OPTIONS MSGLEVEL.Many commands will generate a series of internal commands to perform the requiredprocess, for example Batch Loader statements may generate LIST, SELECT, INSERTand REPLACE command. Internal commands will be listed ahead of the command thatgenerated it, as commands are written to the message log only when they complete,since one of the deciding factors as to whether a message gets written or not iswhether it completed successfully or not.LIST commands generated as a result of OPTIONS EXPAND(YES) and SELECTcommands generated as a result of OPTIONS SELECT(YES) will appear after thecommand that generated them, as the success of the following LIST or SELECT doesnot reflect upon the success of the process that generated them.Copyright IBM 2008 Page 115

The format of a message line is –mm/mm hh.mm.dd ppppnnns textWhere –• mm/dd is the date in Month/Day format.• hh.mm.ss is the time in Hours:Minutes:Seconds format• pppp is the message prefix• nnn is the message number• s is the message severity• text is the message textMessages will automatically wrap to the width of the setting for OPTIONS REPORT(default 80) . Continuation lines will not have the date and time displayed and themessage ID will be prefixed with …07/08 14.34.20 EQQB200I OUTPUT ADDEP DATA(*) LABEL(NOFIELD) FIELDS(ADCOM.ADID...EQQB200I ADOP.ADOPNO ADDEPADID ADDEPOPNO)07/08 14.34.20 EQQB299I Statement completed - RC=007/08 14.34.20 EQQB200I LIST ADCOM TYPE(G) ADID(*) STATUS(A) VALID(=)07/08 14.34.21 EQQB299I Statement completed - RC=0sample continued messagesBatch Loader requests are listed slightly differently. The primary command (e.g.ADSTART, ETTSTART) will be listed on and EQQB200I message, but any sub segmentcommands will be listed on EQQB203I messages.07/08 15.05.41 EQQB200I ADSTART ADID(FRED) OWNER(FREDDY)...EQQB203I ADOP OPNO(1) WSID(DUMM) JOBN(START) DURATION(1)...EQQB203I DESCR('First operation')...EQQB203I ADOP OPNO(005) WSID(CPU1) JOBN(JOBA) DURATION(1)...EQQB203I FORM(DD0001)...EQQB203I ADDEP PREOPNO(1) PREJOBN(START) PREWSID(DUMM)...EQQB203I ADOP OPNO(010) WSID(CPU1) JOBN(JOBQ) DURATION(1)...EQQB203I FORM(DD0001)...EQQB203I ADDEP PREOPNO(1) PREJOBN(START) PREWSID(DUMM)...EQQB203I ADOP OPNO(015) WSID(DUMM) JOBN(JOBB) DURATION(1)...EQQB203I HIGHRC(4) FORM(DD0002)...EQQB203I ADDEP PREOPNO(005) PREJOBN(JOBA) PREWSID(CPU1)...EQQB203I ADOP OPNO(020) WSID(CPU1) JOBN(JOBC) DURATION(1)...EQQB203I FORM(DD0001)...EQQB203I ADDEP PREOPNO(005) PREJOBN(JOBA) PREWSID(CPU1)...EQQB203I ADDEP PREOPNO(010) PREJOBN(JOBQ) PREWSID(CPU1)...EQQB203I ADOP OPNO(025) WSID(CPU1) JOBN(JOBD) DURATION(1)...EQQB203I FORM(DD0001)...EQQB203I ADDEP PREOPNO(015) PREJOBN(JOBB) PREWSID(DUMM)...EQQB203I ADDEP PREOPNO(020) PREJOBN(JOBC) PREWSID(CPU1)...EQQB203I ADOP OPNO(255) WSID(DUMM) JOBN(END) DURATION(1)...EQQB203I DESCR('Last operation')...EQQB203I ADDEP PREOPNO(025) PREJOBN(JOBD) PREWSID(CPU1)07/08 15.05.43 EQQB112I Processing Application ADID(FRED) STATUS(A)...EQQB112I VALTO(711231)07/08 15.05.44 EQQB116I REPLACE for Application ADID(FRED) ADSTAT(A)...EQQB116I ADVALFROM(080708) ADTYPE(A) completed07/08 15.05.44 EQQB299I Statement completed - RC=0sample Batch Loader messagesCopyright IBM 2008 Page 116

12.3 MessagesEQQB001A Starting SOE version Explanation: SOE start up has occurred. The number is the version of theSOE code.System Action: SOE starts.User response: noneEQQB002A Initialising for TWS version Explanation: SOE has initialized for a particular version of IBM TWS for z/OS. The number is the version of the IBM TWS for z/OS software, contains alist of Small Product Enhancements considered to be in effect.System Action: Reference data is loaded in accordance with the IBM TWS for z/OSversion and applied Small Product EnhancementsUser response: noneEQQB003I System information Explanation: A SHOW SYSINFO command has been processed. The information willcontain the following for the LPAR on which SOE is executing –• SYSNAME – The name of the system as specified in the SYSNAMEstatement in SYS1.PARMLIB.• JESNODE – The JES Node name• SMFID – The System Management Facility Identifier• SYSPLEX – The name of the SYSPLEX• SYSID – The name of the field used to identify which subsystem to sendevents to (see OPTIONS SYSID)System Action: Information is displayed.User response: noneEQQB004I OPTIONS in effect Explanation: A SHOW OPTIONS command has been processed. The willshow the current settings of all documented SOE options that are in effect at the pointthe command was processed.System Action: Current option settings are displayed.User response: noneCopyright IBM 2008 Page 117

EQQB005A Segment is not handled by SOEExplanation: A segment has been encountered in the PIF header that is currently notdefined to SOE.System Action: SOE will skip the segment and continue processing from the nextsegment.User response: Ensure you are running with the latest release of SOE.Note: Whilst SOE is in Early Release status, this message is severity A, as it is likelythe current release of SOE will not handle every segment. Once SOE reachescomplete status this message will be raised to W.EQQB006A Exit has set return code Explanation: An SOE Segment Processing Exit has terminated with a non zero returncode.System Action: The return code is passed into the SOE processing and may impactthe final exit code of SOE.User response: Determine if this is expected. If necessary correct the exit and rerun.EQQB099A SOE complete - highest return code - () secExplanation: SOE termination message, including the following key information –• - The maximum return code, after considerations from SETMAX andLISTSTAT.• - The total elapsed time of the SOE session.• - The subset total elapsed time taken executing EQQYCOM.System Action: SOE terminates.User response: noneEQQB101F Unable to read Explanation: SOE has been unable to read a file, possibly due to the DD name notbeing allocated, or the input file never having been written to, or the record format notbeing appropriate to read with EXECIO.System Action: SOE terminatesUser response: Determine the problem with the file, correct it and rerunEQQB102A Input file not allocated - skippingExplanation: SOE has encountered an optional input file that has not been allocated.System Action: The file is not processed, SOE continues.User response: If the file should have been present, correct and rerun.Copyright IBM 2008 Page 118

EQQB103W Output file not allocated - skippingExplanation: SOE has encountered an optional output file that has not been allocated.System Action: No output is written to this file, SOE continues.User response: If the file should have been present, correct and rerun.EQQB104A Records written to = Explanation: As processing terminates SOE issues statistics for all output files.System Action: Statistics issued as file is closed.User response: noneEQQB105W Truncation occurred for file Explanation: A file has been written to with at least one record that is longer than therecord length.System Action: The file is written with any oversize records are truncated at therecord length.User response: Correct the record length and rerun.EQQB106E Failed writing to RC= (records=)Explanation: An attempt has been made to write to an output file that has failed forreasons other than truncation. Possibly space or authority. The return code if fromthe REXX EXECIO service.System Action: The file is not written successfully, it may contain partial data.User response: Determine the cause of the failure from return codes, additionalmessages and other additional information, such as file attributes. Correct and rerun.EQQB107A Number of files written = Explanation: As processing terminates SOE issues statistics for all output files.System Action: Number of output files is reported.User response: noneEQQB109E Item already exists so cannot be addedExplanation: A Batch Loader request using OPTIONS ACTION(ADD) for an object thatis already in the database has been attempted.System Action: The object is not added to the database.User response: Delete the object from the database or change the ACTION to REPLACEand rerun.Copyright IBM 2008 Page 119

EQQB110E No key information specifiedExplanation: A Batch Loader request has been specified that does not include anykey fields to identify the object to update.System Action: The database is not updated.User response: Amend the Batch Loader statements to include key fields or use aSAVELIST and rerun.EQQB111E SAVELIST contains records for instead of Explanation: A request to use a SAVELIST has been coded, but the list containsobjects of a different type to the use that is being applied to.System Action: No update takes place.User response: Correct the control statements to use an appropriate list and rerun.EQQB112I Processing new EQQB112I Processing Explanation: Batch Loader has selected a record to use as the input template for theupdate request. This is either a new empty record, or an existing record.System Action: The record is used for preparing the update.User response: noneEQQB113A OPTIONS may not have full effect for this streamExplanation: The named keyword is one that affects the way control statements areparsed. SOE will prepares an entire input stream of control statements to identifyvalid statements, consolidate continuation and remove comments before executingany of the statements. This means any subsequent statements in the same streammight not benefit from the changes made by this OPTIONS statement and parsingerrors, such as unrecognized commands or keywords, may be reported.System Action: The new parsing behavior takes effect from the next input stream.User response: Verify whether this is acceptable, and possibly move the OPTIONSstatement to an earlier input stream.Note: This warning is only issued for the input streams for standard input (SYSIN)and the REXX stack.EQQB114E not found to deleteExplanation: An attempt has been made to remove a non-existent segment from anexisting object using the ACTION(DELETE) keyword in Batch Loader.System Action: The object is not updated.User response: Correct the Batch Loader statements and rerun.Copyright IBM 2008 Page 120

EQQB115I deletedExplanation: A segment has been removed from an object the ACTION(DELETE)keyword in Batch Loader.System Action: The object is updated with the segment removed.User response: noneEQQB116I for completedExplanation: A Batch Loader request has completed successfully. This messageclarifies the action taken and identifies the object that has been used.The action can be INSERT, REPLACE or SUBMITSystem Action: Batch Loader process completes successfullyUser response: noneEQQB117W for ended with warningsExplanation: A Batch Loader request has completed but has produced additionalwarning messages. This message clarifies the action being attempted and identifiesthe object that has been used.The action can be INSERT, REPLACE or SUBMITSystem Action: Batch Loader process completes with warnings.User response: Review the warning messages, if necessary correct and rerun.EQQB118E for failedExplanation: A Batch Loader request has failed to complete. This message clarifiesthe action being attempted and identifies the object that has been used.The action can be INSERT, REPLACE or SUBMITSystem Action: Batch Loader process failed.User response: Review the warning messages, correct and rerun.EQQB119I SCAN complete no updates performedExplanation: Batch Loader statements have been processed using the statemenetOPTIONS ACTION(SCAN) to prevent execution.System Action: No updates are performed, any syntax errors in the statements arereported.User response: noneCopyright IBM 2008 Page 121

EQQB120W EXECUTE not performedExplanation: Statements to update the Current Plan have been processed but notEXECUTE or RESET request has been performed.System Action: No updates are made to the Current Plan.User response: Add an EXECUTE or RESET command to the control statements or useOPTIONS EXECUTE(AUTO).EQQB121E matches found for LISTSTATExplanation: More than one record was identified as matching the arguments to theLISTSTAT request. Only one record must be identified for LISTSTAT to work.System Action: LISTSTAT fails.User response: noneEQQB122A Maximum return code (1) changed to (2)Explanation: A SETMAX command has altered the maximum return code.System Action: The maximum return code is modified in line with the POLICY.User response: noneEQQB200I Explanation: This message is issued to echo the command being processed and starta block of messages relating to this command terminated by EQQB299I.System Action: A new message block is startedUser response: noneEQQB201F Unrecognized statement in Explanation: An invalid command has been coded in one of the SOE input streams.The input streams can be –• OPTIONS : Site option defaults• SUBSYS : Subsystem option defaults• -ARGS- : The SOE argument• FILESPEC : ILSON file specifications• -STACK- : The REXX stack• INPUT : The main input stream (SYSIN)System Action: SOE terminates.User response: Correct and rerun.Copyright IBM 2008 Page 122

202 I Command directed to Explanation: A TSO event command has been specified without using the SUBSYSkeyword in the statement itself. This message show what subsystem the event wasdirected to.System Action: The subsystem is determined using OPTIONS SYSID to determinewhat LPAR the job is running on and OPTIONS TRACKERS to look up the trackersubsystem.User response: noneEQQB203I Explanation: This message is continuation for message EQQB200I for multistatement Batch Loader constructs.System Action: Additional statements are output to the log.User response: noneEQQB204F Missing end quote for keyword Explanation: A parsing error has occurred.System Action: SOE terminates.User response: Correct quoting and rerun.EQQB205F Missing right parenthesis for keyword (1)Explanation: A parsing error has occurred.System Action: SOE terminates.User response: Correct parenthesis and rerun.EQQB206F Invalid value for keyword Explanation: A parsing error has occurred. An inappropriate value has been foundfor a keyword.System Action: SOE terminates.User response: Consult the documentation, correct and rerun.Note: The documentation may state that the value is valid for the keyword. SOEcould still reject this if the value is not valid for the particular version of TWS you arecommunicating with, or you have not enabled a particular SPE. Check messageEQQB002I to see what version of TWS SOE believes it is operating against.Copyright IBM 2008 Page 123

EQQB207F Invalid keyword Explanation: A parsing error has occurred. An inappropriate keyword has beencoded.System Action: SOE terminates.User response: Consult the documentation, correct and rerun.Note: The documentation may state that keyword is valid. SOE could still reject thisif the keyword is not valid for the particular version of TWS you are communicatingwith, or you have not enabled a particular SPE. Check message EQQB002I to seewhat version of TWS SOE believes it is operating against.EQQB208F Resource is not valid for Explanation: An invalid resource has been specified for a command.System Action: SOE terminates.User response: Consult the documentation, correct and rerun.EQQB209E Exit not found - OPTIONS EXIT resetExplanation: An exit has been specified using OPTIONS EXIT that is not declared inEQQYXU00.System Action: SOE issues an error message and continues without the exit.User response: Correct the OPTIONS statement or update EQQYXU00 to includethe new exit before rerunning.EQQB210E ADID required for INSERT with ALIASExplanation: An attempt has been made to INSERT an occurrence into the CurrentPlan using an alias, but no ADID has been specified to use as the template for theINSERT.System Action: An occurrence is not submitted.User response: Add an ADID keyword and rerun.EQQB211E Unable to find unique Application valid on Explanation: An attempt has been made to INSERT an occurrence into the CurrentPlan using an alias. The ADID specified does not have a Valid Active version for thedate it is due to run on.System Action: An occurrence is not submitted.User response: Correct and rerun.Copyright IBM 2008 Page 124

EQQB212E Unable to retrieve from databaseExplanation: An attempt to SELECT a record from the database has failed.System Action: The record is not retrieved.User response: Additional messages may indicate why the failure occurred. It maybe that the object does not exist in the database. If the SELECT was generated as aresult of a LIST statement it is possible that the object was deleted by another userbetween the LIST and SELECT.EQQB213F Call to has abended RC()Explanation: An attempt to call a load module internal to SOE has failed.System Action: SOE terminates.User response: Determine the reason for the failure and rerun. Possible causes couldbe• Module not found (S806), ensure the library containing the module is definedto SOE by STEPLIB or other means.• Insufficient region.• Version mismatch. The TWS module EQQYCOM can object to being runagainst versions of TWS other that the version it is written for, Ensure you arecalling the correct version of EQQYCOM for the subsystem you arecommunicating with.EQQB215A SPE () is not valid for TWS version – ignoredExplanation: An OPTIONS SPE statement was encountered that attempted toactivate an SPE for a version of TWS earlier than the version from which the SPE wasmade available.System Action: The SPE is not activated.User response: Ensure you have declared the correct SPE and/or version of TWS.EQQB216F is not allowed with Explanation: Two keywords have been encountered that cannot be specified together.System Action: SOE terminates.User response: Correct and rerun.EQQB217E COPY cannot replace existing recordsExplanation: An attempt has been made to copy an object over the top of an existingobject using ACTION(COPY).System Action: No update takes place.User response: Either delete the existing object or alter the NEW_ field specificationsto create an object that does not already exist.Copyright IBM 2008 Page 125

EQQB218E ADRULE must follow ADRUN TYPE R or EExplanation: An ADRULE statement has been encountered that does not follow andADRUN segment for types R or E.System Action: No update takes place.User response: Correct and rerun.EQQB219E Bad predecessor for Explanation: When both workstation and operation number are not specified togetherfor a dependency, SOE must look up the values using the information provided. Thismessage means not enough information was specified to uniquely identify apredecessor. Either the input had more than one possible match, or no match.System Action: No update takes place.User response: Either provide both workstation and operation number, or refine thestatements to ensure a unique operation is identified.EQQB220E and SUFFIX exceeds field length Explanation: The SUFFIX keyword has been used to generate a new name for anobject by combining the original name with a TWS supplied variable. In this case thecombination of the original name and the contents of the variable exceed the fieldlength for the object name and OPTIONS SUFFIX(FAIL) has been used.System Action: No update takes place.User response: Amend the input to use an alternate combination of name and variableor use a different value for OPTIONS SUFFIX.EQQB221F SUBSYS must be specified if OPTIONS TRACKERS + SYSID not setEQQB221F SUBSYS must be specified if OPTIONS TRACKERS not setEQQB221F SUBSYS must be specified if OPTIONS SYSID not setExplanation: A TSO command has been issued without a SUBSYS keyword andOPTIONS TRACKERS and OPTIONS SYSID have not both been set. For SOE toautomatically assign a subsystem both of these options must be set.System Action: The command is not issued.User response: Either provide SUBSYS or set both OPTIONS SYSID and OPTIONSTRACKERS.EQQB222F Tracker not defined to SOE for on Explanation: A TSO command has been issued without a SUBSYS but the valuepointed to by OPTIONS SYSID for this LPAR does not have match in the OPTIONSTRACKERS lookup table.System Action: The command is not issuedUser response: Add a SUBSYS keyword to the command or correct the OPTIONSTRACKERS table to include an entry for the LPAR.Copyright IBM 2008 Page 126

EQQB223W Use of MSTR is not recommendedExplanation: A TSO command has been issued using MSTR as the SUBSYS value.This sends the event to every TWS subsystem on the LPAR, which can lead to errormessages on EQQMLOG for controllers that have no match for the event, and maylead to inappropriate triggering of workload.System Action: The command is issued with RC=4.User response: If possible use the OPTIONS SYSID and OPTIONS TRACKERS feature totarget the event directly to the appropriate subsystem.EQQB224I STAT= RC=Explanation: A LISTSTAT command has run, identified a resource, checked the statusand set the appropriate return code.System Action: Processing continues, the return code is set when SOE terminates.User response: noneEQQB241E The maximum versions already existExplanation: An attempt has been made to create a new version of an object that islimited to the number of versions that can exist at once.Controlled types are –• Application – Limited to 4 versions per status.System Action: No update takes placeUser response: Delete unwanted old versions before attempting a rerun.EQQB299I Statement completed - RC=Explanation: Processing has completed for a command. This message signifies theend of the message block for the command, that was started by message EQQB200I.System Action: Message block is issued.User response: noneEQQB301F PIF command abandoned due to INIT failureExplanation: A PIF process was attempted, but the preceding INIT request failed.System Action: Any commands requiring the PIF will not run.User response: Identify the reason for the failure of the INIT command and rerun.Possible causes could be –• The controller is not active• The server through which PIF is trying to communicate is not active• The communication route to the server is failingCopyright IBM 2008 Page 127

EQQB302F Unable to GET|FREE bytes of storageExplanation: An attempt to obtain storage for a PIF request has failed.System Action: SOE terminates.User response: Identify the cause of the storage problem and rerun.EQQB303O Contention/Delay, retrying in second(s) /Explanation: A contention condition has occurred and the OPTIONS CONTENTIONfeature is active.System Action: SOE will reattempt the command in the specified number of seconds,and repeat this process until has reached . After which SOE willterminate if unsuccessful.User response: Identify and alleviate the contention.EQQB304A Delaying for second(s)Explanation: The OPTIONS DELAY feature has been enabled to cause a time delayto happen after certain categories of command, to reduce risk of contention and allowother processes a share of TWS for z/OS resources.System Action: The program pauses for the stated number of seconds.User response: noneEQQB305O Unable to initialize connection with Explanation: An attempt to connect to a TWS subsystem has been made, butOPTIONS RECONNECT has been set.System Action: SOE we retry the connection in accordance with the information inmessage EQQB303O. Should the maximum number of retries be reached the INITcommand will be considered to have failed.User response: Identify and alleviate the cause for the failed connection.EQQB901C Unable to read EQQLANGExplanation: SOE has been unable to read the language file EQQLANG, possiblydue to the DD name not being allocated, or the input file never having been written to,or the record format not being appropriate to read with EXECIO.System Action: SOE terminates before initialization has completed.User response: Determine the problem with the file, correct it and rerunCopyright IBM 2008 Page 128

EQQB902C Message missingExplanation: SOE has attempted to issue a message that is not contained within theEQQLANG file.System Action: SOE terminatesUser response: Determine the reason for the failure. It is possible that the cause isthat Language File is not the correct file for the version of EQQYXTOP that isexecuting, or has been customized incorrectly.EQQB903C Unrecognized severity Explanation: The message file EQQLANG contains a message in which the severityis one not recognized by EQQYXTOP.System Action: SOE terminates.User response: Determine the reason for the failure. It is possible that the cause isthat Language File is not the correct file for the version of EQQYXTOP that isexecuting, or has been customized incorrectly.EQQB910I >>Issuing Explanation: Trace level 1 has been activated. This message is issued to show theactual PIF commands being issued, which may not be identical to the SOE commandstatements, as SOE can extend some PIF commands.System Action: Processing continuesUser response: noneEQQB920I >>Processing address length Explanation: Trace level 2 has been activated. This message is issued every time arecord or segment is processed in the data area. It identifies the type of record, theaddress it occupies in storage and the length.System Action: Processing continuesUser response: noneEQQB921I >>Segment key Explanation: Trace level 2 has been activated. This message is issued every time asegment is processed. It shows the key information for that segment.System Action: Processing continues.User response: noneCopyright IBM 2008 Page 129

EQQB931I >>Action code Explanation: Trace level 3 has been activated. This message is issued every timeEQQYCOM is called and shows the Action Code being used.System Action: Processing continues.User response: noneEQQB932I >>Resource code Explanation: Trace level 3 has been activated. This message is issued every timeEQQYCOM is called and shows the Resource Code being used.System Action: Processing continues.User response: noneEQQB933I >>Data area address Explanation: Trace level 3 has been activated. This message is issued every timeEQQYCOM is called and shows the Data Area address.System Action: Processing continues.User response: noneEQQB934I >>Argument names Explanation: Trace level 3 has been activated. This message is issued every timeEQQYCOM is called and shows the list of Argument names being used.System Action: Processing continues.User response: noneEQQB935I >>Argument value addresses Explanation: Trace level 3 has been activated. This message is issued every timeEQQYCOM is called and shows the Addresses to each Argument Value being used.System Action: Processing continues.User response: noneEQQB936I >>Argument value block Explanation: Trace level 3 has been activated. This message is issued every timeEQQYCOM is called and shows the data contained in the Argument Value storagearea.System Action: Processing continues.User response: noneCopyright IBM 2008 Page 130

EQQB937I >>Communication block address Explanation: Trace level 3 has been activated. This message is issued every timeEQQYCOM is called and shows the Communication Block address.System Action: Processing continues.User response: noneEQQB938I >>Return code Explanation: Trace level 3 has been activated. This message is issued every timeEQQYCOM is called and shows the return code from EQQYCOM in Hexadecimal.System Action: Processing continues.User response: noneCopyright IBM 2008 Page 131