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

Sun Enterprise 10000 SSP 3.5 Reference Manual

cancelcmdsync(1M)

NAME

cancelcmdsync, cmdsync, 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 nonzero 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