OS - Basic Teradata Query

Basic Teradata Query Reference

Basic Teradata Query
Release Number
October 2018
English (United States)
Last Update
Product Category
Teradata Tools and Utilities


Submits an operating system command to a workstation-attached system.

For mainframe BTEQ, see BTEQ's TSO command.


where the following is true:

A string that represents a valid operating system command.

Usage Notes

The specified operating system command must be valid for execution on the operating system in use. To use more than one operating system command, send the BTEQ OS command repeatedly, or send the operating system command that enables control to be given to another program. This is accomplished differently in each operating system.

BTEQ will store the return code from the last submitted system call. Use the SYSTEMRETURNCODE status keyword to reference the value. When the OS command is used to invoke another BTEQ process instance, the return value from that secondary process is transferred back as the calling process's SYSTEMRETURNCODE value.

The SYSTEMRETURNCODE keyword can be used in IF command conditions for all flavors of BTEQ but is only be valid for use in an EXIT command when using Windows BTEQ.

The OS command can be used to look at the complete contents of a closed export file. Using the OS command to look at the contents of an open export file might not display the last few records in the file, though they transfer to the file when the file is closed. This is because the last few records are still in the buffer, and have not yet been written to disk. (See EXPORT for more information about closing an export file.)

An OS command can be used in a Teradata SQL macro, but only for one specific command at a time. (That is, do not use it to drop into the command processor or shell).

The command is issued to the operating system in the UTF-8 encoding for Workstation BTEQ, whenever the I/O encoding is UTF8 or UTF16. The use of multibyte characters in the OS command is not supported and might produce unpredictable results.

Example 1 – List Directory Files

Use one of the following OS commands to display the files in a directory:

  • For a UNIX system, specify:

    .OS ls

  • For Windows, specify:

    .OS DIR

Example 2 – UNIX

For a UNIX system, use the UNIX command EXECUTE SHELL to exit from BTEQ and press and hold the keys Control and D to return to BTEQ.

For example:

.OS exec s
$ pg myfile.one
$ cp oldfile newfile
$ cd draft
$ <cntrl>/<d>

Example 3 – Windows

For Windows, use the DOS command, COMMAND (secondary command processor) to exit from BTEQ and the EXIT command to return to BTEQ.

.OS command
C> type b:myfile.one
C> edlin b:myfile.one
C> dir a:
C> exit

Example 4 – OS instigated by a macro

In a Teradata SQL macro, the OS command is written as follows:

ECHO '.OS ls';

Example 5 – Change Window Title

When multiple instances of Windows BTEQ are active, the .OS command with the DOS command TITLE can be used to customize the console windows’ title text so they can be differentiated. The following example changes the default title to mach1.

.OS TITLE mach1

Example 6 – Testing OS Results

The following IF...THEN... command can be used to test whether a system call submitted through the OS command resulted in a return code value greater than 0: