ActivePerl FAQ - Modules and sample scripts

# Modules and sample scripts

- NAME
- DESCRIPTION
  - How can I use modules from CPAN?
  - Where do I get make for Win32?
  - How do I access databases from my Perl script?
  - Is there a way to use OLE Automation servers from my Perl script?
  - Is there a way to access Data Access Objects (DAO) from my Perl
  - Can I send Internet mail from ActivePerl?
  - Is there a way to access MAPI from my Perl script?
  - Is there a DBM implementation available for ActivePerl?
  - Is there a way to do GUI programming with ActivePerl?
  - Is there a port of Oraperl for Win32?
  - What modules come with the ActivePerl distribution?
  - Where can I find other modules for ActivePerl?
  - What is CPAN and how do I use it?
  - Is there a library to read or write Microsoft Office or other application files?
- AUTHOR AND COPYRIGHT

## NAME

ActivePerl-faq9 - Modules and sample scripts

## DESCRIPTION

General questions about using modules and scripts with ActivePerl

## How can I use modules from CPAN?

As of version 5.005, ActivePerl supports the MakeMaker utility. This allows you to install modules from CPAN, but requires you to have a make utility, such as nmake or dmake. Modules are generally distributed in gzipped tar files, such as Data-Dumper-2.08.tar.gz.

However, ActivePerl includes the Perl Package Manager (PPM), a utility that allows you to install modules, including modules that contain binary extensions. You should consider using PPM to install a module, as this greatly simplifies the management of modules.

Nevertheless, there are times when it is necessary to build a module from source. Typically, an installation session goes something like this:

1. Extract the module. This creates a directory based on the name of the archive.

           gzip -d -c Data-Dumper-2.08.tar.gz | tar xvf -

2. Change directory to the module's directory.

           cd Data-Dumper-2.08

3. Consult the README file.

           more < README

4. Run the Makefile.PL script. This uses the MakeMaker module to build a makefile you can build the extension with.

           perl Makefile.PL

5. Run your make utility. This prepares the module for installation, and compiles any extension if one is present.

           nmake

6. If this module has tests, run them.

           nmake test

7. If the tests succeeded, install the module.

           nmake install

See Where can I find Win32 ports of UNIX tools? for information on the availability of tools like gzip and tar.

## Where do I get make for Win32?

Nmake is a 'make' like program for Win32 systems by Microsoft. It is included in several Microsoft development tools (such as VisualStudio for .NET) and it is included in the Shared Source Common Language Infrastructure 1.0 Release.

## How do I access databases from my Perl script?

### DBI

  DBI, a Database Interface Module for Perl provides a consistent interface for database application development. DBI supports ODBC drivers as well as the native APIs of certain databases, including Oracle. The DBI home page is located at:

          http://dbi.perl.org/

### ADO

  The ActiveX Data Objects (ADO) API can be used with the Win32::OLE module. You can use ADO to access any ODBC data source.

  The ADO home page is located at:

          http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ado270/htm/dasdkadooverview.asp

### Win32::ODBC

  There are a couple of extensions that have been developed to access databases from ActivePerl. Win32::ODBC is widely popular, and is available on CPAN and at this URL:

          http://www.roth.net/perl/odbc/

### Sybase

  The Sybperl module allows you to connect to Sybase SQL Server (and possibly Microsoft SQL Server). The Sybperl home page, which includes links to binary releases of Sybperl, is located at:

          http://www.peppler.org/freeware/sybperl.html

If you choose to use a database API that depends on ODBC, you must have an ODBC driver for the DBMS you're using. You will need to configure a data source for that driver on each machine that needs to access the database. For more information on ODBC and how to configure a data source, check the ODBC Control Panel help.

Some DBMSes, such as Microsoft Access and Microsoft SQL Server, can be controlled through OLE Automation (see the next question). See the product documentation for details.

## Is there a way to use OLE Automation servers from my Perl script?

Yes. See the documentation for the Win32::OLE module, which is included with Perl. You can use Win32::OLE to control a wide range of Win32 applications and APIs, including ADO.

After reading the documentation, you can read the FAQ on using OLE.

## Is there a way to access Data Access Objects (DAO) from my Perl script?

You should use Win32::OLE to access this API. See question Is there a way to use OLE Automation servers from my Perl script? and consult the DAO documentation.

## Can I send Internet mail from ActivePerl?

If you need to send Internet mail, you should use Net::SMTP, Mail::Sender, or Mail::Sendmail. For more information on these modules, see How do I send email from ActivePerl?.

## Is there a way to access MAPI from my Perl script?

You can use the Win32::OLE module to create an instance of a MAPI session and send a message. In order for this to work, you must have messaging configured correctly on your machine. If you are using Microsoft Exchange, chances are this will work fine.

If you need to send Internet mail, you should use Net::SMTP. For more information on Net::SMTP, see How do I send email from ActivePerl?. Here is an example script that sends mail using MAPI:

        # Sender's Name and Password
        #
        my $sender = "YOUR NAME HERE";
        my $passwd = "YOUR PASSWORD HERE";

        # Create a new MAPI Session
        #
        use Win32::OLE;
        $session = Win32::OLE->new("MAPI.Session")
            or die "Could not create a new MAPI Session: $!";

        # Attempt to log on.
        #
        my $err = $session->Logon($sender, $passwd);
        if ($err) {
            die "Logon failed: $!";
        }

        # Add a new message to the Outbox.
        #
        $msg = $session->Outbox->Messages->Add();

        # Add the recipient.
        #
        $rcpt = $msg->Recipients->Add();
        $rcpt->{Name} = "RECIPIENT NAME HERE";
        $rcpt->Resolve();

        # Create a subject and a body.
        #
        $msg->{Subject} = "Test Message";
        $msg->{Text} = <<EOF;
        This is a sample test message.

        Cheers,

        Mr. Email

        EOF

        # Send the message and log off.
        #
        $msg->Update();
        $msg->Send(0, 0, 0);
        $session->Logoff();

## Is there a DBM implementation available for ActivePerl?

Yes, there is. SDBM_File is a free clone of DBM, and is implemented and distributed with the ActivePerl distribution. You can use it as follows:

        use SDBM_File;
        use Fcntl;

        tie( %myhash, "SDBM_File", 'myfile', O_RDWR | O_CREAT | O_BINARY, 0666 )
            or die( "Can't tie: $!" );

        $myhash{"bibim"} = "bap";

        untie( %myhash );

After the DBM file is tied, you can use it just like any other hash.

## Is there a way to do GUI programming with ActivePerl?

As of the Perl Resource Kit for Win32, the Tk library has been successfully ported to ActivePerl. Tk version 8xx and above also now has the look and feel of Windows programs, and not the old UNIX look of previous versions.

You can also use the Win32::GUI module which also allows for GUI's to be made/manipulated using Perl. This module uses the standard Windows widgets to give the look and feel of Windows programs.

For Perl Tk information, go to http://www.perltk.org/

For Win32::GUI, go to http://dada.perl.it

`Win32::MsgBox` allows for a fast and easy way to display a Windows message box, for example:

> `use Win32;
> MsgBox("Test", "This is a test", 48);
> # display a message box with an exclamation mark and an 'Ok' button
> sub MsgBox {
> my ($caption, $message, $icon_buttons) = @_;
> my @return = qw/- Ok Cancel Abort Retry Ignore Yes No/;
> my $result = Win32::MsgBox($message, $icon_buttons, $caption);
> return $return[$result];
> }`

The last value, $icon_buttons, is the sum of two values, the value for the icon and the value for the buttons. For example, if you need a message box with a question mark and the 'Ok' and 'Cancel' buttons the value you want is 32 (question mark) + 1 (Ok, Cancel) = 39. The values are listed here:

> `Icons:
> 0 - no icon
> 16 - Hand
> 32 - Question
> 48 - Exclamation
> 64 - Asterisk
> Buttons:
> 0 - Ok
> 1 - Ok, Cancel
> 2 - Abort, Retry, Ignore
> 3 - Yes, No, Cancel
> 4 - Yes, No
> 5 - Retry, Cancel`

## Is there a port of Oraperl for Win32?

Oraperl is available as an emulation layer on top of DBD::Oracle. Oraperl is included with the DBD::Oracle distribution. Because the DBI interface is evolving, the Oraperl emulation layer is recommended because its API is fairly stable. Patches are available for DBD::Oracle that allow it to build on Windows. More information is available at:

       http://search.cpan.org/~pythian/DBD-Oracle-1.19/Oraperl.pm

## What modules come with the ActivePerl distribution?

Along with the standard library files, there are several Win32-specific modules that are distributed with ActivePerl. These include:

- Win32::Clipboard: Perl module for Windows clipboard interaction
- Win32::Console: Perl module for Windows console interaction
- Win32::ChangeNotification: Create and use ChangeNotification objects
- Win32::Event: Use Win32 event objects from Perl
- Win32::EventLog: Read from and write to the Windows NT event log
- Win32::File: Manage file attributes (read only, system, hidden...)
- Win32::FileSecurity: manage ACLs in Perl
- Win32::Internet: Perl module for Internet extensions
- Win32::IPC: Wait for objects (processes, mutexes, semaphores)
- Win32::Mutex: Create and use mutexes
- Win32::NetAdmin: Administer users and groups
- Win32::NetResource: Manage resources (servers, file shares, printers)
- Win32::ODBC: work with ODBC data sources
- Win32::OLE: Use OLE automation from Perl
- Win32::Pipe: Perl module for pipes
- Win32::Process: Start and stop Win32 processes
- Win32::Registry: Read and manage the Win32 Registry
- Win32::Semaphore: Create and use semaphores
- Win32::Service: Manage Windows NT services
- Win32::Shortcut: Perl module for shell link interface
- Win32::WinError: For retrieving Win32-defined errors

These are documented on the Win32mod documentation page. There are also a number of subs built into the Win32 package, namely:

- AbortSystemShutdown: I mean, don't shut down this computer
- DomainName: Name of the domain this machine is in
- ExpandEnvironmentStrings: Take a string like %HOMEPATH% and expand it to the actual value
- FormatMessage: Format a Win32 error code into a error message
- FsType: Get the file system type of a drive
- GetCwd: Get current working directory
- GetLastError: Retrieve the last Win32 error code.
- GetNextAvailDrive: Returns the next available drive letter
- GetOSVersion: Get Win32 operating system version
- GetShortPathName: Returns the 8.3 name of a filename
- GetTickCount: Time since Windows started, in milliseconds (for timing)
- InitiateSystemShutdown: Shut down this computer
- IsWinNT: Is this Windows NT?
- IsWin95: Or, is it Windows 95?
- LoginName: Name of logged-in user
- LookupAccountName: Given a user name, get domain, SID, SID type
- LookupAccountSID: Given a SID, get domain, user name, SID type
- NodeName: Name of this machine
- SetCwd: Set current working directory
- Sleep: Sleep for a given number of milliseconds
- Spawn: Spawn a Win32 process
- ExpandEnvironmentStrings: Take a string like %HOMEPATH% and expand it to the actual value

No longer included in the Win32 module:

- PerlVersion: Use $] instead
- GetArchName: Use $ENV{PROCESSOR_ARCHITECTURE}
- GetChipName: Use $ENV{PROCESSOR_LEVEL} . $ENV{PROCESSOR_ARCHITECTURE}

## Where can I find other modules for ActivePerl?

Modules for ActivePerl are available on CPAN (Comprehensive Perl Archive Network), a Perl archive that's mirrored around the world. To find your nearest mirror, check here:

        http://mirrors.cpan.org/

(Note that this will send you to your nearest mirror automagically. Cool, huh?)

## What is CPAN and how do I use it?

CPAN is the Comprehensive Perl Archive Network, a collection of pretty much every file you could ever want for Perl programming. The original archive is in Finland, but it is mirrored on FTP servers throughout the world.

You can connect to your closest CPAN mirror using the CPAN redirector at http://www.perl.com. The following URL:

        http://www.perl.com/CPAN/

will redirect your browser to the nearest CPAN mirror (one on your continent and maybe only a few hops away). This URL

        http://mirrors.cpan.org/

lets you pick a CPAN mirror site yourself, as well as giving a little more information.

CPAN is good for finding ActivePerl distributions as well as modules and scripts. However, read

        How can I use modules from CPAN?

for more information.

## Is there a library to read or write Microsoft Office or other application files?

In general, there aren't any library modules to read or write application files, like Microsoft Word, Microsoft Excel, Microsoft Access, WordPerfect, Lotus 1-2-3, etc.

However, many if not most major Windows applications now support OLE Automation. You can use the OLE Automation support of Microsoft Office applications to read and write their file formats, for example. See the documentation on your application for information on its support for OLE Automation. See Is there a way to use OLE Automation servers from my Perl script? for more information.

As a special case, many database files, like Microsoft Access, FoxPro, dBase or Paradox files, can be accessed using ODBC (Open DataBase Connectivity). See How do I access databases from my Perl script? for details on how to use ODBC with ActivePerl.

## AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove and David Dmytryshyn of ActiveState, Henning Michael Møller-Nielsen of RTO, Kevin Meltzer and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

### ActivePerl FAQ - Modules and sample scripts