Description
WWDosCommand() starts a Windows DOS Box in a specified initial state and runs a specified command line. Once WWDosCommand() completes, the DOS Box will exit and close. See Tech Support Script Function Library to install this function.
Use:
WWDosCommand(DOSCmdLine, InitState);
| DOSCmdLine | A message tag or a quoted string (example: “CHKDSK”) which is a DOS command line that will be executed in the DOS Box . |
| InitState | A message tag or a quoted string (example: “MAXIMIZED”) which is a valid InitialState (see below). |
Important The InitState parameter is case sensitive.
Returns:
WWDosCommand() returns an integer number as described below:
If the integer is greater than 31:
It means WWDosCommand() was successful. This number is the process Id of the instance of the DOS Box. The process Id does not need to be used elsewhere in the script and thus, it can be ignored.
If the integer is equal to -1:
It means either the DOSCommandLine or the InitState was not specified. Both are required variables.
If the integer is between 0 and 31:
It means an error occurred during the execution of DOSPRMPT.PIF (the DOS box Program Information File). See the Wonderware Logger for the specific error message. Usually an error occurs because of a lack of memory. This can be caused by attempting to start too many applications at one time. Look at the return value and trigger an alarm or create a Disable link on the button that enables WWDosCommand(). A discrete colorfill based on: “returnvalue < 31” will allow you to change the color or visibility of the button or some text associated with this action on the screen.
Important The DOS environment variable ERRORLEVEL, any errors encountered during the execution of the DOS function or errors reported by DOS are unavailable to InTouch™. They will be ignored.
Details of WWDosCommand()
The DOS Box is a special window inside the Windows environment. It is a viewport into the DOS environment underneath Windows. Even though the DOS Box is a “virtual machine”, if any files are removed, edited, moved or renamed, the entire Windows system will be affected. Therefore, we suggest that you test any commands passed to the DOS Box before including them with the WWDosCommand() function.
Here are the valid values for the InitState parameter.
Note InitState is case sensitive. Use all caps when specifying the InitState value.
| “RESTORED” | The application will start in its last known non-maximized state. (This is the default value for InitState.) |
| “MAXIMIZED” | The application window will cover the entire screen. |
| “MINIMIZED” | The application will start as an icon. |
| “INVISIBLE” | The application will start but will be hidden and no icon will be visible either. Wonderware Technical Support suggests that if this value is used, you should make sure that the application specified in WindowsApplicationName can shut itself down. Otherwise, the application will run continuously. |
To keep the user from seeing the DOS Box at all (including no icon) you should use the “INVISIBLE” string for InitState. See Example of Using WWDosCommand() below for more information.
Note For any InitState value to work (except for MAXIMIZED), edit the DOSPRMPT.PIF file in your Windows directory using the PIF editor. (PIF is in your Main program group under the Program Manager.) Select the Windowed option under the “Display Usage:” section. By default, this is set to “Full Screen”.
Example of Using WWDosCommand()
The following is a script that uses WWDosCommand():
{ This is an example of using the WWDosCommand() Script function}
{ to COPY a datafile from one directory to another - for backup }
{ Call the function to do the copy }
errorcode = WWDosCommand ( "COPY C:\500APP\LOG.DAT C:\TEMP\080894.DAT", "MAXIMIZED" );
Here is a screen shot of before the DOS Box closed that is the result of executing the script:
When WWDosCommand() is called, the DOS Box appears (because it was not called with the value of “INVISIBLE” for InitState) and the DOS Command line is executed. Without any prompting from the user, the DOS Box will close, thus keeping your system secure.