gtpm2m19Migration Guide: Program Update Tapes

Trace Information in the C Function Trace Table (APAR PJ23493)

The following section discusses the migration considerations for APAR PJ23493.

Prerequisite APARs

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

In addition, APAR PJ23651 and APAR PJ23900 are additional prerequisite APARs for APAR PJ23493. The CCCPSE segment must be assembled using macro libraries for APAR PJ23651, APAR PJ23900, APAR PJ23493, as well as their prerequisite APARs. See the APEDITs for APAR PJ23651 and APAR PJ23900 for a list of those prerequisite APARs.

Functional Overview

APAR PJ23493 provides trace information in the C function trace table for breakpoints other than program entry breakpoints and program exit breakpoints.

Use C function trace to trace ISO-C programs that have been compiled using the TEST option of one of the IBM C/370 family of compilers supported by the TPF 4.1 system. C function trace provides relevant information to help analyze C program problems, therefore reducing the development cycle of these C programs.

C function trace uses breakpoints generated by the compiler when a program is compiled using the TEST option. Breakpoints are grouped into types, for example, program entry, program exit, and others.

After implementing C function trace, ISO-C users have the ability to trace C internal functions, dynamic link modules (DLMs), and C library functions using commands, TPF macros, or unique user exit routines.

Architecture

Most of the changes to the TPF 4.1 system for C function trace and APAR PJ23493 are modifications to existing control program (CP) segments and modules written in assembler language. There also are changes to modules written in PL/I for data reduction.

Operating Environment Requirements and Planning Information

To ensure that your TPF 4.1 system performs correctly with APAR PJ23493, you must establish the required operating environment. The following section describes hardware and software requirements specific to APAR PJ23493.

Operating Environment Requirements and Planning Information provides information about the minimum system configuration requirements that are necessary to operate the TPF 4.1 system. You may find it helpful to review that chapter along with the following information.

Hardware

There are no hardware requirements.

Software (Programming Requirements)

The following section contains information about software requirements for APAR PJ23493. Prerequisite software includes:

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

There are no changes.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C Language Header Files

Table 247 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 247. Changes to General Use C Language Header Files for APAR PJ23493

General Use C Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$ck1ke.h Changed No

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

There are no changes.

Library Interface Scripts

There are no changes.

Library Members (Object Files)

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

Table 248. Changes to Library Members (Object Files) for APAR PJ23493

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CLMINT CISO Not Changed Assembler Although CLMINT was not changed, the IDSCID DSECT was changed so CLMINT must be assembled and linked.
CTRINT CISO Changed Object-Only CTRINT was changed to support breakpoints other than program entry breakpoints and program exit breakpoints.

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

Although there are no changes to the control program interface (CINFC) tags, APAR PJ23493 changed the CINFC area as follows:

Copy Members

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

Notes:

  1. APAR PJ23651 and APAR PJ23900 are additional prerequisite APARs for APAR PJ23493. The CCCPSE segment must be assembled using macro libraries for APAR PJ23651, APAR PJ23900, APAR PJ23493, as well as their prerequisite APARs. See the APEDITs for APARs PJ23651 and PJ23900 for a list of those prerequisite APARs.

  2. CCCTIN copy members use macros that were changed by APAR PJ23493. CCCTIN must be assembled using APAR PJ23493 and its prerequisite APARs.

  3. CCENBK copy members use macros that were changed by APAR PJ23493. CCENBK must be assembled using APAR PJ23493 and its prerequisite APARs.

Table 249. Changes to Copy Members for APAR PJ23493

Copy Member Type CSECT Where Copy Member Is Located New, Changed, or No Longer Supported? Description of Change
CAPT Control Program CCNUCL Changed System nucleus. Added a comment to define a bit for C function trace of other breakpoints.
CIS1 Control Program CCISOC Changed CP routine addresses. Added C function trace data and support for tracing of other breakpoints.
CTRY Control Program CCISOC Changed C function trace other breakpoint routine. Added support to trace other breakpoints.
CTR0 Control Program CCISOC Changed C function trace exception routine. Added support to trace other breakpoints.
CTR1 Control Program CCISOC Changed C function trace debug interface module (DIM) routine. Added support to trace other breakpoints.
CTR2 Control Program CCISOC Changed C function trace program entry and program exit routine. Added support to trace other breakpoints.
CTR3 Control Program CCISOC Changed C function trace update CID fields routine. Added support to trace other breakpoints.
CTR8 Control Program CCISOC Changed C function trace SETTC service routine. Added support to trace other breakpoints.
CTR9 Control Program CCISOC Changed C function trace ENATC service routine. Added support to trace other breakpoints.
CUSR Control Program CCUEXT Changed User exit routines. Changed the CTRC user exit to support other breakpoints.

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 250 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 250. Changes to Data Macros for APAR PJ23493

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
CK1KE Changed No
IDSCID Changed Yes
IDSCTO Changed Yes
IDSCTR Changed Yes
IDSTCA Changed Yes

General Macros

There are no changes.

Selected Equate Macros

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

Table 251. Changes to Selected Equate Macros for APAR PJ23493

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

Structured Programming Macros (SPMs)

There are no changes.

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

Table 252 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 252. Changes to SIP Skeleton and Internal Macros for APAR PJ23493

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

System Initialization Program (SIP) Stage I Macros and Statements

There are no changes.

System Initialization Program (SIP) Stage II Macros

There are no changes.

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

Table 253 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 253. Changes to System Macros for APAR PJ23493

System Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CFMCC Changed Yes
GNAMC Changed Yes

System Macros (IBM Use Only)

There are no changes.

Systems Network Architecture (SNA) Communication Macros and Statements

There are no changes.

Segments

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

Table 254. Changes to Segments for APAR PJ23493

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CVOJ Real-Time Assembler Not Applicable Changed Added the C function trace XHOOKS parameter for the ZSTRC command to trace other breakpoints.
ICDF Real-Time Assembler Not Applicable Not Changed Although this segment was not changed, the CFMCC macro was changed so the ICDF segment must be assembled.
JRA1 Offline DATAREAD Changed Added the value of the C function trace XHOOKS parameter on the ZSTRC command at the start of data collection to data collection output.
JRA3 Offline DATAREAD Changed Added the value of the C function trace XHOOKS parameter on the ZSTRC command at the end of data collection to data collection output.
STPP Offline PPCP Changed Added support for C function trace of other breakpoints.

System Equates

There are no changes.

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 255. Changes to Control Program (CP) User Exits for APAR PJ23493

Control Program (CP) User Exit Activated In User Routine Label New, Changed, or No Longer Supported? Description of Change
CTRC UCCCTRC Changed Added the ability for you to insert additional trace data into the C function trace user area for breakpoints other than program entry breakpoints and program exit breakpoints.

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 256 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 256. Changes to Commands for APAR PJ23493

Command New, Changed, or No Longer Supported? Description of Change
ZSTRC Changed This command now supports the XHOOKS parameter, which enables the C function trace of breakpoints other than program entry breakpoints and program exit breakpoints for ISO-C programs compiled using the TEST option of one of the IBM C/370 family of compilers supported by the TPF 4.1 system.

The NOXHOOKS parameter disables the C function trace of breakpoints other than program entry breakpoints and program exit breakpoints for ISO-C programs compiled using the TEST option of one of the IBM C/370 family of compilers supported by the TPF 4.1 system.

If the CDEBUG parameter is not active, the ZSTRC command with the XHOOKS parameter specified does not trace any information.

Messages and System Errors

Table 257 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 message, online messages, and system errors may impact any automation programs you are using in your complex.

Table 257. Changes to Messages and System Errors for APAR PJ23493

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
STRC0003I Online No Longer Supported
STRC0004I Online No Longer Supported
STRC0005I Online New; replaces STRC0003I
STRC0006I Online New; replaces STRC0004I

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

There are no changes.

System Initialization Program (SIP) and System Generation Changes

There are no changes.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 258 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 258. Changes to TPF Publications for APAR PJ23493

Publication Title Softcopy File Name Description of Change
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about messages and system errors that were added, changed, and no longer supported for APAR PJ23493.
TPF Migration Guide: Program Update Tapes GTPMIG06 Updated with migration considerations for APAR PJ23493.
TPF Operations GTPOPR06 Updated with information about the new XHOOKS parameter of the ZSTRC command for APAR PJ23493.
TPF Program Development Support Reference GTPPDR06 Added examples for the new format of C function trace output., as well as examples for tracing breakpoints other than program entry breakpoints and program exit breakpoints.
TPF System Installation Support Reference GTPINR06 Updated the description of the CTRC user exit.
TPF System Macros GTPSYS06 Updated the description of the SETTC and ENATC macros.
TPF System Performance and Measurement Reference GTPSPR06 Updated the environment summary information.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

There are no changes.

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

Use the following procedure when using APAR PJ23493.

  1. Ensure Program Update Tape (PUT) 5 is installed on your TPF 4.1 system so you have the C function trace level code available to support the E-type loader.
  2. Compile any ISO-C programs that you want to trace using the TEST option of one of the IBM C/370 family of compilers supported by the TPF 4.1 system.

    When you compile a program with the TEST option, the compiler generates a breakpoint (an EX instruction with a hook statement as its subject instruction). The hook statement is stored in the task control area (TCA) and initialized to be a no-operation instruction.

    You can generate breakpoints at various points in your ISO-C program by specifying different compiler options.

  3. Ensure that APAR PJ23493, APAR PJ23651, and APAR PJ23900, as well as their prerequisite APARs are applied to your TPF 4.1 system.
  4. Relink the ISO-C programs that you want to trace using C function trace.
  5. Establish the trace environment, which is used throughout the life of an entry control block (ECB) by doing the following:
    1. Create a new image, if appropriate.
    2. Load the program with the auxiliary loader (TLDR) to the appropriate image.
    3. Set the trace options by entering the ZSTRC command at a system level or using the SETTC and ENATC macros for a specific ECB.
    4. Change the trace table storage size using the SETTC macro, if appropriate.

    Notes:

    1. After taking these preliminary steps, C function trace is started when an active break is issued by an ECB for the first time.

    2. Subsequent attempts to alter or reset the trace environment using the SETTC macro or the ZSTRC command have no effect on the currently running ECB.

    3. You can stop and start C function trace at any time using the ENATC macro.

    4. You can also provide unique code at the C function trace user exits (UCCCDEB, UCCCEXP, and UCCCTRC) to customize your trace output.
  6. Postprocess the tape to obtain trace data.
    Note:
    Before you postprocess your dumps, code the region size as 3 M on the JCL for the postape PPCP. Then, assemble PPCP in step SIP13B of the SIP II job execution.