Chapter 12. The Shared Library (SLIB) Component
Provides a set of types for interacting with shared library functions in order to access functionality outside of the scope of SIMPOL.
sharedlibrary
Description
A sharedlibrary object represents a shared library (in Windows a
DLL) in an operating system. To access functions in a shared library, the
findfunction()
method of the
sharedlibrary object is called and the name of the function
and the appropriate parameters must be passed. This returns a
sharedlibraryfunction object and places it in the ring of
functions.
Note | |
---|---|
The use of this functionality will prevent the program from operating successfully on other platforms, unless equivalent functionality is added to the program for each target platform. Whenever possible, avoid using this functionality if the same result can be achieved using libraries provided by SIMPOL. |
Type Tags
None
Object Value
The value of a sharedlibrary object is undefined and it is an error to attempt to either get or set it.
sharedlibrary.new()
Description
Creates a new sharedlibrary object for the specified shared library.
Prototype
sharedlibrary
.new
(
string
,
integer filename
)
error
Parameters
Parameter | Default value | Type name | Description |
---|---|---|---|
filename | None | string | Specifies the file name (which should be a full path name if the file is not in the path or the current directory). |
error | .nul | integer |
Specifies an object which is used to output any error code generated during
creation of the sharedlibrary object. If
error is not specified or is
.nul then any error which occurs during object
creation will halt the program. If an error object is specified and
an error occurs during object creation then the error code is
output into that object and the new method
returns .nul .
|
Properties
Property | Type | Description |
---|---|---|
_ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. |
__ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. It has the additional feature of being marked with the resolve keyword, so that object resolution can continue down this property. |
filename | string | Provides the file name of the shared library that was opened. |
firstfunction | sharedlibraryfunction |
Contains a reference to the first function that is being made available
through the use of the shared library. Only functions that have been
retrieved using the findfunction() method
appear in the ring of functions. For information about the available
functions for a given shared library, see the associated library or
operating system documentation. The makers of SIMPOL are not able to
provide assistance on functionality that is accessed in this way.
|
type | type | Specifies the sharedlibrary type object. |
Methods
findfunction()
Description
Creates a new sharedlibraryfunction object for a specific function in a shared library.
Prototype
sharedlibraryvar
.findfunction
(
string
,
string functionname
,
string name
,
string returntype
,
integer parameters
)
error
Parameters
Parameter | Default value | Type name | Description |
---|---|---|---|
functionname | None | string |
Specifies the name of the function within the shared library that is to be
made available. Currently it is not possible to access functions
in a Windows DLL by ordinal, only by name. Either this parameter
or else the name must be provided. If only
one is provided, it will be assumed that it is the same for both.
|
name | None | string |
Specifies the name to use when accessing the function using the member (!)
operator as an argument of the sharedlibrary object. Either this
parameter or else the functionname must be
provided. If only one is provided, it will be assumed that it is
the same for both.
|
returntype | "" | string |
Specifies the data type returned by the function. If this is the empty string, then the function is not expected to a return a value. This parameter must be either "" (if the return is void), or else a valid entry in the form "xyyy" where x is the letter representing the type and yyy is the size. Valid types are:
Valid sizes are:
|
parameters | "" | string |
Specifies the data type being passed to the function. If this is the empty string, then the function is expecting any parameters. This parameter must be either "", or else a valid set of parameters in the form "xyyy" where x is the letter representing the type and yyy is the size. Valid types are:
Valid sizes are:
In addition, the "t" and "b" parameters also require a value in parentheses, that indicates the size of the buffer being passed. It is also possible to pass a pointer to a structure, including the definition of the structure and having the elements created for the structure. To pass a buffer that can be modified, the parameter must be passed preceded by the "+" character. For full details on how to use shared library functions, see the chapter on them in the Programmer's Guide. |
error | .nul | integer |
Specifies an object which is used to output any error code generated during
creation of the UTOSdirectoryentry object. If
error is not specified or is
.nul then any error which occurs during object
creation will halt the program. If an error object is specified
and an error occurs during object creation then the error code is
output into that object and the getentry
method returns .nul .
|