The LINK Logic Verb Family |
DEVELOPER |
 |
|
The LINK Logic Verb Family |
DEVELOPER |
|
The LINK, LINK-CLIENT, and LINK_CLIENT_VAR Logic Verbs are used to call subroutines written in another language from PROIV Logic. In the Windows environment, these subroutines are in the Windows DLLs. This is different from other kernel platforms, where subroutines are typically written as C functions, and then linked directly into the kernel or 3GL language for the UNIX.
This difference has two impacts:
The subroutines must be coded in a DLL. Typically, this involves adding wrapper code to the subroutine source file. The example source code provided with the Windows kernel distribution gives a suitable wrapper for subroutines written in C.
The first parameter of a LINK call is used to define the DLL entry point, and therefore, has a more specific meaning than on other platforms. On other platforms, a single entry point extsub is always called. In Windows, the first parameter defines both the DLL and the entry point to call.
Other points to note include:
32-bit versions of Windows do not support 64-bit DLLs. 64-bit versions of Windows do not support calling 32-bit DLLs from 64-bit programs.
For DLLs to be usable by the Windows kernel, there are some issues to be aware of. See the Windows Multi-Threading Issues section below for more information.
The logic call syntax for LINK is:
LINK($name, $param1, $param2, ..)
The logic call syntax for LINK-CLIENT and LINK-CLIENT-VAR is the same:
#stat = LINK-CLIENT($name, $param1, $param2, ..)
#stat = LINK_CLIENT_VAR($name,[direction]$param1,[direction] $param2, ..)
where: [direction] A optional prefix indicating whether the parameter is an input to the DLL, an output from the DLL or both. The prefix is one of the following:
%IN% A parameter is an input to the DLL. Its value is passed to the DLL, but any changes to the parameter by the DLL are not be passed back.
%OUT% A parameter is an output from the DLL. Its initial value is ignored (blanks are passed to the DLL). Its value is passed back on return from the DLL.
%BOTH% A parameter is both an input to the DLL, and an output from the DLL. Its value is passed to the DLL and any changes to the parameter by the DLL are passed back.
Long ALPHA strings are supported on UNIX (i.e. each parameter may be up to 2000 bytes long. The maximum number of parameters is only limited by the PROIV Logic compiler workspace (up to a theoretical limit of 255).
The first parameter is the DLL entry point name. For LINK-CLIENT and LINK_CLIENT_VAR, the Client processes this parameter. For LINK, the kernel processes the parameter. Both accept the same syntax, except as noted below:
If this first parameter contains a period, the part before the period is the DLL name. This is passed exactly as specified to the Windows LoadLibrary() function. Therefore, the search path is as specified for LoadLibrary, or it can contain a pathname. A DLL is only loaded once and is not unloaded until the Kernel or Client process terminates. For DLLs specified using a PROLINK= option, the DLL is loaded at Kernel process startup. Other DLLs are loaded on the first call.
If there is no period, the first DLL listed in the INI file [Environment] section PROLINK= option is used (if PROLINK= does not exist, it is an error not to use a name+period).
The part after the period (the whole string if there is no period) is the entry point name.
The Windows GetProcAddress() function is used to locate the specified entry name.
If this entry point does not exist, GetProcAddress() is used to locate the fixed entry name extsub.
If a valid entry point cannot be located, the function is aborted with a system error 182 (entry point not found).
Once the entry point to call is located, a parameter list is built. This is a standard C argc, argv list, with the first argv parameter (argv[0]) being the first parameter passed to the LINK/LINK-CLIENT (for example, the DLL entry point parameter). Each parameter may be a numeric or string parameter.
Numerics are converted to strings before being passed to the DLL. This conversion uses a free format (the same code as is used for displaying numbers on the screen). As this can generate exponent format in some cases (for example, 1.2e23), numerics are normally avoided. If you want to pass a number, use CONV to convert the numeric to a string in the format preferred and pass the string so you know exactly what format is being passed.
The actual format that a parameter is passed, as is different depending on which verb is used.
For LINK and LINK-CLIENT, each parameter passed is padded to its maximum size with spaces, followed by a null byte. The maximum length of each parameter is stored in the byte immediately before the first byte of the parameter. For example: argv[1][-1] might contain the length of $param1 in the above example logic call. This may be used rather than searching for the null terminator to find out the parameter buffer size. (A current restriction is that the C function strlen is used to calculate this length, so if an ALPHA parameter contains a null character, it only indicates the length up to the first null.)
For LINK_CLIENT_VAR, each parameter is passed without padding (and without a null terminator). There is a 4-byte header at the start of each parameter. The parameter address passed to the DLL is the start of this header (in contrast to LINK/LINK-CLIENT, where the parameter address points after the header):
|
Byte Position |
Use |
|
[0] |
Maximum size (high order byte). For output/both parameters, this is the maximum size that can be returned. For input, it will be set to the same value as current size. |
|
[1] |
Maximum size (low order byte) |
|
[2] |
Current size (high order byte). For output parameters, this will be 0. |
|
[3] |
Current size (low order byte). |
NOTE: The above size parameters are in big-endian byte order (for example, the opposite order that the two bytes of a short are stored on an Intel PC), so do NOT cast them to (short *) to pick up the size. Instead, use syntax similar to the following:
Current_size = (parameter[n][0] << 8) | (parameter[n][1] & 0xff);
Maximum_size = (parameter[n][2] << 8) | (parameter[n][3] & 0xff);
For Output and Both parameters, any changed value must be copied back into the parameter area, and the current size (bytes 2 and 3 of the parameter) must be updated to the size of the new value. Note that the new size must not exceed the maximum size value.
The supplied skeleton source (extsub\extsub.c under the installation directory) uses a table search and switch statement to decide which function to pass a request to. As supplied, this limits you to 10 entry points called SUB0 to SUB9 and a maximum of 10 parameters per entry point.
When control returns from the entry point, the parameter list is passed back to the kernel, which then updates the parameters to the logic LINK/LINK-CLIENT/LINK_CLIENT_VAR verb with these values. Numerics are converted as described above. For LINK/LINK-CLIENT, the first null located in the parameter string is used to decide the return parameter size. For LINK_CLIENT_VAR, the current size field indicates the return size.
The DLL return status is passed back as the result value of the LINK/LINK-CLIENT/LINK_CLIENT_VAR.
The exception to this is for LINK only, if the DLL returns a value of -1, PROIV aborts the function with a system error 182, therefore, do not return -1.
LINK-CLIENT/LINK_CLIENT_VAR with Windows Client only: @CLIENTINFO system variable can be used to find handle of Client main window.
For LINK with the Windows kernel, the DLL needs to support multiple threads from one process (one thread per connected user). Other scenarios of LINK, and all uses of LINK-CLIENT and LINK_CLIENT_VAR need to support one thread per process with multiple processes.
Topic ID: 520016