MEMOIO for Rex 6000 V0.4

This is a package which provides Memo input/output functions, modelled on the C standard I/O (stdio) functions.

Installation

Copyright (C) 2002 Graham R. Cobb. The package is distributed under the GPL (see the copyright notices and the COPYING file).

MEMOIO For Rex 6000 is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

MEMOIO For Rex 6000 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The MEMOIO distribution contains six main files in the top level directory (as well as sources and some informational files):

The addin programmer has a choice of three forms of the library to use:

The package also contains the sources for the two forms of the library and the shareable library addins and also for a test addin.

Documentation

For MEMOIO Version 0.4.

These routines are based on the C stdio.h library but with several important differences:

  1. The most visible difference is that the stream data structures must be allocated as local variables by the caller and the address passed into all routines.
  2. A less visible but critical difference is that streams must be closed before exiting the addin. If this is not done, a database handle will be lost. This will not be recovered until a reset of the Rex occurs (pressing the reset button on the back).
  3. errno is not used. Errors are stored in the stream structure and can be retrieved using memo_err.
  4. Only a subset of stdio.h routines (and a few others) have counterparts. In particular, there is no concept of standard input, output or error.
  5. Binary mode is partially implemented. I think the existing support works but it has not been properly tested and is pretty useless until memo_read and memo_write are developed.

memoio.h

This header file defines several supported constants and one typedef (which should be considered opaque -- the contents can change in future releases).

Stream data structure

The stream data structure is critical -- it is used by all the memo routines to keep context. It is defined in memoio.h as the MEMO type and must be allocated by the caller of memo_open:

MEMO stream;

memo_open(&stream, "name", "r");

Note: the memo routines expect the address of the stream. If you forget the & the current compiler will silently add it and everything will work. However, your code will break if that compiler bug is ever fixed and the structure ends up passed by value!

Constants

memo_open

Open a Memo and associate a stream.

Prototype

int memo_open(MEMO *stream, const unsigned char *memo_name, const unsigned char *mode)

Parameters

Return Value

Notes

  1. Any error is also stored in the stream and can be retrieved using memo_err.
  2. The memo database will be opened and left open with the current record pointing to the memo. The database must be closed by the caller using memo_close.
  3. The memo will be marked as modified (for synchronisation purposes) if it is opened for write access. It doesn't matter whether any writes actually occur.
  4. Categories are not supported: if the Memo is created, the category will be a null string and no entries will be made in the category table.

Comparison with fopen

memo_close

Terminate I/O operations on a Memo, flush the stream, free the database handle and disassociate the stream.

Prototype

int memo_close(MEMO *stream)

Parameters

Return Value

Notes

  1. Any error is also stored in the stream and can be retrieved using memo_err.
  2. If an error has previously occured, the stream can be closed, despite the error incdication in the stream (this is important so the DB is closed) but the existing error code will be preserved and will be returned.

Comparison with fclose

memo_flush

Flush any pending I/O for the stream. This routine is unlikely to be useful on the Rex as other applications cannot be trying to access the Memo simultaneously. The final flush is performed automatically by memo_close.

Prototype

int memo_flush(MEMO *stream)

Parameters

Return Value

Comparison with fflush

memo_remove

Delete a Memo.

Prototype

int memo_remove(const unsigned char *memo_name)

Parameters

Return Value

Notes

  1. The memo status will be marked as deleted (for synchronisation purposes).
  2. The TextInfo table entry will also be deleted.

memo_rename

Rename a Memo.

Prototype

int memo_rename(const unsigned char *old_name, const unsigned char *new_name)

Parameters

Return Value

Notes

  1. The memo status will be marked as modified (for synchronisation purposes).

memo_seek

Seek to a particular position in the memo.

Prototype

int memo_seek(MEMO *stream, int offset, int origin)

Parameters

Return Value

Notes

  1. Seeking beyond the end of file is only permitted if write access is allowed and the file has been opened in binary mode.
  2. Any error is also stored in the stream and can be retrieved using memo_err.

Comparison with fseek

memo_getc

Read a character from a Memo.

Prototype

int memo_getc(MEMO *stream)

Parameters

Return Value

Notes

  1. End of file flag is stored in the stream and can be retrieved using memo_eof.
  2. Any error is stored in the stream and can be retrieved using memo_err.

memo_gets

Read a line from a Memo.

The function reads bytes from stream into the array pointed to by buffer, until length-1 bytes are read, or a newline character is read and transferred to buffer, or an end-of-file condition is encountered. The string is then terminated with a null byte.

Prototype

char *memo_gets(char *buffer, unsigned short length, MEMO *stream)

Parameters

Return Value

Notes

  1. End of file flag is stored in the stream and can be retrieved using memo_eof.
  2. Any error is stored in the stream and can be retrieved using memo_err.
  3. If the memo was opened in binary mode, newlines are not treated specially. However, note that NULs are also not treated specially and may occur in the middle of the buffer, causing confusion. Binary reading is best done using memo_read.

memo_putc

Wite a byte to a Memo.

Prototype

int memo_putc(int c, MEMO *stream)

Parameters

Return Value

Notes

  1. If the memo was opened in binary mode, newlines are not treated specially.
  2. Any error is stored in the stream and can be retrieved using memo_err.
  3. The Memo is always "truncated" after this write. In other words, the byte written becomes the last byte of the Memo. It is not possible to just overwrite bytes of the Memo.

Comparison with fputc

memo_puts

Wite a string to a Memo.

Prototype

int memo_puts(const char *buffer, MEMO *stream)

Parameters

Return Value

Notes

  1. If the memo was opened in binary mode, newlines are not treated specially.
  2. Any error is stored in the stream and can be retrieved using memo_err.
  3. The Memo is always "truncated" after this write. In other words, the last byte written becomes the last byte of the Memo. It is not possible to just overwrite bytes of the Memo.

Macros

Changes

In V0.4

Link with new FindLib from August 2002 RexDk

In V0.3

Remove unintended dependency on GRCLIB.

In V0.2

Use new Rexdk library mechanism.


Return to Graham's Rex page

This page has been accessed Access counter times.

Graham Cobb