CMDLN

Return the command line that started your program

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, 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 you must enter

prog:==$DIR:prog

define DCL$PATH DBLDIR,UTILS,DIR

to make the following command line work with the CMDLN subroutine:

prog arg1 arg2

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