| Oracle® Retail Predictive Application Server Administration Guide for the Classic Client Release 14.1 E59120-01 |
|
 Previous |
 Next |
| Oracle® Retail Predictive Application Server Administration Guide for the Classic Client Release 14.1 E59120-01 |
|
Previous |
Next |
This appendix describes the RPAS Test Driver (RTD).
Support for the RTD library is limited to its basic understanding and usage of the published XML-based APIs. This library is available on specific versions of the Windows platform where the RPAS release is officially supported.
Oracle does not provide support for compilation or linkage of this library. Also, Oracle does not support LoadRunner scripts or any other scripts used to run the rtd.dll library.
This appendix covers the use of rtd.dll provided for the purpose of performance testing of the Oracle Retail RPAS server.
This DLL allows a user to create, open, alter, save, commit, and refresh workbooks by sending commands directly to the RPAS server through an XML structure.
Knowledge of the usage of the Oracle Retail RPAS client is assumed. A user must have a working domain that can be connected to with a client. A user must also know the internal names of dimensions, positions, workbook templates, worksheets, and windows.
Although the interface provided by this library could be used by any testing tool, it has most frequently been used with HP LoadRunner. The use of RTD with LoadRunner is outlined in later sections.
The majority of interactions with RTD assume knowledge of names rather than labels. In order to easily find dimensions and position names, the RPAS client (foundation.exe) can be made to display the internal names rather than labels.
This is accomplished by adding "ShowPositionNames=1" under the [Options] section in %windir%\foundation.ini, for example, C:\Windows\foundation.ini. (The foundation.ini file may be in another location, as described step 3 in "Translation Administration".) Then, when building and displaying a workbook, the client displays position names instead of labels.
To find template, worksheet, and window names, make a search under your domain's "repos" directory for files named "tmpl.cfg" with the label (displayed name) of your template. The template name, worksheet, and window names are contained within this file.
The C interface provided by the library is simple to interact with, the majority of interactions being with rtd_send() and rtd_getResponse() functions. The complexity arises in the messages sent and received by these functions, detailed in the next section.
To log on to the server:
int rtd_logon(const char* user, const char* password, const char* connection, const char* domain, const char* fcfPath, const char* language, const char* logLevel)
Or,
int rtd_logon_ex(const char* user, const char* password, const char* connection, const char* domain, const char* fcfPath, const char* language, const char* logLevel, const char* domainRootDirectory)
Table B-1 provides descriptions of the arguments used by int rtd_logon.
Table B-1 Arguments Used by int rtd_logon
| Argument | Description |
|---|---|
|
const char* user |
User name. |
|
const char* password |
User password. |
|
const char* connection |
Connection defined in the .fcf file. |
|
const char* domain |
Domain defined in the .fcf file. |
|
const char* fcfPath |
Path to the .fcf file. |
|
const char* language |
Language of the domain, usually "english". (Currently unused.) |
|
const char* logLevel |
Log level of the RPAS server, defaults to "debug" if blank. |
|
const char* domainRootDirectory |
The domain path in foundation.fcf that is prepended with this string. This allows the foundation.fcf to specify a relative (or empty) domain path. |
To log off the server:
void rtd_logoff()
To send an XML request to the server:
int rtd_send(const char* request)
To get the XML response from the server request:
char* rtd_getResponse()
To get a particular property from the response XML tag:
char* rtd_getResponseProperty(const char* property)
To free the char buffer that was allocated by rtd_getResponse() or rtd_getResponseProperty():
void rtd_freeCharPtr(char*)
|
Note: The char buffer must be free in order to prevent memory leaks. |
The functions rtd_logon, rtd_logon_ex, and rtd_send indicate success by returning 1 and failure by returning 0.
Figure B-1 shows an example of the expected use of the library. RTD function calls are indicated in the shaded blocks.
This section describes requests that can be sent as XML strings to the server. All tags and attributes are case-sensitive.
There are two connection messages.
The messages below appear in the order in which they are called. They are repeated as necessary for the wizard pages. The wizard pages can be determined by creating the same workbook in the client.
Description:
Start wizard to create a new workbook. Some wizards do not have any wizard pages. After calling this, call rtd_getResponseProperty("skipDisplay") will be true if this wizard does not have any wizard pages.
Properties:
templateName: Internal name of the workbook template, as defined in tmpl.cfg.
Description:
Move to the next page in a wizard. This must be called after <WizardInitialize> to navigate to the first wizard page. After calling this, call rtd_getResponseProperty("nextDialog") to return the name of the new wizard page.
Properties:
templateName: Internal name of the workbook template, as defined in tmpl.cfg.
currentDialog [optional]: Not currently used.
forward: Direction to move the wizard. Values are "true" to go forward or "false" to go backward, but this should almost always be true.
Description:
Returns the layout of a wizard page. The output is a tag called <wizardPage>. Inside that tag is a collection of <control> tags. Each of the <control> tags has attributes for name, class, windowText, styles, xStart, yStart, width, height, enabled, data, option, and associations of a control on the wizard page.
Properties:
templateName: Internal name of workbook template, as defined in tmpl.cfg.
currentDialog: Name of wizard page as defined in tmpl.cfg or returned by <GetNextWizardDialog>.
Description:
Select which positions should be included in the workbook. The <position> child tags are sent in the same message as the <SelectPositions> tag. <GetNextWizardDialog> must be called to navigate to the correct wizard page before calling <SelectPositions>. This is typically used on two-tree wizard pages.
Properties:
templateName: Internal name of workbook template, as defined in tmpl.cfg.
currentDialog: Name of wizard page defined by the template configuration file.
Children:
<position>
Properties:
dimension: Dimension that contains the position.
name: Name of the position.
Description:
This allows explicit control over the UI elements within each page of the wizard. This enables operations beyond simple workbook builds. This is typically used on custom wizard pages.
Properties:
templateName: Internal name of workbook template, as defined in tmpl.cfg.
currentDialog: Name of wizard page defined by the template configuration file.
name: UI control name.
class: UI control class.
The control classes include Edit, DropDownList, Listbox, Groupbox, Checkbox, RadioButton, Text, SingleHierSelect, Tree, SuperTree, DatePicker.
The string "true" or "false" is used set radio buttons and check boxes.
The following example illustrates this use in the context of AutoWorkbook builds.
<!-- Create the workbook --> <WizardInitialize templateName="AutoWb" /> <!-- AutoWorkbookPage0 - select action --> <GetNextWizardDialog templateName="AutoWb" forward="true" /> <SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage0" name="addWb" class="RadioButton">true</SetWizardData> <!-- AutoWorkbookPage1 - select template --> <GetNextWizardDialog templateName="AutoWb" forward="true" /> <SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage1" name="ListBox" class="Listbox">R_TEST</SetWizardData> <!-- AutoWorkbookPage2 - select owner --> <GetNextWizardDialog templateName="AutoWb" forward="true" /> <SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage2" name="ListBox" class="Listbox">adm</SetWizardData> <!-- AutoWorkbookPage3 - enter scheduling data --> <GetNextWizardDialog templateName="AutoWb" forward="true" /> <SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3" name="BuildLabel" class="Edit"><value>RTD Auto Build WB</value></SetWizardData> <SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3" name="BuildFrequency" class="Edit">1000</SetWizardData> <SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3" name="NextBuildDate" class="Edit">05/05/2010</SetWizardData> <SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3" name="GroupAccess" class="RadioButton">true</SetWizardData> <SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3" name="groupNames" class="Listbox">adm</SetWizardData> <!-- … workbook build details omitted … --> <WizardFinish templateName="AutoWb />
Description:
Finish the wizard and build the workbook. After calling this, call rtd_getResponseProperty("workbookName") to get the internal name of the newly created workbook. Wizard-only templates do not have a workbookName and often provide an INFO message. If the workbook cannot be built, an ERROR message is returned. Use rtd_getResponseProperty("ERROR") to check the error message and
rtd_getResponseProperty("INFO") to check the info message.
Properties:
templateName: Internal name of workbook template, as defined in tmpl.cfg.
After a workbook has been created through the wizard process, it must be opened and manipulated. These functions do this for any created workbook.
Description:
Open an existing workbook.
Properties:
workbookName: Internal name of a stored workbook of the form "txxx" where the x's represent a variable number of digits. If the workbook was just created by the wizard process, use the value returned by rtd_getResponseProperty(). See <WizardFinish> above.
access [optional]: Currently unused.
Description:
Fetch data from the workbook.
Properties:
workbookName: Internal name of a stored workbook. See <OpenWorkbook> for more information.
windowName: Internal name of the window on which this measure is located as defined by tmpl.cfg.
Children:
<WindowContext>: Tag that defines what hierarchies and dimensions would be visible if there was a screen. At a minimum, the dimensions of the current cell need to be specified. There should only be one tag per hierarchy.
Properties:
hierarchy: Name of hierarchy.
Children:
<dimension>: Tag that represents the name of a dimension.
Properties:
value: Name of the dimension.
<position>: Tag that represents a position of the cell.
Properties:
dimension: Dimension that contains the position.
name: Name of the position.
hier: Hierarchy that contains the dimension.
axis: Location of this position in the grid if this was on the screen. Values are "row",
"column" or "page".
Description:
Set the values of cells in the workbook.
Properties:
worksheet: Name of sheet as defined in tmpl.cfg.
measure: Measure whose value should be set.
spreadMeasure [optional] - Currently unused.
spreadMethod: Method to use when spreading this cell to lower level cells. See the RPAS Configuration Tools User Guide for more information.
value: Desired value of the cell.
type: Type of cell. More accurately, this is the type of the measure. Locate this by examining the configuration of the domain with the Oracle RPAS Configuration Tools.
Children:
<WindowContext>: Tag that defines what hierarchies and dimensions would be visible if there was a screen. At a minimum, the dimensions of the current cell need to be specified. There should only be one tag per hierarchy.
Properties:
hierarchy: Name of hierarchy.
Children:
<dimension>: Tag that represents the name of a dimension.
Properties:
value: Name of the dimension.
<position>: Tag that represents a position of the cell.
Properties:
dimension: Dimension that contains the position.
name: Name of the position.
Description:
Transfer the data in the workbook back to the domain.
Properties:
synchronous [optional]: If "true", the workbook commits the data now. Otherwise, it is the same as "commit later".
asap [optional]: If "true", the workbook is added to the server's commit ASAP queue.
If the 'synchronous' option is "true", then the 'asap' option is ignored. If both 'synchronous' and 'asap' are omitted or blank, then the default is to commit data now.
Description:
Overwrite the data in the workbook with data from the domain.
Properties:
refreshGroup [optional]: If a workbook has several refresh groups, you may specify the one to use here. If omitted or blank, the default group is used.
Description:
Execute a custom menu event in the current workbook.
Properties:
id: The numeric ID of the custom menu event. The IDs start at 1 and are in the same order as they appear in the Dynamic Template configuration file.
expectedCaption [optional]: Specifies the caption that should be returned. Success is false if the returned caption is different. The return caption is not validated if this is blank.expectedText [optional]: Specified the text that should be returned. Success is false if the returned text is different. The returned text is not validated if this is blank.
Description:
Create a new percent of parent measure (also known as percent participation).
Properties:
window: The name of the window that the new measure is added to.
measure: The name of the "parent" measure for the new percent of parent measure.
hier [optional]: The hierarchy name for a relative percent of parent measure.
hiers [optional]: All hierarchies for an absolute percent of parent measure. Hierarchy names are delimited by a space.
dims [optional]: All dimensions for an absolute percent of parent measure. Dimension names are delimited by a space.
|
Note: Either 'hier' or both 'hiers' and 'dims' must be specified. Both may not be specified. Specifying 'hier' indicates that the percent of parent measure is relative. Specifying both 'hiers' and 'dims' indicates that the percent of parent measure is absolute. 'hiers' and 'dims' are parallel arrays and their order must match. |
Description:
Save the workbook to work on later.
Properties:
workbookLabel: Label (displayed name) for the workbook
workbookName: Internal name of a stored workbook. See <OpenWorkbook> for more information.
user: Access for the current user. Values are "NONE", "READ" or "WRITE".
group: Access for the named group. Values are "NONE", "READ" or "WRITE".
groupName: Name of the group for the above access value.
world: Access for the rest of the world. Values are "NONE", "READ" or "WRITE".
close: Close workbook. Values are "true" or "false".
In this section, familiarity with HP LoadRunner is assumed. For further information on this topic, consult the HP LoadRunner documentation.
The RTD library is not a LoadRunner extension and as such does not provide support for record and replay functionality. Scripts must be hand-coded to suit the RPAS workflow under test and only then can they be replayed using the message passing functions outlined in the previous section.
RTD functions can be called from any C-based virtual user (vuser). The script must reference a header that contains the RTD function prototypes. Additionally, certain LoadRunner replay settings must be set in order to assure correct behavior.
This file contains the functions exported by the RTD library; these are in a format usable by the LoadRunner C runtime engine.
#ifndef _RTD_RTD_H_
#define _RTD_RTD_H_
int rtd_logon(const char* user,
const char* password,
const char* connection,
const char* domain,
const char* fcfPath,
const char* language,
const char* logLevel);
int rtd_logon_ex(const char* user,
const char* password,
const char* connection,
const char* domain,
const char* fcfPath,
const char* language,
const char* logLevel,
const char* domainRootDirectory);
void rtd_logoff();
int rtd_send(const char* request);
char* rtd_getResponse();
char* rtd_getResponseProperty(const char* property);
void rtd_freeCharPtr(char* ptr);
#endif // _RTD_RTD_H_
This section contains the details of LoadRunner scripting.
RTD is not thread-safe and so the virtual user script must be run as a process rather than a thread:
Open run-time settings
Miscellaneous section
Select "Run Vuser as a process"
|
Note: Failure to do this will result in unpredictable and often inexplicable failures at runtime. |
All LoadRunner C-based scripts consist of three sections:
vuser_init
Actions
vuser_end
It is recommended that the vuser_init section is used for initialization and the body of the test placed in the Actions section. The vuser_end section is typically left unused.
This section walks through two examples that validate that LoadRunner and RTD are working correctly together.
The vuser_init section, which can be common to all RTD scripts, deals with the DLL load. In order for it to load correctly, the directory containing the library must be in your system PATH. The DLL load should work without the PATH setting, but results can vary from machine to machine. Explicitly setting the PATH guarantees success.
#include lr_rtd.h
#define RTD_LIBRARY "c:\\path\\to\\rtd.dll"
vuser_init {
int rc = lr_load_dll(RTD_LIBRARY);
if (rc!=0) {
lr_error_message("rtd library did not load (rc=%d). Not in your %PATH%?", rc);
lr_abort();
}
}
This section references the lr_rtd.h interface file defined previously. If it is not in the script directory, it must be prefaced by the full path.
The Actions section contains user actions; these vary on a case-by-case basis. This example uses a simple script to check that the RTD and LR integration is working correctly.
Action {
rtd_logon("user", "pwd", "connect", "dom", "c:\\path\\to\\Foundation.fcf", "english", "debug");
lr_think_time(60);
rtd_logoff(); }
This example causes the virtual user to log on, sleep 60 seconds, and then log off. The login details should be altered to suit the RPAS environment under test. If this succeeds, then RTD is correctly installed.
The following is a more realistic example.
In this more complicated example, a workbook is created and the name retrieved. It is then opened and closed. Additionally, rather than having multiple rtd_send() calls in-line, the XML is placed within a LoadRunner parameter file. This is then iterated over within the LoadRunner script.
The parameter file must consist of one complete XML entity per line, single column called "command" with the following contents.
<Logon … />
<WizardInitialize templateName="perftest"/>
<GetNextWizardDialog templateName="perftest" forward="true"/>
<SelectPositions templateName="perftest" currentDialog="wiz_PerfTestphsd" hierarchy="PHSH" dimension="PHSD"><position dimension="PHSD" name="PHSDP001"/></SelectPositions>
<GetNextWizardDialog templateName="perftest" forward="true"/>
<SelectPositions templateName="perftest" currentDialog="wiz_PerfTestweek" hierarchy="CLND" dimension="WEEK"><position dimension="WEEK" name="WEEK200801"/><position dimension="WEEK" name="WEEK200802"/></SelectPositions>
<GetNextWizardDialog templateName="perftest" forward="true"/>
<SelectPositions templateName="perftest" currentDialog="wiz_PerfTestitem" hierarchy="PROD" dimension="ITEM"><position dimension="ITEM" name="ITM000"/><position dimension="ITEM" name="ITM001"/></SelectPositions>
<WizardFinish templateName="perftest"/>
get_wb_name
<OpenWorkbook workbookName="{_wb}" access="write"/>
<CloseWorkbook method="backwards"/>
<Logoff/>
The vuser_init section must be identical to the prior example.
The Actions section must contain the following:
Action {
char *wb_name, *xml, *response;
int success;
while(…) {
if (0==stricmp("get_wb_name", script.param)) {
wb_name=rtd_getResponseProperty("workbookName");
lr_save_string(wb_name, "_wb");
rtd_freeCharPtr(wb_name);
} else {
rc=rtd_send(lr_eval_string(xml));
if (!rc) {
response=rtd_getResponse();
lr_error_message("error - response was: %s", response);
rtd_freeCharPtr(response);
lr_abort();
}
}
}
The above section accomplishes a number of things:
Uses parameters instead of hard-coded calls
Builds a workbook through the wizard
Obtains the workbook name
Saves the workbook name to the _wb parameter name
Replaces subsequent instances of the _wb parameter with the workbook name, through lr_eval_string()
When RTD is used in a scenario orchestrated by the LoadRunner controller, it is necessary to have RTD on each of the load generators (injectors). RTD must be in the same path, referenced in the LoadRunner script, on each generator.
Check the script runtime settings for the scenario. Match those used within the virtual user generator (vugen) environment.
Ensure that if RTD is upgraded, it is upgraded on each generator.
