PostgreSQL
Abstract
The wrapper class for PosgreSQL connections.
Implements NSCoding,PgSQLBindingProtocol,PgSQLResultSetProtocol protocols.
Methods
Abstract: use to check if an asynchronous query has returned results yet.
- (BOOL)asyncResultAvailable;
Result: YES if data is available ([conn nextRow] will not block).
Abstract: returns backend process id of the database server.
- (int)backendPID;
Result: backend process id.
Abstract: self explanatory
- (BOOL)beginTransaction;
DOES NOTHING (and returns YES) IN DEMO VERSION.
Result: YES if successful
- (BOOL)bufferHasCommands;
Result: YES if command buffer contains not yet executed string.
- (BOOL)cancelRequest;
Abstract: clears the command buffer
- (void)clearCommands;
- (int)clientEncoding;
Result: client encoding id.
Abstract: close the cursor opened with executeCommandWithCursor
- (BOOL)closeCursor:(const char *)cursorName;
Parameters
Name | Description |
cursorName | |
Result: YES if successful.
- (const char *)commandBuffer;
Result: pointer on command buffer
Abstract: present a dialog to let the user fill in fields to connect to a database.
- (BOOL)connectAskingUser:(int *)returnCode;
Parameters
Name | Description |
pointer | an integer buffer o hold result code from backend. |
Result: YES if connection successfull, NO otherwise.
Abstract: present a dialog to let the user fill in fields to connect to a database.
- (BOOL)connectAskingUserWithDefaults:(NSDictionary *)defaults return:(int *)returnCode;
Parameters
Name | Description |
Defaults | is a dictionary with following non mandatory keys
host, port, dbname, user, password, options |
pointer | an integer buffer o hold result code from backend. |
Result: YES if connection successfull, NO otherwise.
- (const char *)connectErrorMessage:(int)errorCode;
Parameters
Name | Description |
errorCode | to be converted into string. |
Result: PQresStatus(errorCode)
Abstract: specify parameters string to start PostgreSQL database connection. See PostgreSQL doc for more details on param string.
- (BOOL)connectToDatabase:(const char *)connectInfo return:(int *)returnCode;
Parameters
Name | Description |
connectInfo | character buffer holding the conenction string to be used. |
return | pointer an integer buffer o hold result code from backend. |
Result: YES if connection successfull, NO otherwise.
Abstract: specify parameters to start PostgreSQL database connection
- (BOOL)connectToDatabase:(const char *)dbName onHost:(const char *)hostName login:(const char *)loginName password:(const char *)password return:(int *)returnCode;
The wrapper is disconnected from any opened database before establishing a new one.
Passing nil or empty string to any of the parameters will fail.
Use (BOOL)connectToDatabase:(const char *)connectInfo return:(int *)returnCode
if you need to pass different arguments like options or tty or if you want to use less arguments and let PostgreSQL use default ones.
Parameters
Name | Description |
dbName | databasename as defined in PostgreSQL. |
hostName | network name of host computer |
loginName | user name for login |
password | user password for login |
returnCode | where to return int result code for connection |
Result: YES if connection successful No otherwise
Abstract: returns database name of the connection.
- (const char *)databaseName;
Result: pointer on database name string buffer.
- (BOOL)debugMode;
Result: current debug mode of the connection.
- (id)delegate;
Abstract: disconnect cuurently opened connection.
- (void)disconnect;
Not strictly necessary in the API since connectTodatabase disconnects automatically from any previously opened connection.
Abstract: self explanatory
- (BOOL)endTransaction;
DOES NOTHING (and returns YES) IN DEMO VERSION.
Result: YES if successful
- (NSData *)escapeBinary:(const unsigned char *)inSource length:(size_t)len;
Result: nil if out of memory
autorelase NSData containing the escaped original
- (NSString *)escapeString:(const char *)inSource;
Result: nil if out of memory
autorelase NSString containing the escaped original
Abstract: pass the current command buffer to the PostgreSQL server for asynchronous execution
- (BOOL)executeAsyncCommand;
Result: YES if successful
Abstract: pass the current command buffer to the PostgreSQL server for asynchronous execution inside a cursor declaration
- (BOOL)executeAsyncCommandWithCursor:(const char *)cursorName binary:(BOOL)binary;
Parameters
Name | Description |
cursorName | the name of the cursor |
binary | if cursor should be declared BINARY |
Result: YES if successful
Abstract: pass the current command buffer to the PostgreSQL server for execution
- (BOOL)executeCommand;
Result: YES if successful
Abstract: pass the current command buffer to the PostgreSQL server for execution inside a cursor declaration
- (BOOL)executeCommandWithCursor:(const char *)cursorName binary:(BOOL)binary;
Parameters
Name | Description |
cursorName | the name of the cursor |
binary | if cursor should be declared BINARY |
Result: YES if successful
Abstract: Export the BLOB to the file system.
- (int)exportBinaryToFile:(Oid)inOid pathName:(const char *)inPathName;
Result: the lo_export returned code.
Abstract: returns version of the framework.
- (NSString *)frameworkVersion;
Result: NSString describing the framework version.
Abstract: returns pointer on PGconn record.
- (PGconn *)getPGconn;
ALWAYS returns NIL in DEMO version. See PostgreSQL for advanced use.
You should never close yourselve a connection by calling PQfinish([pgconn getPGconn]).
Result: pointer on PGconn record.
Abstract: Wrapping the last query result in a PgSQLResult object, makes possible to execute a new
query without losing the result of the previous one.
- (PgSQLResult *)getResultSet;
However once done, it's no more possible to access result's information through methods of the PostgreSQL connection (rowsAffected, bindDouble, etc): you MUST use equivalent methods of the PgSQLResult wrapper object instead. Indeed, getResultSet has as side effect to make the PostgreSQL "forgets" about the last query result. PostgreSQL object maintains a list of PgSQLResult they originated, this list is freed when the PostgreSQL object is deallocated.
Result: Wrapper object for last query result.
Abstract: time out to be used when doing an asynchronous query.
Defaults to 10 sec.
If set to -1 no time out will be used in select().
DON'T DO THAT WHEN TESTING if you want to avoid to kill -9 your testing code... in case of trouble.
- (long)getTimeOut;
Result: time out value in seconds.
- (NSDictionary *)getVariables;
Result: returns a dictionary of Postgre variables ("SHOW ALL" 's result).
Abstract: returns host name of the connection.
- (const char *)hostName;
Result: pointer on host name string buffer.
Abstract: insert a BLOB made from a file specified with its pathname.
- (Oid)importBinaryFromFile:(const char *)inPathName;
Result: the Oid of the created BLOB, 0 if an error occurred.
Abstract: insert a BLOB made from a memory buffer.
- (Oid)insertBinary:(unsigned char *)inData size:(int)size;
Parameters
Name | Description |
inData | pointer on the memory buffer |
size | of the memory buffer |
Result: the Oid of the created BLOB, 0 if an error occurred.
Abstract: insert a BLOB made from NSData
- (Oid)insertBinaryFromData:(NSData *)inData;
Result: the Oid of the created BLOB, 0 if an error occurred.
Abstract: insert a BLOB made from NSFileHandle
- (Oid)insertBinaryFromFile:(NSFileHandle *)inFile;
Parameters
Name | Description |
the | NSFileHandle on the file. |
Result: the Oid of the created BLOB, 0 if an error occurred.
Abstract: returns user name of the connection.
- (const char *)loginName;
Result: pointer on user name string buffer.
Abstract: concat cmd
to current command buffer
- (void)makeCommand:(char *)cmd;
makeCommand family methods don't escape automatically their arguments
Use escapeString if you need to.
Abstract: same as makeCommand but with a format and variable arguments list (printf-like)
- (void)makeCommandf:(const char *)format, ...;
Abstract: returns options of the connection.
- (const char *)options;
Result: pointer on options string buffer.
Abstract: overwrite part a of BLOB with bytes from a NSData object from a specified start point.
- (BOOL)overWriteBinaryWithDataFromStart:(Oid)inOid data:(NSData *)inData start:(int)inStart;
Result: YES if successful (number of bytes written == size of NSData buffer).
Abstract: returns password of the connection.
- (const char *)password;
Result: pointer on password string buffer.
Abstract: returns port of the connection.
- (const char *)port;
Result: pointer on port string buffer.
Abstract: returns version of the running postmaster.
- (NSString *)postgreSQLVersion;
returns reulst of executing the SELECT version()
query.
Result: NSString containing the postgreSQL version.
Abstract: Removes the listener of the list of registered listener and execute a UNLISTEN condition
query.
- (void)removeNotificationFor:(PgSQLListener *)listener;
- (BOOL)resultReturned;
Result: YES if latest command executed returns rows.
Abstract: retrieve a BLOB into an newly created NSData object (autorelease)
- (NSData *)retrieveBinary:(Oid)inOid;
Parameters
Name | Description |
the | Oid of the BLOB to be retrieved. |
Result: NSData object or nil.
Abstract: retrieve part of a BLOB into an newly created NSData object (autorelease)
- (NSData *)retrieveBinaryFromStartLength:(Oid)inOid start:(int)inStart length:(int)length;
Parameters
Name | Description |
the | Oid of the BLOB to be retrieved. |
start | position from which to retrieve data |
length | number of bytes to retrieve. |
Result: NSData object or nil.
Abstract: self explanatory
- (BOOL)rollbackTransaction;
DOES NOTHING (and returns YES) IN DEMO VERSION.
Result: YES if successful
- (const char *)serverMessage;
Result: PQerrorMessage()
- (int)setClientEncoding:(const char *)encoding;
Parameters
Name | Description |
encoding | name |
Abstract: turns on|off global debugging.
+ (void)setDebug:(BOOL)yn;
Newly allocated PostgreSQL objects have their instance debug flag set the the global one.
Parameters
Name | Description |
yn | as you expect. |
Abstract: turns on|off instance debugging.
- (void)setDebugMode:(BOOL)turnOn;
Parameters
Name | Description |
turnOn | as you expect. |
- (void)setDelegate:(id)newDelegate;
- (PQnoticeProcessor)setNoticeProcessor:(PQnoticeProcessor)proc userArg:(void *)arg;
Abstract: set the time out to be used when doing an asynchronous query.
- (void)setTimeOut:(long)inTimeOut;
Parameters
Name | Description |
time | out value in seconds. |
- (NSStringEncoding)showClientEncoding;
Result: returns the client encoding converted into NSStringEncoding.
- (NSStringEncoding)showServerEncoding;
Result: returns the server encoding converted into NSStringEncoding.
Abstract: returns socket of the database server.
- (int)socket;
Result: socket number.
Abstract: Execute a LISTEN inTableName
query.
- (PgSQLListener *)startNotificationFor:(const char *)inTableName delegate:(id)notificatonDelegate userInfo:(id)userInfo;
When the notification arrives, the postgreSQL:notification:
selector of the listener delegate and of the application are invocated, (if thy exist). A PostgreSQLNotification is also posted.
The dictionary of the notification contains:
PgSQLuserInfoNotificationField userInfo
PgSQLconditionNotificationField tableName
PgSQLconnectionNotificationField self (PostgreSQL object)
Note that if a listener on the same table already exist, only the notificationDelegate is assigned to it and the existing one is returned.
Result: The listener object created to hold the notificationDelegate/inTableName couple/
Abstract: start tracing to file traceFileName.
- (BOOL)startTracing:(const char *)traceFileName;
Parameters
Name | Description |
traceFileName | full path name of file to dump tracing information. |
Result: YES if successfull
Abstract: turns off tracing.
- (void)stopTracing;
Abstract: self explanatory
- (BOOL)transactionInProgress;
Result: YES if a transaction is in progress (beginTransaction has been called)
Abstract: returns tty of the connection.
- (const char *)tty;
Result: pointer on tty string buffer.
- (NSData *)unescapeBinary:(const unsigned char *)inSource length:(size_t)len;
supported in 7.3
Result: nil if out of memory
autorelase NSData containing the unescaped original
Abstract: if you need to insert the PostgreSQL object in a NSDictionary,
this is a convenience method that is guaranted to return a unique string usable as key object.
Uniqueness is guaranted for the lifetime of the program duration.
- (NSString *)uniqueID;
Result: unique id string.
Abstract: uniqueRowIdForTable: requires you have a
_rowid bigserial NOT NULL PRIMARY KEY
field in the table
- (const char *)uniqueRowIdForTable:(const char *)tableName;
Result: the column value as a string.
Abstract: let you specify the column name to be used for generating the unique "rowid".
Next rowid is generated by executing the following SQL statement:
SELECT max(colName)+1 FROM tableName
- (const char *)uniqueRowIdForTable:(const char *)tableName column:(const char *)colName;
Result: the column value as a string.
Abstract: delete a large object
- (int)unlinkBinary:(Oid)inOid;
Result: result code from lo_unlink
(Last Updated 12/27/2002)