OS2::DLL - access to DLLs with REXX calling convention.
When you use this module, the REXX variable pool is not available.
See documentation of OS2::REXX module if you need the variable pool.
use OS2::DLL; $emx_dll = OS2::DLL->module('emx'); $emx_version = $emx_dll->emx_revision(); $func_emx_version = $emx_dll->wrapper_REXX('#128'); # emx_revision $emx_version = $func_emx_version->();
$dll = OS2::DLL->module( NAME [, WHERE] );
Loads an OS/2 module NAME, looking in directories WHERE (adding the extension .dll), if the DLL is not found there, loads in the usual OS/2 way (via LIBPATH and other settings). Croaks with a verbose report on failure.
The DLL is not unloaded when the return value is destroyed.
$dll = OS2::DLL->new( NAME [, WHERE] );
Same as module|"Create a DLL handle", but in addition to WHERE, looks in environment paths PERL5REXX, PERLREXX, PATH (provided for backward compatibility).
module
$dll = load OS2::DLL NAME [, WHERE];
Same as new|"Create a DLL handle (looking in some strange locations)", but returns DLL object reference, or undef on failure (in this case one can get the reason via DynaLoader::dl_error()) (provided for backward compatibility).
new
DynaLoader::dl_error()
BOOL = $dll->find(NAME [, NAME [, ...]]);
Returns true if all functions are available. As a side effect, creates a REXX wrapper with the specified name in the package constructed by the name of the DLL so that the next call to $dll->NAME() will pick up the cached method.
$dll->NAME()
$func = $dll->wrapper_REXX(NAME);
Returns a reference to a Perl function wrapper for the entry point NAME in the DLL. Similar to the OS/2 API, the NAME may be "#123" - in this case the ordinal is loaded. Croaks with a meaningful error message if NAME does not exists (although the message for the case when the name is an ordinal may be confusing).
"#123"
$ret_string = $dll->function_name(arguments);
Returns the return string if the REXX return code is 0, else undef. Dies with error message if the function is not available. On the first call resolves the name in the DLL and caches the Perl wrapper; future calls go through the wrapper.
Unless used inside REXX environment (see OS2::REXX), the REXX runtime environment (variable pool, queue etc.) is not available to the called function.
Return the (integer) handle and full path name of a loaded DLL.
TODO: the module name (whatever is specified in the LIBRARY statement of .def file when linking) via OS2::Proc.
LIBRARY
Returns the address of a 32-bit entry point with name $name, or 0 if none found. (Keep in mind that some entry points may be 16-bit, and some may have capitalized names comparing to callable-from-C counterparts.) Name of the form #197 will find entry point with ordinal 197.
#197
Looks for the DLL $name on BEGINLIBPATH, LIBPATH, ENDLIBPATH if bits 0x1, 0x2, 0x4 of $flags are set correspondingly. If called with no arguments, looks on all 3 locations. Returns the full name of the found file. DLL is not loaded.
BEGINLIBPATH
LIBPATH
ENDLIBPATH
$name has .dll appended unless it already has an extension.
If a function takes up to 20 ULONGs and returns ULONG:
$res = call20( $pointer, $arg0, $arg1, ...);
$res = call20_p( $pointer, pack 'L20', $arg0, $arg1, ...);
regparm(3)
$res = call20_rp3( $pointer, $arg0, $arg1, ...);
$res = call20_rp3_p( $pointer, pack 'L20', $arg0, $arg1, ...);
call20_Dos( $msg, $pointer, $arg0, $arg1, ...); # die("$msg: $^E") if error
[Good for Dos* API - and rare Win* calls.]
Dos*
Win*
$res = call20_Win( $msg, $pointer, $arg0, $arg1, ...); # would die("$msg: $^E") if error
[Good for most of Win* API.]
$res = call20_Win_0OK( $msg, $pointer, $arg0, $arg1, ...); # would die("$msg: $^E") if error
[Good for some of Win* API.]
$res = call20_Win_0OK_survive( $pointer, $arg0, $arg1, ...); if ($res == 0 and $^E) { # Do error processing here }
If PERL_REXX_DEBUG is set, emits debugging output. Looks for DLLs in PERL5REXX, PERLREXX, PATH.
PERL_REXX_DEBUG
PERL5REXX
PERLREXX
PATH
Extracted by Ilya Zakharevich perl-module-OS2-DLL@ilyaz.org from OS2::REXX written by Andreas Kaiser ak@ananke.s.bawue.de.
To install sort, copy and paste the appropriate command in to your terminal.
cpanm
cpanm sort
CPAN shell
perl -MCPAN -e shell install sort
For more information on module installation, please visit the detailed CPAN module installation guide.