cmdsync(1M) (Sun Enterprise 10000 SSP 3.5 Reference Manual)

Sun Enterprise 10000 SSP 3.5 Reference Manual

cmdsync(1M)

NAME

cmdsync, cancelcmdsync, initcmdsync, savecmdsync- command synchronization commands

SYNOPSIS

cancelcmdsync

cmdsync_descriptor

initcmdsync

script_name

savecmdsync

-M

identifier

cmdsync_descriptor

DESCRIPTION

The command synchronization commands work together to control the recovery of user-defined scripts interrupted by an SSP failover. You insert the following commands in user-defined scripts to enable command synchronization:

initcmdsync creates a command synchronization descriptor that identifies the script to be recovered.

This descriptor is placed on a command synchronization list that identifies the scripts and commands to be restarted on the new main SSP after a failover.
savecmdsync adds a marker that identifies a location in the script from which processing can be resumed after a failover.
cancelcmdsync removes a command synchronization descriptor from the command synchronization list. This ensures that the script is run only once and not after subsequent failovers.

Be sure that all exit paths of a script have a cancelcmdsync sequence to remove the descriptor from the command synchronization list. If you do not remove the descriptor and a failover occurs, the script will be rerun on the new main SSP.

Note -

Both an initcmdsync and a cancelcmdsync sequence must be contained within a script to enable command synchronization. The use of the savecmdsync command is optional and is used only to mark specific points in a script from which processing can be resumed.

OPTIONS

The following options are supported:

cmdsync_descriptor: Specifies the command synchronization descriptor that identifies the user-defined script. This descriptor is the standard output value returned by the initcmdsync command.
-M identifier: Marks a location in the script from which the script can be resumed after a failover. The identifier must be a positive integer.
parameters: Specifies the options or parameters associated with the user-defined script. These parameters are stored on the spare SSP and are used to restart the specified script after a failover.
script_name: Identifies the name of the user-defined script to be synchronized.

EXTENDED DESCRIPTION

The command synchronization commands are inserted at certain logical points within a user-defined script.

For instance, a Korn shell script might be structured as follows:

  # MAIN CODE STARTS HERE
  # Be sure to use a cleanup procedure to handle any interrupts.       
  # Use the cancelcmdsync to remove the script from the command 
  # synchronization list. Otherwise, the command will get restarted 
  # on the new main SSP.
  #
  clean_up () {
       cancelcmdsync  $desc
       exit 
  }
     
  # Declare the clean_up function to capture system signals
  # and cleanup.  
  trap "clean_up" INT HUP TERM QUIT PWR URG
  goto_label=1
  # Process the arguments, capturing the -M marker point if provided 
  #
  for arg in $*; do
      case $arg in
           -M )
      goto_label=$arg;; 
      .
      .
      .
      esac
  done
  # Place this script and all its parameters in the command synchronization
  # list, which indicates the commands to be restarted after an SSP failover. 
  #
  # NOTE: The script must be executable by user ssp and reside in the same
  # directory on both the main and the spare SSP. If the command is not
  # part of the defined PATH for user ssp, the absolute filename must be
  # passed with the initcmdsync command.
  #
  initcmdsync script_name parameters      
  # The marker point is stored in the goto_label variable.
  # Keep executing this script until all cases have been processed or an
  # error is detected.  
  #
  while (( $goto_label !=  0 )) ; do 

       #
       # Each case should represent a synchronization point in the script. 
       #
       case $goto_label in

            #
            # Step 1: Do something
            #
            1 )
                 do_something
                 .
                 .
                 .
                         
                 # Execute the savecmdsync command with the script's
                 # descriptor and a unique marker to save the position.
                 # If a failover occurs here, the commands
                 # represented in the next goto_label (2) will be
                 # resumed.
                 #

                 savecmdsync -M $(( $goto_label + 1 )) $desc
                 goto_label=$(( $goto_label + 1 ))
                 ;;

            #
            # Step 2: Do more things
            #
            2 )
                 do_more_things
                 .
                 .
                 .
                 savecmdsync -M $(( $goto_label + 1 )) $desc
                 goto_label=$(( $goto_label + 1 ))
                 ;;
            #
            # Step 3: Finish the last step and set the goto_label to 0
            # so that the script ends.
            3 )
                 finish_last_step
                 .
                 .
                 .
                 goto_label=0
                 ;;
        esac
  done

  # END OF MAIN CODE
  # Remember to execute cancelcmdsync to remove the script from the
  # command synchronization list. Otherwise, the command will be restarted
  # after the failover.
  #
  cancelcmdsync $desc

EXIT STATUS

The following exit values are returned:

0: Successful completion.
>0: An error occurred.

Note -

The standard output for initcmdsync contains the command synchronization descriptor. Also, when failover is disabled (after a failover or in a single SSP environment), scripts that contain synchronization commands generate error messages to the platform log file and return non-zero exit codes. These messages can be ignored.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Architecture	All
Availability	SUNWuessp
Stability	Evolving
MT-Level	Safe