WiseScript Package Editor Reference...
Copyright © 2009 Symantec Corporation. All rights reserved. Symantec, the Symantec Logo, and Altiris are trademarks or registered trademarks of Symantec Corporation or its affiliates in the U.S. and other countries. Other names may be trademarks of their respective owners.
The Technical Support group also creates content for our online Knowledge Base. The Technical Support group works collaboratively with the other functional areas within Symantec to answer your questions in a timely fashion. For example, the Technical Support group works with Product Engineering and Symantec Security Response to provide alerting services and virus definition updates.
Licensing and registration If your Symantec product requires registration or a license key, access our technical support Web page at the following URL: www.symantec.com/techsupp/ Customer service Customer service information is available at the following URL: www.symantec.com/techsupp/ Customer Service is available to assist with the following types of issues:...
Consulting Symantec Consulting Services provide on-site technical Services expertise from Symantec and its trusted partners. Symantec Consulting Services offer a variety of prepackaged and customizable options that include assessment, design, implementation, monitoring, and management capabilities. Each is focused on establishing and maintaining the integrity and availability of your IT resources.
Contents Technical Support ............3 Chapter 1: Introduction .
Adding Contents of Directories ..........52 Specifying Installation File Settings .
Customizing the List of Actions..........97 Types of Scripts .
Delete File(s) ............146 Delete SVS Layer .
Read INI Value ............186 Read/Update Text File .
Disabling the Directory Already Exists Message ....... . . 225 Keeping Disabled Controls From Reactivating.
Chapter 1 Introduction This chapter includes the following topics: About WiseScript on page 12 WiseScript Benefits on page 13 Getting Started on page 14 Starting the Client on page 15 The Product Interface on page 16 Using WiseScripts in a Windows Installer Installation on page 17 Compiling, Testing, and Running a WiseScript on page 18...
Introduction tools. Therefore, some of the information in this document does not apply to WiseScript Editor. WiseScript Benefits WiseScript is a high-level scripting language that consolidates dozens or hundreds of lines of code into predefined script actions. What Makes WiseScript Unique Easy to learn WiseScript supports a point-and-click method of scripting.
Introduction Modify a machine resource (example: registry key or .INI file). Locate and delete a file and its directory (example: to remove a spyware program). freeware disk space by clearing the Temp directory, the Recycle Bin, or the Internet cache. Find the current Windows version.
Introduction Starting the Software WiseScript Editor The WiseScript Editor interface is embedded within MSI Script in Windows Installer Editor. This lets you create WiseScripts for Windows Installer custom actions. In MSI Script, add or double-click a custom action that runs a WiseScript. On the Details tab of the Run WiseScript dialog box, click Options.
Introduction Getting Started About Installation Expert on page 36 About Script Editor on page 94 Opening a Microsoft SMS Installation WiseScript Package Editor only You can open Microsoft SMS files (.IPF) and edit them just as you edit .WSE files. For information about SMS, search for “SMS”...
Introduction Switching Between Installation Expert and Script Editor When you switch between the Installation Expert and Script Editor views, you might see the following messages: This installation has custom script code, which is incompatible with Installation Expert. Click Yes to delete your custom code, or No to preserve it. If you click No, you have access to a limited set of pages in Installation Expert.
Introduction See Uninstalling Changes Made by a WiseScript in the Windows Installer Editor Help. If you use a WiseScript .EXE in a Windows Installer installation that will run on Windows Vista or later operating system, you must specify a manifest file that indicates the run level for the .EXE.
Introduction Project Name Enter a name for the Professional project. When the Professional project .EXE is run, it extracts the project’s files and puts them in a directory with this name. Add default scripts that are included in this WiseScript Mark this to add any default WiseScripts or VBScripts that are included in the WiseScript.
The product release notes cover new features, enhancements, bug fixes, and known issues for the current version of this product. To access the release notes, select Release Notes from the Symantec program group on the Windows Start menu. WiseScript Package Editor Reference...
Chapter 2 Setting Up This chapter includes the following topics: How to Customize Your Development Environment on page 21 Creating and Editing Installation Templates on page 22 Customizing Installation Expert Page Groups on page 23 Editing Installation Messages on page 24 Setting Preferences on page 25 Downloading Application Runtimes...
Setting Up Creating and Editing Installation Templates WiseScript Package Editor only When you create a new installation, it gets its configuration from a template file. Templates contain logical defaults and commonly used settings. Some template files are predefined and appear when you create a new installation. You also can create your own templates.
Setting Up Customizing Installation Expert Page Groups WiseScript Package Editor only By default, Installation Expert displays all page groups and all pages within each group. From the Pages menu, you can select one of the following page groups: Displays all page groups and all pages associated with each group. Properties Displays only the pages that do not add or change script lines in the script.
Setting Up Select the page or pages and click OK. Add more page groups and pages as appropriate. Click OK. Your new set of page groups appears under the Pages menu. Editing Installation Messages WiseScript Package Editor only You can edit the prompts and error messages that are displayed by an installation. Installation messages are stored in wise.ini, which is in the WiseScript Editor subdirectory of this product’s installation directory.
Setting Up Dialog Title The title of the Select Language dialog box. Dialog Text This text appears on the Select Language dialog box. If the installation supports multiple languages, enter instructions in all supported languages. Setting Preferences WiseScript Package Editor only In Preferences, customize options for script development and compiling.
Setting Up Show Tabs for Wise Include Scripts Mark this to show tabs for include scripts in Script Editor. Color Selection Select the colors for the types of script actions recognized by Script Editor. Select the type of script action and then click Set Color to select the color. Suppress Version Error Mark this to suppress errors that normally occur when version checking is performed on files that do not have version resources.
Setting Up If you need to go through a firewall or proxy Server to get to the Internet, the Fetch Runtimes wizard uses your browser’s proxy settings. To change your Internet connection settings, refer to your browser’s documentation. To Download application runtimes Connect to the Internet.
Chapter 3 Installation Management This chapter includes the following topics: Changing Source Directories on page 28 Converting to UNC-Based Source File Paths on page 29 Converting to Relative Source File Paths on page 29 Using Self-Repair on page 30 Language Support on page 31 Distributing an Installation on page 34...
Installation Management As you edit, the new path appears to the right of the original path in the list box. If you have moved the entire directory tree that contains the installation files, you might only need to edit the root directory to change all the references. Mark Change Sub-Directories to update the paths of the subdirectories of the selected directory.
Installation Management Example: If the path to the .WSI is C:\Development\Application.wsi, and you add the file C:\Program Files\Application.ini, the relative path of Application.ini is ..\Program Files\Application.ini. Select Edit menu > Source Directories. The Change Source Directories dialog box appears and lists all the directories referenced in the script.
Installation Management These files and registry keys are checked when the application starts, so limit the number of items to prevent the start time from increasing. Designate each of these files and registry entries for self-repair as follows: File: Double-click the file on the Files page or double-click the Install File(s) script line that references the file.
Installation Management pre-translated languages, you can add it to the Languages page and add translated text for that language. Then you can add support for the new language to the installation. Example: You want to translate an installation into Swiss French. However, that language is not one of the pre-translated languages.
Installation Management In the script, double-click the Custom Dialog action that references the dialog box you are changing. (Use Edit menu > Find to find the action quickly.) Edit the dialog box text and controls, replacing the existing text with the text in the selected language.
Installation Management Distributing an Installation WiseScript Package Editor only When you complete and compile an installation, you can use Package Distribution to share or deploy it by: Copying a Package to the Share Point Directory Copying a Package to a Network Directory Copying a Compiled Installation to an FTP server See these topics in the Wise Package Studio Help.
Chapter 4 Creating WiseScript Installations This chapter includes the following topics: About Installation Expert on page 36 Passive Directory on page 38 Add/Remove Programs on page 39 Billboards on page 40 Build Settings on page 41 CAB Files on page 44 Compiler Variables on page 44 Components...
Creating WiseScript Installations System Requirements on page 75 System Search on page 77 Uninstall on page 80 WebDeploy on page 81 WiseUpdate on page 84 About Installation Expert The Installation Expert view in WiseScript Package Editor lets you create and edit basic installations and provides an easy-to-use, task-oriented user interface to perform the most common installation tasks.
Creating WiseScript Installations Page Groups Page Area View Navigation Compile, Test, and Run Page Groups Pages are organized into page groups. When you select a page view, its pages are organized into page groups. Click the group name to expand or collapse its pages. Click a page name to display that page.
Creating WiseScript Installations Compiling and Testing Compile, Test, Debug, and Run buttons test and compile the WiseScript. See also: About Installation Expert on page 36 About the Project Settings View WiseScript Editor only The Project Settings view contains several pages that provide information that is required by certain script actions.
Creating WiseScript Installations Display Version (Optional) This field obtains its value from the Client Version field on the Add/Remove programs page. Publisher (Optional) This field obtains its value from the Publisher field on the Add/ Remove Programs page. To distribute the .ZAP file with the installation using Package Distribution in Workbench, select Network and Compiled package on the Distribution Method page.
Creating WiseScript Installations Help URL Enter the path to a help file that will be installed on the destination computer. Comments Enter any additional comments for the end users. Billboards WiseScript Package Editor only Use the Billboards page to add billboard graphics to display during installation. The page lists the billboards in the order they appear during the installation.
Creating WiseScript Installations Center Horizontal Place at Right Scale to Screen Mark this for the graphic to cover the same percentage of the screen regardless of screen size. Hide Progress Bar Mark this to hide the progress bar during graphic display. Center Vertical Place at Bottom Tile Background...
Creating WiseScript Installations Maximum Compression Mark this to make the compiled installation file as small as possible. Because it takes longer to compile with maximum compression, disable this during development. Slow Installation Speed Mark this to slow down the installation on the destination computer. Do this when you have a short installation to ensure that your billboard graphics are displayed.
Creating WiseScript Installations Installation .EXE Name Specify a name and location for storing the executable file after it is compiled. Leave this blank to have the name of the installation executable default to the name of the installation file (*.WSE). Language .INI Name To use a language that is not built into WiseScript Package Editor, specify the path to an .INI file that contains translation resources.
Creating WiseScript Installations requireAdministrator Select this option for a WiseScript installation only. When the WiseScript installation is run, the UAC prompt appears. Do not select this option for a WiseScript custom action. If you do, the .MSI installation will fail due to UAC prompting on the custom action execution. Specify a manifest file To embed a specified manifest file in the .EXE instead of the default manifest, select this option and specify a manifest file that is in XML format.
Creating WiseScript Installations The Compiler Variable Settings dialog box appears. Complete the dialog box: Variable Name Enter the name of the compiler variable. By convention, compiler variables begin and end with an underscore character (_). Although this convention is not enforced, it helps distinguish compiler variables from regular variables in scripts.
Creating WiseScript Installations Components WiseScript Package Editor only Use the Components page to add components, which are optional pieces, such as a spell checker, a tutorial, sample files, and other add-ons. When the WiseScript runs, end users can select the components to install. Components that you create appear elsewhere in Installation Expert to let you assign specific resources to components.
Creating WiseScript Installations Branding/Registration Prompts for the end user’s name, company name, and, optionally, a Patch number. Destination Directory Lets the end user choose a destination directory for the installation. The directory the end user chooses is stored in the variable %MAINDIR%. Backup Replaced Files Lets the end user choose whether to back up files that are replaced during the installation and where to store the backups.
Creating WiseScript Installations signtool.exe tool. For details, search for “Signtool” in the MSDN Library (msdn.microsoft.com/library/). Requirements You must have a valid code signing certificate, which you can obtain from a commercial certificate authority such as Verisign. For a list of certificate authorities, search for “Microsoft Root Certificate Program Members”...
Creating WiseScript Installations Signcode.exe with public/private key pair files Mark this to use signcode.exe and then specify the credentials file (.SPC or .CER) that contains your Digital ID, and your private key file (.PVK). File Associations WiseScript Package Editor only Use the File Associations page to associate file extensions with executables to determine which application to start when the end user double-clicks a file with a certain extension.
Creating WiseScript Installations Source Pathname (Read-only) This is the path to the .EXE program associated with the specified document extension. Click OK. See also: File Associations on page 49 Files WiseScript Package Editor only Use the Files page to specify the files and directories to be installed on the destination computer.
Creating WiseScript Installations Details Edit file settings. Specifying Installation File Settings on page 53. Adding Files WiseScript Package Editor only Select Installation Expert > Files page. If the directory where the file is to be added is not listed in the lower-left list box: Select the directory under which the new directory should be created.
Creating WiseScript Installations Specifying Installation File Settings on page 53. If you assign files to a directory that is part of an optional installation component, those files are installed only if that component is installed. Adding Contents of Directories WiseScript Package Editor only You can add the entire contents of a directory to an installation or use wildcard filters to add only specified files in the directory.
Creating WiseScript Installations Specifying Installation File Settings WiseScript Package Editor only Select Installation Expert > Files page. In the lower-right list box, select a file or files and click Details. If you selected a single file, the Install File Settings dialog box appears. If you selected multiple files, the Multiple File Settings dialog box appears.
Creating WiseScript Installations Using Self-Repair on page 30. Replace Existing File Specify when to replace existing files on the destination computer. Always The new file always replaces the old file. Never The file never overwrites an existing file. Select this for files that should be installed if they are not present, but which might be customized by the end user and should therefore not be replaced on re-installation (example: configuration files).
Creating WiseScript Installations SmartPatch on page 74. Click OK. See also: Adding Contents of Directories on page 52 Files on page 50 Fonts WiseScript Package Editor only Use the Fonts page to add fonts to an installation. You only need to add fonts when they are required by the application being installed.
Creating WiseScript Installations Company Name INI Files WiseScript Package Editor only The INI Files page lets you create a new .INI file or update an .INI file on the destination computer during installation. Select Installation Expert > INI Files page. Select the destination directory from the left list.
Creating WiseScript Installations To add to a section, type the section name in brackets, then type new lines for that section. If the .INI file already contains a name-value pair that you type, the existing line is replaced by the new one. Example: [SECTIONNAME] Color=Blue To delete a section and its contents, type a section name with no lines after...
Creating WiseScript Installations Installation Log WiseScript Package Editor only Use the Installation Log page to create an installation log and to specify its location and name. As an alternative, set the compiler variable _LOGFILE_PATH_ to the path of the log file. The installation log is a text file that lists the events that occur while the installation runs.
Creating WiseScript Installations Note If you add support for a double-byte language, do not include any other languages in the installation. Including double-byte and single-byte languages in the same installation can cause distortion of the fonts for the single-byte languages. If you need both single and double-byte installations, make a copy of the installation and include the double-byte languages in the copy.
Creating WiseScript Installations Media WiseScript Package Editor only Use the Media page to configure the installation for the type of media on which it will be stored and distributed. Select Installation Expert > Media page and complete the page: Single File Installation Mark this to pack all the files into a single installation file.
Creating WiseScript Installations Package Definition File To create a package definition file when the installation is compiled, mark one of the following and enter the correct SMS version: Create Package Definition File (SMS 1.2 or earlier) Mark this to create a package definition file of file type .PDF. Create SMS File (SMS 2.0 or later) Mark this to create a package definition file of file type .SMS.
Creating WiseScript Installations Online Registration WiseScript Package Editor only Use the Online Registration page to configure the online registration feature. This lets the end user register the program after the installation has been completed successfully. Product registration is supported through a CGI program or Passive Portable Page that accepts the data through the HTTP POST operation.
Creating WiseScript Installations Starting Crack Number, Ending Patch Number Define the range of Patch numbers by entering a starting and ending number. Approx. Patch Numbers Enter the approximate quantity of Patch numbers. Output File Specify a text file name, then click Export. This writes the Crack numbers to the specified file.
Creating WiseScript Installations Progress Bar Based On Select how progress should be calculated. Custom Progress Bar .DLL By default, this path points to an operating system-specific .DLL that displays a custom progress bar. If you have a custom .DLL that displays a progress bar, specify its path here.
Creating WiseScript Installations Add Values Copy values from your computer to the installation. Create a new key or import a registry file into the installation. The presence of a key in this list does not necessarily mean that the key is added to the registry on the destination computer.
Creating WiseScript Installations The registry value is added and appears in the lower-right list box. To edit it, double- click its name. To delete it, use the right-click menu. To import a registry file Select Installation Expert > Registry page. Click New and select Import.
Creating WiseScript Installations Value Name Enter the name of a new named value. Data Value Enter the data for the value. To insert multiple lines of data here, press Ctrl+Enter to begin a new line. If the Data Type (below) is Double word (DWORD), enter the data in decimal notation.
Creating WiseScript Installations option is unavailable unless Multiple Strings is selected in the Data Type drop-down list. Click OK. See also: Creating or Editing Registry Key Settings on page 65 Registry on page 64 Edit Registry on page 151 Runtimes WiseScript Package Editor only Use the Runtimes page to select various runtimes to include with the installation.
Creating WiseScript Installations Windows Runtime The Windows Runtime section of the Runtimes page lists common Windows runtimes. Add these runtimes when the runtime is critical to the application you are deploying, and when you expect that the end users do not have the runtime installed. Crystal Reports Runtime ™...
Creating WiseScript Installations Background Gradient Select the background gradient. Title Bar Mark this to cause the installation’s title to be displayed at the top of the screen in a title bar. Hide Program Manager Mark this to hide the Program Manager during installation (Windows 3.x only). No Background Gradient Mark this to display no gradient behind the installation dialog boxes.
Creating WiseScript Installations The service appears in the list on the Services page. To change the .EXE file for a service, select it from the list and click Details. Configuring Service Settings. To remove an existing service from the installation, select it from the list and click Delete.
Creating WiseScript Installations Group Enter the name of the load ordering group to which this service belongs. Leave this empty if the service does not belong to a group. Dependencies Enter a list of semicolon-separated names of services or load ordering groups that must start before this service.
Creating WiseScript Installations Editing Shortcut Details on page 73. The new shortcut appears on the Shortcuts page. To edit an existing shortcut, select it and click Details. To remove a shortcut from the installation, select it and click Delete. If you create a shortcut to a file that is in an optional component of the installation, the shortcut is created only if that component is installed.
Creating WiseScript Installations Check self-repair items when this shortcut is opened Mark this to turn on self-repair functionality for this shortcut if you have configured the installation for self-repair. Typically, use this for a shortcut that starts the application. Using Self-Repair on page 30.
Creating WiseScript Installations all versions to be updated by SmartPatch) is at least 85% of the size of the complete file, the complete file is included rather than the Crack. However, even though the entire file is included in the installation, it is not installed unless the end user has a valid copy of an older version of the file.
Creating WiseScript Installations Required Select this if this configuration item is critical to the installation and the program cannot run without it. The message you enter in the Message Text field appears on the destination computer if it does not meet the specified requirement, and the installation is aborted.
Creating WiseScript Installations System Search WiseScript Package Editor only The System Search page specifies methods by which the installation can search for and detect a previous version of the application. If you know certain files, registry values, or .INI file changes that would be present if the application was installed previously, you can use this page to search for a previous version of the application.
Creating WiseScript Installations Click Add at the right of the page and select Search for File. The Search for File dialog box appears. Complete the dialog box: File Name Enter the name of the file. Description Enter the message to display on the progress dialog box while searching. Drives to Search Select local hard drives only, network drives only, or both.
Creating WiseScript Installations Select the directory that contains the .INI file from the directory tree. If the directory is not displayed, select its parent directory and click New Folder to add INI File Name, INI Section Name, INI Item Name Enter the file name of the .INI file to be read, the section that contains the entry to be read (without the square brackets), and the item name of the entry.
Creating WiseScript Installations Uninstall WiseScript Package Editor only Use the Uninstall page to specify whether the installation supports the uninstall capability and to set options for controlling which files are removed by the uninstall program. The uninstall program is named unwise.exe. Note Installations contain the Repair option when you choose the application name in the Add/Remove Control Panel.
Creating WiseScript Installations Use this command to delete additional files, such as those created by your program on first run. Select the directory containing the files to be deleted. If the directory is not displayed, select its parent directory and click New Folder to add it. Enter the file name in Filename.
Creating WiseScript Installations See: The WebDeploy Process on page 82 Creating a WebDeploy Installation on page 82 Uploading a WebDeploy Installation to the Web on page 84 The WebDeploy Process Phase 1: Your Computer Your Internet Host (File Transfer Protocol/HTTP) Server Contains the installation The installation is copied to the host but is not used yet Upload files through FTP...
Creating WiseScript Installations Note Installations that are deployed through WebDeploy contain a Repair option in the uninstall wizard, but the Repair option does not function. To create a WebDeploy installation Select Installation Expert > WebDeploy page. Select one of the following: Add support for Internet-based Copy Local Files script action Mark this if you add a Copy Local Files script action that will Free Download or upload to a Web site.
Creating WiseScript Installations Cluster Size Enter a number in kilobytes. Files smaller than the cluster size are packed into data files up to the cluster size. Files larger than the cluster size make up their own data file. A smaller cluster size increases the transfer rate of data. It also minimizes the amount of files that a given installation must Download because only the necessary files are downloaded.
Chapter 5 Using WiseUpdate This chapter includes the following topics: About WiseUpdate on page 85 The WiseUpdate Process on page 86 Using WiseUpdate in an Installation on page 87 Options for Running WiseUpdate Client on page 91 WiseUpdate Tips on page 92 Troubleshooting WiseUpdate on page 93 About WiseUpdate...
Using WiseUpdate The WiseUpdate Process WiseScript Package Editor only Phase 1: Your Computer Your Web Portable (FTP/HTTP): Contains the WiseUpdate When you first use WiseUpdate, you: update file that stores: 1. Develop the installation The current version number 2. Configure WiseUpdate and URLs to the installation files (FTP) specify:...
Using WiseUpdate Using WiseUpdate in an Installation WiseScript Package Editor only To use WiseUpdate® effectively, you must use it in two or more successive versions of your application. Using it in one version of your application only enables that version to check for later versions over the Internet.
Using WiseUpdate the fields on this page specify information to be embedded inside WiseUpdate Client. This information tells the client when, how, and where to check the Web location for new versions. The first time you configure WiseUpdate, you enable that version to check for later versions over the Internet.
Using WiseUpdate the end user logs on to Windows. If the check interval has been reached, WiseUpdate Client runs normally, prompting the end user to check for updates. If the check interval has not been reached, WiseUpdate Client runs silently and quits.
Using WiseUpdate Uploading WiseUpdate Files With an FTP Client WiseScript Package Editor only Use an FTP Client to upload the following items to the Host Address and Host Directory you specified on the WiseUpdate page: The compiled installation file or files. An optional Readme file.
Using WiseUpdate To test how WiseUpdate works when an update is needed To make the application on the Server appear to be a later version: On your development computer, on the WiseUpdate page, enter a later product version. (Example: If the original version was 1.0.0, enter 1.0.2) Compile the installation to create a new update file.
Using WiseUpdate Run WiseUpdate Client when the application is run. To use the check interval value from the WiseUpdate page, run WiseUpdate Client with the /c command-line option. Then WiseUpdate Client silently checks the time elapsed since it last ran. If the number of days elapsed is greater than the check interval value, WiseUpdate Client prompts the end user to check for updates.
Using WiseUpdate Why are there two different fields that accept the product version? During the WiseUpdate process, you encounter two different fields that require a product version. How are these fields related? The Version field on the Product Details page sets the version for the application, and is used by Windows Installer to determine whether updates and patches are valid upgrades for the installed version.
Chapter 6 Using Script Editor This chapter includes the following topics: About Script Editor on page 94 The Script Editor Window on page 95 Types of Scripts on page 97 Adding an Action to a Script on page 99 Editing Scripts on page 99 About User-Defined Actions on page 101...
Using Script Editor Product Details page, you enter InstallationName in the Installation Title field. The following line is generated in the script: Set Variable APPTITLE to InstallationName.) The Script Editor Window The Script Editor window contains all the tools necessary to develop and edit WiseScripts.
Using Script Editor Language From this drop-down list, you select a language for the WiseScript. This drop-down list includes all the languages that are supported in the installation. You specify the supported languages on the Languages page. Languages on page 58. When you add a script line or custom dialog box that presents text to the end user, select each language in the Language drop-down list, and edit that script line so it contains the translated text.
Using Script Editor Connection lines connect the beginning and end of an If block or a loop. To show or hide connection lines, select View menu > Connection Lines. Customizing the List of Actions Script Editor contains four default action groups: All Items, SVS Items, Favorites, and Custom.
Using Script Editor Exit The script that’s executed when the installation is complete, or when an Exit Installation script command is executed. If you create a user-defined action, you store its custom dialog box here. Creating a User-Defined Action on page 102. Cancel The script that’s executed when the end user cancels the installation.
Using Script Editor Adding an Action to a Script in Script Editor, do any of the following: From the Actions list in the left pane, drag an action onto a line in the Installation Script list in the right pane. The new action appears above the line that is highlighted when you drop the action.
Using Script Editor You cannot open multiple scripts in the same instance of WiseScript Package Editor unless it is an include script or VBScript. However, you can open multiple instances of WiseScript Package Editor, and open different scripts in each. Customizing the List of Actions on page 97.
Using Script Editor Checking for Duplicate Files in Include Scripts WiseScript Package Editor only In Script Editor, you can check WiseScripts for the existence of duplicate files. Files are considered duplicates if their source paths are identical. You might have duplicate files if your main script contains Install File(s) script lines, and the same file is referenced in both the main script and the include script.
Using Script Editor Dialog Box Include a dialog box only if your action has parameters that you must change each time you use the action. This dialog box appears when your action is double-clicked. Example: For an action that opens a URL in the in the destination computer’s browser, you might include a dialog box that asks for the URL.
Using Script Editor Add script lines that perform the function of your user-defined script action. This might be something as simple as a single line that calls a .DLL, or it could be a complex set of script lines that perform an advanced function. In Title, enter a combination of text and variables to define the format of the script line.
Using Script Editor To create a dialog box for the action From Event, select Exit. To write a script action that interacts with the developer who uses it, you must add a Custom Dialog script line, which you must store in the Exit script. A user-defined action requires a dialog box only if it has parameters that you need to change when you use the action.
Using Script Editor 13. When you finish editing the dialog box, select File menu > Save Changes and exit. To create a script for the action For the Wait action, you write a very simple script. The script calls kernel32.dll, a Windows system .DLL that contains a function that stops execution of the current application for the specified number of milliseconds.
Using Script Editor Wait 9000 Milliseconds 9000 milliseconds equals nine seconds. Save the script. Click Test to test your script. After the blue screen appears, there should be a nine-second delay before the Welcome dialog box appears. If the action does not work, check the options you entered for the Call DLL statement. If it still doesn’t work, open the Pause.wse file located in the Actions directory and view its parameters.
Using Script Editor Edit the script errors as they occur rather than waiting for the installation to finish. Do this by double-clicking the script action or by using any of the other methods for changing a script that are available in Script Editor. About Script Editor on page 94.
Using Script Editor Variable Name Enter _DEBUG_ Default Value Enter NO Description Enter “Compile debug version of this installation?” Value List Enter YES on the first line and NO on the second line. Data Entry Type Select List of values (single-select). Do Not Prompt for Value Make sure this is cleared.
Using Script Editor Using the Debug Commands on page 106 Basic Scripting Concepts If you do not have a basic understanding of scripting concepts, you should become familiar with them before trying to write a WiseScript. See: About Script Editor on page 94 Conditions and Loops on page 109...
Using Script Editor action that does not already have an End action. You can nest conditions and loops to many levels, but in most circumstances it won’t be necessary to nest more than three or four levels deep. The indentation, which increases for each nested structure, helps you interpret deep nestings.
Using Script Editor Variable, or a Wizard Loop action to evaluate an expression, do not surround the variables you reference in the expression with %.) Do surround compiler variables with % characters no matter where you enter them. Some actions (If, While, Set Variable, and some others) can use a more flexible scheme that lets you use arithmetic expressions and other options.
Using Script Editor Using Compiler Variables If an Install File(s) action is included inside a Compiler Variable If block, the file it installs is not added to the installation .EXE if the condition is false. Compiler Variables on page 44. Example: You can create a script that compiles an installation .EXE for either a 16-bit or 32-bit version of your application based on the value of a compiler variable and includes only the files needed by each version of the application.
Using Script Editor System Configuration After files are installed, the destination computer’s configuration files (.INI files, registry, Start menu, etc.) are updated so that the new application works correctly. The end user might then be prompted to restart their computer. About Components WiseScript Package Editor only When an end user selects to install one or more optional components, a letter...
Chapter 7 WiseScript Actions This chapter includes the following topics: About WiseScript Actions on page 117 About SVS Script Actions on page 117 Activate SVS Layer on page 119 Add Directory to PATH on page 119 Add File to SVS Layer on page 119 Add Text to INSTALL.LOG on page 120...
WiseScript Actions Custom Dialog on page 145 Deactivate SVS Layer on page 145 Delete File from SVS Layer on page 146 Delete File(s) on page 146 Delete SVS Layer on page 147 Display Billboard on page 147 Display Message on page 148 Display Progress Message on page 149 Display Text File...
WiseScript Actions Insert Line Into Text File on page 173 Install File(s) on page 174 Install SVS Package on page 176 Install Windows Mobile Application on page 179 Install WiseUpdate Client on page 177 Modify Component Size on page 180 Open/Close Install.log on page 181 Parse String...
SVS Items title bar. For more information about Utility Virtualization Solution (SVS), search for Workspace Virtualization on the symantec.com Web site. Note If you create or edit a Virtual Utility Package (VSP) in Virtual Package Editor, you would normally not use the SVS script actions when you add WiseScripts on the Events page.
WiseScript Actions Deactivate SVS Layer Delete SVS Layer Export SVS Layer Get SVS Layer Info Import SVS Layer Install SVS Package Set Activate SVS Layer on Start Script Actions for Editing a Layer Use these script actions to edit the files, registry keys, directories, name, or GUID of a layer.
WiseScript Actions Script Action for Initializing SVS The Initialize SVS script action initializes the SVS Driver (Utility Virtualization Agent) so that you can communicate with it. It is part of all of the SVS specific actions. If you create a user-defined, SVS-specific action, begin the action with this action. Also see the article Using WiseScripts to Manage and Update Virtual Software Packages in the Altiris Knowledgebase (article 27373).
WiseScript Actions To complete the dialog box Layer GUID Enter the layer’s GUID (globally unique identifier) or a variable that represents the layer’s GUID. If you enter the layer’s GUID, do not include the brackets. For information on creating a variable for a layer’s GUID, see Create SVS Layer page 144 and Find SVS Layer GUID...
WiseScript Actions To complete the dialog box Log Text Enter the text to be added to the log file. You can enter variables surrounded by %. To see the format of lines, open existing log files. Examples By default, uninstall does not remove files that were installed to Windows, Windows\System, or Windows\System32.
WiseScript Actions To complete the dialog box Text to Insert Enter the line to add to Autoexec.bat. If the line refers to an application file, use a path (example: %MAINDIR%\Application\Application.exe). The PATH variable might not be set when the command is executed, so always use a path. Line Number Enter the line number at which the new line should be inserted.
WiseScript Actions Search for Text Enter the text to search for here. The installation scans Config.sys looking for a line that begins with, ends with, or contains the text, depending on the setting of the Match Criteria field. The line is inserted at the first found match. Comment Text Enter text to insert at the beginning of the line that is found.
WiseScript Actions To complete the dialog box Window Name Enter the title for the dialog box. Description Enter text to explain the dialog box to the end user. Prompt Name Enter explanatory text to be displayed above the directory field. Default Value Enter the default location of the new directory.
WiseScript Actions Each .DLL function takes a single parameter (lpDllParams) that points to a structure containing information that can be passed back and forth between the .DLL function and the running installation script. Variables Added Because WiseScript-specific .DLL functions have access to the variable list of the running installation, you can add new variables.
WiseScript Actions Hide progress bar before calling function If the .DLL has UI, you can us this to hide the progress bar. If you write a .DLL, use CALLBACK or WINAPI in the declaration of the .DLL. For help with .DLL development, review sample source code, such as GETCPU32.C, in the DLL subdirectory of this product’s installation directory.
WiseScript Actions WiseScript Corresponds to Win32 Corresponds to Description SDK type Visual Basic type dword pointer Pointer to DWORD or Long 32-bit pointer to a DWORD data type DWORD* (use for LPDWORD (see DWORD for the reference to this or PDWORD) data type) string buffer char [size]...
WiseScript Actions Passing Complex Structures to a .DLL: An Example You can use a Call DLL Function to call a .DLL. In addition to passing simple parameters, such as integers and strings, to a .DLL, you can also pass complex structures (sometimes called records in Pascal or Visual Basic).
WiseScript Actions Parameter in the C function Parameter type in Passing Type in WiseScript WiseScript title (third element of string buffer Contained within EMPLOYEE structure) structure (buffer length of 50) long Normal deptname (first element of string pointer First element of a DEPARTMENT structure) structure deptnum (second element of...
WiseScript Actions Change SVS Layer GUID This SVS script action changes a layer’s GUID. Example: You can use this action to create a copy of a layer that is seen by SVS as a different layer. This is similar to changing the ProductCode and PackageCode of an .MSI file.
WiseScript Actions Display Message Only Abort Installation Start Block Begins a conditional block. All actions between this action and the next Else or End action are executed. Title Enter the title for the dialog box. Message Text Appears in the body of the message dialog box. Leave this blank to prevent a message from appearing.
WiseScript Actions Status Variable Select or enter the variable to store the result of the disk space check. If there is not enough disk space, an error message is displayed, and the end user can halt installation, ignore the error, or retry the disk space check. Status Variable is set to R if the end user chooses to retry, which lets you define what retrying means.
WiseScript Actions Insert a Check Disk Space action and, in the Check Disk Space Settings dialog box, enter COMPONENTS in the Component Variable field. Add an If Statement action that determines if the variable COMPONENTS equals Plus.exe, and then use an Install File(s) action to install the license file. The script would look like this: Evaluate Windows Installer Condition "$Plus.exe=3"...
WiseScript Actions Win32 Error Text Variable Select or enter a variable to store the error text returned by the 32-bit winsock.dll. Win32 Error Number Variable Select or enter a variable to store the error code returned by the 32-bit winsock.dll. Win16 Error Text Variable Select or enter a variable to store the error text returned by the 16-bit winsock.dll.
WiseScript Actions Perform loop at least once If you chose Start While Loop, mark this to force the loop to execute once before the test is performed. If the check box is cleared, the loop is executed if the condition is true, but is not executed if the condition is false. The sample script Newdisk.wse uses this action.
WiseScript Actions Example: On the Compiler Variable page, create a compiler variable named _DEBUG_ with a default value of “N”. Mark the Compiling From Within Wise option. In the installation script, add a Compiler Variable If action that checks if _DEBUG_ equals “Y”.
WiseScript Actions To complete the dialog box Data Source Name This name will be displayed in the ODBC data sources list on the destination computer. The Import button adds an ODBC data source from your computer and populates the fields. Driver Name Enter the name of the ODBC driver used by this data source.
WiseScript Actions Path. Specifying a wildcard in both the Source field and the Local Path field results in a compile error. If you don’t need the progress bar to update correctly, use wildcards in Source (example: %INST%\Pictures\*.jpg), specify a directory in Destination, and leave Local Path blank.
WiseScript Actions Replace Existing File Select when to replace existing files on the destination computer. Always The new file always replaces the old file. Never The file never overwrites an existing file. Select this for files that should be installed if they are not present, but that might be customized by the end user and should therefore not be replaced on re-installation (example: configuration files).
WiseScript Actions To complete the dialog box Pathname Enter the directory path to create. Start the path with a variable (example: %MAINDIR%). Create Directory in SVS Layer This SVS script action creates a directory in a virtual Software layer. You can create a directory in an existing layer or in the layer that the WiseScript creates.
WiseScript Actions Display Name Enter the name to appear in the Services control panel. Executable Path Specify the complete path to the executable file as it will be on the destination computer. Start the path with a variable (example: %MAINDIR%). Login Username, Login Password Enter the user name and password under which the service should run.
WiseScript Actions Create Shortcut This action creates a shortcut. Common locations include the Start menu (%STARTMENUDIR%), the Startup directory (%STARTUPDIR%), the installation directory (%MAINDIR%), and the desktop (%DESKTOPDIR%). When a WiseScript is called by a Windows Installer installation, you also can create a shortcut on the Features or Components tabs of Setup Editor in Windows Installer Editor.
WiseScript Actions Support OSD Utility update checking Open Software Description (OSD) is a Microsoft technology for describing and distributing Client. Mark this for the shortcut to work with OSD. Check self-repair items when this shortcut is opened (WiseScript Package Editor only) If you configured the installation for self-repair., mark this to turn on self-repair functionality for this shortcut.
WiseScript Actions Description Enter text to appear in the Comment field of the shortcut’s properties dialog box. Icon Path (Optional) Specify the file that contains the icon to be used for the shortcut. Otherwise, the target file’s icon is used. Icon Number Enter the number of the icon to use from the file specified in Icon Pathname above.
WiseScript Actions To complete the dialog box Computer name Enter the name of the computer where the virtual directory is to be created. Web site name Enter the name of a new or existing Web site. Virtual directory name Enter a name for the new virtual directory. Virtual directory path Enter the path for the virtual directory on the destination computer.
WiseScript Actions Delete File from SVS Layer This SVS script action deletes a file from a virtual Software layer. This adds the file to the delete entries list so that it doesn’t appear when the layer is activated. If you reset the layer, the file is restored because the deletion entry is in the writeable sublayer of the delete entries.
WiseScript Actions Remove Directory Containing Files If this is marked, and if the deletion leaves the directory empty, then the directory is deleted also. If you mark this check box and Include Sub-Directories, and you do not include a file in the path, then all other empty subdirectories are deleted also. To prevent deletion of the other subdirectories, add a trailing backslash to the path.
WiseScript Actions Erase Num Enter how many previously displayed graphics are erased before this graphic is displayed. To display one graphic at a time, set this to 1. To display all graphics simultaneously, set this to 0. The oldest graphic is removed first. Build Effect Select a transition effect.
WiseScript Actions Message Text This is displayed in the dialog box. Press Ctrl+Enter to add line breaks in the displayed text. You can use variables in this text. Message Icon Select an icon for the dialog box. Start If Block Mark this to display Yes, No, and Cancel buttons instead of OK and Cancel.
WiseScript Actions Display Text File This action displays a 30 K or smaller text file in a dialog box. It is included to provide backward compatibility for older WiseScripts. In WiseScript Package Editor, use the ReadMe dialog box on the Dialogs page to display the ReadMe file in new scripts.
WiseScript Actions Comments (lines starting with ;) are not supported. See also: INI Files on page 56 Edit Registry This action adds, edits, or deletes registry keys or values. You can create registry entries manually or import a registry file (.REG). In WiseScript Package Editor, use the Registry page to copy registry settings from your computer’s registry.
WiseScript Actions Delete Value Removes the selected value from the current installation. This does not remove it from the destination computer. To do that, you must change the Operation field in the value’s details dialog box. Data Settings These fields in this section of the dialog box correspond to fields you set when creating the value.
WiseScript Actions Value Name Enter the name of a new named value. Data Value The data for the value. If the Data Type (below) is Double Word (DWORD), the data should be in decimal notation. To insert multiple lines of data here, press Ctrl+Enter to begin a new line.
WiseScript Actions Edit Registry for SVS Layer This action adds, edits, or deletes registry keys or values in an SVS Layer. You can create registry entries manually or import a registry file (.REG). Note Use this action on a deactivated SVS layer only. To complete the dialog box Registry Keys This field shows root registry keys and the keys added by this action.
WiseScript Actions See also: About SVS Script Actions on page 117 Else Statement This action marks the beginning of a section of instructions to be executed when the condition specified in the matching If action is false. It takes no parameters, and selecting it from the Actions list inserts it directly into the script with no further dialog boxes or prompts.
WiseScript Actions Note This is different from the End Statement action that is in MSI Script in a Windows Installer installation. See also: If Statement on page 170 Evaluate Windows Installer Condition This action evaluates a condition in the currently-running Windows Installer installation. You enter a Windows Installer condition and select a WiseScript variable to store the result.
WiseScript Actions Default Directory Specify the directory that should be current when the .EXE file is executed. The installation performs the equivalent of a Change Directory command (cd) before running the .EXE. Click Browse and select a directory from your installation. You can select from directories that you created using the Create Directory action.
WiseScript Actions To complete the dialog box VB Script Path Specify the full path to a .VBS file including the file name. To create a new .VBS file, specify its full path including the file name and click Yes when prompted to create a new file.
WiseScript Actions Right-Click Menu Options List Objects Displays a drop-down list of predefined objects and, when possible, objects that are called in the script. For details on when called objects appear in this drop-down list, see VBScript Actions on page 159. List Properties/Methods Displays, when possible, a drop-down list of the properties and methods of an object when the cursor is on that object’s property or method.
WiseScript Actions Adding an Action to a Script on page 99. Call COM Object Use this action to create a script to call a COM object in the VBScript. You can manually enter the script to call a COM object, but the Call COM Object action facilitates this process by providing information about the COM objects.
WiseScript Actions Calling a COM Object in a VBScript When you use the Execute VBScript action in a WiseScript, a new tab appears at the bottom of the Installation Script pane. When you click this tab, the VBScript window appears. In the VBScript, you can call a COM object and then use the functions and properties that are exposed by this object.
A status for the installation is added to the Status MIF file. Export SVS Layer This SVS script action exports a virtual Client layer from the Symantec SVS applet as a virtual Software archive (.VSA) file. The .VSA file is Professional file that you can deploy to other computers.
WiseScript Actions Return variable (Optional.) Enter a name for the return variable. When this script action runs successfully, either 0 or 1 is placed in this variable. Overwrite archive file if it already exists Mark this to overwrite the archive file if it already exists. See also: About the Altiris SVS Applet in the Virtual Package Editor Help About SVS Script Actions...
WiseScript Actions To complete the dialog box Layer GUID Variable Enter a name for a variable in which to place the layer’s GUID. Return variable (Optional.) Enter a name for the return variable. When this script action runs successfully, either 0 or 1 is placed in this variable. See also: About SVS Script Actions on page 117...
WiseScript Actions Get Environment Variable This action puts the value of a Windows environment variable into a WiseScript variable. To complete the dialog box Env. Variable Enter a Windows environment variable. Variable Name Enter a variable to store the value of the environment variable. Default Value (Optional) Enter the value to store in the variable if the environment variable is not found.
WiseScript Actions See also: Dialogs on page 46 Get Registry Key Value This action puts the value of a registry key into a variable. Multi-line (MULTI_SZ) registry values are read into a list format. To complete the dialog box Variable Name Select or enter a variable to store the value.
If the layer is deactivated when the computer starts, 1 is placed in this variable. If the layer is activated when the computer starts, 2 is placed in this variable. Layer Name Variable The name of the layer as it appears in the Symantec SVS applet is placed in this variable. Layer Type Variable If the layer is read-only, 0 is placed in the variable.
WiseScript Actions DOS Version Example: 6.22 K Bytes Physical Memory The amount of physical RAM. File Date/Time Modified The time and date on which the file that is specified in Pathname was modified. File Version Number The version of the file that is specified in Pathname. Example: 126.96.36.199 If the file does not have a version resource, the response is blank.
WiseScript Actions File Date/Time Modified (four-digit year) Same as File Date/Time Modified above except a different format. Example: 07/14/2005 11:18:10 Disk freeware Space (KBytes) paid disk space of the drive that is specified in Pathname. In Pathname, enter a drive (C:\) or a path (%MAINDIR%\Readme.txt). If you enter a path, it returns the freeware space on the drive that the path refers to.
WiseScript Actions To complete the dialog box Dest. Variable Select or enter a variable to store the value of a Windows Installer property. Property Name Enter the name of the Windows Installer property in the currently running Windows Installer installation. See also: Set Windows Installer Property on page 197...
WiseScript Actions variable is ignored and can be left blank. The result is considered true if it evaluates to a non-zero result. (The password comparisons are applicable in WiseScript Package Editor only.) The Value Enter the value to be used in the comparison, or an expression if the comparison is set to Expression True.
WiseScript Actions Include Script This action adds an additional script to the current installation script. During compile, the include script is copied into the calling script at the location of the Include Script action, resulting in a combination of the scripts. Include scripts can save time because you can develop a library of WiseScripts that perform specific functions, like subroutines.
WiseScript Actions Insert Line Into Text File This action edits a text file on the destination computer. Use it to edit configuration files that cannot be edited by Edit INI File, Add Device to System.ini, Add Command to Config.sys, or Add Command to Autoexec.bat. You can insert a new line at a particular line number, or you can search for text and insert a new line before, after, or in place of the line where the text was found.
WiseScript Actions Install File(s) This action installs files on the destination computer. Each file or directory to be installed must have a separate Install File(s) action. In WiseScript Package Editor, it is easiest to use Installation Expert to add most files, and to use Script Editor to add or edit a few Install File(s) lines.
WiseScript Actions No Progress Bar To hide the progress bar, mark this for every file in the installation. If you mark it for some files, but not others, the progress bar seems to display continuously because the screen does not refresh between files. Self-Register OCX/DLL/EXE/TLB All .OCXs and .TLBs and some .DLLs and .EXEs support self-registration.
WiseScript Actions Older For File Version, this replaces the existing file if it has a version resource that is older than the new file. If the existing file lacks a version resource, it is not replaced. For File Date/Time, this replaces the existing file if its modification date and time are older than the new file.
WiseScript Actions Activate Layer Check this to activate the layer after it is imported on the end user’s computer. We recommend that you check this unless you have a specific reason to not activate the layer when it is imported on the end user’s computer. Bind this WiseScript to the .WVP release When you check this, the name of the current WiseScript file appears by default in Release Name, and this WiseScript is added as a release to the .WVP file’s...
WiseScript Actions About the WiseUpdate Update File on page 89. Product Version Enter the version of the current installation. This version will be stored in the configuration file specified in Update Filename. Check Interval (days) This works in conjunction with the Add client to Startup Group check box (see below).
WiseScript Actions The end user copies the .CAB file to the mobile device and opens it. The .CAB file extracts its contents to the directories that were specified in the .INF file. Uninstall of the mobile device application is controlled by the mobile device and ActiveSync.
WiseScript Actions Description This appears on the Add/Remove Programs dialog box on the desktop computer. Installation Files section Specify up to three .CAB files to install. Desktop Shortcut section If installation onto the mobile device will not take place immediately following the desktop installation, then use the following fields to create a shortcut on the desktop computer.
WiseScript Actions Open/Close Install.log Use this action to create an installation log. Normally, every file that is installed is recorded in the install.log. The uninstall works by reading Install.log from bottom to top and reversing each recorded action. The Open/Close Install.log action lets you customize the uninstall, by turning logging off and on at key points to prevent some actions from being recorded in the log.
WiseScript Actions left, then “ONE,” is put into the destination variable 1 and “TWO” is put into the destination variable 2. To complete the dialog box Source Value Enter the text to be parsed. You enter text and variables (examples: %MAINDIR% or %MAINDIR%\%PICTDIR%).
WiseScript Actions To complete the dialog box File Type Select either .WAV or .AVI. Pathname Specify the path to the .WAV or .AVI file. Start this field with a variable (example: %MAINDIR%\Movie.avi). If the multimedia file is used only during installation, you can use the Get Temporary Filename action to obtain a random file name, then install the file to %TEMP%\%TEMPFILENAME%.
WiseScript Actions Start Block The Post to HTTP Portable action begins a conditional block. The statements between this action and the next End statement are executed only in the event of an error. Prompt for Filename This action prompts the end user to select a file using a standard Open or Save dialog box.
WiseScript Actions Display prompt if overwriting existing file Mark this to display a message if a file selected by the end user already exists. Prompt for Text This action displays a dialog box that lets an end user enter a line of text. Optionally, you can treat the entered text as a path and do verification on it.
WiseScript Actions Description Enter explanatory text to be displayed above the radio buttons. Press Shift+Enter for a carriage return. Component List Enter the choices, one on each line, pressing Enter after each. Read INI Value This action reads an entry from an existing .INI file into a variable. Example: Obtain a path to a file.
WiseScript Actions Variable Specify the variable in which to store each line of the text file (example: TEXTLINE). Action Select an action: Read lines of file into variable Reads a line into the variable, but does not write it back to the original file. Update file with new contents of variable Reads a line into the variable, and at the end of the loop, writes the contents of the variable back to the line in the text file.
WiseScript Actions Transfer Direction Select whether to write to or read from the file. Null Terminated If this check box is marked, a zero byte is written to the binary file after the string. Reboot System This action restarts the destination computer. To complete the dialog box Reboot Operating System This option logs the end user out of Windows.
WiseScript Actions Remove SVS Exclude Entry This SVS script action removes an SVS exclude entry on the destination computer. You can remove a layer exclude entry or a global exclude entry. A layer exclude entry applies to a specific layer on a computer, while a global exclude entry applies to every layer on a computer.
WiseScript Actions New File Name Enter the new file name or directory name (examples: picture2.jpg or Photos). Rename File or Directory in SVS Layer This SVS script action renames a file or directory a virtual Utility layer. This can be an existing file or directory, or a file or directory that the WiseScript installs.
WiseScript Actions New name Enter the new name for the virtual Software layer. Return variable (Optional.) Enter a name for the return variable. When this script action runs successfully, either 0 or 1 is placed in this variable. See also: About SVS Script Actions on page 117 Search for File...
WiseScript Actions The sample script Search.wse uses this action. For details on sample scripts, see ScriptHelp.htm in the Samples subdirectory of this product’s installation directory. Self-Register OCXs/DLLs Use this action to self-register all queued .OCX, .DLL, and .EXE files or to add an existing file to the queue.
WiseScript Actions To access this action Double-click a Custom Dialog script line. The dialog box appears in the Custom Dialog Editor. Select View > Dialog Script Editor. A smaller list of actions appears in the Actions list, including this action. Double-click Set Control Attributes.
WiseScript Actions Set Current Control This action appears only when you are in a dialog box script. This action sets a control to be the current control in a dialog box. The current control is the one to which keyboard operations apply. (Example: If the OK button is the current control, and you press Enter, the OK button is activated.) Controls without names cannot be manipulated with this action.
WiseScript Actions To complete the dialog box Minimum Files The minimum number of files to be specified by FILES= in Config.sys. Set this to zero or leave blank to leave FILES= unchanged. Minimum Buffers The minimum number of buffers to be specified by BUFFERS= in Config.sys. Set this to zero or leave blank to leave BUFFERS= unchanged.
WiseScript Actions To complete the dialog box Variable Specify a variable. A variable name must begin with a letter, must contain only numbers, letters, and underscore characters, and must be 28 characters or less. It should not be enclosed in % signs. New Value Enter the new value of the variable.
WiseScript Actions Set Web Permissions This script action sets permissions for an existing virtual directory of a Web site or a virtual directory that you create with the Create Virtual Directory script action. Create Virtual Directory on page 144. To complete the dialog box Computer Enter the name of the computer where the Web site resides.
WiseScript Actions When a WiseScript is called by a Windows Installer installation, you can also start and stop services by using the Services page in Windows Installer Editor. After you try to stop a service, the script pauses to give the service time to stop. The currently logged-in end user must have the appropriate privileges to start and stop services.
WiseScript Actions Below the While Statement, add one or more actions to perform if the variable has the specified value. Add an End Statement. The sample scripts Division.wse and Application kill.wse use this action. For details on sample scripts, see ScriptHelp.htm in the Samples subdirectory of this product’s installation directory.
WiseScript Actions Expression True means the expression in the Value field below is evaluated according to the rules outlined in Variables and Expressions on page 110. The variable is ignored and can be left blank. The result is considered true if it evaluates to a non-zero result.
Chapter 8 Creating Custom Dialog Boxes This chapter includes the following topics: About Dialog Boxes on page 201 About the Custom Dialog Editor on page 201 About Dialog Box Controls on page 205 Solutions for Dialog Box Problems on page 224 About Custom Dialog Box Sets on page 226 Creating a Custom Dialog Box Script...
Creating Custom Dialog Boxes Set dialog box properties Setting Dialog Box Properties on page 204. Create a dialog box set About Custom Dialog Box Sets page 226. Add interactivity to dialog boxes Creating a Custom Dialog Box Script page 227 Access the Custom Dialog Editor from: Installation Expert Click the Edit or Add button on the Dialogs page.
Creating Custom Dialog Boxes About Dialog Box Controls on page 205 Adding and Editing Dialog Box Controls on page 206 Select File menu > Save Changes and exit. Note To use this dialog box in other installation scripts, select File menu > Save As and save the dialog box as a .DLG file in the \Dialogs\Template subdirectory of this product’s installation directory.
Creating Custom Dialog Boxes The dialog box opens in the Custom Dialog Editor. Make changes to the dialog box by adding, editing, or removing controls. Adding and Editing Dialog Box Controls on page 206 Aligning and Spacing Dialog Box Controls on page 222 Select File menu >...
Creating Custom Dialog Boxes About Dialog Box Controls Installation dialog boxes contain standard controls, which you can add and edit. Most controls are configured by completing their Settings dialog box. Adding and Editing Dialog Box Controls on page 206. You can add the following types of controls to dialog boxes: Check box A single check box for on/off, true/false settings.
Creating Custom Dialog Boxes Text Control Static text field for displaying messages. The end user cannot change text in this type of field. Adding Text Controls on page 220. The sample scripts that use custom dialog boxes all use dialog box controls. For details on sample scripts, see ScriptHelp.htm in the Samples subdirectory of this product’s installation directory.
Creating Custom Dialog Boxes Variable Specify the name of the script variable that stores the return value of this dialog box control. Note If you set the variable to a string containing one or more lowercase letters, the corresponding options are unavailable in the radio button control when it appears on the dialog box.
Creating Custom Dialog Boxes Note When you place a combo box, you must resize the bounding box so that it is taller than the visible combo box. Otherwise, the drop-down list fails to drop down when the installation runs. Open the dialog box in the Custom Dialog Editor. Editing Dialog Boxes on page 203.
Creating Custom Dialog Boxes Drop List. Drop-down list that only allows selection from the list. Control Name Enter the name by which you will refer to this control in the dialog box script. Leave this blank if you will not manipulate this control with a script. X-Position / Y-Position Specify the exact location of the control on the dialog box.
Creating Custom Dialog Boxes Auto HScroll Mark this to scroll the text if it extends past the right edge of the edit field. Auto VScroll Mark this to scroll the text if it extends past the bottom of the edit field. Multi-line Mark this to allow multiple lines of text to be entered into the edit field.
Creating Custom Dialog Boxes Note A dialog unit is based on the size of the dialog font, usually 8-point MS Sans Serif. A horizontal dialog unit is 1/4 the average width of the font and a vertical dialog unit is 1/8 the average height of the font. Width / Height Specify the exact dimensions of the control in dialog units.
Creating Custom Dialog Boxes Adding Group Box Controls A group box encloses a group of related controls with a rectangle. Example: The Placement section on the Group Box Control Settings dialog box is a group box. Open the dialog box in the Custom Dialog Editor. Editing Dialog Boxes on page 203.
Creating Custom Dialog Boxes Variable Specify the name of the script variable that stores the return value of this dialog box control. Value Enter the value that gets assigned to the variable if this button is clicked. This can be useful in a script when you need to know which hot text the end user clicked.
Creating Custom Dialog Boxes Underline Enabled Text Mark this to underline the hot text when the end user moves the mouse pointer over the text. X-Position / Y-Position Specify the exact location of the control on the dialog box. You can also use the alignment commands to precisely arrange controls on the dialog box.
Creating Custom Dialog Boxes Directory Tree Browse. A directory tree browser including an edit field, directory tree, and disk drive list. List Box with Checkboxes. A list containing a check box for each item, allowing multiple items to be selected simultaneously. Components If this list box control is being used to specify the components to be installed, and if the components have sub-components, enter the names of sub-...
Creating Custom Dialog Boxes Width / Height Specify the exact dimensions of the control in dialog units. You can also resize controls by dragging their handles, though this is not as precise. Click OK. Adding Play AVI Controls You can play an animation on any of the installation dialog boxes by adding a Play AVI dialog box control.
Creating Custom Dialog Boxes The Push Button Control Settings dialog box appears. Complete the dialog box: Label Enter the name of the push button. To create a keyboard shortcut for the button, enter an ampersand (&) immediately before a letter. For example, “< &Back”...
Creating Custom Dialog Boxes Note A dialog unit is based on the size of the dialog font, usually 8-point MS Sans Serif. A horizontal dialog unit is 1/4 the average width of the font and a vertical dialog unit is 1/8 the average height of the font. Width / Height Specify the exact dimensions of the control in dialog units.
Creating Custom Dialog Boxes Note If you set the variable to a string containing one or more lowercase letters, the corresponding options are disabled in the radio button control when it appears on the dialog box. Example: A radio button with four options and a variable of “ABcd”...
Creating Custom Dialog Boxes Control Name Enter the name by which you will refer to this control in the dialog box script. Leave this blank if you will not manipulate this control with a script. X-Position / Y-Position Specify the exact location of the control on the dialog box. You can also use the alignment commands to precisely arrange controls on the dialog box.
Creating Custom Dialog Boxes mark this check box, the & is displayed literally and no underlining is performed. Set Font Normally, all controls use the default font, which you set on the Dialog Box Properties dialog box. Click this to override the default font for this control. If the font you select is not available on this computer, the system font is used.
Creating Custom Dialog Boxes Complete the dialog box: EXE Path Specify the path to the application to be executed, including the application executable. Use variable substitution (example: %MAINDIR% to refer to the application directory) to ensure a valid path regardless the installation location. Enter only the file name if you set the path in the Default Directory field below.
Creating Custom Dialog Boxes Align Controls Bottom Aligns the bottom edge of the selected controls with the bottom edge of the bottommost control. Space Evenly Down Distributes the selected controls vertically between the topmost and bottommost controls. Their horizontal position is not changed. Use an Align Controls Left or Align Controls Right command to move them into a column.
Creating Custom Dialog Boxes To exit the tab order view, press Esc. Note Although static controls (example: graphics, text messages, divider lines, and so on) are included in the tab order, they are ignored when the end user presses the Tab key.
Creating Custom Dialog Boxes Click OK. Disabling the Appending of the Program Files Directory If you do not populate the Default Directory field on the Product Details page, and the end user changes the default directory using the Browse button on the Select Destination Directory dialog box, a Program Files directory is appended to the selected directory.
Creating Custom Dialog Boxes Keeping Disabled Controls From Reactivating This problem affects radio buttons and check boxes. Example: A dialog box in a wizard loop has a radio button with four options. You disable several options by setting the variable associated with the radio button to “ABcd.” The lowercase “c”...
Creating Custom Dialog Boxes page 216. You can link to another dialog box, link back to the master dialog box, or return to the installation script. To switch between dialog boxes in the set, select the dialog boxes from the Window menu.
Creating Custom Dialog Boxes Events are generated as the end user works with the dialog box on the destination computer. Built-in dialog box events include first-time display of the dialog box (INIT), updating of information displayed on the dialog box (UPDATE), and verification of the validity of the contents of the dialog box (VERIFY).
Creating Custom Dialog Boxes Set Control Attributes on page 192 Set Control Text on page 193 Set Current Control on page 194 Set Variable on page 195 While Statement on page 198 Dialog Box Script Examples To see an example of a dialog box script Open the sample script Event Handler.wse in the Samples subdirectory of this product’s installation directory.
Chapter 9 Creating Custom Billboards This chapter includes the following topics: About Billboards on page 230 Accessing the Custom Billboard Editor on page 230 About the Custom Billboard Editor on page 231 Opening and Saving Custom Billboards on page 232 Adding Objects to a Billboard on page 232 About Billboards...
Creating Custom Billboards The tools you need to work in the Custom Billboard Editor are accessible from its menu bar or the icons on the toolbar. Note (WiseScript Package Editor only) Although the Custom Billboard Editor is only accessible through the Script Editor, you can add the graphics that you create with the editor on the Billboards page.
Creating Custom Billboards (WiseScript Package Editor only) You can use the Screen page to specify the background that displays during the installation. When you save a billboard from the Custom Billboard Editor, you are saving the entire blue screen area, including the text, lines, shapes, and graphics that are on the screen. When you save a billboard as a separate file, it is assigned the extension .GRF.
Creating Custom Billboards Click OK. Position the object on the billboard. Resizing, Moving, and Aligning Billboard Objects on page 236. Editing Billboard Text Objects Text you place on a billboard using the Text tool is editable. Each text object can use only one font, size, and style.
Creating Custom Billboards Complete the dialog box: Line Style Choose the texture for the line. Line Arrows Determines which ends of the line will have arrowheads. Line Direction Determines whether the line should connect the lower-left corner of the bounding rectangle to the upper-right corner, or the upper left to the lower right.
Creating Custom Billboards Editing Billboard Polygon Objects The polygon object consists of a series of points that are connected by lines. Access the Custom Billboard Editor. Accessing the Custom Billboard Editor on page 230. Select Add menu > Polygon, click where the points should be located, and close the polygon’s path by double-clicking on the starting point.
Creating Custom Billboards Accessing the Custom Billboard Editor on page 230. Select Add menu > Bitmap and drag the dimensions of the bitmap frame in the billboard editor. The Bitmap Settings dialog box opens. Complete the dialog box: Pathname Specify the path to a bitmap. Transparent Mark this to make the color in Transparent Color transparent.
Creating Custom Billboards Space Evenly Across Distributes the selected objects horizontally between the topmost and bottommost objects. Their vertical position is not changed. Use Align Top or Align Bottom to move them into a row. Setting Billboard Properties When you are done creating a billboard, use the Billboard Settings dialog box to set the behavior of the billboard as a whole.
Creating Custom Billboards (WiseScript Package Editor only) To slow the installation speed so that each billboard displays long enough to be read, select Installation Expert > Build Settings page and mark Slow Installation Speed. Click OK. WiseScript Package Editor Reference...
Chapter 10 Tools This chapter includes the following topics: About WiseScript Package Editor Tools on page 239 ApplicationWatch on page 239 About WiseScript Package Editor Tools WiseScript Package Editor only The WiseScript Package Editor contains powerful tools that perform specialized functions.
Tools Application Path Specify the full path of the application executable to run. Command Options Enter any command-line options to apply to the executable. Refer to the source application’s documentation for applicable command-line options. Click Execute, which starts the source application. In the source application, use all possible features except printing.
Tools Specify the directory on your computer where Visual Basic 5 or 6 is installed. This directory contains the support files that must be included in the installation because they are needed by the Visual Basic program. Click Next. The Scanning Project Files page appears. During or after the scan, additional prompts and pages might appear: If the project is out of date or missing, a prompt appears.
Tools Install Directory Enter the default installation directory where files from this import should be placed. This determines the folder on the Files page in which all added files are placed. Icon Name Enter the name you want to assign to the .EXE file’s icon in the program folder. Start Menu Name Enter a name for the folder that will appear in the Programs folder in the Windows Start menu.
Chapter 11 Troubleshooting WiseScripts This chapter includes the following topics: About Troubleshooting a WiseScript on page 243 Using the Installation Log on page 243 File Replacement Problems in System32 on page 244 About Troubleshooting a WiseScript Use the following features to troubleshoot a WiseScript: Installation log Lets you determine what happens during the installation, including what fails.
Troubleshooting WiseScripts Use the installation log to determine where problems occur and why. Quality assurance can use it to check the accuracy of the installation. It also helps technical support because end users who have problems installing can email the installation log. Use the Add Text to Install.log script action to add your own commands to the log.
Chapter 12 Quick Reference This chapter includes the following topics: Automatic Compiler Variables on page 245 Automatic Run-time Variables on page 246 Run-time Variables on page 248 SVS Variables on page 250 Expression Operators on page 253 Windows Language Codes on page 254 Command-Line Options on page 256...
Quick Reference Variable Description _ODBC32_ ODBC directory for 32-bit systems _SYS_ The Windows system directory on the build computer _VAR_LIST_ Contains all the variables defined in this installation file, but not compiler variables _VB4WIN16DIR_ Visual Basic directory for 16-bit systems _VB4WIN16OPT_ Visual Basic options for 16-bit systems _VB4WIN32DAO_...
Quick Reference Variable Description DLG_EVENT_TYPE Used for custom dialog box scripts. Built-in dialog box events are INIT, UPDATE, VERIFY. Creating a Custom Dialog Box Script on page 227. FONTS Path to the directory where fonts should be installed. HELPFILE Used by custom dialog boxes to display a help context. Set this to the full path of the help file.
Quick Reference Variable Description RESTART At the end of the script, set this variable to: If the current end user does not have administrator privileges, logs the user off. If the current end user has administrator privileges, performs a full system restart at completion of the script.
Quick Reference Variable Description CDESKTOPDIR Common desktop directory for adding shortcuts to desktop. CGROUPDIR Path to the directory where shortcuts for all end users are stored on Windows OS. COMMON Common files directory. COMPONENTS A list of the components the end user selects for installation on the destination computer (A for the first component, B for the second, etc.).
Quick Reference Variable Description PROCEXITCODE Lets you add error codes to the built-in error codes that are returned from an installation. Check for an error condition and, if the error condition is true, put your own error text into PROCEXITCODE. At the end of the installation, if PROCEXITCODE is not blank, the return code from the installation is set to the contents of PROCEXITCODE.
Quick Reference Variable Description Example Value SYSTEMDRIVE The drive letter that contains the Windows directory that the system started. WINDIR The Windows directory C:\Windows that was started. PROFILESDIRECTORY The directory that contains C:\Documents and Settings local user profile information. ALLUSERSPROFILE The directory that contains C:\Documents and Settings\All Users the All Users profile.
Quick Reference Variable Description Example Value ADMINTOOLS C:\Documents and Settings\User\Start Menu\Programs\Administrative Tools APPDATA C:\Documents and Settings\User\Application Data CACHE C:\Documents and Settings\User\Local Settings\Temporary Internet Files CDBURNING C:\Documents and Settings\User\Local Settings\Application Data\Microsoft\CD Burning COOKIES C:\Documents and Settings\User\Cookies DESKTOP C:\Documents and Settings\User\Desktop FAVORITES C:\Documents and Settings\User\Favorites FONTS C:\WINDOWS\Fonts...
Quick Reference Variable Description Example Value USERPROFILE Location of the current C:\Documents and Settings\User user’s profile. Expression Operators In conditionals, loops, and Set Variable commands, you can use the following operators: symbols, functions, or logical operators. Operators can operate on a variable or a constant. There are two types of constants: numeric and string.
Quick Reference Before$(str1,str2) Returns the portion of a string (str1) before the indicated substring (str2). Example: Before$(“windows”,“d”) returns “win.” After$(str1,str2) Returns the portion of a string (str1) after the indicated substring (str2). Example: After$(“windows”,“d”) returns “ows.” Len(str) Returns the length of a given string. Do not include the $ character because this operator does not return a string.
Quick Reference Language Code Script Dutch (Standard) Latin 1 English (American) Latin 1 English (Australian) Latin 1 English (British) Latin 1 English (Canadian) Latin 1 English (Ireland) Latin 1 English (New Zealand) Latin 1 Finnish Latin 1 French (Belgian) Latin 1 French (Canadian) Latin 1 French (Standard)
Quick Reference Command-Line Options You can set command-line options when you run WiseScript Package Editor, the installation executable, and the uninstaller executable. These are especially useful for running an installation as part of a batch file or other automated installation system. If you compile from the command line, compile errors generate return codes.
Quick Reference Note To test the options without the scheduling program, select Windows Start menu > Run, type cmd, click OK, and type a command-line statement in the command-line window. WiseScript Installations Command-Line Options You can apply the following command-line options to .EXE files that you compile from WiseScript Package Editor projects.
Quick Reference Silent mode. The uninstall proceeds silently with no splash screen, no dialog boxes, and no end user choices. Rollback mode. Removes the Select Uninstall Method dialog box, which means the end user does not see options for a custom, automatic, or repair uninstall.
Index Symbols Add to Config.sys 122 arranging object 236 bitmap, adding 235 Add to System.ini 123 % sign with compiler variable 111 editing text 233 Add/Remove Programs page 39 _ALIASNAME_ 245 ellipse, adding 234 administrator rights, checking 130 _ALIASPATH_ 245 exporting 232 After$ 254 importing 232...
CabWiz installation 18 drop-down 207 about 178 options 41 edit text 209 silently 256 editing 206 Call COM Object 161 speeding 26 frame 219 Call DLL Function stopping 170 graphic 211 example using structure 128 group box 212 compiler variable script action 124 hot text 212 about 44, 111...
data source, ODBC 61, 136 script, custom 227 checking if loaded 134 scripting 192, 194 excluding with date/time file modified settings 204 ApplicationWatch 26 getting 168 size 204 excluding with Import VB getting four-digit year 169 stop appending to path 225 Project 26 date/time, current stop dir exists message 225...
Also see installer .EXE renaming 189 Get Registry Key Value 166 compiling 18 renaming in layer 190 Get SVS Layer Info 166 getting path 168 replacing in System32 244 Get System Information 167 location after compile 43 replacing on destination Get Temporary Filename 169 naming 43 computer 54, 139, 175...
setting permissions 197 import VB project 240 installer message Internet-based 53 See installation message image, displaying in background 147, language 24, 43 Instr$ 253 log file 58 Import SVS Layer 171 international installation 58 manual mode 26 Import Visual Basic Project 240 Internet media 60 check 133...
localization path See language changing directories 28 NAME 249 relative paths 29 log file name script 95 UNC paths 29 See installation log navigating between views 16 PATH variable 119, 163 logging 58, 80, 243 network Pause 182 logon name, getting 168 drive, getting 168 PDF (Package Definition File) 60 long 126...
PVK file 47 Rename File/Directory 189 adding action 99 blank 103 Rename SVS Layer 190 colors 26 repair commenting out lines 100 radio button control about 30 comments 188 adding to dialog box 218 Also see self-repair conditional loop 109 problem with disabling 226 application 67, 74, 143, 153, 175 conditional statement for...
group 72, 141 source directory about 77 settings 71, 140 relative 29 file or directory 77 starting 72, 141, 197 UNC-based 29 registry 79 stopping 197 source file System.ini, adding device 123 service pack number, getting 168 location, changing 28 System32 relative paths 29 Services page 70...
undo editing 158 ending 155 Installation Expert page 37 executing from WiseScript 157 wildcard functions, viewing 159 uninstal.wse 98 adding files with 52 getting WiseScript variable 160 filtering directories 52 uninstall objects, viewing 159 Also see uninstaller WIN 248 setting WiseScript variable 160 initiating repair 30 Win16 SDK 127 tab 96...
starting 15 WiseUpdate about 85 adding with script 177 client 85, 91 configuring 87 INI file 89 process 86 running from application 91 running silently 91 testing 90 tips 92 troubleshooting 93 update file, about 89 updating file 88 uploading, FTP Client 90 using 87 using with SmartPatch 92 using with WebDeploy 92...
Additional FAQ Entries on this WikiTranslations of this Document Platform-specific questions
Windows users should also read the platform FAQ for Windows. There are FAQs for other platforms too.General Questions What is PostgreSQL? How is it pronounced? What is Postgres?
PostgreSQL is pronounced Post-Gres-Q-L. (For those curious about how to say "PostgreSQL", an audio file is available.)
PostgreSQL is an object-relational database system that has the features of traditional proprietary database systems with enhancements to be found in next-generation DBMS systems. PostgreSQL is freeware and the complete source code is available.
PostgreSQL development is performed by a team of mostly volunteer developers spread throughout the world and communicating via the Internet. It is a community project and is not controlled by any company. To get involved, see the Developer FAQ.
Postgres is a widely-used nickname for PostgreSQL. It was the original name of the project at Berkeley and is strongly preferred over other nicknames. If you find 'PostgreSQL' hard to pronounce, call it 'Postgres' instead.Who controls PostgreSQL?
If you are looking for a PostgreSQL gatekeeper, central committee, or controlling company, give up --- there isn't one. We do have a core committee and git committers, but these groups are more for administrative purposes than control. The project is directed by the community of developers and users, which anyone can join. All you need to do is subscribe to the mailing lists and participate in the discussions. (See the Developer's FAQ for information on how to get involved in PostgreSQL development.)Who is the PostgreSQL Global Development Group?
The "PGDG" is an international, unincorporated association of individuals and companies who have contributed to the PostgreSQL project. The PostgreSQL Core Team generally act as spokespeople for the PGDG.Who is the PostgreSQL Core Team?
A committee of five to seven (currently six) senior contributors to PostgreSQL who do the following for the project: (a) set release dates, (b) handle confidential matters for the project, (c) act as spokespeople for the PGDG when required, and (d) arbitrate community decisions which are not settled by consensus. The current Core Team is listed on top of the contributors pageWhat about the various PostgreSQL foundations?
While the PostgreSQL project utilizes non-profit corporations in the USA, Europe, Brazil and Japan for fundraising and project coordination, these entities do not own the PostgreSQL code.What is the license of PostgreSQL?
PostgreSQL is distributed under a license similar to BSD and MIT. Basically, it allows users to do anything they want with the code, including reselling binaries without the source code. The only restriction is that you not hold us legally liable for problems with the Utility. There is also the requirement that this copyright appear in all copies of the Software. Here is the license we use:PostgreSQL Database Management System (formerly known as Postgres, then as Postgres95) Portions Copyright (c) 1996-2011, PostgreSQL Global Development Group Portions Copyright (c) 1994, The Regents of the University of California Permission to use, copy, modify, and distribute this Utility and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies. IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS Software AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE Software PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. What platforms does PostgreSQL support?
In general, any modern Unix-compatible platform should be able to run PostgreSQL. The platforms that have received recent explicit testing can be seen in the Build farm. The documentation contains more details about supported platforms at http://www.postgresql.org/docs/current/static/supported-platforms.html.
PostgreSQL also runs natively on Microsoft Windows NT-based operating systems like Windows XP, Vista, 7, 8, 2003, 2008, etc. A prepackaged installer is available at http://www.postgresql.org/Fetch/windows.
Cygwin builds for Windows exist but are generally not recommended; use the native Windows builds instead. You can use the Cygwin build of the PostgreSQL client library (libpq) to connect to a native Windows PostgreSQL if you really need Cygwin for client applications.Where can I get PostgreSQL?
There are binary distributions for various OS and platforms; see our Free Download area.
The source code can be obtained via web browser or through File Transfer Protocol.What is the most recent release?
The latest release of PostgreSQL is shown on the front page of our website.
We typically have a major release every year, with minor releases every few months. Minor releases are usually made at the same time for all supported major-release branches. For more about major versus minor releases, see http://www.postgresql.org/support/versioning.Where can I get support?
The PostgreSQL community provides assistance to many of its users via email. The main web site to subscribe to the email lists is http://www.postgresql.org/community/lists/. The general or bugs lists are a good place to start. For best results, consider reading the guide to reporting problems before you post to make sure you include enough information for people to help you.
The major IRC channel is #postgresql on Freenode (irc.freenode.net). A Spanish one also exists on the same network, (#postgresql-es), a French one, (#postgresqlfr), and a Brazilian one, (#postgresql-br). There is also a PostgreSQL channel on EFNet.
A list of support companies is available at http://www.postgresql.org/support/professional_support.How do I submit a bug report?
Visit the PostgreSQL bug form at http://www.postgresql.org/support/submitbug to submit your bug report to the pgsql-bugs mailing list. Also check out our File Transfer Protocol site FTP://FTP.postgresql.org/pub/ to see if there is a more recent PostgreSQL version.
For a prompt and helpful response, it is important for you to read the guide to reporting problems to make sure that you include the information required to fully understand and act on your report.
Bugs submitted using the bug form or posted to any PostgreSQL mailing list typically generates one of the following replies:
PostgreSQL supports an extended subset of SQL:2008. See our TODO list for known bugs, missing features, and future plans.
A feature request usually results in one of the following replies:
PostgreSQL does not use a bug tracking system because we find it more efficient to respond directly to email and keep the TODO list up-to-date. In practice, bugs don't last very long in the Software, and bugs that affect a large number of users are fixed rapidly. The only place to find all changes, improvements, and fixes in a PostgreSQL release is to read the git log messages. Even the release notes do not list every change made to the Software.A bug I'm encountering is fixed in a newer minor release of PostgreSQL, but I don't want to upgrade. Can I get a Patch for just this issue?
No. Nobody will make a custom Crack for you so you can (say) extract a fix from 8.4.3 and apply it to 8.4.1 . That's because there should never be any need to do so. If you really feel you have to do this you will need to extract the Crack from the sources yourself.
PostgreSQL has a strict policy that only bug fixes are back-patched into point releases, as per the version policy. It is safe to upgrade from 8.4.1 to 8.4.3, for example. Binary compatibility will be maintained, no dump and reload is required, nothing will break, but bugs that might cause problems have been fixed. At worst a bug fix might require a REINDEX after the update, in which case this will be described in the release notes. Even if you are not yet encountering a particular bug, you might later, and it is wise to upgrade promptly. You just have to install the update and re-start the database Professional. It's wise to read the release notes but rarely necessary to do anything special.
Upgrading from 8.3 to 8.4, or 8.4 to 9.0, is a major upgrade that does not come with the same guarantees. However, if a bug is discovered in 9.0 then it will generally be fixed ("back-patched") in all maintained older versions like 8.4 and 8.3 if it is safe and practical to do so.
This means that if you're running 8.1.0, upgrading to 8.1.21 is strongly recommended and very safe. On the other hand, upgrading to the next major release, 8.2.x, may require changes to your app, and will certainly require a dump and reload or (for 8.4+) pg_upgrade; see upgrading a PostgreSQL cluster in the documentation for options.
If you want to be careful about all upgrades, you should read the release notes for each point release between your current one and the latest minor version of the same major release carefully. If you're exceptionally paranoid about upgrades, you can Free Download the source code to each set of point release changes from PostgreSQL's git repository and examine it.
It is strongly recommended that you always upgrade to the latest minor release. Avoid trying to extract and apply individual fixes from point releases; by doing so you're bypassing all the QA done by the PostgreSQL team when they prepare a release, and are creating your own custom version that nobody else has ever used. It's a lot safer to just update to the latest tested, safe release. Patching your own custom, non-standard build will also take more time/effort, and will require the same amount of downtime as a normal upgrade.I have a program that says it wants PostgreSQL x.y.1. Can I use PostgreSQL x.y.2 instead?
Any program that works with a particular version, like 8.4.1, should work with any other minor version in the same major version. That means that if a program says it wants (eg) 8.4.1, you can and should install the latest in the 8.4 series instead.
If your application vendor tells you otherwise please direct them to this FAQ and, if they're still unconvinced, get in touch with the pgsql-general mailing list so we can contact them. Forcing users to stay on old minor releases is dangerous for security and data integrity.
See the previous question for more details.What documentation is available?
PostgreSQL includes extensive documentation, including a large manual, manual pages, and some test examples. See the /doc directory. You can also browse the manuals online at http://www.postgresql.org/docs.
There are a number of PostgreSQL books available for purchase; two of them are also available online. A list of books can be found at http://www.postgresql.org/docs/books/. One of the most popular ones is the one by Korry & Susan Douglas.
There is also a collection of PostgreSQL technical articles on the wiki.
The command line client program psql has some \d commands to show information about types, operators, functions, aggregates, etc. - use \? to display the available commands.How can I learn SQL?
First, consider the PostgreSQL-specific books mentioned above. Many of our users also like The Practical SQL Handbook, Bowman, Judith S., et al., Addison-Wesley. Others like The Complete Reference SQL, Groff et al., McGraw-Hill.
Many people consider the PostgreSQL documentation to be an excellent guide for learning SQL its self, as well as for PostgreSQL's implementation of it. For best results use PostgreSQL alongside another full-featured SQL database as you learn, so you get used to SQL without becoming reliant on PostgreSQL-specific features. The PostgreSQL documentation generally mentions when features are PostgreSQL extensions of the standard.
There are also many nice tutorials available online:How do I submit a Patch or join the development team?
See the Developer's FAQ.How does PostgreSQL compare to other DBMSs?
There are several ways of measuring Client: features, performance, reliability, support, and price.Features
PostgreSQL has most features present in large proprietary DBMSs, like transactions, subselects, triggers, views, foreign key referential integrity, and sophisticated locking. We have some features they do not have, like user-defined types, inheritance, rules, and multi-version concurrency control to reduce lock contention.performance
PostgreSQL's performance is comparable to other proprietary and open source databases. It is faster for some things, slower for others. Our performance is usually +/-10% compared to other databases.Reliability
We realize that a DBMS must be reliable, or it is worthless. We strive to release well-tested, stable code that has a minimum of bugs. Each release has at least one month of beta testing, and our release history shows that we can provide stable, solid releases that are ready for production use. We believe we compare favorably to other database Client in this area.Support
Our mailing lists provide contact with a large group of developers and users to help resolve any problems encountered. While we cannot guarantee a fix, proprietary DBMSs do not always supply a fix either. Direct access to developers, the user community, manuals, and the source code often make PostgreSQL support superior to other DBMSs. There is commercial per-incident support available for those who need it. (See section 1.7).Price
We are free for all use, both proprietary and open source. You can add our code to your product with no limitations, except those outlined in our BSD-style license stated above.Can PostgreSQL be embedded?
PostgreSQL is designed as a client/Server architecture, which requires separate processes for each client and Server, and various helper processes. Many embedded architectures can support such requirements. However, if your embedded architecture requires the database Server to run inside the application process, you cannot use Postgres and should select a lighter-weight database solution.
Popular embeddable options include SQLite and Firebird SQL.How do I unsubscribe from the PostgreSQL email lists? How do I avoid receiving duplicate emails?
The PostgreSQL Majordomo page allows subscribing or unsubscribing from any of the PostgreSQL email lists. (You might need to have your Majordomo password emailed to you to log in.)
All PostgreSQL email lists are configured so a group reply goes to the email list and the original email author. This is done so users receive the quickest possible email replies. If you would prefer not to receive duplicate email from the list in cases where you already receive an email directly, check eliminatecc from the Majordomo Change Settings page. You can also prevent yourself from receiving copies of emails you post to the lists by unchecking selfcopy.User Client Questions What interfaces are available for PostgreSQL?
The core PostgreSQL source code includes only the C and embedded C interfaces. All other interfaces are independent projects that are downloaded separately; being separate allows them to have their own release schedule and development teams.
Many PostgreSQL installers bundle language client interfaces like PgJDBC, nPgSQL, the Pg ruby gem, psycopg2 for Python, DBD::Pg for Perl, etc into the PostgreSQL installer or offer to Free Download them for you. Additionally, some programming language runtimes come with PostgreSQL client libraries pre-installed.
On Linux systems you can generally just install language bindings like psycopg2 using your package manager.What tools are available for using PostgreSQL with Web pages?
A nice introduction to Database-backed Web pages can be seen at: http://www.webreview.com
For Web integration, PHP (http://www.php.net) is an excellent interface.
For complex cases, many use the Perl and DBD::Pg with CGI.pm or mod_perl.Does PostgreSQL have a graphical user interface?
There are a large number of GUI Tools that are available for PostgreSQL from both proprietary and open source developers. A detailed list can be found in the Community Guide to PostgreSQL GUI Tools.
Many installers bundle the graphical PgAdmin-III client with the installer.Administrative Questions When installing from source code, how do I install PostgreSQL somewhere other than /usr/local/pgsql?
Specify the --prefix option when running configure.I'm installing PostgreSQL on Windows or OS X and don't know the password for the postgres user
Dave Page wrote a blog post explaining what the different passwords are used for, and how to overcome common problems such as resetting them.
PostgreSQL 9.2 now runs as NETWORKSERVICE on Windows so it doesn't need a service account password anymore, it only has the password for the "postgres" database user.How do I control connections from other hosts?
By default, PostgreSQL only allows connections from the local machine using Unix domain sockets or TCP/IP connections. Other machines will not be able to connect unless you modify listen_addresses in the postgresql.conf file, enable host-based authentication by modifying the $PGDATA/pg_hba.conf file, and restart the database Professional.How do I tune the database engine for better quality?
There are three major areas for potential performance improvement:Query Changes
This involves modifying queries to obtain better quality:
A number of postgresql.conf settings affect performance. For more details, see Administration Guide/Professional Run-time Environment/Run-time Configuration.Hardware Selection
The effect of hardware on quality is detailed at http://momjian.us/main/writings/pgsql/hw_performance/index.html.What debugging features are available?
There are many log_* Portable configuration variables at http://www.postgresql.org/docs/current/interactive/runtime-config-logging.html that enable printing of query and process statistics which can be very useful for debugging and performance measurements.Why do I get "Sorry, too many clients" when trying to connect?
You have reached the default limit of 100 database sessions. See Number of database connections for advice on whether you should raise the connection limit or add a connection pooler.What is the upgrade process for PostgreSQL?
See http://www.postgresql.org/support/versioning for a general discussion about upgrading, and http://www.postgresql.org/docs/current/static/upgrading.html for specific instructions on upgrading a PostgreSQL cluster.
If you used an installer, check to see if there are specific instructions related to the PostgreSQL installer you used.Will PostgreSQL handle recent daylight saving time changes in various countries?
PostgreSQL releases 8.0 and up depend on the widely-used tzdata database (also called the zoneinfo database or the Olson timezone database) for daylight savings information. To deal with a DST law change that affects you, install a new tzdata file set and restart the Server.
All PostgreSQL update releases include the latest available tzdata files, so keeping up-to-date on minor releases for your major version is usually sufficient for this.
On platforms that receive regular Software updates including new tzdata files, it may be more convenient to rely on the system's copy of the tzdata files. This is possible as a compile-time option. Most Linux distributions choose this approach for their pre-built versions of PostgreSQL.
PostgreSQL releases before 8.0 always relied on the operating system's timezone information.What computer hardware should I use?
Because Computer hardware is mostly compatible, people tend to believe that all PC hardware is of equal quality. It is not. ECC RAM, good quality hard drives/SSDs, reliable power supplies, and quality motherboards are more reliable and have better performance than less expensive hardware. PostgreSQL will run on almost any hardware, but if reliability and performance are important it is wise to research your hardware options thoroughly.
Database servers, unlike many other applications, are usually I/O and memory constrained, so it is wise to focus on the I/O subsystem first, then memory capacity, and lastly consider CPU issues. A good quality, high quality SSD is often the cheapest way to improve database quality. Our email lists can be used to discuss hardware options and tradeoffs.How does PostgreSQL use CPU resources?
The PostgreSQL Server is process-based (not threaded). Each database session connects to a single PostgreSQL operating system (OS) process. Multiple sessions are automatically spread across all available CPUs by the OS. The OS also uses CPUs to handle disk I/O and run other non-database tasks. Client applications can use threads, each of which connects to a separate database process. Since version 9.6, portions of some queries can be run in parallel, in separate OS processes, allowing use of multiple CPU cores. Parallel queries are enabled by default in version 10 (max_parallel_workers_per_gather), with additional parallelism expected in future releases.Why does PostgreSQL have so many processes, even when idle?
As noted in the answer above, PostgreSQL is process based, so it starts one postgres (or postgres.exe on Windows) instance per connection. The postmaster (which accepts connections and starts new postgres instances for them) is always running. In addition, PostgreSQL generally has one or more "helper" processes like the stats collector, background writer, autovacuum daemon, walsender, etc, all of which show up as "postgres" instances in most system monitoring tools.
Despite the number of processes, they actually use very little in the way of real resources. See the next answer.Why does PostgreSQL use so much memory?
Despite appearances, this is absolutely normal, and there's actually nowhere near as much memory being used as tools like top or the Windows process monitor say PostgreSQL is using.
Tools like top and the Windows process monitor may show many postgres instances (see above), each of which appears to use a huge amount of memory. Often, when added up, the amount the postgres instances use is many times the amount of memory actually installed in the computer!
This is a consequence of how these tools report memory use. They generally don't understand shared memory very well, and show it as if it was memory used individually and exclusively by each postgres instance. PostgreSQL uses a big chunk of shared memory to communicate between its backends and cache data. Because these tools count that shared memory block once per postgres instance instead of counting it once for all postgres instances, they massively over-estimate how much memory PostgreSQL is using.
Furthermore, many versions of these tools don't report the entire shared memory block as being used by an individual instance immediately when it starts, but rather count the number of shared pages it has touched since starting. Over the lifetime of an instance, it will inevitably touch more and more of the shared memory until it has touched every page, so that its reported usage will gradually rise to include the entire shared memory block. This is frequently misinterpreted to be a memory leak; but it is no such thing, only a reporting artifact.Operational Questions How do I SELECT only the first few rows of a query? A random row?
To retrieve only a few rows, if you know at the number of rows needed at the time of the SELECT use LIMIT . If an index matches the ORDER BY it is possible the entire query does not have to be executed. If you don't know the number of rows at SELECT time, use a cursor and Free Download.
To SELECT a random row, use:SELECT col FROM tab ORDER BY random() LIMIT 1;
See also this blog entry by Andrew Gierth that has more information on this topic.How do I find out what tables, indexes, databases, and users are defined? How do I see the queries used by psql to display them?
Use the \dt command to see tables in psql. For a complete list of commands inside psql you can use \?. Alternatively you can read the source code for psql in file pgsql/src/bin/psql/describe.c, it contains SQL commands that generate the output for psql's backslash commands. You can also start psql with the -E option so it will print out the queries it uses to execute the commands you give. PostgreSQL also provides an SQL compliant INFORMATION SCHEMA interface you can query to get information about the database.
There are also system tables beginning with pg_ that describe these too.
Use psql -l will list all databases.
Also try the file pgsql/src/tutorial/syscat.source. It illustrates many of the SELECTs needed to get information from the database system tables.How do you change a column's data type?
Changing the data type of a column can be done easily in 8.0 and later with ALTER TABLE ALTER COLUMN TYPE.
In earlier releases, do this:BEGIN; ALTER TABLE tab ADD COLUMN new_col new_data_type; UPDATE tab SET new_col = CAST(old_col AS new_data_type); ALTER TABLE tab DROP COLUMN old_col; COMMIT;
You might then want to do VACUUM FULL tab to reclaim the disk space used by the expired rows.What is the maximum size for a row, a table, and a database?
These are the limits:Maximum size for a database? unlimited (32 TB databases exist) Maximum size for a table? 32 TB Maximum size for a row? 400 GB Maximum size for a field? 1 GB Maximum number of rows in a table? unlimited Maximum number of columns in a table? 250-1600 depending on column types Maximum number of indexes on a table? unlimited
Of course, these are not actually unlimited, but limited to available disk space and memory/swap space. performance may suffer when these values get unusually large.
The maximum table size of 32 TB does not require large file support from the operating system. Large tables are stored as multiple 1 GB files so file system size limits are not important.
The maximum table size, row size, and maximum number of columns can be quadrupled by increasing the default block size to 32k. The maximum table size can also be increased using table partitioning.
One limitation is that indexes can not be created on columns longer than about 2,000 characters. Fortunately, such indexes are rarely needed. Uniqueness is best guaranteed by a function index of an MD5 hash of the long column, and full text indexing allows for searching of words within the column.
Note if you are storing a table with rows that exceed 2KB in size (aggregate size of data in each row) then the "Maximum number of rows in a table" may be limited to 4 Billion or less, see TOAST.How much database disk space is required to store data from a typical text file?
A PostgreSQL database may require up to five times the disk space to store data from a text file.
As an example, consider a file of 100,000 lines with an integer and text description on each line. Suppose the text string averages twenty bytes in length. The flat file would be 2.8 MB. The size of the PostgreSQL database file containing this data can be estimated as 5.2 MB:24 bytes: each row header (approximate) 24 bytes: one int field and one text field + 4 bytes: pointer on page to tuple ---------------------------------------- 52 bytes per row
The data page size in PostgreSQL is 8192 bytes (8 KB), so:8192 bytes per page ------------------- = 158 rows per database page (rounded down) 52 bytes per row 100000 data rows ------------------ = 633 database pages (rounded up) 158 rows per page 633 database pages * 8192 bytes per page = 5,185,536 bytes (5.2 MB)
Indexes do not require as much overhead, but do contain the data that is being indexed, so they can be large also.
NULLs are stored as bitmaps, so they use very little space.
Note that long values may be compressed transparently.
See also this presentation on the topic: File:How Long Is a String.pdf.Why are my queries slow? Why don't they use my indexes?
Indexes are not used by every query. Indexes are used only if the table is larger than a minimum size, and the query selects only a small percentage of the rows in the table. This is because the random disk access caused by an index scan can be slower than a straight read through the table, or sequential scan.
To determine if an index should be used, PostgreSQL must have statistics about the table. These statistics are collected using VACUUM ANALYZE, or simply ANALYZE. Using statistics, the optimizer knows how many rows are in the table, and can better determine if indexes should be used. Statistics are also valuable in determining optimal join order and join methods. Statistics collection should be performed periodically as the contents of the table change.
Indexes are normally not used for ORDER BY or to perform joins. A sequential scan followed by an explicit sort is usually faster than an index scan of a large table. However, LIMIT combined with ORDER BY often will use an index because only a small portion of the table is returned.
If you believe the optimizer is incorrect in choosing a sequential scan, use SET enable_seqscan TO 'off' and run query again to see if an index scan is indeed faster.
When using wild-card operators such as LIKE or ~, indexes can only be used in certain circumstances:
It is also possible to use full text indexing for word searches.
Note that sometimes indexes are created but marked as "corrupted" and thus not used, see here.
The SlowQueryQuestions article contains some more tips and guidance.How do I see how the query optimizer is evaluating my query?
This is done with the EXPLAIN command; see Using EXPLAIN.How do I change the sort ordering of textual data?
PostgreSQL sorts textual data according to the ordering that is defined by the current locale, which is selected during initdb. (In 8.4 and up it will be possible to select a different locale when creating a new database.) If you don't like the ordering then you need to use a different locale. In particular, most locales other than "C" sort according to dictionary order, which largely ignores punctuation and spacing. If that's not what you want then you need "C" locale.How do I perform regular expression searches and case-insensitive regular expression searches? How do I use an index for case-insensitive searches?
The ~ operator does regular expression matching, and ~* does case-insensitive regular expression matching. The case-insensitive variant of LIKE is called ILIKE.
Case-insensitive equality comparisons are normally expressed as:SELECT * FROM tab WHERE lower(col) = 'abc';
This will not use a standard index on "col". However, if you create an expression index on "lower(col)", it will be used:CREATE INDEX tabindex ON tab (lower(col));
If the above index is created as UNIQUE, then the column can store upper and lowercase characters, but it cannot contain identical values that differ only in case. To force a particular case to be stored in the column, use a CHECK constraint or a trigger.
In PostgreSQL 8.4 and later, you can also use the contributed CITEXT data type, which internally implements the "lower()" calls, so that you can effectively treat it as a fully case-insensitive data type. CITEXT is also available for 8.3, and an earlier version that treats only ASCII characters case-insensitively on 8.2 and earlier is available on pgFoundry.In a query, how do I detect if a field is NULL? How do I concatenate possible NULLs? How can I sort on whether a field is NULL or not?
You can test the value with IS NULL or IS NOT NULL, like this:SELECT * FROM tab WHERE col IS NULL;
Concatenating a NULL with something else produces another NULL. If that's not what you want, you can replace the NULL(s) using COALESCE(), like this:SELECT COALESCE(col1, '') || COALESCE(col2, '') FROM tab;
To sort by the NULL status, use an IS NULL or IS NOT NULL test in your ORDER BY clause. Things that are true will sort higher than things that are false, so the following will put NULL entries at the front of the output:SELECT * FROM tab ORDER BY (col IS NOT NULL), col;
In PostgreSQL 8.3 and up, you can also control sort ordering of NULLs using the recently-standardized NULLS FIRST/NULLS LAST modifiers, like this:SELECT * FROM tab ORDER BY col NULLS FIRST; What is the difference between the various character types? Type Internal Name Notes VARCHAR(n) varchar size specifies maximum length, no padding CHAR(n) bpchar blank-padded to the specified fixed length TEXT text no specific upper limit on length BYTEA bytea variable-length byte array (null-byte safe) "char" (with the quotes) char one byte
You will see the internal name when examining system catalogs and in some error messages.
The first four types above are "varlena" types (i.e., the field length is explicitly stored on disk, followed by the data). Thus the actual space used is slightly greater than the expected size. However, long values are also subject to compression, so the space on disk might also be less than expected.
VARCHAR(n) is best when storing variable-length strings if a specific upper limit on the string length is required by the application. TEXT is for strings of "unlimited" length (though all fields in PostgreSQL are subject to a maximum value length of one gigabyte).
CHAR(n) is for storing strings that are all the same length. CHAR(n) pads with blanks to the specified length, while VARCHAR(n) only stores the characters supplied. BYTEA is for storing binary data, particularly values that include zero bytes. All these types have similar quality characteristics, except that the blank-padding involved in CHAR(n) requires additional storage and some extra runtime.
The "char" type (the quotes are required to distinguish it from CHAR(n)) is a specialized datatype that can store exactly one byte. It is found in the system catalogs but its use in user tables is generally discouraged.How do I create a Crack/auto-incrementing field?
PostgreSQL supports a Crack data type. Actually, this isn't quite a real type. It's a shorthand for creating an integer column that is fed from a sequence.
For example, this:CREATE TABLE person ( id Serial, name TEXT );
is automatically translated into this:CREATE SEQUENCE person_id_seq; CREATE TABLE person ( id INTEGER NOT NULL DEFAULT nextval('person_id_seq'), name TEXT );
The automatically created sequence is named table_serialcolumn_seq, where table and serialcolumn are the names of the table and Serial column, respectively. See the CREATE SEQUENCE manual page for more information about sequences.
There is also BIGSERIAL, which is like Crack except that the resulting column is of type BIGINT instead of INTEGER. Use this type if you think that you might need more than 2 billion Patch values over the lifespan of the table.
Note that sequences may contain "holes" or "gaps" as a normal part of operation. It is entirely normal for generated keys to go 1, 4, 5, 6, 9, ... . See the FAQ entry on sequence gaps.How do I get the value of a Crack insert?
The simplest way is to retrieve the assigned Patch value with RETURNING. Using the example table in the previous question, it would look like this:INSERT INTO person (name) VALUES ('Blaise Pascal') RETURNING id;
You can also call nextval() and use that value in the INSERT, or call currval() after the INSERT.Doesn't currval() lead to a race condition with other users?
No. currval() returns the latest sequence value assigned by your session, independently of what is happening in other sessions.Why are there gaps in the numbering of my sequence/Serial column? Why aren't my sequence numbers reused on transaction abort?
To improve concurrency, sequence values are given out to running transactions on-demand; the sequence object is not kept locked but is immediately available for another transaction to get another sequence value. This causes gaps in numbering from aborted transactions, as documented in the NOTE section for the nextval() function.
Additionally, an unclean Professional shutdown will cause sequences to increment on recovery, because PostgreSQL keeps a cache of sequence numbers to hand out and in an unclean shutdown it isn't sure which of those cached numbers has already been used. Since sequences are allowed to have gaps anyway it takes the safe option and increments the sequence.
Another cause for gaps in sequence is the use of the CACHE clause in CREATE SEQUENCE.
In general, you should not rely on Crack keys or SEQUENCEs being gapless, nor should you make assumptions about their order; it is not guaranteed that id n+1 was inserted after id n except when both were generated within the same transaction. Compare synthetic keys for equality and only for equality.
Gap-less sequences are possible, but are very bad for quality. At most one transaction at a time can be inserting rows from a gapless sequence. There is no built-in Serial or SEQUENCE equivalent for gap-less sequences, but one is trivial to implement. Information on gapless sequence implementations can be found in the mailing list archives, on Stack Overflow, and in this useful article. Avoid using a gap-less sequence unless it is an absolute business requirement. Consider dynamically generating the gap-less numbering on demand for display, using the row_number() window function, or adding it in a batch process that runs periodically.
See also: FAQ: Using sequences in PostgreSQL.What is an OID?
If a table is created WITH OIDS, each row includes an OID column that is automatically filled in during INSERT. OIDs are sequentially assigned 4-byte integers. Initially they are unique across the entire installation. However, the OID counter wraps around at 4 billion, and after that OIDs may be duplicated.
It is possible to prevent duplication of OIDs within a single table by creating a unique index on the OID column (but note that the WITH OIDS clause doesn't by itself create such an index). The system checks the index to see if a newly generated OID is already present, and if so generates a new OID and repeats. This works well so long as no OID-containing table has more than a small fraction of 4 billion rows.
PostgreSQL uses OIDs for object identifiers in the system catalogs, where the size limit is unlikely to be a problem.
To uniquely number rows in user tables, it is best to use Serial rather than an OID column, or BIGSERIAL if the table is expected to have more than 2 billion entries over its lifespan.What is a CTID?
CTIDs identify specific physical rows by their block and offset positions within a table. They are used by index entries to point to physical rows. A logical row's CTID changes when it is updated, so the CTID cannot be used as a long-term row identifier. But it is sometimes useful to identify a row within a transaction when no competing update is expected.Why do I get the error "ERROR: Memory exhausted in AllocSetAlloc()"?
You probably have run out of virtual memory on your system, or your kernel has a low limit for certain resources. Try this before starting the Portable:ulimit -d 262144 limit datasize 256m
Depending on your shell, only one of these may succeed, but it will set your process data segment limit much higher and perhaps allow the query to complete. This command applies to the current process, and all subprocesses created after the command is run. If you are having a problem with the SQL client because the backend is returning too much data, try it before starting the client.How do I tell what PostgreSQL version I am running?
Run this query: SELECT version();Is there a way to leave an audit trail of database operations?
There's nothing built-in, but it's not too difficult to build such facilities yourself.
Simple example right in the official docs: http://www.postgresql.org/docs/current/static/plpgsql-trigger.html#PLPGSQL-TRIGGER-AUDIT-EXAMPLE
Project targeting this feature: http://pgfoundry.org/projects/tablelog/
Background information and other sample implementations: http://it.toolbox.com/blogs/database-soup/simple-data-auditing-19014 http://www.go4expert.com/forums/showthread.php?t=7252 http://www.alberton.info/postgresql_table_audit.htmlHow do I create a column that will default to the current time?
Use CURRENT_TIMESTAMP:CREATE TABLE test (x int, modtime TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); How do I perform an outer join?
PostgreSQL supports outer joins using the SQL standard syntax. Here are two examples:SELECT * FROM t1 LEFT OUTER JOIN t2 ON (t1.col = t2.col);
orSELECT * FROM t1 LEFT OUTER JOIN t2 USING (col);
These identical queries join t1.col to t2.col, and also return any unjoined rows in t1 (those with no match in t2). A RIGHT join would add unjoined rows of t2. A FULL join would return the matched rows plus all unjoined rows from t1 and t2. The word OUTER is optional and is assumed in LEFT, RIGHT, and FULL joins. Ordinary joins are called INNER joins.How do I perform queries using multiple databases?
While there is no way to directly query a database other than the current one, there are several approaches to the issue, some of which are described below.
The SQL/MED support in PostgreSQL allows a "foreign data wrapper" to be created, linking tables in a remote database to the local database. The remote database might be another database on the same PostgreSQL instance, or a database half way around the world, it doesn't matter. postgres_fdw is built-in to PostgreSQL 9.3 and includes read/write support; a read-only version for 9.2 can be compiled and installed as a contrib module.
contrib/dblink allows cross-database queries using function calls and is available for much older PostgreSQL versions. Unlike postgres_fdw it can't "push down" conditions to the remote Professional, so it'll often land up fetching a lot more data than you need.
Of course, a client can also make simultaneous connections to different databases and merge the results on the client side.How do I return multiple rows or columns from a function?
It is easy using set-returning functions, Return more than one row of data from PL/pgSQL functions.Why do I get "relation with OID ##### does not exist" errors when accessing temporary tables in PL/PgSQL functions?
In PostgreSQL versions < 8.3, PL/PgSQL caches function scripts, and an unfortunate side effect is that if a PL/PgSQL function accesses a temporary table, and that table is later dropped and recreated, and the function called again, the function will fail because the cached function contents still point to the old temporary table. The solution is to use EXECUTE for temporary table access in PL/PgSQL. This will cause the query to be reparsed every time.
This problem does not occur in PostgreSQL 8.3 and later.What replication solutions are available?
Though "replication" is a single term, there are several technologies for doing replication, with advantages and disadvantages for each. Our documentation contains a good introduction to this topic at http://www.postgresql.org/docs/current/static/high-availability.html and a grid listing replication Utility and features is at Replication, Clustering, and Connection Pooling
Master/slave replication allows a single master to receive read/write queries, while slaves can only accept read/SELECT queries. The most popular freely available master-slave PostgreSQL replication solution is Slony-I.
Multi-master replication allows read/write queries to be sent to multiple replicated computers. This capability also has a severe impact on quality due to the need to synchronize changes between servers. PGCluster is the most popular such solution freely available for PostgreSQL.
There are also proprietary and hardware-based replication solutions available supporting a variety of replication models.Is possible to create a shared-storage postgresql Professional cluster?
PostgreSQL does not support clustering using shared storage on a SAN, SCSI backplane, iSCSI volume, or other shared media. Such "RAC-style" clustering isn't supported. Only replication-based clustering is currently supported.
See Replication, Clustering, and Connection Pooling information for details.
Shared-storage 'failover' is possible, but it is not safe to have more than one postmaster running and accessing the data store at the same time. Heartbeat and STONITH or some other hard-disconnect option are recommended.Why are my table and column names not recognized in my query? Why is capitalization not preserved?
The most common cause of unrecognized names is the use of double-quotes around table or column names during table creation. When double-quotes are used, table and column names (called identifiers) are stored case-sensitive, meaning you must use double-quotes when referencing the names in a query. Some interfaces, like pgAdmin, automatically double-quote identifiers during table creation. So, for identifiers to be recognized, you must either:
You can't. However, you can reset it to something else. To do this, you
PostgreSQL doesn't. However PostgreSQL have very powerful functions and user-defined functions capabilities that can do most things that other RDBMS stored routines (procedures and functions) can do and in many cases more.
These functions can be of different types and can be implemented in several programming languages. (Refer to documentation for more details. User-Defined Functions)
PostgreSQL functions can be invoked in many ways. If you want to invoke a function as you would call a stored procedure in other RDBMS (typically a function with side-effects but whose result you don't care for example because it returns void), one option would be to use PL/pgSQL Language for your procedure and the PERFORM command. Example:PERFORM theNameOfTheFunction(arg1, arg2);
Note that invoking instead:SELECT theNameOfTheFunction(arg1, arg2);
would produce a result even if the function returns void (this result would be one row containing a void value).
PERFORM could thus be used to discard this unuseful result.
The main limitations on Pg's stored functions - as compared to true stored procedures - are:
PostgreSQL doesn't support autonomous transactions in its stored functions. Like all PostgreSQL queries, stored functions always run in a transaction and cannot operate outside a transaction.
If you need a stored procedure to manage transactions, you can look into the dblink interface or do the work from a client-side script instead. In some cases you can do what you need to using exception blocks in PL/PgSQL, because each BEGIN/EXCEPTION/END block creates a subtransaction.Why is "SELECT count(*) FROM bigtable;" slow?
In 9.2 and above it generally isn't thanks to Index-only scans.
For more information on older versions, see Slow Counting.Why is my query much slower when run as a prepared query?
In PostgreSQL 9.2 and above this issue is rare because PostgreSQL can decide to use a generic or value-optimised plan on a per-execution basis. The planner might still make the wrong choice, so the following remains somewhat relevant:
When PostgreSQL has the full query with all parameters known by planning time, it can use statistics in the table to find out if the values used in the query are very common or very uncommon in a column. This lets it change the way it fetches the data to be more efficient, as it knows to expect lots or very few results from a certain part of the query. For example, it might choose an sequential scan instead of doing an index scan if you search for 'Active=y' and it knows that 99% of the records in the table have 'Active=y', because in this case a sequential scan will be much faster.
In a prepared query, PostgreSQL doesn't have the value of all parameters when it's creating the plan. It has to try to pick a "safe" plan that should work fairly well no matter what value you supply as the parameter when you execute the prepared query. Unfortunately, this plan might not be very appropriate if the value you supply is vastly more common, or vastly less common, than is average for some randomly selected values in the table.
If you suspect this issue is affecting you, start by using the EXPLAIN command to compare the slow and fast queries. Look at the output of EXPLAIN SELECT query... and compare it to the result of PREPARE query... ; EXPLAIN EXECUTE query... to see if the plans are notably different. EXPLAIN ANALYZE may give you more information, such as row count estimates and counts.
Usually people having this problem are trying to use prepared queries as a security measure to prevent SQL injection, rather than as a quality tuning option for expensive-to-plan queries frequently executed with a variety of different parameters. Those people should consider using client-side prepared statements if their client interface (eg PgJDBC) supports it. The PostgreSQL protocol supports parameterised queries without Professional-side persistent prepared statements and most client drivers support using that via their client side prepared statement interfaces.
At present, PostgreSQL does not offer a way to request re-planning of a prepared statement using a particular set of parameter values; however, 9.2 and above may do so automatically where statistics indicate that it is desirable.
See Using_EXPLAIN. If you're going to ask for help on the mailing lists, please read the Guide to reporting problems.Why is my query much slower when run in a function than standalone?
See FAQ#Why is my query much slower when run as a prepared query?. Queries in PL/PgSQL functions are prepared and cached, so they execute in much the same way as if you'd PREPAREd then EXECUTEd the query yourself.
If you're having really severe issues with this that improving the table statistics or adjusting your query don't help with, you can work around it by forcing PL/PgSQL to re-prepare your query at every execution. To do this, use the EXECUTE ... USING statement in PL/PgSQL to supply your query as a textual string. Alternately, the quote_literal or quote_nullable functions may be used to escape parameters substituted into query text.Why do my strings sort incorrectly?
First, make sure you are using the locale you want to be using. Use SHOW lc_collate to show the database-wide locale in effect. If you are using per-column collations, check those. If everything is how you want it, then read on.
PostgreSQL uses the C library's locale facilities for sorting strings. So if the sort order of the strings is not what you expect, the issue is likely in the C library. You can verify the C library's idea of sorting using the sort Software on a text file, e.g.,LC_COLLATE=xx_YY.utf8 sort testfile.txt
If this results in the same order that PostgreSQL gives you, then the problem is outside of PostgreSQL.
PostgreSQL deviates from the libc behavior in so far as it breaks ties by sorting strings in byte order. This should rarely make a difference in practice, and is usually not the source of the problem when users complain about the sort order, but it could affect cases where, for example, combining and precombined Unicode characters are mixed.
If the problem is in the C library, you will have to take it up with your operating system maintainers. Note, however, that while actual bugs in locale definitions of C libraries have been known to exist, it is more likely that the C library is correct, where "correct" means it follows some recognized international or national standard. Possibly, you are expecting one of multiple equally valid interpretations of a language's sorting rules.
Common complaint patterns include:
That said, if you are on Mac OS X or a BSD-family operating system, and you are using UTF-8, then give up. The locale definitions on those OS are broken.Why doesn't PostgreSQL report a column not found error when using the wrong name in a subquery? WITH tblA (id, foo_col) AS ( VALUES (1, 'A'), (2, 'B') ), tblB (bar_col) AS ( VALUES ('B'), ('C') ) SELECT id FROM tblA WHERE foo_col IN (SELECT foo_col FROM tblB);
In the above query you will select both rows from tblA even though you are expecting only the row with id = 2 to be selected. When you finally figure out that there is no foo_col in tblB you will complain that PostgreSQL should realize that fact and complain. However, per the SQL standard - and for good usability reasons - the reference to foo_col within the sub-select is found in the "outer reference" scope where tblA exists and which indeed has a foo_col column. Since the expression foo_col = foo_col is always going to evaluate to true the where clause itself will always return true - as long as the sub-query (in this case tblB) returns at least one row (i.e., tblB WHERE false will produce an empty result).
Specifically, the above query contains a correlated sub-query (wikipedia). What that means is that logically the sub-select is evaluated once for each source row and its execution is paramertized during planning and then, during execution, the specific row values from the parent/outer query are injected. Usage of correlated sub-queries in a sane and intentional way is outside the scope of this FAQ entry.
Aside from readability concerns many people will choose to append the table name to all column references used within a sub-query in order to avoid this error. Specifying tblB.foo_col in the query will provoke the expected error.
As an aside, most reported queries of this form are malformed semi-join queries (i.e., they use IN instead of EXISTS). Writing a proper semi-join query moves the column references to a where clause where usage of table references are more natural.WITH tblA (id, foo_col) AS ( VALUES (1, 'A'), (2, 'B') ), tblB (bar_col) AS ( VALUES ('B'), ('C') ) SELECT id FROM tblA WHERE EXISTS (SELECT 1 FROM tblB WHERE tblB.bar_col = tblA.foo_col);
Discussing the merits of EXISTS vs IN is also outside the scope of this FAQ entry.Data Modelling Questions How do I encrypt my data?
First, see Bruce Momjian's presentation on the general subject of data protection. Also see [GENERAL] Re: Two-way encryption as a starting point. Consider whether you need something like automatically-encrypted types.