EXIT

The EXIT function allows you to interface with a function in an external library or application.

You can use EXIT when you need information from an existing function in a library or a program or when you need to use a general function that is not available.

Depending on the execution operating system, there are two different methods for the EXIT function: 1) the library method and 2) the program method. The program method is not supported on Windows operating systems.

Syntax:

EXIT (single-text-expression, single-text-expression,
single-text-expression)

Meaning:

1. EXIT (library_name, function_name, input_to_the_function)
2. EXIT ( program_name , command_line_arg1 , command_line_arg2 )

Returns:

A single text item

Meaning 1 - library method

At run time, the function_name function will execute in the library specified by library_name passing input_to_the_function as a text string. The result of function_name is returned as a text item by means of lpep- > lpdataFromApp.

Set lpep- > nReturn equal to 0 if the function is to succeed or set it equal to 1 to fail.

For detailed information about the requirements of the library function that is executed by the EXIT, see Implementing a library EXIT function.

AIX operating system

On the AIX operating system, the shared library that contains library_function must also contain an entry_point function. The entry_point function must be prototyped in the same manner as library_function. The server will invoke the entry_point function before invoking library_function. The server passes the name of the library_function to the entry_point function by way of the szFile EXITPARAM structure member. The entry_point function must then determine the address of the library_function and pass this address back to the server by way of the lpv EXITPARAM structure member. The server will then use the contents of lpv as an address to invoke the library_function.

The following example depicts a shared library called mcshex.so which contains the entry_point function and the library_function.

   #include <stdio.h>
#include <string.h>
#include "runmerc.h"
void AIXEntry(LPEXITPARAM);
void bin2hex(LPEXITPARAM);
unsigned int i;
char *syms[] = { "bin2hex", "AIXEntry" };
void *adr[]  = { (void *)bin2hex, (void *)AIXEntry};
void AIXEntry(LPEXITPARAM lpInputStruct)
{
    printf("AIXEntry called\n");
    for (i = 0; i < (sizeof(syms)) / (sizeof(char *)); i++)
       if ( !(strcmp(lpInputStruct->szFile, syms[i])) ) {
           lpInputStruct->lpv = adr[i];
           break;
       }
  }
void bin2hex(LPEXITPARAM lpInputStruct)
  {
    printf("bin2hex called\n");
printf("argument to library function: %s\n",lpInputStruct->lpszCmdLine);
lpInputStruct->nReturn = 0;
}

To build this shared library, run the following commands:

cc -c share1.c

cc -o mcshex.so share1.o -bE:shrsub.exp -bM:SRE -eAIXEntry

Meaning 2 - program method

The program method of the EXIT function is not supported on Windows operating systems.

At execution time, the program specified by program_name executes and passes the concatenation of command_line_arg1 + " " + command_line_arg2 as a text string.

Whatever is returned by program_name to the standard output device is returned as text.

Examples

• EXIT ( program_name , command_line_arg1 , command_line_arg2 )

  Returns a text string from the function or application that is executed. If the EXIT function is not available for a particular operating system, EXIT returns none.

• EXIT ( "mydll.dll" , "myfunction" , "12" )

  This Windows library example passes the value 12 to myfunction, a function in mydll.dll. The value of the item returned depends on what myfunction does with the 12 passed to it.

• IF (EXIT ("mylib.sl" , "ckCust" , CustID Column:Row:DB) = "OK" , MapKnownCust ( Row:DB ) , MapUnknownCust ( Row:DB ) )

  Similarly, this UNIX library example passes the value of CustID Field to ckCust, a function in a UNIX shared library called mylib.sl. If the value returned by ckCust is OK, a functional map is called to map Row for a known customer. Otherwise, another functional map is executed to map Row for an unknown customer.

• EXIT ( "pwd" , " " , " " )

  This UNIX program example executes the UNIX print working directory (pwd) command to determine the current directory. The name of the current working directory is then returned as a text string. Notice that although the pwd command does not require additional command line arguments, command_line_arg1 and command_line_arg2 must be included as a space enclosed in double quotation marks (" ").

• TEXTTONUMBER ( ( EXIT ( "GetIncome" , Applicant:Form , "*Mortgage" ) )

  This program example passes the value of Applicant concatenated to the text literal *Mortgage to an application called GetIncome. The result is converted to a number.

Related functions

• DDEQUERY
• FAIL
• GET
• LASTERRORCODE
• LASTERRORMSG
• PUT
• RUN
• VALID