Chapter 12. The Shared Library (SLIB) Component
Prev Part II. C-Language Components Next

Chapter 12. The Shared Library (SLIB) Component

Table of Contents

sharedlibrary
Description
Type Tags
Object Value
sharedlibrary.new()
Properties
Methods
sharedlibraryfunction
Description
Type Tags
Object Value
Properties
Methods

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]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 filename, integer error )

Parameters

ParameterDefault valueType nameDescription
filenameNonestring Specifies the file name (which should be a full path name if the file is not in the path or the current directory).
error.nulinteger 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

PropertyTypeDescription
_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.
filenamestring Provides the file name of the shared library that was opened.
firstfunctionsharedlibraryfunction 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.
typetype 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 functionname, string name, string returntype, string parameters, integer error )

Parameters
ParameterDefault valueType nameDescription
functionnameNonestring 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.
nameNonestring 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:

  • u|U — unsigned int

  • s|S — signed int

  • f|F — float

Valid sizes are:

  • p|P — pointer, the same size as a pointer for the current machine, but the type has to be a u|U

  • 8|16|32 — for types s|S and u|U on a 32-bit machine

  • 32|64 — for f|F (or the number of bits in a float or a double on the target machine)

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:

  • b|B() — byte

  • u|U — unsigned int

  • s|S — signed int

  • f|F — float

  • t|T() — text

  • p|P[] — pointer

Valid sizes are:

  • p|P — pointer, the same size as a pointer for the current machine, but the type has to be a u|U

  • 8|16|32 — for types s|S and u|U on a 32-bit machine

  • 8|16 — for type t|T (8-bit or 16-bit characters)

  • 32|64 — for f|F (or the number of bits in a float or a double on the target machine)

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.nulinteger 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.
Prev Up Next
wxrgbdialog() Home sharedlibraryfunction