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.
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 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.
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.
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.
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 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"
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.
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.
|
From a clist, append the CLIST operand to the IOF command. The CLIST operand causes the following changes in the way IOF operates:
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.
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.
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.
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.
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
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.
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
When running under ISPF, full ISPF dialog services can be invoked from within an IOF exec/clist.
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.
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
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.
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
DOWNCTRLReturn 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.
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.
|
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:
|
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:
|
To invoke a TSO command in an IOF exec/clist, prefix the command with TSO. For example:
TSO ALLOCATE FILE(OUTPUT) DA(TARGET) SHR
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.
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.
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.
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.
The TSIINDEX command has exactly the same syntax as the FIND command in Browse. It differs from the FIND command in that:
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.
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'"