1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
- 0.17
- Review error handling; regularize; document.
- Implement these calls:
- PQsetNoticeProcessor
Control reporting of notice and warning messages generated by libpq.
void PQsetNoticeProcessor (PGconn * conn,
void (*noticeProcessor) (void * arg, const char * message),
void * arg);
By default, libpq prints "notice" messages from the backend on stderr,
as well as a few error messages that it generates by itself. This
behavior can be overridden by supplying a callback function that does
something else with the messages. The callback function is passed the
text of the error message (which includes a trailing newline), plus a
void pointer that is the same one passed to PQsetNoticeProcessor. (This
pointer can be used to access application-specific state if needed.)
The default notice processor is simply
static void
defaultNoticeProcessor(void * arg, const char * message)
{
fprintf(stderr, "%s", message);
}
To use a special notice processor, call PQsetNoticeProcessor just
after creation of a new PGconn object.
- PQnotifies
PQnotifies returns the next notification from a list of unhandled
notification messages received from the backend. Returns NULL if there
are no pending notifications. Once a notification is returned from
PQnotifies, it is considered handled and will be removed from the list
of notifications.
PGnotify* PQnotifies(PGconn *conn);
typedef struct pgNotify {
char relname[NAMEDATALEN]; /* name of relation
* containing data */
int be_pid; /* process id of backend */
} PGnotify;
After processing a PGnotify object returned by PQnotifies, be sure to
free it with free() to avoid a memory leak.
PQnotifies() does not actually read backend data; it just returns
messages previously absorbed by another libpq function. In prior
releases of libpq, the only way to ensure timely receipt of NOTIFY
messages was to constantly submit queries, even empty ones, and then
check PQnotifies() after each PQexec(). While this still works, it is
deprecated as a waste of processing power. A better way to check for
NOTIFY messages when you have no useful queries to make is to call
PQconsumeInput(), then check PQnotifies(). You can use select(2) to
wait for backend data to arrive, thereby using no CPU power unless there
is something to do. Note that this will work OK whether you use
PQsendQuery/PQgetResult or plain old PQexec for queries. You should,
however, remember to check PQnotifies() after each PQgetResult or PQexec
to see if any notifications came in during the processing of the query.
- Eventually
- Fix places where SCM_ROSTRINGs are treated as null-terminated strings.
We need to make sure they aren't substrings.
- Implement these calls:
- PQclear
void PQclear (PGresult *res);
- PQfinish
void PQfinish (PGconn *conn);
- PQconndefaults
PQconninfoOption *PQconndefaults(void)
struct PQconninfoOption {
char *keyword; /* The keyword of the option */
char *envvar; /* Fallback environment variable name */
char *compiled; /* Fallback compiled in default value */
char *val; /* Option's value */
char *label; /* Label for field in connect dialog */
char *dispchar; /* Character to display for this field
in a connect dialog. Values are:
"" Display entered value as is
"*" Password field - hide value
"D" Debug options - don't
create a field by default */
int dispsize; /* Field size in characters for dialog */
};
Returns the address of the connection options structure. This may be
used to determine all possible PQconnectdb options and their current
default values. The return value points to an array of PQconninfoOption
structs, which ends with an entry having a NULL keyword pointer. Note
that the default values ("val" fields) will depend on environment
variables and other context. Callers must treat the connection options
data as read-only.
- Asynchronous version of PQgetline
int PQgetlineAsync(PGconn *conn, char *buffer, int bufsize)
- Non-blocking query support
int PQsendQuery (PGconn *conn, const char *query)
PGresult *PQgetResult (PGconn *conn)
Returns a pointer to a result or NULL if no more
results are due from the given connection.
int PQconsumeInput (PGconn *conn)
Returns 1 if OK, 0 otherwise.
int PQisBusy(PGconn *conn)
Returns TRUE if there is data waiting for PQconsumeInput,
FALSE otherwise.
int PQsocket(PGconn *conn)
Returns a socket fd for the connection to the backend.
int PQrequestCancel(PGconn *conn)
The return value is TRUE if the cancel request was successfully
dispatched, FALSE if not. (If not, PQerrorMessage tells why not.)
Successful dispatch is no guarantee that the request will have any
effect, however. Regardless of the return value of PQrequestCancel, the
application must continue with the normal result-reading sequence using
PQgetResult. If the cancellation is effective, the current query will
terminate early and return an error result. If the cancellation fails
(say because the backend was already done processing the query), then
there will be no visible result at all.
Note that if the current query is part of a transaction, cancellation
will abort the whole transaction.
- Add to the manual a section giving an overview of using large-objects.
This must explain the ideas of OID's as references to objects. Also we
need examples of using lo-streams. Perhaps a scheme implementation of
lo-export and lo-import and, just for fun, a demonstration of executing
scheme code contained in a large object. There should also be an example
of updating a table with a large number of large objects. Perhaps it could
take a directory with lots of binary files in it and store each file in a
large object in a table listing the names of the files.
- Test the module on OSes other than Linux.
I have used a copy of libtool from the CVS because 1.3 is expected to
support inter-shared-library dependencies when it is released. We need to
find out on which OSes libtool's support works for this module.
UPDATE: 31/1/99 The CVS libtool doesn't work. It is still planned, but it
may never work for ILD.
- Incorporate higher-level interface in scheme.
This should provide query-level functions like (pg:for-each) which
iterates over a set of tuples returned from a query. Also provide a
streams interface so that (pg:stream-cdr) and (pg:stream-car) return
tuples.
- Add a (pg:quote-sql-string-literal) procedure.
This should take an arbitrary scheme string and return it suitably quoted
so that it can appear safely inside single quotes in an sql statement. I
think this should be written in C so that it's fast. To write it we need
to make a careful examination of what characters are special in sql
string-literals. These include, but may not be limited to: backslash,
single quote, carriage return, linefeed, tab.
- Use a better method to check that libpq-fe.h and libpq/libpq-fs.h are
on the -I path.
The current scheme uses ./configure options --with-libpq and
--with-libpq-includes and --with-libpq-lib, but they're awful and the GNU
coding standards say --with options should only be used to include
optional components in the build. It's difficult to argue that libpq is
optional because the interface can't be built without it.
But apparently this is an acceptable way to use the --with flags, so
that's what we should do. Jim Blandy says we should also look in 'obvious
places' for the headers and libraries.
- Add --with-guile-config=PATH to configure.in allow the user to specify the
particular version of guile with which to link.
- Packaging
- guile-pg.spec for Red Hat RPM
- debian/ et al for Debian
Local Variables:
mode: outline
outline-regexp: "\\([ ][ ]\\)*- "
fill-column: 78
End:
|
