FOR EACH struc_name
---
--- block of code
---
NEXT struc_name
10 OPEN STRUCTURE cl: NAME 'tti_run:client'
20 EXTRACT STRUCTURE cl
INCLUDE cl(state) = 'CA'
EXCLUDE cl(phone)[1:3] = '619'
SORT ASCENDING BY cl(last)
END EXTRACT
PRINT 'List of California Clients'
PRINT
30 FOR EACH cl
PRINT cl(first); ' '; cl(last), cl(phone)
NEXT cl
40 CLOSE STRUCTURE cl
50 END
RNH
List of California Clients
Dale Derringer (818) 223-9014
Earl Errant (408) 844-7676
You can use the FOR EACH statement to execute a block of code for each record in the extract list. This allows you to manipulate structure information in your programs.
The FOR EACH statement begins a loop that executes a block of code for each record in the extract list. struc_name is the structure name associated with the structure. NEXT struc_name marks the end of the loop.
You can use the [REPEAT], [ITERATE] and EXIT FOR statements in the FOR EACH loop.
EXTRACT STRUCTURE struc_name: KEY field = expr1 [TO expr2]
---
--- block of code
---
END EXTRACT
struc_name is the structure name associated with the structure. field is the name of the field that contains the key. expr is an expression that tells what key(s) to extract. INTOUCH evaluates the expression, checks the structure's index for records with matching keys, and extracts these records (if any records are found).
The KEY option includes records using the record's key. The key is a field which has an index for fast access. The key option can considerably speed up extractions.
The conditional expression must match the field's data type. For instance, if the field has a CHARACTER data type, the expression must be a string expression.
For example, we have a structure with the following client information and the ID field is a key field:
ID # LAST FIRST CITY STATE PHONE
+------+-----------+--------+--------------+--+----------+
|80543 |Cass |Cathy | San Diego |CA|6197438582|
|80542 |Brock |Bud | Duluth |MN|2185554322|
|80522 |Errant |Earl | Monterey |CA|4088447676|
|80561 |Derringer |Dale | Los Angeles |CA|8182239014|
|80531 |Abott |Al | New York |NY|2025669892|
|80573 |Farmer |Fred | Miami |FL|3055527872|
In the program below, the KEY option is used to extract the client with the ID number 80561.
10 OPEN STRUCTURE cl: NAME 'TTI_RUN:CLIENT'
20 EXTRACT STRUCTURE cl: KEY id = 80561
PRINT 'Client:',
PRINT cl(first); ' '; cl(last), cl(id)
END EXTRACT
CLOSE STRUCTURE cl
30 END
RNH
Client: Dale Derringer 80561
You can extract records with keys in a certain range with the TO option. expr1 is the lowest key to check. expr2 is the highest. INTOUCH extracts any records whose keys are within the range specified.
10 OPEN STRUCTURE cl: NAME 'TTI_RUN:CLIENT'
20 INPUT 'Enter the lowest ID to check': lowest
INPUT 'Enter the highest ID to check': highest
EXTRACT STRUCTURE cl: KEY id = lowest TO highest
PRINT cl(id); TAB(10); cl(last)
END EXTRACT
CLOSE STRUCTURE cl
30 END
RNH
Enter the lowest ID to check? 80540
Enter the highest ID to check? 80570
80542 Brock
80543 Cass
80561 Derringer
EXTRACT STRUCTURE struc_name, FIELD field_expr: PARTIAL KEY str_expr
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
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".
CANCEL EXTRACT
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
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.
EXIT EXTRACT
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
EXIT EXTRACT passes control to the corresponding END EXTRACT statement, performs final sorting (if any), and creates the extracted collection.
REEXTRACT STRUCTURE struc_name
---
[INCLUDE | EXCLUDE] cond_expr...
[SORT [ASCENDING | DESCENDING] BY expression...
---
END EXTRACT
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
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
EXTRACT STRUCTURE struc_name: APPEND
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
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
EXTRACT STRUCTURE struc_name1, SET 'set_name', USING struc_name2
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
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
EXTRACT STRUCTURE struc_name1, SET 'set_name', FIELD field_expr: KEY str_expr
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
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.
The ASK STRUCTURE statement is used to ask about various device and structure characteristics from within your programs.
ASK STRUCTURE struc_name: struc_option [num_var | str_var]
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
ASK STRUCTURE struc_name, FIELD field_expr: item var
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
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.
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
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
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
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
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.
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
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
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.
ASK STRUCTURE struc_name, FIELD field_expr: DESCRIPTION str_var
DESCRIPTION returns the description for the specified field in a string variable.
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.
ASK STRUCTURE struc_name, FIELD field_expr: HELP str_var
HELP returns the help text for the specified field in a string variable.
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.