INTOUCH® 4GL
A Guide to the INTOUCH Language


Previous Contents Index

14.7.6 EXTRACT STRUCTURE, FIELD: PARTIAL KEY

FORMAT:


        EXTRACT STRUCTURE struc_name, FIELD field_expr: PARTIAL KEY str_expr 

EXAMPLE:


        10  OPEN STRUCTURE cl: NAME 'TTI_RUN:CLIENT' 
            EXTRACT STRUCTURE cl, FIELD last: PARTIAL KEY 'Ros' 
            END EXTRACT 
            PRINT 'List of clients with last name starting with Ros' 
            PRINT 
            FOR EACH cl 
              PRINT cl(first); ' '; cl(last) 
            NEXT cl 
        20  CLOSE STRUCTURE cl 
        30  END 
 
        RNH 
        Bud Roske 
        Earl Rost 
        Dale Rosty 

DESCRIPTION:

The PARTIAL KEY option will search in the EXTRACT STRUCTURE for part of a key value.

Here is a structure with the following client information and the ID is a key field:


         ID #      LAST      FIRST      CITY      STATE  PHONE 
      +------+-----------+--------+--------------+--+----------+ 
      |80543 |Roberts    |Cathy   | San Diego    |CA|6197438582| 
      |80542 |Roske      |Bud     | Duluth       |MN|2185554322| 
      |80522 |Rost       |Earl    | Monterey     |CA|4088447676| 
      |80561 |Rosty      |Dale    | Los Angeles  |CA|8182239014| 
      |80531 |Abott      |Al      | New York     |NY|2025669892| 
      |80573 |Farmer     |Fred    | Miami        |FL|3055527872| 

The above example program creates an extract list containing only those clients with a last name starting with "ROS".

14.7.7 CANCEL EXTRACT

FORMAT:


        CANCEL EXTRACT 

EXAMPLE:


        10  OPEN STRUCTURE cl: NAME 'TTI_RUN:CLIENT' 
            EXTRACT STRUCTURE cl 
              PRINT 'Client: '; cl(last) 
              LINE INPUT 'Press return to continue': z$ 
              IF  _EXIT  THEN  CANCEL EXTRACT 
            END EXTRACT 
            PRINT 'Records extracted:'; _EXTRACTED 
        20  CLOSE STRUCTURE cl 
        30  END 
 
        RNH 
        Client: Smith 
        Press return to continue? EXIT 
        Records extracted: 0 

DESCRIPTION:

CANCEL EXTRACT cancels the current extract of a record and transfers control to the next statement after the END EXTRACT statement.

This statement can only be used within an EXTRACT block---that is, between an EXTRACT STRUCTURE and an END EXTRACT pair of statements.

14.7.8 EXIT EXTRACT

FORMAT:


        EXIT EXTRACT 

EXAMPLE:


        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
            EXTRACT STRUCTURE cl 
              PRINT 'Client: '; cl(last) 
              LINE INPUT 'Press return to continue': z$ 
              IF  _EXIT  THEN  EXIT EXTRACT 
            END EXTRACT 
            PRINT 'Records extracted:'; _EXTRACTED 
        20  END 
 
        RNH 
        Client: Smith 
        Press return to continue? <RETURN> 
        Client: Kent 
        Press return to continue? EXIT 
        Records extracted: 1 

DESCRIPTION:

EXIT EXTRACT passes control to the corresponding END EXTRACT statement, performs final sorting (if any), and creates the extracted collection.

14.7.9 REEXTRACT STRUCTURE

FORMAT:


        REEXTRACT STRUCTURE struc_name 
                  --- 
           [INCLUDE | EXCLUDE] cond_expr... 
           [SORT [ASCENDING | DESCENDING] BY expression... 
                  --- 
        END EXTRACT 

EXAMPLE:


        10  OPEN STRUCTURE cl: NAME 'tti_run:client', ACCESS INPUT 
        20  EXTRACT STRUCTURE cl 
              INCLUDE cl(state) = 'CA' 
            END EXTRACT 
            REEXTRACT STRUCTURE cl 
              EXCLUDE cl(phone)[1:3] <> '619' 
              SORT ASCENDING BY cl(last) 
            END EXTRACT 
        30  PRINT 'List of California Clients in Area Code 619' 
            FOR EACH cl 
              PRINT cl(first); ' '; cl(last), cl(phone) 
            NEXT cl 
        40  CLOSE STRUCTURE cl 
        50  END 
 
        RNH 
        List of California Clients in Area Code 619 
        Cathy Cass          (619) 743-8582 
        Paul Johnson        (619) 489-5551 
        Keith Kent          (619) 967-5021 
        Pete Porter         (619) 778-6709 
        Wayne Waters        (619) 564-1231 

DESCRIPTION:

You can use REEXTRACT STRUCTURE to do a second extract on a list of structure records you previously extracted. This lets you choose more and more specific records through a series of REEXTRACTs.

REEXTRACT does an extract on the list of records previously extracted. struc_name is the structure name associated with an open structure.

END EXTRACT marks the end of the REEXTRACT construct. REEXTRACT operates the same as EXTRACT. However, REEXTRACT operates on a previously extracted list.

Note

Extract operations by key cannot be performed with REEXTRACT.

14.7.10 EXTRACT STRUCTURE: APPEND

FORMAT:


        EXTRACT STRUCTURE struc_name: APPEND 

EXAMPLE:


        10  OPEN STRUCTURE detail: name 'tti_run:detail' 
            SET STRUCTURE detail: EXTRACTED 0 
        20  EXTRACT STRUCTURE detail, FIELD lineid : & 
                KEY '10301001' TO '10301999', APPEND 
              SORT BY detail(prodnbr) 
              SORT BY detail(invnbr) 
            END EXTRACT 
        30  EXTRACT STRUCTURE detail, field lineid : & 
                KEY '10311001' to '10311999', APPEND 
              SORT BY detail(prodnbr) 
              SORT BY detail(invnbr) 
            END EXTRACT 
            PRINT 'Prod'; TAB(7); 'Line ID'; TAB(17); 'Qty' 
        40  FOR EACH detail 
              PRINT detail(prodnbr); TAB(7); detail(lineid); & 
                    TAB(17); detail(qty) 
            NEXT detail 
        50  END 
 
        RNH 
        Prod  Line ID   Qty 
        22800 10301-002      2 
        22800 10301-004      1 
        22800 10301-006      2 
        24100 10311-003      1 
        24200 10301-003      1 
        24200 10311-009      1 
        28400 10311-001      2 
        28800 10301-009      2 
        28800 10311-002      9 
        28800 10311-005      1 
        28800 10311-006      1 
        31020 10301-005      1 
        31040 10311-010      2 
        31150 10301-001      1 
        31150 10301-008      8 
        31150 10311-004      1 
        31150 10311-008      1 
        33090 10301-007      2 
        33090 10311-007      1 

DESCRIPTION:

The EXTRACT STRUCTURE: APPEND statement adds records to the last collection of extracted records rather than creating a new collection.

14.7.11 EXTRACT STRUCTURE, SET, USING

FORMAT:


        EXTRACT STRUCTURE struc_name1, SET 'set_name', USING struc_name2 

EXAMPLE:


        10  OPEN STRUCTURE class: name 'devint:intest_dbms' 
        20  OPEN STRUCTURE part : name 'devint:intest_dbms' 
            EXTRACT STRUCTURE class, SET 'class_part', USING part 
            END EXTRACT 
        30  END 

DESCRIPTION:

Used for DBMS handling, this statement fetches all structures, (struc_name1) owned by another structure (struct_name2) within a given set.

14.7.12 EXTRACT STRUCTURE, SET, FIELD: KEY

FORMAT:


        EXTRACT STRUCTURE struc_name1, SET 'set_name', FIELD field_expr: KEY str_expr 

EXAMPLE:


        10  OPEN STRUCTURE class:  name 'devint:intest_dbms' 
        20  OPEN STRUCTURE part :  name 'devint:intest_dbms' 
            EXTRACT STRUCTURE class, SET 'class_part', FIELD class_code: KEY cl_code$ 
            END EXTRACT 
        30  END 

DESCRIPTION:

Used in DBMS handling, this statement allows you to extract all structures specified by struc_name1 owned by the current record within the given set (set_name) with field field_expr equal to the given key.

14.8 ASK STRUCTURE

The ASK STRUCTURE statement is used to ask about various device and structure characteristics from within your programs.

FORMAT:


        ASK STRUCTURE struc_name: struc_option [num_var | str_var] 

DESCRIPTION:

struc_name is the name of a structure whose characteristics are being asked about. struc_option can be any of the structure options available. The options are explained in the following sections.

14.8.1 ASK STRUCTURE FIELD: item

FORMAT:


        ASK STRUCTURE struc_name, FIELD field_expr: item var 

EXAMPLE:


        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
        20  ASK STRUCTURE cl: FIELDS num_fields 
            FOR i = 1 TO num_fields 
              CLEAR 
              ASK STRUCTURE cl, FIELD #i: DESCRIPTION b$ 
              ASK STRUCTURE cl, FIELD #i: PROMPT a$ 
              ASK STRUCTURE cl, FIELD #i: POSITION a% 
              ASK STRUCTURE cl, FIELD #i: LENGTH b% 
              ASK STRUCTURE cl, FIELD #i: HEADING f$ 
              ASK STRUCTURE cl, FIELD #i: PRINTMASK c$, & 
                                          SCREENMASK d$, & 
                                          HELP e$ 
              PRINT AT 5,5: '' 
              PRINT 'Description   : '; b$ 
              PRINT 'Prompt        : '; a$ 
              PRINT 'Position      : '; a% 
              PRINT 'Field length  :' ; b% 
              PRINT 'Rpt. heading  : '; f$ 
              PRINT 'Print mask    : '; c$ 
              PRINT 'Screen mask   : '; d$ 
              PRINT 'Help          : '; e$ 
              DELAY 5 
            NEXT i 
            CLOSE STRUCTURE cl 
        30  END 
 
        RNH 
        Description   : Client ID number 
        Prompt        : Client ID number 
        Position      :  1 
        Field length  : 5 
        Rpt. heading  : CLNT,ID 
        Print mask    : >#### 
        Screen mask   : digits:##### 
        Help          : Client ID number 

DESCRIPTION:

The FIELD option allows you to get information about a specific field in a structure. struc_name is the name of the structure. field_expr is the field you are inquiring about. item specifies what type of information you are asking. The information is stored in the variable specified.

The following sections provide more information on what you can use for field_expr and on the various field items.

Note

The ITEM information is created when the the SETUP routine is used to define the field. You can refer to Chapter 16, Creating Structures, Field Definitions with SETUP for information on defining fields.

14.8.1.1 FIELD Expressions

The field_expr used in the ASK STRUCTURE FIELD: item statement can be either a constant or a string or numeric expression.

You can use a string constant to specify the field name. To use a string constant, just enter the field name, without quotes. INTOUCH will then use the string constant as the field name:


        ASK STRUCTURE TTI_RUN:CLIENT, FIELD LAST: DESCRIPTION A$ 
                                        / 
                  the field is specified by its field name 

You can also specify a field name with an expression. To use an expression, precede the expression with a pound sign (#). The pound sign tells INTOUCH that the following characters are an expression, not the field name. If you do not include a pound sign, INTOUCH will interpret the characters as a field name.


        ASK STRUCTURE CL, FIELD #FIELDNAME$: DESCRIPTION A$ 
                                    / 
          the field is specified by the value of the variable FIELDNAME$ 
 
 
        ASK STRUCTURE CL, FIELD #FIELDNUM: DESCRIPTION A$ 
                                    / 
          the field is specified by the value of the variable FIELDNUM 

EXAMPLE:

This example shows how you can access the actual field data using field expressions.


        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
        20  DO 
            CLEAR 
            PRINT AT 1, 1:; 
              ask_fields 
              IF  _BACK  OR  _EXIT  THEN  EXIT DO 
              show_data 
            LOOP 
            CLOSE STRUCTURE cl 
            STOP 
 
        30  ask_fields: 
            DO 
              IF  _ERROR  THEN  SET ERROR OFF 
              PRINT 'Field List:  '; & 
                      'ID, LAST, FIRST, MIDDLE, STREET, CITY, STATE, ZIP, PHONE' 
              PRINT 
              LINE INPUT 'Select fields to display': field_list$ 
              IF  _BACK  OR  _EXIT  THEN  EXIT DO 
              FOR f = 1 TO ELEMENTS(field_list$) 
                field$ = ELEMENT$(field_list$, f) 
                ASK STRUCTURE cl, FIELD #field$: NUMBER z 
                IF  z = 0  THEN 
                  MESSAGE ERROR: 'Illegal field: '; field$ 
                END IF 
              NEXT f 
        40  LOOP WHILE _ERROR 
            RETURN 
 
        50  show_data: 
            PRINT 
            EXTRACT STRUCTURE cl 
              FOR f = 1 TO ELEMENTS(field_list$) 
                field$ = ELEMENT$(field_list$, f) 
                PRINT cl(#field$), 
              NEXT f 
              PRINT 
        60  END EXTRACT 
            DELAY 
            RETURN 
        70  END 
 
        RNH 
        Field List:  ID, LAST, FIRST, MIDDLE, STREET, CITY, STATE, ZIP, PHONE 
 
        Select fields to display? last,first,phone 
 
        Smith               Sam                 (809) 555-8789 
        Kent                Keith               (619) 967-5021 
        Johnson             Paul                (619) 489-5551 
        Waters              Wayne               (619) 564-1231 
        Rodrigues           Homero              (   )    -   0 
        Donaldson           George              (   )    -   0 
        Errant              Earl                (408) 844-7676 
        Abott               Al                  (202) 566-9892 
        Brock               Bud                 (218) 555-4322 
        Cass                Cathy               (619) 743-8582 
        Porter              Pete                (619) 778-6709 
        Derringer           Dale                (818) 223-9014 
        Farmer              Fred                (305) 552-7872 

14.8.1.2 Item: ACCESS


        ASK STRUCTURE struc_name, FIELD field_name: ACCESS str_var 

ACCESS retrieves the access (read and write) rules for the specified field. This information tells you if the field can be read and written to. N is normal--meaning the field can be read and written to if the structure is also "N"ormal. Depending on whether security levels have been set on the structure and/or field, the letter can be in the range of A thru Z. INTOUCH defaults to N when the structure is created and fields are defined.


        10  OPEN STRUCTURE inv: NAME 'tti_run:invoice', ACCESS INPUT 
        20  ASK STRUCTURE inv, FIELD custnbr: ACCESS x$ 
        30  PRINT x$ 
        40  CLOSE STRUCTURE inv 
        50  END 
 
        RNH 
        READ:N, WRITE:N 

14.8.1.3 Item: APPLICATION


        ASK STRUCTURE struc_name, FIELD field_expr: APPLICATION str_var 

APPLICATION returns a name of an application for the specified field in a string variable. This is optional information the user provides when the field is defined.


        10  OPEN STRUCTURE cl : NAME 'tti_run:client' 
            ASK STRUCTURE cl, FIELD id: APPLICATION str$ 
            PRINT str$ 
        20  END 
 
        RNH 
        REPORTING_ID 

14.8.1.4 Item: ATTRIBUTES


        ASK STRUCTURE struc_name, FIELD field_expr: ATTRIBUTES str_var 

ATTRIBUTES returns the INTOUCH field semantics (NUM - number, UC - upper-case, etc.) for the specified field in a string variable.

You can refer to Section 16.4.8, Semantics for detailed information on field attributes.

14.8.1.5 Item: CHANGEABLE


        ASK STRUCTURE struc_name, FIELD field_expr: CHANGEABLE num_var 

CHANGEABLE returns a value of TRUE or FALSE. If the field specified by field_expr can be changed, the value is TRUE. If the field cannot be changed, the value is FALSE.


        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
            ASK STRUCTURE cl, FIELD id: CHANGEABLE z 
            ASK STRUCTURE cl, FIELD city: CHANGEABLE z1 
            PRINT z 
            PRINT z1 
            CLOSE STRUCTURE CL 
        20  END 
 
        RNH 
         0 
         1 

14.8.1.6 Item: CLASSIFICATION


        ASK STRUCTURE struc_name, FIELD field_expr: CLASSIFICATION str_var 

CLASSIFICATION returns the classification (if there is one) for the specified field in a string variable. This is optional information.


        10  OPEN STRUCTURE cl : NAME 'tti_run:client' 
            ASK STRUCTURE cl, FIELD last: CLASSIFICATION str$ 
            PRINT str$ 
        20  END 
 
        RNH 
        NAME 

14.8.1.7 Item: DATATYPE


        ASK STRUCTURE struc_name, FIELD field_expr: DATATYPE str_var 

DATATYPE returns the field data type, such as CH (character), IN (integer), etc., in a string variable.

You can refer to Section 16.4.4, Data type for detailed information on field data types.

14.8.1.8 Item: DESCRIPTION


        ASK STRUCTURE struc_name, FIELD field_expr: DESCRIPTION str_var 

DESCRIPTION returns the description for the specified field in a string variable.

14.8.1.9 Item: HEADING


        ASK STRUCTURE struc_name, FIELD field_expr: HEADING str_var 

HEADING returns the report column heading for the specified field in a string variable. This is the heading that would appear in a Guided Query Language (GQS) report column.

14.8.1.10 Item: HELP


        ASK STRUCTURE struc_name, FIELD field_expr: HELP str_var 

HELP returns the help text for the specified field in a string variable.

14.8.1.11 Item: KEYED


        ASK STRUCTURE struc_name, FIELD field_expr: KEYED num_var 

KEYED returns a value of TRUE or FALSE in a numeric variable. If the specified field is a key field, the value is TRUE. Otherwise, the value is FALSE.

14.8.1.12 Item: LENGTH


        ASK STRUCTURE struc_name, FIELD field_expr: LENGTH num_var 

LENGTH returns the length of the specified field in a numeric variable.


Previous Next Contents Index