Selects

A select definition enables the user interface to display the valid values for a form field and lets you select a value from that list. The user interface performs the select definition when you press Select (F4) or choose Select button for a form field. When you perform a select from a form field, a DEFINE SELECT entry in the form rules file determines the format of the Select window and which fields appear in that window.

When you select a value from the Select window, the user interface performs any DEFINE RULE statements associated with that field (that is, selecting a value performs an implicit Tab from the field).

You can define more than one select definition for a form field. When you press Select (F4), a pop-up menu of the select definitions displays, and you can choose the desired select.

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

Use To
DEFINE SELECT

Begin each select definition.

Optional. To the right of DEFINE SELECT, put the title for the Select window. The title must be inside double quotes. If you do not enter a title, it defaults to SCRFLD, where SCRFLD is replaced by the first name next to SCRFLD and is formatted (that is, converted from uppercase to initial caps, hyphens removed—"OUTPUT-ACCOUNT" converted to "Output Account").

The standard for a Select window title is the plural of the object name. For example, if the Select window displays employees, the title would be Employees.

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.

FILENAME Name the file that this rule accesses records in.
INDEX Name the index used to access the records.
KEYRNG

Name the key fields or values used to access records for the Select window. Separate entries with a comma. The number of entries next to KEYRNG must be less than the number of key fields in the index (INDEX). The order of the entries next to KEYRNG must follow the order of the index fields.

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.

NXTKEYS

Name the fields or values for the index fields that you did not enter a field or value next to KEYRNG for. The user interface uses these fields for the Next and Previous actions.

If you do not enter fields or values for all remaining index fields, the Next logic skips records until the last key field listed changes. For example, an index has the following key fields and records.

The form displays the first record in the index. KEYRNG is Company and Account Unit. If NXTKEYS is Account, the Next action displays the fourth record in the index because it is the next account number. If NXTKEYS is Account and Sub Account, the Next action displays the second record in the index because it is the next subaccount.

NXTKEYS can take the same kind of entries as KEYRNG. It can also take the entry @CURSCRFLD. This entry is used to support a select that has more than one SCRFLD entry.

In the following example, NXTKEYS is the field that you put the cursor on, either COMPANY-01, TO-COMPANY-30, NEW-COMPANY-G2, POST-TO-COMPANY-01P, or COMPANY-NO-HIERARCHY-01N.

DEFINE SELECT   "Companies"
    ID           GL-GLS-S-0001
    SCRFLD       COMPANY-01,
                 TO-COMPANY-30,
                 NEW-COMPANY-G2,
                 POST-TO-COMPANY-01P,
                 COMPANY-NO-HIERARCHY-01N
    FILENAME     GLSYSTEM
    INDEX        GLSSET1
    NXTKEY       @CURSCRFLD
    DSPFLDS      COMPANY:"Co",NAME,\
      CURRENCY-CODE:"Base",CHART-NAME:"Chart"
    RETURNS      COMPANY
CONDITION Name up to three conditions, separated by commas. They must be valid conditions, defined in the database definition, for the FILENAME. Records that do not meet the conditions do not appear in the Select window or when you scroll through the field values with the Next or Previous actions.
DSPFLDS

Name 4GL fields, from the primary file or a related file, that you want to display in the Select window. The standard is to display the form field and its description.

The size of the displayed field defaults to the defined field size. To override the default size, use the following syntax.

DSPFLDS FieldName=size
The label for a field in a Select window defaults to the defined field name (for example, the label for the field Acct-Unit is Acct Unit). Override the default field label, use the following syntax.
DSPFLDS FieldName[=size]:"Label"

The colon (:) is the override operator. Put the field label inside double quotes.

To display no field label, use the following syntax.

DSPFLDS FieldName[=size]:"
FNDFLDS Name other fields not listed as DSPFLDS that you want to use to find a record in the Select window. These fields must be from the primary file or a related file. When you press Find (F2), you can find a record through the fields in DSPFLDS and FNDFLDS. This entry is optional.
RETURNS

Name the field from the primary file (FILENAME) whose value you want to move from the select window to the form field (SCRFLD).

You can enter up to 15 RETURNS statements, each on its own line. Do not separate RETURNS statements with commas.

If SCRFLD has more than one field, or if you want to return the value of a database field to a field that is not listed next to SCRFLD, use the syntax for a targeted RETURN:

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.

Usually RETURNS has one entry. In most cases you do not need to list targeted RETURNS because the DEFINE RULE statement, invoked when you press Tab or Enter to exit a form field, performs the targeted RETURNS for the form field.

Example for Select Definition

When you press Select (F4) from any of the listed SCRFLD fields (Through Company, To Company, New Company, Post To Company, or Company No Hierarchy), the Company, Company Name, Currency Code, and Chart Name values from the GLSYSTEM file, using the index GLSSET1, display. The Company number is returned to the form field where the select initiated.

DEFINE SELECT       "Companies"
    ID              IF-GLS-S-0001
    SCRFLD          COMPANY-01,
                    TO-COMPANY-30,
                    NEW-COMPANY-G2,
                    POST-TO-COMPANY-01P,
                    COMPANY-NO-HIERARCHY-01N
    FILENAME        GLSYSTEM
    INDEX           GLSSET1
    NXTKEY          @CURSCRFLD
    DSPFLDS         COMPANY:"Co",NAME,CURRENCY-CODE:"Base",
                    CHART-NAME:"Chart"
    RETURNS         COMPANY

When you press Find (F2) from the Select window, you have the choice of finding a company by the Company Number, Company Name, Base Currency, or Chart Name.

When you select a company record from the Select window, that company moves to the form field where the select initiated.

Example for Conditional Select Definition

When you press Select (F4) from the Accounting Unit field, the Company, Accounting Unit, Description, and Status fields from the GLNAMES file, using the index GLNSET1, display.

DEFINE SELECT       "Posting Accounting Units"
    ID              IF-GLN-S-0001
    SCRFLD          ACCOUNT-UNIT-02
    FILENAME        GLNAMES
    INDEX           GLNSET1
    KEYRNG          COMPANY-01
    NXTKEY          @CURSCRFLD
    CONDITION       POSTABLE
    DSPFLDS         COMPANY:"Co",ACCT-UNIT:"Accounting Unit", 
                    DESCRIPTION,ACTIVE-STATUS:"Status"
    FNDFLDS         PERSON-RESP, VAR-LEVEL-DISP
    RETURNS         ACCT-UNIT

Only records that meet the Postable condition appear.

Condition Definition
===================================================================
When                  Posting Flag = "P"                    
And                  Active Status = "A" 

For instructions on defining conditions, see Conditional Rules.

When you select an accounting unit record, the accounting unit moves to the Accounting Unit form field, as named in the RETURNS statement.