mirror of
https://github.com/Gnucash/gnucash.git
synced 2025-02-25 18:55:30 -06:00
83d14e1c1c
It is split into - /libgnucash (for the non-gui bits) - /gnucash (for the gui) - /common (misc source files used by both) - /bindings (currently only holds python bindings) This is the first step in restructuring the code. It will need much more fine tuning later on.
627 lines
16 KiB
Plaintext
627 lines
16 KiB
Plaintext
/** \page kvpvalues KVP Values used By GnuCash
|
|
|
|
Date Last Revised: August 2003
|
|
|
|
API: \ref KVP
|
|
|
|
This file documents the use of keys in the key-value pair system
|
|
used by the GnuCash Application (both the engine, and non-engine, GUI
|
|
pieces). Before assigning keys for use, please read the Key-Value
|
|
Policy in the GnuCash Design Document located under src/doc/design.
|
|
|
|
The format of the data below is:
|
|
|
|
Name: The name of the key, including key names of parent frames
|
|
with the parent frames listed first, as in a fully-qualified
|
|
filename. Use the '/' character to separate keys.
|
|
|
|
Type: The type of value stored in the key. The types are listed in
|
|
'kvp-value.hpp'.
|
|
|
|
Entities: Which engine entities (Accounts, Transactions, Splits)
|
|
can use this key. Use 'All' if every entity could have
|
|
the key.
|
|
|
|
Use: The use to which the key will be put. Include any requirements
|
|
for using the key here. Also include any API calls which use
|
|
the key. If more than one entity can use the key,
|
|
|
|
Example:
|
|
|
|
\verbatim
|
|
Name: /my-favorite-thing
|
|
Type: string
|
|
Entities: Account
|
|
Use: xaccGetMyFavoriteThing(), xaccSetMyFavoriteThing()
|
|
This key stores a text description of the user's
|
|
favorite thing. Do not use this key to store things
|
|
which the user merely likes!
|
|
\endverbatim
|
|
|
|
Please put the keys in alphabetical order.
|
|
|
|
\section kvpvaluelist List of existing values
|
|
|
|
[ \ref kvpA ] [ \ref kvpB ] [ \ref kvpC ] [ \ref kvpD ] [ \ref kvpE ]
|
|
[ \ref kvpF ] [ \ref kvpG ] [ \ref kvpH ] [ \ref kvpJ ] [ \ref kvpK ] [ \ref kvpL ]\n
|
|
[ \ref kvpM ] [ \ref kvpN ] [ \ref kvpO ] [ \ref kvpP ] [ \ref kvpQ ]
|
|
[ \ref kvpR ] [ \ref kvpS ] [ \ref kvpT ] [ \ref kvpU ] [ \ref kvpV ] [ \ref kvpW ]
|
|
|
|
\subsection kvpA A
|
|
|
|
\subsection kvpB B
|
|
|
|
\verbatim
|
|
Name: /book/
|
|
Type: kvp_frame
|
|
Entities: Account, Book, Transaction
|
|
Use: kvp subdirectory holding info relating to accounting periods, including
|
|
the 'twin' of an open/closed account, pointers to the open-balance
|
|
transactions, the closing dates, etc.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/accounting-period
|
|
Type: string, enum {none, week, month, quarter, trimester, year}
|
|
XXX not used, should be UIFreqSpec stuff ..
|
|
Entities: Book
|
|
Use: An enumerated identifier indicating how often books are supposed
|
|
to be closed. This key will typically be present only in an
|
|
open book, as it seems meaningless in a closed book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/close-date
|
|
Type: Timespec
|
|
Entities: Book
|
|
Use: The posted closing date of this book. This book only contains
|
|
transactions whose posted date is earlier than this closing date.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/closed-acct
|
|
Type: GUID
|
|
Entities: Transaction
|
|
Use: The GUID of the account for which this transaction represents the
|
|
opening balance. This value will occur *only* in transactions that
|
|
are opening balances.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/closed-book
|
|
Type: GUID
|
|
Entities: Transaction
|
|
Use: The GUID of the book for which this transaction represents the
|
|
opening balance. This value will occur *only* in transactions that
|
|
are opening balances.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/log-date
|
|
Type: Timespec
|
|
Entities: Book
|
|
Use: A log of the date which the user performed the closing of the book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/next-acct
|
|
Type: GUID
|
|
Entities: Account
|
|
Use: The GUID of the account that follows this one, chronologically.
|
|
Note that the open-date of the next book should equal the close-date
|
|
of the book that this account belongs to.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/next-book
|
|
Type: GUID
|
|
Entities: Account, Book
|
|
Use: The GUID of the book that follows this one, chronologically.
|
|
Note that the open-date of the next book should equal the close-date
|
|
of this book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/notes
|
|
Type: string
|
|
Entities: Book
|
|
Use: User-suplied notes for the book. The user can set this to any value
|
|
and change it at any time for any reason.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/open-date
|
|
Type: Timespec
|
|
Entities: Book
|
|
Use: The posted opening date of this book. This book only contains transactions
|
|
whose posted date is later than this closing date.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/prev-acct
|
|
Type: GUID
|
|
Entities: Account
|
|
Use: The GUID of the account that preceeds this one, chronologically.
|
|
Note that the close-date of the previous book should equal the open-date
|
|
of the book that this account belongs to.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/prev-book
|
|
Type: GUID
|
|
Entities: Account, Book
|
|
Use: The GUID of the book that preceeds this one, chronologically.
|
|
Note that the close-date of the previous book should equal the open-date
|
|
of this book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /book/title
|
|
Type: string
|
|
Entities: Book
|
|
Use: A user-suplied title for the book. The user can set this to any value
|
|
and change it at any time for any reason.
|
|
|
|
\endverbatim
|
|
|
|
\subsection kvpC C
|
|
|
|
\verbatim
|
|
Name: /counters/...
|
|
Type: int64
|
|
Entities: Book
|
|
Use: Holders for a bunch of counters for various types. Used specifically
|
|
in the business objects for ID counters. The counter name is the path
|
|
that follows /counters/, e.g. "/counters/GncCustomer"
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /counter_formats/...
|
|
Type: string
|
|
Entities: Book
|
|
Use: Holders for a bunch of counter formats for various types. Used
|
|
specifically in the business objects, to format a counter value
|
|
into a (string) ID. The counter name is the path that follows
|
|
/counter_formats/, e.g. "/counter_formats/GncCustomer"
|
|
|
|
These formats are printf-style format strings that contain exactly
|
|
one format specifier for an int64 (optionally preceded or followed
|
|
by arbitrary other strings).
|
|
\endverbatim
|
|
|
|
\subsection kvpD D
|
|
|
|
\subsection kvpE E
|
|
|
|
\subsection kvpF F
|
|
|
|
\verbatim
|
|
Name: /from-sched-xaction
|
|
Type: GUID
|
|
Entities: Transaction
|
|
Use: Identifies that the Transaction was created from a ScheduledTransaction,
|
|
and stores the GUID of that SX.
|
|
\endverbatim
|
|
|
|
\subsection kvpG G
|
|
|
|
\verbatim
|
|
Name: /gains-source
|
|
Type: guid
|
|
Entities: Split
|
|
Use: GUID of the split that is at the source of the cap gains recorded
|
|
in this split.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gains-split
|
|
Type: guid
|
|
Entities: Split
|
|
Use: GUID of the split that records the capital gains for this split.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/
|
|
Type: kvp_glist
|
|
Entities: Account, Book
|
|
Use: kvp bag holding frames that identify accounts or books
|
|
that are copies of this account.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/.*
|
|
Type: kvp_frame
|
|
Entities: Account, Book
|
|
Use: bag value holds a frame that identifies a single copied account.
|
|
Other copies would appear in other bag values.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/<type>/acct_guid
|
|
Type: guid
|
|
Entities: Account
|
|
Use: guid of another account that is a copy of this one.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/<type>/book_guid
|
|
Type: guid
|
|
Entities: Account, Book
|
|
Use: When this appears in an account, then it contains the guid of
|
|
the book that the other account belongs to. When this appears
|
|
in a book, then this is the guid of the other book.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /gemini/<type>/date
|
|
Type: timespec
|
|
Entities: Account, Book
|
|
Use: date that the copy was created.
|
|
\endverbatim
|
|
|
|
\subsection kvpH H
|
|
|
|
\verbatim
|
|
Name: /hbci/
|
|
Type: frame
|
|
Entitites: Account, Book
|
|
Use: subdirectory for information related to the German online banking
|
|
protocol HBCI
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/account-id
|
|
Type: string
|
|
Entities: Account
|
|
Use: HBCI Account code of the HBCI counterpart of this gnucash account
|
|
in the real world
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/bank-code
|
|
Type: string
|
|
Entitites: Account
|
|
Use: Bank code of HBCI account
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/country-code
|
|
Type: gint64
|
|
Entitites: Account
|
|
Use: Country code of the bank of HBCI account
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/trans-retrieval
|
|
Type: Timespec
|
|
Entities: Account
|
|
Use: Time of the last statement retrieval through HBCI for this
|
|
specific account
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /hbci/config-filename
|
|
Type: string
|
|
Entitied: Book
|
|
Use: OpenHBCI configuration file name, where the real HBCI
|
|
configuration for the OpenHBCI library can be found
|
|
\endverbatim
|
|
|
|
\subsection kvpJ J
|
|
|
|
\subsection kvpK K
|
|
|
|
\subsection kvpL L
|
|
|
|
\verbatim
|
|
Name: last-num
|
|
Type: string
|
|
Entities: Account
|
|
Use: xaccAccountGetLastNum, xaccAccountSetLastNum
|
|
Store the last number used in an account's transactions.
|
|
Used in auto-filling the Num field.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-mgmt/
|
|
Type: kvp_frame
|
|
Entities: Account
|
|
Use: Frame holding info regarding how lots should be managed in this
|
|
account, including what accounting policy to use, where realized
|
|
gains should be reported, and etc.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-mgmt/gains-acct/
|
|
Type: frame
|
|
Entities: Account
|
|
Use: When a lot in this account is double-balanced, this frame
|
|
holds per-currency accounts to which realized gains are to
|
|
be posted.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-mgmt/gains-acct/xxxxx
|
|
Type: guid
|
|
Entities: Account
|
|
Use: When a lot in this account is double-balanced, this key specifies
|
|
the account to which realized gains are to be posted.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-mgmt/next-id
|
|
Type: int64
|
|
Entities: Account
|
|
Use: The next unused lot id number, used to autogenerate
|
|
a lot title.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-split/
|
|
Type: kvp_glist
|
|
Entities: Split
|
|
Use: A bag of kvp frames holding identification of splits
|
|
that were split off of this split. Same style as the
|
|
/gemini/, look there for additional doco's.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /lot-split/<type>/peer_guid
|
|
Type: GUID
|
|
Entities: Split
|
|
Use: The GUID of the peer split which was split from this split.
|
|
\endverbatim
|
|
|
|
\subsection kvpM M
|
|
|
|
\subsection kvpN N
|
|
|
|
\verbatim
|
|
Name: /notes
|
|
Type: string
|
|
Entities: Account, Lot, Transaction
|
|
Use: A user-suplied 'Notes' text field. The user can set this to
|
|
any value and change it at any time for any reason.
|
|
Accessors: xaccAccountGetNotes(), xaccAccountSetNotes(),
|
|
xaccTransGetNotes(), xaccTransSetNotes()
|
|
\endverbatim
|
|
|
|
\subsection kvpO O
|
|
|
|
\verbatim
|
|
Name: old-currency
|
|
Type: string
|
|
Entities: Account
|
|
Use: This string holds the canonical name of the old Account
|
|
currency. This may be deleted at some point in the future.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: old-currency-scu
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: This holds the old currency scu. This may be deleted at
|
|
some point in the future.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: old-docref
|
|
Type: string
|
|
Entities: Transactions, Splits
|
|
Use: This string holds the old Docref value which was supported in earlier
|
|
versions of GnuCash but which was never used for any purpose. The
|
|
value is retained in case any users were making use of it.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: old-price-source
|
|
Type: string
|
|
Entities: Account
|
|
Use: This string holds the old Price Source code used by earlier versions
|
|
of GnuCash and stored in the obsolete AccInfo structure. The use of
|
|
this value will be deprecated when the new version of Finance::Quote
|
|
is fully supported. The new version of Finance::Quote uses a different
|
|
scheme to identify sources for price quotes.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: old-security
|
|
Type: string
|
|
Entities: Account
|
|
Use: This string holds the canonical name of the old Account
|
|
security. This may be deleted at some point in the future.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: old-security-scu
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: This holds the old security scu. This may be deleted at
|
|
some point in the future.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: online-id
|
|
Type: string
|
|
Entities: All
|
|
Use: This holds a unique identifier for accounts, transactions and splits
|
|
created by the generic import layer. This allows imports of
|
|
successive statements to automatically match accounts and transactions
|
|
which have already been imported.
|
|
|
|
This used to be set on transactions but not splits. It is now set on
|
|
splits but not transactions. It is still checked on transactions, but
|
|
this may change at some point in the future.
|
|
|
|
\subsection kvpP P
|
|
|
|
\subsection kvpQ Q
|
|
|
|
\subsection kvpR R
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/
|
|
Type: frame
|
|
Entities: Account
|
|
Use: store reconcile information about accounts
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/include-children
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: A boolean flag indicating whether transactions in sub-accounts should be
|
|
included during reconcilition.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/last-date
|
|
Type: frame
|
|
Entities: Account
|
|
Use: store the statement date of the last reconciliation
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/postpone/date
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: store the ending statement date of a postponed reconciliation
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/postpone/balance
|
|
Type: numeric
|
|
Entities: Account
|
|
Use: store the ending balance of a postponed reconciliation
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /reconcile-info/auto-interest-transfer
|
|
Type: string
|
|
Entities: Account
|
|
Use: allows the user to override the global reconcile option
|
|
"Automatic interest transfer" on a per-account basis.
|
|
Acceptable values are "true" and "false".
|
|
(This really could use a KVP_TYPE_BOOLEAN.)
|
|
\endverbatim
|
|
|
|
\subsection kvpS S
|
|
|
|
\verbatim
|
|
Name: /sched-xaction/
|
|
Type: frame
|
|
Entities: Split in a SchedXaction
|
|
Use: Storage for the various fields of a scheduled transaction's
|
|
template Splits.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /sched-xaction/account
|
|
Type: GUID
|
|
Entities: Split associated with a SchedXaction
|
|
Use: The GUID of this Split's xfrm account.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /sched-xaction/credit-formula
|
|
Type: string
|
|
Entities: Split associated with a SchedXaction
|
|
Use: Store the formula for the credit side of the split
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /sched-xaction/debit-formula
|
|
Type: string
|
|
Entities: Split associated with a SchedXaction
|
|
Use: Formula for the debit. Either the credit or the
|
|
debit formula must be empty.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: split-type
|
|
Entities: Split
|
|
Use: xaccSplitGetType, xaccSplitMakeStockSplit
|
|
Store a string representing the type of split, if not normal.
|
|
\endverbatim
|
|
|
|
\subsection kvpT T
|
|
|
|
\verbatim
|
|
Name: /tax-US/code
|
|
Type: string
|
|
Entities: Account
|
|
Use: see src/scm/report/[tax,txf]*.scm
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /tax-US/payer-name-source
|
|
Type: string
|
|
Entities: Account
|
|
Use: see src/scm/report/[tax,txf]*.scm
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: tax-related
|
|
Type: gint64
|
|
Entities: Account
|
|
Use: A boolean flag indicated whether the Account is tax-related.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: /title
|
|
Type: string
|
|
Entities: Lot
|
|
Use: A user-supplied title for the lot. The user can set this to
|
|
any value and change it at any time for any reason.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: trans-date-due
|
|
Type: Timespec
|
|
Entities: Transaction
|
|
Use: Accounts/Receivable, Accounts/Payable Due Date.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: trans-txn-type
|
|
Type: string
|
|
Entities: Transaction
|
|
Use: A/R, A/P Transaction Type (Invoice or Payment)
|
|
\endverbatim
|
|
|
|
\subsection kvpU U
|
|
|
|
\verbatim
|
|
Name: user-keys
|
|
Type: frame
|
|
Entities: All
|
|
Use: This frame is used to store keys which are editable directly by
|
|
the user. The program should not attach any semantics to keys
|
|
under this frame.
|
|
\endverbatim
|
|
|
|
\subsection kvpV V
|
|
|
|
\verbatim
|
|
Name: void-reason
|
|
Type: string
|
|
Entities: Transaction
|
|
Use: This string is used to store the reason why a transaction has been
|
|
voided. Note that it should only exist if the transaction has been voided.
|
|
\endverbatim
|
|
|
|
\verbatim
|
|
Name: void-former-amount
|
|
Type: gnc_numeric
|
|
Entities: Split
|
|
Use: To store the amount of the this split before it was voided. Note
|
|
that it should only exist if the parent transaction has been voided (but
|
|
checking the reconcile status of the split is a more direct way of finding
|
|
out a split has been voided).
|
|
\endverbatim
|
|
|
|
\subsection kvpW W
|
|
*/
|
|
|
|
--------------------------- end of document ------------------------
|