QB64-PE/internal/help/COMMAND$.txt

The '''COMMAND$''' [[STRING]] function returns the spaced [[DOS]] command line argument(s) passed when a program is run.



{{PageSyntax}} 
::: option$ = [[COMMAND$]][(count%)]


* Useful when the programmer wants to send specific program options to the command line for later use by the called program.
* The [[STRING]] return value is any '''spaced quoted or unquoted''' parameter(s) following the filename in a [[RUN]] or command line statement.
* '''QB64''' does not '''require or return all [[UCASE$|uppercase]]''' values so keep that fact in mind when checking parameters passed!
* In '''QB64 only''', COMMAND$ can work as an array to return specific elements passed to the command line. COMMAND$(2) would return the '''spaced''' second parameter passed at the command line.  This can be used on modern operating systems to successfully retrieve file names and arguments which contain spaces properly. (versions after May 20, 2015) 
* Use the [[_COMMANDCOUNT]] function to find the number of spaced parameters passed to a program via the command line. (versions after May 20, 2015) '''{{text|See ''Example 2''|green}}'''.
* Reading the spaced command options in the '''COMMAND$(i)''' array in a loop can also be done and reading a COMMAND$ without parameters is also possible. (versions after May 20, 2015) '''{{text|See ''Example 3''|green}}'''.
* COMMAND$ was '''not available in QuickBasic versions below 4.0''' and returned [[UCASE$|uppercase]] [[STRING]] parameters no matter what case they were sent originally. 


''Example 1:'' Compile both programs. ProgramA [[RUN]]s ProgramB with a parameter passed following the filename: 
{{CodeStart}}
{{Cl|LOCATE}} 12, 36: {{Cl|PRINT}} "ProgramA"

{{Cl|LOCATE}} 23, 25: {{Cl|PRINT}} "Press any key to run ProgramB"
K$ = {{Cl|INPUT$}}(1)
{{Cl|RUN}} "ProgramB FS"  'pass FS parameter to ProgramB in QB64 or QB4.5

{{Cl|SYSTEM}}
{{CodeEnd}}
: ''ProgramB'' checks for fullscreen parameter pass in QB64 and goes full screen. 
{{CodeStart}} '' ''
{{Cl|LOCATE}} 17, 36: {{Cl|PRINT}} "ProgramB"
parameter$ = {{Cl|UCASE$}}({{Cl|COMMAND$}}) 'QB64 only as QB4.5 will always return upper case
{{Cl|LOCATE}} 20, 33: {{Cl|PRINT}} "Parameter = " + parameter$
{{Cl|IF...THEN|IF}} {{Cl|LEFT$}}(parameter$, 2) = "FS" {{Cl|THEN}} {{Cl|_FULLSCREEN}} 'parameter changes to full screen

{{Cl|END}} '' ''
{{CodeEnd}}
{{OutputStart}}
                                    ProgramB



                                 Parameter = FS.EXE
{{OutputEnd}}


''Example 2:'' Program gets the number of parameters passed to the program, and then prints those parameters to the screen one at a time. 
{{CodeStart}}count = {{Cl|_COMMANDCOUNT}}
{{Cl|FOR...NEXT|FOR}} c = 1 {{Cl|TO}} count
    {{Cl|PRINT}} {{Cl|COMMAND$}}(c) 'or process commands sent
{{Cl|NEXT}}
{{CodeEnd}}
{{OutputStart}}-1
a data file
{{OutputEnd}}
: ''Explanation: If we start ''ThisProgram.exe'' with the command line '''ThisProgram -l "a data file"''', COMMAND$ will return a single string of "-1 a data file" which might be hard to process and interpret properly, but COMMAND$(1) would return "-l" and COMMAND$(2) would return the quoted "a data file" option as separate entries for easier parsing and processing.


''Example 3:'' As part of the command array upgrade, you can also just read the array to see how many commands were sent: 
{{CodeStart}}DO
    count = count + 1
    cmd$ = {{Cl|COMMAND$}}(count)
    {{Cl|IF...THEN|IF}} cmd$ = "" {{Cl|THEN}} {{Cl|EXIT DO}} 'read until an empty return
    {{Cl|PRINT}} cmd$ 'or process commands sent
{{Cl|LOOP}} '' ''
count = count - 1 'save the number of parameters sent to this program when run
{{CodeEnd}}
:'''Note:''' When using this command [[DO]] loop read procedure, the spaced commands sent must not be empty strings as the count will end!


''See also:'' 
* [[SHELL]], [[RUN]]
* [[UCASE$]], [[LCASE$]]
* [[_COMMANDCOUNT]]


{{PageNavigation}}