Using the SQR Command Line

This chapter provides an overview of the SQR command line and discusses how to:

• Specify command-line arguments.

• Use batch mode.

Understanding the SQR Command Line

You can use the SQR command line to specify flags and to pass arguments to modify your program at runtime.

You can enter command-line flags such as -Bnn, -KEEP, or -S on the command line to modify some aspect of program processing or output. Command-line arguments are typically answers to requests (done in the SQR program by ASK or INPUT commands) for user input.

The following code example and table describes the syntax of the SQR command line:

SQR [program] [connectivity] [flags ...] [args ...] ​[@file ...]

Specifying Command-Line Arguments

This section provides an overview of command-line arguments and discusses how to:

• Retrieve the arguments.

• Specify arguments and argument files.

• Use an argument file.

• Use other approaches to pass command-line arguments.

• Use reserved characters.

• Create an argument file from a report.

Understanding 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.

Retrieving the Arguments

When the ASK and INPUT commands run, SQR determines whether you entered any arguments on the command line or whether an argument file has been 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.

Note. If you compiled the SQR program into an .SQT file, ASK commands will have already been processed. Use INPUT instead.

Specifying Arguments and Argument Files

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.

Using an Argument File

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

Using Other Approaches to Pass Command-Line Arguments

SQR examines an argument file for a program name, username, or password if none is provided on 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 on 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.

Note. SQR for Microsoft Windows does not accept the SQR program name and database connectivity to be part of the argument file.

Using Reserved Characters

The hyphen (-) and @ sign characters have special meanings on the 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.

Creating an Argument File from a Report

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, 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

Using Batch Mode

SQR enables you to run reports in batch mode in:

• UNIX/Linux.

• Microsoft Windows.

You can create UNIX/Linux shell scripts or MS-DOS batch (.bat) files to run SQR. Include the SQR command line in the file as you enter it.