pditvtrc (Periodically acquire the HiRDB status)

Function

The pditvtrc command executes a specified command at a specified interval (in seconds) and then outputs the termination status to the standard output or standard error output file.

Executor

Any user (with or without privileges). The execution permissions required by the command that is executed by the pditvtrc command apply.

Format

pditvtrc interval-in-seconds output-file-prefix file-size retained-generations-count

         command [arg1 [arg2] ...]

Command arguments

Specifies the interval in seconds at which the specified command is to be executed. The specified value must be an integer of 0 or greater (if 0 is specified, the command will be executed consecutively).

If the specified command does not terminate within the specified interval, counting the seconds stops. When the specified command terminates, the pditvtrc command executes the next command and starts counting the seconds again. Even when the specified command terminates within the specified interval, an error may still occur with respect to the specified interval.

Specifies the prefix of the output file.

The actual output file name is output-file-prefixXX (00 [Figure] XX < number of retained generations). If output-file-prefixXX already exists when the pditvtrc command starts, XX begins at YY + 1, where the most recent output file is output-file-prefixYY. However, if YY + 1 is equal to or greater than the number of retained generations and there is no output file with output-file-prefixXX, then XX begins at output-file-prefix00.

After executing the specified command, if the output file exceeds the specified file size, the pditvtrc command swaps output files and outputs the results of the command's execution to the output file named output-file-prefixXX, with XX incremented. When the value of XX reaches the specified number of retained generations, the value of XX is reset to 00 in wrap-around fashion. If this happens, the previous output files will be overwritten.

Each time an output file exceeds the specified file size, the pditvtrc command swaps the output files to retain a maximum of the specified number of generations of output files.

Specifies the maximum output file size in megabytes.

After executing the specified command, if the current output file named output-file-prefixXX exceeds this file size, the pditvtrc command swaps the current output files.

Specifies the number of output file generations to be retained.

The number of generations applies to the actual output file names. The number of output file generations is unlimited, but a maximum of the specified number of the newest output files are retained because the prefix of the output file can be 00 [Figure] XX < number of retained generations.

Specifies the command to be executed and its arguments.

The syntax for the command line is the same as for normal commands. You can specify not only HiRDB operation commands but also any other commands.

Rules

  1. The pditvtrc command can be executed at any time, whether or not HiRDB is active. For the command that is specified within the pditvtrc command, the rules for that command are applicable.
  2. Execute the pditvtrc command from a desired server machine. For the command that is specified within the pditvtrc command, the rules for that command are applicable.
  3. Note the available space at the output target because the pditvtrc command may output more execution results than the file size [Figure] number of retained generations. If the HiRDB directory ($PDDIR) and OS directory (such as /tmp and /var) become full, HiRDB and the OS may not function correctly. For this reason, we recommend that you output the execution results to a different disk than one that contains HiRDB and OS directories.
  4. The pditvtrc command creates a locked directory named output-file-prefix.lck to avoid multiple concurrent outputs to the same output file prefix. This lock is released when the pditvstop command is terminated or when the termination is caused by the SIGTERM or SIGQUIT signal. However, forcible termination using the SIGKILL signal may retain the lock. If the locked directory is retained, use the ps command to make sure that no corresponding process is running, and then delete the locked directory by executing rm -r output-file-prefix.lck.
  5. When executed, the pditvtrc command starts the background process that functions at the specified interval and then terminates the pditvtrc command itself. This background process keeps running even if the terminal used to execute the pditvtrc command is terminated. To terminate the process, you must execute pditvstop output-file-prefix. If you cannot execute the pditvstop command for some reason, such as that output-file-prefix.lck or output-file-prefix.pid has been deleted, use the ps command to check the PID and then use kill PID(kill -TERM PID). This background process treats the SIGQUIT signal in the same manner as the SIGTERM signal.
  6. If you execute the pdstart command while the pditvtrc command is executing, HiRDB startup may fail. If this happens, re-execute the pdstart command. Also, When you execute a HiRDB command with the pditvtrc command, execute the pditvstop command before terminating HiRDB.
  7. If the specified command terminates with a return code other than 0 for more than nine times in a row, the pditvtrc command terminates.

Notes

  1. The following shows the pditvtrc command's return codes:
    0: Normal termination
    1: A pditvtrc command with the same output file is already running or the command is unable to create an output file or the locked directory output-file-prefix.lck.

Output format

YYYY/MM/DD HH:MM:SS   ...............................................1
Standard output + standard error output of "command  arg1  arg2 ..."..2
RC=command return-code   ................................................3
       :

Explanation

  1. Execution date and time of the specified command
  2. Standard output and standard error output of "command arg1 arg2 ..."
  3. Return code of "command arg1 arg2 ..."

For details about 2 and 3, see the applicable manual (for HiRDB commands, see the description of the applicable command in this manual).

Examples

Example 1:
This example executes the pditvtrc command for various commands:

pditvtrc 60 /outputdir/rpc 10 2 pdls -d rpc -a
pditvtrc 60 /outputdir/trn 10 2 pdls -d trn
pditvtrc 60 /outputdir/prc 10 2 pdls -d prc
pditvtrc 60 /outputdir/lck 10 2 pdls -d lck
pditvtrc 60 /outputdir/buf 10 2 pdbufls

Explanation
Every 60 seconds, each pditvtrc command adds the execution result of its command to a separate output file. The maximum size of each output file is 10 megabytes and the number of retained generations is 2 for each output file.

Example 2:

This example executes one pditvtrc command to execute multiple commands:

pditvtrc 60 /outputdir/trc 20 6 trcscript

Contents of trcscript

#!/bin/posix/sh
SCRIPT_RC=0

# date '+%Y/%m/%d %H:%M:%S' pditvtrc displays the first command start time
pdls -d rpc -a
RC=$?
echo "RC=$?"
if [[ $RC != 0 ]] ; then SCRIPT_RC=1; fi

#date '+%Y/%m/%d %H:%M:%S' pdls -d trn displays its own execution time
pdls -d trn
RC=$?
echo "RC=$?"
if [[ $RC != 0 ]] ; then SCRIPT_RC=1; fi

#date '+%Y/%m/%d %H:%M:%S' pdls -d prc displays its own execution time
pdls -d prc
RC=$?
echo "RC=$?"
if [[ $RC != 0 ]] ; then SCRIPT_RC=1; fi

date '+%Y/%m/%d %H:%M:%S'
pdls -d lck
RC=$?
echo "RC=$?"
if [[ $RC != 0 ]] ; then SCRIPT_RC=1; fi

#date '+%Y/%m/%d %H:%M:%S' pdls -d prc displays its own execution time
pdbufls
RC=$?
echo "RC=$?"
if [[ $RC != 0 ]] ; then SCRIPT_RC=1; fi

exit $SCRIPT_RC

Explanation
This example executes the shell script trcscript every 60 seconds and outputs the execution results to the output file /outputdir/trc. The size of the output file is 20 megabytes and the number of retained generations is 6.