libpqtypes home page

PQregisterTypes(3)             libpqtypes Manual            PQregisterTypes(3)



NAME
       PQregisterTypes  -  Registers  sub-classes, composites and user-defined
       types.

SYNOPSIS
       #include <libpqtypes.h>
       int PQregisterTypes(PGconn *conn, int which, PGregisterType *types,
                           int count, int async);

DESCRIPTION
       The PQregisterTypes() function allows an application to register one or
       more  PQT_SUBCLASS,  PQT_COMPOSITE  or  PQT_USERDEFINED  types which is
       defined by the which argument.

       When which is PQT_COMPOSITE or PQT_USERDEFINED, this function must exe-
       cute  a  query  against  the backend to retrieve type information, thus
       this should not be called from within a transaction.  It is recommended
       to  register  multiple  composites at the same time to avoid round trip
       overhead.

       The types argument is an array  containing  count  types  to  register.
       Composites  do  not use the typput or typget members of the PGregister-
       Type structure, thus these memebrs are ignored.  If any composite  does
       not exist, the register is aborted.  User-defined types must set either
       typput and/or typget for each type.   Sub-classes typname member of the
       PGregisterType  structure must specify an inheritence relationship: ex.
       "myint=int4" where myint inherits from int4.  The  '='  is  called  the
       inheritence  operator.  If both typput and typget members of the PGreg-
       isterType structure are NULL, the type  at  that  element  will  behave
       identically  to  the  type it is inheriting from; an alias.  Otherwise,
       the base type's put and/or get routines will be overridden.

       The async argument indicates  if  the  asynchronous  type  registration
       should  be  used.  When non-zero, the caller must proceed in the normal
       async libpq fashion (PQconsumeInput, PQisBusy, PQgetResult) and provide
       a  PGresult to PQregisterResult when obtained to complete the registra-
       tion.

       NOTE: The typname member of the PGregisterType structure can optionally
       contain the type's schema: schema.typname.

       WARNING:  PQparamCreate  is  only aware of types that have already been
       registered.  If you need to put a type into a param, make  sure  it  is
       first registered.


EXAMPLES
   Using PQregisterTypes
       The example registers two composite types.

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

              if (!PQregisterTypes(conn, PQT_COMPOSITE, comp_types, 2, 0))
                   fprintf(stderr, "PQregisterTypes: %s\n", PQgeterror());

RETURN VALUE
       On  success,  both PQregisterTypes returns a non-zero value.  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
       PQregisterResult(3), pqt-handlers(3), PQputf(3), PQgetf(3)





libpqtypes                           2011                   PQregisterTypes(3)

libpqtypes home page