16.10 - The restartscandisk.pl Script - Teradata Database

Teradata Database Support Utilities

prodname
Teradata Database
vrm_release
16.10
created_date
June 2017
category
Configuration
featnum
B035-1180-161K

restartscandisk.pl is a Perl script supplied by Teradata to aid in using SCANDISK. When SCANDISK is started using the script, it is much easier to start a SCANDISK job, stop it, then restart it from the place at which it was stopped. Teradata recommends that you start SCANDISK using the script if you expect to restart it later.

The script is located in /usr/tdbms/bin.

To run SCANDISK from the script, execute the restartscandisk.pl Perl script at the command line or at the Teradata Command Prompt. The following requirements apply when running the script.

  • restartscandisk.pl must be executed in the Teradata environment. Therefore, to run the script on a Linux system, make sure you have executed tdatcmd first to set up the Teradata environment. For more information, see Starting the Utilities.
  • restartscandisk.pl must be run on the Control Node (the node running with the lowest node ID number). To determine the Control Node, type cnscim -host at the command line.
  • restartscandisk.pl configures Filer to use decimal numeric values as input and output. Therefore, you must enter decimal values when specifying numeric input to the script. For more information, see RADIX.
The syntax for restartscandisk.pl is shown below.


Syntax Element Description
scandisk command The SCANDISK command and options you want to run.
You must enter decimal values when specifying numeric input for SCANDISK options, such as tid or ridspec.
input filename The file to be used as input to the script. This file should contain the output from the previously executed SCANDISK job.
If you specify SCANDISK with the TABLE option, restartscandisk.pl will use the TABLE option values and ignore this input file. In this case, SCANDISK can only be manually restarted.
tid [ridspec] Specifies the subtable and optionally, the row where SCANDISK should restart the scan job. For more information on tid formatting, see Specifying a Subtable Identifier (tid). For more information on RowIDs and ridspecformatting, see Rows and Row Ranges. The online help lists the ridspec option as rowspec.
You must enter decimal values for tid and ridspec. If you specify SCANDISK with the TABLE option, restartscandisk.pl will use the TABLE option values and ignore these tidand ridspec values. In this case, SCANDISK can only be manually restarted.
output filename The file which will store the SCANDISK output.
You must specify an absolute path to this file. If you use a relative path, the SCANDISK output from the application log may be redirected to a different location than the output from restartscandisk.pl.

If you do not specify an output file or input file, the script will use the standard output file (stdout). If you specify SCANDISK with the TABLE option, restartscandisk.pl will use the TABLE option values and ignore this output file. In this case, SCANDISK can only be manually restarted.

ENA Specifies to start Filer with locking enabled, which means that Filer will observe the file system locking protocols used to avoid hang or deadlock situations. This is the default.
DIS Specifies to start Filer with locking disabled. This option starts Filer with the -l locking option, which means that Filer will not observe the file system locking protocols used to avoid hang or deadlock situations.

For information about the -l locking option, see Standard Filer Startup Syntax.

time interval The time in seconds specifying the interval at which the INQUIRE request is sent to display SCANDISK progress. The default is 600 seconds.
The minimum time interval allowed is 600 seconds. If you enter a time interval that is less than 600 seconds, restartscandisk.pl uses the default value of 600 seconds.
AMP number Specifies the vproc number to be used with the Filer SCOPE command. The SCANDISK command will be sent only to the specified vproc. For more information, see SCOPE (or VPROC).

Usage Notes for the restartscandisk script

If the file system data structures were fixed to repair a problem, and the location (tid and rowid) where the previous SCANDISK halted is beyond the location where the file system fix occurred, Teradata recommends that you restart the SCANDISK job from the beginning instead of restarting the scan at the location where it last halted.

Entering options to the restartscandisk script

There are many ways to enter options to the restartscandisk script. The following describes how you can specify a SCANDISK command and options for the script to run.

IF you specify... THEN...
a SCANDISK command the script starts Filer to run the SCANDISK command and any options specified.
an input file, but no SCANDISK command the script starts Filer to run the SCANDISK command and options used in the previous scan job as specified in the input file.
an input file, and a SCANDISK command the script will check if the submitted SCANDISK command is the same as the command previously executed. If the submitted command and options are different from the previous command, the script will display a warning and ask for confirmation to run the new command.
no input file and no SCANDISK command the script starts Filer to run SCANDISK with no options.

The following describes how you can specify the location where SCANDISK should restart a previous scan job.

IF you specify... THEN...
an input file SCANDISK restarts from the subtable specified by the tidand rowid from the last INQUIRE command in the input file.
the -t option with a tid and optional ridspec SCANDISK restarts from the subtable specified by tid and ridspec.
the TABLE option with the SCANDISK command the script ignores any input file, -t option, or output file you specify, and runs SCANDISK with the values of the TABLE option. To restart SCANDISK later, you must manually capture the last tid and rowid from the application window.
no input file, no -t option, and no TABLE option SCANDISK restarts the job from the beginning.
You can specify either the -i option or the -t option, but not both options together.

The following describes how you can specify where the SCANDISK output will be saved or sent.

IF you specify... THEN...
an output file the output of SCANDISK is saved to this file.
an input file, but no output file the script reuses the input file to save the output of the SCANDISK job. The new output is appended to the end of the file.
no input file and no output file the output of SCANDISK is sent to the standard output file (stdout).

The output from the restartscandisk script includes output from the INQUIRE command, which contains the lowest tid and rowid scanned among the AMPS involved. This INQUIRE output can be used to identify the location where a scan ended. When this output is saved to a file, you can use the file as input to the restartscandisk script, by using the -i option. The script restarts SCANDISK at the location specified by the tid and rowid from the last INQUIRE command in the file.

If the database restarts while executing this script, the output file may not capture the complete application window output. Therefore, the output file may not contain a restart point for SCANDISK, or the restart point may be incorrect.

If the exact restart point is not important, you can still use this output file as input to restart SCANDISK. However, if the exact restart point is important, then it is better to manually capture the last tid and rowidfrom the application window, and use these values to restart SCANDISK. You can pass the tid and rowid to the restartscandisk script using the -t option, which restarts SCANDISK at the specified location.

If you do not use the -o or -i options to save the SCANDISK output to a file, then you must manually capture the tid and rowid from the last INQUIRE command in the application window if you want to restart SCANDISK later by using the -t option. It is recommended that you use the -o or -i option to ease restartability.

If you manually capture the SCANDISK output in the application window to a separate log file, this file cannot be used as an input file to the restartscandisk script because the application window log does not contain the output required by the restartscandisk script.

Aborting the restartscandisk script

You can use one of the methods listed below to interrupt the restartscandisk script and abort the running SCANDISK job. For specific key sequences used to generate the signals specified, see the documentation for signal generation for your Operating System platform.

  • Send a SIGINT signal (CTRL+C)
  • Send a SIGQUIT signal (CTRL+\, on Linux systems)
  • Enter the ABORT command in the application window where Filer is running

In the first 2 cases, when the restartscandisk script receives the signal to abort, it displays the current percentage of SCANDISK completion and requests confirmation to abort the scan job. Upon confirmation, the script gracefully aborts the running SCANDISK. You can restart the aborted SCANDISK job later by using the -i or -t option.

If you enter the ABORT command in the application window where Filer is running, the script will gracefully abort the running SCANDISK job without asking for confirmation. You can restart the aborted SCANDISK job later by using the -i or -t option.

If you abort SCANDISK when it is scanning free CIs or the WAL log, and you restart the scan job, SCANDISK will restart the scan from the beginning of the particular stage where it was aborted (either scanning free CIs or the WAL log).

restartscandisk errors and warnings

The restartscandisk script displays various error messages when it encounters problems. It also displays warnings and informational messages to assist the user.

The following table lists possible error messages returned by the restartscandisk script, with explanations and suggested remedies for each.

Error Message Explanation Remedy
The AMP number specified with the -s option is invalid. The user specified an invalid AMP number with the -s option. Specify a valid AMP number with the -s option.
The AMP number specified with the -s option is invalid. The AMP number is greater than the total number of AMPs in the system. The user specified an AMP number that is greater than the number of AMPs in the system. Specify an AMP number that is less than the number of AMPs in the system.
Cannot get the application window number. The Teradata Database restarted just after the “start filer” command was submitted. Check the PDE state, and submit the script when the PDE is running.
Cannot get the total number of AMPs in the system to validate the specified AMP number. The script tried to verify that the AMP number specified with the -s option is not greater than the number of AMPs in the system; however, it failed to get the total number of AMPs present in the system. Verify that the DBS is running and that you have the correct permissions to run the vprocmanager command.
cnscim -s failed. The Teradata Database was restarted or stopped after the script submitted the “start filer” command. If the database was restarted, wait until the PDE is running, then resubmit the script. If the PDE is not running, start the PDE, then resubmit the script.
ENA and DIS are options to the restartscandisk script and cannot be used as output file names. Please specify another file name for the output file. The user specified ENA or DIS as the output file, which is not allowed since ENA and DIS are options to the script. Specify a file name other than ENA or DIS for the output file.
Error encountered when submitting the SCANDISK command to Filer. Possible SCANDISK syntax error. The script submitted the SCANDISK command to Filer, and it received an error from SCANDISK. The submitted SCANDISK command may be invalid. Make sure the SCANDISK command you submit to the script is valid. If you are not specifying a SCANDISK command to the script, and the error persists, report the problem to the Teradata Support Center.
Failed to open filename. The script failed to open a needed file. The file may be a temporary file used by the script, the specified input or output file, or cnstool. Verify that the required file has the correct permissions.
Filer cannot be started because all of the interactive partitions are busy. All of the application windows are currently used for other purposes, and the script cannot find an available application window where Filer can be started. Run the script at a later time when an application window is free.
Input file is invalid. Please specify a correct input file to restart SCANDISK. The user specified an invalid input file which does not contain SCANDISK output. Specify an input file which contains output from a previous SCANDISK job. If multiple output files exist, submit the latest output file as input for restarting SCANDISK.
Output file is invalid. Please check the output file name. The user specified an invalid output file. Check the path of the output file for correctness. Do not specify a directory name as the output file name.
PDE must be running to start the restartscandisk script. The PDE is not running, and the script cannot be started if the PDE is down. Start the PDE, and submit the script when the PDE is running.
The restartscandisk script cannot be run on nodes other than the Control Node. The user did not run the restartscandisk script on the Control Node. The script can be run only on the Control Node. Run the script on the Control Node, the node running with the lowest Node ID number. To determine the Control Node, run cnscim -host from the command line.
SCANDISK command submitted with incomplete options. Please resubmit the SCANDISK command with all the required options. The user submitted a SCANDISK command with incomplete options, and Filer prompted for additional input. Make sure the SCANDISK command you submit to the script includes all the required options.
The specified input file does not exist. The user specified an input file that does not exist. Verify the path and file name of the input file, and make sure that the file exists.
Syntax Error: Invalid syntax or options were entered for the restartscandisk script. The user specified invalid options to the script. Check the syntax and options entered for the script, and verify that they are correct.
Syntax Error: Please specify a time interval with the -tm option. The user specified the -tm option, but did not specify a time interval. Specify a time interval in seconds with the -tm option. The time interval must be 600 seconds or more.
Syntax Error: Please specify an AMP number with the -s option. The user specified the -s option, but did not specify an AMP number. Specify an AMP number with the -s option. The AMP number will be used with the Filer SCOPE command to limit the SCANDISK scope.
Syntax Error: Please specify an input file with the -i option. The user specified the -i option, but did not specify an input file. Specify an input file with the -i option.
Syntax Error: Please specify an output file with the -o option. The user specified the -o option, but did not specify an output file. Specify an output file with the -o option.
Syntax Error: Please specify table options tid[ridspec] with the -t option. The user specified the -t option, but did not specify a tid or ridspec. Specify a tid and optional ridspec with the -t option.
Syntax Error: -t option cannot be used together with the -i option. The user specified both -i and -t options to the script. Specify either the -i option or the -t option. You cannot specify both options together.
Syntax Error: The ENA and DIS options cannot be specified together. The user specified both the ENA and the DIS options. Specify either the ENA or the DIS option. You cannot specify both options together.
The time interval specified is invalid. Please enter a number which represents the number of seconds as the time interval. The minimum time interval allowed is 600. The user specified the -tm option, but the time interval specified is not a number. Specify a number which represents the number of seconds as the time interval. The time interval must be 600 seconds or more.
The vprocmanager command failed. The script executed the vprocmanager command to get the number of AMPs in the system, and the command failed. Verify that the DBS is running and that you have the correct permissions to run the vprocmanager command.

The following table lists warnings and informational messages that may be displayed by the restartscandisk script.

Message Description
Already received abort request, please wait... The script already received the previous interrupt signal and is waiting until Filer is in Read mode before it can process the abort request.
Based on the input file, SCANDISK will restart scanning at the FREECIS stage. Based on information from the specified input file, the restart point will be FREECIS. That is, SCANDISK will start scanning the free cylinders. This implies that all of the subtables in the system were scanned already.
Based on the input file, SCANDISK will restart scanning at the WAL log stage. Based on information from the specified input file, the restart point will be the WAL log. That is, SCANDISK will start scanning the WAL log buffers. This implies that all of the subtables and free cylinders in the system were scanned already.
Did not find any status to display. If the script is interrupted, the status of the SCANDISK job is normally displayed before aborting. In this case, the script has not submitted any INQUIRE commands to Filer before the interrupt. Therefore, no status information is available. The script will ask the user for confirmation before aborting.
Filer is not in Read mode, please wait... The script received an interrupt signal when Filer was not in Read mode and could not accept the ABORT command. The script will wait until Filer is in Read mode, then it will ask the user for confirmation to abort after displaying the latest SCANDISK status.
Filer is starting, please wait... The script has started Filer and is waiting for Filer to reach Read mode.
Initializing... The script is submitting initial commands to Filer and has not submitted the SCANDISK command yet.
The input file does not contain output from an INQUIRE command for the last SCANDISK job. Do you want to check previous SCANDISK jobs for status? The specified input file does not contain INQUIRE command output from the latest execution of SCANDISK. The script asks the user for confirmation to check previous SCANDISK jobs to get a restart point. If the input file has output from more than one SCANDISK job, then the latest SCANDISK job containing INQUIRE command output will be used to determine the restart point.
The input file does not contain output from an INQUIRE command. SCANDISK will start the scan from the beginning. The specified input file does not contain any INQUIRE command output. Therefore, the script cannot determine a restart point. The script will ask the user for confirmation to start the scan from the beginning.
Processing the abort request, please wait… The script received an interrupt signal and is processing the abort request.
Restart point found in the input file. Restart subtable is tid and RowID is rowid. SCANDISK will restart from this location. The script found the restart point based on the last INQUIRE command output in the input file. SCANDISK will restart at the specified tid and rowid.
The restartscandisk script received an interrupt signal during the Initializing stage. The script received an interrupt signal before it could send the SCANDISK command to Filer.
SCANDISK completed the scan job in the previous run. Starting this scan job from the beginning. The input file indicates that the previous SCANDISK job was completed. Therefore, the script will start a new SCANDISK job from the beginning.
The specified INQUIRE time interval is less than 600 seconds. Setting the time interval to the default value of 600 seconds. The user specified the -tm option with a time interval that is less than the minimum time interval allowed, which is 600 seconds. The script will set the time interval to the default value of 600 seconds.
Unable to get the current status. If the script is interrupted, the status of the SCANDISK job is normally displayed before aborting. However, since the user did not specify the -o or -i option, the script cannot get the SCANDISK status.

It is recommended that the -o or -i option be used so that SCANDISK output will be saved to a file, which allows the script to display status information before aborting.

User specified an input file, but no output file. Using the file filename as both input and output file. The user specified an input file, but did not specify an output file. The script will reuse the input file as the output file.
User specified an input file, but no SCANDISK command. Using previous SCANDISK command: scandisk_cmd The user specified an input file, but did not specify a SCANDISK command. The script will submit the SCANDISK command used to run the previous scan job as specified in the input file.
WARNING: No output file was specified. To restart this SCANDISK job later, capture the last tid and rowid from the application window. The user did not specify an output file. In order to restart this SCANDISK job later, the user must manually capture the tid and rowid from the latest INQUIRE output in the application window. It is recommended that the user specify an output file to ease restartability.
WARNING: Previous SCANDISK command and current SCANDISK command are different. The user is restarting a previous SCANDISK job and has specified both an input file and a SCANDISK command. The submitted SCANDISK command is different from the command used to run the previous scan job. In this case, the user will be asked for confirmation to run the submitted command.
WARNING: Specifying the INQUIRE option with the SCANDISK command may result in more INQUIRE outputs than expected. Use the -tm option to display INQUIRE output instead. The user specified the INQUIRE option with the SCANDISK command. Since the restartscandisk script already sends periodic INQUIRE commands by default, this will result in more INQUIRE commands sent than expected. The user should use the -tm option to display INQUIRE output instead of using the INQUIRE option with the SCANDISK command.
WARNING: You have specified the TABLE option. The -i, -t, and -o options will be ignored. To restart this SCANDISK job later, capture the last tid and rowid from the application window. The user specified the TABLE option with the SCANDISK command. Therefore, SCANDISK will run with the values of the TABLE option and ignore the -i, -t, and -o options. The SCANDISK output will not be saved to a file. The user must manually capture the last tid and rowid from the application window to restart SCANDISK later.