DeltaV-specific VBA Functions
DeltaV-specific VBA Functions
Writing scripts
For more information and examples on how to use these functions, refer to the Visual Basic
Editor's Automation Help in DeltaV Operate.
frs_User_prefs ()
Opens the User Settings dialog.
frsAddMenuItem (_
Entry as String, _
Optional EntryEnabled As Boolean = True)
As Long
Sequentially adds an entry to the menu.
Returns the error code from the AddMenuEntry
popupmenuclass method.
Entry - The string to be added to the menu.
EntryEnabled - set to True to enable new menu
entry.
frsAddMenuSeperator ( ) As Long
Adds a separator to the next position in the
menu. Returns error code from the
AddSeperatorEntry popupmenuclass method.
frsAssemblePath (_
strParampath As String, _
Optional strServer As String, _
Optional strNode As String, _
Optional strMod As String, _
Optional strFB1 As String, _
Optional strFB2 As String, _
Optional strFB3 As String, _
Optional strParam As String, _
Optional strField As String, _
Optional strExpression As String, _
Optional strZone As String) _
As Boolean
Converts the components of the path into a full
path.
strParampath - The full parameter path.
strServer - The server of the path.
strNode - The node in the parameter path.
strMod - The module in the parameter path.
strFB1 - The function block in the parameter
path.
strFB2- The function block in the parameter
path.
strFB3 - The function block in the parameter
path.
strParam - The parameter in the parameter
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 2 de 25
path.
strField - The field in the parameter path.
strExpressions - Anything after the field (for an
expressions).
strZone - The zone name in the parameter
path.
frsCheckForConfirmation (_
ConfirmRequired as Boolean, _
Optional Caption as string = " ")
As Boolean
Displays the Data Entry Expert confirmation
dialog (which is actually a form that allows the
Data Entry Expert to timeout gracefully).
ConfirmRequired - When True, confirmation is
required.
Optional Caption - The string displayed on the
dialog.
frsCheckForEvent (_
oObj as object, _
sEventName as String, _
lEventIndex as Long)
As Boolean
Checks for the event handler (sEventName) on
the object (oObj) and returns True if found;
otherwise, returns False. The event index is
returned if the event is found.
oObj - The object being checked.
sEventName - The event handler on the object
being checked.
lEventIndex - The event index that is returned if
the event is found.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 3 de 25
frsCheckPictureProperties ( ) As Long
Checks the active picture for the following:
Excessive datalinks with animations
Datalinks with incorrect display formatting
Empty groups
Results are reported to the user and the user is
given the option of viewing (in Notepad) the list
of datalinks that match one of the above
considerations.
frsCloseConfirmationDialog ( ) As Boolean
Searches the list of open forms looking for the
"frmDataEntryConfirmation" form and closes it
if found. If found and closed, returns True;
otherwise, returns False.
frsCloseFile ()
Used by the Close File button on the tool bar to
close the current file.
frsCreatePopupMenu ( ) As Long
Creates a popup menu. Uses the Popup Menu
Class. The handle to the menu is returned and
should be passed to all subsequent calls.
Returns the error code from the
OpenPopupMenu popupmenuclass method.
frsDisassembleAnyPath (_
strParampath As String,
Optional strServer As String, _
Optional strNode As String, _
Optional strMod As String, _
Optional strFB1 As String, _
Optional strFB2 As String, _
Optional strFB3 As String, _
Optional strParam As String, _
Optional strField As String, _
Optional strScale As String, _
Optional blnFB As Boolean, _
Optional bAllowTG As Boolean, _
Optional strZone As String)
As Boolean
Disassembles paths with Server.Node.Tag.Field
[scale].
strParampath - The full parameter path.
strServer - The server of the path. If a server is
not given in the input string, it will return the
default server.
strNode - The node in the parameter path.
strMod - The module in the parameter path.
strFB1 - The function block in the parameter
path.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 4 de 25
frsDisassembleAnyPathFB (_
strInString As String, _
Optional strServer As String, _
Optional strNode As String, _
Optional strMod As String, _
Optional strFB1 As String, _
Optional strFB2 As String, _
Optional strFB3 As String, _
Optional strParam As String, _
Optional strField As String, _
Optional strScale As String, _
Optional strExpression As String,
Optional bAllowTG As Boolean, _
Optional strZone As String)
As Boolean
Disassembles any function block path.
strInString - The input function block path.
strServer - The server of the path. If a server is
not given in the input string, it will return the
default server.
strNode - The node in the parameter path.
strMod - The module in the parameter path.
strFB1 - The function block in the parameter
path.
strFB2- The function block in the parameter
path.
strFB3 - The function block in the parameter
path.
strParam - The parameter in the parameter
path.
strField - The field in the parameter path.
strScale - The special scaling parameter field in
the parameter path.
strExpression - Anything after the scale (for an
expressions).
bAllowTG - When True, a tag group name is
used in the parameter path.
strZone - The zone name in the parameter
path.
frsDisassemblePath
Note
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 5 de 25
frsDoesPicExist (_
sPN As String, _
Optional path As String = "")
As Boolean
Checks to see if the picture exists. If exists,
returns the full path.
sPN - The name of the picture searching for.
path - the path to the picture. Defaults to the
system.picturepath directory if blank.
frsDynamoExpert ()
Calls the Build Dynamo Expert. Use the Build
Dynamo button on the tool bar.
frsExitOIDialog ()
Displays a dialog to confirm the operator wants
to exit DeltaV Operate.
frsFindFile (_
FileToFind As String, _
RootDir As String, _
Optional CheckSubFolder As Boolean = True, _
Optional FullFileName As Variant)
As Boolean
Searches from the location specified in RootDir.
Searches all subfolders for the file specified in
FileToFind if CheckSubFolder is True. Returns
the full path to that file (if found).
FileToFind - The filename searching for.
RootDir - The starting directory (root) for the
search.
CheckSubFolder - The command to check the
subfolders (of the directory specified in
RootDir). Defaults to True.
FullFileName - The result of the search with the
full path and filename.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 6 de 25
frsGetComputerName ( ) As String
Returns the computer name. Returns an empty
string on any error.
frsGetDVInstallFolder ( ) As String
Reads the Windows Registry key to find the
installed DeltaV folder.
frsGetMyMonitorNumber ( ) As Long
Returns the monitor number of the picture that
is active.
frsHandleError ()
The FRSI error handler.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 7 de 25
frsInputAnyModuleNameDT (_
objPic As Object, _
Optional strModPassed As String = " ", _
Optional lngMonOverride As Long = 0, _
Optional blnDoNotAsk As Boolean = False, _
Optional strServerHint As String = "")
Opens the module's detail display picture from
any supported server.
objPic - The object picture name.
strModPassed - The module name.
lngMonOverride - The monitor number. If
entered, overrides the current monitor action.
blnDoNotAsk - The command to not prompt for
any questions. When True, no questions are
asked and the routine ends if it cannot
complete. The default is False.
strServerHint - The server name, if known.
frsInputAnyModuleNameFP (_
objPic As Object, _
Optional strModPassed As String, _
Optional blnDoNotAsk As Boolean = False, _
Optional strServerHint As String = "")
Opens the module's faceplate from any
supported server.
objPic - The object picture name.
strModPassed - The module name.
blnDoNotAsk - The command to not prompt for
any questions. When True, no questions are
asked and the routine ends if it cannot
complete. The default is False.
strServerHint - the server name, if known.
frsInputAnyModuleNamePD (_
objPic As Object, _
Optional strModPassed As String = "", _
Optional lngMonOverride As Long = 0, _
Optional blnDoNotAks As Boolean = False, _
Optional strServerHint As String = "")
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 8 de 25
frsInsufficientPrivilegeDialog ()
Displays an error dialog stating that the
operator does not have privilege to perform the
operation requested.
frsIsDualMonitor ( ) As Boolean
Returns True if it is a multiple monitor system.
frsLabDataEntry (objDynamo)
This subroutine is specifically designed for the
Lab Entry function block.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 9 de 25
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 10 de 25
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 11 de 25
frsNewPicture ()
Opens the dialog to create a new picture from a
template.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 12 de 25
which it is looking.
baseObject - The object to look in for the
ObjectName. If left blank, this function will look
for an open picture.
returnObject - Returns the handle to the object
if found and nothing if not found.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 13 de 25
Optional X As Single,
Optional caption As String,
Optional nickname As String) As Object
Opens a picture and performs a temporary (for
this opening only), dynamic (as it opens)
substitution on the picture.
Picture - Name of the picture to open.
Symbol - The symbol ARRAY in the picture that
the substitution will be performed on. This must
be an array of the same size as the
replacement.
Replacement - The string ARRAY that will be
inserted in for the symbol. This must be an
array of the same size as the symbol.
Y - The top coordinates of the picture in pixels.
X - The left coordinates of the picture in pixels.
caption - The caption to display on the title bar
of the picture being opened.
nickname - The nickname being assigned to the
picture being opened.
frsOpenUnacknowlegedPromptsPicture ()
Replaces the current picture with the
UnacknowledgedPrompts picture.
frsParamPath
Note
This function is no longer used but remains
for backwards compatibility. Use
frsAssemblePath instead.
frsProperty ()
Opens the multiple property form. Used in
configuration only.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 14 de 25
frsRemoveGroups ()
Ungroups an object. If nothing is selected on
the picture, all groups on the picture are
ungrouped.
frsReplace ()
Changes the index of multiple groups.
frsResize ()
Opens the dialog that allows you to change the
size of a picture. The preferred method is to use
the Resize Picture button.
frsSavePicture ()
Called by the Save button on the tool bar.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 15 de 25
frsSetTextBoxState (_
TB As TextBox, _
EnableFlag As Boolean)
As Boolean
Enables or disables a text box. Returns True if
the text box enable/disable state is set;
otherwise, returns False.
TB - The text box being enabled or disabled.
EnableFlag - The Boolean flag that is set to
enable or disable the text box.
frsShowPopupMenu ( ) As Long
Displays the menu. This function will not return
until the left mouse button is clicked (whether
or not the cursor is over the menu). Returns the
sequence number for the menu item selected.
frsStartDebug ()
Creates an instance of the trace class and opens
the tracebox
if trace has been enabled.
frsUserConfigPrivChk ( ) As Boolean
Checks if the currently logged-in user has
configuration privileges. Returns True if the
user can configure; otherwise, returns False.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 16 de 25
frsValidatePictureName (_
sPicName As String, _
Optional PicPath As String = "")
As Boolean
Validates if the picture's name syntax is correct
(as defined by frsPictureNameOK and if True,
checks if the picture exists.
sPicName - The picture name to be validated.
PicPath - The path to the picture.
Note
DeltaV screen (DV_SCREENS) refers to the DeltaV screen name, that is, Primary, Secondary,
USER1 and USER2. Screen refers to the monitor number as configured by the video driver when
installing the hardware for a multiple monitor workstation. Screens are numbered 1, 2, 3 and 4.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 17 de 25
DefPath As String
Returns the DeltaV detail function block path. Equivalent
to system.picturepath & "\DetailFB\".
DetPath As String
Returns the DeltaV detail path. Equivalent to
system.picturepath & "\Detail\".
frsCurrentMainPicName (
Optional Screen As DV_SCREENS) As String
Returns the current main picture name.
Screen - Enumeration of the screen. If Screen is not
specified, the name of the default screen number is
used.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 18 de 25
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 19 de 25
frsDesktopSize (X As Long,
Y As Long)
Returns the X and Y resolution of a desktop. This is the
visible region of the display that might span multiple
monitors.
X - Number of horizontal pixels.
Y - Number of vertical pixels.
frsGetInputTimeout ( ) As Long
Returns the current value for the input timeout. There
are no input parameters for this function.
frsGetLastError (
Optional ErrorText As Variant,
Optional ByVal ClearError As Boolean) As Long
Returns the last error as Long.
ErrorText -The error text that corresponds to the error
number.
ClearError - True to clear the last error. False to retain
the last error.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 20 de 25
Legacy interface for Custom Keyboard Returns the relative vertical offset of a picture relative to
project the upper left corner of a screen as Long.
PicType - Enumeration of picture.
frsMonitorNumFromPoint (
Optional Xpos As Long,
Optional Ypos As Long) As Long
Returns the monitor number (1, 2, 3, 4- as configured
by the video driver ) for where the cursor is.
Xpos - X or left position of the picture.
Ypos - Y or top position of the picture.
frsMonitorOrientation ( ) As DV_SCREEN_ORIENTATION
See Also: frsScreenLayout Returns the monitor orientation as determined from the
desktop size and screen resolution.
frsNumScreens (X As Long,
Y As Long)
Returns the number of screens horizontally and
vertically.
X - Number of screens horizontally.
Y - Number of screens vertically.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 21 de 25
frsOperatorKeyboard ( ) As Boolean
Returns True if the screen is the Operator Keyboard
screen.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 22 de 25
frsScreenLayout ( ) As DV_SCREEN_ORIENTATION
See Also:frsMonitorOrientation Returns the current screen layout.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 23 de 25
frsScreenNumFromPoint (
Optional Xpos As Long,
Optional Ypos As Long) As Long
Returns the screen that contains the point indicated by
Xpos and Ypos. If Xpos and Ypos are not specified, the
current cursor location is used.
Xpos - The X coordinate.
Ypos - The Y coordinate.
frsScreenResolution (X As Long,
Y As Long)
Contains the X and Y resolution of a screen. Note: The
resolution is the same for all screens.
X - Number of horizontal pixels on each screen.
Y - Number of vertical pixels on each screen.
frsSelectDefaultScreen ()
Displays the dialog to select and set the default screen.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 24 de 25
frsTotalNumScreens ( ) As Long
Returns the total number of screens detected on the
computer.
frsXToRel (X As Long,
oPic As Object) As Long
Returns the X coordinate of the picture referenced
relative to the upper left corner of the screen.
X -The left coordinates of the picture in pixels.
oPic - The object reference picture.
frsYToRel (Y As Long,
oPic As Object) As Long
Returns the Y coordinate of the picture referenced
relative to the upper left corner of the screen.
Y - The top coordinate of the picture in pixels.
oPic - The object reference picture.
HepPath As String
Returns the DeltaV help path. Equivalent to
system.picturepath & "\Help\".
IabPath As String
Returns the DeltaV faceplate function block path.
Equivalent to system.picturepath & "\FaceplateFB\".
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
DeltaV-specific VBA functions Página 25 de 25
IafPath As String
Returns the DeltaV faceplate path. Equivalent to
system.picturepath & "\Faceplate\".
MainTempPath As String
Returns the main picture's temp path where the copy is.
PicPath As String
Returns the DeltaV picture path. Equivalent to
system.picturepath.
PocfpPath As String
Returns the DeltaV POC faceplate path. Equivalent to
system.picturepath & "\POC\Faceplate\".
StdPath As String
Returns the DeltaV standard path. Equivalent to
system.picturepath & "\Standard\".
TempPath As String
Returns the DeltaV temp path. Equivalent to
system.picturepath & "\Temp\".
TracePath As String
Returns the DeltaV trace path. Equivalent to
system.picturepath & "\Standard\".
TrbPath As String
Returns the DeltaV trend function block path. Equivalent
to system.picturepath & "\TrendFB\".
TrnPath As String
Returns the DeltaV trend path. Equivalent to
system.picturepath & "\Trend\".
frsGetTerminalServerName Returns the Remote Desktop Services session's name. Returns a null
value if not on a Remote Desktop Services session.
Note
For more information on remote client session-specific settings, see The order in which the
system applies the settings files.
mk:@MSITStore:C:\VIEW\00%20-%20Projetos\CIC%20-%20COMPERJ\Manuais%2... 7/8/2021
The `frsMovePicture` function significantly enhances user experience in multi-monitor setups by allowing pictures to be moved across screens while maintaining their relative positions. This capability is crucial in environments where users manage multiple displays, offering flexibility in organizing workspace layouts without losing the context or positioning of current operations. If a new screen isn't specified, a dialog box provides selection options, further streamlining user interaction and adaptability in complex operational scenarios .
The function `frsDisassemblePath` was originally used to break down parameter paths into their components such as server, node, module, function blocks, and parameter fields. However, for modern applications, `frsDisassembleAnyPath` or `frsDisassembleAnyPathFB` serve similar purposes but with enhanced capabilities to handle additional path types including those involving function blocks and tag groups. Despite being outdated, `frsDisassemblePath` remains in use for backward compatibility, ensuring that legacy systems continue to function without requiring immediate code updates .
The function `frsCheckPictureProperties` evaluates the active picture for optimal performance by checking for excessive datalinks with animations, datalinks with incorrect display formatting, and empty groups. Upon detecting any of these issues, it provides the user options for addressing them, such as viewing a list in Notepad, thus enabling effective troubleshooting and optimization of graphic displays to enhance performance and reduce resource usage .
Using `frsDisassembleAnyPathFB` can introduce challenges due to its reliance on precise input formats, including function block paths and potential tag groups. Errors may occur if inputs aren't formatted correctly or if expected elements like servers or tags are missing. Mitigation involves thorough validation of inputs before calling the function, ensuring all optional parameters are handled appropriately, and incorporating error-checking mechanisms to gracefully respond to missing or malformed path components .
The function `frsProtectBoundaries` ensures display elements remain entirely visible by positioning the referenced picture on the intended screen, considering both the X and Y offsets and the screen's resolution. In scripts where screen boundaries are critical, this ensures that pictures do not spill over screen edges, avoiding situations where elements may be partially obscured due to varied monitor setups. Equivalent protection across diverse resolutions helps maintain visual integrity and user interface consistency, crucial in multi-screen environments .
The `frsGetInputTimeout` function retrieves the current input timeout value, which is crucial for automation scripts involving time-sensitive operations. This function enables scripts to adapt to predefined timing thresholds, crucial for workflows where input delays can disrupt sequences. By dynamically fetching this value, scripts can adjust their operations to align with system expectations, thus mitigating risks associated with untimely inputs and ensuring synchronized execution of automated tasks .
The function `frsCreatePopupMenu` creates a popup menu using the Popup Menu Class within the DeltaV Operate environment. When executed, it returns a handle to the created menu, which is essential for passing to all subsequent calls related to the popup menu. Additionally, it returns an error code obtained from the OpenPopupMenu method of the popupmenuclass, indicating whether the creation was successful or if an error occurred .
The `frsFindFile` function improves file management by providing a mechanism to search for files starting from a specified root directory, with the option to include all subfolders. By returning the full path to the file if found, this function aids in dynamically locating resources without hardcoding paths, essential for scripts that require flexibility and adaptability in accessing various assets on different systems .
The function `frsCheckForMainPic` checks whether a given picture is a main picture, toolbar, or alarm banner picture in the DeltaV Operate environment. Using this function allows scripts to validate picture types before performing operations, ensuring that actions such as editing or displaying information are only applied to suitable picture types. This helps maintain UI consistency and reduces the risk of errors by preventing inappropriate interactions with non-main pictures .
The `frsGetCoordinates` function offers significant benefits by providing the X and Y coordinates of a given picture object, invaluable for developers creating custom layouts. It ensures precise placement of display elements relative to screen dimensions, facilitating the building of interfaces that can be consistently reproduced across different setups. Effective utilization involves integrating these coordinates within layout algorithms to maintain alignment and proportionality of visual components, promoting a uniform user experience .