Thread: ECPG Documentation Improvement

Hi all,

I'm trying to improve the ECPG documents for the ECPG application
developrs, because some of my clients want more detailed information
when they develop (or migrate) an embeded SQL applications.
Of course, I want to contribute this work to the official manual.

So I have one thing to introduce to you, and thing to ask you.

At first, I've done writing ECPG directives.
I think it could be useful for the ECPG application developers,
similar to the SQL reference section in the official manual.

ecpgdocs @ GoogleCode (I'm working here.)
http://code.google.com/p/ecpgdocs/

ecpgdocs downloads (You can find the current document.)
http://code.google.com/p/ecpgdocs/downloads/list?deleted=1&ts=1276763948

However, I'm not familiar with ECPG details or internals,
so here is one asking, I hope someone to review my documents
and give some feedback to me.

Feedbacks which I'm expecting are:

- Is this document useful?
- Missing directives.
- Missing or wrong synopsis.
- More appropriate descriptions on parameters or examples.
- How to contribute this to the official manual.
- Correcting English. (sorry for my poor English.)
- etc...

Honestly, I'm not familiar with the documentation acceptance/review process,
so any advice and/or comments are welcome.

Regards,
--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

Hi Mark,

Thanks for the comments.

On 2010/06/18 4:27, Mark Richardson wrote:
> Here's some info that I found...
> For conversion of Sybase .pc files to postgres .pgc files, you have to
> parse the .pc file and change from sybase format to postgres format. We
> used a simple script but here's what we changed the following (sybase is
> first column, postgres is second - quotes are used just to indicate the
> entire string, you don't need them in the search/replace)

As you mentioned, I feel the embeded SQL technology has
many compatibility challenges to port applications.
So now I'm thinking how we can hold such compatibility
tips or tricks in the manual.

I'm interested in having the "Compatibility" section
to gather compatibility information which depends on
several RDBMSes, like "Informix compatibility mode" section.
If it could be helpful, I will try it.

I have to work on SQLDA stuffs to clarify its usage,
because I heard that the PostgreSQL SQLDA is not compatible
with Oracle's one, it's compatible with others
(DB2? Sorry if it's wrong).

Thus, the PostgreSQL ECPG is currently a mixture of several
RDBMSes, so I want to clarify the spec and its compatibility.
I guess it could be helpful for application developers. :)

> I also looked up the boolean type for ecpg, the problem is in postgres
> 8.0.1 (maybe later)
> postgresql/src/interfaces/ecpglib/execute.c line 775 (case ECPGt_bool)
> the line was

I will check this, and modify the manual if we need.

Regards,
-- 
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

On Thu, Jun 17, 2010 at 12:27:33PM -0700, Mark Richardson wrote:
> Here's some info that I found...

Just a few questions to make sure I understand your correctly.

> "INCLUDE SQLCA" "INCLUDE sqlca"

So it's just the case of the name? We could lowercase the name in ecpg or
simply install a link SQLCA.h->sqlca.h. So there is no need to change that
anymore. Thoughts?

> "SQLCA" "struct sqlca_t"

struct sqlca_t is defined in sqlca.h but I cannot see a reason why it is used
in client code. sqlca.h also defines sqlca, so it might be a case problem
again. Does it still work if you replace "SQLCA" by "sqlca"?

> "CS_BIT" "bool"
> "CS_CHAR" "char"
> "CS_INT" "int"
> "CS_TINYINT" "short"
> "CS_SMALLINT" "short"
> "CS_REAL" "float"
> "CS_FLOAT" "double"
> "CS_LONG_LONG" "long long"
> "CS_LONG" "int"
> "CS_BINARY" "char"
> "CS_TEXT" "char"
> "ISOLATION LEVEL 0" "ISOLATION LEVEL READ COMMITTED"
> "ISOLATION LEVEL 1" "ISOLATION LEVEL READ COMMITTED"
> "ISOLATION LEVEL 2" "ISOLATION LEVEL SERIALIZABLE"

We could add this in a compatibility level.

> "CHAINED OFF" "CHAINED TO OFF"
> "CHAINED ON" "CHAINED TO ON"

These maybe too.

> I also looked up the boolean type for ecpg, the problem is in postgres 8.0.1 (maybe later)
> postgresql/src/interfaces/ecpglib/execute.c line 775 (case ECPGt_bool)
> the line was
> sprintf(mallocedval, "'%c'", (*((char *) var->value)) ? 't' : 'f');
> changed it to
> sprintf(mallocedval, "'%c'", (*((char *) var->value)) ? '1' : '0');

It still uses 't' and 'f', so that's crying for the compatibility level too.

Michael
--
Michael Meskes
Michael at Fam-Meskes dot De, Michael at Meskes dot (De|Com|Net|Org)
Michael at BorussiaFan dot De, Meskes at (Debian|Postgresql) dot Org
ICQ 179140304, AIM/Yahoo/Skype michaelmeskes, Jabber meskes@jabber.org
VfL Borussia! Força Barça! Go SF 49ers! Use Debian GNU/Linux, PostgreSQL

Heikki,

Thanks for the comments.

On 6/19/2010 0:56 Heikki Linnakangas wrote:
> A reference of all the directives seems useful, but it seems at least
> partially redundant with what's there already. WHENEVER for example is
> quite well documented at
> http://www.postgresql.org/docs/current/interactive/ecpg-errors.html already.

Yes. One of the things what I'm afraid is that point.
How could we (re-)organize the document structure to eliminate such redundancy?
Is this necessary?

Any suggestions?
--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

On 17/06/10 12:07, Satoshi Nagayasu wrote:
> I think it could be useful for the ECPG application developers,
> similar to the SQL reference section in the official manual.
>
> ecpgdocs @ GoogleCode (I'm working here.)
> http://code.google.com/p/ecpgdocs/
>
> ecpgdocs downloads (You can find the current document.)
> http://code.google.com/p/ecpgdocs/downloads/list?deleted=1&ts=1276763948
>
> However, I'm not familiar with ECPG details or internals,
> so here is one asking, I hope someone to review my documents
> and give some feedback to me.
>
> Feedbacks which I'm expecting are:
>
> - Is this document useful?
> - Missing directives.
> - Missing or wrong synopsis.
> - More appropriate descriptions on parameters or examples.
> - How to contribute this to the official manual.
> - Correcting English. (sorry for my poor English.)
> - etc...
>
> Honestly, I'm not familiar with the documentation acceptance/review process,
> so any advice and/or comments are welcome.

A reference of all the directives seems useful, but it seems at least
partially redundant with what's there already. WHENEVER for example is
quite well documented at
http://www.postgresql.org/docs/current/interactive/ecpg-errors.html already.

--
  Heikki Linnakangas
  EnterpriseDB   http://www.enterprisedb.com

> Yes. One of the things what I'm afraid is that point.
> How could we (re-)organize the document structure to eliminate such redundancy?

The document structure is not set in stone, if you deem it better to reorganize
it feel free to do so.

Michael
--
Michael Meskes
Michael at Fam-Meskes dot De, Michael at Meskes dot (De|Com|Net|Org)
Michael at BorussiaFan dot De, Meskes at (Debian|Postgresql) dot Org
ICQ 179140304, AIM/Yahoo/Skype michaelmeskes, Jabber meskes@jabber.org
VfL Borussia! Força Barça! Go SF 49ers! Use Debian GNU/Linux, PostgreSQL

Michael,

On 2010/06/24 21:23, Michael Meskes wrote:
>> Yes. One of the things what I'm afraid is that point.
>> How could we (re-)organize the document structure to eliminate such redundancy?
>
> The document structure is not set in stone, if you deem it better to reorganize
> it feel free to do so.

Thanks.
I'm continuing working on the ECPG documents, and I have almost finished
adding more descriptions in the SQLDA section.
So I will show you it tomorrow (after translation).

Regards,
--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

Hi all,

As I mentioned in the previous mail,
I have almost finished writing new ECPG SQLDA section.

This document is based on the current ECPG/SQLDA documents,
and added some examples to help writing SQLDA code in ECPG
for application developers.

It has following 9 sub-sections.

- Developing an ECPG application with SQLDA
- SQLDA data structure
- sqlda_t structure
- sqlvar_t structure
- struct sqlname structure
- Retreiving a resultset with using an output SQLDA
- Passing query parameters with using an input SQLDA
- A sample application with SQLDA
- Retreiving/passing values with using PostgreSQL special types

The new document is available here.

SQLDA.pdf
http://code.google.com/p/ecpgdocs/downloads/detail?name=SQLDA.pdf&can=2&q=#makechanges

I hope you to look this document, and if you're interested in
ECPG and/or documentation things, please send me back
your comments or advices.

Any feedback would be greatly appreciated.

Regards,

--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

Hi all,

I have just finished to update "Using Host Variables" section,
one of the most important sections for ECPG development.

It has following 8 sub-sections.

- Host variables overview
- Mapping between PostgreSQL data types and host variable types
- Declare Sections
- Retreiving query results using host variables (SELECT INTO and FETCH INTO)
- Setting input parameters to SQL statements using host variables
- Accessing numeric data types and text data types
- Accessing special data types
- More on host variables

http://code.google.com/p/ecpgdocs/downloads/detail?name=Using%20Host%20Variables.pdf&can=2&q=#makechanges

If you're interested in ECPG, please look at the document,
and feel free to send some comments to me. Any comments are welcome.

Regards,

--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

Hi all,

I have just remembered I finished writing the "Large Objects" section
to describe large object handling in ECPG.

http://code.google.com/p/ecpgdocs/downloads/detail?name=Large%20objects.pdf&can=2&q=#makechanges

Please look at this document, too.

Thanks,

On 2010/07/06 16:17, Satoshi Nagayasu wrote:
> Hi all,
>
> I have just finished to update "Using Host Variables" section,
> one of the most important sections for ECPG development.
>
> It has following 8 sub-sections.
>
> - Host variables overview
> - Mapping between PostgreSQL data types and host variable types
> - Declare Sections
> - Retreiving query results using host variables (SELECT INTO and FETCH
> INTO)
> - Setting input parameters to SQL statements using host variables
> - Accessing numeric data types and text data types
> - Accessing special data types
> - More on host variables
>
> http://code.google.com/p/ecpgdocs/downloads/detail?name=Using%20Host%20Variables.pdf&can=2&q=#makechanges
>
>
> If you're interested in ECPG, please look at the document,
> and feel free to send some comments to me. Any comments are welcome.
>
> Regards,
>


--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

Hi all,

As I mentioned, I have been working to improve the ECPG official manual,
trying to understand details, and adding more descriptions and examples
in a past few weeks.

I think now is the time to introduce this work again, and hope some of
you to look inside the new documents. And also I want to discuss how
to contribute to the official manual.

New ECPG manual (Zip file)
http://code.google.com/p/ecpgdocs/downloads/detail?name=ecpg_html.zip

Current ECPG manual
http://developer.postgresql.org/pgdocs/postgres/ecpg.html

I have refined and reorganized the ECPG manual from the viewpoint of
application developers who don't have deep knowledge about PostgreSQL
and its internals.

The work is still in progress, but the whole structure and the core
chapters have almost been fixed.

So, I want someone who is interested in the ECPG and/or documentation
to look inside the documents.

Any feedback and comments would be appreciated.

Regards,

On 2010/06/17 18:07, Satoshi Nagayasu wrote:
> Hi all,
>
> I'm trying to improve the ECPG documents for the ECPG application
> developrs, because some of my clients want more detailed information
> when they develop (or migrate) an embeded SQL applications.
> Of course, I want to contribute this work to the official manual.
>
> So I have one thing to introduce to you, and thing to ask you.
>
> At first, I've done writing ECPG directives.
> I think it could be useful for the ECPG application developers,
> similar to the SQL reference section in the official manual.
>
> ecpgdocs @ GoogleCode (I'm working here.)
> http://code.google.com/p/ecpgdocs/
>
> ecpgdocs downloads (You can find the current document.)
> http://code.google.com/p/ecpgdocs/downloads/list?deleted=1&ts=1276763948
>
> However, I'm not familiar with ECPG details or internals,
> so here is one asking, I hope someone to review my documents
> and give some feedback to me.
>
> Feedbacks which I'm expecting are:
>
> - Is this document useful?
> - Missing directives.
> - Missing or wrong synopsis.
> - More appropriate descriptions on parameters or examples.
> - How to contribute this to the official manual.
> - Correcting English. (sorry for my poor English.)
> - etc...
>
> Honestly, I'm not familiar with the documentation acceptance/review process,
> so any advice and/or comments are welcome.
>
> Regards,


--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

Hi all,

In past two months, I was working to improve the ecpg manual,
and work for a draft of the new manual is now 90% finished.
This document is getting very similar to the final edition,
so I hope to introduce to you.

In this version, following chapters has been changed.

- The Concept
- Managing the Database Connections
- Running SQL Commands
- Dynamic SQL
- Error Handling

Some are reorganized, some are rewritten and many things are
newly added.

So please check the new one, and hope to get some feedbacks
from pg guys.

- Browsable manual
  http://www.uptime.jp/dev/ecpg_html/ecpg.html

- Archived manual in ZIP file
  http://code.google.com/p/ecpgdocs/downloads/detail?name=ecpg_html.zip

Any feedback and comments would be appreciated.

Regards,

On 2010/07/08 18:50, Satoshi Nagayasu wrote:
> Hi all,
>
> As I mentioned, I have been working to improve the ECPG official manual,
> trying to understand details, and adding more descriptions and examples
> in a past few weeks.
>
> I think now is the time to introduce this work again, and hope some of
> you to look inside the new documents. And also I want to discuss how
> to contribute to the official manual.
>
> New ECPG manual (Zip file)
> http://code.google.com/p/ecpgdocs/downloads/detail?name=ecpg_html.zip
>
> Current ECPG manual
> http://developer.postgresql.org/pgdocs/postgres/ecpg.html
>
> I have refined and reorganized the ECPG manual from the viewpoint of
> application developers who don't have deep knowledge about PostgreSQL
> and its internals.
>
> The work is still in progress, but the whole structure and the core
> chapters have almost been fixed.
>
> So, I want someone who is interested in the ECPG and/or documentation
> to look inside the documents.
>
> Any feedback and comments would be appreciated.
>
> Regards,
>
> On 2010/06/17 18:07, Satoshi Nagayasu wrote:
>> Hi all,
>>
>> I'm trying to improve the ECPG documents for the ECPG application
>> developrs, because some of my clients want more detailed information
>> when they develop (or migrate) an embeded SQL applications.
>> Of course, I want to contribute this work to the official manual.
>>
>> So I have one thing to introduce to you, and thing to ask you.
>>
>> At first, I've done writing ECPG directives.
>> I think it could be useful for the ECPG application developers,
>> similar to the SQL reference section in the official manual.
>>
>> ecpgdocs @ GoogleCode (I'm working here.)
>> http://code.google.com/p/ecpgdocs/
>>
>> ecpgdocs downloads (You can find the current document.)
>> http://code.google.com/p/ecpgdocs/downloads/list?deleted=1&ts=1276763948
>>
>> However, I'm not familiar with ECPG details or internals,
>> so here is one asking, I hope someone to review my documents
>> and give some feedback to me.
>>
>> Feedbacks which I'm expecting are:
>>
>> - Is this document useful?
>> - Missing directives.
>> - Missing or wrong synopsis.
>> - More appropriate descriptions on parameters or examples.
>> - How to contribute this to the official manual.
>> - Correcting English. (sorry for my poor English.)
>> - etc...
>>
>> Honestly, I'm not familiar with the documentation acceptance/review process,
>> so any advice and/or comments are welcome.
>>
>> Regards,
>
>


--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

On Thursday 22 July 2010, Satoshi Nagayasu wrote:
> Hi all,
>
> In past two months, I was working to improve the ecpg manual,
> and work for a draft of the new manual is now 90% finished.
> This document is getting very similar to the final edition,
> so I hope to introduce to you.
...
> Any feedback and comments would be appreciated.

Comparing the previous version to your draft, I have to say thanks a lot of
for the large amount work that you have put into the new document.

Robert Haas <robertmhaas@gmail.com> writes:
> 2010/7/27 Lars Nordin <lars.nordin@gmail.com>:
>> Comparing the previous version to your draft, I have to say thanks a lot of
>> for the large amount work that you have put into the new document.

> Seems like we need to think about how to integrate this.  Anyone have ideas?

I've been waiting for Michael to weigh in.  But maybe he's not reading
this thread?

            regards, tom lane

On Wed, Jul 28, 2010 at 08:28:34PM -0400, Tom Lane wrote:
> I've been waiting for Michael to weigh in.  But maybe he's not reading
> this thread?

Well he is, sort of. I've got quite a delay in handling/reading my emails due
to real life time constraints and upcoming trips, sorry.

I had a short look at the docs Satoshi-san put online and yes, I'm impressed.
However, I won't be able to proof read them before September. But given that
9.1 development is just starting I see no problem in putting the docs into the
archive be it cvs or git and improve if there if it really needs improvement.
In my short check I didn't see anything major that needed to be changed. This
of course implies that the new docs are available in a suitable format.

Michael

--
Michael Meskes
Michael at Fam-Meskes dot De, Michael at Meskes dot (De|Com|Net|Org)
Michael at BorussiaFan dot De, Meskes at (Debian|Postgresql) dot Org
ICQ 179140304, AIM/Yahoo/Skype michaelmeskes, Jabber meskes@jabber.org
VfL Borussia! Força Barça! Go SF 49ers! Use Debian GNU/Linux, PostgreSQL

2010/7/27 Lars Nordin <lars.nordin@gmail.com>:
> On Thursday 22 July 2010, Satoshi Nagayasu wrote:
>> Hi all,
>>
>> In past two months, I was working to improve the ecpg manual,
>> and work for a draft of the new manual is now 90% finished.
>> This document is getting very similar to the final edition,
>> so I hope to introduce to you.
> ...
>> Any feedback and comments would be appreciated.
>
> Comparing the previous version to your draft, I have to say thanks a lot of
> for the large amount work that you have put into the new document.

Seems like we need to think about how to integrate this.  Anyone have ideas?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company

On 2010/07/29 17:41, Michael Meskes wrote:
> I had a short look at the docs Satoshi-san put online and yes, I'm impressed.
> However, I won't be able to proof read them before September. But given that
> 9.1 development is just starting I see no problem in putting the docs into the
> archive be it cvs or git and improve if there if it really needs improvement.
> In my short check I didn't see anything major that needed to be changed. This
> of course implies that the new docs are available in a suitable format.

Thank you all for your attention to the ecpg document work.

Yes, I see some developers are too busy, so it's difficult to take time
to review such large amount of changes of the doc for now.

I'm thinking about taking a few weeks after August or September
to review and merge the document intensively (like CommitFest)
by some developers who are interested in this doc.

I know this change is very huge, and it's very difficult to review
and give feedback through the whole document. So I think we sould take
an approach to review and merge chapter by chapter during the period,
and it can be an effective way to merge this large change
if we can take time for such intensive work.

Is this possible? Any suggestions?

Regards,
--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>

Satoshi Nagayasu wrote:
> On 2010/07/29 17:41, Michael Meskes wrote:
> > I had a short look at the docs Satoshi-san put online and yes, I'm impressed.
> > However, I won't be able to proof read them before September. But given that
> > 9.1 development is just starting I see no problem in putting the docs into the
> > archive be it cvs or git and improve if there if it really needs improvement.
> > In my short check I didn't see anything major that needed to be changed. This
> > of course implies that the new docs are available in a suitable format.
>
> Thank you all for your attention to the ecpg document work.
>
> Yes, I see some developers are too busy, so it's difficult to take time
> to review such large amount of changes of the doc for now.
>
> I'm thinking about taking a few weeks after August or September
> to review and merge the document intensively (like CommitFest)
> by some developers who are interested in this doc.
>
> I know this change is very huge, and it's very difficult to review
> and give feedback through the whole document. So I think we sould take
> an approach to review and merge chapter by chapter during the period,
> and it can be an effective way to merge this large change
> if we can take time for such intensive work.
>
> Is this possible? Any suggestions?

I would like to help too.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

On fre, 2010-07-30 at 01:23 +0900, Satoshi Nagayasu wrote:
> I'm thinking about taking a few weeks after August or September
> to review and merge the document intensively (like CommitFest)
> by some developers who are interested in this doc.
>
> I know this change is very huge, and it's very difficult to review
> and give feedback through the whole document. So I think we sould take
> an approach to review and merge chapter by chapter during the period,
> and it can be an effective way to merge this large change
> if we can take time for such intensive work.
>
> Is this possible? Any suggestions?

If you want this reviewed, please send in a patch of the source code you
changed.

On 2010/09/26 23:32, Peter Eisentraut wrote:
> On fre, 2010-07-30 at 01:23 +0900, Satoshi Nagayasu wrote:
>> I'm thinking about taking a few weeks after August or September
>> to review and merge the document intensively (like CommitFest)
>> by some developers who are interested in this doc.
>>
>> I know this change is very huge, and it's very difficult to review
>> and give feedback through the whole document. So I think we sould take
>> an approach to review and merge chapter by chapter during the period,
>> and it can be an effective way to merge this large change
>> if we can take time for such intensive work.
>>
>> Is this possible? Any suggestions?
>
> If you want this reviewed, please send in a patch of the source code you
> changed.

Patch is available at here:
http://code.google.com/p/ecpgdocs/downloads/detail?name=ecpg-patches.20100928.tgz

(I uploaded this to the GoogleCode, because this list did not deliver
  my previous message with a patch tarball.)

The patch is split into total 15 patches for each chapter of the ecpg doc,
and every patch could be applied to the Git version with only itself.
So you can review every patch chapter by chapter.

Thanks in advance.

Regards,
--
NAGAYASU Satoshi <satoshi.nagayasu@gmail.com>