Rule Definition

A rule definition takes the value of a form field(s), accesses the database record for the value(s) of that field(s), and moves data from the database record to other fields in the form. A rule is applied to a form field when you press the Tab or Enter key to move the cursor from the field.

The following entries make up a rule definition. The number of DEFINE RULE statements in a form rules file is not limited.


Use	To
DEFINE RULE	Begin each rule definition. This rule applies only when the key number for the field name(s) listed here matches the key number for the form field in the form definition file. For more information, see Key Number.
ID	Specify a unique identifier for this form rules object. For more information on IDs, see Form Rules Guidelines.
SCRFLD	Name the form fields that invoke this rule. You can list up to five form field names, separated by commas. Only field names defined in System Key Number Definition are valid. For more information, see "Defining Key Numbers" in Doc for Developers: Application Development Workbench.
FILENAME	Name the file that this rule accesses a record in.
INDEX	Name the index used to access this record.
KEYRNG	Name the key fields or values used to access this record. Separate entries with a comma. The number and order of the fields and values listed here must be the same as the number and order of fields in the index (INDEX). The following are valid entries for KEYRNG: A form field name. A function name. A constant value, in double quotes. Include any leading or trailing spaces or zeroes in the double quotes. For example, to search for the constant value 4 in a numeric field of length 3, type "004" next to KEYRNG. ~SPACES for spaces. ~ZEROES for zeroes. @CURSCRFLD can be used. This entry is used to support a rule that has more than one SCRFLD entry. In the following example, the value for the key would be taken from Company-01 or Company-01A, depending on where the cursor was.
	`DEFINE RULE ID GL-GLS-R-0001 SCRFLD COMPANY-01,COMPANY-01A FILENAME GLSYSTEM INDEX GLSSET1 KEYRNG @CURSCRFLD RETURNS NAME INTO COMPANY-NAME-01D`
RETURNS	Name the field from the primary file (FILENAME) and the form field that you want to move the primary file field to. Use the syntax: PrimaryField INTO FormField PrimaryField is the name of a field in the primary file. FormField is the name of the form field that you want to move the value of PrimaryField to. You can enter up to 15 RETURNS statements, each on its own line. Do not separate RETURNS statements with a comma.
REQUIRED	Display an error if the rule does not find a record in the database for the key fields listed next to KEYRNG. If the record for a form field does not exist, the error message "Value Does Not Exist" appears, and you cannot move the cursor out of the form field. If the rule definition has more than one SCRFLD, the required rule is checked after the user exits the last SCRFLD. There might be instances where you want to require a rule except on the form that adds the record for the file (FILENAME) which the rule is defined for. When you do not want a required rule to apply on a particular form, do not assign a key number (KN) in the form definition file for that form to at least one of the form field listed next to RETURNS. For information on key numbers, see Key Number. For example, in Authority Codes (AP05.6), when you press Tab or Enter to move the cursor from the Company field, the following rule applies. This rule finds the record in the APCOMPANY file for the value in the Company field and displays the company name on the form. You cannot tab past the Company field without entering a value. If you enter a value but a database record does not exist for that value, the error message "Value Does Not Exist" displays.
	`DEFINE RULE ID AP-CPY-R-0001 SCRFLD COMPANY-01 FILENAME APCOMPANY INDEX CPYSET1 KEYRNG COMPANY-01 RETURNS NAME INTO COMPANY-NAME-01D REQUIRED`
	However, GL10 is the form that you add a new company on, so you do not want a DEFINE RULE in the GL.SR that requires that the company exists in the database. If you do, you would get an error message every time you tried to add a new company.

Example for Rule Definition

When you move the cursor from the Company field in a form (key number 01 or 01A, as indicated by the SCRFLD entry), this rule locates a record in the GLSYSTEM file using the index GLSSET1. The record is chosen based on the current form values of the key fields in GLSSET1.

DEFINE RULE                                                    
     ID              GL-GLS-R-0001                              
     SCRFLD          COMPANY-01,COMPANY-01A                     
     FILENAME        GLSYSTEM                                   
     INDEX           GLSSET1                                    
     KEYRNG          @CURSCRFLD                                 
     RETURNS         NAME           INTO COMPANY-NAME-01D       
     RETURNS         CURRENCY-CODE  INTO GLS-CURRENCY-CODE-GC   
     RETURNS         CURR-NAME-1    INTO CURR-NAME-1-98M        
     RETURNS         CURR-CODE-1    INTO CURR-CODE-1-98G        
     RETURNS         CURR-NAME-2    INTO CURR-NAME-2-98N        
     RETURNS         CURR-CODE-2    INTO CURR-CODE-2-98H        
     RETURNS         CHART-NAME     INTO CHART-NAME-GH1         
     RETURNS         LEVEL-DESC     INTO LEVEL-DESCRIPTION-L4   
     RETURNS         NBR-DIGITS     INTO GLS-NBR-DIGITS-JQ      
     RETURNS         FISCAL-YEAR    INTO FISCAL-YEAR-06 
     RETURNS         ACCT-PERIOD    INTO ACCT-PERIOD-GP

For any fields named in the RETURNS statements that are present on the form and are defined with the same system key numbers as the return fields, the values of the file fields are moved to the form fields.

For example, after you select a company in GL40 (Journal Entry), values are placed in the company name, base currency, report currency 1, report currency 2, fiscal year, and accounting period fields.

Example for Required Rule Definition

When you move the cursor from the To Company field in a form, the rule defined in the following example locates the record in the GLSYSTEM file using the index GLSSET1. The record is chosen based on the current form values of the key fields in GLSSET1.

DEFINE RULE
    ID              IF-GLS-R-0002
    SCRFLD          TO-COMPANY-30
    FILENAME        GLSYSTEM
    INDEX           GLSSET1
    KEYRNG          @CURSCRFLD
    RETURNS         NAME          INTO TO-COMPANY-NAME-30D
    RETURNS         CURRENCY-CODE INTO TO-CURR-CODE-IE 
    RETURNS         LEVEL-DESC    INTO LEVEL-DESCRIPTION-L4
    RETURNS         NBR-DIGITS    INTO GLS-NBR-DIGITS-JQ
    REQUIRED

Because this rule is required, the following file field values must be moved to the form fields, when the system key number is defined as shown in this rule.


GLSYSTEM file field	Form field	System key number
Name	To Company Name	30D
Currency Code	To Company Currency Code	IE
Level Description	Level Description	L4
Number of Digits	Number of Digits (GL System)	JQ

If the database record does not exist, the error message "Value Does Not Exist" displays, and you cannot move the cursor out of the field until you enter a valid To Company.