z/TPF Program Management - IBM

z/Transaction Processing Facility Enterprise Edition
Program Management
Version1Release1
���
GTPL-2MS5-09

|
|
|
|
|
|
Contents
Part 1. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
MakeTPF build solution . . . . . . . . . . . . . . . . . . . . . 3
Configuration files . . . . . . . . . . . . . . . . . . . . . . . . 3
Environment files . . . . . . . . . . . . . . . . . . . . . . . . 3
Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Control files . . . . . . . . . . . . . . . . . . . . . . . . . . 4
bldtpf utility . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
fctbval utility . . . . . . . . . . . . . . . . . . . . . . . . . . 5
loadtpf utility . . . . . . . . . . . . . . . . . . . . . . . . . . 6
maketpf_cntl_tdmdd_checker utility . . . . . . . . . . . . . . . . . . 6
maketpf utility . . . . . . . . . . . . . . . . . . . . . . . . . . 6
tpfObjectConverter utility . . . . . . . . . . . . . . . . . . . . . . 7
Local modifications . . . . . . . . . . . . . . . . . . . . . . . . 7
Assemble, compile, and link options . . . . . . . . . . . . . . . . . 7
LDFLAGS link options. . . . . . . . . . . . . . . . . . . . . . . 9
z/TPF program types and linkage . . . . . . . . . . . . . . . . . 11
Assembler and C program packaging. . . . . . . . . . . . . . . . . 11
Entry points . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Executable and linking format (ELF) . . . . . . . . . . . . . . . . . 12
Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Visibility in shared objects . . . . . . . . . . . . . . . . . . . . . 13
Stubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Transfer vectors . . . . . . . . . . . . . . . . . . . . . . . . 16
Program linkage . . . . . . . . . . . . . . . . . . . . . . . . 16
z/TPF loaders . . . . . . . . . . . . . . . . . . . . . . . . . 19
Loader general file . . . . . . . . . . . . . . . . . . . . . . . 19
Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Loadsets . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Version control file index . . . . . . . . . . . . . . . . . . . . . 21
VCFX programming considerations . . . . . . . . . . . . . . . . 21
Where programs are loaded . . . . . . . . . . . . . . . . . . . . 21
Offline general file loader component (ALDR). . . . . . . . . . . . . . 22
Online general file loader component (ACPL). . . . . . . . . . . . . . 23
Offline image loader component (TLDR) . . . . . . . . . . . . . . . 23
Online image loader component (ZTPLD) . . . . . . . . . . . . . . . 24
Offline E-type loader component (OLDR) . . . . . . . . . . . . . . . 25
Online E-type loader component (OLDR) . . . . . . . . . . . . . . . 26
E-type loader recycle interface . . . . . . . . . . . . . . . . . . . 27
Data loader . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Offline loader support on Linux . . . . . . . . . . . . . . . . . . . 28
Programming considerations . . . . . . . . . . . . . . . . . . . 29
Alternate FCTB loader overview . . . . . . . . . . . . . . . . . . 29
Alternate FCTB loader benefits . . . . . . . . . . . . . . . . . . 30
Alternate FCTB loader programming considerations . . . . . . . . . . 30
Alternate FCTB compatibility checking . . . . . . . . . . . . . . . 31
Compiler overview for z/TPF C/C++ support . . . . . . . . . . . . . 33
GCC ELF-compatible compilers. . . . . . . . . . . . . . . . . . . 33
Systems/C and Systems/C++ ELF-compatible compilers . . . . . . . . . 34
© Copyright IBM Corp. 2005, 2012 iii

|
|
|
|
|
Common deployment . . . . . . . . . . . . . . . . . . . . . . 37
Common deployment configuration file . . . . . . . . . . . . . . . . 38
Common deployment status file. . . . . . . . . . . . . . . . . . . 39
Function-unique processing . . . . . . . . . . . . . . . . . . . . 39
Part 2. Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
iv z/TPF Program Management
Acquire and install an ELF-compatible compiler . . . . . . . . . . . 43
Build the GNU compiler collection for the z/TPF system . . . . . . . . 45
Unpack the GNU compiler collection for the z/TPF system . . . . . . . 49
Set up access to the IBM2047 code page . . . . . . . . . . . . . . 53
Using EBCDIC code pages . . . . . . . . . . . . . . . . . . . . 53
Setting the GCC ELF-compatible compiler version to use . . . . . . . . 55
Assemble, compile, and link (build) application programs . . . . . . . 57
Define the HFS directory structure and environment files . . . . . . . . . 57
Real-time environment file: maketpf.env_billing . . . . . . . . . . . . 58
Linux offline environment file: maketpf.env_billing_linux . . . . . . . . . 58
z/OS offline environment file: maketpf.env_billing_zos . . . . . . . . . 59
Set up a configuration file . . . . . . . . . . . . . . . . . . . . . 59
Set up automated loading to remote z/OS systems . . . . . . . . . . . 60
Create a single-segment BSO . . . . . . . . . . . . . . . . . . . 61
Create a single-segment BSO using a generic makefile . . . . . . . . . . 62
Create a multiple-segment BSO with multiple external entry points . . . . . . 62
Use common source files in multiple-segment BSOs . . . . . . . . . . . 63
Add stubs for BAL programs with transfer vectors . . . . . . . . . . . . 64
Create a C shared object . . . . . . . . . . . . . . . . . . . . . 64
Create an archive for online programs . . . . . . . . . . . . . . . . 67
Create an offline Linux program. . . . . . . . . . . . . . . . . . . 67
Create an archive for offline Linux programs . . . . . . . . . . . . . . 68
Create an offline z/OS program . . . . . . . . . . . . . . . . . . . 68
Create an export file . . . . . . . . . . . . . . . . . . . . . . . 69
Update export files . . . . . . . . . . . . . . . . . . . . . . . 70
Resolve TSOC0001W warnings. . . . . . . . . . . . . . . . . . . 70
Update the FACE table . . . . . . . . . . . . . . . . . . . . . . 71
Load system components to a new z/TPF system . . . . . . . . . . . 73
Initialize and format the loader general file and online modules . . . . . . . 73
Create the general file loader input file . . . . . . . . . . . . . . . . 74
Load system components to the loader general file . . . . . . . . . . . 74
Load fixed-file records . . . . . . . . . . . . . . . . . . . . . . 74
Load system components to an existing z/TPF system . . . . . . . . . 77
Create a new image . . . . . . . . . . . . . . . . . . . . . . . 77
Define a new image . . . . . . . . . . . . . . . . . . . . . . 77
Copy CTKX, IPL areas, program areas, and CIMR components . . . . . . 77
Create an image loader input file . . . . . . . . . . . . . . . . . . 78
Load system components to a storage medium . . . . . . . . . . . . . 78
Load system components to the target image . . . . . . . . . . . . . 78
Enable the target image . . . . . . . . . . . . . . . . . . . . . 78
Move keypoints to the working area (optional) . . . . . . . . . . . . . 78
IPL the image . . . . . . . . . . . . . . . . . . . . . . . . . 79

|
|
|
|
|
Update IPLA on a loader general file . . . . . . . . . . . . . . . . . 79
Load E-type programs and files to an enabled system . . . . . . . . . 81
Create an E-type loader input file . . . . . . . . . . . . . . . . . . 81
Load E-type programs and files to a storage medium . . . . . . . . . . . 81
Load, activate, and accept a loadset of programs and files . . . . . . . . . 82
Load an alternate FCTB . . . . . . . . . . . . . . . . . . . . . 83
Load z/TPF debugger information . . . . . . . . . . . . . . . . . 85
Work with loadsets . . . . . . . . . . . . . . . . . . . . . . . 87
Clear E-type loader file resident records . . . . . . . . . . . . . . . 87
Load a loadset of E-type programs and files . . . . . . . . . . . . . . 87
Activate a loadset of E-type programs and files . . . . . . . . . . . . . 88
Selectively activate a loadset of E-type programs and files . . . . . . . . . 88
Deactivate a loadset of E-type programs and files . . . . . . . . . . . . 88
Delete a loadset of E-type programs and files . . . . . . . . . . . . . 88
Accept a loadset of E-type programs and files . . . . . . . . . . . . . 88
Exclude an E-type program or file from a loadset of E-type programs and files 89
Reinclude an E-type program or file to a loadset of E-type programs and files 89
Reclaim system resources. . . . . . . . . . . . . . . . . . . . . 89
Display loadset information . . . . . . . . . . . . . . . . . . . . 89
Change E-type loader program attributes . . . . . . . . . . . . . . . 90
Change E-type loader values. . . . . . . . . . . . . . . . . . . . 90
Display ECB status . . . . . . . . . . . . . . . . . . . . . . . 90
Use selective activate exits. . . . . . . . . . . . . . . . . . . . 91
Activate the selective activation function . . . . . . . . . . . . . . . 91
Create an enable command . . . . . . . . . . . . . . . . . . . . 91
Create a disable command . . . . . . . . . . . . . . . . . . . . 92
Using common deployment . . . . . . . . . . . . . . . . . . . 93
Loading deployment descriptors . . . . . . . . . . . . . . . . . . 93
Removing a deployment descriptor . . . . . . . . . . . . . . . . . 96
Handling an error during IPL after common deployment is installed. . . . . . 97
Part 3. Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Export files . . . . . . . . . . . . . . . . . . . . . . . . . 101
Control files . . . . . . . . . . . . . . . . . . . . . . . . . 103
XML descriptor control files . . . . . . . . . . . . . . . . . . . 105
Load files for version control . . . . . . . . . . . . . . . . . . 107
General file loader . . . . . . . . . . . . . . . . . . . . . . . 111
Image loader . . . . . . . . . . . . . . . . . . . . . . . . . 113
E-type loader . . . . . . . . . . . . . . . . . . . . . . . . . 115
z/TPF offline loader . . . . . . . . . . . . . . . . . . . . . . 117
JCL statements . . . . . . . . . . . . . . . . . . . . . . . . 117
Linux offldr command . . . . . . . . . . . . . . . . . . . . . . 119
Contents v

vi z/TPF Program Management
Linux labeltape command . . . . . . . . . . . . . . . . . . . . 121
Return codes . . . . . . . . . . . . . . . . . . . . . . . . . 121
Comment conventions. . . . . . . . . . . . . . . . . . . . . . 123
z/TPF offline loader input file control statements. . . . . . . . . . . 125
@APPLICATION . . . . . . . . . . . . . . . . . . . . . . . . 125
@CIMR . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
@CTKX . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
@DEFINE . . . . . . . . . . . . . . . . . . . . . . . . . . 134
@FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
@GFKEYPOINT . . . . . . . . . . . . . . . . . . . . . . . . 142
@INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . 145
@IPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
@KEYPOINT . . . . . . . . . . . . . . . . . . . . . . . . . 148
@LOADSET . . . . . . . . . . . . . . . . . . . . . . . . . 151
@VERIFY . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Sample code . . . . . . . . . . . . . . . . . . . . . . . . . 157
JCL for sending your output. . . . . . . . . . . . . . . . . . . . 157
VRDR. . . . . . . . . . . . . . . . . . . . . . . . . . . 157
GDS . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Input files . . . . . . . . . . . . . . . . . . . . . . . . . . 158
ALDR input file . . . . . . . . . . . . . . . . . . . . . . . 158
OLDR input file . . . . . . . . . . . . . . . . . . . . . . . 158
TLDR input file . . . . . . . . . . . . . . . . . . . . . . . 159

Part 1. Concepts
© Copyright IBM Corp. 2005, 2012 1

2 z/TPF Program Management

MakeTPF build solution
Configuration files
Environment files
The MakeTPF build solution is a set of offline programs that you can use to build
z/TPF application and system programs. The MakeTPF build solution consists of a
set of programs and files that fit together to form an integrated build environment for
online and offline z/TPF programs.
Important
The MakeTPF build solution requires a cross-compiler to build z/TPF application
and system programs that are written in C/C++ language. See “Build the GNU
compiler collection for the z/TPF system” on page 45 for more information.
Configuration files are used to define the build space. They identify:
v The root directory names where the application and z/TPF code reside. Multiple
root directories can be specified and will be searched for needed files in the
order that the directories are specified in the configuration file.
v The z/TPF system or subsystem that programs will be built for.
v User overrides to compile, assemble, and link flags.
v User overrides to process options, such as whether to keep clean listings.
You can have multiple configuration files. By default, the programs in the MakeTPF
build solution look for a configuration file named maketpf.cfg in the current
directory. You can override this choice by setting the TPF_CFG environment variable
to the full path to a configuration file of your choice. The GNU make syntax is used
for configuration files. See “Set up a configuration file” on page 59 for an example
of a configuration file. See “Assemble, compile, and link options” on page 7 for
more information about configuration file override options. For reference information
about coding configuration files, enter man maketpf.cfg on your Linux build
system.
Environment files define the directory structure of your applications by creating a
mapping between the file types known to the MakeTPF build solution and the
directories they reside in. These environment files are referenced in makefiles to
define where the MakeTPF build solution searches for source files and where
output files are written.
This directory structure is defined to the MakeTPF build solution independent from a
parent (or root) directory. This enables the MakeTPF build solution to associate the
directory structure to one or more root directories at build (assemble, compile, and
link) time and provides the capability of concatenating directory structures in much
the same way that data sets can be concatenated in JCL.
Environment files are set up by the system administrator based on the hierarchical
file system (HFS) structure. The GNU make syntax is used for environment files.
See “Define the HFS directory structure and environment files” on page 57 for
examples of environment files.
© Copyright IBM Corp. 2005, 2012 3

Makefiles
Control files
4 z/TPF Program Management
Makefiles are used by the maketpf command to specify the program name, type,
component, and any special build options that are required for a clean build
(assemble, compile, and link). All information is coded by assignment statements
and adheres to GNU make syntax.
Makefiles refer to environment files to define the paths for files that you need for the
build process and to specify the directories to use for output. Makefiles also include
maketpf.rules as their last statement to include the compile, assemble, and link
rules for z/TPF processing.
The maketpf.rules file includes a set of common rules files that are located in the
tpftools/include_ztpf and tpftools/include_ztpf_user directories. The audits in
these files are run by maketpf to check build input and output, and can issue errors
and warning messages. These audits can be external programs that check for
errors. For example, the maketpf audit that checks for programs that export data
objects needing relocation is defined in these files. See “Resolve TSOC0001W
warnings” on page 70 for more information about this maketpf audit.
You can add and audit rules in the maketpf.rules_setup1 and
maketpf.rules_setup2 files. If you want to change a rules file that was included by
IBM ® , move the appropriate file to the tpftools/include_ztpf_user directory (this
directory is searched before the tpftools/include_ztpf directory) and modify the
file.
See “Assemble, compile, and link (build) application programs” on page 57 for tasks
dealing with makefiles. For reference information about coding makefiles, enter man
maketpf.mak on your Linux build system.
Control files contain a list of programs that can be built by the MakeTPF build
solution. Control files do the following:
v Define program build options such as makefile, build order, whether the program
is offline or online, and others
v Are used as input for bldtpf to create general file loader, image loader, and
E-type loader input files
v Are used as input for bldtpf to create the program attribute table (PAT)
v Define program attributes (such as protection, restricted use, and so on)
v Are used for system programs (tpf.cntl) and user applications (usr.cntl).
The MakeTPF build solution recognizes two system-level control files: tpf.cntl and
usr.cntl. However, you can arrange control files into smaller and more
manageable chunks by using include statements in the control files. See Table 4 on
page 103 for information about the set of control files that are included.
You can also use control files on a project level. See “Assemble, compile, and link
(build) application programs” on page 57 for tasks showing how this can be done.
For reference information about control files and the control file format, see “Control
files” on page 103 and the prolog of base/cntl/tpf.cntl.

|
|
|
|
|
|
|
|
|
|
|
bldtpf utility
fctbval utility
The bldtpf utilty (enter the bldtpf command to activate) is a multiple-program
builder for maketpf-format makefiles and issues the maketpf command based on
each program listed in a control file. The bldtpf command also drives the
assemble, compile, and link of all z/TPF system and customer application
programs, both online and offline.
The bldtpf command can do the following tasks:
v Build a FACE table (FCTB)
v Build an online program attribute table (PAT)
v Create image loader input files (TLD), general file loader input files (ALD), and
E-type loader input files (OLD)
v Assemble the sip.asm file (the SIP deck)
v Generate the z/TPF system configuration data (using SIP and FCTB)
v Build z/TPF online, offline, and utility programs
v Generate STUB entries
v Generate PAT entries
v Perform PAT to control file conversions
v Produce programming artifacts (C headers and assembler DSECTS) for the
z/TPF system
v Produce the user application data model descriptor file (the cntl_tdmdd file).
These actions are driven by using either the control files or the SIP deck as the
primary input.
For reference information about the bldtpf command, including the syntax, enter
man bldtpf on your Linux build system.
Related information:
“Update the FACE table” on page 71
“maketpf utility” on page 6
“tpfObjectConverter utility” on page 7
The fctbval utility (enter the fctbval command to activate) compares the contents of
the base FACE table (FCTB) and the alternate FCTB and validates that the
alternate FCTB can be used online. This utility performs the same FACE validations
that are done online with the ZFCTB LOAD and ZODBR LOAD commands. The fctbval
command also produces a list of differences to help you verify your changes and
provides an option to list all detected fixed file and pool record moves.
The fctbval utility writes any validation exceptions and differences between the base
FCTB and alternate FCTB to the standard output stream (stdout).
For reference, enter man fctbval on your Linux build system.
MakeTPF build solution 5

|
|
|
|
|
|
|
|
loadtpf utility
Related reference:
ZFCTB LOAD–Load an alternate FACE table
ZODBR LOAD–Prepare for an online database reorganization
Related information:
“Update the FACE table” on page 71
The loadtpf utility (enter the loadtpf command to activiate) can generate an E-type
load file by using the bldtpf command and the offldr command and transferring
the file (by using FTP) to a z/TPF system. The loadtpf utility can load programs and
files based on a control file, an E-type loader input file, an E-type load file, a
program name, or a z/TPF shared object.
Note: The loadtpf command requires a user ID and password that is specified in a
.netrc file. For more information, see “Set up automated loading to remote
z/OS systems” on page 60.
For reference information, enter man loadtpf on your Linux build system.
Related information:
“Update the FACE table” on page 71
“bldtpf utility” on page 5
“Linux offldr command” on page 119
“Set up automated loading to remote z/OS systems” on page 60
maketpf_cntl_tdmdd_checker utility
maketpf utility
6 z/TPF Program Management
The maketpf_cntl_tdmdd_checker utility verifies the data model descriptor control
file format and content. The utility checks each field in each entry of the cntl_tdmdd
file by using the specifications defined in the prolog of the base/cntl/
tpf.cntl_tdmdd file.
For reference information, enter man maketpf_cntl_tdmdd_checker on your Linux
build system.
The maketpf utility (enter the hmaketpf command to activiate) is a single-program
builder for maketpf-format makefiles and drives the assemble, compile, and link of
all z/TPF system and customer application programs, both online and offline.
To build a program, enter maketpf followed by a program name or a makefile name.
If you enter the maketpf command with a program name as an argument, the
command tries to locate the program in the control files and uses the makefile
specified there. If the program is not found, the command tries to locate and use a
makefile with the same name as the program, but with a .mak extension.
To build a single-source segment without a makefile, enter maketpf followed by the
segment file name.
You also can use maketpf to call targets in a build. For example, enter maketpf
cmqs cmqapi.o to build cmqapi.o for program cmqs.

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
tpfObjectConverter utility
Local modifications
For reference information, enter man maketpf on your Linux build system.
Related information:
“Assemble, compile, and link (build) application programs” on page 57
The tpfObjectConverter utility produces programming artifacts such as C header
files, assembler DSECTS, and Java classes from a descriptor file that contains
Object definitions. You can also use this utility to update the deployable rule request
server enterprise archive (EAR) file to contain the new execution object model that
corresponds to the input data model.
All programming artifacts are produced and placed in subdirectories of the working
directory by default.
Programming artifact Subdirectory
C headers ./include
Assembler DSECTS ./macro
Java ./java
Note: When invoked by the bldtpf utility, which artifacts to create and which
directories to place them in are defined in the cntl_tdmdd files.
For reference information, enter man tpfObjectConverter on your Linux build
system.
Related reference:
Data model descriptor
The data model descriptor contains the definitions for a set of objects.
Business event specification
The business event specification is used to define a business event. This
specialized XML file contains the name of the event, a definition of the data that is
being provided for the event, and a list of business event dispatch adapters that are
used to transmit the data to the event consumers.
Related information:
“bldtpf utility” on page 5
The MakeTPF build solution allows local modifications to code that is included with
the z/TPF system. The MakeTPF build solution searches the local_mod/ directory
for files before searching the z/TPF system directories. You can place modified
copies of files that are included with z/TPF in this directory to prevent your changes
(local modifications) from being overwritten when the files are updated.
Assemble, compile, and link options
Options, also known as flags, define how an assembly, compile, or link will run; for
example, you can use them to set optimization levels, generate debug data, or hide
warnings. A default set of assemble, compile, and link options is defined by the
MakeTPF tools.
MakeTPF build solution 7

8 z/TPF Program Management
There are two ways to add additional options or to override the default options that
are set by the MakeTPF tools:
v Update the maketpf configuration file (maketpf.cfg).
Options that are stored in the configuration file are intended to be temporary
because the configuration file is not stored or retained; it is part of the build
space and can change from build to build. Specifying options in the configuration
file is useful for testing new options before you formally update the makefile, for
temporarily overriding debug levels, and so on. The following variables are
supported in the configuration file:
– ASMFLAGS_USER
– CFLAGS_USER
– CXXFLAGS_USER
– PLIFLAGS_USER
– LDFLAGS_USER.
Options that are specified in the _USER variables apply to all assemblies,
compiles, or links for any program. They take highest precedence and override
the default options as well as any options that are specified in the makefile.
v Update the makefile for the program.
Options that are specified in the makefiles are intended for permanent changes
to the default options because they are stored directly in the makefile. Options in
the makefile can be specified at two levels: either applying to a specific source
file, or applying to all source files of a given type (C, CXX, and so on). The
following variables are supported in the makefile, where pgm is the
case-sensitive program name specified by the primary target in the makefile
(APP, EXE, and so on) and seg is the case-sensitive source file name, without
the file extension, that is specified in the source file lists (C_SRC, ASM_SRC,
and so on):
– ASMFLAGS_pgm and ASMFLAGS_pgm_seg
– CFLAGS_pgm and CFLAGS_pgm_seg
– CXXFLAGS_pgm and CXXFLAGS_pgm_seg
– PLIFLAGS_pgm and PLIFLAGS_pgm_seg
– LDFLAGS_pgm
Options that are specified in _pgm_seg take higher precedence over those
specified in _pgm for source file _seg, and both take higher precedence over the
default options that are set by the MakeTPF tools.
In the following example, MY12 is the name of the program in the APP statement of
the makefile. mycfile1.c, mycfile2.c, and mycfile3.c are source files.
APP := MY12
C_SRC := mycfile1.c
C_SRC += mcyfile2.c
C_SRC += mycfile3.c
CFLAGS_MY12 := -O0
CFLAGS_MY12_mycfile2 := -O3
In this example, the mycfile3.c and mycfile1.c source files would have -O0 as an
override; however, the mycfile2.c source file would have -O3 as an override.
Additional information:

LDFLAGS link options
v See the tpftools/include_ztpf/maketpf.rules_set_flags* files for more
information about options in the MakeTPF tools.
v For more information about the maketpf configuration file, enter man
maketpf.cfg on your Linux build system.
v For more information about makefiles, enter man maketpf.mak on your Linux
build system for a complete list of makefile variables that can be coded.
The following link options can be set using the LDFLAGS _$(APP) variable in the
makefile:
v -Xlinker --defsym -Xlinker CGCC_31BIT=0
This option creates a symbol in the shared object that indicates the shared object
must be loaded below the 2-GB bar and in a 31-bit core resident program area
(CRPA) virtual address area. This option gets propagated online through the
program ordinal (ORDN) record header without being set in the program attribute
table (PAT).
v -Xlinker --defsym CGCC_FastPathStub=0
This option creates a symbol in the shared object that can be used to flag a
condition in the program. The fast path indicator is a core-only value in the PAT
and gets propagated online through the program ordinal (ORDN) record header.
The fast path indicator is valid in the PAT when the program is fetched.
When this option is applied to shared objects that contain library functions, the
linkage path is reduced when calling these functions. This reduction of path
length provides the following benefits:
– Improved system performance.
– The trace name field CE3TRNAME is not changed across function calls,
which are viewed as extensions of the calling shared object.
Note: Only use this option for shared objects that contain fast path linkage
libraries.
v -Xlinker --defsym -Xlinker CGCC_COW_CRPA=0
This option creates a symbol in the shared object that indicates the shared object
must be loaded in the 31-bit or 64-bit standard CRPA virtual address area.
Note: Do not use this option for programs that update static data, import data
from other programs, or have global constructors.
v -Xlinker --defsym -Xlinker CGCC_COW_CRPA=1
This option creates a symbol in the shared object that indicates the shared object
must be loaded in the 31-bit or 64-bit copy-on-write CRPA virtual address area.
For more information about Makefiles, enter man maketpf.mak on your Linux build
system for a complete list of Makefile variables that can be coded.
MakeTPF build solution 9

10 z/TPF Program Management

z/TPF program types and linkage
An object file is a compiler or assembler output file that is suitable as input to a
linkage editor. In the z/TPF system, object files are included in a shared object,
which is all or part of a computer program in a form suitable for loading into main
storage for execution. A shared object usually is the output of a linker. Depending
on the z/TPF program, there are different ways to package programs for linkage.
The number of entry points defined impacts the way these programs are
externalized to other programs for linkage. There are a number of ways to increase
the efficiency of the linkage between these programs and to improve the
performance of your z/TPF system.
A BAL shared object (BSO) is a type of shared object consisting of one or more
objects that are created by assembling z/TPF E-type basic assembler language
(BAL) programs. By contrast, a C shared object (CSO) is a type of shared object
consisting of one or more objects that are created by compiling C language
programs or assembling z/TPF BAL programs using C/C++ calling conventions.
Both BSOs and CSOs can have single and multiple entry points. See z/TPF
Application Programming for more information.
Figure 1 shows E-type program types in the z/TPF system.
BAL shared object (BSO)
Single entry point
CSO program without
the main function
Figure 1. E-type program types
E-type programs / shared objects
Single entry point
CSO program with
the main function
Assembler and C program packaging
C shared object (CSO)
Library
(non-program)
Program and library
BSOs and CSOs can be repackaged into multiple entry point shared object libraries
to provide the following performance advantages and benefits:
v Reduction in system overhead for an application because two segments can be
linked together as one unit, creating a shorter path length because internal
linkage paths are faster than external paths.
v For BSOs:
– Program expansion beyond 4 KB.
– The program can be coded with multiple base registers or can remain
baseless.
– The assembler API of R0 - R7 has been expanded to include R8.
© Copyright IBM Corp. 2005, 2012 11

Figure 2. BAL repackaging
Entry points
Note: R10 - R13 are available for program use.
Figure 2 shows how multiple programs (PGM1, PGM2, and PGM3) are packaged
into one BSO. The result is a BSO with multiple entry points.
The initial packaging will convert each assembler program into its own BSO. It is
possible for an assembler program to reside in more than one BSO, but its entry
point name can only be externalized from one of the BSOs.
Entry points are listed in the entry point linkage table (EPLT). The following shared
objects and entry points are included in the EPLT:
v All shared objects (real-time programs)
v Entry points that are coded for BEGIN macros in BSO source files
– Primary entry points that are specified for the NAME= parameter
– Transfer vectors that are specified for the TV= parameter.
Executable and linking format (ELF)
12 z/TPF Program Management
PGM1
PGM2
PGM3
PGM1.so
Entry point
PGM1
Entry point
PGM2
Entry point
PGM3
ELF is the standard binary format on operating systems such as Linux. Some of the
capabilities of ELF are dynamic linking, dynamic loading, imposing run-time control
on a program, and an improved method for creating shared libraries. The ELF
representation of control data in an object file is platform independent, which is an
additional improvement over previous binary formats.
The ELF representation permits object files to be identified, parsed, and interpreted
similarly, making the ELF object files compatible across multiple platforms and
architectures of different size. The three main types of ELF files are:
v Executable
v Relocatable
v Shared object
These file types hold the code, data, and information about the program that the
operating system and linkage editor need to perform the appropriate actions on
these files.

Archives
Visibility in shared objects
Archives are a collection of ELF objects that are link-edited into a shared object. If
your calling program has an ARCHIVES:= statement coded in the associated
makefile, the archives specified by the statement get link-edited into the shared
object. This way, the link to the functions contained in the archive is static.
Use archives if you have a library of functions that frequently change and you are
interested in changing the functions themselves without impacting the application
programming interfaces (APIs) contained in the shared object or the calling
program. A tape library is an example of an archive. See “Create an archive for
online programs” on page 67 and “Create an archive for offline Linux programs” on
page 68 for more information about creating archives. See “Create an offline Linux
program” on page 67 for an example of a program that calls functions in an archive.
In the GNU compiler collection (GCC) environment, the term that is used for
exporting is visibility. As it applies to functions and variables in a shared object,
visibility refers to the ability of other shared objects to call a C/C++ function.
Functions with default visibility have a global scope and can be called from other
shared objects. Functions with hidden visibility have a local scope and cannot be
called from other shared objects.
Visibility can be controlled by using either compiler options or visibility attributes.
The -fvisibility=default compiler option (used in conjunction with the
-fvisibility inlines=default compiler option for C++ programs) is used to define
all of the functions in a shared object as visible (global scope). These compiler
options are available on all z/TPF-supported compilers. Adding the visibility attribute
can override a compiler option.
Using the z/TPF MakeTPF tool makes it relatively easy to control the visibility of
functions by changing the makefile to specify APP_EXPORT or to use the visibility
attribute in the program.
MakeTPF and visibility
The maketpf APP_EXPORT variable controls which functions are local to the shared
object and which functions can be called from other shared objects, where
APP_EXPORT can be set to: ALL, VISIBILITY, LIST, orENTRY.
v ALL is used to make all functions visible by default at compile time, by adding the
-fvisibility=default compiler option (used in conjunction with the
-fvisibility inlines=default compiler option for C++ programs) to the compile
commands. Individual functions can be hidden by using the visibility attribute; add
__attribute__ ((visibility("hidden")) to the functions you want to hide.
Note: Avoid adding __attribute__ ((visibility("hidden")) to C++ code
unless it is essential for class member functions to be hidden. For more
information about potential problems when you use visibility with C++
classes, see “Special considerations for C++ classes” on page 15.
v VISIBILITY is used to hide all functions by default at compile time, by adding the
-fvisibility=hidden compiler option (used in conjunction with the -fvisibility
inlines=hidden compiler option for C++ programs) to the compile commands.
z/TPF program types and linkage 13

14 z/TPF Program Management
Individual functions can be made visible by using the visibility attribute; add
__attribute__ ((visibility("default")) to the functions you want to make
visible.
Note: Use this option for shared objects that contain only C language code
because runtime problems can occur when you use this option on a
shared object that contains C++ code. For more information about
potential problems when you use visibility with C++ classes, see “Special
considerations for C++ classes” on page 15.
v LIST is used to indicate that the list of visible functions is provided in an export
file. As with ALL, the -fvisibility=default compiler option (used in conjunction
with the -fvisibility inlines=default compiler option for C++ programs) is
used at compile time to make the functions visible; however, at link time, the
export file provides:
– A list of functions that are to be hidden.
– A list of functions that are visible.
Note: You must use the LIST option and export files when hiding functions that
are coded in assembly language, because there is no assembly option
that is equivalent to the -fvisibility option. For more information, see
“Export files” on page 15.
v ENTRY is used to indicate that only the function specified by APP_ENTRY is made
visible. This is also controlled at link time by using the base/exp/app_entry.exp
export file. For more information, see “Export files” on page 15.
Examples
v To make all of the functions for a given program visible except for the
ftpc_get_file function, specify APP_EXPORT := ALL in the makefile for the
program and code the following in your C/C++ application source code:
__attribute__ ((visibility("hidden")))
size_t ftpc_get_file (void *ptr, size_t size, size_t nmemb, void *stream)
{
...
}
Adding the attribute hides the C/C++ function.
v To hide all of the functions for a given program except for the mq_msg function,
specify APP_EXPORT := VISIBILITY in the makefile for the program and code
the following in your C/C++ application source code:
__attribute__ ((visibility("default")))
char *mq_msg(size_t buffer_length);
Adding the attribute makes the C/C++ function visible.
v In this example, the makefile for program ABCD makes all functions visible by
default. However, the application hides uncallableFunction( ) by declaring it as
a static function; the application also hides anotherUncallableFunction( ) by
using the visibility("hidden") attribute. An important distinction to make is that
the scope of the hidden function in terms of visibility is the shared object, while
the scope of the static function is limited to the object.
abcd.mak:
APP := ABCD
APP_EXPORT := ALL
C_SRC := program.c
program.h:

Stubs
void callableFunction( );
void anotherCallableFunction( );
static void uncallableFunction( );
__attribute__ ((visibility("hidden")))
void anotherUncallableFunction( );
Special considerations for C++ classes
C++ classes have a number of vague linkage entities; for example, typeinfo and
vtable. These entities take on the visibility attribute of the class; therefore, if a class
is hidden, the entities are hidden, which might have undesirable side effects. Some
side effects include not being able to be inherited from a class in a different shared
object and not being able to get thrown by an exception.
For example, a common problem that is introduced when you compile a class with
the -fvisibility=hidden option is when the now-hidden class needs to run a
constructor from another shared object (such as running a constructor for an
inherited class); it appears to compile and link, but you will receive a runtime
linkage error.
Note: Unless you know that the C++ logic is contained in the same shared object
without the need to use CPP1 or any other C++ library, avoid using
APP_EXPORT := VISIBILITY.
In general, it is best not to use the visibility option for C++ object-oriented programs
because of the danger of generating runtime errors that are difficult to debug.
Instead, take advantage of the inherent characteristics of C++ object-oriented
programs, such as encapsulation, namespaces, inheritance, and other
characteristics.
If, however, you do use the visibility option for C++ programs, use it with
declarations; in most cases, you do not need to specify the visibility option in the
definition.
Export files
Also called version scripts, export files in the z/TPF system are meant to be used
when you have C/C++ functions that are coded in basic assembly language (BAL)
that need to be hidden (not shared globally); the only way to hide them is by using
an export file. With an export file, you can hide functions that were visible at
assemble (or compile) time. However, at link time, you cannot make visible any
functions that were hidden at assemble or compile time.
The executable and linking format (ELF)-compatible compilers support export files
for z/TPF applications that require specific symbols to be modified. For more
information about export files, go to http://www.gnu.org.
For more information about using export files with the MakeTPF build solution, see
“Create an export file” on page 69 and “Update export files” on page 70.
Stubs are used to resolve external references between BSOs. The control files that
are shipped by IBM contain an entry to generate a stub file that contains a list of
programs with entry points (including transfer vectors). This stub file is entered into
the linkage editor and gets compiled and link-edited to generate a shared object
that contains the entry points for your BAL application programs. The BEGIN macro
z/TPF program types and linkage 15

Transfer vectors
Program linkage
16 z/TPF Program Management
generates an external reference in the shared object that maps to the name of the
entry point. All stub entries for transfer vectors and multiple source BSOs are
located in a control file (tpf_app_base_xv.cntl) that is shipped by IBM. When you
build a z/TPF system, a complete stub library is created.
Because multiple entry point BSOs do not require specific entries in the control file,
no stubs are generated. To create a stub for multiple source BSOs with multiple
entry points and transfer vectors, code a STUB ONLY entry in your control file. See
“Create a multiple-segment BSO with multiple external entry points” on page 62 for
more information about creating stubs.
You do not need to create stubs. However, you will receive unresolved external
references during link-editing if stubs are not generated during the build process.
All stub entries for transfer vectors and multiple source BSOs are located in a
control file (tpfl_app_base_xv.cntl) that is shipped by IBM. When you build a
z/TPF system, a complete stub library is created.
Because transfer vectors do not require specific entries in the control file, no stubs
are generated. To create a stub for transfer vectors, code a STUB ONLY entry in
your control file. See “Add stubs for BAL programs with transfer vectors” on page
64 for more information about creating stubs.
You do not need to create stubs for transfer vectors. However, you will receive
unresolved external references during link-editing if stubs are not generated during
the build process.
External reference validation is performed by default with maketpf and can be
turned off with maketpf options (TPF_VERIFY_LINK_REFS). Validation issues
errors at build time rather than at run time. If the program is built without verifying
external references, it will build cleanly, but a run-time error will be issued if a
function is not found online.
Standard libraries (including stub libraries) are included automatically by maketpf.
The list of standard libraries is managed in the maketpf setup. You can define your
own standard libraries. If you reference nonstandard libraries, you need to make a
corresponding entry in your makefile. For more information about Makefiles, enter
man maketpf.mak on your Linux build system for a complete list of Makefile
variables that can be coded.
Input libraries are specified by using LIBS assignments in the calling makefile. Your
z/TPF programs will not be linked if unresolved references are detected.
The following list describes different linkage types:
v Load-time linkage: Normal load-time linkage is sometimes referred to as dynamic
linkage because the linkage references are resolved dynamically when the
program is loaded into storage.
v Link-time linkage: This internal linkage is resolved at link time and provides the
fastest linkage between programs. For CSOs, this linkage is generated by the

compiler and cannot be controlled. For BSOs, the BEGIN macro controls the
linkage. See z/TPF General Services for more information about the BEGIN
macro.
v Run-time linkage: This is the longest linkage because it is resolved at run time.
The enter stub branches to a program name hash routine, which locates the
program attribute table (PAT) of the program to be entered and determines the
stub based on program type. The hash routine then branches to the CSO stub
code.
v Nonstandard linkage: One type of common nonstandard linkage involves getting
the base address of a program and branching directly to it. You can see an
example of this linkage in recoup descriptors, which are programs that are used
as data records that also can contain the code needed to chase your own file
chains. While not suggested, you can use this type of linkage.
z/TPF program types and linkage 17

18 z/TPF Program Management

z/TPF loaders
Loader general file
A loader is a tool for introducing new or modified system components, programs,
files, or data to a z/TPF system. All loaders have both an online and offline
component.
Offline Component
Takes system components, programs, files, or data from the hierarchical file
system (HFS) data sets and writes them to a storage medium such as tape,
DASD, virtual reader, or user-defined device.
Online Component
Takes the system components, programs , files, or data from the storage
medium and loads them to their correct location on the online system.
The load functions of a z/TPF system are handled by the general file loader, data
loader, E-type loader, and image loader. Only the general file loader is used for an
initial full load (see “Load system components to a new z/TPF system” on page 73).
When you have completed a full load, you do not need to do another except for
some DASD configuration or core image restart (CIMR) changes.
The loader general file (LGF) contains the program and keypoints that are needed
to start or restart the system. The following list shows the loader general file
contents:
v IPLA and the volume ID (VOLID)
Note: This copy of IPLA is used when the loader general file is IPLed.
v Keypoints from an HFS object library
v IPLA
Note: This copy of IPLA is loaded to online modules.
v IPLB
v Core image restart (CIMR) area components
– Control program (CP)
– In-core dump formatter (ICDF) program
– Online component of the general file loader (ACPL)
– Global synchronization table (SIGT)
– Record ID attribute table (RIAT)
– File address compute program table (FCTB)
– USR1
– USR2
v E-type programs and data records
– E-type programs from an HFS object library
– Loader control record (LDCRL)
– Program attribute table (PAT).
Note: The general file loader (ALDR) does not load files. The ALDR loads a
sufficient subset of z/TPF programs and application programs to an image
so that after an initial program load (IPL) is performed, online image load
processing can occur from that image. These programs are not file
dependent.
© Copyright IBM Corp. 2005, 2012 19

Images
Loadsets
20 z/TPF Program Management
v General file IPL keypoints
v Online module IPL keypoints
v Online keypoint patches.
There are two types of general files for High Performance Option (HPO) feature:
one for the basic subsystem (BSS) and one for subsystems. Only the basic
subsystem has the code that is necessary for an IPL.
See “Load system components to a new z/TPF system” on page 73 for information
about creating and loading the loader general file; also see “Update IPLA on a
loader general file” on page 79 for information about updating an existing loader
general file.
An image is a selectable version of the z/TPF system software that includes the
following components:
v Core image restart (CIMR) area components
– Control program (CP)
– In-core dump formatter (ICDF) program
– Online component of the general file loader (ACPL)
– Global synchronization table (SIGT)
– Record ID attribute table (RIAT)
– File address compute program table (FCTB)
– USR1
– USR2.
v Program base components
– Program attribute table (PAT)
– E-type programs and files.
v Keypoints
– Keypoint staging area
– Keypoint backup area.
v IPL area
v The image pointer record (CTKX) area.
The z/TPF system supports multiple images. These images can share IPL areas
and program bases. Multiple images are often used for testing and for migration
because the z/TPF system can fall back to a good image if there is a problem in
the image that is being tested.
See “Load system components to an existing z/TPF system” on page 77 for
information about creating and loading an image.
A loadset is group of E-type programs or files identified by a unique name on which
E-type loader functions can be performed. Loadsets can be loaded to the z/TPF
system without requiring an IPL. Loadsets can be enabled and disabled and are
often used for testing programs.
See “Load E-type programs and files to an enabled system” on page 81 for
information on creating and loading a loadset. See “Version control file index” on
page 21 for more information about including files in a loadset.

Version control file index
File version control requires that versioned files be represented by entries in a
subdirectory of a mounted, explicitly versioned file system known as a version
control file index (VCFX). Symbolic links permit files under version control to be
handled like they reside in any directory in any file system.
The /sys/tpf_pbfiles target in the system pseudo-file system (SYSFS) provides a
symbolic link to the appropriate z/TPF collection support file system (TFS)
subdirectory for program base unique files. Each file referenced in the VCFX
through the /sys/tpf_pbfiles target is a symbolic link to the corresponding
program base unique file version in TFS. See z/TPF Process Pseudo-File System
and System Pseudo-File System Targets for more information about the
/sys/tpf_pbfiles target.
The VCFX is managed by using the E-type loader. Table 1 lists the commands that
you use to manage loaded files.
Table 1. Commands used to manage loaded files
Command File support
The ZOLDR commands. Process files that are both program base
unique and not program base unique to the
TFS.
ZTPLD Load program base unique files to the TFS.
ZFILE fver Locate the specific version of a file.
See z/TPF Operations for more information about the ZOLDR commands, and the
ZTPLD and ZFILE fver commands.
VCFX programming considerations
The following lists the programming considerations for using VCFX support:
Where programs are loaded
v VCFX is managed exclusively by using the E-type loader.
v When using the E-type loader to load files, you must use the ZOLDR ACCEPT
command to ensure that the file changes are persistent. If a loadset is deleted,
changes to any of the files in the loadset are lost. In the case of an affiliated file,
changes to the file in the loadset are not reflected in the existing online version.
v You can specify binary or text files in the offline loader input file. Text files are
translated during load processing.
See the following for more information about using VCFX support:
v “z/TPF offline loader input file control statements” on page 125
v “Load files for version control” on page 107
v z/TPF Database User's Guide
v z/TPF Concepts and Structures.
Programs are generally loaded above the 2-GB bar. However, there are times (such
as when you are migrating to the z/TPF system) when you want to load a program
or set of programs below the 2-GB bar. The CGCC_31BIT symbol determines
where programs will be loaded. The offline loader examines the symbol table of
each shared object to see if the CGCC_31BIT symbol exists. If this symbol is
z/TPF loaders 21

present, the program or programs are loaded below the 2-GB bar; if the symbol is
not there, the program or programs are loaded above the 2-GB bar. The
CGCC_31BIT symbol is added during the link-edit phase of the build process only
when CGCC_31BIT=0 is set as a link edit flag in an individual makefile or in a
MakeTPF configuration file (maketpf.cfg).
Note: You cannot specify where to load a program at load time.
See “Create a C shared object” on page 64 for more information about creating a C
shared object, including where to load programs. For more information about
Makefiles, enter man maketpf.mak on your Linux build system for a complete list
of Makefile variables that can be coded.
Offline general file loader component (ALDR)
ELF objects
and libraries
from the HFS
Loader input file
Begin process
General file
loader
offline component
(TPFLDR – ALDR)
End process
LDCRL = Loader control record
Primary process
Data flow
General
file
LDCRL
Figure 3. General file load using the general file loader offline component (ALDR)
22 z/TPF Program Management
When you create your z/TPF system for the first time, you must initialize and format
the loader general file, initialize and format the online modules, and load IPLA and
the volume ID (VOLID) to the loader general file before you can load system
components to the loader general file. See “Initialize and format the loader general
file and online modules” on page 73 for more information.
Figure 3 shows how the remainder of the loader general file is loaded by the offline
general file loader (ALDR). ALDR loads all the records and programs specified in
the loader input file and creates a loader control record (LDCRL) on the loader
general file. This control record indicates the components to load from the loader
general file to the online modules during the online general file load (ACPL).
The general file loader is only necessary at system generation time or in an
emergency load condition in which no fallback image exists.
Note: The general file loader always overwrites image 1, which must be defined to
use program area 1 and IPL area 1. Therefore, ensure that you reserve
image 1, program area 1, and IPL area 1 for emergency general file loads.

Online general file loader component (ACPL)
General
File
LDCRL
Figure 4 shows what happens when you IPL the loader general file.
General file IPL
(initializer program)
General file
loader
online component
(ACPL)
General file IPL
(restart scheduler)
LDCRL = Loader control record
Primary process
Data flow
Online
module
Online
module
When you IPL the loader general file, the online general file loader component
(ACPL) is placed in main storage. ACPL then uses the loader control record
(LDCRL) to load the contents of the loader general file on the online modules.
Keypoints, if present in the loader general file (LGF), are loaded to the prime and
duplicate modules. They are copied to the first 256 modules of the same type as
the prime module during online processing.
When online loading has been completed, the operator is notified about all the
components that were loaded. If the IPL is unsuccessful, the operator is sent all of
the error messages for the run.
If the IPL is successful, the online general file loader sends the following message
to the operator terminal:
ACPL0001I SYSTEM LOAD COMPLETE
LOAD DATA AFTER 1052 STATE IF NEEDED
IF NOT IPL PRIME MODULE ccud
This message reminds an operator who is performing a full load to load data after
the system has reached 1052 state (see “Load fixed-file records” on page 74).
Offline image loader component (TLDR)
Online
module
Figure 4. General file IPL using the general file loader online component (ACPL)
Figure 5 on page 24 shows how system components are loaded by the offline
image loader component (TLDR).
z/TPF loaders 23

ELF objects
and libraries
from the HFS
Loader input file
Begin process
Primary process
Data flow
Image loader
offline component
(TPFLDR – TLDR)
Figure 5. Image load via image loader (Offline – z/OS)
End process
TLDR places the components that are specified in the loader input file on a storage
medium that can be loaded to the system by the ZTPLD command. For more
information about the ZTPLD command, see z/TPF Operations.
Note: If you are writing to a virtual reader, use the ELDRVRDR EXEC to convert
TLDR JOB output to a spool file that supports virtual reader input. A sample
ELDRVRDR EXEC is shipped as segment base/samples/uelv.rex.
The image loader is the main method for performing system loads for an existing
z/TPF system. The general file loader is only necessary at system generation time
or in an emergency load condition where no fallback image exists.
Use the image loader to load system components from a storage medium to any
defined and disabled z/TPF image. Because the image loader runs in 1052 state or
above, the subsystem must be initialized through a full load before the image loader
can be used. The image loader requires only a hard IPL to switch the image that is
now active.
If you are running more than one z/TPF image, make sure that the FCTBs and
RIATs for each system have compatible structures; that is, make sure that the
tables:
v Do not point to different addresses for the same record
v Do not point to the same address for different records.
Online image loader component (ZTPLD)
24 z/TPF Program Management
Storage
medium
Figure 6 on page 25 shows what happens when you enter the ZTPLD command to
start the online image loader component.

Storage
medium
ZTPLD
command
Image loader
online component
Output message
Primary process
Data flow
Online
module
Online
module
Figure 6. Image load via image loader (Online – z/TPF)
The ZTPLD command loads system components from a storage medium to the
online modules in an area that belongs to a disabled image. For more information
about this command, see z/TPF Operations.
Note: Use the ZTPLD command to load system components to a target image.
This image must be disabled and its IPL area and PROG bases must not be
referred to by any enabled image (if loading IPL area or PROG bases).
Use the ZIMAG DISABLE command to disable an image. Use the ZIMAG
DISPLAY command to display the status of the IPL area and PROG bases.
See z/TPF Operations for more information about the use of these
commands.
The online image loader component sends the following message after a successful
load:
TPLD0004I hh.mm.ss LOAD COMPLETE
In the previous message, hh.mm.ss is a time stamp.
Additional status and error messages also are sent to the operator console. For
more information about image loader messages, see z/TPF Messages (System
Error, Offline, and Program Status Word) and z/TPF Messages (Online,
SQLCODEs, and errno Values).
Offline E-type loader component (OLDR)
Online
module
Figure 7 on page 26 shows how E-type programs and files are loaded by the offline
E-type loader component (OLDR).
z/TPF loaders 25

ELF objects
and libraries
from the HFS
Loader input file
Primary process
Data flow
Begin
process
E-type loader
offline component
End process
Figure 7. E-type load via E-type loader (Offline – z/OS and Linux)
Storage
medium
OLDR places loadsets of programs and files (identified by the input parameters) on
a storage medium that you can load to the system by using the ZOLDR LOAD
command. For more information about the ZOLDR LOAD command, see z/TPF
Operations.
Note: If you are writing to a virtual reader, use the ELDRVRDR EXEC to convert
OLDR JOB output to a spool file that supports virtual reader input. A sample
ELDRVRDR EXEC is included as segment base/samples/uelv.rex.
Online E-type loader component (OLDR)
26 z/TPF Program Management
Figure 8 on page 27 shows what happens when you enter the ZOLDR LOAD
command to start the online E-type loader component.

Storage
medium
ZOLDR LOAD
command
E-type loader
online component
Output message
Primary process
Data flow
The ZOLDR LOAD command loads a loadset of E-type programs or files from a
storage medium to the system. For more information about the ZOLDR LOAD
command, see z/TPF Operations.
If you want to replace a base version of an E-type program, change the program in
main storage using the ZAPGM command or load and activate a loadset of
programs using the E-type loader.
Note: ZAPGM should not be used for major program changes because it permits
you to change only 16 bytes of a program. ZAPGM can be used to make an
immediate change to a program that is causing system problems. In most
cases, make program changes by loading and activating a loadset of
programs.
See z/TPF Operations for more information about the ZAPGM command.
E-type loader recycle interface
Main storage
Online
module
Figure 8. E-type load via E-type loader (Online – z/TPF)
Online
module
The E-type loader recycle interface is used to determine whether any program in a
set of programs has changed versions. A long-running process uses the E-type
loader recycle interface to:
v Determine whether the long-running process needs to be recycled to use
different program versions in the long-running process package
v Update the long-running process to allow E-type loader commands such as
ZOLDR ACCEPT and ZOLDR DELETE to complete if the program versions in
the long-running process package have not changed.
The Internet daemon monitor calls the E-type loader recycle interface for all Internet
server applications using the daemon process model except for the debug server
(DBUG) and the z/TPF Internet mail servers (SMTP, IMAP, and POP3). Use the
z/TPF loaders 27

Data loader
Pilot Tape
(SDF)
ZSLDR LOAD DATA n
E-type loader recycle interface user Internet server programs user exit (UERA) to
specify the programs that comprise the Internet server application.
If the E-type loader recycle interface detects a change in any standard library
version, the caller is notified that a recycle is needed. The standard libraries are
CFVS, CISO, CJ00, CLBM, COMS, COMX, CPP1, CTAD, CTAL, CTBX, CTDF,
CTHD, CTIS, and CTXO. Use the E-type loader recycle interface user libraries user
exit (UERL) to specify additional standard libraries.
Related information:
v See tpf_etype_loader_recycle_interface.
v See ZOLDR ACCEPT and ZOLDR DELETE.
v See ECB-controlled program user exits.
Figure 9 shows how the ZSLDR command takes data from a pilot (SDF) tape and
loads it to online modules.
Data Loader
Output Msg
Primary Process
Data Flow
Online
Module
Online
Module
Figure 9. Loading fixed-file records using the ZSLDR command
When system has been brought to 1052 state for the first time by a loader general
file IPL, use the data loader to load it with fixed-file records. These records are
used by the system and by the application programs.
Offline loader support on Linux
28 z/TPF Program Management
Online
Module
You can use the z/TPF offline loader on Linux to write offline image loader
component (TLDR) and offline E-type loader component (OLDR) files to both tape
devices and hierarchical file system (HFS) files. Use the file transfer protocol (FTP)
to send the z/TPF offline loader files that are created in your HFS to a z/TPF

system. Programs and files that have been compiled and linked on Linux do not
need to be moved to a z/OS ® system before the z/TPF offline loader is created.
The virtual reader (VRDR) and general data set (GDS) files, which are currently
supported on MVS, are not supported by the z/TPF offline loader on Linux.
Programming considerations
The following lists the programming considerations for using the z/TPF offline loader
on Linux:
v The maximum file sizes for a z/TPF loader file that is created in the Linux HFS
are:
– 2 gigabytes (GB) for the ext2 file system
– A range of 2 GB - 32 GB for the ext3 file system depending on the block size
that was specified when the file system was initialized
– 2 exabytes (EB) for the file systems used less frequently (such as XFS and
ReiserFS)
– 2 GB for the HFS file system that is implemented on the z/TPF system.
v The size of an offline loader tape data set is limited to the capacity of a single
tape volume.
v The Linux offldr command creates tapes with MVS standard label (SL) headers
and trailers to provide the z/TPF system with SL tapes, which are not supported
by Linux.
See the “Linux offldr command” on page 119 and the Linux man page for more
information about using the z/TPF offline loader on Linux. See “Linux labeltape
command” on page 121 and the Linux man page for more information about using
the z/TPF labeltape command on Linux.
Alternate FCTB loader overview
An alternate FACE table (FCTB) loader loads an FCTB to a z/TPF system without
requiring an initial program load (IPL).
The following ZFCTB commands support alternate FCTB processing:
v ZFCTB LOAD
Loads an alternate FCTB to the online system
v ZFCTB ACTIVATE
Activates an alternate FCTB
v ZFCTB ACCEPT
Accepts an activated alternate FCTB
v ZFCTB DEACTIVATE
Deactivates an activated alternate FCTB
v ZFCTB DELETE
Deletes a loaded or deactivated alternate FCTB.
See z/TPF Operations for more information about the ZFCTB commands. See
“Load an alternate FCTB” on page 83 for more information about the alternate
FCTB loader.
z/TPF loaders 29

Alternate FCTB loader benefits
Use the alternate FACE table (FCTB) loader to perform the following tasks:
v Modify your database without a scheduled outage. This includes:
– Removing deactivated pool extents
– Expanding the number of tracks and cylinders
– Removing or reduce the number of ordinals in fixed file records
– Changing the physical location of records types
– Changing the file address reference format (FARF) address for fixed-file
records.
Attention: Do not use the alternate FCTB loader to modify records that are
critical to the z/TPF system or unexpected results can occur.
See “Alternate FCTB compatibility checking” on page 31 and Table 2 on page 31
for more information about using an alternate FCTB.
v Activate an alternate FCTB on all processors or any specific processor.
v Use the ufct.c user exit to customize compatibility checking for the alternate
FCTB and the existing database. See “Alternate FCTB compatibility checking” on
page 31 for more information about how to ensure that a valid alternate FCTB is
loaded.
v Use the uftz.c user exit to maintain a log of alternate FCTB activity.
Alternate FCTB loader programming considerations
The following lists the programming considerations for the alternate FACE table
(FCTB) loader:
30 z/TPF Program Management
v A maximum of one alternate FCTB and one base FCTB can be loaded for each
z/TPF image.
v If you use the ZFCTB ACCEPT command to accept an alternate FCTB that is
active, that alternate FCTB becomes the base FCTB; no other FCTB exists.
v You must delete or accept the existing alternate FCTB to load another alternate
FCTB.
v The FCTBCLEAR parameter on the @DEFINE control statement specifies if an
existing alternate FCTB on a z/TPF image is cleared or left intact when an initial
program load (IPL) is performed on the z/TPF image. See z/TPF Program
Management for more information about the FCTBCLEAR parameter on the
@DEFINE control statement.
v You can display the status of an alternate FCTB by using the ZIMAG DISPLAY
IMAGE command. See z/TPF Operations for more information about the ZIMAG
DISPLAY IMAGE command and displaying the status of an alternate FCTB.
v If you perform a hard IPL and an active alternate FCTB exists, you will be
prompted in the IPLB program to specify the base FCTB or the alternate FCTB.
If the base FCTB is specified, the alternate FCTB is deactivated. This allows you
to prevent looping errors that result from an alternate FCTB that is not valid.
When a soft IPL is performed, this option is not available.
v The offline loader (TPFLDR) creates the input medium that contains the alternate
FCTB used by the ZFCTB LOAD command. If there are items on the input
medium other than an FCTB, the ZFCTB LOAD command is rejected.
v The alternate FCTB loader is not supported from image 1 to prevent interference
with the general file loader. See z/TPF Program Management for more
information about the general file loader.

Alternate FCTB compatibility checking
To ensure that a valid alternate FACE table (FCTB) is loaded, a compatibility check
is performed with the existing database. The following lists the database
characteristics that are checked:
v CONK tables that are not equal result in a warning being issued. A CONK table
stores the system constants, such as the number of modules, module file status
table (MFST) slots, general file (GF) modules, and control units (CUs).
v Tracks represented in the module configuration (CTSD) table and defined in the
current database must have the same size and duplication when being loaded.
v You cannot modify the #RLOGx record type.
v The subsystem user (SSU) names must be same.
v You cannot add or delete SSUs.
v The subsystem (SS) names must be the same.
The following table lists the alternate FCTB restrictions for critical record types:
Table 2. Alternate FCTB critical record type restrictions
Critical record types Restrictions when loaded using an alternate FCTB
#CIMR1 to
#CIMR8
#CTKA
#CTKD
#CTKX
#CTK0
#CTK2
#CTK3
#CTK6
#IPL1 to #IPL4
#KEYPT
v The location cannot be changed.
v The file address must be the same.
v There cannot be fewer ordinals defined.
v The extents cannot be expanded because the data would be
relocated.
z/TPF loaders 31

32 z/TPF Program Management

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Compiler overview for z/TPF C/C++ support
The z/TPF system requires three compilers to support C/C++ language programs:
an ELF-compatible compiler (GNU compiler collection (GCC) or Systems/C and
Systems/C++), the IBM z/OS C/C++ compiler, and a native Linux C/C++ compiler.
The executable and linking format (ELF)-compatible compiler is required to build the
online z/TPF system and user application programs. C/C++ language programs that
are written for the z/TPF system must be compiled and linked in an ELF format. To
do this, the z/TPF system uses an ELF-compatible compiler, also known as a
cross-compiler, that emits object code specifically for the z/TPF system. The
ELF-compatible compiler runs on Linux and produces object code that is a
specialization of ELF for the z/TPF system. The ELF-compatible compiler is
required because you cannot use the native compiler that comes with Linux to build
z/TPF applications that are written in C/C++ language.
The ELF-compatible compiler links to the GNU C library (glibc) and the GNU
standard C++ library (libstdc++). Each ELF-compatible compiler is associated with a
specific version of the libstdc++ library that it links to. For more information, see
Required z/TPF and z/TPFDF product software.
The IBM z/OS C/C++ compiler is required to build offline utilities, such as tpfldr
and db2pp, on z/OS. It is not used to build programs that are loaded to the online
system.
A native Linux C/C++ compiler is required to build offline utilities, such as tpfobjpp
and offldr, on Linux. It is not used to build programs that are loaded to the online
system.
For more information about the z/TPF ELF-compatible compilers, see “GCC
ELF-compatible compilers” and “Systems/C and Systems/C++ ELF-compatible
compilers” on page 34.
GCC ELF-compatible compilers
For the GNU compiler collection (GCC) executable and linking format
(ELF)-compatible compilers, the z/TPF system supports a staged approach to
upgrading your compiler.
In other words, you can have a combination of compiled product and application
code levels:
v Continue with all product and application code compiled with GCC V4.1.
v Compile all product code with GCC V4.6, with some applications compiled with
GCC V4.6 and some applications compiled with GCC V4.1.
v Compile all product and application code with GCC V4.6.
All of the combinations assume that you installed all of the compiler-related APARs
for the z/TPF system.
GCC V4.6 only
Using the GCC V4.6 compiler exclusively involves installing the compiler-related
APARs, getting and installing the GCC V4.6 compiler, and rebuilding your product
and application code with the GCC V4.6 compiler.
© Copyright IBM Corp. 2005, 2012 33

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GCC V4.1 only
Apply the APARs for GCC V4.6 support even if you do not intend to use V4.6 at
this time. Applying the APARs means that your z/TPF system remains current while
you avoid recompiling your product and application code. You do not need to do
anything else to continue using GCC V4.1 until you are ready to install and use the
GCC V4.6 compiler.
Open source software packages that are available from the University of Illinois
contain separate directories for versions of the libstdc++ library that are specific to
GCC V4.6 and GCC V4.1. You can ignore the version of the library that is specific
to the GCC V4.6 compiler.
Mixed-mode GCC V4.6 and GCC V4.1
After you install the z/TPF system APARs that are associated with GCC V4.6, you
can get and install the GCC V4.6 compiler and rebuild your product code. You can
start getting some of the benefit from GCC V4.6 by compiling some application
code with GCC V4.6 even while some application objects and CSOs remain
compiled with GCC V4.1. For example, you might choose to use the GCC V4.6
compiler for all future compiles while you continue to run with objects and CSOs
that were built with the GCC V4.1 compiler. That is, a C/C++ program that was built
and linked using the GCC V4.1 compiler can call a function in a library that contains
C/C++ code that was built with the GCC V4.6 compiler. The reverse is also true; a
C/C++ program that was built and linked using the GCC V4.6 compiler can call a
function in a library that contains C/C++ code that was built with the GCC V4.1
compiler. This is possible because there is no change to the application binary
interface (ABI) between the two versions of the GCC compiler.
When you want to start using the GCC V4.6 compiler, rebuild all z/TPF product C
and C++ code with the GCC V4.6 compiler before using the compiler with any
C/C++ applications. Rebuilding all z/TPF C and C++ product code is not required,
but is encouraged to help in problem reporting for the z/TPF system. At a minimum,
z/TPF module CPP1 must be rebuilt with the GCC V4.6 compiler and loaded before
any other C/C++ product or application code built with the GCC V4.6 compiler is
loaded.
For more information about GCC on the z/TPF system, see:
v GNU compiler collection (GCC) V4.6 support (APARs PJ39969, PJ39980,
PJ40647, PJ39875, and PM59949)
v “Unpack the GNU compiler collection for the z/TPF system” on page 49
v “Setting the GCC ELF-compatible compiler version to use” on page 55
For more information about the GCC compilers, see the GCC website
(http://gcc.gnu.org).
Systems/C and Systems/C++ ELF-compatible compilers
34 z/TPF Program Management
The z/TPF system supports the Systems/C and Systems/C++ V1.96 compilers as
ELF-compatible compilers.
Install the Systems/C and Systems/C++ V1.96 compilers and apply all of the
compiler-related APARs for z/TPF PUT 9 so that you can use the latest level of the
Dignus C/C++ compilers. By applying the APARs, your z/TPF system remains
current, even if you choose not to use the latest level of the compilers at this time.

|
|
|
|
|
|
|
|
|
|
|
However, your product code must be compiled with the Systems/C and
Systems/C++ V1.96 compilers to benefit from the function provided in this version
of the compilers. You can start to use the Systems/C and Systems/C++ V1.96
compilers gradually, for example, by using the latest version of the compilers for all
future compiles while you continue to run with application objects and CSOs that
were built with the Systems/C and Systems/C++ V1.91 compilers.
For more information about z/TPF support for the Systems/C and Systems/C++
V1.96 compilers, see Systems/C and Systems/C++ V1.96 compilers support
(APARs PJ39875 and PJ40512).
For more information about the Systems/C and Systems/C++ V1.96 compilers, see
the Dignus website (http://www.dignus.com).
Compiler overview for C/C++ support 35

36 z/TPF Program Management

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Common deployment
The z/TPF system uses a mechanism called common deployment to make
deployment descriptors available for use.
A deployment descriptor is an XML file that describes the capabilities and options
for a specific function or component. This XML file must be deployed on the z/TPF
system before it can be used. When a deployment descriptor is deployed, the XML
file is parsed and the results are placed in memory. This process reduces processor
usage for subsequent uses of this information.
Some aspects of deployment are unique to the type of deployment descriptor. For
example, parsing the file and creating the in-memory structure that holds the results
of the parsing. However, there are several tasks that must occur during deployment
that are common to each type of deployment descriptor. In particular, common
deployment handles the following tasks related to deploying a deployment
descriptor on the z/TPF system:
v Validates that the file exists
v Maintains the status of which files are deployed
v Deploys the file again after an IPL
v Provides a mechanism to find the in-memory structure
v Handles any changes to the file; that is, handles a file in a loadset that was
activated or deactivated.
Deployment descriptors that use common deployment are available for use in all
z/TPF states. During restart, common deployment initializes the memory structures
and calls function-unique processing for each deployment descriptor. Additionally, if
a file is deployed, the in-memory structure is marked as available for use.
Common deployment rules and conventions
Deployment descriptors that use common deployment must conform to the following
rules:
v Deployment descriptors must have a unique file extension that identifies the
function or application. Use the format .function_unique_name.xml, where
function_unique_name is the unique name for the deployment descriptor
associated with your function or application. For example, the unique file
extension for a business event specification is .evspec.xml.
v Deployment descriptors are program base unique files that must be loaded to the
/sys/tpf_pbfiles/tpf-fdes/ directory on the z/TPF system with the E-type
loader or the image loader. For more information, see “Loading deployment
descriptors” on page 93.
v Deployment descriptors contain information that is used by common deployment
to find the in-memory structures; that is, a key, a type, and optionally, a version.
The key, type, and version are generated by the function-unique processing that
creates the in-memory structures and are based on the contents of the
deployment descriptor.
Each deployment descriptor must contain a unique combination of key, type, and
version. The type generally correlates to the file extension of the descriptor;
therefore, each descriptor file with the same type must contain a unique
combination of key and version. For deployment descriptors that do not use a
© Copyright IBM Corp. 2005, 2012 37

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
version (for example, .evspec.xml descriptor for business event processing),
each descriptor file must contain a unique key.
You can use the E-type loader to load and activate new versions of deployment
descriptors. These new versions have the same file name and must have the
same key, type, and version as the previously loaded versions.
IBM uses the following conventions for schemas that define deployment descriptors
that use common deployment:
v Include the unique file extension of the deployment descriptor in the schema
name and use the following naming convention: tpf-function_unique_name.xsd,
where function_unique_name is the unique name for the deployment descriptor.
v IBM-delivered schemas are placed on Linux in relative directory
base/tpf-fdes/schema/.
v Schema files must be loaded to the /sys/tpf_pbfiles/tpf-fdes/schema/
directory on the z/TPF system.
Related reference:
Deployment descriptors
Use this information as a reference guide to deployment descriptors that are
supported by the z/TPF system.
Common deployment configuration file
38 z/TPF Program Management
The z/TPF system uses a configuration file to identify each function or component
that uses common deployment.
The common deployment configuration file is a comma-separated values (.csv) file
that is delivered with the z/TPF product code. The file name and location of the
configuration file, as delivered from IBM, is base/tpf-fdes/fdes-config.csv. To use
common deployment, the fdes-config.csv configuration file must be loaded to the
/sys/tpf_pbfiles/tpf-fdes/ directory on the z/TPF system with the image loader.
For more information about the image loader, see “z/TPF loaders” on page 19.
Each row of the common deployment configuration file identifies one type of
deployment descriptor, as described in Table 3.
Table 3. Common deployment configuration file format
Field Description
1 Unique file extension for the deployment descriptor.
2 4-character name of the function-unique processing program.
3 Automatic deployment indicator, where:
YES
Automatically deploys the deployment descriptor the first time that it is loaded
and activated on the system. You can use the ZMDES command with the
UNDEPLOY parameter specified to undeploy the deployment descriptor.
If an existing deployment descriptor is loaded and activated again to make a
change to the descriptor, the existing deployment status is used.
NO Does not automatically deploy the deployment descriptor. Use the ZMDES
command with the DEPLOY parameter specified to deploy the deployment
descriptor.

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 3. Common deployment configuration file format (continued)
Field Description
4 Permanent deployment indicator, where:
YES
Specifies that the deployment descriptor must be deployed permanently. A
deployment descriptor that is permanently deployed cannot be undeployed.
NO Specifies that the deployment descriptor will not be deployed permanently. A
deployment descriptor that is permanently deployed can be undeployed.
For more information about the ZMDES command, see z/TPF Operations.
Common deployment status file
Function-unique processing
The z/TPF system maintains a status file to track the deployment descriptors that
are deployed on each processor. There is one status file for each processor in the
loosely coupled complex.
The status file contains an entry for each deployment descriptor that has an entry in
the common deployment configuration file and exists in the /sys/tpf_pbfiles/tpffdes/
directory. When the z/TPF system IPLs and restart processing builds the
in-memory structures for each deployment descriptor, the status file is used to
determine whether to mark the deployment descriptor as deployed in memory.
Deployment descriptors are marked as deployed in one of the following ways:
v When a deployment descriptor initially is loaded and activated on the z/TPF
system, the descriptor is marked as deployed if the common deployment
configuration file indicates YES for the automatic deployment indicator or the
permanent deployment indicator.
v When the ZMDES command is entered with the DEPLOY parameter specified, the
specified deployment descriptor is marked as deployed. If you specify the IPROC
parameter, the status file for the processor specified by the IPROC parameter is
updated; otherwise, the status file for the processor that you entered the
command from is updated.
See z/TPF Operations for more information about the ZMDES command.
The status file is a hidden file located in the /etc/tpf-fdes directory. The file name
is .status_x, where x is the processor ID associated with the status file. For
example, the full path name for the status file for processor B is
/etc/tpf-fdes/.status_B.
There is some processing that common deployment cannot do for a deployment
descriptor. For these processes, a function-unique processing program is
referenced from the common deployment configuration file.
Function-unique processing handles the following tasks:
v Build in-memory structures.
The function-unique processing program is called to parse the deployment
descriptor and builds a structure in system heap storage to place the results in.
The in-memory structure includes a common deployment standard header
Common deployment 39

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
40 z/TPF Program Management
(tpf/imfdes.h). This standard header consists of a section that is managed by
common deployment and another section that is managed by the function-unique
processing program.
v Cycle to NORM state processing.
The function-unique processing program is called when the system is cycled to
NORM state to handle tasks that cannot be done during z/TPF restart or 1052
state. For example, if the deployment descriptor requires a socket to be started,
function-unique processing starts the socket during cycle to NORM state
processing.
v Clean-up processing.
The function-unique processing program is called when a previous version of a
deployment descriptor must be removed. For example, when a deployment
descriptor is loaded, activated, and accepted with the E-type loader, the previous
version must be removed and the in-memory structure in system heap must be
returned to the system.

Part 2. Tasks
© Copyright IBM Corp. 2005, 2012 41

42 z/TPF Program Management

Acquire and install an ELF-compatible compiler
You cannot use the native compiler that comes with Linux to build the z/TPF
applications written in the C/C++ language. You must use an executable and linking
format (ELF)-compatible compiler for the z/TPF system as a cross-compiler on a
Linux system; that is, the compiler is (potentially built and) used on a system that is
not the z/TPF system, but the compiler produces code that runs correctly on the
z/TPF system.
You can obtain the GNU compiler collection (GCC) source files from the Free
Software Foundation (FSF) or from a third party vendor. You can also obtain a
pre-built ELF-compatible cross-compiler from various third party vendors. See your
IBM service representative for information about the alternatives available, and then
do one of the following:
v If you obtain the GCC source files, continue with “Build the GNU compiler
collection for the z/TPF system” on page 45.
v If you obtain a binary package containing the GCC, continue with “Unpack the
GNU compiler collection for the z/TPF system” on page 49.
v If you obtain a binary package for another compiler, follow the instructions that
come with the compiler.
© Copyright IBM Corp. 2005, 2012 43

44 z/TPF Program Management

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Build the GNU compiler collection for the z/TPF system
Complete the following steps to build the GCC.
Before you begin
v Ensure that you have approximately 5 GB of free DASD to build the executable
and linking format (ELF)-compatible compiler, which is also known as a
cross-compiler.
v Ensure that you have all the tools on Linux that are required to build the
ELF-compatible compiler by installing Linux using the standard option. Go to
http://gcc.gnu.org and see the documentation for installation to verify that you
have all of the prerequisites.
v See your IBM service representative for information about how to get the
following source files:
– gpl-include.tar.bz2 (the Red Hat, Inc. gpl-include file).
– src-cross.tar.bz2 (the ELF-compatible compiler source files).
v Go to http://www.ibm.com/software/htp/tpf/maint/toolsztpf.html to get the IBM
sysroot file that corresponds to the version of the compiler that you are using.
– tpf-sysroot-ibm.version.tar.bz2
v The directory names that are used in the following instructions and examples are
only suggestions; you can use any directory names that are appropriate for your
environment.
Begin
1. Get and unpack the sysroot files.
a. Get the sysroot files if you do not have them and take note of what directory
you place them in, for example, /home/downloads. The sysroot refers to the
following set of two tar files:
v gpl-include.tar.bz2
v tpf-sysroot-ibm.version.tar.bz2
b. Create a directory and unpack the gpl-include files:
mkdir -p /ztpf/tpfcross/sys-root/usr
cd /ztpf/tpfcross
tar -xjf /home/downloads/gpl-include.tar.bz2
Note: After you complete this step, the /gpl-include directory contains a
subdirectory named ./sys-root.
c. Unpack the IBM sysroot:
mv gpl-include/* sys-root/usr/include
rmdir gpl-include
tar -xjf tpf-sysroot-ibm.version.tar.bz2
2. Set up two subdirectories to use for building and installing the compiler:
mkdir /ztpf/tpfcross/build
mkdir /ztpf/tpfcross/install
3. Get and unpack the source package:
a. Get the src-cross tar file if you do not have it and take note of what
directory you place it in, for example: /home/downloads:
© Copyright IBM Corp. 2005, 2012 45

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
46 z/TPF Program Management
src-cross.tar.bz2
b. Unpack the source files to the root directory. Enter the following commands:
cd /ztpf/tpfcross
tar -xjf /home/downloads/src-cross.tar.bz2
After you complete this step, the /ztpf/tpfcross directory contains a
subdirectory named ./src-cross.
4. Build the compiler:
a. Enter the following command from the /ztpf/tpfcross/build directory to
configure the compiler:
/ztpf/tpfcross/src-cross/configure --target=s390x-ibm-tpf
--with-sysroot=/ztpf/tpfcross/sys-root --prefix=/ztpf/tpfcross/install
--program-prefix=tpf- --enable-languages=c,c++
Note: After configure command processing is complete, if you determine
that you made an error or want to change something (for example,
the installation path), you can enter the rm -rf * command from your
build directory (for example, /ztpf/tpfcross/build) and repeat step
4a.
b. Enter the following command from the /ztpf/tpfcross/build directory to
build the compiler:
make
c. Enter the following command from the /ztpf/tpfcross/build directory to
install the compiler:
make install
5. Complete post-build setup and verification:
a. Update (or create) the path variable and environment variables TPF_X_GCC
and TPF_X_LIBS by using an editor to update a profile file (such as
.bash_profile or /etc/profile.local) or by using the command prompt.
For example, enter the following commands if you are using the GCC 4.1.2
compiler:
export PATH=/ztpf/tpfcross/install/bin:${PATH}
export TPF_X_GCC=/ztpf/tpfcross/install/lib/gcc/s390x-ibm-tpf/4.1.2/include
export TPF_X_LIBS=/ztpf/tpfcross/install/lib/gcc/s390x-ibm-tpf/4.1.2
export TPF_INFO=/ztpf/tpfcross/install/share/info
export INFOPATH=$TPF_INFO:$INFOPATH
If you are using the GCC 4.6.3 compiler, enter the following lines into your
.bash_profile file:
export PATH=/ztpf/tpfcross/install/bin:${PATH}
export TPF_X_GCC=/ztpf/tpfcross/install/lib/gcc/s390x-ibm-tpf/4.6.3/include
export TPF_X_LIBS=/ztpf/tpfcross/install/lib/gcc/s390x-ibm-tpf/4.6.3
export TPF_INFO=/ztpf/tpfcross/install/share/info
export INFOPATH=$TPF_INFO:$INFOPATH
b. Optional: To offer a choice of GCC compiler versions to application
programmers, customize the tpftools/include_ztpf/
maketpf_rules_cfg_REDHAT file to set four environment variables to define
the installation location for the supported levels of the compiler:

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1) Uncomment the export directives by removing the leading number sign
(#).
2) Change the TPF_* variables to identify the directories where the versions
are installed. For example, change
#export TPF_X_LIBS:=
to
export TPF_X_LIBS:=/opt/gcc/current/libs
3) Prefix the PATH setting with the directory where the version is installed.
For example:
export PATH:=/opt/gcc/current/bin:$(PATH)
A set of environment variables for GCC V4.1 and GCC V4.6 might look
like this example:
ifeq ($(TPFGCC_VERSION),41)
export TPF_X_GCC:=/opt/gcc/current/tpf_x_gcc
export TPF_X_LIBS:=/opt/gcc/current/libs
export TPF_INFO:=/opt/gcc/current/info
export PATH:=/opt/gcc/current/bin:$(PATH)
endif
ifeq ($(TPFGCC_VERSION),46)
export TPF_X_GCC:=/cteam/jones/tpf-gcc-4.6.3-8/s390x-ibm-tpf/include/c++/4.6.3
export TPF_X_LIBS:=/cteam/jones/tpf-gcc-4.6.3-8/lib/gcc/s390x-ibm-tpf/4.6.3
export TPF_INFO:=/cteam/jones/tpf-gcc-4.6.3-8/share/info
export PATH:=/cteam/jones/tpf-gcc-4.6.3-8/bin:$(PATH)
endif
c. Verify that the compiler was built successfully. Start a new Linux session and
enter the following command:
tpf-gcc -v
If the compiler was built successfully and the directories that are shown in
the examples were used, the following information is displayed if you are
using the GCC 4.1.2 compiler:
Using built-in specs.
Target: s390x-ibm-tpf
Configured with: /ztpf/tpfcross/src-cross/configure
--target=s390x-ibm-tpf --with-sysroot=/ztpf/tpfcross/sys-root
--prefix=/ztpf/tpfcross/install --program-prefix=tpf-
--enable-languages=c,c++
Thread model: tpf
TARGET_SYSTEM_ROOT: /ztpf/tpfcross/sys-root
gcc version 4.1.2 20060724 (GNUPro 06r1-13) for z/TPF PUT05 or later
If you are using the GCC 4.6 compiler, the following example shows the
output from the tpf-gcc -v command:
Using built-in specs.
COLLECT_GCC=tpf-gcc
COLLECT_LTO_WRAPPER=/opt/tpf-11r1-8/H-s390x-linux-gnu/bin/../libexec/gcc/s390x-ibm-tpf/4.6.3/lto-wrapper
Target: s390x-ibm-tpf
Configured with: /opt/redhat/tpf-11r1-8/sources/tools/cross/configure
--disable-bootstrap --host=s390x-linux-gnu --target=s390x-ibm-tpf
--build=s390x-linux-gnu --prefix=/opt/redhat/tpf-11r1-8
--exec-prefix=/opt/redhat/tpf-11r1-8/H-s390x-linux-gnu
--enable-languages=c,c++ --program-prefix=tpf- --without-newlib --with-sysroot
Thread model: tpf
gcc version 4.6.3 20111128 (tpf-11r1-8) for z/TPF PUT09 or later
(s390x-ibm-tpf) (GCC)
6. Set up access to the IBM2047 code page. For more information, see “Set up
access to the IBM2047 code page” on page 53.
Build the GNU compiler collection for the z/TPF system 47

48 z/TPF Program Management

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Unpack the GNU compiler collection for the z/TPF system
You can unpack a binary package as an alternative to building the GNU compiler
collection (GCC).
Complete the following steps to unpack the GCC executable and linking format
(ELF)-compatible compiler, which is also known as a cross-compiler.
1. Set up a directory structure for unpacking the ELF-compatible compiler. For
example, enter the following commands to create a base directory for the tar
files of the compiler, and a subdirectory to use for building and unpacking the
ELF-compatible compiler:
mkdir /ztpf/tpfcross
mkdir /ztpf/tpfcross/build
2. Unpack the binary package:
a. See your IBM service representative for information about how to get the
compiler tar file. Put the tar file in the /ztpf/tpfcross directory.
v /s390x-linux-gnu-x-s390x-ibm-tpf.tar.bz2
b. Go to http://www.ibm.com/software/htp/tpf/maint/toolsztpf.html to get the IBM
sysroot file that corresponds to the version of the compiler that you are
using:
tpf-sysroot-ibm.version.tar.bz2
c. Unpack the binary files to the build directory. Enter the following commands:
cd /ztpf/tpfcross/build
tar -xjf ../s390x-linux-gnu-x-s390x-ibm-tpf.tar.bz2
The gpl-include sysroot files are included in these tar files. After you
complete this step successfully, the /ztpf/tpfcross/build directory contains
the pre-built ELF-compatible compiler.
3. Enter the following command to unpack the sysroot files into, for example, a
directory called /home/downloads:
tar -xjf /home/downloads/tpf-sysroot-ibm.version.tar.bz2
You then have a directory that is called /ztpf/tpfcross/build/sys-root/ for the
IBM sysroot files.
4. Enter one of the following commands to copy the IBM sysroot files to the
ELF-compatible compiler directory.
v For GCC 4.1.2:
/ztpf/tpfcross/build/tpf-06r1-13/H-s390x-linux-gnu/bin/refix
v For GCC 4.6.3:
/ztpf/tpfcross/build/tpf-11r1-8/H-s390x-linux-gnu/bin/refix
You are prompted to enter the location of the IBM sysroot, for example:
/ztpf/tpfcross/build/sys-root. The fully populated sysroot is ready to use.
5. Complete setup and verification:
a. Update (or create) the path variable and environment variables TPF_X_GCC
and TPF_X_LIBS by using an editor to update a profile file (such as
.bash_profile or /etc/profile.local) or by using the command prompt.
For example, enter the following commands if you are using the GCC 4.1.2
ELF-compatible compiler:
export PATH=/ztpf/tpfcross/build/tpf-06r1-13/H-s390x-linux-gnu/bin:${PATH}
export TPF_X_GCC=/ztpf/tpfcross/build/tpf-06r1-13/include/c++/4.1.2
© Copyright IBM Corp. 2005, 2012 49

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
export TPF_X_LIBS=/ztpf/tpfcross/build/tpf-06r1-13/H-s390x-linux-gnu/lib/gcc/s390x-ibm-tpf/4.1.2
export TPF_INFO=/ztpf/tpfcross/build/tpf-06r1-13/share/info
export INFOPATH=$TPF_INFO:$INFOPATH
For example, enter the following commands if you are using the GCC 4.6.3
ELF-compatible compiler:
export PATH=/ztpf/tpfcross/build/tpf-11r1-8/H-s390x-linux-gnu/bin:${PATH}
export TPF_X_GCC=/ztpf/tpfcross/build/tpf-11r1-8/include/c++/4.6.3
export TPF_X_LIBS=/ztpf/tpfcross/build/tpf-11r1-8/H-s390x-linux-gnu/lib/gcc/s390x-ibm-tpf/4.6.3
export TPF_INFO=/ztpf/tpfcross/build/tpf-11r1-8/share/info
export INFOPATH=$TPF_INFO:$INFOPATH
b. Optional: To offer a choice of GCC compiler versions to application
programmers, customize the tpftools/include_ztpf/
maketpf_rules_cfg_REDHAT file to set four environment variables to define
the installation location for each of the supported levels of the compiler:
1) Uncomment the export directives by removing the leading number sign
(#).
2) Change the TPF_* variables to identify the directories where the versions
are installed. For example, change
#export TPF_X_LIBS:=
to
export TPF_X_LIBS:=/opt/gcc/current/libs
3) Prefix the PATH setting with the directory where the version is installed.
For example:
export PATH:=/opt/gcc/current/bin:$(PATH)
A set of environment variables for GCC V4.1 and GCC V4.6 might look
like this example:
ifeq ($(TPFGCC_VERSION),41)
export TPF_X_GCC:=/opt/gcc/current/tpf_x_gcc
export TPF_X_LIBS:=/opt/gcc/current/libs
export TPF_INFO:=/opt/gcc/current/info
export PATH:=/opt/gcc/current/bin:$(PATH)
endif
ifeq ($(TPFGCC_VERSION),46)
export TPF_X_GCC:=/cteam/jones/tpf-gcc-4.6.3-8/s390x-ibm-tpf/include/c++/4.6.3
export TPF_X_LIBS:=/cteam/jones/tpf-gcc-4.6.3-8/lib/gcc/s390x-ibm-tpf/4.6.3
export TPF_INFO:=/cteam/jones/tpf-gcc-4.6.3-8/share/info
export PATH:=/cteam/jones/tpf-gcc-4.6.3-8/bin:$(PATH)
endif
c. Verify that the compiler was built successfully. Start a new Linux session and
enter the following command:
tpf-gcc -v
If the compiler was unpacked successfully and the directories that are
shown in the examples were used, the following information is displayed if
you are using the GCC 4.1.2 compiler:
Using built-in specs.
Target: s390x-ibm-tpf
Configured with: /ztpf/tpfcross/build/tpf-06r1-13/sources/tools/cross/configure --host=s390x-linux-gnu --target=s390x-ibm-tpf
--build=s390x-linux-gnu --prefix=/ztpf/tpfcross/build/tpf-06r1-13 --exec-prefix=/ztpf/tpfcross/build/tpf-06r1-13/H-s390x-linux-gnu
--enable-languages=c,c++ --program-prefix=tpf- --without-newlib --with-sysroot
Thread model: tpf
TARGET_SYSTEM_ROOT:
/ztpf/tpfcross/build/tpf-cross-tools-4.1-tpf-06r1-13/H-s390x-linux-gnu/bin/../s390x-ibm-tpf/sys-root
gcc version 4.1.2 20060724 (GNUPro 06r1-13) for z/TPF PUT05
50 z/TPF Program Management
If you are using the GCC 4.6 compiler, the following example shows the
output from the tpf-gcc -v command:

|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using built-in specs.
COLLECT_GCC=tpf-gcc
COLLECT_LTO_WRAPPER=/opt/tpf-11r1-8/H-s390x-linux-gnu/bin/../libexec/gcc/s390x-ibm-tpf/4.6.3/lto-wrapper
Target: s390x-ibm-tpf
Configured with: /opt/redhat/tpf-11r1-8/sources/tools/cross/configure
--disable-bootstrap --host=s390x-linux-gnu --target=s390x-ibm-tpf
--build=s390x-linux-gnu --prefix=/opt/redhat/tpf-11r1-8
--exec-prefix=/opt/redhat/tpf-11r1-8/H-s390x-linux-gnu
--enable-languages=c,c++ --program-prefix=tpf- --without-newlib --with-sysroot
Thread model: tpf
gcc version 4.6.3 20111128 (tpf-11r1-8) for z/TPF PUT09 or later
(s390x-ibm-tpf) (GCC)
6. Set up access to the IBM2047 code page. For more information, see “Set up
access to the IBM2047 code page” on page 53.
Unpack the GNU compiler collection for the z/TPF system 51

52 z/TPF Program Management

Set up access to the IBM2047 code page
Using EBCDIC code pages
If you enter the tpf-gcc or tpf-g++ options from the command line to compile C or
C++ segments (such as APACHE HTTPD), you must access the IBM2047 code
page for support of the line feed X'15' value, which is used with the 3215 consoles.
To do this, take one of the following actions:
v Linux administrator action
Request that the GNU/Linux system administrator add the following lines in the
/etc/profile file below the TPF_ROOT= statement where the ${TPF_ROOT}
variable expands to the file system path and the z/TPF source code is always
located:
GCONV_PATH=${TPF_ROOT}/linux/gconv:${GCONV_PATH}
Export GCONV_PATH
v User action
Change your $HOME/.bash_profile file.
If the the GCONV_PATH extension is not specified correctly, the tpf-gcc compiler
option will not complete successfully when -fexec-charset=IBM2047 is run on the
command line, and an error message will result. The following example shows the
kind of error message that can result:
cc1: conversion from cpv to IBM2047 not supported by iconv
Note: Setting up access to the IBM2047 code page is not needed for the
Systems/C and Systems/C++ compilers.
EBCDIC code pages, other than IBM2047, that are used exclusively by the z/TPF
system support the line feed X'15' value. The line feed X'15' value is used with
3215 consoles. These code pages might have been modified to properly match
ASCII-based character encoding, which are used as input character sets. If you
enter the tpf-gcc option from the command line to compile C or C++ segments,
you must set up access to these code pages. If you use the Systems/C and
Systems/C++ compilers, contact the provider for more information about EBCDIC
code page support.
If this setup is not necessary for your development environment, you must specify
one of these code pages as the execution time coded character set instead of the
default value of IBM2047. For example, to use the TPF939 code page, which is a
modified version of the IBM939 code page, specify CFLAGS_USER :=
-fexec-charset=TPF939 or CXXFLAGS_USER := -fexec-charset=TPF939 in your
maketpf.cfg file.
© Copyright IBM Corp. 2005, 2012 53

54 z/TPF Program Management

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Setting the GCC ELF-compatible compiler version to use
You can control the GNU compiler collection (GCC) version to use by setting a
variable in the maketpf configuration file.
Before you begin
Your administrator must have customized the tpftools/include_ztpf/
maketpf_rules_cfg_REDHAT file to support more than one version of the GCC
compiler.
Procedure
1. In the maketpf configuration file (maketpf.cfg), define the compiler to use by
setting the MAKETPF_COMPILER variable to REDHAT (MAKETPF_COMPILER :=
REDHAT). REDHAT is the default.
2. Define the compiler version to use by setting the TPFGCC_VERSION variable.
For example, TPFGCC_VERSION := 41 or TPFGCC_VERSION := 46. The default is
determined by querying the version that is found in the PATH environment
variable.
“Build the GNU compiler collection for the z/TPF system” on page 45
“Unpack the GNU compiler collection for the z/TPF system” on page 49
© Copyright IBM Corp. 2005, 2012 55

56 z/TPF Program Management

|
Assemble, compile, and link (build) application programs
The following tasks provide information about setting up the MakeTPF build
solution, building application programs, and other actions that use the MakeTPF
build solution:
v “Define the HFS directory structure and environment files”
v “Set up a configuration file” on page 59
v “Set up automated loading to remote z/OS systems” on page 60
v “Create a single-segment BSO” on page 61
v “Create a single-segment BSO using a generic makefile” on page 62
v “Create a multiple-segment BSO with multiple external entry points” on page 62
v “Use common source files in multiple-segment BSOs” on page 63
v “Add stubs for BAL programs with transfer vectors” on page 64
v “Create a C shared object” on page 64
v “Create an archive for online programs” on page 67
v “Create an offline Linux program” on page 67
v “Create an archive for offline Linux programs” on page 68
v “Create an offline z/OS program” on page 68
v “Create an export file” on page 69
v “Update export files” on page 70
v “Resolve TSOC0001W warnings” on page 70
v “Update the FACE table” on page 71.
Define the HFS directory structure and environment files
One of the first decisions you must make regarding your applications is the
directory structure. There are an unlimited number of ways that you can define the
directory structure, and the structure that you use may vary from application to
application. The directory structure itself is defined to the MakeTPF tools using
environment files, which define a mapping between the file types known to
MakeTPF and the directories that they reside in. As you will see in the following
sections, these environment files are referenced within the makefiles to define
where source files are located and where output files are written.
For the remainder of this information, we use the following directory structure to
represent a set of real-time and offline applications that pertain to billing. This
structure is set up by using the criteria that each of the application types (real-time,
Linux offline, and z/OS offline) have their own source files (asm, c, or cpp), but
share common include and macro files:
billing/
include/
macro/
rt/
exp/
lib/
load/
lst/
obj/
src/
linux/
bin/
lst/
© Copyright IBM Corp. 2005, 2012 57

zos/
obj/
src/
bin/
lst/
obj/
src/
This directory structure is defined to the MakeTPF tools independent from a parent,
or root directory. This enables the MakeTPF tools to associate the directory
structure to one or more root directories at build (assemble, compile, and link) time
and provides the capability of concatenating directory structures in much the same
way that data sets can be concatenated in JCL. The root directories that will be
used are defined in your configuration file by the APPL_ROOT variable and are
referenced in the environment file examples that follow. For more information about
configuration files, see “Configuration files” on page 3 and “Set up a configuration
file” on page 59.
For the billing application example, three corresponding environment files are
needed: one for the real-time applications, one for the Linux offline applications, and
one for the z/OS offline applications. The contents of each environment file follow,
mapping the directory names to the MakeTPF variables that are used for each of
the file types. Each environment file needs only to define the variables that pertain
to that application type.
GNU make syntax is shown in each environment file. The for each statement
expands the directory structure listed previously in this section for each of the root
directories listed in the APPL_ROOT variable, providing the concatenation. The
directories do not need to exist before you run MakeTPF because nonexistent input
directories will be ignored by the tools and output directories will be created as
needed.
Note: For output directories, the first root directory in the APPL_ROOT list will be
considered the output root directory, and listings, objects, and other build
output files will be written under that root directory.
Real-time environment file: maketpf.env_billing
# Input files
ROOTASMDIRS := $(foreach d,$(APPL_ROOT),$d/billing/rt/src) # asm source files
ROOTCDIRS := $(foreach d,$(APPL_ROOT),$d/billing/rt/src) # C source files
ROOTCXXDIRS := $(foreach d,$(APPL_ROOT),$d/billing/rt/src) # C++ source files
ROOTEXPDIRS := $(foreach d,$(APPL_ROOT),$d/billing/rt/exp) # export files
ROOTINCDIRS := $(foreach d,$(APPL_ROOT),$d/billing/include) # include files
ROOTMACDIRS := $(foreach d,$(APPL_ROOT),$d/billing/macro) # macro files
ROOTCPYDIRS := $(foreach d,$(APPL_ROOT),$d/billing/rt/src) # copy files
# Output files
ROOTLIBDIRS := $(foreach d,$(APPL_ROOT),$d/billing/rt/lib) # real-time libraries
ROOTLOADDIRS := $(foreach d,$(APPL_ROOT),$d/billing/rt/load) # real-time loadables
ROOTLSTDIRS := $(foreach d,$(APPL_ROOT),$d/billing/rt/lst) # listings
ROOTOBJDIRS := $(foreach d,$(APPL_ROOT),$d/billing/rt/obj) # object files
Linux offline environment file: maketpf.env_billing_linux
58 z/TPF Program Management
# Input files
ROOTASMDIRS := $(foreach d,$(APPL_ROOT),$d/billing/linux/src) # asm source files
ROOTCDIRS := $(foreach d,$(APPL_ROOT),$d/billing/linux/src) # C source files
ROOTCXXDIRS := $(foreach d,$(APPL_ROOT),$d/billing/linux/src) # C++ source files
ROOTINCDIRS := $(foreach d,$(APPL_ROOT),$d/billing/include) # include files
ROOTMACDIRS := $(foreach d,$(APPL_ROOT),$d/billing/macro) # macro files
ROOTCPYDIRS := $(foreach d,$(APPL_ROOT),$d/billing/linux/src) # copy files

# Output files
ROOTBINDIRS := $(foreach d,$(APPL_ROOT),$d/billing/linux/bin) # linux executables
ROOTLSTDIRS := $(foreach d,$(APPL_ROOT),$d/billing/linux/lst) # listings
ROOTOBJDIRS := $(foreach d,$(APPL_ROOT),$d/billing/linux/obj) # object files
z/OS offline environment file: maketpf.env_billing_zos
Set up a configuration file
# Input files
ROOTASMDIRS := $(foreach d,$(APPL_ROOT),$d/billing/zos/src) # asm source files
ROOTCDIRS := $(foreach d,$(APPL_ROOT),$d/billing/zos/src) # C source files
ROOTCXXDIRS := $(foreach d,$(APPL_ROOT),$d/billing/zos/src) # C++ source files
ROOTINCDIRS := $(foreach d,$(APPL_ROOT),$d/billing/include) # include files
ROOTMACDIRS := $(foreach d,$(APPL_ROOT),$d/billing/macro) # macro files
ROOTCPYDIRS := $(foreach d,$(APPL_ROOT),$d/billing/zos/src) # copy files
# Output files
ROOTBINDIRS := $(foreach d,$(APPL_ROOT),$d/billing/zos/bin) # z/OS executables
ROOTLSTDIRS := $(foreach d,$(APPL_ROOT),$d/billing/zos/lst) # listings
ROOTOBJDIRS := $(foreach d,$(APPL_ROOT),$d/billing/zos/obj) # object files
# Output Link PDS
LINKPDS := $(subst *,LINK,$(word 1,$(APPL_ROOTPDS)))
Note: For the z/OS offline programs, in addition to the directories, a LINK partition
data set (PDS) is required as the repository for the executables. In this
example, the syntax shown will replace an asterisk (*) with the string LINK. It
chooses only the first string provided in the APPL_ROOTPDS variable, which
also is defined in the configuration file.
For our example, we have set up the billing applications so that each of the
environment files is independent of one another, and all three refer to the macro
and include directory. This was done so that each makefile would need to list only
the environment file related to its type (real-time, Linux or z/OS). As an alternative,
we could have created a fourth environment file named
maketpf.env_billing_common that contained only the macro and include variable
definitions, and removed those definitions from each of the other three files. Each
makefile would have to reference both the common and corresponding
program-type makefile. Both approaches work equally well. The approach that you
use really depends on how you want to set up and manage your directory
structures.
Note: Environment files are intended to be set up with respect to either an
application root directory or a z/TPF root directory. The environment files that
are supplied by z/TPF are set up to reference the TPF_ROOT variable, while
application environment files are expected to reference the APPL_ROOT
variable.
Use the configuration file to define the build space and to identify:
v The root directory names where the application and z/TPF code reside. You can
specify multiple root directory names and each will be concatenated. The files will
be pulled on a topdown, first-found basis.
v The z/TPF system or subsystem being built.
v User overrides to compile, assemble, and link flags.
v User overrides to process options, such as whether to keep clean listings.
For the remainder of this information, we define the configuration file as shown in
the following example and expect the file to reside under the name
/home/joe/mywork/build/maketpf.cfg:
Assemble, compile, and link (build) application programs 59

APPL_ROOT := /home/joe/mywork
APPL_ROOT += /home/project1
APPL_ROOT += /usrtpf/z11/app
TPF_ROOT := /home/joe/mywork
TPF_ROOT += /tpf/z11
TPF_BSS_NAME := BSS
The previous example identifies the following:
v That the z/TPF source code can be found by searching the user working
directory structure (/home/joe/mywork) first, and the z/TPF production directory
(/tpf/z11) second.
Note: Even though we are building an application, a user layer is added to the
list of z/TPF root directory names because updates to the control files may
be needed and they are found under the z/TPF directory structure, not the
application directory structure.
v That the application source code can be found by searching the user working
directory structure (/home/joe/mywork) first, a project level directory
(/home/project1) second, and the application production directory
(/usrtpf/z11/app) last.
v That the z/TPF system that the application will be built for is a basic subsystem
with the default name BSS.
To provide the benefit of keeping all output files generated by maketpf for a
particular configuration file in a common directory, use the default name
(maketpf.cfg) and place the file in a directory named build under the first
APPL_ROOT directory listed; and then run all maketpf commands from that same
build directory.
If you are going to build the same code against different systems, consider creating,
for each system, a build/system-name directory containing the config file
(maketpf.cfg) for the system-name system. You would then run all maketpf
commands from the build/system-name directory.
If you prefer a name other than maketpf.cfg, the full path and file name of the
configuration file can be defined in an environment variable named TPF_CFG. For
example, to use a configuration file named bss.cfg in your build directory, you
would enter the following command at the command prompt:
export TPF_CFG=/home/joe/mywork/build/bss.cfg
If the TPF_CFG variable is set, the MakeTPF tools will always use the file defined
by it instead of a file named maketpf.cfg in the current directory.
Set up automated loading to remote z/OS systems
60 z/TPF Program Management
Some offline z/TPF programs are built and run on the z/OS platform. For any
MakeTPF build solution commands that transfer files to or from z/OS, define your
user ID and password in a file named .netrc under your home directory on Linux.
The .netrc file must contain the following information:
machine zoshost login username password password
In the previous example, zoshost is the name of your z/OS UNIX system, username
is your z/OS UNIX user name, and password is your z/OS UNIX password.

Create a single-segment BSO
The .netrc file must be readable only by you. To test the file setup, enter ftp
zoshost from a Linux command prompt. If you are connected automatically to your
z/OS UNIX system, your .netrc file is set up correctly.
If you have a different user name on z/OS UNIX, complete the following steps:
v Add another entry to the .netrc file for the additional user ID.
v In your maketpf.cfg file, set variable S390USER := diffID. This will force the
commands to connect using diffID rather than your Linux ID.
To create and build a BAL shared object (BSO) that has one assembler source file
(as specified by the BEGIN macro) and one entry point, follow these steps:
1. Create a new makefile (/home/joe/mywork/billing/rt/src/bill.mak) as shown
in the following example:
APP := BILL
ASM_SRC := bill.asm
maketpf_env := billing
maketpf_env += base_rt
include maketpf.rules
Note:
a. Both the billing and base_rt environment files are listed because
the base_rt environment file provided by z/TPF is almost always
required to enable the application program to access macros and
includes that are included in z/TPF.
b. The first environment listed defines the owning environment and,
therefore, the corresponding environment file defines the directory
(under the first root directory listed) that will be used for writing
listings, objects, and executables. Both environments are used to
define where the source files (including macros and include files) will
be found.
2. Create a source segment named /home/joe/mywork/billing/rt/src/bill.asm.
3. Update the user control file with an entry for the new program:
a. Create a copy of the control file in your working directory:
cp /tpf/z11/local_mod/base/cntl/usr.cntl /home/joe/mywork/base/cntl/usr.cntl
b. Edit the file that you just copied and add a new entry for the program named
BILL. Enter the following information on one line.
BILL;APP;billing/rt/src/bill.mak;1;ALL;OBJ;TPF_SBALL;LOADONLINE;STUB;DEMAND;DEBUG;
50;PROGRAM;NOGRP;IBM_DEFT;BPAUTH;RESTRICT;MONTC;KEY0;NOCMB;TIMESLICE;;;;;;;;;;;;;
See “Control files” on page 103 for more information about the control file fields
and values.
4. Enter the maketpf command to build the program. This assumes that a file
named maketpf.cfg exists in the /home/joe/mywork/build directory.
cd /home/joe/mywork/build
maketpf bill
See “maketpf utility” on page 6 for more information about the maketpf
command and its options.
Assemble, compile, and link (build) application programs 61

Create a single-segment BSO using a generic makefile
This task shows you how to create and build a generic makefile that you can use to
assemble and link a BSO that has one assembler source file (as specified by the
BEGIN macro) and one entry point, with the convention that the assembler source
file has the same base name as the application name, but is in lowercase with a
.asm file extension. The application name itself will be in uppercase. This enables
one makefile to be used for all BAL applications that match that criteria.
To create a single-segment BSO using a generic makefile, follow these steps:
1. Create a new makefile (/home/joe/mywork/billing/rt/src/generic_bso.mak) as
shown in the following example:
APP := $(shell echo $(TPF_PGM_NAME) | tr [:lower:] [:upper:] )
ASM_SRC := $(shell echo $(TPF_PGM_NAME) | tr [:upper:] [:lower:]).asm
maketpf_env := billing
maketpf_env += base_rt
include maketpf.rules
This makefile is very similar to the single-segment BSO makefile described in
“Create a single-segment BSO” on page 61; however, the value of variable
TPF_PGM_NAME is derived at build time as input to the maketpf command.
2. Create a source segment named /home/joe/mywork/billing/rt/src/bill.asm.
3. Update the user control file with an entry for the new program:
a. Create a copy of the control file in your working directory:
cp /tpf/z11/local_mod/base/cntl/usr.cntl /home/joe/mywork/base/cntl/usr.cntl
b. Edit the file that you just copied and add a new entry for the program named
BILL. Enter the following information on one line.
BILL;APP;billing/rt/src/generic_bso.mak;1;ALL;OBJ;TPF_SBALL;LOADONLINE;STUB;DEMAND;
DEBUG;50;PROGRAM;NOGRP;IBM_DEFT;BPAUTH;RESTRICT;MONTC;KEY0;NOCMB;TIMESLICE;;;;;;;;;;;;;
See “Control files” on page 103 for more information about the control file fields
and values. Again, this makefile is similar to the entry added in “Create a
single-segment BSO” on page 61; however, you can use the same generic
makefile for many applications.
4. Enter the maketpf command to build the program. This assumes that a file
named maketpf.cfg exists in the /home/joe/mywork/build directory.
cd /home/joe/mywork/build
maketpf bill
The string bill is supplied to the generic_bso.mak file to be used as the value
of "TPF_PGM_NAME". See “maketpf utility” on page 6 for more information
about the maketpf command and its options.
Create a multiple-segment BSO with multiple external entry points
62 z/TPF Program Management
BSO programs can contain multiple BAL segments linked together in one BAL
shared object. Each BAL segment in the BSO will have its own entry point, which
by default can be seen external to the program. For these programs, you must
create a unique makefile for the program; a generic makefile cannot be used.
To create a multiple-segment BSO with multiple external entry points, follow these
steps:
1. Create a new makefile (/home/joe/mywork/billing/rt/src/bill.mak) as shown
in the following example:

APP := BILL
ASM_SRC := bill.asm
ASM_SRC += a123.asm
maketpf_env := billing
maketpf_env += base_rt
include maketpf.rules
The only difference from the example in “Create a single-segment BSO” on
page 61 is the addition of a second BAL segment.
2. Create two source segments: /home/joe/mywork/billing/rt/src/bill.asm and
/home/joe/mywork/billing/rt/src/a123.asm.
3. Update the user control file with entries for the new program:
a. Create a copy of the control file in your working directory:
cp /tpf/z11/local_mod/base/cntl/usr.cntl /home/joe/mywork/base/cntl/usr.cntl
b. Edit the file that you just copied and add a new entry for the program named
BILL. Enter the following information on one line.
BILL;APP;billing/rt/src/bill.mak;1;ALL;OBJ;TPF_SBALL;LOADONLINE;STUB;DEMAND;DEBUG;
50;PROGRAM;NOGRP;IBM_DEFT;BPAUTH;RESTRICT;MONTC;KEY0;NOCMB;TIMESLICE;;;;;;;;;;;;;
c. Add a new stub entry for each of the additional entry points.
A123;STUB;billing/rt/src/bill.mak;;ALL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
See “Control files” on page 103 for more information about the control file fields
and values.
4. Enter the maketpf command to build the program. This assumes that a file
named maketpf.cfg exists in the /home/joe/mywork/build directory.
cd /home/joe/mywork/build
maketpf bill
See “maketpf utility” on page 6 for more information about the maketpf
command and its options.
Use common source files in multiple-segment BSOs
As an extension to the multiple-segment BSO topic, it is possible to include the
same BAL source file in two or more BSOs. However, this can lead to a problem
when two or more BSOs have a commonly named entry point. Therefore, an
additional step must be taken to suppress the common entry point in all but one of
the BSOs. To do this, you must use an export file.
To demonstrate, consider two BSOs named BILL and CRDT, both of which contain
source file a123.asm. We want to suppress the external A123 entry point from CRDT
and only export it from BILL. This task assumes that “Create a multiple-segment
BSO with multiple external entry points” on page 62 has been completed before
starting this task.
1. The BILL makefile remains as shown in “Create a multiple-segment BSO with
multiple external entry points” on page 62.
2. Create a new makefile (/home/joe/mywork/billing/rt/src/crdt.mak) as shown
in the following example:
APP := CRDT
ASM_SRC := crdt.asm
ASM_SRC += a123.asm
APP_EXPORT := LIST
maketpf_env := billing
maketpf_env += base_rt
include maketpf.rules
Assemble, compile, and link (build) application programs 63

Adding the line APP_EXPORT := LIST directs the MakeTPF tools to use a file
named CRDT.exp during link time.
3. Create a source segment named /home/joe/mywork/billing/rt/src/crdt.asm.
4. Create an export file named /home/joe/mywork/billing/rt/exp/CRDT.exp
{
global:
CRDT_BSO;
local:
A123_BSO;
};
See “Create an export file” on page 69 for more information about creating
export files.
5. Update the user control file and add a new entry for the program named CRDT.
Enter the following information on one line.
CRDT;APP;billing/rt/src/crdt.mak;1;ALL;OBJ;TPF_SBALL;LOADONLINE;STUB;DEMAND;DEBUG;
50;PROGRAM;NOGRP;IBM_DEFT;BPAUTH;RESTRICT;MONTC;KEY0;NOCMB;TIMESLICE;;;;;;;;;;;;;
See “Control files” on page 103 for more information about the control file fields
and values.
Add stubs for BAL programs with transfer vectors
Create a C shared object
64 z/TPF Program Management
BSOs also can have multiple entry points when transfer vectors are used. No
changes need to be made to the BSO makefiles that are already shown. The only
additional step required is to add STUB entries to the control file for each of the
transfer vector names.
By convention, make the STUB entry in the control file refer to the parent BSO
program makefile name if a unique makefile exists, or to the parent BSO name if a
generic makefile was used to build the parent BSO. For example, if XVB1 is a
transfer vector in the BSO named BILL, the STUB entry in the control file could be
coded as either of the following:
v XVB1;STUB;billing/rt/src/bill.mak;;ALL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
v XVB1;STUB;BILL;;ALL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
The value provided in the third column has no effect on the build of the program or
the stub library; it is used only for reference.
This task shows you how to create and build a new makefile for a C shared object
(CSO). There are many variations on how to code CSOs. A CSO might have only
one entry point, it might be a library that exports some or all of its functions, it might
be a combination of the two, or it might be a main program.
To create a CSO, follow these steps:
1. Create a new makefile (/home/joe/mywork/billing/rt/src/bill.mak) as shown
in the following example:
APP := BILL
C_SRC := billing1.c
C_SRC += billing2.c
maketpf_env := billing
maketpf_env += base_rt
include maketpf.rules

|
The previous example is the minimal amount that you need to code the CSO
makefile. With no other changes, this defines the CSO as exporting all functions
and having an entry named BILL.
Like the BSOs, both the billing and base_rt environment files are listed. The
base_rt environment file included with z/TPF is almost always required to
enable the application program to access macros and includes that are included
in z/TPF. The first environment listed defines the owning environment and,
therefore, the corresponding environment file defines the directory (under the
first root directory listed) that is used for writing listings, objects, and
executables. Both environments are used to define where the source files
(including macros and include files) are found.
a. To define the CSO as a main program, add the following line to the makefile:
APP_ENTRY := main
b. To specify that there is only one entry point for this program and to make all
other functions in the program local to the program, add the following line to
the makefile: APP_EXPORT := ENTRY
c. To define an entry point name, add the following line to the makefile. The
value specified can be any function name or the CSO name: APP_ENTRY :=
EntryName
Note: You must add APP_ENTRY when APP_EXPORT := ENTRY is specified.
If no entry is given, the CSO cannot be entered.
d. To specify that all functions in the CSO can be called externally, no action is
needed; APP_EXPORT := ALL is the default.
Note: You also can specify APP_ENTRY with APP_EXPORT := ALL to define
the entry point name. If no entry is given, the CSO cannot be
entered.
e. To limit the functions in the CSO that can be called externally, add the
following line to the makefile: APP_EXPORT := LIST
This requires that you also create an export file, which defines which
functions are global or local. See “Create an export file” on page 69 for
information about how to create the export file.
An alternative way to limit the functions in the CSO that can be called
externally is to use the -fvisibility compiler option. Specify
-fvisibility=default to indicate that the functions in the CSO are identified
as global for the shared object. Specify -fvisibility=hidden to indicate that
all C/C++ functions are local except where they are coded with
__attribute__((visibility("default"))).
Note: You also can specify APP_ENTRY to define the entry point name. If
no entry is given, the CSO cannot be entered.
f. To call functions in other CSOs, the referenced CSOs must be listed in the
calling makefile. The exception is for any of the CSOs that are defined as
standard libraries, such as:
v CISO
v CLBM
v TPFSTUB
v USRSTUB
v CTIS
v CTAL
v CFVS
Assemble, compile, and link (build) application programs 65

66 z/TPF Program Management
v CTBX
v CTXO
v COMS
v CPP1
v CTAD
v COMX
v CTHD
v CTDF
v CJ00.
For example, to call a function from a CSO named CRDT from the BILL
CSO, add the following line to the makefile: LIBS := CRDT
You can add additional libraries by separating the names by blanks on the
same line, or by adding additional LIBS += XXXX lines.
g. To call functions from an archive, the referenced archive must be listed in
the calling makefile. For example, to call a function from an archive named
TaxFunctions, add the following line to the makefile: ARCHIVES :=
TaxFunctions
You can add additional archives by separating the names by blanks on the
same line, or adding additional ARCHIVES += ArchiveName lines.
Note: A function that is called from a CSO is dynamically loaded at run
time, but a function that is included from the archive is statically
linked in the calling CSO.
h. To change the assemble, compile, or link options, use flags (ASMFLAGS,
CFLAGS, CXXFLAGS, or LDFLAGS) in your makefile or maketpf.cfg file.
For example, when you are migrating to the z/TPF system, you might want
to load programs below the 2-GB bar.
v To load a single program below the 2-GB bar, add the following statement
to an individual makefile: LDFLAGS_(pgm) := -Xlinker --defsym -Xlinker
CGCC_31BIT=0 where pgm is the name of the makefile.
v To load real-time programs below the 2-GB bar, add the following
statement as an overall configuration option to the maketpf configuration
file (maketpf.cfg) before building the shared object: LDFLAGS_USER :=
-Xlinker --defsym -Xlinker CGCC_31BIT=0
Note: All programs that are built after this flag is added are loaded below
the 2-GB bar.
2. Create two source segments named /home/joe/mywork/billing/rt/src/
billing1.c and /home/joe/mywork/billing/rt/src/billing2.c.
3. Update the user control file with a new entry for the new program:
a. Create a copy of the control file in your working directory: cp
/tpf/z11/local_mod/base/cntl/usr.cntl /home/joe/mywork/base/cntl/
usr.cntl
b. Edit the file that you just copied and add a new entry for the program named
BILL. Enter the following information on one line:
BILL;APP;billing/rt/src/bill.mak;1;ALL;OBJ;TPF_SBALL;LOADONLINE;NOSTUB;DEMAND;DEBUG;
50;PROGRAM;NOGRP;IBM_DEFT;BPAUTH;RESTRICT;MONTC;KEY0;NOCMB;TIMESLICE;;;;;;;;;;;;;
See “Control files” on page 103 for more information about the control file fields
and values.

|
|
4. Enter the maketpf command to build the program. This assumes that a file
named maketpf.cfg exists in the /home/joe/mywork/build directory.
cd /home/joe/mywork/build
maketpf bill
See “maketpf utility” on page 6 for more information about the maketpf
command and its options.
See Compiler and system levels by PUT for more information about the
supported compiler levels for each program update (PUT).
Create an archive for online programs
To create and build an archive for online programs, follow these steps:
1. Create a new makefile (/home/joe/mywork/billing/rt/src/TaxFunctions.mak)
as shown in the following example:
ARCHIVE := TaxFunctions
C_SRC := addtax.c
maketpf_env := billing
maketpf_env += base_rt
include maketpf.rules
2. Create a source segment named /home/joe/mywork/billing/rt/src/addtax.c.
3. Update the user control file and add a new entry for the archive named
TaxFunctions. Enter the following information on one line.
TaxFunctions;ARCHIVE;billing/rt/src/TaxFunctions.mak;1;ALL;OBJ;TPF_SBALL;NOLOAD;
NOSTUB;;;;;;;;;;;;;;;;;;;;;;;;;
Note: You must add this archive to the control file before any program that calls
it. In our example tasks, this means that the entry for TaxFunctions must
appear before online program BILL.
See “Control files” on page 103 for more information about the control file fields
and values.
4. Enter the maketpf command to build the program. This assumes that a file
named maketpf.cfg exists in the /home/joe/mywork/build directory.
cd /home/joe/mywork/build
maketpf TaxFunctions
Create an offline Linux program
See “maketpf utility” on page 6 for more information about the maketpf
command and its options.
To create and build an offline Linux program (EXE), follow these steps:
1. Create a new makefile (/home/joe/mywork/billing/linux/src/
CustomerSummary.mak) as shown in the following example:
Note: This program will use functions from an archive named Receipts.
EXE := CustomerSummary
TPF_OL := Linux
ARCHIVES := Receipts
CXX_SRC := list.cpp
maketpf_env := billing_linux
maketpf_env += base_rt
include maketpf.rules
2. Create a source segment named /home/joe/mywork/billing/linux/src/
list.cpp.
Assemble, compile, and link (build) application programs 67

3. Update the user control file and add a new entry for the offline Linux program
named CustomerSummary. Enter the following information on one line.
CustomerSummary;OL;billing/linux/src/CustomerSummary.mak;1;LINUX;
NOOBJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;
See “Control files” on page 103 for more information about the control file fields
and values.
4. Enter the maketpf command to build the program. This assumes a that file
named maketpf.cfg exists in the /home/joe/mywork/build directory.
cd /home/joe/mywork/build
maketpf CustomerSummary
See “maketpf utility” on page 6 for more information about the maketpf
command and its options.
Create an archive for offline Linux programs
To create and build an archive for offline Linux programs, follow these steps:
1. Create a new makefile (/home/joe/mywork/billing/linux/src/Receipts.mak) as
shown in the following example:
ARCHIVE := Receipts
TPF_OL := Linux
CXX_SRC := receipts.cpp
maketpf_env := billing_linux
maketpf_env += base_rt
include maketpf.rules
2. Create a source segment named /home/joe/mywork/billing/linux/src/
receipts.cpp.
3. Update the user control file and add a new entry for the archive named
Receipts. Enter the following information on one line.
Receipts;ARCHIVE;billing/linux/src/Receipts.mak;1;LINUX;
NOOBJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Note: You must add this archive to the control file before any program that calls
it. In our example tasks, this means that the entry for Receipts must
appear before offline program CustomerSummary.
See “Control files” on page 103 for more information about the control file fields
and values.
4. Enter the maketpf command to build the program. This assumes that a file
named maketpf.cfg exists in the /home/joe/mywork/build directory.
cd /home/joe/mywork/build
maketpf Receipts
Create an offline z/OS program
68 z/TPF Program Management
See “maketpf utility” on page 6 for more information about the maketpf
command and its options.
To create and build a new makefile for an offline z/OS program (EXE), follow these
steps:
1. Create a new makefile (home/joe/mywork/billing/zos/src/custsumm.mak) as
shown in the following example:

Create an export file
EXE := custsumm
TPF_OL := OS/390
C_SRC := list.c
maketpf_env := billing_zos
maketpf_env += base_rt
include maketpf.rules
Note: z/OS programs do not support the use of archives and, because the
programs are written to a PDS, the program name must be 8 characters
or less.
2. Create a source segment named /home/joe/mywork/billing/zos/src/list.c.
3. Update the user control file and add a new entry for the offline Linux program
named custsumm. Enter the following information on one line.
custsumm;ARCHIVE;billing/zos/src/custsumm.mak;1;OS/390;
NOOBJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Note: The control file entry uses the value OS/390 ® rather than z/OS. This was
done for compatibility reasons with TPF 4.1 and the terms are
considered interchangeable.
See “Control files” on page 103 for more information about the control file fields
and values.
4. Enter the maketpf command to build the program. This assumes that a file
named maketpf.cfg exists in the /home/joe/mywork/build directory.
cd /home/joe/mywork/build
maketpf custsumm
See “maketpf utility” on page 6 for more information about the maketpf
command and its options.
The following task shows you how to create an export file for a CSO or BSO.
Export files are used to control the entry points that are exported globally and the
ones that are kept local to the object. Export files are required whenever you code
APP_EXPORT := LIST in the program makefile. (An alternate way to change the
scope of symbols that are global for a shared object is to use the -fvisibility
compiler option. Specify -fvisibility=default to indicate that the functions in the
CSO (or C/C++ functions in a BSO) are global for the shared object. Specify
-fvisibility=hidden to indicate that all C/C++ functions are local except where they
are coded with __attribute__((visibility(default))). )
Note: Although we are using a CSO for an example, you can follow the same
steps to create an export file for a BSO.
If you have created a CSO named BILL as described in “Create a C shared object”
on page 64 and have coded APP_EXPORT := LIST in the /home/joe/mywork/billing/
rt/src/bill.mak makefile, you can create an export file by following these steps:
1. Run maketpf to create a preliminary version of the export file.
cd /home/joe/mywork/build
maketpf bill
Note: Export files present a “what came first” problem; you must link the
program to be able to generate the export file, but when you code
APP_EXPORT := LIST, you need an export file at link time. To work around
Assemble, compile, and link (build) application programs 69

Update export files
this, when an export file is not found, the link will continue and a
preliminary export file will be created with all entry points listed in the
global section of the export file.
2. Move the generated export file from the build/ directory to the exp/ directory:
mv /home/joe/mywork/build/BILL.exp /home/joe/mywork/billing/base/exp/BILL.exp
3. Edit the preliminary export file and move entry points from the global section to
the local section of the file to limit the entry points that can be called from other
programs. The result is shown in the following example:
{
global:
create_bill;
local:
calculate_tax;
print_receipt;
};
Note: The export file is used as input to the link editor and must be relinked to the
called shared object. You must update the export file whenever a new entry
point is added to the BSO or CSO. See “Update export files” for more
information.
When you add an entry point to a BSO or CSO with an export file, the export file
must be updated and the entry point added to either the local or global section as
appropriate. The MakeTPF tools will automate some of this process by creating a
copy of the existing export file in the working (build/) directory and inserting the
new entry point into the global section of the new copy of the export file. You must
edit the new export file and use it to replace the old export file in the source
directory (exp/).
Resolve TSOC0001W warnings
70 z/TPF Program Management
You may receive a TSOC0001W warning message after building your program. This
occurs because with the z/TPF implementation of dynamic linkage, there can be
problems with imported data in rare cases. If a program exports any data object
that references an external symbol, dynamic linkage must occur before another
program tries to import the data.
One common cause of this warning is function pointers. If a program exports a
pointer to an external function and another program imports the function pointer
without causing dynamic linkage to take place, the imported function pointer will not
be initialized correctly because it has not been relocated as part of dynamic linkage.
Note: This warning message is not triggered if a function pointer is passed as an
argument to a function. It is only triggered for functions when a function
pointer is exported by a program.
If you receive this warning message, complete one of the following steps to resolve
the warning and avoid possible errors:
v If you do not need to export the symbol, you can prevent it from being exported
by modifying the source code or by using an export file. See “Create an export
file” on page 69 for information about how to prevent the symbol from being
exported.

|
Update the FACE table
v If a function is called before the data is referenced, code
TPF_RUN_TPFSOCHK:=NO in the makefile for the program.
v If the program will not be used before all programs not marked as DEMAND in
the control files have been fetched during restart, ensure that the program is
defined as DEFAULT in its control file and code TPF_RUN_TPFSOCHK:=NO in the
makefile for the program.
v If you must code the program as DEMAND in the control files or if it is coded as
DEFAULT but may be used before all programs not marked as DEMAND in the
control files have been fetched during restart, the programs that are importing the
data objects that triggered the warning can ensure that the exporting program
has been fully fetched by issuing the GETPC macro or getpc function, or by
calling a function in the exporting program before referencing the exported data
object. You also must code TPF_RUN_TPFSOCHK := NO in the makefile for the
program to avoid the warning in the future.
v You also can avoid this warning by marking the program as PRELOAD in its
control file.
See “Control files” on page 103 for reference information about coding control files.
For more information about Makefiles, enter man maketpf.mak on your Linux build
system for a complete list of Makefile variables that can be coded.
To update the file address compute (FACE) program table, follow these steps:
1. Copy the sip.asm file to your user directory. For example, if you are working on
the basic subsystem (BSS), enter:
mkdir -p /home/joe/mywork/bss/src
cp /tpf/z11/bss/src/sip.asm /home/joe/mywork/bss/src/sip.asm
2. Edit the sip.asm file that you just copied and update the data definition
statements (RAMFIL, UFTFTI, ONLFIL, and others).
3. Enter the bldtpf command to generate an alternate FACE table (FCTB). This
example assumes that a file named maketpf.cfg exists in the
/home/joe/mywork/build directory:
cd /home/joe/mywork/build
bldtpf -fctb /home/joe/mywork/bss/src/sip.asm
Note: This command produces an updated FCTB (FCTB.so) and a set of source
files and macros that are produced while assembling the FCTB.o object.
See “bldtpf utility” on page 5 for more information on the bldtpf command; also,
enter man bldtpf on your Linux system for more information, including the
syntax.
4. Enter the fctbval command to check your changes to the FCTB. For example:
fctbval /tpf/z11/bss/load/FCTB.so /home/joe/mywork/bss/load/FCTB.so
This command performs the same FCTB validations that are done online with
the ZFCTB LOAD command and produces a list of differences to help you verify
your changes. If there are validation errors or differences that you do not
expect, repeat the procedure from step 2 and make any necessary corrections.
See “fctbval utility” on page 5 for more information about the fctbval command;
also, enter man fctbval on your Linux system for more information, including
the syntax.
5. Load the alternate FCTB to your z/TPF system. In this example, step 3 placed
the FCTB in /home/joe/mywork/bss/load/FCTB.so.
Assemble, compile, and link (build) application programs 71

72 z/TPF Program Management
Note: If macros were changed, there might be an impact to z/TPF shared
objects other than the FCTB. You must reassemble and load these
objects with the FCTB.

Load system components to a new z/TPF system
After you assemble all system and application programs and generate their data
records, complete the following steps to load the system components to a new
z/TPF system:
1. “Initialize and format the loader general file and online modules.”
2.
Note: If you have an existing loader general file and want to replace only the
IPLA component, see “Update IPLA on a loader general file” on page 79.
“Create the general file loader input file” on page 74
3. “Load system components to the loader general file” on page 74
4. IPL the general file.
5. “Load fixed-file records” on page 74.
6. IPL the online module.
Note: See z/TPF and z/TPFDF System Generation for more detailed information
about loading the loader general file.
Initialize and format the loader general file and online modules
You must initialize the loader general file before you can load system components
to it. The system initialization process (SIP) creates the JCL to perform the
initialization. The JCL uses z/OS utility program ICKDSF to load IPLA and the
volume ID (VOLID) to the general file. The JCL that is created by SIP is placed in
the jcl/ directory of the hierarchical file system (HFS).
Note: If you have an existing loader general file and want to replace only the IPLA
component, see “Update IPLA on a loader general file” on page 79.
Run the real-time disk formatter to format the general file and online modules. The
real-time disk formatter (FMTR) prepares the general file and online modules to
receive system components.
The JCL that is used to initialize and format the loader general file is produced by
SIP and is placed in the HFS. If the root directory name is /home/joe/mywork and
you built the BSS subsystem, the JCL will be placed in /home/joe/mywork/bss/jcl/
lgffmt.jcl. Complete the following steps to format the loader general file:
1. Update the JCL with any local job library information.
2. The JCL references IPLA in the Linux HFS that it was built in. You must change
the referenced HFS to point to the binary mount HFS name, which contains
IPLA, or you will need to move IPLA to a partitioned data set (PDS) and then
reference that PDS.
3. Submit the JCL.
The JCL that is used to initialize and format the online modules is produced by SIP
and is placed in the HFS. If the root directory name is /home/joe/mywork and you
built the BSS subsystem, the JCL will be placed in /home/joe/mywork/bss/jcl/
fmtrdeck.jcl. Complete the following steps to format the online modules:
1. Update the JCL with any local job library information.
2. The JCL references IPLA in the Linux HFS that it was built in. You must change
the referenced HFS to point to the binary mount HFS name, which contains
IPLA, or you will need to move IPLA to a PDS and then reference that PDS.
© Copyright IBM Corp. 2005, 2012 73

3. The JCL also references the format cards produced by the FACE table
generator (fmta.mac, fmtb.mac, and so on). You will need to change the
referenced HFS to the text mount HFS name where the format cards reside or
you will need to move the format cards to a PDS and then reference that PDS.
4. Submit the JCL for each of the online modules to be formatted.
Create the general file loader input file
Create a general file loader input file by entering bldtpf -ald controlfile, where
controlfile is the path to tpf.cntl. See z/TPF and z/TPFDF System Generation for
more information about creating a general file loader input file. See “ALDR input
file” on page 158 for an example of a general file loader input file.
Load system components to the loader general file
Load fixed-file records
74 z/TPF Program Management
Run the TPFLDR offline program with the ALDR parameter specified to load system
components to the general file. You must load the following z/TPF components to
the loader general file by using TPFLDR:
v Core image restart (CIMR) area components.
v CTKX.
v IPLA.
v IPLB.
v Program attribute table (PAT).
v Real-time components that are required in the loader general file and specified in
the control file. See “Control files” on page 103 for more information about control
files
v Keypoints.
Note: You must load all keypoints to the loader general file, but not necessarily
to the online keypoint area. To avoid loading any particular keypoints to
the online keypoint area, specify the keypoints on the @GFKEYPOINT
control statement and do not specify them on the @KEYPOINT control
statement.
Sample JCL is provided in the base/samples/jcl directory.
Complete the following steps to load fixed-file records:
1. Create a pilot tape (symbolic name = SDF) with the system test compiler (STC)
program. See z/TPF Program Development Support Reference for information
about the system test compiler program.
Note: A maximum of 2 147 483 647 records can be read or written from a pilot
tape.
2. Mount the pilot tape (SDF). This is the only input to the data loader.
3. Enter the ZSLDR command to activate the data loader. See z/TPF Operations
for more information about the ZSLDR command.
Note: Once records are loaded to the z/TPF database, no utility is available to
remove the records from the database. If it is necessary to delete
previously loaded records from the z/TPF database, you must create and
load a new pilot tape that contains dummy records. If the number of

ecords decreases from one load to the next, the additional records from
the first load will not be removed from the database.
4. Take either of the following two actions:
a. If the loaded records are meant for main storage, perform an online module
IPL to place the records there.
b. The system can be cycled to NORM state without an online module IPL. An
IPL will be required in the future to place the records in main storage.
Note:
1. The data loader can be operated only while the z/TPF system is in 1052
state unless the ID of the pilot tape is N. If the ID of the pilot tape is N,
the z/TPF system can be in any state.
2. In a loosely coupled facility, the subsystem cannot be above 1052 state
in any processor unless the ID of the pilot tape is N. If the ID of the pilot
tape is N, the subsystem can be in any state.
Load system components to a new z/TPF system 75

76 z/TPF Program Management

Load system components to an existing z/TPF system
Create a new image
Complete the following steps to load system components to an existing z/TPF
system:
1. “Create a new image.”
2. “Create an image loader input file” on page 78.
3. “Load system components to a storage medium” on page 78.
4. “Load system components to the target image” on page 78.
5. “Enable the target image” on page 78.
6. “Move keypoints to the working area (optional)” on page 78.
7. “IPL the image” on page 79.
Note: If you have an existing loader general file and want to replace only the IPLA
component, see “Update IPLA on a loader general file” on page 79.
Before loading system components to an image, you must first have an image. If
you do not have an image, or want to create a new image, complete the following
steps:
1. “Define a new image.”
2. “Copy CTKX, IPL areas, program areas, and CIMR components.”
Define a new image
To define a new image (for example, TPF02) enter ZIMAG DEF TPF02 NUM 2 IPL
x PROG y. Where x is the IPL area and y is the program area for TPF02.
Note: The general file loader always overwrites image 1, which must be defined to
use program area 1 and IPL area 1. Therefore, ensure that you reserve
image 1, program area 1, and IPL area 1 for emergency general file loads.
For more information on defining an image see the ZIMAG DEFINE command.
Copy CTKX, IPL areas, program areas, and CIMR components
To physically copy CTKX, IPL areas, program areas, and CIMR components to the
new image (for example, from TPF01 to TPF02), complete the following steps:
1. Enter ZIMAG COPY TPF01 TPF02 CTKX to physically copy CTKX from image
TPF01 to image TPF02.
Note: CTKX must be loaded or copied to an image before any CIMR
components can be copied.
2. Enter ZIMAG COPY TPF01 TPF02 IPL to physically copy IPL areas from image
TPF01 to image TPF02.
3. Enter ZIMAG COPY TPF01 TPF02 PROG to physically copy program areas
from image TPF01 to image TPF02.
4. Enter ZIMAG COPY TPF01 TPF02 COMP ALL PHYSICAL to physically copy
all CIMR components from image TPF01 to image TPF02.
© Copyright IBM Corp. 2005, 2012 77

To logically copy CIMR components from image TPF01 to image TPF02, use the
ZIMAG COPY LOGICAL command. For example, enter ZIMAG COPY TPF01
TPF02 COMP FCTB.ICDF.ACPL.SIGT.RIAT.USR1.USR2 LOGICAL, assuming that
you are loading a new CPS0.
Note: The CTKX, IPL areas, and program areas cannot be logically copied.
Create an image loader input file
Create an image loader input file by entering bldtpf -tld controlfile, where controlfile
is the path to tpf.cntl or by coding an image loader input file manually. See
“Image loader” on page 113 for more information on creating image loader input
files. See “TLDR input file” on page 159 for an example image loader input file.
Load system components to a storage medium
Run the TPFLDR offline program with the TLDR parameter specified to load system
components to a storage medium. Sample JCL is provided in the samples/jcl
directory. See “z/TPF offline loader” on page 117 for information about running the
TPFLDR program.
Load system components to the target image
Enable the target image
Use the ZTPLD command to load system components from the storage medium to
a target image. See “Online image loader component (ZTPLD)” on page 24 for
more information.
Use the ZIMAG ENABLE command to enable the image that you loaded the system
components to. For example, to enable image TPF02, enter ZIMAG ENABLE
TPF02. You will receive a message that tells you whether the components were
loaded. To display any CIMR components that were not loaded, enter ZIMAG
DISPLAY IMAGE TPF02. This will show you information about all of the CIMR
components for TPF02. If a CIMR component is missing, you can copy it from
another image by entering the ZIMAG COPY command or you can load the missing
component by using the image loader (TLDR). To display any IPL components that
were not loaded, enter ZIMAG DISPLAY IPL and determine from the IPL2 line if
both IPLA and IPLB are loaded. If an IPL area is missing, you must enter ZIMAG
COPY IPL or load the missing area by using the image loader (TLDR).
Move keypoints to the working area (optional)
78 z/TPF Program Management
If the keypoints for the new image are not compatible with the existing image, you
must move the keypoints to the working area (#KEYPT). If the existing keypoints
are compatible with the new image, you do not have to load or move new
keypoints.
Because it is dangerous to overlay keypoints, they are not loaded directly to the
image; they are loaded to a staging area. Use the ZIMAG KEYPT MOVE command
to move the keypoints from the staging area (#KSAx) to the working area
(#KEYPT). The ZIMAG KEYPT MOVE command prompts you to continue (ZIMAG
KEYPT CONT) or abort (ZIMAG KEYPT ABORT). After you move the keypoints to
the working area, perform a hard IPL to put them in core storage.

IPL the image
Note: Keypoints are shared for all images. If there is something wrong with a
keypoint, that prevents you from bringing a system to NORM, IPL your
loader general file and use the ZIMAG KEYPT RESTORE command to
restore the keypoints you had before you entered the ZIMAG KEYPT MOVE
command. This allows you to come up again on your prime mod.
To use the enabled image, you must perform a hard IPL, choose image selection,
and enter the name of the image.
Note:
Update IPLA on a loader general file
1. If you are IPLing an image that has a different core layout from the
previously used image, IPL with CLEAR to clear the VFA buffers.
2. If the image does not IPL successfully, IPL another image and debug the
problem image.
Use the following sample JCL and complete the following steps to place an updated
version of IPLA on an existing loader general file.
Note: Do this only if you have a loader general file that was previously initialized
and formatted and want to replace only the IPLA component without running
the system initialization process (SIP) to generate the JCL. If you are
creating the loader general file for the first time, see “Initialize and format the
loader general file and online modules” on page 73.
//LGFADD EXEC PGM=ICKDSF
//SYSPRINT DD SYSOUT=A
//IPLTDD DD PATH=’/ztpf/aparbld/18974/bss/obj/ipla.o’,
// PATHOPTS=ORDONLY,BLKSIZE=80,LRECL=80
//CUU DD DSN=GNFLBSS,DISP=OLD,UNIT=3390,
// VOL=(PRIVATE,,,,SER=TX0999)
//SYSIN DD *
REFORMAT DDNAME(CUU) NOVERIFY -
IPLDD(IPLTDD) PURGE
/*
1. Update the JCL with any local job library information.
2. The JCL references IPLA in the Linux HFS that it was built in. You must change
the referenced HFS to point to the binary mount HFS name, which contains
IPLA, or you will need to move IPLA to a partitioned data set (PDS) and then
reference that PDS.
3. Ensure that the CUU information matches the CUU information that was used to
create the loader general file initially.
4. Submit the JCL.
Load system components to an existing z/TPF system 79

80 z/TPF Program Management

Load E-type programs and files to an enabled system
Complete the following steps to load new E-type programs and files to a z/TPF
system:
1. “Create an E-type loader input file.”
2. “Load E-type programs and files to a storage medium”
3. “Load, activate, and accept a loadset of programs and files” on page 82.
E-type loader functions affect only the program base that is being used on the
processor that the function was requested from. If other processors are using a
different program base, those processors do not see the effects of E-type loader
functions until they begin to use the same program base.
For example, in a loosely coupled environment where processor A is using program
base 1 and processor B is using program base 2, if you issue the ZOLDR
ACTIVATE command on processor A, the specified loadset is started on all
processors using program base 1. Because processor B is using program base 2,
the specified loadset is not actually activated on that processor until you perform an
initial program load (IPL) using program base 1.
When using the E-type loader to load files, you must use the ZOLDR ACCEPT
command to ensure that the file changes are persistent. In the case of an affiliated
file, changes to the file in the loadset are not reflected in the existing online version.
If you use the E-type loader to move a C function from one program to another, all
callers of the function must be included in the same loadset.
If you use the E-type loader to move an entry point from one program to another,
the loadset must be deactivated or accepted before the entry point can be moved
again.
Create an E-type loader input file
You can create an E-type loader input file on z/OS or Linux.
To create an E-type loader input file based on a control file, enter bldtpf -old. The
bldtpf command, by default, will write the loader input file to bldtpf.old_loaddeck.
Enter man bldtpf for more information.
To manually create an E-type loader input file, create a file containing the E-type
loader input parameters. See “E-type loader” on page 115 for more information.
See “OLDR input file” on page 158 for an example of an E-type loader input file.
Load E-type programs and files to a storage medium
To load an E-type loader input file on z/OS, use the E-type loader JCL cards.
Sample JCL is provided in the base/samples/jcl directory. See “JCL statements” on
page 117 for more information.
You can use the loadtpf command on Linux to load E-type programs and files to
your z/TPF system. You can specify a control file, a loader input file, a load file, a
program name, a file, or a shared object as input and loadtpf will call the bldtpf and
© Copyright IBM Corp. 2005, 2012 81

offldr programs, as necessary, to create a load file that is then transferred to your
z/TPF system by FTP. See “loadtpf utility” on page 6 or enter man loadtpf for more
information.
Note: You also can generate an E-type load file on Linux by entering the offldr
command and specifying an E-type loader input file. You must manually
transfer the generated load file to your z/TPF system. See “Linux offldr
command” on page 119 for more information.
See “Offline E-type loader component (OLDR)” on page 25 for conceptual
information.
Load, activate, and accept a loadset of programs and files
82 z/TPF Program Management
When you have loaded an E-type loader input file to a storage medium, load and
activate the loadset of programs and files by doing the following steps:
1. Use the ZOLDR LOAD command to load a loadset of programs and files from
the storage medium to the system.
2. Use the ZOLDR ACTIVATE command to activate the loadset and test the new
programs and files.
3. Use the ZOLDR ACCEPT command to accept the loadset (if you want to
replace the base version programs with the new versions). See “Accept a
loadset of E-type programs and files” on page 88 for more information.
See “Work with loadsets” on page 87 for more commands that you can use to work
with loadsets.

Load an alternate FCTB
Complete the following steps to load an alternate FACE table (FCTB) on a z/TPF
image:
1. Use the ZFCTB LOAD command to load an alternate FCTB to the online
system.
The following example shows an alternate FCTB being loaded on the ZTPFB
image.
User: ZFCTB LOAD MYGDS
System: FCTB2004I 15.20.24 LOAD REQUEST RECEIVED
FCTB2410I 15.20.29 LOAD OF ALTERNATE FCTB SCHEDULED
FOR CPU B FOR IMAGE ZTPFB
FCTB2410I 15.20.29 LOAD OF ALTERNATE FCTB SCHEDULED
FOR CPU C FOR IMAGE ZTPFB
FCTB2412I 15.20.29 LOAD OF ALTERNATE FCTB COMPLETED
FOR CPU B AS REQUESTED BY CPU B FOR IMAGE ZTPFB
FCTB2412I 15.20.29 LOAD OF ALTERNATE FCTB COMPLETED
FOR CPU C AS REQUESTED BY CPU B FOR IMAGE ZTPFB
FCTB2414I 15.20.29 LOAD OF ALTERNATE FCTB COMPLETED
FOR ALL REQUESTED PROCESSORS FOR IMAGE ZTPFB
2. Use the ZFCTB ACTIVATE command to activate an alternate FCTB that is
loaded on an image for a specific processor or for all processors so that
programs can now use the new FCTB.
The following example activates an alternate FCTB for the ZTPFB image on
processor B.
User: ZFCTB ACT B
System: FCTB2004I 15.20.24 ACTIVATE REQUEST RECEIVED
FCTB2209I 15.26.55 ACTIVATE OF ALTERNATE FCTB SCHEDULED
FOR CPU B FOR IMAGE ZTPFB
FCTB2211I 15.26.55 ACTIVATE OF ALTERNATE FCTB COMPLETED
FOR CPU B AS REQUESTED BY CPU B FOR IMAGE ZTPFB
FCTB2212I 15.26.55 ACTIVATE OF ALTERNATE FCTB COMPLETED
FOR ALL REQUESTED PROCESSORS FOR IMAGE ZTPFB
3. Use the ZFCTB ACCEPT command to accept an activated alternate FCTB.
When an alternate FCTB is accepted, that FCTB becomes the base version and
an alternate FCTB no longer exists.
The following example accepts an alternate FCTB for the ZTPFB image.
User: ZFCTB ACCEPT
System: FCTB2004I 16.03.17 ACCEPT REQUEST RECEIVED
FCTB2304I 16.03.17 ACCEPT OF ALTERNATE FCTB SCHEDULED
FOR CPU B FOR IMAGE ZTPFB
FCTB2306I 16.03.17 ACCEPT OF ALTERNATE FCTB COMPLETED
FOR CPU B AS REQUESTED BY CPU B FOR IMAGE ZTPFB
FCTB2307I 16.05.14 ACCEPT OF ALTERNATE FCTB COMPLETED
FOR ALL REQUESTED PROCESSORS FOR IMAGE ZTPFB
Complete the following steps to deactivate or delete an alternate FCTB that has
been loaded to a z/TPF system:
v Use the ZIMAG DISPLAY command with the IMAGE parameter specified to
display the status of the alternate FCTB.
The following example displays information about the COMMIT1 image. An
alternate FCTB was loaded and has been activated on some processors.
© Copyright IBM Corp. 2005, 2012 83

84 z/TPF Program Management
User: ZIMAG DISP IMAGE COMMIT1
System: IMAG0019I 17.25.51 IMAGE DISPLAY
NAME - COMMIT1 STATUS - ENABLED IPL - 1 PROG - 1 CTKX - ZZ
PAT CREATION TIME 04-26-05 09.26.56
COMP PHYSICAL COPY LOGICAL LOGICAL
VC DATE TIME REF TO IMAGE REF FROM IMAGE
FCTB GA 04-28-05 10.11.32
ALTFCTB KW 04-29-05 08.24.47
CPS0 ZZ 04-26-05 09.26.56 TPF01
ICDF TPF01
ACPL TPF01
SIGT TPF01
RIAT ZZ 04-26-05 09.26.56 TPF01
USR1 TPF01
USR2 TPF01
ALTERNATE FCTB ACTIVE ON PROCESSORS:
BCD
END OF ZIMAG DISPLAY
v Use the ZFCTB DEACTIVATE command to deactivate an activated alternate
FCTB on an image for a specific processor or for all processors where it is
currently active.
The following example deactivates an alternate FCTB for the ZTPFB image.
User: ZFCTB DEACT B
System: FCTB2004I 15.20.24 DEACTIVATE REQUEST RECEIVED
FCTB2509I 15.32.21 DEACTIVATE OF ALTERNATE FCTB SCHEDULED
FOR CPU B FOR IMAGE ZTPFB
FCTB2511I 15.32.21 DEACTIVATE OF ALTERNATE FCTB COMPLETED
FOR CPU B AS REQUESTED BY CPU B FOR IMAGE ZTPFB
FCTB2512I 15.32.21 DEACTIVATE OF ALTERNATE FCTB COMPLETED
FOR ALL REQUESTED PROCESSORS FOR IMAGE ZTPFB
v Use the ZFCTB DELETE command to delete a loaded or deactivated alternate
FACE table (FCTB) from the z/TPF system.
The following example deletes an alternate FCTB for the ZTPFB image.
User: ZFCTB DELETE
System: FCTB2004I 16.00.06 DELETE REQUEST RECEIVED
FCTB2603I 16.00.06 DELETE OF ALTERNATE FCTB SCHEDULED
FOR CPU B FOR IMAGE ZTPFB
FCTB2605I 16.00.06 DELETE OF ALTERNATE FCTB COMPLETED
FOR CPU B AS REQUESTED BY CPU B FOR IMAGE ZTPFB
FCTB2612I 16.05.14 DELETE OF ALTERNATE FCTB COMPLETED
FOR ALL REQUESTED PROCESSORS FOR IMAGE ZTPFB
See “Alternate FCTB loader overview” on page 29 for more information about the
alternate FCTB. See z/TPF Operations for more information about the ZFCTB
commands and the ZIMAG DISPLAY command.

Load z/TPF debugger information
When you run the offline build procedure by using the MakeTPF build solution,
source code is converted into an executable and link format (ELF) module to
produce a shared object. Debug data can be included in this shared object.
The offline loader writes two copies of each shared object to the desired storage
medium: in one of the copies, the debug data is removed; in the other copy, the
debug data remains intact. When running the offline loader, you can use the
@DEFINE control statement in the loader input file to specify whether to write the
shared object with debug data to the desired storage medium.
Note: No debug data is loaded when you use the loader general file loader.
The online load (performed by using the ZOLDR LOAD command or the ZTPLD
command) then writes the shared object containing the debug data to the z/TPF
collection support file system (TFS). The file will be written based on the following
directory structure:
/tpfdbgelf/ab/abcd/ts
Where:
/tpfdbgelf is the root directory
/ab is the first two letters of the program name
/abcd is the four-character program name
/ts is the timestamp given to the shared object by the post-processor.
User exit UELJ determines how many copies of the debug files are kept. You can
use the NODEBUG option in the online loader component to specify that the shared
object with debug data is not to be written to the z/TPF collection support file
system.
If you use the ZAPGM command to change a program that has debug data, the
z/TPF debugger might not display an accurate listing view of the program.
See z/TPF Debugger User's Guide for information about the z/TPF debugger. See
z/TPF Operations for information about the ZOLDR LOAD, ZTPLD, and ZAPGM
commands.
© Copyright IBM Corp. 2005, 2012 85

86 z/TPF Program Management

Work with loadsets
When using loadsets, use the ZOLDR command to complete the following tasks:
v “Clear E-type loader file resident records.”
v “Load a loadset of E-type programs and files.”
v “Activate a loadset of E-type programs and files” on page 88.
v “Selectively activate a loadset of E-type programs and files” on page 88.
v “Deactivate a loadset of E-type programs and files” on page 88.
v “Delete a loadset of E-type programs and files” on page 88.
v “Accept a loadset of E-type programs and files” on page 88.
v “Exclude an E-type program or file from a loadset of E-type programs and files”
on page 89.
v “Reinclude an E-type program or file to a loadset of E-type programs and files”
on page 89.
v “Reclaim system resources” on page 89.
v “Display loadset information” on page 89.
v “Change E-type loader program attributes” on page 90.
v “Change E-type loader values” on page 90.
You can to use the ZDEAT command to display ECB status.
Note: For online help, enter ZOLDR ?, ZDEAT ?, orseez/TPF Operations for
more information about the ZOLDR and ZDEAT commands.
Clear E-type loader file resident records
Use the ZOLDR CLEAR command to clear and initialize all E-type loader file
resident records the first time the system is IPLed or if E-type loader records are
damaged.
Load a loadset of E-type programs and files
Use the ZOLDR LOAD command to load a loadset of programs and files. ZOLDR
LOAD reads program records from an input device and writes them to 4KB fixed file
records; files are written to z/TPF collection support file system (TFS).
Note: If you are loading from a virtual reader, make sure your OLDR job output has
been converted. Use the ELDRVRDR EXEC to convert OLDR JOB output to
a spool file that supports virtual reader input. A sample ELDRVRDR EXEC is
shipped as segment UELV.
The names of the loaded loadsets are maintained in loadset directory (LSD)
records. The names and temporary file locations of the loaded programs are
maintained in E-type loader program directory (EPD) records. The names and
temporary file locations of the loaded files are maintained in the TFS. Loaded
programs and files have no effect on system activity until they are activated.
© Copyright IBM Corp. 2005, 2012 87

Activate a loadset of E-type programs and files
Use the ZOLDR ACTIVATE command to activate a loadset of programs and files.
The programs and files in a loadset are available for use by new entries in the
z/TPF system when the loadset are activated by using the ZOLDR ACTIVATE
command.
Selectively activate a loadset of E-type programs and files
You can control the use of E-type programs and files by selectively activating a
loadset of programs and files. Use the SEL option of the ZOLDR ACTIVATE
command to limit the use of new programs and files to specific terminals, lines,
users, and others.
Note: Use the selective activate user exits to specify the terminals, lines, users,
and others that you want to allow to use a specific loadset of programs and
files. See “Use selective activate exits” on page 91 for information to help
you write the code needed to support the SEL option.
Deactivate a loadset of E-type programs and files
Use the ZOLDR DEACTIVATE command to deactivate a loadset of programs and
files. ZOLDR DEACTIVATE makes all programs and files in a loadset become
inactive when they finish processing. When all programs and files in a loadset are
deactivated, previously active versions of the programs and files are used by new
entries.
Note: The FORCE option processes before any previously scheduled ZOLDR
tasks. It should only be used if ZOLDR DEACTIVATE processing ends with
an error. The FORCE option can change the version of a program or file that
is currently in use by an entry. This could cause interface problems.
Delete a loadset of E-type programs and files
Use the ZOLDR DELETE command to delete a loadset of programs and files.
ZOLDR DELETE makes all of the fixed file records associated with a loadset of
programs and files be returned to the pool of available fixed file records. It also
removes the z/TPF collection support file system (TFS) files associated with a
loadset. ZOLDR DELETE cannot delete an active loadset until it has been
deactivated.
If a program in the loadset is still active, the system changes the loadset name to
-nnnn (where nnnn is 0000–9999) and marks it as delete pending. The system
deletes the renamed loadset when all ECBs using the loadset are finished.
Accept a loadset of E-type programs and files
Use the ZOLDR ACCEPT command to accept a loadset of programs and files.
ZOLDR ACCEPT makes the active loadset of programs and files replace the base
version of existing programs and files. The fixed file records associated with an
accepted loadset of programs and files are deleted after you perform the accept.
Note:
88 z/TPF Program Management
1. The loadset must be activated on all processors to be accepted.

2. A new program or file will not be accepted if there is an ECB on any
subsystem that can still use the base version program or file.
3. If active loadsets intersect, you must accept them in the order they were
activated. That is, the first activated loadset will be the first accepted
loadset.
4. Use the ZOLDR DISPLAY command before accepting a loadset of
programs and files to make sure that you are accepting the correct
version of a program or file.
Exclude an E-type program or file from a loadset of E-type programs
and files
Use the ZOLDR EXCLUDE command to exclude a program or file from an existing
loadset of programs and files. If a loadset is active, ZOLDR EXCLUDE deactivates
the program or file on all processors. A program or file that is excluded from a
loadset of programs and files will not be included in later functions performed on the
loadset. For example, if you exclude the PGM1 program from the GROUP1 loadset,
PGM1 is not activated when you activate GROUP1.
Reinclude an E-type program or file to a loadset of E-type programs
and files
Reclaim system resources
Display loadset information
Use the ZOLDR REINCLUDE command to reinclude a program or file to an existing
loadset of programs and files. A program that is reincluded to a loadset of programs
and files will be included in later functions performed on the loadset. For example, if
you reinclude the program PGM1 to loadset GROUP1 then PGM1 (which had
previously been excluded from GROUP1) is activated when you activate GROUP1.
You must deactivate an active loadset before an excluded program or file can be
reincluded into the loadset.
Use the ZOLDR RECLAIM command to make inaccessible E-type loader fixed file
records available to the system.
If an E-type loader action is interrupted by a system error, some fixed file records
may not be able to be accessed by the system. Although the information in the
records is still available elsewhere, the original fixed file record may not be
accessible. If the fixed file record is not accessible, the system cannot use that disk
space. Therefore, you must enter ZOLDR RECLAIM to allow the system to be able
to use that disk space again.
Note: Your site's procedures will determine how you use the ZOLDR RECLAIM
command. You may want to enter ZOLDR RECLAIM after any E-type loader
RESTART, or you may want to enter ZOLDR RECLAIM every night to
reclaim inaccessible disk space.
Use the ZOLDR DISPLAY command to display the following information:
v Status or contents of a loadset
v Intersections with other loadsets
v Active loadsets
Work with loadsets 89

v All loadsets containing a particular program
v All loadsets
v E-type loader values and rules.
Change E-type loader program attributes
Change E-type loader values
Display ECB status
90 z/TPF Program Management
Use the ZOLDR ALTER PROGCHAR command to change the characteristics of
unallocated E-type programs. The IBM defaults are:
v NOKEY0
v NOMONTC
v NORESTRICT
v NOCMB
v NOBPAUTH
v DBUG
v TIMESLICE
v TIMEOUT=DEFAULT
v FETCH=DEFAULT
v DUMPGROUP=NONE
v AFFINITY=PROGRAM
v TRACEGROUP=IBM_DEFT.
Use the ZOLDR ALTER command to change the following E-type loader values:
v Extra program attribute table (PAT) slot threshold percentage
v E-type loader fixed file record threshold percentage
v Time interval for starting the E-type loader police routine
v Time interval for starting the E-type loader long running job detection routine and
the E-type loader reclaim detection routine.
Use the ZDEAT commands to see the number of ECBs using each activation
number and if the activation number corresponds to a selectively activated loadset.

Use selective activate exits
Selective activate exits allow you to limit the use of an E-type loader loadset to a
specific ECB origin. An ECB origin can be a terminal address, communication line
number, port number, user ID, NCP ALS, NCP name, and others.
To use the selective activate function you must:
v Activate the selective activation function during system generation.
v Create an enable command.
v Create a disable command.
Activate the selective activation function
Create an enable command
You can activate the selective activation function in the CONFIG macro or by using
the ZSYSG command. When activated, selected ECBs can enter the programs and
files in a selectively activated loadset. Otherwise, no ECBs can enter the programs
and files in a selectively activated loadset. See z/TPF Operations for more
information about ZSYSG.
To enable loadsets for specific ECB origins, create a command that builds two
core-resident structures; a selective activation table and a selective activation index.
The selective activation table should contain loadset names and selective activation
numbers. The selective activation index should contain the ECB origins and
pointers to the loadset names. Entries should be added to these structures using a
user-defined enable message. To do this your command should do the following:
1. Add the ECB origin to the selective activation index.
2. If the loadset name is already in the selective activation table, update the index.
3. If the loadset name is not in the selective activation table, add the entry and call
the selective activate utility (COLW) to set the activation number. Update the
index.
Note: COLW returns an activation number of zero if the loadset has not been
selectively activated.
4. Update the file resident structure (if one exists) to allow enable requests to
survive an IPL.
Figure 10 shows an example of a selective activation table. Figure 11 on page 92
shows an example of a selective activation index.
Loadset Name Selective Activation Number
------------ ---------------------------
Joseph 0
Sally 4
Fred1 8
Figure 10. Selective activation table example
Note: In Figure 10, Joseph was enabled to be used from an ECB origin, but is not
yet activated selectively. Loadsets Sally and Fred1 were selectively activated
and were assigned activation numbers 4 and 8, respectively.
© Copyright IBM Corp. 2005, 2012 91

Terminal Addr Index into Selective Activation Table
------------- ------------------
020103 0
030567 0, 1
002203 1
292834 1, 2
Figure 11. Selective activation index example
Create a disable command
92 z/TPF Program Management
Note: Figure 11 contains a list of ECB origins (terminal addresses) and the
associated index into the selective activation table. In this example, ECBs
originating on terminal 292834 can enter programs and files from loadsets
Sally or Fred1.
The user-defined disable command should stop an ECB from using a loadset. This
message should remove the index pointer for the selective activation index entry,
and if there are no more index entries that reference the specified loadset, remove
the associated selective activation table entry (if there are no more ECB origins that
reference a loadset, there is no longer a need to maintain the activation number in
the selective activation table). If there are no more loadsets enabled to be used by
the specified ECB origin, then the index entry can be removed. By removing the
table index from the index entry, ECBs originating from that origin will not have the
specified loadset's activation number in their activation number list (which is used
by Enter / Back to determine which version of a program or file to use). If a file
copy of the mapping structure is maintained, then it will have to be updated to
reflect the disable request.
Note: It is entirely possible that the loadset name will not be found in either table.
The user-written disable code should handle this condition. This can occur
for 2 reasons:
1. The loadset was selectively activated, but never enabled. Here, a table
entry for the loadset was never created.
2. It is possible that the loadset was enabled; however, the mapping
structure is not recorded on file (for example, the enables do not survive
an IPL). If an IPL were to occur after the enable and before the disable
request, the disable code would not find the loadset in the tables.

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using common deployment
You must load your deployment descriptors to the z/TPF system with the E-type
loader or the image loader. After the descriptors are loaded to the system, you can
use the ZMDES command to deploy and undeploy the descriptor files.
Related concepts:
“Common deployment” on page 37
The z/TPF system uses a mechanism called common deployment to make
deployment descriptors available for use.
Related reference:
ZMDES–Manage deployment descriptors
Loading deployment descriptors
Use this procedure to load your deployment descriptors to the z/TPF system with
the E-type loader.
About this task
You can use the E-type loader or the image loader to load your deployment
descriptors. This procedure is an example of how to load the descriptor files with
the E-type loader.
Procedure
1. On Linux, create an offline loader input file that defines where to find the
deployment descriptors on Linux and where to place them on the z/TPF system.
The following example shows the contents of an offline loader file called
ddfiles.list:
@DEFINE
SYSID=BSS
@LOADSET DESCRIPT
@FILE
/home/mydir/wodmDrvr.ilr.xml /sys/tpf_pbfiles/tpf-fdes/wodmDrvr.ilr.xml
/home/mydir/wodmDrvr.ept.xml /sys/tpf_pbfiles/tpf-fdes/wodmDrvr.ept.xml
/home/mydir/wodmDrvr.tdm.xml /sys/tpf_pbfiles/tpf-fdes/wodmDrvr.tdm.xml
/home/mydir/bepDrvr.evspec.xml /sys/tpf_pbfiles/tpf-fdes/bepDrvr.evspec.xml
/home/mydir/bepDrvr.evda.xml /sys/tpf_pbfiles/tpf-fdes/bepDrvr.evda.xml
2. On Linux, generate the OLDR format loader output file by entering the loadtpf
command with the input file that you created in step 1 specified.
For example, loadtpf ddfiles.list.
The following messages are displayed. In this example, the files are transferred
automatically to the z/TPF system based on a LOADTPF_IP parameter that is
specified in the maketpf.cfg file.
© Copyright IBM Corp. 2005, 2012 93

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
94 z/TPF Program Management
MTPF2210I: Configuration file: "/home/mydir/maketpf.cfg"
MTPF2706I: loadtpf: Using loader input file "wodmfiles.list".
MTPF2701I: loadtpf: Generating offldr output file.
Command: "offldr oldr -o /home/mydir/mydir.oldr -l /home/mydir/ddfiles.list
-r /home/mydir/OLDR.report "
MTPF2709I: offldr return code: 0
The following messages were generated:
LOAD0010I Parsing step ended with return code 0.
LOAD0020I Load step ended with return code 0.
MTPF2702I: loadtpf: FTPing offldr output file.
Command: "echo -e "open 9.57.13.44 \n user ftp ******** \n binary \n epsv4
\n cd /mytpf \n put /home/mydir/mydir.oldr mydir.oldr \n" | ftp -v -n"
Connected to 9.57.13.44.
220 TPF FTP server (Version 1.01) ready.
331 Guest login ok, type your name as password.
230 Guest login ok, access restrictions apply.
Remote system type is UNIX.
Using binary mode to transfer files.
200 Type set to I.
EPSV/EPRT on IPv4 off.
250 CWD command successful.
local: /home/mydir/mydir.oldr remote: mydir.oldr
227 Entering Passive Mode (9,57,13,44,4,4)
150 Opening BINARY mode data connection for ’mydir.oldr’.
226 Transfer complete.
90090 bytes sent in 00:00 (751.58 KB/s)
221 Goodbye.
MTPF2713I: loadtpf ended, RC=0.
3. On the z/TPF system, define a path to the directory where the OLDR format
output file resides by entering the ZDSMG DEFINE command.
For example, ZDSMG DEFINE CMDEPLOY PATH='/mytpf/mydir.oldr'.
The following messages are displayed:
CSMP0097I 15.16.37 CPU-B SS-BSS SSU-HPN IS-01
CSMP0099I 15.16.37 010000-B ZDSMG DEFINE CMDEPLOY PATH=’/MYTPF/MYDIR.OLDR’+
CSMP0097I 15.16.37 CPU-B SS-BSS SSU-HPN IS-01
DSMG0001I 15.16.37 DDNAME CMDEPLOY DEFINED+
4. On the z/TPF system, load the loadset to the system by entering the ZOLDR LOAD
command.
For example, ZOLDR LOAD CMDEPLOY.
The following messages are displayed:
CSMP0097I 15.16.41 CPU-B SS-BSS SSU-HPN IS-01
CSMP0099I 15.16.41 010000-B ZOLDR LOAD CMDEPLOY+
CSMP0097I 15.16.41 CPU-B SS-BSS SSU-HPN IS-01
OLDR1016I 15.16.41 CELA - LOAD REQUEST RECEIVED+
OLDR3000I 15.16.41 CLD0 - LOADSET DESCRIPT HAS BEEN LOADED FROM DDNAME CMDEPLOY+
CSMP0097I 15.16.41 CPU-B SS-BSS SSU-HPN IS-01
OLDR3001I 15.16.41 CELL - LOAD FOR DDNAME CMDEPLOY COMPLETED+
5. On the z/TPF system, activate the loadset by entering the ZOLDR ACTIVATE
command.
For example, ZOLDR ACTIVATE DESCRIPT.
The following messages are displayed:

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CSMP0097I 15.17.02 CPU-B SS-BSS SSU-HPN IS-01
CSMP0099I 15.17.02 010000-B ZOLDR ACTIVATE DESCRIPT+
CSMP0097I 15.17.02 CPU-B SS-BSS SSU-HPN IS-01
OLDR1016I 15.17.02 CELA - ACTIVATE REQUEST RECEIVED+
CSMP0097I 15.17.02 CPU-B SS-BSS SSU-HPN IS-01
OLDR2036I 15.17.02 ACTIVATE OF LOADSET DESCRIPT SCHEDULED
FOR CPU B +
CSMP0097I 15.17.02 CPU-B SS-BSS SSU-HPN IS-01
OLDR2036I 15.17.02 ACTIVATE OF LOADSET DESCRIPT SCHEDULED
FOR CPU C +
CSMP0097I 15.17.02 CPU-B SS-BSS SSU-HPN IS-01
OLDR2036I 15.17.02 ACTIVATE OF LOADSET DESCRIPT SCHEDULED
FOR CPU D +
:
:
CSMP0097I 15.17.02 CPU-B SS-BSS SSU-HPN IS-01
OLDR2036I 15.17.02 ACTIVATE OF LOADSET DESCRIPT SCHEDULED
FOR CPU 6 +
CSMP0097I 15.17.02 CPU-B SS-BSS SSU-HPN IS-01
CYC10007I 15.17.02 POOL TYPE SST DEVICE DEVA COUNTS 1100 IN USE
FIRST TIME THE DIRECTORY IS BEING USED SINCE LAST REALLOCATION+
CSMP0097I 15.17.02 CPU-B SS-BSS SSU-HPN IS-01
OLDR2015I 15.17.02 CEL2 - LOADSET DESCRIPT ASSIGNED ACTIVATION
NUMBER 1 ON CPU B+
CSMP0097I 15.17.02 CPU-B SS-BSS SSU-HPN IS-01
OLDR2043I 15.17.02 ACTIVATE OF LOADSET DESCRIPT COMPLETED
FOR CPU B AS REQUESTED BY CPU B+
CSMP0097I 15.17.10 CPU-B SS-BSS SSU-HPN IS-01
OLDR2043I 15.17.10 ACTIVATE OF LOADSET DESCRIPT COMPLETED
FOR CPU C AS REQUESTED BY CPU B+
CSMP0097I 15.17.10 CPU-B SS-BSS SSU-HPN IS-01
OLDR2043I 15.17.10 ACTIVATE OF LOADSET DESCRIPT COMPLETED
FOR CPU D AS REQUESTED BY CPU B+
:
:
CSMP0097I 15.17.10 CPU-B SS-BSS SSU-HPN IS-01
OLDR2043I 15.17.10 ACTIVATE OF LOADSET DESCRIPT COMPLETED
FOR CPU 6 AS REQUESTED BY CPU B+
6. On the z/TPF system, remove the data definition name that was previously
defined by entering the ZDSMG RELEASE command.
For example, ZDSMG RELEASE CMDEPLOY.
The following messages are displayed:
CSMP0097I 15.17.45 CPU-B SS-BSS SSU-HPN IS-01
CSMP0099I 15.17.45 010000-B ZDSMG RELEASE CMDEPLOY+
CSMP0097I 15.17.45 CPU-B SS-BSS SSU-HPN IS-01
DSMG0014I 15.17.45 DDNAME CMDEPLOY RELEASED+
Results
All deployment descriptors that are specified in the loader input file are loaded to
the /sys/tpf_pbfiles/tpf-fdes/ directory on the z/TPF system. Additionally, any
deployment descriptor that is listed in the common deployment configuration file
with the automatic deployment indicator set to YES is automatically deployed.
What to do next
To deploy any deployment descriptors that were not defined to automatically deploy,
enter the ZMDES command with the DEPLOY parameter specified.
You can display all deployment descriptors that are currently deployed by entering
ZMDES DISPLAY. For example:
Using common deployment 95

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CSMP0097I 15.29.17 CPU-B SS-BSS SSU-HPN IS-01
CSMP0099I 15.29.17 010000-B ZMDES DISP+
CSMP0097I 15.29.17 CPU-B SS-BSS SSU-HPN IS-01 _
MDES0016I 15.29.17 DISPLAY OF ALL DEPLOYMENT DESCRIPTORS FOR PROCESSOR B
IN-MEMORY FILE
STATUS STATUS FILE NAME
DEPLOYED DEPLOYED /sys/tpf_pbfiles/tpf-fdes/wodmDrvr.ept.xml
DEPLOYED DEPLOYED /sys/tpf_pbfiles/tpf-fdes/wodmDrvr.ilr.xml _
DEPLOYED DEPLOYED /sys/tpf_pbfiles/tpf-fdes/wodmDrvr.tdm.xml
DEPLOYED DEPLOYED /sys/tpf_pbfiles/tpf-fdes/bepDrvr.evspec.xml
DEPLOYED DEPLOYED /sys/tpf_pbfiles/tpf-fdes/bepDrvr.evda.xml
END OF DISPL
Related reference:
ZMDES–Manage deployment descriptors
Related information:
“E-type loader” on page 115
“Image loader” on page 113
Removing a deployment descriptor
Use this procedure to remove a deployment descriptor from the z/TPF system.
Procedure
1. Delete or accept any active or inactive loadsets that contain the deployment
descriptor that you want to remove. Wait for the delete or accept operation to
complete before you continue to the next step.
2. Undeploy the deployment descriptor.
a. To undeploy the deployment descriptor on all inactive processors, enter
ZMDES UNDEPLOY FILE-descriptor IPROC-ALL, where descriptor is the file
name of the descriptor.
b. To undeploy the deployment descriptor on all active processors, enter
ALL//ZMDES UNDEPLOY FILE-descriptor, where descriptor is the file name of
the descriptor.
If the deployment descriptor is permanently deployed, an error is issued
because you cannot undeploy a permanently deployed descriptor. If this error
occurs, ensure that the deployment descriptor is no longer used before you
continue to step 3.
3. Remove the deployment descriptor from the file system by entering ZFILE rm
/sys/tpf_pbfiles/tpf-fdes/descriptor, where descriptor is the file name of
the descriptor.
Results
96 z/TPF Program Management
In-memory structures that are associated with the deployment descriptor continue to
exist until the next IPL. Additionally, the deployment descriptor file name remains in
the common deployment status file until the next IPL.
What to do next
At your convenience, IPL the prime module and cycle the z/TPF system to NORM
state to clean up memory and the common deployment status file.

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Related reference:
ZMDES–Manage deployment descriptors
Related information:
“Work with loadsets” on page 87
Handling an error during IPL after common deployment is installed
After common deployment is loaded on your z/TPF system, if you IPL an additional
processor in your loosely coupled complex, you might receive errors during restart.
About this task
Before you load common deployment to the z/TPF system in a loosely coupled
complex, you must ensure that the version control file index (VCFX), process
pseudo-file system (PROCFS), and the system pseudo-file system (SYSFS) are all
mounted on each processor. If you IPL an additional processor in the loosely
coupled complex and these file systems are not mounted on that processor, you
might receive errors during restart. In particular, you might receive message
FDES0011W. Use this procedure to correct the problem.
Procedure
1. In 1052 state, cycle up get file storage (GFS). Enter ZPOOL 1052 UP.
2. Mount the version control file index (VCFX).
3. Mount the process pseudo-file system (PROCFS).
4. Mount the system pseudo-file system (SYSFS).
5. Cycle down GFS. Enter ZPOOL 1052 DOWN.
6. IPL the processor again.
Related concepts:
“Common deployment” on page 37
The z/TPF system uses a mechanism called common deployment to make
deployment descriptors available for use.
Related reference:
ZPOOL 1052–Cycle get file storage support up or down in 1052 state
Related information:
z/TPF file system support
Using common deployment 97

98 z/TPF Program Management

Part 3. Reference
© Copyright IBM Corp. 2005, 2012 99

100 z/TPF Program Management

Export files
The following example shows the C shared object (CSO) export file used when
APP_EXPORT:=ENTRY. The global section lists common symbols that are required by
the z/TPF system. All other symbols are specified as local. This export file is
located at base/exp/app_entry.exp
{
global:
CGCC_31BIT;
__TPF_soinit;
main;
__do_global_ctors_aux;
__do_global_dtors_aux;
__TPFSUD;
local:
*;
};
An alternate way to define functions as global or local for CSOs is to use the
-fvisibility compiler option. Specify -fvisibility=hidden to identify all C/C++ functions
as local except where they are coded with __attribute__((visibility(default))).
An alternate and preferred method to define functions as local for shared objects
that contain assembler code is to use the APP_EXPORT := VISIBILITY makefile
setting.
For more information about export files, called version scripts by the GNU compiler
collection (GCC), go to http://www.gnu.org.
© Copyright IBM Corp. 2005, 2012 101

102 z/TPF Program Management

Control files
The following table provides details about the various types of control files that are
included by IBM.
Note:
1. base/cntl/tpf.cntl and base/cntl/usr.cntl are the only control files
known to the MakeTPF build solution. All other files listed are included by
these two files. These files are included with the z/TPF system to group
and categorize z/TPF programs.
2. To prevent your changes from being overwritten when you make
modifications to these control files, copy them to the
local_mod/base/cntl directory and make your changes to these copies.
For more information about the local_mod/ directory, see “Local
modifications” on page 7.
Table 4. Control file descriptions included by IBM
Control file name and location Description
base/cntl/tpf.cntl List of all z/TPF programs with their build
and load options.
base/cntl/usr.cntl List of all customer programs with their build
and load options.
base/cntl/tpf_app_base.cntl List of all z/TPF applications.
base/cntl/tpf_app_base_ux.cntl List of all z/TPF application user exits.
base/cntl/tpf_app_base_xv.cntl List of all z/TPF transfer vectors and stubs
for multi-segment BSO entry points.
base/cntl/tpf_app_hpo.cntl List of all z/TPF HPO applications. Includes
any archives needed to build the
applications.
base/cntl/tpf_app_tpfdf.cntl List of all z/TPFDF applications.
base/cntl/tpf_app_tpfdf_ux.cntl List of all z/TPFDF application user exits.
base/cntl/tpf_app_tpfdf_xv.cntl List of all z/TPFDF transfer vectors and stubs
for multi-segment BSO entry points.
base/cntl/tpf_app_usr.cntl List of all customer system programs. Use to
list customer programs needed to build the
z/TPF system.
base/cntl/tpf_cimr.cntl List of all z/TPF CP, CIMR, IPL programs.
Any ARCHIVES needed to link these
programs also are included.
base/cntl/tpf_kpt.cntl List of all z/TPF keypoints.
base/cntl/tpf_ol_linux.cntl List of all z/TPF offline programs that run on
the Linux platform. Archives needed to link
the offline programs also are included.
base/cntl/tpf_ol_os390.cntl List of all z/TPF offline programs that run on
the z/OS platform.
base/cntl/tpf_stdlib.cntl List of all standard libraries and includes.
base/cntl/tpf_util_linux.cntl List of all z/TPF utility programs that run on
the Linux platform. Archives needed to link
these utilities also are included.
© Copyright IBM Corp. 2005, 2012 103

|
104 z/TPF Program Management
For details about the content and format, see the prolog of base/cntl/tpf.cntl.

|
|
|
|
|
|
|
XML descriptor control files
The base/cntl/tpf.cntl_tdmdd and base/cntl/usr.cntl_tdmdd files are shipped
with your z/TPF system to list the XML descriptor files and the artifacts that should
be created from each.
For a detailed description of the file content and format, see the prolog of the
base/cntl/tpf.cntl_tdmdd file.
© Copyright IBM Corp. 2005, 2012 105

106 z/TPF Program Management

Load files for version control
The base/cntl/tpf.loadfile and base/cntl/usr.loadfile files are shipped with
your z/TPF system to group and categorize z/TPF files.
The following table describes the record types that are supported by the
base/cntl/tpf.loadfile and base/cntl/usr.loadfile files.
Table 5. Load file record type support
Load file record type Description
Comment A line that begins with the # delimiter.
Include A line reference to a load file that is to be
included on the z/TPF system. Use the
following format:
include filename
where filename is a relative file name such
as base/cntl/tpf_comms.loadfile, which is
found under the TPF_ROOT or APPL_ROOT
directories.
The include statements are only supported in
the base/cntl/tpf.loadfile and
base/cntl/usr.loadfile files.
File entry A line delimited with a semicolon that
contains the file descriptor data, as outlined
in the Table 6.
Version statement The file version of the load list.
The following table provides details about the information that you need to enter in
each column of the load file. See the prolog of the base/cntl/tpf.loadfile file for
more details about the load file format requirements.
Table 6. Load file column definitions
Column
Number Field Name Values Comments
© Copyright IBM Corp. 2005, 2012 107

108 z/TPF Program Management
Table 6. Load file column definitions (continued)
1 Source path Free-form edit v The relative or absolute path
of the file on Linux that is to
be loaded to the z/TPF
system.
If the MakeTPF build solution
determines that the file does
not use the source path as an
absolute path:
– The files in the
base/cntl/tpf.loadfile
file are relative to the
TPF_ROOT directory
– The files in
base/cntl/usr.loadfile
are relative to the
APPL_ROOT directory.
v Pathnames for
configuration-dependent files
can use the string to
represent the configuration
dependent directory name.
The MakeTPF build solution
will replace with the
directory name derived from
the values of
TPF_BSS_NAME,
TPF_SS_NAME, and
TPF_BAS_DIRNAME, defined
in the maketpf configuration
file.
v Example names:
/loadfiles/
data.txt,ztpf/prod/
loadfiles/data.txt,
home/user/myprj//
loadfiles/data.txt
2 Target path Free-form edit v The absolute path on a z/TPF
system.
v The program base unique files
must be loaded to the
/sys/tpf_pbfiles directory.
3 Permission See the permission parameter on
the “@FILE” on page 139 control
statement for more information.
4 Owner Free-form edit See the newowner parameter on
the ZFILE chown command for
more information.
5 Group Free-form edit See the newgroup parameter on
the ZFILE chown command for
more information.

Table 6. Load file column definitions (continued)
6 Source file data
type
v
v
BINARY
TEXT
v ONLINE
7 System
allocation
v ALL
v BSS
v EXC
v ssname
Specifies the data type of the file
that is loaded to the z/TPF
system. Explanation of the
supported values:
BINARY
specifies that the source file
contains binary data that
does not require text
translation when loaded on
the z/TPF system.
TEXT
specifies that the source file
contains text data that is
translated to EBCDIC data
when loaded on the z/TPF
system.
ONLINE
specifies that the source
path identifies an online file
to be affiliated with the
loadset. The ONLINE
parameter applies to files
that not included in loader
input files that are generated
for an OLDR load.
Indicates the type of system to
which a file is loaded.
Explanation of the supported
values:
ALL
BSS
EXC
specifies that the file is
included in the loader input
file for all subsystems.
specifies that the file is
included in the loader input
file for the basic subsystem
(BSS).
specifies that the file is
included in the loader input
file for all subsystems except
the BSS.
ssname
specifies that the file is
included in the loader input
file for a specified
subsystem.
Load files for version control 109

110 z/TPF Program Management
Table 6. Load file column definitions (continued)
8 Function
Switch
Free-form edit The values defined by SIP to
include or exclude the files that
are to be loaded based on the
switch values. For example, the
TPF_SBTPFDF value specifies
that files are loaded when the
z/TPFDF product is active. The
TPF_SBALL value specifies the
files that are to be loaded all the
time.
9-12 User 1–4 Free-form edit Reserved for customer use.
13 Sid Code Free-form edit Use in the base/cntl/
tpf.loadfile file to identify the
support that added or modified
the entry.

General file loader
The general file loader consists of an offline ALDR load and the online ACPL
program:
v Use the z/TPF offline loader to perform an ALDR load. The following control
statements apply to an ALDR load:
– “@APPLICATION” on page 125
– “@CIMR” on page 128
– “@CTKX” on page 132
– “@DEFINE” on page 134
– “@INCLUDE” on page 145
– “@IPL” on page 145
– “@KEYPOINT” on page 148
– “@GFKEYPOINT” on page 142.
v The ACPL program is called when you IPL the pack that contains the loader
general file that was created by ALDR.
Note: The @VERIFY control statement is not necessary because verification is
performed by using the program attribute table (PAT) loaded in the @CIMR
control statement.
See “Offline general file loader component (ALDR)” on page 22, “Online general file
loader component (ACPL)” on page 23, and “Load system components to a new
z/TPF system” on page 73 for more information about the general file loader. See
“z/TPF offline loader” on page 117 for more information about the z/TPF offline
loader.
© Copyright IBM Corp. 2005, 2012 111

112 z/TPF Program Management

|
Image loader
The image loader consists of an offline TLDR load and an online image load:
v Use the z/TPF offline loader to perform a TLDR load. The following control
statements apply to a TLDR load:
– “@APPLICATION” on page 125
– “@CIMR” on page 128
– “@CTKX” on page 132
– “@DEFINE” on page 134
– “@FILE” on page 139
– “@INCLUDE” on page 145
– “@IPL” on page 145
– “@KEYPOINT” on page 148
– “@VERIFY” on page 153.
v Use the ZTPLD command to perform an online image load. See z/TPF
Operations for more information about this command.
See “Offline image loader component (TLDR)” on page 23, “Online image loader
component (ZTPLD)” on page 24, and “Load system components to an existing
z/TPF system” on page 77 for more information about the image loader. See “z/TPF
offline loader” on page 117 for more information about the z/TPF offline loader.
© Copyright IBM Corp. 2005, 2012 113

114 z/TPF Program Management

|
E-type loader
The E-type loader consists of an offline OLDR load and an online E-type load:
v Use the z/TPF offline loader to perform an OLDR load. The following control
statements apply to an OLDR load:
– “@DEFINE” on page 134
– “@FILE” on page 139
– “@INCLUDE” on page 145
– “@LOADSET” on page 151
– “@VERIFY” on page 153.
v Use the ZOLDR command to perform an online E-type load. See z/TPF
Operations for more information about this command.
See “Offline E-type loader component (OLDR)” on page 25, “Online E-type loader
component (OLDR)” on page 26, and “Load E-type programs and files to an
enabled system” on page 81 for more information about the E-type loader. See
“z/TPF offline loader” on page 117 for more information about the z/TPF offline
loader.
© Copyright IBM Corp. 2005, 2012 115

116 z/TPF Program Management

z/TPF offline loader
JCL statements
This section describes how to call the z/TPF offline loader by using:
v “JCL statements”
v The “Linux offldr command” on page 119
v The “Linux labeltape command” on page 121.
The following topics also are included:
v “Return codes” on page 121
v “Comment conventions” on page 123.
Use the TPFLDR program in your job control language (JCL) to call the z/TPF
offline loader on your z/OS system. Your JCL code must reflect your environment,
standards, and naming conventions. For more information about JCL, see “JCL for
sending your output” on page 157.
The EXEC statement of your JCL must conform to the following syntax:
►►
►
PGM=TPFLDR
USER: userparms
,PARM='ALDR,TRACE(OFF)'
ALDR ,TRACE(OFF)
,PARM=' '
OLDR ,TRACE(ON)
TLDR
ALDR
performs an offline ALDR load. See “General file loader” on page 111 for more
information about the general file loader.
OLDR
performs an offline OLDR load. See “E-type loader” on page 115 for more
information about the E-type loader.
TLDR
performs an offline TLDR load. See “Image loader” on page 113 for more
information about the image loader.
TRACE(OFF)
performs the load without performing a trace function.
TRACE(ON)
performs the load while performing a trace function that can help with
debugging the loader. If you specify this option, you must specify the
LDRTRACE DD statement in your JCL.
USER: userparms
is an indicator that allows user parameters that are passed to the offline loader
© Copyright IBM Corp. 2005, 2012 117
►
►◄

118 z/TPF Program Management
user exit (UELR) to be included, where userparms are the parameters that you
have specified. This parameter indicates that no subsequent parameter will be
parsed by the offline loader. If you specify this parameter, the offline loader
does not impose any syntax constraints.
Your JCL must include the following DD statements:
GENFIL
specifies the general file that offline data is written to.
Note: When performing an ALDR load, use the GENFIL and GENFI2
parameters instead of LDROUT.
GENFI2
specifies the general file DSN for the 4 KB region that offline programs and
data are written to.
Note: When performing an ALDR load, use the GENFIL and GENFI2
parameters instead of LDROUT.
LDRLOAD
specifies the location of the loader input file.
LDRTEMP
specifies a temporary data set used to hold information before writing the final
output to the location specified by LDROUT.
LDROUT
specifies the location for the final output. This final output is used as input for
the online load.
Note: When performing an ALDR load, use the GENFIL and GENFI2
parameters instead of LDROUT.
LDRREPORT
specifies the file that the output report is written to. This report includes
information about the programs and components that were loaded and where
they were loaded from. This report also indicates which programs and
components could not be loaded.
If you specify TRACE(ON), your JCL must include the following DD statement:
LDRTRACE
specifies the trace file used for debugging the loader.
Note: This DD statement is ignored when you do not specify the TRACE(ON)
parameter on your JCL EXEC statement.
See “JCL for sending your output” on page 157 for sample JCL.

Linux offldr command
On your Linux system, use the offldr command to call the z/TPF offline loader. See
“z/TPF offline loader input file control statements” on page 125 for more information.
►► offldr oldr
tldr
--help
--Version
►
►
►
►
-output TLDR.out
OLDR.out
-output outfile
-o
-trace tracefile
-t
-load TLDR.load
OLDR.load
-load loadfile
-l
-report TLDR.report
OLDR.report
-report reportfile
-r
-w workdir
-dsn TLD.TAPE
OLD.TAPE
-volser volser
SCRTCH -expdt yyyyddd -dsn datasetname
-retpd nnnn
-u user parms
oldr
writes an OLDR-formatted file to the output file. See “E-type loader” on page
115 for more information about the E-type loader.
tldr
writes a TLDR-formatted file to the output file. See “Image loader” on page 113
for more information about the image loader.
--help
prints help information for the parameters that you can specify using the z/TPF
offline loader command and then exits.
--Version
specifies that the version number of the z/TPF offline loader command is
printed and then exits.
-load loadfile
specifies the location of the loader input file, where loadfile is the path of the
file. The default is OLDR.load if the oldr parameter was specified, or TLDR.load
if the tldr parameter was specified. If the -load parameter is not specified, the
offline loader assumes that your loader input file is named OLDR.load or
TLDR.load, and that this file exists in your current working directory. Otherwise,
an error will occur.
You also can enter -l for this parameter.
►
►
►
►
►◄
z/TPF offline loader 119

120 z/TPF Program Management
-output outfile
specifies the location of the output file, where outfile is the path of the file. The
default is OLDR.out if the oldr parameter was specified. In this case, the offline
loader creates (or replaces the contents of) a file named OLDR.out in your
current working directory. The default is TLDR.out if the tldr parameter was
specified. In this case, the offline loader creates (or replaces the contents of) a
file named TLDR.out in your current working directory.
You also can enter -o for this parameter.
-report reportfile
specifies the location of the report file, where reportfile is the path of the file.
The default is OLDR.report if the oldr parameter was specified. In this case, the
offline loader creates (or replaces the contents of) a file named OLDR.report in
your current working directory. The default is TLDR.report if the tldr parameter
was specified. In this case, the offline loader creates (or replaces the contents
of) a file named TLDR.report in your current working directory.
You also can enter -r for this parameter.
-trace tracefile
specifies the location of the trace file, where tracefile is the path of the file. If
this parameter is not specified, a trace file is not generated.
You also can enter -t for this parameter.
-w workdir
specifies the working directory, where workdir is the path of the directory. Any
relative paths specified for this command are assumed to be relative to this
directory. If this parameter is not specified, the offline loader assumes that the
appropriate working directory is the directory from which the offldr command
was entered.
-volser
specifies a tape volume serial number (VOLSER), where:
volser
is the volume serial number of the tape that you want the data written to.
This value must match the label on the tape that is mounted on the device
specified by the -output parameter.
SCRTCH
writes the data to a scratch tape that is mounted on the device specified by
the -output parameter.
You must specify this parameter if the output device is a tape.
-expdt yyyyddd
specifies the expiration date for the tape specified, where yyyyddd is the year
and day that the data expires. The data on the tape can be overwritten when
the expiration date on the tape has elapsed. If you do not specify this
parameter, the current date is used and the tape expires.
-retpd nnnn
specifies the retention period for the tape specified, where nnnn is the number
of days before the tape expires. The data on the tape can be overwritten when
the expiration date on the tape has elapsed. If you do not specify this
parameter, zero is used and the tape expires.

Linux labeltape command
Return codes
-dsn datasetname
specifies the name of the data set, where datasetname is the data set name.
The default is OLD.TAPE if the oldr parameter was specified, or TLD.TAPE if
the tldr parameter was specified.
-u user parms
is an indicator that allows user parameters that are passed to the offline loader
user exit (UELR) to be included, where user parms are the parameters that you
have specified. This parameter indicates that no subsequent parameters will be
parsed by the offline loader. If you specify this parameter, the offline loader
does not impose any syntax constraints.
See “Offline loader support on Linux” on page 28 for more information about this
command.
Use the z/TPF labeltape command on Linux to create an z/OS-style standard label
on a tape. See “z/TPF offline loader input file control statements” on page 125 and
“Offline loader support on Linux” on page 28for more information about the z/TPF
offline loader.
►► labeltape --help
--Version
--file device --volser volser
= =
-f -v
--help
prints help information for the parameters that you can specify with the z/TPF
labeltape command and then exits.
--Version
specifies that the version number of the z/TPF labeltape command is printed
and then exits.
--file device
specifies the device that the tape is mounted on. This value must be specified
using the /dev/ directory on Linux, which lists the system devices that are
available. You also can enter -f for this parameter.
--volser volser
specifies a tape volume serial number (VOLSER) that is used to label the tape.
This value must contain exactly six alphanumeric characters. You also can enter
-v for this parameter.
See “Offline loader support on Linux” on page 28for more information about this
command.
After running the offline loader, the following two return codes are sent to SYSOUT
(z/OS STDOUT) in a two-line status message:
v A return code indicating the level of success of the parsing phase of the offline
load. If this return code is 8 or greater, the loading phase is not performed.
►◄
z/TPF offline loader 121

0 8
0
v A return code indicating the level of success of the loading phase of the offline
load.
The return code for the entire offline load is the greater of the two return codes.
The following defines the return code values.
Explanation: No errors occurred; no warnings were
generated.
System action: The offline load is completed.
User response: Use the appropriate online loader to
load the components or programs to your z/TPF
system:
1. If you did an offline E-type load, use the ZOLDR
command.
2. If you did an offline general file load, ACPL will start
automatically when you IPL the loader general file.
3. If you did an offline image load, use the ZTPLD
command.
See z/TPF Operations for more information about the
ZOLDR and ZTPLD commands. See “Online general file
loader component (ACPL)” on page 23 for more
information about the ACPL program.
4
Explanation: An error occurred because there was an
unexpected line in the loader input file.
For example, this return code is generated for the
following errors:
v A line started with a slash-asterisk (/*) indicating that
the line is a comment. A closing asterisk-slash (*/)
was not found before the end of the file. The offline
loader assumes that the end of the file is the end of
the comment.
v The @INCLUDE control statement was started with
@INCLUDE, but a file was not specified.
v A processor was specified for something other than a
processor-unique keypoint.
v An object file was specified for a control statement
other than @APPLICATION.
v A control statement was misspelled; for example,
@APPLICATOIN rather than @APPLICATION.
v A control statement includes extra text that was not
expected.
System action: The offline loader program makes
assumptions about the unexpected lines and completes
the load.
User response: Complete the following steps:
1. Review the errors and determine if the assumptions
made by the loader were correct.
2. Do one of the following:
122 z/TPF Program Management
8
v If the assumptions made by the offline loader
were correct, use the appropriate online loader to
load the components to your z/TPF system:
a. If you did an offline E-type load, use the
ZOLDR command.
b. If you did an offline general file load, ACPL
will start automatically when you IPL the
loader general file.
c. If you did an offline image load, use the
ZTPLD command.
See z/TPF Operations for more information about
the ZOLDR and ZTPLD commands. See “Online
general file loader component (ACPL)” on page
23 for more information about the ACPL program.
Consider correcting the loader input file so that
these errors are not repeated in the future.
v If the assumptions made by the offline loader
were incorrect, make the necessary corrections to
the loader input file and run the offline load again.
Explanation: An error occurred that impacts the
output of the offline load.
For example, this return code is generated for the
following error:
v There is an entry point name that is exported by
more than one shared object.
System action: If this return code is for the parsing
phase of the load, the loading phase is not completed.
If this return code is for the loading phase, the load is
completed without the component that caused the error.
User response: Do one of the following:
v If the error occurred during the parsing phase,
complete the following steps:
1. Review the error message and correct the loader
input file.
2. Run the offline load again.
The loading phase will not begin until the parsing
phase has completed with a return code of 0 or 4.
v If the error occurred during the loading phase,
complete the following steps:
1. Review the error message and make the
necessary corrections.
2. If your load requires the component that caused
the error, run the offline load again.

12
Explanation: An error occurred that prevents the load
from being completed.
For example, this return code is generated for the
following errors:
v The loader input file could not be opened.
v The loader input file is empty.
v There are multiple occurrences of the load type
parameter in the JCL. For example, ’TLDR,ALDR’ or
’TLDR,TLDR’.
v There are multiple occurrences of the trace
parameter in the JCL. For example,
’TRACE(ON),TLDR,TRACE(OFF)’ or ’TRACE(ON),
TRACE(ON)’.
Comment conventions
v There is not enough space for one or more
structures.
v A parameter specified in the JCL is not valid.
v An error occurred while opening, writing to, or
reading one of the output files.
System action: The load is not completed.
User response: Complete the following steps:
1. Review the error messages and make the
necessary corrections.
2. Run the offline load again.
When you create the loader input file for the offline loader, you can include
comments that use the following conventions:
v To denote that an entire line is a comment, ensure that the first nonblank
character on the line is an asterisk (*).
v To denote a comment in a line, place a slash-asterisk (/*) before the start of your
comment and an asterisk-slash (*/) after the end of your comment. These inline
comments can span multiple lines.
Note: When your loader input file is inline with your JCL (that is, you are using
the LDRLOAD DD * DD statement), a slash-asterisk (/*) in the first column
indicates the end of the input file. Accordingly, any comments in that inline
loader input file cannot start in the first column.
v To associate a comment with a program, place the comment text in parentheses
after the program specification. The comment is displayed in the output report.
v To associate a comment with a loadset, place the comment text in parentheses
on the line following the @LOADSET statement. The parentheses cannot be
nested and you cannot use a closing parentheses as part of a comment.
Examples
The following example shows:
v The text of a loadset-level comment in parentheses on the line following the
@LOADSET LOADTEST statement
v The text of an inline comment contained between a /* and /*
v The text of a program-associated comment contained in parentheses
v The text of a comment on an entire line denoted by an *.
@LOADSET LOADTEST /home/dfallon/proj/maketpf_load
(Place your loadset-level comment here.)
PRG2bin parentheses.so /* comment in line */
PRG1.so
PRG3.so (This is a program-associated comment.)
@@PRG1.so 044 0047 this is a patch to PRG1.so
* Comment line - include a file in this loadset
@FILE -s /u/dfallon -o tpfdfltu -g tpfdfltg
myfile.txt
@LOADSET LOADTXT
@FILE -s /u/dfallon -o tpfdfltu -g tpfdfltg
filebase1.txt
12
z/TPF offline loader 123

124 z/TPF Program Management
The following two examples show different ways a loadset-level comment can span
multiple lines. The first example shows a load-set level comment that contains more
that 80 characters on a single line wrapping to multiple lines. The second example
shows a loadset-level comment written on separate lines.
@LOADSET LSNAME
(this is a very long line that is to be more
than 80 characters in length coded on a single
line that just wraps when viewed in an editor)
PROG.so
@LOADSET LSNAME
(this is a long comment
that is broken up
onto several lines)
PROG.so
The following example shows an inline comment immediately following a
loadset-level comment.
@LOADSET LSNAME
(this is a loadset comment) /* this is an inline comment */
@FILE -s /u/dfallon -o tpfdfltu -g tpfdfltg
filebase1.txt

z/TPF offline loader input file control statements
@APPLICATION
The z/TPF offline loader can be run on z/OS (using the TPFLDR program) or Linux
(using the OFFLDR program). The offline load is directed by a loader input file,
which consists of a series of control statements. The offline loader supports three
types of offline loads. For more information about each type of load, including a
summary of which control statements apply to which load, see the following:
v “General file loader” on page 111
v “Image loader” on page 113
v “E-type loader” on page 115.
Use a combination of the following control statements to create your loader input
file:
v “@APPLICATION”
v “@CIMR” on page 128
v “@CTKX” on page 132
v “@DEFINE” on page 134
v “@FILE” on page 139
v “@GFKEYPOINT” on page 142
v “@INCLUDE” on page 145
v “@IPL” on page 145
v “@KEYPOINT” on page 148
v “@LOADSET” on page 151
v “@VERIFY” on page 153.
You can use control statements more than once in a loader input file.
Note: When loading a program, the specified file and path names in the loader
input file are case sensitive. When patching a program, however, the case is
ignored.
Use the @APPLICATION control statement to specify the real-time programs that
you want to load to the z/TPF system. If an older version of a particular program
was previously specified in the loader input file, that version will be replaced by the
new version.
The following figure shows the syntax for the @APPLICATION control statement
section of the loader input file. In this figure, the double arrowhead (►►) indicates
that the information must begin on a new line.
© Copyright IBM Corp. 2005, 2012 125

►►
126 z/TPF Program Management
@APPlication
CWD
defaultloc
Note: This must be the first line of the @APPLICATION control statement
section.
,
►► ▼
defaultloc/
progname
specificloc/ version .ext (progcmt)
Note: If you have more than one program to load, use this line as many times
as you need. Each time you use it, separate occurrences with a comma
or start each occurrence on a new line.
►► ▼ @@progname rsa newdata
.objfile valdata-olddata
, MOVe
Note: If you have more than one program to patch (or if you have more than
one patch for a program), use this line as many times as you need. Each
time you use it, start the next occurrence on a new line.
Figure 12. @APPLICATION control statement section of the loader input file
defaultloc
is the default location of programs to load, where defaultloc is one of the
following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &APPLPATH)
v An absolute path (for example, /u/ztpf/applpath)
v A relative path (for example, applpath).
Note: All relative paths are appended to the current working directory, which
must have been defined previously using the CWD parameter in the
@DEFINE control statement section.
The default location is searched for programs listed in the @APPLICATION
control statement section. You can override the default path for a particular
program by specifying a specific path for that program.
specificloc
is the specific location of the program to load, where specificloc is one of the
following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &APPLPATH)
v An absolute path (for example, /u/ztpf/applpath)
v A relative path (for example, applpath).
►◄
►◄
►◄

Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
If you specify a specific location for a program, this location overrides any
default location that might have been defined for the @APPLICATION control
statement section; that is, only the specific location is searched for the program.
If the program is not found in the specific location, an error occurs.
CWD
is the value specified for the CWD parameter in the @DEFINE control
statement section. If you do not specify a default location or a specific location,
this is the only location that is searched.
progname
is the 4-character alphanumeric name of the program that you want to load to
the z/TPF system. Program names must begin with a letter (A–Z). For example,
if the linker creates a program called ctal51.so, the CTAL portion of the name is
required.
version
is the 1- to 2-character alphanumeric version code for the program. For
example, if the linker creates a program called ctal51.so, the 51 portion of the
name is optional.
.ext
specifies an extension of the full program name as created by the linker, where
ext is the appropriate extension. For example, if the linker creates a program
called ctal51.so, the .so portion of the name is optional.
(progcmt)
appends a comment for the program specified by progname that is displayed in
the output report, where progcmt is the text that is appended.
@@progname
specifies a program to patch or to move, where progname is the 4-character
name of the program that you want to patch or move. Program names must
begin with a letter (A–Z).
Note: If you want to patch a program, you must load the program in the current
@APPLICATION control statement section before you can patch it. If you
are moving an entry point, you must ensure that it is being loaded in the
current @APPLICATION control statement section.
.objfile
specifies the object file name, where objfile is an alphanumeric name of the
object file (in the program) that you want to patch on the z/TPF system. Object
file names must begin with a letter (A–Z).
rsa
is the 1- to 6-digit hexadecimal relative starting address in the program or object
file. The relative starting address specifies the offset into the program or object
file where the patch will be applied.
newdata
is the new data (or patch) that will replace the old data in the program or object
file, beginning at the relative starting address. The new data must be an even
number of hexadecimal digits and cannot exceed 32 digits (16 bytes).
z/TPF offline loader input file control statements 127

@CIMR
128 z/TPF Program Management
valdata-olddata
validates the data that is replaced by newdata, where olddata is an even
number in hexadecimal format that does not exceed 32 digits (16 bytes). The
data specified for olddata must match what is currently in the program. If it does
not, the data in the program is not changed and an error occurs. If it does, the
data in the program is replaced by newdata. For example, this parameter can
help to verify that your patch is starting at the correct relative starting address.
Note: The length of the data that you are validating can have fewer bytes or
more bytes than the new data. If the validation is completed successfully,
only the number of bytes in your new data will be replaced.
MOVe
indicates that the single entry BSO specified by @@progname has been moved
into another BSO. The BSO that @@progname has been moved to must be
included in the loader input file.
Use the @CIMR control statement to specify the core image restart (CIMR)
components that you want to load to the z/TPF system.
The following figure shows the syntax for the @CIMR control statement section of
the loader input file. In this figure, the double arrowhead (►►) indicates that the
information must begin on a new line.

►►
@CIMr
CWD
defaultloc
Note: This must be the first line of the @CIMR control statement section.
►► ▼
,
defaultloc/
ACPL
specificloc/ CPS0
FCTB
ICDF
IPAT
RIAT
SIGT
USR1
USR2
version .ext (progcmt)
Note: If you have more than one component to load, use this line as many
times as you need. Each time you use it, separate occurrences with a
comma or start each occurrence on a new line.
►► ▼ @@ACPL rsa newdata
@@CPS0 valdata-olddata
@@FCTB
@@ICDF
@@IPAT
@@RIAT
@@SIGT
@@USR1
@@USR2
@@csect
Note: If you have more than one component to patch (or if you have more than
one patch for a component), use this line as many times as you need.
Each time you use it, start the next occurrence on a new line.
Figure 13. @CIMR control statement section of the loader input file
defaultloc
is the default location for the @CIMR control statement section, where
defaultloc is one of the following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &CIMRPATH)
v An absolute path (for example, /u/ztpf/cimrpath)
v A relative path (for example, cimrpath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
z/TPF offline loader input file control statements 129
►◄
►◄
►◄

The default location is searched for the CIMR components listed in the @CIMR
control statement section. You can override the default location for a particular
CIMR component by specifying a specific location for that CIMR component.
specificloc
is the specific location for the CIMR component to load, where specificloc is one
of the following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &CIMRPATH)
v An absolute path (for example, /u/ztpf/cimrpath)
v A relative path (for example, cimrpath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
If you specify a specific location for a CIMR component, this location overrides
any default location that might have been defined for the @CIMR control
statement section; that is, only the specific location is searched for the CIMR
component. If the CIMR component is not found in the specific location, an
error occurs.
CWD
is the value specified for the CWD parameter in the @DEFINE control
statement section. If you do not specify a default location or a specific location,
this is the only location that is searched.
ACPL
loads the online segment of the general file loader to the z/TPF system.
CPS0
loads the control program (CP) to the z/TPF system.
Note: You can load the CP only to the basic subsystem (BSS).
FCTB
loads the FACE table to the z/TPF system.
ICDF
loads the in-core dump formatter (ICDF) to the z/TPF system.
Note: You can load the ICDF only to the BSS.
IPAT
loads the program attribute table (PAT) to the z/TPF system.
RIAT
loads the record ID attribute table (RIAT) to the z/TPF system.
SIGT
loads the global synchronization table (SIGT) to the z/TPF system.
USR1
loads the first user-defined CIMR area (USR1) to the z/TPF system.
Note:
130 z/TPF Program Management
1. You can load the USR1 only to the BSS.

2. USR1 is required for a full load. See “Load system components to a
new z/TPF system” on page 73 for more information about
performing a full load.
USR2
loads the second user-defined CIMR area (USR2) to the z/TPF system.
version
is the 1- to 2-character alphanumeric version code for the CIMR component.
For example, if the linker creates a program called usr151.so, the 51 portion of
the name is optional.
.ext
specifies an extension of the full program name as created by the linker, where
ext is the appropriate extension. For example, if the linker creates a program
called usr151.so, the .so portion of the name is optional.
(progcmt)
appends a comment for the CIMR component that is displayed in the output
report, where progcmt is the text that is appended.
@@ACPL
patches the online program of the general file loader (ACPL).
Note: You must load the ACPL in the current @CIMR control statement section
before you can patch it.
@@CPS0
patches the control program (CP).
Note: You must load the CP in the current @CIMR control statement section
before you can patch it.
@@FCTB
patches the FACE table.
Note:
1. You must load the FACE table in the current @CIMR control
statement section before you can patch it.
2. You can patch data only in the first 16 MB of the FACE table.
@@ICDF
patches the in-core dump formatter (ICDF).
Note: You must load the ICDF in the current @CIMR control statement section
before you can patch it.
@@IPAT
patches the program attribute table (PAT).
Note: You must load the PAT in the current @CIMR control statement section
before you can patch it.
@@RIAT
patches the record ID attribute table (RIAT).
Note: You must load the RIAT in the current @CIMR control statement section
before you can patch it.
@@SIGT
patches the global synchronization table (SIGT).
z/TPF offline loader input file control statements 131

@CTKX
132 z/TPF Program Management
Note: You must load SIGT in the current @CIMR control statement section
before you can patch it.
@@USR1
patches the first user-defined CIMR area (USR1).
Note: You must load the USR1 in the current @CIMR control statement section
before you can patch it.
@@USR2
patches the second user-defined CIMR area (USR2).
Note: You must load the USR2 in the current @CIMR control statement section
before you can patch it.
@@csect
patches the specified CSECT in the control program, where csect is the
6-character alphanumeric name of the CP CSECT (for example, CCNUCL).
Note: You must load the control program in the current @CIMR control
statement section before you can patch a specific CSECT.
rsa
is the 1- to 6-digit hexadecimal relative starting address in the CIMR component
or CSECT. The relative starting address specifies the offset into the CIMR
component or CSECT where the patch will be applied.
newdata
is the new data (or patch) that will replace the old data in the CIMR component
or CSECT, beginning at the relative starting address. The new data must be an
even number of hexadecimal digits and cannot exceed 32 digits (16 bytes).
valdata-olddata
validates the data that is replaced by newdata, where olddata is an even
number in hexadecimal format that does not exceed 32 digits (16 bytes). The
data specified for olddata must match what is currently in the CIMR component.
If it does not, the data in the CIMR component is not changed and an error
occurs. If it does, the data in the CIMR component is replaced by newdata. For
example, this parameter can help to verify that your patch is starting at the
correct relative starting address.
Note: The length of the data that you are validating can have fewer bytes or
more bytes than the new data. If the validation is completed successfully,
only the number of bytes in your new data will be replaced.
Use the @CTKX control statement to load the image pointer record (CTKX) to the
z/TPF system.
The following figure shows the syntax for the @CTKX control statement section of
the loader input file. In this figure, the double arrowhead (►►) indicates that the
information must begin on a new line.

►►
@CTKx
CWD
defaultloc
Note: This must be the first line of the @CTKX control statement section.
►►
defaultloc/
CTKX
specificloc/ version .ext (progcmt)
►► ▼ @@CTKX rsa newdata
valdata-olddata
Note: If you have more than one patch for the CTKX component, use this line
as many times as you need. Each time you use it, start the next
occurrence on a new line.
Figure 14. @CTKX control statement section of the loader input file
defaultloc
is the default location for the @CTKX control statement section, where
defaultloc is one of the following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &CTKXPATH)
v An absolute path (for example, /u/ztpf/ctkxpath)
v A relative path (for example, ctkxpath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
The default location is searched for the CTKX component listed in the @CTKX
control statement section. You can override the default path for the CTKX
component by specifying a specific location on a separate line.
specificloc
is the specific location for the CTKX component to load, where specificloc is
one of the following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &CTKXPATH)
v An absolute path (for example, /u/ztpf/ctkxpath)
v A relative path (for example, ctkxpath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
If you specify a specific location for the CTKX component, this location
overrides any default location that may have been defined for the @CTKX
z/TPF offline loader input file control statements 133
►◄
►◄
►◄

@DEFINE
134 z/TPF Program Management
control statement section; that is, only the specific location is searched for the
CTKX component. If the CTKX component is not found in the specific location,
an error occurs.
CWD
is the value specified for the CWD parameter in the @DEFINE control
statement section. If you do not specify a default location or a specific location,
this is the only location that is searched.
CTKX
loads the image pointer record (CTKX) to the z/TPF system. When a new copy
of CTKX is loaded, it is compared to the existing version. If the starting ordinal
of a core image record (CIMR) or IPL component is different in the new copy of
CTKX, or the allocated size is too small, that component must also be loaded.
version
is the 1- to 2-character alphanumeric version code for the CTKX component.
.ext
specifies an extension of the full program name as created by the linker, where
ext is the appropriate extension. For example, if the linker creates a program
called ctkx51.so, the .so portion of the name is optional.
(progcmt)
appends a comment to the CTKX component that is displayed in the output
report, where progcmt is the text appended.
@@CTKX
patches the image pointer record (CTKX).
Note: You must load the image pointer record (CTKX) in the current @CTKX
control statement section before you can patch it.
rsa
is the 1- to 6-digit hexadecimal relative starting address in the CTKX
component. The relative starting address specifies the offset into the CTKX
component where the patch will be applied.
newdata
is the new data (or patch) that will replace the old data in the CTKX component,
beginning at the relative starting address. The new data must be an even
number of hexadecimal digits and cannot exceed 32 digits (16 bytes).
valdata-olddata
validates the data that is replaced by newdata, where olddata is an even
number in hexadecimal format that does not exceed 32 digits (16 bytes). The
data specified for olddata must match what is currently in the component. If it
does not, the data in the component is not changed and an error occurs. If it
does, the data in the component is replaced by newdata. For example, this
parameter can help to verify that your patch is starting at the correct relative
starting address.
Note: The length of the data that you are validating can have fewer bytes or
more bytes than the new data. If the validation is completed successfully,
only the number of bytes in your new data will be replaced.
Use the @DEFINE control statement to define system settings.

The following figure shows the syntax for the @DEFINE control statement section
of the loader input file. In this figure, the double arrowhead (►►) indicates that the
information must begin on a new line.
►► @DEFine ►◄
Note: This must be the first line of the @DEFINE control statement section.
►►
(1)
▼ &searchpath= ▼
:
(2)
path
&previouslydefinedsearchpath
Notes:
1 If you have more than one search path to define, use this line as many
times as you need. Each time you use it, start the next occurrence on a
new line.
2 The definition of a search path can span more than one line. To continue
on a new line, end your current line with a colon (:), which indicates there is
more information in the definition.
►►
►►
CWD=path
SYSID=bssname
SYSID=ssname
Figure 15. @DEFINE control statement section of the loader input file
z/TPF offline loader input file control statements 135
►◄
►◄
►◄

136 z/TPF Program Management
Additional syntax for an OLDR or a TLDR load:
DEBUGFILES=YES
DEBUGFILES=NO
Additional syntax for a TLDR load:
►
ELDRCLEAR=NO
ELDRCLEAR=YES
FCTBCLEAR=NO
FCTBCLEAR=YES
OVERLAY_IPAT=NO
OVERLAY_IPAT=YES
Additional syntax for an ALDR load:
IMGCLEAR=NO
IMGCLEAR=YES
PROGCLEAR=NO
PROGCLEAR=YES
Figure 16. Additional syntax for specific uses of the @DEFINE control statement section
&searchpath
specifies the name of a path, where searchpath is the name you want
associated with the path. The path must start with an ampersand (&). If you
specify more than one directory, use a colon (:) to separate directories.
path
is an absolute or relative directory that you can specify to search.
&previouslydefinedsearchpath
is an absolute or relative directory that was defined previously with the
@DEFINE control statement section to search.
The following example shows a path named &CIMRPATH that has three path
definitions.
@DEFINE
&CIMRPATH=/u/ztpf/cp:/u/ztpf/fctb:/u/ztpf/cimrobj
Using this definition, if you specify the path name of &CIMRPATH anywhere in
the loader input file, the offline loader will attempt to locate the object that it
applies to by searching the following directories in order:
1. /u/ztpf/cp
2. /u/ztpf/fctb
3. /u/ztpf/cimrobj
Note: Path names are case sensitive.
CWD=path
specifies the current working directory, where path is the name of the absolute
directory that relative directories are appended to. For other control statements,
the following apply:
►

v Any relative paths are assumed to be relative to this directory.
v The directory specified here is used as the search directory if neither a
default location nor a specific location is specified for the control statement.
Note: You can specify CWD as both a system setting in the @DEFINE control
statement and as a command-line argument when you are performing an
offline load on Linux. However, if you specify both the command-line
argument and the system setting, these values must be consistent.
SYSID
specifies the subsystem ID.
bssname
is the name of the basic subsystem (BSS). You can define your own BSS
name by specifying the BSSNAME parameter on the SSDEF macro; see
z/TPF and z/TPFDF System Generation for more information about the
SSDEF macro.
ssname
is the name of the subsystem.
DEBUGFILES
specifies whether the shared object with debug data will be written to the
desired storage medium.
YES
writes the shared object with debug data to the desired storage medium.
NO does not write the shared object with debug data to the desired storage
medium.
ELDRCLEAR
specifies whether E-type loader record definitions are cleared.
YES
clears and reinitializes all E-type loader records and versioned files for the
target image.
Attention: When ELDRCLEAR=YES is specified, all programs and files
that were loaded using the E-type loader (except those that were accepted)
are cleared from the online system.
NO does not clear or reinitialize E-type loader record definitions.
Attention: Use this line for the @DEFINE control statement section only
when performing a TLDR load.
FCTBCLEAR
specifies whether the alternate FACE table (FCTB) is cleared.
YES
clears the alternate FCTB for the target image.
Attention: When FCTBCLEAR=YES is specified, the alternate FCTB that
was loaded using the ZFCTB LOAD command is cleared from the online
system unless it had already been accepted. See z/TPF Operations for
more information about the ZFCTB LOAD command.
NO does not clear the alternate FCTB.
Attention: Use this line for the @DEFINE control statement section only
when performing a TLDR load.
z/TPF offline loader input file control statements 137

IMGCLEAR
specifies whether image-related records are cleared.
YES
clears and initializes various image-related records. When IMGCLEAR=YES
is specified, IPLA, IPLB, CTKX, and all the CIMR components need to be
loaded.
Attention: When IMGCLEAR=YES is specifed, all image definitions are
NO
cleared from the online system.
does not clear or initialize various image-related records.
Attention: Do not use this line for the @DEFINE control statement section
when performing an OLDR load. If you do, you will receive an error message
and a return code of 8. See “Return codes” on page 121 for more information
about offline loader return codes.
Note: If you specify this line for the @DEFINE control statement section when
performing a TLDR load, it is ignored. You will receive a return code of 4.
See “Return codes” on page 121 for more information about offline
loader return codes.
OVERLAY_IPAT
specifies whether to merge or replace the program attribute table (PAT).
YES
replaces the PAT in core and requires that all programs get reloaded.
NO merges the existing PAT with the PAT that is being loaded.
Attention: Use this line for the @DEFINE control statement section only
when performing a TLDR load.
PROGCLEAR
specifies whether a program base is cleared.
YES
138 z/TPF Program Management
clears and reinitializes the master extra program record for the target image
so that all extra program records (#XPRGn fixed file records, where n is the
program base number for the image you are loading to) are available to be
dispensed.
Additionally, the program base unique file directory (/sys/tpf_pbfiles) is
cleared. If get file storage (GFS) is not active when the online load is
performed, the target program base indicates that its program base unique
file directory has not been cleared. In this case, the directory will be cleared
the next time GFS activation occurs on any processor.
If GFS activation does not occur before an initial program load (IPL) is
performed on the target image, the program base unique file directory is
cleared when GFS is activated following the IPL of the target image.
References to program base unique files that occur before GFS activation
are intercepted by the z/TPF system and the directory appears empty to an
application.
Note: Only files in the program base unique file directory are cleared.
Other files that are loaded by using the loader are not part of the
program base and are not cleared.

@FILE
NO does not clear or reinitialize the master extra program record or the
program base unique file directory.
Attention: Use this line for the @DEFINE control statement section only
when performing a TLDR load.
Note:
1. You must specify PROGCLEAR=YES to initialize a program base
before you can load any real-time programs to an image for the first
time.
2. All real-time programs must be reloaded when you specify
PROGCLEAR=YES.
Use the @FILE control statement to specify one or more files to be loaded. This
control statement is valid for OLDR and TLDR files.
Note: REP cards are not supported for files.
The following figure shows the syntax for the @FILE control statement section of
the loader input file. In this figure, the double arrowhead (►►) indicates that the
information must begin on a new line.
►► @FILe
►
►
-d /sys/tpf_pbfiles
-s default-sourcedir -d default-targetdir
-p default-permission -o default-owner -g default-group
-t NONE
-t ATOE
-ONL
Note: This must be the first line of the @FILE control statement section.
►► sourceloc
►
-t NONE
-t ATOE
-ONL
Note:
targetloc -p permission -o owner -g group
(comment)
v You can specify any number of files.
v When listing programs after files in an E-type loader input file, you must
use a @LOADSET control statement (without specifying a loadset
name) to indicate the end of files and start of programs.
Figure 17. @FILE control statement section of the loader input file
-s default-sourcedir
is the default source location when relative paths are specified. If you do not
z/TPF offline loader input file control statements 139
►
►
►◄
►
►◄

-d
specify this parameter, the source locations that specify a relative path are
based on the CWD parameter of the “@DEFINE” on page 134 and
“@LOADSET” on page 151 control statements.
specifies the target location when relative paths are specified, where:
default-targetdir
is the default target location when relative paths are specified.
/sys/tpf_pbfiles
is the program base unique directory. This is the default.
Note: When using TLDR, if the target location is not in the program base
unique directory (/sys/tpf_pbfiles) the z/TPF online image loader
(ZTPLD) passes the file information to the UELK user exit. By default,
the UELK user exit specifies that the file is not loaded by the image
loader. You can modify the UELK user exit to specify files to be loaded.
See z/TPF and z/TPFDF System Installation Support Reference for more
information about the UELK user exit.
-p default-permission
specifies the default file permission that is used when writing out the files in the
@FILE control statement that do not have permission values specified. If you
do not specify this parameter, the permission will match the source file when it
is read by the z/TPF offline loader.
-o default-owner
specifies the default file owner ID that is used when writing out files in the
@FILE control statement that do not have owner ID values specified. If you do
not specify this parameter, the owner ID will match the source file when read by
the z/TPF offline loader. The owner ID obtained from the source file will be the
mapped text owner ID, not the numeric owner ID.
Note: If you specify an owner ID, use the owner ID name, not the numeric ID.
Owner IDs are not required to be identically mapped online and offline.
-g default-group
specifies the default file group ID that is used when writing out files in the
@FILE control statement that do not have group ID values specified. If you do
not specify this parameter, the group ID will match the source file when read by
the z/TPF offline loader. The group ID obtained from the source file will be the
mapped text group ID, not the numeric group ID.
-t
Note: If you specify a group ID, use the group ID name, not the numeric ID.
Group IDs are not required to be identically mapped online and offline.
specifies a translation option, where:
NONE
specifies no file translation. This is the default.
ATOE
specifies that an ASCII data file is translated to an EBCDIC data file.
Note:
140 z/TPF Program Management

v This translation does not include a verification check that the data file
being translated is in ASCII format. You must ensure that the data file
being translated is an ASCII data file before specifying the ATOE
parameter.
v If specified on the @FILE control statement, this option defines a
default translation that applies to subsequent files that do not have the
-t or -ONL parameter specified. If the -t parameter is specified for a
subsequent file, the -ONL parameter option is ignored for that file.
-ONL
specifies that a file that exists in z/TPF collection support file system (TFS) on
the z/TPF system is affiliated with the loadset. If this parameter is specified on
the @FILE control statement, a default option is defined that applies to
subsequent files that do not have the t or b parameter specified. If the t or b
parameter is specified for a subsequent file, the ONL parameter is ignored for
that file.
Note:
v You only can specify this parameter for OLDR.
v The changes made to the file in the loadset are not reflected in the
existing online version. A ZOLDR ACCEPT must be done to replace
the existing online version with the version in the loadset.
v If you specify this parameter, there is no file translation when an
online file is associated with a loadset.
sourceloc
specifies the path where the file is to be found by the z/TPF offline loader. If the
default-sourcedir parameter is not specified, the source locations that specify a
relative path are based on the CWD parameter of the “@DEFINE” on page 134
control statement. If the -ONL parameter is specified, it indicates the online
location of the file to be affiliated with the loadset.
Note: If the file specified with this parameter is a versioned file when the
loadset is loaded online, the base version of the file is associated with
the loadset.
targetloc
specifies the path where the file is to be written online. If you do not specify this
parameter, the file is written online using the same path as the offline source
file.
Note: When using TLDR, if the target location is not in the program base
unique directory (/sys/tpf_pbfiles) the online image loader (ZTPLD)
passes the file information to the UELK user exit. By default, the UELK
user exit specifies that the file is not loaded by the image loader. You
can modify the UELK user exit to specify files to be loaded. See z/TPF
and z/TPFDF System Installation Support Reference for more
information about the UELK user exit.
-p permission
specifies the permission for the target file when loaded to the file system on the
z/TPF system. If you do not specify this parameter, the file permission is based
on the default-permission value that is specified on the @FILE control
statement.
-o owner
specifies the owner ID of the (target) file when loaded to the file system on the
z/TPF offline loader input file control statements 141

@GFKEYPOINT
142 z/TPF Program Management
z/TPF system. If you do not specify this parameter, the owner is based on the
default-owner value specified on the @FILE control statement.
Note: If you specify an owner ID, use the owner ID name, not the numeric ID.
Owner IDs are not required to be identically mapped online and offline.
-g group
specifies the group ID of the (target) file when loaded to the file system on the
z/TPF system. If you do not specify this parameter, the group ID is based on
the default-group value specified on the @FILE control statement.
Note: If you specify a group ID, use the group ID name, not the numeric ID.
Group IDs are not required to be identically mapped online and offline.
(comment)
appends a comment for the file specified by filename that is displayed in the
output report, where comment is the text that is appended.
Use the @GFKEYPOINT control statement to specify the keypoints to write to the
general file keypoint area.
The following figure shows the syntax for the @GFKEYPOINT control statement
section of the loader input file. In this figure, the double arrowhead (►►) indicates
that the information must begin on a new line.
►► @GFKeypoint
defaultloc
Note: This must be the first line of the @GFKEYPOINT control statement
section.
►► ▼
,
defaultloc/
keypoint
specificloc/ version .ext %cpuid (progcmt)
Note: If you have more than one general file keypoint to load, use this line as
many times as you need. Each time you use it, separate occurrences with
a comma or start each occurrence on a new line.
►► ▼ @@keypoint rsa newdata
%cpuid valdata-olddata
Note: If you have more than one keypoint to patch (or if you have more than
one patch for a keypoint), use this line as many times as you need. Each
time you use it, start the next occurrence on a new line.
Figure 18. @GFKEYPOINT control statement section of the loader input file
►◄
►◄
►◄

defaultloc
is the default location for the @GFKEYPOINT control statement section, where
defaultloc is one of the following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &GFKPPATH)
v An absolute path (for example, /u/ztpf/gfkppath)
v A relative path (for example, gfkppath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
The default location is searched for the keypoints listed in the @GFKEYPOINT
control statement section. You can override the default location for a particular
keypoint by specifying a specific location for that keypoint.
specificloc
is the specific location for the keypoint to load, where specificloc is one of the
following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &GFKPPATH)
v An absolute path (for example, /u/ztpf/gfkppath)
v A relative path (for example, gfkppath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
If you specify a specific location for a keypoint, this location overrides any
default location that may have been defined for the @GFKEYPOINT control
statement section; that is, only the specific location is searched for the keypoint.
If the keypoint is not found in the specific location, an error occurs.
CWD
is the value specified for the CWD parameter in the @DEFINE control
statement section. If you do not specify a default location or a specific location,
this is the only location that is searched.
keypoint
specifies one of the following keypoints to load:
v CTK0
v CTK1
v CTK2
v CTK3
v CTK4
v CTK5
v CTK6
v CTK7
v CTK8
v CTK9
v CTKA
v CTKB
v CTKC
v CTKE
v CTKI
z/TPF offline loader input file control statements 143

144 z/TPF Program Management
v CTKM
v CTKV.
See z/TPF and z/TPFDF System Generation for more information about these
keypoints.
version
is the 1- to 2-character alphanumeric version code for the keypoint.
.ext
specifies an extension of the full keypoint name, as created by the linker, where
ext is the appropriate extension. For example, if the linker creates a keypoint
called ctka51.so, the .so portion of the name is optional.
%cpuid
loads the specified keypoint to a processor, where cpuid is the identifier for the
processor. If a processor identifier is not specified and the keypoint is
processor-specific, the identifier defaults to the first processor that was defined.
(progcmt)
appends a comment for the specified keypoint that is displayed in the output
report, where progcmt is the text that is appended.
@@keypoint
patches one of the following keypoints:
v CTK0
v CTK1
v CTK2
v CTK3
v CTK4
v CTK5
v CTK6
v CTK7
v CTK8
v CTK9
v CTKA
v CTKB
v CTKC
v CTKE
v CTKI
v CTKM
v CTKV.
See z/TPF and z/TPFDF System Generation for more information about these
keypoints.
rsa
is the 1- to 6-digit hexadecimal relative starting address in the keypoint. The
relative starting address specifies the offset into the keypoint where the patch is
applied.
newdata
is the new data (or patch) that will replace the old data in the keypoint,
beginning at the relative starting address. The new data must be an even
number of hexadecimal digits and cannot exceed 32 digits (16 bytes).
valdata-olddata
validates the data that is replaced by newdata, where olddata is an even
number in hexadecimal format that does not exceed 32 digits (16 bytes). The
data specified for olddata must match what is currently in the keypoint. If it does
not, the data in the keypoint is not changed and an error occurs. If it does, the

@INCLUDE
@IPL
data in the keypoint is replaced by newdata. For example, this parameter can
help to verify that your patch is starting at the correct relative starting address.
Note: The length of the data that you are validating can have fewer bytes or
more bytes than the new data. If the validation is completed successfully,
only the number of bytes in your new data will be replaced.
Use the @INCLUDE control statement to specify one or more files that contain a
list of components or programs to load.
The following figure shows the syntax for the @INCLUDE control statement section
of the loader input file. In this figure, the double arrowhead (►►) indicates that the
information must begin on a new line.
►► ▼ @INCLUDE
loc
is the location for the file being included, where loc is one of the following:
v An absolute path name (for example, /u/ztpf/inclpath/filename)
v A relative path name (for example, inclpath/filename).
CWD
CWD
loc
Note: If you have more than one file to include, use this line as many times as
you need. Each time you use it, start the next occurrence on a new line.
Figure 19. @INCLUDE control statement section of the loader input file
Note: All relative path names are appended to the current working directory,
which is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
For more information about the structure of an include file, go to “Input files” on
page 158.
is the value specified for the CWD parameter in the @DEFINE control
statement section. If you do not specify a location, this is the only location that
is searched.
Use the @IPL control statement to specify which IPL programs are to be loaded.
The following figure shows the syntax for the @IPL control statement section of the
loader input file. In this figure, the double arrowhead (►►) indicates that the
information must begin on a new line.
z/TPF offline loader input file control statements 145
►◄

►►
@IPL
146 z/TPF Program Management
CWD
defaultloc
Note: This must be the first line of the @IPL control statement section.
,
►► ▼
defaultloc/
IPLA
specificloc/ IPLB version .ext (progcmt)
Note: If you have more than one program to load, use this line as many times
as you need. Each time you use it, separate occurrences with a comma
or start each occurrence on a new line.
►► ▼ @@IPLA rsa newdata
@@IPLB valdata-olddata
Note: If you have more than one program to patch (or if you have more than
one patch for a component), use this line as many times as you need.
Each time you use it, start the next occurrence on a new line.
Figure 20. @IPL control statement section of the loader input file
defaultloc
is the default location for the @IPL control statement section, where defaultloc
is one of the following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &IPLPATH)
v An absolute path (for example, /u/ztpf/iplpath)
v A relative path (for example, iplpath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
The default location is searched for the programs listed in the @IPL control
statement section. You can override the default location for a particular program
by specifying a specific location for that program.
specificloc
is the specific location for the program to load, where specificloc is one of the
following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &IPLPATH)
v An absolute path (for example, /u/ztpf/iplpath)
v A relative path (for example, iplpath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
►◄
►◄
►◄

statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
If you specify a specific location for a program, this location overrides any
default location that may have been defined for the @IPL control statement
section; that is, only the specific location is searched for the program. If the
program is not found in the specific location, an error occurs.
CWD
is the value specified for the CWD parameter in the @DEFINE control
statement section. If you do not specify a default location or a specific location,
this is the only location that is searched.
IPLA
loads the IPLA program.
IPLB
loads the IPLB program.
version
is the 1- to 2-character alphanumeric version code for the program.
.ext
specifies an extension of the full program name as created by the linker, where
ext is the appropriate extension. For example, if the linker creates a program
called ipla51.so, the .so portion of the name is optional.
(progcmt)
appends a comment for the program specified (either IPLA or IPLB) that is
displayed in the output report, where progcmt is the text that is appended.
@@IPLA
patches the IPLA program.
Note: You must load the IPLA program in the current @IPL control statement
section before you can patch it.
@@IPLB
patches the IPLB program.
Note: You must load the IPLB program in the current @IPL control statement
section before you can patch it.
rsa
is the 1- to 6-digit hexadecimal relative starting address in the program. The
relative starting address specifies the offset into the program where the patch is
applied.
newdata
is the new data (or patch) that will replace the old data in the program,
beginning at the relative starting address. The new data must be an even
number of hexadecimal digits and cannot exceed 32 digits (16 bytes).
valdata-olddata
validates the data that is replaced by newdata, where olddata is an even
number in hexadecimal format that does not exceed 32 digits (16 bytes). The
data specified for olddata must match what is currently in the program. If it does
not, the data in the program is not changed and an error occurs. If it does, the
data in the program is replaced by newdata. For example, this parameter can
help to verify that your patch is starting at the correct relative starting address.
z/TPF offline loader input file control statements 147

@KEYPOINT
Note: The length of the data that you are validating can have fewer bytes or
more bytes than the new data. If the validation is completed successfully,
only the number of bytes in your new data will be replaced.
Use the @KEYPOINT control statement to load keypoints.
The following figure shows the syntax for the @KEYPOINT control statement
section of the loader input file. In this figure, the double arrowhead (►►) indicates
that the information must begin on a new line.
►►
148 z/TPF Program Management
@KEYpoint
CWD
defaultloc
Note: This must be the first line of the @KEYPOINT control statement section.
►► ▼
,
defaultloc/
keypoint
specificloc/ version .ext %cpuid (progcmt)
Note: If you have more than one keypoint to load, use this line as many times
as you need. Each time you use it, separate occurrences with a comma
or start each occurrence on a new line.
►► ▼ @@keypoint rsa newdata
%cpuid valdata-olddata
rsa newdata ONLine
%cpuid
Note: If you have more than one keypoint to patch (or if you have more than
one patch for a keypoint), use this line as many times as you need. Each
time you use it, start the next occurrence on a new line.
Figure 21. @KEYPOINT control statement section of the loader input file
defaultloc
is the default location for the @KEYPOINT control statement section, where
defaultloc is one of the following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &KEYPPATH)
v An absolute path (for example, /u/ztpf/keyppath)
v A relative path (for example, keyppath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
►◄
►◄
►◄

The default location is searched for the keypoints listed in the @KEYPOINT
control statement section. You can override the default location for a particular
keypoint by specifying a specific location for that keypoint.
specificloc
is the specific location for the keypoint to load, where specificloc is one of the
following:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &KEYPPATH)
v An absolute path (for example, /u/ztpf/keyppath)
v A relative path (for example, keyppath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
If you specify a specific location for a keypoint, this location overrides any
default location that may have been defined for the @KEYPOINT control
statement section; that is, only the specific location is searched for the keypoint.
If the keypoint is not found in the specific location, an error occurs.
CWD
is the value specified for the CWD parameter in the @DEFINE control
statement section. If you do not specify a default location or a specific location,
this is the only location that is searched.
keypoint
is the keypoint to write to load. Specify one of the following:
v CTK0
v CTK1
v CTK2
v CTK3
v CTK4
v CTK5
v CTK6
v CTK7
v CTK8
v CTK9
v CTKA
v CTKB
v CTKC
v CTKE
v CTKI
v CTKM
v CTKV.
See z/TPF and z/TPFDF System Generation for more information about these
keypoints.
version
is the 1- to 2-character alphanumeric version code for the keypoint.
.ext
specifies an extension of the full keypoint name as created by the linker, where
ext is the appropriate extension. For example, if the linker creates a keypoint
called ctk751.so, the .so portion of the name is optional.
z/TPF offline loader input file control statements 149

%cpuid
loads the specified keypoint to a processor, where cpuid is the identifier for the
processor. If a processor identifier is not specified and the keypoint is
processor-specific, the identifier defaults to the first processor that was defined.
(progcmt)
appends a comment for the specified keypoint that is displayed in the output
report, where progcmt is the text appended.
@@keypoint
patches a keypoint, where keypoint is one of the following keypoints:
v CTK0
v CTK1
v CTK2
v CTK3
v CTK4
v CTK5
v CTK6
v CTK7
v CTK8
v CTK9
v CTKA
v CTKB
v CTKC
v CTKE
v CTKI
v CTKM
v CTKV.
See z/TPF and z/TPFDF System Generation for more information about these
keypoints.
rsa
is the 1- to 6-digit hexadecimal relative starting address in the keypoint. The
relative starting address specifies the offset into the keypoint where the patch is
applied.
newdata
is the new data (or patch) that will replace the old data in the keypoint,
beginning at the relative starting address. The new data must be an even
number of hexadecimal digits and cannot exceed 32 digits (16 bytes).
valdata-olddata
validates the data that is replaced by newdata, where olddata is an even
number in hexadecimal format that does not exceed 32 digits (16 bytes). The
data specified for olddata must match what is currently in the keypoint. If it does
not, the data in the keypoint is not changed and an error occurs. If it does, the
data in the keypoint is replaced by newdata. For example, this parameter can
help verify that your patch is starting at the correct relative starting address.
Note:
150 z/TPF Program Management
1. The length of the data that you are validating can have fewer bytes
or more bytes than the new data. If the validation is completed
successfully, only the number of bytes in your new data will be
replaced.
2. This parameter is ignored if the patch is for an online keypoint.

@LOADSET
ONLine
specifies that only the patch data is applied to the online keypoint. The entire
keypoint is not loaded and the online keypoint is not changed except for the
patch data.
Note: You must specify the ONLine parameter when patching a keypoint that is
not being loaded.
Use the @LOADSET control statement to create a loadset, which contains a list of
programs or files, or both to load.
The following figure shows the syntax for the @LOADSET control statement section
of the loader input file. In this figure, the double arrowhead (►►) indicates that the
information must begin on a new line.
►► @LOAdset
lsname
CWD
defaultloc
Note: This must be the first line of the @LOADSET control statement section.
►► ▼
,
defaultloc/
progname
specificloc/ version .ext (progcmt)
Note: If you have more than one program in the loadset, use this line as many
times as you need. Each time you use it, separate occurrences with a
comma or start each occurrence on a new line.
►► ▼ @@progname rsa newdata
.objfile valdata-olddata
, MOVe
Note: If you have more than one loadset to patch (or if you have more than one
patch for a loadset), use this line as many times as you need. Each time
you use it, start the next occurrence on a new line.
Figure 22. @LOADSET control statement section of the loader input file
lsname
specifies a name for the loadset to create, where lsname is the 5- to
8-character name of the loadset program that you are creating.
Use the lsname parameter to specify additional programs to follow an @FILES
control statement.
If you do not specify the lsname parameter, the @LOADSET control statement
indicates that the programs to follow are part of the previously defined loadset.
z/TPF offline loader input file control statements 151
►◄
►◄
►◄

152 z/TPF Program Management
defaultloc
is the default location for the @LOADSET control statement section, where
defaultpath is one of the following types of paths:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &LDSTPATH)
v An absolute path (for example, /u/ztpf/ldstpath)
v A relative path (for example, ldstpath).
Note: All relative paths are appended to the current working directory, which
is defined by using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
The default location is searched to locate the programs listed in the
@LOADSET control statement section. You can override the default path for a
particular program by specifying a specific path for that program.
specificloc
is the specific location for the program in the loadset, where specificpath is one
of the following types of paths:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &LDSTPATH)
v An absolute path (for example, /u/ztpf/ldstpath)
v A relative path (for example, ldstpath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
If you specify a specific location for a program, this location overrides any
default location that may have been defined for the @LOADSET control
statement section; that is, only the specific location is searched for the program.
If the program is not found in the specific location, an error occurs.
CWD
is the value specified for the CWD parameter in the @DEFINE control
statement section. If you do not specify a default location or a specific location,
this is the only location that is searched.
progname
is the 4-character alphanumeric name of the program that you want to load to
the z/TPF system. Program names must begin with a letter (A–Z). For example,
if the linker creates a program called ctal51.so, the CTAL portion of the name is
required.
version
is the 1- to 2-character alphanumeric version code for the program. For
example, if the linker creates a program called ctal51.so, the 51 portion of the
name is optional.
.ext
specifies an extension of the full program name as created by the linker, where
ext is the appropriate extension. For example, if the linker creates a program
called ctal51.so, the .so portion of the name is optional.

@VERIFY
(progcmt)
appends a comment for the program specified by progname that is displayed in
the output report, where progcmt is the text that is appended.
@@progname
specifies a program to patch or to move, where progname is the 4-character
name of the program that you want to patch or move. Program names must
begin with a letter (A–Z).
Note: If you want to patch a program, you must load the program in the current
@LOADSET control statement section before you can patch it. If you are
moving an entry point, you must ensure that it is being loaded in the
current @LOADSET control statement section.
.objfile
specifies the object file name, where objfile is the 4-character alphanumeric
name of the object file (within the program) that you want to patch on the z/TPF
system. Object file names must begin with a letter (A–Z).
rsa
is the 1- to 6-digit hexadecimal relative starting address in the program or object
file. The relative starting address specifies the offset into the program or object
file where the patch will be applied.
newdata
is the new data (or patch) that will replace the old data in the program or object
file, beginning at the relative starting address. The new data must be an even
number of hexadecimal digits and cannot exceed 32 digits (16 bytes).
valdata-olddata
validates the data that is replaced by newdata, where olddata is an even
number in hexadecimal format that does not exceed 32 digits (16 bytes). The
data specified for olddata must match what is currently in the program. If it does
not, the data in the program is not changed and an error occurs. If it does, the
data in the program is replaced by newdata. For example, this parameter can
help to verify that your patch is starting at the correct relative starting address.
Note: The length of the data that you are validating can have fewer bytes or
more bytes than the new data. If the validation is completed successfully,
only the number of bytes in your new data will be replaced.
MOVe
indicates that the single entry BSO specified by @@progname has been moved
into another BSO. The BSO that @@progname has been moved to must be
included in the same loadset.
Note: If the E-type loader is used to move an entry point, you cannot activate
another loadset that moves the entry point again. The loadset that
moved the entry point first must be deactivated or accepted before the
entry point can be moved again.
Use the @VERIFY control statement to specify a program attribute table (PAT) that
includes all of the programs being loaded. The loader determines if each program
being loaded exists in the specified PAT.
The following figure shows the syntax for the @VERIFY control statement section of
the loader input file. In this figure, the double arrowhead (►►) indicates that the
z/TPF offline loader input file control statements 153

information must begin on a new line.
►►
@VERIFY
CWD
defaultloc
Note: This must be the first line of the @VERIFY control statement section.
►►
154 z/TPF Program Management
defaultloc/
IPAT
specificloc/ version .ext (progcmt)
Figure 23. @VERIFY control statement section of the loader input file
defaultloc
is the default location for the @VERIFY control statement section, where
defaultloc is one of the following types of paths:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &IPATPATH)
v An absolute path (for example, /u/ztpf/ipatpath)
v A relative path (for example, ipatpath).
Note: All relative paths are appended to the current working directory, which
is defined by using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
The default location is searched for the PAT component listed in the @VERIFY
control statement section. You can override the default path for the PAT
component by specifying a specific location on a separate line.
specificloc
is the specific location for the PAT component to load, where specificloc is one
of the following types of paths:
v The name of a search path that was defined previously in an @DEFINE
control statement section (for example, &VERIFYPATH)
v An absolute path (for example, /u/ztpf/verifypath)
v A relative path (for example, verifypath).
Note: All relative paths are appended to the current working directory, which
is defined using the CWD parameter in the @DEFINE control
statement section. Therefore, you must define the CWD parameter
before you can specify a relative path.
If a specific location is specified for the PAT component, it overrides any default
location that may have been defined for the @VERIFY control statement
section; that is, only the specific location is searched for the PAT component. If
the PAT component is not found in the specific location, an error occurs.
IPAT
specifies the PAT where the list of programs being loaded will be checked. If a
program is not found in the PAT for an OLDR load, the program will be loaded
and a warning will be issued; if a program is not found in the PAT for a TLDR
load, the program will not be loaded.
►◄
►◄

version
is the 1- to 2-character alphanumeric version code for the VERIFY component.
.ext
specifies an extension of the full program name as created by the linker, where
.ext is the appropriate extension. For example, if the linker creates a program
called IPAT51.cimr, the .cimr portion of the name is required.
(progcmt)
appends a comment to the VERIFY component that is displayed in the output
report, where progcmt is the appended text.
z/TPF offline loader input file control statements 155

156 z/TPF Program Management

Sample code
JCL for sending your output
VRDR
GDS
Tape
The following code samples show how to create the code that is necessary to
complete an offline load from your z/OS system.
The following examples show sample JCL for directing the output of your load.
The following JCL will send your output to VRDR:
//VRDRLD JOB MSGLEVEL=1,CLASS=S,MSGCLASS=S
/*ROUTE PRINT TPFVM1()
/*ROUTE PUNCH TPFVM1()
//TLDR EXEC PGM=TPFLDR,PARM=’TLDR’,REGION=90M
//STEPLIB DD DSN=ACP.LINK.CUR51.BSS,DISP=SHR
//LDROUT DD DSN=&&VRDROUT,SPACE=(TRK,(1600,120)),
// DISP=(NEW,PASS),UNIT=SYSDA
//LDRTEMP DD DSN=&&SYSUT1,SPACE=(CYL,(1600,120)),UNIT=SYSDA
//LDRREPRT DD SYSOUT=A
//SYSUDUMP DD DUMMY
//SYSABEND DD DUMMY
//LDRTRACE DD SYSOUT=A
//LDRLOAD DD *
/*
//TRANSMIT EXEC PGM=IKJEFT01,
// PARM=’TRANSMIT TPFVM1.(uderid) DDNAME(SYSTSIN) NOLOG NONOTIFY SEQ’
//SYSTSIN DD UNIT=SYSDA,
// DSN=&&VRDROUT,DISP=(OLD,DELETE)
//SYSTSPRT DD DUMMY
The following JCL will send your output to GDS:
//GDSLDR JOB MSGLEVEL=1,CLASS=S,MSGCLASS=S
/*ROUTE PRINT TPFVM1()
/*ROUTE PUNCH TPFVM1()
//GDSLD EXEC PGM=TPFLDR,PARM=’TLDR’,REGION=90M
//STEPLIB DD DSN=ACP.LINK.CUR51.BSS,DISP=SHR
//LDROUT DD DSN=,DISP=OLD
//LDRTEMP DD DSN=&&SYSUT1,SPACE=(CYL,(1600,120)),UNIT=SYSDA
//LDRREPRT DD SYSOUT=A
//LDRTRACE DD SYSOUT=A
//LDRLOAD DD *
The following JCL will send your output to the Virtual Tape Server (VTS):
//LDROUT DD DSN=BOSS.TAPE,UNIT=VTS,DISP=(OLD,KEEP),
// VOL=SER=TV2127,LABEL=(,SL),
// DCB=(BLKSIZE=4095,RECFM=U)
The following JCL will send your output to VTAPE:
//LDROUT DD DSN=DASD.TAPE,UNIT=VTAPE,DISP=(NEW,KEEP),
// VOL=SER=SCRTCH,LABEL=(,SL),
// SPACE=(TRK,(3500,500)),
// DCB=(BLKSIZE=4095,RECFM=U)
© Copyright IBM Corp. 2005, 2012 157

Input files
The following examples show sample input files for each type of offline load (ALDR,
OLDR, TOLDR).
ALDR input file
The following input file runs the offline loader to perform an ALDR load:
@DEFINE
SYSID=BSS
IMGCLEAR=YES
CWD = /tpf/z11/build/bss/load/
&APPATH = /tpf/z11/build/opensource/stdload/:
/tpf/z11/build/base/stdload/:
/tpf/z11/build/bss/load/
@CTKX
CTKX.kpt
@CIMR
CPS0.cimr, ACPL.cimr, ICDF.cimr, SIGT.cimr, RIAT.cimr,
IPAT.cimr, USR1.cimr, USR2.cimr, FCTB.cimr
@IPL
IPLA.ipl, IPLB.ipl
@GFKEYPOINT
CTKAGF.kpt, CTKVGF.kpt
@@CTKV 8 000E /* patch x’000E’ into keypoint at offset 8 */
@INCLUDE /tpf/z11/build/bss_gfk.loadlist
@KEYPOINT
CTKA.kpt %B, CTKA.kpt %C, CTKA.kpt %D,
CTKB.kpt %O, CTKC.kpt, CTKD.kpt,
CTKEPB.kpt %B, CTKEPC.kpt %C, CTKI.kpt
@INCLUDE /tpf/z11/build/bss_kpt.loadlist
@APPLICATION &APPATH
CISO.so, CLBM.so, CTIS.so, CTAL.so, COSY.so,
/tpf/z11/build/base/xml4c/load/CXML.so, CFIN.so,
@INCLUDE /tpf/z11/build/bss_app.loadlist
@VERIFY
IPAT.cimr
OLDR input file
The following input file runs the offline loader to perform an OLDR load:
158 z/TPF Program Management
@DEFINE
SYSID=BSS
DEBUGFILES=YES
&APPATH = /tpf/z11/build/opensource/stdload/:
/tpf/z11/build/base/stdload/:
/tpf/z11/build/bss/load/
@LOADSET TEST1 &APPATH
CISO.so, CLBM.so, CTIS.so
@FILE
/tpf/files/data/datafile.txt /sys/tpf_pbfiles/data/datafile.txt -p 755 -o tpfdfltu
@LOADSET TEST2 &APPATH

CFIN.so, CXML.so, CTAL.so
@LOADSET TEST#
XNEE.so, XXAA.so
@VERIFY /tpf/z11/build/bss/load
IPAT.cimr
TLDR input file
The following input file runs the offline loader to perform a TLDR load:
@DEFINE
OVERLAY_IPAT=YES
SYSID=BSS
PROGCLEAR=YES
ELDRCLEAR=YES
DEBUGFILES=YES
CWD = /tpf/z11/build/bss/load/
&APPATH = /tpf/z11/build/opensource/stdload/:
/tpf/z11/build/base/stdload/:
/tpf/z11/build/bss/load/
@CTKX
CTKX.kpt
@CIMR
CPS0.cimr, ACPL.cimr, ICDF.cimr, SIGT.cimr, RIAT.cimr,
IPAT.cimr, USR1.cimr, USR2.cimr, FCTB.cimr
@IPL
IPLA.ipl, IPLB.ipl
@KEYPOINT
CTKA.kpt %B, CTKA.kpt %C, CTKA.kpt %D,
CTKB.kpt %O, CTKC.kpt, CTKD.kpt,
CTKEPB.kpt %B, CTKEPC.kpt %C, CTKI.kpt
@@CTKEPB %B 1E 11FF /* patch x’11FF’ into keypoint at offset x’1E’ */
@INCLUDE /tpf/z11/build/bss_kpt.loadlist
@APPLICATION &APPATH
CISO.so, CLBM.so, CTIS.so, CTAL.so, COSY.so,
/tpf/z11/build/base/xml4c/load/CXML.so, CFIN.so,
@INCLUDE /tpf/z11/build/bss_app.loadlist
@FILE
/tpf/files/data/datafile.txt /sys/tpf_pbfiles/data/datafile.txt -p 755 -o tpfdfltu
@VERIFY
IPAT.cimr
Sample code 159

160 z/TPF Program Management

����
Product Number: 5748-T15
Printed in USA
GTPL-2MS5-09