Recording and Script Generation Services

prevnext

The GetAnnotations() Service Function


Script Generation Options describes features that API Recorder Adapters must support and that Custom Recorder Adapters can support. These features allow Robot users to insert comments, synchronization points, start/end blocks, and start/end timers at specified locations inside generated test scripts. If a user specifies these options, they are automatically recorded in an annotations file. Your script generator adapter is then responsible for reading this file and placing the requested code in the test script. You use the GetAnnotations() call to access the entries in the annotations file.


GetAnnotations()

Reads the annotations file.


Syntax

int GetAnnotations(TCHAR sessionName[], int insertType, TCHAR 
*insertVal, int *insertValSize)


Element Description
sessionName Enter the name of the session file that the annotations file you are reading is associated with. For custom recordings, the session file name is an input argument included with StartRecording(). For API recordings, the session file name is returned to the API Script Generator Adapter by SetOptions().
insertType Enter one of the following values indicating the type of insert to be retrieved:
  • RSR_ANNOTATION_SPLITS

  • RSR_ANNOTATION_COMMENTS

  • RSR_ANNOTATION_TIMERS

  • RSR_ANNOTATION_BLOCKS

  • RSR_ANNOTATION_SYNC_PTS

If multiple inserts of this type are present, all are returned.
insertVal OUTPUT. After a successful call, insertVal contains all insertions of the specified type in the annotations file.
insertValSize Pointer to the size of insertVal. If this size is too small, the required size is returned.


Return Value


Comments

The first line of the annotations file contains an integer representing the base time at the creation of the session file. All other lines in the file contain time stamps that are offsets relative to the base time. A script generator adapter uses these offsets in order to determine placement of the insertion in the generated test script.

Following is a sample annotations file containing these insertion requests: two split-scripts, one comment, two synchronization points, two start/stop blocks, and two start/stop timers.

995471049
79334, script_1
86794, script_2
71792, comment 1
35000, sync point 1
61479, sync point 2
29712, 50763, block 1
55941, 79334, block 2
24035, 79294, timer 1
41699, 79334, timer 2

If called with argument RSR_ANNOTATION_SPLITS, GetAnnotations() returns the first three lines; with argument RSR_ANNOTATIONS_COMMENTS, lines 1 and 4; with argument RSR_ANNOTATIONS_TIMERS, the first and last two lines are returned -- and so on.


Example

This example queries the annotations file for insertions of type RSR_ANNOTATION_SPLITS.

	 //specify size of reply buffer
	 int ReplySize = 1024;
	 
	 //dynamically allocate the reply buffer
	 TCHAR *ReplyBuffer = new TCHAR[ReplySize];
	 
	 //call GetAnnotations and react according to its return flag.
	 
switch(GetAnnotations(tchar(SessionName),RSR_ANNOTATION_SPLITS,ReplyBu
ffer,&ReplySize))
	 {
	 case RSR_SUCCESS:
	 	 //you have your request in Reply buffer
	 	 TRACE("\n");
	 	 TRACE(ReplyBuffer);
	 	 TRACE("\n\n");
	 	 break;
	 case RSR_OBJECT_DOES_NOT_EXIST:
	 	 //no split-script insertion requests were present
	 	 break;
	 case RSR_BUFFER_TOO_SHORT:
	 	 //your buffer was too short. Call again with needed size.
	 	 delete ReplyBuffer;
	 	 ReplyBuffer = new TCHAR[ReplySize];
	 	 
switch(GetAnnotations(tchar(SessionName),RSR_ANNOTATION_SPLITS,ReplyBu
ffer,&ReplySize))
	 	 {
	 	 case RSR_SUCCESS:
	 	 	 //you have what you asked for in ReplyBuffer
	 	 	 TRACE("\n");
	 	 	 TRACE(ReplyBuffer);
	 	 	 TRACE("\n\n");
	 	 	 break;
	 	 default:
	 	 	 ASSERT(FALSE);
	 	 }
	 	 break;
	 case RSR_FAILURE:
	 default:
	 	 ASSERT(FALSE);

prevnext


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