SCRIPTS Script Playing: "Playing" a script is the process of executing all commands in the script. In order to play a script, it must be created and registered first; see below for more details. If your database already contains scripts, all you need to do is select the Script Play item from the File menu. xpg will open a dialog listing all scripts registered for the current database. You can double-click on the desired script description, or select one (by clicking on it) and then pressing the Ok button. To learn more about the way xpg passes and executes scripts, read on. An xpg script is a file which contains Postgres commands, similar to command files which you can feed into the monitor program. In fact, xpg scripts differ from such command files mainly in three ways: Backslash-commands, Error handling, and viewing of classes and portals. Backslash-commands: xpg supports none of them. In xpg the query buffer contains exactly one query, which is ended when a newline character is encountered, and the script ends when there are no more lines to read. Error handling: While executing Postgres commands, xpg can be in one of three modes: Warn: In this mode, which is the default mode, failed Postgres commands cause a warning message to pop-up and describe the nature of the error. xpg does not wait for the warning message to be dismissed; it immediately resumes execution of the script. This may cause multiple warning messages if there is a set of commands which depend on the successful execution of a previous command (or commands). In this case, you might want to consider using the next mode. Abort: In this mode, failed Postgres commands abort the execution of the rest of the script. A descriptive error message is popped-up to notify the user when such an error occurs. Ignore: In this mode, failed Postgres commands are regarded as ignorable, and do not cause warning messages or abort the script execution. An example possible use for this mode is when executing a "create" command, which is where you might want to avoid a Postgres message which warns that the class already exists. As noted earlier, the default mode is the warn mode. You can change this default mode anywhere inside the script, by including an error-mode keyword, in a line of its own. The keywords are: ERR-WARN, ERR-ABORT and ERR-IGNORE, for the warn, abort, and ignore modes, respectively. You can change the default mode as many times as you want in a single script; the new mode remains in effect until a different error-mode keyword is encountered, or until the end of the script is reached. You can also switch temporarily to a different mode, which applies only for a single command. You do this by including the desired error-mode keyword at the beginning of the line of the command, followed by one or more space characters. For example, "ERR-IGNORE create class-can-exist (...)". Viewing: In order to view a class or portal from within a script, you have the VIEWCLASS and VIEWPORTAL commands. Including the line "VIEWCLASS " or "VIEWPORTAL " (each in a line of its own), opens a new viewer with the class or portal requested. "Retrieve" commands which would normally output their results to the tty, would open a new portal viewer, carrying a temporary name. This is the same behavior found in the Execute Dialog (see the EXECUTE DIALOG section). Note: For all the xpg-specific keywords in the script syntax, case matters. All keywords must be entered in upper-case. (This makes them different from the regular Postgres keywords which must be in lower-case.) The Script Catalog: Writing your script is not all there is to it. You must also register your script in the xpg Script Catalog. This catalog is implemented as a regular Postgres relation, named "xpg_scripts", which is local to each database. This relation consists of two attributes, both of type Text: "description", and "fname". In order to register your script, view the "xpg_scripts" relation(*), and use the Append command (see the CLASS OPERATIONS section) to add a tuple, in which the "description" attribute contains a short line describing your script (this line will later appear in the script dialog), and the "fname" attribute contains the full pathname of the script. Note: In order to append tuples to the "xpg_scripts" relation, it must be created first. This is automatically done for you when the "Play Script" command is issued in a database where this relation has not been created yet; so simply issue this command - xpg will open the Script Dialog (which will contain no scripts, of course). You can then close the dialog and start appending your scripts. --- (*) Note that you may not see this relation in the list of relations when you issue a View Class command. This happens if the showPgClasses resource is False (see the XPG RESOURCES section). In this case, the easiest way is to manually enter the relation name in the text area of the dialog.