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