__ep_find() — returns the address of the entry point of the function owning the dsa_p DSA

Purpose

The __ep_find() function returns the address of the entry point of the function owning the dsa_p DSA. __ep_find() can be used when the passed-in DSA is not in the current address space. To access storage outside the current address space, the user must provide the callback_p parameter, which is a pointer to a user-written function that fetches all data required by __ep_find(). Generally, the (*callback_p )() function would obtain the data using some application-dependent method (like BPX1PTR) and move it into the current address space, where __ep_find() can access it directly. If the passed-in DSA is in the same address space and is directly accessible to __ep_find(), callback_p can be NULL.

Syntax

#include <edcwccwi.h>

void *_ep_find (const void * dsa_p, int dsa_fmt, void * (*callback_p)(void * data_p, size_t data_l))

const void * dsa_p

Pointer to the DSA. dsa_p may point to a DSA in another address space or in some other place not directly accessible by __ep_find(). If this address is not directly accessible, the callback_p parameter must be non-NULL. The callback function will be used to access dsa_p indirectly.

int dsa_fmt

The format of the DSA pointed to by dsa_p. The allowed values for dsa_fmt are:

__EDCWCCWI_UP: This value indicates that dsa_p points to a non-XPLINK DSA.
__EDCWCCWI_DOWN: This value indicates that dsa_p points to an XPLINK DSA.

void * (*callback_p)()

Pointer to a user-provided function that fetches data not normally accessible by __ep_find(). If callback_p is NULL, __ep_find() accesses dsa_p and any other required Language Environment data areas directly in the current address space. All required data must be directly accessible to __ep_find() in this case. The user-provided (*callback_p)() function is passed the address and length of data to access. It must fetch the data in some application-dependent manner, and make the data available in the current address space in a place accessible to __ep_find(). (*callback_p)() must return a pointer to the copied data. This data must remain available to __ep_find() until the next call to (*callback_p)(), or until __ep_find() returns to its caller, whichever happens first. On subsequent calls, (*callback_p)() is allowed to reuse the same data passback area. There is no provision for (*callback_p)() to pass back an error return code, indicating that the requested data could not be obtained. If (*callback_p)() cannot return the requested data, it must not return to __ep_find(). When an error occurs, (*callback_p)() may:

longjmp() back to some error return point in the user code that called __ep_find()
abend or otherwise terminate abnormally
exit(), pthread_exit()
Raise a caught signal where the catcher does longjmp() so as not to return to __ep_find()
Use Language Environment condition management to bypass __ep_find() after the error and resume in user code
Recover in some other way that does not involve returning to __ep_find().

__ep_find() calls (*callback_p)() with two parameters:

void * data_p: Pointer to the start of the required data. This address might not be in the current address space.
size_t data_l: The number of bytes of data required. data_l will never exceed 16 bytes. If (*callback_p)() cannot pass back the complete data requested, it must not return to __ep_find().

Return values

If successful, __ep_find() returns the entry point address of the function owning the dsa_p DSA.
If unsuccessful, __ep_find() returns a NULL pointer, and sets errno. to one of the following values:
ESRCH

This error indicates that the entry point could not be located for the passed-in DSA. This error also occurs if dsa_p is NULL when __ep_find() is called.

EINVAL

This error occurs if dsa_fmt is not __EDCWCCWI_UP or __EDCWCCWI_DOWN.

Usage notes

__ep_find() may cause program checks if it accesses invalid addresses. This is especially likely to happen if callback_p is NULL and the DSA being looked at is not valid. For this reason, the caller should consider having a signal catcher set up to handle SIGSEGV with appropriate error recovery.
The Vendor Interfaces header file, <edcwccwi.h>, is located in member EDCWCCWI of the SCEESAMP data set. To include <edcwccwi.h> in an application, the header file must be copied into a PDS or into a directory in the UNIX file system where the z/OS® XL C/C++ compiler will find it.