SHELL with HANDLES Option Testing

[Michael Mattias]

You tell me what this means:
Calling (parent) program:

' sheller.bas
' 10.22.08
' Demonstration of use iof the poorly-documented "HANDLES" option in the
' SHELL statement and function.

' This is the parent" program, which SHELLs to "Shellee.exe".
' My best guess when starting is, the HANDLES option opens files with the
' 'binheritHandle' flag in the SECURITY_DESCRIPTOR parameter of the
' "CreateFile" call which underlies the PowerBASIC "OPEN" statement.
'  This program is going to SHELL to "Shellee" twice: once with
'  the HANDLES option, and once without, passing a system file handle on the
'  command line. The SHELLEE program will attempt to open the passed file
'  and will report on success or failure of that operation.
'  Hmm, looks like it's supposed to work the way I thought, except
'  a bug in OPEN HANDLE used in SHELLEE (not setting ERR) prevents using it.

' ONe thing for sure, programs share the console regardless. (?)

' -----------------------------------------------------------------
'  ENVIRONMENT: WIN/XP Pro SP3 all updates
'  I suspect win 9x will work always regardless of HANDLES option
' ----------------------------------------------------------------
#COMPILE  EXE
#DIM      ALL
#DEBUG    ERROR ON
#REGISTER NONE
#TOOLS    OFF
#COMPILER PBCC    ' version 5 used but not using any v5-soecific features.


$TESTFILE_NAME = "~SHELLTEST.TXT"
$SHELLEE_NAME  = "SHELLEE.EXE"

FUNCTION PBMAIN () AS LONG
     
  LOCAL hFile AS LONG, hSys AS LONG
  LOCAL S AS STRING, I AS LONG
  LOCAL cmdLine AS STRING
     
     STDOUT "Program SHELLER begins at " & TIME$ & " on " & DATE$
' Create a file for use with this program
     STDOUT USING$ ("Creating new file '&'", $TESTFILE_NAME)
     
  hFIle = FREEFILE
  OPEN $TESTFILE_NAME FOR OUTPUT AS hFile
  FOR I = 1 TO 10
     S = USING$ ( "& LINE ## ", $TESTFILE_NAME, I)
     PRINT #hFile,S
  NEXT
  CLOSE hFile
  
  ' -------------------------------------------------
  ' OPEN THE FILE FOR INPUT, not shared; and close
  ' after each test to ensure "clean" start.
  ' --------------------------------------------------
  
  FOR I = 1 TO 2
       ' open fresh each time
       hFile = FREEFILE
       OPEN    $TESTFILE_NAME FOR INPUT AS hFile
      ' get system handle
       hSys  = FILEATTR(hFile,2)
       cmdLine = USING$ ("& #", $SHELLEE_NAME, hSys)
       IF I = 1 THEN   ' no handles option
            STDOUT USING$ ("Shelling (no HANDLES option) &", cmdLine)
            SHELL  cmdLine
            STDOUT "Back"
       ELSE
            STDOUT USING$ ("Shelling (With HANDLES option) &" , cmdLine)
            SHELL  HANDLES, cmdLine
            STDOUT "Back"
       END IF
       CLOSE hFIle
  NEXT
  STDOUT "End of demonstration, any key"
  WAITKEY$

END FUNCTION
' end of file sheller.bas

Called (child) program:

' shellee.bas
' 10.22.08
' Demonstration of use of the poorly-documented "HANDLES" option in the
' SHELL statement and function.

' This is the "child" program, which SHELLed by "Sheller.exe".
' the command line is a system file handle to a file opened
' by the parent program "Sheller"
' This program will attempt to open and read that file,
' reporting what happens

#COMPILE  EXE
#DIM      ALL
#DEBUG    ERROR ON
#REGISTER NONE
#TOOLS    OFF
#COMPILER PBCC    ' version 5 used but not using any v5-soecific features.


FUNCTION PBMAIN() AS LONG
     
     LOCAL hSYS AS LONG, hFIle AS LONG, S AS STRING
     LOCAL E AS LONG
     LOCAL bEOF AS LONG
     
     STDOUT "Program SHELLEE begins at " & TIME$ & " on " & DATE$
     
     hSys = VAL (COMMAND$)
     
     STDOUT USING$ ("Opening passed system handle #", hSys)
     hFile   = FREEFILE
     ERRCLEAR
     OPEN    HANDLE hSys FOR INPUT AS hFile
     ' I am not getting an error when shelled without handles error?
     ' BUt file is not reading? EOF is set immediately!
     ' When SHELLed WITH handles option, the file is read just fine.
     IF E THEN
          STDOUT USING$("Open HANDLE failed code # &", E, ERROR$(E))
     ELSE
          STDOUT "Open HANDLE Succeeded, reading file"
          bEOF  = 0
          DO WHILE ISFALSE bEOF
               ERRCLEAR
               bEOF = EOF(hFile)
               IF E THEN
                    STDOUT USING$ ("EOF failed code # &", E, ERROR$(E))
               ELSEIF ISFALSE (bEOF) THEN
                  LINE INPUT #hFIle, S
                  E = ERRCLEAR
                  IF E THEN
                       STDOUT USING$("Line Input Failed Code # &", E, ERROR$(E))
                       EXIT DO
                  ELSE
                       STDOUT S
                   END IF
              END IF
          LOOP
          CLOSE hFile
     END IF
     STDOUT "End of program SHELLEE. Any Key to terminate"
     WAITKEY$
     
END FUNCTION

My results:
Without "HANDLES" option, "SHELLEE" reports no errors but immediately gets EOF()=TRUE and reads nothing.

With "HANDLES" option "SHELLEE" reads file pretty much as I expected

And in either case, the SHELLER and SHELLEE share the same console.

My conciusion is a bug in OPEN HANDLE, not reporting an open error. Or maybe a bug in EOF(), not reporting an error when used on invalid handle. Maybe both.

Stumps me for now, would appreciate others' results.

(If confirmed I'll submit the bug report).

MCM

[Michael Mattias]

I was thinking on this some more...

maybe the HANDLES option means the 'bInherit' parameter will set to TRUE on the underlying "createProcess" call used by SHELL...

bInheritHandles
[in] If this parameter TRUE, each inheritable handle in the calling process is inherited by the new process. If the parameter is FALSE, the handles are not inherited. Note that inherited handles have the same value and access rights as the original handles.

... and the OPEN statement ALWAYS opens files with "inheritable" set.

Now I'm sure it's one of these two things which HANDLES does. I am leaning toward this one based on my demo code... the handle was a valid system handle, but not usable when the HANDLES option was not specified on the SHELL... which means OPEN HANDLE or maybe EOF() has a bug, not setting ERR when it should. I guess I could add code to use API functions to test for EOF and or "read/writeability" ... but I'd rather just read it in the help file.

MCM