gtpm2m0q | Migration Guide: Program Update Tapes |
The following section discusses the migration considerations for C function trace.
See the APEDIT for APAR PJ19422 for information about prerequisite APARs.
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.
To use C function trace you must:
C function trace increases the productivity of ISO-C users by:
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.
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.
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.
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.
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.
There are no hardware requirements.
The following section contains information about software requirements. Prerequisite software includes:
The following section summarizes interface changes.
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.
There are no changes.
There are no changes.
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 |
There are no changes.
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. |
There are no changes.
There are no changes.
There are no changes.
There are no changes.
Although there are no changes to the control program interface (CINFC) tags, the following changes have been made in the CINFC area:
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. |
There are no changes.
The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.
There are no changes.
There are no changes.
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 |
There are no changes.
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 |
There are no changes.
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 |
There are no changes.
There are no changes.
There are no changes.
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 |
There are no changes.
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. |
There are no changes.
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.
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. |
There are no 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.
The following section summarizes functional and operational changes. This information is presented in alphabetic order by the functional or operational change.
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.
|
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 |
The following changes have been made for C function trace.
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.
There are no changes.
There are no changes.
There are no changes.
There are no 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. |
There are no changes.
There are no changes.
There are no changes.
There are no changes.
There are no changes.
A migration scenario follows here that you should consider when using C function trace.
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.
Notes: