SysCmd Function

Description

You can use SysCmd to perform one of the following functions:

For example, if you are building a custom wizard that creates a new form, you can use the SysCmd function to display a progress meter indicating the progress of your wizard as it constructs the form.

Syntax

ReturnValue = SysCmd(action[, text][, value])ObjectState = SysCmd(action[, objecttype][, objectname])

The SysCmd function syntax has the following arguments.

Remarks

By calling the SysCmd function with the various progress meter actions, you can display a progress meter in the status bar for an operation that has a known duration or number of steps, and update it to indicate the progress of the operation.

To display a progress meter in the status bar, you must first call the SysCmd function with the acSysCmdInitMeter action and the text and value arguments. When the action argument is acSysCmdInitMeter, value is the maximum value of the meter, or 100 percent.

To update the meter to show the progress of the operation, call SysCmd with the acSysCmdUpdateMeter action and the value argument. When action is acSysCmdUpdateMeter, SysCmd uses the value argument to calculate the percentage displayed by the meter. For example, if you set the maximum value to 200 and then update the meter with a value of 100, the progress meter will be half-filled.

You can also change the text that is displayed in the status bar by calling SysCmd with the acSysCmdSetStatus action and the text argument. For example, during a sort you might change the text to “Sorting...”. When the sort is complete, you would reset the status bar by removing the text. The text argument can contain approximately 80 characters. Because the status bar text is displayed using a proportional font, the actual number of characters you can display is determined by the total width of all the characters specified by text.

As you increase the width of the status bar text, you decrease the length of the meter. If the text is longer than the status bar and action is acSysCmdInitMeter, SysCmd ignores the text and doesn’t display anything in the status bar. If the text is longer than the status bar and action is acSysCmdSetStatus, SysCmd truncates the text to fit the status bar.

You can’t set the status bar text to a zero-length string (" "). If you want to remove the existing text from the status bar, set the text argument to a single space. The following examples illustrate ways to remove the text from the status bar:

varReturn = SysCmd(acSysCmdInitMeter, " ", 100)

varReturn = SysCmd(acSysCmdSetStatus, " ")

If the progress meter is already displayed when you set the text by calling SysCmd with the acSysCmdSetStatus action, the SysCmd function automatically removes the meter.

Call SysCmd with other actions to determine system information about Microsoft Access, including which version number of Microsoft Access is running, whether it is a run-time version, the location of the Microsoft Access executable file, the setting for the /Profile argument specified in the command line, and the name of an .ini file associated with Microsoft Access.

Note Both general and customized settings for Microsoft Access are now stored in the Windows Registry, so you most likely won’t need an .ini file with your Microsoft Access application. The acSysCmdIniFile action exists for compatibility with earlier versions of Microsoft Access.

Call SysCmd with the acSysCmdGetObjectState action and the objecttype and objectname arguments to return the state of a specified database object. An object can be in one of four possible states: not open or nonexistent, open, new, or changed but not saved.

For example, if you are designing a wizard that inserts a new field in a table, you need to determine whether the structure of the table has been changed but not yet saved, so that you can save it before modifying its structure. You can check the value returned by SysCmd to determine the state of the table.

The SysCmd function with the acSysCmdGetObjectState action can return any combination of the following constants.

Note If the object referred to by objectname is either not open or does not exist, SysCmd returns a value of zero.

Examples

The following example creates a snapshot-type Recordset object, reads each record, and displays a progress meter showing the current relative position in the snapshot.

Function ReadRecords (strTableName As String) As Integer

    Const conBadArgs = -1

    Dim dbs As Database, rst As RecordSet
    Dim lngCount As Long, strMsg As String

    Dim varReturn As Variant, lngX As Long
    
    ReadRecords = 0

    If strTableName <> "" Then
        DoCmd.Hourglass True
        Set dbs = CurrentDb
        On Error Resume Next
        Set rst = dbs.OpenRecordSet(strTableName)

        ' Get record count.
        rst.MoveLast
        rst.MoveFirst
        If Err Then
            ReadRecords = conBadArgs
        End If

        lngCount = rst.RecordCount
        On Error GoTo 0

        If lngCount Then
            strMsg = "Reading " & UCase$(strTableName) & "..."
            ReturnValue = SysCmd(acSysCmdInitMeter , strMsg, lngCount)
            ' Display message in status bar.
            For lngX = 1 To lngCount
                varReturn = SysCmd(acSysCmdUpdateMeter, lngX)

            ' Update meter.
                .                    ' Do something with record.
                .
                .

                rst.MoveNext            ' Go to next record.
            Next lngX

            GoSub CloseObjects
            ReadRecords = lngCount    ' Return number of records.
            Exit Function
        End If
    End If

    ' Not found or contains no records.

    strMsg = "Table '" & strTableName _
        & "'not found or contains no records.'"
    MsgBox strMsg, vbInformation, "ReadRecords"
    GoSub CloseObjects
    Exit Function

CloseObjects:
    On Error Resume Next
    rst.Close
    dbs.Close
    On Error GoTo 0
    DoCmd.Hourglass False
    Return

End Function

The next example illustrates how you can use the SysCmd function with the acSysCmdGetObjectState action to determine the state of the active database object.

Dim intObjType As Integer, strObjName As String, intObjState As Integer

intObjType = Application.CurrentObjectType= Application.CurrentObjectName

intObjState = SysCmd(acSysCmdGetObjectState, intObjType, strObjName)

If intObjState <> 0 Then
.

.
.If