Feedback/TroubleShooting/Bug Reports
Feedback/Known Problems/Troubleshooting

Suggestions/Feedback/Technical Support

We are very interested in your feedback. If you have suggestions or if you encounter what you feel is a bug, please contact us by email at perl@solutionsoft.com. Please use this special Perl Builder email address, rather than our general support or feedback addresses.

Please note that our support department cannot assist you with writing Perl code. Support is limited to problems with the Perl Builder product. Links to online and peer support resources for Perl are provided on our website.

Updates

Maintenance updates/bug fixes for Perl Builder are free downloads.  To check for a later update, choose "Check for Updates" from the Help menu.

Note: The "Check for Updates" menu option is not available for the evaluation version of Perl Builder.

Known Problems/Limitations

Color syntax highlighting currently works only on a line by line basis. Literals broken over multiple lines will not color correctly. This is currently a design decision because multi-line coloring requires that every time a quote character is typed , all subsequent lines in the editor be re-drawn--this can have a negative impact on editing performance.  Let us know if you feel strongly about this one way or the other...

You can run multiple instances of Perl Builder 2.0 for the purpose of using the editor. However, do not attempt to run the debugger in two instances simultaneously. This may result in unpredictable/incorrect results.

A number of known problems, limitations and bugs from version 1.0 should now be fixed. Click here for a list.

Other problems

Cannot set a breakpoint or step into certain lines

Please click here for more information.

 The debugger generates a Perl error which you believe is incorrect

Please click here for more information.

 Cannot step into a module or library

Please click here for more information.

Problems after the script is moved to the web server

Please see the information here.


Examples/Tutorial

Perl Builder 2.0 includes a tutorial and examples to get you started:

The Tutorial walks you through using the CGI Wizard and debugging your script.

The Interactive I/O example shows how to use the new support for scripts with interactive I/O in PB 2.0. This example is located in the \examples\inter_io subdirectory below the main Perl Builder installation directory.

The browser-based testing example shows how to debug a multi-step script directly in your browser. This example is included with Perl Builder Professional only and is located in the \examples\browser_debug subdirectory below the main Perl Builder installation directory.

The multi-step example shows how to debug a multi-stage script using CGI simulation. This example is included with Perl Builder Professional only and is located in the \examples\multi_step subdirectory below the main Perl Builder installation directory.


Version 1.0 issues that should be fixed in 2.0

The list below shows some of the issues that were encountered by users in version 1.0. It may not be comprehensive. These issues should be fixed or dramatically improved in version 2.0.

Editor Problems

The v 2.0 editor is completely new. No code is shared with v 1.0, so if there are problems, they should be new ones:

Some v 1.0 users experienced display glitches including double characters, painting glitches, or regions which did not scroll or resize correctly.

Some users experienced problems with the copy, cut and paste commands.

Scrolling large selected areas in v 1.0 caused a lot of flicker.

Debugging Problems

The v2.0 debugging engine has also been completely redesigned. All of the following should be fixed.

Shutting down a run-way script/infinite loop in v 1.0 required using CNTR+ALT+DEL.  In V2 Pause or Stop will work.

V 1.0 did not support interactive I/O or Perl/TK. Both would cause the script to hang. (TK has not been extensively tested, but we expect it should work in V 2.0).

The V 1.0 debugger created side effects which sometimes caused text files to written to incorrectly or other problems.

Some users experienced incorrect syntax errors when using the my() construct.

A number of other issues which came up in very specific cases.


Using the Professional Version Features

The Professional version of Perl Builder 2.0 includes a number of features geared toward serious/professional Perl developers who place a high value on their time.

This section summarizes these features and explains ways in which the Professional version operates differently from the Standard version.

Opening/Activating Scripts

Debugging CGI Scripts directly in your browser.

Debug multi-step scripts. This can be done using either browser-based debugging or CGI simulation. See the "browser_test" and "multi_step" examples for details.

Using Code Templates and AutoReplace/AutoCorrect to save time while writing code.

Using the performance timing tools.

•	The pod Viewer allows you to view pod-formatted documentation which is embedded in a module. The pod viewer is a floating window which displays the pod documentation in the proper format. This lets you view the documentation while you edit/debug the script.

Mouse-over bracket matching makes it easy to find and fix missing brackets {}. Holding the mouse over a bracket causes the bracket and its partner to be highlighted in blue. Holding the mouse over an unmatched bracket causes the bracket to be highlighted in red.

The professional version includes a version for Linux on the CD-ROM. The Linux version of Perl Builder 2.0 has specific system requirements. If you plan to use Perl Builder primarily on Linux, please be sure to obtain an evaluation copy of Perl Builder 2.0 for Linux to insure that it can be installed properly on your system.


Using the Performance Timing Tools

The professional version includes tools which allow you to time the execution of specific portions of your code. This can help you to optimize your scripts.

To use these tools, you will need to specify two "timers" which indicate the start and end of the code block to be timed. Timers work in a similar fashion to break points. Perl Builder will allow you to insert only two timers. The timers do not need to be in the same source file.

To insert a timer

1.	Place the cursor on the proper line of code.

2.	From the Tools menu or from the pop-up context menu, choose Toggle Timer at Cursor.

To remove timers

Use the same Toggle Timer command to remove a specific timer, or choose Clear Timers from the Tools menu to remove all timers.

To run and time your script

Choose Execute and Time from the Tools menu or click the Timer icon at the right side of the Toolbar. Your script will execute and the time spent executing the specified block of code will be displayed on the status bar.

Note that debugging information will be ignored when you time your script, so the presence of breakpoints, watches, etc. will not affect execution times.

Important Notes

There is some overhead associated with measuring execution times, so you will get meaningful results only when you time code blocks which consume a relatively significant amount of time. For example, timing a single line of code with a simple variable assignment will not give you a useful number.

You may notice that the same code when timed multiple times give varying results. This is especially true if your code includes I/O statements (including print statements). Some of this difference is due to measuring error, while the rest is due to actual variation in the execution time.  For a more accurate result,  you can time the code several times, discard highly divergent results and then take an average.

The results are given on the status bar in milliseconds. However, these numbers are for comparison within Perl Builder only. Code which runs faster when timed in Perl Builder should also run faster elsewhere. However, the actual numbers are not useful in any other context.

You may notice that your script runs faster when you time it than when you execute it normally in Perl Builder. This is because debugging information is ignored when you time your script.

Timers work like breakpoints. They are activated immediately before the line of code at which they appear. This means that the line of code where the first timer is specified will be included in the timed block. The line of code where he second timer is inserted will not be included in the timed block.

Opening or closing files in the IDE will clear the timers. We recommend you open all the files you need before specifying the timers.

To help insure consistent results, shut down any other applications before timing your script.

The Benchmark.pm module provides an alternate way to time execution of your scripts. See the POD documentation in the module for details.


Opening/Activating Scripts

The professional version allows you to open multiple main scripts within the IDE. A main script is the script with the entry point for debugging--as opposed to a module or library which may be called by the main script. Both the Standard and Professional versions allow you to also open modules and libraries for debugging.

With the Professional version, when you choose Open Script from the File menu, the script will appear in a new tab in the IDE. In contrast, opening a new script in the Standard version will close the currently open script and replace it in the first tab.

Although you can have several main scripts open, only one script can be active at any one time. The active script is the one which you are running/debugging. The active main script is indicated by a "lightning bolt" symbol in the tab.

To change the active script, right click in the editor window and choose Select Active Script from the pop-up context menu. You can also choose the same option from the Run/Debug menu. Selecting a new active script will reset the debugger.

When you select a new active script, all the options associated with that script, such as the input type (CGI Form, Standard Input, Interactive I/O), etc will also become active in the IDE.


Browser-based Testing/Debugging

Both the Standard and Professional versions of Perl Builder 2.0 offer CGI simulation so that you can debug CGI scripts without a webserver. Both versions allow you to select an HTML form in the Input Values tab. Perl Builder will then create a simulation of the form so that you can debug the script.

The Professional version also allows you to test and debug your script directly from within your Web browser.  You simply display the HTML form in your browser, fill in the form and click the submit button. Perl Builder will then run the script and allow you to debug it.

Browser-based debugging is especially useful for complex "daisy chained" scripts. This occurs when one script generates an HTML form which calls the same or another script. This is often seen with multi-step data entry forms. Perl Builder Professional includes an example project demonstrating this.

With Perl Builder Professional, you can open all the scripts you want to debug, and then display the first HTML form in your browser. You can then fill in the forms and debug the entire sequence within the IDE. If you run into problem, using this feature, please see the troubleshooting section and the end of this topic.

Supported Browsers

Browser-based testing/debugging supports only Netscape Navigator and MS Internet Explorer:

Netscape 3.0 or later is supported.

IE 5.0 is supported.

IE 3.0 and 4.0 can be used but you must be connected to the internet or your intranet, and you must select the "Use internet/intranet URL" option.  The remote URL can be any static page on the internet or your intranet.

Step-by-step procedure

1.	Open any scripts that you want to debug in the IDE.

2.	Click the Input Values tab.

3.	Check the CGI Form Simulation radio button at the top of the Input Values tab.

4.	On the right, click the box which says "Test Directly in Browser".

5.	Click the Browse button and select the HTML page containing the form for the script you want to test. This form must have the ACTION set to the same script name have open in the IDE (The full path does not matter and may point to your server--only the script name is checked).

6.	Click the Display button to display the script in your browser.

7.	Fill in the form and click the Submit button.

8.	Perl Builder will run the script, and you can use the normal debugging techniques within the IDE.

When the script completes any HTML output will be displayed in your browser. If this output includes a form which calls another script, you can fill in this form and continue debugging.

Troubleshooting

If you have problems with browser-based testing, please check the following points:

You must select the HTML page containing your form in the Input Values tab and open it in your browser by clicking the Display button. You cannot simply open the form directly in your browser. This will not work.

After launching your browser by clicking the Display button, the status in the Input Values tab should change to "Communicating with Browser" highlighted in green. If this doesn't happen, shut down both your browser and Perl Builder and start over. This should restore communication.

Once you launch your browser and begin using it with Perl Builder, it is best to leave it running. If you close your browser, you may lose the communications link and need to shut down Perl Builder and start over.


Problems Stepping into Modules/Libraries

If you have difficulty stepping into (or stopping at a breakpoint within) a module or library, please check the following:

The module or library must be open in the IDE before you start debugging. Perl Builder will not open the file automatically.

Debugging must be enabled for the module. If the module has a standard Perl extension, such as .pl, .pm, etc, debugging will be enabled by default. If you are using another extension, you will need to enable debugging by opening the Module list and checking the box for the file at the bottom of the window. To open the Module List, choose View Module List from the File menu.

If you are using a "require" statement, you cannot specify a path. Use the syntax "require 'libfile.pl' ; "and place the libfile.pl file in the same directory as your script.

If you are using something like, use xxx::yyy, Perl Builder will support up to 3 levels. You will not be able to step into something like www::xxxx::yyyy::zzz.

Modules and their locations must be specified in your code with constructs such as "use" "require", "uselib", etc. Perl Builder does not support using command line switches for this.

If any of the above require you to modify your code, you can use the $PERLBUILDER flag to determine whether you are running in Perl Builder and execute different code accordingly.


Code Templates

Code Templates allow you to save frequently used "snippets" of code and then insert them at any time with a hotkey (cntr+J by default).

To add a new code template

1.	Right click in the editor and choose Set Editor Options/Colors. Or choose the same option from the Tools menu.

2.	Click the Code Templates tab.

3.	Enter a name and description for the new template in the two boxes near the center of the dialog box (right below the list of existing templates).

4.	Enter the code for your new template in the lower edit area.

5.	Click the Add button.

To insert template code

1.	Position the caret at the place where you want to insert the code.

2.	Press the template key combination (cntr+J by default).

3.	Select the template you wish to use from the list.

4.	Press the enter key.

Note

Your code templates are stored in a file called "templates.txt" in the main Perl Builder directory. If you have multiple licenses for Perl Builder, you can share code templates  simply by distributing this file.

Perl Builder Professional ships with code templates for common constructs such as while loops and if statements.  You may wish to modify these templates in accordance with your coding style.


AutoCorrect/AutoReplace

Perl Builder Professional's AutoReplace feature let's you set up specific text strings that will automatically be replaced with other strings as you type in the editor.  This is very similar to the AutoCorrect feature in Microsoft Word.

There are two main uses for this feature:

Correcting errors

If you sometimes mistype words, you can use this feature to automatically correct what you type.

Examples:  	"teh" --> "the"

"thier" --> "their"

Setting up abbreviations

An even more powerful use for the AutoReplace feature is to set up one or two character abbreviations for commonly used Perl constructs or other strings that you use frequently. Perl Builder will automatically expand the abbreviation into the full construct as you type. This can save a lot of typing and help reduce errors!

Examples: 	p  --> print " " ;

w --> while ( ) {

i -->  if ( ) {

Notes

Autoreplace operations occur only after you type a recognized delimiter. In the example above, you could type p + <space> for p + <enter> to insert the print statement string. This prevents the autoreplace from occurring at the wrong time. You can specify the delimiters used for autoreplace recognition in the Editor Options dialog box when you set up autoreplace strings (see below).

To insert constructs which take up more than one line, use code templates instead.

To specify autoreplace strings

1.	Right click in the editor and choose Set Editor Options/Colors. Or choose the same option from the Tools menu.

2.	Click the Autocorrect tab.

3.	Enter the string the be replaced on in the box at the lower left and the replacement string in the box at the lower right of the dialog box.

4.	Click the Add button.

Important

Your autoreplace strings are stored in a file called "autoreplace.txt" in the main Perl Builder directory. If you have multiple licenses for Perl Builder, you can share autoreplace strings simply by distributing this file.

Specifying autoreplace strings is a matter of personal preference and will depend on your coding style. For this reason, Perl Builder does not ship with pre-set strings.

However, an example set of autoreplace strings is included. You can try these strings by doing the following:

1.	In the main Perl Builder directory, look for the file called "rename as autoreplace.txt."

2.	Delete or rename the existing "autoreplace.txt" file (if any) and rename the above file as "autoreplace.txt."

3.	You can then view and modify the autoreplace strings by using the procedure given above.


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.

Note: Version 2.0a includes some important new features beyond those listed below. Version 2.0a is a free update for all registered v. 2.0 users.

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 and background colors for specific syntax elements.

Block indent/outdent using the tab key.

Direct control over keyboard shortcut assignments for editor functions.

Find All and highlight feature.

Improved printing support, including 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.

In addition to major new features, a list of problems/limitations in V 1.0 that have been fixed is available here.


Feature Comparison
Feature Comparison - Perl Builder 2.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.

Feature	Standard	Professional
General Features
Platforms Supported	Windows	Windows, Linux*
Distribution Media	Download	CD-ROM
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).		X
Editor Features
Full-featured programmer's editor with Perl color-syntax highlighting.	X	X
Editor scripts let you automate editor functions by writing Perl code.	X	X
Code templates let you save snippets of code which can later be inserted with a hotkey or menu		X
AutoReplace/AutoCorrect lets you specify strings so that the editor automatically corrects errors or replaces abbreviations with the full text.		X
Mouse-over bracket matching. Just place the cursor over any bracket {} to highlight its partner.		X
Navigation/Online Help Features
"As you type" prompting for parameters for built-in Perl functions	X	X
Subroutine navigator makes it easy to jump directly to any subroutine in the current module.	X	X
Improved bookmark system.	X	X
Context sensitive help for built-in Perl functions (just click a Perl function name in your code and press F1).	X	X
Easy access to Perl documentation in HTML (Windows) or Manpages (Linux) from within the IDE.	X	X
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.		X
Debugging Features
Full-featured visual debugger integrated directly with the editor.	X	X
Supports all standard debugging features: breakpoints, watches, stepping, evaluate/modify, dump complex variables, etc.	X	X
"Mouse-over" variable inspection: just hold the mouse over a variable to inspect its value.	X	X
CGI Simulation lets you debug/test CGI scripts on your desktop without a webserver.	X	X
Full support for non-CGI scripts, including command line, interactive, Perl/TK, etc.	X	X
Debug complex CGI scripts directly in your browser--without the need for a webserver on your PC. (Not available on Linux).		X
Enhanced support for debugging "daisy chained" scripts--where output from a script includes a form which calls the same or another script.		X
Color syntax highlighting for HTML script output	X	X
CGI Wizard Features
Automatically generate CGI scripts to handle forms.	X	X
Visually design a script to validate user input, send email, save data to a log file on the server, and generate HTML output. All without writing code.	X	X
Performance Timing Tools
Built-in tools make it easy to time portions of your code in order to optimize your scripts. (Not available on Linux).		X

*Note:  The Linux version of Perl Builder 2.0 has specific system requirements. If you plan to use Perl Builder primarily on Linux, please be sure to obtain an evaluation copy of Perl Builder 2.0 for Linux to insure that it can be installed properly on your system.


Release Notes

Version 2.0c

This release fixes several specific problems reported by users, and also adds the following new features:

AutoOpen Last Script in Tools | Options | Preferences. If this box is checked, Perl Builder will automatically open the last used script on startup. This option is checked by default.

Store .pbp files together in Tools | Options | Preferences. This option was added at the request of several users who did not like the .pbp files stored in the same directory as the script.

.pbp (Perl Builder Project) files store various settings associated with a script. Examples include settings for the CGI wizard (if used), watch variables, the type of input I/O used (CGI Simulation, Interactive IO, etc) and links to related modules or libraries.  By default, .pbp files have the same name and location as the script (with a .pbp extension).

If the Store .pbp files together box is checked, then all .pbp files will be stored in the \pbp subdirectory below the maIn Perl Builder installation directory. There is no option to change this location.

Important Warnings

•	If you change this setting, you must manually move any existing .pbp files to the new location (either the \pbp directory or the same directory as the script) if you want to retain your settings.

•	If this box is checked, you must insure that all scripts have unique names, since the .pbp file is named based only on script name. If you have two scripts with the same name but different paths, the .pbp files will conflict and results may be unpredictable.

•	In general, this option is intended for those users who have a specific objection to the .pbp files in the script directory. We recommend that most users keep this box CLEARED.

Version 2.0b

This version fixes a few problems that came up with version 2.0a, and also adds two new features.

New Subroutine Navigation Commands are available under the right mouse button pop-up context-menu:

Find Subroutine Definition (Ctrl+D) searches for the definition of the subroutine call at the location of the cursor. For example, if the cursor (text caret, not mouse pointer) is on "MySub(0)", this command will search for "sub MySub".

Perl Builder will search only in modules which are open in the IDE. It will start with the current file and then search other open files left to right.

If Perl Builder does not find a definition for the subroutine, or if the cursor is not positioned on a valid subroutine name, nothing will happen. No error message will be displayed.

Return to Subroutine Call (Shift+Ctrl+D) allows you to jump back to the location of the call after using the Find Subroutine Definition command. These two commands maintain a stack, so you can use the commands multiple times (up to 10 nested levels). Other cursor movements will not affect these commands.

Mouse-over bracket matching (Professional Version Only) now displays the line number of the matching bracket if it is not visible on the screen. You can jump directly to the matching bracket by pressing Ctrl + [ ; Also, we fixed some problems with mouse-over bracket matching with deeply nested brackets.

Fixes

Fixed several issues with the Evaluate/Modify command. Evaluating an expression caused a hang in some cases.

Fixed a problem with "Indent based on Brackets." (This has to be turned on in Tools | Options | Preferences).

Several other minor fixes.

Version 2.0a

Version 2.0a is significant update which addresses some problems which came up in the initial release of version 2.0 and which also includes some important new features. The version 2.0a update is a free download for all registered v. 2.0 users.

Tool tip Evaluation

The "Mouse-over" tooltips used to display the values of variables while debugging were sometimes unreliable and difficult to initiate in version 2.0 This has been dramatically improved in version 2.0a.

Function Parameter Prompting

•	Version 2.0a will now automatically prompt you for function parameters for the core Perl functions. The pop-up prompt will appear after you enter the function name and then a space or a left parenthesis. This works in a similar fashion to the  prompting in products like Visual Basic, Delphi, Visual Studio, etc.

•	Note that many Perl functions can take several forms, so some pop-up prompts will list two or more variations.

•	The pop-up prompt is integrated with the online help. Click the mouse anywhere on the pop-up hint to bring up online help for the function.

•	Function parameter prompting is on by default, but can be turned off by clearing the "Function Prompting" box in Tools | Options | Preferences.

Pop-up Function List

You can display a list of all the core Perl functions by pressing CNTRL + L or by selecting "List Perl Functions" from the right mouse button context menu. This will display an alphabetical list of functions. Double click (or select and press RETURN) to insert the function into your code.  After inserting the function name, pressing space or left parenthesis will bring up the parameter prompt as described above.

CPU Utilization

Some version 2.0 users reported difficulty switching to other applications while stopped at a breakpoint in the Perl Builder debugger because all CPU cycles were being utilized. This has been fixed in v. 2.0a.

Improved Stability

Some users reported stability problems with version 2.0, especially when running Windows 2000 or NT. We believe these problems have been resolved in version 2.0a.

Other Fixes

In addition this version includes fixes for several other specific problems that were reported by users.

_______

For a list of new features in Version 2.0, please see What's New in Version 2.0


Introducing Perl Builder
Introducing Perl Builder 2.0

Perl Builder is the first true integrated development environment (IDE) for creating Perl scripts under Windows 95, 98, NT or 2000.  Version 2.0 is a major upgrade with many new features and a redesigned programming environment which addresses most of the limitations that were present in Perl Builder 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.

Perl Builder provides a number of key features that will dramatically enhance the productivity of Perl developers:

An integrated editor/debugger which is reminiscent of the top visual programming tools for Microsoft Windows. Features like color syntax highlighting, breakpoints, single step, watches, and "tool tip" variable inspection make it easy to write and debug scripts.

Perl Builder's CGI Wizard is a code generator which makes it easy for anyone to create sophisticated CGI scripts without programming. Experienced Perl developers can use the CGI wizard to design major portions of their scripts visually and then add their own custom code as needed.

Built in CGI simulation allows you to test your CGI scripts right within the development environment, without the need for a web server. Script output such as dynamic HTML and email messages can be examined visually.

Fully windowed (GUI) environment. With Perl Builder, you never need to work with the command line.

Perl Builder runs on Windows 95/98/NT/2000. However, the scripts created may be used on any platform which supports Perl.

While Perl Builder includes a number of powerful features which are specifically geared toward creating CGI scripts, the environment can also be used to develop general purpose Perl scripts.

_________________

See also

What's New in Version 2.0


An Overview of the CGI Wizard

Perl Builder's CGI Wizard is a visual tool which makes it easy for anyone to create sophisticated Perl CGI scripts.

To access the CGI Wizard, click the [image] icon on the toolbar or select CGI Wizard from the Tools menu.

The CGI Wizard consists of four panels:

Panel 1 allows you to select the HTML form which is associated with the CGI script you are creating. The CGI Wizard will read the form and determine what input fields will be available to the script.

Panel 2 lets you validate the data entered by the user. For example, you can check to be sure that certain fields are filled in. You can also perform more advanced validation such as checking the format of email addresses or making sure a value entered falls into a certain range.

Panel 3 lets you have your script write data to text file on your webserver. This makes it easy to collect data from visitors to your website.

Panel 4 allows you to have your script automatically send one or more email messages. Email messages can be used to notify the website owner of the user's submission, send a thank you note to the user, or even sign the user up for a mailing list.

Panel 5 is where you specify the HTML page which the user will see after submitting the form. The CGI Wizard supports both dynamic HTML output and redirection to an existing page.

The CGI Wizard will automatically generate the code for your script when you click the Finish button. You can add your own custom code to the script and it will be preserved even if you run the Wizard again. This allows you to easily update your script (for example, if the visual layout/format of your website changes).


Wizard Panel 1: Read Form Data

This panel allows you to select the HTML Form which is associated with your script. The data which the user enters in this form will become the input values for your CGI script.

To select the form

1	Click the Select >> button and then use the open dialog to find and open the HTML page. You must select an HTML page on your local drive--you cannot access a page on your website.

2	The fields in the form will appear in the list box at the lower left of the Wizard Panel.

Notes

The Wizard reads only the first form in the selected HTML page. If your page contains more than one form, you will need to copy the subsequent forms to new HTML pages in order to use the Wizard.

Because the field names in the form become variable names in your script, it is very important to use meaningful field names (for example "EMAIL" rather than "TEXTBOX1").

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">

The field names in your forms must begin with an alphabetic character or you will get an error when you run your script. For example, if you have a field name like name="3", you need to change it something like name="F3" before using Perl Builder.

To view or Edit the HTML Page

After selecting an HTML page, you can view it or edit it from within the Wizard panel. Click View to display the page in your browser or Edit to open it in your HTML Editor. Note that by default, your HTML Editor is set to be Windows Notepad. You can change this to a real HTML Editor by selecting Options from the Tools menu and click the General tab. If you use the editor to change the fields in your form, you need to re-select the page after saving it.

Optional Comment/Description

This box allows you to add a descriptive comment for the field. To add a comment, select the field name in the list box and then type the comment.

Input Parse Method

These radio buttons allow you to select the technique which your script uses to parse the input values. If you are not familiar with CGI programming, leave this set to Standard.

If Standard is selected the CGI Wizard creates a subroutine within the script to handle parsing the form inputs. If cgi-lib.pl or CGI.pm, is checked the Wizard will instead create code which utilizes these standard libraries.


Wizard Panel 2
Wizard Panel 2: Validate Inputs

This panel lets you check the data submitted by the user to make sure it meets certain requirements. If the data does not pass the tests you specify, an error message will be displayed asking the user to try again.

To validate a field

1	Drop down the field list at the top of the Panel and select the field which you want to validate.

2	Select the type of validation you want to perform (see below).

3	Fill in any required values (for example minimum or maximum values for a range).

4	If you also want to check the length of the data (the number of digits or characters entered), check the box and fill in the length value. This check is done in addition to any other validation.

5	If the Field may be left blank box is checked, then the field will be validated only if the user enters something. This allows you to perform validation to find errors is a field which is not required.

6	Fill in the error message to be displayed if the validation condition is not met. The CGI Wizard will fill in a default message for you. You can change this if you wish.

7	Your selections will automatically be saved if you choose another field or move to another Wizard panel.

Validation Options

Anything/No Validation means the field is not validated. The user may fill it in or leave it blank.

Non-blank means the field is required and must be filled in (any text is acceptable).

Email Address means the value entered must be in x@y.z format. This does not mean the address is valid.

A Number means the value entered must be a number in the specified range (specify a min and/or max).

Exactly Equal to is useful for password fields. The value entered must exactly match the specified value (including case).

Checking the Length of Data Entered

In addition to the other validation options, you can also check for the number of characters/digits entered.  You can enter both a minimum and maximum allowable length.  Set both the min and max to the same value if the user must enter an exact number of characters. If you do not want to check for the min or max, enter 0.

For example, setting min=5 and max=0 would require the user to enter at least 5 characters, with no maximum limit.

If you validate the length of the data, you should also change the corresponding error message for the field to reflect this. For example, "Field 'zip" must be filled in and must contain 5 digits."

To select an Error Format Page

Your CGI script will be more professional if the error message is displayed on a page which matches the rest of your website (background, table formatting, etc.). This option allows you to specify a page which is a template for the error message. If you do not specify this option, your error messages will be displayed in plain text against a default browser screen.

To choose an error format model page, click the Select >> button and then use the Open dialog box to find and open the HTML page.

The HTML page you select must contain a field reference of the form [$message]. This field reference will be replaced by the error message(s) generated by your script. See Designing HTML Output for details.

Note

The script created by the CGI Wizard accumulates error messages and displays them in a list. So, if the user enters several invalid values, he or she will see a list of all the error messages, rather than only the first one encountered by the script. Each error message is displayed on its own line.


Wizard Panel 3: Write to a Log File

This panel allows you to have your script write data to a text log file on the server. This makes it easy to capture and store data obtained from users.

The data will be written to the text file one record per line. This panel allows you to specify exactly what you want written in each line of data.

Check the Write data to text file box in order to enable this feature.

Enter the name of the text file you want to write to. It is easiest to enter only a file name and then create this file in the same directory as the script. However, you can enter a path if you wish. See the very important note below about the need to create this file on your server.

Choose the Field Delimiter, ether tab or comma. Tab or comma delimited text files are supported by nearly all database and spreadsheet applications, so these formats will make it very easy to import your data.  You can use another delimiter if you wish, but you will need to edit the record format directly (see below).

Replace line breaks in text area fields with allows you to specify the character that will replace hard line breaks in data entered by the user. Since we are using a one-record-per-line format, we cannot allow fields to contain line breaks. The default is a space.

The Record Format box specifies how a line (record) of data will be written to the text file. The easiest way to add fields is to use the Add Record and Add All buttons at the bottom right.

However, you can also edit the record directly. The Wizard will not check for syntax errors.  So if you edit the record directly and make a mistake, you will get an error message or incorrect result when your run your script.

The Add Date/Time button adds a field to your record which includes the date and time that the user submitted the data.

Important Notes

When you run your script in Perl Builder, Perl will create the text log file if necessary. This will not happen on your Unix webserver. You must create the text file and set the proper permissions.

You can do this with the following commands (assuming the file is called log.txt).

touch log.txt
chmod 660 log.txt

If you have high volume website, it is possible that users may be entering data at the same time. This can result in "collisions" or simultaneous writes to the log file that may cause errors in your data.

Perl Builder will insert some code which will lock the text file to prevent this problem. However, these lines use the flock() function which is not implemented in the Windows version of Perl. Therefore, Perl Builder will comment out these lines.

When you are ready to move your script to a Unix server, you can uncomment these lines.


Wizard Panel 4: Send Email

This panel allows you to have your script automatically send up to 5 separate email messages.

To compose an email

1	Click the first unused Message button in the Panel. The Compose Email dialog box  will appear.

2	Fill in the fields to define your email message.

3	Click Ok to save your message.


The Compose Email Dialog Box

Send this email only if

Check this box and fill in a condition if you only want the email to be sent under certain conditions. For example, you might put a checkbox with the field name "WANTLIST" on your form asking if the user wants to sign up for your mailing list. The condition would then be:

$WANTLIST eq "ON"

To:

Specifies the email address to which the message will be sent. You can drop down the list to select a variable, for example, [$email] or you can enter an email address directly as in, "feedback@solutionsoft.com".

From:

Specifies the "from" and "reply-to" fields for the message. You can drop down the list to select a variable or you can enter an email address directly.

Subject:

Specifies the subject of the message. You can include data entered by the user by including a field reference. For example, a subject of "Thank you, [$FNAME]" would become "Thank you, John" at runtime if a user enters "John" in the FNAME field.

Body

The large edit area at the bottom of the dialog box can be used to write the body of your message. You can merge a field into the body by dropping down the field list and selecting the field name.

Example:

Hi [$FNAME],

You live in [$COUNTRY].

Might become,

Hi John,

You live in France.


Wizard Panel 4: HTML Output
Wizard Panel 5: HTML Output

The final wizard panel allows you to specify the HTML page which the user will see after he or she submits the form successfully.

The CGI Wizard can create a script which uses one of two methods to display the page:

Dynamic HTML Output is created "on the fly" by your script. In other words, a custom HTML page is written specifically for the user. This makes it easy for you to customize the output based on what the user entered in the form.

Redirection simply displays an existing page on your website (or anywhere on the web). If you choose this option, all users will see the same HTML page.

To specify dynamic HTML output

Check the top radio button and then click the Select >> button. Use the Open dialog box to select an HTML page which serves as a model for the dynamic HTML output.

The CGI Wizard allows you to define dynamic HTML output using any HTML Editor. You can "merge" fields into the HTML output in a fashion which is very similar to designing mailing labels or a database form.

For details on this, see Designing HTML Output.

To specify redirection

Check the bottom radio button and fill in the URL of the page the user should be redirected to.


Designing HTML Output

Perl Builder's CGI Wizard 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.


Adding Custom Code to the CGI Wizard Output

The CGI Wizard is designed so that it can be used again and again to update your script as needed. For example, if your website undergoes a design change, you will want to update your scripts so that the dynamic HTML output matches the new look.

In order to allow for this type of reuse, while still letting you add your own custom code to your script, the CGI Wizard places special comment lines in the code it generates.

These lines look something like this:

# ***AUTOGEN:VALIDATE*** Do NOT modify this line!! Do NOT enter custom code in this section.

... Automatically generated code here ...

# ***ENDAUTOGEN:VALIDATE*** Do NOT modify this line!!  You may enter custom code after this line.

... custom code may be entered here ...

It is very important that you not remove or modify these special comment lines. The CGI Wizard looks for these comments if you use it to update an existing script. If the lines are missing or modified, you may lose work or your script may not work properly.

When you add your own code to the script, add it only after the ENDAUTOGEN comments. If you enter or change code within an automatically generated bock, your changes will be lost the next time you use the Wizard.

If you must modify code with the AUTOGEN blocks

In some advanced cases you may have to modify auto-generated code in order to achieve the desired results. In this case you will need to save a back up copy of your script. If you re-run the Wizard, your custom changes will be lost; you can then restore them by copying and pasting from the backup copy.


Running Scripts and Examining Output

Perl Builder allows you run your scripts and examine the results right within the development environment. If you are creating a CGI script, Perl Builder's powerful CGI simulation will allow you test both your form and your script without the need for a web server.

Before you can run scripts, you must have the Windows 95/NT version of Perl installed on your computer. If you do not yet have Perl, you can download it from the internet.

To run your script

1	Open your script in the Perl Builder Editor (or create it ether manually or with the CGI Wizard).

2	Set the inputs for your script. To do this, click the Input Values Tab. You can either enter values in a simulation of an HTML form or specify standard input for a non-cgi Perl script. Click here  for more on setting input values.

3	Click the [image] icon on the toolbar or choose Run/Continue from the Run/Debug menu. Your script will run and the output will appear as described below.

Examining Script Output

HTML/TEXT

HTML or Text output from your script is displayed in the Output: HTML/Text tab. The output shown is "raw" HTML or text, so it will show any HTML tags. To view HTML output in your browser, click the View in Browser button at the bottom of the screen.

If your HTML output contains a form which calls the same or another script, you can debug the entire sequence by using the "Use as Input For" button at the bottom of the screen. Select the script called by the output form and press Go to begin debugging the next script in the sequence. See the "multi-step" example for details.

The output window color codes HTML output so it is easy to see the syntax elements. You can control the color highlighting and other settings by clicking the Options button.

EMAIL

Email messages show up in a separate tab called Output: MAIL, provided the stream opened for writing is called "MAIL" , as in: print MAIL "Hi There!".

If more than one email message is sent, they will appear one after another in this window.

ERRORS

If your script contains syntax errors, an Errors pane will appear at the bottom of the screen. This pane contains the error messages generated by Perl. If you double click a message which includes a reference to a line number, you will jump directly to the corresponding line in your script. This makes it easy to track down errors. Note that the error may sometimes be one or two lines before the specified line number.


Setting Script Inputs

In order to test your script, you need to specify the input data which it will process. With Perl Builder, you set the inputs for your script in the Input Values tab in the Editor/Debugger's main window.

Three methods are provided for setting inputs:

HTML Form Simulation

This is usually the easiest way to test a CGI script. Perl Builder will create a simulation of any HTML form so that you can enter input values in a similar fashion to the end user. To use this method, make sure the left radio button is checked at the top of the Input Values window.

If you created your script using the CGI Wizard, a form simulation will be created for you automatically when you generate your code. Otherwise, you will need to select an HTML form by clicking the button on the right side of the Input Values window.

The simulation created by Perl Builder is very similar to the original HTML form, but there are a few important differences:

All fields are shown vertically in the simulation in the order they appear in the HTML code. The layout will be different from the original if you used HTML tables.

Radio buttons and select menus (list or combo boxes) are converted to drop down lists to save space. The function is the same.

In the simulation, field values are displayed. This may be different from the visible text in the HTML form in the case of Radio buttons and select menus. The value comes from the value=xxxx parameter in the HTML field tag. When designing forms, it is best to use meaningful values.

The simulation shows all fields, including hidden fields. Hidden fields, push buttons and images are all converted to text boxes in the simulation. These special fields are marked with a label such as "(HIDDEN)".

Note

Perl Builder Professional also lets you debug scripts directly from your browser. This is the preferred method for complex scripts which generate output that calls the same or other scripts.

Standard "Batch" Input

If the script you are testing is not a CGI Script, or if you prefer to enter the CGI inputs in "query string" format, you will use the Standard Input Option.

To use this method, make sure the middle radio button is checked at the top of the Input Values window.

Use this option only if all the input data is available when your script starts (for example when reading from a file). If your script will wait for interactive input from the user, use the interactive I/O option below.

You can either type of paste the input data for your script directly in the large edit area, or you can select an input file by clicking the Select >> button.

Interactive I/O

The interactive I/O option displays a window where you can enter input interactively. Output is shown in the top pane of the window and input is entered in the bottom area. You can either click the Enter button or press the RETURN key to send your input to the script.

To use this method, make sure the right radio button is checked at the top of the Input Values window.

Use this option if your script will wait for input from the user.

You can also display the Interactive I/O window by choosing the proper option from the Run/Debug menu or by clicking the "i/o" icon on the toolbar. All output goes to this window, so it also provides a way to view your script's output while your are debugging without having to switch to the Output tab.

Input Size Limitations

Because of design issues, there are some limitations on the length of data that can be specified for inputs.

With HTML form simulation, the data from Text Boxes and Text Areas is limited to about 300 characters per field. If you enter data beyond this, Perl Builder will truncate it before passing it onto your script.

With standard input, there is an approximate 10K limit on the input data. If you specify data longer than this, Perl Builder will truncate it before passing it onto your script.

If you need input data longer than these limits, debug and test the function of your script using smaller data sets first. Then try larger inputs by running from the command line or by testing on your webserver.


Debugging your Script

Perl Builder's integrated debugger makes it easy to track down and fix problems in your scripts. You can make changes in the editor and then immediately run your script and see the results in the debugger.

Syntax Errors

If your script contains syntax errors, an Errors pane appear at the bottom of the screen when you run your script. This tab contains the error messages generated by Perl. If you double click a message which includes a reference to a line number, you will jump directly to the corresponding line in your script. This makes it easy to track down errors. Note that the error may sometimes be one or two lines before the specified line number.

Using the Debugger to Solve Run-Time Errors

Errors in the behavior of your script are usually more difficult to find and fix than syntax errors. Perl Builder includes a number of capabilities which make this process dramatically easier:

You can set breakpoints. The easiest way to do this is to click in the margin to the left of the line you want to break on. Clicking a line which already has a breakpoint set clears the breakpoint. To clear all the breakpoints, use the Clear all Breakpoints command under the Run/Debug menu.

You can single step through your code. To do this, use the [image] icon on the toolbar or press the F7 key.

The Step Over [image] function (F8) works the same way as step, except that it will not step into subroutines.

"Tool Tip" variable inspection makes it easy to see the values of variables while execution is stopped at a breakpoint or step. Just move the mouse cursor over any scalar variable or array element name. For best results, position the cursor just to the right of the "$",

Watches are another way to see variable values. To add a watch, place the cursor on the variable name and then right click and choose Set Watch at Cursor from the context menu. The variable will be added to the Watch List window. The Watch List floats on top of the editor; you can close it or move it if it gets in the way. To view it again, choose View Watch List from the Run/Debug menu or the context menu.

 The Run to Cursor function in the right mouse button context menu allows you to quickly run your script to the cursor. This is similar to setting a breakpoint and then clicking Run/Continue.

 The Stop/Reset function halts your script and resets it to begin again from the beginning.

The Pause function stops a running script which at the next breakable instruction.

The Step Backward function reverses execution and takes you one line backward in your code. All variables revert to their proper values. You can step forward and backwards in problem area of code until you find the cause of the problem.

The Evaluate/Modify  command lets you evaluate an expression of change the value of a variable while you are stopped at a breakpoint or step.

Notes

Modifying the text in the editor automatically resets the debugger. So if you click Run/Continue after making a change, you will be executing the script from the beginning.

You can change the keyboard mapping for the debugger commands so they match your favorite Windows development tool in the Tools | Options dialog box, Preferences tab.

The debugger status is displayed on the right side of the Status bar at the bottom of the main window.

Remember that you can click Run/Continue at any time after making changes to your script and immediately see the results. This makes it very easy to experiment and test your code as you develop it.


Setting Breakpoints

Breakpoints cause execution of your script to halt, so that you can examine intermediate variable values.

There are several ways to "toggle" (set or clear) an unconditional breakpoint:

Click in the gray margin to the left of the line you want to break on. If a breakpoint is already set on the line, clicking in the margin will clear it.

Place the cursor on the line and then right click and choose Toggle Breakpoint from the context menu.

Use the Toggle Breakpoint item under the Run/Debug menu or click the icon on the toolbar.

If you attempt to set a breakpoint on a comment or other invalid line, Perl Builder will set it on the next breakable line (see note below).

Clearing all Breakpoints

To clear all the breakpoints in your script, choose Clear all Breakpoints from the Run/Debug menu.

Conditional Breakpoints

Conditional breakpoints cause execution to stop only when a specified condition is met. You can set conditional breakpoints using the Set Conditional Breakpoint command  under the Edit/Debug menu or the right mouse button context menu.

Note on "Breakable" Lines

Not all lines in your script are able to accept a breakpoint. An obvious example is a comment line. If you click on a line on which Perl Builder cannot set a breakpoint, the breakpoint will be set on the next breakable line in the script.

In some cases, Perl Builder is more restrictive than the command line debugger in allowing you to set breakpoints. You may see instances where Perl Builder will not allow you to break on a line which should technically be breakable. This is a design tradeoff, which was made to overcome problems interpreting Perl syntax.

If this becomes a problem for you, you can generally add a simple line of code such as

  $tempvar = 1 ;

at strategic point and then set the breakpoint on that line.


Setting Conditional Breakpoints

Conditional breakpoints cause execution to stop only when a specified condition is met.

To set a conditional breakpoint

1	Place the cursor on the line on which you want to break.

2	Choose Set Conditional Breakpoint from the Run/Debug menu or the right mouse button context menu.

3	Enter the condition you want to use in the dialog box. (Please see the note on specifying conditions below).

4	Click the Set button. Conditional breakpoints are indicated with a red stop sign symbol containing the letter "c".

To clear a conditional breakpoint

You can either use the Set Conditional Breakpoint command as described above and then click the Clear button, or you can simply use the Toggle Breakpoint command.

To modify an existing breakpoint

1	Place the cursor on the line on which the breakpoint is set.

2	Choose Set Conditional Breakpoint from the Run/Debug menu or the right mouse button context menu.

3	Modify the condition as necessary and then click Set.

Note on Specifying Break Conditions

You can specify any valid Boolean (true or false) condition when setting a breakpoint. You can use any variables in the expression as long as they are valid within the current scope.

When setting conditions, be careful to avoid some common Perl errors.  In particular, be sure to use the proper operators depending on whether you are working with a number or a string.

Correct Examples

$i == 5

(stop only if $i is equal to 5)

$i >= 6

(stop only if $i is greater than or equal to 6)

$name eq "Fred"

(stop only if $name is stringwise equal to "Fred")

Common Mistakes

$i = 5

This sets $i to 5 and will always be true. Should be $i == 5.

$name == "Fred"

For strings, you must use the string operators: eq ne gt lt ge le.


Setting Options

Perl Builder's Options dialog box allows you to set various options for the development environment.

The Locations tab allows you set the paths for Perl  your HTML editor and other tools.

The Preferences tabs lets you set general options for the IDE.

The CGI Wizard tab lets you set options for the CGI Wizard.

_________________

See also

Setting Editor Options


Setting Editor Options
Setting Editor Options/Colors

To access the Editor Options dialog box, choose Set Editor Options and Colors from the Tools menu or from the pop-up context menu.

The Editor Options dialog box has several tabs (5 tabs in the Professional version, 3 tabs in the Standard version):

Options lets you specify a variety of general settings, both for the editor and for printing. Please see below for a list of the various editor options available.

Highlighting lets you specify the colors and fonts used in the editor.

Key Assignments lets you specify hotkeys for individual editor functions. Note that debugging functions hotkeys are controlled in the Tools | Options | Preferences dialog box.

AutoCorrect (professional version only), lets you specify words and phrases to be automatically replaced as you type in the editor.

Code Templates (professional version only), lets you specify snippets of frequently used code that can be inserted with a hotkey.

Options Tab Settings

Print Options control the output when your print and are self-explanatory.

Editor Options

Word Wrap:  Word-wrap text display

Visible Right Margin:  Show a right margin mark at Right Margin column

Visible Gutter: Show left gutter area

Auto Indent: When not in word-wrap mode, indent caret to first non-space character in line above

Smart tab: When not in word-wrap mode, TAB keys move to next non-space character in line above

Override Wrapping: When in word-wrap mode, override word-wrapping for lines that start with a character in the WrapOverride property

Word Select: Double clicking selects word nearest to mouse position

Show Word WrapColumn: Show word-wrap column in word-wrap mode

Block Overwrite Cursor:  Show a block cursor when the editor is in overwrite mode

Mark Wrapped Lines:  Show a glyph in the gutter for wrapped lines

Use Tab Character:  When present, causes TAB characters to be inserted into the text. When absent, spaces are used instead.

Smart fill: When auto-indenting (Auto Indent required) or tabbing to a column (Smart Tabs required) the editor will fill the required gap with a minimum number of characters made up of tabs (if the use tab character option is checked) and spaces.

Show All Chars:  Show hidden white space characters as glyphs (applies to TAB, SPACE, NEWLINE and wrapped lines)

Cursor Beyond EOL: Allow caret to move beyond the end of the line


Tools | Options Dialog box: Locations Tab

Perl Executable Path

This is the path to the Perl interpreter. You must have Perl installed on your computer in order to run/debug scripts. If you do not have Perl, you can download it from the internet for free.

HTML Editor

This is the path to your HTML editor. The editor is invoked if you click the Edit button in the CGI Wizard.

Local Location of Perl Documentation

This specifies the directory which contains the HTML documentation for Perl. The documentation is included with the ActiveState Perl distribution, or it can be downloaded from http://www.perl.com. This setting allows you to display the documentation in your browser by choosing "Perl Documentation (Local)" from the Help menu.

The default location is the subdirectory \docs\Perl under the main Perl installation directory.

The latest release of ActivePerl(tm) from ActiveState contains greatly improved documentation.

To set Perl Builder to use this documentation, choose Tools | Options | Locations and set the "Local Location of Perl Documentation (HTML)" to the proper HTML file. For example:

c:\perl\html\index.html

Note

If your Perl distribution does not have an "html" directory, download the latest version of Perl from http://www.activestate.com. This will include the documentation.

Web Browser

Perl Builder should your browser if you click the "View in Browser" button in the Output tab. If the browser does not launch, start it manually, leave it running and then try again.  You may also wish to re-install your browser, since Perl Builder uses the standard Windows method of launching the browser.

In general it is faster to leave your browser running and minimize it rather than shutting it down each time.

Perl Builder supports only Netscape and MS IE.

External Text Editor Path

If you want to use an external, stand-alone text editor with Perl Builder, specify the location here. If this path is filled in, Perl Builder will add a new icon to the far right of the toolbar. You can click this icon to open the active file in your editor.

The checkboxes below let you synchronize an external editor with Perl Builder. See Using an External Editor with Perl Builder  for more details.

Automatically Load Modified Files on Activation

If this box is checked, then whenever you activate Perl Builder any open files which have been modified on disk by another application will automatically be reloaded (without displaying a message).  If this box is cleared, then Perl Builder will still check to see if open files have been modified, but will display a message asking if you want to reload the file.

Regardless of whether this box is checked, Perl Builder will always display a warning message if there are unsaved modifications to the file within Perl Builder. If you get into a situation where you have modified the file in both Perl Builder and another editor, you will lose your changes in one environment if you reload or save the file. If this happens, you can use the File | Save As command to preserve your Perl Builder changes in another file.

You can avoid the situation above by also checking the "Automatically Save Modified Files before Deactivating" box.  See below.

Automatically Save Modified Files before Deactivating

If this box is checked, Perl Builder will automatically save any open, modified files whenever you switch to another application. This will keep files synchronized with another editor, provided that the editor checks to see if open files have been modified on disk when the application is activated (virtually all good programming editors do this).

Perl Builder will always create a backup copy of your file with the extension ".bak" before it automatically saves the changes on deactivation. This is to help prevent loss of work if, for example, you inadvertently change or delete part of your script and then switch to another application before restoring it.

We recommend you keep this box cleared unless you are actively using an external editor.


Tools | Options Dialog box: Preferences Tab

This tab allows you to set various preferences for the Perl Builder IDE.

If Enable Integrated Debugging is not checked, you will not be able to use Perl Builder's debugging commands (step, breakpoints, etc).  You scripts may execute somewhat faster if this option is cleared.

Set Perl Priority to Low controls the priority of the Perl process while you are using the debugger. Some users have reported better performance while stepping through code if the priority is set to low. You can experiment with this setting to see what gives the best results. If you change this setting, you must reset the debugger and re-rerun your script before the new priority will take affect.

Keyboard Mapping Style allows you to change the keyboard shortcuts for the debugging commands to match other Windows development tools with which you may be familiar.

AutoIndent based on Brackets: {}

If this box is checked, when you end a line with an open bracket "{", Perl Builder will automatically add a tab to the beginning of the next line.  It will also automatically outdent (remove a leading tab) from the line on which you type a closing bracket: }.

Save files in UNIX format causes Perl Builder to save files using only "\n" at the end of each line, as opposed to the "\r\n" used in Windows.

If Block Indent with Tab Key is checked then pressing the tab key while the selection includes at least one end of line character results in a block indent. In a similar fashion, pressing Shift+Tab causes a block outdent.

Left Margin Behavior, lets you change the action associated with clicking in the left margin.

"Mouse-Over" Bracket Matching (Professional Version Only) enables automatic bracket pair highlighting when you move the mouse over a bracket.

Function Prompting enables automatic pop-up prompting for built-in Perl function parameters.

AutoOpen Last Script. If this box is checked, Perl Builder will automatically open the last used script on startup. This option is checked by default.

Store .pbp files together. This option was added at the request of several users who did not like the .pbp files stored in the same directory as the script.

.pbp (Perl Builder Project) files store various settings associated with a script. Examples include settings for the CGI wizard (if used), watch variables, the type of input I/O used (CGI Simulation, Interactive IO, etc) and links to related modules or libraries.  By default, .pbp files have the same name and location as the script (with a .pbp extension).

If the Store .pbp files together box is checked, then all .pbp files will be stored in the \pbp subdirectory below the maIn Perl Builder installation directory. There is no option to change this location.

Important Warnings

•	If you change this setting, you must manually move any existing .pbp files to the new location (either the \pbp directory or the same directory as the script) if you want to retain your settings.

•	If this box is checked, you must insure that all scripts have unique names, since the .pbp file is named based only on script name. If you have two scripts with the same name but different paths, the .pbp files will conflict and results may be unpredictable.

•	In general, this option is intended for those users who have a specific objection to the .pbp files in the script directory. We recommend that most users keep this box CLEARED.

The Editor Settings button brings up the Editor Options dialog box, which allows you to set items such as colors, editor keyboard mappings, etc.


Tools | Options Dialog box: CGI Wizard Tab

This tab includes options which affect the code generated by the CGI Wizard:

Header Line

This is the first line of every script generated. The default value is #!/usr/local/bin/perl which is the value typically required by UNIX servers.

Mail Program

This specifies the path to the mail program (most often SendMail) on the webserver. You should check with your webmaster or WebHost company to make sure this setting is correct.

Intermediate Variables

If this box is checked, the CGI Wizard will generate code which uses scalar intermediate variables, rather than directly using array elements.

This will add lines of the form

$email = $field{'email'} ;

to your script. These simpler variables are easier to work with, but make your script somewhat less efficient since these lines are not really necessary.

If you clear this box, the CGI Wizard will use the array element directly, rather than first assigning it to a scalar variable.

Note

Even if this box is cleared, you still use the shorthand notation, [$emall] (rather than {$field{'email}] when specifying field references for dynamic HTML. The CGI Wizard will automatically replace the shorthand notation with the full array element name when your code is generated.


Tools | Options Dialog box: Editor Options/Colors Tab

AutoIndent based on Whitespace

If this box is checked, then whenever you press the Return key in the editor, the caret will be positioned below the first non-blank character on the preceding line.

Enable Syntax Color Highlighting

If this box is checked, various Perl syntax elements will be color coded. If this box is cleared, all text will be displayed in the default color (usually black).

Color Settings

Click the appropriate Set Color button to specify the colors for the various syntax elements.


Moving your Script to your Web Server

Once you have developed and tested your CGI script in Perl Builder, you will need to move it to your web server. The following information lists some important points and trouble spots to watch out for for:

Determine where your script should go

The most common place for scripts on web servers is the cgi-bin directory; however, there are many exceptions. You will need to check with your webmaster, ISP or Web Host company to find the answer to this question.

Check the Script Header Line and Mail Prog Path

Two very important lines in your script are the first line and the line which specifies the location of the server's mail program (used if your script sends emails).

The default values are:

#!/usr/local/bin/perl

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

Both of these values are set in the Tools | Options dialog box, CGI Wizard tab.

You will need to check with your webmaster or web host company to be sure these values are correct. The easiest way to find out is usually to examine a script which you know works. If your web sites is managed by another company, check their website for example scripts.

Note on NT Webservers

Perl Builder is set up to assume a Unix webserver using Sendmail. If you are using an NT server, your script will still run, but the email probably will not be sent correctly. Unlike Unix, where Sendmail is the standard for email, NT has a variety of email applications.

To get things working on NT, you will need to obtain a working Perl script which sends email on your server. Use this script as a guideline to modify the code generated by Perl Builder.

Make sure the script name matches the <FORM> tag

The HTML file which contains the form associated with your script has a <form> tag has with a value which looks line ACTION="\cgi-bin\myfile.cgi". Make sure the script name matches your script exactly, including case. Also make sure the path (if any) is correct for your server.

If you use FTP to move the script to your server, choose ASCII as the transfer type

If you select binary, your script will fail on the server.

After moving your script to the server, set the permissions

You must give your script execute permission on the server for it to work.

The following command will do this:

chmod 755 myscript.cgi

If your script writes to a text log file, you also need to create the text file and set its permissions:

touch log.txt

chmod 660 log.txt

If your website is on a remote server, this command must be entered with a Telnet client. Check with your webmaster or ISP if you do not know how to telnet into your server.


Downloading Perl

You must have the Windows 95/NT of Perl on your computer in order to run or debug scripts.

Like all versions of Perl, the Windows 95/NT port is freeware.

Solutionsoft maintains a page with download links to the latest version of Perl at:

http://www.solutionsoft.com/getperl.htm

Note

Perl Builder is not tied to a specific Perl port and should work with any build for Windows. However, we recommend that unless you have specific reason to do otherwise, you use the latest build from ActiveState: http://www.activestate.com.


Reading and Writing to Disk Files

With Perl Builder, your scripts can read and write to files on your disk in the normal fashion. However, there are a few issues to keep in mind:

If you open/create a file without specifying a path, the file will be located in the Perl (not Perl Builder) executable directory.

For example:

open (LOGFILE, "> myfile.txt");

would create a file called myfile in the directory where Perl.exe resides (typically c:\perl\bin).

If you want to work with a file in another location, specify a full path--but use forward slashes in the path.

For example:

open (LOGFILE, "> c:/mydir/myfile.txt");

#note that we used forward "/" rather than usual MSDOS "\".

If you specify a full path on your local drive for debugging, make sure you change the path as necessary if you move your script to the server.


Other Products from Solutionsoft

Free evaluation copies of all Solutionsoft's products are available for download at http://www.solutionsoft.com.

WordToWeb

WordToWeb automatically converts any Microsoft Word document into HTML format. Unlike Microsoft's Internet Assistant, or the HTML support built into Word 97, WordToWeb is designed to fully automate the conversion of long, complex documents such as manuals.

Key Features:

Breaks long Word documents into smaller HTML files and links them together with navigation buttons.

Converts and links multiple Word documents.

Converts Word cross references to hyperlinks.

Creates an online table of contents and index.

Supports frames and HTML 3.0 tables.

Exact control over how Word elements translate to HTML.

HelpBreeze

HelpBreeze turns Microsoft Word into a complete, integrated environment for creating Windows help files, as well as professional quality printed documentation. The optional HTML Wizard add-in provides support for standard HTML as well as Microsoft's new HTML Help format.

Key Features:

Visual environment lets you create, test and compile your help file from within MS Word.

Full support for both 32-bit Windows 95/NT help and 16-bit Windows 3.1 help.

Create online help and professional quality printed documentation from the same source documents.

Full support for adding context-sensitive help to any 32- or 16-bit Windows application. Supports all development environments (VB, Delphi, C++, PowerBuilder, etc.).


Tutorial
Perl Builder Tutorial

This short tutorial will walk you through a simple example using the CGI Wizard and the Perl Builder IDE. To access this tutorial in the future, choose Tutorial from the Help menu.

Using the CGI WIzard

1	From the File menu, choose Open Script. Use the Open dialog box to navigate into the "tutorial" subdirectory (c:\Program Files\Perl Builder\tutorial by default).

2	Open the script "example.cgi". The script will appear in the Editor/Debugger.

3	Click the [image] icon on the toolbar to bring up the CGI Wizard.

4	Notice that "form.htm" is selected in Panel 1 of the Wizard. Click the View button to see this HTML page. Each of the form fields in the HTML page has a corresponding variable in the list at the lower left of the wizard panel.  When you select an HTML Page, the CGI Wizard scans the form and automatically defines variables based on the fields.

5	Click Next > to move to Panel 2.

6.	Drop down the "Select input value" list at the top of the panel.  Try selecting variables "first", "last" and "email". Notice how the validation is set for these variables.

7.	Click the View button at the bottom of the panel to see the Error model page. This page defines the overall format of error messages.

8.	Click Next > to move to Panel 3. This panel lets you store the data entered by the user in a text file on your server.

9.	Notice the Record Format in the center of the dialog box. This shows the fields which will be written to the log file. One line will be written for each user, with the fields separated by tabs. Tab-delimited text files are easy to import into applications like spreadsheets and databases.

10. The date will be written to a file called log.txt. It is very important to remember that this feature not work unless you create the log.txt file on your server and set its permissions correctly (chmod 660 log.txt). Click the Help button in the CGI Wizard for more on this.

11. Click Next to move to Panel 4.

12. Click the Message #1 and Message #2 buttons and examine the email messages that have been defined. The first message submits the form results to the webmaster, and the second message sends a thank you note to the user. Notice how the field references are merged into the email text using the [$name] syntax.

13. Click Next > to move to Panel 5.

14. Click the View button at the top-right of the panel to view the output model page. Notice that again variables are merged into the page.

15. Click Finish to re-generate the code for the script.

Setting Input Values, Running your Script and Examining Output

You must have Perl installed on your computer to complete the rest of the tutorial. If you do not have Perl, you can downlload it from the internet.

1	Click the Input Values tab. Notice that Perl Builder has created a simulation of the form selected in Panel 1 of the CGI Wizard.

2	Leave the input fields blank for now, and click [image] on the toolbar.  Your script will run, and output will be generated.

3	Click the View in Browser button at the bottom of the Output: HTML/Text screen. This is the error page generated by the script because the required values were not filled in.

4	Click the Input Values Tab and fill in some values for the fields. Click [image] again.

5	If you entered valid input values, you should now see the HTML output page. Click the View in Browser button at the bottom of the window to see the page.

6	Click The Output: MAIL tab. This tab shows the email output from your script. Notice that there are two messages shown one after the other.

7	For a more detailed discussion of setting inputs and Perl Builder's HTML form simulation, click here.

Using the Debugger

1	Click the Main Script tab to display your script.

2	Look for the line which says "&GetFormInput;" (about 6 lines from the top). Click in the gray margin just to the left of this line. A red "stop sign" appears. This sets a breakpoint.

3	Click the [image] icon. Your script will run and execution will halt at the breakpoint.

4	Move the mouse cursor to the top of the window and place it over the variable "$mail_prog" (2nd line). The value of this variable ('/usr/lib/sendmail') appears in a small "tool tip" pop-up window. For best results, place the cursor just to the right of the $.

5	Place another breakpoint about 6 more lines down on the line which says: if ($field{'first'} eq "") {

6	Click [image] again. Execution advances to the second breakpoint.

7	Try single stepping through the code. Click [image] or press the F7 key.  Execution advances to the next line. Note that when you single step or stop at a breakpoint, the line indicated by the blue arrow has not yet been executed.

8	Other debugging functions are available on the right mouse button context menu. To access this, right click in the Editor window. From the context menu, you can set watches on variables and use the Run to Cursor function.

9	For more on using the debugger, click here.


Set Arguments Dialog Box

This dialog box allows you to set command line arguments to be passed to your script. It also lets you set the value of the $ENV{PATH_INFO} variable which is used with some CGI scripts.

For example if you would normally run your script from the command line using the syntax:

  perl myscript.pl arg1 arg2 arg3

Then you would enter "arg1 arg2 arg3" in this dialog box to achieve the same result in Perl Builder.

To set the value of $ENV{PATH_INFO}, type the value into the second edit box. This information corresponds to the text that comes after the "?" in the cgi script's URL.


Working with Multiple Source Files in the IDE

Perl Builder allows you to open 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.

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.  See Using the Module List  for details.

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.


An Overview of Editor Scripts

Editor Scripts let you extend the Perl Builder IDE using Perl.

You can write scripts to perform custom editing functions or to generate reports from your files. You can easily save your scripts for future use and attach frequently used scripts to Perl Builder's main menu and assign keyboard shortcuts to them.

Perl Builder supports two general types of Editor Scripts:

Edit function scripts operate on the selected text in the IDE. You can write scripts which perform any editing function you want.  The Block Right and Block Left functions under the Editor-scripts menu are examples of this type of script.

Reporting scripts extract information from the selected text and place the results in Perl Builder's HTML/Text Output tab.  Once the information is in the Output tab, it can be copied to the clipboard or saved to a file. A possible use of a reporting script might be to automatically generate documentation for a script.

Editor scripts can also perform other functions, such a reading and writing to disk files.

How Editor Scripts Work

Editor scripts are normal Perl scripts, except that Perl Builder automatically sets up the script to loop through the selected text line by line.  The code looks something like this:

while (<INPUT>) {

Your code here: Make changes to $_ and then print it.

}

The while loop is added automatically when your script is run; you only need to add code for the inside of the loop.

Inside the loop, the current line of text is contained in the standard Perl variable $_.  The last step of your code should be to print $_. Perl Builder will replace the selected text with the text you print.

Example:

The following code would cause a space to be added in front of every line of the selected text:

$_ = " ".$_ ;

print $_ ;

Adding Code before or after the loop

By default, Perl Builder will place all of your code inside the while loop as described above. In most cases, this makes it easy to quickly develop code to implement editing features.

In some cases, however, you need to add code before and/or after the loop. Examples might be opening and closing files, initializing a variable or specifying "use" or "require" statements.

The special commands #LOOPSTART and #LOOPEND allow you to control where the while loop will be placed.

Example:

The following code writes the selected text to a file called "myfile.txt" with line numbers.

open (FILE ">myfile.txt") ;

$line = 0 ;

#LOOPSTART

$_ = $line++."  ".$_ ;

print FILE $_ ;

#LOOPEND

close (FILE) ;

Notice that this example does not print anything to STDOUT, so it has no effect on the selected text.

Creating Reporting Scripts

As described above, reporting scripts place the results (the text which you print to STDOUT) in the HTML/Text Output tab, rather than replacing the selected text in the IDE. To create a reporting script, simply include the line #DOREPORT somewhere in your script.


The Script Manager

The Editor Script Manager makes it easy to develop, save and run your Editor scripts. See An Overview of Editor Scripts  for an explanation of how editor scripts work.

Editor Scripts List

The Editor Scripts List at the top left of the dialog box shows all your existing scripts. Your scripts are saved in the subdirectory "Editor Scripts" under the main Perl Builder installation directory. To open a script, simply select the name in the list.

Script Name

This is the file name for your script. Perl Builder will automatically add a ".pl" extension.

Add to Menu checkbox and Menu Item

If the Add to Menu box is checked, then Perl Builder will add the specified menu item to the Editor-scripts menu when you save your script. If you want to remove a script from the menu, clear the Add to Menu box and then click the Save button.

HotKey

You can assign a key sequence to your editor script using this control.  Simply press the actual keys you want to use (for exampe cntr+1). The hotkey combination will work only if you also add the script to the menu.

Code Window

The code window allows you to enter and edit your script. You cannot debug scripts in this window; copy your script into the IDE instead. See Debugging Editor Scripts  for details.

Errors Window

The errors window appears at the top of the Script Manager if you try to run your script and compiler errors result. You can double click a line in the error window to jump to the corresponding line in your script. (In some cases, the line # may be off slightly because of the additional code added by Perl Builder at runtime.).


Debugging Editor Scripts in the IDE

If you are developing a complex editor script, you may want to debug it in the IDE:

1	Save and close any open main script and secondary scripts you have open in the IDE.

2	Open the script manager and copy your script to the clipboard.

3	Paste your script into the main script window.

4	Add a while loop around your script as follows:

while <> {

<your code>

}

 	If you have used the #LOOPSTART and #LOOPEND commands, position the while loop accordingly.

5	Click the Input Values Tab.

6	Check the Right radio button at the top of the screen which says "Standard Input".

7	Type or paste sample text into the Input Values window. This text will correspond to the selected text operated on by the editor script.

8	Run and debug your script.

9	Copy any changes back into the Script Manager.


Regular Expression Search/Replace

This dialog allows you to perform search or replace operations using the powerful regular expression support built into Perl. When you use this function, Perl Builder invokes Perl to perform the operation; therefore, the regular expression syntax is identical to that of Perl.

For information on Regular Expressions see the "perlre.html" file which is included with Perl. This file will be placed in the /docs/Perl/ subdirectory under the main Perl installation directory.

The regular expression replace features uses the Perl command:    s/<find>/<replace>/.  Regular Expression replace operations work only on the selected text. If you want to perform the operation on the entire document, use the Edit | Select All command first.

Quick RegEx Reference

\ Quote the next metacharacter

^ Match the beginning of the line

 . Match any character (except newline)

$ Match the end of the line (or before newline at the end)

| Alternation

() Grouping

[] Character class

* Match 0 or more times

+ Match 1 or more times

? Match 1 or 0 times

{n} Match exactly n times

{n,} Match at least n times

{n,m} Match at least n but not more than m times

$1, $2, etc. Refer to the groups specified in the search expression using ().

Example

Remove leading tabs from every selected line (ie. Block Left):

Search  (^\t)(.)

Explanation: Find tab characters (\t) at the start of the line only (^) , followed by any other character (.). Enclose the tab and the character following the tab in parenthesis so we can refer to them in the replace expression.

Replace:     $2

Replaces the found result with just $2, which contains the character following the tab.


The Evaluate/Modify Dialog Box
The Evaluate/Modify/Add Watch Dialog Box

This dialog box allows you to evaluate an expression or change the value of a variable while execution is stopped at a breakpoint or step. You can also add the variable or expression to the watch list.

To display the dialog box, right click and choose Evaluate/Modify from the context menu, or use the Run/Debug menu. You can place the cursor on a variable before using the Evaluate/Modify command to quickly see its value.

Variable or Expression

Enter either a simple variable or an expression. Clicking the Evaluate button displays the resulting value in the Current Value field.

If you enter an array or hash (associative array) name, as in "@myarray" or "%myhash", the dialog box will be enlarged and all the elements of the array or hash will be listed.  You can also "dump" the contents of complex variables (see below).

Current Value

This is a read-only field which displays the value of a variable or expression.

New Value

This field allows you to modify the value of a variable. Type the new value and click the Set New Value button. The new value can be a simple value or an expression.

Set Watch

The Set Watch button allows you to set a watch on the current variable or expression.

Dump

Press this button to dump the contents of a complex data structure. To use this feature, the Data::Dumper module must be installed. This module is included in the standard Perl distribution.

When you click this button, the dialog box will become larger to allow easier viewing of the data. You can also resize the dialog box if you wish.

Click the "X" button at the right top of the dialog box to close the Dump output; this will allow you to enter a new expression to be evaluated.


Using the Module List

The Module List provides basic project management for Perl Builder. You can access the Module List by choosing View Module List from the File menu.

The Top List displays files which you have recently opened using the Open Module/Library command under the File menu.

To reopen a file, double click it in the top list.

To remove a file reference from the list, click the trash can icon. This will not delete the file on disk. It simply removes the reference from the module list.

The Bottom List displays the files which are currently open in the IDE (except for the main script).

The checkbox at the left of each line allows you to turn debugging on or off for each open file. Leaving files open in the IDE with debugging turned on impacts performance, so if you are not actively debugging a file, clear this box or close the file.

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.

Although the Open Module/Library command is most often used to open Perl modules and libraries (.pm and .pl files), it can be used to open any file.  By default, if you open a file which does not have one of the extensions .pl, .pm or .cgi, debugging will initially be turned off for the file.

For more information on module and libraries and how Perl Builder handles multi-file project, see Working with Multiple Files in the IDE.


Checking the Syntax of your Script

Whenever you run your script, Perl first checks the syntax for any serious errors. If errors occur, these will be reported in the Errors pane at the bottom of the screen.

In addition to this basic error checking, Perl Builder provides two commands which allow you to take advantage of the enhanced syntax checking capabilities built into Perl.  These commands can sometimes help you to find mistakes which are not technically syntax errors, but which may result in problems when your script executes.

The -w flag causes Perl to do additional syntax checking and generate warnings when it parses your script. These warnings are not fatal errors, but they may (or may not) be indicative of problems in your code.

The Use Strict option causes Perl to insist that all variables be declared with the my() construct or by explicitly referencing a package, as in $::myvar or $mypack::myvar.

More detailed information on these options is available in the Perl documentation.

Check Syntax with -w Flag under the Run/Debug menu invokes Perl with the -cw flags. This command parses the syntax of your script only; it does not actually run your script. Any warnings generated will be displayed in the Errors tab.

Run with "Strict" under the Run/Debug menu invokes Perl with "use Strict" specified. This command runs your script and you will see the results in the Output tabs. However, when you run with this command, the debugger will not be active, and breakpoints will be ignored.

If either of these commands generates errors or warnings, you can double click the message in the Errors pane to jump to the corresponding line in your script.


Using an External Text Editor with Perl Builder

While most users will probably want to take advantage of Perl Builder's integrated editor/debugger, some developers may prefer to use a familiar stand-alone text editor (for example MultiEdit, CodeWright or the Windows port of Emacs).

Perl Builder includes features which allow you to synchronize the IDE with your Editor. Follow the steps below to take advantage of these features.

To set up Perl Builder to use an external editor

1	Choose Options from the Tools menu and click the Locations tab.

2	Set the path to your external editor. You can click the Browse button at the lower right of the dialog box and then use the Open dialog box to find the .exe file for your editor.

3	Check the "Automatically Load Modified Files on Activation" and "Automatically Save Modified Files before Deactivating" boxes if you want to take advantage of these features. For maximum synchronization with an external editor, check both of these boxes.  See below for details.

4	Click OK. You will see a new icon on the far right of the Perl Builder toolbar. You can click this icon to open the current file in your text editor.

Automatically Load Modified Files on Activation

If this box is checked, then whenever you activate Perl Builder any open files which have been modified on disk by another application will automatically be reloaded (without displaying a message).  If this box is cleared, then Perl Builder will still check to see if open files have been modified, but will display a message asking if you want to reload the file.

Regardless of whether this box is checked, Perl Builder will always display a warning message if there are unsaved modifications to the file within Perl Builder. If you get into a situation where you have modified the file in both Perl Builder and another editor, you will lose your changes in one environment if you reload or save the file. If this happens, you can use the File | Save As command to preserve your Perl Builder changes in another file.

You can avoid the situation above by also checking the "Automatically Save Modified Files before Deactivating" box.  See below.

Automatically Save Modified Files before Deactivating

If this box is checked, Perl Builder will automatically save any open, modified files whenever you switch to another application. This will keep files synchronized with another editor, provided that the editor checks to see if open files have been modified on disk when the application is activated (virtually all good programming editors do this).

Perl Builder will always create a backup copy of your file with the extension ".bak" before it automatically saves the changes on deactivation. This is to help prevent loss of work if, for example, you inadvertently change or delete part of your script and then switch to another application before restoring it.

We recommend you keep this box cleared unless you are actively using an external editor.

To launch your editor from within Perl Builder

Click the External Editor icon at the far right of the Perl Builder toolbar. This icon is visible only if you have selected an external editor in Tools | Options | Locations as described above.

To launch Perl Builder from within your Editor

If your editor allows you to launch another application, you can start Perl Builder with the following command line:

<PERL BUILDER PATH> <SCRIPT PATH>

Example:

c:\program files\perl builder\pbuilder.exe c:\mydir\myscript.pl


Keyboard Map

Perl Builder supports all the standard keyboard shortcuts which you would normally find in a Windows edit control (cntr+c to copy, cntr+v to paste and so forth). We have not listed all the standard shortcuts here. Instead, the list below shows only the special purpose key strokes which are specific to Perl Builder.

Commands which are followed by (ES) are implemented with editor scripts.  Editor  scripts allow you to create your own custom edit commands using Perl. See An Overview of Editor Scripts  for details.

Indentation
Block Right	cntr+shift+i      or tab if one or more line ends are selected	Indent selected lines right one tab stop
Block Left	cntr+shift+u     or shift+tab if one or more line ends are selected	Unindent select lines by removing a leading tab.
Fix Indentation	cntr+shift+f  (ES)	Formats indentation in the entire script based on the position of brackets {}. You must choose Edit | Select All before using this command.
Block Comment
Block Comment	cntr+3	Comment out one or more lines by adding a leading # to each line
Block Uncomment	cntr+shift+3	Uncomment one or more lines by removing the leading # from each line.
Bracket Matching
Match Bracket	cntr+[ or cntr+]	Find the bracket which matches the one at the cursor. This works with: () {} <> [].
Searching
Find	cntr+f	Displays the Find dialog box.
Find Again	F3	Finds the next occurrence of the previously found text.
Replace	cntr+h	Displays the Replace dialog box.
Find/Replace Regular Expression	cntr+r	Displays the Find/Replace Regular Expression dialog box.
Find Subroutine Definition	cntr+d	Jumps to the definition of the subroutine call at the cursor (if the definition is in a file open in the IDE).
Return to Subroutine Call	cntr+shift+d	Returns to the subroutine call (used after Find Subroutine Definition). These commands support up to nested levels.
IDE Navigation
Next IDE Tab	cntr+tab	Switches to the next tab in the Perl Builder IDE.
Previous IDE Tab	cntr+shift+tab	Switches to the previous tab in the Perl Builder IDE.
Debugging Command Shortcuts

To see the keyboard shortcuts for the debugging commands, drop down the Run/Debug menu.

The debugging command shortcuts can be customized to match other environments with which you may be familiar. For example, if you use Borland tools the step command is F7 or F8, in Microsoft's tools it is usually F10 or F11.

To customize the debugging shortcuts, choose Tools from the Options menu and then click the Preferences tab. You can then select the desired keyboard mapping style.

Editor Shortcuts

You can modify the keyboard shortcuts for specific editor commands by using the Tools| Set Editor Options and Colors command, and then clicking the Keyboard tab.


Solving Problems with the Debugger

Perl Builder's integrated debugger has been tested and used by thousands of users, and is accurate virtually all the time. However there may be isolated instances where the debugger has a problem interpreting the syntax of a particular script.

If you suspect that a Perl error message generated by Perl Builder is incorrect

First verify that the error occurs only when running in Perl Builder with debugging enabled:

Choose Tools | Options | Preferences and turn off integrated debugging. Then run the script again in Perl Builder.

Run the script from the command line to make sure that you don't get the error message.

If the error occurs only when running in Perl Builder with debugging enabled, then you may have discovered a problem in the debugger.

How to Work around the Problem

If you are getting an incorrect error it is almost always because Perl Builder is not parsing your code correctly and is trying to make a line breakable when it shouldn't.

Perl Builder provides a mechanism to manually disable making a line breakable. Follow the steps below to get your code running properly:

Locate the line of code where the (incorrect) error is being reported.

Add the following comment to the end of this line (upper case is required):  #PBNOBRK

For example:

$i = 5 ;	#PBNOBRK

Try running your script again (with debugging turned back on).

If it still doesn't work, try placing the comment on the lines immediately before or after where the error is reported. Some trial and error may be required.

Please also report the problem by sending the script (or at least the problem lines of code) to perl@solutionsoft.com.