Methods



asyncResultAvailable

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

backendPID

Abstract: returns backend process id of the database server.
- (int)backendPID; 

Result: backend process id.

beginTransaction

Abstract: self explanatory
- (BOOL)beginTransaction; 

DOES NOTHING (and returns YES) IN DEMO VERSION.

Result: YES if successful

bufferHasCommands

- (BOOL)bufferHasCommands; 

Result: YES if command buffer contains not yet executed string.

cancelRequest

- (BOOL)cancelRequest; 


clearCommands

Abstract: clears the command buffer
- (void)clearCommands; 


clientEncoding

- (int)clientEncoding; 

Result: client encoding id.

closeCursor

Abstract: close the cursor opened with executeCommandWithCursor
- (BOOL)closeCursor:(const char *)cursorName; 

Parameters

NameDescription
cursorName
Result: YES if successful.

commandBuffer

- (const char *)commandBuffer; 

Result: pointer on command buffer

connectAskingUser

Abstract: present a dialog to let the user fill in fields to connect to a database.
- (BOOL)connectAskingUser:(int *)returnCode; 

Parameters

NameDescription
pointeran integer buffer o hold result code from backend.
Result: YES if connection successfull, NO otherwise.

connectAskingUserWithDefaults

Abstract: present a dialog to let the user fill in fields to connect to a database.
- (BOOL)connectAskingUserWithDefaults:(NSDictionary *)defaults return:(int *)returnCode; 

Parameters

NameDescription
Defaultsis a dictionary with following non mandatory keys
host, port, dbname, user, password, options
pointeran integer buffer o hold result code from backend.
Result: YES if connection successfull, NO otherwise.

connectErrorMessage

- (const char *)connectErrorMessage:(int)errorCode; 

Parameters

NameDescription
errorCodeto be converted into string.
Result: PQresStatus(errorCode)

connectToDatabase

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

NameDescription
connectInfocharacter buffer holding the conenction string to be used.
returnpointer an integer buffer o hold result code from backend.
Result: YES if connection successfull, NO otherwise.

connectToDatabase

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

NameDescription
dbNamedatabasename as defined in PostgreSQL.
hostNamenetwork name of host computer
loginNameuser name for login
passworduser password for login
returnCodewhere to return int result code for connection
Result: YES if connection successful No otherwise

databaseName

Abstract: returns database name of the connection.
- (const char *)databaseName; 

Result: pointer on database name string buffer.

debugMode

- (BOOL)debugMode; 

Result: current debug mode of the connection.

delegate

- (id)delegate; 


disconnect

Abstract: disconnect cuurently opened connection.
- (void)disconnect; 

Not strictly necessary in the API since connectTodatabase disconnects automatically from any previously opened connection.


endTransaction

Abstract: self explanatory
- (BOOL)endTransaction; 

DOES NOTHING (and returns YES) IN DEMO VERSION.

Result: YES if successful

escapeBinary

- (NSData *)escapeBinary:(const unsigned char *)inSource length:(size_t)len; 

Result: nil if out of memory
autorelase NSData containing the escaped original

escapeString

- (NSString *)escapeString:(const char *)inSource; 

Result: nil if out of memory
autorelase NSString containing the escaped original

executeAsyncCommand

Abstract: pass the current command buffer to the PostgreSQL server for asynchronous execution
- (BOOL)executeAsyncCommand; 

Result: YES if successful

executeAsyncCommandWithCursor

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

NameDescription
cursorNamethe name of the cursor
binaryif cursor should be declared BINARY
Result: YES if successful

executeCommand

Abstract: pass the current command buffer to the PostgreSQL server for execution
- (BOOL)executeCommand; 

Result: YES if successful

executeCommandWithCursor

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

NameDescription
cursorNamethe name of the cursor
binaryif cursor should be declared BINARY
Result: YES if successful

exportBinaryToFile

Abstract: Export the BLOB to the file system.
- (int)exportBinaryToFile:(Oid)inOid pathName:(const char *)inPathName; 

Result: the lo_export returned code.

frameworkVersion

Abstract: returns version of the framework.
- (NSString *)frameworkVersion; 

Result: NSString describing the framework version.

getPGconn

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.

getResultSet

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.

getTimeOut

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.

getVariables

- (NSDictionary *)getVariables; 

Result: returns a dictionary of Postgre variables ("SHOW ALL" 's result).

hostName

Abstract: returns host name of the connection.
- (const char *)hostName; 

Result: pointer on host name string buffer.

importBinaryFromFile

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.

insertBinary

Abstract: insert a BLOB made from a memory buffer.
- (Oid)insertBinary:(unsigned char *)inData size:(int)size; 

Parameters

NameDescription
inDatapointer on the memory buffer
sizeof the memory buffer
Result: the Oid of the created BLOB, 0 if an error occurred.

insertBinaryFromData

Abstract: insert a BLOB made from NSData
- (Oid)insertBinaryFromData:(NSData *)inData; 

Result: the Oid of the created BLOB, 0 if an error occurred.

insertBinaryFromFile

Abstract: insert a BLOB made from NSFileHandle
- (Oid)insertBinaryFromFile:(NSFileHandle *)inFile; 

Parameters

NameDescription
theNSFileHandle on the file.
Result: the Oid of the created BLOB, 0 if an error occurred.

loginName

Abstract: returns user name of the connection.
- (const char *)loginName; 

Result: pointer on user name string buffer.

makeCommand

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.


makeCommandf

Abstract: same as makeCommand but with a format and variable arguments list (printf-like)
- (void)makeCommandf:(const char *)format, ...; 


options

Abstract: returns options of the connection.
- (const char *)options; 

Result: pointer on options string buffer.

overWriteBinaryWithDataFromStart

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

password

Abstract: returns password of the connection.
- (const char *)password; 

Result: pointer on password string buffer.

port

Abstract: returns port of the connection.
- (const char *)port; 

Result: pointer on port string buffer.

postgreSQLVersion

Abstract: returns version of the running postmaster.
- (NSString *)postgreSQLVersion; 

returns reulst of executing the SELECT version() query.

Result: NSString containing the postgreSQL version.

removeNotificationFor

Abstract: Removes the listener of the list of registered listener and execute a UNLISTEN condition query.
- (void)removeNotificationFor:(PgSQLListener *)listener; 


resultReturned

- (BOOL)resultReturned; 

Result: YES if latest command executed returns rows.

retrieveBinary

Abstract: retrieve a BLOB into an newly created NSData object (autorelease)
- (NSData *)retrieveBinary:(Oid)inOid; 

Parameters

NameDescription
theOid of the BLOB to be retrieved.
Result: NSData object or nil.

retrieveBinaryFromStartLength

Abstract: retrieve part of a BLOB into an newly created NSData object (autorelease)
- (NSData *)retrieveBinaryFromStartLength:(Oid)inOid start:(int)inStart length:(int)length; 

Parameters

NameDescription
theOid of the BLOB to be retrieved.
startposition from which to retrieve data
lengthnumber of bytes to retrieve.
Result: NSData object or nil.

rollbackTransaction

Abstract: self explanatory
- (BOOL)rollbackTransaction; 

DOES NOTHING (and returns YES) IN DEMO VERSION.

Result: YES if successful

serverMessage

- (const char *)serverMessage; 

Result: PQerrorMessage()

setClientEncoding

- (int)setClientEncoding:(const char *)encoding; 

Parameters

NameDescription
encodingname

setDebug

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

NameDescription
ynas you expect.

setDebugMode

Abstract: turns on|off instance debugging.
- (void)setDebugMode:(BOOL)turnOn; 

Parameters

NameDescription
turnOnas you expect.

setDelegate

- (void)setDelegate:(id)newDelegate; 


setNoticeProcessor

- (PQnoticeProcessor)setNoticeProcessor:(PQnoticeProcessor)proc userArg:(void *)arg; 


setTimeOut

Abstract: set the time out to be used when doing an asynchronous query.
- (void)setTimeOut:(long)inTimeOut; 

Parameters

NameDescription
timeout value in seconds.

showClientEncoding

- (NSStringEncoding)showClientEncoding; 

Result: returns the client encoding converted into NSStringEncoding.

showServerEncoding

- (NSStringEncoding)showServerEncoding; 

Result: returns the server encoding converted into NSStringEncoding.

socket

Abstract: returns socket of the database server.
- (int)socket; 

Result: socket number.

startNotificationFor

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/

startTracing

Abstract: start tracing to file traceFileName.
- (BOOL)startTracing:(const char *)traceFileName; 

Parameters

NameDescription
traceFileNamefull path name of file to dump tracing information.
Result: YES if successfull

stopTracing

Abstract: turns off tracing.
- (void)stopTracing; 


transactionInProgress

Abstract: self explanatory
- (BOOL)transactionInProgress; 

Result: YES if a transaction is in progress (beginTransaction has been called)

tty

Abstract: returns tty of the connection.
- (const char *)tty; 

Result: pointer on tty string buffer.

unescapeBinary

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

uniqueID

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.

uniqueRowIdForTable

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.

uniqueRowIdForTable

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.

unlinkBinary

Abstract: delete a large object
- (int)unlinkBinary:(Oid)inOid; 

Result: result code from lo_unlink

(Last Updated 12/27/2002)