GPPC API与PostgreSQL定义的C语言函数共享一些概念。 有关开发C语言函数的详细信息，请参阅PostgreSQL文档中的C语言函数。

GPPC API是一个包装器，它使C/C++函数可以在Greenplum数据库中调用SQL。 这个包装器通过API定义的函数和宏对表和数据操作以及SPI操作进行规范化来屏蔽您从Greenplum数据库更改中编写的GPPC函数。

GPPC API包括以下函数和宏：

• 对基础和复合数据类型进行操作。
• 处理函数参数和返回值。
• 分配和释放内存。
• 记录并向客户报告错误。
• 发出SPI查询。
• 返回一个表或一组行。
• 将表作为函数输入参数。

您可以将使用GPPC API编写的函数编译到Greenplum数据库服务器按需加载的一个或多个共享库中。

您可以使用PostgreSQL构建扩展基础结构（PGXS）根据Greenplum数据库安装为您的GPPC函数构建源代码。 该框架自动化简单模块的通用构建规则。 如果您有一个更复杂的用例，则需要编写自己的构建系统。

要使用PGXS基础结构为使用GPPC API创建的函数生成共享库，请创建一个设置PGXS特定变量的简单Makefile。

MODULE_big = sharedlib_name
OBJS = src1.o src2.o
PG_CPPFLAGS = -I$(shell $(PG_CONFIG) --includedir)
SHLIB_LINK = -L$(shell $(PG_CONFIG) --libdir) -lgppc

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

MODULE_big标识Makefile生成的共享库的基本名称。

PG_CPPFLAGS将Greenplum数据库安装包含目录添加到编译器头文件搜索路径中。

SHLIB_LINK将Greenplum数据库安装库目录添加到链接器搜索路径。 此变量还将GPPC库（-lgppc）添加到link命令。

PG_CONFIG和PGXS变量设置和include语句是必需的， 通常位于Makefile的最后三行。

在用户可以从SQL调用GPPC函数之前，必须使用Greenplum数据库注册该函数。

注册GPPC函数涉及将GPPC函数签名映射到SQL用户定义的函数。 您可以使用CREATE FUNCTION .. AS 命令定义此映射，以指定GPPC共享库名称。 您可以选择为GPPC和SQL函数使用相同的名称或不同的名称。

CREATE FUNCTION sql_function_name(arg[, ...]) RETURNS return_type
  AS 'shared_library_path'[, 'gppc_function_name']
LANGUAGE C STRICT [WITH (DESCRIBE=describe_function)];

指定shared_library_path时，可以省略共享库.so扩展名。

CREATE FUNCTION add_two_int4s_gppc(int4, int4) RETURNS int8
  AS 'gppc_try.so', 'add_int4s'
LANGUAGE C STRICT;

您必须以适合Greenplum集群中Greenplum数据库管理员部署的形式打包GPPC共享库和SQL函数注册脚本。 提供GPPC包的特定部署说明。

构建程序包和部署说明时，请考虑以下事项：

• 考虑提供Greenplum数据库管理员运行的shell脚本或程序，以便将共享库安装到所需的文件系统位置并注册GPPC函数。
• 必须将GPPC共享库安装到master主机上的相同文件系统位置以及Greenplum数据库群集中的每个segment主机上。
• gpadmin用户必须具有遍历GPPC共享库文件的完整文件系统路径的权限。
• 安装在Greenplum数据库部署中后， GPPC共享库的文件系统位置决定了在使用CREATE FUNCTION ... AS命令在库中注册函数时如何引用共享库。
• 创建一个.sql脚本文件，为GPPC共享库中的每个GPPC函数注册一个SQL UDF。 您在.sql注册脚本中创建的函数必须引用GPPC共享库的部署位置。 在GPPC部署包中包含此脚本。
• 记录运行GPPC包部署脚本的说明（如果提供）。
• 如果未在程序包部署脚本中包含此任务，请记录有关安装GPPC共享库的说明。
• 如果未在程序包部署脚本中包含此任务，请记录有关安装和运行函数注册脚本的说明。

在此示例中，您将开发，构建和部署GPPC共享库，并注册并运行名为concat_two_strings的GPPC函数。 此函数使用GPPC API连接两个字符串参数并返回结果。

您将在Greenplum数据库主控主机上开发GPPC函数。 部署您在此示例中创建的GPPC共享库需要对Greenplum数据库集群的管理访问权限。

执行以下过程以运行该示例：

1. 登录Greenplum数据库主控主机并设置您的环境。例如：

   $ ssh gpadmin@<gpmaster>
   gpadmin@gpmaster$ . /usr/local/greenplum-db/greenplum_path.sh

2. 创建工作目录并导航到新目录。例如：

   gpadmin@gpmaster$ mkdir gppc_work
   gpadmin@gpmaster$ cd gppc_work

3. 通过在您选择的编辑器中打开文件，为GPPC源代码准备文件。 例如，要使用vi打开名为gppc_concat.c的文件：

   gpadmin@gpmaster$ vi gppc_concat.c

4. 将以下代码复制/粘贴到文件中：

   #include <stdio.h>
   #include <string.h>
   #include "gppc.h"
   
   // make the function SQL-invokable
   GPPC_FUNCTION_INFO(concat_two_strings);
   
   // declare the function
   GppcDatum concat_two_strings(GPPC_FUNCTION_ARGS);
   
   GppcDatum
   concat_two_strings(GPPC_FUNCTION_ARGS)
   {
       // retrieve the text input arguments
       GppcText arg0 = GPPC_GETARG_TEXT(0);
       GppcText arg1 = GPPC_GETARG_TEXT(1);
   
       // determine the size of the concatenated string and allocate
       // text memory of this size
       size_t arg0_len = GppcGetTextLength(arg0);
       size_t arg1_len = GppcGetTextLength(arg1);
       GppcText retstring = GppcAllocText(arg0_len + arg1_len);
   
       // construct the concatenated return string
       memcpy(GppcGetTextPointer(retstring), GppcGetTextPointer(arg0), arg0_len);
       memcpy(GppcGetTextPointer(retstring) + arg0_len, GppcGetTextPointer(arg1), arg1_len);
   
       GPPC_RETURN_TEXT( retstring );
   }

   代码声明并实现了concat_two_strings()函数。 它使用GPPC数据类型，宏和函数来获取函数参数， 为连接的字符串分配内存，将参数复制到新字符串中，然后返回结果。

5. 保存文件并退出编辑器。
6. 在您选择的编辑器中打开名为Makefile的文件。 将以下文本复制/粘贴到文件中：

   MODULE_big = gppc_concat
   OBJS = gppc_concat.o
   
   PG_CONFIG = pg_config
   PGXS := $(shell $(PG_CONFIG) --pgxs)
   
   PG_CPPFLAGS = -I$(shell $(PG_CONFIG) --includedir)
   SHLIB_LINK = -L$(shell $(PG_CONFIG) --libdir) -lgppc
   include $(PGXS)

7. 保存文件并退出编辑器。
8. 为concat_two_strings()函数构建GPPC共享库。例如：

   gpadmin@gpmaster$ make all

   make命令在当前工作目录中生成名为gppc_concat.so的共享库文件。

9. 将共享库复制到Greenplum数据库安装。 您必须具有Greenplum数据库管理权限才能复制该文件。 例如：

   gpadmin@gpmaster$ cp gppc_concat.so /usr/local/greenplum-db/lib/postgresql/

10. 将共享库复制到Greenplum数据库安装中的每个主机。 例如，如果seghostfile包含Greenplum数据库集群中segment主机的列表，每个主机行：

    gpadmin@gpmaster$ gpscp -v -f seghostfile /usr/local/greenplum-db/lib/postgresql/gppc_concat.so =:/usr/local/greenplum-db/lib/postgresql/gppc_concat.so

11. 打开psql会话。例如：

    gpadmin@gpmaster$ psql -d testdb

12. 使用Greenplum数据库注册名为concat_two_strings()的GPPC函数。 例如，将Greenplum数据库函数concat_with_gppc()映射到GPPC concat_two_strings()函数：

    testdb=# CREATE FUNCTION concat_with_gppc(text, text) RETURNS text
      AS 'gppc_concat', 'concat_two_strings'
    LANGUAGE C STRICT;

13. 运行concat_with_gppc()函数。例如：

    testdb=# SELECT concat_with_gppc( 'happy', 'monday' );
     concat_with_gppc
    ------------------
     happymonday
    (1 row)
    

在此示例中，您将开发，构建和部署GPPC共享库。 您还可以为名为return_tbl()的GPPC函数创建并运行.sql注册脚本。 此函数使用GPPC API获取带有整数和文本列的输入表，确定整数列是否大于13， 并返回带有输入整数列的结果表和一个标识整数是否为的整数的布尔列return_tbl()使用GPPC API报告和SRF函数和宏。

您将在Greenplum数据库master主机上开发GPPC函数。 部署您在此示例中创建的GPPC共享库需要对Greenplum数据库集群的管理访问权限。

执行以下过程以运行该示例：

1. 登录Greenplum数据库master主机并设置您的环境。例如：

   $ ssh gpadmin@<gpmaster>
   gpadmin@gpmaster$ . /usr/local/greenplum-db/greenplum_path.sh

2. 创建工作目录并导航到新目录。例如：

   gpadmin@gpmaster$ mkdir gppc_work
   gpadmin@gpmaster$ cd gppc_work

3. 通过在您选择的编辑器中打开文件，为GPPC代码准备源文件。 例如，要使用vi打开名为gppc_concat.c的文件：

   gpadmin@gpmaster$ vi gppc_rettbl.c

4. 将以下代码复制/粘贴到文件中：

   #include <stdio.h>
   #include <string.h>
   #include "gppc.h"
   
   // initialize the logging level
   GppcReportLevel level = GPPC_INFO;
   
   // make the function SQL-invokable and declare the function
   GPPC_FUNCTION_INFO(return_tbl);
   GppcDatum return_tbl(GPPC_FUNCTION_ARGS);
   
   GppcDatum
   return_tbl(GPPC_FUNCTION_ARGS)
   {
       GppcFuncCallContext	fctx;
       GppcAnyTable	intbl;
       GppcHeapTuple	intuple;
       GppcTupleDesc	in_tupdesc, out_tupdesc;
       GppcBool  		resbool = false;
       GppcDatum  		result, boolres, values[2];
       bool		nulls[2] = {false, false};
   
       // single input argument - the table
       intbl = GPPC_GETARG_ANYTABLE(0);
   
       // set the function context
       if (GPPC_SRF_IS_FIRSTCALL()) {
           fctx = GPPC_SRF_FIRSTCALL_INIT();
       }
       fctx = GPPC_SRF_PERCALL_SETUP();
   
       // get the tuple descriptor for the input table
       in_tupdesc  = GppcAnyTableGetTupleDesc(intbl);
   
       // retrieve the next tuple
       intuple = GppcAnyTableGetNextTuple(intbl);
       if( intuple == NULL ) {
         // no more tuples, conclude
         GPPC_SRF_RETURN_DONE(fctx);
       }
   
       // get the output tuple descriptor and verify that it is
       // defined as we expect
       out_tupdesc = GPPC_SRF_RESULT_DESC();
       if (GppcTupleDescNattrs(out_tupdesc) != 2                ||
           GppcTupleDescAttrType(out_tupdesc, 0) != GppcOidInt4 ||
           GppcTupleDescAttrType(out_tupdesc, 1) != GppcOidBool) {
           GppcReport(GPPC_ERROR, "INVALID out_tupdesc tuple");
       }
   
       // log the attribute names of the output tuple descriptor
       GppcReport(level, "output tuple descriptor attr0 name: %s", GppcTupleDescAttrName(out_tupdesc, 0));
       GppcReport(level, "output tuple descriptor attr1 name: %s", GppcTupleDescAttrName(out_tupdesc, 1));
   
       // retrieve the attribute values by name from the tuple
       bool text_isnull, int_isnull;
       GppcDatum intdat = GppcGetAttributeByName(intuple, "id", &int_isnull);
       GppcDatum textdat = GppcGetAttributeByName(intuple, "msg", &text_isnull);
   
       // convert datum to specific type
       GppcInt4 intarg = GppcDatumGetInt4(intdat);
       GppcReport(level, "id: %d", intarg);
       GppcReport(level, "msg: %s", GppcTextGetCString(GppcDatumGetText(textdat)));
   
       // perform the >13 check on the integer
       if( !int_isnull && (intarg > 13) ) {
           // greater than 13?
           resbool = true;
           GppcReport(level, "id is greater than 13!");
       }
   
       // values are datums; use integer from the tuple and
       // construct the datum for the boolean return
       values[0] = intdat;
       boolres = GppcBoolGetDatum(resbool);
       values[1] = boolres;
   
       // build a datum tuple and return
       result = GppcBuildHeapTupleDatum(out_tupdesc, values, nulls);
       GPPC_SRF_RETURN_NEXT(fctx, result);
   
   }

   代码声明并实现了return_tbl()函数。 它使用GPPC数据类型，宏和函数来获取函数参数，检查元组描述符，构建返回元组，并返回结果。 该函数还使用SRF宏来跟踪函数调用之间的元组上下文。

5. 保存文件并退出编辑器。
6. 在您选择的编辑器中打开名为Makefile的文件。 将以下文本复制/粘贴到文件中：

   MODULE_big = gppc_rettbl
   OBJS = gppc_rettbl.o
   
   PG_CONFIG = pg_config
   PGXS := $(shell $(PG_CONFIG) --pgxs)
   
   PG_CPPFLAGS = -I$(shell $(PG_CONFIG) --includedir)
   SHLIB_LINK = -L$(shell $(PG_CONFIG) --libdir) -lgppc
   include $(PGXS)

7. 保存文件并退出编辑器。
8. 为return_tbl()函数构建GPPC共享库。例如：

   gpadmin@gpmaster$ make all

   make命令在当前工作目录中生成名为gppc_rettbl.so的共享库文件。

9. 将共享库复制到Greenplum数据库安装。 您必须具有Greenplum数据库管理权限才能复制该文件。 例如：

   gpadmin@gpmaster$ cp gppc_rettbl.so /usr/local/greenplum-db/lib/postgresql/

   此命令将共享库复制到$libdir

10. 将共享库复制到Greenplum数据库安装中的每个主机。 例如，如果seghostfile包含Greenplum数据库集群中segment主机的列表，每个主机一行：

    gpadmin@gpmaster$ gpscp -v -f seghostfile /usr/local/greenplum-db/lib/postgresql/gppc_rettbl.so =:/usr/local/greenplum-db/lib/postgresql/gppc_rettbl.so

11. 创建.sql文件以注册GPPC return_tbl()函数。 在您选择的编辑器中打开名为gppc_rettbl_reg.sql的文件。
12. 将以下文本复制/粘贴到文件中：

    CREATE FUNCTION rettbl_gppc(anytable) RETURNS TABLE(id int4, thirteen bool)
      AS 'gppc_rettbl', 'return_tbl'
    LANGUAGE C STRICT;

13. 通过运行刚刚创建的脚本来注册GPPC功能。 例如，要在名为testdb的数据库中注册该函数：

    gpadmin@gpmaster$ psql -d testdb -f gppc_rettbl_reg.sql

14. 打开psql会话。例如：

    gpadmin@gpmaster$ psql -d testdb

15. 创建包含一些测试数据的表。例如：

    CREATE TABLE gppc_testtbl( id int, msg text );
    INSERT INTO gppc_testtbl VALUES (1, 'f1');
    INSERT INTO gppc_testtbl VALUES (7, 'f7');
    INSERT INTO gppc_testtbl VALUES (10, 'f10');
    INSERT INTO gppc_testtbl VALUES (13, 'f13');
    INSERT INTO gppc_testtbl VALUES (15, 'f15');
    INSERT INTO gppc_testtbl VALUES (17, 'f17');

16. 运行rettbl_gppc()函数。例如：

    testdb=# SELECT * FROM rettbl_gppc(TABLE(SELECT * FROM gppc_testtbl));
     id | thirteen 
    ----+----------
      1 | f
      7 | f
     13 | f
     15 | t
     17 | t
     10 | f
    (6 rows)