This plugin is designed to pass feature data to your shell ("/bin/sh" on unix or linux machines, "c:\\windows\\system32\\cmd.exe" on windows). Properly employed, it can speed and simplify many common QGIS tasks which would otherwise would take lots of typing and mouse clicking.
The ShellDB Configure choice is where you tell ShellDB what command you wish to run and what feature data you wish to pass to it. If you click the Configure menu choice, you'll see the Shell Script Plugin Setup panel. Click the Find Script button to bring up a file menu where you can select the script to which you wish to pass feature data. You can also type a shell command directly in to the Shell Command Line box on this panel.
Next, you'll pick the vector layer where the features you're working with reside. Do this by clicking on its name from the Map Layers: list. When you click on this name, the names of the fields in its backing store will appear in the Data Fields: list. Right now, alas, you can only work with one vector layer at a time in this plugin.Now you're ready to pick the data fields you wish to pass to the shell. When you click on a member of the Data Fields: list, you'll see it appear surrounded by "@@" in the Shell Command Line field. You can, of course simply type "@@fieldname@@" in to the Shell Command Line field if you wish. If you mess this up, the template string will simply be passed whole to your shell script (e.g. if you specify "@@FOO@@" when you meant "@@BAR@@", your script will see "@@FOO@@" rather than the contents of the "BAR" data field. If the field you're going to pass to the shell contains spaces or other special characters, you will need to surround the "@@fieldname@@" in the Shell Command Line box with single or double-quotes to ensure it is properly passed to your shell script.
You are now ready to start picking features with the select feature of QGIS and passing them to the shell with the Run choice in the ShellDB plugin. You have a few other options before doing so, however. You can use the Find Log File button to fill out the Log File text box, if you want ShellDB to keep a log of the stdout and stderr streams from your shell script. This can be handy if you have errors in your shell script, although of course there's nothing to prevent you from logging things inside your script, separate from this facility. If you check the Delete Processed Features radio button, ShellDB will delete features from your map after it has processed them; this is very handy if you're doing a lot of map features and need to keep track of what you have and have not done. This feature will, however, permanently delete features from your map. If you leave the Edit Commands button clicked in ShellDB's configuration, then ShellDB will display a text editor to allow you to examine or change the shell commands it has created before running them.
ShellDB keeps its configuration in your QGIS project, so once you save your project you won't have to reconfigure ShellDB when you bring it back up. If the configuration dialog completely fails ( by giving a python error message), you can manually edit the .qgs file to remove or change the <ShellDB> stanza in the project xml.
After you have configured ShellDB, you can create shell commands and run them on features you have selected. To do this, use the select tool to select the features you wish to run commands against, then press the Run choice from the ShellDB menu choice. If you have the Edit Commands radio button selected in the Configure panel, you'll see an edit box pop up in the middle of your screen with the command lines you're about to pass to the shell. You can edit your command lines here, but don't delete commands or change their order; doing so will cause internal errors in ShellDB.
After you press <OK> in the command edit screen, the commands you have constructed will run and your map will re-draw, possibly with the features you processed deleted. You can then select more features and select Run to process more map features through ShellDB.
An operating system error occurred while ShellDB was trying to pass command lines to the shell. The exact error should appear in the message box. The most common error is a file not found error, when the script is not where ShellDB thinks it is. This error will halt all further processing of command lines.
You selected to Run the ShellDB plugin but provided no selected features for it to process.
You tried to run the ShellDB plugin before it was configured. This message can also appear if you have deleted the layer for which ShellDB is configured.
One or more of the command lines you ran in this group of selected features has returned an errorlevel of more than 0. This doesn't stop processing; subsequent commands will run. If you configured a ShellDB log file, you can look in it for additional information on what happened. If the Delete Processed Features radio button is set, ShellDB will not delete features corresponding to command lines with non-0 errorlevels.
Setting a query on a vector layer turns it read-only. If you lack privilege to write to a shape file or database table, you will also get this error.
If you remove the layer which ShellDB is working on and then re-add it to your project, ShellDB will not be able to find the layer. This is because QGis layer names include the date and time they were created, in order to you to add two or more layers with the same display name. To fix this trouble, re-select the layer (with its new timestamp value) which you are working on in the Map Layers: line of ShellDB's Configure panel.
If ShellDB cannot find her log file, she will notify you of this fact and continue to march. Fix the Log File line in ShellDB's Configure panel to fix this.
Copyright 2012 Spatial Focus Incorporated
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see the GNU License Page.