Return the command line that started your program
|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall CMDLN(command, [num_args], [arg_pos][, arg_len])
Arguments
command
The variable that will be loaded with the command line. (a)
num_args
(optional) A variable that will be loaded with the number of arguments in command. (n)
arg_pos
(optional) An array that will be loaded with the beginning position of each argument. (n)
arg_len
(optional) An array that will be loaded with the length of each argument. (n)
Discussion
The CMDLN subroutine returns the command line that started your Synergy program. Command is loaded left-justified over blanks.
On Windows and Unix, command includes the system command that starts the runtime (dbr). The command includes the full path name of the Synergy runtime. CMDLN does not return the quotation marks in the command line.
On Windows, do not specify a trailing backslash character (\) as part of the directory path. The Windows command line parser treats the trailing backslash as an escape character, which may cause it to interpret the character that follows the backslash incorrectly. For example, use
dbr genxml -f test.xml -s "c:\Documents\smc"
rather than
dbr genxml -f test.xml -s "c:\Documents\smc\"
On OpenVMS, the command line is returned in uppercase characters and does not include the full path name of the Synergy runtime or the program name. To use CMDLN on OpenVMS, you need to either set up a symbol as a foreign command to invoke the program or include the location of the program in the DCL$PATH search list. For example, if we set up a foreign symbol as follows for a program called MAIN (where $PATH was previously set as an environment variable pointing to the directory that contains MAIN.EXE):
prog:==$PATH:MAIN
we could use the CMDLN subroutine in this program as follows:
main MAIN
.define TTCHN ,1
record
buffer ,a80
proc
open(TTCHN, o, "tt:")
xcall cmdln(buffer)
writes(TTCHN, "Buffer = "+buffer)
endmain
If we then ran this program with the following command line arguments:
prog arg1 arg2 arg3
the output would be as follows:
Buffer = arg1 arg2 arg3
However, if we ran the program MAIN without arguments, or if we ran it without a foreign symbol command, the output would be as follows:
Buffer =
If num_args is passed, it is returned with the number of arguments contained in command. On Windows and Unix, this includes the path of dbr as the first argument and the program filename as the second argument. Arguments are divided according to the rules for each specific platform. For instance, on Windows the first argument is the entire path of dbr.exe, even if it includes spaces. On OpenVMS, the arguments are divided at each occurrence of any number of spaces, commas, or tabs that are not enclosed in matching quotation marks.
If arg_pos is passed, the beginning position of each argument in command is returned in each successive element of arg_pos. To retrieve more than the first position, arg_pos must be a real array (that is, declared using [ ] for the dimensions). If the number of elements passed is less than the number of arguments encountered, only the number of elements passed are returned. If more than num_args elements are passed, the remaining elements are filled with zeros. Positions are returned base-1 (in other words, 1 indicates the first character of command).
If arg_len is passed, the length of each argument (not including any delimiters) is returned in each successive element of arg_len. To retrieve more than the first length, arg_len must be a real array (that is, declared using [ ] for the dimensions). If the number of elements passed is less than the number of arguments encountered, only the number of elements passed is returned. If more than num_args elements are passed, the remaining elements are filled with zeros.
Note that the number of elements in arg_pos and arg_len do not have to match, and the rules stated above are applied independently to each. Note also that num_args is always returned with the true number of arguments, even if neither array contains enough elements to receive the information about all of them.
Examples
The following example checks the number of arguments in the command line that starts your program and displays an error if that number is incorrect. If the number of arguments is correct, the main routine calls the do_it routine with each argument that was passed on the command line. In the process_cmdlin function, the argpos and arglen arrays are filled with the starting position and length of each argument by the CMDLN routine. The argument array, a_argary, is then filled with each of the arguments that were found on the command line. You might use this routine to identify the start and length of a filename specification on the command line (for example, on Windows, where a filename specification can contain a space), which enables your program to easily recognize the entire specification as a single argument.
main
.define MAX_ARGS 3
.align
record
argcnt ,i4
cnt ,i4
args ,[MAX_ARGS]a255
external function
process_cmdlin ,^val
proc
xcall flags(1001010, 1)
open(1, o, "TT:")
argcnt = %process_cmdlin(args, MAX_ARGS)
if ((argcnt .lt. 1) .or. (argcnt .gt. MAX_ARGS))
goto usage
for cnt from 1 thru argcnt
xcall do_it(args[cnt])
done,
close 1
stop
usage,
writes(1, "Wrong number of arguments")
writes(1, "Number of arguments must be between 1 and " +
& %string(MAX_ARGS))
goto done
endmain
function process_cmdlin ,^val
a_argary ,[*]a
a_maxargs ,n
record
argcnt ,i4
cnt ,i4
start ,i4
argpos ,[10]i4
arglen ,[10]i4
cmdlin ,a255
proc
xcall cmdln(cmdlin, argcnt, argpos, arglen)
.ifdef OS_VMS
cnt = 1
.else
.ifdef DEBUG
cnt = 4
.else
cnt = 3
.endc
.endc
start = cnt - 1
do
begin
a_argary[cnt - start] = cmdlin(argpos[cnt]:arglen[cnt])
incr cnt
end
until((cnt .gt. argcnt) .or. ((cnt - start) .gt. a_maxargs))
freturn (argcnt - start)
endfunction
