source: glpk-cmake/doc/glpk06.tex @ 1:c445c931472f

%* glpk06.tex *%

\chapter{Miscellaneous API Routines}

\section{GLPK environment routines}

\subsection{glp\_long---64-bit integer data type}

Some GLPK API routines use 64-bit integer data type, which is declared
in the header \verb|glpk.h| as follows:

\begin{verbatim}
typedef struct { int lo, hi; } glp_long;
\end{verbatim}

\noindent
where \verb|lo| contains low 32 bits, and \verb|hi| contains high 32
bits of 64-bit integer value.\footnote{GLPK conforms to ILP32, LLP64,
and LP64 programming models, where the built-in type {\tt int}
corresponds to 32-bit integers.}

\subsection{glp\_init\_env---initialize GLPK environment}

\subsubsection*{Synopsis}

\begin{verbatim}
int glp_init_env(void);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_init_env| initializes the GLPK environment.
Normally the application program does not need to call this routine,
because it is called automatically on the first call to any API routine.

\newpage

\subsubsection*{Returns}

The routine \verb|glp_init_env| returns one of the following codes:

\noindent
0 --- initialization successful;

\noindent
1 --- environment is already initialized;

\noindent
2 --- initialization failed (insufficient memory);

\noindent
3 --- initialization failed (unsupported programming model).

\subsection{glp\_version---determine library version}

\subsubsection*{Synopsis}

\begin{verbatim}
const char *glp_version(void);
\end{verbatim}

\subsubsection*{Returns}

The routine \verb|glp_version| returns a pointer to a null-terminated
character string, which specifies the version of the GLPK library in
the form \verb|"X.Y"|, where `\verb|X|' is the major version number, and
`\verb|Y|' is the minor version number, for example, \verb|"4.16"|.

\subsubsection*{Example}

\begin{footnotesize}
\begin{verbatim}
printf("GLPK version is %s\n", glp_version());
\end{verbatim}
\end{footnotesize}

\subsection{glp\_free\_env---free GLPK environment}

\subsubsection*{Synopsis}

\begin{verbatim}
int glp_free_env(void);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_free_env| frees all resources used by GLPK
routines (memory blocks, etc.) which are currently still in use.

Normally the application program does not need to call this routine,
because GLPK routines always free all unused resources. However, if
the application program even has deleted all problem objects, there
will be several memory blocks still allocated for the internal library
needs. For some reasons the application program may want GLPK to free
this memory, in which case it should call \verb|glp_free_env|.

Note that a call to \verb|glp_free_env| invalidates all problem objects
which still exist.

\subsubsection*{Returns}

The routine \verb|glp_free_env| returns one of the following codes:

\noindent
0 --- termination successful;

\noindent
1 --- environment is inactive (was not initialized).

\subsection{glp\_printf---write formatted output to terminal}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_printf(const char *fmt, ...);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_printf| uses the format control string
\verb|fmt| to format its parameters and writes the formatted output to
the terminal.

This routine is a replacement of the standard C function
\verb|printf| and used by all GLPK routines to perform terminal
output. The application program may use \verb|glp_printf| for the same
purpose that allows controlling its terminal output with the routines
\verb|glp_term_out| and \verb|glp_term_hook|.

\subsection{glp\_vprintf---write formatted output to terminal}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_vprintf(const char *fmt, va_list arg);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_vprintf| uses the format control string
\verb|fmt| to format its parameters specified by the list \verb|arg|
and writes the formatted output to the terminal.

This routine is a replacement of the standard C function
\verb|vprintf| and used by all GLPK routines to perform terminal
output. The application program may use \verb|glp_vprintf| for the same
purpose that allows controlling its terminal output with the routines
\verb|glp_term_out| and \verb|glp_term_hook|.

\newpage

\subsection{glp\_term\_out---enable/disable terminal output}

\subsubsection*{Synopsis}

\begin{verbatim}
int glp_term_out(int flag);
\end{verbatim}

\subsubsection*{Description}

Depending on the parameter flag the routine \verb|glp_term_out| enables
or disables terminal output performed by glpk routines:

\verb|GLP_ON | --- enable terminal output;

\verb|GLP_OFF| --- disable terminal output.

\subsubsection*{Returns}

The routine \verb|glp_term_out| returns the previous value of the
terminal output flag (\verb|GLP_ON| or \verb|GLP_OFF|).

\subsection{glp\_term\_hook---intercept terminal output}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_term_hook(int (*func)(void *info, const char *s),
      void *info);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_term_hook| installs the user-defined hook routine
to intercept all terminal output performed by GLPK routines.

%This feature can be used to redirect the terminal output to other
%destination, for example, to a file or a text window.

The parameter {\it func} specifies the user-defined hook routine. It is
called from an internal printing routine, which passes to it two
parameters: {\it info} and {\it s}. The parameter {\it info} is a
transit pointer specified in corresponding call to the routine
\verb|glp_term_hook|; it may be used to pass some additional information
to the hook routine. The parameter {\it s} is a pointer to the null
terminated character string, which is intended to be written to the
terminal. If the hook routine returns zero, the printing routine writes
the string {\it s} to the terminal in a usual way; otherwise, if the
hook routine returns non-zero, no terminal output is performed.

To uninstall the hook routine both parameters {\it func} and {\it info}
should be specified as \verb|NULL|.

\newpage

\subsubsection*{Example}

\begin{footnotesize}
\begin{verbatim}
static int hook(void *info, const char *s)
{     FILE *foo = info;
      fputs(s, foo);
      return 1;
}

int main(void)
{     FILE *foo;
      . . .
      /* redirect terminal output */
      glp_term_hook(hook, foo);
      . . .
      /* resume terminal output */
      glp_term_hook(NULL, NULL);
      . . .
}
\end{verbatim}
\end{footnotesize}

\subsection{glp\_open\_tee---start copying terminal output}

\subsubsection*{Synopsis}

\begin{verbatim}
int glp_open_tee(const char *fname);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_open_tee| starts copying all the terminal output
to an output text file, whose name is specified by the character string
\verb|fname|.

\subsubsection*{Returns}

The routine \verb|glp_open_tee| returns one of the following codes:

\noindent
0 --- operation successful;

\noindent
1 --- copying terminal output is already active;

\noindent
2 --- unable to create output file.

\newpage

\subsection{glp\_close\_tee---stop copying terminal output}

\subsubsection*{Synopsis}

\begin{verbatim}
int glp_close_tee(void);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_close_tee| stops copying the terminal output to
the output text file previously open by the routine \verb|glp_open_tee|
closing that file.

\subsubsection*{Returns}

The routine \verb|glp_close_tee| returns one of the following codes:

\noindent
0 --- operation successful;

\noindent
1 --- copying terminal output was not started.

\subsection{glp\_error---display error message and terminate execution}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_error(const char *fmt, ...);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_error| (implemented as a macro) formats its
parameters using the format control string \verb|fmt|, writes the
formatted message to the terminal, and then abnormally terminates the
program.

\subsection{glp\_assert---check logical condition}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_assert(int expr);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_assert| (implemented as a macro) checks
a logical condition specified by the expression \verb|expr|. If the
condition is true (non-zero), the routine does nothing; otherwise, if
the condition is false (zero), the routine prints an error message and
abnormally terminates the program.

This routine is a replacement of the standard C function \verb|assert|
and used by all GLPK routines to check program logic. The application
program may use \verb|glp_assert| for the same purpose.

\subsection{glp\_error\_hook---install hook to intercept abnormal
termination}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_error_hook(void (*func)(void *info), void *info);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_error_hook| installs a user-defined hook routine
to intercept abnormal termination.

The parameter \verb|func| specifies the user-defined hook routine. It
is called from the routine \verb|glp_error| before the latter calls the
abort function to abnormally terminate the application program because
of fatal error. The parameter \verb|info| is a transit pointer,
specified in the corresponding call to the routine
\verb|glp_error_hook|; it may be used to pass some information to the
hook routine.

To uninstall the hook routine the parameters \verb|func| and \verb|info|
should be specified as \verb|NULL|.

\subsubsection*{Usage note}

If the hook routine returns, the application program is abnormally
terminated. To prevent abnormal termnation the hook routine may perform
a global jump using the standard function \verb|longjmp|, in which case
the application program {\it must} call the routine \verb|glp_free_env|.

\subsection{glp\_malloc---allocate memory block}

\subsubsection*{Synopsis}

\begin{verbatim}
void *glp_malloc(int size);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_malloc| dynamically allocates a memory block of
\verb|size| bytes long. Should note that:

1) the parameter \verb|size| must be positive;

2) being allocated the memory block contains arbitrary data, that is,
it is {\it not} initialized by binary zeros;

3) if the block cannot be allocated due to insufficient memory, the
routine prints an error message and abnormally terminates the program.

This routine is a replacement of the standard C function \verb|malloc|
and used by all GLPK routines for dynamic memory allocation. The
application program may use \verb|glp_malloc| for the same purpose.

\subsubsection*{Returns}

The routine \verb|glp_malloc| returns a pointer to the memory block
allocated. To free this block the routine \verb|glp_free| (not the
standard C function \verb|free|!) must be used.

\subsection{glp\_calloc---allocate memory block}

\subsubsection*{Synopsis}

\begin{verbatim}
void *glp_calloc(int n, int size);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_calloc| dynamically allocates a memory block of
\verb|n|$\times$\verb|size| bytes long. Should note that:

1) both parameters \verb|n| and \verb|size| must be positive;

2) being allocated the memory block contains arbitrary data, that is,
it is {\it not} initialized by binary zeros;

3) if the block cannot be allocated due to insufficient memory, the
routine prints an error message and abnormally terminates the program.

This routine is a replacement of the standard C function \verb|calloc|
(with exception that the block is not cleaned) and used by all GLPK
routines for dynamic memory allocation. The application program may use
\verb|glp_calloc| for the same purpose.

\subsubsection*{Returns}

The routine \verb|glp_calloc| returns a pointer to the memory block
allocated. To free this block the routine \verb|glp_free| (not the
standard C function \verb|free|!) must be used.

\subsection{glp\_free---free memory block}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_free(void *ptr);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_free| frees (deallocates) a memory block pointed
to by \verb|ptr|, which was previously allocated by the routine
\verb|glp_malloc| or \verb|glp_calloc|. Note that the pointer \verb|ptr|
must valid and must not be \verb|NULL|.

This routine is a replacement of the standard C function \verb|free|
and used by all GLPK routines for dynamic memory allocation. The
application program may use \verb|glp_free| for the same purpose.

\subsection{glp\_mem\_usage---get memory usage information}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_mem_usage(int *count, int *cpeak, glp_long *total,
      glp_long *tpeak);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_mem_usage| reports some information about
utilization of the memory by the routines \verb|glp_malloc|,
\verb|glp_calloc|, and \verb|glp_free|. Information is stored to
locations specified by corresponding parameters (see below). Any
parameter can be specified as \verb|NULL|, in which case corresponding
information is not stored.

\verb|*count| is the number of currently allocated memory blocks.

\verb|*cpeak| is the peak value of \verb|*count| reached since the
initialization of the GLPK library environment.

\verb|*total| is the total amount, in bytes, of currently allocated
memory blocks.

\verb|*tpeak| is the peak value of \verb|*total| reached since the
initialization of the GLPK library envirionment.

\subsubsection*{Example}

\begin{footnotesize}
\begin{verbatim}
glp_mem_usage(&count, NULL, NULL, NULL);
printf("%d memory block(s) are still allocated\n", count);
\end{verbatim}
\end{footnotesize}

\subsection{glp\_mem\_limit---set memory usage limit}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_mem_limit(int limit);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_mem_limit| limits the amount of memory available
for dynamic allocation (with the routines \verb|glp_malloc| and
\verb|glp_calloc|) to \verb|limit| megabytes.

\subsection{glp\_time---determine current universal time}

\subsubsection*{Synopsis}

\begin{verbatim}
glp_long glp_time(void);
\end{verbatim}

\subsection*{Returns}

The routine \verb|glp_time| returns the current universal time (UTC),
in milliseconds, elapsed since 00:00:00 GMT January 1, 1970.

\subsection{glp\_difftime---compute difference between two time values}

\subsubsection*{Synopsis}

\begin{verbatim}
double glp_difftime(glp_long t1, glp_long t0);
\end{verbatim}

\subsection*{Returns}

The routine \verb|glp_difftime| returns the difference between two time
values \verb|t1| and \verb|t0|, expressed in seconds.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newpage

\section{Plain data file reading routines}

\subsection{Introduction}

On developing simple applications to solve optimization problems it is
often needed to read data from plain text files. To do this the standard
C function \verb|fscanf| may be used, however, it is not convenient; for
example, if it scans an integer number according to the format
specification `\verb|%d|', and that number is coded incorrectly,
no diagnostics is provided.

This section describes a set of GLPK API routines, which may be used in
application programs to simplify reading data from plain text files.

\subsubsection*{Example 1}

The following main program reads ten integer numbers from plain text
file \verb|data.txt| and prints their sum.

\begin{footnotesize}
\begin{verbatim}
/* sdfsamp1.c */

#include <stdio.h>
#include <stdlib.h>
#include <glpk.h>

int main(void)
{     glp_data *data;
      int j, num, sum;
      /* open plain data file */
      data = glp_sdf_open_file("data.txt");
      if (data == NULL) exit(EXIT_FAILURE);
      sum = 0;
      for (j = 1; j <= 10; j++)
      {  /* read next integer number */
         num = glp_sdf_read_int(data);
         sum += num;
      }
      printf("sum = %d\n", sum);
      /* close plain data file */
      glp_sdf_close_file(data);
      return 0;
}

/* eof */
\end{verbatim}
\end{footnotesize}

The input data are coded in free format. For example, the file
\verb|data.txt| may look like this:

\begin{footnotesize}
\begin{verbatim}
123 65 432 890 -12 743 895 -7 111 326
\end{verbatim}
\end{footnotesize}

\noindent
or like this:

\begin{footnotesize}
\begin{verbatim}
123   65  432  890  -12
743  895   -7  111  326
\end{verbatim}
\end{footnotesize}

\noindent
If the input data file contains incorrect data, the routine
\verb|glp_sdf_read_int| prints an error message and, if no error
handling is provided by the application program, abnormally terminates
program execution. For example, the file \verb|data.txt| could contain
the following data:

\begin{footnotesize}
\begin{verbatim}
123   65  432  890  -12
743  895   =7  111  326
\end{verbatim}
\end{footnotesize}

\noindent
in which case the error message would be the following:

\begin{footnotesize}
\begin{verbatim}
data.txt:2: cannot convert `=7' to integer
\end{verbatim}
\end{footnotesize}

\subsubsection*{Example 2}

As it was said above, by default any attempt to read incorrect data
leads to abnormal termination. However, sometimes it is desirable to
catch such errors. This feature is illustrated by the following main
program, which does the same job as in the previous example.

\begin{footnotesize}
\begin{verbatim}
/* sdfsamp2.c */

#include <setjmp.h>
#include <stdio.h>
#include <stdlib.h>
#include <glpk.h>

int main(void)
{     glp_data *data;
      jmp_buf jump;
      int j, num, sum, ret;
      /* open plain data file */
      data = glp_sdf_open_file("data.txt");
      if (data == NULL)
      {  ret = EXIT_FAILURE;
         goto done;
      }
      /* set up error handling */
      if (setjmp(jump))
      {  ret = EXIT_FAILURE;
         goto done;
      }
      glp_sdf_set_jump(data, jump);
      /* read and process data */
      sum = 0;
      for (j = 1; j <= 10; j++)
      {  /* read next integer number */
         num = glp_sdf_read_int(data);
         if (abs(num) > 1000)
            glp_sdf_error(data, "integer %d too big\n", num);
         if (num < 0)
            glp_sdf_warning(data, "integer %d is negative\n", num);
         sum += num;
      }
      printf("sum = %d\n", sum);
      ret = EXIT_SUCCESS;
done: /* close plain data file */
      if (data != NULL) glp_sdf_close_file(data);
      return ret;
}

/* eof */
\end{verbatim}
\end{footnotesize}

\subsection{glp\_sdf\_open\_file---open plain data file}

\subsubsection*{Synopsis}

\begin{verbatim}
glp_data *glp_sdf_open_file(const char *fname);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_sdf_open_file| opens a plain data file, whose
name is specified by the character string \verb|fname|.

\subsubsection*{Returns}

If the operation was successful, the routine \verb|glp_sdf_open_file|
returns a pointer to the opaque program object of the type
\verb|glp_data|\footnote{This data structure is declared in the header
file {\tt glpk.h}.} associated with the plain data file. Otherwise, if
the operation failed, the routine prints an error message and returns
\verb|NULL|.

\subsubsection*{Note}

The application program should use the pointer returned by the routine
\verb|glp_sdf_open_file| to perform all subsequent operations on the
data file.

\newpage

\subsection{glp\_sdf\_set\_jump---set up error handling}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_sdf_set_jump(glp_data *data, jmp_buf jump);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_sdf_set_jump| sets up error handling for the
plain data file specified by the parameter \verb|data|.

The parameter \verb|jump| specifies the environment buffer, which must
be initialized with the standard C function \verb|setjmp| prior to call
to the routine \verb|glp_sdf_set_jump|. Detecting any incorrect data in
the corresponding plain data file will cause non-local ``go to'' by
a call to the standard C function \verb|longjmp|.

The parameter \verb|jump| can be specified as \verb|NULL|, in which
case the routine \verb|glp_sdf_set_jump| restores the default behavior,
in which case detecting incorrect data leads to abnormal termination.

\subsection{glp\_sdf\_error---print error message}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_sdf_error(glp_data *data, const char *fmt, ...);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_sdf_error| prints an error message related to the
plain data file specified by the parameter \verb|data|. If error handing
was not previously provided, the routine then abnormally terminates
execution of the application program. Otherwise, it signals about the
error by a call to the standard C function \verb|longjmp|.

The character string \verb|fmt| and optional parameters following it
have the same meaning as for the standard C function \verb|printf|.

The message produced by the routine \verb|glp_sdf_error| looks like
follows:

\medskip

{\it file}{\tt :}{\it line}{\tt :} {\it message text}

\medskip

\noindent
where {\it file} is the filename passed to the routine
\verb|glp_sdf_open| and {\it line} is the current line number.

\newpage

\subsection{glp\_sdf\_warning---print warning message}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_sdf_warning(glp_data *data, const char *fmt, ...);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_sdf_warning| prints a warning message related to
the plain data file specified by the parameter \verb|data|.

The character string \verb|fmt| and optional parameters following it
have the same meaning as for the standard C function \verb|printf|.

The message produced by the routine \verb|glp_sdf_warning| looks like
follows:

\medskip

{\it file}{\tt :}{\it line}\verb|: warning:| {\it message text}

\medskip

\noindent
where {\it file} is the filename passed to the routine
\verb|glp_sdf_open| and {\it line} is the current line number.

\subsection{glp\_sdf\_read\_int---read integer number}

\subsubsection*{Synopsis}

\begin{verbatim}
int glp_sdf_read_int(glp_data *data);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_sdf_read_int| skips optional white-space
characters and then reads an integer number from the plain data file
specified by the parameter \verb|data|. If the operation failed, the
routine \verb|glp_sdf_read_int| calls the routine \verb|glp_sdf_error|
(see above).

\subsubsection*{Returns}

The routine \verb|glp_sdf_read_int| returns the integer number read.

\newpage

\subsection{glp\_sdf\_read\_num---read floating-point number}

\subsubsection*{Synopsis}

\begin{verbatim}
double glp_sdf_read_num(glp_data *data);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_sdf_read_num| skips optional white-space
characters and then reads a floating-point number from the plain data
file specified by the parameter \verb|data|. If the operation failed,
the routine \verb|glp_sdf_num| calls the routine \verb|glp_sdf_error|
(see above).

\subsubsection*{Returns}

The routine \verb|glp_sdf_read_num| returns the floating-point number
read.

\subsection{glp\_sdf\_read\_item---read data item}

\subsubsection*{Synopsis}

\begin{verbatim}
const char *glp_sdf_read_item(glp_data *data);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_sdf_read_item| skips optional white-space
characters and then reads a data item from the plain data file specified
by the parameter \verb|data|. If the operation failed, the routine
\verb|glp_sdf_read_item| calls the routine \verb|glp_sdf_error| (see
above).

{\it Data item} is a sequence of 1 to 255 arbitrary graphic characters
delimited by white-space characters. Data items may be used to represent
symbolic names, identifiers, etc.

\subsubsection*{Returns}

The routine \verb|glp_sdf_read_item| returns a pointer to the internal
buffer, which contains the data item read in the form of a
null-terminated character string.

\newpage

\subsection{glp\_sdf\_read\_text---read text until end of line}

\subsubsection*{Synopsis}

\begin{verbatim}
const char *glp_sdf_read_text(glp_data *data);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_sdf_read_text| reads a text from the plain data
file specified by the parameter \verb|data|.

Reading starts from the current position and extends until end of the
current line. Initial and trailing white-space characters as well as
the newline character are not included in the text.

\subsubsection*{Returns}

The routine \verb|glp_sdf_read_text| returns a pointer to the internal
buffer, which contains the text read in the form of a null-terminated
character string.

\subsection{glp\_sdf\_line---determine current line number}

\subsubsection*{Synopsis}

\begin{verbatim}
int glp_sdf_line(glp_data *data);
\end{verbatim}

\subsubsection*{Returns}

The routine \verb|glp_sdf_line| returns the current line number for the
plain data file specified by the parameter \verb|data|.

\subsection{glp\_sdf\_close\_file---close plain data file}

\subsubsection*{Synopsis}

\begin{verbatim}
void glp_sdf_close_file(glp_data *data);
\end{verbatim}

\subsubsection*{Description}

The routine \verb|glp_sdf_close_file| closes the plain data file
specified by the parameter \verb|data| and frees all the resources
allocated to this program object.

%* eof *%