gtpc2m7s | C/C++ Language Support User's Guide |
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
- These macros cannot be called from either of the following:
- C++ language
- C language that is compiled using the dynamic link library (DLL)
option.
- The TPF_CALL_BY_NAME_STUB() macro should be used only to define
stub variables that will be passed to the TPF_CALL_BY_NAME()
macro.
- The stubname parameter that is passed to each
TPF_CALL_BY_NAME() macro must have previously been defined by a
call to the TPF_CALL_BY_NAME_STUB() macro.
- There are 3 parts to calling a program by name using the
TPF_CALL_BY_NAME() macro:
- Declaring a typedef for the type of the address of the entry
point in the called program (funtype), or, in other words, a
pointer to function type.
- Defining a call stub variable by calling the
TPF_CALL_BY_NAME_STUB() macro. This macro must be called in
the declaration section of a block (that is, before any statements) or at file
scope. If it is called at block scope, it defines the stub in automatic
storage. If it is called at file scope, it defines the stub with
external linkage in writable static storage; therefore, the source file
in which it is called must be compiled with the RENT option. The same
stubname can be reused for more than one
TPF_CALL_BY_NAME() macro call.
- Calling the TPF_CALL_BY_NAME() macro, passing it the program
name, stub variable identifier (stubname) defined by the previous
TPF_CALL_BY_NAME_STUB() macro, and program entry point address type
(funtype) declared by the previous typedef. The
TPF_CALL_BY_NAME() macro returns a function pointer value of type
funtype.
- Each execution of TPF_CALL_BY_NAME() modifies the stub variable
stubname passed to it.
- Subsequent calls to TPF_CALL_BY_NAME() may invalidate the
pointer to function value returned by a previous call to
TPF_CALL_BY_NAME().
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