Program configuration file

A program configuration file is a comma-separated values (CSV) file that you can use to specify program configuration values for individual programs.

The z/TPF system supports the following program configuration files:

An IBM® program configuration file, which is named ibmconfig.csv.
A user program configuration file, which is named usrconfig.csv.

The program configuration file is not supported for the following programs:

UTDF (the z/TPFDF central database routines)
Unallocated programs that have no base program attribute table (PAT) entries.

You can load a program configuration file by using the image loader or E-type loader.

Whenever a new version of either program configuration file is activated or deactivated by using the E-type loader, configuration information is updated in memory to match the contents of both the IBM and user program configuration files that have the highest activation numbers for new ECBs to use. The IBM program configuration file is processed first, and then the user program configuration file is processed. If an entry exists in both the IBM and user program configuration files, the entry in the user program configuration file takes effect, even if the IBM program configuration file has a higher activation number. The system is not paused while the configuration information is being updated in memory, so a brief timing window exists while the configuration information for some programs matches one version of the file and the configuration information for other programs matches another version of the file.

The z/TPF product includes only an IBM program configuration file, which is stored as base/cntl/ibmconfig.csv. You can create user program configuration files by copying the IBM program configuration file. The loadtpf utility supports subsystem-unique copies of user program configuration files from unique directories. For more information about the location in the file system to create your user program configuration files, see the comment in the base/cntl/tpf_app_usr.loadfile file.

Format

version
prog, owner, fepstatus, collectionstatus, library
.
.
.
prog, owner, fepstatus, collectionstatus, library

Table 1. Program configuration file fields
Field	Applicability	Description
`version`	Version 1 or later	An integer that indicates the version of the file.
`prog`	Version 1 or later	The 4-character program name. The program name is the shared object name, not an entry point name in a shared object.
`owner`	Version 1 or later	The 32-character ECB owner name in the form of `high`.`mid`.`low`, where: `high` The 8-character high-level qualifier. `mid` The 8-character mid-level qualifier. `low` The 16-character low-level qualifier. You can use this field to define how the z/TPF system automatically sets ECB owner names for your application. By specifying this field, you do not have to modify your application to issue the EOWNRC macro or `tpf_eownrc` function to set ECB owner names. Notes: If this field is specified in this file for a program, the ECB owner name is changed to this value each time an ECB enters this program. The periods are used only as separators in this configuration file and do not go into the actual owner name. If any of the qualifiers are specified with fewer characters, the qualifier is padded with blanks when the ECB owner name is changed. You can specify an asterisk () for any of the qualifiers. If a qualifier is specified with an asterisk, this qualifier is not changed when an ECB enters the program. If you want to specify only the high-level qualifier, specify the high-level qualifier followed by two periods. For example, if the high-level qualifier is `IPOOLS`, you must specify `IPOOLS..` as the owner name. If you want to specify only the high- and mid-level qualifiers, specify the high-level qualifier followed by a period and the mid-level qualifier followed by a period. For example, if the high-level qualifier is `IPOOLS` and the mid-level qualifier is `CYC0`, you must specify `IPOOLS.CYC0.` as the owner name. The change of ECB owner name incurs a runtime overhead cost. Therefore, do not specify this field for programs that are entered many times per ECB. The default value for the owner name is `..`. If the default value is not specified for the owner name of an program, the program configuration is rejected when one of the following conditions occurs: The program is a special linkage library. The program was compiled with the fast path linkage option specified. The program was compiled with the -mo-tpf-trace option specified. For more information about compile options, see LDFLAGS link options.
`fepstatus`	Version 2 or later	One of the following values: FEP Specifies that the program is a frequently entered program. NOFEP Specifies that the program is not a frequently entered program. If an E-type loaded program is heavily used or might potentially cause heavy system overhead, you can specify this program as a frequently entered program to reduce overhead and lock contention that are generated by running this program when the program is in an active loadset. For programs other than special linkage libraries, NOFEP is the default value. For special linkage libraries, which are CISO, CTAL, CTIS, CTAD, and CTDF, this field must be omitted because they automatically use frequently entered program linkage. Besides the 5 special linkage libraries, as many as 245 frequently entered programs can be defined across both the ibmconfig.csv and usrconfig.csv files for all subsystems. IBM can define as many as 20 frequently entered programs in the ibmconfig.csv file; therefore, you can define no more than 225 frequently entered programs in the usrconfig.csv files.
`collectionstatus`	Version 3 or later	One of the following values: EXCLUDE Excludes the ECB that enters this program and any associated child ECBs from name-value pair collection. Specify this option for the main entry points for background work. When you specify this option, the ECBs are excluded even if other programs that are entered by these ECBs have the INCLUDE option specified. Use this option to exclude work so that the name-value pair collection tapes are smaller and real-time runtime metrics collection contains less name-value pair collection results. For example, you can exclude the background and monitoring work from name-value pair collection results. This option is useful for testing environments where that work might be the most prevalent portion of the active ECBs. You can use the ZCNVP command with the INCLUDE parameter specified to include these ECBs in your name-value pair collection results. Use the ZCNVP command with the INCLUDE parameter specified in production environments where work such as the background and monitoring work are typically the least prevalent portion of the active ECBs. Enter `ZRTMC MODIFY NVPC INCLUDE-YES` in production environments to include background and monitoring work in the real-time runtime metrics collection results. INCLUDE Includes the ECB that enters this program and any associated child ECBs in name-value pair collection and real-time runtime metrics collection results. Specify this option for your applications and utilities. There is no additional linkage overhead when you specify this option. If the ECB subsequently calls a program that has the EXCLUDE option specified, from that point on, the ECB and the children ECBs are excluded from name-value pair collection and real-time runtime metrics collection by default. The INCLUDE option is the default. If the default value is not specified in this field for a program, the program configuration is rejected when one of the following conditions occurs: The program is a special linkage library. The program was compiled with the fast path linkage option specified. The program was compiled with the -mo-tpf-trace option specified.
`library`	Version 4 or later	One of the following values: YES Specifies that the program is considered a library program. NO Specifies that the program is considered an application program. This value is default. The library indicator is used by different system services, such as the z/TPF software profiler, which has special processing for a library program.

Examples

The following example shows a program configuration file. After the file is loaded to and activated on the z/TPF system, the following conditions occur:

When an ECB enters the Q000 program, the owner name of the ECB is set to fare quote A.
When an ECB enters the QABC program, the high-level qualifier in the owner name is changed to flight.
When an ECB enters the QDEF program, the mid-level qualifier in the owner name is changed to newmid.
When an ECB enters the QDEF program, the ECB and associated child ECBs are excluded from name-value pair collection and real-time runtime metrics collection results.
The QABC and QEFG programs are processed as frequently entered programs, and the Q000 and QDEF programs are processed as nonfrequently entered programs.
The QEFG program is considered a library program.

4
Q000,fare.quote.A,,,               
QABC,flight.*.* ,FEP,,NO
QDEF,*.newmid.*,NOFEP,EXCLUDE,NO
QEFG,,FEP,,YES