gtpm2m0qMigration Guide: Program Update Tapes

C Function Trace (APAR PJ19422)

The following section discusses the migration considerations for C function trace.

Prerequisite APARs

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

Functional Overview

C function trace provides tracing capabilities to 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. 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.

Migration Considerations

To use C function trace you must:

Increased Productivity for ISO-C Users

C function trace increases the productivity of ISO-C users by:

Postprocessor Control Program (PPCP)

The TPF 4.1 system now supports function names greater than 8 characters in length. A postprocessor control program (PPCP) that does not contain changes for function names greater than 8 characters in length cannot be used to post process a TPF dump tape from a TPF 4.1 system containing these function name changes.

C Function Trace Table

The C function trace table now accommodates function names greater than 8 characters in length. Therefore, you should investigate any user exit or non-IBM product that relies on the format of the C function trace table or the format of the output from this table to determine if any changes are required.

IBM C/C++ for MVS/ESA Version 3 Release 1 Compiler Function Entries

C function trace and ISO-C now support the IBM C/C++ for MVS/ESA Version 3 Release 1 compiler function entries.

Question marks (?????????) in the FUNCTION name field of the C function trace dump output indicate that C function trace code cannot determine the function name. Question marks (?????????) in the ISO-C STACK FRAME FUNCTION field of the ISO-C dump output indicate that ISO-C code cannot determine the function name.

For C function trace, the ICID_FUNL IDSCID DSECT field contains the length of the function name. Previously, this field contained the address of the function name length.

Architecture

Most of the changes to the TPF 4.1 system for C function trace are modifications to existing CP segments and modules written in assembler language. The remainder are written in the PL/I language for data collection and reduction.

Operating Environment Requirements and Planning Information

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

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. 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 52 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 52. Changes to General Use C Language Header Files for C Function Trace

General Use C Language Header File TARGET (TPF) ISO-C New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$ck1ke.h X X Changed No

Library Interface Scripts

There are no changes.

Library Members (Object Files)

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

Table 53. Changes to Library Members (Object Files) for C Function Trace

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CTRINT CISO Changed Object-Only Added logic for C function trace initialization.

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, the following changes have been made in the CINFC area:

Copy Members

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

Table 54. Changes to Copy Members for C Function Trace

Copy Member Type CSECT Where Copy Member Is Located New, Changed, or No Longer Supported? Description of Change
CAAA Control Program CCNUCL Changed Add C function trace comments.
CAPT Control Program CCNUCL Changed Support C function trace.
CHSZ Control Program CCNUCL Changed Initialize C function trace ECB data.
CIS1 Control Program CCISOC Changed C function trace environment data and support.
CLHV Control Program CCSTOR Changed Handle GSTACK frames.
CPSE Control Program CCCPSE Changed Save extended trace indicator byte.
CPSL Control Program CCCPSE Changed Change system error dump to format C function trace structures.
CT00 Control Program CCCTIN Changed Get maximum heap size from CTKA.
CTRY Control Program CCISOC New C function trace other breakpoint skeleton routine.
CTR0 Control Program CCISOC New C function trace exception routine.
CTR1 Control Program CCISOC New C function trace Debug Interface Module (DIM) routine.
CTR2 Control Program CCISOC New C function trace entry and exit breakpoint routine.
CTR3 Control Program CCISOC New C function trace update CID fields.
CTR8 Control Program CCISOC New C function trace SETTC service routine.
CTR9 Control Program CCISOC New C function trace ENATC service routine.
CUSR Control Program CCUEXT Changed New user exits support for C function trace.

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

Table 55. Changes to Data Macros for C Function Trace

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

General Macros

There are no changes.

Selected Equate Macros

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

Table 56. Changes to Selected Equate Macros for C Function Trace

Selected Equate Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CZOCP Changed No
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 57 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 Stgae I deck and run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

Table 57. Changes to SIP Skeleton and Internal Macros for C Function Trace

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 58 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 58. Changes to System Macros for C Function Trace

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

System Macros (IBM Use Only)

There are no changes.

Segments

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

Table 59. Changes to Segments for C Function Trace

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CCISOC CSECT CPS0 Changed ISO-C support services updated for C function trace.
CVOJ Real-Time Not Applicable Changed C function trace parameters for the ZSTRC commnd.
JRA1 Offline PL/I DATAREAD Changed Added C function trace options at start to output.
JRA3 Offline PL/I DATAREAD Changed Added C function trace options at end to output.
STPP Offline PPCP Changed Added support for C function trace.

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 60. Changes to Control Program (CP) User Exits for C Function Trace

Control Program (CP) User Exit Activated In User Routine Label New, Changed, or No Longer Supported? Description of Change
CDEB UCCCDEB New Customize the environment before it is set up for C function trace.
CEXP UCCCEXP New Initialize storage after the user trace area storage is allocated.
CTRC UCCCTRC New Allows you to insert additional trace data into the user data area.

ECB User Exits

There are no changes.

Data Collection Changes

There are no new data collection functions and no new data reduction reports for C function trace. However the Environment Summary Report indicates when C function trace, stack and static options are active at the start and end of data collection. See TPF System Performance and Measurement Reference for an example of the Environment Summary Report.

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.

Commands

Table 61 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 61. Changes to Commands for C Function Trace

Command New, Changed, or No Longer Supported? Description of Change
ZSTRC Changed This command now supports the following parameters.

CDEBUG
Enables C function trace for ISO-C programs compiled using the TEST option of the compiler.

NOCDEBUG disables C function trace for ISO-C programs compiled using the TEST option of the compiler.

STACK
Places up to 68 bytes of the C function stack data in the trace table when CDEBUG is active. The information is displayed in the dump.

If you specify NOSTACK, only the address of the stack area is placed in the trace table when CDEBUG is active.

If CDEBUG is not active, STACK or NOSTACK will not trace any information.

STATIC
Places up to 68 bytes of the C function static data in the trace table when CDEBUG is active. The information is displayed in the dump.

If you specify NOSTATIC, only the address of the static area is placed in the trace table when CDEBUG is active.

If CDEBUG is not active, STATIC or NOSTATIC will not trace any information.

Messages and System Errors

Table 62 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 62. Changes to Messages and System Errors for C Function Trace

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
STRC0001I Online No Longer Supported
STRC0002I Online No Longer Supported
STRC0003I (Replaces STRC0001I) Online New
STRC0004I (Replaces STRC0002I) Online New

Performance or Tuning Changes

The following changes have been made for C function trace.

Performance

There is an impact to performance for C function trace. However, it is possible to completely override the support for a given C module, eliminating the impact. This can be done by either:

C function trace results in a longer instruction path for the ECB. The increase in instructions may cause a system error CTL-000010 (an ECB-control program (CP) has been operating for 500MS). If this occurs, you can deactivate C function trace or issue a DEFRC or DLAYC macro in the CTRC user exit to give up ECB control.

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 63 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 63. Changes to TPF Publications for C Function Trace

Publication Title Softcopy File Name Description of Change
TPF Application Programming GTPAPP03 Brief overview of C function trace.
TPF Library Guide GTPDOC03 Updated with definitions for new terminology in the master glossary.
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 C function trace.
TPF Migration Guide: Program Update Tapes GTPMIG03 Updated with migration considerations for C function trace.
TPF Operations GTPOPR03 Updated with information about the commands that were added and changed for C function trace.
TPF Program Development Support Reference GTPPDR03 Tracing examples added.
TPF System Generation GTPSYG03 Installation parameters changed.
TPF System Installation Support Reference GTPINR03 User exits added.
TPF System Macros GTPSYS03 Macros added.
TPF System Performance and Measurement Reference GTPSPR03 Updated Environment Summary Report.

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

A migration scenario follows here that you should consider when using C function trace.

  1. Any C programs that you want to trace must be compiled with the TEST option of one of the IBM SAA AD/Cycle 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 TCA and initialized to be a no-operation instruction.

    You can generate breakpoints at various points in your program by specifying different compiler options. However, IBM recommends using the NOBLOCK suboption. If the BLOCK suboption is specified, C function trace results are unpredictable.

  2. Include the C function trace APAR.
  3. Relink the C programs that you want to trace with C function trace.
  4. Establish the trace environment, which is used throughout the life of an ECB:
    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 desired.

    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.
  5. 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.