Difference between revisions of "He/שימוש ב API"

From GnuCash
Jump to: navigation, search
(→‎תיעוד: Translation)
(→‎יצירת תנועה חדשה: translation)
Line 35: Line 35:
  
 
== יצירת תנועה חדשה ==
 
== יצירת תנועה חדשה ==
−
Here's the code to create a new transaction (abbreviated by "txn") and populate it with data, using "almost correct" C code (in reality, all the variable declarations must appear on top and not within the code):
+
להלן הקוד ליצירת תנועה חדשה (בקיצור "txn") ואכלסה בנתונים תוך שימוש בקוד C "כמעט אמיתי" (במציאות כל הצהרות המשתנים חייבות להופיע בתחילת הקוד בראש התסריט ולא משולב בתוך שורות הקוד):
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
−
  Account *account = ...; // get this from somewhere
+
  Account *account = ...; // לקבל זאת מהיכן שהו
 
  QofBook *book = gnc_account_get_book(account);
 
  QofBook *book = gnc_account_get_book(account);
 
   
 
   
−
  Transaction *transaction = xaccMallocTransaction(book); // Creating the new transaction
+
  Transaction *transaction = xaccMallocTransaction(book); // יצירת התנועה החדשה
−
  xaccTransBeginEdit(transaction); // Opening it for editing
+
  xaccTransBeginEdit(transaction); // פתיחת התנועה לעריכה
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
The txn is created. We can set the txn-related data fields:
+
קוד txn נוצר. כעת ניתן להגדיר את שדות המידע הקשורים לקוד ה-txn:
  
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
−
  xaccTransSetDatePostedSecs(transaction, 1234567); // Date of this txn
+
  xaccTransSetDatePostedSecs(transaction, 1234567); // תאריך txn זה
 
  xaccTransSetNum(transaction, "X23");
 
  xaccTransSetNum(transaction, "X23");
−
  xaccTransSetNotes(transaction, "Some notes, bla bla");
+
  xaccTransSetNotes(transaction, "הערות כל שהן...");
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
As gnucash is capable of multi-currency handling, every txn must have a "transaction currency" set:
+
מכיוון שגנוקאש מסוגלת לטפל ברבוי-מטבעות , כל txn חייב לכלול הגדרת ''מטבע תנועה'':
 
   
 
   
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
 
  Commodity *currency = xaccAccountGetCommodity(account);
 
  Commodity *currency = xaccAccountGetCommodity(account);
−
  xaccTransSetCurrency(transaction, currency); // Txn must have a commodity/currency set
+
  xaccTransSetCurrency(transaction, currency); // Txn חייב לכלול הגדרות/סחורה/מטבע
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
The actual amount/value of a transaction is given by its two or more splits. We create the first split:
+
הסכום/הערך בפועל של התנועה יתקבל על ידי שנים (או יותר) הפיצולים שלה. הקוד ייצור את הפיצול הראשון:
  
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
 
  Split *split = xaccMallocSplit(book);
 
  Split *split = xaccMallocSplit(book);
−
  xaccTransAppendSplit(transaction, split); // Split belongs to this txn
+
  xaccTransAppendSplit(transaction, split); // הפיצול שייך  זהtxn ל-
−
  xaccAccountInsertSplit(account, split); // Split belongs to this account
+
  xaccAccountInsertSplit(account, split); // הפיצול שייך לחזבון זה
 
  gnc_numeric amount = gnc_numeric_create(123, 100); // 1.23
 
  gnc_numeric amount = gnc_numeric_create(123, 100); // 1.23
 
  xaccSplitSetValue(split, amount);
 
  xaccSplitSetValue(split, amount);

Revision as of 07:06, 13 May 2021

שפות אנגלית גרמנית ספרדית עִברִית פורטוגזית צרפתית

כללי

עמוד זה מרכז מספר דוגמאות אודות אופן השימוש ב- C API של גנוקאש לצורך מניפולציה בסיסית בסוגי נתונים. C API (מכונה גם "המנוע") הוא שכבה שהפשטה מכל שרת. כלומר, מתכנת של מנשק המשתמש או מתכנת המתקעים לעולם לא יוכלו לגשת לאף אחד מתוכניות ה-XML או ה-SQL ישירות, במקום זאת הוא משתמש רק בפונקציות של מנשק ה- API כדי לגשת לנתונים.

תיעוד

As for documentation: Unfortunately there doesn't exist any up-to-date coherent set of documentation. Part of it is in דוקסיג'ן, but part of it are only in the C header files.

A module overview is available for those parts that are documented in doxygen. For example, there is a module group entitled "GnuCash Engine: Core, Non-GUI Accounting Functions" which contains the doxygen-ized parts of this, including the "Account", but not including Transaction and Split which are the other important basic data types.

Entity-Relationship Diagram is an up-to-date (May 2011, but the schema is unchanged in mid-2017) Entity-Relationship-Diagram (ERD) which shows those most important types of gnucash (in the form of tables, as common for an ERD):

  • פיצול
  • תנועה
  • חשבון
  • סחורה (typedef name: gnc_commodity)
  • ספר (typedef name: QofBook)

המקום היחיד בו ניתן למצוא מידע עדכני לבטח הם בכותרות הקבצים:

  • libgnucash/engine/Split.h
  • libgnucash/engine/Transaction.h
  • libgnucash/engine/Account.h
  • libgnucash/engine/gnc-commodity.h
  • libgnucash/engine/qofbook.h

יצירת תנועה חדשה

להלן הקוד ליצירת תנועה חדשה (בקיצור "txn") ואכלסה בנתונים תוך שימוש בקוד C "כמעט אמיתי" (במציאות כל הצהרות המשתנים חייבות להופיע בתחילת הקוד בראש התסריט ולא משולב בתוך שורות הקוד): 

 Account *account = ...; // לקבל זאת מהיכן שהו
 QofBook *book = gnc_account_get_book(account);
 
 Transaction *transaction = xaccMallocTransaction(book); // יצירת התנועה החדשה
 xaccTransBeginEdit(transaction); // פתיחת התנועה לעריכה

קוד txn נוצר. כעת ניתן להגדיר את שדות המידע הקשורים לקוד ה-txn: 

 xaccTransSetDatePostedSecs(transaction, 1234567); // תאריך txn זה
 xaccTransSetNum(transaction, "X23");
 xaccTransSetNotes(transaction, "הערות כל שהן...");

מכיוון שגנוקאש מסוגלת לטפל ברבוי-מטבעות , כל txn חייב לכלול הגדרת מטבע תנועה: 

 Commodity *currency = xaccAccountGetCommodity(account);
 xaccTransSetCurrency(transaction, currency); // Txn חייב לכלול הגדרות/סחורה/מטבע

הסכום/הערך בפועל של התנועה יתקבל על ידי שנים (או יותר) הפיצולים שלה. הקוד ייצור את הפיצול הראשון: 

 Split *split = xaccMallocSplit(book);
 xaccTransAppendSplit(transaction, split); // הפיצול שייך  זהtxn ל-
 xaccAccountInsertSplit(account, split); // הפיצול שייך לחזבון זה
 gnc_numeric amount = gnc_numeric_create(123, 100); // 1.23
 xaccSplitSetValue(split, amount);
 xaccSplitSetAmount(split, amount);

As for the SetValue and SetAmount: In multi-currency or stock trading txn, the amount is different from the value and vice versa. As long as you're dealing with exactly one currency, both value and amount are set to be the same value.

Then we create the second split so that we have a normal two-split transaction, as usual in the double-entry bookkeeping: 

 Account* other_account = ...; // need to get this from somewhere
 Split *split2 = xaccMallocSplit(book);
 xaccTransAppendSplit(transaction, split2); // Split belongs to this txn
 xaccAccountInsertSplit(other_account, split2); // Split belongs to this account
 gnc_numeric other_amount = gnc_numeric_create(-123, 100); // -1.23, the negative value for above
 xaccSplitSetValue(split, other_amount);
 xaccSplitSetAmount(split, other_amount);

In the end, we must finish the transaction editing by calling the CommitEdit function: 

 xaccTransCommitEdit(transaction); // We are finished editing

דוגמאות שימוש

ניתן למצא מספר דוגמאות ב- Python_shell#Usage_examples.
Retrieved from "https://code.gnucash.org/wiki/index.php?title=He/שימוש_ב_API&oldid=19370"