The [[SHELL]] statement allows a program to run external programs or command line statements in Windows, macOS and Linux.


{{PageSyntax}}
: [[SHELL]] [{{Parameter|DOSCommand$}}]
: [[SHELL]] ['''_DONTWAIT'''] ['''_HIDE'''] [{{Parameter|DOSCommand$}}]


{{PageDescription}}
* If the ''DOSCommand$'' [[STRING]] parameter isn't used, the "command console" is opened and execution is halted until the user closes it manually.
* If [[_DONTWAIT]] is used, the '''QB64''' program doesn't wait for the SHELLed program/command to end.
* When the [[_HIDE]] action is used, the [[CONSOLE|console]] window is hidden and screen info can be "redirected" (using redirection characters like >) to a file (recommended).
* Commands are external commands, according to the user's operating system, passed as [[STRING|strings]] enclosed in quotes or string variables.
* Commands can be a mixture of [[STRING|strings]] and string variables added together using the + [[concatenation]] operator.
* Command text can be in upper or lower case. Use single spacing between items and options.
* '''QB64''' automatically uses CMD /C when using [[SHELL]], but it is allowed in a command string. {{text|Note: CMD alone may lock up program.|red}}
** '''Note: Some commands may not work without adding CMD /C to the start of the command line.'''
* '''QB64''' program screens will not get distorted, minimized or freeze the program like QBasic fullscreen modes would. 
* '''QB64''' can use long path folder names and file names and [[SHELL]] command lines can be longer than 124 characters.
* In Windows, use additional [[CHR$]](34) quotation marks around folder or file names that contain spaces.
* For other operating systems, both the quotation mark character and the apostrophe can be used to enclose a file name that contains spaces.
*'''NOTE: Use [[CHDIR]] instead of CD as SHELL commands cannot affect the current program path.'''


{{PageQBasic}}
* '''QBasic BAS files could be run like compiled programs without returning to the IDE when [[SYSTEM]] was used to [[END|end]] them.'''
* A user would invoke it with {{InlineCode}}SHELL "QB.EXE /L /RUN program.BAS"{{InlineCodeEnd}}


{{PageExamples}}
''Example 1:'' When working with file or folder names with spaces, add quotation marks around the path and/or file name with [[CHR$]](34).
{{CodeStart}} '' ''
{{Cl|SHELL}} {{Cl|_HIDE}} "dir " + {{Cl|CHR$}}(34) + "free cell.ico" + {{Cl|CHR$}}(34) + " /b > temp.dir" '' '' 
{{Cl|SHELL}} "start Notepad temp.dir" ' display temp file contents in Notepad window '' ''
{{CodeEnd}}
:Contents of ''temp.dir'' text file:
{{OutputStart}}
Free Cell.ico
{{OutputEnd}}


''Example 2:'' Opening a Windows program (Notepad) to read or print a Basic created text file.
{{CodeStart}}
{{Cl|INPUT}} "Enter a file name to read in Notepad: ", filename$
{{Cl|SHELL}} "CMD /C start /max notepad " + filename$  ' display in Notepad full screen in XP or NT   

'{{Cl|SHELL}} "start /min notepad /p " + filename$ ' taskbar print using QB64 CMD /C not necessary
{{CodeEnd}}

:''Explanation:'' Notepad is an easy program to open in Windows as no path is needed. Windows NT computers, including XP, use CMD /C where older versions of DOS don't require any command reference. The top command opens Notepad in a normal window for a user to view the file. They can use Notepad to print it. The second command places Notepad file in the taskbar and prints it automatically. The filename variable is added by the program using proper spacing. 

::*'''Start''' is used to allow a Basic program to run without waiting for Notepad to be closed.
::* '''/min''' places the window into the taskbar. '''/max''' is fullscreen and no option is a normal window.
::* Notepad's '''/p''' option prints the file contents, even with USB printers.



''Example 3:'' Function that returns the program's current working path.
{{CodeStart}}
 currentpath$ = Path$ ' function call saves a path for later program use
 {{Cl|PRINT}} currentpath$

 {{Cl|FUNCTION}} Path$   
   {{Cl|SHELL}} {{Cl|_HIDE}} "CD > D0S-DATA.INF"  'code to hide window in '''QB64'''
   {{Cl|OPEN}} "D0S-DATA.INF" {{Cl|FOR (file statement)|FOR}} {{Cl|APPEND}} {{Cl|AS}} #1  'this may create the file
        L% = {{Cl|LOF}}(1)          'verify that file and data exist
   {{Cl|CLOSE}} #1   
   {{Cl|IF}} L% {{Cl|THEN}}                       'read file if it has data
     {{Cl|OPEN}} "DOS-DATA.INF" {{Cl|FOR (file statement)|FOR}} {{Cl|INPUT (file mode)|INPUT}} {{Cl|AS}} #1
     {{Cl|LINE INPUT (file statement)|LINE INPUT}} #1, line$           'read only line in file
     Path$ = line$ + "\"            'add slash to path so only a filename needs added later
     {{Cl|CLOSE}} #1
   {{Cl|ELSE}} : Path = ""                 'returns zero length string if path not found
   {{Cl|END IF}}
   {{Cl|KILL}} "D0S-DATA.INF"              'deleting the file is optional
 {{Cl|END FUNCTION}} '' ''
{{CodeEnd}}
{{small|Code by Ted Weissgerber}}
:''Explanation:'' The '''SHELL "CD"''' statement requests the current working path. This info is normally printed to the screen, but the '''>''' pipe character sends the information to the DOS-DATA.INF file instead('''QB64''' can use [[_HIDE]] to not display the DOS window). The function uses the [[OPEN]] FOR [[APPEND]] mode to check for the file and the data([[INPUT (file mode)|INPUT]] would create an error if file does not exist). The current path is listed on one line of the file. The file is opened and [[LINE INPUT (file statement)|LINE INPUT]] returns one line of the file text. The function adds a "\" so that the Path$ returned can be used in another file statement by just adding a file name. Save the Path$ to another variable for later use when the program has moved to another directory.
: In '''QB64''' you can simply use the [[_CWD$]] statement for the same purpose of the example above.


''Example 4:'' Determining if a drive or path exists. Cannot use with a file name specification.
{{CodeStart}} '' ''
{{Cl|LINE INPUT}} "Enter a drive or path (no file name): ", DirPath$
{{Cl|IF}} PathExist%(DirPath$) {{Cl|THEN}} {{Cl|PRINT}} "Drive Path exists!" {{Cl|ELSE}} PRINT "Drive Path does not exist!"
{{Cl|END}}

{{Cl|FUNCTION}} PathExist% (Path$)
PathExist% = 0
{{Cl|IF}} {{Cl|LEN}}(Path$) = 0 {{Cl|THEN}} {{Cl|EXIT FUNCTION}} 'no entry
{{Cl|IF}} {{Cl|LEN}}({{Cl|ENVIRON$}}("OS")) {{Cl|THEN}} CMD$ = "CMD /C " {{Cl|ELSE}} CMD$ = "COMMAND /C "
{{Cl|SHELL}} {{Cl|_HIDE}} CMD$ + "If Exist " + Path$ + "\nul echo yes > D0S-DATA.INF"
{{Cl|OPEN}} "D0S-DATA.INF" {{Cl|FOR (file statement)|FOR}} {{Cl|APPEND}} {{Cl|AS}} #1
{{Cl|IF}} {{Cl|LOF}}(1) {{Cl|THEN}} PathExist% = -1       'yes will be in file if path exists
{{Cl|CLOSE}} #1
{{Cl|KILL}} "D0S-DATA.INF"                  'delete data file optional
{{Cl|END FUNCTION}} '' ''
{{CodeEnd}}
{{small|Code by Ted Weissgerber}}
:''Explanation: IF Exist'' checks for the drive path. ''\Nul'' allows an empty folder at end of path. ''Echo'' prints '''yes''' in the file if it exists.
: In '''QB64''' you can simply use the [[_FILEEXISTS]] statement for the same purpose of the example above.


''Snippet 1:'' When looking for '''printers''' this command gives you a file list with the default printer marked as '''TRUE''':
{{CodeStart}}
{{Cl|SHELL}} {{Cl|_HIDE}} "CMD /C" + "wmic printer get name,default > default.txt"
{{CodeEnd}}
: Created file's text:
{{OutputStart}}Default  Name                           
  FALSE    Microsoft XPS Document Writer 
  TRUE     HP Photosmart C7200 series     
  FALSE    HP Officejet Pro 8600         
  FALSE    Fax
{{OutputEnd}}
: ''Explanation:'' [[LINE INPUT]] could be used to find the printer names as [[STRING]] variables.


''Snippet 2:'' Here is the code to set the default printer to the "HP Officejet Pro 8600":
{{CodeStart}}
{{Cl|SHELL}} {{Cl|_HIDE}} "CMD /C" + "wmic printer where name='HP Officejet Pro 8600' call setdefaultprinter"
{{CodeEnd}}
: After executing this program, and then running the first snippet again, we see the following contents of the text file:
{{OutputStart}}Default  Name 
  FALSE    Microsoft XPS Document Writer 
  FALSE    HP Photosmart C7200 series     
  TRUE     HP Officejet Pro 8600         
  FALSE    Fax
{{OutputEnd}}


===More examples===
''See examples in:''
* [[FILELIST$ (function)]] (member-contributed file search routine)
* ''File Exist'' C++ Function that does not create a temp file: [[Windows_Libraries#File_Exist|FileExist Library Function]]


{{PageSeeAlso}}
* [[SHELL (function)]], [[_SHELLHIDE]]
* [[FILES]], [[CHDIR]], [[MKDIR]]
* [[_CWD$]], [[_STARTDIR$]]
* [[_FILEEXISTS]], [[_DIREXISTS]]
* [[RMDIR]], [[NAME]], [[KILL]], [[RUN]]
* [[_HIDE]], [[_DONTWAIT]]
* [[_CONSOLE]], [[$CONSOLE]]
* [[$SCREENHIDE]], [[$SCREENSHOW]] {{text|(QB64 [[Metacommand]]s)}}
* [[_SCREENHIDE]], [[_SCREENSHOW]]
* [[FILELIST$]], [[PDS_(7.1)_Procedures#DIR.24|DIR$]] {{text|(member-contributed file list array function)}}


===Extra reference===
* [[Windows_Libraries#File_Dialog_Boxes|Windows Open and Save Dialog Boxes]]
* [[C_Libraries#Console_Window|C Console Library]]
* [[Windows Printer Settings]]


{{PageNavigation}}
