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):

• memoio.h -- This is the header file for programs using this library. It must be copied to a suitable "include" directory (e.g. rexdk/include/rex/).
• memoio.lib -- This is the self-contained precompiled library file. It must be copied to rexdk/lib/clibs/ and can be linked using -lmemoio on the zcc command line.
• memoio-ro.lib -- This is a smaller self-contained precompiled library file which only supports read operations on Memos. It must be copied to rexdk/lib/clibs/ and can be linked using -lmemoio-ro on the zcc command line.
• memoio-so.lib -- This is a precompiled library file using the shareable library version of MEMOIO. It should be copied to rexdk/lib/clibs/ and linked using -lmemoio-so on the zcc command line. This library must be used in conjunction with the Rex addins described below.
• memoio-read.rex -- This is a Rex addin which contains the MEMOIO library routines needed for Memo reading. It is accessed using the shareable library version of the MEMOIO library. This addin must be loaded on the Rex before a program which uses the MEMOIO shareable library can run. If you know your addin only does read operations you only need to load this library.
• memoio-write.rex -- This is a Rex addin which contains the MEMOIO library routines needed for write access to Memos. It is also accessed using the shareable library version of the GRCLIB library. This addin must be loaded on the Rex before a program which opens a Memo for write access can run.

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

• If the addin is linked against memoio.lib, any required library routines are included in the addin and no extra programs are required to run it. Full read-write access is available. Note that the GRCLIB library must also be linked in.
• If the addin is linked against memoio-ro.lib, any required library routines are included in the addin and no extra programs are required to run it. However, only read access is available -- attempts to open a Memo with any mode which would permit writing returns an error. Note that the GRCLIB library must also be linked in.
• Alternatively, if the addin is linked against memoio-so.lib, a minimum amount of code is included in to the addin and the library routines themselves are accessed from the memoio-read.rex and memoio-write.rex shareable library addins. If you do not have the memoio-write.rex addin loaded and you attempt to open a Memo for write access, your addin will terminate as the stub fails to find the required write routines. In this case, the GRCLIB library must also be included in the link but it does not matter whether the static (-lgrclib) or shareable (-lgrclib-so) versions are used: in either case the required GRCLIB routines are linked statically and the GRCLIB library addin is not required.

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

• NULL, true, false -- all with conventional defintions, and only defined if they are not defined already.
• MEMONAME_MAX -- maximum supported length for a Memo name.
• MEMO_EOF -- end of file indicator.
• MEMO_SEEK_SET, MEMO_SEEK_CUR, MEMO_SEEK_END -- analogous to SEEK_SET, SEEK_CUR, SEEK_END.

memo_open

Open a Memo and associate a stream.

Prototype

Parameters

• MEMO *stream -- pointer to MEMO stream structure (must be allocated by caller)
• unsigned char *memo_name -- pointer to memo title
• unsigned char *mode -- mode string (as for fopen). If mode is NULL, "r" is assumed.

Return Value

• >=0 -- success
• <0 -- error

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

• Stream is allocated by caller, not returned by the function.
• Stream is of type MEMO not FILE.
• Return value is error status (negative indicates error, non-negative is success)
• If the return value is success, memo_close must be called for the same stream or a database handle will be permanently lost.

memo_close

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

Prototype

Parameters

• MEMO *stream -- pointer to MEMO stream structure

Return Value

• >=0 -- success
• <0 -- error

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

• Return value is error status (negative indicates error, non-negative is success)

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

Parameters

• MEMO *stream -- pointer to MEMO stream structure

Return Value

• >=0 -- success
• <0 -- error

Comparison with fflush

• The NULL stream argument is not supported.
• Return value is error status (negative indicates error, non-negative is success)

memo_remove

Delete a Memo.

Prototype

Parameters

• const unsigned char *memo_name -- pointer to memo title

Return Value

• >=0 -- success
• <0 -- error

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

Parameters

• const unsigned char *old_name -- pointer to old memo title
• const unsigned char *new_name -- pointer to new memo title

Return Value

• >=0 -- success
• <0 -- error

Notes

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

memo_seek

Seek to a particular position in the memo.

Prototype

Parameters

• MEMO *stream -- pointer to MEMO stream structure
• int offset -- offset, in bytes, from the origin
• int origin -- one of MEMO_SEEK_SET (offset is from beginning of file), MEMO_SEEK_CUR (offset is from current file position), MEMO_SEEK_END (offset is from end of file).

Return Value

• 0 -- success
• <0 -- error

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

• The offset is an int, not a long int.
• Seeking beyond the end of file is only permitted in limited circumstances.

memo_getc

Read a character from a Memo.

Prototype

Parameters

• MEMO *stream -- pointer to MEMO stream structure

Return Value

• character or MEMO_EOF -- MEMO_EOF indicates an error or end of file

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

Parameters

• char *buffer -- address of buffer to store characters
• int length -- maximum size of buffer
• MEMO *stream -- pointer to MEMO stream structure

Return Value

• buffer or NULL -- NULL indicates an error or end of file

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

Parameters

• int c -- single character
• MEMO *stream -- pointer to MEMO stream structure

Return Value

• >=0 -- success
• MEMO_EOF -- error

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

• Success value is zero, not the input character, c.

memo_puts

Wite a string to a Memo.

Prototype

Parameters

• char *buffer -- address of NUL-terminated string
• MEMO *stream -- pointer to MEMO stream structure

Return Value

• >=0 -- success
• MEMO_EOF -- error

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

• memo_clearerr(MEMO *stream) -- reset the error flag (but not the eof flag).
• int memo_eof(MEMO *stream) -- return the end of file indicator.
• int memo_err(MEMO *stream) -- return the error code (0 indicates no error, all error codes are negative).
• int memo_tell(MEMO *stream) -- return the current Memo offset.
• memo_rewind(MEMO *stream) -- seek to start of Memo.

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 times.