Getting Started with Perl Builder 2.0

© Solutionsoft, 1998-200, All Rights Reserved.

Perl Builder is a trademark of Solutionsoft.
All other product names are trademarks of their respective owners.

This document may be viewed and printed using Microsoft Word, WordPad (under the Windows 95/NT Accessories menu), or any other application which supports Rich Text Format (RTF). 

Table of Contents

Introduction	
What's new in Version 2.0	
Installation	
Other Documentation Resources (available under the Help menu)	
An Introduction to Perl	
An Introduction to CGI	
An Overview of Perl Builder	
Chapter 1: Creating CGI Scripts without Programming	
An Overview of the CGI Wizard	
Basic Steps in Creating a Form Processing Script	
Creating HTML Forms	
Using the CGI Wizard	
Creating Dynamic HTML Output in your HTML Editor	
Testing your Script in the IDE	
Getting Ready to Move your Script to the Webserver	
Moving your Script to the Server	
Troubleshooting Problems on the Server	
Learning to Program in Perl	
Chapter 2: Perl Builder for Experienced Developers	
Introduction to the IDE	
Working with Multiple Files in the IDE	
Customizing and Extending Perl Builder	
Using Perl Builder with Perl's Command Line Tools	

Introduction

Welcome to Perl Builder: the first integrated development environment (IDE) for the Perl programming language.

Perl Builder is designed to be useful to people with a wide range of skill levels. If you are an experienced Perl developer, Perl Builder's powerful IDE and advanced debugging features will help you to rapidly develop, debug and test your scripts. On the other hand, if you are an HTML author without a programming background, or if you are just getting started with Perl, Perl Builder will allow you to create powerful scripts visually--without the need to write code. 

Perl Builder Version 2.0 is a major upgrade with dozens of new features and refinements, based directly on feedback from the thousands of people who have used version 1.0. 

How to Use this Manual

•	If you are a non-programmer, or if you are just getting started with Perl or CGI programming, we suggest you read the rest of this introductory chapter and also Chapter 1: Creating CGI Scripts without Programming. This will give you a brief introduction to Perl and CGI and will take you through the basic steps involved in creating a CGI script using Perl Builder.  

•	If you are an experienced Perl programmer, we suggest you read the Other Documentation Resources and An Overview of Perl Builder sections of this introductory chapter and also Chapter 2: Perl Builder for Experienced Developers. This chapter summarizes some important information for developers who are already familiar with Perl and will help you to quickly get the most out of Perl Builder.

What's new in Version 2.0

Perl Builder 2.0 includes a number of new features and also addresses most of the limitations present in version 1.0.  

Perl Builder 2.0 is available in two versions: The standard version provides a cost-effective solution for both programmers and non-programmers who wish to create Perl CGI scripts.  The professional version includes a number of enhancements and advanced time-saving features which are geared toward serious Perl developers who place a high value on their time. 

The professional version also includes support for the Linux operating system. The standard version is available only on Windows.

New Features (both standard and professional versions)

Redesigned and enhanced editor provides a powerful environment for serious Perl developers:

•	Unlimited undo/redo levels.
•	Improved performance/speed.
•	Improved color syntax highlighting lets you use bold/italic as well as colors for specific syntax elements.
•	Control over the background color.
•	Direct control over keyboard shortcut assignments for editor functions.
•	Find All and highlight feature.
•	Improved printing, including printing in color and printing only the selected text.
	
•	Copy as HTML or RTF and paste highlighted text in color into other applications such as MS Word or HTML editors.
•	Glitches in display, scrolling, etc. that some V 1.0 users experienced have been eliminated.

Improved navigation and online help:

•	Subroutine navigator makes it easy to jump directly to any subroutine in the current module.
•	Improved bookmark system.
•	Context sensitive help for built-in Perl functions (just click a Perl function name in your code and press F1).

New Debugging Engine
	
•	Faster and higher fidelity.
•	Supports interactive I/O and Perl TK. The new interactive I/O window also allows you to view HTML/Text output as you debug, without having to switch to the HTML/Text Output tab.
•	Includes all standard debugging features.
•	New "Dump" feature in the Evaluate/Modify command displays complex/nested data.
•	Pause button lets you stop run-away scripts/infinite loops.
•	Execution directory for scripts can be specified.
•	Customizable HTML color syntax highlighting in the output window.

Improved CGI Wizard
	
•	Enhanced validation options.
•	Support for saving data in a text file on the server.

New Features (Professional Version Only)

•	Open multiple main scripts in the IDE and select the active script for debugging. (The standard version allows only one main script to be open at a time. However both versions support opening modules/libraries).
•	Debug complex CGI scripts directly in your browser-without the need for a webserver on your PC.
•	Enhanced support for debugging "daisy chained" scripts--where output from a script includes a form which calls the same or another script.
•	Code templates let you save snippets of code which can later be inserted with a hotkey or menu.
•	AutoReplace/AutoCorrect lets you specify strings so that the editor automatically corrects errors or replaces abbreviations with the full text.
•	Built-in performance timing tools help you optimize your scripts.
•	Pod Viewer lets you view pod documentation which is embedded in a module in a floating window. The Pod viewer formats the text and provides a table of contents for navigation. 
•	Mouse-over bracket matching. Just place the cursor over any bracket {} to highlight its partner.

Installation
Windows 9x/NT/2000
To make full use of the software, you will need to install both Perl Builder 2.0 and the Windows 9x/NT/2000 version of Perl. 
1.	Download and install Perl for Windows 95/NT. Perl is a free download; you can find links to the software at http://www.solutionsoft.com/getperl.htm. 
2.	Install Perl Builder by running the installation program.
Linux
To install the Linux version of Perl Builder 2.0 Professional, please follow the instructions in the Readme.txt file.

Other Documentation Resources (available under the Help menu)

This manual is intended to be only a brief introduction. For more comprehensive documentation, please refer to the following resources (all are available under Perl Builder's Help menu.)

•	The Perl Builder Online Help  The online help includes information on all Perl Builder features. You can also access the online help by clicking the Help button or pressing F1 in any Perl Builder dialog box.

•	The Perl Builder FAQ (Frequently Asked Questions) The FAQ contains answers to most common questions about Perl Builder.

•	The Perl Language Documentation Two menu items are provided: one for local documentation and one for documentation on the internet. 

•	Perl FAQs and Resources This item displays a web page with links to Perl related information and resources on the Web. You'll find the Perl FAQs, as well as links to Perl related newsgroups where you can post questions, and other resources such as books and online tutorials for Perl.

An Introduction to Perl

"PERL" is an acronym which stands for Practical Extraction and Reporting Language. Perl was created in 1987 by Larry Wall, a Unix programmer. Larry made Perl available as freeware, and Perl quickly became popular among Unix programmers and system administrators.

Perl is designed so that people can quickly write programs without having to worry about many of the details which make programming with other languages (such as C, C++ and Pascal) more difficult and time consuming. In addition, Perl includes special features which are geared toward manipulating and searching for information in text format. As a result, Perl is arguably the fastest and easiest way to create a program which needs to process lots of text.

When the internet exploded in popularity, website developers found that Perl was freely available and ideally suited to writing CGI programs (programs which run on webservers). Perl is now far and away the most popular language for CGI programming. Any time you visit a website which includes dynamic features like the ability to search for information, send email messages, or keep track of user information in a database, there is an excellent chance that a Perl program is working behind the scenes to make these features possible. 

While Perl has become the dominant language for CGI programming, it is important to note that this is certainly not the only use for the language. Perl was popular among Unix users long before the web became a household word and is increasingly being used for a variety of  purposes on the Microsoft Windows platform. Perl is a general purpose language which can be used for almost any task, and is especially suited for any application which requires significant text processing. 

An Introduction to CGI

CGI stands for the "Common Gateway Interface." This is basically a set of instructions which describe the way that programs running on a webserver can communicate with an internet user's browser. When  you fill in a form on a website and then click the Submit button, the information is passed to a program running on the server according to the CGI standard.

It is important to note that CGI is not specific to any programming language; it simply describes the way information is made available to programs running on a webserver. As noted above, Perl is the most popular language for creating CGI programs. However, many other languages are also used. Examples include C/C++, tcl, and Python. 

An Overview of Perl Builder

Perl Builder provides a complete set of tools which make it easy to create, debug and test Perl scripts.  Because CGI programming is such an important application for Perl, Perl Builder includes a number of features which will help you to create and test CGI scripts. However, it is important to note that Perl Builder can also be used to develop Perl programs for other purposes.

Here is a brief look at some of the most important features in Perl Builder:

The CGI Wizard

The CGI Wizard is a tool which allows you to create CGI scripts without programming. To use the CGI Wizard, you start with an HTML form and then use the wizard panels to specify options for your script. 

The CGI Wizard is designed so that it can be used by people without a programming background. However, experienced programmers may also find the wizard useful as way to quickly generate and update code. Chapter 2 of this manual covers the CGI Wizard in more detail.

The Ability to Test your Scripts on the Desktop 

One of the most important features in Perl Builder is the ability to run your Perl script within the integrated development environment (IDE) and see the results immediately. This is especially significant for CGI scripts, because testing and debugging these scripts can often be difficult.

If you have used an HTML authoring tool like Microsoft Front Page, you are probably used to creating web pages and immediately previewing them in your browser. This ability to preview the pages on your computer saves a lot of time; you typically move the HTML pages to your webserver only after they have been carefully edited and tested on the desktop.

With CGI scripts, the situation is more complicated. Because CGI is integrated into the server, you can only test a CGI script on a webserver. So unless you have installed and configured a webserver on your desktop computer, you can't use your browser to test a script on your local drive.

For this reason, CGI scripts are typically tested and debugged directly on the server. However, this can be a difficult and confusing process, especially if you are not an experienced CGI developer or webmaster. In particular, finding and fixing problems in your scripts can be very difficult.

Perl Builder addresses these problems by simulating CGI on the desktop. When you run a CGI script in Perl Builder, it works in the same way it would if it were running on a webserver. You can see the output right away and display it in your web browser--in much the same way that you would preview a static HTML page. This allows you to find and fix any problems in your script before you move it to the server. 

Integrated Editor/Debugger

Perl Builder provides a visual editor/debugger which is similar to other Microsoft Windows programming tools like Visual Basic or Delphi. The editor includes features like color syntax highlighting which make it easier to write and understand your code. 

The integrated debugger makes it easy to set breakpoints, single step through code and inspect the values of variables in your script. These features--especially when combined with Perl Builder's ability to simulate CGI--make it much easier to find problems in your code.

Chapter 3 of this manual summarizes some important information that will help programmers to take full advantage of these features.

Chapter 1: Creating CGI Scripts without Programming 

This chapter focuses primarily on the CGI Wizard, a tool which allows you to create CGI scripts without writing code. 

In order to understand this chapter, you must have an understanding of how to create HTML files, and in particular HTML forms. If you are not familiar with HTML forms, please consult your HTML editor's documentation or a book on HTML before attempting to use Perl Builder. 

An Overview of the CGI Wizard

While CGI scripts can be written to perform a variety of tasks, the most common and basic need they fulfill is processing the information which users enter into HTML forms.  Perl Builder's CGI Wizard allows you to create powerful form processing scripts with an easy-to-use wizard interface. 

The CGI Wizard is capable of automatically generating scripts which do any or all of the following:

•	Read the input values submitted by a user through an HTML form.

•	Validate the user's inputs. In other words, check to make sure certain fields are filled in correctly, and if not, ask the user to try again.
	
•	Write the data collected from the user to a text log file on your server. This file can be in tab or comma delimited format. This makes it very easy for you to import you data into other applications such as spreadsheets, databases, etc.

•	Send automated email messages. This might include sending the information the user enters to the webmaster and/or sending an automatic acknowledgment or thank you letter to the user.

•	Display HTML output to the user. The output displayed can be generated dynamically by the Perl script and can be customized based on the information entered by the user. Alternatively, you can simply redirect the user to an existing HTML page on your website. 

The basic capabilities listed above will allow you to create CGI scripts to process most online forms without programming. If you know how to program in Perl, or if you are willing to learn, you can also extend the CGI Wizard's basic functions by adding your own code.  

Basic Steps in Creating a Form Processing Script

To create a script to process your form and get it working on your webserver you will need to complete the following basic steps. We'll look at these steps in more detail in subsequent sections of this chapter.

1.	Create your HTML form. You should finalize the design of your form before using Perl Builder to generate the processing script.

2.	Start Perl Builder, create a new script, and invoke the CGI Wizard.

3.	Select your form in Panel 1 of the CGI Wizard.

4.	Use the remaining Wizard panels to define the behavior of your script, and then click the Finish button to generate the Perl code.

5.	Test your script within Perl Builder's IDE. This will allow you to enter sample inputs and view the output. You may need to return to the CGI Wizard to correct any problems you discover.

6.	Once your script works correctly with Perl Builder, you will need to upload it and the associated HTML form your server and set the proper file permissions.

7.	Test your script on your server using your browser.

Creating HTML Forms

Your HTML Editor probably has features to help you create HTML forms. We assume here that you are familiar with forms; if not, please consult your editor's documentation or a book on HTML. If you are using Microsoft Front Page, please also see the note below.

Perl Builder does not place any restrictions on the design of your forms; however, the following guidelines will make it easier to use the CGI Wizard:

•	Use meaningful field names. The field names are used within the Wizard panels, so use names like "EMAIL" or "lastname". If you are using a WYSIWYG editor like Front Page, the editor may create meaningless default names like "T2" for "field3" whenever you insert a new field. You should change these before using the CGI Wizard.

Note that the field name is part of the HTML tag for the field, not the visible "label" next to the field. In the example below, the field name is "FNAME".

<input type="text" size="20" name="FNAME">

Note: Fields names must begin with a letter in order to work with Perl Builder. Something like name="3" will cause an error when you try to run your script.

•	Make sure you note the name of the script in the <FORM> tag. Later, when you create your script, the file name will have to match this.
For example, if the form tag might looks like: <FORM ACTION="myscript.cgi">  You will need to name your script myscript.cgi. 

•	Perl Builder will process only the first form in each HTML file, so if you need to create scripts to process multiple forms on a single page, you need to first place each form in a separate file. The separate files are only necessary for use with Perl Builder, you can still have the forms on the same page on your webserver.

Using Microsoft Front Page

By default, Front Page will assume that you want your form to be processed by one of its "WebBots," rather than your own CGI script. To change this behavior, you'll need to follow these steps:

1.	Create your form in the normal fashion. Be sure to use meaningful field names as noted above.

2.	Right click within the form and select Form Properties from the right mouse button context menu.

3.	Under "What to do with form results", choose the Send to Other radio button.

4.	Choose "Custom ISAPI, NSAPI, CGI or ASP Script" from the drop down list.

5.	Click the Options button.

6.	Fill in the name and path of your script under Action. For example: http://www.mysite.com/cgi-bin/myscript.cgi. You will need to check with your webmaster or ISP to find out where your script will be installed on the webserver. See Gettting Ready to Move your Script to Your Webserver later in this chapter for more information. 

7.	Under Method, choose Post. Then click Ok twice to confirm your choices.

Using the CGI Wizard

The best way to introduce yourself to the CGI wizard is to complete the Perl Builder tutorial. To access this, choose "Tutorial" from Perl Builder's Help menu. The tutorial will walk you through the basic steps involved in using the wizard. 

The basic steps in creating a new script with the CGI Wizard are as follows:

1.	Start Perl Builder and choose New Script to start a new script.

2.	Click the CGI Wizard icon on the toolbar or choose CGI Wizard from the Tools menu. The Wizard will appear.

3.	Click the Select >> button and choose the HTML form you want to process.

4.	Use the remaining 4 panels to specify field validation, writing to a text log file, email messages and HTML output. Each panel of the Wizard has a Help button which will take you to specific instructions. 

5.	Click the Finish button to generate your code.

Creating Dynamic HTML Output in your HTML Editor

In panels 2 and 4 of the wizard, you can specify a "model" page which the Wizard will use to generate Perl code which creates dynamic HTML output. The advantage of using dynamic HTML which is created "on the fly" is that the output can be customized for each user. For example, you can use some or all of the information entered by the user in the output. There is an example of this in the Perl Builder tutorial.

Perl Builder allows you to use any HTML Editor to create dynamic HTML Output. To do this you simply create a "model" HTML page in your editor and then specify this page in Panel 4 of the Wizard.

You "merge" script variables into the model page by including a reference to the variable in square brackets, as in [$EMAIL]. Make sure you use square brackets [ ] and that the variable name starts with a dollar sign, $. 

At runtime, when the user enters information and submits the form, the field reference will be replaced with live data. If you have ever printed mailing labels or designed a form for a database, then the idea of merging fields in this way is familiar to you.

The CGI Wizard automatically creates variables which are based on the field names in your form. However, you can also merge variables which you define with custom code in your script.

The Field Pallet

It is very important that the field references in your HTML page match the variable names in your script exactly. This includes upper and lower case.

To help with this, Perl Builder provides the Field Palette--a tool which allows you to easily enter field references without typing. 

To Enter Field References

1.	If you have not done it already, start the CGI Wizard and select your form in Panel 1. This will read the input fields in your form. Click either Close or Finish to put the Wizard away.

2.	From Perl Builder's Tools menu, choose Field Palette. The Field Palette will appear.

3.	Start your HTML Editor and open your model HTML page. The Field Palette will float on top of your editor.

4.	Double clicking a field name in the palette (or selecting it and clicking the Copy icon) copies the field reference to the clipboard.

5.	After copying a field reference, use your editor's paste function (or CNTR+V) to paste the reference into the HTML page.

Note

If you are creating a model page for the validation error messages specified in Panel 2 of the Wizard, the only field reference you will be working with is [$message]. This special field reference will be replaced with the error message lines generated by your script.

Testing your Script in the IDE

Once you have used the CGI Wizard to create your script, you can test it within Perl Builder. This will allow you to catch and fix problems before moving your script to the server.

Note

To test your script, you must first download and install Perl for Windows 95/NT. If you haven't already done this, visit the page http://www.solutionsoft.com/getperl.htm for download links.

To test your script

1.	Click the Input Values tab in the Perl Builder IDE and enter test values in the simulated form. You should try entering both valid and invalid data, try leaving required fields blank, etc., so that you completely test your script. Note that the layout of the Input Values tab may be somewhat different from the original HTML form. Click the Help button for more information on this. 

2.	Click the Run icon on the toolbar or choose Run/Continue from the Run/Debug menu. Your script will run and output will appear in Perl Builder's output tabs.

3.	Check the Output: HTML/Text tab to see dynamic HTML output. You can view this in your browser by clicking the button at the bottom of the screen.

4.	Check the Output: MAIL tab to see any email messages sent by your script. 

If there are problems

If you find problems in the design of your script, for example the HTML output is not as you would like or you forgot to validate a particular field, you can simply re-invoke the CGI Wizard. Everything you entered previously will be there and available to be edited. To update your script, simply click the Finish button. 

Getting Ready to Move your Script to the Webserver

Once your script runs correctly within Perl Builder, it is time to move it to your webserver for final testing. In some cases, this can be a little tricky. Unfortunately we cannot offer a "one size fits all" solution because the configuration of webservers varies widely. In order to make sure your script will work on your server, you will need to get some information from your webmaster/ISP and perhaps make a few minor changes.  

To get your script running you will need to complete these basic steps (we'll cover each step in more detail later).

1.	Check to be sure any system specific elements in your script (such as the location of the mail program) are correct for your server. See the information below for details on this.

2.	Move both the script and the HTML form to the server (for example, by using FTP). 

3.	Set the file permissions for the script. This step gives your script "execute" permission so that the system knows it is a program which it should run. 

4.	Test the HTML form and your script using your browser.

If this is your first time installing a CGI script on your server, we strongly recommend that you first begin by obtaining and installing a script which is known to work. If your website is hosted by a third party ISP or Host company, they will nearly always have a FAQ/Information Center which gives details on how to install CGI scripts on the system. They also are likely to have several sample or generic Perl scripts which work on their server. 

Obtain one of these scripts and follow the instructions for getting it to work. If you run into problems, you will need to contact their support department for help. You will get a much better response if you are using a script which is known to work because this eliminates the possibility that there is a problem with the script itself. 

Once you have successfully installed and tested the working script, you can then move on to your own scripts with confidence that you understand the installation procedure correctly.

Information you will need from your Webmaster or ISP/WebHost Company
1.	First, make sure that you are allowed to run CGI scripts. If you have a basic account with an ISP/WebHost company, CGI may or may not be included. If not, you will need to change companies or upgrade your account.
2.	Find out the correct location to install CGI scripts. Most often, this is in the "cgi-bin" directory, but this varies widely. With some providers, you may simply install the script in your /public_html directory or in some other location. 
3.	Verify system specific information in the script. This includes initialization lines at the top of the script and the location of the mail program. See below for details on how to do this.

Modifying your Script to work on your Server
When generating code, the CGI Wizard uses the most common defaults for Unix webservers. If you are lucky, your script will run unchanged on your server. If not, you may need to make some minor changes so the script will work properly.
The easiest way to determine whether or not you need to change anything is to look at a working script from your webmaster or ISP (see the note at the beginning of this section.).

Look for the following:

The first line of the script:   
  
#!/usr/local/bin/perl

This line tells the system where to find the Perl interpreter. On Unix systems, it nearly always appears as shown above. Check it against your working script to make sure it matches.

Other initialization lines (usually lines 2-3)

push (@INC, '/cgi-bin');

In some cases, your working script may contain a line near the top of the script that looks something like the one above. Instead of "push" the line might use the command "unshift" or "use lib". 

If your working script has a line like this, copy it to the same location in the script created with Perl Builder. 

Mail Program Location

The mail program (usually sendmail on Unix systems) is the utility which enables your script to send email messages. This location must be correct in order for your script to send messages.

The default location generated by Perl Builder looks like this:

$mail_prog = '/usr/lib/sendmail' ;

Look for a line in your working script which looks similar to this. If you can't find it, you will need to contact your webmaster/ISP and ask them for the location. To do this, simply copy the line above into an email message and ask if it is correct for your system.

Important note on NT Servers

Perl Builder is set up to assume a Unix server running Sendmail. Unlike Unix, where Sendmail is a standard, NT has a variety of email applications and Perl Builder does not support these directly.

If you are using NT, you will need to obtain a working Perl script which properly send email on your system. Then modify the output from Perl Builder's CGI to conform to this working script.

Changing the CGI Wizard defaults

If you need to change the first line of your script or the mail program location, you can just type or paste the change directly in the Perl Builder editor. However, if you do this, you will need to make the change every time you use the CGI Wizard to create a script.

As an alternative, you can change the defaults by choosing Options from the Tools menu and clicking the CGI Wizard tab. Paste the correct information into the dialog box and click OK. 

Moving your Script to the Server

Once you have verified that your script works properly in the Perl Builder IDE and you have made any necessary changes so that the script will work on your system, you are ready to actually move the script to your server and test it.

Your webmaster or ISP may have provided specific instructions for installing a CGI script on the server. If so, you should follow those instructions. However, the generic steps below should work in most cases.

1.	Double check that ACTION specified in the <FORM> tag matches your script name and that the path is correct. The script name must match exactly, including upper/lower case. Also the path must be correct. It may be either a complete path as in, ACTION="http://www.mysite.com/cgi-bin/myscript.cgi", or a relative path as in ACTION="../cgi-bin/myscript.cgi". Be careful that this path is correct, especially if you have used a relative path. Again, the best way to be sure is to check the working script you obtained from your webmaster/ISP.

2.	Move the both the script and the HTML form to the server. These files may need to go in different locations. For example, the HTML form may go in /public_html and the script in /cgi-bin. If you use an FTP utility to move the files, make certain that the transfer type is set to "ASCII" when you upload the script. If it is set to "binary", the script will fail on the server.

3.	Set the file permissions. On Unix systems you will use the chmod command for this. Generally, you will use commands which look like the following:

	cd cgi-bin
	chmod 755 *.cgi

If you script writes data to a text log file, you will also need to create that file and set its 
permissions:

touch log.txt
chmod 660 log.txt
	
Note that in order to execute these commands, you may need to telnet into your server. If you are not familiar with telnet or how to log onto your account, please contact your webmaster or ISP/WebHost company for help. Usually this information is provided to you when you sign up for a new account with ISPs.

4.	Your script should now be installed correctly. Test the form in your web browser. 

Troubleshooting Problems on the Server

If your script works in Perl Builder but not on the server, check the list below to see if you can identify your problem. If you still can't get it to work, contact your ISP's support department or your webmaster for help.

Your browser reports that it cannot find or open your script or that you don't have permission to run the script

Check that:

•	You uploaded your script to the correct place on the server.

•	The <Form> tag has the correct script name and path in the "action=" setting. 

•	You set the permission for the script using "chmod 755 myscript.cgi."

Your browser reports an error or says "Document contains no Data"

•	If you used an FTP utility, make sure you uploaded your script using ASCII transfer type (not binary).

•	Make sure there are no syntax errors in your script (re-run within Perl Builder).

•	Double check the initialization lines of your script and make sure they match the working script you obtained from your webmaster or ISP.
	
	Your script does not write to the log file
	
	Check that you have created the log file on your server (most likely in the same directly as your script) and set the permissions (chmod 660 log.txt). You script cannot create the log file for you on the server (even though it does so when you run the script in Perl Builder) because it does not have write access to this directory.

Your script does not send email messages

•	Check the location of the mail program $mail_prog, to make sure it matches the working script you obtained from your webmaster or ISP.

•	Double check the initialization lines of your script and make sure they match the working script you obtained from your webmaster or ISP.
	
•	If you are using NT, the script will probably not work as generated by the CGI Wizard. You will need to get a working script and modify the output from the CGI Wizard accordingly.

Learning to Program in Perl

This chapter has discussed how to use Perl Builder's CGI Wizard to create scripts without programming. If you would like to take the next step and learn how to program in Perl, a number of resources are available to help you do this:

•	Visit our Perl resources web page. You can access this by choosing Perl FAQs and Resources from Perl Builder's Help menu, or by directly visiting http://www.solutionsoft.com/perl_resources.htm. This page has links to the online tutorials, FAQs (frequently asked questions), newsgroups, and other resources to help you learn and use Perl.

•	Get a good book on Perl programming. Our Perl resources page (above) also has links to some books about Perl which we think are especially good. 

Chapter 2: Perl Builder for Experienced Developers

If you are an experienced Perl programmer, or if you are familiar with another programming language or environment like Visual Basic, Delphi, or C++, then this chapter is for you. We will present a very brief summary of some of the most important features in Perl Builder and also list some helpful hints that will allow you to set up the IDE to suite your personal preferences.

Perl Builder 2.0 offers a number of advanced features for Professional developers. Please see "using the "Professional Version Features" in the online help for details.

Again, this chapter is only a summary. For more comprehensive documentation, please see the Perl Builder online help.

Introduction to the IDE

If you have worked with other Windows programming IDEs (Visual Basic/C++, Delphi, etc), then Perl Builder's environment will probably seem quite familiar. If you have worked exclusively with command line tools, the brief summary below will help you get up to speed quickly.

Integrated/Editor Debugger

Perl Builder's debugging functions are integrated directly into the editor. You can set a breakpoint on any line simply by clicking in the gray left margin. The remaining debugging functions (watches, evaluate/modify, conditional breakpoints, etc.) are available under the Run/Debug menu or the right mouse button context menu (see below).

Frequently used commands are also available on the Perl Builder toolbar. To learn the function of a toolbar icon, hold the mouse over it for a few seconds; a brief description will appear. The icons are arranged in groups, with editing functions on the left and debugging functions on the right.

One very convenient feature which may not be familiar to you if you have not used other IDEs is "tool tip" variable inspection. This allows you to display the current value of any scalar variable simply by moving the mouse over the variable name in the editor. The value will appear in a small pop-up window.

If you discover a problem while debugging your code, you can fix it immediately in the editor. However, keep in mind that if you modify the text in the editor, this will reset the debugger, so that the next time you run your script you will be starting from the beginning. The current debugger status is displayed on the status bar.

Right Mouse Button Context Menu

The context menu includes the most often used editing and debugging commands. To access the context menu, right click anywhere in the editor window.

Some of the commands on the context menu refer to the cursor position (for example, Run to Cursor and Set Watch at Cursor). It is important to note that these commands refer to the editor "caret" -- not the position of the mouse pointer. 

For example, if you choose Set Watch at Cursor, Perl Builder will set a watch on the variable at the caret (if there is one). Note that this behavior is slightly different from Microsoft Visual C++ which bases these commands on the mouse pointer. With Perl Builder, you may need to click twice to set a watch or run to the cursor: first left click to move the editor caret; then right click to display the context menu.

IDE tabs

Perl Builder's IDE organizes its windows into tabs:

•	Your main script will always be displayed in the leftmost tab. With Perl Builder, your main script also plays the role of a project file or "workspace". See the section on opening multiple files in the IDE later on this chapter for details.
	
Note: If you have the Professional Version you can open multiple main scripts, so the main script will not always be in the left-most tab. You can activate a main script by using the Select Active Script command in the pop-up context menu. The active main script is indicated with an icon in the tab.

•	If you have any modules/libraries or related scripts open in the IDE, these will be displayed in tabs immediately to the right of the main script.

•	The Input Values tab is where you enter test data for your script. This tab can behave in two ways: If you are debugging a CGI script, Perl Builder can simulate an HTML form here. If you are working with a non-cgi script, choose the STDIN radio button at the top of the window and choose a file or paste the data into the window.

•	The Output: HTML/Text tab is where the standard output for your script appears. If the output is HTML, you can view it in your browser by clicking the button at the bottom of the screen. 

•	The Errors pane will appear  at the bottom of the screen only if your script generates Perl compiler errors or warnings. You can double click any error message line which specifies a line number to jump directly to the problem line in your script. 

•	The Output: MAIL tab is where email messages are displayed, provided that you used a file handle called MAIL in your Perl script.

You can move between the tabs in the IDE either with the mouse or by pressing cntr+tab or cntr+shift+tab.

Keyboard Commands

Many of the Perl Builder menu commands also have keyboard shortcuts. In addition, there are some commands which are available only from the keyboard. An example is bracket matching (searching for a matching bracket or brace).

To see a list of Perl Builder's keyboard commands, choose Keyboard Map from the Help menu.

The keyboard shortcuts for the debugging commands can be customized. See the Section on Customizing and Extending Perl Builder later in the chapter for details.

Bookmarks

Bookmarks allow you to mark specific points in your code for quick navigation. Perl Builder's bookmark commands are listed under the Edit menu. These commands also have keyboard shortcuts.

Working with Multiple Files in the IDE

Perl Builder allows you to open and debug multiple files in the IDE. For example, you can open a Perl module or library which is used by your main script and edit and debug it.

Opening and Closing Main Scripts

Use the File | Open Script or File | New Script commands to open or create a new main script. The main script always appears in the first tab in the IDE. 

Note: If you have the Professional Version you can open multiple main scripts, so the main script will not always be in the left-most tab. You can activate a main script by using the Select Active Script command in the pop-up context menu. The active main script is indicated with an icon in the tab.

Perl Builder maintains a project file for every main script you work with. The project file has the same name as the script, but a ".pbp" extension. The project file keeps track of various settings associated with your script. You can think of the main script as playing a similar role to a "makefile, " "workspace," or "project" in other development tools.   

Opening and Closing Modules, Libraries and Related Scripts

To open or create secondary scripts in the IDE, use the File | Open Module/Library or File | New Module/Library commands. Related scripts appear in tabs to the right of the main script and to the left of the Input Values tab.

You can use this command to open module or libraries which are specified with the "use" or "require" statements in your main script. You can edit the files, set breakpoints, inspect variables, etc. 

You can also use this command to open an unrelated script. For example, you might want to examine or copy the code in another script while you are working. If you do this, it is best to close the script after you finish or disable debugging for the file. Leaving scripts open in the IDE with debugging enabled does incur some performance overhead while you are debugging. You can disable debugging by clearing the checkbox for the file in the Module List (see below).

Using the Module List

Perl Builder keeps track of any modules, libraries or other related scripts you open while working with a particular main script and lists them in the Module List. You can access the Module List by choosing View Module List from the File menu. The Module List acts as a kind of informal project manager and  lets you quickly reopen the files associated with your main script. Double click a file in the Module List to open it in the IDE. You can also turn debugging on or off for specific files.  For details, search the online help for "Module List" or click the help icon in the Module List window.

Debugging Modules and Libraries

You can use all the normal debugging functions to work with modules and libraries in the IDE. However, you must open the file in the IDE before running your script. If a module or library is not open in the IDE, Perl Builder will step over it when debugging. 

Note that subroutines in a module or library will still be called and executed even if debugging is turned off for the file, or if the file is not open in the IDE.  However, if the file is not open with debugging enabled, you will not be able to set breakpoints or step into the file.

Opening or closing a related script resets the debugger so the next time you click Run/Continue you will be executing your script from the beginning. 

Customizing and Extending Perl Builder

Perl Builder is designed to work the way you work. The tips below will help you set up the environment so you can get the most out of it.

If you are familiar with another Windows IDE (such as Visual C++, Visual Basic, etc)

You can customize Perl Builder so that the debugging keyboard shortcuts and other items work in the way you are used to. To change these preferences, choose Options from the Tools menu and then click the Preferences tab.

If you prefer to use a stand-alone editor for some or all of your work

Perl Builder has features to help synchronize the IDE with your editor. To set this up, choose Options from the Tools menu and click the Locations tab. Also, please read the topic on Using an External Text Editor in the online help.

To change the colors used for syntax highlighting

Choose Editor Options and Colors from the Toold menu.

To add your own custom editing functions to Perl Builder

You can extend Perl Builder by writing editor scripts. To find out more about editor scripts, choose Script Manager from the Editor-scripts menu and then click the Help button.

Using Perl Builder with Perl's Command Line Tools

If you are an experienced Perl programmer, you are probably familiar with Perl's powerful command line debugger. It is important to note that installation and use of Perl Builder does not in any way impact Perl or the command line debugger. You can continue to use these tools in conjunction with Perl Builder if you wish.

Perl Builder acts just like a standard text editor as far as the command line tools are concerned. This means that, while your script is open in Perl Builder, you can open a console window and run or debug your script using the command line if you wish. This allows you to easily move between Perl Builder's visual environment and the command line as needed.