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