<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.

~~~if WINGPRO:
**Run in Container** is present in projects that use a container configuration, to select
whether the command should be run on the local host or in the container.
~~~

**I/O Encoding** is the encoding to use for text sent to and received from the sub-process.
On Windows, this defaults to UTF-8.  On other platforms, it defaults to the console's
native encoding.  When set to UTF-8 on Windows, ``PYTHONIOENCODING`` is set in the
sub-process environment and terminal commands use ``chcp 65001`` so that ``cmd.exe``
also operates in UTF-8 mode.  To revert to the system's default code page, set this
to ``Console default``.

**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** runs the subprocess in a pseudo-TTY and uses a TTY-enabled console
that supports color, cursor movement, and other ANSI escape sequences.  On Linux and macOS,
this uses a Unix pseudo-TTY. On Windows 10 (version 1809 and later) and Windows 11, it uses the ConPTY
pseudo-terminal interface.  When this option is enabled, the ``Start Terminal`` command
creates a terminal with ``TERM`` set to ``xterm-256color`` on Linux and macOS.  This option
is hidden on versions of Windows older than Windows 10 version 1809.

**Line Mode** 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 hidden on older versions of Windows that lack
ConPTY support.

**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.
