gnucash/libgnucash/engine/kvp_doc.txt

/** \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/<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: 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/<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: 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 ------------------------