Register statements to be invoked when a procedure or script ends.

Arguments:

{statements}

The list of statements to be executed at the end of the current procedure or script, or {} to delete a previously registered list of commands.

Example:

The following example procedure makes changes to the tracking offsets, that may need to be undone when the procedure ends or is aborted. Specifically, it shows part of a hypothetical procedure that attempts to find the azimuth and elevation offsets at which the received power from the current source is maximized. If this succedes, then it should keep the optimized offsets, but if it fails, or is aborted, then it should reinstate the offsets that were in place before the procedure was invoked. To arrange that the original offsets be reinstated if the procedure fails or is aborted, it uses the at_end command to register a set of commands that must be run when the procedure ends or is aborted.

  command point_az_el() {

    # Keep a record of the initial tracking offsets.

    TrackingOffsets old = $tracking_offsets()

    # The following variable says whether to reinstate the above offsets
    # when the point_az_el procedure ends.

    Boolean restore = true

    # Arrange to reinstate the above tracking offsets at the end of
    # this procedure.

    at_end {
      if($restore) {
        print "Restoring the original tracking offsets:"
        offset az=$old.az, el=$old.el
      }
    }

    # Find the az,el offsets that maximize the received power.
    ....

    # If a peak is found, arrange to keep the new offsets.

    if($peak_found) {
      restore = false
    }
  }

Context:

The at_end command can be used in two places.

1. When used within the top-level statements of a schedule, it registers commands to be run when the script ends normally or is aborted.
2. When used within the top-level statements of a user-defined command, it registers commands to be run when the command ends normally, when the script is aborted, or when the command is aborted by a higher level catch statement.

Thus the at_end command allows user defined commands and scripts to clean up after themselves, regardless of whether or not they finish normally.

The placement of a given at_end command within a given user-defined command or script is important. There can be multiple at_end commands within the body of a given user-defined command or the top-level statements of a schedule, each of which replaces the commands that were registered by the previous one. This allows one to change or remove the cleanup commands as the script advances.

In general, at_end commands should be placed after any commands or variable assignments that record the state that the at_end statements are to restore, and before any statements that change that state. Note that the statements that an at_end command registers can only access variables that are declared before it in the parent command or schedule.