A reference to a Kwd_List object is passed into every stub function. The Kwd_List object contains all the parameters for the current alias name. Through operations on the Kwd_List object, values of parameters may be set or retrieved from the current alias the test script. By referencing the same Kwd_List parameter, two or more stub functions can share a parameter. Each Kwd_List is a List object. Each item "on the" Kwd_List is also an object and consists of a Keyword and a Value. Both Keyword and Value are IString objects. Think of the Keyword as that parameter's "ASCII handle" and Value as the current content or value of that parameter. The DDTT creates an entry for each parameter keyword specified in the associated grammar file for the current DDTT alias. Thus, the stub function's view of the Kwd_List object is primarily that of accessing and updating the existing entries in the Kwd_List.

The following constructor method is available to create Kwd_List objects:

   Kwd_List();            // Creates an empty list

The following methods are available for Kwd_List objects:

   // Add or update a keyword-value pair in the  Kwd_List
   void set(IString kwd, IString value);

   // Remove a keyword-value pair from the Kwd_List
   void unset(IString kwd);

   // Return an sscanf'd int corresponding to a keyword
   long int getInt(IString kwd);

   // Return an sscanf'd pointer corresponding to a keyword
   void * getPtr(IString kwd);

   // Return true if the keyword is known
   BOOL isKeyword(IString kwd);

   // Return the number of entries in the Kwd_List
   int nKey();

   // Return a pointer corresponding to the FILES keyword
   FileInfo * files();

The following overloaded operator methods are available for Kwd_List objects:

   // Return the corresponding value to a keyword
   IString operator[](IString kwd);

   // Numerically indexes the list, return  keyword-value
   void operator()(int inx, IString& kwd, IString& value);

Below is a declaration of a sample stub function:

   #include "kwdlist.h"
   .
   .
   APIRET SampleStubFtn( Kwd_List &param )
   { // code here };

The only parameter to all stub functions must be a Kwd_List object reference. Assume the grammar file specifies the following parameter keywords:

DEVICENAME
READTRYS
BUFFERCOUNT
OUTPUTBUFFER

Also assume that input kwd_list reference is named param, as in the above example stub declaration.

To access DEVICENAME as an IString use the overloaded operator: []

   IString name;
   .
   .
   .
   name = param["DEVICENAME"];

The overloaded operator [] expects an IString object as input, (an input variable of type const char * works also, because const char * can convert themselves to IString objects). The [] operator then automatically converts to IString, performs the lookup in the Kwd_List, param, and returns a copy of the value associated with the parameter keyword. A stub function can change the current Value of an item on the input Kwd_List by way of the set method.

   param.set("READTRYS", (long)6);

This function sets the current value of the READTRYS parameter keyword to 6. This procedure will overwrite any value set in the test case script file to this point in the script file's execution.

Keyword parameter values can be retrieved as long integers and pointers respectively, by way of the getInt getPtr methods:

   long loop_cnt;
   char * huge_buf;
   .
   .
   .
   loop_cnt = param.getInt("READTRYS");
   huge_buf = param.getPtr("OUTPUTBUFFER");

The unset method has a more permanent effect on the input parameter's keyword param.unset("READTRYS");.

This unset operation removes READTRYS from Kwd_List. After executing this method, any future reference to the READTRYS parameter keyword within the execution of the current DDTT alias would return an empty IString object. The unset method drops the entire Keyword and Value pair from the input Kwd_List. As such, the unset method should be used with caution!

The isKeyword method tests the Kwd_List object to determine if the specified parameter keyword is currently in the Kwd_List object.

   int test;
   .
   .
   // This will return TRUE
   test = param.isKeyword("READTRYS");
   // This will return FALSE.
   test = param.isKeyword("RETRYCNT");

Returns TRUE if the keyword is on the list, FALSE otherwise.

   int kwd_count;
   .
   .
   kwd_count = param.nKey();

Returns the number of keywords currently in the Kwd_List object.

By convention, keywords that begin with a "$" character are built-in, automatic variables. Existing #define macros in the DDTKWDS.H file ensure proper error checking by the compiler. For example:

   // Pointer to associated FileInfo object
   #define FILES_KEY   "$FILES"
   // Pointer to associated BufferList object
   #define BUFFER_LIST "$BUFFERLIST"
   // Current DO, FOR loop index value
   #define COUNTER     "$I"

Access to the protected log file output stream is obtained through the $FILES parameter keyword. The required C++ syntax is relatively complicated; therefore, a special Kwd_List method, files(), is provided to simplify access to the standard logging output stream:

   IString s1;
   .
   .
   param.files()->out1<<s1;