IDL_KW_PAR

The IDL_KW_PAR struct provides the basic specification for keyword processing. The IDL_KWProcessByOffset() function is passed a null-terminated array of these structures. IDL_KW_PAR structures specify which keywords a routine accepts, the attributes required of them, and the kinds of processing that should be done to them. IDL_KW_PAR structures must be defined in lexical order according to the value of the keyword field.

The definition of IDL_KW_PAR is:

typedef struct { char *keyword;

   UCHAR type;

   unsigned short mask;

   unsigned short flags;

   int *specified;

   char *value;

} IDL_KW_PAR;

where:

keyword

A pointer to a null-terminated string. This is the name of the keyword, and must be entirely upper case. The array of IDL_KW_PAR structures passed to IDL_KWProcessByOffset() must be lexically sorted by the strings pointed to by this field. The final element in the array is signified by setting the keyword field to NULL ((char *) 0).

type

IDL_KWProcessByOffset() automatically converts the keywords to the IDL type specified by the type field. Specify 0 (IDL_TYPE_UNDEF) in cases where ID_KW_VIN or IDL_KW_OUT are specified in the flags field.

mask

The enable mask. This field is ANDed with the mask argument to IDL_KWProcessByOffset() and if the result is non-zero, the keyword is accepted. If the result is 0, the keyword is ignored. This ability allows you to share an array of IDL_KW_PAR structures between several routines, and enable or disable the keywords used by each one.

As an example of this, the IDL graphics and plotting routines have a large number of keywords in common. In addition, each routine has a few keywords that are unique to it. Keywords are implemented using a single shared array of IDL_KW_PAR with appropriate values of the mask field. This technique dramatically reduces the amount of data that would otherwise be required by graphics keyword processing, and makes IDL easier to maintain.

flags

This field specifies special processing instructions. It is a bit mask made by ORing the following values:

• IDL_KW_ARRAY: Set this bit to specify that the keyword must be an array. Otherwise, a scalar is required. If IDL_KW_ARRAY is specified, the value field must point at an associated IDL_KW_ARR_DESC_R structure.
• IDL_KW_OUT: Set this bit to indicate that the keyword specifies an output parameter, passed by reference. Expressions and constants are excluded. In other words, the routine is going to change the value of the keyword argument, as opposed to the more usual case of reading it. The address of the IDL_VARIABLE will be placed in a user supplied field of type IDL_VPTR in the KW_RESULT structure (kw). The offset of this field in the KW_RESULT structure is specified by the value field (discussed below). IDL_KW_OUT implies that no type checking or processing will be performed on the keyword—it is up to the routine to perform the same sort of type checking normally carried out for plain positional arguments. A standard approach to find out if an IDL_KW_OUT parameter is present in a call to a system routine is to specify IDL_TYP_UNDEF (0) for the type field and IDL_KW_OUT | IDL_KW_ZERO for flags. The IDL_VPTR referenced by the value field will either contain NULL, or a pointer to the IDL_VARIABLE.
• IDL_KW_VIN: Set this bit to indicate that the keyword parameter is an input parameter (expressions and/or constants are valid) passed by reference. The address of the IDL_VARIABLE or expression is stored in a user-supplied field of the KW_RESULT structure (kw) referenced by the value field, as with IDL_KW_OUT. IDL_KW_VIN implies that no type checking or processing will be performed on the keyword—it is up to the routine to perform the same sort of type checking normally carried out for plain positional arguments.
• IDL_KW_ZERO: Set this bit in order to zero the C variable pointed to by the value field before parsing the keywords. This means that the object pointed to by value will always be zero unless it was specified by the user. Use this technique to create keywords that have Boolean (on or off) meanings.
• IDL_KW_VALUE: If this bit is set and the specified keyword is present and non-zero, the low 12 bits of this field (flags) will be bitwise ORed with the IDL_LONG field of the KW_RESULT structure referenced by the value field. Note that this implies the IDL_TYP_LONG type code, and is incompatible with the IDL_KW_ARRAY, IDL_KW_VIN, and IDL_KW_OUT flags.

specified

NULL, or the offset of the user supplied field within the KW_RESULT structure (kw) of a C int variable that will be set to TRUE (non-zero) or FALSE (0) based on whether the routine was called with the keyword present. The IDL_KW_OFFSETOF() macro should be used to calculate the offset. Setting this field to NULL (0) indicates that this information is not needed.

value

If the keyword is a read-only scalar, this field is the offset of the user supplied field in the KW_RESULT structure (kw) into which the keyword value will be copied. The IDL_KW_OFFSETOF() macro should be used to calculate the offset.

In the case of a read-only array, value is the memory address of an IDL_KW_ARR_DESC_R, structure, which is discussed in The IDL_KW_ARR_DESC_R Structure.

In the case of an input (IDL_KW_VIN) or output (IDL_KW_OUT) variable, this field should contain the offset to the IDL_VPTR field within the user supplied KW_RESULT that will be filled by IDL_KWProcessByOffset() with the address of the keyword argument. The IDL_KW_OFFSETOF() macro should be used to calculate the offset.