COIN-OR::LEMON - Graph Library

source: glpk-cmake/doc/glpk06.tex @ 1:c445c931472f

Last change on this file since 1:c445c931472f was 1:c445c931472f, checked in by Alpar Juttner <alpar@…>, 14 years ago

Import glpk-4.45

  • Generated files and doc/notes are removed
File size: 24.8 KB
Line 
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
9Some GLPK API routines use 64-bit integer data type, which is declared
10in the header \verb|glpk.h| as follows:
11
12\begin{verbatim}
13typedef struct { int lo, hi; } glp_long;
14\end{verbatim}
15
16\noindent
17where \verb|lo| contains low 32 bits, and \verb|hi| contains high 32
18bits of 64-bit integer value.\footnote{GLPK conforms to ILP32, LLP64,
19and LP64 programming models, where the built-in type {\tt int}
20corresponds to 32-bit integers.}
21
22\subsection{glp\_init\_env---initialize GLPK environment}
23
24\subsubsection*{Synopsis}
25
26\begin{verbatim}
27int glp_init_env(void);
28\end{verbatim}
29
30\subsubsection*{Description}
31
32The routine \verb|glp_init_env| initializes the GLPK environment.
33Normally the application program does not need to call this routine,
34because it is called automatically on the first call to any API routine.
35
36\newpage
37
38\subsubsection*{Returns}
39
40The routine \verb|glp_init_env| returns one of the following codes:
41
42\noindent
430 --- initialization successful;
44
45\noindent
461 --- environment is already initialized;
47
48\noindent
492 --- initialization failed (insufficient memory);
50
51\noindent
523 --- initialization failed (unsupported programming model).
53
54\subsection{glp\_version---determine library version}
55
56\subsubsection*{Synopsis}
57
58\begin{verbatim}
59const char *glp_version(void);
60\end{verbatim}
61
62\subsubsection*{Returns}
63
64The routine \verb|glp_version| returns a pointer to a null-terminated
65character string, which specifies the version of the GLPK library in
66the 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}
73printf("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}
82int glp_free_env(void);
83\end{verbatim}
84
85\subsubsection*{Description}
86
87The routine \verb|glp_free_env| frees all resources used by GLPK
88routines (memory blocks, etc.) which are currently still in use.
89
90Normally the application program does not need to call this routine,
91because GLPK routines always free all unused resources. However, if
92the application program even has deleted all problem objects, there
93will be several memory blocks still allocated for the internal library
94needs. For some reasons the application program may want GLPK to free
95this memory, in which case it should call \verb|glp_free_env|.
96
97Note that a call to \verb|glp_free_env| invalidates all problem objects
98which still exist.
99
100\subsubsection*{Returns}
101
102The routine \verb|glp_free_env| returns one of the following codes:
103
104\noindent
1050 --- termination successful;
106
107\noindent
1081 --- environment is inactive (was not initialized).
109
110\subsection{glp\_printf---write formatted output to terminal}
111
112\subsubsection*{Synopsis}
113
114\begin{verbatim}
115void glp_printf(const char *fmt, ...);
116\end{verbatim}
117
118\subsubsection*{Description}
119
120The routine \verb|glp_printf| uses the format control string
121\verb|fmt| to format its parameters and writes the formatted output to
122the terminal.
123
124This routine is a replacement of the standard C function
125\verb|printf| and used by all GLPK routines to perform terminal
126output. The application program may use \verb|glp_printf| for the same
127purpose 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}
135void glp_vprintf(const char *fmt, va_list arg);
136\end{verbatim}
137
138\subsubsection*{Description}
139
140The routine \verb|glp_vprintf| uses the format control string
141\verb|fmt| to format its parameters specified by the list \verb|arg|
142and writes the formatted output to the terminal.
143
144This routine is a replacement of the standard C function
145\verb|vprintf| and used by all GLPK routines to perform terminal
146output. The application program may use \verb|glp_vprintf| for the same
147purpose 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}
157int glp_term_out(int flag);
158\end{verbatim}
159
160\subsubsection*{Description}
161
162Depending on the parameter flag the routine \verb|glp_term_out| enables
163or 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
171The routine \verb|glp_term_out| returns the previous value of the
172terminal 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}
179void glp_term_hook(int (*func)(void *info, const char *s),
180      void *info);
181\end{verbatim}
182
183\subsubsection*{Description}
184
185The routine \verb|glp_term_hook| installs the user-defined hook routine
186to 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
191The parameter {\it func} specifies the user-defined hook routine. It is
192called from an internal printing routine, which passes to it two
193parameters: {\it info} and {\it s}. The parameter {\it info} is a
194transit pointer specified in corresponding call to the routine
195\verb|glp_term_hook|; it may be used to pass some additional information
196to the hook routine. The parameter {\it s} is a pointer to the null
197terminated character string, which is intended to be written to the
198terminal. If the hook routine returns zero, the printing routine writes
199the string {\it s} to the terminal in a usual way; otherwise, if the
200hook routine returns non-zero, no terminal output is performed.
201
202To uninstall the hook routine both parameters {\it func} and {\it info}
203should be specified as \verb|NULL|.
204
205\newpage
206
207\subsubsection*{Example}
208
209\begin{footnotesize}
210\begin{verbatim}
211static int hook(void *info, const char *s)
212{     FILE *foo = info;
213      fputs(s, foo);
214      return 1;
215}
216
217int 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}
235int glp_open_tee(const char *fname);
236\end{verbatim}
237
238\subsubsection*{Description}
239
240The routine \verb|glp_open_tee| starts copying all the terminal output
241to an output text file, whose name is specified by the character string
242\verb|fname|.
243
244\subsubsection*{Returns}
245
246The routine \verb|glp_open_tee| returns one of the following codes:
247
248\noindent
2490 --- operation successful;
250
251\noindent
2521 --- copying terminal output is already active;
253
254\noindent
2552 --- 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}
264int glp_close_tee(void);
265\end{verbatim}
266
267\subsubsection*{Description}
268
269The routine \verb|glp_close_tee| stops copying the terminal output to
270the output text file previously open by the routine \verb|glp_open_tee|
271closing that file.
272
273\subsubsection*{Returns}
274
275The routine \verb|glp_close_tee| returns one of the following codes:
276
277\noindent
2780 --- operation successful;
279
280\noindent
2811 --- 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}
288void glp_error(const char *fmt, ...);
289\end{verbatim}
290
291\subsubsection*{Description}
292
293The routine \verb|glp_error| (implemented as a macro) formats its
294parameters using the format control string \verb|fmt|, writes the
295formatted message to the terminal, and then abnormally terminates the
296program.
297
298\subsection{glp\_assert---check logical condition}
299
300\subsubsection*{Synopsis}
301
302\begin{verbatim}
303void glp_assert(int expr);
304\end{verbatim}
305
306\subsubsection*{Description}
307
308The routine \verb|glp_assert| (implemented as a macro) checks
309a logical condition specified by the expression \verb|expr|. If the
310condition is true (non-zero), the routine does nothing; otherwise, if
311the condition is false (zero), the routine prints an error message and
312abnormally terminates the program.
313
314This routine is a replacement of the standard C function \verb|assert|
315and used by all GLPK routines to check program logic. The application
316program may use \verb|glp_assert| for the same purpose.
317
318\subsection{glp\_error\_hook---install hook to intercept abnormal
319termination}
320
321\subsubsection*{Synopsis}
322
323\begin{verbatim}
324void glp_error_hook(void (*func)(void *info), void *info);
325\end{verbatim}
326
327\subsubsection*{Description}
328
329The routine \verb|glp_error_hook| installs a user-defined hook routine
330to intercept abnormal termination.
331
332The parameter \verb|func| specifies the user-defined hook routine. It
333is called from the routine \verb|glp_error| before the latter calls the
334abort function to abnormally terminate the application program because
335of fatal error. The parameter \verb|info| is a transit pointer,
336specified in the corresponding call to the routine
337\verb|glp_error_hook|; it may be used to pass some information to the
338hook routine.
339
340To uninstall the hook routine the parameters \verb|func| and \verb|info|
341should be specified as \verb|NULL|.
342
343\subsubsection*{Usage note}
344
345If the hook routine returns, the application program is abnormally
346terminated. To prevent abnormal termnation the hook routine may perform
347a global jump using the standard function \verb|longjmp|, in which case
348the 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}
355void *glp_malloc(int size);
356\end{verbatim}
357
358\subsubsection*{Description}
359
360The routine \verb|glp_malloc| dynamically allocates a memory block of
361\verb|size| bytes long. Should note that:
362
3631) the parameter \verb|size| must be positive;
364
3652) being allocated the memory block contains arbitrary data, that is,
366it is {\it not} initialized by binary zeros;
367
3683) if the block cannot be allocated due to insufficient memory, the
369routine prints an error message and abnormally terminates the program.
370
371This routine is a replacement of the standard C function \verb|malloc|
372and used by all GLPK routines for dynamic memory allocation. The
373application program may use \verb|glp_malloc| for the same purpose.
374
375\subsubsection*{Returns}
376
377The routine \verb|glp_malloc| returns a pointer to the memory block
378allocated. To free this block the routine \verb|glp_free| (not the
379standard C function \verb|free|!) must be used.
380
381\subsection{glp\_calloc---allocate memory block}
382
383\subsubsection*{Synopsis}
384
385\begin{verbatim}
386void *glp_calloc(int n, int size);
387\end{verbatim}
388
389\subsubsection*{Description}
390
391The routine \verb|glp_calloc| dynamically allocates a memory block of
392\verb|n|$\times$\verb|size| bytes long. Should note that:
393
3941) both parameters \verb|n| and \verb|size| must be positive;
395
3962) being allocated the memory block contains arbitrary data, that is,
397it is {\it not} initialized by binary zeros;
398
3993) if the block cannot be allocated due to insufficient memory, the
400routine prints an error message and abnormally terminates the program.
401
402This 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
404routines for dynamic memory allocation. The application program may use
405\verb|glp_calloc| for the same purpose.
406
407\subsubsection*{Returns}
408
409The routine \verb|glp_calloc| returns a pointer to the memory block
410allocated. To free this block the routine \verb|glp_free| (not the
411standard C function \verb|free|!) must be used.
412
413\subsection{glp\_free---free memory block}
414
415\subsubsection*{Synopsis}
416
417\begin{verbatim}
418void glp_free(void *ptr);
419\end{verbatim}
420
421\subsubsection*{Description}
422
423The routine \verb|glp_free| frees (deallocates) a memory block pointed
424to by \verb|ptr|, which was previously allocated by the routine
425\verb|glp_malloc| or \verb|glp_calloc|. Note that the pointer \verb|ptr|
426must valid and must not be \verb|NULL|.
427
428This routine is a replacement of the standard C function \verb|free|
429and used by all GLPK routines for dynamic memory allocation. The
430application 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}
437void glp_mem_usage(int *count, int *cpeak, glp_long *total,
438      glp_long *tpeak);
439\end{verbatim}
440
441\subsubsection*{Description}
442
443The routine \verb|glp_mem_usage| reports some information about
444utilization of the memory by the routines \verb|glp_malloc|,
445\verb|glp_calloc|, and \verb|glp_free|. Information is stored to
446locations specified by corresponding parameters (see below). Any
447parameter can be specified as \verb|NULL|, in which case corresponding
448information 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
453initialization of the GLPK library environment.
454
455\verb|*total| is the total amount, in bytes, of currently allocated
456memory blocks.
457
458\verb|*tpeak| is the peak value of \verb|*total| reached since the
459initialization of the GLPK library envirionment.
460
461\subsubsection*{Example}
462
463\begin{footnotesize}
464\begin{verbatim}
465glp_mem_usage(&count, NULL, NULL, NULL);
466printf("%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}
475void glp_mem_limit(int limit);
476\end{verbatim}
477
478\subsubsection*{Description}
479
480The routine \verb|glp_mem_limit| limits the amount of memory available
481for 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}
489glp_long glp_time(void);
490\end{verbatim}
491
492\subsection*{Returns}
493
494The routine \verb|glp_time| returns the current universal time (UTC),
495in 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}
502double glp_difftime(glp_long t1, glp_long t0);
503\end{verbatim}
504
505\subsection*{Returns}
506
507The routine \verb|glp_difftime| returns the difference between two time
508values \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
518On developing simple applications to solve optimization problems it is
519often needed to read data from plain text files. To do this the standard
520C function \verb|fscanf| may be used, however, it is not convenient; for
521example, if it scans an integer number according to the format
522specification `\verb|%d|', and that number is coded incorrectly,
523no diagnostics is provided.
524
525This section describes a set of GLPK API routines, which may be used in
526application programs to simplify reading data from plain text files.
527
528\subsubsection*{Example 1}
529
530The following main program reads ten integer numbers from plain text
531file \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
541int 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
563The 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}
568123 65 432 890 -12 743 895 -7 111 326
569\end{verbatim}
570\end{footnotesize}
571
572\noindent
573or like this:
574
575\begin{footnotesize}
576\begin{verbatim}
577123   65  432  890  -12
578743  895   -7  111  326
579\end{verbatim}
580\end{footnotesize}
581
582\noindent
583If the input data file contains incorrect data, the routine
584\verb|glp_sdf_read_int| prints an error message and, if no error
585handling is provided by the application program, abnormally terminates
586program execution. For example, the file \verb|data.txt| could contain
587the following data:
588
589\begin{footnotesize}
590\begin{verbatim}
591123   65  432  890  -12
592743  895   =7  111  326
593\end{verbatim}
594\end{footnotesize}
595
596\noindent
597in which case the error message would be the following:
598
599\begin{footnotesize}
600\begin{verbatim}
601data.txt:2: cannot convert `=7' to integer
602\end{verbatim}
603\end{footnotesize}
604
605\subsubsection*{Example 2}
606
607As it was said above, by default any attempt to read incorrect data
608leads to abnormal termination. However, sometimes it is desirable to
609catch such errors. This feature is illustrated by the following main
610program, 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
621int 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;
650done: /* 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}
664glp_data *glp_sdf_open_file(const char *fname);
665\end{verbatim}
666
667\subsubsection*{Description}
668
669The routine \verb|glp_sdf_open_file| opens a plain data file, whose
670name is specified by the character string \verb|fname|.
671
672\subsubsection*{Returns}
673
674If the operation was successful, the routine \verb|glp_sdf_open_file|
675returns a pointer to the opaque program object of the type
676\verb|glp_data|\footnote{This data structure is declared in the header
677file {\tt glpk.h}.} associated with the plain data file. Otherwise, if
678the operation failed, the routine prints an error message and returns
679\verb|NULL|.
680
681\subsubsection*{Note}
682
683The application program should use the pointer returned by the routine
684\verb|glp_sdf_open_file| to perform all subsequent operations on the
685data file.
686
687\newpage
688
689\subsection{glp\_sdf\_set\_jump---set up error handling}
690
691\subsubsection*{Synopsis}
692
693\begin{verbatim}
694void glp_sdf_set_jump(glp_data *data, jmp_buf jump);
695\end{verbatim}
696
697\subsubsection*{Description}
698
699The routine \verb|glp_sdf_set_jump| sets up error handling for the
700plain data file specified by the parameter \verb|data|.
701
702The parameter \verb|jump| specifies the environment buffer, which must
703be initialized with the standard C function \verb|setjmp| prior to call
704to the routine \verb|glp_sdf_set_jump|. Detecting any incorrect data in
705the corresponding plain data file will cause non-local ``go to'' by
706a call to the standard C function \verb|longjmp|.
707
708The parameter \verb|jump| can be specified as \verb|NULL|, in which
709case the routine \verb|glp_sdf_set_jump| restores the default behavior,
710in 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}
717void glp_sdf_error(glp_data *data, const char *fmt, ...);
718\end{verbatim}
719
720\subsubsection*{Description}
721
722The routine \verb|glp_sdf_error| prints an error message related to the
723plain data file specified by the parameter \verb|data|. If error handing
724was not previously provided, the routine then abnormally terminates
725execution of the application program. Otherwise, it signals about the
726error by a call to the standard C function \verb|longjmp|.
727
728The character string \verb|fmt| and optional parameters following it
729have the same meaning as for the standard C function \verb|printf|.
730
731The message produced by the routine \verb|glp_sdf_error| looks like
732follows:
733
734\medskip
735
736{\it file}{\tt :}{\it line}{\tt :} {\it message text}
737
738\medskip
739
740\noindent
741where {\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}
751void glp_sdf_warning(glp_data *data, const char *fmt, ...);
752\end{verbatim}
753
754\subsubsection*{Description}
755
756The routine \verb|glp_sdf_warning| prints a warning message related to
757the plain data file specified by the parameter \verb|data|.
758
759The character string \verb|fmt| and optional parameters following it
760have the same meaning as for the standard C function \verb|printf|.
761
762The message produced by the routine \verb|glp_sdf_warning| looks like
763follows:
764
765\medskip
766
767{\it file}{\tt :}{\it line}\verb|: warning:| {\it message text}
768
769\medskip
770
771\noindent
772where {\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}
780int glp_sdf_read_int(glp_data *data);
781\end{verbatim}
782
783\subsubsection*{Description}
784
785The routine \verb|glp_sdf_read_int| skips optional white-space
786characters and then reads an integer number from the plain data file
787specified by the parameter \verb|data|. If the operation failed, the
788routine \verb|glp_sdf_read_int| calls the routine \verb|glp_sdf_error|
789(see above).
790
791\subsubsection*{Returns}
792
793The 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}
802double glp_sdf_read_num(glp_data *data);
803\end{verbatim}
804
805\subsubsection*{Description}
806
807The routine \verb|glp_sdf_read_num| skips optional white-space
808characters and then reads a floating-point number from the plain data
809file specified by the parameter \verb|data|. If the operation failed,
810the routine \verb|glp_sdf_num| calls the routine \verb|glp_sdf_error|
811(see above).
812
813\subsubsection*{Returns}
814
815The routine \verb|glp_sdf_read_num| returns the floating-point number
816read.
817
818\subsection{glp\_sdf\_read\_item---read data item}
819
820\subsubsection*{Synopsis}
821
822\begin{verbatim}
823const char *glp_sdf_read_item(glp_data *data);
824\end{verbatim}
825
826\subsubsection*{Description}
827
828The routine \verb|glp_sdf_read_item| skips optional white-space
829characters and then reads a data item from the plain data file specified
830by the parameter \verb|data|. If the operation failed, the routine
831\verb|glp_sdf_read_item| calls the routine \verb|glp_sdf_error| (see
832above).
833
834{\it Data item} is a sequence of 1 to 255 arbitrary graphic characters
835delimited by white-space characters. Data items may be used to represent
836symbolic names, identifiers, etc.
837
838\subsubsection*{Returns}
839
840The routine \verb|glp_sdf_read_item| returns a pointer to the internal
841buffer, which contains the data item read in the form of a
842null-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}
851const char *glp_sdf_read_text(glp_data *data);
852\end{verbatim}
853
854\subsubsection*{Description}
855
856The routine \verb|glp_sdf_read_text| reads a text from the plain data
857file specified by the parameter \verb|data|.
858
859Reading starts from the current position and extends until end of the
860current line. Initial and trailing white-space characters as well as
861the newline character are not included in the text.
862
863\subsubsection*{Returns}
864
865The routine \verb|glp_sdf_read_text| returns a pointer to the internal
866buffer, which contains the text read in the form of a null-terminated
867character string.
868
869\subsection{glp\_sdf\_line---determine current line number}
870
871\subsubsection*{Synopsis}
872
873\begin{verbatim}
874int glp_sdf_line(glp_data *data);
875\end{verbatim}
876
877\subsubsection*{Returns}
878
879The routine \verb|glp_sdf_line| returns the current line number for the
880plain 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}
887void glp_sdf_close_file(glp_data *data);
888\end{verbatim}
889
890\subsubsection*{Description}
891
892The routine \verb|glp_sdf_close_file| closes the plain data file
893specified by the parameter \verb|data| and frees all the resources
894allocated to this program object.
895
896%* eof *%
Note: See TracBrowser for help on using the repository browser.