gtpm2m12Migration Guide: Program Update Tapes

Resource Control (APAR PJ23178)

The following section discusses the migration considerations for resource control.

Prerequisite APARs

See the APEDIT for APAR PJ23178 for information about prerequisite APARs.

Functional Overview

Resource control provides:

You can do all of the previous by using the following new macros.

Macro Name
Description

 LODIC 
Check the system load and identify an entry control block (ECB) as a batch-type transaction.

 TMSLC 
Enable or disable time slicing for a transaction.

Architecture

New Supervisor Call (SVC) Service Routines

Two new macros, LODIC and TMSLC, are provided. They are SVC-type macros and have a corresponding macro service routine in the control program.

While running one of these macros, the service routine sets up the appropriate ECB fields, return conditions, or both. Control usually returns back to the application program through the common macro exit routine. However, sometimes the ECB does not receive control immediately and can be placed on a new list called the suspend list, in which case the system task dispatcher (CPU loop) is then entered. The suspend list is a CPU loop list that contains ECBs that have been suspended.

Once a LODIC macro has been run, after the ECB gives up control, the ECB will not get back control until enough system resources exist. Once a TMSLC macro has been run, an ECB can be forced to give up control at preset time intervals during processing to enable other system work to complete.

System Task Dispatcher Changes

A major change in functional flow has been made to the system task dispatcher (CPU loop) for all I-streams. A new list, called the suspend list, has been added. This list will function similarly to the virtual file access count (VCT) list.

ECBs that issue TMSLC or LODIC macros, or both, can be suspended at any point following the macro call. While suspended, these ECBs reside on a suspend list while other transactions are processed. The system task dispatcher will dispense from the suspend list in a fashion similar to the VCT list; that is, at equal priority to the input list but still dispatched during input list shutdown.

Application Timeout Changes

A new application timeout dump has been added that pertains only to ECBs that can be time sliced. This timeout will only occur if this type of ECB exceeded its maximum allowable CPU run time, which is never reset (even during a loss of control) while the ECB is marked as being able to be time sliced.

When an ECB issues a TMSLC macro, the ECB is enabled for time slicing and generally will not time out. Instead, the ECB is time-sliced and allows the system to perform other work. The time-sliced ECB can theoretically use an infinite amount of CPU time while giving up control at system-defined time intervals.

Other Changes

Two new commands for changing the LODIC and TMSLC run-time parameters have been added.

Command
Description

 ZSYSL 
Display or change priority class shutdown levels.

 ZTMSL 
Display or change time-slice attributes.

There are new data collection and data reduction fields, such as:

Operating Environment Requirements and Planning Information

There are none.

Interface Changes

The following section summarizes interface changes.

C/C++ Language

The following section summarizes C/C++ language changes. This information is presented in alphabetic order by the type of C/C++ language information. See the TPF C/C++ Language Support User's Guide and TPF Application Programming for more information about the C/C++ language.

Build Scripts

Table 169 summarizes changes to the build scripts used by the build tool. This information is presented in alphabetic order by the name of the build script.

Table 169. Changes to Build Scripts for Resource Control

Build Script Type New, Changed, or No Longer Supported? Description of Change
CTALBS DLM Changed Added new lodic_ext and tmslc C functions.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C Language Header Files

Table 170 summarizes the general use C language header file changes. This information is presented in alphabetic order by the name of the general use C language header file.

General use means these header files are available for your use.

Table 170. Changes to General Use C Language Header Files for Resource Control

General Use C Language Header File Target (TPF) ISO-C New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$cinfc.h X X Changed No
c$ck1ke.h X X Changed No
c$eb0eb.h X X Changed No
c$syseq.h X X Changed No
sysapi.h
X Changed No
tpfapi.h
X Changed No
tpfglb.h X X Changed Yes

Implementation-Specific C/C++ Language Header Files (IBM Use Only)

There are no changes.

Library Interface Scripts

Table 171 summarizes changes to the library interface scripts used by the library interface tool and the build tool. This information is presented in alphabetic order by the name of the library interface script.

Table 171. Changes to Library Interface Scripts for Resource Control

Library Interface Script New, Changed, or No Longer Supported? Description of Change
CTALXV Changed Added the CLODIC and CTMSLC library members.

Library Members (Object Files)

Table 172 summarizes the library member (object file) changes. This information is presented in alphabetic order by the name of the library member (object file).

Table 172. Changes to Library Members (Object Files) for Resource Control

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CLODIC CTAL New Assembler LODIC library function.
CTMSLC CTAL New Assembler TMSLC library function.

Link-Edited Modules

There are no changes.

Members (Object Files)

There are no changes.

Object Code Only (OCO) Stubs

There are no changes.

Configuration Constant (CONKC) Tags

There are no changes.

Control Program Interface (CINFC) Tags

Table 173 summarizes the control program interface (CINFC) tag changes. The information in this table is ordered numerically by the equate value.

Table 173. Changes to CINFC Tags for Resource Control

CINFC Tag Equate Value New, Changed, or No Longer Supported?
CMMLODIC 293 New
CMMTMSLC 294 New

Copy Members

Table 174 summarizes copy member changes. This information is presented in alphabetic order by the name of the copy member.

Table 174. Changes to Copy Members for Resource Control

Copy Member Type CSECT Where Copy Member Is Located New, Changed, or No Longer Supported? Description of Change
CAAA Control Program CCNUCL Changed Updated CP directory.
CAPE Control Program CCNUCL Changed Defined post-interrupt (PI) entry points for ECBs that can be suspended.
CAPT Control Program CCNUCL Changed Defined PI entry points for ECBs that can be suspended.
CCEB Control Program CCENBK Changed Added low-priority ECB checks to the file resident/core resident (FR/CR) program ENTER routine.
CCEC Control Program CCENBK Changed Added low-priority ECB check to the GETPC exit point.
CCED Control Program CCENBK Changed Added low-priority ECB check to the DLM enter routine.
CCE3 Control Program CCIISC Changed Updated the application timeout value in the PAUSC routine.
CCE4 Control Program CCIISC Changed Set up the resource control data in the SWISC CREATE transfer block.
CCE7 Control Program CCIISC Changed Included size of the suspend list in I-stream scheduling calculations.
CCIT Control Program CCNUCL Changed Added low-priority ECB checks to the TAPE PI routine. Added the PI subroutine for suspending low-priority and time-sliced ECBs.
CEDM Control Program CCMCDC Changed Added the macro decoder entry point for time-sliced ECBs.
CHSZ Control Program CCNUCL Changed Copied LODIC data from the ECB CREATE transfer block.
CICR Control Program CCNUCL Changed Added a low-priority ECB check to the ECB CREATE routine. Set up LODIC data in the ECB CREATE transfer block. Updated the ELLEC macro with the ability to unsuspend ECBs.
CICS Control Program CCNUCL Changed Added the LODIC and TMSLC macro service routines.
CLHL Control Program CCCLHR Changed Added code to the queue and an ECB to the suspend list. Added the suspend list PI routine.
CTME Control Program CCNUCL Changed Added application time-slice support to timer routines.
CT01 Control Program CCCTIN Changed Allocated storage for the new time-slice name table.
CT40 Control Program CCCTIN Changed Set up new LODIC shutdown table.
CUSR Control Program CCUEXT Changed Added new user exit support.

Fixed File Records

There are no changes.

Macros

The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.

Advanced Program-to-Program Communications (APPC) Macros

There are no changes.

Communication Macros and Statements

There are no changes.

Data Macros

Table 175 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 175. Changes to Data Macros for Resource Control

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
CK1KE Changed No
DCTPFX Changed No
DCTUCL Changed No
DLTEC Changed Yes
IDSXFC Changed Yes
ISUSP New Not Applicable
ITSNT New Not Applicable

General Macros

Table 176 summarizes the general macro changes. This information is presented in alphabetic order by the name of the general macro. See TPF General Macros for a complete description of all general macros.

Table 176. Changes to General Macros for Resource Control

General Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
LODIC New Not Applicable

Selected Equate Macros

Table 177 summarizes the selected equate macro changes. This information is presented in alphabetic order by the name of the selected equate macro.

Table 177. Changes to Selected Equate Macros for Resource Control

Selected Equate Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CZ1SE Changed No
CZ4CP Changed No
IEQCE2 Changed No
SYSEQ Changed No

Structured Programming Macros (SPMs)

There are no changes.

System Initialization Program (SIP) Skeleton and Internal Macros (Inner Macros)

Table 178 summarizes the system initialization program (SIP) skeleton and internal macro changes. This information is presented in alphabetic order by the name of the SIP skeleton and internal macro. See TPF System Generation for a complete description of the SIP skeleton and internal macros. If the SIP skeleton and internal macro (inner macro) is changed, you must reassemble the SIP Stage I deck and run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

Table 178. Changes to SIP Skeleton and Internal Macros for Resource Control

SIP Skeleton and Internal Macro New, Changed, or No Longer Supported?
SKCTKA Changed
SPPGML Changed

System Initialization Program (SIP) Stage I Macros and Statements

There are no changes.

System Initialization Program (SIP) Stage II Macros

Table 179 summarizes system initialization program (SIP) Stage II macro changes. This information is presented in alphabetic order by the name of the SIP Stage II macro. See TPF System Generation for a complete description of the SIP Stage II macros. If IBMPAL is changed, you must run the system allocator (SALO) and load the new program allocation table (PAT) to the TPF 4.1 system.

Table 179. Changes to SIP Stage II Macros for Resource Control

SIP Stage II Macro New, Changed, or No Longer Supported?
IBMPAL Changed

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

Table 180 summarizes system macro changes. This information is presented in alphabetic order by the name of the system macro. See TPF System Macros for a complete description of all system macros.

Table 180. Changes to System Macros for Resource Control

System Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CINFC Changed No
ELLEC Changed No
IBMSVC Changed Not Applicable
TMSLC New Not Applicable
UXITC Changed No

System Macros (IBM Use Only)

Table 181 summarizes system macro changes that are for IBM use only. This information is presented in alphabetic order by the name of the system macro.

Table 181. Changes to System Macros (IBM Use Only) for Resource Control

System Macro (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CFMCC Changed Yes
CFMDC Changed Yes

Segments

Table 182 summarizes segment changes. This information is presented in alphabetic order by the name of the segment.

Table 182. Changes to Segments for Resource Control

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CAPC Real-Time Assembler Not Applicable Changed Updated the ZECBL command processing to allow for the display and dispatch of suspended ECBs.
CAPD Real-Time Assembler Not Applicable Changed Updated the ZECBL command with messages that support the display and dispatch of suspended ECBs.
CAPF Real-Time Assembler Not Applicable Changed Updated the ZECBL command with error messages related to attempts to display or dispatch suspended ECBs.
CLH1 Real-Time Assembler Not Applicable New Processes the ZSYSL command.
CTKO Real-Time Assembler Not Applicable Changed Added a call to the time-slice restart (CTMS) segment.
CTMS Real-Time Assembler Not Applicable New Initialized the time-slice name table during restart. Provides help support for the ZTMSL command.
CTMT Real-Time Assembler Not Applicable New Processes the ZTMSL command.
CVAB Real-Time Assembler Not Applicable Changed Added code to route the ZSYSL command to the CLH1 segment. Added code to route the ZTMSL command to the CTMT segment.
CVOO Real-Time Assembler Not Applicable Changed Updated the ZSTAT command with the U parameter specified to include the VCT list and the suspend list.
DCR2 Offline Assembler DCRS Changed Added new system error fields to the macro cross-reference table.
JCD4 Real-Time Assembler Not Applicable Changed Updated data collection to collect relevant resource control data.
JCS0 Real-Time Assembler Not Applicable Changed Updated data collection to collect relevant resource control data.
JRA1 Offline PL/I DATAREAD Changed Updated data reduction to use relevant resource control data.
JRA2 Offline PL/I DATAREAD Changed Updated data reduction to use relevant resource control data.
JRA3 Offline PL/I DATAREAD Changed Updated data reduction to use relevant resource control data.
JRS3 Offline PL/I DATAREAD Changed Updated data reduction to use relevant resource control data.

System Equates

The following section summarizes system equate changes.

SYSEQ Tags

Table 183 summarizes changes to equates that are not configuration dependent (in SYSEQ). This information is presented in alphabetic order by the name of the SYSEQ tag.

Table 183. Changes to SYSEQ Tags for Resource Control

SYSEQ Tag Equate Value New, Changed, or No Longer Supported?
#TMSLTAB 118 New

User Exits

Control Program (CP) User Exits and ECB User Exits summarize the control program (CP) and ECB user exit changes. See TPF System Installation Support Reference for a complete description of all user exits.

Control Program (CP) User Exits

This information is presented in alphabetic order by the name of the control program (CP) user exit.

Table 184. Changes to Control Program (CP) User Exits for Resource Control

Control Program (CP) User Exit Activated In User Routine Label New, Changed, or No Longer Supported? Description of Change
CTME (CCNUCL) UCCAPL New Called before issuing the 000010 or 00002010.
CCEB (CCENBK) CCED (CCENBK) CLHL (CCCLHR) UCCCREB Changed Called at the end of macro processing and before control is passed to the destination program for either an enter-type macro going to a core resident program or a BACKC macro coming from a core resident program.
CCEB (CCENBK) CCED (CCENBK) CLHL (CCCLHR) UCCFREB Changed Called at the end of macro processing and before control is passed to the destination program for either an enter-type macro going to a file resident program or a BACKC macro coming from a file resident program.
CICS (CCNUCL) UCCLODC New Called at the end of the LODIC macro processing routine.
CICS (CCNUCL) UCCSUSC New Called when determining if an ECB should be added to the suspend list or dispatched from the suspend list.
CLHL (CCCLHR) UCCSUSE New Called whenever an ECB that is marked as being able to be suspended is about to be suspended during CPU loop dispatch time.
CLHL (CCCLHR) UCCSUSP New Called whenever an item is taken from the suspend list and is about to be dispatched.
CICS (CCNUCL) UCCTMSL New Called at end of the TMSLC macro processing routine.

ECB User Exits

There are no changes.

Functional and Operational Changes

The following section summarizes functional and operational changes. This information is presented in alphabetic order by the functional or operational change.

See Appendix A, "PUT 2-15 Interface Changes by Authorized Program Analysis Report (APAR)" for a summary of functional and operational changes by APAR.

Commands

Table 185 summarizes command changes. This information is presented in alphabetic order by the name of the command. See TPF Operations for a complete description of all commands.

Attention: Changes to commands can impact any automation programs you are using in your complex.

Table 185. Changes to Commands for Resource Control

Command New, Changed, or No Longer Supported? Description of Change
ZECBL Changed Added the ability to display and dispatch suspended ECBs.
ZSTAT Changed Updated the ZSTAT command with the U parameter to include the VCT list and the suspend list.
ZSYSL New Display or change shutdown levels for LODIC priority classes.
ZTMSL New Display or change time-slice attributes. Add or remove a time-slice name from the time slice name table.

Messages and System Errors

Table 186 summarizes message (offline and online messages) and system error changes.

The message IDs or system error numbers are listed in numeric order preceded by their alphabetic prefix. Some offline and online messages do not have a standard message ID. For these, the messages are presented in alphabetic order based on the initial message text; or for those messages that begin with variable information, the initial message text that follows that variable information. See Messages (System Error and Offline) and Messages (Online) for a complete description of all messages and system errors.

Attention: Changes to offline messages, online messages, and system errors may impact any automation programs you are using in your complex.

Table 186. Changes to Messages and System Errors for Resource Control

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
000010 System Error Changed
00002010 System Error New
00002011 System Error New
00002012 System Error New
00002013 System Error New
00002014 System Error New
CTMS0001I Online New
CTMS0002W Online New
CTMS0003E Online New
CTMS0004E Online New
ECBL0008E Online No Longer Supported
ECBL0012I Online No Longer Supported
ECBL0014I Online New
ECBL0015I Online New
ECBL0016I Online New
ECBL0017E Online New
ECBL0018E Online New
STAT0009I Online No Longer Supported
STAT0011I Online New
SYSL0001I Online New
SYSL0002I Online New
SYSL0003I Online New
SYSL0004E Online New
SYSL0005E Online New
SYSL0006E Online New
SYSL0007E Online New
SYSL0008E Online New
SYSL0009E Online New
TMSL0001I Online New
TMSL0002I Online New
TMSL0003I Online New
TMSL0004I Online New
TMSL0005I Online New
TMSL0006E Online New
TMSL0007E Online New
TMSL0008E Online New
TMSL0009E Online New
TMSL0010I Online New
TMSL0011E Online New
TMSL0013E Online New
TMSL0014E Online New
TMSL0015E Online New

Performance or Tuning Changes

Resource control is used by application programmers to control system resources. Utilities and batch processes can be controlled automatically so they will not deplete system resources during peak periods and can maximize the use of available resources under varying system conditions.

Resource control adds the capability in the TPF 4.1 system to time slice CPU-intensive applications, forcing them to relinquish control after running for specified intervals of time. This will allow you to process other transactions.

Overall system performance can be improved by identifying low-priority batch-type jobs and using the LODIC macro to suspend these jobs automatically when system activity gets too high.

Likewise, you can use the TMSLC macro to increase overall system performance by using it to control CPU-intensive transactions.

Storage Considerations and Changes

There are no changes.

System Initialization Program (SIP) and System Generation Changes

Two new tables have been added to the TPF 4.1 system. The priority class table is associated with the LODIC macro. The time-slice name table is associated with the TMSLC macro.

Priority Class Table

One of the parameters used by the LODIC macro is the priority class parameter. Each LODIC priority class defines 5 shutdown values, one for each block type (CMB, ECB, FRM, IOB, SWB).

Resource control provides 4 predefined priority classes:

IBMHI and IBMLO are reserved for use by IBM.

See the LODIC macro in TPF General Macros and the ZSYSL command in TPF Operations for additional information on these 4 predefined priority classes.

As many as four additional priority classes (a total of eight) can be defined. These priority classes must be defined in the system before they can be used by the LODIC macro.

The LODIC priority class table is located in copy segment CICS of CSECT CCNUCL. It is built by CTIN from data in keypoint A.

To add additional priority classes, update the following segments:

Time-Slice Name Table

One of the parameters used by the TMSLC macro is the NAME parameter. Each time-slice name has four time-slice values associated with it, one for each of the following TMSLC attributes:

Resource control provides three predefined time-slice names:

You can define as many as 100 TMSLC names in the system. These names can be added, changed, or removed dynamically with the new ZTMSL command. See TPF Operations for more information about the ZTMSL command.

You can also code TMSLC names in the resource control restart segment (CTMS). resource control restart (CTMS) receives control during system restart. It rebuilds the time-slice name table in core from the time-slice name table on file. If the file copy has been corrupted, or has not yet been created, resource control restart uses the coded TMSLC names to rebuild both the file and core copies of the time-slice name table.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 187 summarizes changes to the publications in the TPF library. This information is presented in alphabetic order by the publication title. See the TPF Library Guide for more information about the TPF library.

Table 187. Changes to TPF Publications for Resource Control

Publication Title Softcopy File Name Description of Change
TPF C Language Support Reference Summary N/A Added the lodic, lodic_ext, and tmslc C functions.
TPF C Language Support User's Guide GTPCLU05 Added the lodic, lodic_ext, and tmslc C functions.
TPF Concepts and Structures GTPCON03 Added VCT list and suspend list information.
TPF General Macros GTPGEN05 Added the LODIC macro.
TPF Library Guide GTPDOC05 Updated with definitions for new terminology in the master glossary.
TPF Main Supervisor Reference GTPMSR05 Added information on the suspend list, on suspend processing of an entry, and on altering and displaying resource control values.
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about the messages and system errors that were added, changed, and no longer supported for resource control.
TPF Migration Guide: Program Update Tapes GTPMIG05 Updated with migration considerations for resource control.
TPF Operations GTPOPR05 Added the ZSYSL and ZTMSL commands and updated the ZECBL and ZSTAT commands.
TPF Program Development Support Reference GTPPDR05 Added a new dump label.
TPF System Installation Support Reference GTPINR05 Added 5 new user exits and updated 2 user exits.
TPF System Macros GTPSYS05 Added the TMSLC macro.
TPF System Performance and Measurement Reference GTPSPR05 Added new data collection and data reduction fields.

Host System Changes

There are changes to the offline data reduction job control language (JCL). The logical record length (LRECL) of STEMP must be increased from 248 bytes to 328 bytes, and the block size (BLKSIZE) of STEMP must be changed accordingly.

The LRECL of STEMPIS varies according to the number of I-streams specified in JPC0, and will increase from 96 bytes for each I-stream to 128 bytes for each I-stream with the application of resource control. BLKSIZE must be changed accordingly.

SeeTPF Operations for an updated sample of JCL for offline data reduction for eight I-streams.

Application Programming Interface (API) Changes

Resource control includes one new general macro (LODIC), one new system macro (TMSLC), and three new C-library functions (lodic, lodic_ext, and tmslc). See TPF General Macros for more information about the LODIC and TMSLC macros. See the TPF C/C++ Language Support User's Guide for more information about the lodic, lodic_ext, and tmslc functions.

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

You can quickly verify that resource control has been installed by entering the following new commands:

Migration Scenarios

Adding resource control will have no impact on existing TPF 4.1 system or the applications on an existing TPF 4.1 system.

Investigate your current application and system program base to identify places where you have implemented your own forms of resource checking or time slicing. It may be to your advantage to remove any modifications you made and use the new macros that are provided by resource control.

Installing resource control requires allocation of:

Installation of resource control also requires a CP load.