The following cases occur in keyword processing:
Scalar Input-Only
For scalar, input-only keywords, the user never sees the IDL_VARIABLE passed as the keyword argument. Instead, the value of the IDL_VARIABLE is converted to the type specified by the type field of the IDL_KW_PAR struct and is placed into the field of the user specified KW_RESULT structure, the offset of which is given by the value field. This offset is calculated using the IDL_KW_OFFSETOF() macro.
Array Input-Only
Array input-only keywords work similarly to the scalar case, except that the value field contains the address of an IDL_KW_ARR_DESC_R struct that supplies the added information required to convert the passed array elements to the specified type and place them into a C array for easy access. The array data is copied into a array within the user supplied KW_RESULT structure. The data field of the IDL_KW_ARR_DESC_R struct supplies the offset of the array field within the KW_RESULT structure. This offset is calculated using the IDL_KW_OFFSETOF() macro.
As part of this process, the number of array elements passed is checked to be within the range specified in the IDL_KW_ARR_DESC_R struct, and if no error results, the number is stored into a field of the user supplied KW_RESULT struct. The n_offset field of the IDL_KW_ARR_DESC_R struct supplies the offset of this “number of elements” field within the KW_RESULT structure. This offset is calculated using the IDL_KW_OFFSETOF() macro.
It is worth noting that input-only array keywords don’t pass information about the number of dimensions or their sizes, only the total number of elements. Therefore, they are treated as 1-dimensional vectors. For more flexibility, use an Input/Output keyword instead.
Input/Output
This case occurs if the IDL_KW_VIN or IDL_KW_OUT flag is set in the IDL_KW_PAR struct. In this case, the value field contains the offset of the IDL_VPTR field (computed with the IDL_KW_OFFSETOF() macro) in the user defined KW_RESULT struct into which the actual keyword argument is copied. In this case, you must do all error checking and type conversion yourself, just like with two cases are much easier to use, and are suitable for the vast majority of keywords.