Functions Exported by the LINGO DLL

The LINGO DLL exports twelve functions. The exported functions are contained in the file Lingo20\Lingd20.Dll (or Lingo64_20\Lingd64_20.dll for 64-bit versions). The library file Lingo20\Programming Samples\Lingd20.lib (or Lingo64_20\Programming Samples\Lingd64_20.lib for 64-bit versions) may be used to import these functions into your own custom application.

Below is a list of the functions exported by the LINGO DLL, along with a brief description of each routine’s functionality. The definitions are written using C language conventions. Refer to the programming samples in the following sections for specific examples of the use of each of these routines using Visual C and Visual Basic.

void LSclearPointersLng( pLSenvLINGO pL)

This clears out the list of @POINTER() pointers to user memory transfer areas established through calls to LSsetPointerLng().

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().

int LScloseLogFileLng( pLSenvLINGO pL)

This closes LINGO’s log file that was opened previously by a call to LSopenLogFileLng().

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().

Return Value:

Returns 0 if no error occurred. Otherwise, one of the nonzero error codes listed in section LINGO DLL Error Codes is returned.

pLSenvLINGO CALLTYPE LScreateEnvLng()

This creates a LINGO environment object. All other LINGO DLL routines require a valid pointer to a LINGO environment object. You should free this object at the end of your application by calling LSdeleteEnvLng(). LScreateEnvLng() will search the application's startup directory and the system path for a valid LINGO license file.  If you would prefer to pass LINGO the license key directly, refer to the following function, LScreateEnvLicenseLNG().

Return Value:

Returns 0 if an error occurred, otherwise, a pointer to a LINGO environment object is returned.

pLSenvLINGO CALLTYPE LScreateEnvLicenseLng( char* pcLicenseKey, int* pnErr)

This creates a LINGO environment object. All other LINGO DLL routines require a valid pointer to a LINGO environment object. You should free this object at the end of your application by calling LSdeleteEnvLng(). LScreateEnvLicenseLng() requires that you pass the license key directly.  If you would prefer to have LINGO search the application's startup directory and the system path for a valid LINGO license file, refer to the previous function, LScreateEnvLng().

Arguments:

pcLicenseKeyPointer to a text string containing a LINGO license key.  The license key may be found at the bottom of your LINGO license file, typically stored in the main LINGO directory under the file name LNDLNG??.LIC, where ?? is LINGO's version number.  The license key is delimited in the license file by a greater-than (>) character.
pnError        Pointer to an integer that returns 0 if no problem or an error code listed in section LINGO DLL Error Codes.

Return Value:

Returns 0 if an error occurred, otherwise, a pointer to a LINGO environment object is returned.

int LSdeleteEnvLng( pLSenvLINGO pL)

This deletes a LINGO environment object previously created through a call to LScreateEnvLng(), which frees up the system memory allocated to the LINGO object.

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().

Return Value:

Returns 0 if no error occurred. Otherwise, one of the nonzero error codes listed in section LINGO DLL Error Codes is returned.

int LSexecuteScriptLng( pLSenvLINGO pL, char* pcScript)

This routine is the main workhorse of the LINGO DLL that processes LINGO command scripts. The script may be contained entirely in memory, or it may contain one or more TAKE commands to load scripts from disk.

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().
pcScriptPointer to a character string containing a LINGO command script. Each line must be terminated with a linefeed character (ASCII 10), and the entire script must be terminated with a NULL (ASCII 0).

Return Value:

Returns 0 if no error occurred. Otherwise, one of the nonzero error codes listed in section LINGO DLL Error Codes is returned.

int LSgetCallbackInfoLng( pLSenvLINGO pL, intnObject, void* pResult)

You may establish a function in your application that the LINGO solver calls back to at regular intervals to keep you abreast of its progress. We refer to this type of routine as being a callback function, and you may refer to section Callback Functions for more information.  Your callback function may then call LINGO through LSgetCallbackInfoLng() to request specific information from the solver while it is processing a model.

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().
nObjectIndex of the information item you are seeking. Current possibilities are:

Index

Name

Type

Information Item

0

LS_IINFO_VARIABLES_LNG

Int

Total number of variables

1

LS_IINFO_VARIABLES_INTEGER_LNG

Int

Number of integer variables

2

LS_IINFO_VARIABLES_NONLINEAR_LNG

Int

Number of nonlinear variables

3

LS_IINFO_CONSTRAINTS_LNG

Int

Total number of constraints

4

LS_IINFO_CONSTRAINTS_NONLINEAR_LNG

Int

Number of nonlinear constraints

5

LS_IINFO_NONZEROS_­LNG

Int

Total nonzero matrix elements

6

LS_IINFO_NONZEROS_NONLINEAR_LNG

Int

Nonlinear nonzero matrix elements

7

LS_IINFO_ITERATIONS_LNG

Int

Number of iterations

8

LS_IINFO_BRANCHES_LNG

Int

Number of branches (IPs only)

9

LS_DINFO_SUMINF_LNG

Double

Sum of infeasibilities

10

LS_DINFO_OBJECTIVE_LNG

Double

Objective value

11

LS_DINFO_MIP_BOUND_LNG

Double

Objective bound (IPs only)

12

LS_DINFO_MIP_BEST_OBJECTIVE_LNG

Double

Best objective value found so far (IPs only)

pResultPointer to where you want LINGO to store the results of your query. LINGO will place the result at this address. You must allocate four bytes of memory for ints and eight bytes of memory for doubles beforehand.

Return Value:

Returns 0 if no error occurred. Otherwise, one of the nonzero error codes listed in section LINGO DLL Error Codes is returned.

int LSgetCallbackVarPrimalLng( pLSenvLINGO pL, char* pcVarName, double* pdPrimals)

You may establish a function in your application that the LINGO solver calls back to at regular intervals to keep you abreast of its progress. We refer to this type of routine as being a callback function, and you may refer to section Callback Functions for more information. Your callback function may then call LINGO through LSgetCallbackVarPrimal() to request the current values for attributes and/or scalar variables.  This will allow you to keep your users posted on the values of the model's variables in the current best solution found so far.  This routine will only return values successfully when solving integer models, or when solving models with the global solver.

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().
pcVarNamePointer to a character string containing the name of the scalar variable or attribute. The name must be terminated with either a blank or a NULL (ASCII 0).
pdPrimalsPoints to where LINGO should write the variable value(s).  You must ensure that enough space is available for the full set of values to avoid memory protection faults.

Return Value:

Returns 0 if no error occurred. Otherwise, one of the nonzero error codes listed in section LINGO DLL Error Codes is returned.

int LSopenLogFileLng( pLSenvLINGO pL, char *pcLogFile)

This creates a file for LINGO to write a log to while processing your script. In general, you should always try to create a log file (at least in the early stages of your project) to assist with debugging. If an error is occurring and you are not exactly sure why, then it is always a good idea to refer to the log file for a clue.

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().
pcLogFilePointer to a character string containing the pathname for your log file.

Return Value:

Returns 0 if no error occurred. Otherwise, one of the nonzero error codes listed in section LINGO DLL Error Codes is returned.

int LSsetCallbackErrorLng( pLSenvLINGO pL, lngCBFuncError_t pcbf, void* pUserData)

Use this routine to specify a callback function that LINGO will call whenever an error is encountered. This allows you application to keep close watch on any unusual conditions that might arise while processing your script.

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().
pcbfPointer to your callback routine.
pUserDataThis is a user specified pointer. You may use it to point to any data you might need to reference from your callback function. LINGO merely passes the value of this pointer through to your callback function. You may set this pointer to NULL if it is not required.

Return Value:

Returns 0 if no error occurred. Otherwise, one of the nonzero error codes listed in section LINGO DLL Error Codes is returned.

The callback function you supply must use the standard call convention and must have the following interface:

int MyErrCallback( pLSenvLINGO pL, void* pUserData, int nErrorCode, char* pcErrorText)

Your computer will most likely crash if you don’t follow this interface specification exactly. The LINGO error code is reported through the nErrorCode argument, along with the error text in pcErrorText. You should set aside at least 200 bytes for the error text. The list of LINGO error codes can be found in the Error Messages section.

int LSsetCallbackSolverLng( pLSenvLINGO pL, lngCBFuncError_t pcgf, void* pUserData)

Use this routine to specify a callback function that LINGO will call at frequent intervals when solving a model.

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().
pcbfPointer to your callback routine.
pUserDataThis is a user specified pointer. You may use it to point to any data you might need to reference from your callback function. LINGO merely passes the value of this pointer through to your callback function. You may set this pointer to NULL if it is not required.

Return Value:

Returns 0 if no error occurred. Otherwise, one of the nonzero error codes listed in section LINGO DLL Error Codes is returned.

The callback function you supply must use the standard call convention and must have the following interface:

int MySolverCallback( pLSenvLINGO pL, int nReserved, void* pUserData)

Your computer will most likely crash if you don’t follow this interface specification exactly. The nReserved argument is reserved for future use and may be ignored.

int CALLTYPE LSsetPointerLng( pLSenvLINGO pL, double* pdPointer, int* pnPointersNow)

Call this routine one or more times to pass a list of memory pointers to LINGO. These pointers are used by LINGO’s @POINTER() function for moving data into and solutions out of the solver. In other words, this allows you to have direct memory links with LINGO for fast and convenient data transfer.

Arguments:

pLPointer to a LINGO environment created by a previous call to LScreateEnvLng().
pdPointerPointer to a memory transfer location to be used by an instance of @POINTER().
pnPointersNowThis is a pointer to an integer variable in which LINGO returns the current number of entries in the @POINTER() pointer list. Thus, on the first call to LSsetPointersLng(), this argument will return a value of 1. The pointer list may be cleared at any time by a call to LSclearPointersLng().

Return Value:

Returns 0 if no error occurred. Otherwise, one of the nonzero error codes listed in section LINGO DLL Error Codes is returned.