File Definition Services function

This topic describes planning considerations for the ThruPut Manager Files. The space and allocation techniques are described.

Introduction

This topic provides all the information required to implement the supporting files that ThruPut Manager requires. The chapters describing the ThruPut Manager Functions indicate which files they require, if any.

File to Function Cross Reference

The following table shows the relationship between ThruPut Manager functions and ThruPut Manager files: 

The Control File

Job Setup Services and the optional components Job Binding Services, Job Limiting Services, Job Chaining Services, and Dataset Contention Services require the ThruPut Manager Control File to be active. Note that the Control File is a critical resource. Access times to this file can impact the overall performance of the system.

Implementation Summary

The steps for implementing the Control File are:

• Find a device that delivers good to excellent service times.
• Allocate the file with 64 cylinders of 3380 or 3390 space.
  • If you are using DCS across multiple JESplexs, allocate one Control File per JESplex.
• Add the FILE CF statement to the TMSS initialization statements.
  • If you are using DCS, add the XCF(ON) keyword to the DCS SET initialization statement.
• Start TMSS using the COLD parameter for CF.
• Confirm the TMSS formatting request by replying 'Y'.

FILE CF Initialization Statement

The FILE CF statement must be included in your TMSS initialization statements. The format of this statement is documented in TMSS Initialization Statements.

Control File Structure

For the JSS application, the Control File contains information necessary to manage the JSS Hold Extensions. For applications such as JBS and JLS, the Binding Agents, Limiting Agents, and all the necessary information to manage the jobs dependent on these Agents are stored in the Control File.

The conceptual structure of the Control File is simple. It is organized into three distinct but related areas. Here is a schematic representation of the file:

The first area contains information describing the file. For example, file size, number of applications, parameters such as MAXDORM, and other items required to manage the file are stored in this area.

The second area maintains all the information required to coordinate the relationship between ThruPut Manager held jobs and JES2. All the necessary information to synchronize JES2 and ThruPut Manager is contained here. The link between JES2 and the specific application is also contained in here.

The third area is where the application-specific information is kept. There is one section per application.

Each application section contains all the detail information to control the jobs receiving its services. For example, in the case of JSS the information needed to hold and release jobs automatically is contained in the JSS application section. For JBS, the Agents that have been defined are stored in the JBS application section, and as the relationships between jobs and Agents evolve, the necessary connections are also kept here. Similar relationships exist for each application using the Control File.

Note: The Control File is a high performance file and should be placed in a device that can deliver good to excellent service times. It requires 64 cylinders of a 3380 or 3390 device. The file access algorithms have been optimized for a cylinder boundary allocation.

Allocating the CF

You can use any convenient technique to allocate this file. Here is a typical DD statement allocating the Control File:

//CF      DD   DSN=cf.filename,DISP=(,CATLG),
//             SPACE=(CYL,64,,CONTIG),UNIT=unitname

This JCL is self-explanatory.

No other allocation parameters are required.  

The file must be cataloged.

The name of the file you chose must be then included in the FILE CF initialization statement.

CF and Performance

The control file must be placed on a device that provides good to excellent service times. Access to the file has been optimized for a cylinder boundary.

The MINDORM, MAXDORM, and MINHOLD keywords are provided to ensure that all systems sharing the file can have access to it. The use of these values is similar to the equivalent parameters in JES2.

ThruPut Manager also supports a MAXHOLD keyword that allows you to specify the maximum time a system can HOLD the Control File. MAXHOLD is intended to control JESplex members that do not run much (or any) batch work. It is a requirement that ThruPut Manager be running on all members of the JESplex but it is not desirable that these non-batch members interfere with Control File activity by any unnecessary accesses.

A recommended set of time values for a quiet or non-batch member is:

This allows the member to be responsive if any activity originates from that member, such as a job arriving or a VARY ONLINE command being issued. Yet it will only access the Control File once every 2 minutes otherwise, and will release it immediately if no work is to be processed.

If your JES2 checkpoint is in OS/390 R4 mode, the DEPTH keyword allows you to control how many JES2 action requests can be queued before ThruPut Manager waits.

These keywords can be specified on the FILE CF initialization statement or on a CFM SET initialization statement within a FOR group. Additionally, these parameters can be changed with the /CFM SET operator command.

For synchronization purposes, the SYNCTOL value of JES2 is used.

 CF and Resource Hold

If you are running JES2 in OS/390 R4 mode, WLM accounts for jobs held by JBS and JLS in the "operator hold" category, which might not be desirable. You can change this behavior by using the /CFM SET RESOURCEHOLD operator command:

RESOURCEHOLD is OFF by default. When it is set to ON, ThruPut Manager prevents JBS and JLS jobs from running by temporarily removing the system affinity. WLM therefore accounts for the delay in the "lack of resource" category.

RESOURCEHOLD can be turned OFF at any time. Affected jobs are returned to the normal ThruPut Manager hold category. If any image of ThruPut Manager must revert to a level without RESOURCEHOLD support, or if any JES2 is UNACTIVATED to pre-R4 mode, you must set RESOURCEHOLD to OFF before reverting to the earlier level.

Formatting the CF

The first time that the Control File is used, TMSS automatically formats the file. TMSS

always asks for confirmation before formatting the Control File.

Note that this takes place only if the FILE CF initialization statement is present.

Note: The contents of this file are critical. Make sure that operating procedures are in place to take care of problems with this file. Only one system should be active at the time this file is formatted.

A complete description of the operational procedures for formatting the Control File, or if necessary, the individual application areas of the Control File, is contained in the Operating Guide.

CF and RESERVE

For performance reasons, do not allow the Control File RESERVE to be converted to a GLOBAL ENQ or propagated as a GLOBAL ENQ. If your installation is using GRS or a similar means of propagating ENQs, do not include the CF RESERVE in the RESERVE conversion RNL, but include it in the SYSTEMS exclusion RNL. The qname used by ThruPut Manager for the CF RESERVE is TMRMCF. The rname is formed by the data set name, padded with blanks to 44 characters, followed by the serial number of the volume containing the Control File.

Sharing the Control File

For each JES2 node, you must share the Control File among all systems that comprise the node.

Do not share the Control File across JES2 nodes. Use multiple Control Files, one per node.

In systems with DCS, use the DCS SET initialization statement to activate XCFM support for cross-systems communications:

Note that ThruPut Manager does not allow two active nodes with the same name.

The Control File Utility

The Control File Manager uses area sizes and boundaries optimized either for a 3380 or a 3390 device, depending on the allocation.

Note: To move the Control File to another area or another device you must use the Control File Utility.

The utility DTMCFMUn (where n represents the current ThruPut Manager release number) provides the necessary facilities to move the Control File, and also to perform problem analysis and repair.

Installing and Running the Utility

The utility is installed with the Base Product under the name DTMCFMUn. This utility can be used for the following purposes:

• To move the file to another area on disk, or to a different device type.
• To produce a formatted dump.

For the move function, you should allocate space for the new Control File. You can use any standard allocation technique. 64 cylinders are needed for a 3380 or 3390, regardless of the device used. The allocation should be on a cylinder boundary and on a device that provides good to excellent service times.

To run DTMCFMUn, you need one of the following sets of JCL. Shown on the next page are examples for copying the file, dumping the file, and for performing both tasks simultaneously.

 JCL to Copy the Control File

//Name     EXEC PGM=DTMCFMUn,PARM=COPY
//SYSPRINT DD   SYSOUT=*
//DTMRMCF  DD   DSN=name.of.the.control.file,DISP=OLD
//NEWRMCF  DD   DSN=name.of.the.new.file,DISP=(,CATLG),
//              SPACE=(CYL,64,,CONTIG),UNIT=unitname

 JCL to Dump the Control File

//Name     EXEC PGM=DTMCFMUn,PARM=DUMP
//SYSPRINT DD   SYSOUT=*
//DTMRMCF  DD   DSN=name.of.the.control.file,DISP=OLD
//DTMDUMP  DD   SYSOUT=*

 JCL to Copy and Dump the Control File

//Name     EXEC PGM=DTMCFMUn,PARM=SYSIN
//SYSPRINT DD   SYSOUT=*
//DTMRMCF  DD   DSN=name.of.the.control.file,DISP=OLD
//NEWRMCF  DD   DSN=name.of.the.new.file,DISP=(,CATLG),
//              SPACE=(CYL,64,,CONTIG),UNIT=unitname
//DTMDUMP  DD   SYSOUT=*
//SYSIN    DD   *
DUMP
COPY
/*

Analyzing and Repairing JBS and JLS Control Areas

If you suspect problems with the JBS or JLS control areas, or if you have encountered message DTM6603E, you can use DTMCFMUn to analyze and perhaps repair the damage. To do this, use one of the following PARMs on the EXEC statement:

This parameter requests an analysis of the JBS and JLS areas of the Control File, and produces a report that is directed to the data set described by the DD statement DTMRMUP.

This parameter performs the same functions as ANALYZE, and also writes a repaired copy of the Control File to a pre-allocated data set described by the DD statement NEWRMCF.

Note that if the REPAIR function terminates successfully, the resulting Control File will not contain errors, but information about some jobs might be lost. Examine the analysis report to determine which jobs might be affected.

Some examples of the JCL needed to perform analysis and repair are shown below.

 JCL to Analyze the Control File

//Name     EXEC PGM=DTMCFMUn,PARM=ANALYZE
//SYSPRINT DD   SYSOUT=*
//DTMRMCF  DD   DSN=name.of.the.control.file,DISP=SHR
//DTMRMUP  DD   SYSOUT=*

 JCL to Repair the Control File

//Name     EXEC PGM=DTMCFMUn,PARM=REPAIR
//SYSPRINT DD   SYSOUT=*
//DTMRMCF  DD   DSN=name.of.the.control.file,DISP=SHR
//NEWRMCF  DD   DSN=name.of.the.new.file,DISP=OLD
//DTMRMUP  DD   SYSOUT=*

The Volume Information File (VIF)

The VIF is a mandatory shared DASD file which tracks volumes that are being managed by JSS. The VIF is used to maintain information about volumes, including virtual volumes, and their status.

Implementation Summary

The steps for implementing VIF support are:

• Determine the approximate number of volumes that your installation will be tracking through the VIF. A formula is provided under the heading "Calculating VIF Capacity".
• Calculate the size of the file required. If you plan to write exits that use the user data area, include the size of the area (VSEG) in each record.
• Allocate the file.
• Add the FILE VIF statement to the TMSS initialization statements. If your installation wants to use the user data area, include the parameter. This field is accessible through installation exits only.
• Start TMSS using the COLD parameter for the VIF.
• Confirm the TMSS formatting request by replying 'Y'.

TMSS Initialization Statements

The VIF is a required file. It must be specified with the FILE VIF TMSS initialization statement. The size of the VIF depends on the number of volumes tracked, and the size of the user segment of the record. These parameters are specified using the TMSS FILE VIF statement documented in TMSS Initialization Statements.

VIF Size and Structure

The VIF file consists of a control record, followed by a number of volume records. The maximum number of volume records is defined by the ENTRIES parameter of the TMSS initialization statement FILE VIF.

A diagram of the structure of this file is shown below.

Volume Information File Structure

In the VIF:

• The control record indicates the number of volume records being used.
• A volume record contains information about one volume serial number:
  • The volume serial number.
  • The job that requested it.
  • The time of the request.
  • The status of the volume.
  • Installation data, if any. The size of the installation data area is defined by the VSEG parameter of the FILE VIF statement.

Allocating the VIF

The VIF can be allocated using any convenient technique. Here is a typical DD statement to allocate the file:

//VIF     DD  DSN=vif.filename,DISP=(,CATLG),
//            SPACE=(CYL,n,,CONTIG),UNIT=unitname

This JCL is self-explanatory.

Note that the number of cylinders required for the VIF depends on the space specified for installation data in the VSEG parameter of the FILE VIF statement. VIF records are 80 bytes long plus any installation data segment.

No other allocation parameters are necessary.

Calculating VIF Capacity

To calculate the space requirements for the VIF, use the following formula:

NumberOfTracks = [(NumberOf VolumesEntries x (80 + VSEG)) / 2] +1

Each individual volume used in a job occupies one volume entry, no matter how many references are made to the volume. If the volume is referred to in another job, however, it requires another volume entry. If you are using IBM Virtual Volumes, note that these volumes are added to the VIF.

The first track of the VIF is used to hold the control information, so one is added to the quotient of volumes divided by track capacity.

A single cylinder usually holds a VIF large enough for most installation's needs.

Formatting the VIF

The VIF characteristics are controlled through the TMSS initialization statement described above. The VIF is formatted automatically upon its first use, and any time VIF=COLD is specified when starting TMSS. If the VIF is moved to a different device type, the operator is informed and is given a choice to format the file.

TMSS always asks for operator conformation before formatting the VIF.

A complete description of the operational procedure for formatting the VIF is contained in the Operating Guide.

Moving the VIF

The VIF can be moved among identical device types. If it is necessary to move the file to a different device type, the VIF must be reallocated and formatted.

VIF and RESERVE

ThruPut Manager issues both a RESERVE and an ENQ for the VIF. For performance reasons, do not allow the VIF RESERVE to be converted to a GLOBAL ENQ or propagated as a GLOBAL ENQ. If your installation is using GRS or a similar means of propagating ENQs, do not include the VIF RESERVE in the RESERVE conversion RNL, but include it in the SYSTEMS exclusion RNL.

The qname used by ThruPut Manager for both the VIF RESERVE and ENQ is DTMVIF. The rname for the RESERVE is formed by the data set name, padded with blanks to 44 characters, followed by the serial number of the volume containing the VIF:

The rname for the ENQ is formed in the same way, but LOCK is appended to the volume serial number:

Sharing the VIF

The VIF should be shared across nodes. To allow JSS to hold and release all jobs depending on a particular volume, the VIF must be shared by all systems using the same set of volumes. If systems from multiple nodes share the VIF, each node must have a unique name.

SPOOL File

The SPOOL file serves a function for Console Printing Services that is similar to your JES2 Spool. It allows you to place DCS ALERTs in this file so that they can be printed by a single CPS WRITER, thus you only need one CPS printer for your MAS Complex. This file has been designed to be shared.

Spooling gives you flexibility to manage DCS ALERTs. ALERTs are spooled to the SPOOL File, from which they can be selected by a CPS Writer on any system sharing the file, providing that the CPS Writer's selection criteria are met.

Implementation Summary

The implementation steps for the SPOOL file are simple:

•  Determine the size of the SPOOL file. Refer to the discussion below.
• Allocate the file.
• Include the FILE SPOOL initialization statement in all systems.
• The first time it is used, code the TMSS start SPOOL=COLD parameter.
• Confirm the TMSS formatting request by replying 'Y'.

TMSS Initialization Statements

The SPOOL file is defined to TMSS with the FILE SPOOL initialization statement. The statement is described in TMSS Initialization Statements.

SPOOL File Size

The nature of the SPOOL File does not permit an exact calculation of its size. The following points may help in your space allocation decision:

• The minimum space occupied by one record is 1K, and most DCS ALERTs do not exceed this.

Allocating the SPOOL File

The SPOOL File can be allocated using any convenient technique. Typical JCL to allocate the file would include a DD statement such as:

//SPOOL   DD  DSN=spool.filename,DISP=(,CATLG),
//            SPACE=(CYL,n,,CONTIG),UNIT=unitname

This JCL is self-explanatory.

No other allocation parameters are necessary.

SPOOL File Limits

ThruPut Manager Spooling supports the following maximums:

• 32 systems
• 64 CPS Writers
• 128 Destinations
• 2048 slots for records

Formatting the SPOOL File

A newly defined SPOOL File is automatically formatted the first time it is used.

The data set is also formatted if TMSS is started using the SPOOL=COLD parameter. The first TMSS function to open the file triggers the formatting.

TMSS always asks for operator confirmation before formatting the SPOOL file.

A complete description of the operational procedure for formatting the SPOOL File is contained in the Operating Guide.

Note: When multiple CPU installations share a SPOOL File, formatting the file without proper synchronization causes errors. The severity of the error depends on the circumstances. Only one system should be active at the time the SPOOL File is being formatted.

SPOOL File Structure

The SPOOL File is a DASD file, consisting of a SPOOL Control Record and a record for each DCS Alert waiting to be printed. Once Alert is printed, its SPOOL record is purged. The data set is formatted with fixed length records.

SPOOL File Considerations

The following points about the SPOOL File should be noted:

• It is confined to a single volume.
• The primary allocation must contain sufficient space, since secondary allocation is not supported.
• All DASD devices supported by MVS are eligible for the SPOOL File except the 3340.
• The SPOOL File is completely portable among supported devices. It can be copied to a different device and used by ThruPut Manager without being reformatted.
• The qname used by ThruPut Manager for the SPOOL File RESERVE is DTMJBMQ.

SPOOL File and Reserve

For performance reasons, do not allow the SPOOL RESERVE to be converted to a GLOBAL ENQ or propagated as a GLOBAL ENQ. If your installation uses GRS or a similar means of propagating ENQs, do not include the SPOOL RESERVE in the RESERVE conversion RNL, but include it in the SYSTEMS exclusion RNL. The qname used by ThruPut Manager for the SPOOL RESERVE is DTMJBMQ. The rname is formed by the data set name, padded with blanks to 44 characters, followed by the serial number of the volume containing the SPOOL. file.

Sharing the SPOOL File

The SPOOL File can be shared across nodes. SPOOL File sharing should duplicate VIF sharing; that is, the SPOOL File should be shared by all systems using the same set of volumes. If systems from multiple nodes share the SPOOL File, each node must have a unique name.

The CMF File

This optional file is used exclusively by DCS to record contention records that are used by the management reports produced by DCS. This file is shared by all the systems that are part of the DCS complex.

Implementation Summary

The implementation steps for the CMF file are simple:

• Determine the size of the CMF file. Refer to the discussion on file size below.
• Allocate the file.
• Include the FILE CMF initialization statement.
• The first time the CMF file is used, DCS detects that the file has not been formatted. The formatting process is automatically initiated.
• Confirm the TMSS formatting request by replying 'Y'.

TMSS Initialization Statements

The CMF file is defined to TMSS with the FILE CMF initialization statement. The statement is described in TMSS Initialization Statements.

CMF File Size

The nature of the CMF File does not permit an exact calculation of its size. The following points may help in your space allocation decision:

• This file is a "wrap-around" file, that is, you do not run out of space. You can, however, lose the oldest data if the file wraps before you have collected the data for your reporting system.
• A "snap-shot" utility is provided to transfer the records from this shared file to another external file suitable for input to the management reporting system.
• One cylinder of a 3380/3390 device holds records for approximately 600 to 1000 jobs in contention. The precise number cannot be established because the number of data sets and TSO holders varies from situation to situation.
• This data is not critical so the consequences of losing some records should not be severe.
• Establish a cycle for data "unloading" (daily, weekly, ...) that suits your installation. Calculate the number of jobs that might run into contention during that cycle time, then double the space needed. This approach should provide you with a comfortable margin of error.

Allocating the CMF File

The CMF File can be allocated using any convenient technique. Typical JCL to allocate the file would include a DD statement such as:

//TMCMF    DD  DSN=cmf.filename,DISP=(,CATLG),
//             SPACE=(CYL,n,,CONTIG),UNIT=unitname

The JCL shown above is self-explanatory.

Formatting the CMF File

The data set is formatted if DCS detects that it has not been formatted. TMSS asks for operator confirmation before formatting the CMF file.

A complete description of the operational procedure for formatting the CMF File is contained in the publication Operating Guide.

CMF File Structure

The CMF File is a DASD file, consisting of an CMF Control Record and a variable number of data set contention records. The control record points to where the next record is to be written.

The structure of the file prevents the situation where you run out of space by using a "wrap-around" technique.

CMF File Considerations

The following points about the CMF File should be noted:

• It is confined to a single volume.
• The primary allocation must contain sufficient space, since secondary allocation is not supported.
• All DASD devices supported by MVS are eligible for the CMF File except the 3340.
• DCS formats it as follows:
  DSORG  PS
  RECFM  F
  LRECL  4096
• The CMF File is completely portable among supported devices. It can be copied to a different device and used by ThruPut Manager without being reformatted.

CMF File Sharing

CMF File sharing should duplicate Control File sharing; that is, the CMF File should be shared to include all systems in a particular JES2 node, and there should be one CMF file per JESplex.

The Automation File

The Automation File is required by DBS. It is shared among all systems in a JESplex. Installations with more than one JESplex will need one Automation File for each JESplex.

Automation Edition components use the Automation File to store Configurations and Policies. The Automation File is initialized and maintained using ISPF dialogs. When you define an Automation File for the first time, information describing the JESplex is collected. Since this description is used by other automation facilities, the Automation File for a particular JESplex needs to be created and initialized only once.

There are no performance considerations. You need only specify a volume that is shared across the JESplex. The ISPF dialogue performs the actual allocation and initialization. For details, see the Drive Booking Services: System Programming Guide.

Facilities Summary