Custom Adapter Reference

prevnext

Custom Recorder Adapter API


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

Function Description
IsCustomRecorderAdapter() Identifies a Custom Recorder Adapter.
InitializeRecorder() Performs initialization procedures.
StartRecording() Starts recording a session.
StopRecording() Concludes a recording session.
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.


IsCustomRecorderAdapter()

Identifies a Custom Recorder Adapter.


Syntax

BOOL IsCustomRecorderAdapter();

Comments

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


Example

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

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

See Also

IsCustomScriptgenAdapter()


InitializeRecorder()

Performs initialization procedures.


Syntax

int InitializeRecorder (TCHAR *errorMessage, size_t 
errorMessageSize);


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


Comments

Initialization procedures are optional and adapter-defined. A return of RSR_SUCCESS indicates that the adapter is prepared to begin recording a session on request.


Example

extern "C"
int LINKDLL InitializeRecorder (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

StartRecording(), StopRecording()


StartRecording()

Starts recording a session.


Syntax

int StartRecording (TCHAR *sessionPath, size_t sessionPathSize, 
StatusCallbackPtr fPtr, TCHAR *errorMessage, size_t 
errorMessageSize);


Element Description
sessionPath INPUT. Pointer to a read-only location containing the session file's path name, without extension.
sessionPathSize INPUT. The size allocated of sessionPath.
fPtr INPUT. Pointer to a Robot-defined callback function that communicates the adapter's status. The function has this signature:
fPtr (msgType, "status message");
msgType may be one of the following:

RSR_CALLBACK_PROGRESSRSR_CALLBACK_STOPRSR_CALLBACK_ERROR.

errorMessage Pointer to a container for a message to be displayed if recording fails to start. Copy the message to this location.
errorMessageSize INPUT. The size allocated for errorMessage, which cannot exceed this size.


Example

This example starts recording into an XML session file.

extern "C" 
int LINKDLL StartRecording(TCHAR* pathname,
                            size_t pathnameSize,
                            StatusCallbackPtr fPtr,
                            TCHAR* errorMessage,
                            size_t errorMessageSize)
{
    TCHAR buf[1024];
    _tcscpy (buf, "Start recording to: ");
    _tcscat(buf, pathname);
    MessageBox(NULL, buf,"", MB_OK);
    
    TCHAR fileName[1024];
    _tcscpy(fileName, pathname);
    _tcscat(fileName, ".xml");
    ofstream of (fileName);
    if (of)
        of << "<?xml version=\"1.0\" ?>\n<Sample>\n </Sample>" << endl;

    fPtr(RSR_CALLBACK_PROGRESS, "I am doing OK");
    return RSR_SUCCESS;
}

See Also

InitializeRecorder(), StopRecording()


StopRecording()

Concludes a recording session.


Syntax

int StopRecording (TCHAR *errorMessage, size_t 
errorMessageSize);


Element Description
errorMessage Pointer to a container for a message to be displayed in case there is 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 ends a recording session. Stop recording and return RSR_SUCCESS.

If you return RSR_BUFFER_TOO_SHORT to indicate that the initial errorMessageSize is too small, Robot loops until errorMessageSize is large enough to contain errorMessage.


Example

extern "C" 
int LINKDLL StopRecording(TCHAR* errorMessage, 
                          size_t errorMessageSize)
{
	 //stop recording
	 if (successful)
	 	 return RSR_SUCCESS
	 else
	 {
	 	 TCHAR buf[] = "Couldn't stop!!!";
	 	 if (_tcslen(buf) >= errorMessageSize)
	 	 	 return RSR_BUFFER_TOO_SHORT;

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

See Also

InitializeRecorder(), StartRecording()


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 Recorder 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. Adapter-defined options have the format: name,value,description[,value1, value2, ...valuen] Adapter-defined options that you return in response to this call appear on the Method:Custom tab of the Robot Session Record Options dialog. They can also appear on an adapter-supplied GUI.
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.

Your adapter can define a custom format for options and provide a custom GUI for displaying and editing them and code to communicate the user's choices to the adapter. Do not include custom-format options in your response to this call.

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

Configuration Option Description
CONFIGURATION, USE_CUSTOM_UI Specifies that the adapter provides a custom GUI for displaying and selecting adapter-defined configuration options.
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 Method:Custom tab 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.
DEFAULT_SCRIPT_GENERATOR, sga Specifies the name of the companion Custom Script Generator Adapter for this Custom Recorder Adapter. Enter the adapter's display name as specified with GetDisplayName().
GENERAL_START_APP_PROMPT On the General tab of the Session Record Options dialog, the Prompt for application name on start recording check box is enabled.
RECORD_BLOCK On the Session Insert dialog and the Insert menu, the Start Block and Stop Block options are enabled.
RECORD_COMMENT On the Session Insert dialog and the Insert menu, the Comment option is enabled.
RECORD_SPLITS On the Session Record dialog, the Split Script icon is enabled.
RECORD_SYNC_PT On the Session Insert dialog and the Insert menu, the Sync point option is enabled.
RECORD_TIMER On the Session Insert dialog and the Insert menu, the Start timer and Stop timer options are enabled.
RECORD_START_APP On the Session Insert dialog and the Insert menu, the Start Application option is enabled.
SESSION_FILES, format Specifies the file format(s) and extension(s) of the session file(s), which can be one or more of the following:
  • RSR_SESSION_FILE_EXT -- user-defined type, extension .ext.

  • RSR_SESSION_FILE_EXT -- XML format, extension .xml. (The BEA WebLogic recorder uses this format).

  • RSR_SESSION_FILE_EXT -- Rational's proprietary trace file format (called a watch file), extension .wch. API Recorder Adapters use this format.


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, SESSION_FILES);
	 _tcscat(buf, _T(",xml"));
	 _tcscat(buf, _T(";"));
	 _tcscat(buf, DEFAULT_SCRIPT_GENERATOR);
	 _tcscat(buf, _T(",mySGA"));
	 _tcscat(buf, _T(";"));
	 _tcscat(buf, RECORD_SPLITS);
	 _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 or edits an adapter-defined option, this call communicates the user's choice to your adapter.

This call also returns a user's choices for adapter-defined options, in the triplet format, that were selected from a Robot-provided dialog. However, if you use a custom GUI for displaying and editing custom options, you are responsible for reading the dialog, conveying the user's choices to the adapter, parsing, validation, and sending an appropriate error message for invalid user specifications.


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 Method:Custom 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