Specifying Command-Line Arguments

You can pass an almost unlimited number of command-line arguments to SQR at runtime. On some platforms, the operating system imposes a limit on the number of arguments or the total size of the command line. Passing arguments is especially useful in automated reports, such as those that are invoked by scripts or menu-driven applications.

You can pass arguments to SQR on the command line, in files, or with the SQRFLAGS environment variable. When you pass arguments in a file, reference the file name on the command line and put one argument on each line of the file. This avoids any limits that are imposed by the operating system.

To reference a file on the command line, precede its name with the @ sign as shown in the following code example:

sqr myreport sammy/baker arg1 arg2 @file.dat

In this example, arg1 and arg2 are passed to SQR, followed by the file.dat file. Each line in file.dat has an additional argument.

When the ASK and INPUT commands run, SQR determines whether you entered any arguments in the command line or whether an argument file was opened. If either has happened, SQR uses this input instead of prompting the user. After the available arguments are used, subsequent ASK or INPUT commands prompt the user for input. If you use the INPUT command with the BATCH-MODE argument, SQR does not prompt the user but instead returns a status meaning No more arguments.

SQR processes all ASK commands before INPUT commands.

You can mix argument files with simple arguments, as shown in the following code example:

sqr rep2 sammy/baker 18 @argfile1.dat "OH" @argfile2.dat "New York"

This command line passes SQR the number 18, the contents of argfile1.dat, the value OH, the contents of argfile2.dat, and the value New York, in that order.

The OH argument is in quotes to ensure that SQR uses uppercase OH. When a command-line argument is case-sensitive or contains spaces, you must enclose it within quotes. Arguments that are stored in files do not require quotes and cannot contain them; the actual strings with uppercase characters and any spaces are passed to SQR.

To print the same report on different printers with different characteristics, you can save values for the different page sizes, printer initializations, and fonts in separate files and use a command-line argument to specify which file to use. For example, the following command line code example passes the value 18 to SQR:

sqr myreport sammy/baker 18

An #INCLUDE command in the report file selects the printer18.dat file based on the command-line argument:

begin-setup
  ask num      ! Printer number.
  #include 'printer{num}.dat'  ! Contains #DEFINE commands for 
               ! printer and paper width and length
  declare-layout report
        paper-size =({paper_width} {paper_length})
  end-declare
end-setup

In this example, the ASK command assigns the value 18 to the num variable; 18 is a compile-time argument. The #INCLUDE command then uses the value of num to include the printer18.dat file, which could include commands like this:

! Printer18.dat-definitions for printer in Bldg 4.
#define paper_length 11
#define paper_width 8.5
#define bold_font LS12755
#define light_font LS13377
#define init HM^J73011

SQR examines an argument file for a program name, username, or password if none is provided in the command line. The following command line omits the program name, username, and password:

sqr @argfile.dat

The first two lines of the argument file for this code example contain the program name and the username and password:

myreport
sammy/baker
18
OH
...

If you do not want to specify the report name, username, or password in the command line or in an argument file, use the question mark (?). SQR prompts the user to supply these. For example:

sqr myreport ? @argfile.dat

In this example, the program prompts the user for the username and password instead of taking them from the first line in the argument file.

You can use more than one question mark on the command line, as shown in the following code example:

sqr ? ? @argfile.dat

In this example, the program prompts the user for the program name and the username and password.

The hyphen (-) and @ sign characters have special meanings in a command line. The hyphen precedes an SQR flag, and the @ sign precedes an argument file name. To use either of these characters as the first character of a command-line argument, enter the character twice to indicate that it is a literal hyphen or @ sign, as shown in the following code example:

sqr myreport ? --17 @argfile.dat @@X2H44

In this example, the double hyphen and double @ sign are interpreted as single literal characters.

You can create an argument file for one program from the output of another program. For example, you can print a list of account numbers to the acctlist.dat file, and then run a second report with the following command:

sqr myreport sammy/baker @acctlist.dat

End acctlist.dat with a flag such as END, as shown in the following code example:

123344
134455
156664
 ...
END

An SQR program can use the numbers in acctlist.dat with an INPUT command, as shown in the following code example:

begin-procedure get_company
next:
input $account            batch-mode status = #status
  if #status = 3
      goto end_proc
  end-if
begin-select
cust_num, co_name, contact, addr, city, state, zip
  do print-page               ! Print page with
               ! complete company data
from customers
where cust_num = $account
end-select
goto next               ! Get next account number
end_proc:
end-procedure !get_company