15.00 - Chapter 6 CNS Run (cnsrun) - Teradata Database

Teradata Database Utilities

Product
Teradata Database
Release Number
15.00
Content Type
Configuration
Publication ID
B035-1102-015K
Language
English (United States)
Last Update
2018-09-25

The CNS Run utility, cnsrun, provides the ability to run a database utility from a script. It is suitable for running other utilities as pre-scheduled tasks or cron jobs.

Scenarios Runs From

CNS Run is intended to be run from operating system scripts, which can be run either from the command line or by daemons, such as cron.

For general information on starting the utilities from different interfaces, see Appendix B: “Starting the Utilities”

Scenarios Syntax

Use the following syntax:

 

Syntax Element

Description

-utility uname

Specifies the utility program to start.

-join uname

Specifies the name of an already running database utility.

-screen number

Specifies the screen number where a utility that is to be joined is already running. -screen must be used only with the -join option.

-file file_name

Specifies a file that contains input commands to send to the utility program.

-commands clist

Specifies the commands to send to the utility.

Each command must be enclosed within braces { }, and there must be one or more spaces between commands.

Note: If there is more than one command, enclose clist in double quotation marks.

-machine host_name

the host name associated with the Control Node for the TPA instance on which to run the utility program. The Control Node is the node running with the lowest Node ID number. The Control Node can move between TPA restarts. To determine the name of the Control Node, type  cnscim -host at the command prompt.

The default is localhost, which only works on SMP systems or when the program is actually running on the Control Node of an MPP system.

-force

that this utility is to be started even if the database software is not running.

-ok

that this utility is to be started even if logons are disabled.

In the absence of this option and the -force option, the utility is not started if logons are not enabled.

-multi

Permits more than one instance of the specified utility program to run simultaneously. Without the -multi option, cnsrun fails to start a utility if an instance of the utility is already running.

-nostop

Considers the operation successful even if the utility continues to run after all input is exhausted.

-prompt string

When running a database utility that accepts input after a text prompt, this switch is required to enable cnsrun to know when to send input.

String is a regular expression that allows cnsrun to recognize an input prompt from the utility.

-tool cns_tool_path

the full path to the cnstool program.

-debug n

Specifies the level of debug output that will be shown on screen.

A value of 0 (the default) shows no output if the utility runs successfully.

A value of 1 shows the utility program output and its state changes.

Other larger values of n produce additional debugging output. All output, including error messages, appears in STDOUT, the standard console output.

-output

that the utility output should be directed to STDOUT, the standard console output.

Note: The -output option is effective only when the -debug option is set to zero.

-log logfile

Produces a log of the utility run to the specified file.

-query

to display the names of the utilities currently running in each of the screens, after which cnsrun exits.

-help

Displays information on how to use cnsrun.

Scenarios Usage Notes

This program runs the utility uname with the input provided by either the -file or -commands option. The command is run by this program connecting to CNS on the node specified by the -machine option and starting the utility from the Supervisor subwindow of Database Window (DBW). When the utility issues a read, the commands specified are sent to it until all of the commands are exhausted or until the program exits.

To use this command, the user running cnsrun must have access permission to run a DBW session on the machine. To set up a user to have CNS access, use the GET PERMISSIONS, GRANT, and REVOKE commands in DBW. For more information about the DBW Supervisor Commands, see Chapter 10: “Database Window (xdbw).”

An error occurs if all of the interactive partitions are in use.

By default, this command produces no output unless an error occurs.

When running the Ferret utility with CNS Run, you must specify the Ferret command

enable script

as the first command. This enables the script mode of Ferret, which allows scripts that run Ferret to run uninterrupted. For more information, see Chapter 13: “Ferret Utility (ferret).”

Regular Expressions for the -prompt option

Some database utilities prompt for input or commands. While those commands can be included in the command list, cnsrun needs to be able to recognize the utility prompts to know when to send the response. The -prompt option accepts regular expressions that represent utility program text prompts, to which cnsrun will respond by sending the next command in the command list.

The regular expression syntax follows that used in the Tool Command Language (Tcl), a subset of which is described below. For the full documentation on Tcl regular expressions, see http://wiki.tcl.tk/396.

 

Regular Expression Character

Meaning

.

A period in the regular expression matches any literal character at that position in the prompt string, to ensure that the prompt matches the regular expression.

?

A question mark indicates the preceding character or group of characters in the regular expression can occur zero or one time at that position in the prompt string, to ensure that the prompt matches the regular expression.

Example: “fee?d” would match either “feed” or “fed” in the prompt string.

*

An asterisk indicates the preceding character or group of characters in the regular expression can occur zero or more times in succession at that position in the prompt string, to ensure that the prompt matches the regular expression. This means that the pattern may or may not occur at that position in the prompt string.

Example: “fe*d” would match fed, feed, feeed, and would match fd, at the corresponding position in the prompt string.

+

A plus character indicates the preceding character or group of characters in the regular expression can occur one or more times in succession at that position in the prompt string, to ensure that the prompt matches the regular expression.

Example: “fe+d” would match fed, feed, feeed, but would not match fd.

^

A circumflex character in the regular expression indicates the character or characters that follow the circumflex in the regular expression must occur at the beginning of the prompt string, to ensure that the prompt matches the regular expression.

Example: “^E” requires that the prompt string begin with an upper case E so that it matches the regular expression.

$

A dollar sign character in the regular expression indicates the character or characters that precede the dollar sign in the regular expression must occur at the end of the prompt string, to ensure that the prompt matches the regular expression.

Example “:$” requires that the prompt string ends with a colon so that it matches the regular expression.

()

Parentheses enclose a group of characters that is to be treated as a single regular expression entity.

Example: “(ABC)+” would match one or more successive occurrences of ABC at the corresponding position in a prompt string.

[]

Square braces enclose a subset of characters to match.

Example: “[0-9]” would match any single digit at the corresponding position in a prompt string.

Example  

To run the utility updatespace with the input:

update space for all databases;
quit

connecting to CNS on an SMP system, use the following command:

cnsrun -utility updatespace -commands "{update space for all databases;} {quit}"