contents   index   previous   next



SElib.dynamicLink() - for OS/2

syntax:

SElib.dynamicLink(library, procedure, bitSize,

                  convention[, [desc,] param …])

where:

library - a string, the name of the dynamic link library, DLL, being used, the one having the procedure being called.

 

procedure - a string or number, the name or ordinal number of a routine in a dynamic link library to be used.

 

bitSize - indicates whether this call is 16-bit or 32-bit and may be either of two defined values: BIT16 or BIT32.

 

convention - the calling convention to use when invoking or using the procedure being called.

 

CDECL    Push right parameter first.

         Caller pops parameters.

STDCALL  Push right parameter first.

         Caller pops parameters.

PASCAL   Push left parameter first.

         Callee pops parameters.

 

desc - a blobDescriptor that describes the following param if param is a structure. (See blobDescriptor example.) A blobDescriptor is only used in front of params that are structures and is required for such params. A Blob (Binary Large Object) and a Buffer are very similar in ScriptEase. The Blob is the type that was used, in the early days of ScriptEase, to work with data in sections of memory. The Buffer is the newer type. Structure types may be created in Blobs or Buffers and blobDescriptors may be used to describe the data in either type. So, in ScriptEase, you will sometimes see blobDescriptor before a param of type Blob or a param of type buffer. In either case, the blobDescriptor is describing how data is stored in the param, even if the data is a string.

 

param - a variable for a section of memory that holds data in the form of a structure of elements or a buffer a string.

 

return:

value - the value returned by the procedure being called, else void if the procedure does not return a value.

 

description:

For OS/2

 

Calls a routine in a dynamic link library, DLL.

 

Any parameters required by a dynamically linked function should be passed at the end of the parameters listed above, as indicated by the ellipsis at the end of the parameter list. These variables are interpreted as follows, depending on the operating system.

 

For 32-bit functions, all values are passed as 32-bit values. For 16-bit functions, if the parameter is a Blob, a byte-array, or an undefined value, then it is passed as a 16:16 segment:offset pointer, otherwise all numeric values are passed as 16-bit values, so if 32-bits are needed they must be passed in parts, with the low word first and the high word second.

 

If a parameter is undefined when SElib.dynamicLink() is called, then it is assumed that parameter is a 32-bit value to be filled in, that is, that the address of a 32-bit data element is passed to the function and that function will set the value. If any parameter is a structure then it must be a structure that defines the binary data types in memory to represent the following variable. Before calling the DLL function, the structure is copied to a binary buffer as described in Blob.put() and Clib.fwrite(). After calling the DLL function, the binary data is converted back into the data structure according to the rules defined in Blob.get() and Clib.fread(). Data conversion is performed according to the current _BigEndianMode setting.

 

An alternative syntax:

 

The OS/2 processor also allows you to call a function via a call gate with the following syntax:

 

SElib.dynamicLink(callGate, bitSize, convention,

   ...)

 

Where callGate is the gate selector for a routine referenced through a call gate.

 

see:

Blob object, blobDescriptor example, Clib.fread()