Author Topic: Error in SCICompanion documentation - fopen  (Read 228 times)

0 Members and 1 Guest are viewing this topic.

Offline ZvikaZ

Error in SCICompanion documentation - fopen
« 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):
Quote
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):
Quote
(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:
Code: [Select]
(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?



Offline Kawa

Re: Error in SCICompanion documentation - fopen
« Reply #1 on: October 04, 2020, 06:30:42 AM »
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.
« Last Edit: October 04, 2020, 07:24:50 AM by Kawa »

Offline lskovlun

Re: Error in SCICompanion documentation - fopen
« Reply #2 on: October 04, 2020, 07:12:12 AM »
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.

Offline OmerMor

Re: Error in SCICompanion documentation - fopen
« Reply #3 on: October 04, 2020, 07:27:53 AM »
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) mentions it return -1 on error:

Quote
(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.

Offline ZvikaZ

Re: Error in SCICompanion documentation - fopen
« Reply #4 on: October 04, 2020, 11:39:23 AM »
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.

Offline EricOakford

Re: Error in SCICompanion documentation - fopen
« Reply #5 on: October 04, 2020, 05:15:12 PM »
You can also use the File class to manage files.

Code: [Select]
(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...
My SCI templates
SCI0 SCI0.1 SCI1.0 SCI1.1
SCI2.1 planned

Offline cosmicr

Re: Error in SCICompanion documentation - fopen
« Reply #6 on: October 04, 2020, 10:29:39 PM »
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.

Offline OmerMor

Re: Error in SCICompanion documentation - fopen
« Reply #7 on: October 05, 2020, 11:16:19 AM »
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

Offline Kawa

Re: Error in SCICompanion documentation - fopen
« Reply #8 on: October 05, 2020, 03:41:59 PM »
Of course, if the program itself uses a local copy of the docs, it's well within my power to correct it that far.

Offline cosmicr

Re: Error in SCICompanion documentation - fopen
« Reply #9 on: October 05, 2020, 11:51:15 PM »
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.

Offline Kawa

Re: Error in SCICompanion documentation - fopen
« Reply #10 on: October 06, 2020, 05:55:44 AM »
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.


SMF 2.0.14 | SMF © 2017, Simple Machines
Simple Audio Video Embedder

Page created in 0.129 seconds with 25 queries.