KB Workspace>New Definition >foreign-function-declaration
FOREIGN-FUNCTION-DECLARATION class, and invokes the Text Editor immediately so that you can complete the declaration. The following figure shows an example declaration of one of the sample functions used throughout this chapter,
g2-demo-add.
|
The declaration text of this item is the
declare foreign function statement (followed by the name of the function, its arguments and return type) that has been compiled and linked into the foreign image to which G2 is connected.
 |
After connecting to a foreign image, G2 maintains an internal list of the functions contained in the foreign image file. When you enter the foreign function name, G2 checks the arguments and return value against the information it has in the internal list. If a function of the name you enter does not exist, or if argument or return value discrepancies do exist, G2 displays an appropriate message in the
Notes attribute of the foreign function declaration.G2 FOREIGN-FUNCTION-DECLARATION items are:
Providing the Name of the C Function
The Name-in-foreign-image attribute indicates the exact name of the C function as it appears in the foreign image (the name you entered in the template file). By default, the value of this attribute is a lowercase version of the function name you enter in the declaration text. Name-in-foreign-image attribute. my-foreign-function in the declaration text, that name will appear in this attribute. If you then change the value to:
"my-foreign-function"
Timeout-interval attribute determines the amount of time allowed before G2 times out while waiting for a value from a foreign function. The value of this attribute (other than use default) overrides the Foreign-function-timeout-interval value set in the Timing Parameters system table, which is 30 seconds by default. Typically, when G2 fails to receive a value from a foreign function, it means that the foreign image has exited due to a coding error.
Name-in-foreign-image attribute and the function name as it appears within the foreign image. Because G2 can connect to more than one foreign image, the possibility of a name collision exists. A name collision occurs when a foreign image transmits a foreign function name for which G2 already has an association. G2 may have obtained that name from a different foreign image or from a name previously transmitted by the foreign image to which G2 is connecting. When checking for name collisions, G2 distinguishes between upper-and lower-case names.
If G2 detects a name collision, it issues a warning in the logbook and replaces the old name-to-image association with the new one. Although G2 can detect the collision and issue a warning, we recommend that you make sure that each foreign function in your KB has a distinct name and that you do not depend on this behavior.