PQregisterResult(3)

NAME
PQregisterResult - Registers sub-classes, composites and user-defined types found within a PGresult.

SYNOPSIS

#include <libpqtypes.h>
int PQregisterResult(PGconn *conn, int which, PGregisterType *types,
                    int count, PGresult *res);

DESCRIPTION

The PQregisterResult() function registers the types found within a given PGresult, thus this function makes no calls to a PostgreSQL server since the result data is already available.

The which argument can be PQT_COMPOSITE or PQT_USERDEFINED, but not PQT_SUBCLASS. The only reason being sub-classes don't talk to the server so they have no result set.

The types argument is an array containing count types to register. This array must be identical to what was provided to the originating PQregisterTypes call.

The res argument is a PGresult normally created by calling PQregisterTypes followed by PQgetResult. However, it is possible to create your own result via PQmakeEmptyPGresult, PQsetResultAttrs, PQsetvalue and call this function. This approach is a bit risky being how the result set generated by type lookup queries are internal and subject to change.

EXAMPLES

  Using PQregisterResult
The example registers two composite types asynchronously. It is worth noting that the PGresult obtained via PQgetResult can be cached by an application and used when creating new connections, as a way to avoid repeatedly performing type lookups with the server.

    PGregisterType comp_types[] = {
    	{"myschema.simple", NULL, NULL},
    	{"complex", NULL, NULL}
    };

    /* asynchronous registration */
    if (PQregisterTypes(conn, PQT_COMPOSITE, comp_types, 2, 1))
    {
    	/* example of a typical event loop */
    	for(;;)
    	{
    		int n;
    		fd_set set;
    		int fd = PQsocket(conn);
    		struct timeval tv = {0, 500000};

    		FD_ZERO(&set);
    		FD_SET(fd, &set);
    		n = select(fd + 1, &set, NULL, NULL, &tv); //or kqueue,epoll,poll,etc..

    		if (n == -1)
    		{
    			//error
    		}
    		else if (n == 0)
    		{
    			//timeout, do other work ....
    		}
    		else
    		{
    			PGresult *res;

    			PQconsumeInput(conn);
    			if(!PQisBusy(conn))
    			{
    				/* done */
    				if(!(res = PQgetResult(conn)))
    					break;

    				n = PQregisterResult(conn, PQT_COMPOSITE, comp_types, 2, res);

    				/* This could also be cached and reused with PQregisterResult */
    				PQclear(res);

    				if (!n)
    					//error, consult PQgeterror()
    			}
    		}
    	}
    }

RETURN VALUE

On success, a non-zero value is returned. On error, zero is returned and PQgeterror(3) will contain an error message.

EXAMPLES

None.

AUTHOR

A contribution of eSilo, LLC. for the PostgreSQL Database Management System. Written by Andrew Chernow.

REPORTING BUGS

Report bugs to <libpqtypes@esilo.com>.

COPYRIGHT

Copyright (c) 2011 eSilo, LLC. All rights reserved.
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

PQregisterTypes(3), pqt-handlers(3), PQputf(3), PQgetf(3)