gtpa2m0g | Application Programming |
TPF has established certain programming conventions to achieve high
performance and ease program maintenance. It is important that the
application conform to these conventions. TPF enforces some of the
conventions; only good programming discipline can maintain others.
Some of these conventions have been mentioned already and some will be
discussed, in detail, in later sections.
These conventions apply to TPF applications programming in general.
Those particular to assembler language and C language follow this
section.
- All application programs must be reentrant. They must not contain
any internal switches, indicators, or counters.
- Do not modify the fields in the ECB that TPF maintains. These
fields include, but are not limited to, core block reference words, the TPF
register save area, and other control information. Refer to these
fields as necessary.
- Remember that TPF does not necessarily clear or initialize any working
storage blocks before assigning them to the application program.
All working storage blocks begin on a doubleword boundary.
- Symbolic references must be maintained in all areas. This will
enable programming to be configuration independent and system parameters to be
changed without extensive programming effort.
- In assembly language no absolute address constants can be used; the
technique of subtracting one label from another in order to obtain an actual
byte count of the distance between the two locations can be used, provided the
two labels are defined within the same program segment or data record.
- Also in assembly language the names for all storage locations, registers,
and I/O devices should be symbolic.
- Use of absolute values of all types should be minimized. In C
language only put absolute values in headers and associate symbolic names with
these values.
- Use the TPF_regs structure in C language for passing data in
registers to programs where registers must be specified.
- When your application programs will operate on any I-stream of a
multiengined CPC, follow the rules of multiprogramming and multiprocessing as
described in the ESA/390 Principles of
Operation. In general, TPF will handle the serial access to data
records via the normal system services (for example, getcc,
relcc, find_record or FINDC, file_record or
FILEC, fiwhc, filuc). However, when your
application interacts with a shared resource, such as a common global field,
use appropriate multiprocessing techniques to access and update these
areas.
- Ensure that your application programs return control to TPF within 500
milliseconds of activation. Control may be returned in several ways,
some of which follow:
- Call the waitc function while waiting for I/O activity to
complete. This is required for any find request. A program may
call the waitc function explicitly, or may call another function
(for example, a fiwhc function) that, in turn, performs a
wait. Note that waitc returns control to the application
program, and resets the 500-millisecond timer, only after all I/O activity for
the ECB actually has completed.
- Call the dlayc or defrc function partway through the
program logic to place the program's entry at a lower priority than other
work. You might use this method if the program does little I/O
activity, but might run slowly enough to risk breaking the 500-millisecond
limit.
- Call the exit function to end processing of the program.
Most application programs are transaction- and I/O-oriented, so they return
control to TPF frequently with each waitc. The timing
constraint usually only becomes a concern if the programs will be retrieving
much of their data from the virtual file access area. Such retrieval
does not reset the 500-millisecond timeout counter. See Virtual File Access Facility for more information.
- Ensure that all application programs call a waitc function,
either explicitly or implicitly, after a read or write request to ensure that
the I/O is complete before attempting to use the requested resource (for
example, the file record to be read with a Find function. See Summary of File Reference Functions and Macros).
- Application programs should return any system resources not in use or
imminently planned for use. This is an important discipline. All
system resources (such as main storage blocks and file pool addresses) should
be returned promptly. Because many ECBs operate concurrently, failure
to do this could be a significant drain on system performance and require
excessive resource allocation.
- During execution of a TPF API function, a variety of exceptional
conditions may be detected. Application programs regain control only on
I/O hardware errors or I/O-associated unusual conditions related to a unique
entry. A function parameter error results in a forced exit and a
dump. TPF takes a dump and sends an operator message only on I/O
hardware errors. These conditions are recorded in the ECB on return to
the application program from the TPF API function.
- Use the find-and-hold functions to hold all file storage records before
you update them, to ensure the proper sequence of update.
See Record Hold Facility for more explanation. Ensure that your program holds
only one record at any given time, to prevent a lockout condition
from occurring.
Below is a summary listing of assembler language programming
conventions:
- Except where otherwise noted, only 31-bit addresses must be passed to TPF
system services.
- All assembly language application programs must fit into a 4KB block to
adhere to the basic file structure and main storage management facilities of
the system. Approaching the block size limit too closely, for example,
within 20%, increases the difficulty of making corrections or
modifications to the program.
- Application programs should not execute privileged instructions, nor
explicitly issue the supervisor call (SVC) instruction.
- Application programs should not make use of the restricted-use control
program macros described in TPF System
Macros. Only the general use control program macros and the
general purpose application macros are appropriate for application programs,
because only these macros are guaranteed to be compatible with later releases
of TPF.
- The general registers 0 through 7 are reserved for use by application
programs. Their contents are saved across all control program
macros. Registers 14 and 15 may also be used by application programs,
but are often used by the control program to pass information between
programs. The contents are not guaranteed across macro calls unless
otherwise indicated.
- General register 8 always contains the base address of the active
application program. It must not be altered by application
programs.
- General register 9 always contains the address of the current active entry
control block. It must not be altered by application programs.
- General register 10 is reserved for CP use, but can be used as a scratch
register (the contents are not guaranteed across macro calls).
- General registers 11 and 12 are reserved for control program use.
Their contents must not be modified by an application program.
- General register 13 is reserved for CP use, but can be used as a scratch
register (the contents are not guaranteed across macro calls).
- All storage is assigned by the control program. You do not, in
general, code define storage (DS) commands in your own application program to
describe storage block formats. Instead, your program requests storage
blocks from the control program and uses TPF or user data macros to describe
the formats.
- An application macro may generate inline code or an SVC through the use of
a control program macro. The SVC machine instruction is never directly
used by an application.
The following summary lists conventions that apply to using the C
language.
- Allocate your program as 31-bit mode only. In general, TPF programs
may be allocated in either 24-bit mode or 31-bit mode; however, TPF C
language support requires programs in C to be in 31-bit mode.
- Give a unique 4-character name to each application program segment.
For ISO-C, each application program segment must contain either a
main function or a function with the same name as the program
segment. For TARGET(TPF) programs, the name of the first external
function will be used as the name of the segment.
If you prefer to use a longer name for readability, code a
#pragma map statement for the segment name.
#pragma linkage(name ,TPF, type) is not supported for
ISO-C
- Use the system function to activate a C program that contains a
main function.
- Follow the register conventions established in the TPF
Program Development Support Reference when coding programs that interact
between the assembler and C language support.