Chapter 9: Input and Output

This chapter describes functions that write formatted data to the screen and access disk files.

9.1 Formatted Output with PRINTF

The function PRINTF translates internal values and prints them on the screen.

The call is: ISTAT = PRINTF (CFMT, ARG1, ARG2, ..., ARGn)

CFMT is a format string.
ARG1, .., ARGn are optional arguments.
ISTAT is the returned status of PRINTF and can have the values 0 and -1. On error, PRINTF returns -1.

The format string can contain ordinary characters and format specifications. Ordinary characters are printed as text while format specifications define how the arguments of PRINTF are formatted. A format specification begins with a % and ends with a conversion character. Between the % and the conversion character there may be the following parts:

Conversion characters are shown in the following table:


  --------------------------------------------------
  | Character |             Meaning                |
  --------------------------------------------------
  |    %c     | prints a character.                | 
  |    %d     | prints an integer.                 |
  |    %i     | prints an integer (same as %d).    | 
  |    %s     | prints a string.                   |
  |    %f     | prints a floating point number.    | 
  |    %e     | prints a floating point number in  |
  |           | e format.                          | 
  |    %x     | prints an integer in hexadecimal   |
  |           | format.                            |
  |    %o     | prints an integer in octal format. |
  |    \n     | inserts a newline.                 |
  --------------------------------------------------
          Figure 9.1: Conversion Characters
Examples:

The first example shows the effect of some format specifications for printing the string 'This is a string.' (17 characters). 

   %GCL

   s = 'This is a string.'
   printf (':%s:      \n', s)
   printf (':%15s:    \n', s)
   printf (':%17s:    \n', s)
   printf (':%20s:    \n', s)
   printf (':%-20s:   \n', s)
   printf (':%17.13s: \n', s)
   printf (':%-17.13s:\n', s)
The output of the GCL script is:

   :This is a string.:      
   :This is a string.:    
   :This is a string.:    
   :   This is a string.:    
   :This is a string.   :   
   :    This is a str: 
   :This is a str    :
The next example shows the effect of some format specifications for printing the integer 254:

   %GCL

   i = 254
   printf (':%d:    \n', i)
   printf (':%8d:   \n', i)
   printf (':%08d:  \n', i)
   printf (':%-8d:  \n', i)
   printf (':%-8.2d:\n', i)
   printf (':%x:    \n', i)
   printf (':%08X:  \n', i)
   printf (':%o:    \n', i)
The output is:

   :254:    
   :     254:   
   :00000254:  
   :254     :  
   :254     :
   :fe:    
   :000000FE:
   :376:
The next example shows the effect of some format specifications for printing the floating point number 123.456:

   %GCL

   x = 123.456
   printf (':%f:      \n', x)
   printf (':%15f:    \n', x)
   printf (':%-15f:   \n', x)
   printf (':%-15.2f: \n', x)
   printf (':%e:      \n', x)
   printf (':%-15E:   \n', x)
   printf (':%-15.2E: \n', x)
The output is:

   :123.456000:      
   :     123.456000:    
   :123.456000     :   
   :123.46         : 
   :1.234560e+02:      
   :1.234560E+02   :   
   :1.23E+02       :

9.2 Formatted Output with SPRINTF

The function SPRINTF does the same conversions as PRINTF does, but stores the output in a character array.

The call is: ISTAT = SPRINTF (CRAY, CFMT, ARG1, ARG2, ..., ARGn)

CRAY is a character array that must be created with the CHAR command. CRAY must be big enough to hold the result and the string terminator.
CFMT is a format string.
ARG1,..,ARGn are optional arguments.
ISTAT is the returned status of SPRINTF and can have the values 0 and -1. On error, SPRINTF returns -1.

9.3 Formatted Input with SCANF

The function SCANF is an analogue function to PRINTF for formatted input from the keyboard. It uses the format specifications listed in table 9.1.

The call is: ISTAT = SCANF (CFMT, ARG1, ARG2, ..., ARGn)

CFMT is a format string.
ARG1,..,ARGn are optional arguments where the arguments must be variables. If a string should be read, the corresponding variable must be created with the GCL command CHAR and big enough to hold the string and a trailing string terminator.
ISTAT is the returned status of SCANF and can have the values 0 and -1. On error, SCANF returns -1.

Additional note:

9.4 Formatted Input with SSCANF

The function SSCANF does the same conversions as SCANF does, but reads the input from a string.

The call is: ISTAT = SSCANF (CSTR, CFMT, ARG1, ARG2, ..., ARGn)

CSTR is a string where the input characters are taken from.
CFMT is a format string.
ARG1,..,ARGn are optional arguments (see SCANF).
ISTAT is the returned status of SSCANF and can have the values 0 and -1. On error, SSCANF returns -1.

9.5 File Access

The following functions deal with operations on files.

F O P E N

The routine FOPEN opens a file and returns a file unit.

The call is: NU = FOPEN (CFIL, CMOD)

CFIL is the name of a file. If CFIL = 'CON:', the console is opened for file I/O. If GCL is used in interactive mode, the console can only be opened for output (CMOD = 'w').
CMOD is a string that defines the mode for file access. The modes are listed in table 9.2.
NU is the returned file unit, or -1 if an error occurs.

The following table shows the allowed file modes for FOPEN:

  --------------------------------------------------------
  |  Mode  |             Meaning                         |
  --------------------------------------------------------
  |  'r'   | opens a text file for reading. The file     |
  |        | must exist, or an error message is printed. | 
  |  'w'   | opens a text file for writing. The contents | 
  |        | of an existing file will be overwritten.    |
  |  'a'   | opens a text file for appending.            |
  |  'rb'  | opens a file for binary reading.            |
  |  'wb'  | opens a file for binary writing.            |
  |  'ab'  | opens a file for binary appending.          |
  --------------------------------------------------------
            Figure 9.2: File Modes for FOPEN
F C L O S E

The function FCLOSE closes a file.

The call is: ISTAT = FCLOSE (NU)

NU is a file unit.
ISTAT is the returned status of FCLOSE and can have the values 0 and -1. On error, FCLOSE returns -1.

R E M O V E

The function REMOVE deletes a file.

The call is: ISTAT = REMOVE (CFIL)

CFIL is the name of a file.
ISTAT is the returned status of REMOVE and can have the values 0 and -1. On error, REMOVE returns -1.

R E N A M E

The function RENAME changes the name of a file.

The call is: ISTAT = RENAME (COLD, CNEW)

COLD is the old name of the file.
CNEW is the new name of the file.
ISTAT is the returned status of RENAME and can have the values 0 and -1. On error, RENAME returns -1.

F T E L L

The function FTELL returns the current file position.

The call is: NPOS = FTELL (NU)

NU is a file unit.
NPOS is the returned file position, or -1 on error.

F S E E K

The function FSEEK defines the current file position.

The call is: ISTAT = FSEEK (NU, NPOS)

NU is a file unit.
NPOS is the new file position.
ISTAT is the returned status of FSEEK and can have the values 0 and -1. On error, FSEEK returns -1.

F F L U S H

The function FFLUSH flushes any output buffers. For input, FFLUSH has no effect.

The call is: ISTAT = FFLUSH (NU)

NU is a file unit.
ISTAT is the returned status of FFLUSH and can have the values 0 and -1. On error, FFLUSH returns -1.

R E W I N D

The function REWIND sets the current file position to the beginning of the file.

The call is: ISTAT = REWIND (NU)

NU is a file unit.
ISTAT is the returned status of REWIND and can have the values 0 and -1. On error, REWIND returns -1.

9.6 Formatted Output to Files

F P R I N T F

The function FPRINTF does the same conversions as PRINTF does, but writes the output to a file.

The call is: ISTAT = FPRINTF (NU, CFMT, ARG1, ARG2, ..., ARGn)

NU is a file unit.
CFMT is a format string.
ARG1,..,ARGn are optional arguments.
ISTAT is the returned status of FPRINTF and can have the values 0 and -1. On error, FPRINTF returns -1.

9.7 Formatted Input from Files

F S C A N F

The function FSCANF is an analogue function to FPRINTF for formatted input. It uses the format specifications listed in table 9.1.

The call is: ISTAT = FSCANF (NU, CFMT, ARG1, ARG2, ..., ARGn)

NU is a file unit.
CFMT is a format string.
ARG1,..,ARGn are optional arguments where the arguments must be variables. If a string should be read from the file, the corresponding variable must be created with the GCL command CHAR and big enough to hold the string and the trailing string terminator.
ISTAT is the returned status of FSCANF and can have the values 0 and -1. On error, FSCANF returns -1.

9.8 Text Input and Output Functions

F G E T C

The function FGETC returns the next character from a file.

The call is: N = FGETC (NU)
NU is a file unit.
N is the ASCII code of the returned character, or -1 if end of file or error occurs.

F G E T S

The function FGETS reads at most N-1 characters into a character array, stopping if a newline is encountered. The newline character is included in the character array.

The call is: ISTAT = FGETS (CRAY, N, NU)

CRAY is a character array filled by FGETS. CRAY must be created with the GCL command CHAR (i.e. CHAR CRAY[N]).
N defines the number of characters to be read. At most N-1 characters will be read.
NU is a file unit.
ISTAT is the returned status of FGETS and can have the values 0 and -1. FGETS returns -1 if end of file or error occurs.

Additional note:

F P U T C

The function FPUTC writes a character to a file.

The call is: ISTAT = FPUTC (N, NU)

N is the ASCII code of a character that should be written to a file.
NU is a file unit.
ISTAT is the returned status of FPUTC and can have the values 0 and -1. On error, FPUTC returns -1.

F P U T S

The function FPUTS writes a string to a file.

The call is: ISTAT = FPUTS (CSTR, NU)

CSTR is a string that should be written to the file. A newline character is inserted after the string.
NU is a file unit.
ISTAT is the returned status of FPUTS and can have the values 0 and -1. On error, FPUTS returns -1.

Additional note:

9.9 Binary Input and Output Functions

F R E A D

The function FREAD reads binary data from a file.

The call is: NRET = FREAD (VRAY, N, NU)

VRAY is an array where the binary data should be filled in.
N is the number of array elements that should be filled with data.
NU is a file unit.
NRET is the number of elements read, or -1 if end of file or error occurs.

F W R I T E

The function FWRITE writes binary data to a file.

The call is: NRET = FWRITE (VRAY, N, NU)

VRAY is an array containing the data that should be written to the file.
N is the number of array elements that should be written to the file.
NU is a file unit.
NRET is the number of elements written, or -1 if error occurs.

9.10 Example

The following example copies a text files and converts it to uppercase letters. 
  %GCL
  // Copies a file and converts it to uppercase letters

  char cr[100], cinp[40], cout[40]

  printf ('Inputfile: ')
  gets   (cinp)

  printf ('Outputfile: ')
  gets   (cout)

  inp =  fopen (cinp, 'r')
  if (inp == -1) exit
  out =  fopen (cout, 'w')
  if (out == -1) exit

  i = fgets (cr, 100, inp)
  while (i != -1)
    s = strupr (cr)
    fputs (s, out)
    i = fgets (cr, 100, inp)
  end while

  fclose (inp)
  fclose (out)
The example can be stored in a file and executed with the command:

gcl filename

Next | Previous | Contents