book.open

Open an XML or SQLite book. Some books open read-only (see readOnlyReasons).

Opens an existing GnuCash book, XML or SQLite, so the other methods can read and change it. Call it first, with the book's path; a server holds one book at a time, so close the open one with book.close before opening another. Unless you ask for readOnly, it takes the book's lock, as GnuCash does, and fails with book-locked while GnuCash or another red-ale has the book open.

A book can also open read-only without being asked: readOnly is then true and readOnlyReasons says why, for instance a Book feature red-ale does not implement. Read-only books are never locked and never written.

Examples

Example: with a copy of the reports/test-data example book saved as book.gnucash, not open.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"book.open","params":{"path":"book.gnucash"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "path": "…",
    "guid": "…",
    "rootAccount": "…",
    "readOnly": false,
    "readOnlyReasons": [],
    "dirty": false,
    "compressed": "…",
    "format": "xml",
    "journal": "…",
    "features": "…",
    "counts": "…"
  }
}

Command line

red-ale exec book.open '{"path":"book.gnucash"}'

It prints:

{
  "path": "…",
  "guid": "…",
  "rootAccount": "…",
  "readOnly": false,
  "readOnlyReasons": [],
  "dirty": false,
  "compressed": "…",
  "format": "xml",
  "journal": "…",
  "features": "…",
  "counts": "…"
}

MCP tool call

Tool call:

{"name":"book.open","arguments":{"path":"book.gnucash"}}

Result:

{
  "structuredContent": {
    "path": "…",
    "guid": "…",
    "rootAccount": "…",
    "readOnly": false,
    "readOnlyReasons": [],
    "dirty": false,
    "compressed": "…",
    "format": "xml",
    "journal": "…",
    "features": "…",
    "counts": "…"
  }
}

Opening it read-only leaves it free for GnuCash:

Example: with a copy of the reports/test-data example book saved as book.gnucash, not open.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"book.open","params":{"path":"book.gnucash","readOnly":true}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "readOnly": true,
    "readOnlyReasons": [
      {
        "code": "requested",
        "message": "opened read-only on request"
      }
    ],
    "…": "…"
  }
}

Command line

red-ale exec book.open '{"path":"book.gnucash","readOnly":true}'

It prints:

{
  "readOnly": true,
  "readOnlyReasons": [
    {
      "code": "requested",
      "message": "opened read-only on request"
    }
  ],
  "…": "…"
}

MCP tool call

Tool call:

{"name":"book.open","arguments":{"path":"book.gnucash","readOnly":true}}

Result:

{
  "structuredContent": {
    "readOnly": true,
    "readOnlyReasons": [
      {
        "code": "requested",
        "message": "opened read-only on request"
      }
    ],
    "…": "…"
  }
}

Effect: read.

Params

Params of book.open.

path (string, required): A path, or an xml://, sqlite3:// or file:// URI.
readOnly (boolean): Open without taking the lock; nothing can be changed.

Result

The result of book.open, book.create and book.info.

path (string, required): The book's file.
guid (Guid, required): The book's GUID.
rootAccount (Guid, required): The root account's GUID.
readOnly (boolean, required): Nothing can be changed.
readOnlyReasons (array of ReadOnlyInfo, required): Why, when read-only.
dirty (boolean, required): There are unsaved changes.
compressed (boolean, required): The file is gzip-compressed; always false for an SQLite book.
format (BookFormat, required): The file's format: xml or sqlite.
versions (array of VersionInfo or null): SQLite books only: the versions table as read, in its order.
journal (string or null): The transaction journal being written, if any.
features (array of FeatureInfo, required): Book features the book declares.
counts (Counts, required): Entity counts.