z/TPF debugger and code coverage configuration file

The z/TPF debugger and code coverage configuration file is a JSON file that you can use to specify system-wide parameters for the z/TPF debugger and scriptable code coverage support.

Last updated

Changed in 2024.
Changed in 2023.
Changed in 2021 (information only; no code change).
Changed in 2020.
Added for PUT15.

Requirements and restrictions

Name the configuration file tpf_debugger.cfg.json and ensure that the file is loaded to the /etc directory on the z/TPF system in UTF-8 character encoding. Additionally, ensure that the UDUT_dbgcfg.lib.dfdl.xsd file is loaded to the z/TPF system as UTF-8 by using the online E-type loader or in binary format by using FTP. This file is used to serialize the configuration file.
Note: When you use FTP to load these files, you must transfer the file in binary format to maintain the UTF-8 character encoding. z/TPF FTP support converts ASCII data to EBCDIC format.
The format and syntax of this file must follow the JSON standards.
Element names must be exact in spelling and capitalization. Only elements that are listed in Table 1 can be read or validated on the z/TPF system.
If z/TPF DFDL parser enhancements for PUT 15 (APAR PJ45191) is applied to your z/TPF system, elements in the configuration file are order-independent. If the APAR is not applied, elements are order-dependent and must match the sequence in Table 1.

Element details

Table 1. z/TPF debugger and code coverage configuration file elements
Element name	Applicable version	Description
`version`	Version 1 or later	An unsigned short that determines the API level in use. The version number is increased when supported elements are added to this configuration file for a new service. The version must correspond to an existing API level on the z/TPF system. If you specify a lower version, the z/TPF system ignores the elements that are added for the services of higher API levels. For more information about each version number and its corresponding services, see Table 2.
`port`	Version 1 or later	The port number that is available for Linux® on IBM Z® to accept z/TPF REST calls.
`host`	Version 1 or later	A string that indicates the name of the host or the IP address where Linux on IBM Z is available to accept z/TPF REST calls. The string that you specify must not exceed 255 characters. If you want to specify a host name for this element, ensure that the host name is defined in the remote Domain Name System (DNS) server that the z/TPF system uses. If necessary, ask your system administrator for the addresses of the primary and secondary DNS servers, or use the ZDTCP command to define those DNS server addresses.
`tpfTKwebcontext`	Version 2 or later	The name of the .war file that provides web services. The name that you specify must not exceed 23 characters; the default value for this element is TPFToolkitServices.
`substitutePaths`	Version 1 or later	A string that specifies one or more pairs of a build path and its substitution path. This element is used to support builds that copy files to a different location after a successful build. Each pair has the following format: `build_path:substitute_path` where: `build_path` The fully qualified path on Linux on IBM Z where the program is built. `substitute_path` The fully qualified path on Linux on IBM Z that the code is moved to after a successful build. You can specify multiple pairs and separate pairs by using semicolons, for example: `build_path_1:substitute_path_1;build_path_2:substitute_path_2;…;build_path_n:substitute_path_n` The web application for TPF Toolkit services on Linux on IBM Z uses this element in the following cases: To locate source files when you choose to include source files in scriptable code coverage results For automatic load support for remote debug information For example, consider the following scenario: Your code is built in the /ztpf/build directory. If the build succeeds, the build moves the code to the /ztpf/cur directory. In this case, you can specify this element as `/ztpf/build:/ztpf/cur`. With this pair specified, the following conditions occur: During scriptable code coverage processing, if source files are to be included in code coverage results, the source files are retrieved from the successful build. With certain conditions met, the web application constructs the search path for the debug information based on this specified pair. For more information, see Automatic load support for remote debug information. You can use regular expressions to specify this element. For example, if your code is built in the /ztpf/build/20201216/0600/ directory and then moved to a permanent location /ztpf/test, you can specify this element as follows: `/ztpf/build/.?/.?:/ztpf/test` In this case, if the path of a source file in the initial build location is /ztpf/build/20201216/0600/base/rt/cuda.cpp, the resulting file path that the web application uses to locate the source file is /ztpf/test/base/rt/cuda.cpp. For scriptable code coverage processing, if an invalid or unavailable substitute path is specified, no error is issued, and processing continues, but source files are not included in the generated code coverage results. For automatic load support for remote debug information, if an invalid or unavailable substitute path is specified, or if the debug information is not found, the web application uses the `rootDir` element to locate the debug information.
`rootDir`	Version 2 or later	One or more fully qualified paths that are separated with a semicolon. Each path represents a root directory on Linux on IBM Z for the web application to recursively search for debug information. For example, if you specify this element as `/ztpf/cur;/ztpf/commit`, with certain conditions met, the web application searches for debug information in the /ztpf/cur directory and its subdirectories and then in the /ztpf/commit directory and its subdirectories. For more information, see Automatic load support for remote debug information.
`traceLogDirectory`	Version 3 or later	The fully qualified path of the directory where trace log results are stored on the z/TPF system. For example, you can specify `"traceLogDirectory" : "/traceLog"`. If the specified path does not exist, the directory will be automatically created with the correct permissions. The read, write, and execute permissions to this directory must be granted to all members.
`secure`	Version 4	One of the following values: true Enables secure z/TPF REST connections to Linux on IBM Z for automatic source lookup and remote debug information. If this element is set to true, you must also update the `port` element to use the secure port that the Apache Tomcat server uses. false Disables secure z/TPF REST connections to Linux on IBM Z for automatic source lookup and remote debug information. For version 5 or later, the `secure` element is no longer required. The z/TPF debug server definition, which is created by using the ZINET ADD command, determines whether to use secure z/TPF REST connections to Linux on IBM Z. If you specify the `secure` element in the configuration file, it will be ignored. If the z/TPF debug server is defined to use secure connections, you must also update the `port` element to use the secure port that the Apache Tomcat server uses.

Table 2. Version numbers and corresponding services
Version number	Corresponding services
1	Scriptable code coverage services
2	Remote debug information
3	REST services for trace log data
4	Secure z/TPF REST connections to Linux on IBM Z for automatic source lookup and remote debug information
5	Secure z/TPF debug support

Additional information

When a REST service that requires this configuration file is called, the contents of the configuration file are read into memory for the z/TPF debugger and scriptable code coverage support to use.
If an element cannot be validated, processing of the file continues, an error message is displayed to the z/TPF console, and all element values in memory are changed to unset.
If the configuration file is not found, all element values are cleared from memory.
To clear element values from memory, take one of the following actions:
- Load a configuration file with any or all elements that are specified with an empty string.
- Remove the configuration file by entering the following command:
  zfile rm /etc/tpf_debugger.cfg.json

Examples

The following example shows a z/TPF debugger and code coverage configuration file.

{
    "version":"5",
    "port":"8080",
    "host":"linuxtpf.pok.ibm.com",
    "tpfTKwebcontext": "TPFToolkitServices",
    "substitutePaths" : "/ztpf/bld:/ztpf/commit;/ztpf/blddrv:/ztpf/commitdrv",
    "rootDir" : "/ztpf/cur;/ztpf/commit;/ztpf/curdrv;/ztpf/blddrv;/ztpf/curdrv",
    "traceLogDirectory" : "/traceLog"
}