InTouchEntryDialogs Script Function Library

Posted on 941 views

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™.

  1. Unzip the InTouchEntryDialogs.zip file.
  2. 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.

Leave a Reply

Your email address will not be published. Required fields are marked *

× 3 = 6