def do_create_profile(options):
    '''Run System Configuration Interactive Tool in order to create
    System Configuration profile'''
    try:
        _prepare_engine(options)

        # insert sysconfig CLI options into DOC
        doc_options = SysConfigOptions(options)
        doc = InstallEngine.get_instance().doc.persistent
        doc.insert_children(doc_options)

        # Navigate user through the set of configuration screens. Generate
        # resulting profile only if user went through the complete set of
        # sysconfig screens.
        if _show_screens(options):
            # First set the umask read-only by user (root).
            # Then let the ManifestWriter generate resulting SC profile.
            # Finally, reset umask to the original value.
            orig_umask = os.umask(0377)
            eng = InstallEngine.get_instance()
            (status, failed_cps) = eng.execute_checkpoints()
            os.umask(orig_umask)

            # If ManifestWriter failed to create SC profile, inform user
            # and exit with error.
            if status != InstallEngine.EXEC_SUCCESS:
                print _("Failed to generate SC profile.")
                _exit(options.logname, errcode=1)
            else:
                print _("SC profile successfully generated.")

        _exit(options.logname, errcode=0)
    except SystemExit:
        raise
    except:
        if LOGGER is None:
            # Error occurred before logging is setup; no place to
            # dump the traceback
            raise
        LOGGER.exception(_("An unhandled exception occurred."))
        exc_type, exc_value = sys.exc_info()[:2]

        try:
            doc = InstallEngine.get_instance().doc.persistent
            sc_prof = doc.get_first_child(name="sysconfig")
            LOGGER.error("Sysconfig profile:\n%s", sc_prof)
        except:
            # Ignore any errors to avoid masking the original exception
            pass

        print _("An unhandled exception occurred.")
        if exc_value:
            print '\t%s: "%s"' % (exc_type.__name__, exc_value)
        else:
            print "\t%s" % exc_type.__name__
        print _("Full traceback data is in the log")
        _exit(options.logname, errcode=1)

    def report_status(self):
        '''Update the install status. Also checks the quit_event to see
        if the installation should be aborted.

        '''
        try:
            processing_quit = False
            while self.prog_handler.server_up:
                if not processing_quit:
                    ready_to_read = select([self.prog_handler.engine_skt],
                                           [], [], 0.25)[0]
                    if len(ready_to_read) > 0:
                        percent, msg = self.prog_handler.parseProgressMsg(\
                            ready_to_read[0])
                        LOGGER.debug("message = %s", msg)
                        LOGGER.debug("percent = %s", percent)
                        self.update_status_func(float(percent), msg)

                # check whether F9 is pressed
                input_key = self.screen.main_win.getch()
                if input_key == curses.KEY_F9:
                    LOGGER.info("User selected Quit")
                    really_quit = self.screen.confirm_quit()
                    if really_quit:
                        LOGGER.info("User confirmed Quit")
                        engine = InstallEngine.get_instance()
                        engine.cancel_checkpoints()
                        processing_quit = True
        except Exception, e:
            LOGGER.exception("progressServer Error")

    def reset(self, dummy=None):
        '''Reset ui_obj to value found from Target Discovery.
        Meaningful only for editable DiskWindows

        '''
        if not self.editable:
            return
        doc = InstallEngine.get_instance().doc

        # "reset" the desired target
        reset_obj = None
        if isinstance(self.ui_obj, UIDisk):
            reset_obj = (self.tc.reset_layout(disk=self.ui_obj.doc_obj))[0]
        else:
            # reset the partition by removing the modified Partition, and
            # resetting it with the partition found during target discovery.

            discovered_obj = self.ui_obj.discovered_doc_obj

            desired_disk = get_desired_target_disk(doc)
            desired_part = get_solaris_partition(doc)

            desired_disk.delete_partition(desired_part)
            part_copy = deepcopy(discovered_obj)
            desired_disk.insert_children(part_copy)

            # get the updated reference
            reset_obj = get_solaris_partition(doc)

        dump_doc("After doing reset")

        self.set_disk_info(disk_info=reset_obj)
        self.activate_solaris_data()

def register_checkpoint(sc_profile=SC_FILE, xslt=XSLT_FILE):
    '''Registers the GENERATE_SC_PROFILE_CHKPOINT checkpoint with the engine.
    Also adds config_profile to InstallEngine.doc.persistent'''
    eng = InstallEngine.get_instance()

    sc_kwargs = {'xslt_file': xslt}
    sc_args = [sc_profile]
    eng.register_checkpoint(GENERATE_SC_PROFILE_CHKPOINT,
                            "solaris_install/manifest/writer",
                            "ManifestWriter", args=sc_args, kwargs=sc_kwargs)

    # Add profile location to the ApplySysconfig checkpoint's data dict.
    # Try to find the ApplySysconfig data dict from the DOC in case it
    # already exists.
    as_doc_dict = None
    as_doc_dict = eng.doc.volatile.get_first_child(name=APPLY_SYSCONFIG_DICT)
    if as_doc_dict is None:
        # Initialize new dictionary in DOC
        as_dict = {APPLY_SYSCONFIG_PROFILE_KEY: sc_profile}
        as_doc_dict = DataObjectDict(APPLY_SYSCONFIG_DICT, as_dict)
        eng.doc.volatile.insert_children(as_doc_dict)
    else:
        # Add to existing dictionary in DOC
        as_doc_dict.data_dict[APPLY_SYSCONFIG_PROFILE_KEY] = sc_profile

    eng.doc.persistent.insert_children([ConfigProfile()])

def execute_checkpoint(log=DEFAULTLOG, resume_checkpoint=None,
                       pause_checkpoint=None):
    """ wrapper to the execute_checkpoints (and friends) methods
    """
    eng = InstallEngine.get_instance()

    if resume_checkpoint is not None:
        (status, failed_cps) = eng.resume_execute_checkpoints(
            start_from=resume_checkpoint, pause_before=pause_checkpoint,
            dry_run=False, callback=None)
    else:
        (status, failed_cps) = eng.execute_checkpoints(start_from=None,
            pause_before=pause_checkpoint, dry_run=False, callback=None)

    if status != InstallEngine.EXEC_SUCCESS:
        for failed_cp in failed_cps:
            for err in errsvc.get_errors_by_mod_id(failed_cp):
                DC_LOGGER.info("'%s' checkpoint failed" % failed_cp)
                DC_LOGGER.info(err.error_data[ES_DATA_EXCEPTION])
                # if a CalledProcessError is raised during execution of a
                # checkpoint, make sure the strerror() is also logged to give
                # the user additional feedback
                if isinstance(err.error_data[ES_DATA_EXCEPTION],
                              CalledProcessError):
                    DC_LOGGER.debug(os.strerror(
                        err.error_data[ES_DATA_EXCEPTION].returncode))
        raise RuntimeError("Please check the log for additional error "
                           "messages. \nLog: " + log)

def update_doc_paths(build_data_mp):
    """ function to replace placeholder strings in the DOC with actual paths

    build_data_mp - mountpoint of the build_data dataset
    """
    eng = InstallEngine.get_instance()
    doc = eng.data_object_cache

    # find all of the Software nodes
    software_list = doc.volatile.get_descendants(class_type=Software)

    # iterate over each node, looking for Dir and/or Image nodes
    for software_node in software_list:
        for dir_node in software_node.get_descendants(class_type=Dir):
            path = dir_node.dir_path
            path = path.replace("{BUILD_DATA}", build_data_mp)
            path = path.replace("{BOOT_ARCHIVE}",
               os.path.join(build_data_mp, "boot_archive"))
            path = path.replace("{PKG_IMAGE_PATH}",
               os.path.join(build_data_mp, "pkg_image"))
            dir_node.dir_path = path
        for image_node in software_node.get_descendants(class_type=Image):
            path = image_node.img_root
            path = path.replace("{BUILD_DATA}", build_data_mp)
            path = path.replace("{BOOT_ARCHIVE}",
               os.path.join(build_data_mp, "boot_archive"))
            path = path.replace("{PKG_IMAGE_PATH}",
               os.path.join(build_data_mp, "pkg_image"))
            image_node.img_root = path

    def execute(self, dry_run=False):
        '''
            Abstract method defined in AbstractCheckpoint class.

            Loads the specified Manifest and does the requested validation.
            Imports resulting data into DOC.

            Parameters:
            - the dry_run keyword paramater, specified in AbstractCheckpoint,
              is ignored in this method.

            Returns:
            - Nothing
              On success, this method returns; on error it raises an exception.

            Raises:
            - ManifestError is raised if unable to fetch DOC reference or
              if an error occurs in parse().
        '''

        self.logger.debug("ManifestParser.execute(dry_run=%s) called", dry_run)

        engine = InstallEngine.get_instance()

        doc = engine.data_object_cache
        if doc is None:
            raise ManifestError("Cannot get DOC reference from InstallEngine")

        self.parse(doc=doc)

    def test_mp_engine_load_good(self):
        '''
            test_mp_engine_load_good - test manifest_parser succeeds parsing manifest stored in DOC
        '''
        # Store manifest in DOC
        doc = InstallEngine.get_instance().data_object_cache
        if doc is not None:
            mp_data = doc.volatile.get_first_child(name=MANIFEST_PARSER_DATA)
            if mp_data is None:
                mp_data = ManifestParserData(MANIFEST_PARSER_DATA)
                doc.volatile.insert_children(mp_data)
            mp_data.manifest = common.MANIFEST_DC

        my_args = None
        my_kwargs = {}
        my_kwargs["validate_from_docinfo"] = False

        self.engine.register_checkpoint("manifest_parser",
            "solaris_install/manifest/parser",
            "ManifestParser",
            args=my_args,
            kwargs=my_kwargs)

        status = self.engine.execute_checkpoints()[0]

        self.assertEqual(status, InstallEngine.EXEC_SUCCESS,
            "ManifestParser checkpoint should have succeeded")

    def parse_doc(self):
        """ class method for parsing data object cache (DOC) objects for use by
        the checkpoint.
        """
        self.doc = InstallEngine.get_instance().data_object_cache

        try:
            self.dc_dict = self.doc.volatile.get_children(name=DC_LABEL,
                class_type=DataObjectDict)[0].data_dict
            self.ba_build = self.dc_dict["ba_build"]
            self.pkg_img_path = self.dc_dict["pkg_img_path"]
            # path to the save directory
            self.save_path = os.path.join(self.pkg_img_path, "save")
            self.img_info_path = os.path.join(self.pkg_img_path, ".image_info")
            self.tmp_dir = self.dc_dict.get("tmp_dir")
            svc_profile_list = self.doc.volatile.get_descendants(self.name,
                class_type=Configuration)
            dc_pers_dict = self.doc.persistent.get_children(name=DC_PERS_LABEL,
                class_type=DataObjectDict)
            if dc_pers_dict:
                self.dc_pers_dict = dc_pers_dict[0].data_dict

        except KeyError, msg:
            raise RuntimeError("Error retrieving a value from the DOC: " +
                               str(msg))

    def execute(self, dry_run=False):
        '''
            Abstract method defined in AbstractCheckpoint class.

            Exports data from InstallEngine's DataObjectCache to the
            file named in self._manifest.

            Parameters:
            - dry_run is used to control what actions are taken if
              self._manifest already exists.  If dry_run is False, the
              file will be overwritten if it exists.  if dry_run is
              True, the output will be written to a similarly-named,
              but non-existing file.

            Returns:
            - Nothing
              On success, this method returns; on error it raises an exception.

            Raises:
            - ManifestError is raised if unable to fetch DOC reference or
              if an error occurs in write().
        '''

        self.logger.debug("ManifestWriter.execute(dry_run=%s) called", dry_run)

        engine = InstallEngine.get_instance()

        doc = engine.data_object_cache
        if doc is None:
            raise ManifestError("Cannot get DOC reference from InstallEngine")

        if dry_run and os.path.exists(self._manifest):
            self._manifest = _create_unique_variant(self._manifest)

        self.write(doc)

def validate_target():
    """ validate_target() - function to validate the target element specified
    in the manifest.
    """
    eng = InstallEngine.get_instance()
    doc = eng.data_object_cache

    # retrieve the build dataset
    build_datasets = doc.get_descendants(class_type=Filesystem)
    if len(build_datasets) > 1:
        raise RuntimeError("More than one dataset specified as the build "
                           "dataset")

    base_dataset = build_datasets[0].name
    base_action = build_datasets[0].action
    base_mountpoint = build_datasets[0].mountpoint

    # verify the base_action is not "delete" for the Filesystem
    if base_action == "delete":
        raise RuntimeError("distro_const: 'delete' action not supported "
                           "for Filesystems")

    # get the zpool name and action
    build_zpool = doc.get_descendants(class_type=Zpool)
    if len(build_zpool) > 1:
        raise RuntimeError("More than one zpool specified")

    zpool_name = build_zpool[0].name
    zpool_action = build_zpool[0].action
    zpool_mountpoint = build_zpool[0].mountpoint

    if zpool_action == "delete":
        raise RuntimeError("distro_const: 'delete' action not supported "
                           "for Zpools")

    # if the user has selected "create" for the action, verify the zpool is
    # not the bootfs zpool since there is an implied "delete" before any
    # "create" actions in TI
    elif zpool_action == "create":
        if is_root_pool(zpool_name):
            raise RuntimeError("distro_const: 'create' action not allowed "
                               "on a build dataset that is also a root "
                               "pool: " + zpool_name)

        # since the zpool_action is "create", unless the mountpoint of the
        # base_dataset is explictly set, it will be set to None.
        if base_mountpoint is None:
            # let ZFS figure out the mountpoint
            if zpool_mountpoint is None:
                base_mountpoint = os.path.join("/", base_dataset)
            else:
                # if the mountpoint has been specified, strip the zpool name
                # from the dataset name.
                fixed_name = "/".join(base_dataset.split("/")[1:])
                base_mountpoint = os.path.join(zpool_mountpoint, fixed_name)

    return(zpool_name, base_dataset, base_action, base_mountpoint)

def dump_doc(msg): 

    if not LOGGER.isEnabledFor(logging.DEBUG):
        return

    LOGGER.debug(msg)
    doc = InstallEngine.get_instance().doc
    disk = get_desired_target_disk(doc)
    LOGGER.debug(str(disk))

def get_sc_options_from_doc():
    '''Obtains list of sysconfig CLI options from Data Object Cache'''
    doc = InstallEngine.get_instance().doc.persistent
    sc_options = doc.get_first_child(name=SC_OPTIONS_LABEL)

    if sc_options is not None:
        return sc_options.options
    else:
        return None

    def discovered_doc_obj(self):
        ''' Search for the same disk found during Target Discovery
    
            Returns the object in the discovered target tree of the DOC.
 
            Raise RuntimeError() if disk is not found in discovered target.
        '''
        doc = InstallEngine.get_instance().doc
        return(find_discovered_disk(self.doc_obj, doc))

 def setUp(self):
     InstallEngine._instance = None
     InstallEngine()
     self.engine = InstallEngine.get_instance()
     self.doc = self.engine.data_object_cache.volatile
     self.soft_node = Software("CPIO_Transfer", "CPIO")
     self.tr_node = CPIOSpec()
     self.soft_node.insert_children([self.tr_node])
     self.doc.insert_children([self.soft_node])
     self.tr_cpio = TransferCPIO("CPIO_Transfer")

def from_engine():
    '''Convenience function for getting the ConfigProfile from
    the engine's DOC instance.

    '''
    doc = InstallEngine.get_instance().doc
    sysconfig = doc.get_descendants(class_type=ConfigProfile)
    if sysconfig:
        return sysconfig[0]
    else:
        return None

def parse_manifest(manifest):
    """ function to parse the manifest
    """
    eng = InstallEngine.get_instance()

    kwargs = dict()
    kwargs["call_xinclude"] = True
    args = [manifest]
    eng.register_checkpoint(MP_DICT["name"], MP_DICT["mod_path"],
                            MP_DICT["class"], args=args, kwargs=kwargs)
    execute_checkpoint()

    def __init__(self, name, be_mountpoint="/a"):
        super(TargetSelectionZone, self).__init__(name, be_mountpoint)

        # instance attributes
        self.be_mountpoint = be_mountpoint
        self.doc = InstallEngine.get_instance().data_object_cache

        # set the zone's alternate pool dataset
        self.selected_dataset = None

        # set the platform
        self.arch = platform.processor()

def to_engine(profile, override=True):
    '''Convenience function for putting a ConfigProfile into
    the engine's DOC instance. By default, removes any existing
    ConfigProfiles - set override=False to bypass that
    behavior.

    '''
    parent = InstallEngine.get_instance().doc.persistent
    if override:
        remove = parent.get_children(name=profile.name)
        parent.delete_children(children=remove)
    parent.insert_children(profile)

    def __init__(self, name, command):
        super(CustomScript, self).__init__(name)

        self.doc = InstallEngine.get_instance().data_object_cache
        self.dc_dict = self.doc.volatile.get_children(name=DC_LABEL,
            class_type=DataObjectDict)[0].data_dict
        self.pkg_img_path = self.dc_dict["pkg_img_path"]
        self.ba_build = self.dc_dict["ba_build"]

        # If command is over multiple lines, join with spaces, and then strip
        # any spaces at the ends.
        self.command = " ".join(command.splitlines()).strip()