11.3.1 Input and output functions

WriteF(string,param1,param2,...)

Writes a string to the standard output and returns the number of characters written. If place-holders are used in the string then the appropriate number of parameters must be supplied after the string in the order they are to be printed as part of the string. So far we've only met the `\d' place-holder for decimal numbers. The complete list is:

Place-Holder  Parameter Type   Prints
-------------------------------------------------
     \c          Number        Character
     \d          Number        Decimal number
     \h          Number        Hexadecimal number
     \s          String        String

So to print a string you use the `\s' place-holder in the string and supply the string (i.e., a PTR TO CHAR) as a parameter. Try the following program (remember `\a' prints an apostrophe character):

PROC main()
  DEF s[30]:STRING
  StrCopy(s, 'Hello world', ALL)
  WriteF('The third element of s is "\c"\n', s[2])
  WriteF('or \d (decimal)\n',                s[2])
  WriteF('or \h (hexadecimal)\n',            s[2])
  WriteF('and s itself is \a\s\a\n',         s)
ENDPROC

This is the output it generates:

The third element of s is "l"
or 108 (decimal)
or 6C (hexadecimal)
and s itself is 'Hello world'

You can control how the parameter is formatted in the `\d', `\h' and `\s' fields using another collection of special character sequences before the place-holder and size specifiers after it. If no size is specified the field will be as big as the data requires. A fixed field size can be specified using [number] after the place-holder. For strings you can also use the size specifier (min,max) which specifies the minimum and maximum sizes of the field. By default the data is right justified in the field and the left part of the field is filled, if necessary, with spaces. The following sequences before the place-holder can change this:

Sequence        Meaning
-----------------------------------
   \l     Left justify in field
   \r     Right justify in field
   \z     Set fill character to "0"

See how these formatting controls affect this example:

PROC main()
  DEF s[30]:STRING
  StrCopy(s, 'Hello world', ALL)
  WriteF('The third element of s is "\c"\n', s[2])
  WriteF('or \d[4] (decimal)\n',             s[2])
  WriteF('or \z\h[4] (hexadecimal)\n',       s[2])
  WriteF('\a\s[5]\a are the first five elements of s \n', s)
  WriteF('and s in a very big field  \a\s[20]\a\n',   s)
  WriteF('and s left justified in it \a\l\s[20]\a\n', s)
ENDPROC

Here's the output it should generate:

The third element of s is "l"
or  108 (decimal)
or 006C (hexadecimal)
'Hello' are the first five elements of s 
and s in a very big field  '         Hello world'
and s left justified in it 'Hello world         '

WriteF uses the standard output, and this file handle is stored in the stdout variable. If your program is started from Workbench this variable will contain NIL. In this case, the first call to WriteF will open a special output window and put the file handle in the variables stdout and conout, as outlined above (see 11.2 Built-In Variables).

PrintF(string,param1,param2,...)

PrintF works just like WriteF except it uses the more efficient, buffered output routines only available if your Amiga is using Kickstart version 37 or greater (i.e., AmigaDOS 2.04 and above).

StringF(e-string,string,arg1,arg2,...)

The same as WriteF except that the result is written to e-string instead of being printed. For example, the following code fragment sets s to `00123 is a' (since the E-string is not long enough for the whole string):

  DEF s[10]:STRING
  StringF(s, '\z\d[5] is a number', 123)

Out(filehandle,char)

Outputs a single character, char, to the file or console window denoted by filehandle, and returns -1 to indicate success (so any other return value means an error occurred). For instance, filehandle could be stdout, in which case the character is written to the standard output. (You need to make sure stdout is not NIL, and you can do this by using a WriteF(") call.) In general, you obtain a filehandle using the Amiga system function Open from the `dos.library' (see 19 String Handling and I/O).

Inp(filehandle)

Reads and returns a single character from filehandle. If -1 is returned then the end of the file (EOF) was reached, or there was an error.

ReadStr(filehandle,e-string)

Reads a whole string from filehandle and returns -1 if EOF was reached or an error occurred. Characters are read up to a linefeed or the size of the string, whichever is sooner. Therefore, the resulting string may be only a partial line. If -1 is returned then EOF was reached or an error occurred, and in either case the string so far is still valid. So, you still need to check the string even if -1 is returned. (This will most commonly happen with files that do not end with a linefeed.) The string will be empty (i.e., of zero length) if nothing more had been read from the file when the error or EOF happened.

This next little program reads continually from its input until an error occurs or the user types quit. It echoes the lines that it reads in uppercase. If you type a line longer than ten characters you'll see it reads it in more than one go. Because of the way normal console windows work, you need to type a return before a line gets read by the program (but this allows you to edit the line before the program sees it). If the program is started from Workbench then stdin would be NIL, so WriteF(") is used to force stdout to be valid, and in this case it will be a new console window which can be used to accept input! (To make the compiled program into a Workbench program you simply need to create a tool icon for it. A quick way of doing this is to copy an existing tool's icon.)

PROC main()
  DEF s[10]:STRING, fh
  WriteF(")
  fh:=IF stdin THEN stdin ELSE stdout
  WHILE ReadStr(fh, s)<>-1
    UpperStr(s)
  EXIT StrCmp(s, 'QUIT', ALL)
    WriteF('Read: \a\s\a\n', s)
  ENDWHILE
  WriteF('Finished\n')
ENDPROC

There are some worked examples in Part Three (see 19 String Handling and I/O) which also show how to use ReadStr.

FileLength(string)

Returns the length of the file named in string, or -1 if the file doesn't exist or an error occurred. Notice that you don't need to Open the file or have a filehandle, you just supply the filename. There is a worked example in Part Three (see 19 String Handling and I/O) which shows how to use this function.

SetStdIn(filehandle)

Returns the value of stdin before setting it to filehandle. Therefore, the following code fragments are equivalent:

  oldstdin:=SetStdIn(newstdin)

  oldstdin:=stdin
  stdin:=newstdin

SetStdOut(filehandle)

Returns the value of stdout before setting it to filehandle, and is otherwise just like SetStdIn.

Go to the Next or Previous section, the Detailed Contents, or the Amiga E Encyclopedia.