Microsoft KB Archive/77376

{|
 * width="100%"|

CALLing Functions that Modify a Passed Buffer in Excel
'Article ID: Q77376

Creation Date: 15-OCT-1991

Revision Date: 03-NOV-1994' The information in this article applies to:


 * Microsoft Excel for Windows, version 3.0

IMPORTANT: The CALL and REGISTER functions are provided for advanced users only. If you use these functions incorrectly you could accidentally cause errors in your system's operation. SUMMARY

Many of the functions built into Windows take the address of a buffer as one of their parameters; the contents of the buffer are then modified, and the function returns an error code, a count of the characters placed in the buffer, or similar peripheral information.

To call these functions using the CALL and REGISTER functions of Microsoft Excel, the F data type must be used for the return value of the function in the type_text parameter.

MORE INFORMATION

When the return type of a function given in CALL or REGISTER is given as type F, this causes Microsoft Excel to ignore the true return value. Instead, Microsoft Excel allocates a buffer when the function is called, passes its address in as the parameter given type F, and takes the contents of the buffer after the function terminates to be the return value.

For example, the lstrcpy function built into Windows takes as parameters the addresses of two string buffers. It copies the contents of the second buffer into the first, and then returns the address of the first buffer. If a CALL statement for this function is coded as

=CALL(&quot;Kernel&quot;,&quot;lstrcpy&quot;,&quot;CCC&quot;,Q3000,&quot;This is a test!&quot;) the data in cell Q3000 may or may not be properly set to &quot;This is a test!&quot; In addition, this usage may cause corruption on the worksheet or even an Unrecoverable Application Error (UAE) because there may not be enough space allocated in Q3000 to hold this string.

However, if the function is coded as

=CALL(&quot;Kernel&quot;,&quot;lstrcpy&quot;,&quot;FFC&quot;,Q3000,&quot;Nebulas to Ted!&quot;) the data in Q3000 will not be affected, and the cell containing the CALL function will be given the value of &quot;Nebulas to Ted!&quot; A somewhat more complex, but more commonly used, example is the Windows function GetProfileString. This function obtains the value of a given setting in a given section of the WIN.INI file. If this is coded as

=CALL(&quot;Kernel&quot;,&quot;GetProfileString&quot;,&quot;ICCCCI&quot;,&quot;Windows&quot;,&quot;Spooler&quot;,&quot;Burp&quot;  ,N97,132) the contents of cell N97 will probably be corrupted. The proper way to code this function is  =CALL(&quot;Kernel&quot;,&quot;GetProfileString&quot;,&quot;FCCCFI&quot;,&quot;Windows&quot;,&quot;Spooler&quot;,   &quot;Burp&quot;,,132) which will return the value of the spooler= line in the [Windows] section of WIN.INI to the cell containing the CALL. NOTE: The above code should appear as one line without a carriage return. The lines are word wrapped here for convenience.

REFERENCES

&quot;Microsoft Windows Software Development Kit Reference - Vol. 1,&quot; version 3.0, page 4-202

&quot;Microsoft Excel Function Reference,&quot; version 3.0, Appendix A
 * }

-

"THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY." '' ©1997 Microsoft Corporation. All rights reserved. Legal Notices.

''

KBCategory: kbother

KBSubcategory:

Additional reference words: 3.00 3.0 getprivateprofilestring