Visual Perl User Guide

Visual Perl Release Notes

Visual Perl Tutorial

		Visual Perl User Guide

Version 1.8.1 Table of Contents Getting Started Configuring Editor Behavior Configuring Project Defaults Debugging the Sample Project About Solutions and Projects Creating New Projects and Files Configuring Projects Removing Projects from Solutions Working with Files Working with Folders Editing Programs Syntax Coloring Syntax Checking Keyword Tips IntelliSense Smart Indenting Code Folding Commenting Blocks of Code Brace, Bracket and Parenthesis Matching Indentation Formatting Adding Entries to the Task List Open a Module in the Editor Pane Using Web Services Using the Rx Toolkit Rx Toolkit Component Overview Creating Regular Expressions Node Tips Evaluating Regular Expressions Examples of Regular Expressions Running Programs Debugging Programs Debugger Commands Debugger Windows Breakpoints Viewing and Changing Variable Values Call Stack Emulating a CGI Environment Remote Debugging Configuring the Local Machine for Remote Debugging Configuring the Remote Machine for Remote Debugging Using Remote Debugging Visual Perl and the Perl Dev Kit (PDK) Creating PDK Components Configuring PDK Components Building and Debugging Components PerlNET Components Adding Tools to the Visual Studio Tools Menu Source Code Control Using the Class View Documentation Dynamic Perl Help Perl Module Reference Visual Perl Documentation Visual Perl FAQ Contact ActiveState

ASPN, the ActiveState Programmer Network, features comprehensive Perl programming resources. Check out: The Rx Cookbook, a collaborative library of Regular Expressions. The Perl Code Archive, based on the Comprehensive Perl Archive Network. ASPN's archive, combined with ActivePerl's Perl Package Manager, makes ASPN's Perl Code Archive the easiest way to find and install Perl extensions. Upgrade to an ASPN Perl membership and receive even more: The Perl Dev Kit, a suite of Perl tools that makes it easy to build and deploy applications, services and controls for the Windows platform. PerlAlert, ActiveState's weekly newsletter that keeps you informed of new Perl developments. O'Reilly Books online, delivered through ASPN Reference.

Getting Started

Visual Studio .NET is the next generation of Microsoft's integrated development environment. With Visual Studio .NET, Microsoft opened the Visual Studio API so that third-party software developers could write extensions to the environment. ActiveState, taking advantage of the open API, developed Visual Perl, Visual Python and Visual XSLT, three plug-ins that bring the power and popularity of these open-source languages into the rich Visual Studio IDE.

Visual Perl runs within Visual Studio .NET. We have included a sample Visual Studio solution containing a Visual Perl project to help you get started. In the section below, you will configure the Visual Perl environment defaults, then open the sample project and begin debugging.

Configuring Editor Behavior

Editing defaults (such as tab size, word wrap, etc) can be configured for each language supported by Visual Studio. To configure Perl defaults, select Tools|Options, then select the Text Editor folder, and the Perl sub-folder. These Perl-specific defaults override the environment defaults specified in the All Languages sub-folder. Only items specific to Visual Perl are described below; for a description of other editor options, refer to the Visual Studio .NET documentation.

General options

• Auto list members Check this box to enable IntelliSense, which provides pop-up lists of context-sensitive modules and methods as you type.
• Parameter information If this check box is selected, keyword tips will be displayed as you enter code. See Keyword Tips for a description of this function.

Tabs options

• Smart Indenting automatically indents lines in the editor after open braces and open parenthesis. When a line ends with an open brace, the following line is indented based on the configuration of the Tab section of the Tabs dialog. When a line ends with an open parenthesis, the following line is indented to the column following the parenthesis.

Visual Perl Specific options

• Check syntax while editing If this check box is selected, Visual Perl will analyze the language syntax as you type and indicate potential errors by underlining text with a red wavy line. A summary of syntax errors is added to the Visual Studio Task List (View|Other Windows|Task List).
• Enable taint-checking If this option is enabled, taint checking will be performed in the editor. Potentially unsafe commands will be underlined in the same manner as syntax errors. Debugger taint checking is configured in the Project Properties.
• Show code folding If this check box is selected, Visual Perl will "notice" discrete blocks of code by monitoring bracket constructs. On the left margin of the editing workspace, plus and minus symbols will indicate sections of code that can be "folded" (that is, collapsed or expanded). Click on the plus or minus symbol to collapse or expand blocks of code. When a section of code is collapsed, you can display the hidden code by hovering the mouse pointer over the symbol that appears to the right of the first line of the collapsed block. Collapsed code blocks will be automatically opened during debugging or editor-driven modifications.

Configuring Project Defaults

Environment defaults, such as the location of the Perl interpreter, are specified using the Tools|Options|Projects|VisualPerl dialog. As necessary, configure the following options:

• Perl Interpreter Location By default, the Perl interpreter is located at C:\Perl\bin\Perl.exe. If your Perl interpreter is not installed in the default location, modify the value in this field to point to the location of your Perl interpreter.
• PDK Install Location Visual Perl and ActiveState's Perl Dev Kit (PDK) can be used in conjunction to easily build Windows applications, services and controls, and to generate .NET compliant objects using Perl. If the PDK is installed on your system, specify the location in this field. By default, the PDK is installed in C:\Perl\bin.
• File Extensions During installation, Visual Perl creates an association between the file extensions ".pl" and ".pm" and the Perl language. Therefore, whenever you open files with those extensions, features such as Perl-specific syntax coloring are enabled. To associate additional file extensions with the Perl language, enter the desired extensions in this field. Separate each extension with a semicolon. You must re-start Visual Studio in order for the change to take effect.
• Default Remote Port Enter the port number that should be used for controlling the remote process during Remote Debugging. The default port number is 3000. The Remote Port number can also be configured for individual projects in the project properties.

Debugging the Sample Project

Click Start|Programs|ActiveState Visual Perl|Samples|Response Tracker. This will automatically load Visual Studio; on the banner that displays while Visual Studio .NET loads, notice the logo for ActiveState Visual Perl along with logos for other registered languages.

In the Solution Explorer, double click the Perl file to open it for editing. (If the Solution Explorer pane is not visible in the Visual Studio .NET workspace, click View|Solution Explorer.) Press F10 (Debug|Step Over) or F11 (Debug|Step Into) to begin, and continue through the document by pressing F11. Set breakpoints by clicking in the grey margin to the left of the editing pane. Perl programs are always debugged inside a DOS console window. You can enter input to the program and read its output in the console.

You can use our sample project to familiarize yourself with using Visual Perl to edit and debug Perl programs. The next section discusses how to create a new project, configure project options, and manipulate project files.

About Solutions and Projects

The fundamental unit of organization in Visual Studio .NET is the solution. If you've worked with Visual InterDev 6.0, you're familiar with solutions. If you're a Visual Studio 6 user, a solution is similar to a "Workspace". Solutions can contain one or more projects, with each project associated with a programming language.

Solutions are collections of projects, and projects are collections of individual "items". In Visual Perl, "items" are equivalent to files. When you create a new project from the File menu, Visual Studio .NET automatically creates a new solution. Alternatively, you can add a new project to an existing solution by right-clicking the solution name (in the Solution Explorer pane) and selecting Add|New Project.

In Visual Studio there is one primary program per project, so you must create a project for each Perl program you intend to work with. A Perl program is considered to be a top-level .pl file, in which execution begins, and any additional .pm or .pl files your program brings in with use, require, or do operators.

"Items" (files) are stored within projects. You can also open files that are not assigned to projects. When you do this, they are placed in a temporary project called "Miscellaneous Files". You can edit files in temporary projects, but you can't run or debug them until you place the files in a permanent project.

Creating New Projects and Files

Visual Perl includes a number of templates for creating Perl projects and programs. When you create a new Perl project using a template, the project will include a Perl program file with code elements appropriate to the template you selected. The Visual Perl templates are most useful when creating Perl Applications, Services and Controls in conjunction with the Perl Dev Kit (PDK).

To create a new Perl project:

1. From the File menu, select New|Project. This will create a new project in a new solution. To create a new project in an existing solution, open the solution, then right-click the solution name in the Solution Explorer and select Add|New Project.
2. Select Visual Perl Projects from the list of Project Types, then select the type of Perl project you wish to create.
   • Simple Project Creates a Perl project that contains a Perl program with minimal Perl code.
   • Empty Project Creates a Perl project that does not contain a program file.
   • Control Library Creates a Perl project with a Perl program that has elements and examples for building a Windows Control in conjunction with the Perl Dev Kit.
   • Managed DLL Library Creates a Perl project with a Perl program that has elements and examples for building a .NET-compliant DLL in conjunction with the Perl Dev Kit.
   • Executable Creates a Perl project with a Perl program that has elements and examples for building a Windows Application in conjunction with the Perl Dev Kit.
   • Managed Exe Creates a Perl project with a Perl program that has elements and examples for building a .NET-compliant application in conjunction with the Perl Dev Kit.
   • Tray Application Creates a Perl project with a Perl program that has elements and examples for building a Windows System Tray application in conjunction with the Perl Dev Kit.
   • Windows Service Creates a Perl project with a Perl program that has elements and examples for building a Windows Service in conjunction with the Perl Dev Kit.
3. Configure the new project's properties

Configuring Projects

Specify the parameters for running, debugging and building Perl programs inside the associated project. To access the project's properties, right-click the project name in the Solution Explorer window and select Properties.

Configuration Properties - General

• ApplicationType Select the type of Perl application you are running, debugging, or building. This field works in conjunction with the options configured on the Debugging page. For example, if you set the DebugMode option to "Project", the debugger will check the ApplicationType value to determine the project type.
  • Standard Perl: Refers to a Perl program that is not built in conjunction with the Perl Dev Kit.
  • Application: Refers to an application built in conjunction with the Perl Dev Kit.
  • Service: Refers to a service built in conjunction with the Perl Dev Kit.
  • Control Library: Refers to a control built in conjunction with the Perl Dev Kit.
  • System Tray Application: Refers to a system tray application built in conjunction with the Perl Dev Kit.
  • Managed Perl Exe: Refers to an application built in conjunction with the Perl Dev Kit.
  • Managed Perl Dll: Refers to a library built in conjunction with the Perl Dev Kit.
• StartupObject: If the value in the DebugMode field on the Debugging page is set to "Project", the file name specified in this field will be run when the project is run or debugged. If you are building a project, specify the target script in this field.

Configuration Properties - Debugging

• DebugMode
  • Project When the debugger starts, if this value is specified, the debugger will run the script specified in the "StartupObject" field on the General page.
  • External Script When the debugger starts, if this value is specified, the debugger will run the script specified in the "StartScriptExtern" field.
  • External Command When the debugger starts, if this value is specified, the debugger will run the command or program specified in the "StartApplicationExtern" field.
  • Remote Debugging When the debugger starts, if this value is specified, the debugger will attempt to establish a connection with a remote machine using the ports specified in the "WatcherPort" and "RemotePort" fields.
• StartScriptExtern If the DebugMode value is set to "External Script", enter the path and name of the external Perl script in this field.
• StartApplicationExtern If the DebugMode value is set to "External Command", enter the command or application name in this field.
• CommandArguments Enter command-line arguments for the script in this field.
• InterpreterArguments Enter command-line arguments for the Perl interpreter in this field.
• WorkingDirectory By default, the working directory is the directory where the project file is located. To specify an alternate directory, enter the path in this field.
• RunInShell In Visual Perl, you can run programs within the Visual Studio environment (in the "Run" window), or in an external "cmd" (shell) window. When you are debugging programs, the value of this field will be ignored and programs will be debugged using a shell window.
• Use_CGI_Environment If this value is set to "Yes", CGI debugging will be enabled and the variables configured on the CGI page of the project properties will be passed to the CGI program. See Emulating a CGI Environment for more information.
• WatcherPort The port number specified in this field determines the port to be used to for monitoring remote connections during remote debugging. The default value is the port specified in Visual Perl's configuration (Tools|Options|Projects|VisualPerl). To specify a port number to be used by the current project, enter the port number in this field. See Configuring the Local Machine for Remote Debugging for more information.
• RemotePort The port number specified in this field determines the port to be used to for controlling remote processes during remote debugging. The default value is the port specified in Visual Perl's configuration (Tools|Options|Projects|VisualPerl). To specify a port number to be used by the current project, enter the port number in this field. See Configuring the Local Machine for Remote Debugging for more information.

Configuration Properties - Perl Options

• autosplit corresponds to Perl's -a command-line option. The value specified in the pattern field corresponds to Perl's -F command-line option.
• @INC/#include directories corresponds to Perl's -I command-line option; use either forward or back slashes to indicate subdirectories; separate multiple directories with semicolons (";").
• line end processing terminator corresponds to Perl's -l command-line option; specify octal values in the field to the right.
• while loop around script corresponds to Perl's -n command-line option.
• print line like sed corresponds to Perl's -p command-line option.
• run through C preprocessor corresponds to Perl's -P command-line option.
• enable some switch parsing corresponds to Perl's -s command-line option.
• tainting checks corresponds to Perl's -T command-line option.
• allow unsafe operations corresponds to Perl's -U command-line option.
• emit warnings corresponds to Perl's -w command-line option.
• strip off before #!perl -cd to corresponds to Perl's -x command-line option. Specify the destination directory in the field to the right.
• record separator corresponds to Perl's -0 command-line option. Enter octal values in the field to the right.

Configuration Properties - CGI

These pages are used to create and configure CGI variables used to emulate a CGI environment during debugging. For a description of CGI debugging, see Emulating a CGI Environment. To enable CGI debugging, set the Use_CGI_Debugging option on the Debugging page of the project properties to "Yes".

Build - Build Options

Build Options These options correspond to command-line functions used with the Perl Dev Kit, and are not displayed unless the Application Type on the General page of the Configuration properties is set to something other than "Standard Perl". For an explanation of each option in the context of each PDK tool, see Visual Perl and the Perl Dev Kit.

Build - Version Info

Version Info These options correspond to the -i command-line option for the Perl Dev Kit's PerlApp, PerlSvc and PerlCtrl, and are not displayed unless the Application Type on the General page of the Configuration properties is set to something other than "Standard Perl". This option is used to add version information to the output application. All values are taken as strings except 'filenumber' and 'productnumber', which must be of the form 'W.X.Y.Z' (where W, X, Y, and Z are numbers in the range 0-65535. X, Y, and Z are optional and default to 0).

Build - CommandLine

The Generated CommandLine field displays the command-line equivalent of the options entered on the Build Options and Version Info pages. To update the display in this field, click Apply. Use the Additional Options field to add additional command-line options to the build string. This page is blank unless the Application Type on the General page of the Configuration properties is set to something other than "Standard Perl".

Build - Build Events

The Build Events page is used to configure commands that should run before or after a component is built. In some cases, build events are automatically configured when you create a new component using the Visual Perl templates. For an explanation of build events as they apply to relevant PDK tools, see Visual Perl and the Perl Dev Kit.

Removing Projects from Solutions

If a project is no longer required by a Visual Studio .NET solution, you can remove it from the solution. This does not delete the project; it simply disassociates it from the solution. To remove a project from a solution:

1. In the Solution Explorer window, right-click the project name.
2. Select Remove.

Working with Files

In Visual Studio, it is possible to open a file that is not contained in a project using the folder icon on the standard toolbar. However, you cannot run or debug these files until you add them to a project. For more information on projects, see Configuring Projects

Adding Files to Projects

To add files to a project:

1. In the Solution Explorer window, right-click the project name.
2. If the item already exists on your system, select Add Existing Item..., then navigate to the location of the file.
3. If you are creating a new item, select Add New Item..., then select a document type and specify a name. By default, new documents will be created in the same directory as the project.

It is not necessary for all files in a project to be located in the same directory; however, if you move the project or associated files, you will have to re-specify file locations.

Installed Perl libraries do not need to be made part of a Perl project. You can step into Perl libraries while debugging; Visual Studio .NET will automatically make them part of a temporary "Miscellaneous Files" project. This project disappears when the solution is closed. The "Miscellaneous Files" project is a generic project, not a Visual Perl project, and thus has no configurable properties.

Removing Files from Projects

To remove a file from a project:

1. In the Solution Explorer window, right-click the file name.
2. Select Remove. Note that this does not delete the file; it simply removes the file from the project.

Working with Folders

You can add directories containing multiple folders and files, or you can add new folders. Note that these folders are virtual. That is, they do not correspond directly to folders on disk. If you add a folder to a project using the "New Folder" command, the folder will not be added on disk. Folders imported from disk using the "Import Folder" command will be added with the same names as files on disk. However, if you rename a folder on disk, it will not be renamed in the Solution Explorer, and vice versa.

Adding Folders to Projects

When importing existing folders from disk, use the Import Folder dialog box to set import options:

• Importing from Folder Displays the path location of the folder to be imported.
• File extensions to filter by Enter the extensions for the file types that you want to import. If no extensions are specified, all file types will be imported.
• Include child folders Select this check box to also import child folders within the specified folder.
• Flatten folder structure Select this check box to import the contents of a folder and one or more subfolders. If you choose this option, the folder structure will be discarded, and the files will be added beneath the selected folder in the Solution Explorer.

To add an existing folder to a project:

1. In the Solution Explorer, right-click the project, and select Add|Import Folder. A dialog box will be displayed prompting you to select a folder to import. Select a folder, and click Open. The Import Folder dialog box will be displayed.
2. Specify the appropriate options, and click OK. The folder will be added beneath the selected folder in the Solution Explorer.

To add a new folder to a project:

• In the Solution Explorer, right-click the project, and select Add|New Folder. The folder will be added beneath the selected folder in the Solution Explorer.
  
  Note: right-click a folder in the Solution Explorer and select Add|New Folder to add a folder beneath an existing folder.

Removing Folders from Projects

To remove a folder from a project:

• In the Solution Explorer, right-click the folder, and click Remove.

Editing Programs

Visual Perl supports many features that make writing and editing Perl programs easier. Note that these editor features continue to function while the debugger is running, so you can edit code while you debug it.

Double Clicking

Visual Perl makes some assumptions regarding double-clicking in the editor pane.

• Double-clicking on a regular expression selects the entire regular expression.
• Double-clicking on a variable name outside a comment or string selects the leading variable type character for scalars, arrays, and hashes.
• Double-clicking at the end of a line selects the last word on the line (if the line ends with a Perl keyword)

Syntax Coloring

Visual Perl supports syntax coloring. Configure colors in the Tools|Options|Environment|Fonts and Colors dialog by selecting the syntactic type and its corresponding color.

Perl-specific syntactic types include:

• Array
• Back Ticks
• Data Section
• Hash
• Here
• POD
• Punctuation
• Operator
• RegEx Match
• RegEx Substitution
• Scalar
• Typeglob

Some language elements are common to multiple languages, including Visual Perl. The coloration settings will apply in all languages where these elements are used. Common syntactic types supported by Visual Perl include:

• Comment
• Identifier
• Keyword
• Number
• String

Syntax Checking

Visual Perl's syntax checking function monitors the validity of your code as you type. To enable syntax checking, select Tools|Options|Text Editor|Perl|Visual Perl Specific, and ensure that the Check syntax while editing box is checked. See Configuring Editor Behavior for more information about configuration options.

When a syntax error is detected, the error is underlined by a red wavy line. If you hover the mouse pointer over the error, an explanatory pop-up tip will describe the nature of the error. Also, the error will be automatically added to Visual Studio's Task List.

Keyword Tips

When you enter a keyword in a keyword context (not in a string, comment, or POD statement) followed by an open parenthesis, Visual Perl displays a keyword tip. This pop-up shows the variations of a given keyword, and the syntax of each variation. If the keyword has multiple usages, each tip will be numbered; use the arrow keys or click on the arrows in the tip to cycle the tip display.

If a keyword has multiple arguments, the arguments are consecutively highlighted in bold text. That is, each time a comma is entered in the argument set, the next argument in the keyword tip is highlighted in bold.

Note that when keyword arguments use spaces as delimiters, Visual Perl does not display pop-up keyword tips. These keywords include: exec, grep, map, no, print, printf, sort, sub, system, use and write.

To enable or disable keyword tips, check or uncheck Parameter information under Tools|Options|Text Editor|Perl. See Configuring Editor Behavior for more information.

IntelliSense

To enable IntelliSense, ensure that the "Auto list members" box is checked in the Statement Completion section of Visual Perl's Text Editor Options dialog. To view the dialog, select Tools|Options|Text Editor|Perl. See Configuring Editor Behavior for more information.

In some cases, the pop-up IntelliSense list is displayed automatically; in other cases, you must use Ctrl+J or Alt+Right Arrow to display the list.

• Automatic IntelliSense Display
  • Scalar Bound to a Class or Web Service: When the characters "-@gt;" follow a scalar that has been previously assigned to a class or Web service, methods and properties within the class or Web service will be automatically displayed in the pop-up IntelliSense list. When the "-@gt;" characters are followed by an open brace, properties within the method are automatically displayed.
  • "use" Statements: Following a "use" statement, directories and modules in the Perl tree are automatically displayed in the pop-up IntelliSense list. Further, if you select a directory or module from and follow it with two colons, directories and modules beneath the previous selection are displayed.
• Manual IntelliSense Display

  Use the Ctrl+J key combination to invoke the IntelliSense pop-up (or select the menu option Edit | IntelliSense | List Members). The contents of the dialog will depend on the current cursor position. If you have entered a portion of a statement that is unique among IntelliSense items in the current context, you can automatically complete the word using the Alt+Right Arrow key combination (or select the menu option Edit | IntelliSense | Complete Word).

  • Redisplay of Automatic IntelliSense: If you have cleared an IntelliSense pop-up window that was automatically displayed, you can re-display it using the Ctrl+J key combination.
  • Keyword Tips
  • Names of subs in Current Buffer
  • Modules and Packages Brought in with "use" Statements

To position the pop-up list, type one or more of the starting letters of the desired item. Alternatively, use the keyboard arrow keys to navigate the list items. To insert an item from the pop-up list at the current cursor position, highlight the item in the list and press Enter or Tab.

To re-display the pop-up list, type Ctrl+J. The editing cursor must be within the segment of the statement where the pop-up list is applicable. For example, to re-display the list of methods for the module "SOAP", the editing cursor must be after the colons, but before the semicolon that ends the statement.

IntelliSense provides pop-up lists of valid values for the following language elements:

• Perl Method and Module Names: When a module name is followed by two colons, Visual Perl displays a pop-up list box with the methods, modules and directories contained by the module.
• COM Objects Loaded by the Win32::OLE Module: When the Win32::OLE module is brought in via a "use" statement, methods and properties for Win32 COM classes are displayed in the IntelliSense drop down list. (The target application must be installed on your system in order to provide IntelliSense.)

  Visual Perl distinguishes between methods and properties within objects. For example:

  my $var = Win32::OLE->new("Excel.Application");
  $var-> (methods and properties off the main object are displayed in the drop-down)
  $var->Properties-> (methods and properties within the selected method are displayed)
  $var->Properties->{ (only properties within the method are displayed)
  
  

  Additionally, you can transfer the Win32::OLE IntelliSense properties to another variable simply by associating the original variable with a new variable. For example:

  $var = Win32::OLE->new("Excel.Application");
  my $var2 = $var;
  

  In this example, $var2 will have the same IntelliSense properties as $var.

• Web Services: Visual Perl provides two methods for loading Web services: you can bind a Web service to a variable, or create a Web Reference in your project that contains a proxy for the Web service. See Using Web Services for instructions. Note that the IntelliSense properties can be transferred from one variable to another simply by associating the original variable with a new variable.
  
  
  • Web Services Bound to a Variable: If you are using the WebService or SOAP::Lite modules to access Web services, Visual Perl provides a pop-up list of methods in the Web service when the variable to which the Web service is assigned is followed by "->". Further, after an open parenthesis, arguments for the Web service are presented in a pop-up hint box.

    There are two ways to enable IntelliSense for Web services:

    1. $var = WebService::ServiceProxy->new(url);
    2. $var = SOAP::Lite->service(url);

    In both cases, url must be a constant string, corresponding to the URI for a WSDL file. Also, this version of Visual Perl is not able to parse WSDL files from some services. You can successfully consume these services using Perl-based tools, but Visual Perl won't be able to prompt with IntelliSense.

  • Web Services Defined as Web References: Modules defined as Web References, and methods and classes defined within the Web service, will be displayed in the pop-up tip box invoked using the Ctrl+J key combination.

    There are two "styles" of Web service: "DOC" (Microsoft .NET implementation) and "RPC" (SOAP implementation). The method by which IntelliSense for methods is implemented depends on the style of the Web service.

    • RPC style: Methods contained in an RPC-style Web service will be included in the pop-up IntelliSense list when "->" follows the namespace and module name. For example:

      my $var = www_webservice_com::WSproxy->

    • DOC style: Methods contained in a DOC-style Web service will be included in the pop-up IntelliSense list when "->" follows the namespace, module name and class. The class name will be the name of the proxy module followed by the text "Soap". For example:

      my $var = www_webservice_com::WSproxy::WSproxySoap->

Smart Indenting

When you enable Smart Indenting in the Tools|Options|Text Editor|Perl|Tabs dialog, Visual Perl performs advanced auto-indenting in the editor.

Smart Indenting within Control Structures

Smart indenting distinguishes between control structures and hash objects, and indents accordingly. When an open brace "{" occurs in the context of a control structure, the indentation level is incremented by the Indent size value specified in the Options dialog. After a close-brace "}", the indentation level is decremented by the same value.

If the indentation value is manually modified (for example, by manually adding additional spaces), the number of manual spaces will be added to the number of spaces configured for the Indent size, thus allowing the local context to take precedence over the global setting.

For example:

while ($oldval != 1) {
    if ($oldval % 2) {
        $oldval = 3 * $oldval + 1;
    } else {
        $oldval /= 2
    }

Smart Indenting and Hash Objects

When an open bracket or parenthesis is used, the indentation level is set to the column following the bracket or parenthesis. After the closing bracket or parenthesis, the cursor will return to the original position. Open braces used in the context of a hash objects are indented in a similar manner. These constructs can nest. For example:

my %phone_book = (
                  pizza => '967-1111',
                  help => '911',
                  info => '411',
                  'area-codes' => {
                                   'ny' => 212,
                                   'sf' => 415,
                                   'sj' => 408
                                   },
                  );

Smart Indenting and "Here" Documents, Multi-Line Strings and POD

After the beginning of a "here" document, the cursor will be placed at the left margin. After the beginning of a POD section, the cursor will also be placed at the left margin. (However, you must manually position the start of the POD section at the left margin.) Pressing Enter during a multi-line string will also place the cursor at the left margin.

At the end of the here-document or POD section, the cursor position will return to the position that prevailed at the start of the here-document or POD section.

For example:

if ($test1) {
    print $a;
    if ($test2) {
        print $a, $b, <<HereDoc
content
HereDoc
        |

Smart Indenting and Backspacing

The backspace and delete keys are aware of tab positions. For example, if the cursor position follows a tab (or an equivalent number of spaces) the backspace key will cause the tab before the cursor to be deleted, rather than a single space.

Code Folding

Code folding is used to collapse and expand sections of your Perl program. To enable code folding, select Tools|Options|Text Editor|Perl|Visual Perl Specific, and ensure that the Show code folding box is checked.

Fold points are indicated on the left margin by minus symbols. Visual Perl determines fold points by monitoring bracket, brace and parenthesis constructs, POD sections and "here" document markers. When a section of code has been folded, it is indicated by a plus symbol. The folded code can be displayed by hovering the mouse pointer over the ellipses that appear to the right of the first line of the collapsed block. Collapsed code blocks will be automatically opened during debugging or editor-driven modifications.

Commenting Blocks of Code

To automatically comment the currently selected block of code, press Ctrl+K, Ctrl+C or select the menu item Edit|Advanced|Comment Selection. Visual Perl adds a '#' character to the start of each line in the selection. To automatically uncomment the currently selected block of code, press Ctrl+K, Ctrl+U or select menu item Edit|Advanced|Uncomment Selection. Visual Perl removes the first '#' character in each line in the selection.

Brace, Bracket and Parenthesis Matching

Visual Perl monitors brace, bracket and parenthesis constructs, making it easy to identify and select blocks of code.

• When the editing cursor passes over a brace (or bracket or parenthesis), the brace will be displayed in a bold font, and the corresponding opening (or closing) brace will also be displayed in a bold font.
• Use Ctrl+] to move the editing cursor from its current position to the corresponding opening or closing brace (or bracket or parenthesis). The editing cursor must be adjacent to a starting or ending brace; the editing cursor will move to the corresponding opening or closing brace.
• Use Shift+Ctrl+] to select a block of text within braces (or brackets or parentheses). The editing cursor must be adjacent to a starting or ending brace; the text between the braces (and the braces themselves) will be selected.

Indentation Formatting

Visual Perl provides sophisticated indentation formatting.

To format the indentation of a selection of text:

• In the editor, select the text you wish to format.
• Select Edit|Advanced|Format Selection (Ctrl+K Ctrl+F). The block of code will be indented according to the bracket constructs in the code block and the bracket constructs that surround the code blocks. The indentation size is based on the value specific in the Indent Size field in the Perl Options (Tools|Options|Text Editor|Perl|Tabs|Indent size).

To format the indentation of an entire document:

• Select Edit|Advanced|Format Document (Ctrl+K Ctrl+D). The document will be indented according to its bracket constructs. The indentation size is based on the value specific in the Indent Size field in the Perl Options (Tools|Options|Text Editor|Perl|Tabs|Indent size).

Adding Entries to the Task List

Visual Studio's Task List is used to maintain a list of outstanding tasks for each Visual Studio solution. To display the Task List, select View|Other Windows|Task List.

Ensure that the Task List is configured to display all tasks. To change the Task List filter, right click in the Task List pane, and select Show Tasks| All.

Visual Perl will automatically add items to the Task List associated with the current solution as follows:

• Syntax Checking If syntax checking is enabled, syntax errors will be added as items to the Visual Studio Task List.
• TODO Comments Add items to the solution's Task List by entering "TODO" comments in the program in the following format:
  
  # TODO: comments

Open a Module in the Editor Pane

When your program uses an external Perl module, you can open the module in the editor pane using the Open Document option on the right-mouse context menu. To enable the menu option, right-click while the editing cursor is positioned over the module name.

Using Web Services

Visual Perl provides IntelliSense for Web services. In order to provide IntelliSense for Web services, the Web service must either be bound to a variable, or be assigned to the project as a "Web Reference". Both methods are described below.

Binding a Web Service to a Variable

While this is the simplest method of accessing Web services, it is more resource-intensive than the Web Reference method as the Web service must be parsed each time it is called.

There are two ways to bind a web service to a variable:

1. $var = WebService::ServiceProxy->new(url);
2. $var = SOAP::Lite->service(url);

In both cases, url must be a constant string, corresponding to the URI for a WSDL file. Also, this version of Visual Perl is not able to parse WSDL files from some services. You can successfully consume these services using Perl-based tools, but Visual Perl won't be able to prompt with IntelliSense.

Using Perl to Call a Web Service

Visual Perl 1.8 generates slightly different Web service proxy classes than in previous versions. The classes are backwards-compatible with old code, so if you built Web service proxies with earlier versions of Visual Perl, you will not need to change the proxies or the clients after upgrading to Version 1.8.

Prior to Version 1.8, the client code looked like this:

With the new proxy generator, each method throws an exception if the service returns a fault, or it returns the underlying result object. Generated proxies now look as follows:

In Version 1.8, the calling client has been simplified as follows:

You can easily update proxies generated with previous versions of Visual Perl by right-clicking on the namespace (e.g., www_xmethods_net) in the Solution Explorer and selecting Update Web Reference.

Creating a Web Reference

The Web Reference method generates a proxy module for the Web service based on the service's WSDL description. This proxy is added to the project as a Web Reference. This method is more efficient than binding a Web service to a variable, as the proxy module is local.

Note: if you are developing on a machine that is behind a firewall and receive an error message stating that your proxy settings are "not configured correctly for Web discovery," you will have to explicitly specify a proxy server for Internet Explorer connections.

To create a Web Reference to the Web service:

1. In the Solution Explorer, right-click the project name and select Add Web Reference.
2. Enter the entire address to the WSDL of the desired Web service in the Address field. For example:
   
   http://web.service.loc/service/wsdl
   
   Visual Perl will contact the Web service and download the WSDL description.
3. Click Add Reference to add the Web service to the project.

After the Web service has been added to the project, you must call the Web service with "use" or "require" statements. For example, if your Web Reference was called "www_webservice_com", and the proxy was called "WSproxy.pm", you could call the Web service with the following statement:

Modules defined as Web References, and methods and classes defined within the Web service, will be displayed in the pop-up tip box invoked using the Ctrl+J key combination as described in the IntelliSense topic.

Using the Rx Toolkit

Visual Perl's Rx Toolkit is ActiveState's powerful tool for creating and debugging regular expressions. Regular expressions are sets of symbols and syntactic elements used to match patterns of text. Regular expressions are not a language or a tool; they are a syntax convention which many languages and tools support.

Regular expressions are used to perform text-manipulation tasks, such as searching and replacing text or testing for certain conditions in a text file or data file. Email filtering programs often use regular expressions to sort incoming email by topic or by sender.

Note: the Rx Toolkit requires ActivePerl version 626 or greater.

To open Visual Perl's Rx Toolkit, select View|Rx Toolkit.

Rx Toolkit Component Overview

The Rx Toolkit form is made up of the following components:

• Control Buttons - Movement The movement buttons are used to apply the regular expression to the data. You can step forward or backward in single increments, where each component of the expression is tested against each node of data, or you can run the regular expression forward or backward through the entire expression and data set.
• Check Boxes - Modifiers and Metacharacters The Rx Toolkit Modifiers are used to apply "rules" to the regular expression match criteria. Modifiers include Global, Multi-line Mode, Ignore Case, Single-line mode, and Extended. Regular expression metacharacters, quantifiers and anchors are accessed from the drop-down list by clicking the arrow button to the right of the "regular expression" pane.
• Enter a Regular Expression regular expressions are entered in this pane
• Enter a string to match against test data is entered in this pane.
• Group Match Variables this pane displays the matches found by applying the regular expression to the data set.

Creating Regular Expressions

1. Enter the regular expression in the regular expression pane. The following "rules" apply:
   • regular expression can include metacharacters, anchors, quantifiers, digits, and alphanumeric characters
   • regular expressions are not enclosed in forward slashes "/"
2. Add metacharacters, quantifiers and anchors to the regular expression. From the drop-down list, select the desired elements. These will be inserted in the regular expressions at the current position of the cursor. These elements may also be manually added to the regular expression.
3. Select modifiers for processing the regular expression. Modifiers must be assigned by selecting the modifier buttons; they cannot be manually entered in the Enter a Regular Expression pane:
   • Global This option will match all occurrences of the specified regular expression. Use this when you want Rx Toolkit to cycle through several repetitions in your test string.
   • Multi-line Mode This option will allow the caret "^" and dollar "$" symbols to match next to newline characters. Use this when your pattern is more than one line long and has at least one newline character.
   • Ignore Case This option will ignore alphabetic case distinctions while matching. Use this when you don't want to specify the case in the pattern you're trying to match.
   • Single-line Mode This option will allow the dot "." to match newline characters. Use this when your pattern is more than one line long and has at least one newline character.
   • Extended This option will ignore whitespace and comments. Use this when you want to print your regular expression or when you want to annotate your regular expression with comments.

Node Tips

Node Tips

The RX Toolkit provides node tips in the status bar beneath the middle pane to help you design an effective regular expression. You can view these tips by selecting the characters in a regular expression.

For example, if the regular expression is (.*)(\d+) and you select each character in order from left to right, the Rx Toolkit status bar displays:

(    Capture group $1
.    Match any one character (except newline)
*    Match <.> 0 or more times
)    Capture group $1
(    Capture group $2
\d   Match any numeric character
+    Match <\d> 1 or more times
)    Capture group $2

Evaluating Regular Expressions

1. Enter the Regular Expression In the top pane, enter a regular expression.
2. Enter the string to match In the pane labeled Enter a string to match against, enter the data to which to want to apply the regular expression. You can also load data into this pane from a file; click the File button to browse for files on your system.
3. Select Modifiers Select modifiers as desired by clicking the modifier buttons.
4. Step though the data Use the movement buttons to step through the application of the regular expression to the data. The results of the process will be displayed in the Variable and Value fields of the Group Match Variables pane.
5. Analyze the Results As you step through the data, matches are displayed in the Variable and Value fields. The Variable field lists variables by name; the Value field lists the contents of the variables. If you click a variable name or variable value, the corresponding pattern in the test string and the corresponding part of your regular expression is highlighted. Review your output carefully. When you try to match a pattern you may match a longer or shorter pattern than you expect.

Examples of Regular Expressions

A Regular Expression Using the Global Modifier

The Global modifier matches all occurrences of the specified regular expression. Use this when you want Rx Toolkit to cycle through several repetitions in your test string.

To match the following test string

testing123
foobar75

you could use the following regular expression with Global selected

(.*?)(\d+)

The Variable and Value fields show the following results:

$1 (match1)    testing
$2 (match1)    123
$1 (match2)    foobar
$2 (match2)    75


This regular expression matches the entire test string. The .* matches any character zero or more times, the ? tells * to not be greedy, which means (.*?) matches the words "testing" and "foobar". The (\d+) matches any digits one or more times, which matches the numbers "123" and "75". The Global modifier means that Rx Toolkit matches more than the first occurrence of the pattern. That's why Rx Toolkit matched $1 and $2 twice.

A Regular Expression Using the Multi-line Mode Modifier

The Multi-line Mode modifier allows ^ and $ to match next to newline characters. Use this when your pattern is more than one line long and has at least one newline character.

To match the subject part of the following test string

"okay?"

you could use the following regular expression with Multi-line Mode selected

^(\"okay\?\")

The Variable and Value fields show the following results:

$1    "okay?"

This regular expression matches the entire test string. The ^ matches the beginning of any line. The \" matches the double quotes in the test string """. The match matches the literal word "okay". The \? matches the question mark "?". The \" matches the terminal double quotes """. There is only one variable group in this regular expression, and it contains the entire test string.

A Regular Expression Using the Multi-line Mode, Ignore Case and Global Modifiers

If you want to match the contents of a standard email header, you would compose your regular expression and apply three modifiers: multi-line, ignore case, and global. To match the following test string

From: joe@isp.com
To: sue@nisp.com
Cc: bob@anisp.com
Subject: Use modifiers in regular expressions


you could use this regular expression with Multi-line Mode, Ignore Case, and Global selected

^([a-z]+):\s+(.+?)$

The Variable and Value fields show the following results:

$1 (match1)    From
$2 (match1)    joe@isp.com
$1 (match2)    To
$2 (match2)    sue@nisp.com
$1 (match3)    Cc
$2 (match3)    bob@anisp.com
$1 (match4)    Subject
$2 (match4)    Use modifiers in regular expressions


This regular expression matches each part of the email header. The ^ matches the beginning of any line. The ([a-z]+) matches any lowercase letter one or more times. The : matches a colon and the \s+ matches a space one or more times. The (.+?) matches any character one or more times. The $ matches the end of a line.

Multi-line Mode allows caret "^" to match the beginning of any line. Without the multi-line mode modifier, caret "^" matches the beginning of a string. Ignore Case allows Rx Toolkit to match any lower or uppercase letter. Without the ignore case modifier, there would be no group match variables. Global allows Rx Toolkit to keep matching after the first match is found. Without global, Rx Toolkit only matches the first line, "From: joe@isp.com".

Running Programs

Run the "StartUp Project" by invoking the menu item Debug|Start Without Debugging (or press Ctrl+F5). In a multi-project solution, the StartUp Project's name is displayed in bold text in the Solution Explorer. To run a different project in a multi-project solution, right-click the desired project name in the Solution Explorer and select Set as StartUp Project

To change the options for running a program, right-click the project name in the Solution Explorer and select Properties. See Configuring Projects for information about project properties.

Running Programs in the Shell Window

To run programs in a temporary cmd window (the "shell window"), set the value in the RunInShell field on the Debugging page of the Project Properties to "Yes". This run behaves as if it were started from a regular shell window. Input is entered in the same manner as on the command line, and sent to the program by pressing the Enter key. To indicate end of input, press Ctrl+Z

Running Programs in the "Run" Window

If the value in the RunInShell field on the Debugging page of the Project Properties is set to "No", the program runs in Visual Studio's Run window. If input is required, enter the desired characters and press Enter to proceed. To indicate end of input, press Ctrl+Z

To cut, copy or clear the contents of the Run window, click the right mouse button and select the desired action from the context menu.

Debugging Programs

Visual Perl includes a full-featured debugger which you can use to analyze your Perl programs.

Start Debug sessions by selecting either the Debug|Step Over (F10) or Debug|Step Into (F11). The session can also be started by pressing Debug|Start (F5), but if there are no active breakpoints in the program, the program will run to the end more slowly than if you select Debug|Start Without Debugging (Ctrl+F5).

Visual Studio .NET provides three visual cues to indicate that the debugger is active:

• The current line is indicated with a yellow arrow in the breakpoint margin.
• The debug toolbar is only visible during Debug mode.
• The menu options and window configuration changes between editing mode and debugging mode. For example, only some of the functions accessible from the Debug|Windows|... menu are visible while you are editing, but all are visible in debugging mode.

Debugger Commands

Debugger commands can be invoked from the Debug menu, from the Debug Toolbar buttons, or by keyboard shortcuts.

• Debug|Start (F5) runs the program to the first breakpoint. If the debugger is already running, this command is called Debug|Continue. If there are no active breakpoints in the program, the program will run to the end more slowly than if you select Debug|Start Without Debugging.
• Debug|Step Into (F11) will run the program until the first "executable" line is encountered. The debugger will stop before executing that line. Subsequently, Step Into will execute the line at the current debugger position (indicated by a yellow arrow on the breakpoint margin), advance to the next executable line, and then pause.
• Debug|Step Over (F10) executes the current line of code. If the current line of code calls a function, method, or procedure, then the function, method, or procedure is executed in the background.
• Debug|Step Out (Shift+F11) executes the code in a function or method without stepping through the code line by line. Program execution is suspended again on the line of code following the function or method call in the calling program.
• Debug|Stop (Shift+F5) stops the debugger.

Debugger Windows

The following windows are accessible during debug sessions:

Exceptions (Ctrl+Alt+E)

Not Applicable to Visual Perl

Running Documents (Ctrl+Alt+N)

Not Applicable to Visual Perl

Autos (Ctrl+Alt+V, A)

Not yet supported

Locals (Ctrl+Alt+V, L)

Proximity variables. These are the variables referenced and/or set in the vicinity of the current line. It's a convenient way of monitoring the program state without having to supply a large number of variable names. Note that you can expand hashes and arrays in this window.

This (Ctrl+Alt+V, T)

Same as the Locals window

Watch (Ctrl+Alt+W, number)

Use to change the value of variables during debugging, to add a variable, and to calculate new values based on variables. Note that you can expand hashes and arrays in this window.

Immediate (Ctrl+Alt+I)

Not yet supported

Call Stack (Ctrl+Alt+C)

Displays the function name, line number and file for each stack frame in the program. You can control whether to show filenames and / or line numbers by right-clicking in the call stack window and checking the corresponding entries.

Threads (Ctrl+Alt+H)

Not yet supported

Modules (Ctrl+Alt+U)

Not applicable

Breakpoints

Breakpoints are indicated by red circles on the left margin of the editor pane. Breakpoints have two states: enabled and disabled. Enabled breakpoints are indicated by solid red circles; disabled breakpoints by empty red circles. The debugger will not pause at disabled breakpoints. Breakpoints can be manipulated in several ways:

• Click the breakpoint margin on the left side of the editor window to set a breakpoint. Click an active breakpoint in order to remove it.
• Select Debug|Window|Breakpoints (Ctrl+Alt+B) to display the Breakpoint window, where you can add, remove, activate or deactivate breakpoints.
• Select Debug|New Breakpoint (Ctrl+B) to display the New Breakpoint dialog.
• Use the right-mouse context menu to add, remove, disable or enable breakpoints.

Viewing and Changing Variable Values

Visual Perl provides a number of ways to watch and modify variables as you debug:

Locals Window

The Locals window displays variables referenced and/or set in the vicinity of the current line. To display the Locals window, select Debug|Windows|Locals or use the keyboard shortcut Ctrl+Alt+V, L.

Watch Window

Watch Windows are used to view and alter specific variables. To display a Watch window, select Debug|Windows|Watch, and then select a specific Watch window. Alternatively, use the keyboard shortcut Ctrl+Alt+W, number.

To add a variable to a Watch window:

• Select the variable in the editor pane, then drag it to the Watch window (or use the right-mouse context menus to copy and paste).
• Drag the variable from the Locals window to the Watch window (or use the right-mouse context menus to copy and paste).

To change the name or values of variables in a Watch window, double-click in the Name or Value field and make the desired changes.

To convert a variable to an array, enclose the variable name in (square) brackets. This function is useful for analyzing the contents of a variable, and can be combined with Perl language functions. For example, say the variable $foo contained three lines of text, separated by newlines. If you change the name of the variable from $foo to [split(/\n+/,$foo)], the variable would be converted to an array (because of the square brackets), and each line of text in the original variable would be displayed as an element of the array (because of the "split" function).

Variable Value Hover Tips

While the debugger is running, you may view variable values by hovering the mouse pointer over the desired variable. If the variable is a scalar, or a function with no arguments, the value will display in a hover tip. To view the value of a function that operates on a variable or value, or an interpreted variables or regular expression, select the entire expression, then hover the mouse pointer over the selected text.

Call Stack

The Call Stack displays the name and language of each function that is currently on the stack. To display the Call Stack, select Debug|Windows|Call Stack. By selecting different stacks, you can view the variables (in the Locals windows) particular to each stack. To display the position where the stack changed in the editor pane, double click the stack in the Call Stack window.

Emulating a CGI Environment

Using Visual Perl, you can create a simulated CGI environment which allows you to debug CGI applications without initiating a Remote Debugging session. The main difference between running a Perl program from the command-line and running it as a CGI process is that the CGI program has a set of environment variables that let the user's web browser pass settings to the program.

Currently Visual Perl supports only GET-type CGI programs.

To configure CGI debugging, right-click the project name in the Solution Explorer, select Project Properties and select the Debugging folder on the left. Set the Use_CGI_Environment option to "Yes".

Select the CGI folder to configure environment variables for CGI programs. The Environment page lists environment variables that are commonly configured on a web server. These variables are passed to programs invoked using the "system" keyword.

• To add a new variable click the New... button and enter the variable name and value.
• To modify an existing variable select the variable and click the Edit button.
• To delete a variable select the variable and click the Delete button.

The Parameters page is used to configure environment variables that will be called by the CGI program. Variable values can include any alphanumeric characters; variable names cannot include extended characters.

• To add a new variable click the New... button and enter the variable name and value.
• To modify an existing variable select the variable and click the Edit button.
• To delete a variable select the variable and click the Delete button.

In order to emulate a CGI environment during debugging, your script must call the CGI.pm module through "use" or "require" statements.

Remote Debugging

Visual Perl can be used to debug Perl programs running in other processes on the same machine, on other Windows machines, and even other types of machines that have a compatible version of Perl installed.

It is not necessary to have administrative access on the remote machine in order to debug programs remotely. The necessary variables are configured at the user level, rather than the system level.

Configuring the Local Machine for Remote Debugging

Configure the Environment

If the Perl Dev Kit is installed on your system, you must change some environment settings in order to use Visual Perl's Remote Debugging features.

1. Rename the PERL5DB Registry Setting: From the Windows Start menu, select Run, and enter regedit in the dialog box. In the left panel of the Registry Editor, select HKEY_LOCAL_MACHINE|SOFTWARE|Perl. In the right panel, right-click the PERL5DB entry, select Rename, and change the name to xPERL5DB.
2. Rename the PERLDB_OPTS Environment Variable: On the Windows desktop, right-click "My Computer" and select Properties. On the Advanced tab, click the Environment Variables button. In the System Variables pane, select PERLDB_OPTS. Click the Edit button, and change the Variable Name.
3. Stop the Perl Socket Service: In the Windows Control Panel, select Administrative Tools|Services. In the right panel, select Perl Socket Service. Change the Startup type to Manual. Click the Stop button to stop the service.

To revert to using the Perl Debugger included with the Perl Dev Kit, undo the above changes.

Configure the Project Properties

To debug Perl programs located on remote machines, you must identify the port that controls the remote process (the "Remote Port"). The values for this ports can be configured globally, or can be configured individually for each Perl project.

The port numbers specified for the Remote Port must be the same as the port number specified in the Perl5DB_OPTS variable on the remote machine. See Configuring the Remote Machine for Remote Debugging for more information.

To configure default port values for remote debugging, select Tools|Options|Projects|VisualPerl. Set port values for the Default Remote Port.

To configure port values for a specific project, right-click the project name and select Properties, then select the Debugging option. Configure the port number for the Remote Port. The default value for the Default Remote Port is 3000. Port values configured in the project properties override the default values configured in the Options dialog. Port values must be between 256 and 32767.

Configuring the Remote Machine for Remote Debugging

1. Copy the version of perl5db.pl that is distributed with Visual Perl to the remote machine. If you installed Visual Perl in the default location, the file can be found in the C:\Program Files\ActiveState VisualPerl directory. On the remote machine, copy this file to the directory that contains the Perl program you want to debug. Alternatively, you could create a new directory for Visual Perl's perl5db.pl and copy the Visual Perl version of the file to the new directory.
   
   Note: do not copy perl5db.pl to Perl's "lib" directory on the remote machine, as this will overwrite the standard perl5db.pl file with the version that is specific to Visual Perl.



2. On the remote machine, specify the location of Visual Perl's version of perl5db.pl. (If you are running a web server on the same machine where Visual Studio .NET is installed, set this variable in the web server's environment.) In a command shell, enter the following:
   
   
   set PERL5LIB=path_to_perl5db.pl (where "path_to_perl5db.pl" is the directory where Visual Perl's perl5db.pl resides)
   
   
   For example, if the remote machine is running Windows and perl5db.pl was copied to the directory C:\misc\perl, enter the variable as follows:
   
   
   set PERL5LIB=C:\misc\perl
   
   
   If the remote machine is running a flavor of Unix and perl5db.pl was copied to the directory /usr/home/me/perl/vperl_debugger, enter the variable as follows:
   
   
   export PERL5LIB=/usr/home/me/perl/vperl_debugger
   
   
3. Ensure that the version of Perl on the remote machine is compatible with the version of perl5db.pl included with Visual Perl. On the remote machine, run the following command on the version of perl5db.pl that is distributed with Visual Perl:
   
   
   perl -c perl5db.pl
   
   
   If Perl responds with a message similar to
   
   
   perl5db.pl syntax OK
   
   
   then the file is usable on the remote system. If there are error messages, they need to be fixed. The only problem currently anticipated is that near line 1522, the directive
   
   
   no warnings;
   
   
   should be commented out if Perl issues the error message "Can't locate warnings.pm in @INC...". Doing this might produce some ignorable warning messages while debugging.



4. On the remote machine, set the PERLDB_OPTS variable, which will tell the Perl program on the remote machine to connect to a debugger on the local machine.
   
   
   • Replace hostname with the domain name of the local machine running Visual Studio.
   • Replace RemotePortNumber with the Remote Port number specified in the Project's Properties or the Visual Studio Options dialog. See Configuring the Local Machine for Remote Debugging.
   • The variable definition must be on one line.
   • Remote Debugging is not supported on remote machines running Windows 9x.

   The syntax of the variable is as follows:

   Windows XP and 2000 Systems

   set PERLDB_OPTS=RemotePort=hostname:RemotePortNumber PrintRet=0

   Windows Me

   Use the MSCONFIG utility to configure the PERLDB_OPTS variable. From the Windows Start menu, select Run, then enter MSCONFIG in the dialog. Select the Environment tab, and create a new variable with the Variable Name of PERLDB_OPTS, and the Variable Value of:

   RemotePort=hostname:RemotePortNumber PrintRet=0

   Unix Systems

   PERLDB_OPTS="RemotePort=hostname:RemotePortNumber PrintRet=0"
   
   export PERL5DB_OPTS
   
   

Using Remote Debugging

On the local machine, ensure that the Perl project is configured to allow Remote Debugging. To check the project's configuration, right-click the project name in the Visual Studio Solution Explorer, select Properties, and ensure that the value in the DebugMode field on the Debugging page is set to "Remote Debugging". Also, ensure that the Perl project is configured as the StartUp Project. Note that the project does not necessarily contain any programs; when the remote program runs, Visual Studio will treat it as a local program.

Start debugging by selecting Debug|Step Over (F10) or Debug|Step Into (F11). A dialog box will say that Visual Perl is waiting for the remote session to start.

Run the Perl program on the remote machine. You may use Telnet or VPN to start the remote program, or a user at the remote site may manually run the program. Ensure that the remote Perl program is launched with the "-d" command-line switch in order to invoke debugging. For example:

perl -d arguments program_name program_arguments

If you are debugging an embedded Perl program (for example, a CGI script), set the remote web server's environment variables to include PERL5LIB and PERLDB_OPTS as described in the Configuring Remote Debugging section above. Ensure that the remote Perl program is configured to run with the "-d" switch. (For this reason, you should debug programs on test, rather than live, servers wherever possible.) Then run the remote Perl program through a web browser.

Visual Perl may appear to be frozen while contact is made between the local and remote machines. Generally, this pause will only last for a moment; then Visual Perl will display the remote program's code within Visual Studio, and you can proceed as usual by setting breakpoints, browsing variables, etc. However, if a problem occurs while establishing a connection (such as differing Remote Port values on the local and remote machines), Visual Perl will keep trying to establish a connection for five minutes. In this case, you can kill the debugger by ending the sl_perl_debugger.exe (or sl_per~d.exe) task in the Windows Task Manager. This will return control to the Visual Studio editor.

Visual Perl and the Perl Dev Kit (PDK)

Visual Perl provides a graphical interface for the tools included in ActiveState's Perl Dev Kit (PDK).

Ensure that the location of the PDK installation is properly configured in the Visual Perl Project Defaults.

Applications (PerlApp)

PerlApp is used to generate executable-file wrappers around the current project's main Perl program. This option wraps the project's main Perl program in a file with an executable (.exe) extension, so that the program can be run from the command line.

Services (PerlSvc)

PerlSvc is used to generate a Windows service wrapper around the current project's main Perl program. This option wraps the project's main Perl file a Windows Service executable.

When you create a new Service, the template will automatically generate a build event that will install the component after it is built.

Control Library (PerlCtrl)

PerlCtrl is used to generate a standalone ActiveX control from the current project's main Perl program. This option wraps the project's main Perl file in an ActiveX component.

When you create a new Control Library project, the template will automatically generate a harness script used for debugging the control. The template will generate a a PostBuildCommand that registers the control after the build. You can also set a PreBuildCommand that unregisters any previously registered control. Then, if the build fails, there wi