1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/deps/glpk/doc/glpk06.tex	Sun Nov 06 20:59:10 2011 +0100
     1.3 @@ -0,0 +1,896 @@
     1.4 +%* glpk06.tex *%
     1.5 +
     1.6 +\chapter{Miscellaneous API Routines}
     1.7 +
     1.8 +\section{GLPK environment routines}
     1.9 +
    1.10 +\subsection{glp\_long---64-bit integer data type}
    1.11 +
    1.12 +Some GLPK API routines use 64-bit integer data type, which is declared
    1.13 +in the header \verb|glpk.h| as follows:
    1.14 +
    1.15 +\begin{verbatim}
    1.16 +typedef struct { int lo, hi; } glp_long;
    1.17 +\end{verbatim}
    1.18 +
    1.19 +\noindent
    1.20 +where \verb|lo| contains low 32 bits, and \verb|hi| contains high 32
    1.21 +bits of 64-bit integer value.\footnote{GLPK conforms to ILP32, LLP64,
    1.22 +and LP64 programming models, where the built-in type {\tt int}
    1.23 +corresponds to 32-bit integers.}
    1.24 +
    1.25 +\subsection{glp\_init\_env---initialize GLPK environment}
    1.26 +
    1.27 +\subsubsection*{Synopsis}
    1.28 +
    1.29 +\begin{verbatim}
    1.30 +int glp_init_env(void);
    1.31 +\end{verbatim}
    1.32 +
    1.33 +\subsubsection*{Description}
    1.34 +
    1.35 +The routine \verb|glp_init_env| initializes the GLPK environment.
    1.36 +Normally the application program does not need to call this routine,
    1.37 +because it is called automatically on the first call to any API routine.
    1.38 +
    1.39 +\newpage
    1.40 +
    1.41 +\subsubsection*{Returns}
    1.42 +
    1.43 +The routine \verb|glp_init_env| returns one of the following codes:
    1.44 +
    1.45 +\noindent
    1.46 +0 --- initialization successful;
    1.47 +
    1.48 +\noindent
    1.49 +1 --- environment is already initialized;
    1.50 +
    1.51 +\noindent
    1.52 +2 --- initialization failed (insufficient memory);
    1.53 +
    1.54 +\noindent
    1.55 +3 --- initialization failed (unsupported programming model).
    1.56 +
    1.57 +\subsection{glp\_version---determine library version}
    1.58 +
    1.59 +\subsubsection*{Synopsis}
    1.60 +
    1.61 +\begin{verbatim}
    1.62 +const char *glp_version(void);
    1.63 +\end{verbatim}
    1.64 +
    1.65 +\subsubsection*{Returns}
    1.66 +
    1.67 +The routine \verb|glp_version| returns a pointer to a null-terminated
    1.68 +character string, which specifies the version of the GLPK library in
    1.69 +the form \verb|"X.Y"|, where `\verb|X|' is the major version number, and
    1.70 +`\verb|Y|' is the minor version number, for example, \verb|"4.16"|.
    1.71 +
    1.72 +\subsubsection*{Example}
    1.73 +
    1.74 +\begin{footnotesize}
    1.75 +\begin{verbatim}
    1.76 +printf("GLPK version is %s\n", glp_version());
    1.77 +\end{verbatim}
    1.78 +\end{footnotesize}
    1.79 +
    1.80 +\subsection{glp\_free\_env---free GLPK environment}
    1.81 +
    1.82 +\subsubsection*{Synopsis}
    1.83 +
    1.84 +\begin{verbatim}
    1.85 +int glp_free_env(void);
    1.86 +\end{verbatim}
    1.87 +
    1.88 +\subsubsection*{Description}
    1.89 +
    1.90 +The routine \verb|glp_free_env| frees all resources used by GLPK
    1.91 +routines (memory blocks, etc.) which are currently still in use.
    1.92 +
    1.93 +Normally the application program does not need to call this routine,
    1.94 +because GLPK routines always free all unused resources. However, if
    1.95 +the application program even has deleted all problem objects, there
    1.96 +will be several memory blocks still allocated for the internal library
    1.97 +needs. For some reasons the application program may want GLPK to free
    1.98 +this memory, in which case it should call \verb|glp_free_env|.
    1.99 +
   1.100 +Note that a call to \verb|glp_free_env| invalidates all problem objects
   1.101 +which still exist.
   1.102 +
   1.103 +\subsubsection*{Returns}
   1.104 +
   1.105 +The routine \verb|glp_free_env| returns one of the following codes:
   1.106 +
   1.107 +\noindent
   1.108 +0 --- termination successful;
   1.109 +
   1.110 +\noindent
   1.111 +1 --- environment is inactive (was not initialized).
   1.112 +
   1.113 +\subsection{glp\_printf---write formatted output to terminal}
   1.114 +
   1.115 +\subsubsection*{Synopsis}
   1.116 +
   1.117 +\begin{verbatim}
   1.118 +void glp_printf(const char *fmt, ...);
   1.119 +\end{verbatim}
   1.120 +
   1.121 +\subsubsection*{Description}
   1.122 +
   1.123 +The routine \verb|glp_printf| uses the format control string
   1.124 +\verb|fmt| to format its parameters and writes the formatted output to
   1.125 +the terminal.
   1.126 +
   1.127 +This routine is a replacement of the standard C function
   1.128 +\verb|printf| and used by all GLPK routines to perform terminal
   1.129 +output. The application program may use \verb|glp_printf| for the same
   1.130 +purpose that allows controlling its terminal output with the routines
   1.131 +\verb|glp_term_out| and \verb|glp_term_hook|.
   1.132 +
   1.133 +\subsection{glp\_vprintf---write formatted output to terminal}
   1.134 +
   1.135 +\subsubsection*{Synopsis}
   1.136 +
   1.137 +\begin{verbatim}
   1.138 +void glp_vprintf(const char *fmt, va_list arg);
   1.139 +\end{verbatim}
   1.140 +
   1.141 +\subsubsection*{Description}
   1.142 +
   1.143 +The routine \verb|glp_vprintf| uses the format control string
   1.144 +\verb|fmt| to format its parameters specified by the list \verb|arg|
   1.145 +and writes the formatted output to the terminal.
   1.146 +
   1.147 +This routine is a replacement of the standard C function
   1.148 +\verb|vprintf| and used by all GLPK routines to perform terminal
   1.149 +output. The application program may use \verb|glp_vprintf| for the same
   1.150 +purpose that allows controlling its terminal output with the routines
   1.151 +\verb|glp_term_out| and \verb|glp_term_hook|.
   1.152 +
   1.153 +\newpage
   1.154 +
   1.155 +\subsection{glp\_term\_out---enable/disable terminal output}
   1.156 +
   1.157 +\subsubsection*{Synopsis}
   1.158 +
   1.159 +\begin{verbatim}
   1.160 +int glp_term_out(int flag);
   1.161 +\end{verbatim}
   1.162 +
   1.163 +\subsubsection*{Description}
   1.164 +
   1.165 +Depending on the parameter flag the routine \verb|glp_term_out| enables
   1.166 +or disables terminal output performed by glpk routines:
   1.167 +
   1.168 +\verb|GLP_ON | --- enable terminal output;
   1.169 +
   1.170 +\verb|GLP_OFF| --- disable terminal output.
   1.171 +
   1.172 +\subsubsection*{Returns}
   1.173 +
   1.174 +The routine \verb|glp_term_out| returns the previous value of the
   1.175 +terminal output flag (\verb|GLP_ON| or \verb|GLP_OFF|).
   1.176 +
   1.177 +\subsection{glp\_term\_hook---intercept terminal output}
   1.178 +
   1.179 +\subsubsection*{Synopsis}
   1.180 +
   1.181 +\begin{verbatim}
   1.182 +void glp_term_hook(int (*func)(void *info, const char *s),
   1.183 +      void *info);
   1.184 +\end{verbatim}
   1.185 +
   1.186 +\subsubsection*{Description}
   1.187 +
   1.188 +The routine \verb|glp_term_hook| installs the user-defined hook routine
   1.189 +to intercept all terminal output performed by GLPK routines.
   1.190 +
   1.191 +%This feature can be used to redirect the terminal output to other
   1.192 +%destination, for example, to a file or a text window.
   1.193 +
   1.194 +The parameter {\it func} specifies the user-defined hook routine. It is
   1.195 +called from an internal printing routine, which passes to it two
   1.196 +parameters: {\it info} and {\it s}. The parameter {\it info} is a
   1.197 +transit pointer specified in corresponding call to the routine
   1.198 +\verb|glp_term_hook|; it may be used to pass some additional information
   1.199 +to the hook routine. The parameter {\it s} is a pointer to the null
   1.200 +terminated character string, which is intended to be written to the
   1.201 +terminal. If the hook routine returns zero, the printing routine writes
   1.202 +the string {\it s} to the terminal in a usual way; otherwise, if the
   1.203 +hook routine returns non-zero, no terminal output is performed.
   1.204 +
   1.205 +To uninstall the hook routine both parameters {\it func} and {\it info}
   1.206 +should be specified as \verb|NULL|.
   1.207 +
   1.208 +\newpage
   1.209 +
   1.210 +\subsubsection*{Example}
   1.211 +
   1.212 +\begin{footnotesize}
   1.213 +\begin{verbatim}
   1.214 +static int hook(void *info, const char *s)
   1.215 +{     FILE *foo = info;
   1.216 +      fputs(s, foo);
   1.217 +      return 1;
   1.218 +}
   1.219 +
   1.220 +int main(void)
   1.221 +{     FILE *foo;
   1.222 +      . . .
   1.223 +      /* redirect terminal output */
   1.224 +      glp_term_hook(hook, foo);
   1.225 +      . . .
   1.226 +      /* resume terminal output */
   1.227 +      glp_term_hook(NULL, NULL);
   1.228 +      . . .
   1.229 +}
   1.230 +\end{verbatim}
   1.231 +\end{footnotesize}
   1.232 +
   1.233 +\subsection{glp\_open\_tee---start copying terminal output}
   1.234 +
   1.235 +\subsubsection*{Synopsis}
   1.236 +
   1.237 +\begin{verbatim}
   1.238 +int glp_open_tee(const char *fname);
   1.239 +\end{verbatim}
   1.240 +
   1.241 +\subsubsection*{Description}
   1.242 +
   1.243 +The routine \verb|glp_open_tee| starts copying all the terminal output
   1.244 +to an output text file, whose name is specified by the character string
   1.245 +\verb|fname|.
   1.246 +
   1.247 +\subsubsection*{Returns}
   1.248 +
   1.249 +The routine \verb|glp_open_tee| returns one of the following codes:
   1.250 +
   1.251 +\noindent
   1.252 +0 --- operation successful;
   1.253 +
   1.254 +\noindent
   1.255 +1 --- copying terminal output is already active;
   1.256 +
   1.257 +\noindent
   1.258 +2 --- unable to create output file.
   1.259 +
   1.260 +\newpage
   1.261 +
   1.262 +\subsection{glp\_close\_tee---stop copying terminal output}
   1.263 +
   1.264 +\subsubsection*{Synopsis}
   1.265 +
   1.266 +\begin{verbatim}
   1.267 +int glp_close_tee(void);
   1.268 +\end{verbatim}
   1.269 +
   1.270 +\subsubsection*{Description}
   1.271 +
   1.272 +The routine \verb|glp_close_tee| stops copying the terminal output to
   1.273 +the output text file previously open by the routine \verb|glp_open_tee|
   1.274 +closing that file.
   1.275 +
   1.276 +\subsubsection*{Returns}
   1.277 +
   1.278 +The routine \verb|glp_close_tee| returns one of the following codes:
   1.279 +
   1.280 +\noindent
   1.281 +0 --- operation successful;
   1.282 +
   1.283 +\noindent
   1.284 +1 --- copying terminal output was not started.
   1.285 +
   1.286 +\subsection{glp\_error---display error message and terminate execution}
   1.287 +
   1.288 +\subsubsection*{Synopsis}
   1.289 +
   1.290 +\begin{verbatim}
   1.291 +void glp_error(const char *fmt, ...);
   1.292 +\end{verbatim}
   1.293 +
   1.294 +\subsubsection*{Description}
   1.295 +
   1.296 +The routine \verb|glp_error| (implemented as a macro) formats its
   1.297 +parameters using the format control string \verb|fmt|, writes the
   1.298 +formatted message to the terminal, and then abnormally terminates the
   1.299 +program.
   1.300 +
   1.301 +\subsection{glp\_assert---check logical condition}
   1.302 +
   1.303 +\subsubsection*{Synopsis}
   1.304 +
   1.305 +\begin{verbatim}
   1.306 +void glp_assert(int expr);
   1.307 +\end{verbatim}
   1.308 +
   1.309 +\subsubsection*{Description}
   1.310 +
   1.311 +The routine \verb|glp_assert| (implemented as a macro) checks
   1.312 +a logical condition specified by the expression \verb|expr|. If the
   1.313 +condition is true (non-zero), the routine does nothing; otherwise, if
   1.314 +the condition is false (zero), the routine prints an error message and
   1.315 +abnormally terminates the program.
   1.316 +
   1.317 +This routine is a replacement of the standard C function \verb|assert|
   1.318 +and used by all GLPK routines to check program logic. The application
   1.319 +program may use \verb|glp_assert| for the same purpose.
   1.320 +
   1.321 +\subsection{glp\_error\_hook---install hook to intercept abnormal
   1.322 +termination}
   1.323 +
   1.324 +\subsubsection*{Synopsis}
   1.325 +
   1.326 +\begin{verbatim}
   1.327 +void glp_error_hook(void (*func)(void *info), void *info);
   1.328 +\end{verbatim}
   1.329 +
   1.330 +\subsubsection*{Description}
   1.331 +
   1.332 +The routine \verb|glp_error_hook| installs a user-defined hook routine
   1.333 +to intercept abnormal termination.
   1.334 +
   1.335 +The parameter \verb|func| specifies the user-defined hook routine. It
   1.336 +is called from the routine \verb|glp_error| before the latter calls the
   1.337 +abort function to abnormally terminate the application program because
   1.338 +of fatal error. The parameter \verb|info| is a transit pointer,
   1.339 +specified in the corresponding call to the routine
   1.340 +\verb|glp_error_hook|; it may be used to pass some information to the
   1.341 +hook routine.
   1.342 +
   1.343 +To uninstall the hook routine the parameters \verb|func| and \verb|info|
   1.344 +should be specified as \verb|NULL|.
   1.345 +
   1.346 +\subsubsection*{Usage note}
   1.347 +
   1.348 +If the hook routine returns, the application program is abnormally
   1.349 +terminated. To prevent abnormal termnation the hook routine may perform
   1.350 +a global jump using the standard function \verb|longjmp|, in which case
   1.351 +the application program {\it must} call the routine \verb|glp_free_env|.
   1.352 +
   1.353 +\subsection{glp\_malloc---allocate memory block}
   1.354 +
   1.355 +\subsubsection*{Synopsis}
   1.356 +
   1.357 +\begin{verbatim}
   1.358 +void *glp_malloc(int size);
   1.359 +\end{verbatim}
   1.360 +
   1.361 +\subsubsection*{Description}
   1.362 +
   1.363 +The routine \verb|glp_malloc| dynamically allocates a memory block of
   1.364 +\verb|size| bytes long. Should note that:
   1.365 +
   1.366 +1) the parameter \verb|size| must be positive;
   1.367 +
   1.368 +2) being allocated the memory block contains arbitrary data, that is,
   1.369 +it is {\it not} initialized by binary zeros;
   1.370 +
   1.371 +3) if the block cannot be allocated due to insufficient memory, the
   1.372 +routine prints an error message and abnormally terminates the program.
   1.373 +
   1.374 +This routine is a replacement of the standard C function \verb|malloc|
   1.375 +and used by all GLPK routines for dynamic memory allocation. The
   1.376 +application program may use \verb|glp_malloc| for the same purpose.
   1.377 +
   1.378 +\subsubsection*{Returns}
   1.379 +
   1.380 +The routine \verb|glp_malloc| returns a pointer to the memory block
   1.381 +allocated. To free this block the routine \verb|glp_free| (not the
   1.382 +standard C function \verb|free|!) must be used.
   1.383 +
   1.384 +\subsection{glp\_calloc---allocate memory block}
   1.385 +
   1.386 +\subsubsection*{Synopsis}
   1.387 +
   1.388 +\begin{verbatim}
   1.389 +void *glp_calloc(int n, int size);
   1.390 +\end{verbatim}
   1.391 +
   1.392 +\subsubsection*{Description}
   1.393 +
   1.394 +The routine \verb|glp_calloc| dynamically allocates a memory block of
   1.395 +\verb|n|$\times$\verb|size| bytes long. Should note that:
   1.396 +
   1.397 +1) both parameters \verb|n| and \verb|size| must be positive;
   1.398 +
   1.399 +2) being allocated the memory block contains arbitrary data, that is,
   1.400 +it is {\it not} initialized by binary zeros;
   1.401 +
   1.402 +3) if the block cannot be allocated due to insufficient memory, the
   1.403 +routine prints an error message and abnormally terminates the program.
   1.404 +
   1.405 +This routine is a replacement of the standard C function \verb|calloc|
   1.406 +(with exception that the block is not cleaned) and used by all GLPK
   1.407 +routines for dynamic memory allocation. The application program may use
   1.408 +\verb|glp_calloc| for the same purpose.
   1.409 +
   1.410 +\subsubsection*{Returns}
   1.411 +
   1.412 +The routine \verb|glp_calloc| returns a pointer to the memory block
   1.413 +allocated. To free this block the routine \verb|glp_free| (not the
   1.414 +standard C function \verb|free|!) must be used.
   1.415 +
   1.416 +\subsection{glp\_free---free memory block}
   1.417 +
   1.418 +\subsubsection*{Synopsis}
   1.419 +
   1.420 +\begin{verbatim}
   1.421 +void glp_free(void *ptr);
   1.422 +\end{verbatim}
   1.423 +
   1.424 +\subsubsection*{Description}
   1.425 +
   1.426 +The routine \verb|glp_free| frees (deallocates) a memory block pointed
   1.427 +to by \verb|ptr|, which was previously allocated by the routine
   1.428 +\verb|glp_malloc| or \verb|glp_calloc|. Note that the pointer \verb|ptr|
   1.429 +must valid and must not be \verb|NULL|.
   1.430 +
   1.431 +This routine is a replacement of the standard C function \verb|free|
   1.432 +and used by all GLPK routines for dynamic memory allocation. The
   1.433 +application program may use \verb|glp_free| for the same purpose.
   1.434 +
   1.435 +\subsection{glp\_mem\_usage---get memory usage information}
   1.436 +
   1.437 +\subsubsection*{Synopsis}
   1.438 +
   1.439 +\begin{verbatim}
   1.440 +void glp_mem_usage(int *count, int *cpeak, glp_long *total,
   1.441 +      glp_long *tpeak);
   1.442 +\end{verbatim}
   1.443 +
   1.444 +\subsubsection*{Description}
   1.445 +
   1.446 +The routine \verb|glp_mem_usage| reports some information about
   1.447 +utilization of the memory by the routines \verb|glp_malloc|,
   1.448 +\verb|glp_calloc|, and \verb|glp_free|. Information is stored to
   1.449 +locations specified by corresponding parameters (see below). Any
   1.450 +parameter can be specified as \verb|NULL|, in which case corresponding
   1.451 +information is not stored.
   1.452 +
   1.453 +\verb|*count| is the number of currently allocated memory blocks.
   1.454 +
   1.455 +\verb|*cpeak| is the peak value of \verb|*count| reached since the
   1.456 +initialization of the GLPK library environment.
   1.457 +
   1.458 +\verb|*total| is the total amount, in bytes, of currently allocated
   1.459 +memory blocks.
   1.460 +
   1.461 +\verb|*tpeak| is the peak value of \verb|*total| reached since the
   1.462 +initialization of the GLPK library envirionment.
   1.463 +
   1.464 +\subsubsection*{Example}
   1.465 +
   1.466 +\begin{footnotesize}
   1.467 +\begin{verbatim}
   1.468 +glp_mem_usage(&count, NULL, NULL, NULL);
   1.469 +printf("%d memory block(s) are still allocated\n", count);
   1.470 +\end{verbatim}
   1.471 +\end{footnotesize}
   1.472 +
   1.473 +\subsection{glp\_mem\_limit---set memory usage limit}
   1.474 +
   1.475 +\subsubsection*{Synopsis}
   1.476 +
   1.477 +\begin{verbatim}
   1.478 +void glp_mem_limit(int limit);
   1.479 +\end{verbatim}
   1.480 +
   1.481 +\subsubsection*{Description}
   1.482 +
   1.483 +The routine \verb|glp_mem_limit| limits the amount of memory available
   1.484 +for dynamic allocation (with the routines \verb|glp_malloc| and
   1.485 +\verb|glp_calloc|) to \verb|limit| megabytes.
   1.486 +
   1.487 +\subsection{glp\_time---determine current universal time}
   1.488 +
   1.489 +\subsubsection*{Synopsis}
   1.490 +
   1.491 +\begin{verbatim}
   1.492 +glp_long glp_time(void);
   1.493 +\end{verbatim}
   1.494 +
   1.495 +\subsection*{Returns}
   1.496 +
   1.497 +The routine \verb|glp_time| returns the current universal time (UTC),
   1.498 +in milliseconds, elapsed since 00:00:00 GMT January 1, 1970.
   1.499 +
   1.500 +\subsection{glp\_difftime---compute difference between two time values}
   1.501 +
   1.502 +\subsubsection*{Synopsis}
   1.503 +
   1.504 +\begin{verbatim}
   1.505 +double glp_difftime(glp_long t1, glp_long t0);
   1.506 +\end{verbatim}
   1.507 +
   1.508 +\subsection*{Returns}
   1.509 +
   1.510 +The routine \verb|glp_difftime| returns the difference between two time
   1.511 +values \verb|t1| and \verb|t0|, expressed in seconds.
   1.512 +
   1.513 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   1.514 +
   1.515 +\newpage
   1.516 +
   1.517 +\section{Plain data file reading routines}
   1.518 +
   1.519 +\subsection{Introduction}
   1.520 +
   1.521 +On developing simple applications to solve optimization problems it is
   1.522 +often needed to read data from plain text files. To do this the standard
   1.523 +C function \verb|fscanf| may be used, however, it is not convenient; for
   1.524 +example, if it scans an integer number according to the format
   1.525 +specification `\verb|%d|', and that number is coded incorrectly,
   1.526 +no diagnostics is provided.
   1.527 +
   1.528 +This section describes a set of GLPK API routines, which may be used in
   1.529 +application programs to simplify reading data from plain text files.
   1.530 +
   1.531 +\subsubsection*{Example 1}
   1.532 +
   1.533 +The following main program reads ten integer numbers from plain text
   1.534 +file \verb|data.txt| and prints their sum.
   1.535 +
   1.536 +\begin{footnotesize}
   1.537 +\begin{verbatim}
   1.538 +/* sdfsamp1.c */
   1.539 +
   1.540 +#include <stdio.h>
   1.541 +#include <stdlib.h>
   1.542 +#include <glpk.h>
   1.543 +
   1.544 +int main(void)
   1.545 +{     glp_data *data;
   1.546 +      int j, num, sum;
   1.547 +      /* open plain data file */
   1.548 +      data = glp_sdf_open_file("data.txt");
   1.549 +      if (data == NULL) exit(EXIT_FAILURE);
   1.550 +      sum = 0;
   1.551 +      for (j = 1; j <= 10; j++)
   1.552 +      {  /* read next integer number */
   1.553 +         num = glp_sdf_read_int(data);
   1.554 +         sum += num;
   1.555 +      }
   1.556 +      printf("sum = %d\n", sum);
   1.557 +      /* close plain data file */
   1.558 +      glp_sdf_close_file(data);
   1.559 +      return 0;
   1.560 +}
   1.561 +
   1.562 +/* eof */
   1.563 +\end{verbatim}
   1.564 +\end{footnotesize}
   1.565 +
   1.566 +The input data are coded in free format. For example, the file
   1.567 +\verb|data.txt| may look like this:
   1.568 +
   1.569 +\begin{footnotesize}
   1.570 +\begin{verbatim}
   1.571 +123 65 432 890 -12 743 895 -7 111 326
   1.572 +\end{verbatim}
   1.573 +\end{footnotesize}
   1.574 +
   1.575 +\noindent
   1.576 +or like this:
   1.577 +
   1.578 +\begin{footnotesize}
   1.579 +\begin{verbatim}
   1.580 +123   65  432  890  -12
   1.581 +743  895   -7  111  326
   1.582 +\end{verbatim}
   1.583 +\end{footnotesize}
   1.584 +
   1.585 +\noindent
   1.586 +If the input data file contains incorrect data, the routine
   1.587 +\verb|glp_sdf_read_int| prints an error message and, if no error
   1.588 +handling is provided by the application program, abnormally terminates
   1.589 +program execution. For example, the file \verb|data.txt| could contain
   1.590 +the following data:
   1.591 +
   1.592 +\begin{footnotesize}
   1.593 +\begin{verbatim}
   1.594 +123   65  432  890  -12
   1.595 +743  895   =7  111  326
   1.596 +\end{verbatim}
   1.597 +\end{footnotesize}
   1.598 +
   1.599 +\noindent
   1.600 +in which case the error message would be the following:
   1.601 +
   1.602 +\begin{footnotesize}
   1.603 +\begin{verbatim}
   1.604 +data.txt:2: cannot convert `=7' to integer
   1.605 +\end{verbatim}
   1.606 +\end{footnotesize}
   1.607 +
   1.608 +\subsubsection*{Example 2}
   1.609 +
   1.610 +As it was said above, by default any attempt to read incorrect data
   1.611 +leads to abnormal termination. However, sometimes it is desirable to
   1.612 +catch such errors. This feature is illustrated by the following main
   1.613 +program, which does the same job as in the previous example.
   1.614 +
   1.615 +\begin{footnotesize}
   1.616 +\begin{verbatim}
   1.617 +/* sdfsamp2.c */
   1.618 +
   1.619 +#include <setjmp.h>
   1.620 +#include <stdio.h>
   1.621 +#include <stdlib.h>
   1.622 +#include <glpk.h>
   1.623 +
   1.624 +int main(void)
   1.625 +{     glp_data *data;
   1.626 +      jmp_buf jump;
   1.627 +      int j, num, sum, ret;
   1.628 +      /* open plain data file */
   1.629 +      data = glp_sdf_open_file("data.txt");
   1.630 +      if (data == NULL)
   1.631 +      {  ret = EXIT_FAILURE;
   1.632 +         goto done;
   1.633 +      }
   1.634 +      /* set up error handling */
   1.635 +      if (setjmp(jump))
   1.636 +      {  ret = EXIT_FAILURE;
   1.637 +         goto done;
   1.638 +      }
   1.639 +      glp_sdf_set_jump(data, jump);
   1.640 +      /* read and process data */
   1.641 +      sum = 0;
   1.642 +      for (j = 1; j <= 10; j++)
   1.643 +      {  /* read next integer number */
   1.644 +         num = glp_sdf_read_int(data);
   1.645 +         if (abs(num) > 1000)
   1.646 +            glp_sdf_error(data, "integer %d too big\n", num);
   1.647 +         if (num < 0)
   1.648 +            glp_sdf_warning(data, "integer %d is negative\n", num);
   1.649 +         sum += num;
   1.650 +      }
   1.651 +      printf("sum = %d\n", sum);
   1.652 +      ret = EXIT_SUCCESS;
   1.653 +done: /* close plain data file */
   1.654 +      if (data != NULL) glp_sdf_close_file(data);
   1.655 +      return ret;
   1.656 +}
   1.657 +
   1.658 +/* eof */
   1.659 +\end{verbatim}
   1.660 +\end{footnotesize}
   1.661 +
   1.662 +\subsection{glp\_sdf\_open\_file---open plain data file}
   1.663 +
   1.664 +\subsubsection*{Synopsis}
   1.665 +
   1.666 +\begin{verbatim}
   1.667 +glp_data *glp_sdf_open_file(const char *fname);
   1.668 +\end{verbatim}
   1.669 +
   1.670 +\subsubsection*{Description}
   1.671 +
   1.672 +The routine \verb|glp_sdf_open_file| opens a plain data file, whose
   1.673 +name is specified by the character string \verb|fname|.
   1.674 +
   1.675 +\subsubsection*{Returns}
   1.676 +
   1.677 +If the operation was successful, the routine \verb|glp_sdf_open_file|
   1.678 +returns a pointer to the opaque program object of the type
   1.679 +\verb|glp_data|\footnote{This data structure is declared in the header
   1.680 +file {\tt glpk.h}.} associated with the plain data file. Otherwise, if
   1.681 +the operation failed, the routine prints an error message and returns
   1.682 +\verb|NULL|.
   1.683 +
   1.684 +\subsubsection*{Note}
   1.685 +
   1.686 +The application program should use the pointer returned by the routine
   1.687 +\verb|glp_sdf_open_file| to perform all subsequent operations on the
   1.688 +data file.
   1.689 +
   1.690 +\newpage
   1.691 +
   1.692 +\subsection{glp\_sdf\_set\_jump---set up error handling}
   1.693 +
   1.694 +\subsubsection*{Synopsis}
   1.695 +
   1.696 +\begin{verbatim}
   1.697 +void glp_sdf_set_jump(glp_data *data, jmp_buf jump);
   1.698 +\end{verbatim}
   1.699 +
   1.700 +\subsubsection*{Description}
   1.701 +
   1.702 +The routine \verb|glp_sdf_set_jump| sets up error handling for the
   1.703 +plain data file specified by the parameter \verb|data|.
   1.704 +
   1.705 +The parameter \verb|jump| specifies the environment buffer, which must
   1.706 +be initialized with the standard C function \verb|setjmp| prior to call
   1.707 +to the routine \verb|glp_sdf_set_jump|. Detecting any incorrect data in
   1.708 +the corresponding plain data file will cause non-local ``go to'' by
   1.709 +a call to the standard C function \verb|longjmp|.
   1.710 +
   1.711 +The parameter \verb|jump| can be specified as \verb|NULL|, in which
   1.712 +case the routine \verb|glp_sdf_set_jump| restores the default behavior,
   1.713 +in which case detecting incorrect data leads to abnormal termination.
   1.714 +
   1.715 +\subsection{glp\_sdf\_error---print error message}
   1.716 +
   1.717 +\subsubsection*{Synopsis}
   1.718 +
   1.719 +\begin{verbatim}
   1.720 +void glp_sdf_error(glp_data *data, const char *fmt, ...);
   1.721 +\end{verbatim}
   1.722 +
   1.723 +\subsubsection*{Description}
   1.724 +
   1.725 +The routine \verb|glp_sdf_error| prints an error message related to the
   1.726 +plain data file specified by the parameter \verb|data|. If error handing
   1.727 +was not previously provided, the routine then abnormally terminates
   1.728 +execution of the application program. Otherwise, it signals about the
   1.729 +error by a call to the standard C function \verb|longjmp|.
   1.730 +
   1.731 +The character string \verb|fmt| and optional parameters following it
   1.732 +have the same meaning as for the standard C function \verb|printf|.
   1.733 +
   1.734 +The message produced by the routine \verb|glp_sdf_error| looks like
   1.735 +follows:
   1.736 +
   1.737 +\medskip
   1.738 +
   1.739 +{\it file}{\tt :}{\it line}{\tt :} {\it message text}
   1.740 +
   1.741 +\medskip
   1.742 +
   1.743 +\noindent
   1.744 +where {\it file} is the filename passed to the routine
   1.745 +\verb|glp_sdf_open| and {\it line} is the current line number.
   1.746 +
   1.747 +\newpage
   1.748 +
   1.749 +\subsection{glp\_sdf\_warning---print warning message}
   1.750 +
   1.751 +\subsubsection*{Synopsis}
   1.752 +
   1.753 +\begin{verbatim}
   1.754 +void glp_sdf_warning(glp_data *data, const char *fmt, ...);
   1.755 +\end{verbatim}
   1.756 +
   1.757 +\subsubsection*{Description}
   1.758 +
   1.759 +The routine \verb|glp_sdf_warning| prints a warning message related to
   1.760 +the plain data file specified by the parameter \verb|data|.
   1.761 +
   1.762 +The character string \verb|fmt| and optional parameters following it
   1.763 +have the same meaning as for the standard C function \verb|printf|.
   1.764 +
   1.765 +The message produced by the routine \verb|glp_sdf_warning| looks like
   1.766 +follows:
   1.767 +
   1.768 +\medskip
   1.769 +
   1.770 +{\it file}{\tt :}{\it line}\verb|: warning:| {\it message text}
   1.771 +
   1.772 +\medskip
   1.773 +
   1.774 +\noindent
   1.775 +where {\it file} is the filename passed to the routine
   1.776 +\verb|glp_sdf_open| and {\it line} is the current line number.
   1.777 +
   1.778 +\subsection{glp\_sdf\_read\_int---read integer number}
   1.779 +
   1.780 +\subsubsection*{Synopsis}
   1.781 +
   1.782 +\begin{verbatim}
   1.783 +int glp_sdf_read_int(glp_data *data);
   1.784 +\end{verbatim}
   1.785 +
   1.786 +\subsubsection*{Description}
   1.787 +
   1.788 +The routine \verb|glp_sdf_read_int| skips optional white-space
   1.789 +characters and then reads an integer number from the plain data file
   1.790 +specified by the parameter \verb|data|. If the operation failed, the
   1.791 +routine \verb|glp_sdf_read_int| calls the routine \verb|glp_sdf_error|
   1.792 +(see above).
   1.793 +
   1.794 +\subsubsection*{Returns}
   1.795 +
   1.796 +The routine \verb|glp_sdf_read_int| returns the integer number read.
   1.797 +
   1.798 +\newpage
   1.799 +
   1.800 +\subsection{glp\_sdf\_read\_num---read floating-point number}
   1.801 +
   1.802 +\subsubsection*{Synopsis}
   1.803 +
   1.804 +\begin{verbatim}
   1.805 +double glp_sdf_read_num(glp_data *data);
   1.806 +\end{verbatim}
   1.807 +
   1.808 +\subsubsection*{Description}
   1.809 +
   1.810 +The routine \verb|glp_sdf_read_num| skips optional white-space
   1.811 +characters and then reads a floating-point number from the plain data
   1.812 +file specified by the parameter \verb|data|. If the operation failed,
   1.813 +the routine \verb|glp_sdf_num| calls the routine \verb|glp_sdf_error|
   1.814 +(see above).
   1.815 +
   1.816 +\subsubsection*{Returns}
   1.817 +
   1.818 +The routine \verb|glp_sdf_read_num| returns the floating-point number
   1.819 +read.
   1.820 +
   1.821 +\subsection{glp\_sdf\_read\_item---read data item}
   1.822 +
   1.823 +\subsubsection*{Synopsis}
   1.824 +
   1.825 +\begin{verbatim}
   1.826 +const char *glp_sdf_read_item(glp_data *data);
   1.827 +\end{verbatim}
   1.828 +
   1.829 +\subsubsection*{Description}
   1.830 +
   1.831 +The routine \verb|glp_sdf_read_item| skips optional white-space
   1.832 +characters and then reads a data item from the plain data file specified
   1.833 +by the parameter \verb|data|. If the operation failed, the routine
   1.834 +\verb|glp_sdf_read_item| calls the routine \verb|glp_sdf_error| (see
   1.835 +above).
   1.836 +
   1.837 +{\it Data item} is a sequence of 1 to 255 arbitrary graphic characters
   1.838 +delimited by white-space characters. Data items may be used to represent
   1.839 +symbolic names, identifiers, etc.
   1.840 +
   1.841 +\subsubsection*{Returns}
   1.842 +
   1.843 +The routine \verb|glp_sdf_read_item| returns a pointer to the internal
   1.844 +buffer, which contains the data item read in the form of a
   1.845 +null-terminated character string.
   1.846 +
   1.847 +\newpage
   1.848 +
   1.849 +\subsection{glp\_sdf\_read\_text---read text until end of line}
   1.850 +
   1.851 +\subsubsection*{Synopsis}
   1.852 +
   1.853 +\begin{verbatim}
   1.854 +const char *glp_sdf_read_text(glp_data *data);
   1.855 +\end{verbatim}
   1.856 +
   1.857 +\subsubsection*{Description}
   1.858 +
   1.859 +The routine \verb|glp_sdf_read_text| reads a text from the plain data
   1.860 +file specified by the parameter \verb|data|.
   1.861 +
   1.862 +Reading starts from the current position and extends until end of the
   1.863 +current line. Initial and trailing white-space characters as well as
   1.864 +the newline character are not included in the text.
   1.865 +
   1.866 +\subsubsection*{Returns}
   1.867 +
   1.868 +The routine \verb|glp_sdf_read_text| returns a pointer to the internal
   1.869 +buffer, which contains the text read in the form of a null-terminated
   1.870 +character string.
   1.871 +
   1.872 +\subsection{glp\_sdf\_line---determine current line number}
   1.873 +
   1.874 +\subsubsection*{Synopsis}
   1.875 +
   1.876 +\begin{verbatim}
   1.877 +int glp_sdf_line(glp_data *data);
   1.878 +\end{verbatim}
   1.879 +
   1.880 +\subsubsection*{Returns}
   1.881 +
   1.882 +The routine \verb|glp_sdf_line| returns the current line number for the
   1.883 +plain data file specified by the parameter \verb|data|.
   1.884 +
   1.885 +\subsection{glp\_sdf\_close\_file---close plain data file}
   1.886 +
   1.887 +\subsubsection*{Synopsis}
   1.888 +
   1.889 +\begin{verbatim}
   1.890 +void glp_sdf_close_file(glp_data *data);
   1.891 +\end{verbatim}
   1.892 +
   1.893 +\subsubsection*{Description}
   1.894 +
   1.895 +The routine \verb|glp_sdf_close_file| closes the plain data file
   1.896 +specified by the parameter \verb|data| and frees all the resources
   1.897 +allocated to this program object.
   1.898 +
   1.899 +%* eof *%