%U_CMDLINOPT

Search for a command line option

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
status=%U_CMDLINOPT(option, [max], [args][, argcount])

Return value

status

True if the option is found; false if not. (^VAL)

Arguments

option

Command line option to search for. (a)

max

(optional) Maximum number of arguments to return for the option. (n)

args

(optional) Array for returned arguments. (a)

argcount

(optional) Number of returned arguments. (n)

Discussion

%U_CMDLINOPT searches the command line for the command line option specified by option. A command line option is defined as a dash (‑) or a slash (/) (if you’ve set DBLOPT 34) followed immediately by a string that identifies the option. The string can be up to 80 characters. If the option has arguments, they follow the option with separating spaces.

%U_CMDLINOPT parses the entire command line. If the option occurs multiple times, the argument sets are concatenated. Unless the last character in option is a space, %U_CMDLINOPT selects each option that starts with the characters specified by option, even if an option has more characters than option specifies. For example, if you specify “n” for option, %U_CMDLINOPT will select ‑number. However, if you specify “n ” (note the space), %U_CMDLINOPT selects only ‑n or /n, not ‑number or /number.

If max is passed, it specifies the maximum number of arguments that may be returned for this option. If max is greater than 0, args is presumed to be the base of an array with max or greater elements that contains the returned arguments. If argcount is passed, it is returned with the actual number of arguments found for the option, even if that number is greater than max. (Note, however, that only max arguments will be returned in args.)

For example, to retrieve the first two options (opt1 and opt2) from the command line

dbr myprogram -a "opt1" "opt2" "opt3"

your program could have the following:

status = %U_CMDLINOPT("a", 2, options_array, count)

Switches that precede the program name on the command line are ignored. For example, %U_CMDLINOPT will always return false for the following command:

dbr -n program_name

It may return true, however, for the following:

dbr program_name -n

Examples

The following example looks for an option with ‑r (or /r if DBLOPT 34 is set):

if (%u_cmdlinopt("r"))

Note that ‑rec would qualify because it starts with ‑r. To search for a command line option that contains only ‑r or /r, specify the following:

if (%u_cmdlinopt("r "))

Note the space after the r in the above example; this prevents anything other than ‑r (‑rec for example) from qualifying.

In the next example, %U_CMDLINOPT looks for ‑names or /names. Note that it will retrieve only 10 arguments and that the address of the returned arguments will be assigned to nmnames.

if (%u_cmdlinopt("names ", 10, names, nmnames))