free-item

Arguments: dde-topic-or-item-name

Frees an OS dde string handle resource used by a dde-topic-or-item-name. The argument can be either a symbol or a string, just as you would pass it as a dde topic or item name to other dde functions.

When passing symbols or strings that serve as dde topic and item names, internally a special handle is created for each name, and the name is passed quickly to and/or from DDE by simply passing the handle. There is a limit in the OS to the number of such strings that may be created. Usually this is not a problem, since Allegro knows to always re-use the same dde string handle for a given topic or item name. So if you call (send-request spreadsheet-port :current-row-number) thousands of times, only one dde string handle will be created for the item name "current-row-number". These string handles are freed automatically either when close-dde is called or when lisp exits.

But if, on the other hand, the item names are not a handful of constants but are instead some sort of variable that is being passed as many different values (for example, passing "RxCy" as an item name to a spreadsheet to ask for the value of cell x, y, with lots of different values of x and y being passed), then many dde string handles may be getting created and may even exceed the maximum that may be created. If this is a possibility, then you may want to explicitly call free-item on such dde item names after passing them to dde functions. This will free each handle shortly after it is created, to leave maximum capacity for further string handles. If the same item-name is used again later after it has been freed, then the dde string handle for it will be recreated internally automatically, so you don't have to make sure that you are no longer using a particular topic or item name before you call free-item on it.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.