Description
You can use the SysCmd function to perform one of the following functions:
Argument | Description | |
action | One of the following intrinsic constants identifying the type of action to take. | |
The following set of constants applies to a progress meter. The SysCmd function returns a Null if these actions are successful. Otherwise, Microsoft Access generates a run-time error. | ||
acSysCmdInitMeter | Initializes the progress meter. You must specify the text and value arguments when you use this action. | |
acSysCmdUpdateMeter | Updates the progress meter with the specified value. You must specify the text argument when you use this action. | |
acSysCmdRemoveMeter | Removes the progress meter. | |
acSysCmdSetStatus | Sets the status bar text to the text argument. | |
acSysCmdClearStatus | Resets the status bar text. |
The following set of constants provides information about Microsoft Access. | ||
acSysCmdRuntime | Returns True (–1) if a run-time version of Microsoft Access is running. | |
acSysCmdAccessVer | Returns the version number of Microsoft Access. | |
acSysCmdIniFile | Returns the name of the .ini file associated with Microsoft Access. | |
acSysCmdAccessDir | Returns the name of the directory where Msaccess.exe is located. | |
acSysCmdProfile | Returns the /profile setting specified by the user when starting Microsoft Access from the command line. | |
acSysCmdGetWorkgroupFile | Returns the path to the workgroup file (System.mdw). | |
The following constant provides information on the state of a database object. | ||
acSysCmdGetObjectState | Returns the state of the specified database object. You must specify the objecttype and objectname parts when you use this action value. | |
text | A string expression identifying the text to be displayed left-aligned in the status bar. This argument is required when the action argument is acSysCmdInitMeter, acSysCmdUpdateMeter, or acSysCmdSetStatus; this argument isn't valid for other action argument values. | |
value | A numeric expression that controls the display of the progress meter. This argument is required when the action argument is acSysCmdInitMeter; this argument isn't valid for other action argument values. | |
objecttype | One of the following intrinsic constants: | |
acTable acQuery acForm acReport acMacro acModule | ||
This argument is required when the action argument is acSysCmdGetObjectState; this argument isn't valid for other action argument values. | ||
objectname | A string expression that is the valid name of a database object of the type specified by the objecttype argument. This argument is required when the action argument is acSysCmdGetObjectState; this argument isn't valid for other action argument values. |
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 argument, and the text and value arguments. When the action argument is acSysCmdInitMeter, the value argument is the maximum value of the meter, or 100 percent. To update the meter to show the progress of the operation, call the SysCmd function with the acSysCmdUpdateMeter action argument and the value argument. When the action argument is acSysCmdUpdateMeter, the SysCmd function 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's displayed in the status bar by calling the SysCmd function with the acSysCmdSetStatus action argument 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 by using a proportional font, the actual number of characters you can display is determined by the total width of all the characters specified by the text argument. 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 the action argument is acSysCmdInitMeter, the SysCmd function ignores the text and doesn't display anything in the status bar. If the text is longer than the status bar and the action argument is acSysCmdSetStatus, the SysCmd function 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 the SysCmd function with the acSysCmdSetStatus action argument, the SysCmd function automatically removes the meter.
Call the SysCmd function 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 probably won't need an .ini file with your Microsoft Access application. The acSysCmdIniFile action argument exists for compatibility with earlier versions of Microsoft Access.
Call the SysCmd function with the acSysCmdGetObjectState action argument 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 the SysCmd function to determine the state of the table.
The SysCmd function with the acSysCmdGetObjectState action argument can return any combination of the following constants.
Constant | State of database object |
acObjStateOpen | Open |
acObjStateNew | New |
acObjStateDirty | Changed but not saved |
See Also CurrentObjectType, CurrentObjectName properties.
Example 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) & "..."
varReturn = 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
varReturn = SysCmd(acSysCmdClearStatus)
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 argument to determine the state of the active database object.
Dim intObjType As Integer, strObjName As String, intObjState As Integer
intObjType = Application.CurrentObjectType
strObjName = Application.CurrentObjectName
intObjState = SysCmd(acSysCmdGetObjectState, intObjType, strObjName)
If intObjState <> 0 Then
.
.
.
End If