<type>documentation</type>
<domain>oscommands</domain>
<id>properties</id>
<title>OS Command Properties</title>
<date>$Date: 2006-05-26 17:43:42 -0400 (Fri, 26 May 2006) $</date>
<version>$Revision: 13128 $</version>
<product>per+</product>

The runtime environment for commands added to the ``OS Commands`` tool is configured
in the dialog shown when the item is added or edited.

**Shared Properties**

All OS Command types share the following configurable properties:

**Title** is the display title to use for the command. If not set, the command line or
file name is shown instead.

**I/O Encoding** is the encoding to use for text sent to and received from the sub-process.

**Key Binding** assigns a key binding to execute the command. To enter a binding, just
press the desired binding while focus is in the ``Key Binding`` field. Bindings can
consist of multiple parts, such as ``Ctrl-H B``. Pressing multiple keys will create a key
binding sequence, unless too much time elapses between the key presses. To reset the value
to blank (no key binding), select all text and press ``Backspace`` or ``Delete``.

**Raise OS Commands When Executed** causes the ``OS Commands`` tool to be shown whenever
this command is executed. When disabled, the tool will not be brought to front.

**Auto-save Files Before Execution** automatically saves any unsaved changes in open files
before the command is executed, even if the `Files > Auto-Save Files Before Debug or Execute 
<script:show_preferences_gui#prefname="gui.auto-save-before-action">`__ preference is
disabled.

**Use Pseudo-TTY** (on Linux and OS X) runs the subprocess in a pseudo-TTY and tries to
(minimally) emulate how the command would work in a shell. Many of the ANSI escape
sequences are not supported, but the basics should work. For some commands, adding options
can help it to work better in the ``OS Commands`` tool. For example, ``bash -norc`` works
better than ``bash`` if you have bash using colors, and ``ipython -colors NoColor`` works
better than ``ipython`` alone.  This option is omitted for OS Commands being executed on
Windows.

**Line Mode** (on Linux and OS X) can be disabled to enter raw mode and send every
keystroke to the subprocess, rather than collecting input line by line. Often, but not
always, when a pseudo-TTY is being used then line mode should be disabled. Some
experimentation may be required to determine the best settings. This option
is omitted for OS Commands executed on Windows, and all I/O is performed line by line.

**Shared** stores the OS Command in the `Settings Directory
<ref:install/user-settings-dir>`__ so that it appears in all projects.

**Additional Properties for Command Lines**

The ``Environment`` tab provided for *Command Line* style OS Commands allows specifying the
``Initial Directory``, ``Python Path``, and ``Environment``, which act the same as the
corresponding values configurable in `Project Properties`__.

__ ref:proj/project-properties

~~~if WINGPRO:
**Hostname** (only in Wing Pro) is used with *Command Line* style OS Commands to select the
remote host where the command should be executed. For *Python File* and *Named
Entry Point* style OS Commands, the hostname on which the command will execute is
determined by the location of the Python file. See `Remote Hosts <ref:proj/remote-hosts>`__ 
for details. 
~~~

In command lines, use ``$(ENV)`` or ``${ENV}`` to insert values from the
environment or from the special variables enumerated in `Environment Variable Expansion
<ref:proj/variable-expansion>`__. These values will be empty if undefined.

Note that the commands are executed on their own and not in a shell, so any commands
that are built into the shell cannot be used here.  For example, on Windows ``dir`` 
and some others are built-in commands so cannot be used directly; however, the form 
``cmd /c dir`` will work in this case.  On Linux, invoking ``bash`` directly may
be necessary in similar cases.

**Additional Properties for Python Files**

For *Python File* style OS Commands, ``Python Prompt after Execution`` in the ``Options``
menu specifies that the Python interpreter should be left active and at a prompt after the
file is executed.

**Test Execute**

While editing command properties, the ``Test Execute`` button can be used
to try executing with the current settings.  A temporary entry is added
to the ``OS Commands`` tool, and removed again after the command properties
dialog is closed.
