/** \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: Time64 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: Time64 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: Time64 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 precedes 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 precedes 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//acct_guid Type: guid Entities: Account Use: guid of another account that is a copy of this one. \endverbatim \verbatim Name: /gemini//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//date Type: time64 Entities: Account, Book Use: date that the copy was created. \endverbatim \subsection kvpH H \verbatim Name: /hbci/ Type: frame Entities: 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 Entities: Account Use: Bank code of HBCI account \endverbatim \verbatim Name: /hbci/country-code Type: gint64 Entities: Account Use: Country code of the bank of HBCI account \endverbatim \verbatim Name: /hbci/trans-retrieval Type: Time64 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//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: Time64 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 ------------------------