The IDL_KWProcessByOffset() function is used to process keywords. IDL_KWProcessByOffset() performs the following actions on behalf of the calling system routine:

  • Verify that the keywords passed to the routine are all allowed by the routine.
  • Carry out the type checking and conversions required for each keyword.
  • Find the positional (non-keyword) arguments that are scattered among the keyword arguments in argv and copy them in order into the plain_args array.
  • Return the number of plain arguments copied into plain_args.

IDL_KWProcessByOffset() has the form:

int IDL_KWProcessByOffset(int argc, IDL_VPTR *argv, 
   char *argk, 
   IDL_KW_PAR *kw_list,
   IDL_VPTR plain_args[], 
   int mask,
   void * base)

where:

argc

The number of arguments passed to the caller. This is the first parameter to all system routines.

argv

The array of IDL_VPTR to arguments that was passed to the caller. This is the second parameter to all system routines.

argk

The pointer to the keyword list that was passed to the caller. This is the third parameter to all system routines that accept keyword arguments.

kw_list

An array of IDL_KW_PAR structures (see Overview Of IDL Keyword Processing) that specifies the acceptable keywords for this routine. This array is terminated by setting the keyword field of the final struct to NULL ((char *) 0).

plain_args

NULL, or an array of IDL_VPTR into which the IDL_VPTRs of the positional arguments will be copied. This array must have enough elements to hold the maximum possible number of positional arguments, as defined in IDL_SYSFUN_DEF2. See Registering Routines.

Note: IDL_KWProcessByOffset() sorts the plain arguments into the front of the input argv argument. Hence, plain_args is often not necessary, and can be set to NULL.

mask

Mask enable. This variable is ANDed with the mask field of each IDL_KW_PAR struct in the array given by kw_list. If the result is non-zero, the keyword is accepted as a valid keyword for the called system routine. If the result is zero, the keyword is ignored.

base

Address of the user supplied KW_RESULT structure, which must be named kw.

Speeding Keyword Processing

As mentioned above, the kw_list argument to IDL_KWProcessByOffset() is a null terminated list of IDL_KW_PAR structures. The time required to scan each item of the keyword array and zero the required fields (those fields specified, and value fields with IDL_KW_ZERO set), can become significant, especially when more than a few keyword array elements (e.g., 5 to 10 elements) are present.

To speed things up, specify IDL_KW_FAST_SCAN as the first keyword array element. If IDL_KW_FAST_SCAN is the first keyword array element, the keyword array is compiled by IDL_KWProcessByOffset() into a more efficient form the first time it is used. Subsequent calls use this efficient version, greatly speeding keyword processing. Usage of IDL_KW_FAST_SCAN is optional, and is not worthwhile for small lists. For longer lists, however, the improvement in speed is noticeable. For example, the following list does not use fast scanning:

static IDL_KW_PAR	kw_pars[] = {
  { "DOUBLE", IDL_TYP_DOUBLE, 1, 0, 
     IDL_KW_OFFSETOF(d_there), IDL_KW_OFFSETOF(d) },
  { "FLOAT", IDL_TYP_FLOAT, 1,IDL_KW_ZERO,0,
     IDL_KW_OFFSETOF(f) },
  { NULL }
};

To use fast scanning, it would be written as:

static IDL_KW_PAR	kw_pars[] = { IDL_KW_FAST_SCAN,
{ "DOUBLE", IDL_TYP_DOUBLE, 1, 0, 
   IDL_KW_OFFSETOF(d_there), IDL_KW_OFFSETOF(d) },
{"FLOAT", IDL_TYP_FLOAT, 1, IDL_KW_ZERO, 0,
   IDL_KW_OFFSETOF(f) },
{ NULL }
};