Open topic with navigation

Object Status Properties

InstallShield 2015

Every InstallScript object—whether predefined or user-defined—has the following read-only properties:

StatusBase and StatusStruct are intended only for advanced users. See the following sections for information on these properties.

Status

The Status property is a structure with the following properties as members:

In an object script, you can set these values by calling SetStatusEx. When you query the status of an object, by default it first queries the status of its subobjects (if any); if one or more of an object’s subobjects report an error (that is, have a Status.Number property that is less than OBJ_STATUS_SUCCESS), the value of the first failing object’s status property is returned as the value of the parent object’s status. A user-defined object’s script can override this default behavior by explicitly defining a get_Status function (with no arguments).

You can check the value of an object’s Status.Number property to determine whether the object can be successfully installed—and, if not, what the cause is—and display the value of Status.Description to your end user. You can perform this check at any point in a setup; it is recommended that you at least check for success or failure in the OnBegin event handler, as in the following example:

function OnBegin()

    /* Declare an object variable to hold a reference to the object. */

    OBJECT oObject;

begin

    /* Get a reference to a custom object named "My Custom Object". */

    set oObject = GetObject("My Custom Object");

    /* Check the Status.Number property. */

    if oObject.Status.Number != OBJ_STATUS_SUCCESS then

        /* Respond to the error as appropriate for your setup.

        For example, you can display the Status.Description

        text and abort the setup. */

        MessageBox ( oObject.Status.Description, SEVERE );

        abort;

    endif;

end;

The following table lists those possible values of Status.Number and Status.Description that are common to all objects. Some objects also have possible values of these properties that are unique to that object. For lists of those possible values, see the individual object’s help page (by selecting the object in the Objects view, or in the Setup Design or Features view under its associated feature).

StatusBase

The StatusBase property is a structure with the same members as the Status property. This property is typically used only by objects that have a customized get_Status method; except for special cases a setup should not query this property directly, as it could bypass any custom status handling that the object provides.

The StatusBase property enables you to use an object’s default status handling, including checking the statuses of the object’s subobjects. If you have created a custom get_Status function for your object, you can use the StatusBase property within the get_Status function to use the default object status handling, as in the following example:

function object get_Status()

    object oThis;

begin

    // Do some custom handling here.

    // Get a reference to this object.

    set oThis = GetObject( "" );

    // Fail if this is not an object.

    if( !IsObject( oThis ) ) then

        return NULL;

    endif;

    // Return the standard status information.

    return oThis.StatusBase;

end;

StatusStruct

The StatusStruct property is a structure with the same members as the Status property. This property is typically used only by objects that have a customized get_Status method; except for special cases, an installation should not query this property directly because it could bypass any custom status handling that the object provides.

The StatusStruct property allows you to bypass the default object status handling. You can use this property if you want your object to ignore subobject status values, as in the following example:

function object get_Status()

    object oThis;

begin

    // Get a reference to this object.

    set oThis = GetObject( "" );

    // Fail if this is not an object.

    if( !IsObject( oThis ) ) then

        return NULL;

    endif;

    // Return the status information directly.

    return oThis.StatusProp;

end;

See Also

GetStatus