Additional Data Type Information

This section contains detailed information about the F, G, K, O, P, and R data types and other information about the type_text argument.

F and G Data Types

With the F and G data types, a function can modify a string buffer that is allocated by Microsoft Excel. If the return value type code is F or G, then Microsoft Excel ignores the value returned by the function. Instead, Microsoft Excel searches the list of function arguments for the first corresponding data type (F or G) and then takes the current contents of the allocated string buffer as the return value. Microsoft Excel allocates 256 bytes for the argument, so the function may return a larger string than it received.

K Data Type

The K data type uses a pointer to a variable-size FP structure. You must define this structure in the DLL or code resource as follows:

typedef struct _FP
{
    unsigned short int rows;
    unsigned short int columns;
    double array[1];        /* Actually, array[rows][columns] */
} FP;

The declaration double array[1] allocates storage for only a single-element array. The number of elements in the actual array equals the number of rows multiplied by the number of columns.

O Data Type

The O data type can be used only as an argument, not as a return value. It passes three items: a pointer to the number of rows in an array, a pointer to the number of columns in an array, and a pointer to a two-dimensional array of floating-point numbers.

Instead of returning a value, a function can modify an array passed by the O data type. To do this, you can use ">O" as the type_text argument. For more information, see "Modifying in Place — Functions Declared as Void" below.

The O data type was created for direct compatibility with Fortran DLLs, which pass arguments by reference.

P Data Type

The P data type is a pointer to an OPER structure. The OPER structure contains 8 bytes of data, followed by a 2-byte identifier that specifies the type of data. With the P data type, a DLL function or code resource can take and return any Microsoft Excel data type.

The OPER structure is defined as follows:

typedef struct _oper

{
    union
    {
        double num;
        unsigned char *str;
        unsigned short int bool;
        unsigned short int err;
        struct
        {
            struct _oper *lparray;
            unsigned short int rows;
            unsigned short int columns;
        } array;
    } val;
    unsigned short int type;
} OPER;

The type field contains one of these values.

The last two values can be used only as arguments, not return values. The missing argument value (128) is passed when the caller omits an argument. The empty cell value (256) is passed when the caller passes a reference to an empty cell.

R Data Type — Calling Microsoft Excel Functions from DLLs

The R data type is a pointer to an XLOPER structure, which is an enhanced version of the OPER structure. In Microsoft Excel version 4.0 and later, you can use the R data type to write DLLs and code resources that call Microsoft Excel functions. With the XLOPER structure, a DLL function can pass sheet references and implement flow control, in addition to passing data. A complete description of the R data type and the Microsoft Excel application programming interface (API) is beyond the scope of this topic. The Microsoft Excel Developer's Kit contains detailed information about the R data type, the Microsoft Excel API, and many other technical aspects of Microsoft Excel.

Volatile Functions and Recalculation

Microsoft Excel usually calculates a DLL function (or a code resource) only when it is entered into a cell, when one of its precedents changes, or when the cell is calculated during a macro. On a worksheet, you can make a DLL function or code resource volatile, which means that it recalculates every time the worksheet recalculates. To make a function volatile, add an exclamation point (!) as the last character in the type_text argument.

For example, in Microsoft Excel for Windows 95 and Microsoft Excel for Windows NT, the following worksheet formula recalculates every time the worksheet recalculates:

CALL("Kernel32","GetTickCount","J!")

Modifying in Place — Functions Declared as Void

You can use a single digit n for the return type code in type_text, where n is a number from 1 to 9. This tells Microsoft Excel to modify the variable in the location pointed to by the nth argument in type_text, instead of returning a value. This is also known as modifying in place. The nth argument must be a pass-by-reference data type (C, D, E, F, G, K, L, M, N, O, P, or R). The DLL function or code resource must also be declared with the void keyword in the C language (or the procedure keyword in the Pascal language).

For example, a DLL function that takes a null-terminated string and two pointers to integers as arguments can modify the string in place. Use "1FMM" as the type_text argument, and declare the function as void.

Versions prior to Microsoft Excel 4.0 used the > character to modify the first argument in place; there was no way to modify any argument other than the first. The > character is equivalent to n = 1 in Microsoft Excel version 4.0 and later.