mirror of
https://github.com/Gnucash/gnucash.git
synced 2024-11-26 02:40:43 -06:00
document the KVP values used by the book
git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@6176 57a11ea4-9604-0410-9ed3-97b8803252fd
This commit is contained in:
Linas Vepstas
parent
e5fe29e6c1
commit
b876d45ca4
@ -181,6 +181,7 @@ static void
|
||||
add_closing_balances (AccountGroup *closed_grp,
|
||||
GNCBook *open_book,
|
||||
GNCBook *closed_book,
|
||||
Account *equity_account,
|
||||
Timespec *post_date, Timespec *date_entered,
|
||||
const char *desc)
|
||||
{
|
||||
@ -244,7 +245,14 @@ add_closing_balances (AccountGroup *closed_grp,
|
||||
|
||||
/* find the equity account into which we'll poke the
|
||||
* balancing transaction */
|
||||
equity = find_nearest_equity_acct (twin);
|
||||
if (NULL == equity_account)
|
||||
{
|
||||
equity = find_nearest_equity_acct (twin);
|
||||
}
|
||||
else
|
||||
{
|
||||
equity = equity_account;
|
||||
}
|
||||
|
||||
/* -------------------------------- */
|
||||
/* create the balancing transaction */
|
||||
@ -297,6 +305,7 @@ add_closing_balances (AccountGroup *closed_grp,
|
||||
if (childs)
|
||||
{
|
||||
add_closing_balances (childs, open_book, closed_book,
|
||||
equity_account,
|
||||
post_date, date_entered, desc);
|
||||
}
|
||||
}
|
||||
@ -306,7 +315,8 @@ add_closing_balances (AccountGroup *closed_grp,
|
||||
/* split a book into two by date */
|
||||
|
||||
GNCBook *
|
||||
gnc_book_calve_period (GNCBook *existing_book, Timespec calve_date,
|
||||
gnc_book_close_period (GNCBook *existing_book, Timespec calve_date,
|
||||
Account *equity_account,
|
||||
const char * memo)
|
||||
{
|
||||
Query *query;
|
||||
@ -315,6 +325,8 @@ gnc_book_calve_period (GNCBook *existing_book, Timespec calve_date,
|
||||
kvp_value *vvv;
|
||||
Timespec ts;
|
||||
|
||||
if (!existing_book) return NULL;
|
||||
|
||||
/* Get all transactions that are *earlier* than the calve date,
|
||||
* and put them in the new book. */
|
||||
query = xaccMallocQuery();
|
||||
@ -332,14 +344,14 @@ gnc_book_calve_period (GNCBook *existing_book, Timespec calve_date,
|
||||
|
||||
/* Mark the boundary date between the books */
|
||||
vvv = kvp_value_new_timespec (calve_date);
|
||||
kvp_frame_set_slot_nc (exist_cwd, "start-date", vvv);
|
||||
kvp_frame_set_slot_nc (partn_cwd, "end-date", vvv);
|
||||
kvp_frame_set_slot_nc (exist_cwd, "open-date", vvv);
|
||||
kvp_frame_set_slot_nc (partn_cwd, "close-date", vvv);
|
||||
|
||||
/* Mark partition as being closed */
|
||||
ts.tv_sec = time(0);
|
||||
ts.tv_nsec = 0;
|
||||
vvv = kvp_value_new_timespec (ts);
|
||||
kvp_frame_set_slot_nc (partn_cwd, "close-date", vvv);
|
||||
kvp_frame_set_slot_nc (partn_cwd, "log-date", vvv);
|
||||
|
||||
/* Set up pointers to each book from the other. */
|
||||
vvv = kvp_value_new_guid (&existing_book->guid);
|
||||
@ -352,6 +364,7 @@ gnc_book_calve_period (GNCBook *existing_book, Timespec calve_date,
|
||||
* hold the colsing balances */
|
||||
add_closing_balances (gnc_book_get_group(partition_book),
|
||||
existing_book, partition_book,
|
||||
equity_account,
|
||||
&calve_date, &ts, memo);
|
||||
return partition_book;
|
||||
}
|
||||
|
||||
@ -22,53 +22,81 @@
|
||||
#include "Query.h"
|
||||
|
||||
|
||||
/* The gnc_book_calve_period() routine will split the indicated
|
||||
* book into two books, returning a newly created book with
|
||||
* the older transactions placed in it.
|
||||
/* The gnc_book_close_period() routine will 'close' a book at
|
||||
* the indicated date. It returns a pointer to the closed book,
|
||||
* while the argument remains open. This routine will move
|
||||
* all of the older transactions from the open book to the
|
||||
* closed book. The guid's of the old transactions will not
|
||||
* be changed in the move. Note, however, that the closed
|
||||
* book will have a copy of every account in the open book,
|
||||
* and that these copies will have new GUID's issued to them.
|
||||
* Thus, every account has a 'twin' in the other book.
|
||||
*
|
||||
* This routine will also create 'equity transactions' in
|
||||
* order to preserve the balances on accounts. For any
|
||||
* account that is not of income, expense or equity type,
|
||||
* this routine wil find the closing balance of each account
|
||||
* in the closed book. It will then create an 'equity
|
||||
* transaction' in the open book, creating an opening balance
|
||||
* between an equity account and the twin account to the
|
||||
* closed account. The 'memo' field will be used to set
|
||||
* the description in the equity transaction. Typically,
|
||||
* you will want to set this field to _("Opening Balance").
|
||||
*
|
||||
* The 'memo' is used as the description in the transaction that
|
||||
* creates the opening balances for the accounts. Typically,
|
||||
* it should be _("Opening Balance")
|
||||
* The equity_account argument is supposed to indicate the
|
||||
* equity account in the open book into which the opening
|
||||
* balances will be placed. This argument may be NULL,
|
||||
* if it is NULL, then a search algorithm will be used to
|
||||
* find a suitable equity account. If NULL, this routine
|
||||
* searches for the 'nearest' account of GNCAccountType EQUITY
|
||||
* among its siblings, or the siblings of its parents. It
|
||||
* does not search downwards. If it does not find such an
|
||||
* account, it will create one, hanging off the top-most group.
|
||||
*
|
||||
-- Make an equity transfer so that we can carry forward the balances.
|
||||
the equity account is created if not found. only the peers and
|
||||
immediate parents of an account is searchd for the qeuity account.
|
||||
* This routine also populates a number of KVP values in
|
||||
* order to make a log of the closing. In principle, the
|
||||
* stored KVP's should be enough to locate everything needed
|
||||
* to safely re-open and re-close a closed book. In particular,
|
||||
* if a closed book is re-opened, the 'equity transaction'
|
||||
* would need to be adjusted.
|
||||
*
|
||||
* The kvp values that are set are:
|
||||
*
|
||||
* Implemented in the closed book:
|
||||
* /book/close-date Latest date in this book. Must not change.
|
||||
* /book/log-date Date on which user called this routine.
|
||||
* /book/next-book GUID of next book (the still-open book).
|
||||
*
|
||||
* Implemented in still-open book:
|
||||
* /book/open-date Earliest date in this book.
|
||||
* /book/prev-book GUID of previous book (the closed book).
|
||||
*
|
||||
* Implemented in the balancing transaction:
|
||||
* /book/closed-acct GUID of account whose balance was brought forward
|
||||
* /book/closed-book GUID of book whose balance was brought forward
|
||||
*
|
||||
* Implemented in the closed account:
|
||||
* /book/balancing-trans GUID of equity-balancing transaction.
|
||||
* /book/next-book GUID of equity-balancing book.
|
||||
* /book/next-acct GUID of twin of this account in the open book.
|
||||
*
|
||||
* Implemented in the still-open account:
|
||||
* /book/prev-acct GUID of twin of this account in the closed book.
|
||||
* /book/prev-book GUID of previous book (the closed book)
|
||||
*
|
||||
-- hack alert --
|
||||
Not imlemented (yet), these should go into book:
|
||||
/book/name=some-user-supplied-name
|
||||
/book/notes=user-supplied-descriptive-comments
|
||||
/book/accounting-period=enum {none, week, month, quarter, trimester, year}
|
||||
|
||||
-- hack alert -- should not allow closed books to have unreconciled
|
||||
transactions ???
|
||||
-- It will use the following kvp entries in /book/:
|
||||
|
||||
Implemented in the closed book:
|
||||
/book/end-date latest date in this book. must not change ...
|
||||
/book/close-date date on which book was closed.
|
||||
/book/next-book guid of next book (the still-open book)
|
||||
|
||||
Implemented in still-open book:
|
||||
/book/start-date earliest date in this book.
|
||||
/book/prev-book guid of previous book (the closed book)
|
||||
|
||||
Implemented in the balancing transaction:
|
||||
/book/closed-acct guid of account whose balance was brought forward
|
||||
/book/closed-book guid of book whose balance was brought forward
|
||||
|
||||
Implemented in the closed account:
|
||||
/book/balancing-trans GUID of equity-balancing transaction.
|
||||
/book/next-book GUID of equity-balancing book.
|
||||
/book/next-acct GUID of twin of this account in the open book.
|
||||
|
||||
Implemented in the still-open account:
|
||||
/book/prev-acct GUID of twin of this account in the closed book.
|
||||
/book/prev-book guid of previous book (the closed book)
|
||||
|
||||
Not imlemented (yet), these should go into book:
|
||||
/book/name=some-user-supplied-name
|
||||
/book/notes=user-supplied-descriptive-comments
|
||||
/book/accounting-period=enum {none, week, month, quarter, trimester, year}
|
||||
|
||||
|
||||
|
||||
*/
|
||||
GNCBook * gnc_book_calve_period (GNCBook *, Timespec, const char *memo);
|
||||
GNCBook * gnc_book_close_period (GNCBook *, Timespec,
|
||||
Account *equity_acct,
|
||||
const char *memo);
|
||||
|
||||
/* The gnc_book_partition() uses the result of the indicated query
|
||||
* to partition an existing book into two parts. It returns
|
||||
|
||||
@ -39,6 +39,73 @@ Use: xaccGetMyFavoriteThing(), xaccSetMyFavoriteThing()
|
||||
Please put the keys in alphabetical order.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Name: /book/log-date
|
||||
Type: Timespec
|
||||
Entities: Book
|
||||
Use: A log of the date which the user performed the closing of the book.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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 laterr than this closing date.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
-----------------------
|
||||
|
||||
Name: from-sched-xaction
|
||||
Type: GUID
|
||||
@ -146,33 +213,35 @@ Entities: Account
|
||||
Use: This holds the old security scu. This may be deleted at
|
||||
some point in the future.
|
||||
|
||||
Name: reconcile-info
|
||||
-----------------------
|
||||
|
||||
Name: /reconcile-info
|
||||
Type: frame
|
||||
Entities: Account
|
||||
Use: store reconcile information about accounts
|
||||
|
||||
Name: reconcile-info/include-children
|
||||
Name: /reconcile-info/include-children
|
||||
Type: gint64
|
||||
Entities: Account
|
||||
Use: A boolean flag indicating whether transactions in sub-accounts should be
|
||||
included during reconcilition.
|
||||
|
||||
Name: reconcile-info/last-date
|
||||
Name: /reconcile-info/last-date
|
||||
Type: frame
|
||||
Entities: Account
|
||||
Use: store the statement date of the last reconciliation
|
||||
|
||||
Name: reconcile-info/postpone/date
|
||||
Name: /reconcile-info/postpone/date
|
||||
Type: gint64
|
||||
Entities: Account
|
||||
Use: store the ending statement date of a postponed reconciliation
|
||||
|
||||
Name: reconcile-info/postpone/balance
|
||||
Name: /reconcile-info/postpone/balance
|
||||
Type: numeric
|
||||
Entities: Account
|
||||
Use: store the ending balance of a postponed reconciliation
|
||||
|
||||
Name: reconcile-info/auto-interest-transfer
|
||||
Name: /reconcile-info/auto-interest-transfer
|
||||
Type: string
|
||||
Entities: Account
|
||||
Use: allows the user to override the global reconcile option
|
||||
@ -180,6 +249,8 @@ Use: allows the user to override the global reconcile option
|
||||
Acceptable values are "true" and "false".
|
||||
(This really could use a KVP_TYPE_BOOLEAN.)
|
||||
|
||||
-----------------------
|
||||
|
||||
Name: /sched-xaction/
|
||||
Type: frame
|
||||
Entities: Split in a SchedXaction
|
||||
@ -206,6 +277,8 @@ Entities: Split
|
||||
Use: xaccSplitGetType, xaccSplitMakeStockSplit
|
||||
Store a string representing the type of split, if not normal.
|
||||
|
||||
-----------------------
|
||||
|
||||
Name: /tax-US/code
|
||||
Type: string
|
||||
Entities: Account
|
||||
|
||||
Loading…
Reference in New Issue
Block a user