Subject: ECPG Documentation Improvement

From: Satoshi Nagayasu <[email-masked]>
Date: Thu, 17 Jun 2010 18:07:05 +0900

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 <[email-masked]>

---

From: Mark Richardson <[email-masked]>
Date: Thu, 17 Jun 2010 12:27:33 -0700 (PDT)

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)
"INCLUDE SQLCA" "INCLUDE sqlca"
"SQLCA" "struct sqlca_t"
"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"
"SQL CONNECT :" "SQL CONNECT TO :dbName_ USER:"
"CHAINED OFF" "CHAINED TO OFF"
"CHAINED ON" "CHAINED TO ON"

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');
 
If you have more questions I can dig in the code and find answers for you.
Mark
--- On Thu, 6/17/10, Satoshi Nagayasu <[email-masked]> wrote:

From: Satoshi Nagayasu <[email-masked]>
Subject: [INTERFACES] ECPG Documentation Improvement
To: [email-masked], [email-masked]
Cc: "Bruce Momjian" <[email-masked]>, "Michael Meskes" <[email-masked]>
Date: Thursday, June 17, 2010, 3:07 AM

Hi all,

Regards,

-- 
Sent via pgsql-interfaces mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-interfaces

---

From: Satoshi Nagayasu <[email-masked]>
Date: Fri, 18 Jun 2010 17:05:53 +0900

Hi Mark,

Thanks for the comments.

On 2010/06/18 4:27, Mark Richardson wrote:
> 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. :)

> postgresql/src/interfaces/ecpglib/execute.c line 775 (case ECPGt_bool)

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

Regards,

---

From: Michael Meskes <[email-masked]>
Date: Fri, 18 Jun 2010 11:40:08 +0200

> 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"?

> "ISOLATION LEVEL 2" "ISOLATION LEVEL SERIALIZABLE"

We could add this in a compatibility level.

> "CHAINED ON" "CHAINED TO ON"

These maybe too.

> 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 [email-masked]
VfL Borussia! Força Barça! Go SF 49ers! Use Debian GNU/Linux, PostgreSQL

---

From: Heikki Linnakangas <[email-masked]>
Date: Fri, 18 Jun 2010 18:56:37 +0300

> 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

---

From: [email-masked]
Date: Sat, 19 Jun 2010 10:01:05 +0900

Heikki,

Thanks for the comments.

> 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?

---

From: Michael Meskes <[email-masked]>
Date: Thu, 24 Jun 2010 14:23:25 +0200

> 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

---

From: Satoshi Nagayasu <[email-masked]>
Date: Thu, 24 Jun 2010 22:45:08 +0900

Michael,

> The document structure is not set in stone, if you deem it better to reorganize

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,

---

From: Satoshi Nagayasu <[email-masked]>
Date: Fri, 25 Jun 2010 22:57:43 +0900

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,

---

From: Satoshi Nagayasu <[email-masked]>
Date: Tue, 06 Jul 2010 16:17:56 +0900

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,

---

From: Satoshi Nagayasu <[email-masked]>
Date: Tue, 06 Jul 2010 16:30:00 +0900

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,

---

From: Satoshi Nagayasu <[email-masked]>
Date: Thu, 08 Jul 2010 18:50:51 +0900

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,

---

From: Satoshi Nagayasu <[email-masked]>
Date: Thu, 22 Jul 2010 15:35:43 +0900

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

Regards,

---

From: Lars Nordin <[email-masked]>
Date: Tue, 27 Jul 2010 21:42:31 -0400

> 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.

---

From: Robert Haas <[email-masked]>
Date: Wed, 28 Jul 2010 18:59:58 -0400

> 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

---

From: Tom Lane <[email-masked]>
Date: Wed, 28 Jul 2010 20:28:34 -0400

> 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

---

From: Michael Meskes <[email-masked]>
Date: Thu, 29 Jul 2010 10:41:36 +0200

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

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

---

From: Satoshi Nagayasu <[email-masked]>
Date: Fri, 30 Jul 2010 01:23:22 +0900

> 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,

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 11 Aug 2010 21:47:11 -0400 (EDT)

> Is this possible? Any suggestions?

I would like to help too.

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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

---

From: Peter Eisentraut <[email-masked]>
Date: Sun, 26 Sep 2010 17:32:37 +0300

> Is this possible? Any suggestions?

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

---

From: Satoshi Nagayasu <[email-masked]>
Date: Tue, 28 Sep 2010 19:01:52 +0900

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

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,

---

From: Peter Eisentraut <[email-masked]>
Date: Sun, 10 Oct 2010 13:55:22 +0300

> So you can review every patch chapter by chapter.

I've committed this now, after some extensive revision.  The ECPG
documentation looks really good and more complete now.  Thanks a lot.

---

From: Satoshi Nagayasu <[email-masked]>
Date: Sun, 10 Oct 2010 21:03:24 +0900

> documentation looks really good and more complete now.  Thanks a lot.

Thanks for your review and commit.
I guess you had tough work on not only reviewing a lot changes,
but also correcting my English. Great work. :)

Regards,