Community
SCI Programming => SCI Development Tools => Topic started by: ZvikaZ on October 04, 2020, 05:47:22 AM
-
Hi.
I think there's an error in SCICompanion's documentation for `fopen` (http://scicompanion.com/Documentation/Kernels/FOpen.html):
Upon success, it returns a handle to the file, otherwise, it returns NULL.
However, in Sierra's original kernel documentation (https://github.com/OmerMor/SCI16/blob/master/DOC/KERNEL.TXT):
(FileIO fileOpen filename [mode])
Opens the file whose name is filename and returns a handle to it. The
optional parameter mode may be either fAppend, in which case the file
pointer will be positioned at the end of the file for appending, or
fTrunc, in which case the file will be truncated to zero length, or FRead
in which case the file pointer will be positioned at the beginning of the
file. If mode is not specified, fAppend is assumed. If there is an
error in opening the file, a value of -1 is returned, else the file handle.
i.e., in case of an error, "a value of -1 is returned", while in SCICompanion it says "it returns NULL" (which is of course 0; but to be 100% certain I've verified that it's so - it's defined in SYSTEM.SH)
Also, the code example in the bottom of that page should be fixed accordingly:
(procedure (Foo &tmp hFile [buffer41])
; Open the file and write to it
(if (!= NULL (= hFile (FOpen "somefile.txt" fCREATE)))
(FPuts hFile "Hello World!")
(FClose hFile)
)
; Open the file, read it's first string, and print it to the screen
(if (!= NULL (= hFile (FOpen "somefile.txt" fOPENFAIL)))
(FGets buffer 40 hFile)
(FClose hFile)
(Print buffer)
)
)
Is there any better place to report this?
-
The only better place would be GitHub, and even then specifically Phil's if you want the online version to be corrected. But this'll do, and I'll at least update the copy that comes with my branch.
At a closer look, you might want to notice how the SCI Companion doc you linked describes FOpen, a kernel method onto its own, while the original documentation describes FileIO fileOpen, a sub-operator.
-
These are not the same kernel calls. There's FOpen, FGets and friends, and then there's FileIO. The latter is used in SCI01 and later, SCI0 has the former ones. I haven't checked the return types of each, but they could be different.
-
These are not the same kernel calls. There's FOpen, FGets and friends, and then there's FileIO. The latter is used in SCI01 and later, SCI0 has the former ones. I haven't checked the return types of each, but they could be different.
You're right Lars.
However, even the Kernel documentation for SCI0 (from 1988-04-04) (https://gist.github.com/OmerMor/3490296ec7cd7bfe45e7689fed35779c#file-sci-kernel-documentation-1988-04-04-txt-L661) mentions it return -1 on error:
(FOpen filename [mode])
Opens the file whose name is filename and returns a handle to it. The
optional parameter mode may be either fAppend, in which case the file
pointer will be positioned at the end of the file for appending, or
fTrunc, in which case the file will be truncated to zero length. If
mode is not specified, fAppend is assumed. If there is an error in
opening the file, a value of -1 is returned.
-
Lars, and Omer, thanks.
You're right of course. It was my copy-paste error.
(funny to have an error, in an error report ;D )
BTW,
I forgot to credit sluicebox, from ScummVM team, for raising the issue of `fopen` return value.
-
You can also use the File class to manage files.
(instance fooFile of File
(properties
name "somefile.txt"
)
(procedure (Foo &tmp [buffer 41])
; Open the file and write to it
(if (fooFile open: fTrunc)
(fooFile write: "Hello World!")
(fooFile close:)
)
; Open the file, read it's first string, and print it to the screen
(if (fooFile open: fRead)
(fooFile read: @buffer 40)
(fooFile close:)
(Printf "%s" buffer)
)
)
This way is much simpler than using the kernel functions directly. With SCI01 and up, read: and write: are renamed to readString: and writeString: respectively. Should test this to see how it works...
-
I've noticed a few mistakes throughout the SCI Companion Docs, mostly negligible though. Such as references to Python, and the obvious broken links to SCI Studio docs etc.
-
I've noticed a few mistakes throughout the SCI Companion Docs, mostly negligible though. Such as references to Python, and the obvious broken links to SCI Studio docs etc.
That's expected, expected in a non-maintained project.
Have you seens Kawa's suggestion?
The only better place would be GitHub, and even then specifically Phil's if you want the online version to be corrected.
You can send Phil a Pull Request in Github to fix the docs. The documentation "source code" can be found here:
https://github.com/icefallgames/SCICompanion/tree/master/SCICompanion/Docs
-
Of course, if the program itself uses a local copy of the docs, it's well within my power to correct it that far.
-
You can send Phil a Pull Request in Github to fix the docs. The documentation "source code" can be found here:
https://github.com/icefallgames/SCICompanion/tree/master/SCICompanion/Docs
Hmm I never considered that. I mean, it doesn't really bother me but if I get around to it I'll send a pull request.
-
Looking deeper into this just to confirm, according to the SCI11 source code the FileIO kernel call passes the return values from creat and open, old-school file routines that return either a valid handle or -1.
- If the mode argument is 2 (F_TRUNC in C, fTrunc in Sierra's header, fCREATE in Brian's), call create(buf, 0) and return the handle it returned, which may be -1.
- If it's not 2, try to open(buf, O_RDWR).
- If that didn't work (it's -1) and the mode is 0/F_APPEND/fAppend/fOPENCREATE (fOPENFAIL in SCI0 because of a mistake), creat the file instead.
- If it did open the file and the mode is 0/F_APPEND/fAppend/fOPENCREATE, seek to the end. In either case, return the handle, which again may be -1 if the creat call failed.
- Behavior for 1/F_READ/fRead/fOPENFAIL is implied -- if the file could be opened in the first place, we're done!
Lacking any source code for SCI0, I can only assume its separated file IO kernel calls are the same in actual use. Just make sure to keep in mind that Phil has chosen to keep Brian's mistake in the SCI Companion header file, so fOPENCREATE and fOPENFAIL are reversed. Personally, I'd just use the Sierra names and avoid the collission.