INTOUCH® 4GL
A Guide to the INTOUCH Language


Previous Contents Index


Chapter 7
Program Directives

7.1 Compile Directives

The following sections describe the directives that are available for use in your programs. These directives are invoked when the compiler OLDs in a program and/or when a program is compiled.

7.1.1 %MESSAGE

FORMAT:


        %MESSAGE 'quoted_text' 

EXAMPLE:


        10  %MESSAGE 'Including HELP module' 
        20  %INCLUDE 'tti_run:help' 
        30  END 

DESCRIPTION:

This compiler directive displays a message, quoted_text, on the message line. The message is displayed when a program is OLD'ed into a workspace or compiled.

7.1.2 %MESSAGE ERROR

FORMAT:


        %MESSAGE ERROR: 'quoted_text' 

EXAMPLE:


        10  %MESSAGE ERROR: 'Using experimental HELP module' 
        20  %INCLUDE 'tti_run:help' 
        30  END 

DESCRIPTION:

This compiler directive rings the bell and displays an error message, quoted_text, on the message line. The message is displayed when a program is OLD'ed into a workspace or compiled.

7.1.3 %INCLUDE

FORMAT:


        %INCLUDE 'file_spec' 

EXAMPLE:


        1000  %INCLUDE 'tti_run:example' 

PURPOSE:

%INCLUDE allows you to put common subroutines into a separate file to be shared among applications.

DESCRIPTION:

%INCLUDE includes a source code, file_spec, file into the current INTOUCH program. The included file cannot contain line numbers. The default extension for the included file is .INC.

7.1.4 %INCLUDE CONDITIONAL

FORMAT:


        %include CONDITIONAL: 'file_spec' 

DESCRIPTION:

If the file to be included, file_spec, does not exist, no error is generated. This allows programs to conditionally include modules.

%INCLUDE CONDITIONAL includes a source code, file_spec, file into the current INTOUCH program if the file to be included is found. The included file cannot contain line numbers. The default extension for the included file is .INC.

7.1.5 %DEBUG

FORMAT:


        %DEBUG INTOUCH_statement 

EXAMPLE:


        10  %DEBUG PRINT 'DEBUG Items' 
        20  END 

DESCRIPTION:

The %DEBUG directive gives an error only if an image compile (/COMPILE) is being done. Use this directive to make sure that DEBUG code does not show up in production applications.


Chapter 8
Assigning Variables

Variables specify storage locations. Numeric and string variables are assigned values with the LET statement. String variables can also be assigned values with the LSET, RSET and CSET statements.

The LET statement assigns the value of an expression to a variable. The expression is evaluated and its value is stored in the location specified by the variable. The data types of the expression and the variable must match. Thus, you must assign a string variable string values and you must assign numeric variables numeric values. A string variable must end with a dollar sign "$" unless you declare it. An integer variable must end with a percent sign (%) unless you declare it.

The DECLARE statement allows you to dispense with data type designations. DECLARE declares a variable as either string, integer or real. Once the variable has been declared, you do not need to attach a $ or % to it. Functions, arrays, etc., can also be declared with the DECLARE statement.

8.1 DECLARE

FORMAT:


        DECLARE [STRING | INTEGER | REAL | BOOLEAN | DYNAMIC] var, var... 

EXAMPLE:


        10  DECLARE STRING name, sex 
            DECLARE INTEGER age 
            DECLARE REAL amount 
            DECLARE DYNAMIC anything 
            DECLARE BOOLEAN is_male 
        20  INPUT 'Enter your name': name 
            INPUT 'Enter your age': age 
            INPUT 'Enter your sex': sex 
            INPUT 'Enter an amount': amount 
        25  IF  sex = 'male'  THEN  is_male = true  else  is_male = false 
        30  PRINT 
            PRINT name; ' is a'; AGE; 'year old '; sex 
            PRINT name; ' entered the amount'; amount 
        35  IF  is_male  THEN  PRINT name; ' is male' 
        40  anything = 4 + 5 
            PRINT 'This dynamic variable contains: '; anything 
            anything = 'kitty' 
            PRINT 'Now it contains a string value: '; anything 
        50  END 
 
        RNH 
        Enter your name? Sammy 
        Enter your age? 28 
        Enter your sex? male 
        Enter an amount? 25.38 
 
        Sammy is a 28 year old male 
        Sammy entered the amount 25.38 
        Sammy is male 
        This dynamic variable contains:  9 
        Now it contains a string value: kitty 

PURPOSE:

Use DECLARE to specify the data types of variables, functions, etc. Once you have declared the data type of a variable or function, you do not have to designate them with a trailing $ or %.

DESCRIPTION:

DECLARE declares the data type of a variable or function. The STRING option indicates that the following are string variables or functions. INTEGER declares integer numeric. REAL indicates real numeric. The BOOLEAN option indicates that the following are Boolean variables. Only one of the four data type options can be used in each DECLARE statement. Any number of variables can be declared with a DECLARE statement.

DECLARE DYNAMIC declares one or more variables to be of type DYNAMIC. A variable of type DYNAMIC receives the data type of the data that you put into it. You can find out the current data type of a dynamic variable with the DTYPE function (see DTYPE(expr)).

Multiple Data Types

You can declare multiple data types by using the following format:


        DECLARE datatype var, var, datatype var, var, datatype var, var, ... 

For example:


        10  DECLARE STRING name, sex, INTEGER age, year, REAL amount 
        20  INPUT 'Enter your name': name 
            INPUT 'Enter your age': age 
            INPUT 'Enter your sex': sex 
            INPUT 'Enter the year': year 
            INPUT 'Enter an amount': amount 
        30  PRINT 
            PRINT name; ' is a'; age; 'year old '; sex; ' in'; year 
            PRINT name; ' entered the amount'; amount 
        40  END 
 
        rnh 
        Enter your name? Terry 
        Enter your age? 25 
        Enter your sex? female 
        Enter the year? 1996 
        Enter an amount? 582.69 
 
        Terry is a 25 year old female in 1996 
        Terry entered the amount 582.69 

8.1.1 DECLARE STRUCTURE

FORMAT:


        DECLARE STRUCTURE struc_name1 [, struc_name2 ...] 

EXAMPLE:


        10  DECLARE STRUCTURE str 
            OPEN STRUCTURE cl: NAME 'tti_run:client' 
            ASK STRUCTURE cl: ID cl_id$ 
            SET STRUCTURE str: ID cl_id$ 
        20  EXTRACT STRUCTURE str 
            END EXTRACT 
            FOR EACH str 
              PRINT str(#1); ' '; str(#2) 
            NEXT str 
        30  END 
 
        RNH 
        20000 Smith 
        20001 Jones 
        20002 Kent 
        23422 Johnson 
        32001 Waters 
        43223 Errant 
        80542 Brock 
        80543 Cass 
        80544 Porter 
        80561 Derringer 
        80573 Farmer 

DESCRIPTION:

DECLARE STRUCTURE declares one or more symbols to be of type STRUCTURE. Once you have declared a symbol to be of type STRUCTURE, you can use it in statements such as SET STRUCTURE..ID to write generalized routines where you do not know at compile time which structure you are going to use.

Usage example: This statement could be used in the situation where you have a transaction structure and a transaction history structure and, optionally, want a report on one or the other. You could use one report program and the DECLARE STRUCTURE statement to declare which structure to use when the user makes the report selection.

8.1.2 DECLARE PREFIX

FORMAT:


        DECLARE PREFIX str_expr 

EXAMPLE:


        irp$total   prefix is IRP 
        doit$now$   prefix is DOIT 
        doing_it$   there is no prefix 

DESCRIPTION:

Any variable that contains as part of the body of its name a "$" is said to be a PREFIXED variable.

In some cases, you might want an IMPLICIT prefix for variables in a routine. To declare an IMPLICIT prefix:


        DECLARE PREFIX prefix_name 

EXAMPLE:


        PRINT total    <-->  PRINT doit$total 
        PRINT name$    <-->  PRINT doit$name$ 
        PRINT xyz$sum  <-->  PRINT xyz$sum    (prefix is explicitly given) 

DESCRIPTION:

The DECLARE PREFIX statement causes all non-prefixed variable references, structure name references and field name references to inherit a prefix (i.e. "DOIT").

Declared prefixes are local to the routine that they are declared in. For this first release, nested declared prefixes are not supported. The following statements turn OFF any declared prefixing:


        ROUTINE routine_name 
        END ROUTINE 
        DECLARE PREFIX none 

In addition, at run time, prefixing is turned off before and after a string is EXECUTEd. (See Section 11.3 for information on the EXECUTE statement.) This allows you to locally prefix executed code:


        10  a = 100 
        20  EXECUTE 'DECLARE PREFIX excode \ a = 45 \ PRINT a' 
        30  PRINT a 
        40  EXECUTE 'PRINT excode$a' 
        50  END 
 
        RNH 
        45 
        100 
        45 

If you want the same prefix to be used throughout an entire procedure, you need to put a DECLARE PREFIX at the beginning of the procedure and after every ROUTINE statement.

When referencing structure field names and using a prefix, you must:


        STRUC(#'field_name') 
 
               so: 
 
        VEND(city)  --> vend(#'city') 

Without the quotes, CITY would receive a prefix and would be an invalid field name.

Prefixing also applies to structure names. Therefore, if the structure is not opened within the prefixed routine that references it, you must have opened the structure with an explicit prefix.


        10  OPEN STRUCTURE ar$cust : NAME 'tti_run::customer', ACCESS INPUT 
            GOSUB find_customer 
            STOP 
 
       100  ROUTINE find_customer 
              DECLARE PREFIX find 
              c$ = '13727' 
              SET STRUCTURE ar$cust, FIELD custnbr : KEY c$ 
              PRINT ar$cust(#'name') 
            END ROUTINE 
       999  END 

8.2 OPTION Statements

8.2.1 OPTION REQUIRE DECLARE

FORMAT:


        OPTION REQUIRE DECLARE 

EXAMPLE:


        10  OPTION REQUIRE DECLARE 
        20  DECLARE STRING name, comment 
        30  INPUT 'Please enter your name': name 
        40  LINE INPUT 'Enter a comment in quotes': comment 
        50  PRINT name; ' says, '; comment 
        60  END 
 
        RNH 
        Please enter your name? George 
        Enter a comment in quotes? 'Have a nice day!' 
        George says, 'Have a nice day!' 

DESCRIPTION:

OPTION REQUIRE DECLARE causes INTOUCH to require all variables in the program to be declared. If the OPTION REQUIRE DECLARE statement is used and a variable is left undeclared, INTOUCH will return an error when program execution is attempted. The OPTION REQUIRE DECLARE statement should occur before any DECLARE statements and before any variables are assigned.

8.2.2 OPTION BASE

FORMAT:


        OPTION BASE  [0 | 1] 

DESCRIPTION:

OPTION BASE sets the lowest subscript or base for arrays. The base can be either zero or one. If you use OPTION BASE 0, the lowest element of an array has the subscript zero (0). If you use OPTION BASE 1, the lowest element is subscript one (1).

See Section 10.1.3 for an example and detailed information on this statement.

8.3 LET

FORMAT:


        [LET] var = expr 

EXAMPLE:


        10  INPUT 'Last name': last$ 
            INPUT 'First name': first$ 
            LET name$ = first$ & ' ' & last$ 
            PRINT name$ 
        20  END 
 
        RNH 
        Last name? Taylor 
        First name? Rick 
        Rick Taylor 

PURPOSE:

Use the LET statement to store information into a variable or data structure.

DESCRIPTION:

var is the variable being assigned a value. expr is an expression. The expression is evaluated and its result is assigned to the variable. The expression can be any INTOUCH expression (see Section 3.2.) The variable and the expression data types must match. For instance, if var is a string variable, expr must be a string expression.

NOTE: The keyword LET is optional. For example:


        LET name$ = first$ & ' ' & last$ 
can be stated as:


        name$ = first$ & ' ' & last$ 

When INTOUCH executes the LET statement, it first evaluates the expression on the right side of the equal sign. It then assigns this value to the variable on the left side of the equal sign. The variable represents a location in memory. The value of the expression is stored in this location. Each time a new value is assigned, the old value is lost and the new value is stored in its memory location.

Assigning Numeric Values


        10  INPUT 'Amount': amount 
            LET rounded% = amount 
        20  PRINT 'Real numeric amount:'; amount 
            PRINT 'Integer amount (after rounding):'; rounded% 
        30  END 
 
        RNH 
        Amount? 1.54 
        Real numeric amount: 1.54 
        Integer amount (after rounding): 2 

Assigning String Values

8.4 LSET, RSET and CSET

LSET, RSET and CSET assign string values to variables. LSET left-justifies the new value. RSET right-justifies and CSET center-justifies it. These statements can only be used to assign string values.

LSET, RSET and CSET justify the new value within the length of the previous value. For example, in the following program, HEADING$ has a length of twenty characters and consists of twenty dots:


        10  heading$ = REPEAT$('.', 20)          ! Twenty dots 
        20  PRINT '('; heading$; ')' 
        30  END 
 
        RNH 
        (....................) 

In the following example, the RSET statement is used to assign the new value 'Page 12' to HEADING$. INTOUCH uses the current length of HEADING$, 20 characters, and replaces it with the new value, 'Page 12'. INTOUCH right-justifies this value by padding it with 13 leading spaces. Thus, HEADING$ still has a length of twenty characters.


        10  heading$ = REPEAT$('.', 20)          ! Twenty dots 
            PRINT '('; heading$; ')' 
        20  RSET heading$ = 'Page 12' 
            PRINT '('; heading$; ')' 
        30  END 
 
        RNH 
        (....................) 
        (             Page 12) 

8.4.1 LSET

FORMAT:


        LSET str_var = str_expr 

EXAMPLE:


        10  heading$ = REPEAT$('.', 20)          ! Twenty dots 
        20  PRINT '('; heading$; ')' 
        30  LSET heading$ = 'Page 12' 
            PRINT '('; heading$; ')' 
        40  END 
 
        RNH 
        (....................) 
        (Page 12             ) 

PURPOSE:

Use LSET to left-justify string data.

DESCRIPTION:

When INTOUCH executes an LSET statement, it evaluates the string expression on the right side of the equal sign. INTOUCH assigns the new value to the string variable and left-justifies this value within the length of the old value. If the new value has leading or trailing spaces, these spaces are carried over and the string is justified with those spaces. LSET can only be used with strings.

8.4.2 RSET

FORMAT:


        RSET str_var = str_expr 

EXAMPLE:


        10  heading$ = REPEAT$('.', 20)          ! Twenty dots 
        20  PRINT '('; heading$ ;')' 
        30  RSET heading$ = 'Page 12' 
            PRINT '(' ; heading$ ; ')' 
        40  END 
 
        RNH 
        (....................) 
        (             Page 12) 

PURPOSE:

Use RSET to right-justify string data.

DESCRIPTION:

When INTOUCH executes the RSET statement, it evaluates the string expression on the right side of the equal sign. INTOUCH assigns the new value to the string variable and right-justifies this value within the length of the old value. If the new value has leading or trailing spaces, these spaces are carried over and the string is justified with those spaces. RSET can only be used with strings.

8.4.3 CSET

FORMAT:


        CSET str_var = str_expr 

EXAMPLE:


        10  heading$ = REPEAT$('.', 20)          ! Twenty dots 
        20  PRINT '('; heading$; ')' 
        30  CSET heading$ = 'Page 12' 
            PRINT '('; heading$; ')' 
        40  END 
 
        RNH 
        (....................) 
        (       Page 12      ) 

PURPOSE:

Use CSET to center string data.

DESCRIPTION:

When INTOUCH executes the CSET statement, it evaluates the expression on the right side of the equal sign. Next, INTOUCH assigns the new value to the string variable and centers it within the length of the old value. If the string value has leading or trailing spaces, the spaces are carried over and the string is centered with those spaces. CSET can only be used with strings.


Previous Next Contents Index