Do you need to reduce the amount of informational messages that BTEQ produces? Then try out the enhanced version of the BTEQ 14.10 command "SET ECHOREQ".
This article explains how to use ECHOREQ command's ERRORONLY option to instruct BTEQ to only echo back SQL requests that fail.
Why add a new ERRORONLY option to the ECHOREQ command?
Consider a large BTEQ script that contains several hundred SQL statements and that the corresponding BTEQ output needs to be retained. The script can use the ECHOREQ OFF setting to reduce the standard output size. This inhibits all the SQL requests from being echoed, but at the same time, it becomes nearly impossible to identify a failed request.
This scenario served as the primary reason to enhance BTEQ's ECHOREQ command with a new ERRORONLY option, so that the need of suppressing echoed requests is met, while allowing SQL statements to be displayed only when they fail.
After reading this article you will know how to control BTEQ's echoing of user input in order to reduce the size of standard output, while also being able to echo SQL statements selectively based on their success or failure. You will also see how to use BTEQ's SHOW command.
User input can contain BTEQ commands and SQL requests. Whenever user input is received by BTEQ (either in interactive or batch mode), BTEQ by default displays an exact copy of the input to the standard output stream. The only exceptions to this are for protected mode input, such as the LOGON command's password and LOGDATA command's data values.
The "echo required" function (ECHOREQ command) can be used to control BTEQ's echoing of the user input. The ECHOREQ command accepts three values: ON, OFF, and ERRORONLY. If no option is specified, BTEQ assumes ON.
Note that, the ECHOREQ command is not related to the QUIET command, which is used to suppress a different category of informational messages, altogether.
The behavior of all the options will be demonstrated throughout this article using a static BTEQ script named echoreq.bteq as shown below:
/* Display the current ECHOREQ setting */ .SHOW CONTROLS ECHOREQ /* Perform LOGON */ .LOGON nodeid/dbc,dbc /* Successful SQL statement */ SELECT date; /* Erroneous SQL statement */ SELECT junk; /* Successful BTEQ command */ .SET WIDTH 72 /* Erroneous BTEQ command */ .SET WIDTH XX /* Display last SQL sent to database */ .SHOW /* Exit BTEQ */ .QUIT
Note: SHOW is a new BTEQ command, which can be used to display the last SQL request that was sent to the database. For more details on using the SHOW command, please refer to the Basic Teradata Query Reference Manual.
Using ECHOREQ ON
By default, ECHOREQ is set to ON, in which case, BTEQ will echo all BTEQ commands and SQL requests to standard output.
Using either of the following variants will set ECHOREQ to ON:
.SET ECHOREQ ON
.SET ECHOREQ
Below is BTEQ's output with ECHOREQ initially set to ON.
Executed as: bteq .SET ECHOREQ ON < echoreq.bteq
+---------+---------+---------+---------+---------+---------+---------+---- .SET ECHOREQ ON +---------+---------+---------+---------+---------+---------+---------+---- /* Display the current ECHOREQ setting */ .SHOW CONTROLS ECHOREQ [SET] ECHOREQ = ON +---------+---------+---------+---------+---------+---------+---------+---- .LOGON nodeid/dbc, *** Logon successfully completed. *** Teradata Database Release is 14.10.00.00 *** Teradata Database Version is 14.10.00.00 *** Transaction Semantics are BTET. *** Session Character Set Name is 'ASCII'. *** Total elapsed time was 7 seconds. +---------+---------+---------+---------+---------+---------+---------+---- /* Successful SQL statement */ SELECT date; *** Query completed. One row found. One column returned. *** Total elapsed time was 1 second. Date -------- 12/03/14 +---------+---------+---------+---------+---------+---------+---------+---- /* Erroneous SQL statement */ SELECT junk; *** Failure 3822 Cannot resolve column 'junk'. Specify table or view. Statement# 1, Info =0 *** Total elapsed time was 1 second. +---------+---------+---------+---------+---------+---------+---------+---- /* Successful BTEQ command */ .SET WIDTH 72 +---------+---------+---------+---------+---------+---------+---------+- /* Erroneous BTEQ command */ .SET WIDTH XX *** Syntax Error : Width command must be followed by a number. +---------+---------+---------+---------+---------+---------+---------+- /* Display last SQL sent to database */ .SHOW SELECT junk; +---------+---------+---------+---------+---------+---------+---------+- .QUIT *** You are now logged off from the DBC. *** Exiting BTEQ... *** RC (return code) = 8
Using ECHOREQ OFF
You can use "SET ECHOREQ OFF" if you do not want any BTEQ command or SQL request to be echoed by BTEQ. This setting can be useful when running large BTEQ scripts where the standard output file size is a concern and one wants to reduce BTEQ's informational output.
Note: The following are not affected by the ECHOREQ setting, and will be echoed regardless:
- A stand-alone BTEQ comment (which is not embedded in a BTEQ command or SQL request)
- The LOGON command (of course, the password is never echoed)
Below is BTEQ's output with ECHOREQ initially set to OFF.
Executed as: bteq .SET ECHOREQ OFF < echoreq.bteq
+---------+---------+---------+---------+---------+---------+---------+---- .SET ECHOREQ OFF +---------+---------+---------+---------+---------+---------+---------+---- /* Display the current ECHOREQ setting */ [SET] ECHOREQ = OFF +---------+---------+---------+---------+---------+---------+---------+---- .LOGON nodeid/dbc, *** Logon successfully completed. *** Teradata Database Release is 14.10.00.00 *** Teradata Database Version is 14.10.00.00 *** Transaction Semantics are BTET. *** Session Character Set Name is 'ASCII'. *** Total elapsed time was 6 seconds. +---------+---------+---------+---------+---------+---------+---------+---- /* Successful SQL statement */ *** Query completed. One row found. One column returned. *** Total elapsed time was 1 second. Date -------- 12/03/14 +---------+---------+---------+---------+---------+---------+---------+---- /* Erroneous SQL statement */ *** Failure 3822 Cannot resolve column 'junk'. Specify table or view. Statement# 1, Info =0 *** Total elapsed time was 1 second. +---------+---------+---------+---------+---------+---------+---------+---- /* Successful BTEQ command */ +---------+---------+---------+---------+---------+---------+---------+- /* Erroneous BTEQ command */ *** Syntax Error : Width command must be followed by a number. +---------+---------+---------+---------+---------+---------+---------+- /* Display last SQL sent to database */ SELECT junk; +---------+---------+---------+---------+---------+---------+---------+- *** You are now logged off from the DBC. *** Exiting BTEQ... *** RC (return code) = 8
Using ECHOREQ ERRORONLY
You saw above that when using ECHOREQ OFF, no user input is echoed back. What if you wanted BTEQ to echo out the failed SQL request?
You can use "SET ECHOREQ ERRORONLY", instructing BTEQ to echo back only the failed SQL requests. The echoed SQL request is printed just after the database Failure/Error message is displayed. The ERRORONLY option is available starting with BTEQ 14.10.
With this new ERRORONLY option, all BTEQ commands will still be echoed. However, this behavior of BTEQ commands equating to ON for ERRORONLY is subject to change. In a future release, it is expected that BTEQ commands will behave the same way as failed SQL requests, in that, successful BTEQ commands will not be echoed, but failed BTEQ commands will be.
Note: When ERRORONLY is in effect and the SQL request is issued with a REPEAT factor greater than 1, it may be the case that more than one error response is generated. So for the duration of the REPEAT, only one instance of the request text will be echoed.
Below is BTEQ's output with ECHOREQ initially set to ERRORONLY.
Executed as: bteq .SET ECHOREQ ERRORONLY < echoreq.bteq
+---------+---------+---------+---------+---------+---------+---------+---- .SET ECHOREQ ERRORONLY +---------+---------+---------+---------+---------+---------+---------+---- /* Display the current ECHOREQ setting */ .SHOW CONTROLS ECHOREQ [SET] ECHOREQ = ERRORONLY +---------+---------+---------+---------+---------+---------+---------+---- .LOGON nodeid/dbc, *** Logon successfully completed. *** Teradata Database Release is 14.10.00.00 *** Teradata Database Version is 14.10.00.00 *** Transaction Semantics are BTET. *** Session Character Set Name is 'ASCII'. *** Total elapsed time was 7 seconds. +---------+---------+---------+---------+---------+---------+---------+---- /* Successful SQL statement */ *** Query completed. One row found. One column returned. *** Total elapsed time was 1 second. Date -------- 12/03/14 +---------+---------+---------+---------+---------+---------+---------+---- /* Erroneous SQL statement */ *** Failure 3822 Cannot resolve column 'junk'. Specify table or view. Statement# 1, Info =0 *** Request Text: SELECT junk; *** Total elapsed time was 1 second. +---------+---------+---------+---------+---------+---------+---------+---- /* Successful BTEQ command */ .SET WIDTH 72 +---------+---------+---------+---------+---------+---------+---------+- /* Erroneous BTEQ command */ .SET WIDTH XX *** Syntax Error : Width command must be followed by a number. +---------+---------+---------+---------+---------+---------+---------+- /* Display last SQL sent to database */ .SHOW SELECT junk; +---------+---------+---------+---------+---------+---------+---------+- .QUIT *** You are now logged off from the DBC. *** Exiting BTEQ... *** RC (return code) = 8
Notice the BTEQ message " *** Request Text:" followed by the failed SQL request, which gets displayed after the database Failure message.
What if you do not have a BTEQ version that supports ECHOREQ ERRORONLY?
In order to get a similar ERRORONLY-like benefit from an older version of BTEQ, try using the ECHOREQ OFF setting and modify your BTEQ script to use the IF-THEN command to issue a SHOW command after every SQL request.
For example, the script echoreq.bteq can be modified (named echoreq_erroronly_workaround.bteq) as below:
/* Display the current ECHOREQ setting */ .SHOW CONTROLS ECHOREQ /* Perform LOGON */ .LOGON nodeid/dbc,dbc /* Successful SQL statement */ SELECT date; /* Check if the SQL statement failed */ .IF ERRORCODE <> 0 THEN .RUN FILE = display_last_SQL.run /* Erroneous SQL statement */ SELECT junk; /* Check if the SQL statement failed */ .IF ERRORCODE <> 0 THEN .RUN FILE = display_last_SQL.run /* Successful BTEQ command */ .SET WIDTH 72 /* Erroneous BTEQ command */ .SET WIDTH XX /* Display last SQL sent to database */ .SHOW /* Exit BTEQ */ .QUIT
where, display_last_SQL.run file's content is shown below:
.SET ECHOREQ ON .SHOW .SET ECHOREQ OFF
Prior to the BTEQ 14.10 release, the SHOW command does not display anything if ECHOREQ is set to OFF, which is why an ON-OFF pair is needed in the above RUN file.
Below is BTEQ's output with ECHOREQ initially set to OFF and using the workaround to display the failed SQL requests.
Executed as: bteq .SET ECHOREQ OFF < echoreq_erroronly_workaround.bteq
+---------+---------+---------+---------+---------+---------+---------+---- .SET ECHOREQ OFF +---------+---------+---------+---------+---------+---------+---------+---- /* Display the current ECHOREQ setting */ [SET] ECHOREQ = OFF +---------+---------+---------+---------+---------+---------+---------+---- /* Perform LOGON */ .LOGON nodeid/dbc, *** Logon successfully completed. *** Teradata Database Release is 14.10.00.00 *** Teradata Database Version is 14.10.00.00 *** Transaction Semantics are BTET. *** Session Character Set Name is 'ASCII'. *** Total elapsed time was 7 seconds. +---------+---------+---------+---------+---------+---------+---------+---- /* Successful SQL statement */ *** Query completed. One row found. One column returned. *** Total elapsed time was 1 second. Date -------- 12/03/14 +---------+---------+---------+---------+---------+---------+---------+---- /* Check if the SQL statement failed */ +---------+---------+---------+---------+---------+---------+---------+---- /* Erroneous SQL statement */ *** Failure 3822 Cannot resolve column 'junk'. Specify table or view. Statement# 1, Info =0 *** Total elapsed time was 1 second. +---------+---------+---------+---------+---------+---------+---------+---- /* Check if the SQL statement failed */ +---------+---------+---------+---------+---------+---------+---------+---- +---------+---------+---------+---------+---------+---------+---------+---- .SHOW SELECT junk; +---------+---------+---------+---------+---------+---------+---------+---- .SET ECHOREQ OFF +---------+---------+---------+---------+---------+---------+---------+---- *** Warning: EOF on INPUT stream. +---------+---------+---------+---------+---------+---------+---------+---- /* Successful BTEQ command */ +---------+---------+---------+---------+---------+---------+---------+- /* Erroneous BTEQ command */ *** Syntax Error : Width command must be followed by a number. +---------+---------+---------+---------+---------+---------+---------+- /* Display last SQL sent to database */ +---------+---------+---------+---------+---------+---------+---------+- /* Exit BTEQ */ *** You are now logged off from the DBC. *** Exiting BTEQ... *** RC (return code) = 8
Concluding remarks
Hopefully, reading through this article has given you a better understanding of how to control the echoing of requests to the output file, using the ECHOREQ command. There are other BTEQ commands that can also further reduce BTEQ's output size, such as SET QUIET and SET TIMEMSG. For more details, refer to the Basic Teradata Query Reference Manual (Publication B035-2414) from http://www.info.teradata.com.