gtpc2m7sC/C++ Language Support User's Guide

TPF_CALL_BY_NAME, TPF_CALL_BY_NAME_STUB-Call (Enter) a Program by Name

The TPF_CALL_BY_NAME_STUB() macro defines a call stub variable, which can be passed to a TPF_CALL_BY_NAME() macro. The TPF_CALL_BY_NAME() macro returns a pointer to a function value which can be used to transfer control to a TPF segment. Calling the function pointer executes enter with return linkage to the specified program. 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>
TPF_CALL_BY_NAME_STUB(stubname);
funtype TPF_CALL_BY_NAME(const char *program, stubname, funtype);

stubname
The ordinary identifier name of the call stub to be defined by the TPF_CALL_BY_NAME_STUB() macro and passed to the TPF_CALL_BY_NAME() macro.

funtype
A pointer to function type of the same type as the address of the entry point of the application program you want to enter. If the application program is a TPF BAL segment, funtype must be a pointer to a function that takes a single parameter of type (struct TPF_regs *) and returns a pointer, integer, or void type. The tpfapi.h header file provides 2 typedef identifiers 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;

program
A 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.

Normal Return

The TPF_CALL_BY_NAME() macro returns a pointer to function type as specified by the funtype parameter.

Error Return

Not applicable.

Programming Considerations

Examples

The following example shows the 3 steps for entering a TPF program by name using the TPF_CALL_BY_NAME() macro.

#include <tpfapi.h>
 
/**********************************************************************/
/* 1. Declare (typedef) function pointer types for the programs you   */
/*    need to enter (this is often done in a header file which can be */
/*    included in multiple applications).                             */
/**********************************************************************/
typedef char *(*chptrfn)(int);
typedef void (*voidfn)(void);
 
char *XYZ0(int index)
{
    /******************************************************************/
    /* 2. Call the TPF_CALL_BY_NAME_STUB() macro to define a stub     */
    /*    variable which can be passed to the TPF_CALL_BY_NAME()      */
    /*    macro.                                                      */
    /******************************************************************/
    TPF_CALL_BY_NAME_STUB(cbn_stub);
 
    /******************************************************************/
    /* 3a. Call the TPF_CALL_BY_NAME() macro to execute an enter by   */
    /*     name with return.  This statement calls a (char *(*)(int)) */
    /*     type function.                                             */
    /******************************************************************/
    char *program = TPF_CALL_BY_NAME("ABCD", cbn_stub, chptrfn)(index);
 
    /******************************************************************/
    /* 3b. This statement calls a (void (*)(void)) type function.     */
    /******************************************************************/
    TPF_CALL_BY_NAME(program, cbn_stub, voidfn)();
 
    return program;
}

Related Information