Custom Script Generator Adapter API

prevnext

Custom Script Generator Adapter API


Use this API to develop a script generator adapter to be used with a Custom Recorder Adapter. Use API Script Generator Adapter API to develop a script generator adapter to be used with the API recording method.

Custom Script Generator Adapters implement the following calls. The shaded rows list functions that other adapter types also implement.

Function Description
IsCustomScriptgenAdapter() Identifies a Custom Script Generator Adapter.
InitializeScriptgen() Performs initialization procedures.
StartScriptgen() Starts a script generation session.
CancelScriptgen() Cancels a script generation request.
GetDisplayName() Returns the public name of this adapter.
GetOptions() Returns configuration options in effect for this adapter.
SetOptions() Sets user-specified configuration options for this adapter.
DisplayCustomConfigGUI() Provides a custom GUI for adapter-defined configuration options.


IsCustomScriptgenAdapter()

Identifies a Custom Script Generator Adapter.


Syntax

BOOL IsCustomScriptgenAdapter();

Comments

Return TRUE to indicate that this is a Custom Script Generator Adapter. Any other response disables the adapter.


Example

A C adapter should respond to this call as illustrated below.

extern "C"
BOOL LINKDLL IsCustomScriptgenAdapter()
{
	 return TRUE;
}

See Also

IsCustomRecorderAdapter()


InitializeScriptgen()

Performs initialization procedures.


Syntax

int InitializeScriptgen (TCHAR *errorMessage, size_t 
errorMessageSize);


Element Description
errorMessage Pointer to a container for a message to be displayed in case there is an initialization error. Copy the message to this location.
errorMessageSize INPUT. The size allocated for errorMessage, which cannot exceed this size.


Comments

In response to this call, perform any needed initialization procedures and return RSR_SUCCESS.


Example

extern "C"
int LINKDLL InitializeScriptgen (TCHAR *errorMessage, size_t 
errorMessageSize)
{
	 //perform initialization procedures
	 if (successful)
	 	 return RSR_SUCCESS
	 else
	 {
	 	 TCHAR buf[] = "Recorder failed to initialize";
	 	 if (_tcslen(buf) >= errorMessageSize)
	 	 	 return RSR_BUFFER_TOO_SHORT;

	 	 _tcscpy(errorMessage, buf);
	 	 return RSR_FAILURE;
	 }
}

See Also

CancelScriptgen(), InitializeRecorder(), StartScriptgen()


StartScriptgen()

Starts a script generation session.


Syntax

int StartScriptgen (TCHAR *sessionPath, size_t sessionPathSize, 
TCHAR *scriptPath, size_t scriptPathSize, StatusCallbackPtr 
fPtr, TCHAR *errorMessage, size_t errorMessageSize);


Element Description
sessionPath INPUT. Pointer to a location containing the session file's path name, without extension.
sessionPathSize INPUT. The size allocated for sessionPath, which cannot exceed this size.
scriptPath INPUT. Pointer to a location for the script file's path name, without extension.
scriptPathSize INPUT. The size allocated for scriptPath, which cannot exceed this size.
fPtr Pointer to a Robot-defined callback function for communication of completion status. The function has this signature: fPtr (msgType, "status message"); msgType can be one of the following:

RSR_CALLBACK_DETAILSRSR_CALLBACK_ERRORRSR_CALLBACK_FINISHEDRSR_CALLBACK_PROGRESSRSR_CALLBACK_STOP

As shown in the example, with msgType RSR_CALLBACK_PROGRESS, the status message is a number between 0 and 100, indicating percent completed, formatted as a string.
errorMessage Pointer to a location for a message to be displayed in case of a startup error.
errorMessageSize INPUT. The size allocated for errorMessage, which cannot exceed this size.


Comments

Respond to this call by starting script generation and returning RSR_SUCCESS.


Example

The following example provides progress information in 10% intervals and parses for multiple script names.

extern "C" 
int LINKDLL StartScriptgen(TCHAR* pathname,
                           size_t pathnameSize,
                           TCHAR* scriptFilePathnames, 
                           size_t scriptFilePathnamesSize,
                           StatusCallbackPtr fPtr,
                           TCHAR* errorMessage,
                           size_t errorMessageSize)
{
    
 
	 CStringArray ScriptNames;

	 for (int i=1; i<=10; i++)
    {
        TCHAR progress[5];
	 	 sprintf(progress,"%d",i*10);
	 	 fPtr(RSR_CALLBACK_PROGRESS, progress);
        Sleep(1000);
    }
	 
	 
	 ParseString(scriptFilePathnames,';',&ScriptNames);
	 
	 
	 for(i = 0;i<ScriptNames.GetSize();i++)
	 {
	 	 CopyFile("c:\\seed.java",ScriptNames[i]+".java",FALSE);
	 }
    fPtr(RSR_CALLBACK_FINISHED, "Scriptgen successful!!!");
    
    return RSR_SUCCESS;
}

See Also

CancelScriptgen(), InitializeScriptgen(), StartRecording()


CancelScriptgen()

Cancels a script generation request.


Syntax

int CancelScriptgen (TCHAR *errorMessage, size_t 
errorMessageSize);


Element Description
errorMessage Pointer to a container for a message to be displayed in case of a cleanup error. Copy the message to this location.
errorMessageSize INPUT. The size allocated for errorMessage, which cannot exceed this size.


Comments

This call is made when a Robot user cancels script generation, or in case of a system error. On receiving the call, stop script generation as soon as possible, perform cleanup operations, and return RSR_SUCCESS.


Example

extern "C" 
int LINKDLL CancelScriptgen(TCHAR* errorMessage, 
                          size_t errorMessageSize)
{
	 //stop scriptgen and perform cleanup
	 if (successful)
	 	 return RSR_SUCCESS
	 else
	 {
	 	 TCHAR msg[] = "Cancellation cleanup failed";
	 	 if (_tcslen(buf) >= errorMessageSize)
	 	 	 return RSR_BUFFER_TOO_SHORT;

	 	 _tcscpy(errorMessage, buf);
	 	 return RSR_FAILURE;
	 }
}

See Also

InitializeScriptgen(), StartScriptgen()


GetDisplayName()

Returns the public name of this adapter.


Syntax

int GetDisplayName (TCHAR *name, size_t nameSize);


Element Description
name Pointer to a container for the adapter's display name. Copy the name to this location.
nameSize INPUT. The size allocated for name. The adapter's display name cannot exceed this size.


Comments

Specify the GUI name for this adapter. This name is presented to the Robot user (in the Script Generator list box beside the Use Custom radio box) on the Method tab of the Session Record Options dialog.


Example

This example specifies that the GUI name of this adapter is rtweblogicEJB.

extern "C"
int LINKDLL GetDisplayName (TCHAR *name, size_t nameSize)
{
	 TCHAR buf[] = "rtweblogicEJB";
	 if (_tcslen(buf) > nameSize)
	 	 return RSR_BUFFER_TOO_SHORT;

	 _tcscpy(name, buf);
	 return RSR_SUCCESS;
}

GetOptions()

Returns configuration options in effect for this adapter.


Syntax

int GetOptions (TCHAR *options, size_t optionsSize);


Element Description
options Pointer to a container for this adapter's options. Copy supported options, separated by semicolons, to this location. Robot-defined options have the format: argument[,setting] where argument is one of the strings described in the options table shown below, and setting can be a value for the argument. Generator:Custom
optionsSize INPUT. The size allocated by Robot for options, which must not exceed this size.


Comments

As illustrated in the example, options supported by an adapter should be entered from a saved, local file. Otherwise, they do not persist between sessions.

The following table describes the Robot-defined configuration option arguments that a Script Generator Adapter can support. See Adapter Configuration on page 81 for a mapping of these options to the Robot GUI.

Configuration Option Description
CONFIGURATION, name, value, description [,value1, value2 ...] The adapter supports a configuration option of the specified name and value, which works as indicated by the description. Adapter-defined options may be entered either from the Generator:Customtab of the Session Record Options dialog or from a supplied custom GUI. If a configuration triplet includes [, value1, value2, ...] , the supplied values are implemented by a value pull-down menu on the grid.
GENERATOR_BIND_VU_VARS On the Generator tab of the Session Record Options dialog, the Bind output parameters to VU variables check box is enabled.
GENERATOR_COMMAND_ID On the Generator tab of the Session Record Options dialog, the Command ID prefix box is enabled.
GENERATOR_CPU_THRESH On the Generator tab of the Session Record Options dialog, the CPU/user threshold (ms) check box is enabled.
GENERATOR_DISPLAY_ROWS On the Generator tab of the Session Record Options dialog, the Display recorded rows boxes are enabled. The Robot user's choices are communicated by SetOptions() in the format: GENERATOR_DISPLAY_ROWS, choice, rows where:
  • choice is one of these values corresponding to the user's selection of None, First, Last, or All:

    RSR_DISPLAY_RECORDED_ROWS_NONE
    RSR_DISPLAY_RECORDED_ROWS_FIRST
    RSR_DISPLAY_RECORDED_ROWS_LAST
    RSR_DISPLAY_RECORDED_ROWS_ALL

  • rows is 0 (for All or None) or the specified number of rows.

GENERATOR_PLAYBACK_PACING On the Generator tab of the Session Record Options dialog, the Playback pacing radio boxes are enabled. The Robot user's choice of per command, per script, or none is communicated by SetOptions() as:

RSR_GENERATOR_PLAYBACK_PACING_
COMMAND
RSR_GENERATOR_PLAYBACK_PACING_
SCRIPT
RSR_GENERATOR_PLAYBACK_PACING_
NONE

GENERATOR_THINK On the Generator tab of the Session Record Options dialog, the Think maximum (ms) check box is enabled.
GENERATOR_USE_DATAPOOLS On the Generator tab of the Session Record Options dialog, the Use datapools check box is enabled.
GENERATOR_VERIFY_RETURN_CODES On the Generator tab of the Session Record Options dialog, the Verify playback return codes check box is enabled.
GENERATOR_VERIFY_ROW_COUNTS On the Generator tab of the Session Record Options dialog, the Verify playback row counts check box is enabled.
TEST_SCRIPT_TYPE, type Specifies the type of test script generated by this Script Generator Adapter; type may be one of the following indicating, respectively, Java, Visual Basic, or VU:

RSR_SCRIPT_TYPE_JAVA
RSR_SCRIPT_TYPE_VISUAL_BASIC
RSR_SCRIPT_TYPE_VU


Example

The following response indicates that this adapter:

extern "C" 
int LINKDLL GetOptions(TCHAR* options, size_t optionsSize)
{
	 TCHAR buf[RSR_MAX_OPTIONS];
	 _tcscpy(buf, _T(""));
	 _tcscat(buf, TEST_SCRIPT_TYPE);
	 _tcscat(buf, _T(","));
	 _tcscat(buf, _T(RSR_SCRIPT_TYPE_JAVA));
	 _tcscat(buf, _T(";"));
	 _tcscat(buf, GENERATOR_USE_DATAPOOLS);
	 _tcscat(buf, _T(";"));

	 if (_tcslen(buf) > optionsSize)
	 	 return RSR_BUFFER_TOO_SHORT;
	 _tcscpy(options, buf);
	 return RSR_SUCCESS;
}

See Also

SetOptions()


SetOptions()

Sets user-specified configuration options for this adapter.


Syntax

int SetOptions (TCHAR *options, size_t optionsSize);


Element Description
options INPUT. Pointer to a read-only location containing the Robot user's selections.
optionsSize INPUT. The size of options.


Comments

When the user selects or specifies a value for a Robot-defined option, this call communicates the user's choice to your adapter.

For Robot-defined options pertaining to script generation (those specified on the Generator tab of the Session Record Options dialog), this call communicates the user's choices using this format:

option[,choice][,value]

where:

For example, if your adapter supports option GENERATOR_THINK and a user checks this option and specifies a maximum of 5 milliseconds, the options argument of SetOptions() contains this value: GENERATOR_THINK,1,5. If the user does not check this option, SetOptions() returns this value: GENERATOR_THINK,0,0. Options are separated from one another by semicolons.


Example

This example checks to see whether a Robot user selected the Think maximum (ms) option.

extern "C" 
int LINKDLL SetOptions(TCHAR* options, size_t optionsSize)
{
	 /* CStringArray declared for parsed sub-strings */
	 CStringArray OptionsArray;

	 /* parse the original string with semi-colon delimeter.*/
	 ParseString(options,';',&OptionsArray);

	 for(int i = 0;i<OptionsArray.GetSize();i++)
	 {
	 	 /* for every sub-string, create another CStringArray*/
	 	 CStringArray SubArray;
	 	 if(!OptionsArray.GetAt(i).IsEmpty())
	 	 {
	 	 	 /*parse the substrings with comma delimeters */
	 	 	 ParseString (OptionsArray.GetAt(i).GetBuffer
	 	 	 	 (OptionsArray.GetAt(i).GetLength()),',',&SubArray);
	 	 	 
	 	 	 /* deal with each sub-string set */
	 	 	 if(SubArray[0]==GENERATOR_THINK)
	 	 	 {
	 	 	 	 if(SubArray[1] == 0)
	 	 	 	 {
	 	 	 	 int think_min = SubArray[2];
	 	 	 }
	 	 	 else
	 	 	 {
	 	 	 	 /* Unrecognized option -- error may be thrown*/
	 	 	 }
	 	 }
	 }
}

See Also

GetOptions()


DisplayCustomConfigGUI()

Provides a custom GUI for adapter-defined configuration options.


Syntax

int DisplayCustomConfigGUI (TCHAR *errorMessage, size_t 
errorMessageSize);


Element Description
errorMessage Pointer to a location for a message to be displayed in the event of error. Copy the message to this location.
errorMessageSize INPUT. The size allocated for errorMessage, which cannot exceed this size.


Comments

If your adapter specifies the option CONFIGURATION,USE_CUSTOM_UI, a Configure button on the Generator per Protocol tab of the Session Record Options dialog is enabled. If a user clicks this button, Robot issues this call. In response, your adapter should display a custom GUI for entering or editing custom configuration options.

If you provide a custom GUI:


Example

extern "C"
int LINKDLL DisplayCustomConfigGUI (TCHAR *errorMessage, size_t 
errorMessageSize)
{
	 //display custom GUI and gather user input
	 if (successful)
	 	 return RSR_SUCCESS;
	 else
	 {
	 	 TCHAR buf[] = "Custom GUI failed to start";
	 	 if (_tcslen(buf) > errorMessageSize)
	 	 	 return RSR_BUFFER_TOO_SHORT;

	 	 _tcscpy(errorMessage, buf);
	 	 return RSR_FAILURE;
	 }
}

See Also

GetOptions(), SetOptions()


prevnext


Session Recording Extensibility Reference Rational Software Corporation
Copyright (c) 2003, Rational Software Corporation http://www.rational.com
support@rational.com
info@rational.com