lemon-project-template-glpk

comparison 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
comparison
equal deleted inserted replaced
-1:000000000000 0:ead2505bc460
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 *%