TSO and FOCUS Interaction

In this section:

You can execute TSO commands from within FOCUS. These commands can be used in conjunction with FOCUS to create and maintain applications. You can also go directly to ISPF edit screens from within the FOCUS command environment. This means that you can start a FOCUS session and then issue TSO and ISPF commands to allocate files, create, and edit FOCUS procedures and Master Files, all directly from with FOCUS.

Additionally, you can issue command interrupts to halt processing or suppress output.

Issuing TSO Commands From Within FOCUS

How to:

You can issue almost all of the standard TSO commands from within the FOCUS environment. The exceptions are EXEC, TIME, and TSO commands that load programs, like CALL and COMPILE.

This facility applies only to interactive FOCUS sessions. FOCUS ignores TSO commands when running in batch mode, and does not generate error diagnostics. You can still run unaltered procedures in batch mode and TSO, but you must add supplementary JCL statements in the batch mode version to replace any TSO ALLOC statements embedded in a FOCUS procedure.

Syntax: How to Issue a TSO Command From Within FOCUS

{TSO|MVS} system command parameters

Note: The MVS prefix may be substituted for the TSO prefix.

The initial keyword, TSO or MVS, tells FOCUS how to interpret what follows and appears only once on the first line of the command. Otherwise, the syntax of the TSO command and accompanying parameters is the same whether you are inside or outside of FOCUS. For example:

TSO ALLOCATE F(SAVE1) SPACE(5 5) TRACKS

TSO commands are documented in the IBM TSO User's Guide. Installation written commands should be avoided or thoroughly tested, as they may or may not execute properly within FOCUS.

Example: Executing a CLIST From Within FOCUS

You can execute TSO Command Lists (CLISTs) from within FOCUS by invoking the services of ISPF. To execute a CLIST from within FOCUS, all of the files needed to run ISPF must be allocated and the CLIST to be invoked must exist as a member of a partitioned data set (PDS) allocated to the ddname SYSPROC. For example:

ALLOC FILE(SYSPROC) DA('WIBMBP.M.CLIST') SHR

There are two ways of running the CLIST, depending on whether FOCUS was entered from TSO or from within ISPF.

  • If FOCUS was entered from the TSO command level, the command
    TSO ISPSTART CMD(memname)

    executes CLIST memname from the library allocated to SYSPROC (WIBMBP.M.CLIST in this case). The ISPSTART command could be incorporated in a LET statement such as

    LET GOCLIST = TSO ISPSTART CMD (< >)

    and may be issued at the FOCUS command level by specifying:

    GOCLIST memname
  • If FOCUS was entered from within ISPF, a FOCEXEC should be created to invoke the ISPLINK processor. The FOCEXEC is needed to pass the correct parameters to the ISPLINK utility. The parameter COMLEN, which specifies the length of the command, must be passed as a binary integer. For example:
    -SET &COMAND  = 'CMD('|| &MEMNAME.Enter name of CLIST. || ')';
    -SET &COMLEN1 = HEXBYT(O,'A1');
    -SET &COMLEN2 = HEXBYT(&COMAND.LENGTH,'A1');
    -SET &COMLEN  = &COMLEN1 || &COMLEN1 || &COMLEN1 || &COMLEN2;
    -TSO RUN ISPLINK,SELECT,&COMLEN,&COMAND

Note:

  • Some commands placed in a CLIST that is invoked from within FOCUS may give unpredictable results, particularly when FOCUS has been invoked from within ISPF.
  • For detailed documentation on ISPSTART or ISPLINK, consult the System Productivity Facility (ISPF), Dialogue Management Services, or contact your system support group.

Using TSO Commands in FOCUS Applications

Four TSO commands, COPY, LIST, LISTDS, and RENAME, are frequently used within the FOCUS environment to create and maintain FOCUS Master Files and FOCEXECs. TSO COPY and TSO LIST are program product commands, available only if you have exercised those options. From within FOCUS, you can reference data sets in the command segments either by actual data set names (as in normal TSO syntax) or by ddnames. Obviously, in most instances, the short ddname syntax will appeal simply for ease of entry. The FOCUS syntax for the ddname versions of the four TSO commands follows:

TSO COPY   ddname datasetname 
TSO LIST   ddname 
TSO LISTDS ddname 
TSO RENAME ddname datasetname

FOCUS recognizes that you are using the ddname syntax by the absence of embedded periods (.) in the name field of the argument. When FOCUS receives one of these commands, it replaces the ddname portion of the argument with the fully qualified data set name for that ddname. FOCUS then reprints the translated command on your terminal as an informational message before sending it to TSO for execution.

For example, if you want to rename the file, GM.FOCUS (allocated as ddname CAR), to data set name CHEVY.FOCUS, you enter:

TSO RENAME CAR CHEVY.FOCUS

FOCUS responds with an informational message:

RENAME 'ID.GM.FOCUS' CHEVY.FOCUS

TSO then receives and executes the command.

Note:

If you want to suppress the printing of the informational messages, you can do so by issuing the FOCUS SET MESSAGE command (in this case, SET MESSAGE=OFF).

The argument in any of the TSO commands mentioned in the previous paragraphs can also refer to a member in a partitioned data set by including the member name within parentheses after the ddname under which the PDS was allocated. For example, the command TSO LIST INDATA(CAR), calls the TSO command LIST to display member CAR in the PDS allocated as INDATA. The ddname can be any ddname, including significant FOCUS ddnames such as MASTER or FOCEXEC.

You can use the FOCUS ddname TSO command syntax to refer to concatenated data sets in any case to make sure that the reference cannot be interpreted unambiguously. FOCUS evaluates the combination of ddnames, member names, data set organizations, and concatenations, and then diagnoses the command. If the command request is unambiguous, it is executed. If the command could have ambiguous results, it is not executed and a message is returned.

For example, if you wish to display a member named ACCOUNTS that is part of the only PDS allocated to ddname FOCEXEC, you enter:

TSO LIST FOCEXEC(ACCOUNTS)

FOCUS displays the member, ACCOUNTS, in the PDS allocated to FOCEXEC.

If, in the same example, there were several partitioned data sets allocated to ddname FOCEXEC and TSO EDIT was called, FOCUS would diagnose the potential problem and would not process the edit request because it would not know where to put the output. Instead, FOCUS would return an error message to the terminal.

FOCUS Command Interrupt Levels

Reference:

When you are in the FOCUS command environment, you can issue an external interrupt to stop execution of some commands (MODIFY, FSCAN, TABLE, TABLEF, MATCH, and GRAPH). This results in an orderly closing of the FOCUS data source and/or suppressing the output. To issue an interrupt, press one of the following function keys:

Terminal

Function Key

IBM 327X
PA1 or ATTN
IBM 2714
ATTN
ASCII
BREAK
ASCII (full duplex)
ESC

FOCUS signals receipt of the interrupt by the message

FOCUS INTERRUPTED..ENTER KX,KT,RT, FX OR ?

and waits for the user's reply. The effect of each reply is as follows:

KX

Kill execution, stay in FOCUS.

KT

Kill typing until next terminal read.

RT

Resume typing.

FX

Kill execution, exit FOCUS.

?

Display current run-time statistics.

Other

Ignored, execution resumes.

Reference: Kill Execution: KX

This reply stands for "Kill Execution" and remains in FOCUS. It can be used with the GRAPH, MATCH, MODIFY, TABLE, TABLEF, and FSCAN commands. It tells FOCUS to halt execution and return you to the FOCUS command level outside all FOCEXEC procedures (that is, to the next command from SYSIN, which is generally the terminal). The interrupted command may terminate normally or it may be cut short. The FOCUS data source is closed in an orderly manner. The commands are terminated as follows.

MODIFY

At end of current transaction.

SCAN

At end of current subcommand.

TABLE, TABLEF, MATCH and 
GRAPH

At next data access or generation of an output line.

All others

Ignore the KX reply and continue to completion.

Reference: Kill Typing: KT

This reply stands for "Kill Typing" and can be used with GRAPH, MODIFY, FSCAN, TABLE, and TABLEF. It tells FOCUS to suppress output of the command but to allow the command to continue to completion. After you enter KT, nothing more will appear on the screen until the command finishes, when FOCUS will prompt you for the next command.

The KT feature is useful when FOCUS is producing a report of unexpected length. Suppressing output eliminates terminal I/O and speeds up processing. You can save the output in a file with the SAVE and HOLD commands, or you can display the output from the beginning with the RETYPE and REPLOT commands.

Reference: Resume Typing: RT

This reply stands for "Resume Typing" and is used after entering the KT subcommand in response to a previous interrupt. After you enter KT, nothing will appear on the screen until the command is finished executing. To have FOCUS resume display of the output, press the interrupt key and enter RT. FOCUS displays output with the first output record it produces after this latest interrupt.

The RT interrupt reply is useful for discovering how far FOCUS has gone in producing output. If you want to suppress output again, press the interrupt key and enter KT.

Reference: Kill Execution: FX

This reply stands for "Kill Execution" and exit FOCUS. It can be used with the GRAPH, MATCH, MODIFY, TABLE, TABLEF, and FSCAN commands. It tells FOCUS to halt execution and return you to the TSO session. The interrupted command may terminate normally, or it may be cut short. The FOCUS data source is closed in an orderly manner. The commands are terminated as follows:

MODIFY

At end of current transaction.

SCAN

At end of current subcommand.

TABLE, TABLEF, MATCH and 
GRAPH

At next data access or generation of an output line.

All others

Ignore the FX reply and continue to completion.

Reference: Display Statistics: ?

This reply can be used with the commands TABLE, TABLEF, GRAPH, MATCH, and MODIFY. It displays statistics on reports of record modifications that FOCUS has processed. Afterwards, FOCUS displays the output from the point where it was interrupted. The statistics are: the number of records in the report or the records modified by the MODIFY or FSCAN command, the number of lines in the report, and the number of I/O operations FOCUS performed to read or modify the data source.

Reference: Interrupting TSO Commands

When you are executing a TSO command from within the FOCUS environment, you can issue an interrupt to cancel execution of the command by pressing down once on the appropriate function key. FOCUS signals receipt of the interrupt with the message:

FOCUS INTERRUPTED..ENTER KX,KT,RT, FX OR ?

Enter KX. This will terminate execution of the TSO command and return you to the FOCUS environment. Any other response will have no effect and you will simply remain in suspended operation. You must hit interrupt again and make the correct KX response.

Reference: TSO Time Check

If you hit the interrupt key twice, you return to the TSO environment and you can enter the TSO command TIME. You can then resume your FOCUS session by pressing the Enter key. Entering any other TSO command leaves you in the TSO environment after the command is processed.

ISPF From FOCUS

How to:

Under TSO, you can enter ISPF edit screens directly, without going through the ISPF menus. To directly enter an edit screen from FOCUS, you must create a procedure that issues the EDIT DATASET command. This procedure must be a member of a partitioned data set that is concatenated to the allocation for ddname SYSPROC. The steps for creating such a procedure are as follows:

  1. Create a PDS (LRECL=80, RECFM=FB, BLKSIZE=1600) to contain your procedure.
  2. Concatenate the PDS to your allocation for ddname SYSPROC.
  3. Create a member in this PDS to contain your procedure. Give the member a name that reminds you of the fact that you use it to edit screens, but do not give it the name of an actual ISPF or TSO function. For example, you can call the member EDITIT.

    This member should contain the following procedure:

    PROC 1 ARG
    ISPEXEC EDIT DATASET(&ARG)

    When you call this procedure, it will take as an argument the fully qualified data set name of the member or sequential file you want to edit, and it will open an edit screen for that member or file.

In order to call your procedure and open an ISPF edit screen from FOCUS, you must enter FOCUS from the TSO Ready prompt, not from ISPF 6.

Syntax: How to Call a Procedure From Within FOCUS

TSO ISPSTART CMD(procname 'file_to_edit')

where:

procname

Is the name of the member that contains your procedure.

file_to_edit

Is the fully qualified name of the sequential file or PDS member that you want to edit, enclosed in single quotation marks.

For example, if your procedure is called EDITIT and you want to edit member MYFILE in the PDS named USER1.MASTER.DATA, issue the following command:

TSO ISPSTART CMD(EDITIT 'USER1.MASTER.DATA(MYFILE)')

ISPF From FOCUS From ISPF

The previous technique will only work if FOCUS has been entered directly from TSO command level. It will not work if FOCUS has been entered from option 6 of ISPF, since it calls ISPF. ISPF cannot be called when running under ISPF, either directly or indirectly.

ISPF Service Procedures do allow parts of ISPF to be called from within another program. By combining this facility with FOCUS' ability to dynamically call subroutines, the ISPF within ISPF limitation can be overcome. To accomplish this using FOCUS facilities and the ISPF facilities known as ISPLINK and ISPEXEC, follow these steps:

  1. Prior to entry into ISPF, the FOCUS load library (FOCLIB.LOAD) must be in a system search library. This may be STEPLIB, LINKLIB, or some other standard system ddname. If not, the user (or systems person) can put it under the ISPF library name of ISPLLIB. Once done, ISPF can be entered through normal means.
  2. From within ISPF, FOCUS may be entered from option screen 6 or some other screen. However, instead of a direct call to FOCUS, FOCUS should be entered by a call to the ISPF facility called ISPEXEC. This command cannot be entered directly, but it can be executed from within a CLIST. The syntax is:
    CONTROL NOMSG
    ISPEXEC SELECT PGM(FOCUS)
  3. Once within FOCUS, the ISPF edit screens can be invoked by calling a second ISPF facility called ISPLINK. ISPLINK must be dynamically called using the -TSO RUN Dialogue Manager command. The first parameter of the call is the command (EDIT or BROWSE), and the second parameter is the data set name. If a PDS is specified without a member, a member list screen is provided.

    A sample FOCEXEC with the necessary syntax follows:

    -TSO RUN ISPLINK, CONTROL, DISPLAY, REFRESH
    -TSO RUN ISPLINK, EDIT, FOCEXEC.DATA(&1.A8.FOCEXEC NAME.)
    TSO PROFILE PROMPT

    In the sample, the first -TSO RUN statement prevents screen erasure errors that may occur when entering ISPF after FOCUS performs a full screen I/O.

    Note the TSO command after the call. This is required to ensure that when the FOCEXEC file is next accessed, the updated FOCEXECs are used. If your FOCEXEC file is not called FOCEXEC.DATA, the fully qualified data set name may be used. If not fully qualified, the TSO PREFIX is appended to the data set name.

    ISPLINK does provide the facilities to call other parts of ISPF, though less directly. These can be provided upon request from Information Builders or through your systems support group.

Reviewing Attributes of Allocated Files

How to:

Reference:

FOCUS enables you to check on existing file allocations within the interactive environment. The FOCUS command ? TSO DDNAME provides this facility through three optional command formats:
? TSO DDNAME

For listing allocated files.

? TSO DDNAME ddname

For listing file attributes.

-? TSO DDNAME ddname

For placing file attribute information into Dialogue Manager variables.

The first two formats are direct FOCUS commands that you can enter live at run time or place in a FOCEXEC. Both produce a listing on file SYSPRINT (ordinarily the TSO terminal) even if you issue the OFFLINE command. The third format can occur only in a FOCEXEC procedure and does not produce any visible output. Instead, the attributes of the queried ddname are returned as values for Dialogue Manager variables.

Note: The MVS prefix may be substituted for the TSO prefix.

Example: Listing the Currently Allocated Files

The ? TSO DDNAME command lists all the currently allocated files by ddname, shows the number of occurrences for each, and lists their corresponding data set names. It displays currently allocated files regardless of whether the allocations took place in the logon procedure or through TSO ALLOCATE and DYNAM ALLOCATE commands. Sample output follows:

>>? TSO DDNAME
DDNAME         OCCURRENCES    DSNAME
STEPLIB             2         TSO.TS.FOCUS.LOADLIB
                              INPDQ.PROC.PROCLIB
MASTER              1         INPDQ.MASTER.DATA
FOCEXEC             1         INPDQ.FOCEXEC.DATA
WINFORMS            1         INPDQ.WINFORMS.DATA
ERRORS              1         INPDQ.ERRORS.DATA
FOCSTACK            1         SYS88229.TO95525.RA000.INPDQ.R0000001
FOCSORT             1         SYS88229.TO95540.RA000.INPDQ.R0000002
OFFLINE             1         TSOINFOC.TSOINFOC.OFFLINE
SYSUT1              1         SYS88229.TO95058.RA000.INPDQ.SYSUT1
SYSEDIT             1         SYS88229.T095058.RA000.INPDO.EDIT
HOLD                1         SYS88229.TO95058.RA000.INPDQ.R0000003
HOLDMAST            1         SYS88229.T095044.RA000.INPDQ.R0000004
CAR                 1         INPDQ.CAR.FOCUS

The DDNAME column lists all allocated file names (ddnames). The OCCURRENCES column shows how many data sets are allocated to the corresponding ddname. This number will be one unless two or more data sets are concatenated under the ddname. The DSNAME column shows the fully qualified data set name (DSN) corresponding to the ddname. For concatenated data sets, all the data set names are shown.

Example: Displaying Attributes of a Queried ddname

This command displays attributes of the queried file name (ddname). If the specified ddname was not allocated, the command displays the attributes as either blanks or zeroes. Sample output is as follows:

>>? TSO DDNAME CAR
DDNAME              =          CAR
DSNAME              =          INPDQ.CAR.FOCUS
DISP                =          OLD
DEVICE              =          DISK
VOLSER              =          TSOPAK
DSORG               =          PS
RECFM               =          F
SECONDARY           =          1
ALLOCATION          =          TRACKS
BLKSIZE             =          4096
LRECL               =          4096
TRKTOT              =          2
EXTENTSUSED         =          1
BLKSPERTRK          =          10
TRKSPERCYL          =          15
CYLSPERDISK         =          886
BLKSWRITTEN         =          20
FOCUSPAGES          =          8

Syntax: How to Create a General List of Allocated Files

You can also create a general list of allocated files by ddname. To do so, specify a wildcard character (* or ?) with part of the ddname when you issue the query command. The syntax is

? {MVS|TSO} DDNAME ddn

where:

ddn

Is the first three characters of the ddname. You may specify up to eight characters, including the wildcard character. Use the wildcard character ? to represent one character. To represent a sequence of characters, use the * wildcard.

Example: TSO System Variables

The -? TSO DDNAME ddname statement is a Dialogue Manager control statement that works similarly to the ? TSO DDNAME ddname command, except that it places the information in variables instead of displaying the information on the terminal. These Dialogue Manager TSO system variables have the same names as the attributes returned by the ? TSO DDNAME ddname command. A complete list of variables is provided in TSO ddname Variables.

If there is no information for a variable, the variable will contain blanks if it is an alphanumeric variable, or zeroes if it is numeric.

The following is an example of how to use this Dialogue Manager control statement:

1. -? TSO DDNAME &DD.ENTER DDNAME.
2. -IF &DSNAME EQ ' ' GOTO ALLOCATE;
   -TYPE DATASET &DSNAME ALLOCATED TO &DD
   -EXIT
   -ALLOCATE
       .
       .
       .

The process is as follows:

  1. This statement prompts you for the ddname. The information that is entered from the terminal is then placed in the variable &DD. Depending on the value of &DD, the system supplies the information for the variable &DSNAME. If no data set is allocated to the ddname that was supplied, the variable &DSNAME will contain a blank, as it is alphanumeric.
  2. This statement tests whether the variable &DSNAME is a blank. If it is blank (that is, if no data set was found for the ddname entered by the operator), the procedure jumps to the label -ALLOCATE and continues. If it is not blank (that is, if a data set was found for the ddname entered by the operator), the procedure prints a message stating the name of the data set and exits.

Note: For detailed information on how to use Dialogue Manager control statements and variables, see the Developing Applications manual.

Reference: TSO ddname Variables

TSO ddname Variable

Meaning

&DDNAME

Queried file name (ddname).

&DSNAME

Fully qualified data set name. For concatenated data sets, only the first data set name is returned.

&DISP

Disposition: OLD, NEW, MOD, or SHR.

&DEVICE

DISK, TAPE, TERM, or READER-PRINTER.

&VOLSER

Disk or tape volume serial number(s).

&DSORG

Data set organization: PS (sequential); IS (indexed sequential); PO (partitioned); U (undefined); DA (direct).

&RECFM

Record format F, FB, V, VB, and so on.

&SECONDARY

Quantity specified for secondary allocations.

&ALLOCATION

Unit of secondary allocation: TRACKS, BLOCKS, or CYLINDER.

&BLKSIZE

Block size.

&LRECL

Record length, in bytes.

&TRKTOT

Total number of currently allocated tracks, spanning both primary and secondary allocation.

&EXTENTSUSED

Total number of currently allocated extents (max 16).

&BLKSPERTRK

Number of blocks (of BLKSIZE bytes) that can be written on to 1 track of the device.

&TRKSPERCYL

Number of tracks per cylinder for the device.

&CYLSPERDISK

Number of cylinders per disk for the device.

&BLKSWRITTEN

Total number of blocks in the data set, assuming that all blocks are BLKSIZE long.

&FOCUSPAGES

Posted only for FOCUS data sources. This number is the total number of 4096-byte pages in the data source. This is the same as the total number of pages shown by the ? FILE file name command. It is also the same as the highest page number shown by the ? FDT file name command. It does not include SHADOW pages and directory.

Syntax: How to Determine If a Database Exists: ? TSO DSNAME

Since you can logically erase an existing data set by issuing a CREATE command against it if it already exists, it is necessary to have a means of testing for the existence of a data set before issuing the CREATE command. Use the following command:

? {TSO|MVS} DSNAME datasetname

You supply the data set name. If you supply only the unqualified data set name, FOCUS will take the prefix from the profile to create a fully qualified data set name. Do not specify member names.

This command may also be executed from Dialogue Manager, allowing you to test whether a data set exists:

-? TSO DSNAME dsname

In this case, there is no output message. The system variable &RETCODE is set and must be tested for the outcome. The possible results follow:

&RETCODE Value

Equivalent FOCUS Code/Message

0
(FOC488) Dataset is in catalog:
4
(FOC489) Dataset is in catalog, but not on volume 
indicated:
8
(FOC490) Dataset is not in catalog:

Procedure: How to Estimate Data Set Sizes to Determine Available Space

You can use the file attribute information returned by the ? TSO ddname command to determine the number of records in the data set and to estimate how much available space is left on the currently allocated tracks. Keep in mind that the estimates obtained from the formulas that follow are only approximations and do not take into account space that was reused after it was logically vacated by deleted segments.

  • FOCUS data source formulas:
    Available pages (without additional extents) = BLKSWRITTEN -FOCUSPAGES
    BLKSWRITTEN = BLKSPERTRK x TRKTOT
  • Fixed-block data set formulas:
    RECSPERBLK = BLKSIZE/LRECL
    No. of records = BLKSWRITTEN x RECSPERBLK
    No. of free blocks = (TRKTOT x BLKSPERTRK) -BLKSWRITTEN
  • Variable-length blocked data sets:

    The formulas for fixed-block data sets (that is, FOCUS SAVE files) usually apply to variable-length blocked (VB) data sets as well: VB data sets usually have the same length blocks, even though the description implies otherwise.

Note: If SET SHADOW=ON, use the following formula:

(FOCUSPAGES x 2) + 3

Information Builders