API Script Generator Adapter API

prevnext

API Script Generator Adapter API


Implement this API in a script generator adapter to be used with an API Recorder Adapter. Implement the Custom Script Generator Adapter API in a script generator adapter to be used with the custom recording method.

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

Function Description
IsAPISgenAdapter() Identifies an API Script Generator Adapter.
InitializeScriptgen() Performs initialization procedures.
ProcessAPIPacket() Receives an API packet for processing.
PassComplete() Returns the pass completion status.
GetStatus() Returns the progress status.
GetOptions() Returns configuration options in effect for this adapter.
SetOptions() Sets user-specified configuration options for this adapter.


IsAPISgenAdapter()

Identifies an API Script Generator Adapter.


Syntax

BOOL IsAPISgenAdapter();

Comments

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

This adapter is associated with a single Generator Filter Adapter. When a user selects the associated Generator Filter Adapter from the Generator Filtering tab and starts an API recording session, this adapter receives any scriptable packets that are exchanged between the AUT and the target.


Example

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

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

See Also

IsAPIRecorderAdapter(), IsAPIGenFiltExtAdapter()


InitializeScriptgen()

Performs initialization procedures.


Syntax

int InitializeScriptgen (TCHAR *scriptPathname);


Element Description
scriptPathname Pointer to a location containing the path name of the script file (stored inside the Rational datastore). The script filename base is supplied by the Robot user. If split scripts are supported, their names are generated from this base.


Comments

An initialization procedure sets up the output path for scripts and can perform other startup functions.


Example

This example illustrates a successful response.

extern "C"
int LINKDLL InitializeScriptgen (TCHAR *scriptPathname)
{
	 MessageBox(NULL, "InitializeScriptgen Called","Hello from APISgen 
Adapter Stub!", MB_OK);
	 return RSR_SUCCESS;
}

ProcessAPIPacket()

Receives an API packet for processing.


Syntax

int ProcessAPIPacket (void *packet, int IDNum);


Element Description
packet INPUT. Pointer to a container for the name of an API packet in the session file.
IDNum INPUT. The API packet ID assigned by the session controller.


Comments

The associated Generator Filter Adapter designated this packet as relevant for script generation.


Example

This example illustrates a successful response.

extern "C"
int LINKDLL ProcessAPIPacket (void *packet, int IDNum)
{
	 MessageBox(NULL, "ProcessAPIPacket Called","Hello from APISgen 
Adapter Stub!", MB_OK);
	 return RSR_SUCCESS;
{

See Also

CheckAPIPacket()


PassComplete()

Returns the pass completion status.


Syntax

int PassComplete (int passNumber);


Element Description
passNumber INPUT. The ID of the pass through the session file.


Comments

The packets in a session file are read by the session controller and presented to the Generator Filter Adapter, which designates packets that are relevant to script generation. There are usually multiple passes through the session file.

Return RSR_SUCCESS to indicate that script generation is progressing normally. Otherwise, return a nonzero integer and supply an appropriate error message.


Example

This example illustrates a successful response.

extern "C"
int LINKDLL PassComplete (int passNumber)
{
	 MessageBox(NULL, "PassComplete Called","Hello from APISgen Adapter 
Stub!", MB_OK);
	 return RSR_SUCCESS;
}

See Also

CheckAPIPacket(), ProcessAPIPacket()


GetStatus()

Returns the progress status.


Syntax

int GetStatus (TCHAr *msg, size_t msgSize);


Element Description
msg Pointer to a container for the status message to be displayed. Copy the message to this location.
msgSize INPUT. The size allocated for msg, which cannot exceed this size.


Comments

Return RSR_SUCCESS to indicate that script generation is progressing normally. Otherwise, return a nonzero integer and supply an appropriate error message.


Example

This example illustrates a successful response.

extern "C"
int LINKDLL GetStatus (TCHAR *msg, size_t msgSize)
{
	 MessageBox(NULL, "GetStatus Called","Hello from APISgen Adapter 
Stub!", MB_OK);
	 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.

This function returns the session file name, sessionfile, in this format:

GENERATOR_SESSION_NAME,sessionfile

You need this name in order to use the service call GetAnnotations() on page 70.


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()


prevnext


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