Leonardo and I have been working on structuring together some notes and docs for fcl-db and sqldb. I am not as experienced with sqldb yet but as I have more time there will be more notes added.

http://z505.com/cgi-bin/powtils/docs/1.6/idx.cgi?file=fcldbnotes

An interface view is also available:
http://z505.com/cgi-bin/powtils/docs/1.6/idx.cgi?file=index-4&unit=sqldb

Hi L,

Good to see anyone working on documenting anything, especially the db stuff, but why not add to what is in the wiki, rather than yet another documentation site ?

cheers,
John

Hi Lars,

http://z505.com/cgi-bin/powtils/docs/1.6/idx.cgi?file=fcldbnotes

Where do I get a Doc ID to edit those pages? There are loads of spelling and grammar mistakes I would like to fix. Oh btw, 'Remember' is still spelled incorrectly in that page I mentioned before. :)

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Or providing patches against the original docs?

Op dinsdag 27-11-2007 om 00:59 uur [tijdzone +1100], schreef John:

There are none. (at least not comitted) But they should be in the fpc-docs repository. So you could add them there.

Btw: you can better start documenting the db-unit. Teh sqldb-documentation is kind of useless without the db-unit documentation.

Then you can use something like your notes to explain how one can use sqldb.

And I think that documenting the internals, thus what is called when, is not very usefull in this stage. (Unless you want to help develop for sqldb, offcourse) First get the main things working.

And if you want to document sqldb, document .applyupdates and .commit.

Joost

Of course Db unit will be documented as well. By documenting SQLDb (in fact, I don't call it a documentation, but a how-to in this instance), we started answering the common question of how to connect to an sql database, maybe the first most important thing a new user of an unknown database library wants to know before deciding to use it.

The following addendums should be Params usage and TFields, as well as transactions.

Leonardo.

____________________________________________________________________________________ Get easy, one-click access to your favorites.
Make Yahoo! your homepage.
http://www.yahoo.com/r/hs

Where do I get a Doc ID to edit those pages?

The current doc id is -lufdocz- including dashes.
We'd be happy if you helped.. there is also the tiOPF page that I opened..

There are loads of spelling and grammar mistakes I would like to fix. Oh btw, 'Remember' is still spelled incorrectly in that page I mentioned before. :)

I don't rmembr any spelling mistake.

Help the help, help our help!

Hello,

Thank you guys for starting to write documentation about sqldb and database access in
general !
It's painful to rely on those few examples and using the code-completion feature of Lazarus
for guessing the methods each time when needing to work with databases ...

Which is the right place for discussing about the new sqldb guide ? Since I'm a sqldb beginner I'm not
sure how much documentation text can I contribute with. But at least i can come up with ideas
since I know what kind of information would I expect to find in a "Working with databases" guide.

For instance :
- I'd move the "Step-by-step" section before the box about FCL-DB , or even in a separate page
because it seems to contain information for people who want to add connectivity for new database
vendors . So it's not information for the typical developer.

- I think that the guide should contain easily identifiable sub-sections : "Connecting to a database" (with links to another page that presents the specifics for connecting to
the various db engines) , "Reading the contents of a table" , "Executing SQL commands" ,
"Using parameters" , "Calling a stored procedure" , "Getting metadata information from the database" ,
etc. A long, complete tutorial is hard to follow if it doesn't have sub-sections .

- The guide should avoid ending up like this one : http://wiki.lazarus.freepascal.org/Lazarus_Database_Tutorial which contains 6 tutorials , each having its own, unique structure. Some tutorials are verbose, others are shorter .
Creating a connection is different for each database type, but afterwards the handling of the data is supposed to be the same regardless of the database being used. The mentioned wiki page fails to present the common
elements involved in working with databases.

Cheers,
Adrian Maier

Ooops, sorry. What i meant to say was : it's worth considering to move the FCL-DB box
at the bottom of the page of in a separate page because it seems to contain information
about implementing new connection classes and has therefore a more limited audience .

Feel free to refactor and improve. Help the help, help your help!

Vincent

I like the idea, can you start by creating the section's skeleton?

____________________________________________________________________________________ Looking for last minute shopping deals?
Find them fast with Yahoo! Search. http://tools.search.yahoo.com/newsearch/category.php?category=shopping

Point taken ;)

I can give it a try. Where should i put the skeleton once I think about it ? here on
the mailing list , or you are suggesting me to modify the online page ?

Adrian Maier wrote

I can give it a try. Where should i put the skeleton once I think about it ? here on the mailing list , or you are suggesting me to modify the online page ?

Or create a new page and possibly move contents from the existing pages.

Vincent

Leonardo M. Ramé wrote

I like the idea, can you start by creating the section's skeleton?

Here is a possible structure of the page. I'm not familiar yet to working with this
lufdoc , that's why i'm putting the skeleton here on the mailing list for the moment.

Sqldb guide

1. Introduction
- what is FCL-db
- what is Sqldb ; the supported databases
- the current document concentrates on the sql databases

2. Concepts
- the diagram shown here
http://wiki.lazarus.freepascal.org/SQLdb_Programming_Reference
- explanations about each of the classes

3. Connecting to a database
- how to instatiate a TsqlConnection for each of the supported databases
- checking that the connection succeeded
- closing the connection
- frequently used methods of the TSqlConnection class
- maybe : link to another doc "Setting up the database for the sqldb guide examples" , so that
the specific instructions for creating the db doesn't clutter this guide

4. Transactions
- how to instantiate a TsqlTransaction and "link" it to the connection object
- frequently used methods of the TSqlTransaction class : StartTransaction, Commit, CommitRetaining, Rollback.

5. Executing SQL commands

5.1 The TSqlQuery class
- how to instante and "link" the query to the transaction and connection.
- frequently used methods

5.2 Executing simple sql queries (which don't return tuples)
- cfilltable.pp

5.3 Executing a sql query and traversing the records
- example for accessing the fields by name - dshowtable.pp
- example for accessing the fields by position
- using filters - gfiltertable.pp

5.4 Editing the records
- fedittable.pp

5.5 Queries with parameters
- efilltableparams.pp

5.6 Executing sql commands with connection.ExecuteDirect
- example for using ExecuteDirect - bcreatetable.pp
- advantages/disavantages compared to using a TSqlQUery

5.7 Other stuff
- getting the list of tables - alisttables.pp
- other functionality that i'm not aware of

6. Developing FCL-DB and SqlDb
6.1 Structure of the FCL-DB directory in the FPC sources 6.2 Implementing a new kind of TSqlConnection

7. Resources
- links to the reference pages of the classes used
- links to tutorials, wiki pages, etc.

Hello,

Unfortuately , L's initiative to start writing a guide for fcl-db and sqldb has
stalled completely :
http://z505.com/cgi-bin/powtils/docs/1.6/idx.cgi?file=fcldbnotes

At that time I've tried to contribute with a possible structure of the guide. After that, nothing else happened.

GIven that the few information on the subject is spread in tiny places (the only comprehensive source of information being the source code...) it's hard for me to understand how some people can actually build applications that need to access sql databases. Probably their Delphi experience helps them a lot , because the docs surely don't .

Are there any people still interested in making it possible to have some real docs for sqldb and fcl-db ?

If so, let's organize ourselves and see what needs to be done . I am very interested in the subject but I can't do it myself alone : if I knew enough about sqldb I wouldn't be so unhappy about the lack of documentation .

Best wishes,
Adrian Maier

Op woensdag 23-01-2008 om 10:35 uur [tijdzone +0200], schreef Adrian Maier:

The basics of fcl-db are completely compatible with Delphi. I think most users use their Delphi knowledge. The sqldb-part is very easy if you understand the rest.

Are there any people still interested in making it possible to have some real docs for sqldb and fcl-db ?

I really would like it if such documentation will arise. But I also would like to add index-support and some more TClientDataset functionality.

If so, let's organize ourselves and see what needs to be done . I am very interested in the subject but I can't do it myself alone : if I knew enough about sqldb I wouldn't be so unhappy about the lack of documentation .

I'm the one who knows the most of sqldb, apart from some parts which aren't written by me. I would really like to help and eventually I'll start writing the documentation on my own. but I doubt if I'm the right person to do that now. But I'm willing to help and answer all questions.

About the structure: I think it's best to use fpdoc to build the documentation. Just like Delphi does. Then in the descriptions of the components itself a short description of the whole component can be given, to explain the basics to new users. From there they can browse further into the documentation.

So that's a completely different approach then suggested by Lars.

Joost

Hi Adrian,

I am also.

cheers,
John Sunderland

Hi John, Joost and Adrian -

As you might know, I have been trying to get the documentation for parts of the Lazarus Component Library (LCL) into shape, mainly by putting information into the .XML files associated with each Unit, to enable generation of .HTML files using FPDoc. Quite a few elements in the LCL are now documented to the stage that useful information appears as on-line hints when using the Lazarus IDE.

I have started trying to describe some of the Data-Aware components (see the DataAccess and Data Control tabs in the Component Palette) but am having to delve deeply into the SQLDb and Db files in the FCL in order to get information to describe the use of these components. So I should very much like to collaborate with you guys in improving the documentation of sqldb and fc-db, as well as the stuff in the LCL. I agree we should try to use the FPDoc approach as suggested by Joost.

I have been given commit access to the /docs/xml/lcl/ directory in the lazarus SVN tree. At present the SQLDb and fcl-db documentation files would not appear in that pathway, and we would need to find some way of sharing our work on the files - perhaps we need to find a branch of SVN to which some or all of us gain access.

I am copying this communication to the lazarus developers list, as they are the guys with write-access to the appropriate SVN repositories, and may be able to offer suggestions on how best to proceed. I am also copying it to the main lazarus mailing list, in the hope that more volunteers may emerge!

Please keep in touch and keep the impetus going.

Regards - Chris

Well, this clarifies why I'm having problems when trying to work with sqldb : I've never done any kind of Delphi programming ...

In my opinion there are two distinct kinds of documentation that we need :
- the reference documentation (which describes what does each of the classes,methods,etc. do. With a few examples)
- a guide which explains the infrastructure, what are the components involved, how to do typical things , etc.

I know very little about fpdoc, but my feeling is that it's only suitable for having the reference docs for sqldb and fcl-db.

But anyway , the first thing we need is the full reference docs for the units involved. The guide can wait.

So, I'll start by seeing exactly how does fpdoc work.

Cheers,
Adrian Maier

Op woensdag 23-01-2008 om 12:35 uur [tijdzone +0000], schreef Chris Kirkpatrick:

As fcl-db and sqldb are parts of fpc, the documenatation should be in the fpc-docs-repository. I have full write access there so at first I can commit any changes. I have an (almost empty) framework ready. I you want I can commit that, so you guys have something to start with.

Joost.

Op woensdag 23-01-2008 om 15:16 uur [tijdzone +0200], schreef Adrian Maier:

Yes, fpdoc is only for the reference documentation.

But anyway , the first thing we need is the full reference docs for the units involved. The guide can wait. So, I'll start by seeing exactly how does fpdoc work.

If you use Lazarus, you can use LazDoc.

Joost.

Yes please, an empty skeleton would be a very useful start. I can send you patches when I have made changes to the XMLs.
Regards - Chris

What's the URL of the fpc-docs-repository ?

Op donderdag 24-01-2008 om 10:44 uur [tijdzone +0200], schreef Adrian Maier:

http://svn.freepascal.org/svn/fpcdocs

Joost.

As far as I can see, there are no files relevant to fc-db or SQLDb in this repository. Have you committed your skeleton XMLs yet? If so, in which subdirectory?
Regards - Chris

Op vrijdag 25-01-2008 om 23:59 uur [tijdzone +0000], schreef Chris Kirkpatrick:

As far as I can see, there are no files relevant to fc-db or SQLDb in this repository. Have you committed your skeleton XMLs yet? If so, in which subdirectory?

I just did, revision 373, in the root you can find db.xml.

Joost

My suggestion:
- Add a 'short' description for all visible identifiers
- Add a 'short' description for all protected identifiers
- Forget about private fields, you can remove them from the XML file.
- After this, start documenting public stuff.

Note that the documentation for this unit will not be generated till it is completely documented.

If you need help, let me know, I'll try to explain as good as possible.

Michael.

Hi Joost -
Would you have time to do the same for SQLDb? Otherwise, should I do a MakeSkel and send you a zipped file to commit?
I have already started work on Db, but the two units depend heavily upon each other.
Regards - Chris

Strange that you say this. DB does not depend on any of the SQLDB units ?

Michael.

Op maandag 04-02-2008 om 09:10 uur [tijdzone +0000], schreef Chris Kirkpatrick:

You can make your own. But the documentation of the db-unit should not be dependent on the sqldb documentation. The other way around is not a problem, offcourse.

Joost

OK - speaking a bit loosely! When trying to untangle database stuff, I need to refer to both Units.
Sorry - Chris