Interface Functions Between PROIV and the DLL |
Virtual Machine |
 |
The EXTSUB DLL has three exported cdecl functions, init() with ordinal value 1, term() with ordinal value 2, and extsub() with ordinal value 3.
The function init() is called by PROIV to initialise the module. Two arguments are passed to the function - a char * pointer to the name of the configuration file so that the module can access any configuration settings, and a pointer to an internal table of callback functions. You can insert your own code in this function to handle one-time initialization of your module's variables. This table allows the user code access to privileged PROIV internal functions and is defined in the include file extsub.h by the PROSUB data type, as follows:
typedef struct tagPROSUB
{
int(__cdecl *prompt)(const char *title, const char *text, char *reply, int len);
int(__cdecl *printf)(const char *format, ...);
void(__cdecl *QueryInfo)(const QUERYINFO *qinfo);
} PROSUB;
typedef PROSUB *PPROSUB;
The user code accesses the table via the local variable prosub, of type PPROSUB. Only three callback functions are currently defined, although the table allows for further functions to be made available over time and on demand:
prompt Invokes a input-box window with OK . The input box displays a prompt message and retrieve a single line of input text from the user.
title points to a null-terminated string to be used for the input box title. If this argument is NULL, the default title ‘PROIV Kernel Prompt’ is used.
text points to a null-terminated string containing the message to be displayed.
reply points to a character array of length len to return the user input text. If len is zero, no input field appears and the reply argument is ignored.
printf Displays a null-terminated text string on the PROIV status line. Note that printf will not support a variable number of arguments in this release.
QueryInfo Returns PROIV and GUI environment information to the user provided QUERYINFO structure. The definition of this structure is as follows:
typedef struct tagQUERYINFO {
short nSize;
char szIniFile[144];
WININFOpro;
WININFOgui;
} QUERYINFO;
where:
nSize is reserved. Must be set to size of (QUERYINFO) prior to the QueryInfo function call.
szIniFile is a character array that returns the null terminated pathname of the PROIV initialization file.
pro is a WININFO structure to return PROIV Windows information (see below).
gui is a WININFO structure to return GUI Windows information (see below).
The WININFO structure holds Windows specific information that allows interaction between the EXTSUB module and the PROIV sub-system; refer to your Microsoft Windows SDK documentation for further information. The definition of this structure is as follows:
typedef struct tagWININFO {
HINSTANCE hinstApp;
HWNDhwndMain;
} WININFO;
where:
hinstApp is the application instance handle.
HwndMain is the application’s main window handle.
Prior to exiting back to the system, PROIV calls the function term() to allow the module to relinquish any data structures created; no arguments are passed. You can insert your own code in this function to handle termination of your module.
Any code that you write for the init() or term() functions or which makes use of the callback table, will be GUI platform-specific and hence non-portable. You should consider this carefully in the design of your module.
The function extsub() is indirectly invoked by the LINK and LINK-CRT commands. The prototype of the function is:
int __cdecl extsub(short argc, void *argv[]);
where:
argc is the argument count.
argv[0] is the function name, e.g. SUB0. Note that this is treated in a case sensitive manner.
argv[1...] is the string form of PROIV NUMERIC or STRING argument, padded to the variable size and with a null terminating byte. The byte preceding the start of the string is the size of character array allocated for the string.
Return codes are as follows:
0= successful operation
-1=function not found
-2=too many arguments supplied
Topic ID: 750028