IOF REXX and Clist Interface

Introduction

Everything that a user at a terminal can do with IOF can be done using a REXX exec or TSO clist. All fields that are displayed on the terminal can be assigned to REXX or clist variables. Standard REXX and clist facilities can then be used to process the variables.

IOF execs must reside in an exec or clist library that is part of the TSO or batch TSO session's SYSEXEC or SYSPROC concatenation. IOF clists must reside in a clist library that is part of the SYSPROC concatenation. Execs and clists can be invoked under IOF, or they can invoke IOF. Clists and REXX execs are not available when running IOF under CICS.

Distributed Clists and Execs

Several useful clists and execs are distributed in the IOF clist library. Not only do the distributed clists and execs provide valuable extensions to the product, but they are the best guides to learning how to write your own exec/clist.

Member $INDEX in the distributed IOF clist library lists all the clists and execs that are included in the distribution. All member names that begin IOF$ are clists or execs that are invoked by IOF commands to perform a documented function.

The following clists and execs are of particular interest because of the extended IOF function they provide.

IOFWTR

IOFWTR is a very flexible external writer clist. It normally is run as a TSO batch job to retrieve output from the system and write it to designated output data set(s). Output can be selected based on many criteria, such as job name, destination, sysout class, forms, writer, user name, age, or account number.

Designation of the target is also very flexible. For example, data can be copied to output MVS data sets with data set names that are a function of the original job name, date and/or time the job was run, sysout class, etc.

IOFWTR will only operate on the jobs that the submitter has authority to review. Normal users can use it to manage only their own data, while systems personnel can use it to manage all output in the system.

The IOFWTR parameters are fully documented in the comments in the clist. Review the clist to learn how to use it.

OUTQUE

The OUTQUE clist reports and manages the JES2 output queue. It is normally run from TSO batch. It can select output jobs based on job name, destination, size, age, user name, and many other criteria. OUTQUE always produces an output report of the selected jobs, and additionally can cancel, route, or otherwise modify selected jobs.

OUTQUE parameters are fully documented in the comments in the clist. Review the clist to learn how to use it.

IOFSETUP

This exec displays the volume serial numbers from /*SETUP statements in the COMMENTS field of the Job List Menu. It finds all /*SETUP statements in all INPUT jobs that are on HOLD. From the Job List Menu, enter %IOFSETUP to have the setup volume serial numbers of all input jobs in the list displayed.

Writing Your Own IOF Execs and Clists

IOF execs and clists perform the same steps that would be performed using a terminal with a few exceptions. The major difference is that IOF produces no output while an exec or clist has control. The data that would be displayed on the panel can be accessed by REXX or clist commands. The exec/clist may produce its own output using REXX/clist commands. If IOF is active when the exec/clist completes execution, the IOF panel will be displayed.

To write an exec or clist, first determine the steps that would be required to perform a function from the terminal. Then execute those same steps from within the exec or clist to do the same function. The distributed execs and clists can be used as a guide.

IOF REXX Environment

IOF establishes its own REXX environment when an exec is started from IOF. However, the default addressing environment is not changed. An "ADDRESS IOF" REXX command must be issued before REXX can execute IOF subcommands. See examples of addressing the IOF environment in the distributed execs.

IOF sets the SOURCE parse string user token (9th token) value to "IOF" to allow an exec to verify that the IOF environment is in effect. The following example checks the current environment:

         parse source . . . . . . . . environ .
         if environ = 'IOF' then say "Environment is IOF"

Invoking an Exec/Clist under IOF

In order for a clist to be invoked from within IOF it must be stored as a member of a clist library that is allocated to the DD name SYSPROC in your TSO session. REXX execs can reside in a SYSPROC file or optionally can reside in a SYSEXEC file.

The percent ( % ) IOF subcommand invokes an exec or clist. The name of the exec or clist immediately follows the percent.

For example assume the exec/clist CHKJOBS will analyze the jobs on the current IOF Job List Menu for bad return codes and produce an output report to a sysout data set. It has an optional class parameter that can be used to specify the sysout class of the output report. To invoke CHKJOBS with sysout class C from the Job List Menu enter in the command area:

%CHKJOBS      CLASS(C)

IOF will automatically enter exec/clist mode and read subsequent command input from the exec/clist instead of the terminal. REXX execs that are invoked under IOF are initialized in the IOF environment. IOF will display no data to the terminal until the exec/clist terminates, at which time the then-current IOF screen will be displayed.

Exec/clists can also be invoked as line commands by preceding the exec/clist name with % in the line action area. When an exec/clist is invoked as a line command, IOF automatically adds a MENU(nnn) keyword parm to the line command that was entered to indicate the menu number of the item on which the line command was issued. For example, entering %TSTLC as a line command on the third item in an IOF list causes the exec/clist to be invoked by:

%TSTLC       MENU(3)

The exec/clist can use the menu parm to process the line item for which the command was issued. See the IOF$ED1 clist for an example of using the MENU keyword.

Please note that a REXX exec cannot be invoked from an IOF clist.

Invoking IOF from within an Exec

When an IOF command is issued from a REXX exec, control is transferred directly to IOF and the exec loses control. The example below shows how an exec can invoke IOF and then reinvoke itself under IOF to execute IOF subcommands.

/* Rexx multi-environment example */ /* Determine exec name and environment */ parse source . . myname . . . . . myenv . /* If not IOF environment, re-invoke the exec under IOF */ if myenv = 'IOF' then do /* push the IOF command including any parms. In this */ /* example there are no parms. */ push "IOF *.%"myname exit /* exit the initial exec */ end /* If IOF environment, process IOF subcommands */ else do ADDRESS IOF ... exec and IOF statements ... exit end

Invoking IOF from within a Clist

From a clist, append the CLIST operand to the IOF command. The CLIST operand causes the following changes in the way IOF operates:

  • IOF will read subsequent command input from the clist instead of the terminal until the clist is empty or an error arises that causes it to terminate.
  • IOF will display no data to the terminal while the clist has control.
  • The current IOF panel will be displayed on the screen when the clist terminates.

    A single clist can invoke IOF from TSO ready, issue IOF subcommands, and return to TSO. The OUTQUE clist in the distribution clist is a good example of this technique.

    Setting REXX/Clist and ISPF Dialog Variables

    IOF panels are organized into sections and fields. Within a panel section, each row of the display has several fields of data displayed in columns. For example, the jobname field (column) contains the name of the job being displayed on each row of the display.

    Each display field has a field name that can normally be easily determined from the field heading. For example, JOBNAME is the heading on the column of job names on the IOF Job List Menu, and is also the name of the job name field. Some field headings are abbreviated (such as ACT for ACTION) to make them fit on the display. In this case the field name will normally be the entire word (ACTION). For field headings that are two words (such as DATE TIME) the field name will normally be the two words concatenated without the intervening blank (DATETIME). See the Appendix for detailed information on using HELP to determine field names.

    TSICOPY Command

    The TSICOPY command is used to assign data from IOF panel fields to REXX, clist and ISPF dialog variables. All IOF fields on all IOF panels can be accessed with TSICOPY. The IOF field name becomes the default REXX, clist or dialog variable name that is set with TSICOPY.

    TSICOPY operates on the top row of the current IOF display panel by default. Remember that a field is a column of information, and that each row can have a different value in the column. The UP, DOWN, DOWNCTRL, FIND and other screen positioning commands can be used to position a particular row to the top of the current display panel. TSICOPY also can move data between REXX/clist and dialog variables, or from rows other than the top row.

    Syntax

            TSICOPY  NAME(names)  TO(CLIST/REXX/DIALOG)
                [FROM(CLIST/REXX/DIALOG/SESSION/LOCAL/PROFILE/OPTIONS/LIST)]
                [SECTION(section-name)]   [ROW(row-number)]
                [VARNAME(alt-varname)]
    

    NAME(names). One to eight field names separated by blanks.

    TO(REXX/CLIST/DIALOG). The type of variable that will be set.

    FROM(CLIST/REXX/DIALOG/SESSION/LOCAL/PROFILE/OPTIONS/LIST). Optional parm that specifies where data is taken from. When this parm is not present, data is copied from the current display panel. CLIST, REXX and DIALOG specify the type of variable. SESSION, LOCAL, PROFILE, and OPTIONS are used to fetch IOF generation parms. LIST fetches from LOCAL, PROFILE, SESSION and OPTIONS in that order.

    SECTION(section-name). The optional name of the IOF section from which data will be copied. Section names are documented in HELP for the panel. A special section name of PANEL is used to assign non-display type information, and will be discussed in more detail later.

    ROW(row-number). The row number in the section specified above from which field variables should be copied if the top row is not desired.

    VARNAME(alt-varname). The name of the destination variable(s). By default the destination variable names are the same as the NAME variables. When VARNAME is specified, one destination name must be specified for each NAME variable.

    To copy the name of the job that is currently at the top of the IOF Job List Menu into the exec/clist variable JOBNAME, use the following statement in an exec/clist:

              TSICOPY NAME(JOBNAME) TO(CLIST/REXX)
    

    After the execution of this statement, the variable JOBNAME will contain the name of the job that is currently at the top of the IOF Job List Menu. The NAME operand of the TSICOPY command can specify the name of any display field that is defined for that job. See the Appendix for detailed information on using HELP to determine field names.

    Multiple fields can be copied with a single TSICOPY command by specifying up to eight different names in the NAME operand, separated by blanks. Copying multiple fields with a single TSICOPY command is much more efficient than individual commands.

    The name of the variable that is set is the same as the name of the field from which the data was copied unless a VARNAME parm also is specified. Although the above example is for the IOF Job List Menu, the TSICOPY command is also supported for all IOF display panels.

    TSICOPY also can be used to copy REXX/clist variables to identically named dialog variables. For example, to copy the JOBNAME REXX variable to the JOBNAME dialog variable:

              TSICOPY NAME(JOBNAME) FROM(REXX)  TO(DIALOG)
    

    Dialog variables can also be copied to REXX/clist variables. To copy the dialog JOBNAME variable into the clist JOBN variable:

              TSICOPY  NAME(JOBNAME) FROM(DIALOG) TO(CLIST) VARNAME(JOBN)
    

    To copy data from other than the top display row in a menu, use the SECTION and ROW operands to specify the section and row number of the menu item from which the display field is to be copied. For example, to copy the JOBNAME field of the third job in the OUTPUT section of the IOF Job List Menu into a REXX variable:

              TSICOPY  NAME(JOBNAME)  SECTION(OUTPUT)  ROW(3)  TO(REXX)
    

    If the section name specified in the SECTION operand is found but the row number specified is too large, then a return code of 8 will be set but the clist will not be terminated.

    This means that you can use the SECTION and ROW operands to loop through the display items in a particular section of a display and check the return code after the TSICOPY command to tell when you have completed the section. You must always examine the return code from a TSICOPY command with the SECTION and ROW operands to avoid having your exec or clist enter an endless program loop.

    TSICOPY Line Command

    The TSICOPY line command is available on the Job List Menu, Job Summary, Output Group Display, Monitor and Device List Menu to permit capturing data from a specific line on the display. The display is not repositioned to the line from which data is copied.

    Syntax

    menu TSICOPY NAME ( field-names )

    TO ( CLIST / REXX / DIALOG )

    menu. The menu number of the item to copy from.

    NAME(field-names). One to eight IOF field names separated by blanks. The field names must all be present on the current IOF display panel. See the Appendix for detailed information on using HELP to determine field names.

    TO(REXX/CLIST/DIALOG). The type of variable that will be set.

    Section PANEL Variable Names

    If you specify SECTION(PANEL) on the TSICOPY command, the NAME operand is used to request information that is specific to the current IOF panel. For example, for any IOF panel, to return the HELP name for the current panel to the clist variable HELP:

              TSICOPY   NAME(HELP)   SECTION(PANEL)   TO(CLIST)
    

    The following field names are valid when SECTION(PANEL) is specified in the TSICOPY command:

    Variable               Contents
    HELP                   HELP member name for current panel
    SECTION                Section name for menu item at top of screen
    MESSAGE                Long message text for last error raised
    ROWS                   Total number of rows on the current panel
    SECTROWS               Total number of rows in the current section
    OPERCMD                MVS modify command operand value, or 'STOP' if an MVS stop command was issued.
    DEFENTY#               Total number of DEFENTRY commands for this browse session.
    

    Under the IOF Browse panel, the following additional variables can be accessed when SECTION(PANEL) is specified.

    Variable               Contents
    JOBNAME                Name of job in which data set is being browsed
    JOBID                  JES2 jobid of job being browsed
    STEP                   Name of step in which data set is being browsed
    PROCSTEP               Procedure step name
    PROC                   Name of procedure
    DDNAME                 DD name of data set being browsed
    CURRENT                Text of data record currently on top of screen
    NEXT                   Text of data record currently on top of screen (then scroll down 1 record)
    PAGE#                  Page number of record on top of screen
    LINE#                  Line number on page of record on top of screen
    REC#                   Record number of record on top of screen
    FINDCOL                Column number of last found string (0 if none)
    SEGMENT                Current segment number
    COL1                   Column displayed at left margin
    COL2                   Column displayed a right margin
    CSRROW                 Row number of current cursor
    CSRCOL                 Column number of current cursor
    

    Session and Options Variables

    Many attributes of the current IOF user's session can be retrieved by using FROM(SESSION) parm on the TSICOPY command. FROM(OPTIONS) is used to retrieve options variables. Session and options variable names can be displayed using the DVAR command from any IOF panel.

    Panel Names

    The PANNAME command can be entered on any IOF panel to display the name of the IOF panel. TSICOPY also can be used to copy the HELP name from SECTION(PANEL) in order to determine the panel name. Some of the more commonly used panel names are:

    Panel Name             Description
    BROWZE                 Browse display panel
    CATMNU                 Data Indices Menu
    CNSBRZ                 Console browse
    DEVDSP                 Device List Menu
    DVINI                  Initiator detail panel
    DVLNE                  Line detail menu
    DVNJD                  NJE device detail menu
    DVODV                  Offload device detail menu
    DVOJR                  Offload job receiver
    DVOJT                  Offload job transmitter
    DVOSR                  Offload sysout receiver
    DVOST                  Offload sysout transmitter
    DVPPU                  Print/punch detail menu
    DVRDR                  Reader detail menu
    DVRMT                  Remote detail menu
    FNDALL                 FIND ALL panel
    HELP                   HELP panel
    INPUTQ                 Input Queue Summary Display
    JOBSUM                 Job Summary Display
    JOEDSP                 IOF Output Group Display
    JQEDSP                 IOF Job List
    MASDSP                 IOF MAS Display
    MONITR                 System Monitor panel
    NDXMNU                 Data Index Menu
    OPTOPT                 IOF Option Menu
    OPTUS1                 Alternate Option Menu
    SDPANL                 "SD" panel for SNAP data set attributes
    

    Invoking ISPF Functions under IOF

    When running under ISPF, full ISPF dialog services can be invoked from within an IOF exec/clist.

    TSIEXEC Command

    The TSIEXEC command is used to invoke an ISPF dialog service from within an IOF exec/clist. The ISPF function will be executed just as though it had been invoked via ISPEXEC in a normal ISPF exec/clist. TSIEXEC requires that IOF be running under ISPF.

    Syntax

    TSIEXEC any-ISPEXEC-function

    Any ISPEXEC function can be used as a parameter.

    Controlling Error Conditions in IOF Clists

    If the CLIST operand of IOF is specified on an IOF command in a clist, or if a clist is invoked with the % command under IOF, the clist is completely controlled by IOF. This means that IOF must control whether or not the clist should terminate in case of error. For example, to allow a clist to continue even if there is an error:

    NOFLUSH
    

    To restore the default value (terminate the clist in case of error):

    FLUSH
    

    Scrolling Through Displays with an IOF Exec/Clist

    For IOF display menus, like the Job List Menu and Job Summary displays, you can create an exec/clist to examine each item (row) on the display and then conditionally perform some function against selected items.

    DOWNCTRL Command

    The DOWNCTRL command scrolls the current IOF panel down one row unless currently positioned to the bottom. It never flushes the exec/clist, but instead sets a return code that can be checked by the exec/clist.

    Syntax

    DOWNCTRL

    Return codes are:

    0 - Display scrolled down one line successfully
    4 - Display scrolled down to the next section of the same IOF panel.
    8 - Display was not scrolled because it was currently at the bottom.

    Scrolling by Number of Rows on the Panel

    There are several different approaches that can be used to scroll through a display menu. The first approach determines the number of rows on the display, and then steps through this number of rows. The example clist below shows how to use this approach to scan through all the jobs of the IOF Job List Menu.

    CONTROL END(ENDO) LOCK /* Keep display static */ TSICOPY NAME(ROWS) SECTION(PANEL) TO(CLIST) /*Number rows */ SET &CURROW = 1 /* Start with 1st row */ DO WHILE &CURROW LE &ROWS /* Process all rows */ TSICOPY NAME(JOBNAME JOBID) TO(CLIST ) /*Top job on menu*/ WRITE &JOBNAME &JOBID /* Just write variables */ ... do whatever processing is desired DOWNCTRL /* Down to next job */ SET CURROW = &CURROW + 1 /* Step row count */ ENDO UNLOCK /* Unlock the display */


    Scrolling by Checking DOWNCTRL Return Code

    The second approach to scrolling through a display menu is to check the return code from the DOWNCTRL command. The DOWNCTRL command scrolls the display down by one row but will not terminate the clist even if there are no more rows. You can use the return code from the DOWNCTRL command to tell when you have reached the end of the display menu. A sample CLIST using the DOWNCTRL command:

    CONTROL END(ENDO) LOCK /* Lock the display */ /* Begin loop through the job list */ DO WHILE &LASTCC LT 8 /* Copy display fields for current job to CLIST */ /* variables. */ TSICOPY NAME(MENU JOBNAME ...) TO(CLIST) /* Analyze current job; optionally perform a function,*/ /* using the CLIST variables set by TSICOPY command */ ... /* Move next job to top of screen */ DOWNCTRL ENDO UNLOCK /* Unlock the display */


    Reviewing the execs and clists in the distributed IOF clist library will show you additional techniques for scrolling through lists of jobs, groups, and data sets.

    In an IOF exec/clist you will normally want to perform some IOF function against certain display items (rows) in the list, based upon your analysis of the items.

    To select the top display element on the current screen for a command use the menu selection character ( * ). For example, to cancel the job that is currently displayed on the top of the IOF Job List:

    *      CANCEL
    

    You can also perform functions against specific display rows in an IOF exec/clist by using the menu number for the display row, which can be easily obtained with the TSICOPY command. For example, the following sequence illustrates how to use the menu number for a job to cancel the job in a clist:

    TSICOPY NAME(MENU JOBNAME ...) TO(CLIST) /* Perform analysis to determine if CANCEL is needed ... /* Assume CANCEL is needed. &MENU CANCEL /* Cancel the job


    Invoking a TSO Command from an IOF Exec/Clist

    To invoke a TSO command in an IOF exec/clist, prefix the command with TSO. For example:

    TSO      ALLOCATE  FILE(OUTPUT)  DA(TARGET)  SHR
    

    Reading the Spool with a User Program

    IOF allows you to read any sysout data set directly from the spool with your own program. The IOF data set ALLOC command can be used on the IOF Job Summary to allocate the spool data set for later use by other programs.

    To allocate a specific sysout data set on the IOF Job Summary:

    3      ALLOC  DDNAME(INPUT)
    

    where INPUT above is the DD name that you want to associate with the sysout data set. You then can use the TSO command option (described above) to invoke your own program to read DD name INPUT, or you can terminate the IOF session and invoke a program directly. The IOF allocation remains in effect until it is freed with a TSO FREE command.

    Sysout data set characteristics such as LRECL, RECFM, and DSORG can be specified on the ALLOC command if needed.

    Pausing in an IOF Exec/Clist

    In many applications it is useful to pause for a few seconds (or minutes) and then resume execution. The PAUSE command allows you to pause and then determine why the pause was terminated.

    Syntax

    PAUSE nnnn [NOFLUSH]

    nnnn. The time interval, in .01 seconds, to pause.

    NOFLUSH. IOF should not terminate the exec/clist if PAUSE ends with a non- zero return code.

    PAUSE. Gives a return code in variable LASTCC for clists, and in variable rc for execs. The meaningful return codes are:

    0 Normal completion of time interval

    1307 Console operator has sent a command to this clist with the MVS MODIFY or STOP command. (see next section)

    1308 The terminal user pressed attention.

    PAUSE with the NOFLUSH option lets you process the return code to decide what to do next. Or, you can leave off the NOFLUSH operand, in which case the clist will simply terminate in the case of attention or an operator command.

    Receiving Operator Commands in an IOF Exec/Clist

    It is very useful in IOF exec/clist applications, like an external writer, to allow the system console operator to communicate with the application. The OPERCMD command is used to enable operator communication with an IOF exec/clist via the MVS MODIFY and STOP commands.

    Syntax

    OPERCMD ENABLE / DISABLE

    ENABLE. Enable operator commands.

    DISABLE. Disable operator commands.

    After OPERCMD ENABLE has been issued by the application, operator STOP and MODIFY command operands are passed to the application. If the application is currently in a PAUSE, the pause command will be terminated with a return code of 1307.

    To retrieve the operator's command, the exec/clist may issue a TSICOPY command to copy the command string into the REXX/clist variable named OPERCMD:

    TSICOPY      NAME(OPERCMD)  SECTION(PANEL)  TO(CLIST)
    

    The value will be STOP if the MVS STOP command was issued. The value will be null if no command has been entered, so you can use this TSICOPY to check for an operator command at any point in your clist. Note that you will only receive the 1307 return code described above if your clist is in a PAUSE command at the time the operator command is entered.

    Special Features for the Browse Panel

    As described on page 13, several special variables are available for assignment with the TSICOPY SECTION(PANEL) command from the IOF Browse panel.

    The DOWNCTRL command can be used in Browse to scroll down by 1 record. If there are no more records in the data set, DOWNCTRL will end with a return code of 8 and the clist will not be terminated.

    TSIINDEX Command

    The TSIINDEX command has exactly the same syntax as the FIND command in Browse. It differs from the FIND command in that:


    Features of Specific Panels

    The SECTION(PANEL) feature of the TSICOPY command is supported by all panels. The ROW operand of the TSICOPY command is supported only on the Job List, Output Group Display, Device List, System Monitor and Job Summary panels. The DOWNCTRL command is supported only for the Job List, Output Group Display, Job Summary, Device List, System Monitor, and Browse panels.

    Error Message from Exec/Clist Applications

    IOF exec/clist applications often need to present error and informational messages to the IOF user as standard short and long messages. The TSIMSG command can be used to construct and display variable short and long messages.

    Syntax

              TSIMSG  [INFO/LONG] 'short msg' 'long msg'
    

    INFO. This is optional and defines an informational message. The long message is displayed immediately and the message is defined to be informational rather then an error message. The audible alarm is not sounded.

    LONG. This is optional and specifies that the long message should be displayed immediately for the error message being defined. The audible alarm is sounded.

    short msg. This is required and defines the text for the short message to be displayed in the short message area at the top of the screen.

    long msg. This is required, and defines the text for the long message to be displayed in the long message area at the top of the screen when requested by entering the HELP key.

    Examples:

              TSIMSG  'No More' 'There are no more elements'
              TSIMSG  INFO  'View' 'Enter the "V" line command'
    

    From a REXX exec, to include the variable "class" in the error message:

              ADDRESS IOF
              "TSIMSG  'No"class"' 'No class"class "on queue'"
    

    Table of Contents