From 142d34b7532fdd8e439bdf21b00983c13f4325a5 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Wed, 15 Aug 2018 17:01:39 +0200 Subject: [PATCH 1/3] doc: Update uses of the word "procedure" Historically, the term procedure was used as a synonym for function in Postgres/PostgreSQL. Now we have procedures as separate objects from functions, so we need to clean up the documentation to not mix those terms. In particular, mentions of "trigger procedures" are changed to "trigger functions", and access method "support procedures" are changed to "support functions". (The latter already used FUNCTION in the SQL syntax anyway.) Also, the terminology in the SPI chapter has been cleaned up. A few tests, examples, and code comments are also adjusted to be consistent with documentation changes, but not everything. --- doc/src/sgml/brin.sgml | 52 ++++++------ doc/src/sgml/catalogs.sgml | 20 ++--- doc/src/sgml/event-trigger.sgml | 6 +- doc/src/sgml/func.sgml | 2 +- doc/src/sgml/plhandler.sgml | 2 +- doc/src/sgml/plperl.sgml | 2 +- doc/src/sgml/plpgsql.sgml | 34 ++++---- doc/src/sgml/pltcl.sgml | 40 ++++----- doc/src/sgml/ref/alter_opfamily.sgml | 4 +- doc/src/sgml/ref/create_language.sgml | 2 +- doc/src/sgml/ref/create_opclass.sgml | 6 +- doc/src/sgml/ref/create_operator.sgml | 8 +- doc/src/sgml/ref/create_trigger.sgml | 2 +- doc/src/sgml/spi.sgml | 83 +++++++++---------- doc/src/sgml/xindex.sgml | 2 +- doc/src/sgml/xplang.sgml | 4 +- src/backend/access/gin/ginvalidate.c | 2 +- src/backend/access/gist/gistvalidate.c | 2 +- src/backend/access/hash/hashutil.c | 4 +- src/backend/access/hash/hashvalidate.c | 4 +- src/backend/access/spgist/spgvalidate.c | 2 +- src/backend/commands/opclasscmds.c | 30 +++---- src/bin/psql/describe.c | 2 +- src/include/access/hash.h | 12 +-- src/test/regress/expected/alter_generic.out | 16 ++-- src/test/regress/expected/create_operator.out | 6 +- src/test/regress/sql/create_operator.sql | 6 +- 27 files changed, 174 insertions(+), 181 deletions(-) diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml index f02e061bc1..f47e1968a4 100644 --- a/doc/src/sgml/brin.sgml +++ b/doc/src/sgml/brin.sgml @@ -537,7 +537,7 @@ Extensibility } BrinOpcInfo; BrinOpcInfo.oi_opaque can be used by the - operator class routines to pass information between support procedures + operator class routines to pass information between support functions during an index scan. @@ -587,27 +587,27 @@ Extensibility defined by the user for other data types using equivalent definitions, without having to write any source code; appropriate catalog entries being declared is enough. Note that assumptions about the semantics of operator - strategies are embedded in the support procedures' source code. + strategies are embedded in the support functions' source code. Operator classes that implement completely different semantics are also - possible, provided implementations of the four main support procedures + possible, provided implementations of the four main support functions described above are written. Note that backwards compatibility across major - releases is not guaranteed: for example, additional support procedures might + releases is not guaranteed: for example, additional support functions might be required in later releases. To write an operator class for a data type that implements a totally - ordered set, it is possible to use the minmax support procedures + ordered set, it is possible to use the minmax support functions alongside the corresponding operators, as shown in . - All operator class members (procedures and operators) are mandatory. + All operator class members (functions and operators) are mandatory. - Procedure and Support Numbers for Minmax Operator Classes + Function and Support Numbers for Minmax Operator Classes @@ -617,19 +617,19 @@ Procedure and Support Numbers for Minmax Operator Classes - Support Procedure 1 + Support Function 1 internal function brin_minmax_opcinfo() - Support Procedure 2 + Support Function 2 internal function brin_minmax_add_value() - Support Procedure 3 + Support Function 3 internal function brin_minmax_consistent() - Support Procedure 4 + Support Function 4 internal function brin_minmax_union() @@ -659,7 +659,7 @@ Procedure and Support Numbers for Minmax Operator Classes To write an operator class for a complex data type which has values included within another type, it's possible to use the inclusion support - procedures alongside the corresponding operators, as shown + functions alongside the corresponding operators, as shown in . It requires only a single additional function, which can be written in any language. More functions can be defined for additional functionality. All operators @@ -668,7 +668,7 @@ Procedure and Support Numbers for Minmax Operator Classes
- Procedure and Support Numbers for Inclusion Operator Classes + Function and Support Numbers for Inclusion Operator Classes @@ -679,42 +679,42 @@ Procedure and Support Numbers for Inclusion Operator Classes - Support Procedure 1 + Support Function 1 internal function brin_inclusion_opcinfo() - Support Procedure 2 + Support Function 2 internal function brin_inclusion_add_value() - Support Procedure 3 + Support Function 3 internal function brin_inclusion_consistent() - Support Procedure 4 + Support Function 4 internal function brin_inclusion_union() - Support Procedure 11 + Support Function 11 function to merge two elements - Support Procedure 12 + Support Function 12 optional function to check whether two elements are mergeable - Support Procedure 13 + Support Function 13 optional function to check if an element is contained within another - Support Procedure 14 + Support Function 14 optional function to check whether an element is empty @@ -803,7 +803,7 @@ Procedure and Support Numbers for Inclusion Operator Classes
- Support procedure numbers 1-10 are reserved for the BRIN internal + Support function numbers 1-10 are reserved for the BRIN internal functions, so the SQL level functions start with number 11. Support function number 11 is the main function required to build the index. It should accept two arguments with the same data type as the operator class, @@ -814,11 +814,11 @@ Procedure and Support Numbers for Inclusion Operator Classes - Support procedure numbers 12 and 14 are provided to support - irregularities of built-in data types. Procedure number 12 + Support function numbers 12 and 14 are provided to support + irregularities of built-in data types. Function number 12 is used to support network addresses from different families which - are not mergeable. Procedure number 14 is used to support - empty ranges. Procedure number 13 is an optional but + are not mergeable. Function number 14 is used to support + empty ranges. Function number 13 is an optional but recommended one, which allows the new value to be checked before it is passed to the union function. As the BRIN framework can shortcut some operations when the union is not changed, using this diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 3bb48d4ccf..07e8b3325f 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -67,7 +67,7 @@ System Catalogs pg_amproc - access method support procedures + access method support functions @@ -814,8 +814,8 @@ <structname>pg_amproc</structname> The catalog pg_amproc stores information about - support procedures associated with access method operator families. There - is one row for each support procedure belonging to an operator family. + support functions associated with access method operator families. There + is one row for each support function belonging to an operator family. @@ -864,14 +864,14 @@ <structname>pg_amproc</structname> Columnsamprocnumint2 - Support procedure number + Support function number amproc regproc pg_proc.oid - OID of the procedure + OID of the function @@ -882,9 +882,9 @@ <structname>pg_amproc</structname> Columns The usual interpretation of the amproclefttype and amprocrighttype fields is that they identify the left and right input types of the operator(s) - that a particular support procedure supports. For some access methods - these match the input data type(s) of the support procedure itself, for - others not. There is a notion of default support procedures for + that a particular support function supports. For some access methods + these match the input data type(s) of the support function itself, for + others not. There is a notion of default support functions for an index, which are those with amproclefttype and amprocrighttype both equal to the index operator class's opcintype. @@ -2471,7 +2471,7 @@ <structname>pg_conversion</structname> The catalog pg_conversion describes - encoding conversion procedures. See + encoding conversion functions. See for more information. @@ -2537,7 +2537,7 @@ <structname>pg_conversion</structname> Columnsconprocregprocpg_proc.oid - Conversion procedure + Conversion function diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml index 0a8860490a..be975d1399 100644 --- a/doc/src/sgml/event-trigger.sgml +++ b/doc/src/sgml/event-trigger.sgml @@ -1053,9 +1053,9 @@ A Complete Event Trigger Example =# \dy List of event triggers - Name | Event | Owner | Enabled | Procedure | Tags --------+-------------------+-------+---------+-----------+------ - noddl | ddl_command_start | dim | enabled | noddl | + Name | Event | Owner | Enabled | Function | Tags +-------+-------------------+-------+---------+----------+------ + noddl | ddl_command_start | dim | enabled | noddl | (1 row) =# CREATE TABLE foo(id serial); diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index edc9be92a6..c6f61ce2c0 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -12360,7 +12360,7 @@ Conditional Expressions If your needs go beyond the capabilities of these conditional - expressions, you might want to consider writing a stored procedure + expressions, you might want to consider writing a server-side function in a more expressive programming language. diff --git a/doc/src/sgml/plhandler.sgml b/doc/src/sgml/plhandler.sgml index 4f8c4d040a..73cd7d1387 100644 --- a/doc/src/sgml/plhandler.sgml +++ b/doc/src/sgml/plhandler.sgml @@ -119,7 +119,7 @@ Writing A Procedural Language Handler if (CALLED_AS_TRIGGER(fcinfo)) { /* - * Called as a trigger procedure + * Called as a trigger function */ TriggerData *trigdata = (TriggerData *) fcinfo->context; diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml index 82f56cb8ab..6296a226b6 100644 --- a/doc/src/sgml/plperl.sgml +++ b/doc/src/sgml/plperl.sgml @@ -1337,7 +1337,7 @@ PL/Perl Event Triggers - The return value of the trigger procedure is ignored. + The return value of the trigger function is ignored. diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index d6688e13f4..abe67fa50e 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -19,7 +19,7 @@ Overview - can be used to create functions and trigger procedures, + can be used to create functions and triggers, @@ -305,7 +305,7 @@ Structure of <application>PL/pgSQL</application> for transaction control. PL/pgSQL's BEGIN/END are only for grouping; they do not start or end a transaction. - Functions and trigger procedures are always executed within a transaction + Functions are always executed within a transaction established by an outer query — they cannot start or commit that transaction, since there would be no context for them to execute in. However, a block containing an EXCEPTION clause effectively @@ -579,7 +579,7 @@ <literal>ALIAS</literal> function parameters. The main practical use for this is to assign a different name for variables with predetermined names, such as NEW or OLD within - a trigger procedure. + a trigger function. @@ -3796,7 +3796,7 @@ Checking Assertions - Trigger Procedures + Trigger Functions trigger @@ -3805,8 +3805,8 @@ Trigger Procedures PL/pgSQL can be used to define trigger - procedures on data changes or database events. - A trigger procedure is created with the CREATE FUNCTION + functions on data changes or database events. + A trigger function is created with the CREATE FUNCTION command, declaring it as a function with no arguments and a return type of trigger (for data change triggers) or event_trigger (for database event triggers). @@ -3946,7 +3946,7 @@ Triggers on Data Changes Data type integer; the number of arguments given to the trigger - procedure in the CREATE TRIGGER statement. + function in the CREATE TRIGGER statement. @@ -4025,11 +4025,11 @@ Triggers on Data Changes shows an example of a - trigger procedure in PL/pgSQL. + trigger function in PL/pgSQL. - A <application>PL/pgSQL</application> Trigger Procedure + A <application>PL/pgSQL</application> Trigger Function This example trigger ensures that any time a row is inserted or updated @@ -4078,11 +4078,11 @@ A <application>PL/pgSQL</application> Trigger Procedure holds a row for each insert, update, or delete that occurs. This approach can be thought of as auditing changes to a table. shows an example of an - audit trigger procedure in PL/pgSQL. + audit trigger function in PL/pgSQL. - A <application>PL/pgSQL</application> Trigger Procedure For Auditing + A <application>PL/pgSQL</application> Trigger Function For Auditing This example trigger ensures that any insert, update or delete of a row @@ -4139,7 +4139,7 @@ A <application>PL/pgSQL</application> Trigger Procedure For Auditing</tit </para> <example id="plpgsql-view-trigger-audit-example"> - <title>A <application>PL/pgSQL</application> View Trigger Procedure For Auditing + A <application>PL/pgSQL</application> View Trigger Function For Auditing This example uses a trigger on the view to make it updatable, and @@ -4215,13 +4215,13 @@ A <application>PL/pgSQL</application> View Trigger Procedure For Auditing This technique is commonly used in Data Warehousing, where the tables of measured or observed data (called fact tables) might be extremely large. <xref linkend="plpgsql-trigger-summary-example"/> shows an example of a - trigger procedure in <application>PL/pgSQL</application> that maintains + trigger function in <application>PL/pgSQL</application> that maintains a summary table for a fact table in a data warehouse. </para> <example id="plpgsql-trigger-summary-example"> - <title>A <application>PL/pgSQL</application> Trigger Procedure For Maintaining A Summary Table + A <application>PL/pgSQL</application> Trigger Function For Maintaining A Summary Table The schema detailed here is partly based on the Grocery Store @@ -4445,7 +4445,7 @@ Triggers on Events PL/pgSQL can be used to define event triggers. - PostgreSQL requires that a procedure that + PostgreSQL requires that a function that is to be called as an event trigger must be declared as a function with no arguments and a return type of event_trigger. @@ -4480,11 +4480,11 @@ Triggers on Events shows an example of an - event trigger procedure in PL/pgSQL. + event trigger function in PL/pgSQL. - A <application>PL/pgSQL</application> Event Trigger Procedure + A <application>PL/pgSQL</application> Event Trigger Function This example trigger simply raises a NOTICE message diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index 01f6207d36..97906a67df 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -16,7 +16,7 @@ PL/Tcl - Tcl Procedural Language PostgreSQL database system that enables the Tcl language to be used to write functions and - trigger procedures. + triggers. @@ -587,7 +587,7 @@ Database Access from PL/Tcl - Trigger Procedures in PL/Tcl + Trigger Functions in PL/Tcl trigger @@ -595,13 +595,13 @@ Trigger Procedures in PL/Tcl - Trigger procedures can be written in PL/Tcl. - PostgreSQL requires that a procedure that is to be called + Trigger functions can be written in PL/Tcl. + PostgreSQL requires that a function that is to be called as a trigger must be declared as a function with no arguments and a return type of trigger. - The information from the trigger manager is passed to the procedure body + The information from the trigger manager is passed to the function body in the following variables: @@ -619,7 +619,7 @@ Trigger Procedures in PL/Tcl $TG_relid - The object ID of the table that caused the trigger procedure + The object ID of the table that caused the trigger function to be invoked. @@ -629,7 +629,7 @@ Trigger Procedures in PL/Tcl $TG_table_name - The name of the table that caused the trigger procedure + The name of the table that caused the trigger function to be invoked. @@ -639,7 +639,7 @@ Trigger Procedures in PL/Tcl $TG_table_schema - The schema of the table that caused the trigger procedure + The schema of the table that caused the trigger function to be invoked. @@ -722,9 +722,9 @@ Trigger Procedures in PL/Tcl $args - A Tcl list of the arguments to the procedure as given in the + A Tcl list of the arguments to the function as given in the CREATE TRIGGER statement. These arguments are also accessible as - $1 ... $n in the procedure body. + $1 ... $n in the function body. @@ -733,7 +733,7 @@ Trigger Procedures in PL/Tcl - The return value from a trigger procedure can be one of the strings + The return value from a trigger function can be one of the strings OK or SKIP, or a list of column name/value pairs. If the return value is OK, the operation (INSERT/UPDATE/DELETE) @@ -764,7 +764,7 @@ Trigger Procedures in PL/Tcl - Here's a little example trigger procedure that forces an integer value + Here's a little example trigger function that forces an integer value in a table to keep track of the number of updates that are performed on the row. For new rows inserted, the value is initialized to 0 and then incremented on every update operation. @@ -792,14 +792,14 @@ Trigger Procedures in PL/Tcl FOR EACH ROW EXECUTE PROCEDURE trigfunc_modcount('modcnt'); - Notice that the trigger procedure itself does not know the column + Notice that the trigger function itself does not know the column name; that's supplied from the trigger arguments. This lets the - trigger procedure be reused with different tables. + trigger function be reused with different tables. - Event Trigger Procedures in PL/Tcl + Event Trigger Functions in PL/Tcl event trigger @@ -807,13 +807,13 @@ Event Trigger Procedures in PL/Tcl - Event trigger procedures can be written in PL/Tcl. - PostgreSQL requires that a procedure that is + Event trigger functions can be written in PL/Tcl. + PostgreSQL requires that a function that is to be called as an event trigger must be declared as a function with no arguments and a return type of event_trigger. - The information from the trigger manager is passed to the procedure body + The information from the trigger manager is passed to the function body in the following variables: @@ -839,11 +839,11 @@ Event Trigger Procedures in PL/Tcl - The return value of the trigger procedure is ignored. + The return value of the trigger function is ignored. - Here's a little example event trigger procedure that simply raises + Here's a little example event trigger function that simply raises a NOTICE message each time a supported command is executed: diff --git a/doc/src/sgml/ref/alter_opfamily.sgml b/doc/src/sgml/ref/alter_opfamily.sgml index 3c0922c645..848156c9d7 100644 --- a/doc/src/sgml/ref/alter_opfamily.sgml +++ b/doc/src/sgml/ref/alter_opfamily.sgml @@ -185,7 +185,7 @@ Parameters support_number - The index method's support procedure number for a + The index method's support function number for a function associated with the operator family. @@ -196,7 +196,7 @@ Parameters The name (optionally schema-qualified) of a function that is an index - method support procedure for the operator family. If no argument list + method support function for the operator family. If no argument list is specified, the name must be unique in its schema. diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index 6bb69cf0ef..13b28b1ccc 100644 --- a/doc/src/sgml/ref/create_language.sgml +++ b/doc/src/sgml/ref/create_language.sgml @@ -33,7 +33,7 @@ Description CREATE LANGUAGE registers a new procedural language with a PostgreSQL - database. Subsequently, functions and trigger procedures can be + database. Subsequently, functions and procedures can be defined in this new language. diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml index 0714aeca7c..dd5252fd97 100644 --- a/doc/src/sgml/ref/create_opclass.sgml +++ b/doc/src/sgml/ref/create_opclass.sgml @@ -38,7 +38,7 @@ Description An operator class defines how a particular data type can be used with an index. The operator class specifies that certain operators will fill particular roles or strategies for this data type and this - index method. The operator class also specifies the support procedures to + index method. The operator class also specifies the support functions to be used by the index method when the operator class is selected for an index column. All the operators and functions used by an operator @@ -201,7 +201,7 @@ Parameters support_number - The index method's support procedure number for a + The index method's support function number for a function associated with the operator class. @@ -212,7 +212,7 @@ Parameters The name (optionally schema-qualified) of a function that is an - index method support procedure for the operator class. + index method support function for the operator class. diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml index 35f2f46985..c8263437ab 100644 --- a/doc/src/sgml/ref/create_operator.sgml +++ b/doc/src/sgml/ref/create_operator.sgml @@ -94,7 +94,7 @@ Description The function_name - procedure must have been previously defined using CREATE + function must have been previously defined using CREATE FUNCTION and must be defined to accept the correct number of arguments (either one or two) of the indicated types. @@ -264,11 +264,11 @@ Examples CREATE OPERATOR === ( LEFTARG = box, RIGHTARG = box, - PROCEDURE = area_equal_procedure, + PROCEDURE = area_equal_function, COMMUTATOR = ===, NEGATOR = !==, - RESTRICT = area_restriction_procedure, - JOIN = area_join_procedure, + RESTRICT = area_restriction_function, + JOIN = area_join_function, HASHES, MERGES ); diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml index 7b971ee6b4..b2dddafb46 100644 --- a/doc/src/sgml/ref/create_trigger.sgml +++ b/doc/src/sgml/ref/create_trigger.sgml @@ -348,7 +348,7 @@ Parameters - This specifies whether the trigger procedure should be fired + This specifies whether the trigger function should be fired once for every row affected by the trigger event, or just once per SQL statement. If neither is specified, FOR EACH STATEMENT is the default. Constraint triggers can only diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index 2dad215859..9db11d22fb 100644 --- a/doc/src/sgml/spi.sgml +++ b/doc/src/sgml/spi.sgml @@ -21,23 +21,16 @@ Server Programming Interface The available procedural languages provide various means to - execute SQL commands from procedures. Most of these facilities are + execute SQL commands from functions. Most of these facilities are based on SPI, so this documentation might be of use for users of those languages as well. - - To avoid misunderstanding we'll use the term function - when we speak of SPI interface functions and - procedure for a user-defined C-function that is - using SPI. - - Note that if a command invoked via SPI fails, then control will not be - returned to your procedure. Rather, the - transaction or subtransaction in which your procedure executes will be + returned to your C function. Rather, the + transaction or subtransaction in which your C function executes will be rolled back. (This might seem surprising given that the SPI functions mostly have documented error-return conventions. Those conventions only apply for errors detected within the SPI functions themselves, however.) @@ -73,7 +66,7 @@ Interface Functions SPI_connect SPI_connect_ext - connect a procedure to the SPI manager + connect a C function to the SPI manager @@ -91,9 +84,9 @@ Description SPI_connect opens a connection from a - procedure invocation to the SPI manager. You must call this + C function invocation to the SPI manager. You must call this function if you want to execute commands through SPI. Some utility - SPI functions can be called from unconnected procedures. + SPI functions can be called from unconnected C functions. @@ -159,7 +152,7 @@ Return Value SPI_finish - disconnect a procedure from the SPI manager + disconnect a C function from the SPI manager @@ -174,7 +167,7 @@ Description SPI_finish closes an existing connection to the SPI manager. You must call this function after completing the - SPI operations needed during your procedure's current invocation. + SPI operations needed during your C function's current invocation. You do not need to worry about making this happen, however, if you abort the transaction via elog(ERROR). In that case SPI will clean itself up automatically. @@ -198,7 +191,7 @@ Return Value SPI_ERROR_UNCONNECTED - if called from an unconnected procedure + if called from an unconnected C function @@ -238,7 +231,7 @@ Description - This function can only be called from a connected procedure. + This function can only be called from a connected C function. @@ -345,7 +338,7 @@ Description SPI_finish frees all SPITupleTables allocated during the current - procedure. You can free a particular result table earlier, if you + C function. You can free a particular result table earlier, if you are done with it, by calling SPI_freetuptable. @@ -539,7 +532,7 @@ Return Value SPI_ERROR_UNCONNECTED - if called from an unconnected procedure + if called from an unconnected C function @@ -555,7 +548,7 @@ Notes SPI_processed and SPI_tuptable (just the pointer, not the contents of the structure). Save these two global variables into local - procedure variables if you need to access the result table of + C function variables if you need to access the result table of SPI_execute or another query-execution function across later calls. @@ -835,7 +828,7 @@ Description The statement returned by SPI_prepare can be used - only in the current invocation of the procedure, since + only in the current invocation of the C function, since SPI_finish frees memory allocated for such a statement. But the statement can be saved for longer using the functions SPI_keepplan or SPI_saveplan. @@ -926,7 +919,7 @@ Notes - This function should only be called from a connected procedure. + This function should only be called from a connected C function. @@ -1702,9 +1695,9 @@ Description Using a cursor instead of executing the statement directly has two benefits. First, the result rows can be retrieved a few at a time, avoiding memory overrun for queries that return many rows. Second, - a portal can outlive the current procedure (it can, in fact, live + a portal can outlive the current C function (it can, in fact, live to the end of the current transaction). Returning the portal name - to the procedure's caller provides a way of returning a row set as + to the C function's caller provides a way of returning a row set as result. @@ -2534,7 +2527,7 @@ Description SPI_prepare) so that it will not be freed by SPI_finish nor by the transaction manager. This gives you the ability to reuse prepared statements in the subsequent - invocations of your procedure in the current session. + invocations of your C function in the current session. @@ -2604,7 +2597,7 @@ Description by SPI_finish nor by the transaction manager, and returns a pointer to the copied statement. This gives you the ability to reuse prepared statements in the subsequent invocations of - your procedure in the current session. + your C function in the current session. @@ -2644,7 +2637,7 @@ Return Value SPI_ERROR_UNCONNECTED - if called from an unconnected procedure + if called from an unconnected C function @@ -2757,7 +2750,7 @@ Return Value SPI_ERROR_UNCONNECTED - if called from an unconnected procedure + if called from an unconnected C function @@ -2862,7 +2855,7 @@ Return Value SPI_ERROR_UNCONNECTED - if called from an unconnected procedure + if called from an unconnected C function @@ -2977,7 +2970,7 @@ Return Value SPI_ERROR_UNCONNECTED - if called from an unconnected procedure + if called from an unconnected C function @@ -3011,7 +3004,7 @@ Interface Support Functions All functions described in this section can be used by both - connected and unconnected procedures. + connected and unconnected C functions. @@ -3655,37 +3648,37 @@ Memory Management makes it current. SPI_finish restores the previous current memory context and destroys the context created by SPI_connect. These actions ensure that - transient memory allocations made inside your procedure are - reclaimed at procedure exit, avoiding memory leakage. + transient memory allocations made inside your C function are + reclaimed at C function exit, avoiding memory leakage. - However, if your procedure needs to return an object in allocated + However, if your C function needs to return an object in allocated memory (such as a value of a pass-by-reference data type), you cannot allocate that memory using palloc, at least not while you are connected to SPI. If you try, the object will be deallocated by SPI_finish, and your - procedure will not work reliably. To solve this problem, use + C function will not work reliably. To solve this problem, use SPI_palloc to allocate memory for your return object. SPI_palloc allocates memory in the upper executor context, that is, the memory context that was current when SPI_connect was called, which is precisely the right context for a value returned from your - procedure. Several of the other utility procedures described in + C function. Several of the other utility functions described in this section also return objects created in the upper executor context. When SPI_connect is called, the private - context of the procedure, which is created by + context of the C function, which is created by SPI_connect, is made the current context. All allocations made by palloc, repalloc, or SPI utility functions (except as described in this section) are made in this context. When a - procedure disconnects from the SPI manager (via + C function disconnects from the SPI manager (via SPI_finish) the current context is restored to the upper executor context, and all allocations made in the - procedure memory context are freed and cannot be used any more. + C function memory context are freed and cannot be used any more. @@ -4263,12 +4256,12 @@ Description - This function is useful if a SPI procedure needs to execute + This function is useful if an SPI-using C function needs to execute multiple commands and does not want to keep the results of earlier commands around until it ends. Note that any unfreed row sets will be freed anyway at SPI_finish. Also, if a subtransaction is started and then aborted within execution - of a SPI procedure, SPI automatically frees any row sets created while + of an SPI-using C function, SPI automatically frees any row sets created while the subtransaction was running. @@ -4373,9 +4366,9 @@ Transaction Management is part of some SQL command will probably result in obscure internal errors or crashes. The interface functions presented here are primarily intended to be used by procedural language implementations to support transaction - management in procedures that are invoked by the CALL + management in SQL-level procedures that are invoked by the CALL command, taking the context of the CALL invocation into - account. SPI procedures implemented in C can implement the same logic, but + account. SPI-using procedures implemented in C can implement the same logic, but the details of that are beyond the scope of this documentation. @@ -4487,7 +4480,7 @@ Description SPI_start_transaction starts a new transaction. It can only be called after SPI_commit or SPI_rollback, as there is no transaction active at - that point. Normally, when an SPI procedure is called, there is already a + that point. Normally, when an SPI-using procedure is called, there is already a transaction active, so attempting to start another one before closing out the current one will result in an error. @@ -4566,7 +4559,7 @@ Examples This section contains a very simple example of SPI usage. The - procedure execq takes an SQL command as its + C function execq takes an SQL command as its first argument and a row count as its second, executes the command using SPI_exec and returns the number of rows that were processed by the command. You can find more complex diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml index 9f5c0c3fb2..f7713e8aba 100644 --- a/doc/src/sgml/xindex.sgml +++ b/doc/src/sgml/xindex.sgml @@ -50,7 +50,7 @@ Index Methods and Operator Classes WHERE-clause operators that can be used with an index (i.e., can be converted into an index-scan qualification). An operator class can also specify some support - procedures that are needed by the internal operations of the + function that are needed by the internal operations of the index method, but do not directly correspond to any WHERE-clause operator that can be used with the index. diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index 4b52210459..db765b4644 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -146,7 +146,7 @@ Installing Procedural Languages the language does not grant access to data that the user would not otherwise have. Trusted languages are designed for ordinary database users (those without superuser privilege) and allows them - to safely create functions and trigger + to safely create functions and procedures. Since PL functions are executed inside the database server, the TRUSTED flag should only be given for languages that do not allow access to database server @@ -206,7 +206,7 @@ Manual Installation of <application>PL/Perl</application> VALIDATOR plperl_validator; then defines that the previously declared functions - should be invoked for functions and trigger procedures where the + should be invoked for functions and procedures where the language attribute is plperl. diff --git a/src/backend/access/gin/ginvalidate.c b/src/backend/access/gin/ginvalidate.c index 1035be4463..1922260b75 100644 --- a/src/backend/access/gin/ginvalidate.c +++ b/src/backend/access/gin/ginvalidate.c @@ -90,7 +90,7 @@ ginvalidate(Oid opclassoid) { ereport(INFO, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("operator family \"%s\" of access method %s contains support procedure %s with different left and right input types", + errmsg("operator family \"%s\" of access method %s contains support function %s with different left and right input types", opfamilyname, "gin", format_procedure(procform->amproc)))); result = false; diff --git a/src/backend/access/gist/gistvalidate.c b/src/backend/access/gist/gistvalidate.c index dd87dad386..c300e52ca5 100644 --- a/src/backend/access/gist/gistvalidate.c +++ b/src/backend/access/gist/gistvalidate.c @@ -90,7 +90,7 @@ gistvalidate(Oid opclassoid) { ereport(INFO, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("operator family \"%s\" of access method %s contains support procedure %s with different left and right input types", + errmsg("operator family \"%s\" of access method %s contains support function %s with different left and right input types", opfamilyname, "gist", format_procedure(procform->amproc)))); result = false; diff --git a/src/backend/access/hash/hashutil.c b/src/backend/access/hash/hashutil.c index 4e485cc4b3..7c9b2cfc9e 100644 --- a/src/backend/access/hash/hashutil.c +++ b/src/backend/access/hash/hashutil.c @@ -73,10 +73,10 @@ _hash_checkqual(IndexScanDesc scan, IndexTuple itup) } /* - * _hash_datum2hashkey -- given a Datum, call the index's hash procedure + * _hash_datum2hashkey -- given a Datum, call the index's hash function * * The Datum is assumed to be of the index's column type, so we can use the - * "primary" hash procedure that's tracked for us by the generic index code. + * "primary" hash function that's tracked for us by the generic index code. */ uint32 _hash_datum2hashkey(Relation rel, Datum key) diff --git a/src/backend/access/hash/hashvalidate.c b/src/backend/access/hash/hashvalidate.c index 513a3bbc4c..aac148fd35 100644 --- a/src/backend/access/hash/hashvalidate.c +++ b/src/backend/access/hash/hashvalidate.c @@ -96,7 +96,7 @@ hashvalidate(Oid opclassoid) { ereport(INFO, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("operator family \"%s\" of access method %s contains support procedure %s with different left and right input types", + errmsg("operator family \"%s\" of access method %s contains support function %s with different left and right input types", opfamilyname, "hash", format_procedure(procform->amproc)))); result = false; @@ -182,7 +182,7 @@ hashvalidate(Oid opclassoid) result = false; } - /* There should be relevant hash procedures for each datatype */ + /* There should be relevant hash functions for each datatype */ if (!list_member_oid(hashabletypes, oprform->amoplefttype) || !list_member_oid(hashabletypes, oprform->amoprighttype)) { diff --git a/src/backend/access/spgist/spgvalidate.c b/src/backend/access/spgist/spgvalidate.c index 619c357115..c7acc7fc02 100644 --- a/src/backend/access/spgist/spgvalidate.c +++ b/src/backend/access/spgist/spgvalidate.c @@ -96,7 +96,7 @@ spgvalidate(Oid opclassoid) { ereport(INFO, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("operator family \"%s\" of access method %s contains support procedure %s with different left and right input types", + errmsg("operator family \"%s\" of access method %s contains support function %s with different left and right input types", opfamilyname, "spgist", format_procedure(procform->amproc)))); result = false; diff --git a/src/backend/commands/opclasscmds.c b/src/backend/commands/opclasscmds.c index e4b1369f19..3b5c90e3f4 100644 --- a/src/backend/commands/opclasscmds.c +++ b/src/backend/commands/opclasscmds.c @@ -517,7 +517,7 @@ DefineOpClass(CreateOpClassStmt *stmt) if (item->number <= 0 || item->number > maxProcNumber) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("invalid procedure number %d," + errmsg("invalid function number %d," " must be between 1 and %d", item->number, maxProcNumber))); funcOid = LookupFuncWithArgs(OBJECT_FUNCTION, item->name, false); @@ -891,7 +891,7 @@ AlterOpFamilyAdd(AlterOpFamilyStmt *stmt, Oid amoid, Oid opfamilyoid, if (item->number <= 0 || item->number > maxProcNumber) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("invalid procedure number %d," + errmsg("invalid function number %d," " must be between 1 and %d", item->number, maxProcNumber))); funcOid = LookupFuncWithArgs(OBJECT_FUNCTION, item->name, false); @@ -986,7 +986,7 @@ AlterOpFamilyDrop(AlterOpFamilyStmt *stmt, Oid amoid, Oid opfamilyoid, if (item->number <= 0 || item->number > maxProcNumber) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("invalid procedure number %d," + errmsg("invalid function number %d," " must be between 1 and %d", item->number, maxProcNumber))); processTypesSpec(item->class_args, &lefttype, &righttype); @@ -1141,11 +1141,11 @@ assignProcTypes(OpFamilyMember *member, Oid amoid, Oid typeoid) if (procform->pronargs != 2) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("btree comparison procedures must have two arguments"))); + errmsg("btree comparison functions must have two arguments"))); if (procform->prorettype != INT4OID) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("btree comparison procedures must return integer"))); + errmsg("btree comparison functions must return integer"))); /* * If lefttype/righttype isn't specified, use the proc's input @@ -1162,11 +1162,11 @@ assignProcTypes(OpFamilyMember *member, Oid amoid, Oid typeoid) procform->proargtypes.values[0] != INTERNALOID) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("btree sort support procedures must accept type \"internal\""))); + errmsg("btree sort support functions must accept type \"internal\""))); if (procform->prorettype != VOIDOID) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("btree sort support procedures must return void"))); + errmsg("btree sort support functions must return void"))); /* * Can't infer lefttype/righttype from proc, so use default rule @@ -1177,11 +1177,11 @@ assignProcTypes(OpFamilyMember *member, Oid amoid, Oid typeoid) if (procform->pronargs != 5) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("btree in_range procedures must have five arguments"))); + errmsg("btree in_range functions must have five arguments"))); if (procform->prorettype != BOOLOID) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("btree in_range procedures must return boolean"))); + errmsg("btree in_range functions must return boolean"))); /* * If lefttype/righttype isn't specified, use the proc's input @@ -1200,22 +1200,22 @@ assignProcTypes(OpFamilyMember *member, Oid amoid, Oid typeoid) if (procform->pronargs != 1) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("hash procedure 1 must have one argument"))); + errmsg("hash function 1 must have one argument"))); if (procform->prorettype != INT4OID) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("hash procedure 1 must return integer"))); + errmsg("hash function 1 must return integer"))); } else if (member->number == HASHEXTENDED_PROC) { if (procform->pronargs != 2) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("hash procedure 2 must have two arguments"))); + errmsg("hash function 2 must have two arguments"))); if (procform->prorettype != INT8OID) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("hash procedure 2 must return bigint"))); + errmsg("hash function 2 must return bigint"))); } /* @@ -1240,7 +1240,7 @@ assignProcTypes(OpFamilyMember *member, Oid amoid, Oid typeoid) if (!OidIsValid(member->lefttype) || !OidIsValid(member->righttype)) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("associated data types must be specified for index support procedure"))); + errmsg("associated data types must be specified for index support function"))); ReleaseSysCache(proctup); } @@ -1265,7 +1265,7 @@ addFamilyMember(List **list, OpFamilyMember *member, bool isProc) if (isProc) ereport(ERROR, (errcode(ERRCODE_INVALID_OBJECT_DEFINITION), - errmsg("procedure number %d for (%s,%s) appears more than once", + errmsg("function number %d for (%s,%s) appears more than once", member->number, format_type_be(member->lefttype), format_type_be(member->righttype)))); diff --git a/src/bin/psql/describe.c b/src/bin/psql/describe.c index 80d8338b96..4f7e93fe02 100644 --- a/src/bin/psql/describe.c +++ b/src/bin/psql/describe.c @@ -3907,7 +3907,7 @@ listEventTriggers(const char *pattern, bool verbose) gettext_noop("always"), gettext_noop("disabled"), gettext_noop("Enabled"), - gettext_noop("Procedure"), + gettext_noop("Function"), gettext_noop("Tags")); if (verbose) appendPQExpBuffer(&buf, diff --git a/src/include/access/hash.h b/src/include/access/hash.h index d6c306e969..543d802949 100644 --- a/src/include/access/hash.h +++ b/src/include/access/hash.h @@ -263,7 +263,7 @@ typedef struct HashMetaPageData * allocated */ uint32 hashm_firstfree; /* lowest-number free ovflpage (bit#) */ uint32 hashm_nmaps; /* number of bitmap pages */ - RegProcedure hashm_procid; /* hash procedure id from pg_proc */ + RegProcedure hashm_procid; /* hash function id from pg_proc */ uint32 hashm_spares[HASH_MAX_SPLITPOINTS]; /* spare pages before each * splitpoint */ BlockNumber hashm_mapp[HASH_MAX_BITMAPS]; /* blknos of ovfl bitmaps */ @@ -338,15 +338,15 @@ typedef HashMetaPageData *HashMetaPage; /* * When a new operator class is declared, we require that the user supply - * us with an amproc procedure for hashing a key of the new type, returning - * a 32-bit hash value. We call this the "standard" hash procedure. We - * also allow an optional "extended" hash procedure which accepts a salt and + * us with an amproc function for hashing a key of the new type, returning + * a 32-bit hash value. We call this the "standard" hash function. We + * also allow an optional "extended" hash function which accepts a salt and * returns a 64-bit hash value. This is highly recommended but, for reasons * of backward compatibility, optional. * * When the salt is 0, the low 32 bits of the value returned by the extended - * hash procedure should match the value that would have been returned by the - * standard hash procedure. + * hash function should match the value that would have been returned by the + * standard hash function. */ #define HASHSTANDARD_PROC 1 #define HASHEXTENDED_PROC 2 diff --git a/src/test/regress/expected/alter_generic.out b/src/test/regress/expected/alter_generic.out index f24a17f40e..6faa9d739d 100644 --- a/src/test/regress/expected/alter_generic.out +++ b/src/test/regress/expected/alter_generic.out @@ -354,9 +354,9 @@ ERROR: invalid operator number 0, must be between 1 and 5 ALTER OPERATOR FAMILY alt_opf4 USING btree ADD OPERATOR 1 < ; -- operator without argument types ERROR: operator argument types must be specified in ALTER OPERATOR FAMILY ALTER OPERATOR FAMILY alt_opf4 USING btree ADD FUNCTION 0 btint42cmp(int4, int2); -- function number should be between 1 and 5 -ERROR: invalid procedure number 0, must be between 1 and 3 +ERROR: invalid function number 0, must be between 1 and 3 ALTER OPERATOR FAMILY alt_opf4 USING btree ADD FUNCTION 6 btint42cmp(int4, int2); -- function number should be between 1 and 5 -ERROR: invalid procedure number 6, must be between 1 and 3 +ERROR: invalid function number 6, must be between 1 and 3 ALTER OPERATOR FAMILY alt_opf4 USING btree ADD STORAGE invalid_storage; -- Ensure STORAGE is not a part of ALTER OPERATOR FAMILY ERROR: STORAGE cannot be specified in ALTER OPERATOR FAMILY DROP OPERATOR FAMILY alt_opf4 USING btree; @@ -412,7 +412,7 @@ BEGIN TRANSACTION; CREATE OPERATOR FAMILY alt_opf12 USING btree; CREATE FUNCTION fn_opf12 (int4, int2) RETURNS BIGINT AS 'SELECT NULL::BIGINT;' LANGUAGE SQL; ALTER OPERATOR FAMILY alt_opf12 USING btree ADD FUNCTION 1 fn_opf12(int4, int2); -ERROR: btree comparison procedures must return integer +ERROR: btree comparison functions must return integer DROP OPERATOR FAMILY alt_opf12 USING btree; ERROR: current transaction is aborted, commands ignored until end of transaction block ROLLBACK; @@ -421,7 +421,7 @@ BEGIN TRANSACTION; CREATE OPERATOR FAMILY alt_opf13 USING hash; CREATE FUNCTION fn_opf13 (int4) RETURNS BIGINT AS 'SELECT NULL::BIGINT;' LANGUAGE SQL; ALTER OPERATOR FAMILY alt_opf13 USING hash ADD FUNCTION 1 fn_opf13(int4); -ERROR: hash procedure 1 must return integer +ERROR: hash function 1 must return integer DROP OPERATOR FAMILY alt_opf13 USING hash; ERROR: current transaction is aborted, commands ignored until end of transaction block ROLLBACK; @@ -430,7 +430,7 @@ BEGIN TRANSACTION; CREATE OPERATOR FAMILY alt_opf14 USING btree; CREATE FUNCTION fn_opf14 (int4) RETURNS BIGINT AS 'SELECT NULL::BIGINT;' LANGUAGE SQL; ALTER OPERATOR FAMILY alt_opf14 USING btree ADD FUNCTION 1 fn_opf14(int4); -ERROR: btree comparison procedures must have two arguments +ERROR: btree comparison functions must have two arguments DROP OPERATOR FAMILY alt_opf14 USING btree; ERROR: current transaction is aborted, commands ignored until end of transaction block ROLLBACK; @@ -439,7 +439,7 @@ BEGIN TRANSACTION; CREATE OPERATOR FAMILY alt_opf15 USING hash; CREATE FUNCTION fn_opf15 (int4, int2) RETURNS BIGINT AS 'SELECT NULL::BIGINT;' LANGUAGE SQL; ALTER OPERATOR FAMILY alt_opf15 USING hash ADD FUNCTION 1 fn_opf15(int4, int2); -ERROR: hash procedure 1 must have one argument +ERROR: hash function 1 must have one argument DROP OPERATOR FAMILY alt_opf15 USING hash; ERROR: current transaction is aborted, commands ignored until end of transaction block ROLLBACK; @@ -447,7 +447,7 @@ ROLLBACK; -- without defining left / right type in ALTER OPERATOR FAMILY ... ADD FUNCTION CREATE OPERATOR FAMILY alt_opf16 USING gist; ALTER OPERATOR FAMILY alt_opf16 USING gist ADD FUNCTION 1 btint42cmp(int4, int2); -ERROR: associated data types must be specified for index support procedure +ERROR: associated data types must be specified for index support function DROP OPERATOR FAMILY alt_opf16 USING gist; -- Should fail. duplicate operator number / function number in ALTER OPERATOR FAMILY ... ADD FUNCTION CREATE OPERATOR FAMILY alt_opf17 USING btree; @@ -464,7 +464,7 @@ ALTER OPERATOR FAMILY alt_opf17 USING btree ADD OPERATOR 5 > (int4, int2) , FUNCTION 1 btint42cmp(int4, int2) , FUNCTION 1 btint42cmp(int4, int2); -- procedure 1 appears twice in same statement -ERROR: procedure number 1 for (integer,smallint) appears more than once +ERROR: function number 1 for (integer,smallint) appears more than once ALTER OPERATOR FAMILY alt_opf17 USING btree ADD OPERATOR 1 < (int4, int2) , OPERATOR 2 <= (int4, int2) , diff --git a/src/test/regress/expected/create_operator.out b/src/test/regress/expected/create_operator.out index e35eb09250..fd8b37fff5 100644 --- a/src/test/regress/expected/create_operator.out +++ b/src/test/regress/expected/create_operator.out @@ -185,11 +185,11 @@ CREATE OPERATOR === ( "Leftarg" = box, "Rightarg" = box, - "Procedure" = area_equal_procedure, + "Procedure" = area_equal_function, "Commutator" = ===, "Negator" = !==, - "Restrict" = area_restriction_procedure, - "Join" = area_join_procedure, + "Restrict" = area_restriction_function, + "Join" = area_join_function, "Hashes", "Merges" ); diff --git a/src/test/regress/sql/create_operator.sql b/src/test/regress/sql/create_operator.sql index c71765f9be..9edf32b3f8 100644 --- a/src/test/regress/sql/create_operator.sql +++ b/src/test/regress/sql/create_operator.sql @@ -189,11 +189,11 @@ CREATE OPERATOR === ( "Leftarg" = box, "Rightarg" = box, - "Procedure" = area_equal_procedure, + "Procedure" = area_equal_function, "Commutator" = ===, "Negator" = !==, - "Restrict" = area_restriction_procedure, - "Join" = area_join_procedure, + "Restrict" = area_restriction_function, + "Join" = area_join_function, "Hashes", "Merges" ); -- 2.18.0