The InTouchEntryDialogs script function library consists of two files:
- InTouchEntryDialogs.dll
- InTouchEntryDialogs.wdf
This library provides the InTouch application developer with the option to
use familiar Windows Dialog Boxes to enter data to the InTouch application
during runtime. The dialog boxes used do not incorporate a keypad. However,
script functions are included that will allow the InTouch developer to open and
close the Windows On-Screen Keyboard. This option will be helpful on touch
screen systems.
The dialog boxes are displayed as modals, meaning that when they are open, no
interaction will be possible with the underlying InTouch window.
The functions in this library can cause InTouch to hesitate while processing
the dialog input. Please test the performance of the dialog box processing,
especially when you press OK, to determine whether any InTouch
hesitation occurs and if so, whether it is acceptable.
If it is determined that InTouch hesitation cannot be tolerated, consider
using these script functions from within asynchronous Quickfunctions. Executing
the function in this way processes the script on a separate thread from InTouch.
This allows InTouch to continue processing without interruption.
Download the InTouchEntryDialogs.zip file from the Wonderware®
Knowledge Base™.
- Unzip the InTouchEntryDialogs.zip file.
- Copy the InTouchEntryDialogs.dll and InTouchEntryDialogs.wdf
files and place them in your InTouch™ Install directory. The functions
will then be available from scripts when running WindowMaker.
Library Functions
This library consists of the following script functions:
- InTouchLogon(
“ResultTag” ) - InTouchLogon2(“ResultTag”,
“DefaultLogOnDomain” EnableAuditLogging) - ValueEntry(“ValueTag”,
Minimum, Maximum, “ResultTag” ) - ProtectedValueEntry(“ValueTag”,
Minimum, Maximum, “ResultTag” ) - ChangeWindowsPassword(“ResultTag”
) - OnScreenKeyboardOpen()
- OnScreenKeyboardClose()
InTouchLogon( “ResultTag” )
Use this function to log on to InTouch using the ArchestrA, InTouch or OS
security models. The Security Model configuration is only applicable in InTouch
8.0 and later. InTouch versions prior to 8.0 use the InTouch model exclusively.
Executing this function displays a Windows dialog box that accepts the InTouch
user name and password.
The Username Edit Box echos back the typed characters as asterisks rather
than the actual typed characters. When the log in information is invalid a
MessageBox displays a Logon Failure. The dialog box is shown in
Figure 1 (below).
Examples
ResultTag = InTouchLogon( “ResultTag” )
- ResultTag is the argument and also
the return value. Use the script this way because of the way the entry dialog
box is created and displayed:- When this script executes, a dialog modal loop is entered.
- Upon creation of the dialog a -1 is written to the tag
provided as the argument to the function call. This can then be used to
indicate that the dialog is open. - The user enters the logon information and presses OK.
The user can also press Cancel. - The modal loop exits and control returns to the calling procedure.
- The calling procedure returns the result back to the InTouch tag
specified. - If a valid account logon is entered, a 1 is returned to
ResultTag. If Cancel is pressed a 0 will be returned. - The $Operator, $AccessLevel and $OperatorDomain (InTouch 8.0 and later)
system tags reflect the log on account and assigned access level.
Figure 1 – The Logon
Entry Dialog
InTouchLogon2( “ResultTag”, “DefaultLogOnDomain”,
EnableAuditLogging )
Use this function to log on to InTouch using the ArchestrA, InTouch or OS
security models. The Security Model configuration is only applicable in InTouch
8.0 and later. InTouch versions prior to 8.0 use the InTouch model exclusively.
Executing this function displays a Windows dialog box that accepts the InTouch
user name and password.
The Username Edit Box echos back the typed characters as asterisks rather
than the actual typed characters. When the log in information is invalid a
MessageBox displays a Logon Failure. The dialog box is shown in
Figure 1 (above).
Examples
ResultTag = InTouchLogon( “ResultTag”, “DefaultLogOnDomain”,
EnableAuditLogging )
- ResultTag is shown as the argument and also the return
value. See
the previous ResultTag example for details. - When provided, DefaultLogOnDomain is the selected domain
when the dialog appears. This is true whether the supplied domain name is
valid or not. Using InTouchLogon2 with this parameter (rather than
InTouchLogon) provides the advantage and convenience of not having to enter or
select the domain each time a user logs on to InTouch.When an
empty string (i.e. “”) is provided for this parameter, the domain of the user
currently logged onto Windows is the selected domain.If a local
account is used predominantly, you can supply “localhost” for this parameter.
Entering “localhost” selects the local machine name as the domain. - EnableAuditLogging is used to record changes to the
logged on user or logon failures to the Wonderware or SMC Logger. A zero
(0) does not enable the audit logging. A non-zero value
enables the feature.
ValueEntry(“ValueTag”, Minimum, Maximum, “ResultTag”)
Use this function to enter a value into an InTouch tag. The tag can be any of
the four InTouch tag types (Discrete, Integer, Real, Message). Discrete tag
entries accept a 0 as false, and an integer value greater than
0 as true. The values entered are echoed back to the edit box. If an
invalid value is entered a MessageBox appears with an “invalid” message. The
dialog displayed is shown in Figure
2 (below).
Example
ResultTag = ValueEntry( “ValueTag”, Minimum, Maximum, “ResultTag”
)
- ValueTag is the name of the tag that the value entered will be written to.
This can be any of the InTouch tag types although it is unlikely that this
function would be used for discrete tag entries. This argument can be a quoted
string, as shown, or a message tag. - Minimum and Maximum are used to specify the allowable input range within
the engineering unit range of ValueTag. These two arguments are only relevant
for Integer and Real tags.For clarity, zeros should be supplied for
these fields if using this script to enter a discrete or message value. If it
is desired to use the engineering unit range of ValueTag as the allowable
input range, enter zero for both arguments Minimum and Maximum. These values
can be hard coded or entered as tag values of the type of ValueTag. The dot
fields that configure the minimum and maximum can also be used. - ResultTag is shown as the fourth argument and also the return value. See
the ResultTag
function above.
Note: The “ResultTag” argument field can be
entered as a message tag or a quoted string as illustrated.Figure 2 – The Entry
Dialog
ProtectedValueEntry(“ValueTag”, Minimum, Maximum,
“ResultTag” )
Use this function to enter a value into an InTouch tag without echoing the
characters back. Instead, asterisks are echoed back, similar to a Windows
password entry. ProtectedValueEntry() can be used to enter a value to any of the
four InTouch tag types (Discrete, Integer, Real, Message). Discrete tag entries
will accept a 0 as false and an integer value greater than 0 as
true. If an invalid value is entered a MessageBox appears with an “invalid”
message. The dialog displayed is shown in Figure
2 (above).
Example:
ResultTag = ProtectedValueEntry( “ValueTag”, Minimum, Maximum,
“ResultTag” )
- ValueTag is the name of the tag that the value entered will be written to.
As previously mentioned this can be any of the InTouch tag types although it
is unlikely that this function would be used for discrete tag entries. This
argument can be a quoted string, as shown, or a message tag. - Minimum and Maximum are used to specify the allowable input range within
the engineering unit range of ValueTag. These two arguments are only relevant
for Integer and Real tags.For clarity, zeros should be supplied for
these fields if using this script to enter a discrete or message value. If it
is desired to use the engineering unit range of ValueTag as the allowable
input range, enter zero for both arguments Minimum and Maximum. These values
can be hard coded or entered as tag values of the type of ValueTag. The dot
fields that configure the minimum and maximum can also be used. - ResultTag is shown as the fourth argument and also the return value. See
the ResultTag
function above.
Note: The “ResultTag” argument field can be
entered as a message tag or a quoted string as illustrated.
ChangeWindowsPassword( “ResultTag” )
Use this function to modify the password of a Windows user account in order
to maintain a valid account status for InTouch. This function can be used with
any InTouch security model. Similar to the “Change Password” dialog presented by
Windows, the dialog requires the Username, Domain, Old (Current) Password and
the new password entered twice to protect against typographical errors.
Asterisks are echoed back for all password fields. The dialog displayed is shown
in Figure
3 (below).
Example
ResultTag = ChangeWindowsPassword( “ResultTag” )
- ResultTag is the argument and also the return value. See the ResultTag
function above.
Note: As mentioned above if InTouch is not
configured for OS Security Model a -2 will be immediately returned. This
argument field can be entered as a message tag or a quoted string as
illustrated.Figure 3 – The
ChangeWindowsPassword Dialog
OnScreenKeyboardOpen( )
This function opens the Windows On-Screen Keyboard application. If needed
this keyboard can be opened to enter data to any of the dialogs of this script
library. This function can be used in an InTouch installation that uses a touch
screen computer or a system that does not have a keyboard available. The
application window displayed is shown in Figure 4 (below).
Example
ResultTag = OnScreenKeyboardOpen( )
- ResultTag accepts the return value of
OnScreenKeyboardOpen(). If the function successfully opens
the keyboard or the On-Screen Keyboard is already displayed a
1 is returned. A 0 is returned when a
failure occurs in trying to create the On-Screen Keyboard (osk.exe) process.If an error occurred while attempting to display the application
window, -1 will be returned. A -2 is
returned if a timeout occurred while waiting for the application window to
appear. In this case a logger message will also be written to inform the user
of the exact error.
Figure 4 – Windows
On-Screen Keyboard
OnScreenKeyboardClose( )
This function closes the Windows On-Screen Keyboard application. The
application window displayed is shown in Figure 4 (above).
Example
ResultTag = OnScreenKeyboardClose( )
- ResultTag accepts the return value of OnScreenKeyboardClose(). When the
function successfully closes the On-Screen Keyboard, or the On-Screen Keyboard
is not open a 1 is returned. A 0 is returned
when a failure occurs in trying to close the On-Screen Keyboard.