


                                                                  C_Shell()
                                                                  C_Shell()
                                                                  C_Shell()





                                  Table of Contents
                                  Table of Contents
                                  Table of Contents

               Introduction.............................................3

               Installation.............................................3

               Compatibility............................................4

               Using C_Shell()..........................................4

               Errors...................................................8

               Linking with C_Shell()...................................9

               Index....................................................11



          C_Shell()
          C_Shell()
          C_Shell()

























































                                       2



                                                                  C_Shell()
                                                                  C_Shell()
                                                                  C_Shell()




               Introduction
               Introduction
               Introduction

               C_Shell() is a replacement function for exec and spawn that
               optionally swaps out its memory image to XMS, EMS, or disk,
               and then shrinks itself down to its smallest possible size
               (about 5K) before executing a program. C_Shell() is
               particularly useful for memory hungry applications, DOS
               menuing applications, or front end type programs.

               C_Shell() is based in part on public domain software
               developed by Thomas Wagner.


               Installation
               Installation
               Installation

               To install C_Shell() insert the distribution disk into a
               floppy drive and type

               A:install A: D:

               Where A represents the floppy drive where the distribution
               disk is located and D represents the drive where you want to
               install C_Shell(). When the installation process is complete
               it will have created a CSHELL directory in the root of the
               destination disk.

               The directory structure should look like this:

               CSHELL-------+
                            |
                            +- Source (source code, header files,
                            |          and make files)
                            |
                            +- BC3L   (Borland C++ large model
                            |          make files)
                            |
                            +- BC3S   (Borland C++ small model
                            |          make files)
                            |
                            +- MC6L   (Microsoft C large model
                            |          make files)
                            |
                            +- MC6S   (Microsoft C small model
                            |          make files)
                            |
                            +- LIB    (Library files)







                                            3



          C_Shell()
          C_Shell()
          C_Shell()




          Compatibility
          Compatibility
          Compatibility

          C_Shell() is compatible with other SeaBreeze Software
          Products, including the MoreHeap memory manager, the
          SafeHeap memory debugger, MegaHeap the XMS/EMS manager, and
          4Sight a graphical application framework.

          C_Shell() is compatible with large and small memory models
          of Borland C++  and Microsoft C.

          C_Shell()'s EMS support is compatible with LIM-EMS version
          3.0 and above.

          C_Shell()'s XMS support requires an XMS manager such as
          HIMEM.SYS, QEMM-386, or 386 to the MAX to be installed.

          C_Shell() requires DOS 2.0 or above to operate properly.
          (DOS 3.0 or above for disk swapping.)


          Using C_Shell()
          Using C_Shell()
          Using C_Shell()

          Your application's interface to C_Shell() consists of a
          single function call. The prototype for this function call
          and the definitions of constants used to construct arguments
          to the function call are found in SOURCE\CSHELL.H

          To use the C_Shell() function simply include "cShell.h" in
          the source modules where you want to use C_Shell(). The
          C_Shell() function prototype is :

          int C_Shell ( char *prog, char *cmdline,
                        unsigned minmem, char **envp,
                        char swapflags );



















                                       4



                                                                  C_Shell()
                                                                  C_Shell()
                                                                  C_Shell()



               Each argument is interpreted as following:

               prog                 The name of the program to execute,
                                    use "" to shell to the command line.

               cmdline              The parameters that would be passed to
                                    the program on the command line. For
                                    example, to display a directory
                                    listing you pass "" for prog and "/c
                                    dir" for cmdline. The command line
                                    cannot exceed 127 characters.

               minmem               The minimum number of paragraphs
                                    needed to execute the program. If this
                                    number is less than available memory
                                    the current application will not be
                                    swapped. Use 0xFFFFU to always force
                                    the swap.

               envp                 The environment table to be passed to
                                    the new application. If you want prog
                                    to have a copy of the current
                                    applications environment table pass
                                    NULL (putenv won't affect your
                                    application's environment table). If
                                    you want the prog to have the same
                                    environment table pass the standard
                                    variable environ.

               swapflags            OR ("|") the following bit flags
                                    together to indicate the following
                                    options.






















                                            5



          C_Shell()
          C_Shell()
          C_Shell()




          FLAG        Explanation

          _EXEC
          _EXEC
          _EXEC       Using this terminates your application on
                      return from the spawned application.


          _SWAPPING
          _SWAPPING
          _SWAPPING   Enables swapping out of the current
                      applications memory image.


          _USE_XMS
          _USE_XMS
          _USE_XMS    When combined with _SWAPPING will attempt
                      to swap out the memory image to extended
                      memory. XMS swapping requires an XMS
                      manager like HIMEM.SYS or QEMM-386 to be
                      present.


          _USE_EMS
          _USE_EMS
          _USE_EMS    When combined with _SWAPPING will attempt
                      to swap out the memory image to expanded
                      memory. EMS swapping requires a LIM-EMS
                      3.0 (or greater) manager like QEMM-386 to
                      be present.


          _USE_DISK
          _USE_DISK
          _USE_DISK   When combined with _SWAPPING will attempt
                      to swap out the memory image to disk. The
                      swap file will be a hidden file. It will
                      be located in the current directory or
                      the directory indicated in the TEMP or
                      TMP environment variable. The filename is
                      guaranteed not to conflict with existing
                      filenames.


          _SAVE_VID
          _SAVE_VID
          _SAVE_VID   Saves the video mode and restores it on
                      return.


          _SAVE_INT
          _SAVE_INT
          _SAVE_INT   Saves the interrupt table and restores it
                      on return.


          _SAVE_EMS
          _SAVE_EMS
          _SAVE_EMS   Saves the EMS mappings and restores them
                      on return.



          So to do a directory listing using the current environment
          table (faster and uses less memory) that would swap to XMS,
          EMS, or DISK you would call C_Shell() like this:



                                       6



                                                                  C_Shell()
                                                                  C_Shell()
                                                                  C_Shell()



               #include "cshell.h"
                 .
                 .
                 C_Shell ( "", "/c dir", 0xFFFFU, environ,
                    _SWAPPING | _USE_XMS | _USE_EMS | _USE_DISK );
                 .
                 .

               Errors
               Errors
               Errors

               C_Shell() returns an integer to indicate a problem. If the
               high word is 0x00 the low word contains the return value
               from the executed program.

               Anything other than a 0x00 in the high word indicates an
               error. The error conditions are as follows:


               Error Name        Error    Explanation

               SWAPOUT_ERR
               SWAPOUT_ERR
               SWAPOUT_ERR       0x0100
                                 0x0100
                                 0x0100   Could not find XMS, EMS, or
                                          disk space to swap out.

               FILE_NOT_FOUND
               FILE_NOT_FOUND
               FILE_NOT_FOUND    0x0200
                                 0x0200
                                 0x0200   Could not find the file to
                                          execute.

               DOS_ERROR
               DOS_ERROR
               DOS_ERROR         0x0300
                                 0x0300
                                 0x0300   Could not swap to disk due
                                          to problem with DOS. The
                                          lower bytes is the actual
                                          DOS error number.

               NO_ENVBUFSPACE
               NO_ENVBUFSPACE
               NO_ENVBUFSPACE    0x0400
                                 0x0400
                                 0x0400   You passed a NULL as envp
                                          but there was not enough
                                          heap space to allocate a
                                          copy of the environment
                                          table.

               MISALIGNED_OBJ
               MISALIGNED_OBJ
               MISALIGNED_OBJ    0x0500
                                 0x0500
                                 0x0500   SPAWN.OBJ is linked in too
                                          close the beginning of the
                                          executable. SPAWN.OBJ should
                                          not be the first object
                                          module linked in.












                                            7



          C_Shell()
          C_Shell()
          C_Shell()




          Linking 
          Linking 
          Linking with C_Shell()
                  with C_Shell()
                  with C_Shell()

          Once you've included a call to C_Shell() in you application
          you will need to link your application with the appropriate
          C_Shell() library to execute it.

          The C_Shell() libraries are included in CSHELL\LIB. There
          are 4 versions of the library:

          CSHELLBL.LIB
          CSHELLBL.LIB
          CSHELLBL.LIB       Borland C++ large
                             model

          CSHELLBS.LIB
          CSHELLBS.LIB
          CSHELLBS.LIB       Borland C++ small
                             model.

          CSHELLML.LIB
          CSHELLML.LIB
          CSHELLML.LIB       Microsoft C large
                             model.

          CSHELLMS.LIB
          CSHELLMS.LIB
          CSHELLMS.LIB       Microsoft C small
                             mode.

          For example to compile and link the sample TEST application
          under Borland C++, from the CSHELL\BC3L
                                      CSHELL\BC3L
                                      CSHELL\BC3L directory you would
          type:

          bcc -ml -I..\source -L..\lib test.c cshellbl.lib

          Under Microsoft C from the CSHELL\MC6L 
                                     CSHELL\MC6L 
                                     CSHELL\MC6L directory you would
          type:

          cl /AL /I..\source /L..\lib test.c cshellml.lib






















                                       8



                                                                  C_Shell()
                                                                  C_Shell()
                                                                  C_Shell()




                                          Index
                                          Index
                                          Index

               _EXEC, 6                        MoreHeap, 4

               _SAVE_EMS, 6                    NO_ENVBUFSPACE, 8

               _SAVE_INT, 6                    QEMM-386, 4, 6

               _SAVE_VID, 6                    SafeHeap, 4

               _SWAPPING, 6                    small memory model, 4

               _USE_DISK, 6                    spawn, 3

               _USE_EMS, 6                     SWAPOUT_ERR, 8

               _USE_XMS, 6                     video, 6

               386 to the MAX, 4               XMS, 3, 4, 6

               4Sight, 4

               disk, 3, 6

               DOS ERROR, 8

               EMS, 3, 4, 6

               environment table, 5, 8

               Errors, 8

               exec, 3

               FILE_NOT_FOUND, 8

               HIMEM.SYS, 4, 6

               Installation, 3

               interrupt table, 6

               large memory model, 4

               libraries, 9

               linking, 9

               MegaHeap, 4

               MISALIGNED_OBJ, 8


                                            9
