1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/doc/glpk06.tex Mon Dec 06 13:09:21 2010 +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 *%