lemon-project-template-glpk
view deps/glpk/doc/glpk06.tex @ 9:33de93886c88
Import GLPK 4.47
| author | Alpar Juttner <alpar@cs.elte.hu> |
|---|---|
| date | Sun, 06 Nov 2011 20:59:10 +0100 |
| parents | |
| children |
line source
1 %* glpk06.tex *%
3 \chapter{Miscellaneous API Routines}
5 \section{GLPK environment routines}
7 \subsection{glp\_long---64-bit integer data type}
9 Some GLPK API routines use 64-bit integer data type, which is declared
10 in the header \verb|glpk.h| as follows:
12 \begin{verbatim}
13 typedef struct { int lo, hi; } glp_long;
14 \end{verbatim}
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.}
22 \subsection{glp\_init\_env---initialize GLPK environment}
24 \subsubsection*{Synopsis}
26 \begin{verbatim}
27 int glp_init_env(void);
28 \end{verbatim}
30 \subsubsection*{Description}
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.
36 \newpage
38 \subsubsection*{Returns}
40 The routine \verb|glp_init_env| returns one of the following codes:
42 \noindent
43 0 --- initialization successful;
45 \noindent
46 1 --- environment is already initialized;
48 \noindent
49 2 --- initialization failed (insufficient memory);
51 \noindent
52 3 --- initialization failed (unsupported programming model).
54 \subsection{glp\_version---determine library version}
56 \subsubsection*{Synopsis}
58 \begin{verbatim}
59 const char *glp_version(void);
60 \end{verbatim}
62 \subsubsection*{Returns}
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"|.
69 \subsubsection*{Example}
71 \begin{footnotesize}
72 \begin{verbatim}
73 printf("GLPK version is %s\n", glp_version());
74 \end{verbatim}
75 \end{footnotesize}
77 \subsection{glp\_free\_env---free GLPK environment}
79 \subsubsection*{Synopsis}
81 \begin{verbatim}
82 int glp_free_env(void);
83 \end{verbatim}
85 \subsubsection*{Description}
87 The routine \verb|glp_free_env| frees all resources used by GLPK
88 routines (memory blocks, etc.) which are currently still in use.
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|.
97 Note that a call to \verb|glp_free_env| invalidates all problem objects
98 which still exist.
100 \subsubsection*{Returns}
102 The routine \verb|glp_free_env| returns one of the following codes:
104 \noindent
105 0 --- termination successful;
107 \noindent
108 1 --- environment is inactive (was not initialized).
110 \subsection{glp\_printf---write formatted output to terminal}
112 \subsubsection*{Synopsis}
114 \begin{verbatim}
115 void glp_printf(const char *fmt, ...);
116 \end{verbatim}
118 \subsubsection*{Description}
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.
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|.
130 \subsection{glp\_vprintf---write formatted output to terminal}
132 \subsubsection*{Synopsis}
134 \begin{verbatim}
135 void glp_vprintf(const char *fmt, va_list arg);
136 \end{verbatim}
138 \subsubsection*{Description}
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.
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|.
150 \newpage
152 \subsection{glp\_term\_out---enable/disable terminal output}
154 \subsubsection*{Synopsis}
156 \begin{verbatim}
157 int glp_term_out(int flag);
158 \end{verbatim}
160 \subsubsection*{Description}
162 Depending on the parameter flag the routine \verb|glp_term_out| enables
163 or disables terminal output performed by glpk routines:
165 \verb|GLP_ON | --- enable terminal output;
167 \verb|GLP_OFF| --- disable terminal output.
169 \subsubsection*{Returns}
171 The routine \verb|glp_term_out| returns the previous value of the
172 terminal output flag (\verb|GLP_ON| or \verb|GLP_OFF|).
174 \subsection{glp\_term\_hook---intercept terminal output}
176 \subsubsection*{Synopsis}
178 \begin{verbatim}
179 void glp_term_hook(int (*func)(void *info, const char *s),
180 void *info);
181 \end{verbatim}
183 \subsubsection*{Description}
185 The routine \verb|glp_term_hook| installs the user-defined hook routine
186 to intercept all terminal output performed by GLPK routines.
188 %This feature can be used to redirect the terminal output to other
189 %destination, for example, to a file or a text window.
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.
202 To uninstall the hook routine both parameters {\it func} and {\it info}
203 should be specified as \verb|NULL|.
205 \newpage
207 \subsubsection*{Example}
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 }
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}
230 \subsection{glp\_open\_tee---start copying terminal output}
232 \subsubsection*{Synopsis}
234 \begin{verbatim}
235 int glp_open_tee(const char *fname);
236 \end{verbatim}
238 \subsubsection*{Description}
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|.
244 \subsubsection*{Returns}
246 The routine \verb|glp_open_tee| returns one of the following codes:
248 \noindent
249 0 --- operation successful;
251 \noindent
252 1 --- copying terminal output is already active;
254 \noindent
255 2 --- unable to create output file.
257 \newpage
259 \subsection{glp\_close\_tee---stop copying terminal output}
261 \subsubsection*{Synopsis}
263 \begin{verbatim}
264 int glp_close_tee(void);
265 \end{verbatim}
267 \subsubsection*{Description}
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.
273 \subsubsection*{Returns}
275 The routine \verb|glp_close_tee| returns one of the following codes:
277 \noindent
278 0 --- operation successful;
280 \noindent
281 1 --- copying terminal output was not started.
283 \subsection{glp\_error---display error message and terminate execution}
285 \subsubsection*{Synopsis}
287 \begin{verbatim}
288 void glp_error(const char *fmt, ...);
289 \end{verbatim}
291 \subsubsection*{Description}
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.
298 \subsection{glp\_assert---check logical condition}
300 \subsubsection*{Synopsis}
302 \begin{verbatim}
303 void glp_assert(int expr);
304 \end{verbatim}
306 \subsubsection*{Description}
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.
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.
318 \subsection{glp\_error\_hook---install hook to intercept abnormal
319 termination}
321 \subsubsection*{Synopsis}
323 \begin{verbatim}
324 void glp_error_hook(void (*func)(void *info), void *info);
325 \end{verbatim}
327 \subsubsection*{Description}
329 The routine \verb|glp_error_hook| installs a user-defined hook routine
330 to intercept abnormal termination.
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.
340 To uninstall the hook routine the parameters \verb|func| and \verb|info|
341 should be specified as \verb|NULL|.
343 \subsubsection*{Usage note}
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|.
350 \subsection{glp\_malloc---allocate memory block}
352 \subsubsection*{Synopsis}
354 \begin{verbatim}
355 void *glp_malloc(int size);
356 \end{verbatim}
358 \subsubsection*{Description}
360 The routine \verb|glp_malloc| dynamically allocates a memory block of
361 \verb|size| bytes long. Should note that:
363 1) the parameter \verb|size| must be positive;
365 2) being allocated the memory block contains arbitrary data, that is,
366 it is {\it not} initialized by binary zeros;
368 3) if the block cannot be allocated due to insufficient memory, the
369 routine prints an error message and abnormally terminates the program.
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.
375 \subsubsection*{Returns}
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.
381 \subsection{glp\_calloc---allocate memory block}
383 \subsubsection*{Synopsis}
385 \begin{verbatim}
386 void *glp_calloc(int n, int size);
387 \end{verbatim}
389 \subsubsection*{Description}
391 The routine \verb|glp_calloc| dynamically allocates a memory block of
392 \verb|n|$\times$\verb|size| bytes long. Should note that:
394 1) both parameters \verb|n| and \verb|size| must be positive;
396 2) being allocated the memory block contains arbitrary data, that is,
397 it is {\it not} initialized by binary zeros;
399 3) if the block cannot be allocated due to insufficient memory, the
400 routine prints an error message and abnormally terminates the program.
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.
407 \subsubsection*{Returns}
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.
413 \subsection{glp\_free---free memory block}
415 \subsubsection*{Synopsis}
417 \begin{verbatim}
418 void glp_free(void *ptr);
419 \end{verbatim}
421 \subsubsection*{Description}
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|.
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.
432 \subsection{glp\_mem\_usage---get memory usage information}
434 \subsubsection*{Synopsis}
436 \begin{verbatim}
437 void glp_mem_usage(int *count, int *cpeak, glp_long *total,
438 glp_long *tpeak);
439 \end{verbatim}
441 \subsubsection*{Description}
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.
450 \verb|*count| is the number of currently allocated memory blocks.
452 \verb|*cpeak| is the peak value of \verb|*count| reached since the
453 initialization of the GLPK library environment.
455 \verb|*total| is the total amount, in bytes, of currently allocated
456 memory blocks.
458 \verb|*tpeak| is the peak value of \verb|*total| reached since the
459 initialization of the GLPK library envirionment.
461 \subsubsection*{Example}
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}
470 \subsection{glp\_mem\_limit---set memory usage limit}
472 \subsubsection*{Synopsis}
474 \begin{verbatim}
475 void glp_mem_limit(int limit);
476 \end{verbatim}
478 \subsubsection*{Description}
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.
484 \subsection{glp\_time---determine current universal time}
486 \subsubsection*{Synopsis}
488 \begin{verbatim}
489 glp_long glp_time(void);
490 \end{verbatim}
492 \subsection*{Returns}
494 The routine \verb|glp_time| returns the current universal time (UTC),
495 in milliseconds, elapsed since 00:00:00 GMT January 1, 1970.
497 \subsection{glp\_difftime---compute difference between two time values}
499 \subsubsection*{Synopsis}
501 \begin{verbatim}
502 double glp_difftime(glp_long t1, glp_long t0);
503 \end{verbatim}
505 \subsection*{Returns}
507 The routine \verb|glp_difftime| returns the difference between two time
508 values \verb|t1| and \verb|t0|, expressed in seconds.
510 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
512 \newpage
514 \section{Plain data file reading routines}
516 \subsection{Introduction}
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.
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.
528 \subsubsection*{Example 1}
530 The following main program reads ten integer numbers from plain text
531 file \verb|data.txt| and prints their sum.
533 \begin{footnotesize}
534 \begin{verbatim}
535 /* sdfsamp1.c */
537 #include <stdio.h>
538 #include <stdlib.h>
539 #include <glpk.h>
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 }
559 /* eof */
560 \end{verbatim}
561 \end{footnotesize}
563 The input data are coded in free format. For example, the file
564 \verb|data.txt| may look like this:
566 \begin{footnotesize}
567 \begin{verbatim}
568 123 65 432 890 -12 743 895 -7 111 326
569 \end{verbatim}
570 \end{footnotesize}
572 \noindent
573 or like this:
575 \begin{footnotesize}
576 \begin{verbatim}
577 123 65 432 890 -12
578 743 895 -7 111 326
579 \end{verbatim}
580 \end{footnotesize}
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:
589 \begin{footnotesize}
590 \begin{verbatim}
591 123 65 432 890 -12
592 743 895 =7 111 326
593 \end{verbatim}
594 \end{footnotesize}
596 \noindent
597 in which case the error message would be the following:
599 \begin{footnotesize}
600 \begin{verbatim}
601 data.txt:2: cannot convert `=7' to integer
602 \end{verbatim}
603 \end{footnotesize}
605 \subsubsection*{Example 2}
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.
612 \begin{footnotesize}
613 \begin{verbatim}
614 /* sdfsamp2.c */
616 #include <setjmp.h>
617 #include <stdio.h>
618 #include <stdlib.h>
619 #include <glpk.h>
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 }
655 /* eof */
656 \end{verbatim}
657 \end{footnotesize}
659 \subsection{glp\_sdf\_open\_file---open plain data file}
661 \subsubsection*{Synopsis}
663 \begin{verbatim}
664 glp_data *glp_sdf_open_file(const char *fname);
665 \end{verbatim}
667 \subsubsection*{Description}
669 The routine \verb|glp_sdf_open_file| opens a plain data file, whose
670 name is specified by the character string \verb|fname|.
672 \subsubsection*{Returns}
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|.
681 \subsubsection*{Note}
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.
687 \newpage
689 \subsection{glp\_sdf\_set\_jump---set up error handling}
691 \subsubsection*{Synopsis}
693 \begin{verbatim}
694 void glp_sdf_set_jump(glp_data *data, jmp_buf jump);
695 \end{verbatim}
697 \subsubsection*{Description}
699 The routine \verb|glp_sdf_set_jump| sets up error handling for the
700 plain data file specified by the parameter \verb|data|.
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|.
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.
712 \subsection{glp\_sdf\_error---print error message}
714 \subsubsection*{Synopsis}
716 \begin{verbatim}
717 void glp_sdf_error(glp_data *data, const char *fmt, ...);
718 \end{verbatim}
720 \subsubsection*{Description}
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|.
728 The character string \verb|fmt| and optional parameters following it
729 have the same meaning as for the standard C function \verb|printf|.
731 The message produced by the routine \verb|glp_sdf_error| looks like
732 follows:
734 \medskip
736 {\it file}{\tt :}{\it line}{\tt :} {\it message text}
738 \medskip
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.
744 \newpage
746 \subsection{glp\_sdf\_warning---print warning message}
748 \subsubsection*{Synopsis}
750 \begin{verbatim}
751 void glp_sdf_warning(glp_data *data, const char *fmt, ...);
752 \end{verbatim}
754 \subsubsection*{Description}
756 The routine \verb|glp_sdf_warning| prints a warning message related to
757 the plain data file specified by the parameter \verb|data|.
759 The character string \verb|fmt| and optional parameters following it
760 have the same meaning as for the standard C function \verb|printf|.
762 The message produced by the routine \verb|glp_sdf_warning| looks like
763 follows:
765 \medskip
767 {\it file}{\tt :}{\it line}\verb|: warning:| {\it message text}
769 \medskip
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.
775 \subsection{glp\_sdf\_read\_int---read integer number}
777 \subsubsection*{Synopsis}
779 \begin{verbatim}
780 int glp_sdf_read_int(glp_data *data);
781 \end{verbatim}
783 \subsubsection*{Description}
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).
791 \subsubsection*{Returns}
793 The routine \verb|glp_sdf_read_int| returns the integer number read.
795 \newpage
797 \subsection{glp\_sdf\_read\_num---read floating-point number}
799 \subsubsection*{Synopsis}
801 \begin{verbatim}
802 double glp_sdf_read_num(glp_data *data);
803 \end{verbatim}
805 \subsubsection*{Description}
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).
813 \subsubsection*{Returns}
815 The routine \verb|glp_sdf_read_num| returns the floating-point number
816 read.
818 \subsection{glp\_sdf\_read\_item---read data item}
820 \subsubsection*{Synopsis}
822 \begin{verbatim}
823 const char *glp_sdf_read_item(glp_data *data);
824 \end{verbatim}
826 \subsubsection*{Description}
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).
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.
838 \subsubsection*{Returns}
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.
844 \newpage
846 \subsection{glp\_sdf\_read\_text---read text until end of line}
848 \subsubsection*{Synopsis}
850 \begin{verbatim}
851 const char *glp_sdf_read_text(glp_data *data);
852 \end{verbatim}
854 \subsubsection*{Description}
856 The routine \verb|glp_sdf_read_text| reads a text from the plain data
857 file specified by the parameter \verb|data|.
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.
863 \subsubsection*{Returns}
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.
869 \subsection{glp\_sdf\_line---determine current line number}
871 \subsubsection*{Synopsis}
873 \begin{verbatim}
874 int glp_sdf_line(glp_data *data);
875 \end{verbatim}
877 \subsubsection*{Returns}
879 The routine \verb|glp_sdf_line| returns the current line number for the
880 plain data file specified by the parameter \verb|data|.
882 \subsection{glp\_sdf\_close\_file---close plain data file}
884 \subsubsection*{Synopsis}
886 \begin{verbatim}
887 void glp_sdf_close_file(glp_data *data);
888 \end{verbatim}
890 \subsubsection*{Description}
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.
896 %* eof *%