e2e_appmon API

The e2e_appmon developer edition allows the developer to include checkpoints within the NimRecorder script. This functionality enables the probe to measure intermediate times of each process with the total runtime of the script.
uimpga-ga
The
e2e_appmon developer edition
allows the developer to include checkpoints within the NimRecorder script. This functionality enables the probe to measure intermediate times of each process with the total runtime of the script.
The package contains the CA Nimsoft API to be used with the e2e_appmon probe. The API allows the NimRecorder to use the functions in the script. The functions enable the programmer to access alarm and quality of service functions.The alarms and functions are acessed from the Nimsoft API in their in-house developed scripts.
This API contains core Nimsoft functions (for sending Alarms and QoS) and other supporting functions to make scripting easier.
While using the e2e_appmon probe:
  • Your script must begin with
    Include NimBUS-functions.src
    .
  • The
    NimBUS -functions.src
    file must be in the same directory as the script.
  • The file
    nimmacro.dll
    must be in the same directory as
    NimBUS -functions.src
    .
SDK_appmon
offers advanced scripting by offering the following functionalities:
  • Gathering multiple QoS points to identify the bottlenecks
  • Pre and post run cleanup
  • Synchronization
  • Error handling
  • Tuning your script to minimize the resource usage
  • Hiding or encrypting the passwords
  • Working with Citrix
Contents
nimGetEnv
nimGetEnv$(var$,def$)
Parameters
String
var$
The environment variable to fetch.
String
def$
Default if the variable is not in the environment.
Returns
String environment value
Description
Returns the contents of the environment variable referred to in var$. If the variable is not in the environment, by default it returns the value of def$.
Example
home$=nimGetEnv("HOMEDRIVE", "C:")
Dialog that is used in nimGetEnvEx to allow user to enter a value/string:
begindialog dlgAsk 225,130,200,110
caption "Please enter value"
defpushbutton "&OK",btnOk,10,50,65,20
edittext txtAsk$, 10,10,170,24
enddialog
Dialog that is used in nimGetEnvEx to allow the user to enter a password:
begindialog dlgAskSec 225,130,200,110
caption "Please enter value"
defpushbutton "&OK",btnOk,10,50,65,20
edittext txtAsk$, 10,10,170,24,protected
enddialog
nimGetEnvEx
nimGetEnvEx$(var$,def$,ask,pass).
Parameters
String
var$
The environment variable to fetch.
String
def$
Default if the variable is not in the environment.
Number
ask
If set, the dialog asks the user to input the string.
Number
pass
If set, the dialog masks out the input string.
Returns
String value
Description
Returns the contents of the environment variable referred to in var$. If the variable is not in the environment, it defaults to def$. If
ask
is set to 1, the dialog prompts you to input the string. If the
pass
is set to 1, the dialog masks out the input string.
Example
user$= nimGetEnvEx("Test-user","admin",1,0)
pass$= nimGetEnvEx("Test-pass","admin","",1,1)
nimStartRun
nimStartRun(cmd$)
Parameters
String
cmd$
The cmd$ to be executed from the
Run
entry on the Start menu.
Returns
0: OK.
1: Failed to get the Run window.
Description
Allows you to execute the cmd$ from the
Run
entry on the Start menu. The caller ensures that the command to be executed uses <doublequote> and other special keys. This is to ensure that the command understandable to SendKeys.
nimProcessExist
nimProcessExist(procname$,killproc)
Parameters
String
procname$
Name of the process to be located and terminated.
Number
killproc
Terminates the specified process soft (if 1), and hard (if 2).
Returns
0: process not found.
1: process found.
Description
Locate named process (procname) and terminates the process if (killproc) is (1=soft,2=hard).
The method is deprecated and in wintask 2.6a the function killapp() was added and does the same thing natively.
nimWaitForWebContents
nimWaitForWebContents(pageid$,contents$,load_timeout)
Parameters
String
pageid$
The web page to search for the contents specified.
String
contents$
The contents to search for in the web page specified.
Number
load_timeout
The number of seconds to wait for match before timeout.
Returns
0: timeout, no match.
1: match.
Description
Waits for matching contents of the web page for (load_timeout) seconds.
nimWaitForWebContentsEx
nimWaitForWebContentsEx(pageid$,contents$,content_fail$,load_timeout)
Parameters
String
pageid$
The web page to search for the contents specified.
String
contents$
The contents to search for in the web page specified.
String
content_fail$
The failure match to be applied as failure match when the content specified fails to match.
Number
load_timeout
The number of seconds to wait for match before timeout.
Returns
0: timeout, no match.
1: match.
Description
Waits for matching contents of the web page for (load_timeout) seconds. Applies a failure match too when the content fails to match.
nimWaitForWindow
nimWaitForWindow(winid$,load_timeout)
Parameters
String
winid$
The identification of the window to wait for.
Number
load_timeout
The number of seconds to wait for the specified window to appear before timeout.
Returns
0: timeout, no match
1: match
Description
Waits for a window matching (winid$) to appear within (load_timeout) seconds.
nimWaitForWindowText
nimWaitForWindowText(winid$,textstr$,load_timeout)
Parameters
String
winid$
The identification of the window to wait for.
String
textstr$
The text string to search for in the window specified.
Number
load_timeout
The number of seconds to wait for match before timeout.
Returns
0: timeout, no match
1: match
Description
Waits for a window matching (winid$) containing the text string (textstr$) to appear within (load_timeout) seconds.
nimAlarm
nimAlarm(severity,msg$,supp$,subsys$)
Parameters
Number
severity
The severity level of the alarm message.
String
msg$
The alarm message text.
String
supp$
Suppression ID.
String
subsys$
The id of the subsystem, identifying the module that the alarm is related to.
Returns
0 = OK
Description
Sends alarm message containing severity level, message text, checkpoint id, and subsystem id.
Example
nimAlarm(5,"critical alarm","script-name","E2E-appmon")
nimAlarmSimple
nimAlarmSimple(severity,msg$)
Parameters
Number
severity
The severity level of the alarm message.
String
msg$
The alarm message text.
Returns
0 = OK.
Description
Sends alarm message containing severity level and message text. The rest is provided by the global variables suppression_id$ and subsystem$.
Example
nimAlarm(5,"critical alarm")
nimInit
nimInit()
Parameters
None
Returns
0 = OK
Description
Initializes the Nimsoft SDK components. Must be run if using QoS.
nimEnd
nimEnd()
Parameters
None.
Returns
0 = OK
Description
Unloads the Nimsoft components and releases memory.
nimSetVariable
nimSetVariable(variable$, value$)
Parameters
None
Returns
0 = OK
Description
Sets the global variable named (variable$) to a new value. Allows you to override the suppression-id or subsystem.
Example
nimSetVariable("suppression-id","script")
nimQoSSendTimer
nimQoSSendTimer(target$)
Parameters
String
target$
Unique identifier for the QoS checkpoint.
Returns
0 = OK.
Description
Sends the recorded timer for the specified target.
Example
nimQoSSendTimer("citrix login")
nimQoSSendNull
nimQoSSendNull(target$)
Parameters
String
target$
Unique identifier for the QoS checkpoint.
Returns
0 = OK
Description
Sends a NULL (invalid data) for the specified target.
Example
nimQoSSendNull("citrix login")
nimQoSSendValue
nimQoSSendValue(target$,value)
Parameters
String
target$
Unique identifier for the QoS checkpoint.
Number
value
The value to send to the specified target.
Returns
0 = OK.
Description
Sends the recorded value (when not using timers) to the specified target.
Example
nimQoSSendValue("xxx",69)
nimQoSSendValueStdev
nimQoSSendValueStdev(target$,value$,stdev$)
Parameters
String
target$
Unique identifier for the QoS checkpoint.
String
value$
Number that is represented as a string,("12.45").
String
stdev$
Number that is represented as a string, ("12.45").
Returns
0 = OK.
Description
Sends the value and standard deviation (when not using timers).
nimQoSStart
nimQoSStart()
Parameters
None
Returns
Nothing
Description
Starts the QoS timer.
nimQoSStop
nimQoSStop()
Parameters
None
Returns
Nothing
Description
Stops the QoS timer.
nimQoSReset
nimQoSReset()
Parameters
None
Returns
Nothing
Description
Resets the QoS timer.
nimQoSGetTimer
nimQoSGetTimer()
Parameters
None
Returns
Timer in milliseconds
Description
Returns the stored (last) QoS Timer. If the nimQoSStop function has notbeencalled, then the time between nimQoSStart was called and the current time is returned.
nimInitWithMax
nimInitWithMax(qos_name$, source$, description$, long_unit$, short_unit$, max_value)
Parameters
String
qos_name$
The qos name of the e2e_appmon probe.
String
source$
Source from where QOS is coming.
String
description$
e2e_appmon Script Run Time.
String
long_unit
Full unit ex. “milliseconds”.
String
short_unit
Abbr. ex “ms”.
Int
max_value
QOS max values.
Returns
0 = OK.
Description
This function allows you to set various QoS parameters.
Example
nimInitWithMax(QOS_E2E_EXECUTION, QOS_source1, description$, Milliseconds, ms, 100)
nimSetCi
nimSetCi(type$, name$, remotename$, Metric$)
This function is used to add an additional device and metric information to alarms or quality of service message sent afterwards.
Parameters
String
type$
The CI type Id 
String
name$
The name of the object
String
remotename$
If the object is remote, the remotename is the hostname of the object owner. An empty string denotes the local host.
String
Metric$
The metric identifies the required property of the monitored object. For example, response time, usage or other performance parameters of the application.
Example
nimSetCi("3.21", "e2eappmon", "", "3.21:1") nimInit()
This API is required to be called before nimInit().
Setting nimSetCi before nimInit ensures that same Device Id/Metric Id are generated for all alarms and QoS.
For modifying Metric Id of Alarm, call the above API with modified parameters before nimAlarmSimple API.
nimSetCi("3.21", "e2eappmon", "", "3.21:2")
nimAlarmSimple(3,qos$(rc) + " failed")
For modifying Metric Id of QoS, follow this sequence:
nimSetCi("3.21", "e2eappmon", "", "3.21:3")
nimInit()
nimQoSSendNull(qos$(1)) 
nimInit is used to reset Metric Id for a QoS. And, it also resets the Metric Id of alarms being generated after sending this QoS.
nimLogin
nimLogin()
Parameters
String
username$
Username of the primary hub 
String
password$
Password of the primary hub 
Returns
None
Description
This function allows you to login to the CA UIM where the probe is installed.
nimActivateTotRule
nimActivateTotRule(time$,windows$,autoClear$,clearTime$)
Parameters
Number
time$
The time duration, in seconds, when a metric must remain over threshold before an alarm is sent.
Number
windows$
The time duration, in seconds, in the sliding window in which metrics are monitored for threshold violations.
Number
autoClear$
The state that defines whether the auto-clear functionality is enabled. The value must be either 0 or 1.
String
clearTime$
The time, in seconds, used in the auto-clear timer. If no alarms are sent in the set time period, the alarm is automatically cleared.
Returns
None
Description
This function activates the Time Over Threshold (TOT) rule in the probe from your script.
Example
nimActivateTotRule(120,600,0,0)
nimDeactivateTotRule
nimDeactivateTotRule(,time$,windows$,autoClear$,clearTime$)
Parameters
Number
time$
The time duration, in seconds, when a metric must remain over threshold before an alarm is sent.
Number
windows$
The time duration, in seconds, in the sliding window in which metrics are monitored for threshold violations.
Number
autoClear$
The state that defines whether the auto-clear functionality is enabled. The value must be either 0 or 1.
String
clearTime$
The time, in seconds, used in the auto-clear timer. If no alarms are sent in the set time period, the alarm is automatically cleared.
Returns
None
Description
This function deactivates the TOT rule in the probe from your script.
Example
nimDeactivateTotRule(180,1200,0,0)