diff -r d59bea55db9b -r c445c931472f doc/glpk06.tex
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/glpk06.tex	Mon Dec 06 13:09:21 2010 +0100
@@ -0,0 +1,896 @@
+%* glpk06.tex *%
+
+\chapter{Miscellaneous API Routines}
+
+\section{GLPK environment routines}
+
+\subsection{glp\_long---64-bit integer data type}
+
+Some GLPK API routines use 64-bit integer data type, which is declared
+in the header \verb|glpk.h| as follows:
+
+\begin{verbatim}
+typedef struct { int lo, hi; } glp_long;
+\end{verbatim}
+
+\noindent
+where \verb|lo| contains low 32 bits, and \verb|hi| contains high 32
+bits of 64-bit integer value.\footnote{GLPK conforms to ILP32, LLP64,
+and LP64 programming models, where the built-in type {\tt int}
+corresponds to 32-bit integers.}
+
+\subsection{glp\_init\_env---initialize GLPK environment}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+int glp_init_env(void);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_init_env| initializes the GLPK environment.
+Normally the application program does not need to call this routine,
+because it is called automatically on the first call to any API routine.
+
+\newpage
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_init_env| returns one of the following codes:
+
+\noindent
+0 --- initialization successful;
+
+\noindent
+1 --- environment is already initialized;
+
+\noindent
+2 --- initialization failed (insufficient memory);
+
+\noindent
+3 --- initialization failed (unsupported programming model).
+
+\subsection{glp\_version---determine library version}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+const char *glp_version(void);
+\end{verbatim}
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_version| returns a pointer to a null-terminated
+character string, which specifies the version of the GLPK library in
+the form \verb|"X.Y"|, where `\verb|X|' is the major version number, and
+`\verb|Y|' is the minor version number, for example, \verb|"4.16"|.
+
+\subsubsection*{Example}
+
+\begin{footnotesize}
+\begin{verbatim}
+printf("GLPK version is %s\n", glp_version());
+\end{verbatim}
+\end{footnotesize}
+
+\subsection{glp\_free\_env---free GLPK environment}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+int glp_free_env(void);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_free_env| frees all resources used by GLPK
+routines (memory blocks, etc.) which are currently still in use.
+
+Normally the application program does not need to call this routine,
+because GLPK routines always free all unused resources. However, if
+the application program even has deleted all problem objects, there
+will be several memory blocks still allocated for the internal library
+needs. For some reasons the application program may want GLPK to free
+this memory, in which case it should call \verb|glp_free_env|.
+
+Note that a call to \verb|glp_free_env| invalidates all problem objects
+which still exist.
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_free_env| returns one of the following codes:
+
+\noindent
+0 --- termination successful;
+
+\noindent
+1 --- environment is inactive (was not initialized).
+
+\subsection{glp\_printf---write formatted output to terminal}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_printf(const char *fmt, ...);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_printf| uses the format control string
+\verb|fmt| to format its parameters and writes the formatted output to
+the terminal.
+
+This routine is a replacement of the standard C function
+\verb|printf| and used by all GLPK routines to perform terminal
+output. The application program may use \verb|glp_printf| for the same
+purpose that allows controlling its terminal output with the routines
+\verb|glp_term_out| and \verb|glp_term_hook|.
+
+\subsection{glp\_vprintf---write formatted output to terminal}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_vprintf(const char *fmt, va_list arg);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_vprintf| uses the format control string
+\verb|fmt| to format its parameters specified by the list \verb|arg|
+and writes the formatted output to the terminal.
+
+This routine is a replacement of the standard C function
+\verb|vprintf| and used by all GLPK routines to perform terminal
+output. The application program may use \verb|glp_vprintf| for the same
+purpose that allows controlling its terminal output with the routines
+\verb|glp_term_out| and \verb|glp_term_hook|.
+
+\newpage
+
+\subsection{glp\_term\_out---enable/disable terminal output}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+int glp_term_out(int flag);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+Depending on the parameter flag the routine \verb|glp_term_out| enables
+or disables terminal output performed by glpk routines:
+
+\verb|GLP_ON | --- enable terminal output;
+
+\verb|GLP_OFF| --- disable terminal output.
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_term_out| returns the previous value of the
+terminal output flag (\verb|GLP_ON| or \verb|GLP_OFF|).
+
+\subsection{glp\_term\_hook---intercept terminal output}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_term_hook(int (*func)(void *info, const char *s),
+      void *info);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_term_hook| installs the user-defined hook routine
+to intercept all terminal output performed by GLPK routines.
+
+%This feature can be used to redirect the terminal output to other
+%destination, for example, to a file or a text window.
+
+The parameter {\it func} specifies the user-defined hook routine. It is
+called from an internal printing routine, which passes to it two
+parameters: {\it info} and {\it s}. The parameter {\it info} is a
+transit pointer specified in corresponding call to the routine
+\verb|glp_term_hook|; it may be used to pass some additional information
+to the hook routine. The parameter {\it s} is a pointer to the null
+terminated character string, which is intended to be written to the
+terminal. If the hook routine returns zero, the printing routine writes
+the string {\it s} to the terminal in a usual way; otherwise, if the
+hook routine returns non-zero, no terminal output is performed.
+
+To uninstall the hook routine both parameters {\it func} and {\it info}
+should be specified as \verb|NULL|.
+
+\newpage
+
+\subsubsection*{Example}
+
+\begin{footnotesize}
+\begin{verbatim}
+static int hook(void *info, const char *s)
+{     FILE *foo = info;
+      fputs(s, foo);
+      return 1;
+}
+
+int main(void)
+{     FILE *foo;
+      . . .
+      /* redirect terminal output */
+      glp_term_hook(hook, foo);
+      . . .
+      /* resume terminal output */
+      glp_term_hook(NULL, NULL);
+      . . .
+}
+\end{verbatim}
+\end{footnotesize}
+
+\subsection{glp\_open\_tee---start copying terminal output}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+int glp_open_tee(const char *fname);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_open_tee| starts copying all the terminal output
+to an output text file, whose name is specified by the character string
+\verb|fname|.
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_open_tee| returns one of the following codes:
+
+\noindent
+0 --- operation successful;
+
+\noindent
+1 --- copying terminal output is already active;
+
+\noindent
+2 --- unable to create output file.
+
+\newpage
+
+\subsection{glp\_close\_tee---stop copying terminal output}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+int glp_close_tee(void);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_close_tee| stops copying the terminal output to
+the output text file previously open by the routine \verb|glp_open_tee|
+closing that file.
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_close_tee| returns one of the following codes:
+
+\noindent
+0 --- operation successful;
+
+\noindent
+1 --- copying terminal output was not started.
+
+\subsection{glp\_error---display error message and terminate execution}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_error(const char *fmt, ...);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_error| (implemented as a macro) formats its
+parameters using the format control string \verb|fmt|, writes the
+formatted message to the terminal, and then abnormally terminates the
+program.
+
+\subsection{glp\_assert---check logical condition}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_assert(int expr);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_assert| (implemented as a macro) checks
+a logical condition specified by the expression \verb|expr|. If the
+condition is true (non-zero), the routine does nothing; otherwise, if
+the condition is false (zero), the routine prints an error message and
+abnormally terminates the program.
+
+This routine is a replacement of the standard C function \verb|assert|
+and used by all GLPK routines to check program logic. The application
+program may use \verb|glp_assert| for the same purpose.
+
+\subsection{glp\_error\_hook---install hook to intercept abnormal
+termination}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_error_hook(void (*func)(void *info), void *info);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_error_hook| installs a user-defined hook routine
+to intercept abnormal termination.
+
+The parameter \verb|func| specifies the user-defined hook routine. It
+is called from the routine \verb|glp_error| before the latter calls the
+abort function to abnormally terminate the application program because
+of fatal error. The parameter \verb|info| is a transit pointer,
+specified in the corresponding call to the routine
+\verb|glp_error_hook|; it may be used to pass some information to the
+hook routine.
+
+To uninstall the hook routine the parameters \verb|func| and \verb|info|
+should be specified as \verb|NULL|.
+
+\subsubsection*{Usage note}
+
+If the hook routine returns, the application program is abnormally
+terminated. To prevent abnormal termnation the hook routine may perform
+a global jump using the standard function \verb|longjmp|, in which case
+the application program {\it must} call the routine \verb|glp_free_env|.
+
+\subsection{glp\_malloc---allocate memory block}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void *glp_malloc(int size);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_malloc| dynamically allocates a memory block of
+\verb|size| bytes long. Should note that:
+
+1) the parameter \verb|size| must be positive;
+
+2) being allocated the memory block contains arbitrary data, that is,
+it is {\it not} initialized by binary zeros;
+
+3) if the block cannot be allocated due to insufficient memory, the
+routine prints an error message and abnormally terminates the program.
+
+This routine is a replacement of the standard C function \verb|malloc|
+and used by all GLPK routines for dynamic memory allocation. The
+application program may use \verb|glp_malloc| for the same purpose.
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_malloc| returns a pointer to the memory block
+allocated. To free this block the routine \verb|glp_free| (not the
+standard C function \verb|free|!) must be used.
+
+\subsection{glp\_calloc---allocate memory block}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void *glp_calloc(int n, int size);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_calloc| dynamically allocates a memory block of
+\verb|n|$\times$\verb|size| bytes long. Should note that:
+
+1) both parameters \verb|n| and \verb|size| must be positive;
+
+2) being allocated the memory block contains arbitrary data, that is,
+it is {\it not} initialized by binary zeros;
+
+3) if the block cannot be allocated due to insufficient memory, the
+routine prints an error message and abnormally terminates the program.
+
+This routine is a replacement of the standard C function \verb|calloc|
+(with exception that the block is not cleaned) and used by all GLPK
+routines for dynamic memory allocation. The application program may use
+\verb|glp_calloc| for the same purpose.
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_calloc| returns a pointer to the memory block
+allocated. To free this block the routine \verb|glp_free| (not the
+standard C function \verb|free|!) must be used.
+
+\subsection{glp\_free---free memory block}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_free(void *ptr);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_free| frees (deallocates) a memory block pointed
+to by \verb|ptr|, which was previously allocated by the routine
+\verb|glp_malloc| or \verb|glp_calloc|. Note that the pointer \verb|ptr|
+must valid and must not be \verb|NULL|.
+
+This routine is a replacement of the standard C function \verb|free|
+and used by all GLPK routines for dynamic memory allocation. The
+application program may use \verb|glp_free| for the same purpose.
+
+\subsection{glp\_mem\_usage---get memory usage information}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_mem_usage(int *count, int *cpeak, glp_long *total,
+      glp_long *tpeak);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_mem_usage| reports some information about
+utilization of the memory by the routines \verb|glp_malloc|,
+\verb|glp_calloc|, and \verb|glp_free|. Information is stored to
+locations specified by corresponding parameters (see below). Any
+parameter can be specified as \verb|NULL|, in which case corresponding
+information is not stored.
+
+\verb|*count| is the number of currently allocated memory blocks.
+
+\verb|*cpeak| is the peak value of \verb|*count| reached since the
+initialization of the GLPK library environment.
+
+\verb|*total| is the total amount, in bytes, of currently allocated
+memory blocks.
+
+\verb|*tpeak| is the peak value of \verb|*total| reached since the
+initialization of the GLPK library envirionment.
+
+\subsubsection*{Example}
+
+\begin{footnotesize}
+\begin{verbatim}
+glp_mem_usage(&count, NULL, NULL, NULL);
+printf("%d memory block(s) are still allocated\n", count);
+\end{verbatim}
+\end{footnotesize}
+
+\subsection{glp\_mem\_limit---set memory usage limit}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_mem_limit(int limit);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_mem_limit| limits the amount of memory available
+for dynamic allocation (with the routines \verb|glp_malloc| and
+\verb|glp_calloc|) to \verb|limit| megabytes.
+
+\subsection{glp\_time---determine current universal time}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+glp_long glp_time(void);
+\end{verbatim}
+
+\subsection*{Returns}
+
+The routine \verb|glp_time| returns the current universal time (UTC),
+in milliseconds, elapsed since 00:00:00 GMT January 1, 1970.
+
+\subsection{glp\_difftime---compute difference between two time values}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+double glp_difftime(glp_long t1, glp_long t0);
+\end{verbatim}
+
+\subsection*{Returns}
+
+The routine \verb|glp_difftime| returns the difference between two time
+values \verb|t1| and \verb|t0|, expressed in seconds.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newpage
+
+\section{Plain data file reading routines}
+
+\subsection{Introduction}
+
+On developing simple applications to solve optimization problems it is
+often needed to read data from plain text files. To do this the standard
+C function \verb|fscanf| may be used, however, it is not convenient; for
+example, if it scans an integer number according to the format
+specification `\verb|%d|', and that number is coded incorrectly,
+no diagnostics is provided.
+
+This section describes a set of GLPK API routines, which may be used in
+application programs to simplify reading data from plain text files.
+
+\subsubsection*{Example 1}
+
+The following main program reads ten integer numbers from plain text
+file \verb|data.txt| and prints their sum.
+
+\begin{footnotesize}
+\begin{verbatim}
+/* sdfsamp1.c */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <glpk.h>
+
+int main(void)
+{     glp_data *data;
+      int j, num, sum;
+      /* open plain data file */
+      data = glp_sdf_open_file("data.txt");
+      if (data == NULL) exit(EXIT_FAILURE);
+      sum = 0;
+      for (j = 1; j <= 10; j++)
+      {  /* read next integer number */
+         num = glp_sdf_read_int(data);
+         sum += num;
+      }
+      printf("sum = %d\n", sum);
+      /* close plain data file */
+      glp_sdf_close_file(data);
+      return 0;
+}
+
+/* eof */
+\end{verbatim}
+\end{footnotesize}
+
+The input data are coded in free format. For example, the file
+\verb|data.txt| may look like this:
+
+\begin{footnotesize}
+\begin{verbatim}
+123 65 432 890 -12 743 895 -7 111 326
+\end{verbatim}
+\end{footnotesize}
+
+\noindent
+or like this:
+
+\begin{footnotesize}
+\begin{verbatim}
+123   65  432  890  -12
+743  895   -7  111  326
+\end{verbatim}
+\end{footnotesize}
+
+\noindent
+If the input data file contains incorrect data, the routine
+\verb|glp_sdf_read_int| prints an error message and, if no error
+handling is provided by the application program, abnormally terminates
+program execution. For example, the file \verb|data.txt| could contain
+the following data:
+
+\begin{footnotesize}
+\begin{verbatim}
+123   65  432  890  -12
+743  895   =7  111  326
+\end{verbatim}
+\end{footnotesize}
+
+\noindent
+in which case the error message would be the following:
+
+\begin{footnotesize}
+\begin{verbatim}
+data.txt:2: cannot convert `=7' to integer
+\end{verbatim}
+\end{footnotesize}
+
+\subsubsection*{Example 2}
+
+As it was said above, by default any attempt to read incorrect data
+leads to abnormal termination. However, sometimes it is desirable to
+catch such errors. This feature is illustrated by the following main
+program, which does the same job as in the previous example.
+
+\begin{footnotesize}
+\begin{verbatim}
+/* sdfsamp2.c */
+
+#include <setjmp.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <glpk.h>
+
+int main(void)
+{     glp_data *data;
+      jmp_buf jump;
+      int j, num, sum, ret;
+      /* open plain data file */
+      data = glp_sdf_open_file("data.txt");
+      if (data == NULL)
+      {  ret = EXIT_FAILURE;
+         goto done;
+      }
+      /* set up error handling */
+      if (setjmp(jump))
+      {  ret = EXIT_FAILURE;
+         goto done;
+      }
+      glp_sdf_set_jump(data, jump);
+      /* read and process data */
+      sum = 0;
+      for (j = 1; j <= 10; j++)
+      {  /* read next integer number */
+         num = glp_sdf_read_int(data);
+         if (abs(num) > 1000)
+            glp_sdf_error(data, "integer %d too big\n", num);
+         if (num < 0)
+            glp_sdf_warning(data, "integer %d is negative\n", num);
+         sum += num;
+      }
+      printf("sum = %d\n", sum);
+      ret = EXIT_SUCCESS;
+done: /* close plain data file */
+      if (data != NULL) glp_sdf_close_file(data);
+      return ret;
+}
+
+/* eof */
+\end{verbatim}
+\end{footnotesize}
+
+\subsection{glp\_sdf\_open\_file---open plain data file}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+glp_data *glp_sdf_open_file(const char *fname);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_sdf_open_file| opens a plain data file, whose
+name is specified by the character string \verb|fname|.
+
+\subsubsection*{Returns}
+
+If the operation was successful, the routine \verb|glp_sdf_open_file|
+returns a pointer to the opaque program object of the type
+\verb|glp_data|\footnote{This data structure is declared in the header
+file {\tt glpk.h}.} associated with the plain data file. Otherwise, if
+the operation failed, the routine prints an error message and returns
+\verb|NULL|.
+
+\subsubsection*{Note}
+
+The application program should use the pointer returned by the routine
+\verb|glp_sdf_open_file| to perform all subsequent operations on the
+data file.
+
+\newpage
+
+\subsection{glp\_sdf\_set\_jump---set up error handling}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_sdf_set_jump(glp_data *data, jmp_buf jump);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_sdf_set_jump| sets up error handling for the
+plain data file specified by the parameter \verb|data|.
+
+The parameter \verb|jump| specifies the environment buffer, which must
+be initialized with the standard C function \verb|setjmp| prior to call
+to the routine \verb|glp_sdf_set_jump|. Detecting any incorrect data in
+the corresponding plain data file will cause non-local ``go to'' by
+a call to the standard C function \verb|longjmp|.
+
+The parameter \verb|jump| can be specified as \verb|NULL|, in which
+case the routine \verb|glp_sdf_set_jump| restores the default behavior,
+in which case detecting incorrect data leads to abnormal termination.
+
+\subsection{glp\_sdf\_error---print error message}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_sdf_error(glp_data *data, const char *fmt, ...);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_sdf_error| prints an error message related to the
+plain data file specified by the parameter \verb|data|. If error handing
+was not previously provided, the routine then abnormally terminates
+execution of the application program. Otherwise, it signals about the
+error by a call to the standard C function \verb|longjmp|.
+
+The character string \verb|fmt| and optional parameters following it
+have the same meaning as for the standard C function \verb|printf|.
+
+The message produced by the routine \verb|glp_sdf_error| looks like
+follows:
+
+\medskip
+
+{\it file}{\tt :}{\it line}{\tt :} {\it message text}
+
+\medskip
+
+\noindent
+where {\it file} is the filename passed to the routine
+\verb|glp_sdf_open| and {\it line} is the current line number.
+
+\newpage
+
+\subsection{glp\_sdf\_warning---print warning message}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_sdf_warning(glp_data *data, const char *fmt, ...);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_sdf_warning| prints a warning message related to
+the plain data file specified by the parameter \verb|data|.
+
+The character string \verb|fmt| and optional parameters following it
+have the same meaning as for the standard C function \verb|printf|.
+
+The message produced by the routine \verb|glp_sdf_warning| looks like
+follows:
+
+\medskip
+
+{\it file}{\tt :}{\it line}\verb|: warning:| {\it message text}
+
+\medskip
+
+\noindent
+where {\it file} is the filename passed to the routine
+\verb|glp_sdf_open| and {\it line} is the current line number.
+
+\subsection{glp\_sdf\_read\_int---read integer number}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+int glp_sdf_read_int(glp_data *data);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_sdf_read_int| skips optional white-space
+characters and then reads an integer number from the plain data file
+specified by the parameter \verb|data|. If the operation failed, the
+routine \verb|glp_sdf_read_int| calls the routine \verb|glp_sdf_error|
+(see above).
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_sdf_read_int| returns the integer number read.
+
+\newpage
+
+\subsection{glp\_sdf\_read\_num---read floating-point number}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+double glp_sdf_read_num(glp_data *data);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_sdf_read_num| skips optional white-space
+characters and then reads a floating-point number from the plain data
+file specified by the parameter \verb|data|. If the operation failed,
+the routine \verb|glp_sdf_num| calls the routine \verb|glp_sdf_error|
+(see above).
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_sdf_read_num| returns the floating-point number
+read.
+
+\subsection{glp\_sdf\_read\_item---read data item}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+const char *glp_sdf_read_item(glp_data *data);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_sdf_read_item| skips optional white-space
+characters and then reads a data item from the plain data file specified
+by the parameter \verb|data|. If the operation failed, the routine
+\verb|glp_sdf_read_item| calls the routine \verb|glp_sdf_error| (see
+above).
+
+{\it Data item} is a sequence of 1 to 255 arbitrary graphic characters
+delimited by white-space characters. Data items may be used to represent
+symbolic names, identifiers, etc.
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_sdf_read_item| returns a pointer to the internal
+buffer, which contains the data item read in the form of a
+null-terminated character string.
+
+\newpage
+
+\subsection{glp\_sdf\_read\_text---read text until end of line}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+const char *glp_sdf_read_text(glp_data *data);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_sdf_read_text| reads a text from the plain data
+file specified by the parameter \verb|data|.
+
+Reading starts from the current position and extends until end of the
+current line. Initial and trailing white-space characters as well as
+the newline character are not included in the text.
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_sdf_read_text| returns a pointer to the internal
+buffer, which contains the text read in the form of a null-terminated
+character string.
+
+\subsection{glp\_sdf\_line---determine current line number}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+int glp_sdf_line(glp_data *data);
+\end{verbatim}
+
+\subsubsection*{Returns}
+
+The routine \verb|glp_sdf_line| returns the current line number for the
+plain data file specified by the parameter \verb|data|.
+
+\subsection{glp\_sdf\_close\_file---close plain data file}
+
+\subsubsection*{Synopsis}
+
+\begin{verbatim}
+void glp_sdf_close_file(glp_data *data);
+\end{verbatim}
+
+\subsubsection*{Description}
+
+The routine \verb|glp_sdf_close_file| closes the plain data file
+specified by the parameter \verb|data| and frees all the resources
+allocated to this program object.
+
+%* eof *%