Skip to Main Content
Return to Navigation

SQR Commands

The following sections discuss the SQR commands in alphabetical order.

ADD

Syntax

ADD{src_num_lit | _var |  _col} TO dst_num_var  [ROUND=nn]

Description

Adds one number to another.

The source value is added to the destination variable and the result is placed in the destination. The source is always first and the destination is always second.

When dealing with money-related values, use decimal variables rather than float variables . Float variables are stored as double-precision floating point numbers , and small inaccuracies can occur when a program is adding many numbers in succession. These inaccuracies can appear due to the way floating point numbers are represented by different hardware and software implementations and also due to inaccuracies that can be introduced when a program is converting between floating point and decimal.

Parameters

Parameter

Description

src_num_lit | _var | _col

Source number literal, variable, or column.

dst_num_var

A numeric destination variable that contains the result after execution.

ROUND

Rounds the result to the specified number of digits to the right of the decimal point. For float variables, this value can be from 0 to 15. For decimal variables, this value can be from 0 to the precision of the variable. For integer variables, this argument is not appropriate.

Example

To add 10 to #counter:

add  #counter  to  #new_count
add  &price  to  #total  round=2

See LET Command

ALTER-COLOR-MAP

Syntax

ALTER-COLOR-MAP       NAME = {color_name_lit | _var | _col} VALUE =
({color_name_lit | _var | _col} | {rgb})

Description

Dynamically alters a defined color.

The ALTER-COLOR-MAP command is allowed wherever the PRINT command is allowed. This command enables you to dynamically alter a defined color. You cannot use this command to define a new color.

Parameters

Parameter

Description

NAME

Defines the name of the color that you want to alter. For example, light blue.

VALUE

Defines the RGB value of the color that you want to alter, for example, (193, 233, 230).

{color_name_lit | _var | _col}

The color_name is composed of alphanumeric characters (A–Z, 0–9), the underscore (_) character, and the hyphen (-) character. It must start with an alpha (A–Z) character and is not case-sensitive. The name 'none' is reserved and cannot be assigned a value. A name in the format (RGBredgreenblue) cannot be assigned a value. The name 'default' is reserved and can be assigned a value. 'Default' is used during execution when a referenced color is not defined in the runtime environment.

{rgb}

red_lit | _var | _col, green_lit | _var | _col, blue_lit | _var | _col where each component is a value in the range of 000 to 255. In the BEGIN-SETUP section, only literal values are allowed.

The default colors implicitly installed with SQR include:

  • black=(0,0,0)

  • white=(255,255,255)

  • gray=(128,128,128)

  • silver=(192,192,192)

  • red=(255,0,0)

  • green=(0,255,0)

  • blue=(0,0,255)

  • yellow=(255,255,0)

  • purple=(128,0,128)

  • olive=(128,128,0)

  • navy=(0,0,128)

  • aqua=(0,255,255)

  • lime=(0,128,0)

  • maroon=(128,0,0)

  • teal=(0,128,128)

  • fuchsia=(255,0,255)

Example

The following example illustrates the ALTER-COLOR-MAP command:

begin-setup
   declare-color-map
   light_blue = (193, 222, 229)
   end-declare
end-setup

begin-program
   alter-color-map name = 'light_blue' value = (193, 233, 230)

   print 'Yellow Submarine' ()
      foreground = ('yellow')
      background = ('light_blue')

   get-color print-text-foreground = ($print-foreground)  
   set-color print-text-foreground = ('purple')
   print 'Barney' (+1,1)
   set-color print-text-foreground = ($print-foreground)
end-program

See DECLARE-COLOR-MAP SET-COLOR,GET-COLOR

ALTER-LOCALE

Syntax

ALTER-LOCALE [LOCALE={txt_lit _var|DEFAULT|SYSTEM}] [NUMBER-EDIT-MASK={txt_lit|_var|DEFAULT|SYSTEM}] [MONEY-EDIT-MASK={txt_lit|_var|DEFAULT|SYSTEM}] [DATE-EDIT-MASK={txt_lit|_var|DEFAULT|SYSTEM}] [INPUT-DATE-EDIT-MASK={txt_lit|_var|DEFAULT|SYSTEM}]
[MONEY-SIGN={txt_lit|_var|DEFAULT|SYSTEM}] [MONEY-SIGN-LOCATION={txt_var|DEFAULT|SYSTEM|LEFT |RIGHT}] [THOUSAND-SEPARATOR={txt_lit|_var|DEFAULT|SYSTEM}] [DECIMAL-SEPARATOR={txt_lit|_var|DEFAULT|SYSTEM}] [DATE-SEPARATOR={txt_lit|_var|DEFAULT|SYSTEM}] [TIME-SEPARATOR={txt_lit|_var|DEFAULT|SYSTEM}] [EDIT-OPTION-NA={txt_lit|_var|DEFAULT|SYSTEM}] [EDIT-OPTION-AM={txt_lit|_var|DEFAULT|SYSTEM}] [EDIT-OPTION-PM={txt_lit|_var|DEFAULT|SYSTEM}] [EDIT-OPTION-BC={txt_lit|_var|DEFAULT|SYSTEM}] [EDIT-OPTION-AD={txt_lit|_var|DEFAULT|SYSTEM}] [DAY-OF-WEEK-CASE={txt_var|DEFAULT|SYSTEM|UPPER|LOWER |EDIT|NO-CHANGE}] [DAY-OF-WEEK-FULL=({txt_lit1|_var1}...{txt_lit7 |_var7})] [DAY-OF-WEEK-SHORT=({txt_lit1|_var1}...{txt_lit7 |_var7})] [MONTHS-CASE={txt_var|DEFAULT|SYSTEM|UPPER|LOWER|EDIT |NO-CHANGE}] [MONTHS-FULL=({txt_lit1|_var1}...{txt_lit12| _var12})] [MONTHS-SHORT=({txt_lit1|_var1}...{txt_lit12|_var12})]

Description

Selects a locale or changes locale parameters used for printing date, numeric, and money data and for data accepted by the INPUT command. A locale is a set of preferences for language, currency, and presentation of charts and numbers.

The SYSTEM locale represents the behavior of older versions of SQR prior to Version 4.0. When you install SQR for PeopleSoft Version 4.0 or later, the default locale is set to SYSTEM. This provides upwards compatibility for older SQR programs. This table describes the SYSTEM locale settings:

Keyword

Value

NUMBER-EDIT-MASK

The PRINT command prints two digits to the right of the decimal point and left-justifies the number in the field. The MOVE, SHOW, and DISPLAY commands format the number with six digits to the right of the decimal point and left-justify the number.

MONEY-EDIT-MASK

SQR uses the same default as the NUMBER-EDIT-MASK keyword.

DATE-EDIT-MASK

SQR uses the default database date format. See the Date Time section for more details.

INPUT-DATE-EDIT-MASK

SQR uses a default date edit mask with the INPUT command. See the Sample Date Edit Masks table for a listing of the date edit mask.

MONEY-SIGN

'$'

MONEY-SIGN-LOCATION

LEFT

THOUSAND-SEPARATOR

','

DECIMAL-SEPARATOR

'.'

DATE-SEPARATOR

'/'

TIME-SEPARATOR

':'

EDIT-OPTION-NA

'NA'

EDIT-OPTION-AM

'am'

EDIT-OPTION-PM

'pm'

EDIT-OPTION-BC

'bc'

EDIT-OPTION-AD

'ad'

DAY-OF-WEEK-CASE

EDIT

DAY-OF-WEEK-FULL

('Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday')

DAY-OF-WEEK-SHORT

('Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat')

MONTHS-CASE

EDIT

MONTHS-FULL

('January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December')

MONTHS-SHORT

('Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec')

Parameters

The following table lists and describes the parameters:

Note: Many of the settings can have a value of DEFAULT or SYSTEM . For a given setting, specifying DEFAULT retrieves the value from the corresponding setting of the default locale as identified in the Default-Settings section of the pssqr.ini file. Similarly, specifying SYSTEM retrieves the value from the corresponding setting of the system locale. You can alter the system locale using the ALTER-LOCALE command; however, you cannot define it in the pssqr.ini file.

Parameter

Description

LOCALE

Specifies the name of the locale to use. This name must be defined in the pssqr.ini file. If this field is omitted, then the current locale is used. The locale name is not case-sensitive and is limited to the following character set: A–Z, 0–9, underscore, and hyphen. The current locale can be determined by printing the reserved variable $sqr-locale.

NUMBER-EDIT-MASK

Specifies the numeric edit mask to use with the keyword NUMBER in a PRINT, MOVE, SHOW, or DISPLAY command.

MONEY-EDIT-MASK

Specifies the numeric edit mask to use with the keyword MONEY in a PRINT, MOVE, SHOW, or DISPLAY command.

DATE-EDIT-MASK

The default date edit mask to use with the keyword DATE in the PRINT, MOVE, SHOW, or DISPLAY command, or the LET function datetostr() or strtodate().

INPUT-DATE-EDIT-MASK

The default date format to use with the INPUT command when TYPE=DATE is specified with the command or the input variable is a date variable. For information about edit masks, see PRINT.

MONEY-SIGN

Specifies the characters that replace the $ or other currency symbol used in edit masks.

MONEY-SIGN-LOCATION

Specifies where to place the MONEY-SIGN characters. Valid values are LEFT and RIGHT.

THOUSAND-SEPARATOR

Specifies the character to replace the ',' edit character.

DECIMAL-SEPARATOR

Specifies the character to replace the '.' edit character.

DATE-SEPARATOR

Specifies the character to replace the '/' character.

TIME-SEPARATOR

Specifies the character to replace the ':' character.

EDIT-OPTION-NA

Specifies the characters to use with the 'na' option.

EDIT-OPTION-AM

Specifies the characters to replace 'AM'.

EDIT-OPTION-PM

Specifies the characters to replace 'PM'.

EDIT-OPTION-BC

Specifies the characters to replace 'BC'.

EDIT-OPTION-AD

Specifies the characters to replace 'AD'.

DAY-OF-WEEK-CASE

Specifies how the case for the DAY-OF-WEEK-FULL or DAY-OF-WEEK-SHORT entries is affected when used with the format codes 'DAY' or 'DY'. Valid values are UPPER, LOWER, EDIT, and NO-CHANGE. UPPER and LOWER force the output to either all uppercase or lowercase, ignoring the case of the format code in the edit mask. Use EDIT to follow the case specified with the format code in the edit mask. Use NO-CHANGE to ignore the case of the format code and output the day of week explicitly listed in the DAY-OF-WEEK-FULL or DAY-OF-WEEK-SHORT entries.

DAY-OF-WEEK-FULL

Specifies the full names for the days of the week. SQR considers the first day of the week to be Sunday. You must specify all seven days.

DAY-OF-WEEK-SHORT

Specifies the abbreviated names for the days of the week. SQR considers the first day of the week to be Sunday. You must specify all seven abbreviations.

MONTHS-CASE

Specifies how the case for the MONTHS-FULL or MONTHS-SHORT entries is affected when used with the format code 'MONTH' or 'MON'. Valid values are UPPER, LOWER, EDIT, and NO-CHANGE. UPPER and LOWER force the output to either all uppercase or lowercase, ignoring the case of the format code in the edit mask. Use EDIT to follow the case specified with the format code in the edit mask. Use NO-CHANGE to ignore the case of the format code and format the month explicitly listed in the MONTHS-FULL or MONTHS-SHORT entries.

MONTHS-FULL

Specifies the full names for the months of the year. SQR for PeopleSoft considers the first month of the year to be January. You must specify all 12 months.

MONTHS-SHORT

Specifies the abbreviated names for the months of the year. SQR for PeopleSoft considers the first month of the year to be January. You must specify all 12 abbreviations.

Example

The following example illustrates the ALTER-LOCALE command:

!
! The following program segments will illustrate the various
! ALTER-LOCALE features.
!
begin-setup
 declare-variable
  date $date $date1 $date2 $date3
 end-declare
end-setup

 !
 ! Set default masks
 !
 alter-locale
  number-edit-mask = '9,999,999.99'
  money-edit-mask  = '$999,999,999.99'
  date-edit-mask   = 'Mon DD, YYYY'
 
 let #value = 123456
 let $edit = 'Mon DD YYYY HH:MI:SS'
 let $date = strtodate('Jan 01 2004 11:22:33', $edit)
 show 'With NUMBER option    #Value = ' #value number
 show 'With MONEY  option    #Value = ' #value money
 show 'Without NUMBER option #Value = ' #value
 show 'With DATE option      $Date  = ' $date date
 show 'Without DATE option   $Date  = ' $date 

Produces the following output:

With NUMBER option    #Value =   123,456.00
With MONEY  option    #Value = $    123,456.00
Without NUMBER option #Value = 123456.000000
With DATE option      $Date  = Jan 01, 2004
Without DATE option   $Date  = 01-JAN-04

 !
 ! Reset locale to SQR defaults and assign a multi-character
 ! money-sign.
 !
 alter-Locale
  locale = 'System'
  money-sign = 'AU$'                ! Australian dollars
 
 let #value = 123456
 show #value edit '$999,999,999,999.99'
 show #value edit '$$$$,$$$$999,999.99'

Produces the following output:

AU$      123,456.00
      AU$123,456.00

 !
 ! Move the money-sign to the right side of the value.  Note
 ! the leading space.
 !
 alter-locale
  money-sign = ' AU$'               ! Australian dollars
  money-sign-location = right

 let #value = 123456
 show #value edit '$999,999,999,999.99'
 show #value edit '$$$$,$$$$999,999.99'

Produces the following output:

        123,456.00 AU$
        123,456.00 AU$

 !
 ! Reset locale to SQR defaults and flip the thousand and
 ! decimal separator characters.
 !
 alter-locale
  locale = 'System'
  thousand-separator = '.'
  decimal-separator = ','
 
 let #value = 123456
 show #value edit '999,999,999,999.99'

Produces the following output:

123.456,00

 !
 ! Reset locale to SQR defaults and change the date and time
 ! separators
 !
 alter-locale
  locale = 'System'
  date-separator = '-'
  time-separator = '.'
 
 let $edit = 'Mon/DD/YYYY HH:MI:SS'
 let $date = strtodate('Jan/01/2004 11:22:33', $edit)
 show $date edit :$edit

Produces the following output:

Jan-01-2004 11.22.33

 !
 ! Reset locale to SQR defaults and change the text used with
 ! the edit options 'na', 'am', 'pm', 'bc, 'ad'
 !
 alter-locale
  locale = 'System'
  edit-option-na = 'not/applicable'
  edit-option-am = 'a.m.'
  edit-option-pm = 'p.m.'
  edit-option-bc = 'b.c.'
  edit-option-ad = 'a.d.'
 
 let $value = ''
 let $edit = 'Mon DD YYYY HH:MI'
 let $date1 = strtodate('Jan 01 2004 11:59', $edit)
 let $date2 = strtodate('Feb 28 2004 12:01', $edit)
 show $value edit '999,999,999,999.99Na'
 show $date1 edit 'Mon DD YYYY HH:MI:SS PM'
 show $date2 edit 'Mon DD YYYY HH:MI:SS pm'

Produces the following output:

    Not/Applicable
Jan 01 2004 11:59:00 A.M.
Feb 28 2004 12:01:00 p.m.

 !
 ! Input some dates using the 'system' locale and
 ! output using other locales from the PSPSPSSQR.INI file.
 !
 alter-locale
  locale = 'System'
 let $date1 = strtodate('Jan 01 2004', 'Mon DD YYYY')
 let $date2 = strtodate('Feb 28 2004', 'Mon DD YYYY')
 let $date3 = strtodate('Mar 15 2004', 'Mon DD YYYY')
 show 'System:'
 show
 show $date1 edit 'Month DD YYYY' ' is ' $date1 edit 'Day'
 show $date2 edit 'Month DD YYYY' ' is ' $date2 edit 'Day'
 show $date3 edit 'Month DD YYYY' ' is ' $date3 edit 'Day'
 alter-locale
  locale = 'German'
 show
 show 'German:'
 show 
 show $date1 edit 'DD Month YYYY' ' ist ' $date1 edit 'Day'
 show $date2 edit 'DD Month YYYY' ' ist ' $date2 edit 'Day'
 show $date3 edit 'DD Month YYYY' ' ist ' $date3 edit 'Day'
 alter-locale
  locale = 'Spanish'
 show
 show 'Spanish:'
 show
 show $date1 edit 'DD Month YYYY' ' es ' $date1 edit 'Day'
 show $date2 edit 'DD Month YYYY' ' es ' $date2 edit 'Day'
 show $date3 edit 'DD Month YYYY' ' es ' $date3 edit 'Day'

Produces the following output:

System:

January 01 2004 is Thursday
February 28 2004 is Saturday
March 15 2004 is Monday

German:

01 Januar 2004 ist Donnerstag
28 Februar 2004 ist Samstag
15 März 2004 ist Montag

Spanish:

01 enero 2004 es jueves
28 febrero 2004 es sábado
15 marzo 2004 es lunes

See DISPLAY , LET, MOVE ,PRINT, SHOW

ALTER-PRINTER

Syntax

ALTER-PRINTER [POINT-SIZE={point_size_num_lit|_var}] [FONT-TYPE={font_type|txt_var}] [SYMBOL-SET={symbol_set_id|txt_var}] [FONT={font_int_lit|_var}] [PITCH={pitch_num_lit|_var}]

Description

Alters printer parameters at runtime.

You can place the ALTER-PRINTER command in any part of an SQR program except the SETUP section.

ALTER-PRINTER attempts to change the attributes of the current printer for the current report. If an attribute does not apply to the current printer, it is ignored. For example, ALTER-PRINTER is ignored if it specifies proportional fonts for a report printed on a line printer. When your program is creating multiple reports and the printer is shared by another report, the attributes are changed for that report as well.

Parameters

Parameter

Description

POINT-SIZE

Specifies the new font point size.

FONT-TYPE

Specifies the new font type. Values are PROPORTIONAL or FIXED.

SYMBOL-SET

Specifies the new symbol set identifier.

FONT

Specifies the new font as a number. (For example, font=3 for Courier and font=4 for Helvetica.)

PITCH

Specifies the new pitch in characters per inch.

See the DECLARE-PRINTER arguments table for information about these arguments.

Example

Change the font and symbol set for the current printer:

alter-printer

font=4   ! Helvetica

symbol-set=12U   ! PC-850 Multilingual

If the output prints to a PostScript printer, the SYMBOL-SET argument is ignored; however, if the .spf file is kept (-KEEP) and later printed on an HP LaserJet, the symbol set 12U can be used.

See The DECLARE-PRINTER command and the -KEEP command-line flag

ALTER-REPORT

Syntax

ALTER-REPORT  [HEADING={heading_name_txt_lit|_var|_col}]
 [HEADING-SIZE={heading_size_int_lit|_var|_col}]  [FOOTING={footing_name_txt_lit|_var|_col}]
 [FOOTING-SIZE={heading_size_int_lit|_var|_col}]

Description

Alters some of the report-specific functionality.

This command enables you to dynamically change the heading or footing sections that are active for the current report. You can also change how much space the heading or footing sections occupy.

If the HEADING or FOOTING value is set to NONE, the section is disabled for the current report.

If the HEADING or FOOTING value is set to DEFAULT, the section reverts to the setting that was in effect when the report was initiated.

If no HEADING or FOOTING value is set, the HEADING-SIZE or FOOTING-SIZE values affect the HEADING/FOOTING currently being used.

If the ALTER-REPORT command was not invoked from within a BEGIN-HEADING or BEGIN-FOOTING section and the page has not been written to, the assignment takes effect immediately; otherwise, it takes effect for the next page.

Parameters

Parameter

Description

HEADING

Specifies the name of the BEGIN-HEADING section to use.

HEADING-SIZE

Specifies the amount of space the BEGIN-HEADING section occupies on the page.

FOOTING

Specifies the name of the BEGIN-FOOTING section to use.

FOOTING-SIZE

Specifies the amount of space the BEGIN-FOOTING section occupies on the page

Example

The following example illustrates the ALTER-REPORT command:

begin-footing 2 name=confidental
  print 'Company Confidential' (1,1,0) center
  page-number (2,37,0)
end-footing

begin-footing 2       name=proprietary
  print 'Company Proprietary' (1,1,0) center
  page-number (2,37,0)
end-footing

begin-report
 alter-report 
   footing = 'Proprietary'
   footing-size = 6                     ! Increase depth

.
.
.
end-report

See The BEGIN-FOOTING and BEGIN-HEADING commands in this section.

ARRAY-ADD, ARRAY-DIVIDE, ARRAY-MULTIPLY, ARRAY-SUBTRACT

Syntax

ARRAY-ADD{src_num_lit|_var|_col}...TO dst_array_name (element_lit|_var|_col)[field [(occurs_lit|_var|_col)]]... ARRAY-DIVIDE{src_num_lit|_var|_col}...INTO dst_array_name (element_int_lit|_var|_col)[field [(occurs_lit|_var|_col)]]... ARRAY-MULTIPLY{src_num_lit|_var|_col}...TIMES dst_array_name (element_int_lit|_var|_col)[field [(occurs_lit|_var|_col)]]... ARRAY-SUBTRACT{src_num_lit|_var|_col}...FROM dst_array_name (element_int_lit|_var|_col)[field [(occurs_lit|_var|_col)]]...

Description

These four commands perform arithmetic operations on one or more elements in an array.

The following information applies to the array arithmetic commands:

  • The array must first be created with the CREATE-ARRAY command.

  • The four array arithmetic commands perform on one or more source numbers, placing the result into the corresponding field in the array.

  • Array element and field occurrence numbers can be numeric literals (123) or numeric variables (#j) and can be from zero (0) to one less than the size of the array.

  • If fields are not listed, the results are placed into consecutively defined fields in the array. If fields are listed, results are placed into those fields at the specified occurrence of the field. If an occurrence is not specified, the zeroth (0) occurrence is used.

  • All fields must be of type number, decimal, float, or integer. They cannot be of type date, char, or text.

  • If division by zero is attempted, a warning message appears, the result field is unchanged, and SQR continues running.

Parameters

Parameter

Description

src_num_lit|_var|_col

Source values are added to, divided into, multiplied by, or subtracted from the respective destination array fields. All variables must be numeric in type.

dst_array_name ( element_int_lit|_var|_col) [ field [ ( occurs_lit|_var|_col) ] ]

Destination array fields contain the results after the operation. All variables must be numeric in type.

Example

The following example adds &salary and #comm to the first two fields defined in the emps array. The #j'th element of the array is used:

array-add &salary #comm to emps(#j)

The following example subtracts #lost, #count, and 1 from the fields loses, total, and sequence of the #j2'th element of the stats array:

array-subtract #lost #count 1 from stats(#j2) loses total sequence

The following example multiplies occurrences 0 through 2 of the field p in the #i'th element of the percentages array by 2:

array-multiply 2 2 2 times percentages(#i) p(0) p(1) p(2)

The following example divides the #i2'th occurrence of the salesman field of the #j'th element of the commissions array by 100:

array-divide 100 into commissions(#j) salesman(#i2)

The following example uses the ARRAY-ADD command in an SQR program:

begin-setup
! declare arrays
create-array name=emps size=1              ! one row needed for this example
   field=Salary:number=35000               ! initialize to 35,000
   field=Comm:number=5000                  ! initialize to 5,000
end-setup

begin-program
do Main
end-program

begin-procedure Main local
! Show original contents of the arrays, then the modified arrays
! array-add
! retrieve values from the only row of array "emps"
get #sal #com FROM emps(0) Salary Comm
print 'Array-Add'         (+1, 1)

print 'Add 1000 to each column'  (+1, 1)
print 'Salary'  (+1, 3) bold underline
print 'Comm'  (,25) bold underline

print #sal   (+1, 1) money
print #com   (,22) money

let #salary = 1000
let #commission = 1000
let #j = 0  ! address the array row with variable "#j"
! Add 1000 (in variables) to each column of row 0 (the 1st and only row)
array-add #salary  #commission  TO emps(#j)
! retrieved the new "added" values
get #sal #com FROM emps(0) Salary Comm
print #sal  (+1,1) money
print #com  (,22) money
end-procedure

See The CREATE-ARRAY command for information about creating an array.

See The CLEAR-ARRAY command for information about clearing or initializing an array.

See The GET, PUT, and LET commands for information about using arrays.

ASK

Syntax

ASK substitution_variable [prompt]

Description

Retrieves values for a compile-time substitution variable. The retrieval can be by user input or command-line arguments, or as entries in the @file on the command line.

The value of the substitution variable replaces the reference variable in the program. Variables are referenced by enclosing the variable name in braces, for example, '{state_name}'. When the substitution variable is text or date, enclose the brackets with single quotes. Substitutions are made when the program is compiled and are saved in the .sqt file. Each variable can be referenced multiple times.

ASK is used only in the SETUP section and must appear prior to any substitution variable references.

You cannot break the ASK command across program lines.

Parameters

Parameter

Description

Substitution_variable

The variable to be used as the substitution variable.

Prompt

An optional, literal text string to be displayed as a prompt if the value for the substitution variable is not entered on the command line or in an argument file.

Example

In the following example, state takes the value entered by the user in response to the prompt Enter state for this report:

begin-setup
  ask state 'Enter state for this report'
end-setup
  ...
begin-select
name, city, state, zip
from customers where state = '{state}'
end-select

See The INPUT command for information about input at runtime.

BEGIN-DOCUMENT

Syntax

BEGIN-DOCUMENT position END-DOCUMENT

Description

Begins a document paragraph . A document paragraph enables you to write free-form text to create form letters, invoices, and so on.

You can reference database columns, SQR variables, and document markers within a document. Their locations in the document determine where they print on the page. You should not use tabs inside a document paragraph. To indent text or fields, use the spacebar. Note also that if the variables being printed inside a document paragraph are variable in length, you might need to manipulate the variable outside the document paragraph.

Note: A document must be run before you can reference its document markers. Because documents can be printed at relative positions on the page, the actual location of a document marker may not be known by SQR until the document itself has been run.

Parameters

Parameter

Description

position

The location on the page where the document begins. The position can be fixed or relative to the current position. See the POSITION command for a description and examples of the position parameter.

Example

The following example illustrates the BEGIN-DOCUMENT command

begin-document (1,1)
.b
Dear $firstname
  ...
end-document

See END-DOCUMENT

BEGIN-EXECUTE

Syntax

BEGIN-EXECUTE [CONNECTION=uq_txt_lit] [ON-ERROR=procedure[(arg1[,argi]...)]] [RSV=num_var] [STATUS=list_var|num_var|txt_var] [SCHEMA=txt_lit|txt_var] [PROCEDURE=txt_lit|txt_var [PARAMETERS=(arg1[IN|INOUT|NULL[,argi[IN|INOUT]]...]])] |COMMAND=txt_lit|txt_var |GETDATA=txt_lit|txt_var] [BEGIN-SELECT[BEFORE=sqr_procedure[(arg1[,argi]...]])]] [AFTER=sqr_procedure[(arg1[,argi]...]])]]] col-name type=char|text|number|date[edit-mask] [on-break]... FROM ROWSETS=({m,-n,n-m,m-|all}) |FROM PARAMETER=txt_lit|txt_var END-SELECT] END-EXECUTE

Description

Begins a new construct. In a BEGIN-EXECUTE paragraph, the syntax of BEGIN-SELECT varies as shown in the following syntax:

Parameters

Parameter

Description

CONNECTION

Identifies a name previously specified with the DECLARE-CONNECTION construct. If you do not specify a name, SQR Server uses the default connection. The default connection is defined by the command-line entries for datasource (DSN), username (USER), and password (PASSWORD). Name is not case-sensitive.

ON-ERROR

Declares the procedure to run if an error occurs.

RSV

Row Set Variable. A global SQR variable containing the row set being retrieved.

STATUS

Identifies a list or scalar variable that receives the status of the stored procedure.

SCHEMA

Identifies the location in the datasource of the object being queried.

PROCEDURE

The name of the datasource-stored procedure to be run. The name may include spaces. If the datasource is SAP R/3, this procedure is a BAPI.

PARAMETER_LIST

Scalar variables, list variables, or both of the form list_var | num_lit | txt_lit | txt_var | num_var | any_col. If you do not specify the keywords IN or INOUT, the default value is IN. Specify all parameters in order; leaving any parameters unnamed causes a syntax error. To ignore a parameter, fill its position with the keyword NULL. This results in a null value for that parameter position.

COMMAND

A text string that you pass to the datasource without modification by SQR. This string can include embedded SQR variables.

BEFORE/AFTER

Names an SQR procedure to be run before or after the row set. The procedure is not performed unless at least one row is returned from the specified row sets.

FROM ROWSET

Special case addition to the BEGIN-SELECT syntax. Available for use with all datasource types, including SAP R/3 and JDBC. Names the row sets from which to retrieve the column variables. If you specify more than one row set, use identical column name/type signatures. Row set numbers must be sequential from left to right within the parentheses, and they must not overlap as in this example: (1–3, 2–4). Numeric literals or #variables are allowed.

FROM PARAMETER

Special case addition to the BEGIN-SELECT syntax. Available only for SAP R/3 datasources. Use only with the PROCEDURE keyword. This argument names an output parameter containing one or more rows from which the column variables are to be retrieved.

PROPERTIES = (txt_var | strlit = txt_var | strlit | num_var | num_lit | any_col, … )

Specifies a set of keyword-value pairs that represent modifications to be made to the properties of the datasource (specified by the CONNECTION = statement). An arbitrary number of such pairs can be specified.

Note: This is a similar concept to the PARAMETERS = statement in DECLARE-CONNECTION, with the minor difference that the properties specified here alter the flow of returned information, as opposed to just setting login properties. Can be used in conjunction with any data-access model (Procedure, Command, Getdata). An application of this statement would be in the MDB setting, where it might be used to specify such things as Level, Generation, or Include-Column, for example, PROPERTIES = ( 'SetColumn' = 5 )

Example

The following example illustrates the BEGIN-EXECUTE command

begin-setup
   declare-variable 
      date $when_ordered 
      text $ship_method
      integer #theRow
      integer #theStatus
      integer #howMany
   end-declare
end-setup

input #howMany type=integer 
input $pword
let %parm1 = list($when_ordered, $ship_method, #howMany)

declare-connection SAPR3
user=scott 
parameters=clientno=5;node=starfish;
end-declare

alter-connection 
   name=SAPR3
   password=$pword

Begin-Execute 
   connection=SAPR3 
      rsv=#theRow 
         status=#theStatus
            on-error=it_failed(#theStatus)
            procedure='CreditHistory version 5'
                parameters=(%parm1,'recalculate')

   print 'proc ran OK, status is ' (+1,1)
   print #theStatus (,+5) edit 999

Begin-Select before=do_eject after=cleanup
city &col=char (1,1) on-break level=1 after=city-tot
keyval type=number (1,+1) 
rcvd type=date (0,+2)
from Rowsets=(1)
End-Select

End-Execute

See EXECUTE

BEGIN-FOOTING

Syntax

BEGIN-FOOTING footing_lines_int_lit [FOR-REPORTS=(ALL|report_name1[,report_namei]...)] [FOR-TOCS=(ALL|toc_name1[,toc_namei]...)] [NAME={footing_name}] END-FOOTING

Description

Begins the FOOTING section.

The FOOTING section defines and controls the information to be printed at the bottom of each page.

You must define the report_name in a DECLARE-REPORT paragraph. If you do not use DECLARE-REPORT, the footing is applied to all reports. You can also specify FOR-REPORTS=(ALL). Note that the parentheses are required.

You can specify more than one BEGIN-FOOTING section; however, only one can exist for each report. A BEGIN-FOOTING section with FOR-REPORTS=(ALL) can be followed by other BEGIN-FOOTING sections for specific reports, which override the ALL setting.

You must define the toc_name in a DECLARE-TOC paragraph. You can also specify FOR-TOCS=(ALL). Note that the parentheses are required.

You can specify more than one BEGIN-FOOTING section; however, only one section can exist for each table of contents. A BEGIN-FOOTING section with FOR-TOCS=(ALL) can be followed by other BEGIN-FOOTING sections for a specific table of contents, which override the ALL setting.

The BEGIN-FOOTING section can be shared between reports and tables of contents.

You can print outside the footing area of the report—that is, in the body area—from the footing, but you cannot print in the footing area from the body.

Parameters

Parameter

Description

footing_lines_int_lit

The number of lines to be reserved at the bottom of each page.

FOR-REPORTS

Specifies the reports to which this footing applies. This argument is required only for a program with multiple reports. If you are writing a program that produces a single report, you can ignore this argument.

FOR-TOCS

Specifies the table of contents to which this heading applies.

NAME

Specifies the name to be associated with this footing section. Use this parameter with the ALTER-REPORT command. The name cannot be NONE or DEFAULT.

Example

The following example illustrates the BEGIN-FOOTING command

begin-footing 2 for-reports=(customer, summary)
  print 'Company Confidential' (1,1,0) center
  page-number (2,37,0)
end-footing
begin-footing 2                      ! For all reports
  print 'Division Report' (1,1,0) center
  page-number (2,37,0)
end-footing
begin-footing 2 for-tocs=(all) 
  print 'Table of Contents' (2,1) 
  let $page = roman(#page-count)     ! ROMAN numerals 
  print $page (,64) 
end-footing

See The ALTER-REPORT command for information about dynamic headings and footings.

See The DECLARE-LAYOUT command for information about page layout.

See The DECLARE-REPORT command for information about programs with multiple reports.

See The DECLARE-TOC command for information about the table of contents.

See The END-FOOTING command.

BEGIN-HEADING

Syntax

BEGIN-HEADING heading_lines_int_lit [FOR-REPORTS=(ALL| report_name1[, report_namei]...)] [FOR-TOCS=(ALL|toc_name1[, toc_namei]...)] [NAME={footing_name}] END-HEADING

Description

Begins a HEADING section.

The HEADING section defines and controls information to be printed at the top of each page.

You must define the report_name in a DECLARE-REPORT paragraph. If you do not use DECLARE-REPORT, the heading is applied to all reports. You can also specify FOR-REPORTS=(ALL). Note that the parentheses are required.

You can specify more than one BEGIN-HEADING section; however, only one can exist for each report. A BEGIN-HEADING section with FOR-REPORTS=(ALL) can be specified followed by other BEGIN-HEADING sections for specific reports, which override the ALL setting.

You must define the toc_name in a DECLARE-TOC paragraph. You can also specify FOR-TOCS=(ALL). Note that the parentheses are required.

You can specify more than one BEGIN-HEADING section; however, only one section can exist for each table of contents. A BEGIN-HEADING section with FOR-TOCS=(ALL) can be specified, followed by other BEGIN-HEADING sections for specific tables of contents, which override the ALL setting.

The BEGIN-HEADING section can be shared between reports and a table of contents.

You can print outside the heading area of the report—that is, in the body area—from the heading, but you cannot print in the heading area from the body.

Parameters

Parameter

Description

heading_lines_int_lit

The number of lines to be reserved at the top of each page.

FOR-REPORTS

Specifies the reports to which this heading applies. This is required only for a program with multiple reports. If you are writing a program that produces a single report, you can ignore this argument.

FOR-TOCS

Specifies the table of contents to which this heading applies.

NAME

Specifies the name to be associated with this heading section. This option cannot be used if FOR-REPORTS or FOR-TOCS is also specified. Use this parameter with the ALTER-REPORT command. The name cannot be NONE or DEFAULT.

Example

The following example illustrates the BEGIN-HEADING command

begin-heading 2                              ! Use 2 lines for
print $current-date (1,1) edit MM/DD/YY      ! heading,
  print 'Sales for the Month of ' (1,30)     ! 2nd is blank.
  print $month ()
end-heading
begin-heading 2 for-tocs=(all) 
  print 'Table of Contents' (1,1) bold center 
end-heading

See The ALTER-REPORT command for information about dynamic headings/footings

See The DECLARE-LAYOUT command for information about page layout

See The DECLARE-REPORT command for information about programs with multiple reports

See The DECLARE-TOC command for information about Table of Contents

See The END-HEADING command

BEGIN-PROCEDURE

Syntax

BEGIN-PROCEDURE procedure_name [LOCAL|(arg1 [, argi]...)] END-PROCEDURE

Description

Begins a procedure. A procedure is one of the most powerful parts of the SQR language. It enables modularized functions and provides standard execution control.

The procedure name must be unique. The name is referenced in DO commands. Procedures contain other commands and paragraphs (for example, SELECT, SQL, DOCUMENT).

By default, procedures are global. That is, variables or columns defined within a procedure are known and can be referenced outside of the procedure.

A procedure is local when the word LOCAL appears after the procedure name or when the procedure is declared with arguments. That is, variables declared within the procedure are available only within the procedure, even when the same variable name is used elsewhere in the program. In addition, any query defined in a local procedure has local database, column-variable names assigned that do not conflict with similarly named columns defined in queries in other procedures.

SQR procedures can be called recursively. However, unlike C or Pascal, SQR maintains only one copy of the local variables and they are persistent.

Arguments passed by a DO command to a procedure must match in number:

  • Database text or date columns, string variables, and literals can be passed to procedure string arguments. If you are passing a date string to a date argument, the date string must be in the format specified by the SQR_DB_DATE_FORMAT setting, or a database-dependent format, or the database-independent format SYYYYMMDD[HH24[MI[SS[NNNNNN]]]].

    See the Default Database Formats table in the PRINT command description.

  • Database numeric columns, numeric variables, and numeric literals can be passed to procedure numeric arguments.

  • Numeric variables (DECIMAL, INTEGER, FLOAT) can be passed to procedure numeric arguments without regard to the argument type of the procedure. SQR automatically converts the numeric values upon entering and leaving the procedure as required.

  • Date variables or columns can be passed to procedure date or string arguments . When a date variable or column is passed to a string argument, the date is converted to a string according to the following rules:

    • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

      If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

    • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

      If this has not been set, SQR uses the format listed in the Default Database Formats table.

    • For TIME columns, the format specified by the SQR_DB_TIME_ONLY_FORMAT setting is used.

      If this has not been set, SQR uses the format listed in the TIME Column Formats table.

To reference or declare global variables from a local procedure, add a leading underscore to the variable name, after the initial $, #, or &. (Example: #_amount)

Note: All the SQR-reserved variables, such as #sql-status and $sql-error, are global variables. Within a local procedure, they must be referenced by the leading underscore: #_sql-status or $_sql-error.

Parameters

Parameter

Description

procedure_name

Specifies a unique name for this procedure. Procedure names are not case-sensitive.

LOCAL

Specifies that this is a local procedure.

arg1 [, argi]...

Specifies the arguments to be passed to or returned from the procedure. Arguments can be string variables ($arg), numeric variables (#arg), or date variables ($arg). If you want to return a value passed back to the calling DO command, place a colon (:) before the variable name. The arguments of the BEGIN-PROCEDURE and DO commands must match in number, order, and type.

Example

The following example shows a procedure, main, that also runs the procedure print_list for each row returned from the Select statement. No parameters are passed to print_list:

begin-procedure main
begin-select
name
address
phone
  do print_list
from custlist order by name
end-select
end-procedure               ! main

In the following example, five arguments are passed to the Calc procedure:

do Calc (&tax, 'OH', &county_name, 12, #amount)

begin-procedure Calc(#rate, $state, $county, #months, :#answer)
.
.
.
let #answer = ...
end-procedure

In the preceding example, the value for :#answer is returned to #amount in the calling DO command.

The following example references global variables:

begin-procedure print-it ($a, $b)
print  $_deptname (+2,5,20)           ! $deptname is
print  $a         (,+1)               ! declared outside
print  $b         (,+1)               ! this procedure
end-procedure

See DO, END-PROCEDURE

BEGIN-PROGRAM

Syntax

BEGIN-PROGRAM END-PROGRAM

Description

Begins the PROGRAM section of an SQR program.

After processing any commands in the SETUP section, SQR starts program execution at the BEGIN-PROGRAM section. The PROGRAM section typically contains a list of DO commands, though other commands can be used. This is the only required section in an SQR program.

Example

The following example illustrates the BEGIN-PROGRAM command:

begin-program
   do startup
   do main
   do finish
end-program

See BEGIN-REPORT, BEGIN-SETUP, END-PROGRAM

BEGIN-SELECT

Syntax

BEGIN-SELECT[DISTINCT][-Cnn][-Bnn][-XP][-NR][-SORTnn] [-LOCK{RR|CS|RO|RL|XX}][-DBdatabase] [-DBconnectionstring] [LOOPS=nn][ON-ERROR=procedure[(arg1[,argi]...)]] {column} [&synonym] {expression &synonym} {[$columnname] &synonym = (char | number | date)} [SQR commands] FROM
{table,...|[table:$tablename]}                 [additional SQL]  
              [$variable] END-SELECT

Description

Begins a SELECT paragraph . A SELECT paragraph is the principal means of retrieving data from the database and printing it in a report. A SELECT paragraph must be inside a PROCEDURE or BEGIN-PROGRAM section.

Note that SELECT * FROM is not a valid SQR SQL statement. BEGIN-SELECT can be placed inside a BEGIN-PROGRAM section.

Parameters

The table describes the parameters:

Note: The arguments can span multiple lines; however, the first character position cannot be used unless the continuation character terminated the previous line. If the first character position is used with arguments spanning multiple lines, the argument will be misconstrued as a Select column.

Parameter

Description

DISTINCT

Specifies that duplicate rows be eliminated from your query.

-Cnn

(Oracle) Sets the context area size (buffer size for query) to larger or smaller than the default. This option is rarely needed.

-Bnn

(Oracle, ODBC, Sybase CT-Lib) Sets the number of rows to retrieve at one time. This is for performance purposes only. Regardless of this setting, all rows are selected. The default, without using -B, is 10 rows. An overall setting for a program can be indicated on the SQR command line with -B, which can be overridden by a separate -B flag on each BEGIN-SELECT command.

-XP

(Sybase) Prevents the creation of a stored procedure for the SELECT paragraph. When -XP is specified, SQR generates a new SQL statement using the current value of any bind variables each time the BEGIN-SELECT is is carried out. This disables the potential performance optimization created by stored procedures. Use this flag if you change the variables frequently during execution and you do not want SQR to automatically create a stored procedure. You can also use -XP if the username/password to your program does not have permission to create stored procedures.

If you do not change variables frequently during execution, the use of stored procedures may optimize your program's performance. In that case, do not use this argument. Note also that -XP is available as a command-line flag.

-XP improves performance when you use bind variables and dynamic query variables in the same query. Each time the dynamic query variable changes in value, a new stored procedure is created. If the dynamic query variable changes often and the query contains bind variables, you create many stored procedures if you do not use -XP.

-DBconnectionstring

(ODBC) Specifies the ODBC connection string for this SELECT paragraph only. A connection string has the following syntax:

DSN=data_source_name[;keyword=value[;keyword=value [;...]]]

This option enables you to combine data from multiple databases in one program. For example, a connection string for an Oracle database named ora8 might look like this:

'DSN=ora8;UID=scott;PWD=tiger' 

where DSN, UID, and PWD are keywords common to all drivers (representing name, user ID, and password, respectively). Connection string options are always separated by a semicolon (;). Other driver-specific options can be added to the connection string by driver-defined keywords. See your ODBC driver documentation for available options.

LOOPS

Specifies the number of rows to retrieve. After the specified number has been processed, the SELECT loop exits.

ON-ERROR

Declares a procedure to run if an error occurs due to incorrect SQL syntax. Error trapping should be used with dynamic query variables. SELECT paragraphs without dynamic variables are checked for errors before the program is processed and therefore do not require a special error procedure.

Optionally, you can specify arguments to be passed to the ON-ERROR procedure. Arguments can be any variable, column, or literal.

Example

In this example, duplicate rows are not selected for the city, state, and zip columns because of the distinct keyword. The numbers within parentheses accompanying city, state, and zip define the column positions of these rows. Column names cannot have spaces in front of them.

See Using Column Variables

begin-select distinct
city      (1,1,30)
state     (0,+2,2)
zip       (1,+3,6)
from custlist order by city
end-select

In this example, the first two columns may be present when the statement is compiled. The column cust_id is declared to be a number. A runtime error occurs if the database table, as identified by the variable $table_name, declares it to be something other than a number.

begin-select           loops=100
[$col_var_char]        &col1=char
[$col_var_num]       &col2=number
cust_id                &id=number
from [$table_name]
[$where clause]
[$order_by_clause]
end-select

In this example, the embedded SQR command Do Print_Row is carried out once for each row.

begin-select distinct
city      (1,1,30)
state     (0,+2,2)
zip       (1,+3,6)
    Do Print_Row
from custlist order by city
end-select

See END-SELECT , EXIT-SELECT

BEGIN-SETUP

Syntax

BEGIN-SETUP END-SETUP

Description

Begins a SETUP section. This optional section is processed prior to the BEGIN-PROGRAM, BEGIN-HEADING, and BEGIN-FOOTING sections.

The SETUP section should be the first section in the program.

The SETUP section contains commands that determine the overall characteristics of the program. The commands used in the SETUP section cannot be used elsewhere unless specified. The SETUP section can include the following commands:

ASK
BEGIN-SQL

(The BEGIN-SQL command can also be used in BEGIN-PROCEDURE paragraphs.)

CREATE-ARRAY

(The CREATE-ARRAY command can also be used in the other sections of an SQR program.)

DECLARE-CHART
DECLARE-IMAGE
DECLARE-LAYOUT
DECLARE-PRINTER
DECLARE-PROCEDURE
DECLARE-REPORT
DECLARE-VARIABLE

(The DECLARE-VARIABLE command can also be used in LOCAL procedures.)

DECLARE-TOC
LOAD-LOOKUP

(The LOAD-LOOKUP command can also be used in the other sections of an SQR program.)

USE

(Sybase and Microsoft SQL Server only.)

Example

The following example illustrates the BEGIN-SETUP command:

begin-setup
   declare-layout customer_list
      paper-size=(8.5, 11)
      left-margin=1.0
      right-margin=1.0
   end-declare
end-setup

See ASK, BEGIN-SQL, CREATE-ARRAY, LOAD-LOOKUP , USE

BEGIN-SQL

Syntax

BEGIN-SQL[-Cnn][-XP][-NR][-SORTnn] [-LOCK{RR|CS|RO|RL|XX}]
[-DBdatabase][-DBconnectionstring]    [ON-ERROR=procedure[(arg1[,argi]]...)]! In the SETUP section
   |[ON-ERROR={STOP|WARN|SKIP}](insetup)! Outside the SETUP section
END-SQL

Description

Begins an SQL paragraph . This paragraph can reside in a BEGIN-PROCEDURE, BEGIN-SETUP, or BEGIN-PROGRAM section.

BEGIN-SQL starts all SQL statements except SELECT, which has its own BEGIN-SELECT paragraph. If a single paragraph contains more than one SQL statement, each statement except the last must be terminated by a semicolon (;).

If a single paragraph contains more than one SQL statement, and the -C flag is used, all are assigned the same context area size or logical connection number.

Only non-SELECT statements can be used (except SELECT INTO for Sybase and Microsoft SQL Server). Columns and variables can be referenced in the SQL statements.

Stored Procedures

For Oracle, stored procedures are implemented by PL/SQL in the BEGIN-SQL paragraph. For Sybase and Microsoft SQL Server, SQR supports stored procedures with the EXECUTE command.

For some databases, such as Oracle, using DDL statements within a BEGIN-SQL paragraph causes a commit of outstanding inserts, updates, and deletes and releases cursors. For this reason, ensure that these are done in the proper order or the results will be unpredictable.

Oracle PL/SQL

For Oracle, PL/SQL is supported in a BEGIN-SQL paragraph. This requires an additional semicolon at the end of each PL/SQL statement.

For Oracle PL/SQL:

begin-sql
declare
   varpl varchar2 (25);;
   var2 number (8,2);;
begin
varpl :='abcdefg';;
$v1 :=varpl;;
$v2 :='1230894asd';; 
var2 :=1234.56;; 
#v :=var2;;
end;;
end-sql

For Oracle stored procedures:

begin-sql
begin
#dept_number :=get_dept_no($dept_name);;
end;;
end-sql

Parameters

Parameter

Description

-Cnn

(Oracle) Sets the context area size (buffer size for query) to larger or smaller than the default. This option is rarely needed.

-XP

(Sybase) Prevents the creation of a stored procedure for the SQL paragraph. When -XP is specified, SQR generates a new SQL statement using the current value of the bind variables each time the BEGIN-SQL is carried out. This disables the performance optimization created by stored procedures. Use this flag if you change the variables frequently during execution and you do not want SQR to automatically create stored procedures. You can also use it if your program does not have permission to create stored procedures.

If you do not change variables frequently during execution, the use of stored procedures optimizes the performance of the program. In that case, do not use this argument.

-XP improves performance when you use bind variables and dynamic query variables in the same query. Each time the dynamic query variable changes in value, a new stored procedure is created. If the dynamic query variable changes often and the query contains bind variables, you create many stored procedures if you do not use -XP.

-DBconnectionstring

(ODBC) Specifies the ODBC connection string for this SQL paragraph only. A connection string has the following syntax:

DSN=data_source_name[;keyword=value[;keyword=value[;...]]]

This option enables you to combine data from multiple databases in one program. For example, a connection string for an Oracle database named ora8 might look like this:

'DSN=ora8;UID=scott;PWD=tiger'

where DSN, UID, and PWD are keywords common to all drivers (representing name, user ID, and password, respectively). Connection string options are always separated by a semicolon (;). Other driver-specific options can be added to the connection string with driver-defined keywords. See your ODBC driver documentation for available options.

ON-ERROR

Declares a procedure to run if an error occurs due to incorrect SQL syntax except when the statement is run in a BEGIN-SETUP section. By default, SQR reports any error and then halts; if an error procedure is declared, you can trap errors, report or log them, and continue processing. The procedure is invoked when an error occurs in any SQL statement in the paragraph. After the error procedure ends, control returns to the next SQL statement.

Optionally, you can specify arguments to be passed to the ON-ERROR procedure. Arguments can be any variable, column, or literal.

If ON-ERROR is used in the SETUP section, it is a condition flag supporting the following conditions:

STOP: Do not run the program.

WARN: Run the program but with a warning message.

SKIP: Ignore any errors and run the program.

Example

The following example illustrates the BEGIN-SQL command:

begin-sql
update orders set invoice_num = #next_invoice_num

where order_num = &order_num
end-sql

begin sql
delete orders

where order_num = &order_num;
insert into orders values ($customer_name, #order_num,...)
end-sql

See END-SQL, BEGIN-PROCEDURE, EXECUTE

See The -S command-line flag

BREAK

Syntax

BREAK

Description

Causes an exit from within an EVALUATE or WHILE command. Execution then continues to the command immediately following the END-WHILE or END-EVALUATE.

This command is used inside a WHILE ... END-WHILE loop or within an EVALUATE command.

Related Links

See Also: WHILE, EVALUATE

CALL, CALL SYSTEM

Syntax

CALL subroutine USING  {src_txt_lit|_var|_col}|{ src_num_lit|_var|_col} {dst_txt_var|_num_var}  [param]

To issue operating system commands from within an SQR program, use the following syntax:

CALL SYSTEM USING command status [ WAIT
| NOWAIT ]

Description

Issues an operating system command or calls a subroutine that you have written in another language, such as C or COBOL, and passes the specified parameters.

You can write your own subroutines to perform tasks that are awkward in SQR. Subroutines can be written in any language.

Warning! Oracle recommends that the UCALL function not use any database calls because it may cause erroneous results.

Used in an SQR program, CALL has the following format:

   CALL your_sub USING source destination [param_literal]
   CALL SYSTEM USING command status [WAIT|NOWAIT]

The CALL SYSTEM is a special subroutine that is provided as part of SQR to enable the program to issue operating system commands. Its arguments, command, status, and WAIT|NOWAIT are described subsequently.

The values of the source and destination variables and the parameter's literal value are passed to your subroutine. Upon return from the subroutine, a value is placed in the destination variable.

You must write the subroutine and call it in one of the supplied UCALL routines. Optionally, you could rewrite UCALL in another language instead.

The source file UCALL.C contains sample subroutines written in C. The UCALL function takes the following arguments:

Argument

Description

How Passed

callname

Name of the subroutine.

By reference with a maximum of 31 characters, null terminated.

strsrc

Source string.

By reference with a maximum of 255 characters, null terminated.

strdes

Destination string.

By reference with a maximum of 255 characters.

dblsrc

Source double floating point.

By reference.

dbldes

Destination double floating point.

By reference.

param

Subroutine parameter string. It must be a literal.

By reference with a maximum of 80 characters, null terminated.

When you use the CALL command, your arguments are processed in the following way:

  • Calling arguments are copied into the variables depending on the type of argument. Strings are placed into strsrc and numerics are placed into dblsrc.

  • Return values are placed into strdes or dbldes depending on whether your destination argument for CALL is a string or numeric variable.

The destination arguments can also be used to pass values to your subroutine.

To access your subroutine, add a reference to it in UCALL and pass along the arguments that you need.

You must relink SQR to CALL after compiling a user-defined function that becomes another SQR function.

If you have created a new object file, you must add your subroutine to the link command file: in UNIX/Linux it is called SQRMAKE; in Microsoft Windows it is called SQREXT.MAK. (Alternatively, you could add your routine to the bottom of the UCALL source module that is already included in the link).

Your subroutine and calling SQR program are responsible for passing the correct string or numeric variables and optional parameter string to the subroutine. No checking is performed.

Parameters

Parameter

Description

subroutine

Specifies the name of your subroutine.

src_txt_lit|_var|_col

Specifies a text column, variable, or literal that is to be input to the called subroutine.

src_num_lit|_var|_col

Specifies a numeric column, variable (decimal, float, or integer), or literal that is to be input to the called subroutine.

dst_txt_var|_num_var

Specifies a text or numeric variable (decimal, float, or integer) into which the called subroutine is to place the return result.

param

Specifies an optional alphanumeric string of characters to be passed as a parameter to the subroutine.

SYSTEM

Specifies that this CALL command issues an operating system command.

command

Specifies the operating system command to carry out. The command can be a quoted string, string variable, or column.

status

Contains the status returned by the operating system. The status must be a numeric variable. The value returned in status is system-dependent as described here:

UNIX/Linux: Zero (0) indicates success. Any other value is the system error code.

PC/ Microsoft Windows: A value less than 32 indicates an error.

WAIT|NOWAIT

(Microsoft Windows only): WAIT specifies that SQR suspend its execution until the CALL SYSTEM command has finished processing. NOWAIT specifies that SQR start the CALL SYSTEM command but continue its own processing while that command is in progress.

For Microsoft Windows, the default is NOWAIT. On UNIX\Linux operating systems, the behavior is always WAIT.

Example

For example, if your program runs under UNIX and you want to make a copy of a file, you can use the following code in your program:

!Executing a UNIX command from an SQR program
Let $Command_String='cp /usr/tmp/file1.dat /usr/tmp/file2.dat'
Call System Using $Command_String #Status
If #Status<>0
  Show 'Error executing the command in Unix: '$command
End-If

See these sample subroutines included in the UCALL source file:

  • TODASH shows how strings can be manipulated.

  • SQROOT demonstrates how to access numerics.

  • SYSTEM invokes a secondary command processor.

The following code calls these subroutines:

call todash using $addr $newaddr '/.',                   ! Convert these to 
                                                         ! dashes
call sqroot using #n #n2                                 ! Put square root of
                                                         ! #n into #n2
call sqroot using &hnvr #j                               ! Hnvr is numeric
                                                         ! database column
call system using 'dir' #s                               ! Get directory listing

The following example uses the SYSTEM argument to issue an operating system command. Some operating systems enable you to invoke a secondary command processor to enter one or more commands and then return to SQR.

! Unix (Type 'exit' to return to SQR)
!
let $shell = getenv('SHELL')
if isblank($shell)
  let $shell = '/bin/sh'
end-if
call system using $shell #unix_status

!Windows (Type 'exit' to return to SQR)
!
let $comspec = getenv('COMSPEC')
let $cmd = comspec || '/c' ||$comspec || ' /k' 
call system using $cmd #win_status wait

The following step-by-step example shows how to add a user-defined subroutine to SQR so that it can be invoked from SQR with the CALL command. For this example, the C function initcap, which makes the first letter of a string uppercase, is added. The function accepts two parameters. The first parameter is the string to which the initcap function is applied. The second is the resultant string.

To add the initcap function to SQR, you need to make the following modifications to the UCALL.C file that was provided with SQR:

  1. Add the prototype for the initcap function:

    static void initcap CC_ARGS((char *, char *));
  2. Modify the UCALL routine in the UCALL.C file.

    Specifically, add an else if statement at the end of the if statement to check for the initcap function:

       void ucall CC_ARGL((callname, strsrc, strdes, dblsrc, dbldes, params))
       ...   
    
           /* If other subroutines, add "else if..." statement for each */
           else if (strcmp(callname,"initcap") == 0)
               initcap(strsrc, strdes);
           else
               sq999("Unknown CALLed subroutine:  %s\n", callname);
           return;
           }
    
  3. At the end of the UCALL.C file, add the initcap routine listed in the following example.

    The routine name must be lowercase; however, in your SQR program, it can be referenced by using either uppercase or lowercase.

    static void initcap CC_ARGL((strsrc, strdes))
    CC_ARG(char *, strsrc)               /* Pointer to source string      */
    CC_LARG(char *, strdes)              /* Pointer to destination string */
       {
       int nIndex;
       int nToUpCase;
       char cChar;
       
       nToUpCase = 1;
       for (nIndex = 0; cChar = strsrc[nIndex]; nIndex++)
          {
          if (isalnum(cChar))
             {
             if (nToUpCase)
                strdes[nIndex] = islower(cChar) ? toupper(cChar) : cChar;
             else
                strdes[nIndex] = isupper(cChar) ? tolower(cChar) : cChar;
             nToUpCase = 0;
             }
          else
             {
             nToUpCase = 1;
             strdes[nIndex] = cChar;
             }
          }
       strdes[nIndex] = '\0';
       }

Note: The CC_ARG macros are defined in the UCALL.C source module. The macros enable the programmer to define a fully prototyped function without concern for whether the C compiler supports the feature.

After these modifications, recompile UCALL.C and relink SQR. See the programming manual for your particular machine for details.

Finally, the following example shows a simple SQR program that uses the initcap function:

begin-program
   input $name 'Enter the first name '! Get the first name from the user 
   lowercase $name                    ! Set the first name to all lowercase 
   call initcap using $name $capname  ! Now set the first character to uppercase
   input $last 'Enter the last name ' ! Get the last name from the user 
   lowercase $last                    ! Set the last name to all lowercase 
   call initcap using $last $caplast  ! Now set the first character to uppercase
   .
   .
   .

See The LET command for information about user-defined functions using UFUNC. C that can be used in the context of an expression and that can either or both pass and return any number of arguments.

CLEAR-ARRAY

Syntax

CLEAR-ARRAY NAME=array_name

Description

Resets each field of an array to its initial value.

The CLEAR-ARRAY command resets each field of the named array to the initial value specified for that field in the CREATE-ARRAY command. If no initial value was specified, numeric fields are reset to zero, text fields are reset to null, and date fields are reset to null. CLEAR-ARRAY also releases all memory that was used by the specified array and returns it to its pristine state.

Parameters

Parameter

Description

NAME

Specifies the name of the array to be cleared.

Example

The following example illustrates the CLEAR-ARRAY command:

clear-array  name=custs

See CREATE-ARRAY

CLOSE

Syntax

CLOSE {filenum_lit|_var_col}

Description

Closes a file, specified by its file number.

Closes a flat file that was previously opened with the OPEN command.

Parameters

Parameter

Description

filenum_lit|_var_col

Specifies the number assigned to the file in the OPEN command.

Example

The following example illustrates the CLOSE command:

close 5
close #j

See OPEN, READ, WRITE

COLUMNS

Syntax

COLUMNS {int_lit|_var|_col}[int_lit|_var|_col]...

Description

Defines logical columns to be used for PRINT commands.

COLUMNS defines the leftmost position of one or more columns within the current page layout. It sets the first column as current.

You can use COLUMNS for printing data either down the page or across the page, depending on how you use the NEXT-COLUMN and USE-COLUMN commands.

The COLUMNS command applies only to the current report. If you want to print columns in more than one report, you must specify the COLUMNS command for each report.

The USE-COLUMN 0 deselects columns. See USE-COLUMN.

Parameters

Parameter

Description

int_lit|_var|_col

Specifies the left margin position of each column.

See NEXT-COLUMN, NEXT-LISTING, NEW-PAGE, USE-COLUMN, USE-REPORT

COMMIT

Syntax

COMMIT

Description

Causes a database commit.

COMMIT is useful when you are doing many inserts, updates, or deletes in an SQL paragraph. A database commit releases the locks on the records that have been inserted, updated, or deleted. Used with some databases, it also has other effects. For this reason, it should not be used within the scope of an active SELECT paragraph or results will be unpredictable.

When the application finishes, a commit is performed automatically unless a ROLLBACK was done or, for callable SQR, the -XC flag was set.

Other commands or options, such as the CONNECT command and the use of DDL statements for some databases with a BEGIN-SQL paragraph, can also cause the database to do a commit.

COMMIT is an SQR command and should not be used within an SQL paragraph. If COMMIT is used in an SQL paragraph, results will be unpredictable.

Note: The COMMIT command can be used with SQR servers for Oracle, DB2, Informix, and ODBC. For Sybase and Microsoft SQL Server, use BEGIN TRANSACTION and COMMIT TRANSACTION within SQL paragraphs as in the following code segment.

Example

The following example illustrates the COMMIT command:

add 1 to #updates_done
if #updates_done > 50
    commit
    move 0 to #updates_done
end-if

For Sybase:

...      ! Begin Transaction occurred previously
begin-sql
   insert into custlog values (&cust_num, &update_date)
end-sql
add 1 to #inserts
if #inserts >= 50
   begin-sql
      commit transaction;             ! Commit every 50 rows
      begin transaction               ! Begin next transaction
   end-sql
   move 0 to #inserts
end-if

...      ! One more Commit Transaction is needed

Warning! Any data being changed by a current transaction is locked by the database and cannot be retrieved in a SELECT paragraph until the transaction is completed by a COMMIT or ROLLBACK statement (or COMMIT TRANSACTION or ROLLBACK TRANSACTION statement for Sybase or Microsoft SQL Server).

CONCAT

Syntax

CONCAT {src_any_lit|_var|_col} WITH  dst_txt_var[[:$]edit_mask]

Description

Concatenates a variable, column, or literal with a string variable.

The contents of the source field are appended to the end of the destination field.

CONCAT can optionally edit the source field before appending it. You can change edit masks dynamically by placing them in a string variable and referencing the variable name preceded by a colon (:).

Also, the source can be a date variable or column. If an edit mask is not specified, the date is converted to a string according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, the first database-dependent format listed in the Default Database Formats table is used.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT.

    If a format has not been set, the format listed in the Default Database Formats table is used.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT.

    If a format has not been set, the format listed in the Time Column Formats table is used.

Parameters

Parameter

Description

src_any_lit|_var|_col

Specifies the source field to be concatenated with the dst_txt_var field.

dst_txt_var

Contains the result after execution

edit_mask

Specifies an optional edit mask.

Example

The following example illustrates the CONCAT command:

concat &zip_plus_4 with $zip '-xxxx'        ! Edit zip plus 4.
concat &descrip with $rec :$desc_edit       ! Edit mask in variable.
concat $date1 with $string                  ! Concatenate a date.

See The PRINT command for information about the Default Database Formats table, the Time Column Formats table, and edit masks

See The LET command for string functions

See STRING, UNSTRING

CONNECT

Syntax

CONNECT {txt_lit|_var|_col}[ON-ERROR=procedure[(arg1 [, argi]...)]]

Description

Logs off the database and logs on under a new username and password.

The new username and password can be stored in a string variable, column, or literal.

Warning! The username and password are not encrypted, so beware of security issues.

After each CONNECT, the reserved variable $username is set to the new username.

All database cursors or logons are closed before the CONNECT occurs. You should not issue a CONNECT within a SELECT or an SQL paragraph while a query is actively fetching or manipulating data from the database.

Parameters

Parameter

Description

txt_lit|_var|_col

Specifies a username and password for the logon.

ON-ERROR

Specifies a procedure to be run if the logon fails. If no ON-ERROR procedure is specified and the logon fails, SQR halts with an error message.

Note: You can optionally specify arguments to be passed to the ON-ERROR procedure. Arguments can be any variable, column, or literal.

Example

The following example illustrates the CONNECT command:

connect  $new-user  on-error=bad-logon($new_user)
connect  'sqr/test'

CREATE-ARRAY

Syntax

CREATE-ARRAY NAME=array_name SIZE=nn  {FIELD=name:type[:occurs] [={init_value_txt_lit|_num_lit}]}...

Description

Creates an array of fields to store and process data.

You can define arrays to store intermediate results or data retrieved from the database. For example, a SELECT paragraph can retrieve data, store it in an array, and gather statistics at the same time. When the query finishes, a summary could be printed followed by the data previously stored in the array.

SQR creates arrays before a program starts to run. The CREATE-ARRAY command can be used in any section of a program.

Commands to process arrays include:

CREATE-ARRAY
CLEAR-ARRAY
GET
PUT
ARRAY-ADD
ARRAY-SUBTRACT
ARRAY-MULTIPLY
ARRAY-DIVIDE
LET

The maximum number of arrays in a program is 128; the maximum number of fields per array is 200.

The following code is a representation of an array emps with three fields in which the CREATE-ARRAY command defines the array:

create-array name=emps size=10
field=name:char='Unknown'
   field=rate:number:2=10.50
   field=phone:char='None'

The name is a simple field (one occurrence), rate has two occurrences, and phone is a simple field. Both array elements and field occurrences are referenced beginning with 0 (zero). The rate is referenced by rate(0) or rate(1). The emps array will contain 10 elements, 0 through 9. All name fields are initialized to Unknown, all phone fields are initialized to None, and all rate fields are initialized to 10.50.

Parameters

Parameter

Description

NAME

Names the array. The name is referenced in other array commands.

SIZE

Defines the number of elements in the array.

FIELD

Defines each field or column in the array. Each field must be defined as type:

DECIMAL[(p)]: Decimal numbers with an optional precision (p).

FLOAT: Double precision floating point numbers.

INTEGER: Whole numbers.

NUMBER: Uses the DEFAULT-NUMERIC type. See the DECLARE-VARIABLE command.

CHAR (or TEXT): Character string.

DATE: Same as date variable.

You can specify an initialization value for each field. Each field is set to this value when the array is created and when the CLEAR-ARRAY command is carried out. If no initialization value is specified, numeric fields (DECIMAL, FLOAT, INTEGER) are set to zero, character fields are set to null, and date fields are set to null. All occurrences of a multiple occurring field are set to the same value. For dates, the initialization string must be formatted as 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]'.

OCCURS

Fields can optionally have a number of occurrences (occurs); that is, they can be repeated any number of times.

Example

The following example illustrates the CREATE-ARRAY command:

create-array  name=custs size=100
   field=name:char
   field=no:number
   field=state:char
   field=zip:char
   field=contacts:char:5
   field=last-contacted:date

See The sample report CUSTOMR4.SQR included with SQR

See DECLARE-VARIABLE, ARRAY-ADD, ARRAY-DIVIDE, ARRAY-MULTIPLY , ARRAY-SUBTRACT, GET , PUT , LET , CLEAR-ARRAY

See The LOAD-LOOKUP command for an alternative way to store database tables in memory

CREATE-COLOR-PALETTE

Syntax

CREATE-COLOR-PALETTE  NAME = {palette_name_txt_lit}  COLOR_1 = {rgb_value}  COLOR_2 = {rgb_value}  [COLOR_n] = {rgb_value} 

Description

Create a color palette.

This command enables you to create a palette of colors. The number of palettes that can be defined in a program is not limited. No gaps are permitted in the palette.

Parameters

Parameter

Description

NAME

Specifies the name of the color palette.

COLOR_1

Specifies the first color in the palette.

COLOR_2

Specifies the second color in the palette.

COLOR_n

Specifies the nth color in the palette. You can specify up to 64 colors in the palette.

{rgb}

Designates a color reference. This can be expressed as (r,g,b), where r, g, and b are either a numeric literal (0 to 255), a numeric variable, or a numeric column. It can also be expressed as a (c), where c is a string literal, column, or variable that is the name of a color.

Example

The following example illustrates the CREATE-COLOR-PALETTE command:

begin-report
 create-color-palette 
   name = 'funky'
   color_1 = ('blue')
   color_2 = ('red')
   color_3 = ('orange')

  Print-Chart Groovy
   Color-Palette = 'Funky'
 end-report

See DECLARE-CHART, PRINT-CHART

#DEBUG

Syntax

#DEBUG[x...]SQR_Command

Description

Causes the current command to be processed during a debugging session.

A -DEBUG[xx] flag in the SQR command line enables conditional compilation of SQR commands. When this flag is used, any command (including other compiler directives) preceded by the word #DEBUG is processed; other commands are ignored.

This is useful for placing DISPLAY, SHOW, PRINT or other commands in your program for testing and for deactivating them when the report goes into production.

The -DEBUG flag can contain a suffix of up to 10 letters or digits. These characters are used to match any letters or digits appended to the #DEBUG preprocess command inside the program. #DEBUG commands with one or more matching suffix characters are processed; other commands are ignored. Commands without any suffix always match.

In addition, for each -DEBUGxx letter, a substitution variable is defined. For example, if the flag -DEBUGab is used on the command line, three substitution variables are defined: debug, debuga, and debugb. These variables can be referenced in #IFDEF commands to enable or disable whole sections of code for debugging.

Parameters

Parameter

Description

x

Represents any letter or digit.

Example

The following SQR command line contains the -DEBUG flag with no suffixes:

sqr  myprog  sammy/baker  -debug

The following SHOW command in the program is carried out if invoked with the previous command line because the -DEBUG flag was used:

#debug show 'The total is ' #grand-tot 999,999,999

In the following code example, the command line contains the -DEBUG flag with the suffixes a, b, and c:

sqr  myprog  sammy/baker  -debugabc

In the following code example, the first three #DEBUG commands are compiled, but the fourth, beginning #debuge, is not because its suffix does not match any of the suffixes on the -DEBUG flag:

#debuga  show 'Now selecting rows...'
#debug   show 'Finished query.'
#debugb  show 'Inserting new row.'
#debuge  show 'Deleting row.'

The following code example shows the use of an #IF with a #DEBUG:

#debuga  #if {platform}='unix'
#debuga     show 'Platform is UNIX'
#debuga  #endif

See CommnadsThe #IF, #IFDEF, #IFNDEF

DECLARE-CHART

Syntax

DECLARE-CHART chart_name [DATA-LABELS=data_labels_lit]
[COLOR-PALETTE=color_palette_lit] [ITEM-COLOR=(chart_item_keyword_lit,
color_value_lit |(r,g,b)] [CHART-SIZE=(chart_width_int_lit,chart_depth_int_lit)]
[TITLE=title_txt_lit] [SUB-TITLE=subtitle_txt_lit] [FILL=fill_lit]
[3D-EFFECTS=3d_effects_lit] [BORDER=border_lit] [POINT-MARKERS=point_markers_lit]
[TYPE=chart_type_lit] [LEGEND=legend_lit] [LEGEND-TITLE=legend_title_txt_lit]
[LEGEND-PLACEMENT=legend_placement_lit] [LEGEND-PRESENTATION=legend_presentation_lit]
[PIE-SEGMENT-QUANTITY-DISPLAY= pie_segement_quantity_display_lit]
[PIE-SEGMENT-PERCENT-DISPLAY= pie_segement_percent_display_lit] [PIE-SEGMENT-EXPLODE=pie_segement_explode_lit]
[X-AXIS-LABEL=x_axis_label_txt_lit] [X-AXIS-MIN-VALUE={x_axis_min_value_lit|_num_lit}]
[X-AXIS-MAX-VALUE={x_axis_max_value_lit|_num_lit}] [X-AXIS-SCALE=x_axis_scale_lit]
[X-AXIS-MAJOR-TICK-MARKS=x_axis_major_tick_marks_lit] [X-AXIS-MINOR-TICK-MARKS=x_axis_minor_tick_marks_lit]
[X-AXIS-MAJOR-INCREMENT= {x_axis_major_increment_lit|_num_lit}] [X-AXIS-MINOR-INCREMENT=
x_axis_minor_increment_num_lit] [X-AXIS-TICK-MARK-PLACEMENT= x_axis_tick_mark_placement_lit]
[X-AXIS-GRID=x_axis_grid_lit] [Y-AXIS-LABEL=y_axis_label_lit] [Y-AXIS-MIN-VALUE={y_axis_min_value_lit|_num_lit}]
[Y-AXIS-MAX-VALUE={y_axis_max_value_lit|_num_lit}] [Y-AXIS-SCALE=y_axis_scale_lit]
[Y-AXIS-MAJOR-TICK-MARKS=y_axis_major_tick_marks_lit] [Y-AXIS-MINOR-TICK-MARKS=y_axis_minor_tick_marks_lit]
[Y-AXIS-MAJOR-INCREMENT= {y_axis_major_increment_lit|_num_lit}] [Y-AXIS-MINOR-INCREMENT=
y_axis_minor_increment_num_lit] [Y-AXIS-TICK-MARK-PLACEMENT= y_axis_tick_mark_placement_lit]
[Y-AXIS-GRID=y_axis_grid_lit] END-DECLARE

Note: If CHART-SIZE is not defined, it must be defined in PRINT-CHART.

Description

Defines the attributes of a chart that can later be displayed using PRINT-CHART.

The DECLARE-CHART command can define the attributes of a chart to be printed as part of a report.

This command can appear only in the SETUP section.

A chart defined with DECLARE-CHART is printed by referencing its name in the PRINT-CHART command. Some or all of the chart attributes can be overridden at runtime with the PRINT-CHART command. As such, DECLARE-CHART is useful when the basic properties of a chart are common to many PRINT-CHART commands.

Note: All DECLARE-CHART attributes can be overridden as part of the PRINT-CHART command. Columns are not supported within the DECLARE-CHART command or the PRINT-CHART command. Attributes that are specified more than once produce a warning, and the first instance is regarded as the actual value. Attributes can be used in any order, with the exception of chart-name, which must follow the DECLARE-CHART keyword.

Also, the FILL specification in the DECLARE-PRINTER command can influence the appearance of the chart. The following table lists the final appearance of the chart with a combination of values for PRINTER.COLOR and CHART.FILL options.

CHART.FILL=

PRINTER.COLOR=Y

PRINTER.COLOR=N

GRAYSCALE

GRAYSCALE

GRAYSCALE

COLOR

COLOR

GRAYSCALE

CROSS­HATCH

COLOR-CROSS­HATCH

CROSSHATCH

NONE

NONE

NONE

Specifying Chart Data Series Colors

Color palettes are used in the new graphics to set the colors of each data point in a data series. You specify the color palette to be used in a business chart by creating an SQR COLOR-PALETTE using the CREATE-COLOR-PALETTE command. The following code demonstrates how to create the color palette:

Create-Color-Palette
   Name = 'Test-Palette'
   Color_1 = (100,133,238)  
   Color_2 = (0, 0, 255)
   Color_3 = (0,255,0)
   Color_4 = (0,0,255)   
   Color_5 = (0,0,0)

Users can specify any number of palettes, with up to 64 colors defined in each palette. If more data points are in the data sets than are defined colors in the palette, the palette resets and continues to set the data point colors from Color_1 to Color_n.

After a color palette has been defined, it can be used within the DECLARE-CHART and PRINT-CHART commands to specify the color palette to be used. The following code example demonstrates the use of a color palette:

Print-Chart test_Chart
   COLOR-PALETTE = 'Test-Palette'

Specifying Chart Item Colors

Users can specify the foreground and background colors of the individual areas within a business chart using ITEM-COLOR = (rgb-value) within the DECLARE-CHART and PRINT-CHART commands. The following list shows chart item keywords that are valid for ITEM-COLOR:

  • ChartBackground – Background color of entire chart area.

  • ChartForeground – Text and Line color of chart area.

  • HeaderBackground – Area within the text box specified for the Title and Subtitle.

  • HeaderForeground – Text color of the Title and Subtitle.

  • FooterBackground – Area within the text box specified for the X Axis label.

  • FooterForeground – Text color of the X Axis label.

  • LegendBackground – Area within the box defining the legend.

  • LegendForeground – Text and outline color of the legend.

  • ChartAreaBackground – Area that includes the body of the chart.

  • ChartAreaForeground – Text and line colors of the chart area.

  • PlotAreaBackground – Area within the X and Y Axis of a chart.

  • PlotAreaForeground – Text and line colors of the plot area.

Parameters

Parameter

Description

chart_name

A unique name to be used for referencing a chart.

CHART-SIZE

The size of the chart frame in standard SQR coordinate units.

The following DECLARE-CHART Command Arguments table describes other arguments for the DECLARE-CHART command.

Note: Oracle does not currently support setting NewGraphics to Yes. You should not use the DATA-LABELS, COLOR-PALETTE, and ITEM-COLOR attributes listed in the following table because they are valid only when NewGraphics=Yes.

Argument

Values

Description

DATA-LABELS

Yes|No

If NewGraphics is set to Yes, use this argument to specify whether SQR prints the numeric value above the individual data points. Set to NO to suppress the numeric values.

COLOR-PALETTE

palette_name

If NewGraphics is set to Yes, use this argument to specify the name of the color palette to be used to color the individual data points in each chart (for example, bar, slice, point). A valid SQR color-palette must be defined to use COLOR-PALETTE.

ITEM-COLOR

ChartBackground|ChartForeground

HeaderBackground|HeaderForeground

FooterBackground|FooterForeground

LegendBackground|LegendForeground

ChartAreaBackground|ChartAreaForeground

PlotAreaBackground

If NewGraphics is set to Yes, use this argument to specify the color of an individual item in a chart. Specify a chart item and a valid (r,g,b) color to set the color of the chart item.

TITLE

NONE | text

Specifies a title for the chart. That text is placed at the top of the chart.

SUB-TITLE

NONE | text

Specifies a subtitle for the chart. That text is placed below the title regardless of whether TITLE is specified.

FILL

GRAYSCALE | COLOR | CROSS­HATCH | NONE

Specifies the type of filling that is applied to the shapes (bars, pie segments, and so on) in the chart. GRAYSCALE varies the density of black dots. COLOR sends color instructions to the current printer. If the current printer does not support color, then color can appear in a GRAYSCALE fashion. CROSSHATCH uses patterns to fill the shapes representing each data set. With NONE, all graph shapes are filled with white.

3D-EFFECTS

YES | NO

Specifies whether the chart depth appears with 3-D effects. If this argument is set to NO, the chart is displayed in the default 2D mode.

BORDER

YES | NO

If this argument is set to YES, a border is drawn around the chart. If it is set to NO, no border is displayed around the chart.

POINT-MARKERS

YES | NO

Specifies whether point markers appear on line charts. If this argument is set to YES, point markers appear on line charts. If it is set to NO, point markers do not appear.

TYPE

LINE | PIE | BAR, STACKED-BAR | 100%-BAR | OVERLAPPED-BAR | FLOATING-BAR | HISTOGRAM | AREA | STACKED-AREA | 100%-AREA | XY-SCATTER-PLOT | HIGH-LOW-CLOSE

Specifies the type of chart.

See Using Business Charts.

LEGEND

YES | NO

Specifies whether to display a legend.

LEGEND-TITLE

NONE | text

Specifies the title for the legend. If this argument is set to NONE, no title is displayed in the legend box.

LEGEND-PLACEMENT

CENTER-RIGHT | CENTER-LEFT | UPPER-RIGHT | UPPER-LEFT | UPPER-CENTER | LOWER-RIGHT | LOWER-LEFT | LOWER-CENTER |

Places the legend in the specified location on the chart. The first portion of the placement parameter (CENTER, UPPER, or LOWER) is the vertical position, and the second portion (RIGHT, LEFT, or CENTER) is the horizontal.

LEGEND-PRESENTATION

INSIDE | OUTSIDE

Specifies where the legend appears on the chart. If this argument is set to INSIDE, the legend is presented inside the area defined by the two axes. If it is set to OUTSIDE, the legend is presented within the chart border, but outside of the region represented by the two axes.

PIE-SEGMENT-QUANTITY- DISPLAY

YES | NO

Specifies whether quantity is presented for each pie segment. If this argument is set to YES, the quantity is presented.

PIE-SEGMENT-PERCENT-DISPLAY

YES | NO

Specifies whether the percent-of-total number is presented for each pie segment. If this argument is set to YES, the percent-of-total figures is presented.

PIE-SEGMENT-EXPLODE

NONE | MAX |MIN | USE-3RD-DATA-COLUMN

Controls which pie segments are exploded (selected) within the pie chart. MAX selects the largest segment. MIN selects the smallest segment. USE-3RD-DATA-COLUMN uses the third field in the DATA-ARRAY to determine which pie segments are exploded. This third field should be a CHAR and values of YES or Y indicate that the segment should be exploded.

X-AXIS-LABEL or Y-AXIS-LABEL

NONE | text

Specifies a line of text to be displayed below (or alongside) the tick-mark labels on the axis.

X-AXIS-MIN-VALUE

AUTOSCALE | number

Specifies the minimum value on the axis. If data values exist that are less than X-AXIS- MIN-VALUE, they are not displayed. AUTOSCALE directs SQR to calculate an appropriate minimum value.

Y-AXIS-MIN-VALUE

AUTOSCALE | number

Specifies the minimum value on the axis. If data values exist that are less than Y-AXIS- MIN-VALUE, then they are not displayed. AUTOSCALE directs SQR to calculate an appropriate minimum value.

X-AXIS-MAX-VALUE

AUTOSCALE | number

Specifies the maximum value on the axis. If data values exist that are greater than X- AXIS-MAX-VALUE, they are not displayed. AUTOSCALE directs SQR to calculate an appropriate maximum value.

Y-AXIS-MAX-VALUE

AUTOSCALE | number

Specifies the maximum value on the axis. If data values exist that are greater than Y- AXIS-MAX-VALUE, they are not displayed. AUTOSCALE directs SQR to calculate an appropriate maximum value.

X-AXIS-SCALE or Y-AXIS-SCALE

LOG | LINEAR

Specifies the scale for the axis. LOG specifies a logarithmic scale for the axis. Otherwise, the scale is linear.

X-AXIS-MAJOR-TICK- MARKS

YES | NO

Specifies whether to display tick-marks for major increments on the X-axis. If this argument is set to YES, tick-marks appear on the axis between X-AXIS-MIN-VALUE and X-AXIS-MAX-VALUE, according to the X-AXIS-SCALE setting spaced by X-AXIS-MAJOR-INCREMENT.

Y-AXIS-MAJOR-TICK- MARKS

YES | NO

Specifies whether to display tick-marks for major increments on the Y-axis. If this argument is set to YES, tick-marks appear on the axis between Y-AXIS-MIN-VALUE and Y-AXIS-MAX-VALUE, according to the Y-AXIS-SCALE setting spaced by Y-AXIS-MAJOR-INCREMENT.

X-AXIS-MINOR-TICK- MARKS

YES | NO

Specifies whether to display tick-marks for minor increments on the X-axis. If this argument is set to YES, tick-marks appear on the axis between X-AXIS-MIN-VALUE and X-AXIS-MAX-VALUE, according to the X-AXIS-SCALE setting spaced by X-AXIS-MINOR-INCREMENT.

Y-AXIS-MINOR-TICK- MARKS

YES | NO

Specifies whether to display tick-marks for minor increments on the Y-axis. If this argument is set to YES, tick-marks appear on the axis between Y-AXIS-MIN-VALUE and Y-AXIS-MAX-VALUE, according to the Y-AXIS-SCALE setting spaced by Y-AXIS-MINOR-INCREMENT.

X-AXIS-MAJOR-INCREMENT or Y-AXIS-MAJOR-INCREMENT

AUTOSCALE | number

Specifies, for SQR, the increment used for spacing the major tick-marks on the axis. AUTOSCALE directs SQR to determine an appropriate increment.

X-AXIS-MINOR-INCREMENT or Y-AXIS-MINOR-INCREMENT

number

Specifies, for SQR, the increment used for spacing the minor tick-marks on the axis. These arguments must be set for the X-AXIS- MINOR-TICK-MARKS and the Y-AXIS- MINOR-TICK-MARKS to appear.

X-AXIS-TICK-MARK- PLACEMENT or Y-AXIS-TICK-MARK- PLACEMENT

INSIDE | OUTSIDE | BOTH

Specifies where to place the tick-marks on the axis. INSIDE (or OUTSIDE) directs SQR to place the tick-marks on the inside (or outside) of the axis only. BOTH directs SQR to draw the tick-marks such that they appear on both sides of the axis.

X-AXIS-GRID or Y-AXIS-GRID

YES | NO

Specifies whether a grid line is drawn for each major tick-mark on the axis. If this argument is set toYES, a dashed grid line is drawn for each major tick-mark. If it is set to NO, no grid line is drawn on the axis.

Example

This code example declares a basic sales chart using DECLARE-CHART. For each region, the SUB-TITLE, DATA-ARRAY, and other elements are overridden to provide the chart with the specific features desired.

begin-setup


declare-chart base_sales_chart
chart-size             = (30, 20 )
title                  = 'Quarterly Sales'
sub-title              = none
fill                   = color
3d-effects             = yes
type                   = stacked-bar
legend-title           = 'Product'
x-axis-grid            = yes
end-declare


end-setup

begin-program


print-chart base_sales_chart
sub-title               = 'Region I' 
data-array              = reg1_sales
data-array-row-count    = #rows_reg1
data-array-column-count = 2
y-axis-max-value        = #max_of_all_regions
y-axis-min-value        = #min_of_all_regions
legend                  = no


print-chart base_sales_chart
sub-title               = 'Region II' 
data-array              = reg2_sales
data-array-row-count    = #rows_reg2
data-array-column-count = 2
y-axis-max-value        = #max_of_all_regions
y-axis-min-value        = #min_of_all_regions
legend                  = no


end-program

begin-procedure chart_region_sales ($sub, $ary,
                     #rows, #cols,
                     #max_of_all_regions,
                     #min_of_all_regions)



print-chart base_sales_chart (20, 15 )
sub-title                 = $sub
data-array                = all sales
data-array-row-count      = #rows
data-array-column-count   = #cols
data-array-column-labels  = ('Q1', 'Q2', 'Q3', 'Q4' )
y-axis-max-value          = #max_of_all_regions
y-axis-min-value          = #min_of_all_regions
chart-size                = (50, 30)


end-procedure

See The PRINT-CHART command

DECLARE-COLOR-MAP

Syntax

In the SETUP section:

DECLARE-COLOR-MAP       color_name = ({rgb}) color_name = ({rgb}) . . . END-DECLARE 

Description

Defines colors in an SQR report.

The DECLARE-COLOR-MAP command in the BEGIN-SETUP section defines or redefines colors in an SQR report. You can define an endless number of entries.

Parameters

Parameter

Description

color_name

A color_name is composed of alphanumeric characters (A–Z, 0–9), the underscore (_) character, and the hyphen (-) character. It must start with an alphabetical (A–Z) character and is not case-sensitive. The name none is reserved and cannot be assigned a value. A name in the format (RGBredgreenblue) cannot be assigned a value. The name default is reserved and cannot be assigned a value. Default is used during execution when a referenced color is not defined in the runtime environment.

{rgb}

red_lit | _var | _col, green_lit | _var | _col, blue_lit | _var | _col where each component is a value in the range of 000 to 255. In the BEGIN-SETUP section, only literal values are allowed.

The default colors implicitly installed with SQR include:

black=(0,0,0)

white=(255,255,255)

gray=(128,128,128)

silver=(192,192,192)

red=(255,0,0)

green=(0,255,0)

blue=(0,0,255)

yellow=(255,255,0)

purple=(128,0,128)

olive=(128,128,0)

navy=(0,0,128)

aqua=(0,255,255)

lime=(0,128,0)

maroon=(128,0,0)

teal=(0,128,128)

fuchsia=(255,0,255)

Example

The following example illustrates the DECLARE-COLOR-MAP command:

begin-setup
   declare-color-map
    light_blue = (193, 222, 229)
   end-declare
end-setup

See CommandsThe ALTER-COLOR-MAP, SET-COLOR, GET-COLOR

DECLARE-CONNECTION

Syntax

In the SETUP section:

DECLARE-CONNECTION connection_name_txt_lit DSN={uq_txt_lit} [USER={uq_txt_lit}] [PASSWORD={uq_txt_lit}] [PARAMETERS=keyword_str=attr_str;[,keyword_str=attr_str ;...]] END-DECLARE 

In the body of the report:

DECLARE-CONNECTION connection_name DSN={uq_txt_lit|_var} [USER={uq_txt_lit|_var}] [PASSWORD={uq_txt_lit|_var}] [PARAMETERS=keyword_str=attr_str;[, keyword_str=attr_str;...]] END-DECLARE 

Description

Defines the datasource logon parameters prior to logon. Can be used to override the default connection logon parameters.

Parameters

Parameter

Description

connection_name

A user-defined name for describing a datasource connection.

USER, PASSWORD

Traditional logon semantics.

PARAMETERS = keyword_str=attr_str;

Defines a list of keyword-attribute pairs required by a datasource driver for logon. No syntax restriction exists for these entries apart from the delimiting semicolons (;) and equal signs (=). The keywords must match the logon property names listed for a datasource.

NO-DUPLICATE=

TRUE|FALSE

(default is FALSE)

This optional keyword prevents SQR from automatically creating additional logins to datasources that are busy handling a previous query. Creating a new login in such cases is the default behavior for SQR, which allows a single CONNECTION declaration to be used in a subquery. The behavior, while allowing dynamic logins as needed, causes problems when you are doing both DDL (BEGIN-SQL) and DML (BEGIN-SELECT) against temporary tables in certain vendors' datasources. In such cases, you must fetch from the temporary table using the same login in which it was created. Here, you should code the CONNECTION as NO-DUPLICATE=TRUE, and then use that connection in both the table creation logic of BEGIN-SQL and the row fetching logic of BEGIN-SELECT.

Example

The following example illustrates the DECLARE-CONNECTION command:

declare-connection SAPR3-1
   dsn=SAPR3
   username=guest
   password=guest
end-declare

DECLARE-IMAGE

Syntax

DECLARE-IMAGE image_name [TYPE=image_type_lit] [IMAGE-SIZE=(width_num_lit,height_num_lit)] [SOURCE=file_name_lit] END-DECLARE

Note: If TYPE, IMAGE-SIZE, and SOURCE are not defined in DECLARE-IMAGE, they must be defined in PRINT-IMAGE.

Description

Declares the type, size, and source of an image to be printed.

The DECLARE-IMAGE command defines and names an image. This image can then be placed in a report at the position specified in the PRINT-IMAGE command.

Note: If the image file is unrecognizable, or has incomplete header information, a box (either shaded, for HP printers, or having a diagonal line through it in the case of postscript) appears where the image is expected.

Parameters

Parameter

Description

image_name

Specifies a unique name for referencing the image declaration.

TYPE

Specifies the image type. Types can be EPS-FILE, HPGL-FILE, GIF-FILE, JPEG-FILE, or BMP-FILE (for Microsoft Windows).

IMAGE-SIZE

Specifies the width and height of the image in SQR coordinates.

SOURCE

Specifies the name of a file containing the image. The file must be in the SQRDIR directory or you must specify the full path.

Note: If the file is not in the SQRDIR directory, the full path or no path should be given. You cannot specify a relative path, because you must know where to run the file from.

Example

The following example illustrates the DECLARE-IMAGE command:

declare-image officer-signature
   type           = eps-file
   source         = 'off_sherman.eps'
   image-size     = (40, 5)
end-declare

See PRINT-IMAGE

DECLARE-LAYOUT

Syntax

DECLARE-LAYOUT layout_name [PAPER-SIZE=({paper_width_num_lit[uom],
paper_depth_num_lit[uom]}|{paper_name})] [FORMFEED=form_feed_lit]
[ORIENTATION=orientation_lit] [LEFT-MARGIN=left_margin_num_lit[uom]]
[TOP-MARGIN=top_margin_num_lit[uom]] [RIGHT-MARGIN=right_margin_num_lit[uom]
|LINE-WIDTH=line_width_num_lit[uom] |MAX-COLUMNS=columns_int_lit]
[BOTTOM-MARGIN=bottom_margin_num_lit[uom] |PAGE-DEPTH=page_depth_num_lit[uom]
|MAX-LINES=lines_int_lit] [CHAR-WIDTH=char_width_num_lit[uom]] [LINE-HEIGHT=line_height_num_lit[uom]]
END-DECLARE

Description

Defines the attributes for the layout of an output file .

The DECLARE-LAYOUT command describes the characteristics of a layout to be used for an output file. A layout can be shared by more than one report. If no DECLARE-LAYOUT is defined or if a DECLARE-REPORT does not reference a defined layout, a layout named DEFAULT is created with the default attribute values shown in the DECLARE-LAYOUT Command Arguments table. For an example of how DECLARE-LAYOUT relates to DECLARE-REPORT, see the DECLARE-REPORT examples in this document.

You can define as many layouts as are necessary for the requirements of the application. You can override the DEFAULT layout attributes by defining a layout called DEFAULT in your program. Each layout name must be unique.

SQR maps its line and column positions on the page by using a grid determined by the LINE-HEIGHT and CHAR-WIDTH arguments. That is, SQR calculates the number of columns per row by dividing the LINE-WIDTH by the CHAR-WIDTH and calculates the number of lines by dividing the PAGE-DEPTH by the LINE-HEIGHT. Each printed segment of text is placed on the page using this grid. Because the characters in proportional fonts vary in width, a word or string may be wider than the horizontal space you have allotted, especially in words containing uppercase letters or boldfaced characters. To account for this behavior, you can either move the column position in the PRINT or POSITION statements or indicate a larger CHAR-WIDTH in the DECLARE-LAYOUT command.

The DECLARE-LAYOUT command selects the proper fonts. In addition, the parameter interacts with PAPER-SIZE like this:

  • When you do not specify ORIENTATION=LANDSCAPE or the PAPER-SIZE dimensions, SQR creates a page with the dimensions set to 11 inch by 8.5 inch. This results in a page of 100 columns by 45 lines with 0.5 inch margins.

  • When you specify PAPER-SIZE=(paper_name), the page orientation is set according to the paper_name specified. If you also specify ORIENTATION and the value differs from the PAPER-SIZE value, the ORIENTATION value overrides the PAPER-SIZE value.

  • When you specify PAPER-SIZE=(page_width, page_depth), SQR does not swap the page width and page depth if ORIENTATION=LANDSCAPE.

Parameters

Parameter

Description

layout_name

A unique layout name to be used for referencing the layout and its attributes.

uom

(unit of measure)

An optional suffix that denotes the unit of measure to apply to the preceding value.

paper_name

An option of PAPER-SIZE. This name is associated with predefined dimensions.

This table lists valid unit of measure suffixes:

Suffix

Meaning

Definition

dp

decipoint

0.001388 inch

pt

point

0.01388 inch

mm

millimeter

0.03937 inch

cm

centimeter

0.3937 inch

in

inch

1.0000 inch

This table lists valid paper names for the paper_name parameter.

Name

Width

Depth

Orientation

Letter

8.5 in

11 in

Portrait

Legal

8.5 in

14 in

Portrait

A4

8.27 in

11.69 in

Portrait

Executive

7.25 in

10.5 in

Portrait

B5

7.17 in

10.12 in

Portrait

Com-10

4.125 in

9.5 in

Landscape

Monarch

3.875 in

7.5 in

Landscape

DL

4.33 in

8.66 in

Landscape

C5

6.378 in

9.016 in

Landscape

This table describes the arguments of the DECLARE-LAYOUT command:

Argument

Choice or Default UOM

Default Value

Description

PAPER-SIZE

inches

8.5 in, 11 in

Physical size of the page. The first parameter is the width of the page. The second parameter is the depth or length. It may also be a predefined name. (See the table of valid paper names.) Note that when ORIENTATION= LANDSCAPE, the default values are 11 in, 8.5 in.

FORMFEED

YES, NO

YES

Specifies whether formfeeds are to be written at the end of each page.

ORIENTATION

PORTRAIT, LANDSCAPE

PORTRAIT

Portrait pages are printed vertically. Landscape pages are printed horizontally. Printing in landscape for the printer type HPLASERJET requires landscape fonts.

LEFT-MARGIN

inches

0.5 in

Amount of blank space to leave at the left side of the page.

TOP-MARGIN

inches

0.5 in

Amount of blank space to leave at the top of the page.

RIGHT-MARGIN

inches

0.5 in

Amount of blank space to leave at the right side of the page. If you specify LINE-WIDTH or MAX-COLUMNS, you cannot use this parameter.

LINE-WIDTH

inches

7.5 in

Length of the line. If you specify RIGHT-MARGIN or MAX-COLUMNS, you cannot use this parameter.

MAX-COLUMNS

 NA (not applicable)

75

Maximum number of columns in a line. If you specify RIGHT-MARGIN or LINE-WIDTH, you cannot use this parameter.

BOTTOM-MARGIN

inches

0.5 in

Amount of blank space to leave at the bottom of the page. If you specify PAGE-DEPTH or MAX-LINES, you cannot use this parameter.

PAGE-DEPTH

inches

10 in

Depth of the page. If you specify BOTTOM-MARGIN or MAX-LINES, you cannot use this parameter.

MAX-LINES

 NA

60

Maximum number of lines printed on the page. If you specify PAGE-DEPTH or BOTTOM-MARGIN, you cannot use this parameter.

LINE-HEIGHT

points

12 pt

Size of each SQR line on the page. An inch has 72 points. If LINE-HEIGHT is not specified, it follows the value for POINT-SIZE, if specified. The default value of 12 points yields 6 lines per inch. For the printer type LINEPRINTER, this value is used only to calculate the TOP-MARGIN and BOTTOM-MARGIN (for example, not in computing the position on the page).

CHAR-WIDTH

points

7.2 pt

Size of each SQR horizontal character column on the page (for example, the distance between the locations (1, 12) and (1, 13)). For the printer type LINEPRINTER, this value is used only to calculate the TOP-MARGIN and BOTTOM-MARGIN (not for computing the position on the page).

Example

This example illustrates the ability to specify these parameters using a different measurement system, such as metric:

!
declare-layout my-layout      ! Results in: 

paper-size=(a4)               !   paper-size=(210mm, 297mm) 

left-margin=12.7 mm           !   top-margin=12.7mm 

right-margin=25.4 mm          !  left-margin=12.7mm
end-declare                   !  right-margin=25.4mm

                              !   bottom-margin=12.7mm

                              !   orientation=portrait

                              !   columns=67

                              !   lines=64

This example changes the page dimensions and also changes the left and right margins to be 1 inch:

!
declare-layout large-paper    ! Results in:

paper-size=(14, 11)           !   paper-size=(14in, 11in)

left-margin=1                 !   top-margin=0.5in 

right-margin=1                !   left-margin=1.0in
end-declare                   !   right-margin=1.0in

                              !   bottom-margin=0.5in

                              !   orientation=portrait

                              !   columns=120

                              !   lines=60

This example retains the default page dimensions and changes the left and right margins to be 1 inch:

declare-layout default        ! Results in:

left-margin=1                 !   paper-size=(8.5in, 11in)

right-margin=1                !   top-margin=0.5in
end-declare                   !   left-margin=1.0in 

                              !   right-margin=1.0in

                              !   bottom-margin=0.5in

                              !   orientation=portrait

                              !   columns=65

                              !   lines=60

This example changes the orientation to landscape; the default page dimensions (8.5in and 11in) are swapped, the columns and rows are recalculated, and all other values remain the same:

declare-layout default         ! Results in:

orientation=landscape          !   paper-size=(11in, 8.5in)
end-declare                    !   top-margin=0.5in

                               !   left-margin=0.5in

                               !   right-margin=0.5in

                               !   bottom-margin=0.5in

                               !   orientation=landscape

                               !   columns=100

                               !   lines=45

This example changes the orientation to landscape; the default page dimensions (8.5in and 11in) are swapped, and the top margin is set to 1 inch:

declare-layout my_landscape     ! Results in:

orientation=landscape           !   paper-size=(11in, 8.5in)

top-margin=1                    !   top-margin=1.0in
end-declare                     !   left-margin=0.5in

                                !   right-margin=0.5in

                                !   bottom-margin=0.5in

                                !   orientation=landscape

                                !   columns=100

                                !   lines=43

This example illustrates how to specify the page dimensions using one of the predefined names (note that the orientation has also changed because this example is an envelope):

declare-layout envelope          ! Results in: 

paper-size=(com-10)              !   paper-size=(4.125in, 9.5in) 
end-declare                      !   top-margin=0.5in 

                                 !   left-margin=0.5in

                                 !   right-margin=0.5in

                                 !   bottom-margin=0.5in

                                 !   orientation=landscape

                                 !   columns=85

                                 !   lines=18

See DECLARE-REPORT

DECLARE-PRINTER

Syntax

DECLARE-PRINTER printer_name [FOR-REPORTS=(report_name1[,report_namei]...)]
[TYPE=printer_type_lit] [INIT-STRING=initialization_string_txt_lit]
[RESET-STRING=reset_string_txt_lit] [COLOR=color_lit] [POINT-SIZE=point_size_num_lit]
[FONT-TYPE=font_type_int_lit] [SYMBOL-SET=symbol_set_id_lit] [STARTUP-FILE=file_name_txt_lit]
[PITCH=pitch_num_lit] [FONT=font_int_lit] [BEFORE-BOLD=before_bold_string_txt_lit]
[AFTER-BOLD=after_bold_string_txt_lit] END-DECLARE

Description

Overrides the printer defaults for the specified printer type.

Each printer has a set of defaults as listed in the DECLARE-PRINTER Command Arguments table. The DECLARE-PRINTER command overrides these defaults.

Use the DECLARE-PRINTER command in the SETUP section to define the characteristics of the printer or printers to be used. If you need to change some of the arguments depending on the runtime environment, you can use the ALTER-PRINTER command in any part of the program except the PROGRAM and SETUP sections.

A program can contain no more than one DECLARE-PRINTER command for each printer type for each report. If you do not provide a printer declaration, the default specifications are used. You can override the default printer attributes by providing a DECLARE-PRINTER specification for each printer. The names are:

  • DEFAULT-LP for line printer.

  • DEFAULT-HP for HP LaserJet.

  • DEFAULT-HT for HTML.

  • DEFAULT-PS for PostScript.

This table lists the arguments, provides the possible choices or measure, lists the default values, and describes the arguments.

Argument

Choice or Measure

Default

Description

FOR-REPORTS

NA (Not Applicable) 

ALL

The name of the reports that use this printer definition. The default is ALL, for all reports. This argument is required only for a program with multiple reports. If you are writing a program that produces only a single report, you can ignore this argument.

TYPE

LINEPRINTER, POSTSCRIPT, HPLASERJET, HTML, LP, PS, HP, HT

LP

The output type specific to each printer. LINEPRINTER (LP) files can be viewed by a text editor. POSTSCRIPT (PS) files require you to know PostScript to understand what will be shown on the printer. HPLASERJET (HP) files are binary files and cannot be edited or viewed. HTML (HT) files can be viewed by a browser.

INIT-STRING

NA 

(none)

Sends control or other characters to the printer at the beginning of the report. This parameter is designed primarily for the LINEPRINTER and has limited use with other printer types. Specify nondisplay characters by placing their decimal values inside angle brackets. For example, <27> is the ESC or escape character.

RESET-STRING

NA 

(none)

Sends control or other characters to the printer at the end of the report. This parameter is designed primarily for the LINEPRINTER and has limited use with other printer types. Specify nondisplay characters by placing their decimal values inside angle brackets. For example, <27> is the ESC or escape character.

COLOR

Yes, No

No

Specifies whether this printer can print in color.

POINT-SIZE

points

12

This argument does not apply to LINEPRINTER printers. It is the beginning size of the selected font.

FONT-TYPE

PROPORTIONAL, FIXED

Depends on the font

This argument applies only to HPLASERJET printers and needs to be specified only for font types not defined in the Fonts Available for HP LaserJet Printers in the SQR table.

SYMBOL-SET

HP defined sets

0U

This argument applies only to HPLASERJET printers. The default value of 0U is for the USASCII symbol set. For a complete list of the symbol sets, see the HP LaserJet Technical Reference Manual.

STARTUP-FILE

file name

POSTSCRI.STR

This argument applies only to POSTSCRIPT printers. This argument is used to specify an alternate startup file. Unless otherwise specified, the default startup file is located in the directory pointed to by the environment variable SQRDIR.

PITCH

characters/inch

10

This argument is for HPLASERJET printers only. If you specify a fixed pitch font, you should also indicate the pitch.

FONT

font_number

3

This is the font number of the typeface to use. For HPLASERJET printers, this is the typeface value as defined by Hewlett-Packard. For a complete list of the typeface numbers, see the HP LaserJet Technical Reference Manual.

For POSTSCRIPT printers, SQR supplies a list of fonts and arbitrary font number assignments in the file POSTSCRI.STR. The font numbers are the same as those for HP LaserJet printers, wherever possible, so that you can use the same font number for reports to be printed on both types of printers. You can modify the font list in POSTSCRI.STR to add or delete fonts. Read the POSTSCRI.STR file for instructions. The Fonts Available for HP LaserJet Printers in SQR table lists the fonts available in SQR internally. The Fonts Available for PostScript Printers table lists the fonts available in the SQR POSTSCRI.STR file.

BEFORE-BOLD

any string

(none)

The BEFORE-BOLD and AFTER-BOLD arguments are for LINEPRINTER printers only. They specify the character string to enable or disable boldfacing. If the string contains blank characters, enclose it in single quote marks ('...'). To specify nonprintable characters, such as ESC, enclose the decimal value inside angle brackets as shown here: BEFORE-BOLD=<27>[r ! Turn on bold AFTER-BOLD=<27>[u ! Turn it off

These arguments work with the BOLD argument of the PRINT command.

AFTER-BOLD

any string

(none)

See BEFORE-BOLD.

This table lists the fonts that are available in SQR for use with the FONT argument for HPLASERJET printer types.

Value

Typeface

Style

0

Line printer

Fixed

1

Pica

Fixed

2

Elite

Fixed

3

Courier

Fixed

4

Helvetica

Proportional

5

Times Roman

Proportional

6

Letter Gothic

Fixed

8

Prestige

Fixed

11

Presentations

Fixed

17

Optima

Proportional

18

Garamondi

Proportional

19

Cooper Black

Proportional

20

Coronet Bold

Proportional

21

Broadway

Proportional

22

Bauer Bodini Black Condensed

Proportional

23

Century Schoolbook

Proportional

24

University Roman

Proportional

The font that you choose—in orientation, typeface, and point size—must be an internal font, available in a font cartridge, or downloaded to the printer.

For fonts not listed in the Fonts Available for HP LaserJet Printers in SQR table, you must indicate the font style using the FONT-TYPE argument to ensure that the correct typeface is selected by the printer.

This table lists the fonts that are available in SQR for use with the FONT argument for PostScript printer types:

Value

Typeface

Boldface Type Available

3

Courier

Y

4

Helvetica

Y

5

Times Roman

Y

6

Avant Garde Book

NA (Not Applicable)

8

Palatino Roman

Y

11

Symbol

NA

12

Zapf Dingbats

NA

17

Zapf Chancery Medium Italic

NA

18

Bookman Light

NA

23

New Century Schoolbook Roman

Y

30

Courier Oblique

Y

31

Helvetica Oblique

Y

32

Times Italic

Y

33

Avant Garde Demi

NA

34

Avant Garde Book Oblique

NA

35

Avant Garde Demi Oblique

NA

36

Palatino Oblique

Y

37

New Century Schoolbook Italic

Y

38

Helvetica Narrow

Y

39

Helvetica Narrow Oblique

Y

40

Bookman Demi

NA

41

Bookman Light Italic

NA 

42

Bookman Demi Italic

NA

Other type faces can be added to the POSTSCRI.STR file.

Different fonts are available in SQR for Microsoft Windows when you are printing with Microsoft Windows printer drivers (using the -PRINTER:WP command-line flag). When you use the -PRINTER:WP flag, your report is sent directly to the default Microsoft Windows printer. To specify a nondefault Microsoft Windows printer, enter -PRINTER:WP:{printer name}. The {printer name} is the name assigned to your printer. For example, to send output to a Microsoft Windows printer named NewPrinter, you would use -PRINTER:WP:NewPrinter. If your printer name has spaces, enclose the entire argument in quotes.

Fonts are specified by number in the FONT qualifier of the ALTER-PRINTER command.

This table lists the fonts that are available when you are printing with Microsoft Windows printer drivers:

Value

Windows Font/Name

Style

3

Courier New

Fixed

300

Courier New

Bold

4

Arial

Proportional

400

Arial

Bold

5

Times New Roman

Proportional

500

Times New Roman

Bold

6

AvantGarde

Proportional

8

Palatino

Proportional

800

Palatino

Bold

11

Symbol

Proportional

Note: Fonts 6, 8, and 800 are not supplied with Microsoft Windows. You can get these fonts by purchasing the ADOBE Type Manager (ATM). The advantage of using ATM fonts is the compatibility for PostScript printer fonts. The Symbol font uses the SYMBOL_CHARSET instead of the usual ANSI_CHARSET character set. You can add more fonts by editing the appropriate Fonts section in the pssqr.ini file.

See Using the PSPSPSPSSQR.INI File and the PSSQR Command Line.

Parameters

Parameter

Description

printer_name

A unique name to be used for referencing a printer definition and its attributes.

Note: The DECLARE-PRINTER Command Arguments table describes the other arguments of the DECLARE-PRINTER command. The table lists the options, default values, and description of each of the arguments.

Example

The following example illustrates the DECLARE-PRINTER command:

declare-printer HP-definition   ! Default HP definition

type=HP                         ! for all reports

font=4                          ! Helvetica

symbol-set=12U                  ! PC-850 Multilingual
end-declare
declare-printer PS-Sales        ! PS definition

for-reports=(sales)             ! for the Sales report

type=PS

font=5                          ! Times-Roman
end-declare

See ALTER-PRINTER, DECLARE-REPORT

DECLARE-PROCEDURE

Syntax

DECLARE-PROCEDURE [FOR-REPORTS=(report_name1[,report_namei]...)] [BEFORE-REPORT=procedure_name[(arg1[,argi]...)]] [AFTER-REPORT=procedure_name[(arg1[,argi]...)]] [BEFORE-PAGE=procedure_name[(arg1[,argi]...)]] [AFTER-PAGE=procedure_name[(arg1[,argi]...)]] END-DECLARE

Description

Declares procedures that are triggered when a specified event occurs.

The DECLARE-PROCEDURE command can be used to define SQR procedures that are to be invoked before or after a report is printed or before the beginning or end of each page.

Issue the DECLARE-PROCEDURE in the SETUP section. For multiple reports, you can use the command as often as required to declare procedures required by all the reports. If you issue multiple DECLARE-PROCEDURE commands, the last one takes precedence. In this way, you can use one command to declare common procedures for ALL reports and others to declare unique procedures for individual reports. The referenced procedures can accept arguments.

If no FOR-REPORTS are specified, ALL is assumed. Initially, the default for each of the four procedure types is NONE. If a procedure is defined in one DECLARE-PROCEDURE for a report, that procedure is used unless NONE is specified.

Use the USE-PROCEDURE command to change the procedures to be used at runtime. To disable a procedure, specify NONE in the USE-PROCEDURE statement.

Parameters

Parameter

Description

FOR-REPORTS

Specifies one or more reports that use the given procedures. This argument is required only for a program with multiple reports. If you are writing a program that produces only a single report, you can ignore this argument.

BEFORE-REPORT

Specifies a procedure to be run when the first command that causes output to be generated (PRINT) is carried out. It can be used, for example, to create a report heading.

AFTER-REPORT

Specifies a procedure to be run just before the report file is closed at the end of the report. It can be used to print totals or other closing summary information. If no report was generated, the procedure does not run.

BEFORE-PAGE

Specifies a procedure to be run at the beginning of every page, just before the first output command for the page. It can be used, for example, to set up page totals.

AFTER-PAGE

Specifies a procedure to be run just before each page is written to the file. It can be used, for example, to display page totals.

You can optionally specify arguments to be passed to any of the procedures. Arguments can be any variable, column, or literal.

Example

The following example illustrates the DECLARE-PROCEDURE command:

declare-procedure              ! These procedures will

before-report=report_heading   ! be used by all reports

after-report=report_footing
end-declare
declare-procedure             ! These procedures will

for-reports=(customer)        ! be used by the customer

before-page=page_setup        ! report

after-page=page_totals
end-declare

See USE-PROCEDURE

DECLARE-REPORT

Syntax

DECLARE-REPORT report_name [TOC=toc_name] [LAYOUT=layout_name] [PRINTER-TYPE=printer_type] END-DECLARE

Description

Defines reports and their attributes.

Issue the DECLARE-REPORT in the SETUP section.

You can use the DECLARE-REPORT command to declare one or more reports to be produced in the application.

You must use this command when developing applications to produce more than one report.

Multiple reports can share the same layout and the same printer declarations or each report can use its own layout or printer definitions if the report has unique characteristics.

When you are printing multiple reports, unless you specify report names by using the -F command-line flag, the first report declared is generated with the name of program.lis, where program is the application name.

Additional reports are generated with names conforming to the rules dictated by the OUTPUT-FILE-MODE setting in the pssqr.ini file.

When the -KEEP or -NOLIS flag is used, the first intermediate print file (.spf file) is generated with a name of program.spf and additional reports are generated with names conforming to the rules dictated by the OUTPUT-FILE-MODE setting in the pssqr.ini file.

Parameters

Parameter

Description

report_name

Specifies the name of the report.

TOC

Specifies the name of the table of contents for this report.

LAYOUT

Specifies the name of the layout for this report. If no layout is specified, the default layout is used.

PRINTER-TYPE

Specifies the type of printer to be used for this report. If no printer type is specified, the default, LINEPRINTER, is used for this report. If no DECLARE-PRINTER is specified, DEFAULT-LP is used. Valid values for PRINTER-TYPE are HT, HP, PD, PS, LP, HTML, HPLASERJET, POSTSCRIPT, and LINEPRINTER.

Example

The following example illustrates the DECLARE-REPORT command:

declare-layout customer_layout
   left-margin
   right-margin
end-declare

declare-layout summary_layout
   orientation=landscape
end-declare

declare-report customer_detail

toc=detailed

layout=customer_layout

printer-type=postscript
end-declare
declare-report customer_summary

layout=summary_layout

printer-type=postscript
end-declare
.
.
.
use-report customer_detail

...print customer detail...
use-report customer_summary

...print customer summary...

See USE-REPORT, DECLARE-LAYOUT, DECLARE-PRINTER, DECLARE-TOC

DECLARE-TOC

Syntax

DECLARE-TOC toc_name [FOR-REPORTS=(report_name1[,report_namei]...)]
[DOT-LEADER=YES|NO] [INDENTATION=position_count_num_lit] [BEFORE-TOC=procedure_name[(arg1[,argi]...)]] [AFTER-TOC=procedure_name[(arg1[,argi]...)]] [BEFORE-PAGE=procedure_name[(arg1[,argi]...)]] [AFTER-PAGE=procedure_name[(arg1[,argi]...)]] [ENTRY=procedure-name [(argi [,argi] ...)]] END-DECLARE

Description

Defines the table of contents and its attributes.

Use DECLARE-TOC in the SETUP section.

You can use the DECLARE-TOC command to declare one or more tables of contents for the application.

A table of contents can be shared between reports.

Parameters

Parameter

Description

toc_name

Specifies the name of the table of contents.

FOR-REPORTS

Specifies one or more reports that use this table of contents.

DOT-LEADER

Specifies whether a dot leader precedes the page number. The default setting is NO.

INDENTATION

Specifies the number of spaces by which each level is indented. The default setting is 4.

BEFORE-TOC

Specifies a procedure to be run before the application generates the table of contents. If no table of contents is generated, the procedure does not run.

AFTER-TOC

Specifies a procedure to be run after the application generates the table of contents. If no table of contents is generated, the procedure does not run.

BEFORE-PAGE

Specifies a procedure to be run at the start of every page.

AFTER-PAGE

Specifies a procedure to be run at the end of each page.

ENTRY

Specifies a procedure that is run to process each table of contents entry (instead of SQR doing it for you). When this procedure is invoked, the following SQR-reserved variables are populated with data about the TOC entry:

#SQR-TOC-LEVEL contains the level.

#SQR-TOC-TEXT contains the text.

#SQR-TOC-PAGE contains the page number.

These are global variables. If the procedure is local, you must precede it with an underscore (for example, #_sqr-toc-page). These three SQR-reserved variables are valid only within the scope of the ENTRY procedure. They can be referenced outside the scope, but their contents are undefined.

Example

The following example illustrates the DECLARE-TOC command:

begin-setup
  declare-toc common
    for-reports=(all)
    dot-leader=yes
    indentation=2
end-declare
end-setup
.
.
.
toc-entry level=1 text=$Chapter
toc-entry level=2 text=$Heading
.
.

See BEGIN-FOOTING, BEGIN-HEADING, DECLARE-REPORT, TOC-ENTRY

DECLARE-VARIABLE

Syntax

DECLARE-VARIABLE [DEFAULT-NUMERIC={DECIMAL[(prec_lit)]|FLOAT|INTEGER}] [DECIMAL[(prec_lit)]num_var[(prec_lit)][num_var [(prec_lit)]]...]
[FLOAT num_var[num_var]...] [DATE date_var[date_var]...] [INTEGER num_var[num_var]...] [TEXT string_var[string_var]...] END-DECLARE

Description

Enables you to explicitly declare a variable type.

You can set the default numeric type externally, using the -DNT command-line flag or the DEFAULT-NUMERIC setting in the Default-Settings section of the pssqr.ini file. However, the setting in the DECLARE-VARIABLE command takes precedence over all other settings. If the command has not been used, then the -DNT command-line flag takes precedence over the setting in the pssqr.ini file.

In addition to FLOAT, INTEGER, and DECIMAL, you can set DEFAULT-NUMERIC in the pssqr.ini file and the -DNT command-line flag to V30. With V30, the program acts in the same manner as in versions prior to release 4.0; that is, all variables are FLOAT. V30 is not a valid setting for the DEFAULT-NUMERIC setting in the DECLARE-VARIABLE command.

The DECLARE-VARIABLE command enables you to determine the type of variables to use. This command can appear only in the SETUP section or as the first statement of a local procedure. The placement of the command affects its scope. When used in the SETUP section, it affects all variables in the entire program. Alternatively, when it is placed in a local procedure, its effect is limited to the scope of the procedure. If the command is in both places, the local declaration takes precedence over the SETUP declaration.

In addition to declaring variables, this command enables you to specify the default numeric type using the DEFAULT-NUMERIC setting as FLOAT, INTEGER, or DECIMAL. When dealing with money or when more precision is required, use the DECIMAL qualifier.

The DECLARE-VARIABLE command, the -DNT command-line flag, and the DEFAULT-NUMERIC setting in the pssqr.ini file affect the way numeric literals are typed. If V30 is specified, then all numeric literals are FLOAT (just as in versions prior to release 4.0); otherwise, the use or lack of a decimal point determines the type of the literal as either FLOAT or INTEGER, respectively. Finally, not specifying the DECLARE-VARIABLE command, the -DNT command-line flag, and the DEFAULT-NUMERIC setting in the pssqr.ini file is the same as specifying V30.

Parameters

Parameter

Description

DEFAULT-NUMERIC

Specifies the default type for numeric variables. Unless explicitly declared otherwise, a numeric variable assumes the variable type. This qualifier overrides any setting from the command-line flag -DNT or the DEFAULT- NUMERIC entry in the [Default-Settings] section of the pssqr.ini file. If -DNT was not specified on the command line and the pssqr.ini file entry has no DEFAULT-NUMERIC entry, then the default numeric type is FLOAT.

DECIMAL

Specifies that the numeric variables that follow are decimal variables with a precision specified with prec_lit. The precision can be assigned to the group of variables or to each individual variable. The precision is the total number of digits used to represent the number. This precision can range from 1 to 38. The default value is 16. The range of decimal numbers is from –9.9999999999999999999999999999999999999E±4096 to +9.9999999999999999999999999999999999999E±4096

FLOAT

Specifies that the numeric variables that follow are used as double-precision floating points. The range and precision of these numbers are machine-dependent.

DATE

Specifies that the date variables that follow can contain a date in the range of January 1, 4713 BC to December 31, 9999 AD.

INTEGER

Specifies that the numeric variables that follow are used as integers with a range of –2147483648 to +2147483647.

TEXT

Specifies that the string variables that follow are text variables.

Example

The following example illustrates the DECLARE-VARIABLE command:

begin-setup
  declare-variable 
    default-numeric=float
    decimal  #decimal(10)
    integer  #counter
    date     $date
  end-declare
end-setup
.
.
let $date = strtodate('Jan 01 2004','Mon DD YYYY')
print $date (1,1)
position (+2,1)

let #counter = 0
while #counter < 10
 let #decimal = sqrt(#counter)
 add 1 to counter
 print #decimal  (+1,1) 9.999999999
end-while

do sub1($date, 'day', 10)

do sub2

.
.
begin-procedure sub1(:$dvar, $units, #uval)
declare-variable
 date $dvar
 integer #uval
end-declare
let $dvar = dateadd($dvar, $units, #uval)
print $dvar (+1,1)
position (+2,1)
end-procedure
.
.
begin-procedure sub2 LOCAL
declare-variable
 date $mydate
end-declare
let $mydate = dateadd($_date, 'year', 5)
print $mydate (+1,1)
position (+2,1)
end-procedure
.
.

#DEFINE

Syntax

#DEFINE substitution_variable value

Description

Declares a value for a substitution variable within the body of the report (rather than using the ASK command).

#DEFINE is useful for specifying constants such as column locations, printer fonts, or any number or string that is used in several locations in the program. When the value of the number or string must be changed, you need only change the #DEFINE command. All references to that variable change automatically, which makes modifying programs much simpler.

If the ASK command is used to obtain the value of a substitution variable that has already been defined, ASK uses the previous value and the user is not prompted. This enables you to predefine some variables and not others. When the report runs, ASK requests values for only those variables that have not had a value assigned.

You can use #DEFINE commands inside an include file. This is a method of gathering commonly used declarations into one place, and reusing them for more than one report.

The value in the #DEFINE command can have embedded spaces and does not need to be enclosed within quotes. The entire string is used as is.

The #DEFINE command cannot be broken across program lines.

Parameters

Parameter

Description

substitution_variable

The variable to be used as the substitution variable. The substitution variable is used to substitute any command, argument, or part of a SQL statement at compile time.

Value

The value to be substituted.

Example

This code example defines several constants:

#define  page_width  8.5
#define  page_depth  11
#define  light LS^10027
#define  bold  LS^03112
#define  col1  1
#define  col2  27
#define  col3  54
#define  order_by  state, county, city, co_name

This code example from a report uses the definitions from the preceding example:

   begin-setup

declare-printer contacts

   type=hp

   paper-size=({page_width}, {page_depth})

end-declare
end-setup
begin-heading 5
  print 'Company Contacts'     (1,1)  center
  print 'Sort:  {order_by}'    (2,1)  center
  print 'Company'              (4,{col1})
  print 'Contact'              (4,{col2})
  print 'Phone'                (4,{col3})
end-heading
begin-procedure main
begin-select
company      (1,{col1})
  print '{bold}'      (0,{col2})         ! Print contact in boldface.
contact         ()
  print '{light}'         ()             ! Back to lightface.
phone         (0,{col3})                 ! Note: There must be enough
  next-listing                           ! space between col2
from customers                           ! and col3 for both
order by  {order_by}                     ! font changes and the
end-select                               ! contact field.
end-procedure

See ASK

DISPLAY

Syntax

DISPLAY {any_lit|_var|_col} [[:$]edit_mask|NUMBER|MONEY|DATE][NOLINE]

Description

Displays the specified column, variable, or literal.

The DISPLAY command can display data to a terminal. The data is displayed to the current location on the screen. If you want to display more than one field on the same line, use NOLINE on each display except the last.

Dates can be contained in a date variable or column, or a string literal, column, or variable. When a date variable or column is displayed without an edit mask, the date appears in the following manner:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the DATE Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the TIME Column Formats table.

When the program displays a date in a string literal, column, or variable using EDIT or DATE, the string uses the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats as listed in the Default Database Formats table, or the database-independent format SYYYYMMDD[HH24[MI[SS[NNNNNN]]]].

If you require more control over the display, use the SHOW command.

Parameters

Parameter

Description

any_lit|_var|_col

The text, number, or date to be displayed.

edit_mask

Causes the field to be edited before being displayed. For additional information regarding edit masks, see the PRINT command.

NUMBER

Indicates that any_lit|_var|_col is to be formatted using the NUMBER-EDIT-MASK of the current locale. This option is not valid with date variables.

MONEY

Indicates that any_lit|_var|_col is to be formatted using the MONEY-EDIT-MASK of the current locale. This option is not valid with date variables.

DATE

Indicates that any_lit|_var|_col is to be formatted using the DATE-EDIT-MASK of the current locale. This option is not valid with numeric variables. If DATE-EDIT-MASK has not been specified, the date is displayed by the default format for that database (see the Default Database Formats table).

NOLINE

Suppresses the carriage return after the field is displayed.

Example

The following segments illustrate the various features of the DISPLAY command:

 !
 ! Display a string using an edit mask
 !
 display '123456789' xxx-xx-xxxx

Produces the following output:

123-45-6789


!
 ! Display a number using an edit mask
 !
 display 1234567.89 999,999,999.99

Produces the following output:

1,234,567.89

!
 ! Display a number using the default edit mask (specified in PSPSPSSQR.INI)
 !
 display 123.78

Produces the following output:

123.780000

!
 ! Display a number using the locale default numeric edit mask
 !
 alter-locale  number-edit-mask = '99,999,999.99'
 display 123456.78 number

Produces the following output:

123,456.78

!
 ! Display a number using the locale default money edit mask
 !
 alter-locale  money-edit-mask = '$$,$$$,$$9.99'
 display 123456.78 money

Produces the following output:

$123,456.78

!
 ! Display a date column using the locale default date edit mask
 !
 begin-select
 dcol
  from tables
 end-select
 alter-locale  date-edit-mask = 'DD-Mon-YYYY'
 display &dcol date

Produces the following output:

01-Jan-2004

!
 ! Display two values on the same line
 !
 display 'Hello' noline
 display ' World'

Produces the following output:

Hello World

!
 ! Display two values on the same line with editing of the values
 !
 alter-locale  money-edit-mask = '$$,$$$,$$9.99'
 let #taxes = 123456.78
 display 'You owe ' noline
 display #taxes money noline
 display ' in back taxes.'

Produces the following output:

You owe $123,456.78 in back taxes.

See The SHOW command for information about screen control

See The LET command for information about copying, editing, or converting fields

See The EDIT parameter of the PRINT command for a description of the edit masks

See The ALTER-LOCALE command for a description of the arguments NUMBER-EDIT-MASK, MONEY-EDIT-MASK, and DATE-EDIT-MASK

DIVIDE

Syntax

DIVIDE {src_num_lit|_var|_col} INTO dst_num_var [ON-ERROR={HIGH|ZERO}][ROUND=nn]

Description

Divides one number into another.

The source field is divided into the destination field and the result is placed in the destination. The source is always first, the destination always second.

When dealing with money-related values (dollars and cents), use decimal variables rather than float variables. Float variables are stored as double-precision floating-point numbers, and small inaccuracies can appear when many numbers are divided in succession. These inaccuracies can appear due to the way different hardware and software implementations represent floating point numbers.

Parameters

Parameter

Description

src_num_lit|_var|_col

Divided into the contents of dst_num_var.

dst_num_var

Contains the result after execution.

ON-ERROR

Sets the result to the specified number when a division by zero is attempted. If ON-ERROR is omitted and a division by zero is attempted, SQR halts with an error message.

ROUND

Rounds the result to the specified number of digits to the right of the decimal point. For float variables, this value can be from 0 to 15. For decimal variables, this value can be from 0 to the precision of the variable. For integer variables, this argument is not appropriate.

Example

The following example illustrates the DIVIDE command:

divide  37.5  into  #price   ! #price / 37.5
divide  &rate  into  #tot  on-error=high
divide  #j  into  #subtot  on-error=zero

Note: In the preceding example, High is the maximum value and zero is the lowest value.

See ADD

See The LET command for a discussion of complex arithmetic expressions

DO

Syntax

DO procedure_name[(arg1[, argi]...)]

Description

Invokes the specified procedure.

When the procedure ends, processing continues with the command following the DO command. You can use arguments to send values to or receive values from a procedure.

Arguments passed by a DO command to a procedure must match in number:

  • Database text columns, string variables, and literals can be passed to procedure string or date arguments.

  • Database numeric columns, numeric variables, and numeric literals can be passed to procedure numeric arguments.

  • Numeric variables (DECIMAL, INTEGER, FLOAT) can be passed to procedure numeric arguments without regard to the argument type of the procedure.

    SQR automatically converts the numeric values upon entering and leaving the procedure as required.

  • Date variables can be passed to procedure date or string arguments.

When a field in a DO command receives a value back from a procedure (a colon indicates that it is a back value, that is, a value that is being returned), it must be a string, numeric, or date variable, depending on the procedure argument; however, a date can be returned to a string variable and vice versa.

When a date is passed to a string, the date is converted to a string according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the DATE Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

Parameters

Parameter

Description

procedure_name

Specifies the name of the procedure to be run.

arg1 [, argi ]

Specifies the arguments to be passed to the procedure. Arguments can be any type of variable or constant value.

Example

The following example illustrates the DO command:

do get_names
do add_to_list ($name)
do print_list ('A', #total, &co_name, $name)

See The BEGIN-PROCEDURE command for information about passing arguments

See The PRINT command for information about date and time formats

#ELSE

Syntax

#ELSE

Description

Compiles the code following the #ELSE command when a preceding #IF, #IFDEF, or #IFNDEF command is FALSE. (#ELSE is a compiler directive that works with the #IF, #IFDEF, and #IFNDEF compiler directives.)

Related Links

See Also:The #IF, #IFDEF, and #IFNDEF commands for a description of each compiler directive.

ELSE

Syntax

ELSE

Description

ELSE is an optional command in an IF command.

Related Links

See Also:The IF command for a description and example.

ENCODE

Syntax

ENCODE src_code_string_lit INTO dst_txt_var

Description

Assigns a nondisplay or display character to a string variable.

The ENCODE command can define nondisplay characters or escape sequences sent to an output device. These characters or sequences can perform complex output device manipulations. The ENCODE command also displays characters not on the keyboard. If your keyboard does not have the euro symbol, use the ENCODE feature to create a string variable for it.

The encode characters can be included in a report at the appropriate location using a PRINT or PRINT-DIRECT command.

Unicode (UCS-2) code that points from <1> to <65535> can be defined in the ENCODE command.

Parameters

Parameter

Description

src_code_string_lit

Specifies a string of characters to be encoded and placed in dst_txt_var.

dst_txt_var

Contains the result after execution.

Example

The following example illustrates the ENCODE command:

encode '<27>L11233' into $bold            ! Code sequence to turn bold on.
print $bold () code-printer=lp

See The chr function described in the Miscellaneous Functions table under the LET command

See PRINT, PRINT-DIRECT

END-DECLARE, END-DOCUMENT, END-EVALUATE, END-FOOTING, END-HEADING

Syntax

END-DECLARE END-DOCUMENT END-EVALUATE END-FOOTING
END-HEADING

Description

Completes a section or paragraph.

The END-DECLARE command completes a paragraph started with:

DECLARE-CHART
DECLARE-IMAGE
DECLARE-LAYOUT
DECLARE-PRINTER
DECLARE-PROCEDURE
DECLARE-REPORT
DECLARE-VARIABLE

Other END- commands complete the corresponding BEGIN- command:

BEGIN-DOCUMENT
EVALUATE
BEGIN-FOOTING
BEGIN-HEADING

Each command must begin on its own line.

Example

The following example illustrates the BEGIN-FOOTING and END-FOOTING commands:

begin-footing  2
   print  'Company Confidential'  (1)  center
end-footing

See DECLARE-paragraph, BEGIN-section

#END-IF, #ENDIF

Syntax

#END-IF

Description

Ends an #IF, #IFDEF, or #IFNDEF command. (#END-IF is a compiler directive.)

#ENDIF (without the hyphen) is a synonym for #END-IF.

Example

The following example illustrates the #END-IF compiler directive:

#ifdef debuga
  show  'DebugA: #j = '  #j  edit  9999.99
  show  'Cust_num   = '  &cust_num
#end-if

See commands for a description of each compiler directiveThe #IF, #IFDEF, #IFNDEF

END-IF

Syntax

END-IF

Ends an IF command.

See The IF command for a description and example

END-PROCEDURE, END-PROGRAM, END-SELECT, END-SETUP, END-SQL, END-WHILE

Syntax

END-PROCEDURE END-PROGRAM END-SELECT END-SETUP
END-SQL END-WHILE

Description

Completes the corresponding section or paragraph.

Each END- command completes the corresponding BEGIN- command:

BEGIN-PROCEDURE
BEGIN-PROGRAM
BEGIN-SELECT
BEGIN-SETUP
BEGIN-SQL
WHILE

Each command must begin on its own line.

Example

The following example illustrates the END-PROGRAM command:

begin-program
   do main
end-program

See BEGIN-section, WHILE

EVALUATE

Syntax

EVALUATE {any_lit|_var|_col}

This command is equivalent to case/switch in C or Java. The general format of an EVALUATE command is:

EVALUATE {any_lit|_var|_col} WHEN comparison_operator
{any_lit|_var|_col} SQR_Command...
[BREAK] [WHEN comparison_operator {any_lit|_var|_col} SQR_Command... [BREAK]] [WHEN-OTHER SQR_Command... [BREAK]] END-EVALUATE

Description

Determines the value of a column, literal, or variable and takes action based on that value.

The EVALUATE command is useful for branching to different commands depending on the value of a specified variable or column.

EVALUATE commands can be nested.

Evaluating a date variable or column with a string results in a date comparison (chronological, not a byte-by-byte comparison as is done for strings). The string must be in the proper format as shown in the following list:

  • For DATETIME columns and SQR DATE variables in the format specified by the SQR_DB_DATE_FORMAT setting, SQR uses one of the database-dependent formats (see the Default Database Formats table), or the database-independent format 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]'.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting, or the format listed in the DATE Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting, or the format as listed in the TIME Column Formats table.

Parameters

Parameter

Description

any_lit|_var|_col

Specifies a text or numeric column; a text, numeric, or date variable; or a text or numeric literal to be used in the evaluation. In short, this is an evaluation argument.

comparison_operator

Any valid comparison operator. See the list of operators in the #IF command.

See #IF.

WHEN

Specifies the evaluation expression. The evaluation argument is compared with the argument, beginning from the first WHEN. If the expression is TRUE, SQR processes the commands after the WHEN. If the expression is FALSE, SQR processes the next WHEN expression. Each WHEN must be on its own line.

If more than one WHEN expression appears directly before a set of commands, any one of them, if TRUE, causes the commands to be carried out.

BREAK

Causes an immediate exit of the EVALUATE command. Use BREAK at the end of a set of commands.

WHEN-OTHER

Signifies the start of default commands to be processed if all other WHEN expressions are FALSE. WHEN-OTHER must appear after all other WHEN expressions.

Example

The following example illustrates the EVALUATE command:

evaluate &code
  when = 'A'
     move 1 to #j
     break
  when = 'B'
  when = 'C'
     move 2 to #j     ! Will happen if &code is B or C.
     break
  when > 'D'
     move 3 to #j     ! Move 3 to #j and continue checking.
  when > 'H'
     add 1 to #j      ! Add 1 to #j and continue checking.
  when > 'W'
     add 2 to #j
     break
  when-other
     if isnull (&code)
         do null_code
      else
         move 0 to #j  ! Unknown code.
     end-if
     break
end-evaluate 

See The commands IF and LET for comparison operators

EXECUTE (Sybase and Microsoft SQL Server)

Syntax

EXECUTE [-XC][ON-ERROR=procedure[(arg1[,argi]...)]]
[DO=procedure[(arg1[,argi]...)]] [@#status_var=]stored_procedure_name
[[@param=]{any_col|_var|_lit}[,...]] [INTO any_coldata_type[(length_int_lit)]
[,...]][WITH RECOMPILE]

The syntax of this command generally follows that of the Sybase Transact-SQL EXECUTE command, with the exception of optional arguments and the INTO argument.

Description

Runs a stored procedure in Sybase or Microsoft SQL Server database.

If the stored procedure specified in stored_procedure_name contains a SELECT query, the EXECUTE command must specify an INTO argument to process the values from the query. If no INTO argument is specified, then the values from the query are ignored.

EXECUTE retrieves just the first row when the following conditions are met:

  • The DO procedure is not specified.

  • The stored procedure, stored_procedure_name, selects one or more rows.

  • An INTO argument is specified.

This is useful for queries returning a single row.

Parameters

Parameter

Description

-XC

(Sybase only) Specifies that the EXECUTE command share the same connection as the DO=procedure it can invoke. This argument is required to share Sybase temporary tables.

ON-ERROR

Declares an SQR procedure to run if an error occurs. If ON-ERROR is omitted and an error occurs, SQR halts with an error message. For severe errors (for example, passing too few arguments) SQR halts, even if an error procedure is specified.

You can specify arguments to be passed to the ON-ERROR procedure. Arguments can be any variable, column, or literal.

DO

Specifies an SQR procedure to run for each row selected in the query. Processing continues until all rows have been retrieved. You can specify arguments to be passed to the procedure. Arguments can be any variable, column, or literal.

@#status_variable

Returns the procedure status in the specified numeric variable. The status is returned only after selected rows are retrieved.

stored_procedure_name

Names the stored procedure to run.

@param

Names the parameter to pass to the stored procedure. Parameters can be passed with or without names. If used without names, they must be listed in the same sequence as defined in the stored procedure.

any_lit|_var|_col

Specifies the value passed to the stored procedure. It can be a string, numeric, or date variable, a previously selected column, a numeric literal, or a string literal.

OUT[PUT]

Indicates that the parameter receives a value from the stored procedure. The parameter must be a string, numeric, or date SQR variable. Output parameters receive their values only after rows selected have been retrieved. If you specify multiple output parameters, they must be in the same sequence as defined in the stored procedure.

INTO

Indicates where to store rows that are retrieved from the stored procedure's SELECT statement. The INTO argument contains the names of the columns with data types and lengths (if needed). You must specify the columns in the same sequence and match the data type used in the stored procedure's SELECT statement.

If the stored procedure contains more than one SELECT query, only the first query is described with the INTO argument. Rows from subsequent queries are ignored.

WITH RECOMPILE

Causes the query to recompile each time it is run rather than using the plan stored with the procedure. Normally, this is not required or recommended.

Example

The following code example invokes the stored procedure get_total with two parameters: a string literal and a string variable. The result from the stored procedure is stored in the variable #total.

execute get_total 'S. Q. Reporter' $State #Total Output

The following code example invokes the stored procedure get_products with two parameters. The stored procedure selects data into five column variables. The SQR procedure print_products is called for each row retrieved. The return status from the stored procedure is placed in the variable #proc_return_status.

execute do=print_products
   @#proc_return_status=
   get_products
   @prodcode=&code,            @max=#maximum
   INTO &prod_code         int,
      &description         char (45),
      &discount         float,
      &restock         char,
      &expire_date         datetime

begin-procedure print_products
print &prod_code            (+1,1)
print &description            (+5,45)
print &discount            (+5) edit 99.99
print &restock            (+5) match Y 0 5 Yes N 0 5 No
print &expire_date            (+5,) edit 'Month dd, yyyy'
end-procedure

EXIT-SELECT

Syntax

EXIT-SELECT

Description

Exits a SELECT paragraph immediately.

EXIT-SELECT causes SQR to jump to the command immediately following the END-SELECT command.

Use EXIT-SELECT when you need to end a query before all rows have been retrieved.

Example

The following example illustrates the EXIT-SELECT command:

begin-select
cust_num, co_name, contact, city, state, zip, employees
  add &employees to #tot_emps
  if #tot_emps >= 5000
    exit-select         ! Have reached required total emps.
  end-if
  do print_company
from customers order by employees desc
end-select

See BEGIN-SELECT

EXTRACT

Syntax

EXTRACT {dst_txt_var|date_var} FROM {{src_txt_lit|_var|_col}|{src_date_var|_col}} {start_num_lit|_var}{length_num_lit|_var}

Description

Copies a portion of a string into a string variable.

You must specify the starting location of the string as an offset from the beginning of the string and its length. An offset of 0 (zero) begins at the leftmost character; an offset of 1 begins one character beyond that, and so on.

If the source is a date variable or column, it is converted to a string before the extraction according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR specifies the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the DATE Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

If the destination is a date variable, the string extracted from the source must be in one of the following formats:

  • The format specified by the SQR_DB_DATE_FORMAT setting.

  • One of the database-dependent formats (see the Default Database Formats table).

  • The database-independent format 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]'.

Parameters

Parameter

Description

dst_txt_var | date_var

Specifies a text or date variable into which the extracted string is placed.

{src_txt_lit|_var|_col}|

{src_date_var|_col}

Specifies a text or date variable, column, or literal from which the string is to be extracted.

start_num_lit|_var

Specifies starting location of the string to be extracted.

length_num_lit|_var

Specifies length of the string to be extracted.

Example

The following example illustrates the EXTRACT command:

extract  $state  from  $record  45  2
extract  $foo from "SQR Rocks" 0 4 ! $foo='SQR'

code  from  &phone  0  3
extract  $zip_four  from  &zip  5  4
extract  $rec  from  $tape_block  #loc  #rec_len

Note: Oracle recommends that you not use the EXTRACT command when processing strings.

See The substr function described in the Miscellaneous Functions table under the LET command

See FIND

See The PRINT command for information about default date and time formats

FIND

Syntax

FIND {{obj_txt_lit|_var|_col}|{date_var|_col}} IN {{src_txt_var|_col}|{date_var|_col}} {start_int_lit|_var} dst_location_int_var

Description

Determines the location of a character sequence within a string.

FIND searches the specified string for a character sequence and, if the string is found, returns its location as an offset from the beginning of the specified string. If the sequence is not found, FIND returns –1 in dst_location_int_var.

You must specify an offset from which to begin the search and supply a numeric variable for the return of the location.

If the source or search object is a date variable or column, it is converted to a string before the search according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the DATE Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

Parameters

Parameter

Description

{obj_txt_lit|_var|_col}|{date_var|_col}

Specifies a text variable, column, or literal that is to be sought in src_txt_var|_col.

{src_txt_var|_col}|

{date_var|_col}

Specifies a text variable or column to be searched.

start_int_lit|_var

Specifies the starting location of the search.

dst_location_int_var

Specifies the returned starting location of the leftmost character of the matching text in {src_txt_var|_col| date_var|_col }.

Example

The following example illustrates the FIND command:

find  'aw.2'  in  &code5  0  #loc
find  ','  in  &name  0  #comma_loc
if #comma_loc = -1
   ...comma not found...

See The instr function described in the Miscellaneous Functions table under the LET command

See EXTRACT

See The PRINT command for information about default date and time formats

GET

Syntax

GET dst_any_var...FROM src_array_name(element) [field[(occurs)]]...

Description

Retrieves data from an array and places it into a date, string, or numeric variable.

Parameters

Parameter

Description

dst_any_var

Date, string, or numeric variables (not database columns) can be destination variables. Numeric variables (decimal, float, integer) are copied from number fields. String variables are copied from the char, text, or date field. Date variables are copied from the char, text, or date field.

When a date field is copied to a string variable, SQR converts the date to a string in the format specified by the SQR_DB_DATE_FORMAT setting. If this has not been set, SQR uses the first database-dependent format listed in the Default Database Formats table.

If the destination is a date variable, the string extracted from the source must be in the format specified by the SQR_DB_DATE_FORMAT setting, or one of the database-dependent formats (see the Default Database Formats table), or the database-independent format 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]'.

src_array_name(element)

If the array's field names are listed, SQR takes the values from the fields and occurrences specified. If the array's field names are not listed, the values are taken from consecutively defined fields in the array.

field[(occurs)]

Array element and field occurrence numbers can be numeric literals (such as 123) or numeric variables (such as #j). If no field occurrence is stated, occurrence zero is used.

Example

The following code example copies $name, $start_date, and #salary from the first three fields in the #jth element of the emps array:

get $name $start_date #salary from emps(#j)

The following code example copies #city_tot and #county_tot from the fields cities and counties in the #jth element of the states array:

get #city_tot #county_tot from states(#j) cities counties

The following code example copies $code from the #jth occurrence of the code field in the #nth element of the codes array:

get $code from codes(#n) code(#j)

See The PUT command for information about moving data into an array

GET-COLOR

Syntax

GET-COLOR [PRINT-TEXT-FOREGROUND=({color_name_var |{rgb})] [PRINT-TEXT-BACKGROUND=({color_name_var |{rgb})]

Description

Retrieves the current colors.

The GET-COLOR command is allowed wherever the PRINT command is allowed. If the requested color settings do not map to a defined name, the name is returned as RGBredgreenblue, where each component is a three-digit number—for example, RGB127133033. You can use this format wherever you use a color name. The color name 'none' is returned if no color is associated with the specified area.

Parameters

Parameter

Description

PRINT-TEXT-

FOREGROUND

Defines the color in which the text prints.

PRINT-TEXT-

BACKGROUND

Defines the color to print as a background behind the text.

{color_name_var}

A color_name is composed of alphanumeric characters (A–Z, 0–9), the underscore (_) character, and the hyphen (-) character. The name must start with an alphabetical (A–Z) character and is not case-sensitive. The name 'none' is reserved and cannot be assigned a value. A name in the format (RGBredgreenblue) cannot be assigned a value. The name 'default' is reserved and can be assigned a value. 'Default' is used during execution when a referenced color is not defined in the runtime environment.

{rgb}

red_lit | _var | _col, green_lit | _var | _col, blue_lit | _var | _col where each component is a value in the range of 000 to 255. In the BEGIN-SETUP section, only literal values are allowed.

The default colors implicitly installed with SQR include:

black=(0,0,0)

white=(255,255,255)

gray=(128,128,128)

silver=(192,192,192)

red=(255,0,0)

green=(0,255,0)

blue=(0,0,255)

yellow=(255,255,0)

purple=(128,0,128)

olive=(128,128,0)

navy=(0,0,128)

aqua=(0,255,255)

lime=(0,128,0)

maroon=(128,0,0)

teal=(0,128,128)

fuchsia=(255,0,255)

Example

The following example illustrates the GET-COLOR command:

begin-setup
   declare-color-map
   light_blue = (193, 222, 229)
   end-declare
end-setup

begin-program
   alter-color-map name = 'light_blue' value = (193, 233, 230)

   print 'Yellow Submarine' ()
      foreground = ('yellow')
      background = ('light_blue')

   get-color print-text-foreground = ($print-foreground)  
   set-color print-text-foreground = ('purple')
   print 'Barney' (+1,1)
   set-color print-text-foreground = ($print-foreground)
end-program

See DECLARE-COLOR-MAP, ALTER-COLOR-MAP, SET-COLOR

GOTO

Syntax

GOTO  label

Description

Skips to the specified label.

Labels must end with a colon (:) and can appear anywhere within the same section or paragraph as the GOTO command.

Parameters

Parameter

Description

label

Specifies a label within the same section or paragraph.

Example

The following example illustrates the GOTO command:

begin-select
price
 if &price < #old_price
    goto next
 end-if
 print &price (2,13,0) edit 999,999.99
   ...
next:
 add 1 to #count
from products
end-select

GRAPHIC BOX, GRAPHIC HORZ-LINE, GRAPHIC VERT-LINE

Syntax

The GRAPHIC commands have the following syntax:

GRAPHIC ({line_int_lit|_var},{column_int_lit|_var},
{width_int_lit|_var})  BOX {depth_int_lit|_var} [rule_width_int_lit|_var[shading_int_lit|_var]]
 GRAPHIC ({line_int_lit|_var},{column_int_lit|_var}, {length_int_lit|_var})
 HORZ-LINE [rule_width_int_lit|_var]  GRAPHIC ({line_int_lit|_var},{column_int_lit|_var},
{length_int_lit|_var})  VERT-LINE [rule_width_int_lit|_var]

Description

Draws a box or line.

After GRAPHIC commands are carried out, SQR changes the current print location to the starting location of the graphic. This is different from the way the PRINT command works.

The GRAPHIC command has the following variations:

  • BOX

  • HORZ-LINE

  • VERT-LINE

The following sections describe the individual GRAPHIC commands:

Parameters

Parameter

Description

BOX

BOX draws a box of any size at any location on the page. Boxes can be drawn with any size rule and can be shaded or left empty.

width and depth

The width is the horizontal size in character columns; depth is the vertical size in lines. The top left corner of the box is drawn at the line and column specified. The bottom right corner is calculated by the width and depth. You can specify relative placement with (+), (-), or numeric variables, as with regular print positions.

rule_width

The default rule width is 2 decipoints (an inch has 720 decipoints). The top horizontal line is drawn just below the base of the line above the starting point. The bottom horizontal line is drawn just below the base of the ending line. Therefore, a one-line deep box surrounds a single line.

shading

A number between 1 and 100, specifying the percentage of shading to apply. 1 is very light, and 100 is black. If no shading is specified, the box is blank. Specify a rule-width of zero if you do not want a border.

HORZ-LINE

HORZ-LINE draws a horizontal line from the location specified, for the length specified. Horizontal lines are drawn just below the base.

rule_width

The default rule width is 2 decipoints.

VERT-LINE

VERT-LINE draws a vertical line from the location specified for the length (in lines) specified. Vertical lines are drawn just below the base line of the line position specified to just below the base line of the line reached by the length specified. To draw a vertical line next to a word printed on line 27, position the vertical line to begin on line 26, for a length of 1 line.

rule_width

The default rule width is 2 decipoints.

Example

The following code example shows the GRAPHIC BOX command:

graphic (1,1,66) box 58 20     ! Draw box around page
graphic (30,25,10) box 10      ! Draw a 10-characters-wide-by-10- characters-long box
graphic (1,1,66) box 5 0 8     ! Draw 5 line shaded box (without border)
graphic (50,8,30) box 1        ! Draw box around 1 line

The following code example shows the GRAPHIC HORZ-LINE command:

graphic (4,1,66) horz-line 10  ! Put line under page heading
graphic (+1,62,12) horz-line   ! Put line under final total

The following code example shows the GRAPHIC VERT-LINE command:

graphic (1,27,54) vert-line    ! Draw lines between columns
graphic (1,52,54) vert-line
graphic (3,+2,4) vert-line 6   ! Red line the paragraph

See The ALTER-PRINTER and DECLARE-PRINTER commands for information about setting and changing the FONT, FONT-TYPE, POINT-SIZE, and PITCH

#IF

Syntax

#IF {txt_lit|num_lit}comparison_operator {txt_lit|num_lit}

Description

Indicates that the commands following #IF are to be compiled when the expression is TRUE. (#IF is a compiler directive.)

SQR has five compiler directives that enable different pieces of SQR code to be compiled, depending on the existence or value of substitution variables (not program variables, such as string, numeric, or date).

Substitution variables defined automatically for each -DEBUGxxx letter can also be used with the #IF, #IFDEF, and #IFNDEF directives. They can enable or disable entire sections of an SQR program from the command line, depending on the -DEBUGxxx flag.

You can nest #IF, #IFDEF, and #IFNDEF directives to a maximum of 10 levels.

The #IF, #IFDEF, and #IFNDEF directives cannot be broken across program lines.

The following table lists the compiler directives.

Directive

Example

Description

#IF

#IF {option}='A'

Compiles the commands following the #IF directive if the substitution variable option is equal to 'A'. The test is not case-sensitive. Only one simple expression is allowed per #IF command.

#ELSE

#ELSE

Compiles the commands following the #ELSE directive when the #IF expression is FALSE.

#ENDIF

#ENDIF

Ends the #IF directive. #ENDIF can also be typed #END-IF (with a hyphen).

#IFDEF

#IFDEF option

Compiles the commands following the #IFDEF directive if the substitution variable option is defined.

#IFNDEF

#IFNDEF option

Compiles the command following the #IFNDEF directive if the substitution variable option is not defined.

Parameters

Parameter

Description

txt_lit | num_lit

Any text or numeric literal.

comparison_operator

Any of the comparison operators as shown here:

=Equal

!=Not Equal

<>Not Equal

<Less than

>Greater than

<=Less than or equal

>=Greater than or equal

Example

The following example illustrates the #IF compiler directive:

begin-setup 
  ask type 'Use Male, Female or Both (M,F,B)'
end-setup
begin-procedure Main
#if {type} = 'M' 
  ...code for M here
#else
#if {type} = 'F'
  ...code for F here
#else
#if {type} = 'B'  
  ...code for B here
#else
  show 'M, F or B not selected.   Report not created.' 
  stop
#endif   ! for B
#endif   ! for F
#endif   ! for M

#ifdef  debug 
  show 'DEBUG:  Cust_num = '  &cust_num  edit  099999
#endif

#ifndef debugB            ! DebugB turned on with -DEBUGB on 
  do test_procedure       ! SQR command line.
#endif

See The #DEBUG command for information about the -DEBUG command-line flag

IF

Syntax

IF logical_expression

IF commands have the following structure:

IF logical_expression SQR Command... [ELSE SQR Command...] END-IF

Description

Carries out commands depending on the value of a condition.

The expression is evaluated as a logical TRUE or FALSE. A value or expression that evaluates to nonzero is TRUE.

Each IF command must have a matching END-IF command.

IF commands can be nested.

Comparing a date variable or column with a string results in a date comparison (chronological, not a byte-by-byte comparison as is done for strings). The string must be in the proper format as described in the following list:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats (see the Default Database Formats table), or the database-independent format 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]'.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting, or the format listed in the Date Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting, or the format as listed in the Time Column Formats table.

Parameters

Parameter

Description

logical_expression

Any valid logical expression. See the LET command for a description of logical expressions.

Example

The following example illustrates the IF command:

if &price > &old_price and instr(&code, 'M', 1) > 0
   add 1 to #price_count
   if #price_count > 50
      show 'More than 50 prices found.' noline
      input $x 'Continue? (Y/N)'
      if upper($x) = 'N'
         stop
      end-if
   end-if
else
   add 1 to #old_price_count
end-if
if #rows   ! Will be TRUE if #rows is non-zero.
   do print-it
end-if

if $date1 > 'Apr 21 2004 23:59'
   do past_due
end-if

See The LET command for a description of logical expressions

See EVALUATE

#IFDEF

Syntax

#IFDEF substitution_variable

Description

Indicates that the following commands are to be compiled when the substitution variable has been declared by an ASK or #DEFINE command, or by the -DEBUG flag on the SQR command line. (#IFDEF is a compiler directive.)

Parameters

Parameter

Description

substitution_variable

The variable to be used as the substitution variable.

See The #IF command for a description of each compiler directive

#IFNDEF

Syntax

#IFNDEF substitution_variable

Description

Indicates that the following commands are to be compiled when the substitution variable has not been declared by an ASK or #DEFINE command, or by the -DEBUG flag on the SQR command line. (#IFNDEF is a compiler directive.)

Parameters

Parameter

Description

substitution_variable

The variable to be used as the substitution variable.

See The #IF command for a description of each compiler directive

#INCLUDE

Syntax

#INCLUDE filename_lit

Description

Includes an external source file in the SQR report specification.

You may want to keep commonly used routines in a single file and reference or include that file in programs that use the routine. For example, you might have a set of #DEFINE commands for different printers to control initialization, font changes, and page size declarations. You can reference the appropriate include file depending on which printer you want to use.

Include files can be nested up to four levels. Variable substitution scanning takes place before the #INCLUDE command is processed. This enables you to substitute all or part of the include file name at runtime, adding flexibility for controlling which file is included for the run.

Parameters

Parameter

Description

filename_lit

A file name that is valid for the platform on which the application is to be compiled.

Example

The following example illustrates the #INCLUDE command:

#include 'gethours.dat'        ! Common procedure.
#include 'XYZheader.dat'       ! Common report heading for XYZ Company.
#include 'printer{num}.dat'    ! Include printer definitions for 
                               ! printer {num}, which is passed
                               ! on the command line:
                               ! SQR REP1A SAM/JOE 18
                               ! where 18 is the arbitrary number 
                               ! assigned your printer
                               ! definition file, 'printer18.dat'.
                               ! The report would contain the
                               ! command:  ASK num
                               ! in the SETUP section, preceding
                               ! this #include statement.

INPUT

Syntax

INPUT input_var[MAXLEN=nn][prompt] [TYPE={CHAR|TEXT|NUMBER|INTEGER|DATE}] [STATUS=num_var][NOPROMPT][BATCH-MODE] [FORMAT={txt_lit|_var|_col}]

Description

Accepts data entered by the user at a terminal.

Use MAXLEN to prevent the user from entering data that is too long. If an INSERT or UPDATE command references a variable for which the length is greater than the length defined in the database, the SQL is rejected and SQR halts. If the maximum length is exceeded, the terminal beeps (on some systems, this may cause the screen to flash instead).

If prompt is omitted, SQR uses the default prompt. Enter [$|#]var: . In either case, a colon (:) and two spaces are added to the prompt.

Specifying TYPE causes data type checking to occur. If the string entered is not the type specified, the terminal beeps and an error message is displayed. The INPUT command is then rerun. If TYPE=DATE is specified, then input_var can be a date or text variable; however, TYPE=DATE is optional if input_var is a date variable. If a numeric variable is used, it is validated as a numeric variable. The types CHAR, TEXT, and DATE are invalid types. The data types supported are described in the following table:

Data Type

Description

CHAR, TEXT

Any character. This is the default datatype.

NUMBER

A floating point number in the format [+|-]9999.999[E[+|- ]99]

INTEGER

An integer in the format [+|-]99999

DATE

A date in one of the following formats:

  • MM/DD/YYYY [BC|AD] [HH:MI[:SS[.NNNNNN]] [AM|PM]]

  • MM-DD-YYYY [BC|AD] [HH:MI[:SS[.NNNNNN]] [AM|PM]]

  • MM.DD.YYYY [BC|AD] [HH:MI[:SS[.NNNNNN]] [AM|PM]]

  • SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]

Specifying STATUS causes the INPUT command to finish regardless of what the user enters. No error message is displayed. A nonzero error code is stored in the indicated numeric variable if the length or datatype entered is incorrect.

The following table lists the values of the STATUS argument of the INPUT command:

Status Value

Indicates

0

Successful.

1

Bad type (did not match the datatype of TYPE).

2

Too long (longer than MAXLEN, or the input for an INTEGER variable is < –2147483648 or > +2147483647).

3

No arguments remain on the command line. The command was ignored.

By using NOPROMPT and STATUS with the SHOW command, you can write a sophisticated data entry routine.

FORMAT can be used only with dates. It can be a date edit mask or the keyword DATE. Use the keyword DATE if the date must be in the format as specified with the INPUT-DATE-EDIT-MASK setting for the current locale. If FORMAT has not been set, use a database-independent format for the data as listed in the datatypes table.

Parameters

Parameter

Description

input_var

Specifies a text, numeric, or date variable for the input data.

MAXLEN

Specifies the maximum length for the data.

prompt

Specifies the prompt displayed to the user.

TYPE

Specifies the datatype required for the input.

STATUS

Specifies a numeric variable for a return status code.

NOPROMPT

Prevents the prompt from being displayed before the INPUT command is processed.

BATCH-MODE

If BATCH-MODE is specified and no more arguments are in the command line, a value of 3 is returned in the STATUS variable and the user is not prompted for input.

FORMAT

Specifies the format for entering a date. The Date Edit Format Codes table lists date edit format codes.

Example

The following example shows several INPUT commands:

input  $state  maxlen=2  'Please enter state abbreviation'
input  #age  'Enter lower age boundary'  type=integer
input  $start_date  'Enter starting date for report'  type=date
input  $date_in  format='Mon dd yyyy'
input  $date  format=date

The following example shows another INPUT command:

show clear-screen (5,32) reverse 'CUSTOMER SUMMARY' normal
Try_again:
show  (12,20)  'Enter Start Date: '  clear-line
input  $start-date  noprompt  status=#istat  type=date
if  #istat  !=  0
     show (24,1) 'Please enter date in format DD-MON-YY' beep
     goto  try_again
end-if
show  (24,1)  clear-line            ! Clear error message line.

The following example illustrates the use of the BATCH-MODE option:

begin-program
 while (1)
  input $A status=#stat batch-mode
  if #stat = 3
   break
  else
   do procedure ($a)
  end-if
 end-while
end-program

See ] ALTER-LOCALE

See The INPUT-DATE-EDIT-MASK setting in the topic“Using the PSPSPSPSSQR.INI File and the PSSQR Command Line

LAST-PAGE

Syntax

LAST-PAGE position [pre_txt_lit[post_txt_lit]]

Description

Places the last page number on each page, as in page n of m.

The text strings specified in pre_txt_lit and post_txt_lit are printed immediately before and after the number.

Using LAST-PAGE causes SQR and SQRT to delay printing until the last page has been processed so that the number of the last page is known.

Parameters

Parameter

Description

position

Specifies the position for printing the last page number. See the POSITION command for a description of the position parameter.

pre_txt_lit

Specifies a text string to be printed before the last page number.

post_txt_lit

Specifies a text string to be printed after the last page number.

Example

The following example illustrates the LAST-PAGE command:

begin-footing 1
   page-number         (1,37)  'Page '    ! Will appear as
   last-page            ()  ' of ' '.'    ! "Page 12 of 25."
end-footing

See PAGE-NUMBER, BEGIN-HEADING, BEGIN-FOOTING

LET

Syntax

LET dst_var=expression

Description

Assigns the value of an expression to a string, numeric, or date variable.

Valid expressions are formed as a combination of operands, operators, and functions. String, numeric, date, and array field operands can be used in an expression and embedded functions. SQR supports a standardized set of mathematical operators and logical comparison operators working within a carefully defined set of precedence rules. SQR also provides a rich set of mathematical, string, date, and file manipulation functions along with a number of special purpose utility functions. All combined, the SQR expression provides a powerful tool that can be tailored to suit any information processing need. The following detail outlines the specific behavior of each expression component: (1) the operand, (2) the operator, and (3) the function.

Parameters

Parameter

Description

dst_var

A string, numeric, or date variable or array field to which the result of the expression is assigned.

expression

The expression to evaluate.

Operands

Operands form the backbone of an SQR expression. Operands do not have to be the same type. You can combine string, numeric, and array field operands to form a valid expression. SQR performs a sequence of automatic operand conversions when it evaluates expressions that contain dissimilar operand types. As the expression is evaluated, operands of lower precision are converted to match the operand of higher precision. Consider the following code example:

let  #answer = #float * #decimal  / #integer

Because the multiply and divide operators are equal in precedence, the expression is evaluated as (#float * #decimal) / #integer. Working from the inside out, the #float variable is converted to a decimal type in which a multiply is performed yielding the simplified expression (#decimal)/#integer. SQR now converts the #integer operand to a decimal type before performing the final divide. When finished with the expression evaluation, SQR converts the result to match the type of the #answer variable.

Converting operands of lower precision to operands of higher precision preserves the number of significant digits. The number of significant digits is not lost when an integer is converted to float or decimal. In a similar manner, the number of significant digits is preserved when floating point operands are converted to the decimal type. The number of significant digits is sacrificed only when the final result is converted to match the type of the #answer variable and this variable is less precise than the highest of the operands being evaluated. In the example, precision is not lost if the #answer is declared as a decimal type. SQR considers integer variables as the lowest in the precision hierarchy, followed by float and then decimal.

Here are a few simple expression examples:

let #discount  =  round (&price * #rate / 100, 2)
let $name  =  $first_name || ' ' || $last_name
let customer.total (#customer_id) =

   customer.total (#customer_id) + #invoice_total
if not range(upper($code), 'A', 'G')
   ...processing when out of range...
let store.total (#store_id, #qtr) =

   store.total (#store_id, #qtr) + #invoice_total
let $date1 = strtodate ('Apr 10 2004', 'MON DD YYYY')

The following sections list operators and functions supported in expressions.

Operators

Operators of the same precedence are processed in the sequence in which they appear in the expression, from left to right. Use parentheses to override the normal precedence rules. All numeric types (decimal, float, integer) are supported for all operators.

This table lists operators in descending order of precedence (operators listed in the same row within the table have the same precedence):

Operator

Explanation

||

Concatenate two strings or dates

+, -

Sign prefix (positive or negative)

^

Exponent

*, /, %

Multiply, divide, remainder: a % b = mod(a,b) for integers

+, -

Plus, minus

Note: SQR distinguishes between a sign prefix and arithmetic operation by the context of the expression.

>, <, >=, <=, <>, !=, =

Comparison operators: greater than, less than, greater or equal to, less than or equal to, not equal to (!= or <>), equal to.

not

Logical NOT

and

Logical AND

or, xor

Logical OR, XOR (exclusive OR)

Functions

This section lists numeric, file-related, and miscellaneous functions. The functions are listed in alphabetical order.

Function arguments are enclosed in parentheses and can be nested. Arguments referenced as x, y, or z indicate the first, second, or third argument of a function. Otherwise, functions take a single argument or no arguments. All arguments are evaluated before a function is evaluated.

Not all functions support all numeric types (decimal, float, integer). Certain functions do not support the decimal type directly, but convert input decimal operands to the float type before the function is evaluated. The following table annotates the functions that directly support the decimal type and the ones that do not.

Use parentheses to override the normal precedence rules.

This table describes numeric functions:

Function

Description

abs

Returns the absolute value of num_value. This function returns a value of the same type as num_value.

Syntax:

dst_var = abs(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression.

dst_var = decimal, float, or integer variable.

Example:

let #dabsvar = abs(#dvar) 
acos

Returns the arccosine of num_value in the range of 0 to p radians. The value of num_value must be between –1 and 1. This function returns a float value.

Syntax:

dst_var = acos(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #facosvar = acos(#fvar) 
asin

Returns the arcsine of num_value in the range of –p/2 to p/2 radians. The value of num_value must be between –1 and 1. This function returns a float value.

Syntax:

dst_var = asin(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fasinvar = asin(#fvar) 
atan

Returns the arctangent of num_value in the range of –p/2 to p/2 radians. The value of num_value must be between –1 and 1. This function returns a float value.

Syntax:

dst_var = atan(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fatanvar = atan(#fvar) 
ceil

Returns a value representing the smallest integer that is greater than or equal to num_value. This function returns a value of the same type as num_value.

Syntax:

dst_var = ceil(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression.

dst_var = decimal, float, or integer variable.

Example:

let #fceilvar = ceil(#fvar)
cos

Returns the cosine of num_value. This function returns a float value.

Syntax:

dst_var = cos(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fcosvar = cos(#fvar) 
cosh

Returns the hyperbolic cosine of num_value. This function returns a float value.

Syntax:

dst_var = cosh(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fcoshvar = cosh(#fvar) 
deg

Returns a value expressed in degrees of num_value, which is expressed in radians. This function returns a float value.

Syntax:

dst_var = deg(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fdegvar = deg(#fvar) 
e10

Returns the value of 10 raised to num_value. This function returns a float value.

Syntax:

dst_var = e10(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fe10var = e10(#fvar) 
exp

Returns the value of e raised to num_value. This function returns a float value.

Syntax:

dst_var = exp(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fexpvar = exp(#fvar) 
floor

Returns a value representing the largest integer that is less than or equal to num_value. This function returns a value of the same type as num_value.

Syntax:

dst_var = floor(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression.

dst_var = decimal, float, or integer variable.

Example:

let #ffloorvar = floor(#fvar) 
log

Returns the natural logarithm of num_value. This function returns a float value.

Syntax:

dst_var = log(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #flogvar = log(#fvar) 
log10

Returns the base-10 logarithm of num_value. This function returns a float value.

Syntax:

dst_var = log10(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #flog10var = log10(#fvar) 
mod

Returns the fractional remainder, f, of x_value/ y_value such that x_value = i * y_value + f, where i is an integer, f has the same sign as x_value, and the absolute value of f is less than the absolute value of y_value. The arguments are promoted to the type of the greatest precision and the function returns a value of that type.

Syntax:

dst_var = mod(x_value, y_value) 

x_value = decimal, float, or integer literal, column, variable, or expression.

y_value = decimal, float, or integer literal, column, variable, or expression.

dst_var = decimal, float, or integer variable.

Example:

let #fmodvar = mod(#fxvar, #fyvar)
power

Returns the value of x_value raised to the power of y_value. This function returns a float value.

Syntax:

dst_var = power(x_value, y_value) 

x_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

y_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fpowervar = power(#fxvar, #fyvar)
rad

Returns a value expressed in radians of num_value, which is expressed in degrees. This function returns a float value.

Syntax:

dst_var = rad(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

place_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fradvar = rad(#fvar) 
round

Returns a value that is num_value rounded to place_value digits after the decimal separator. This function returns a value of the same type as num_value.

Syntax:

dst_var = round(num_value, place_value)

num_value = decimal, float, or integer literal, column, variable, or expression.

place_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #frndvar = round(#fvar, #fplace) (#x, #y)
sign

Returns a –1, 0, or +1 depending on the sign of num_value. This function returns a float value.

Syntax:

dst_var = sign(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression.

dst_var = decimal, float, or integer variable.

Example:

let #fsignvar = sign(#fvar)
sin

Returns the sine of num_value. This function returns a float value.

Syntax:

dst_var = sin(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fsinvar = sin(#fvar) 
sinh

Returns the hyperbolic sine of num_value. This function returns a float value.

Syntax:

dst_var = sinh(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fsinhvar = sinh(#fvar) 
sqrt

Returns the square root of num_value. This function returns a float value.

Syntax:

dst_var = sqrt(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #fsqrtvar = sqrt(#fvar) 
tan

Returns the tangent of num_value. This function returns a float value.

Syntax:

dst_var = tan(num_value) 

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #ftanvar = tan(#fvar) 
tanh

Returns the hyperbolic tangent of num_value. This function returns a float value.

Syntax:

dst_var = tanh(num_value)

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #ftanhvar = tanh(#fvar) 
trunc

Returns a value that is num_value truncated to place_value digits after the decimal separator. This function returns a value of the same type as num_value.

Syntax:

dst_var = trunc(num_value, place_value)

num_value = decimal, float, or integer literal, column, variable, or expression.

place_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = decimal, float, or integer variable.

Example:

let #ftruncvar = trunc(#fvar, #fplace) 

The transcendental functions sin, cos, tan, sinh, cosh, and tanh take their arguments in radians. The functions asin, acos, and atan return radian values. To convert from radians to degrees or degrees to radians, use the rad or deg functions as shown here:

let #x = sin(rad(45))            ! Sine of 45 degrees.
let #y = deg(asin(#x))           ! Convert back to degrees.

If arguments or intermediate results passed to a numeric function are invalid for that function, SQR halts with an error message.

For example, passing a negative number to the sqrt function causes an error. Use the cond function described in the Miscellaneous Functions table to prevent division by zero or other invalid function or operator argument values.

The following table lists file-related functions. These functions return 0 (zero) when successful; otherwise, they return the system error code.

Function

Description

delete

Deletes the file filename. The function returns either a 0 (zero) to indicate success or the value returned from the operating system to indicate an error.

Syntax:

stat_var = delete(filename) 

filename = text literal, column, variable, or expression.

stat_var = decimal, float, or integer variable.

Example:

let #fstatus = delete($filename)

exists

Determines whether the file filename exists. The function returns either a 0 (zero) to indicate success or the value returned from the operating system to indicate an error.

Syntax:

stat_var = exists(filename)

filename = text literal, column, variable, or expression.

stat_var = decimal, float, or integer variable.

Example:

let #fstatus = exists($filename)

rename

Renames old_filename to new_filename. The function returns either a 0 (zero) to indicate success or the value returned from the operating system to indicate an error.

Syntax:

stat_var = rename(old_filename, new_filename) 

old_filename = text literal, column, variable, or expression.

new_filename = text literal, column, variable, or expression.

stat_var = decimal, float, or integer variable.

Example:

let #fstatus = rename($old_filename, $new_filename)

The following table lists miscellaneous functions. These functions return a string value unless otherwise indicated.

In these functions where a string argument is expected and a date variable, column, or expression is entered, SQR converts the date to a string according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the DATE Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

Except where noted in an individual function, if a string variable, column, or expression is entered where a date argument is expected, the string must be in the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats listed in the Default Database Formats table, or the database-independent format 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]'.

Function

Explanation

array

Returns a pointer to the starting address of the specified array field. The value returned from this function can be used only by a user-defined function. See the routine printarray in the file UFUNC.C for complete instructions on how to use this function.

Syntax:

array_var = array(array_name, field_name)

array_name = text literal, column, variable, or expression

field_name = text literal, column, variable, or expression

array_var = text variable

Example:

let #fstatus = printarray(array('products', 'name'), 10, 2, 'c')

ascii

Returns the numeric value for the first character in str_value. This function returns a float value.

Syntax:

ascii_var  = ascii(str_value)

str_value = date or text literal, column, variable, or expression

ascii_var = decimal, float, or integer variable

Example:

let #fascii = ascii($filename)

asciic

Returns the numeric value for the first character (rather than byte) of the specified string.

Syntax:

ascii_var  = asciic(str_value)

str_value = date or text literal, column, variable, or expression

ascii_var = decimal, float, or integer variable

Example:

let #fascii = asciic($filename)

chr

Returns a string that is composed of a character with the numeric value of num_value.

Syntax:

dst_var = chr(num_value)

num_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = text variable.

Example:

let $svar = chr(#num)

cond

Returns y_value if the x_value is nonzero; otherwise, returns z_value. If y_value is numeric, the z_value must also be numeric; otherwise, date and textual arguments are compatible. If either the y_value or z_value is a date variable, column, or expression, a date is returned. The return value of the function depends on which value is returned.

Syntax:

dst_var = cond(x_value, y_value, z_value)

x_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

y_value = Any literal, column, variable, or expression

z_value = Any literal, column, variable, or expression

dst_var = Any variable

Example:

let #avg = #total / cond(&rate != 0, &rate, 1)

dateadd

Returns a date after adding (or subtracting) the specified units to the date_value.

Syntax:

dst_var = dateadd(date_value, units_value, quantity_value)

date_value = date variable or expression.

units_value = text literal, column, variable, or expression. Valid units are 'year', 'quarter', 'week', 'month', 'day', 'hour', 'minute', and 'second'.

quantity_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to float.

dst_var = date variable

Example:

let $date = dateadd($startdate, 'day', 7.5)

datediff

Returns the difference between the specified dates expressed in units_value. The function returns a float value. The result can be negative if the first date is earlier than the second date.

Syntax:

dst_var = datediff(date1_value, date2_value, units_value)

date1_value = date variable or expression.

date2_value = date variable or expression.

units_value = text literal, column, variable, or expression. Valid units are 'year', 'quarter', 'week', 'month', 'day', 'hour', 'minute', and 'second'

dst_var = decimal, float, or integer variable.

Example:

let #diff = datediff($date1, $date2, 'hour')

datenow

Returns the current local date and time from the client machine.

Syntax:

dst_var = datenow()

dst_var = date variable

Example:

let $date = datenow()

datetostr

Converts the date date_value to a string in the format format_mask.

Syntax:

dst_var = datetostr(date_value [, format_mask])

date_value = date variable or expression.

format_mask = text literal, column, variable, or expression. The keyword DATE can be used to specify the DATE-EDIT-MASK setting from the current locale. If this argument is not specified, the format specified by the SQR_DB_DATE_FORMAT setting is used. If this has not been set, the first database-dependent format listed in the Default Database Formats table is used.

dst_var = text variable

Example: let $formdate = datetostr($date, 'Day Mon DD, YYYY') let $localedate = datetostr($date, DATE)

edit

Formats source_value according to edit_mask and returns a string containing the result.

Syntax:

dst_var = edit(source_value, edit_mask)

source_value = Any literal, column, variable, or expression

edit_mask = text literal, column, variable, or expression

dst_var = text variable

Example: )

let $phone  =  edit(&phone, '(xxx) xxx-xxxxx') let $price = edit(#price, '999.99') let $today = edit($date, 'DD/MM/YYYY'

getenv

Returns the value of the specified environment variable. If the environment variable does not exist, an empty string is returned.

Syntax:

dst_var = getenv(env_value)

env_value = text literal, column, variable, or expression

dst_var = text variable

Example:

let $myuser = getenv('USER')

instr

Returns the numeric position of sub_value in source_value or 0 (zero) if not found. The search begins at offset offset_value. This function returns a float value.

Syntax:

dst_var = instr(source_value, sub_value, offset_value)

source_value = date or text literal, column, variable, or expression.

sub_value = text literal, column, variable, or expression.

offset_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

dst_var = decimal, float, or integer variable.

Example:

let #offset = instr(&description, 'auto', 10)

instrb

Performs the same functionality as the instr function except that the starting point and returned value are expressed in bytes rather than in characters.

Syntax:

dst_var = instrb(source_value, sub_value, offset_value)

source_value = date or text literal, column, variable, or expression.

sub_value = text literal, column, variable, or expression.

offset_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

dst_var = decimal, float, or integer variable.

Example:

let #offset = instrb(&description, 'auto', 10)

isblank

Returns a value of 1 (one) if source_val is an empty string, null string, or composed entirely of white-space characters; otherwise, returns a value of 0 (zero).

Syntax:

dst_var = isblank(source_value)

source_value = date or text literal, column, variable, or expression

dst_var = decimal, float, or integer variable

Example:

let #blank = isblank(&description)

isnull

Returns a value of 1 (one) if source_val is null; otherwise, returns a value of 0 (zero).

Syntax:

dst_var =  isnull(source_value)

source_value = date or text literal, column, variable, or expression

dst_var = decimal, float, or integer variable

Example:

let #null = isnull($date)

length

Returns the number of characters in source_value.

Syntax:

dst_var = length(source_value)

source_value = date or text literal, column, variable, or expression

dst_var = decimal, float, or integer variable

Example:

let #length = length(&description)

Note: Oracle recommends that you use either the lengthp or lengtht function instead of the length function.

lengthb

(Multibyte versions of SQR only) Has the same functionality as the length function except that the return value is expressed in bytes rather than in characters.

Syntax:

dst_var = lengthb(source_value)

source_value = date or text literal, column, variable, or expression

dst_var = decimal, float, or integer variable

Example:

let #length = lengthb(&description)

Note: Oracle recommends that you use either the lengthp or lengtht function instead of the lengthb function.

lengthp

Returns the length of a given string in print positions.

Syntax:

dst_var = lengthp(source_value)

source_value = date or text literal, column, variable, or expression

dst_var = decimal, float, or integer variable

Example:

let #printlen = lengthp(&string)

lengtht

Returns the length of a given string in bytes when converted (transformed) to a specified encoding.

Syntax:

dst_var = lengtht(source_value, encoding_value)

source_value = date or text literal, column, variable, or expression

encoding_value = text literal, column, variable, or expression

dst_var = decimal, float, or integer variable

Example:

let #sjislen = lengtht($string, 'Shift-JIS')

lower

Converts the contents of source_value to lowercase and returns the result.

Syntax:

dst_var = lower(source_value)

source_value = date or text literal, column, variable, or expression

dst_var = text variable

Example:

let $lower = lower(&description)

lpad

Pads the source_value on the left to a length of length_value using pad_value and returns the result.

Syntax:

dst_var = lpad(source_value, length_value, pad_value)

source_value = date or text literal, column, variable, or expression.

length_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

pad_value = text literal, column, variable, or expression.

dst_var = text variable.

Example:

let $lpad = lpad($notice, 25, '.')

ltrim

Trims characters in source_value from the left until a character is not in set_value and returns the result.

Syntax:

dst_var = ltrim(source_value, set_value)

source_value = date or text literal, column, variable, or expression

set_value = text literal, column, variable, or expression

dst_var = text variable

Example:

let $ltrim = ltrim(&description, '.')

nvl

Returns y_value if the x_value is null; otherwise, returns x_value. If x_value is numeric, y_value must also be numeric; otherwise, date and textual arguments are compatible. In any case, the x_value determines the type of expression returned. The return value of the function depends on which value is returned.

Syntax:

dst_var = nvl(x_value, y_value)

x_value = Any literal, column, variable, or expression

y_value = Any literal, column, variable, or expression

dst_var = Any variable

Example:

let $city = nvl(&city, '-- not city --')

If x_value is a date and y_value is textual, y_value is validated according to the following rules:

For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats (see the Default Database Formats table), or the database-independent format 'SYYYYMDD[HH24[MI[SS[NNNNNN]]]]'.

For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting, or the format listed in the DATE Column Formats table.

For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting, or the format as listed in the TIME Column Formats table.

range

Returns a value of 1 (one) if x_value is between y_value and z_value; otherwise, returns a value of 0 (zer0). If the first argument is text or numeric, the other arguments must be of the same type. If the first argument is a date, the remaining arguments can be dates, text, or both. You can also perform a date comparison on a mix of date and text arguments, for example, where x_value is a date and y_value and z_value are text arguments. In a comparison of this sort, y_value must represent a date that is earlier than that of z_value.

Syntax:

dst_var = range(x_value, y_value, z_value)

x_value = Any literal, column, variable, or expression

y_value = Any literal, column, variable, or expression

z_value = Any literal, column, variable, or expression

dst_var = decimal, float, or integer variable

Example:

let #inrange = range(&grade, 'A', 'D') let #inrange = range($date, $startdate, $enddate) let #inrange = range($date, $startdate, '15-Apr-04') let #inrange = range(#price, #low, #high)

If x_value is a date and y_value and/or z_value is textual, then y_value and/or z_value is validated according to the following rules:

For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats (see the Default Database Formats table), or the database-independent format 'SYYYYM­MDD[HH24[MI[SS[NNNNNN]]]]'.

For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting, or the format listed in the table DATE Column Formats.

For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting, or the format as listed in table TIME Column Formats.

replace

Inspects the contents of source_value and replaces all occurrences of from_string with to_string and returns the modified string.

Syntax:

dst_var = replace(source_value, from_string, to_string)

source_value = date or text literal, column, variable, or expression

from_string = text literal, column, variable, or expression

to_string = text literal, column, variable, or expression

dst_var = text variable

Example:
let $replaced = replace($paragraph, 'good', 'excellent')

roman

Returns a string that is the character representation of source_value expressed in lowercase roman numerals.

Syntax:

dst_var = roman(source_value)

source_value = text literal, column, variable, or expression

dst_var = text variable

Example:

let $roman = roman(#page-count)

rpad

Pads the source_value on the right to a length of length_value using pad_value and returns the result.

Syntax:

dst_var = rpad(source_value, length_value, pad_value)

source_value = date or text literal, column, variable, or expression

length_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

pad_value = text literal, column, variable, or expression

dst_var = text variable

Example:

let $rpad = rpad($notice, 25, '.')

rtrim

Trims characters in source_value from the right until a character is not in set_value and returns the result.

Syntax:

dst_var = rtrim(source_value, set_value)

source_value = date, or text literal, column, variable, or expression

set_value = text literal, column, variable, or expression

dst_var = text variable

Example:

let $rtrim = rtrim(&description, '.')

strtodate

Converts the string source_value in the format format_mask to a date type.

Syntax:

dst_var = strtodate(source_value [, format_mask])

source_value = text literal, column, variable, or expression.

format_mask = text literal, column, variable, or expression that describes the exact format of the source_value. The keyword DATE can be used to specify the DATE-EDIT-MASK setting from the current locale. If this argument is not specified, then source_value must be in the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats (see the Default Database Formats table), or the database-independent format 'SYYYYMDD[HH24[MI[SS[NNNNNN]]]]'. Valid format codes are specified in the Date Edit Format Codes table.

dst_var = date variable

Example: let $date = strtodate($str_date, 'Mon DD, YYYY') let $date = strtodate($str_date, DATE)

substr

Extracts the specified portion source_value. The extraction begins at offset_value (origin is 1) for a length of length_value characters.

Syntax:

dst_var = substr(source_value, offset_value, length_value)

source_value = date or text literal, column, variable, or expression.

offset_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

length_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

dst_var = text variable.

Example:

let $piece = substr(&record, 10, #len)

Note: Oracle recommends that you use either the substrp or substrt function instead of the substr function.

substrb

Has the same functionality as the substr function except that the starting point and length are expressed in bytes rather than in characters.

Syntax:

dst_var = substrb(source_value, offset_value, length_value)

source_value = date or text literal, column, variable, or expression.

offset_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

length_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

dst_var = text variable.

Example:

let $piece = substrb(&record, 10, #len)

Note: Oracle recommends that you use either the substrp or substrt function instead of the substrb function.

substrp

Returns a substring of a given string starting at a specified print position into the string and of a specified print length.

Syntax:

dst_var = substrp(source_value, offset_value, length_value)

source_value = date or text literal, column, variable, or expression.

offset_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

length_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

dst_var = decimal, float, or integer variable.

Example:

let $sub = substrp(&string, #printpos, #printlen)

substrt

Returns a substring of a given string starting at a specified byte and byte length in a given encoding.

Syntax:

dst_var = substrt(source_value, offset_value, length_value, encoding_value)

source_value = date or text literal, column, variable, or expression.

offset_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

length_value = decimal, float, or integer literal, column, variable, or expression. The value is always converted to integer.

encoding_value = text literal, column, variable, or expression.

dst_var = text variable.

Example:

let $sjisPrep = substrt(&string, 1, 10, 'Shift-JIS')

to_char

Converts source_value to a string, using maximum precision.

Syntax:

dst_var = to_char(source_value)

source_value = decimal, float, or integer literal, column, variable, or expression

dst_var = text variable

Example:

let $string = to_char(#number)

to_multi_byte

Converts the specified string in the following way: Any occurrence of a double-byte character that also has a single-byte representation (numerals, punctuation, roman characters, and katakana) is converted.

Syntax:

dst_var = to_multi_byte (source_value)

source_value = date or text literal, column, variable, or expression

Example:

let $multi = to_multi_byte (&text)

to_number

Converts source_value to a number. This function returns a float value.

Syntax:

dst_var = to_number(source_value)

source_value = date or text literal, column, variable, or expression

dst_var = decimal, float, or integer variable

Example:

let #value = to_number($number)

to_single_byte

Converts the specified string in the following way: For SJIS, EBCDIK290, and EBCDIK1027, any occurrence of a single-byte character that also has a multibyte representation (numerals, punctuation, roman characters, and katakana) is converted. This function also converts a sequence of kana characters followed by certain grammatical marks into a single-byte character that combines the two elements. For all other encodings, the string is not modified.

Syntax:

dst_var = to_single_byte(source_value)

source_value = date or text literal, column, variable, or expression

Example:

let $single = to_single_byte (&text)

translate

Inspects the contents of source_value and converts characters that match those in from_set to the corresponding character in to_set and returns the translated string.

Syntax:

dst_var =  translate(source_value, from_set, to_set)

source_value = date or text literal, column, variable, or expression

from_set = text literal, column, variable, or expression

to_set = text literal, column, variable, or expression

dst_var = text variable

Example:

let $translated = translate(edit(&price, '999,999.99'),',',',')

transform

Returns a Unicode string that is a specified transform of a given string.

Syntax:

dst_var = transform(source_value, transform_value)

source_value = date or text literal, column, variable or expression

transform_value = text literal, column, variable, or expression

dst_var = text variable

Example:

let $hiragana = transform($string, 'ToHiragana')

unicode

Returns a Unicode string from the string of hexadecimal values provided.

Syntax:

dst_var = unicode(source_value)

source_value = text literal, column, variable or expression

dst_var = text variable

Example:

let $uniStr = unicode('u+5e73 u+2294')

upper

Converts the contents of source_value to uppercase and returns the result.

Syntax:

dst_var =  upper(source_value)

source_value = date or text literal, column, variable, or expression

dst_var = text variable

Example:

let $upper = upper(&description)

wrapdepth

Returns the number of print lines required by source_value. See the PRINTWRAP command for detailed descriptions of the parameters to this function. This function returns a float value.

Syntax:

dst_var = wrapdepth(source_value, wrap_width, line_height, on, strip)

source_value = text literal, column, variable, or expression

wrap_width = decimal, float, or integer literal, column, variable, or expression

line_height = decimal, float, or integer literal, column, variable, or expression

on = text literal, column, variable, or expression

strip = text literal, column, variable, or expression

dst_var = decimal, float, or integer variable

Example:

let #depth = wrapdepth(&description,40,1,'<13>','')

Writing Custom Functions

In addition to using the preceding built-in functions, you can write your own functions in C, using the supplied source file UFUNC.C .

You can pass any number of arguments to your function and values can be returned by the function or passed back in variables.

After editing and recompiling UFUNC.C, you must relink SQR.

The following step-by-step example shows how to add a user-defined function to SQR so that it can be invoked using the LET, IF, or WHILE command.

The example adds the C function random, which returns a random number. The function accepts a parameter that is used as the seed to start a new sequence of numbers. If the seed is zero, then the same sequence is used.

When adding functions to UFUNC, remember the following considerations:

  • String functions require the following arguments:

    • (int) Number of arguments.

    • (char *) or (double *) Array of argument pointers, to either char[ ] or double.

    • (char *) Address for result string. If unchanged, function returns a NULL string.

    • (int) Maximum length of result string, in bytes.

  • Numeric functions require the following arguments:

    • (int) Number of arguments.

    • (char *) or (double *) Array of argument pointers, to either char[ ] or double.

    • (double *) Address for result numeric value. If unchanged, function returns zero.

To add the random function to SQR, add the following modifications to the UFUNC.C file that was provided with SQR:

  • Add the prototype for the random function: static void random CC_ARGS((char *, char *));

  • Add the function name to the declaration list. The name of the function called from SQR is random. The return type is n for numeric. The number of arguments passed is 1, and the argument type is n for numeric. The function name in UFUNC.C is random. The characters PVR must be entered before the function name.

Name

Return_type

Number of Arguments

Arg_Types

Function

"max",

'n',

0,

"n",

PVR max,

"max",

'n',

0,

"n",

PVR max,

"split",

'n',

0,

"C",

PVR split,

"printarray",

'n',

4,

"cnnc",

PVR printarray,

"random",

'n',

1,

"n",

PVR random,

/* Last entry must be NULL -- do not change */
"", '\0', 0, "", 0
};

At the end the of UFUNC.C file, add the following random routine. The routine name must be lowercase; however, in your SQR program it can be referenced in either uppercase or lowercase.

static void random CC_ARGL((argc, argv, result)) 
CC_ARG(int, argc)               /* The number arguments passed   */
CC_ARG(double *, argv[])        /* The argument list             */
CC_LARG(double *, result)       /* Where to store result         */
{
if (*argv[0] != 0)
       srand(*argv[0]);
*result = rand();
return;
}

After these modifications, recompile UFUNC.C and relink SQR. See the programmer's reference manual for details about your particular machine.

This is a simple SQR program that uses the random function:

  begin-program 
    do get-random-number
    do process-calculations
  end-program

  begin-procedure
     let #seed = 44
     let #ran = random(#seed)
  end-procedure

  begin-procedure process-calculations
   .
   .
   .

Example

These examples show some complex expressions:

let #j = ((#a + #b) * #c) ^ 2
if #j > 2 and sqrt(#j) < 20 or #i + 2 > 17.4
while upper(substr(&descrip,1,#j+2)) != 'XXXX' 

and not isnull(&price)
let #len = length(&fname || &initial || &lname) + 2
let $s = edit(&price * &rate, '99999.99')
let summary.total(#j) = summary.total(#j) + (&price * &rate)
if summary.total(#j) > 1000000
let store.total (#store_id, #dept)

   = store.total (#store_id, #dept) + #total
let #diff = datediff(datenow(), strtodate('1995','YYYY'),'day')
let $newdate = dateadd(datenow(),'month',50)
let $date1 = datetostr(strtodate(&sale_date), 'Day Month DD, YYYY')

SQR analyzes LET, IF, and WHILE expressions when it compiles your code and saves the result in an internal format so that repetitive execution is at maximum speed.

LOAD-LOOKUP

Syntax

In the SETUP section:

LOAD-LOOKUP NAME=lookup_table_name TABLE=database_table_name
KEY=key_column_name RETURN_VALUE=return_column_name [ROWS=initial_row_estimate_int_lit]
[EXTENT=size_to_grow_by_int_lit] [WHERE=where_clause_txt_lit] [SORT=sort_mode]
[QUIET] [SCHEMA=schema_name] [PROCEDURE=procedure_name] [COMMAND=command_string]
[GETDATA=getdata_string] [PARAMETERS=(...)] [FROM-ROWSET=(m,n,-n,m-,all)]
[FROM-PARAMETER=rowset_name]

In the body of the report:

LOAD-LOOKUP NAME=lookup_table_name TABLE=database_table_name
KEY=key_column_name RETURN_VALUE=return_column_name [ROWS=initial_row_estimate_lit|_var|_col]
[EXTENT=size_to_grow_by_lit|_var|_col] [WHERE=where_clause_txt_lit|_var|_col]
[SORT=sort_mode] [QUIET] [SCHEMA=schema_name] [PROCEDURE=procedure_name]
[COMMAND=command_string] [GETDATA=getdata_string] [PARAMETERS=(...)]
[FROM-ROWSET=(m,n,-n,m-,all)] [FROM-PARAMETER=rowset_name]

Description

Loads an internal table with columns from the database. Enables a quick search using the LOOKUP command.

Use the LOAD-LOOKUP command in conjunction with one or more LOOKUP commands.

LOAD-LOOKUP retrieves two columns from the database, the KEY field and the RETURN_VALUE field. Rows are ordered by KEY and stored in an array.

LOAD-LOOKUP commands specified in the SETUP section are always loaded and cannot reference variables for the ROWS, EXTENT, and WHERE arguments.

When you use the LOOKUP command, SQR searches the array (with a binary search) to find the RETURN_VALUE corresponding to the KEY referenced in the lookup.

Usually this type of lookup can be done with a database join , but joins take substantially longer. However, if your report is small and the number of rows to be joined is small, a lookup table can be slower because the entire table has to be loaded and sorted for each report run.

By default, SQR lets the database sort the data. This works well if the database and SQR both use the same character set and collating sequence. The SORT argument enables you to specify the sorting method if this is not true. Additionally, if the machine that SQR is running on is faster than the machine that the database is running on, letting SQR perform the sort could decrease the execution time of the report.

The only limit to the size of a lookup table is the amount of memory that your computer has available. You could conceivably load an array with many thousands of rows. The binary search is performed quickly regardless of how many rows are loaded.

Except for the amount of available memory, the number of lookup tables that can be defined is unlimited.

Parameters

Parameter

Description

NAME

The name of the lookup table. The array name is referenced in the LOOKUP command.

TABLE

The name of the table in the database, where the KEY and RETURN_VALUE columns or expressions are stored.

KEY

The name of the column that is used as the key in the array that is used for looking up the information. Keys can be character, date, or numeric data types. If the key is numeric, SQR permits only integers with 12 digits or fewer for the KEY column. Keys can be any database-supported expression. See the RETURN_VALUE argument.

RETURN_VALUE

The name of the column (expression) that is returned for each corresponding key.

The following example is for ORACLE. See your database manual for the correct syntax.

RETURN_VALUE='name||''-''||country||''-''||population'

ROWS

The initial size of the lookup table. This argument is optional, and if it is not specified, a value of 100 is used.

EXTENT

The amount to increase the array when it becomes full. This argument is optional, and if it is not specified, a value of 25% of the ROWS value is used.

WHERE

A WHERE clause used to select a subset of all the rows in the table. If it is specified, the selection begins after the word WHERE. The WHERE clause is limited to 255 characters.

SORT

The sorting method to be used. The following values are permitted:

DC: Database sorts data, case-sensitive sort

DI: Database sorts data, case-insensitive sort

SC: SQR sorts data, case-sensitive sort

SI: SQR sorts data, case-insensitive sort

The default is SC or the method specified by the -LL command-line flag. The DI method is applicable only to databases that provide this feature and have been installed in that manner.

QUIET

Suppresses the message Loading lookup array... when the command executes. The warning message stating the number of duplicate keys found is also suppressed.

Example

The following command loads the array states with the columns abbr and name from the database table stateabbrs, where country is USA.

load-lookup

name=states

rows=50

table=stateabbrs

key=abbr

return_value=name

where=country='USA'

The preceding array is used in the example for the LOOKUP command to retrieve the full text of a state name from the abbreviation.

The following example uses the LOOKUP command to validate data entered by a user using an INPUT command:

get_state:
input $state 'Enter state abbreviation'
uppercase $state
lookup states $state $name
if $name = ''         ! Lookup didn't find a match
  show 'No such state.'
  goto get_state
end-if

Enclose any command argument with embedded spaces by single quotes, as shown in the following example:

where='country=''USA'' and region = ''NE'''

The entire WHERE clause is surrounded by quotes. The two single quotes around USA and NE are translated to one single quote in the SQL statement.

The following example uses joins in a LOAD-LOOKUP command by including two tables in TABLE and the join in WHERE:

load-lookup

name=states

rows=50

sort=sc

table='stateabbrs s, regions r'

key=abbr

return_value=name

where='s.abbr = r.abbr and r.location = ''ne'''

LOOKUP

Syntax

LOOKUP lookup_table_name{key_any_lit|_var|_col} {ret_txt_var|_date_var}

Description

Searches a lookup table (an array) for a key value and returns the corresponding text string.

Speeds up processing for long reports. For example, if you want to print the entire state name rather than the abbreviation, you could use LOAD-LOOKUP and then LOOKUP to do this.

Parameters

Parameter

Description

lookup_table_name

Specifies the lookup table. This table must have been loaded previously with a LOAD- LOOKUP command.

key_any_lit | _var | _col

The key used for the lookup.

ret_txt_var | _date_var

A string variable into which the corresponding value is returned.

Example

The following example works in conjunction with the example for the LOAD-LOOKUP command:

lookup  states  &state_abbr  $state_name

This example searches the states lookup table for a matching &state_abbr value; if the value is found, the example returns the corresponding state name in $state_name. If it is not found, a null is placed in $state_name.

See The LOAD-LOOKUP command

LOWERCASE

Syntax

LOWERCASE txt_var

Description

Converts the contents of a text variable to lowercase.

Parameters

Parameter

Description

txt_var

Specifies a text variable to be converted to lowercase.

Example

The following example illustrates the LOWERCASE command:

input  $answer  'Type EXIT to stop'
lowercase  $answer     ! Allows user to enter
                       ! upper or lowercase.
if  $answer = 'exit'
   ...etc...

See The lower function listed in the Miscellaneous Functions table

MBTOSBS

Syntax

MBTOSBS {txt_var}

Description

Converts a double-byte string to its single-byte equivalent.

This command converts the specified string in the following way: any occurrence of a double-byte character that also has a single-byte representation (numerals, punctuation, roman characters, and katakana) is converted.

Parameters

Parameter

Description

txt_var

Specifies the string to be converted.

See The TO_SINGLE_BYTE function of the LET command

MOVE

Syntax

MOVE {src_any_lit|_var|_col} TO dst_any_var [[:$]format_mask|NUMBER|MONEY|DATE]

Description

Moves the source field to the destination field. Optionally, you can reformat the field using the format_mask argument. Source and destination fields can be different types: numeric, text, or date. MOVE is also useful for converting from one type to another; however, date and numeric variables are incompatible.

When a date variable or column is moved to a string variable, the date is converted according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the DATE Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

Finally, as the example shows, the edit mask can be contained in a string variable.

Parameters

Parameter

Description

src_any_lit | _var | _col

Specifies any source column, variable, or literal. Note that a date can be stored in a date variable or column, or a string literal, column, or variable. When you are using a date format_mask or the keyword DATE with the MOVE command, the source, if a string literal, column, or variable, must be in the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats as listed in the Default Database Formats table, or the database-independent format 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]'.

dst_any_var

Specifies a destination variable.

format_mask

Specifies an optional format mask. For additional information regarding edit masks, see the PRINT command.

NUMBER

Indicates that src_any_lit|_var|_col is to be formatted using the NUMBER-EDIT-MASK from the current locale. This option is not allowed with date variables. (See the ALTER_LOCALE command.)

MONEY

Indicates that src_any_lit|_var|_col is to be formatted using the MONEY-EDIT-MASK from the current locale. This option is not allowed with date variables. (See the ALTER_LOCALE command.)

DATE

Indicates that src_any_lit|_var|_col is to be formatted using the DATE-EDIT-MASK from the current locale. This option is not allowed with numeric variables. (See the ALTER_LOCALE command.)

Example

The following example illustrates the various features of the MOVE command:

 !
 ! Convert a string in place
 !
 move '123456789' to $ssn
 move $ssn to $ssn xxx-xx-xxxx
 show '$SSN = ' $ssn

Produces the following output:

$SSN = 123-45-6789

 !
 ! Convert a number to a string using an edit mask
 !
 move 1234567.89 to #value
 move #value to $value 999,999,999.99
 show '$Value = ' $value

Produces the following output:

$Value =   1,234,567.89

 !
 ! Convert a number to a string using a variable edit mask
 !
 move 123 to #counter
 move '099999' to $mask
 move #counter to $counter :$mask
 show '$Counter = ' $counter

Produces the following output:

$Counter = 000123

 !
 ! Convert a number to a string using the default edit mask
 !
 ! SQR, by default, outputs six digits of precision.
 ! If you require more or less precision, specify an edit mask.
 !
 move 123.78 to #defvar
 move #defvar to $defvar
 show '$DefVar = ' $defvar

Produces the following output:

$DefVar = 123.780000

 !
 ! Convert the number to a string using the locale default
 ! numeric edit mask
 !
 alter-locale number-edit-mask = '99,999,999.99'
 move 123456.78 to #nvar
 move #nvar to $nvar number
 show '$NVar = ' $nvar

Produces the following output:

$NVar =    123,456.78

 !
 ! Convert the money value to a string using the locale default 
 ! money edit mask
 !
 alter-locale money-edit-mask = '$9,999,999.99'
 move 123456.78 to #mvar
 move #mvar to $mvar money
 show '$MVar = ' $mvar

Produces the following output:

$MVar = $  123,456.78

  !
 ! Convert the date column to a string using the locale default 
 ! date edit mask
 !
 begin-select
 dcol
  from tables
 end-select
 alter-locale date-edit-mask = 'Mon-DD-YYYY'
 move &dcol to $dvar date
 show '$DVar = ' $dvar

Produces the following output:

$DVar = Jan-01-2004

  !
 ! Reset date to first day of the month
 ! ($date1 and $date2 have been defined as date variables)
 ! 
 let $date1 = datenow()
 move $date1 to $date2 'MMYYYY'
 show '$Date2 = ' $date2 edit 'MM/DD/YY HH:MI'

Produces the following output if the report was run in October of 2004:

$Date2 = 10/01/04 00:00

  !
 ! Convert date to a string
 ! ($date1 has been defined as a date variable)
 ! 
 move $date1 to $str_date 'DD-MON-YYYY'
 show '$Str_Date = ' $str_date

Produces the following output:

$Str_Date = 01-DEC-2004

  !
 ! Convert string (in partial format of SYYYYMMDDHHMISSNNN) to a
 ! date
 ! 
 move '20041129' to $date1
 show '$Date1 = ' $date1 edit 'Mon DD YYYY HH:MI'

Produces the following output:

$Date1 = Nov 29 2004 00:00

See The LET command for information about copying, editing, or converting fields

See The EDIT parameter of the PRINT command for a description of the edit masks

See The ALTER-LOCALE command for a description of the arguments NUMBER-EDIT-MASK, MONEY-EDIT-MASK, and DATE-EDIT-MASK

See The PRINT command regarding the default date-time components as a result of moving an incomplete date to a date variable

MULTIPLY

Syntax

MULTIPLY {src_num_lit|_var|_col} TIMES dst_num_var [ROUND=nn]

Description

Multiplies the first field by the second and places the result into the second field.

When dealing with money-related values (dollars and cents), use decimal variables rather than float variables. Float variables are stored as double-precision floating-point numbers, and small inaccuracies can appear when the program multiplies many numbers in succession. These inaccuracies can appear due to the way different hardware and software implementations represent floating point numbers.

Parameters

Parameter

Description

src_num_lit | _var | _col

Specifies a numeric source column, variable, or literal.

dst_num_var

Specifies a destination numeric variable.

ROUND

Rounds the result to the specified number of digits to the right of the decimal point. For float variables, this value can be from 0 to 15. For decimal variables, this value can be from 0 to the precision of the variable. For integer variables, this argument is not appropriate.

See The ADD command for more information

See The LET command for a discussion of complex arithmetic expressions

Example

The following example illustrates the MULTIPLY command:

multiply  &quantity  times  #cost
multiply  1.5  times  #result

NEW-PAGE

Syntax

NEW-PAGE [erase_from_line_num_lit|_var|_col]

Description

Writes the current page and begins a new one.

For line printers, this command can optionally erase the old page starting at a specified line. After this action is performed, the location on the page is unchanged—that is, the value of #current-line is the same. The default action is to erase the entire page and reset #current-line to its initial value for the page.

In reports in which an overflow page is needed, sometimes retaining information from the first page on succeeding pages is useful.

Each NEW-PAGE occurrence adds a form feed character to the output file unless you specify FORMFEED=NO in the DECLARE-LAYOUT for this program in the SETUP section.

Note: A NEW-PAGE automatically occurs if page overflow is detected. Tabular reports do not require explicit NEW-PAGE commands; use NEXT-LISTING instead.

Parameters

Parameter

Description

erase_from_line_num_lit | _var | _col

Specifies a numeric column, variable, or literal for line printers.

Example

The following example illustrates the NEW-PAGE command:

! Write current page, then erase it
! beginning at line 5.
new-page  5

NEW-REPORT

Syntax

NEW-REPORT {report_filename_txt_lit|_var|_col}

Description

Closes the current report output file and opens a new one with the specified file name.

This command is normally used with single reports only. When used with multiple report declarations, this command affects the current report only.

The internal page counter is reset to 1 when NEW-REPORT is executed.

Note: SQR does not create a report output file until the first page is completed. NEW-REPORT might not create a new file, for example, if no data is selected and nothing is printed on the page.

Parameters

Parameter

Description

{report_filename_txt_lit | _var | _col}

Specifies a new file name.

Example

The following example shows the NEW-REPORT command:

new-report  'rep2a.lis'
new-report  $next-file

Assign the report file name within an SQR report by issuing the NEW-REPORT command before printing. You might even prompt for the file name to use, as shown in the following example:

begin-report
  input  $file  'Enter report file name'
  new-report  $file
  ...

After execution of this command, the reserved variable $sqr-report is updated to reflect the new report name.

See DECLARE-REPORT, USE-REPORT

See The -F command-line flag

NEXT-COLUMN

Syntax

NEXT-COLUMN [AT-END={NEWLINE|NEWPAGE}] [GOTO-TOP={num_lit|_var|_col}] [ERASE-PAGE={num_lit|_var|_col}]

Description

Sets the current position on the page to the next column defined with the COLUMNS command.

Parameters

Parameter

Description

AT-END

Takes effect if the current column is the last one defined when NEXT-COLUMN is invoked.

GOTO-TOP

Causes the current line in the next column to be num_lit|_var|_col. This argument is useful when you are printing columns down the page.

ERASE-PAGE

Specifies where to begin erasing the page when an AT-END=NEWPAGE occurs.

Example

The following example prints columns across the page:

columns 10 50                     ! Define two columns
begin-select
name   (0,1,20)
phone  (0,+3,0) edit (xxx)bxxx-xxxx
  next-column  at-end=newline     ! Print names
                                  ! across the page
from phonelist                    ! within two columns.
order by name
end-select

The following example prints columns down the page:

columns 10 50
move 55 to #bottom_line
begin-select
name   (0,1,20)
phone  (0,+3,0) edit (xxx)bxxx-xxxx
  if #current-line >= #bottom_line
     next-column  goto-top=1  at-end=newpage
  else
     position (+1,1)
  end-if
from phonelist
order by name
end-select

See COLUMNS, USE-COLUMN

NEXT-LISTING

Syntax

NEXT-LISTING[NO-ADVANCE] [SKIPLINES={num_lit|_var|_col}] [NEED={num_lit|_var|_col}]

Description

Ends the current set of detail lines and begins another.

NEXT-LISTING is used in tabular reports. This command causes a new vertical offset in the page to begin.

After NEXT-LISTING is executed, line 1 is reset one line below the deepest line previously printed in the page body. That is, if you then write PRINT (1, 5), the string is printed on the next available line starting in column 5. Note that the SQR-reserved variable #current-line still reflects the actual line number within the page body.

The value of SKIPLINES must be a nonnegative integer. If it is less than 0 (zero), then 0 is assumed.

The value of NEED must be an integer greater than 0. If it is less than or equal to 0, then 1 is assumed.

Parameters

Parameter

Description

NO-ADVANCE

Suppresses any line movement when no printing has occurred since the previous NEXT-LISTING or NEW-PAGE. The default increments the line position even when nothing was printed.

SKIPLINES

Causes the specified number of lines to be skipped before setting up the new offset.

NEED

Specifies the minimum number of lines needed to begin a new listing or set of detail lines. If this number of lines does not exist, a new page is started. You can use NEED to prevent a group of detail lines from being broken across two pages.

Example

The following example shows the NEXT-LISTING command:

begin-select
cust_num  (1,1)      edit 099999           ! Each detail group prints
city   (,+3)                               ! starting on line 1 since
name   (2,10,30)                           ! NEXT-LISTING keeps
address   (,+2)                            ! moving line 1 down the
  next-listing  skiplines=1  need=2        ! page. NEED=2 keeps 2
from customers order by cust_num           ! line detail groups from
end-select                                 ! breaking across pages.

Note: The NEXT-LISTING command automatically issues a Use-Column 1 command if columns are active.

OPEN

Syntax

OPEN {filename_lit|_var|_col} AS {filenum_num_lit|_var|_col} {FOR-READING|FOR-WRITING|FOR-APPEND} {RECORD=length_num_lit[:FIXED|:FIXED_NOLF|:VARY]}
[STATUS=num_var]

Description

Opens an operating system file for reading or writing. After a file is opened, it remains open until explicitly closed by the CLOSE command. A maximum of 256 files can be opened at one time.

Parameters

Parameter

Description

{filename_lit | _var | _col}

Specifies the file name. The file name can be literal, variable, or column. This makes prompting for a file name at runtime easy.

{filenum_num_lit | _var | _col}

Specifies a number that identifies the file in the application. All file commands use the file number to reference the file. File numbers can be numeric variables and literals. The number can be any positive integer less than 64,000.

FOR-READING

When a file is opened for reading, SQR procures all data sequentially. SQR does not allow for random access of information.

FOR-WRITING

When a file is opened for writing, a new file is created. If a file of the same name already exists, it can be overwritten (this depends on the operating system).

FOR-APPEND

When a file is opened in append mode, the current file contents are preserved. All data written is placed at the end of the file. SQR creates the file if one does not already exist. For existing files, make sure that the attributes used are the same as those used when the file was created. Failure to do this causes the unpredictable results.

RECORD

For the VARY file type , this is the maximum size for a record. For the FIXED file type , this is the size of each record without the line terminator. For the FIXED_NOLF file type , this is the size of each record.

FIXED

This file type assumes that all records contained within the file are the same length. Terminate each record by a line terminator (system-dependent). You can use this file type when writing or reading binary data.

FIXED_NOLF

This file type specifies that all records contained within the file are the same length with no line terminators. When writing records, SQR pads short records with blank characters to ensure that each record is the same length. This file type can be used when SQR is writing or reading binary data.

VARY

This file type specifies that the records can be of varying length. Each record is terminated by a line terminator (system-dependent). Only records containing display characters (no binary data) can be used safely. When SQR is reading records, any data beyond the maximum length specified is ignored. This is the default file type.

STATUS

Sets the numeric variable to zero if the OPEN command succeeds and to –1 if it fails. Without the STATUS argument, a failure on OPEN causes SQR to halt. By using a STATUS variable, you can control what processing occurs when a file cannot be opened.

Example

This section contains two examples: a regular open command and an expanded command:

open 'stocks.dat' as 1  for-reading record=100
open 'log.dat'    as 5  for-writing record=70
open $filename    as #j for-append  record=80:fixed
open $filename    as 2  for-reading record=80:fixed_nolf

open $filename    as 6  for-reading record=132:vary status=#filestat
if #filestat != 0
  ... error processing ...
end-if

An encoding directive added to the OPEN command allows differently encoded files to be managed in a single run of SQR. When no ENCODING is specified on the OPEN command, SQR uses the file input or output encoding specified in the INI file unless the file is UCS-2 encoded and auto-detection of UCS-2 files is enabled. The complete syntax of the OPEN command is:

OPEN {filename_lit | _var | _col} AS {filenum_num_lit |
_var | _col}
{ FOR-READING | FOR-WRITING | FOR-APPEND }
{ RECORD = length_num_lit[:FIXED | :FIXED_NOLF |
:VARY]}
[ STATUS = num_var ]
[ ENCODING = { _var | _col | ASCII | ANSI | SJIS | JEUC
| EBCDIC |
EBCDIK290 | EBCDIK1027 | UCS-2 | UTF-8 | others... }

The ENCODING directive is allowed only when you are converting to Unicode internally.

See The READ, WRITE, and CLOSE commands for information about using files

PAGE-NUMBER

Syntax

PAGE-NUMBER position[pre_txt_lit[post_txt_lit]]

Description

Places the current page number on the page.

The text specified in pre_txt_lit and post_txt_lit is printed immediately before and after the number.

Parameters

Parameter

Description

position

Specifies the position of the page number. See the POSITION command for a description and examples of the position parameter.

pre_txt_lit

Specifies a text string to be printed before the page number.

post_txt_lit

Specifies a text string to be printed after the page number.

Example

The following example shows the PAGE-NUMBER command:

begin-footing 1
   page-number         (1,37)  'Page '      ! Will appear as
   last-page           ()  ' of '  '.'      ! "Page 12 of 25."
end-footing

See LAST-PAGE

POSITION

Syntax

POSITION position [@document_marker[COLUMNS{num_lit|_var|_col} [num_lit|_var|_col]...]]

Description

Sets the current position on a page.

Parameters

Parameter

Description

position

A position qualifier consisting of (line, column, width), where column and width are numbers that denote characters and spaces. Line, column, and width are all optional. If line or column is omitted, the print position is set by default to the current position, which is the position following the last printed item. Width is set by default to the width of the text that is being printed. A plus sign or minus sign indicates relative positioning in SQR. A plus sign moves the print position forward from the current position, and a minus sign moves it back.

@document_markerg

References a location defined in a document paragraph . In this case, the position used is the location of that marker in the text of the document.

COLUMNS

Defines columns beginning at the location of the document marker. The columns defined are relative to the position of the document marker.

When COLUMNS is used, the entire command cannot be broken across more than one program line.

Example

The following example shows the POSITION command:

position  (12,5)          ! Set current position to line 12, column 5.
position  (+2,25)         ! Set position 2 lines down, at 25th column.
position  ()  @total_location               ! Set position to document
print #total  ()  edit  999,999,999         ! marker @total_location.
position  ()  @name_loc  columns 1 30
print name  ()            !  Columns are defined at @name_loc and
next-column               !  29 characters to the right of @name_loc
print title ()

See The COLUMNS command for more information

PUT

Syntax

PUT {src_any_lit|_var|_col}... INTO dst_array_name(element)[field[(occurs)]]...

Description

Moves data into an array.

Columns retrieved from the database and SQR variables or literals can be moved into an array. The array must have been created previously by the CREATE-ARRAY command.

Considerations for Using PUT

When a date variable or column is moved into a text or char array field, the date is converted to a string according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the DATE Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

When a string variable, column, or literal is moved to a date array field, the string must be in the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats as listed in the DATE Column Formats table is used, or the database-independent format 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]' is used.

dst_array_name(element)

If array fields are listed, data is placed into each field in the sequence in which it is listed, in the occurrence specified for that field.

If array fields are not listed, data is placed into consecutive fields in the order in which they were defined in the CREATE-ARRAY command; data is copied into occurrence zero of each field of the element specified in the array.

 field [ ( occurs ) ]

Array element and field occurrence numbers can be numeric literals (123) or numeric variables (#j).

If no occurrence is specified, occurrence zero is used.

Parameters

Parameter

Description

src_any_var

The source variable or literal to be moved into the array. Numeric variables, literals, and database columns can be put into number (decimal, float, integer) fields. String variables, literals, and database columns can be put into char, text, or date fields. Date variables can be put into date, char, or text fields.

Example

In the following example, the four variables &name, #count, $date1, and $code are placed in the first four fields defined in the names array. The data is put into the #jth element of the array.

put  &name  #count $date1  $code  into  names(#j)

The following command places #j2, #j3, and #j4 into the zero through 2nd occurrences of the tot field in the #jth element of the totals array.

put  #j2  #j3  #j4  into  totals(#j)  tot(0)  tot(1)  tot(2)

The following command copies #count into the #j2th occurrence of the count field in the #jth element of the states array.

put  #count  into  states(#j)  count(#j2)

READ

Syntax

READ {filenum_lit|_var|_col} INTO {any_var:length_int_lit}...[STATUS=status_num_var]

Description

Reads the next record of a file into the specified variables.

Text and binary data are parsed according to the following criteria:

  • Text data is any string of characters. The length of the variable name indicates how many characters to place in the variable.

    After text is transferred, trailing blanks in the variable are omitted.

  • If the field was written as a date variable, then it can be read into a date variable or text variable.

    When reading a date into a date variable, it must be in the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats as listed in the DATE Column Formats table, or the database-independent format 'SYYYYMMDD[HH24[MI[SS[NNNNNN]'.

  • Binary numbers can be 1, 2, or 4 bytes in length.

    They must be read into numeric variables. Note that the bytes making up the binary number must be in the standard sequence expected by your operating system.

  • When the program is reading binary data, the file must be opened with the FIXED or FIXED-NOLF qualifier.

  • Only the integer portion of the number is represented with binary numbers.

    To maintain the decimal portion of the number, convert the number to a string variable.

  • If you use binary numbers, the file is not portable across platforms.

    Different hardware represents binary numbers differently.

The total length indicated for the variables must be less than or equal to the length of the record being read.

If no more records exist to read, the #end-file reserved variable is set to 1; otherwise, it is set to 0 (zero). Your program should check this variable after each READ command.

If STATUS is specified, SQR returns 0 if the read is successful; otherwise, it returns the value of errno, which is system-dependent.

Parameters

Parameter

Description

filenum_lit|_var | _col

Specifies the number assigned in the OPEN command to the file to be read.

any_var :length_int_lit

Specifies one or more variables into which data from the record that is read are to be put. length_int_lit specifies the length of each field of data.

STATUS

Specifies an optional variable into which a read status is returned.

Example

The following example shows several READ commands:

read  1  into  $name:30  $addr:30  $city:20  $state:2  $zip:5
read  3  into  $type:2  #amount:2  #rate:1  $code:5  $date:11
read  #j into  #sequence:2  $name:20  $title:15

The following example shows a READ command that reads two dates. One is loaded into a date variable; the other is loaded into a string variable, which is then converted to a date using the strtodate function.

.
.
.
declare-variable
 date $date1 $date2
 text $text
end-declare
.
.
.
read 4 into $date1:18 $text1:18
let $date2 = strtodate($text1,'SYYYYMMDDHHMISSNNN')
         or
let $date2 = strtodate($text1)

The following example shows a READ command with an INSERT loop:

begin-sql
 begin transaction
end-sql

while  1    ! Infinite loop, exited by BREAK, below.
 read  10  into  $company:40  $parent:30  $location:50
 if #end-file
  break   ! End of file reached.
 end-if
 begin-sql
  insert into comps (name, parent, location)
     values ($company, $parent, $location)
 end-sql
 add 1 to #inserts
 if #inserts >= 100
   begin-sql
    end transaction;
    begin transaction
   end-sql
 move 0 to #inserts
 end-if
end-while

begin-sql
 end transaction
end-sql

See commands for information about filesOPEN, CLOSE, WRITE

ROLLBACK

Syntax

ROLLBACK

Description

An automatic rollback is performed whenever SQR ends due to program errors. ROLLBACK is useful for testing or for certain error conditions.

ROLLBACK is an SQR command and should not be used inside an SQL paragraph.

Note: The ROLLBACK command can be used with Oracle, DB2 , Informix, and ODBC (Microsoft SQL Server is accessible only with SQR Server for ODBC). For Sybase and Microsoft SQL Server , use BEGIN TRANSACTION and ROLLBACK TRANSACTION within SQL paragraphs as in the following example. See the COMMIT command for an example of ROLLBACK.

Example

The following example shows the ROLLBACK command:

if #error-status = 1
   rollback
   stop
end-if

See The COMMIT command

SBTOMBS

Syntax

SBTOMBS { txt_var }

Description

Converts a single-byte character into a multibyte equivalent.

This command converts the specified string in the following way: Any occurrence of a single-byte character that also has a multibyte representation (numerals, punctuation, roman characters, and katakana) is converted. This command also converts a sequence of a kana character followed by certain grammatical marks into a single multibyte character, which combines the two elements.

Parameters

Parameter

Description

txt_var

Specifies the string to be converted.

See The TO_MULTI_BYTE function of the LET command

SECURITY

Syntax

SECURITY [SET=(sid [,sid]...)] [APPEND=(sid [,sid]...)] [REMOVE=(sid [,sid]...)] [MODE=mode]

Description

Enables you to mark sections of a report for security purposes.

The SECURITY command can be repeated as many times as desired for the current report. After the SECURITY command is carried out, all subsequent commands for the current report are constrained by the designated sids until the report ends or another SECURITY command executes.

You can use the SECURITY command wherever you use the PRINT command.

Parameters

Parameter

Description

SET

Sets the list of security IDs for subsequent commands. The previous list of security IDs is replaced by the specified security IDs. This argument is optional and can be used only once.

sid

Can be any string literal, column, or variable. The value is case-sensitive.

APPEND

Appends the specified security IDS to the current list. This argument is optional and can be used multiple times.

REMOVE

Removes the specified security IDS from the current list. This argument is optional and can be used multiple times.

MODE

Used to enable (reactivate) or disable (suspend) the security feature for the current report. This argument is optional and can be used only once.

mode

Can be any string literal, column, or variable. The value is not case-sensitive and can be either ON or OFF.

Example

The following example shows the SECURITY command:

Begin-Report
   Security Set=('Directors', 'Vice-Presidents')
      .               
      .         ! Only Directors and VPS can see this.
   Security Remove=('Directors').   
      .         ! Only VPS can see this.   
   Security Mode='Off'.   
      .         ! Anybody can see this.   
   Security Mode='On' Append=('Managers').   
      .         ! Only VPs and Managers can see this.
   Security Append=('Engineers').
      .         ! Only VPs, Managers, and Engineers can see this.
End-report

SET-COLOR

Syntax

SET-COLOR    [PRINT-TEXT-FOREGROUND=({color_name_lit|_var|_col|{rgb})]    [PRINT-TEXT-BACKGROUND=({color_name_lit|_var|_col|{rgb})]

Description

Defines default colors.

The SET-COLOR command is allowed wherever the PRINT command is allowed. If the specified color name is not defined, SQR uses the settings for the color name 'default.' Use the color name 'none' to color for the specified area.

Parameters

Parameter

Description

PRINT-TEXT- FOREGROUND

Defines the color in which the text is printed.

PRINT-TEXT- BACKGROUND

Defines the color to print as a background for the text.

{color_name_lit | _var | _col}

A color_name is composed of alphanumeric characters (A–Z, 0–9), the underscore (_) character, and the hyphen (-) character. It must start with an alphabetical (A–Z) character and is case-insensitive. The name 'none' is reserved and cannot be assigned a value. A name in the format (RGBredgreenblue) cannot be assigned a value. The name 'default' is reserved and can be assigned a value. 'Default' is used during execution when a referenced color is not defined in the runtime environment.

{rgb}

red_lit | _var | _col, green_lit | _var | _col, blue_lit | _var | _col where each component is a value in the range of 000 to 255. In the BEGIN-SETUP section, only literal values are allowed.

The default colors implicitly installed with SQR include:

black=(0,0,0)

white=(255,255,255)

gray=(128,128,128)

silver=(192,192,192)

red=(255,0,0)

green=(0,255,0)

blue=(0,0,255)

yellow=(255,255,0)

purple=(128,0,128)

olive=(128,128,0)

navy=(0,0,128)

aqua=(0,255,255)

lime=(0,128,0)

maroon=(128,0,0)

teal=(0,128,128)

fuchsia=(255,0,255)

Example

The following example shows the SET-COLOR command:

begin-setup
   declare-color-map
   light_blue = (193, 222, 229)
   end-declare
end-setup

begin-program
   alter-color-map name = 'light_blue' value = (193, 233, 230)

   print 'Yellow Submarine' ()
      foreground = ('yellow')
      background = ('light_blue')

   get-color print-text-foreground = ($print-foreground)  
   set-color print-text-foreground = ('purple')
   print 'Barney' (+1,1)
   set-color print-text-foreground = ($print-foreground)
end-program

See DECLARE-COLOR-MAP, ALTER-COLOR-MAP, GET-COLOR

SET-GENERATIONS

Syntax

SET-GENERATIONS=(dimension, hierarchy, dimension, hierarchy, dimension, hierarchy,...,...)

Description

Specifies dimension hierarchy for the previously declared dimension.

Returns the set of members in the dimension 'product' that are at the 5th generation in the dimension's hierarchy. (Returns all 'Brand Name' members (Generation Level 5) under the product hierarchy of 'all products.drink.alcoholic beverages.beer and wine.' This would increase the result set to a list of beers and wines.) Returns the set of members in the dimension 'time' that are at the 1st generation deep into the dimension. (Returns all 'Year' members (Generation Level 1) under the time hierarchy of '2004.Q1.2'. This reduces result set to '2004'.)

Example

The following example shows the SET-GENERATIONS command:

set-generations=('product',5,'time',1 )

SET-LEVELS

Syntax

Set-levels=(dimension,
level, dimension, level,...,...)

Description

Extends the dimension hierarchy for the previously declared dimension.

Set-levels used with only the previous 'set-members' returns all members under the product hierarchy and the next two generations (Product SubCategory and Brand Name) for the product hierarchy of all products.drink.alcoholic beverages.beer and wine'. Set-levels used with the previous 'set-members' and 'set-generations' returns all members for generation levels 5 through 7 under the product hierarchy of all products.drink.alcoholic beverages.beer and wine.'

Example

The following example shows the SET-LEVELS command:

set-levels=('product',2 )

SET-MEMBERS

Syntax

set-members=(dimension,
hierarchy, dimension, hierarchy,..., ...)

Description

Returns the set of members in a dimension, level, or hierarchy for which name is specified by a string.

Example

Returns the set of members in the dimension 'product' at the specific hierarchy of 'all products', at a specific level of 'drink', at a specific level of 'alcoholic beverages', at a specific level of 'beer and wine'. Returns the set of members in the dimension 'time' at the specific hierarchy of '2004', at the specific level of 'Q1', at the specific level of '2'.

set-members=('product','all products.drink.alcoholic beverages.beer and wine','time','2004.Q1.2')

SHOW

Syntax

SHOW[cursor_position] [CLEAR-SCREEN|CS|CLEAR-LINE|CL][any_lit|_var|_col] [EDITedit_mask|NUMBER|MONEY|DATE][BOLD][BLINK]
[UNDERLINE][REVERSE][NORMAL][BEEP][NOLINE]...

Description

Displays one or more variables or literals on the screen. In addition, cursor control is supported for ANSI terminals.

Any number of variables and screen positions can be used in a single command. Each one is processed in sequence.

Screen locations can be indicated by either fixed or relative positions in the format (A,B), where A is the line and B is the column on the screen. A, B, or both can also be numeric variables. Relative positions depend on where the previous SHOW command ended. If the line was advanced, the screen cursor is usually immediately to the right of the previously displayed value and one line down.

Fixed or relative cursor positioning can be used only within the boundaries of the terminal screen. Scrolling off the screen using relative positioning, for example (+1,1), is not supported. Instead, use a SHOW command without any cursor position when you want to scroll. Also, you cannot mix SHOW and DISPLAY commands while referencing relative cursor positions.

The SHOW command does not advance to the next line if a cursor location (...), CLEAR-SCREEN, CLEAR-LINE, or BEEP is used. (A SHOW command without any of these arguments automatically advances the line.) To add a line advance, add (+1,1) to the end of the line or use an extra empty SHOW command.

Only ANSI terminals are supported for cursor control, screen blanking, line blanking, and display characteristics.

Dates can be contained in a date variable or column, or a string literal, column, or variable. When the program displays a date variable or column without an edit mask, the date is displayed according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the Default Database Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

When displaying a date in a string literal, column, or variable using EDIT or DATE, the string must be in the format specified by the SQR_DB_DATE_FORMAT setting, one of the database-dependent formats as listed in the Default Database Formats table, or the database-independent format 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]].

Parameters

Parameter

Description

cursor_position

Specifies the position on the screen to begin the display.

{CLEAR-SCREEN | CS}

Clears the screen and sets the cursor position to (1,1).

{CLEAR-LINE | CL}

Clears a line from the current cursor position to the end of the line.

{any_lit | _var | _col}

Specifies the information to be displayed.

EDIT

Shows variables under an edit mask. If the mask contains spaces, enclose it in single quotes. For additional information regarding edit masks, see the PRINT command.

NUMBER

Indicates that any_lit|_var|_col is to be formatted with the NUMBER-EDIT-MASK from the current locale. (See the ALTER-LOCALE command.) This option is not valid for date variables.

MONEY

Indicates that any_lit|_var|_col is to be formatted with the MONEY-EDIT-MASK from the current locale. (See the ALTER-LOCALE command.) This option is not valid for date variables.

DATE

Indicates that any_lit|_var|_col is to be formatted with the DATE-EDIT-MASK from the current locale. (See the ALTER-LOCALE command.) This option is not valid for numeric variables. If DATE-EDIT-MASK has not been specified, the date is displayed with the default format for that database (see the Default Database Formats table).

BOLD, BLINK, UNDERLINE, and REVERSE

Changes the display of characters on terminals that support those characteristics. Some terminals support two or more characteristics at the same time for the same text. To disable all special display characteristics, use NORMAL.

NORMAL

Disables all special display characteristics set with BOLD, BLINK, UNDERLINE, and REVERSE.

BEEP

Causes the terminal to beep.

NOLINE

Inhibits a line advance.

Example

The following program segments illustrate the various features of the SHOW command:

 !
 ! Show a string using an edit mask
 !
 let $ssn = '123456789'
 show $ssn edit xxx-xx-xxxx

Produces the following output:

123-45-6789

 !
 ! Show a number using an edit mask
 !
 show 1234567.89 edit 999,999,999.99

Produces the following output:

1,234,567.89

 !
 ! Show a number using the default edit mask
 !
 show 123.78

Produces the following output:

123.780000

 !
 ! Show a number using the locale default numeric edit mask
 !
 alter-locale number-edit-mask = '99,999,999.99'
 show 123456.78 number

Produces the following output:

   123,456.78

 !
 ! Show a number using the locale default money edit mask
 !
 alter-locale money-edit-mask = '$$,$$$,$$8.99'
 show 123456.78 money

Produces the following output:

$123,456.78

 !
 ! Show a date column using the locale default date edit mask
 !
 begin-select
 dcol
  from tables
 end-select
 alter-locale date-edit-mask = 'DD-Mon-YYYY'
 show &dcol date

Produces the following output:

01-Jan-2004

 !
 ! Show two values on the same line
 !
 show 'Hello' ' World'

Produces the following output:

Hello World

 !
 ! Show two values on the same line with editing of the values
 !
 let #taxes = 123456.78
 show 'You owe ' #taxes money ' in back taxes.'

Produces the following output:

You owe $123,456.78 in back taxes.

The following program illustrates the usage of additional options of the SHOW command. Only terminals that support the ANSI escape characters can use the cursor control, screen blanking, line blanking, and display attributes.

begin-program
 !
 ! Produces a menu for the user to select from
 !
 show clear-screen
      (3,30)  bold 'Accounting Reports for XYZ Company' normal
      (+2,10)  '1. Monthly Details of Accounts'
      (+1,10)  '2. Monthly Summary'
      (+1,10)  '3. Quarterly Details of Accounts'
      (+1,10)  '4. Quarterly Summary'

 !
 ! Show a line of text and numerics combined
 !
 show (+2,1)
      'The price is ' #price edit 999.99 

      '    Total = ' #total edit 99999.99

 !
  ! Put an error message on a particular line
 !
 show (24,1) clear-line 'Error in SQL.  Please try again.' beep
end-program

See The LET command for information about copying, editing, or converting fields

See The EDIT parameter of the PRINT command for a description of the edit masks

See The ALTER-LOCALE command for a description of the arguments NUMBER-EDIT-MASK, MONEY-EDIT-MASK, and DATE-EDIT-MASK

See DISPLAY

STOP

Syntax

STOP [QUIET]

Description

The STOP command halts SQR and executes a ROLLBACK command (not in Sybase, Microsoft SQL Server, or Informix). All report page buffers are flushed if they contain data; however, no headers or footers are printed and the AFTER-PAGE and AFTER-REPORT procedures are not executed.

STOP is useful in testing.

Parameters

Parameter

Description

QUIET

Causes the report to finish with the "SQR: End Of Run" message, instead of ending with an error message.

Example

The following example shows the STOP command:

if #error-status = 1
   rollback
   stop
else
   commit
   stop quiet
end-if

STRING

Syntax

STRING {src_any_lit|_var|_col}...BY {delim_txt_lit|_var|_col} INTO dst_txt_var

Description

Concatenates a list of variables, columns, or literals into a single text variable. Each member of the list is separated by the specified delimiter string.

The destination string must not be included in the list of source strings.

Parameters

Parameter

Description

{src_any_lit|_var|_col}

Specifies one or more fields to be concatenated, separated by the delim_txt_lit|_var|_col character or characters, and placed into the dst_txt_var variable.

If the source is a date variable or column, it is converted to a string according to the following rules:

For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

If this has not been set, SQR uses the format listed in the Default Database Formats table.

For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

{delim_txt_lit|_var|_col}

Specifies one or more characters to be used as separator characters between the source fields.

dst_txt_var

Specifies the destination field for the concatenated result.

Example

The following example shows the STRING command:

string  &name  &city  &state  &zip  by  ' - '  into  $show-info
                  ! Result:  Sam Mann - New York - NY - 11287
string  &cust_num  &entry-date  &total  by  ','  into  $cust-data
                  ! Result:  100014,12-MAR-04,127
                  ! Use null delimiter.
string  &code1  &code2  &code3  by  ''  into  $codes123
                  ! Result:  AGL

See The UNSTRING command for additional information

See The "||" concatenation operator in the Operators table under the LET command

SUBTRACT

Syntax

SUBTRACT {src_num_lit|_var|_col} FROM dst_num_var[ROUND=nn]

Description

Subtracts the first value from the second and moves the result into the second field.

When dealing with money-related values (dollars and cents), use decimal variables rather than float variables. Float variables are stored as double-precision floating-point numbers, and small inaccuracies can appear when you are subtracting many numbers in succession. These inaccuracies can appear due to the way floating point numbers are represented by different hardware and software implementations.

Parameters

Parameter

Description

{src_num_lit | _var | _col}

Is subtracted from the contents of dst_num_var.

dst_num_var

Contains the result after execution.

ROUND

Rounds the result to the specified number of digits to the right of the decimal point. For float variables this value can be from 0 (zero) to 15. For decimal variables, this value can be from 0 to the precision of the variable. For integer variables, this argument is not appropriate.

Example

The following example shows the SUBTRACT command:

subtract  1  from  #total      ! #total - 1
subtract &discount from #price ! #price - &discount

See The ADD command for more information

See The LET command for information about complex arithmetic expressions

TOC-ENTRY

Syntax

TOC-ENTRY TEXT={src_txt_lit|_var|_col} [LEVEL={level_num_lit|_var|_col}]

Description

Enter the text in the table of contents at the desired level.

Parameters

Parameter

Description

TEXT

Specifies the text to be placed in the table of contents.

LEVEL

Specifies the level at which to place the text. If this argument is not specified, the value of the previous level is used.

Example

The following example shows the TOC-ENTRY command:

toc-entry text = &heading 
toc-entry text = &caption level=2

See The DECLARE-TOC command

UNSTRING

Syntax

UNSTRING {{src_txt_lit|_var|_col}|{src_date_var|_col}}
BY {delim_txt_lit|_var|_col} INTO dst_txt_var...

Description

Copies portions of a string into one or more text variables.

Each substring is located usingby means of the specified delimiter. The source string must not be included in the list of destination strings.

If more destination strings than substrings are found in the source strings, the extra destination strings are each set to an empty string.

If more substrings are found in the source string than in the destination strings, the extra substrings are not processed. The programmer is responsible for ensuring that enough destination strings are specified.

If the source is a date variable or column, it is converted to a string according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the Default Database Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

Parameters

Parameter

Description

{src_txt_lit|_var|_col}|{ src_date_var|_col}

Specifies the source field to be parsed.

delim_txt_lit|_var|_col

Specifies one or more characters to be used to delimit the fields within {src_txt_lit|_var|_col}|{src_date_var|_col}

dst_txt_var

Specifies one or more destination fields to receive the results.

Example

The following example shows the UNSTRING command:

unstring $show-info by ' - ' into $name $city $state $zip
unstring $cust-data by ',' into $cust_num $entry-date $total

See STRING, EXTRACT

See The substr and instr functions in the Miscellaneous Functions table under the LET command

UPPERCASE

Syntax

UPPERCASE txt_var

Description

Converts a string variable to uppercase.

Parameters

Parameter

Description

txt_var

Specifies a text variable to be converted to uppercase.

Example

The following example shows the UPPERCASE command:

input  $state  'Enter state abbreviation'
uppercase  $state     ! Force uppercase.

See The upper function in the Miscellaneous Functions table under the LET command.

USE

Syntax

USE database

Description

Uses the named database rather than the default database associated with your username. (Sybase and Microsoft SQL Server only.)

Use USE in the SETUP section only. When used, it must appear at the top of your report, before any queries are defined.

To reference more than one database in a program, specify secondary databases explicitly. For example:

from sqdb.sqr.customers

You cannot issue the Sybase or Microsoft SQL Server USE command from within an SQL paragraph.

Parameters

Parameter

Description

database

Specifies the name of the database to use.

Example

The following example shows the USE command:

begin-setup
 use pubs
end-setup

USE-COLUMN

Syntax

USE-COLUMN {column_number_int_lit|_var|_col}

Description

Sets the current column.

The column must have been defined previously with the COLUMNS command.

To stop printing within columns, use a column number of 0 (zero). Printing returns to normal; however, the columns remain defined for subsequent NEXT-COLUMN or USE-COLUMN commands.

Parameters

Parameter

Description

{column_number_int_lit|_var|_col}

Specifies the number of the defined column (not the location on the page). For example, if five columns are defined, the column_number_int_lit|_var|_col can be 1 to 5.

Example

The following example shows the USE-COLUMN command:

use-column  3     ! Print total in 3rd column.
print  #total  ()  999,999
use-column  0     ! End of column printing.

USE-PRINTER-TYPE

Syntax

USE-PRINTER-TYPE printer-type

Description

Sets the printer type to be used for the current report.

The USE-PRINTER-TYPE command sets or alters the printer type to be used for the current report. The USE-PRINTER-TYPE command must appear before the first output is written to that report. If output has already been written to the report file, the USE-PRINTER-TYPE command is ignored.

Parameters

Parameter

Description

printer-type

Specifies the printer type to be used for the current report. See DECLARE-PRINTER for valid types.

Example

The following example shows the USE-PRINTER-TYPE command:

use-report customer_orders
use-printer-type PostScript
print (1, 1) 'Customer Name: '
print () $customer_name

See DECLARE-PRINTER, DECLARE-REPORT, USE-REPORT

USE-PROCEDURE

Syntax

USE-PROCEDURE [FOR-REPORTS=(report_name1[,report_namei]...)] [BEFORE-REPORT=procedure_name[(arg1[,argi]...)]] [AFTER-REPORT=procedure_name[(arg1[,argi]...)]] [BEFORE-PAGE=procedure_name[(arg1[,argi]...)]] [AFTER-PAGE=procedure_name[(arg1[,argi]...)]]

Description

Changes the procedure usage.

The USE-PROCEDURE command must be issued in the PROGRAM or PROCEDURE sections of an SQR program. USE-PROCEDURE is a runtime command; its compile-time equivalent is DECLARE-PROCEDURE. You can use the command as often as required to change to the necessary procedures required by the reports. If you issue multiple USE-PROCEDURE commands, each remains in effect for that report until altered by another USE-PROCEDURE command for that report. In this way, you can use one to change common procedures for ALL reports and others to change unique procedures for individual reports. The referenced procedures can accept arguments.

If no FOR-REPORTS is specified, ALL is assumed. Initially, the default for each of the four procedure types is NONE. If a procedure is defined in one DECLARE-PROCEDURE for a report, that procedure is used unless NONE is specified.

You can change the BEFORE-REPORT only before the first output is written to that report, because that causes the BEFORE-REPORT procedure to be executed.

Parameters

Parameter

Description

FOR-REPORTS

Specifies the reports that are to use these procedures. This argument is required only for a program with multiple reports. If you are writing a program that produces a single report, you can ignore this argument.

BEFORE-REPORT

Specifies a procedure to execute at the time of execution of the first command, which causes output to be generated. You can use the command, for example, to create a report heading.

AFTER-REPORT

Specifies a procedure to execute just before the report file is closed at the end of the report. This argument can be used to print totals or other closing summary information. If no report was generated, the procedure does not execute.

BEFORE-PAGE

Specifies a procedure to execute at the beginning of every page, just before the first output command for the page. It can be used, for example, to set up page totals.

AFTER-PAGE

Specifies a procedure to execute just before each page is written to the file. This argument can be used, for example, to display page totals.

You can also specify arguments to be passed to the procedure. Arguments can be any variable, column, or literal.

Example

The following example shows the USE-PROCEDURE command:

use-procedure               ! These procedures will

for-reports=(all)           ! be used by all reports

before-report=report_heading

after-report=report_footing
use-procedure               ! These procedures will

for-reports=(customer)      ! be used by the customer

before-page=page_setup      ! report

after-page=page_totals
use-procedure               ! The after-report 

for-reports=(summary)       ! procedure will be 

after-report=none           ! disabled for the

                            ! summary report

See DECLARE-PROCEDURE

USE-REPORT

Syntax

USE-REPORT {report_name_lit|_var|_col}

Description

For programs with multiple reports, enables the user to switch between reports.

The USE-REPORT command specifies which report files the subsequent report output is to be written to. An application can contain several USE-REPORT statements to control several reports.

You must specify the report name and report characteristics in a DECLARE-REPORT paragraph and in the associated DECLARE-LAYOUT and DECLARE- PRINTER paragraphs.

Parameters

Parameter

Description

{report_name_lit|_var|_col}

Specifies the report to become the current report. All subsequent PRINT and PRINT-DIRECT statements are written to this report until the next USE- REPORT is encountered.

Example

The following example shows the USE-REPORT command:

use-report customer_orders
use-printer-type PostScript
print (1, 1) 'Customer Name: '
print () $customer_name

See DECLARE-REPORT, DECLARE-LAYOUT, DECLARE-PRINTER , USE-PRINTER-TYPE

WHILE

Syntax

WHILE logical_expression

The general format of a WHILE command is:

WHILE logical_expression SQR_commands...
[BREAK] SQR_commands... END-WHILE

Description

Begins a WHILE ... END-WHILE loop.

The WHILE loop continues until the condition being tested is FALSE.

An expression returning 0 (zero) is considered FALSE; an expression returning nonzero is TRUE.

BREAK causes an immediate exit of the WHILE loop; SQR continues with the command immediately following END-WHILE.

WHILE commands can be nested to any level and can include or be included within IF and EVALUATE commands.

Parameters

Parameter

Description

logical_expression

A valid logical expression. See the LET command for a description of logical expressions.

Example

This example shows an IF nested within a WHILE:

while #count < 50
    do get_statistics
    if #stat_count = 100
       break     ! Exit WHILE loop.
    end-if
    add 1 to #count
end-while

You can use single numeric variables in your expression to make your program more readable, for example, when using flags:

move 1 to #have_data
...
 while #have_data
   ...processing...
end-while

This example sets up an infinite loop:

while 1
    ...processing...
    if ...
       break     ! Exit loop
    end-if
end-while

Any complex expression can be used in the WHILE command, as shown in this example:

while #count < 100 and (not #end-file or isnull(&state))
   ...
end-while

SeeThe LET command for a description of expressions.

WRITE

Syntax

WRITE {filenum_lit|_var|_col} FROM {{{txt_lit|_var|_col}|{date_var|_col}|num_col} [:len_int_lit]}|{num_lit|_var:len_int_lit}}... [STATUS=status_num_var]

Description

Writes a record to a file from data stored in variables, columns, or literals.

The file must already be opened for writing.

If length is specified, the variable is either truncated at that length or padded with spaces to that length. If length is not specified (for string variables or database columns), the current length of the variable is used.

When you are writing numeric variables, the length argument is required. Only 1-byte, 2-byte, or 4-byte binary integers are written. Floating point values are not supported directly in the WRITE command. However, you can first convert floating point numbers to strings and then write the string.

When you are writing binary data, you must open the file using the FIXED or FIXED-NOLF qualifiers. The file is not portable across platforms because binary numbers are represented differently.

When writing a date variable or column, the date is converted to a string according to the following rules:

  • For DATETIME columns and SQR DATE variables, SQR uses the format specified by the SQR_DB_DATE_FORMAT setting.

    If this has not been set, SQR uses the first database-dependent format as listed in the Default Database Formats table.

  • For DATE columns, SQR uses the format specified by the SQR_DB_DATE_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format listed in the DATE Column Formats table.

  • For TIME columns, SQR uses the format specified by the SQR_DB_TIME_ONLY_FORMAT setting.

    If this has not been set, SQR uses the format as listed in the TIME Column Formats table.

Text literals take the length of the literal.

Files opened for writing are treated as having variable-length records. If you need a fixed-length record, specify a length for each variable written to the file.