CPXXaddfuncdest and CPXaddfuncdest

Description

The routine CPXXaddfuncdest/CPXaddfuncdest adds a function msgfunction to the message destination list for a channel. This routine allows users to trap messages instead of printing them. That is, when a message is sent to the channel, each destination that was added to the message destination list by CPXXaddfuncdest/CPXaddfuncdest calls its associated message.

To illustrate this idea, consider an application in which you want to trap CPLEX error messages and display them in a dialog box that prompts the user for an action. Use CPXXaddfuncdest/CPXaddfuncdest to add the address of a function to the list of message destinations associated with the cpxerror channel. Then write the msgfunction routine. It must contain the code that controls the dialog box. When CPXXmsgstr/CPXmsgstr is called with cpxerror as its first argument, it calls the msgfunction routine, which can then display the error message.

The length of the string (including the terminating NUL character) with which CPLEX invokes the registered function never exceeds CPXMESSAGEBUFSIZE.

The argument handle is a generic pointer that can be used to hold information needed by the msgfunction to avoid making such information global to all routines.

The routine CPXXaddfuncdest/CPXaddfuncdest consults the parameter known as the API string encoding switch (CPXPARAM_Read_APIEncoding) when it adds a function to a destination channel. The value of that parameter at that time persists for the destination channel, regardless of later changes of the parameter. This convention means that a user can associate different channels with different encodings. For more about the API encoding, see the documentation of that parameter in the CPLEX Parameters Reference Manual.

Callbacks added to channels by CPXXaddfuncdest/CPXaddfuncdest by default receive their messages in UTF-8 encoding.

Arguments

env

A pointer to the CPLEX environment as returned by CPXXopenCPLEX/CPXopenCPLEX.

channel

A pointer to the channel to which the function destination is to be added.

handle

A void pointer that can be used to pass arbitrary information into msgfunction.

msgfunction

A pointer to the function to be called when a message is sent to a channel.

Return

The routine returns 0 (zero) if successful and nonzero if an error occurs. Failure occurs when msgfunction is not in the message-destination list or the channel does not exist.

Example

void CPXPUBLIC msgfunction (void *handle, const char *msg_string)
{
FILE *fp;
fp = (FILE *)handle;
fprintf (fp, "%s", msg_string);
}
status = CPXaddfuncdest (env, mychannel, fileptr, msgfunction);