lemon-project-template-glpk

annotate deps/glpk/doc/glpk06.tex @ 9:33de93886c88

find changesets by author, revision, files, or words in the commit message
Import GLPK 4.47
author Alpar Juttner <alpar@cs.elte.hu>
date Sun, 06 Nov 2011 20:59:10 +0100
parents
children
rev   line source
alpar@9 1 %* glpk06.tex *%
alpar@9 2
alpar@9 3 \chapter{Miscellaneous API Routines}
alpar@9 4
alpar@9 5 \section{GLPK environment routines}
alpar@9 6
alpar@9 7 \subsection{glp\_long---64-bit integer data type}
alpar@9 8
alpar@9 9 Some GLPK API routines use 64-bit integer data type, which is declared
alpar@9 10 in the header \verb|glpk.h| as follows:
alpar@9 11
alpar@9 12 \begin{verbatim}
alpar@9 13 typedef struct { int lo, hi; } glp_long;
alpar@9 14 \end{verbatim}
alpar@9 15
alpar@9 16 \noindent
alpar@9 17 where \verb|lo| contains low 32 bits, and \verb|hi| contains high 32
alpar@9 18 bits of 64-bit integer value.\footnote{GLPK conforms to ILP32, LLP64,
alpar@9 19 and LP64 programming models, where the built-in type {\tt int}
alpar@9 20 corresponds to 32-bit integers.}
alpar@9 21
alpar@9 22 \subsection{glp\_init\_env---initialize GLPK environment}
alpar@9 23
alpar@9 24 \subsubsection*{Synopsis}
alpar@9 25
alpar@9 26 \begin{verbatim}
alpar@9 27 int glp_init_env(void);
alpar@9 28 \end{verbatim}
alpar@9 29
alpar@9 30 \subsubsection*{Description}
alpar@9 31
alpar@9 32 The routine \verb|glp_init_env| initializes the GLPK environment.
alpar@9 33 Normally the application program does not need to call this routine,
alpar@9 34 because it is called automatically on the first call to any API routine.
alpar@9 35
alpar@9 36 \newpage
alpar@9 37
alpar@9 38 \subsubsection*{Returns}
alpar@9 39
alpar@9 40 The routine \verb|glp_init_env| returns one of the following codes:
alpar@9 41
alpar@9 42 \noindent
alpar@9 43 0 --- initialization successful;
alpar@9 44
alpar@9 45 \noindent
alpar@9 46 1 --- environment is already initialized;
alpar@9 47
alpar@9 48 \noindent
alpar@9 49 2 --- initialization failed (insufficient memory);
alpar@9 50
alpar@9 51 \noindent
alpar@9 52 3 --- initialization failed (unsupported programming model).
alpar@9 53
alpar@9 54 \subsection{glp\_version---determine library version}
alpar@9 55
alpar@9 56 \subsubsection*{Synopsis}
alpar@9 57
alpar@9 58 \begin{verbatim}
alpar@9 59 const char *glp_version(void);
alpar@9 60 \end{verbatim}
alpar@9 61
alpar@9 62 \subsubsection*{Returns}
alpar@9 63
alpar@9 64 The routine \verb|glp_version| returns a pointer to a null-terminated
alpar@9 65 character string, which specifies the version of the GLPK library in
alpar@9 66 the form \verb|"X.Y"|, where `\verb|X|' is the major version number, and
alpar@9 67 `\verb|Y|' is the minor version number, for example, \verb|"4.16"|.
alpar@9 68
alpar@9 69 \subsubsection*{Example}
alpar@9 70
alpar@9 71 \begin{footnotesize}
alpar@9 72 \begin{verbatim}
alpar@9 73 printf("GLPK version is %s\n", glp_version());
alpar@9 74 \end{verbatim}
alpar@9 75 \end{footnotesize}
alpar@9 76
alpar@9 77 \subsection{glp\_free\_env---free GLPK environment}
alpar@9 78
alpar@9 79 \subsubsection*{Synopsis}
alpar@9 80
alpar@9 81 \begin{verbatim}
alpar@9 82 int glp_free_env(void);
alpar@9 83 \end{verbatim}
alpar@9 84
alpar@9 85 \subsubsection*{Description}
alpar@9 86
alpar@9 87 The routine \verb|glp_free_env| frees all resources used by GLPK
alpar@9 88 routines (memory blocks, etc.) which are currently still in use.
alpar@9 89
alpar@9 90 Normally the application program does not need to call this routine,
alpar@9 91 because GLPK routines always free all unused resources. However, if
alpar@9 92 the application program even has deleted all problem objects, there
alpar@9 93 will be several memory blocks still allocated for the internal library
alpar@9 94 needs. For some reasons the application program may want GLPK to free
alpar@9 95 this memory, in which case it should call \verb|glp_free_env|.
alpar@9 96
alpar@9 97 Note that a call to \verb|glp_free_env| invalidates all problem objects
alpar@9 98 which still exist.
alpar@9 99
alpar@9 100 \subsubsection*{Returns}
alpar@9 101
alpar@9 102 The routine \verb|glp_free_env| returns one of the following codes:
alpar@9 103
alpar@9 104 \noindent
alpar@9 105 0 --- termination successful;
alpar@9 106
alpar@9 107 \noindent
alpar@9 108 1 --- environment is inactive (was not initialized).
alpar@9 109
alpar@9 110 \subsection{glp\_printf---write formatted output to terminal}
alpar@9 111
alpar@9 112 \subsubsection*{Synopsis}
alpar@9 113
alpar@9 114 \begin{verbatim}
alpar@9 115 void glp_printf(const char *fmt, ...);
alpar@9 116 \end{verbatim}
alpar@9 117
alpar@9 118 \subsubsection*{Description}
alpar@9 119
alpar@9 120 The routine \verb|glp_printf| uses the format control string
alpar@9 121 \verb|fmt| to format its parameters and writes the formatted output to
alpar@9 122 the terminal.
alpar@9 123
alpar@9 124 This routine is a replacement of the standard C function
alpar@9 125 \verb|printf| and used by all GLPK routines to perform terminal
alpar@9 126 output. The application program may use \verb|glp_printf| for the same
alpar@9 127 purpose that allows controlling its terminal output with the routines
alpar@9 128 \verb|glp_term_out| and \verb|glp_term_hook|.
alpar@9 129
alpar@9 130 \subsection{glp\_vprintf---write formatted output to terminal}
alpar@9 131
alpar@9 132 \subsubsection*{Synopsis}
alpar@9 133
alpar@9 134 \begin{verbatim}
alpar@9 135 void glp_vprintf(const char *fmt, va_list arg);
alpar@9 136 \end{verbatim}
alpar@9 137
alpar@9 138 \subsubsection*{Description}
alpar@9 139
alpar@9 140 The routine \verb|glp_vprintf| uses the format control string
alpar@9 141 \verb|fmt| to format its parameters specified by the list \verb|arg|
alpar@9 142 and writes the formatted output to the terminal.
alpar@9 143
alpar@9 144 This routine is a replacement of the standard C function
alpar@9 145 \verb|vprintf| and used by all GLPK routines to perform terminal
alpar@9 146 output. The application program may use \verb|glp_vprintf| for the same
alpar@9 147 purpose that allows controlling its terminal output with the routines
alpar@9 148 \verb|glp_term_out| and \verb|glp_term_hook|.
alpar@9 149
alpar@9 150 \newpage
alpar@9 151
alpar@9 152 \subsection{glp\_term\_out---enable/disable terminal output}
alpar@9 153
alpar@9 154 \subsubsection*{Synopsis}
alpar@9 155
alpar@9 156 \begin{verbatim}
alpar@9 157 int glp_term_out(int flag);
alpar@9 158 \end{verbatim}
alpar@9 159
alpar@9 160 \subsubsection*{Description}
alpar@9 161
alpar@9 162 Depending on the parameter flag the routine \verb|glp_term_out| enables
alpar@9 163 or disables terminal output performed by glpk routines:
alpar@9 164
alpar@9 165 \verb|GLP_ON | --- enable terminal output;
alpar@9 166
alpar@9 167 \verb|GLP_OFF| --- disable terminal output.
alpar@9 168
alpar@9 169 \subsubsection*{Returns}
alpar@9 170
alpar@9 171 The routine \verb|glp_term_out| returns the previous value of the
alpar@9 172 terminal output flag (\verb|GLP_ON| or \verb|GLP_OFF|).
alpar@9 173
alpar@9 174 \subsection{glp\_term\_hook---intercept terminal output}
alpar@9 175
alpar@9 176 \subsubsection*{Synopsis}
alpar@9 177
alpar@9 178 \begin{verbatim}
alpar@9 179 void glp_term_hook(int (*func)(void *info, const char *s),
alpar@9 180 void *info);
alpar@9 181 \end{verbatim}
alpar@9 182
alpar@9 183 \subsubsection*{Description}
alpar@9 184
alpar@9 185 The routine \verb|glp_term_hook| installs the user-defined hook routine
alpar@9 186 to intercept all terminal output performed by GLPK routines.
alpar@9 187
alpar@9 188 %This feature can be used to redirect the terminal output to other
alpar@9 189 %destination, for example, to a file or a text window.
alpar@9 190
alpar@9 191 The parameter {\it func} specifies the user-defined hook routine. It is
alpar@9 192 called from an internal printing routine, which passes to it two
alpar@9 193 parameters: {\it info} and {\it s}. The parameter {\it info} is a
alpar@9 194 transit pointer specified in corresponding call to the routine
alpar@9 195 \verb|glp_term_hook|; it may be used to pass some additional information
alpar@9 196 to the hook routine. The parameter {\it s} is a pointer to the null
alpar@9 197 terminated character string, which is intended to be written to the
alpar@9 198 terminal. If the hook routine returns zero, the printing routine writes
alpar@9 199 the string {\it s} to the terminal in a usual way; otherwise, if the
alpar@9 200 hook routine returns non-zero, no terminal output is performed.
alpar@9 201
alpar@9 202 To uninstall the hook routine both parameters {\it func} and {\it info}
alpar@9 203 should be specified as \verb|NULL|.
alpar@9 204
alpar@9 205 \newpage
alpar@9 206
alpar@9 207 \subsubsection*{Example}
alpar@9 208
alpar@9 209 \begin{footnotesize}
alpar@9 210 \begin{verbatim}
alpar@9 211 static int hook(void *info, const char *s)
alpar@9 212 { FILE *foo = info;
alpar@9 213 fputs(s, foo);
alpar@9 214 return 1;
alpar@9 215 }
alpar@9 216
alpar@9 217 int main(void)
alpar@9 218 { FILE *foo;
alpar@9 219 . . .
alpar@9 220 /* redirect terminal output */
alpar@9 221 glp_term_hook(hook, foo);
alpar@9 222 . . .
alpar@9 223 /* resume terminal output */
alpar@9 224 glp_term_hook(NULL, NULL);
alpar@9 225 . . .
alpar@9 226 }
alpar@9 227 \end{verbatim}
alpar@9 228 \end{footnotesize}
alpar@9 229
alpar@9 230 \subsection{glp\_open\_tee---start copying terminal output}
alpar@9 231
alpar@9 232 \subsubsection*{Synopsis}
alpar@9 233
alpar@9 234 \begin{verbatim}
alpar@9 235 int glp_open_tee(const char *fname);
alpar@9 236 \end{verbatim}
alpar@9 237
alpar@9 238 \subsubsection*{Description}
alpar@9 239
alpar@9 240 The routine \verb|glp_open_tee| starts copying all the terminal output
alpar@9 241 to an output text file, whose name is specified by the character string
alpar@9 242 \verb|fname|.
alpar@9 243
alpar@9 244 \subsubsection*{Returns}
alpar@9 245
alpar@9 246 The routine \verb|glp_open_tee| returns one of the following codes:
alpar@9 247
alpar@9 248 \noindent
alpar@9 249 0 --- operation successful;
alpar@9 250
alpar@9 251 \noindent
alpar@9 252 1 --- copying terminal output is already active;
alpar@9 253
alpar@9 254 \noindent
alpar@9 255 2 --- unable to create output file.
alpar@9 256
alpar@9 257 \newpage
alpar@9 258
alpar@9 259 \subsection{glp\_close\_tee---stop copying terminal output}
alpar@9 260
alpar@9 261 \subsubsection*{Synopsis}
alpar@9 262
alpar@9 263 \begin{verbatim}
alpar@9 264 int glp_close_tee(void);
alpar@9 265 \end{verbatim}
alpar@9 266
alpar@9 267 \subsubsection*{Description}
alpar@9 268
alpar@9 269 The routine \verb|glp_close_tee| stops copying the terminal output to
alpar@9 270 the output text file previously open by the routine \verb|glp_open_tee|
alpar@9 271 closing that file.
alpar@9 272
alpar@9 273 \subsubsection*{Returns}
alpar@9 274
alpar@9 275 The routine \verb|glp_close_tee| returns one of the following codes:
alpar@9 276
alpar@9 277 \noindent
alpar@9 278 0 --- operation successful;
alpar@9 279
alpar@9 280 \noindent
alpar@9 281 1 --- copying terminal output was not started.
alpar@9 282
alpar@9 283 \subsection{glp\_error---display error message and terminate execution}
alpar@9 284
alpar@9 285 \subsubsection*{Synopsis}
alpar@9 286
alpar@9 287 \begin{verbatim}
alpar@9 288 void glp_error(const char *fmt, ...);
alpar@9 289 \end{verbatim}
alpar@9 290
alpar@9 291 \subsubsection*{Description}
alpar@9 292
alpar@9 293 The routine \verb|glp_error| (implemented as a macro) formats its
alpar@9 294 parameters using the format control string \verb|fmt|, writes the
alpar@9 295 formatted message to the terminal, and then abnormally terminates the
alpar@9 296 program.
alpar@9 297
alpar@9 298 \subsection{glp\_assert---check logical condition}
alpar@9 299
alpar@9 300 \subsubsection*{Synopsis}
alpar@9 301
alpar@9 302 \begin{verbatim}
alpar@9 303 void glp_assert(int expr);
alpar@9 304 \end{verbatim}
alpar@9 305
alpar@9 306 \subsubsection*{Description}
alpar@9 307
alpar@9 308 The routine \verb|glp_assert| (implemented as a macro) checks
alpar@9 309 a logical condition specified by the expression \verb|expr|. If the
alpar@9 310 condition is true (non-zero), the routine does nothing; otherwise, if
alpar@9 311 the condition is false (zero), the routine prints an error message and
alpar@9 312 abnormally terminates the program.
alpar@9 313
alpar@9 314 This routine is a replacement of the standard C function \verb|assert|
alpar@9 315 and used by all GLPK routines to check program logic. The application
alpar@9 316 program may use \verb|glp_assert| for the same purpose.
alpar@9 317
alpar@9 318 \subsection{glp\_error\_hook---install hook to intercept abnormal
alpar@9 319 termination}
alpar@9 320
alpar@9 321 \subsubsection*{Synopsis}
alpar@9 322
alpar@9 323 \begin{verbatim}
alpar@9 324 void glp_error_hook(void (*func)(void *info), void *info);
alpar@9 325 \end{verbatim}
alpar@9 326
alpar@9 327 \subsubsection*{Description}
alpar@9 328
alpar@9 329 The routine \verb|glp_error_hook| installs a user-defined hook routine
alpar@9 330 to intercept abnormal termination.
alpar@9 331
alpar@9 332 The parameter \verb|func| specifies the user-defined hook routine. It
alpar@9 333 is called from the routine \verb|glp_error| before the latter calls the
alpar@9 334 abort function to abnormally terminate the application program because
alpar@9 335 of fatal error. The parameter \verb|info| is a transit pointer,
alpar@9 336 specified in the corresponding call to the routine
alpar@9 337 \verb|glp_error_hook|; it may be used to pass some information to the
alpar@9 338 hook routine.
alpar@9 339
alpar@9 340 To uninstall the hook routine the parameters \verb|func| and \verb|info|
alpar@9 341 should be specified as \verb|NULL|.
alpar@9 342
alpar@9 343 \subsubsection*{Usage note}
alpar@9 344
alpar@9 345 If the hook routine returns, the application program is abnormally
alpar@9 346 terminated. To prevent abnormal termnation the hook routine may perform
alpar@9 347 a global jump using the standard function \verb|longjmp|, in which case
alpar@9 348 the application program {\it must} call the routine \verb|glp_free_env|.
alpar@9 349
alpar@9 350 \subsection{glp\_malloc---allocate memory block}
alpar@9 351
alpar@9 352 \subsubsection*{Synopsis}
alpar@9 353
alpar@9 354 \begin{verbatim}
alpar@9 355 void *glp_malloc(int size);
alpar@9 356 \end{verbatim}
alpar@9 357
alpar@9 358 \subsubsection*{Description}
alpar@9 359
alpar@9 360 The routine \verb|glp_malloc| dynamically allocates a memory block of
alpar@9 361 \verb|size| bytes long. Should note that:
alpar@9 362
alpar@9 363 1) the parameter \verb|size| must be positive;
alpar@9 364
alpar@9 365 2) being allocated the memory block contains arbitrary data, that is,
alpar@9 366 it is {\it not} initialized by binary zeros;
alpar@9 367
alpar@9 368 3) if the block cannot be allocated due to insufficient memory, the
alpar@9 369 routine prints an error message and abnormally terminates the program.
alpar@9 370
alpar@9 371 This routine is a replacement of the standard C function \verb|malloc|
alpar@9 372 and used by all GLPK routines for dynamic memory allocation. The
alpar@9 373 application program may use \verb|glp_malloc| for the same purpose.
alpar@9 374
alpar@9 375 \subsubsection*{Returns}
alpar@9 376
alpar@9 377 The routine \verb|glp_malloc| returns a pointer to the memory block
alpar@9 378 allocated. To free this block the routine \verb|glp_free| (not the
alpar@9 379 standard C function \verb|free|!) must be used.
alpar@9 380
alpar@9 381 \subsection{glp\_calloc---allocate memory block}
alpar@9 382
alpar@9 383 \subsubsection*{Synopsis}
alpar@9 384
alpar@9 385 \begin{verbatim}
alpar@9 386 void *glp_calloc(int n, int size);
alpar@9 387 \end{verbatim}
alpar@9 388
alpar@9 389 \subsubsection*{Description}
alpar@9 390
alpar@9 391 The routine \verb|glp_calloc| dynamically allocates a memory block of
alpar@9 392 \verb|n|$\times$\verb|size| bytes long. Should note that:
alpar@9 393
alpar@9 394 1) both parameters \verb|n| and \verb|size| must be positive;
alpar@9 395
alpar@9 396 2) being allocated the memory block contains arbitrary data, that is,
alpar@9 397 it is {\it not} initialized by binary zeros;
alpar@9 398
alpar@9 399 3) if the block cannot be allocated due to insufficient memory, the
alpar@9 400 routine prints an error message and abnormally terminates the program.
alpar@9 401
alpar@9 402 This routine is a replacement of the standard C function \verb|calloc|
alpar@9 403 (with exception that the block is not cleaned) and used by all GLPK
alpar@9 404 routines for dynamic memory allocation. The application program may use
alpar@9 405 \verb|glp_calloc| for the same purpose.
alpar@9 406
alpar@9 407 \subsubsection*{Returns}
alpar@9 408
alpar@9 409 The routine \verb|glp_calloc| returns a pointer to the memory block
alpar@9 410 allocated. To free this block the routine \verb|glp_free| (not the
alpar@9 411 standard C function \verb|free|!) must be used.
alpar@9 412
alpar@9 413 \subsection{glp\_free---free memory block}
alpar@9 414
alpar@9 415 \subsubsection*{Synopsis}
alpar@9 416
alpar@9 417 \begin{verbatim}
alpar@9 418 void glp_free(void *ptr);
alpar@9 419 \end{verbatim}
alpar@9 420
alpar@9 421 \subsubsection*{Description}
alpar@9 422
alpar@9 423 The routine \verb|glp_free| frees (deallocates) a memory block pointed
alpar@9 424 to by \verb|ptr|, which was previously allocated by the routine
alpar@9 425 \verb|glp_malloc| or \verb|glp_calloc|. Note that the pointer \verb|ptr|
alpar@9 426 must valid and must not be \verb|NULL|.
alpar@9 427
alpar@9 428 This routine is a replacement of the standard C function \verb|free|
alpar@9 429 and used by all GLPK routines for dynamic memory allocation. The
alpar@9 430 application program may use \verb|glp_free| for the same purpose.
alpar@9 431
alpar@9 432 \subsection{glp\_mem\_usage---get memory usage information}
alpar@9 433
alpar@9 434 \subsubsection*{Synopsis}
alpar@9 435
alpar@9 436 \begin{verbatim}
alpar@9 437 void glp_mem_usage(int *count, int *cpeak, glp_long *total,
alpar@9 438 glp_long *tpeak);
alpar@9 439 \end{verbatim}
alpar@9 440
alpar@9 441 \subsubsection*{Description}
alpar@9 442
alpar@9 443 The routine \verb|glp_mem_usage| reports some information about
alpar@9 444 utilization of the memory by the routines \verb|glp_malloc|,
alpar@9 445 \verb|glp_calloc|, and \verb|glp_free|. Information is stored to
alpar@9 446 locations specified by corresponding parameters (see below). Any
alpar@9 447 parameter can be specified as \verb|NULL|, in which case corresponding
alpar@9 448 information is not stored.
alpar@9 449
alpar@9 450 \verb|*count| is the number of currently allocated memory blocks.
alpar@9 451
alpar@9 452 \verb|*cpeak| is the peak value of \verb|*count| reached since the
alpar@9 453 initialization of the GLPK library environment.
alpar@9 454
alpar@9 455 \verb|*total| is the total amount, in bytes, of currently allocated
alpar@9 456 memory blocks.
alpar@9 457
alpar@9 458 \verb|*tpeak| is the peak value of \verb|*total| reached since the
alpar@9 459 initialization of the GLPK library envirionment.
alpar@9 460
alpar@9 461 \subsubsection*{Example}
alpar@9 462
alpar@9 463 \begin{footnotesize}
alpar@9 464 \begin{verbatim}
alpar@9 465 glp_mem_usage(&count, NULL, NULL, NULL);
alpar@9 466 printf("%d memory block(s) are still allocated\n", count);
alpar@9 467 \end{verbatim}
alpar@9 468 \end{footnotesize}
alpar@9 469
alpar@9 470 \subsection{glp\_mem\_limit---set memory usage limit}
alpar@9 471
alpar@9 472 \subsubsection*{Synopsis}
alpar@9 473
alpar@9 474 \begin{verbatim}
alpar@9 475 void glp_mem_limit(int limit);
alpar@9 476 \end{verbatim}
alpar@9 477
alpar@9 478 \subsubsection*{Description}
alpar@9 479
alpar@9 480 The routine \verb|glp_mem_limit| limits the amount of memory available
alpar@9 481 for dynamic allocation (with the routines \verb|glp_malloc| and
alpar@9 482 \verb|glp_calloc|) to \verb|limit| megabytes.
alpar@9 483
alpar@9 484 \subsection{glp\_time---determine current universal time}
alpar@9 485
alpar@9 486 \subsubsection*{Synopsis}
alpar@9 487
alpar@9 488 \begin{verbatim}
alpar@9 489 glp_long glp_time(void);
alpar@9 490 \end{verbatim}
alpar@9 491
alpar@9 492 \subsection*{Returns}
alpar@9 493
alpar@9 494 The routine \verb|glp_time| returns the current universal time (UTC),
alpar@9 495 in milliseconds, elapsed since 00:00:00 GMT January 1, 1970.
alpar@9 496
alpar@9 497 \subsection{glp\_difftime---compute difference between two time values}
alpar@9 498
alpar@9 499 \subsubsection*{Synopsis}
alpar@9 500
alpar@9 501 \begin{verbatim}
alpar@9 502 double glp_difftime(glp_long t1, glp_long t0);
alpar@9 503 \end{verbatim}
alpar@9 504
alpar@9 505 \subsection*{Returns}
alpar@9 506
alpar@9 507 The routine \verb|glp_difftime| returns the difference between two time
alpar@9 508 values \verb|t1| and \verb|t0|, expressed in seconds.
alpar@9 509
alpar@9 510 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
alpar@9 511
alpar@9 512 \newpage
alpar@9 513
alpar@9 514 \section{Plain data file reading routines}
alpar@9 515
alpar@9 516 \subsection{Introduction}
alpar@9 517
alpar@9 518 On developing simple applications to solve optimization problems it is
alpar@9 519 often needed to read data from plain text files. To do this the standard
alpar@9 520 C function \verb|fscanf| may be used, however, it is not convenient; for
alpar@9 521 example, if it scans an integer number according to the format
alpar@9 522 specification `\verb|%d|', and that number is coded incorrectly,
alpar@9 523 no diagnostics is provided.
alpar@9 524
alpar@9 525 This section describes a set of GLPK API routines, which may be used in
alpar@9 526 application programs to simplify reading data from plain text files.
alpar@9 527
alpar@9 528 \subsubsection*{Example 1}
alpar@9 529
alpar@9 530 The following main program reads ten integer numbers from plain text
alpar@9 531 file \verb|data.txt| and prints their sum.
alpar@9 532
alpar@9 533 \begin{footnotesize}
alpar@9 534 \begin{verbatim}
alpar@9 535 /* sdfsamp1.c */
alpar@9 536
alpar@9 537 #include <stdio.h>
alpar@9 538 #include <stdlib.h>
alpar@9 539 #include <glpk.h>
alpar@9 540
alpar@9 541 int main(void)
alpar@9 542 { glp_data *data;
alpar@9 543 int j, num, sum;
alpar@9 544 /* open plain data file */
alpar@9 545 data = glp_sdf_open_file("data.txt");
alpar@9 546 if (data == NULL) exit(EXIT_FAILURE);
alpar@9 547 sum = 0;
alpar@9 548 for (j = 1; j <= 10; j++)
alpar@9 549 { /* read next integer number */
alpar@9 550 num = glp_sdf_read_int(data);
alpar@9 551 sum += num;
alpar@9 552 }
alpar@9 553 printf("sum = %d\n", sum);
alpar@9 554 /* close plain data file */
alpar@9 555 glp_sdf_close_file(data);
alpar@9 556 return 0;
alpar@9 557 }
alpar@9 558
alpar@9 559 /* eof */
alpar@9 560 \end{verbatim}
alpar@9 561 \end{footnotesize}
alpar@9 562
alpar@9 563 The input data are coded in free format. For example, the file
alpar@9 564 \verb|data.txt| may look like this:
alpar@9 565
alpar@9 566 \begin{footnotesize}
alpar@9 567 \begin{verbatim}
alpar@9 568 123 65 432 890 -12 743 895 -7 111 326
alpar@9 569 \end{verbatim}
alpar@9 570 \end{footnotesize}
alpar@9 571
alpar@9 572 \noindent
alpar@9 573 or like this:
alpar@9 574
alpar@9 575 \begin{footnotesize}
alpar@9 576 \begin{verbatim}
alpar@9 577 123 65 432 890 -12
alpar@9 578 743 895 -7 111 326
alpar@9 579 \end{verbatim}
alpar@9 580 \end{footnotesize}
alpar@9 581
alpar@9 582 \noindent
alpar@9 583 If the input data file contains incorrect data, the routine
alpar@9 584 \verb|glp_sdf_read_int| prints an error message and, if no error
alpar@9 585 handling is provided by the application program, abnormally terminates
alpar@9 586 program execution. For example, the file \verb|data.txt| could contain
alpar@9 587 the following data:
alpar@9 588
alpar@9 589 \begin{footnotesize}
alpar@9 590 \begin{verbatim}
alpar@9 591 123 65 432 890 -12
alpar@9 592 743 895 =7 111 326
alpar@9 593 \end{verbatim}
alpar@9 594 \end{footnotesize}
alpar@9 595
alpar@9 596 \noindent
alpar@9 597 in which case the error message would be the following:
alpar@9 598
alpar@9 599 \begin{footnotesize}
alpar@9 600 \begin{verbatim}
alpar@9 601 data.txt:2: cannot convert `=7' to integer
alpar@9 602 \end{verbatim}
alpar@9 603 \end{footnotesize}
alpar@9 604
alpar@9 605 \subsubsection*{Example 2}
alpar@9 606
alpar@9 607 As it was said above, by default any attempt to read incorrect data
alpar@9 608 leads to abnormal termination. However, sometimes it is desirable to
alpar@9 609 catch such errors. This feature is illustrated by the following main
alpar@9 610 program, which does the same job as in the previous example.
alpar@9 611
alpar@9 612 \begin{footnotesize}
alpar@9 613 \begin{verbatim}
alpar@9 614 /* sdfsamp2.c */
alpar@9 615
alpar@9 616 #include <setjmp.h>
alpar@9 617 #include <stdio.h>
alpar@9 618 #include <stdlib.h>
alpar@9 619 #include <glpk.h>
alpar@9 620
alpar@9 621 int main(void)
alpar@9 622 { glp_data *data;
alpar@9 623 jmp_buf jump;
alpar@9 624 int j, num, sum, ret;
alpar@9 625 /* open plain data file */
alpar@9 626 data = glp_sdf_open_file("data.txt");
alpar@9 627 if (data == NULL)
alpar@9 628 { ret = EXIT_FAILURE;
alpar@9 629 goto done;
alpar@9 630 }
alpar@9 631 /* set up error handling */
alpar@9 632 if (setjmp(jump))
alpar@9 633 { ret = EXIT_FAILURE;
alpar@9 634 goto done;
alpar@9 635 }
alpar@9 636 glp_sdf_set_jump(data, jump);
alpar@9 637 /* read and process data */
alpar@9 638 sum = 0;
alpar@9 639 for (j = 1; j <= 10; j++)
alpar@9 640 { /* read next integer number */
alpar@9 641 num = glp_sdf_read_int(data);
alpar@9 642 if (abs(num) > 1000)
alpar@9 643 glp_sdf_error(data, "integer %d too big\n", num);
alpar@9 644 if (num < 0)
alpar@9 645 glp_sdf_warning(data, "integer %d is negative\n", num);
alpar@9 646 sum += num;
alpar@9 647 }
alpar@9 648 printf("sum = %d\n", sum);
alpar@9 649 ret = EXIT_SUCCESS;
alpar@9 650 done: /* close plain data file */
alpar@9 651 if (data != NULL) glp_sdf_close_file(data);
alpar@9 652 return ret;
alpar@9 653 }
alpar@9 654
alpar@9 655 /* eof */
alpar@9 656 \end{verbatim}
alpar@9 657 \end{footnotesize}
alpar@9 658
alpar@9 659 \subsection{glp\_sdf\_open\_file---open plain data file}
alpar@9 660
alpar@9 661 \subsubsection*{Synopsis}
alpar@9 662
alpar@9 663 \begin{verbatim}
alpar@9 664 glp_data *glp_sdf_open_file(const char *fname);
alpar@9 665 \end{verbatim}
alpar@9 666
alpar@9 667 \subsubsection*{Description}
alpar@9 668
alpar@9 669 The routine \verb|glp_sdf_open_file| opens a plain data file, whose
alpar@9 670 name is specified by the character string \verb|fname|.
alpar@9 671
alpar@9 672 \subsubsection*{Returns}
alpar@9 673
alpar@9 674 If the operation was successful, the routine \verb|glp_sdf_open_file|
alpar@9 675 returns a pointer to the opaque program object of the type
alpar@9 676 \verb|glp_data|\footnote{This data structure is declared in the header
alpar@9 677 file {\tt glpk.h}.} associated with the plain data file. Otherwise, if
alpar@9 678 the operation failed, the routine prints an error message and returns
alpar@9 679 \verb|NULL|.
alpar@9 680
alpar@9 681 \subsubsection*{Note}
alpar@9 682
alpar@9 683 The application program should use the pointer returned by the routine
alpar@9 684 \verb|glp_sdf_open_file| to perform all subsequent operations on the
alpar@9 685 data file.
alpar@9 686
alpar@9 687 \newpage
alpar@9 688
alpar@9 689 \subsection{glp\_sdf\_set\_jump---set up error handling}
alpar@9 690
alpar@9 691 \subsubsection*{Synopsis}
alpar@9 692
alpar@9 693 \begin{verbatim}
alpar@9 694 void glp_sdf_set_jump(glp_data *data, jmp_buf jump);
alpar@9 695 \end{verbatim}
alpar@9 696
alpar@9 697 \subsubsection*{Description}
alpar@9 698
alpar@9 699 The routine \verb|glp_sdf_set_jump| sets up error handling for the
alpar@9 700 plain data file specified by the parameter \verb|data|.
alpar@9 701
alpar@9 702 The parameter \verb|jump| specifies the environment buffer, which must
alpar@9 703 be initialized with the standard C function \verb|setjmp| prior to call
alpar@9 704 to the routine \verb|glp_sdf_set_jump|. Detecting any incorrect data in
alpar@9 705 the corresponding plain data file will cause non-local ``go to'' by
alpar@9 706 a call to the standard C function \verb|longjmp|.
alpar@9 707
alpar@9 708 The parameter \verb|jump| can be specified as \verb|NULL|, in which
alpar@9 709 case the routine \verb|glp_sdf_set_jump| restores the default behavior,
alpar@9 710 in which case detecting incorrect data leads to abnormal termination.
alpar@9 711
alpar@9 712 \subsection{glp\_sdf\_error---print error message}
alpar@9 713
alpar@9 714 \subsubsection*{Synopsis}
alpar@9 715
alpar@9 716 \begin{verbatim}
alpar@9 717 void glp_sdf_error(glp_data *data, const char *fmt, ...);
alpar@9 718 \end{verbatim}
alpar@9 719
alpar@9 720 \subsubsection*{Description}
alpar@9 721
alpar@9 722 The routine \verb|glp_sdf_error| prints an error message related to the
alpar@9 723 plain data file specified by the parameter \verb|data|. If error handing
alpar@9 724 was not previously provided, the routine then abnormally terminates
alpar@9 725 execution of the application program. Otherwise, it signals about the
alpar@9 726 error by a call to the standard C function \verb|longjmp|.
alpar@9 727
alpar@9 728 The character string \verb|fmt| and optional parameters following it
alpar@9 729 have the same meaning as for the standard C function \verb|printf|.
alpar@9 730
alpar@9 731 The message produced by the routine \verb|glp_sdf_error| looks like
alpar@9 732 follows:
alpar@9 733
alpar@9 734 \medskip
alpar@9 735
alpar@9 736 {\it file}{\tt :}{\it line}{\tt :} {\it message text}
alpar@9 737
alpar@9 738 \medskip
alpar@9 739
alpar@9 740 \noindent
alpar@9 741 where {\it file} is the filename passed to the routine
alpar@9 742 \verb|glp_sdf_open| and {\it line} is the current line number.
alpar@9 743
alpar@9 744 \newpage
alpar@9 745
alpar@9 746 \subsection{glp\_sdf\_warning---print warning message}
alpar@9 747
alpar@9 748 \subsubsection*{Synopsis}
alpar@9 749
alpar@9 750 \begin{verbatim}
alpar@9 751 void glp_sdf_warning(glp_data *data, const char *fmt, ...);
alpar@9 752 \end{verbatim}
alpar@9 753
alpar@9 754 \subsubsection*{Description}
alpar@9 755
alpar@9 756 The routine \verb|glp_sdf_warning| prints a warning message related to
alpar@9 757 the plain data file specified by the parameter \verb|data|.
alpar@9 758
alpar@9 759 The character string \verb|fmt| and optional parameters following it
alpar@9 760 have the same meaning as for the standard C function \verb|printf|.
alpar@9 761
alpar@9 762 The message produced by the routine \verb|glp_sdf_warning| looks like
alpar@9 763 follows:
alpar@9 764
alpar@9 765 \medskip
alpar@9 766
alpar@9 767 {\it file}{\tt :}{\it line}\verb|: warning:| {\it message text}
alpar@9 768
alpar@9 769 \medskip
alpar@9 770
alpar@9 771 \noindent
alpar@9 772 where {\it file} is the filename passed to the routine
alpar@9 773 \verb|glp_sdf_open| and {\it line} is the current line number.
alpar@9 774
alpar@9 775 \subsection{glp\_sdf\_read\_int---read integer number}
alpar@9 776
alpar@9 777 \subsubsection*{Synopsis}
alpar@9 778
alpar@9 779 \begin{verbatim}
alpar@9 780 int glp_sdf_read_int(glp_data *data);
alpar@9 781 \end{verbatim}
alpar@9 782
alpar@9 783 \subsubsection*{Description}
alpar@9 784
alpar@9 785 The routine \verb|glp_sdf_read_int| skips optional white-space
alpar@9 786 characters and then reads an integer number from the plain data file
alpar@9 787 specified by the parameter \verb|data|. If the operation failed, the
alpar@9 788 routine \verb|glp_sdf_read_int| calls the routine \verb|glp_sdf_error|
alpar@9 789 (see above).
alpar@9 790
alpar@9 791 \subsubsection*{Returns}
alpar@9 792
alpar@9 793 The routine \verb|glp_sdf_read_int| returns the integer number read.
alpar@9 794
alpar@9 795 \newpage
alpar@9 796
alpar@9 797 \subsection{glp\_sdf\_read\_num---read floating-point number}
alpar@9 798
alpar@9 799 \subsubsection*{Synopsis}
alpar@9 800
alpar@9 801 \begin{verbatim}
alpar@9 802 double glp_sdf_read_num(glp_data *data);
alpar@9 803 \end{verbatim}
alpar@9 804
alpar@9 805 \subsubsection*{Description}
alpar@9 806
alpar@9 807 The routine \verb|glp_sdf_read_num| skips optional white-space
alpar@9 808 characters and then reads a floating-point number from the plain data
alpar@9 809 file specified by the parameter \verb|data|. If the operation failed,
alpar@9 810 the routine \verb|glp_sdf_num| calls the routine \verb|glp_sdf_error|
alpar@9 811 (see above).
alpar@9 812
alpar@9 813 \subsubsection*{Returns}
alpar@9 814
alpar@9 815 The routine \verb|glp_sdf_read_num| returns the floating-point number
alpar@9 816 read.
alpar@9 817
alpar@9 818 \subsection{glp\_sdf\_read\_item---read data item}
alpar@9 819
alpar@9 820 \subsubsection*{Synopsis}
alpar@9 821
alpar@9 822 \begin{verbatim}
alpar@9 823 const char *glp_sdf_read_item(glp_data *data);
alpar@9 824 \end{verbatim}
alpar@9 825
alpar@9 826 \subsubsection*{Description}
alpar@9 827
alpar@9 828 The routine \verb|glp_sdf_read_item| skips optional white-space
alpar@9 829 characters and then reads a data item from the plain data file specified
alpar@9 830 by the parameter \verb|data|. If the operation failed, the routine
alpar@9 831 \verb|glp_sdf_read_item| calls the routine \verb|glp_sdf_error| (see
alpar@9 832 above).
alpar@9 833
alpar@9 834 {\it Data item} is a sequence of 1 to 255 arbitrary graphic characters
alpar@9 835 delimited by white-space characters. Data items may be used to represent
alpar@9 836 symbolic names, identifiers, etc.
alpar@9 837
alpar@9 838 \subsubsection*{Returns}
alpar@9 839
alpar@9 840 The routine \verb|glp_sdf_read_item| returns a pointer to the internal
alpar@9 841 buffer, which contains the data item read in the form of a
alpar@9 842 null-terminated character string.
alpar@9 843
alpar@9 844 \newpage
alpar@9 845
alpar@9 846 \subsection{glp\_sdf\_read\_text---read text until end of line}
alpar@9 847
alpar@9 848 \subsubsection*{Synopsis}
alpar@9 849
alpar@9 850 \begin{verbatim}
alpar@9 851 const char *glp_sdf_read_text(glp_data *data);
alpar@9 852 \end{verbatim}
alpar@9 853
alpar@9 854 \subsubsection*{Description}
alpar@9 855
alpar@9 856 The routine \verb|glp_sdf_read_text| reads a text from the plain data
alpar@9 857 file specified by the parameter \verb|data|.
alpar@9 858
alpar@9 859 Reading starts from the current position and extends until end of the
alpar@9 860 current line. Initial and trailing white-space characters as well as
alpar@9 861 the newline character are not included in the text.
alpar@9 862
alpar@9 863 \subsubsection*{Returns}
alpar@9 864
alpar@9 865 The routine \verb|glp_sdf_read_text| returns a pointer to the internal
alpar@9 866 buffer, which contains the text read in the form of a null-terminated
alpar@9 867 character string.
alpar@9 868
alpar@9 869 \subsection{glp\_sdf\_line---determine current line number}
alpar@9 870
alpar@9 871 \subsubsection*{Synopsis}
alpar@9 872
alpar@9 873 \begin{verbatim}
alpar@9 874 int glp_sdf_line(glp_data *data);
alpar@9 875 \end{verbatim}
alpar@9 876
alpar@9 877 \subsubsection*{Returns}
alpar@9 878
alpar@9 879 The routine \verb|glp_sdf_line| returns the current line number for the
alpar@9 880 plain data file specified by the parameter \verb|data|.
alpar@9 881
alpar@9 882 \subsection{glp\_sdf\_close\_file---close plain data file}
alpar@9 883
alpar@9 884 \subsubsection*{Synopsis}
alpar@9 885
alpar@9 886 \begin{verbatim}
alpar@9 887 void glp_sdf_close_file(glp_data *data);
alpar@9 888 \end{verbatim}
alpar@9 889
alpar@9 890 \subsubsection*{Description}
alpar@9 891
alpar@9 892 The routine \verb|glp_sdf_close_file| closes the plain data file
alpar@9 893 specified by the parameter \verb|data| and frees all the resources
alpar@9 894 allocated to this program object.
alpar@9 895
alpar@9 896 %* eof *%