gtpc2m1vC/C++ Language Support User's Guide

entrc-Enter a Program with Expected Return

This macro transfers control to a TPF segment. The current active program remains held by the entry control block (ECB). The address of the next sequential instruction (NSI) in the current program is saved for an expected return.

Format

#include   <tpfapi.h>
void       entrc(const char *program, struct TPF_regs *regs);

program
Pointer to the name of the application program you want to enter. program must be the 4-character name of a BAL segment, a TARGET(TPF) segment, or a TPF ISO-C DLM.

regs
Treated as a pointer to struct TPF_regs (defined in <tpfregs.h>) that contains 8 signed long integer members, r0-r7. When calling a BAL segment, the TPF control program enter routine uses these members to load general registers R0-R7 before passing control to the entered segment. If this argument is coded as NULL, no registers are loaded.

When calling a TARGET(TPF) segment or TPF ISO-C DLM, the value of the regs parameter is passed the same as any other C function parameter. Therefore, the called entry point address must have a type equivalent to (void (*)(struct TPF_regs *)). The <tpfapi.h> header file provides 2 typedefs for declaring functions and pointers to functions of this type, TPF_BAL_FN and TPF_BAL_FN_PTR, defined as:

    typedef void TPF_BAL_FN(struct TPF_regs *);
    typedef TPF_BAL_FN *TPF_BAL_FN_PTR;

Normal Return

Void.

Error Return

Not applicable.

Programming Considerations

This function cannot be called from either of the following:

Examples

The following example looks up a table of program names and calls the appropriate program based on the index parameter.

#include <tpfapi.h>
#include <tpfregs.h>
const char (*getpgmtbl(void))[4];
void polymorph(int index, struct TPF_regs *regs)
{
    entrc(getpgmtbl()[index], regs);
    
  ·
  ·
  ·
}

Related Information