This general macro comes at the beginning of a TPF real-time
program. It provides the necessary formatting for a program header in
E-type assembler language programs. The information formatted by the
macro is used by the system loader and the application core load and restart
information. See TPF System Installation Support
Reference for more information about the system loader and global area
program.
BEGIN also generates a TITLE card with an operand field consisting of the
NAME parameter concatenated with the VERSION parameter. BEGIN must be
the first statement of each assembler language ECB-controlled program,
including drivers, to require the use of the program CSECT because it defines
the CSECT and program header.
BEGIN can also be coded in assembler code that is linked into ISO-C object
files.
Format
- label
- A symbolic name may be assigned to the macro statement.
- NAME=ann..n
- The program name. The first character must be alphabetic; the
remaining characters must be alphanumeric.
- If TPFISOC=NO is specified (or defaults), the program name must be 4
characters.
- If TPFISOC=YES is specified, the program name can be up to 6
characters. If the program name is a dynamic link module (DLM) entry
point, it must match the 4-character DLM load module name.
The program name will be set to XXXX if not coded or not valid.
- VERSION=vv
- A 2-character version number to be associated with this program.
If not coded, a default version of 99 will be supplied.
- IBM
- Specify one of the following:
- NO
- The default; signifies this is not IBM-released code.
- YES
- Signifies this is IBM-released code.
- BASE=Rx
- The base register to be used by this program. R8, the default, is
assumed to be used by all nondriver programs. If TPFISOC=YES is
specified, the BASE parameter default is R15.
- DRIVER
- Specify one of the following:
- NO
- The default, the program is not a driver.
- YES
- The program is a driver. R11 will be the base register.
- SDS
- This is used for drivers that do not want to activate the global restart
programs CIJH and GOGO.
- CPS
- This is the same as in the YES option, but R8 will be the base
register.
Do not code the DRIVER parameter when TPFISOC=YES is specified.
- TEST
- Specify one of the following:
- NO
- The default; indicates the TSTEQ equates will not be called.
- YES
- Indicates a request for the TSTEQ equates.
Do not code the TEST parameter when TPFISOC=YES is specified.
Entry Requirements
None.
Return Conditions
None.
Programming Considerations
- The normal program header is 8 bytes (2-byte record ID, 2-byte program
length, 4-byte program name).
- A check is made by the macro for a valid NAME keyword. If the name
is incorrect, the macro will insert the name XXXX. The program cannot
be loaded with an XXXX name entry.
- This macro calls the following macros:
TSTEQ, when TEST=YES or DRIVER=YES|SDS|CPS
EB0EB, always
SYSEQ, always
SYSEQC, when IBM=NO
UXTEQ, when IBM=NO
XMSEQ, always.
- This macro will enter the global restart programs CIJH and GOGO on initial
activation of this program when DRIVER is YES or CPS. In these cases
the program is non-reentrant because it modifies itself to do this.
- When assembly language segments are linked into ISO-C object files, the
TPFISOC parameter must be coded as YES. The BEGIN macro does not
generate a program header, but does generate an ENTRY point label using the
NAME parameter. BEGIN in ISO-C code is particularly useful for
migrating TARGET(TPF) library functions; see also TMSPC-Prolog for ISO-C Functions Calling TPF Macro Services and TMSEC-Epilog for ISO-C Functions Calling TPF Macro Services.
Examples
None.