16.20 - getPhase(int[] phase) - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL External Routine Programming

Product
Advanced SQL Engine
Teradata Database
Release Number
16.20
Release Date
April 2020
Content Type
Programming Reference
Publication ID
B035-1147-162K
Language
English (United States)

This method returns the current mode of the table function and also returns the current phase value in the first element of the phase argument.

Argument

The processing phases that getPhase() can return depend on the mode.

Mode Phase Meaning
Tbl.TBL_MODE_VARY Tbl.TBL_PRE_INIT The table UDF is being called for the first time for all the rows that it will be called for. The input arguments to the UDF contain the first set of data.

During this phase, the UDF has an opportunity to establish overall global context, but should not build any result row.

The UDF continues to the TBL_INIT phase.

Tbl.TBL_INIT The input arguments to the UDF contain the first set of data.

During this phase, the UDF should not build any result row.

The UDF continues to the TBL_BUILD phase.

Tbl.TBL_BUILD The UDF should fill out the result arguments to build a row.

The UDF remains in the TBL_BUILD phase until it throws an SQLException with the sqlstate set to "02000" to indicate no data, whereupon it continues to the TBL_FINI phase.

Tbl.TBL_FINI If there is more variable input data, the UDF returns to the TBL_INIT phase. Otherwise, the UDF continues to the TBL_END phase.
Tbl.TBL_END The table function is not called again after this phase.
Tbl.TBL_ABORT The table UDF is being aborted. A UDF can be invoked at any time with this phase, which is only entered when a copy of the table UDF invokes Tbl.abort(). It is not entered when the function is aborted for an external reason, such as a user abort.
Tbl.TBL_MODE_CONST Tbl.TBL_PRE_INIT The UDF may decide whether it should be the controlling copy of all table functions running on other AMP vprocs.

If the function wants to provide control context to all other copies of the table function, the function must call Tbl.control().

If the function does not want to be the controlling copy of the table function, or if the function is designed without the need for a controlling function, the function can simply return and do nothing during this phase.

All copies of the table function must complete this phase before any copy continues to the TBL_INIT phase.

Tbl.TBL_INIT Any copy of the UDF that does not want to participate further must call Tbl.optOut(). After the function returns, it is not called again.

All copies of the table UDF must complete this phase before any copy continues to the TBL_BUILD phase.

Tbl.TBL_BUILD The table UDF should fill out the result arguments to build a row.

The function remains in the Tbl.TBL_BUILD phase until it throws an SQLException, setting the sqlstate to "02000" to indicate no data, whereupon it continues to the Tbl.TBL_END phase.

Tbl.TBL_END The table function is not called again after it returns from this phase.

The controlling copy of the table function, if one exists, is called with this phase after all other copies of the table function have completed this phase, which allows the controlling function to do any final cleanup or notification to the external world.

Tbl.TBL_ABORT The table UDF is being aborted and should perform cleanup, if necessary. A function can be called at any time with this phase, which is only entered when one of copies of the table function calls Tbl.abort(). It is not entered when the function is aborted for an external reason, such as a user abort.

Return Value

Value Meaning
Tbl.TBL_MODE_CONST The table UDF arguments are constant.
Tbl.TBL_MODE_VARY The table UDF arguments vary and are based on the rows produced by the correlated table specification in the SELECT statement.

The table UDF might only be called on specific AMP vprocs in this mode.