execsql2 2.18.0__py3-none-any.whl → 2.19.0__py3-none-any.whl

execsql/db/mysql.py

@@ -73,12 +73,6 @@ class MySQLDatabase(Database):
             f"{self.need_passwd!r}, {self.port!r}, {self.encoding!r})"
         )
 
-    def auto_commits_ddl(self) -> bool:
-        """MySQL / MariaDB implicitly commit DDL — ``rollback()`` is a
-        silent no-op for any transaction whose boundary the DDL
-        crossed. See ``docs/about/divergence.md``."""
-        return True
-
     def quote_identifier(self, identifier: str) -> str:
         """MySQL / MariaDB native identifier quoting uses backticks.
 

execsql/db/oracle.py

@@ -61,12 +61,6 @@ class OracleDatabase(Database):
             f"{self.need_passwd!r}, {self.port!r}, {self.encoding!r})"
         )
 
-    def auto_commits_ddl(self) -> bool:
-        """Oracle implicitly commits DDL — ``rollback()`` is a silent
-        no-op for any transaction whose boundary the DDL crossed.
-        See ``docs/about/divergence.md`` for the per-DBMS matrix."""
-        return True
-
     def open_db(self) -> None:
         """Open a connection to the Oracle database."""
         import cx_Oracle

execsql/db/sqlserver.py

@@ -58,12 +58,6 @@ class SqlServerDatabase(Database):
             f"{self.need_passwd!r}, {self.port!r}, {self.encoding!r})"
         )
 
-    def auto_commits_ddl(self) -> bool:
-        """SQL Server implicitly commits DDL on Microsoft's pyodbc
-        driver in autocommit mode — ``rollback()`` is a silent no-op
-        for any transaction whose boundary the DDL crossed."""
-        return True
-
     def quote_identifier(self, identifier: str) -> str:
         """SQL Server native identifier quoting uses square brackets.
 

execsql/debug/repl.py

@@ -12,10 +12,26 @@ The REPL allows the user to:
 - Step through the script one statement at a time.
 - Resume or abort execution.
 
-All REPL commands are dot-prefixed (``.continue``, ``.vars``, ``.next``)
-to avoid ambiguity with variable names and SQL.  Anything not starting
-with ``.`` is treated as either a variable lookup (if it matches a known
-variable) or SQL (if it ends with ``;``).
+Dispatch is two-way (psql-style): input starting with ``.`` is a REPL
+command (``.continue``, ``.vars [VAR]``, ``.next``, etc.), everything
+else is SQL.  Multi-line SQL is supported: any non-``.`` input opens a
+buffer whose continuation prompt is ``  ...        > ``, accumulating
+until a line ends with ``;``.  ``.cancel`` (or Ctrl-C / EOF) discards
+the partial buffer.
+
+Variable lookup is explicit — ``.vars LOGFILE`` prints one variable;
+``.vars`` lists them all.  There is no bare-identifier lookup, so any
+SQL keyword you type starts a buffer the moment you press Enter.
+
+The trailing ``;`` is the SQL terminator both within one line and across
+multiple lines — the REPL has no read-only mode and DDL on most adapters
+is irreversible, so requiring ``;`` is a small intent gate against
+accidental DML/DDL on mistyped input.  Use SQL ``BEGIN; … ROLLBACK;`` to
+bracket exploratory DML if you need recoverability.
+
+Errors raised by any REPL helper — bad SQL, malformed dot-commands, etc. —
+are caught at the loop level so the session re-prompts instead of escaping
+through ``x_breakpoint`` and being stamped as a "Metacommand error".
 
 In non-interactive environments (CI, piped input, ``sys.stdin.isatty()`` is
 ``False``) the metacommand is silently skipped so automated pipelines are not
@@ -104,21 +120,21 @@ def _c(code: str, text: str) -> str:
 
 _HELP_COMMANDS = [
     (".continue", ".c", "Resume script execution"),
-    (".abort", ".q", "Halt the script (exit 1)"),
-    (".vars", ".v", "List user, system, local, and counter variables"),
-    (".vars all", ".v all", "Include environment variables (&) in the listing"),
+    (".quit", ".q", "Halt the script (exit 1)"),
+    (".vars", ".v", "List all execsql substitution variables"),
+    (".vars VAR", ".v VAR", "Print the value of a single variable (e.g. .vars logfile)"),
     (".next", ".n", "Execute the next statement then pause again (step mode)"),
     (".where", ".w", "Show the current script location and upcoming statement"),
     (".stack", "", "Show the command-list stack (script name, line, depth)"),
     (".set VAR VAL", ".s", "Set or update a substitution variable"),
     (".scripts", "", "List all registered SCRIPT definitions"),
     (".scripts NAME", "", "Show detail for a specific SCRIPT"),
+    (".cancel", "", "Discard a partial multi-line SQL buffer"),
     (".help", ".h", "Show this help text"),
 ]
 
 _HELP_OTHER = [
-    ("varname", "Print a variable's value (e.g. logfile, $ARG_1, &HOME)"),
-    ("SELECT ...;", "Run SQL ending with ';' (expects columns returned, e.g. SELECT)"),
+    ("SELECT ...;", "Run SQL — multi-line accepted, terminate with ';' to execute"),
 ]
 
 _HELP_CMD_WIDTH = 13  # width of the command column
@@ -216,40 +232,71 @@ def _debug_repl(*, step: bool = False) -> None:
     _hint_c = _c(_DIM, "'.c'")
     _write(f"  Type {_hint_help} for commands, {_hint_c} to resume.\n\n")
 
+    sql_buffer: list[str] = []
+
     while True:
+        prompt = "  ...        > " if sql_buffer else "execsql debug> "
         try:
-            line = input("execsql debug> ").strip()
+            line = input(prompt).strip()
         except EOFError:
+            if sql_buffer:
+                sql_buffer.clear()
+                _write("\n  (input discarded)\n")
+                continue
             _write("\n")
-            return  # Ctrl-D → continue
+            return
         except KeyboardInterrupt:
+            if sql_buffer:
+                sql_buffer.clear()
+                _write("\n  (input discarded)\n")
+                continue
             _write("\n")
-            return  # Ctrl-C → continue
+            return
 
         if not line:
             continue
 
-        # Dot-prefixed → REPL command
-        if line.startswith("."):
-            cmd = line[1:].strip().lower()
-            _handle_dot_command(line)
-            if cmd in ("continue", "c"):
-                return
-            if cmd in ("abort", "q", "quit"):
-                # _handle_dot_command already raised SystemExit, but guard anyway
-                return
-            if cmd in ("next", "n"):
-                return
+        try:
+            if line.startswith("."):
+                cmd = line[1:].strip().lower()
+                if cmd == "cancel":
+                    if sql_buffer:
+                        sql_buffer.clear()
+                        _write("  (input discarded)\n")
+                    continue
+                _handle_dot_command(line)
+                if cmd in ("continue", "c"):
+                    return
+                if cmd in ("abort", "q", "quit"):
+                    return
+                if cmd in ("next", "n"):
+                    return
+                continue
+
+            if sql_buffer:
+                sql_buffer.append(line)
+                joined = " ".join(sql_buffer)
+                if joined.rstrip().endswith(";"):
+                    _run_sql(joined)
+                    sql_buffer.clear()
+                continue
+
+            if line.rstrip().endswith(";"):
+                _run_sql(line)
+                continue
+
+            sql_buffer.append(line)
+        except SystemExit:
+            raise
+        except KeyboardInterrupt:
+            sql_buffer.clear()
+            _write("\n  (interrupted)\n")
             continue
-
-        # SQL (ends with semicolon)
-        if line.rstrip().endswith(";"):
-            _run_sql(line)
+        except Exception as exc:
+            sql_buffer.clear()
+            _write(f"  {_c(_RED, 'Error:')} {exc}\n")
             continue
 
-        # Everything else → variable lookup
-        _print_var(line)
-
 
 def _handle_dot_command(line: str) -> None:
     """Dispatch a dot-prefixed REPL command."""
@@ -262,10 +309,14 @@ def _handle_dot_command(line: str) -> None:
         raise SystemExit(1)
     elif cmd in ("help", "h"):
         _write(_format_help())
-    elif cmd in ("vars all", "v all"):
-        _print_all_vars(include_env=True)
     elif cmd in ("vars", "v"):
         _print_all_vars()
+    elif cmd.startswith("vars ") or cmd.startswith("v "):
+        rest = cmd.split(None, 1)[1].strip() if " " in cmd else ""
+        if rest:
+            _print_var(rest)
+        else:
+            _print_all_vars()
     elif cmd in ("where", "w"):
         _print_where()
     elif cmd == "stack":
@@ -383,7 +434,11 @@ def _print_all_vars(*, include_env: bool = False) -> None:
         _write(f"  {_c(_BOLD, label)}:\n")
         max_name = max(len(n) for n, _ in group)
         for name, value in group:
-            _write(f"    {_c(_CYAN, name):<{max_name}}  {_c(_DIM, '=')}  {value}\n")
+            # Pre-compute padding from RAW name length — the format-spec ``:<{max_name}``
+            # form measures the colored string, which (when ANSI is on) is ~9 chars
+            # longer per wrap and breaks the column alignment.
+            pad = " " * (max_name - len(name))
+            _write(f"    {_c(_CYAN, name)}{pad}  {_c(_DIM, '=')}  {value}\n")
 
     _print_group("User", user_vars)
     _print_group("System ($)", system_vars)
@@ -477,7 +532,7 @@ def _print_stack() -> None:
 
 
 def _run_sql(sql: str) -> None:
-    """Execute ad-hoc SQL against the current database and pretty-print the results."""
+    """Execute ad-hoc SQL and pretty-print results or affected rowcount."""
     dbs = _state.dbs
     if dbs is None:
         _write("  (no database connection is active)\n")
@@ -486,8 +541,35 @@ def _run_sql(sql: str) -> None:
     if db is None:
         _write("  (no database connection is active)\n")
         return
+
     try:
-        colnames, rows = db.select_data(sql)
+        with db._cursor() as curs:
+            try:
+                curs.execute(sql)
+            except Exception as exc:
+                try:
+                    db.rollback()
+                except Exception:
+                    pass
+                _write(f"  {_c(_RED, 'SQL error:')} {exc}\n")
+                return
+
+            try:
+                _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
+            except Exception:
+                pass
+
+            if curs.description is None:
+                rowcount = curs.rowcount if curs.rowcount is not None else -1
+                if rowcount >= 0:
+                    row_word = "row" if rowcount == 1 else "rows"
+                    _write(f"  {_c(_DIM, f'({rowcount} {row_word} affected)')}\n")
+                else:
+                    _write(f"  {_c(_DIM, '(statement executed)')}\n")
+                return
+
+            colnames = [d[0] for d in curs.description]
+            rows = curs.fetchall()
     except Exception as exc:
         _write(f"  {_c(_RED, 'SQL error:')} {exc}\n")
         return

execsql/exporters/feather.py

@@ -58,20 +58,26 @@ def write_query_to_hdf5(
             other_msg="The tables Python library must be installed to export data to the HDF5 format.",
         ) from e
     try:
-        hdrs, rows = db.select_rowsource(select_stmt)
+        hdrs, row_iter = db.select_rowsource(select_stmt)
     except ErrInfo:
         raise
     except Exception as e:
         raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
+    # Materialize once so DataTable's type inference (below) and the write
+    # loop (further below) share the same rows without a second query.
+    rows = list(row_iter)
 
     def h5type(datatype, size):
-        if datatype in (_state.DT_Varchar, _state.DT_Text):
+        if datatype == _state.DT_Varchar:
             t = tables.StringCol(size)
             do_cast = False
         elif datatype == _state.DT_Text:
             t = tables.StringCol(_state.conf.hdf5_text_len)
             do_cast = False
-        elif datatype in (_state.DT_Integer, _state.DT_Long):
+        elif datatype == _state.DT_Long:
+            t = tables.Int64Col()
+            do_cast = False
+        elif datatype == _state.DT_Integer:
             t = tables.IntCol()
             do_cast = False
         elif datatype in (_state.DT_Float, _state.DT_Decimal):
@@ -87,25 +93,20 @@ def write_query_to_hdf5(
             raise ErrInfo("error", other_msg=f"Invalid data type for export to HDF5: {repr(datatype)}")
         return t, do_cast
 
-    # Create a dictionary of column names with the HDF5 data types
     tbl_desc = DataTable(hdrs, rows)
     h5type_dict = {}
     cast_flags = []
-    # Iterate over hdrs instead of tbl_desc.cols to preserve column order.
     for h in hdrs:
         dt = [col for col in tbl_desc.cols if col.name == h][0].dt
-        # dt is a tuple of: 0: the column name; 1: the data type class; 2: the maximum length or None if NA; other info.
+        # dt is (name, data-type-class, max-length-or-None, ...)
         h5typ, as_str = h5type(dt[1], dt[2])
         h5type_dict[h] = h5typ
         cast_flags.append(as_str)
-    # Open the HDF5 table
     filewriter_close(outfile)
     h5file_mode = "a" if append else "w"
     h5file = tables.open_file(outfile, mode=h5file_mode)
     h5grp = h5file.create_group("/", table_name, title=desc)
     h5tbl = h5file.create_table(h5grp, table_name, h5type_dict)
-    # Write the data.
-    hdrs, rows = db.select_rowsource(select_stmt)
     for datarow in rows:
         h5row = h5tbl.row
         for i, h in enumerate(hdrs):

execsql/format.py

@@ -16,11 +16,27 @@ import io
 import re
 from pathlib import Path
 
-import sqlglot
-import sqlglot.errors
-
 __all__ = ["collect_paths", "format_file", "main", "parse_keyword"]
 
+
+_SQLGLOT_MISSING_MSG = (
+    "execsql-format requires sqlglot for SQL reformatting.\n"
+    "  Install with:  pip install execsql2[formatter]\n"
+    "  Or skip SQL reformatting with the --no-sql flag."
+)
+
+
+def _require_sqlglot():
+    """Lazy import of sqlglot, raising ImportError with an install hint if missing."""
+    try:
+        import sqlglot
+        import sqlglot.errors  # noqa: F401
+
+        return sqlglot
+    except ImportError as e:
+        raise ImportError(_SQLGLOT_MISSING_MSG) from e
+
+
 # ---------------------------------------------------------------------------
 # Constants
 # ---------------------------------------------------------------------------
@@ -161,6 +177,9 @@ def _sqlglot_format(
     leading_comma: bool = False,
 ) -> list[str]:
     """Format a list of SQL-only lines (no comment-only lines) via sqlglot."""
+    sqlglot = _require_sqlglot()
+    import sqlglot.errors as sqlglot_errors
+
     text = "\n".join(sql_lines)
     protected, replacements = _protect_variables(text)
 
@@ -169,7 +188,7 @@ def _sqlglot_format(
 
     try:
         with contextlib.redirect_stderr(io.StringIO()):
-            ast = sqlglot.parse(protected, read="postgres", error_level=sqlglot.errors.ErrorLevel.IGNORE)
+            ast = sqlglot.parse(protected, read="postgres", error_level=sqlglot_errors.ErrorLevel.IGNORE)
             statements: list[str] = []
             for node in ast:
                 if node is None:

execsql/importers/base.py

@@ -15,7 +15,6 @@ from typing import Any
 from execsql.exceptions import ErrInfo
 from execsql.db.base import Database
 import execsql.state as _state
-from execsql.types import dbt_firebird
 
 __all__ = ["import_data_table"]
 
@@ -84,9 +83,9 @@ def import_data_table(
         sql = get_ts().create_table(db.type, schemaname, tablename)
         try:
             db.execute(sql)
-            # Don't commit here; commit will be done after populating the table
-            # ...except for Firebird.
-            if db.type == dbt_firebird:
+            # Most adapters delay commit until after populating the table; adapters
+            # that need DDL committed first (Firebird) must do it here.
+            if db.needs_explicit_commit_after_ddl():
                 db.conn.commit()
         except Exception as e:
             raise ErrInfo(

execsql/importers/xls.py

@@ -39,7 +39,12 @@ def xls_data(
 
         wbk = XlsFile()
     elif ext3 == "lsx":
-        # openpyxl imported lazily
+        from execsql.utils.fileio import check_zip_decompression_ratio
+
+        try:
+            check_zip_decompression_ratio(filename)
+        except FileNotFoundError:
+            pass
         from execsql.exporters.xls import XlsxFile
 
         wbk = XlsxFile()

execsql/metacommands/__init__.py

@@ -2,8 +2,8 @@
 
 Importing this module populates a ``MetaCommandList`` (``DISPATCH_TABLE``)
 with every metacommand regex and its handler function. The dispatch
-table is consumed by ``script.MetacommandStmt.run()`` via
-``_state.metacommandlist``.
+table is consumed by :func:`execsql.script.executor._exec_metacommand`
+via ``_state.metacommandlist``.
 
 The table itself is built by ``build_dispatch_table()`` in
 :mod:`execsql.metacommands.dispatch`. Handler functions are organized

execsql/metacommands/data.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
+
 from execsql.exceptions import ErrInfo
 
 """

execsql/metacommands/dispatch.py

@@ -1377,8 +1377,8 @@ def build_dispatch_table() -> MetaCommandList:
     # BEGIN / END BATCH / ROLLBACK
     # ------------------------------------------------------------------
     mcl.add(r"^\s*BEGIN\s+BATCH\s*$", x_begin_batch, description="BEGIN BATCH", category="block")
-    mcl.add(r"^\s*END\s+BATCH\s*$", x_end_batch, "END BATCH", run_in_batch=True, category="block")
-    mcl.add(r"^\s*ROLLBACK(:?\s+BATCH)?\s*$", x_rollback, "ROLLBACK BATCH", run_in_batch=True, category="block")
+    mcl.add(r"^\s*END\s+BATCH\s*$", x_end_batch, "END BATCH", category="block")
+    mcl.add(r"^\s*ROLLBACK(:?\s+BATCH)?\s*$", x_rollback, "ROLLBACK BATCH", category="block")
 
     # ------------------------------------------------------------------
     # ERROR_HALT / METACOMMAND_ERROR_HALT / CANCEL_HALT
@@ -1727,14 +1727,12 @@ def build_dispatch_table() -> MetaCommandList:
         x_assert,
         description="ASSERT",
         category="action",
-        run_when_false=False,
     )
     mcl.add(
         r"^\s*ASSERT\s+(?P<condtest>.+?)\s+(?P<message>(?:\"[^\"]*\"|'[^']*'))\s*$",
         x_assert,
         description="ASSERT",
         category="action",
-        run_when_false=False,
     )
 
     # ------------------------------------------------------------------
@@ -1745,7 +1743,6 @@ def build_dispatch_table() -> MetaCommandList:
         x_breakpoint,
         description="BREAKPOINT",
         category="action",
-        run_when_false=False,
     )
 
     # ------------------------------------------------------------------
@@ -1765,26 +1762,24 @@ def build_dispatch_table() -> MetaCommandList:
         r"^\s*ORIF\s*\(\s*(?P<condtest>.+)\s*\)\s*$",
         x_if_orif,
         description="ORIF",
-        run_when_false=True,
         category="control",
     )
     mcl.add(
         r"^\s*ELSEIF\s*\(\s*(?P<condtest>.+)\s*\)\s*$",
         x_if_elseif,
         description="ELSEIF",
-        run_when_false=True,
         category="control",
     )
     mcl.add(r"^\s*ANDIF\s*\(\s*(?P<condtest>.+)\s*\)\s*$", x_if_andif, description="ANDIF", category="control")
-    mcl.add(r"^\s*ELSE\s*$", x_if_else, description="ELSE", run_when_false=True, category="control")
+    mcl.add(r"^\s*ELSE\s*$", x_if_else, description="ELSE", category="control")
     mcl.add(
         r"^\s*IF\s*\(\s*(?P<condtest>.+)\s*\)\s*{\s*(?P<condcmd>.+)\s*}\s*$",
         x_if,
         description="IF",
         category="control",
     )
-    mcl.add(r"^\s*IF\s*\(\s*(?P<condtest>.+)\s*\)\s*$", x_if_block, run_when_false=True, category="control")
-    mcl.add(r"^\s*ENDIF\s*$", x_if_end, description="ENDIF", run_when_false=True, category="control")
+    mcl.add(r"^\s*IF\s*\(\s*(?P<condtest>.+)\s*\)\s*$", x_if_block, category="control")
+    mcl.add(r"^\s*ENDIF\s*$", x_if_end, description="ENDIF", category="control")
 
     # ------------------------------------------------------------------
     # CONNECT — SQL Server

execsql/metacommands/script_ext.py

@@ -3,22 +3,23 @@ from __future__ import annotations
 """
 Script-block extension and dispatch handlers for execsql.
 
-Handlers for the named-script invocation and dynamic-extension
-metacommands. Used by both the AST executor and legacy command paths:
+Handlers for the named-script extension metacommands invoked by the
+AST executor:
 
-- ``x_executescript`` — ``EXECUTE SCRIPT <name>`` / ``RUN SCRIPT <name>``
-  (look up a previously-registered ``BEGIN SCRIPT`` block and run it,
-  optionally with parameter bindings and a WHILE / UNTIL loop).
 - ``x_extendscript`` — ``EXTEND SCRIPT <name> WITH SCRIPT|FILE …``
   (append additional commands to an existing named script block from
   an inline source).
 - ``x_extendscript_metacommand`` — ``EXTEND SCRIPT … WITH METACOMMAND …``.
 - ``x_extendscript_sql`` — ``EXTEND SCRIPT … WITH SQL …``.
+- ``x_executescript`` — dispatch-table sentinel only. ``EXECUTE SCRIPT``
+  / ``RUN SCRIPT`` are handled natively by the AST executor; this stub
+  raises ``ErrInfo`` if the parser ever fails to recognize them as
+  structural nodes.
 
 Registration of ``BEGIN SCRIPT … END SCRIPT`` blocks themselves is
 handled by the AST parser (block boundaries) and executor (registering
-the block on ``ctx.ast_scripts``); this module is only the call-site /
-extension handlers.
+the block on ``ctx.ast_scripts``); this module is only the
+extension-site handlers.
 """
 
 import copy

execsql/script/engine.py

@@ -67,25 +67,18 @@ class MetaCommand:
         rx: Any,
         exec_func: Any,
         description: str | None = None,
-        run_in_batch: bool = False,
-        run_when_false: bool = False,
         set_error_flag: bool = True,
         category: str | None = None,
     ) -> None:
         self.rx = rx
         self.exec_fn = exec_func
         self.description = description
-        self.run_in_batch = run_in_batch
-        self.run_when_false = run_when_false
         self.set_error_flag = set_error_flag
         self.category = category
         self.hitcount = 0
 
     def __repr__(self) -> str:
-        return (
-            f"MetaCommand({self.rx.pattern!r}, {self.exec_fn!r}, {self.description!r}, "
-            f"{self.run_in_batch!r}, {self.run_when_false!r})"
-        )
+        return f"MetaCommand({self.rx.pattern!r}, {self.exec_fn!r}, {self.description!r})"
 
     def run(self, cmd_str: str) -> tuple:
         """Match *cmd_str* against this entry's regex and, if it matches, invoke the handler.
@@ -171,8 +164,6 @@ class MetaCommandList:
         matching_regexes: Any,
         exec_func: Any,
         description: str | None = None,
-        run_in_batch: bool = False,
-        run_when_false: bool = False,
         set_error_flag: bool = True,
         category: str | None = None,
     ) -> None:
@@ -193,8 +184,6 @@ class MetaCommandList:
                 rx,
                 exec_func,
                 description,
-                run_in_batch,
-                run_when_false,
                 set_error_flag,
                 category,
             )

execsql/script/executor.py

@@ -83,10 +83,6 @@ _DEFER_RX = re.compile(r"!\{([$@&~#+]?\w+)\}!")
 _VARLIKE = re.compile(r"!![$@&~#]?\w+!!", re.I)
 
 
-# Legacy module-level alias — ``_ast_scripts`` is now ``ctx.ast_scripts``
-# on the RuntimeContext.  Kept as a comment for grep-ability.
-
-
 def _stack_localvars(ctx: RuntimeContext) -> SubVarSet | None:
     """Build the merged ``~`` local + ``#`` param overlay for the current scope.
 
@@ -210,7 +206,7 @@ def _set_command_vars(ctx: RuntimeContext, source: str, line_no: int) -> None:
 
 
 # ---------------------------------------------------------------------------
-# SQL execution (bypasses SqlStmt.run's if_stack check)
+# SQL execution
 # ---------------------------------------------------------------------------
 
 
@@ -264,7 +260,7 @@ def _exec_sql(
 
 
 # ---------------------------------------------------------------------------
-# Metacommand execution (bypasses MetacommandStmt.run's if_stack check)
+# Metacommand execution
 # ---------------------------------------------------------------------------