INTOUCH® 4GL
A Guide to the INTOUCH Language


Previous page... Table of Contents

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.

14.8.1.13 Item: NAME

        ASK STRUCTURE struc_name, FIELD field_expr: NAME str_var 

NAME returns the name of the specified field in a string variable.

14.8.1.14 Item: NULL

        ASK STRUCTURE struc_name, FIELD field_name: NULL int_var 

If the specified field is NULL (i.e. contains no data), this statement returns TRUE. If the field is not NULL, the statement returns FALSE.

14.8.1.15 Item: NUMBER

        ASK STRUCTURE struc_name, FIELD field_expr: NUMBER num_var 

NUMBER returns the field number of the specified field in a numeric variable. Fields are numbered sequentially. If the field does not exist, INTOUCH returns a value of 0.

14.8.1.16 Item: OPTIMIZED

        ASK STRUCTURE struc_name, FIELD field_expr: OPTIMIZED num_var 

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

        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
            ASK STRUCTURE cl, FIELD id: OPTIMIZED z 
            PRINT z 
            CLOSE STRUCTURE cl 
        20  END 
 
        RNH 
         1 

14.8.1.17 Item: POSITION

        ASK STRUCTURE struc_name, FIELD field_expr: POSITION num_var 

POSITION returns the starting position for the specified field in a numeric variable.

14.8.1.18 Item: PRINTMASK

        ASK STRUCTURE struc_name, FIELD field_expr: PRINTMASK str_var 

PRINTMASK returns the print mask for the specified field in a string variable.

14.8.1.19 Item: PROMPT

        ASK STRUCTURE struc_name, FIELD field_expr: PROMPT str_var 

PROMPT returns the prompt for the specified field in a string variable.

14.8.1.20 Item: SCREENMASK

        ASK STRUCTURE struc_name, FIELD field_expr: SCREENMASK str_var 

SCREENMASK returns the screen mask for the specified field in a string variable. This option is not currently used.

14.8.1.21 Item: VRULES

        ASK STRUCTURE struc_name, FIELD field_expr: VRULES str_var 

VRULES returns the validation rules for the specified field in a string variable.

You can refer to the "VALID" function item in Section A.2, Other Functions for information on validation rules.

        10  OPEN STRUCTURE cl : NAME 'tti_run:client' 
            ASK STRUCTURE cl, FIELD bday: VRULES str$ 
            PRINT str$ 
        20  END 
 
        RNH 
        date ymd; minlength 8 

14.8.2 ASK STRUCTURE: CURRENT

FORMAT:

        ASK STRUCTURE struc_name: CURRENT str_var 

EXAMPLE:

        10  DIM a$(100) 
            LET i = 0 
        20  OPEN STRUCTURE cl: NAME 'tti_run:client' 
        30  EXTRACT STRUCTURE cl 
            END EXTRACT 
        40  FOR EACH cl 
              PRINT cl(last); ', '; cl(first) 
              INPUT 'Would you like to see this record (Y/N)': yn$ 
              IF  yn$ = 'Y'  THEN    
                LET i = i + 1 
                ASK STRUCTURE cl: CURRENT a$(i) 
              END IF 
            NEXT cl 
        50  PRINT 
            FOR j = 1 TO i 
              SET STRUCTURE cl: CURRENT a$(j) 
              PRINT cl(last); ','; cl(first), cl(state), cl(phone) 
            NEXT j 
        60  END 
 
        RNH 
        Errant, Earl      Would you like to see this record (Y/N)? Y 
        Abott, Al         Would you like to see this record (Y/N)? Y 
        Brock, Bud        Would you like to see this record (Y/N)? N 
        Cass, Cathy       Would you like to see this record (Y/N)? N 
        Derringer, Dale   Would you like to see this record (Y/N)? Y 
        Farmer, Fred      Would you like to see this record (Y/N)? Y 
        Errant, Earl       CA       (408) 844-7676 
        Abott, Al          NY       (202) 566-9892 
        Derringer, Dale    CA       (818) 223-9014 
        Farmer, Fred       FL       (305) 552-7872 

DESCRIPTION:

ASK STRUCTURE: CURRENT assigns the current record value to the str_var. Once the current record has been assigned with ASK STRUCTURE: CURRENT, you can use the SET STRUCTURE: CURRENT statement to get this record.

INTOUCH returns a zero length string if there is no CURRENT record.

14.8.3 ASK STRUCTURE: FIELDS

FORMAT:

        ASK STRUCTURE struc_name: FIELDS num_var 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client', ACCESS INPUT 
            ASK STRUCTURE cl: FIELDS z 
            PRINT z 
        20  END 
 
        RNH 
         18 

DESCRIPTION:

You can find out the number of fields in a structure with the ASK STRUCTURE: FIELDS statement. The number is assigned to the numeric variable num_var.

14.8.4 ASK STRUCTURE: KEYS

FORMAT:

        ASK STRUCTURE struc_name: KEYS num_var 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client', ACCESS INPUT 
            ASK STRUCTURE cl: KEYS z 
            PRINT z 
        20  END 
 
        RNH 
         2 

DESCRIPTION:

The ASK STRUCTURE: KEYS statement returns the number of keys that are accessible by INTOUCH. It returns the value of 0 if no keys are available.

14.8.5 ASK STRUCTURE: CAPABILITY

FORMAT:

        ASK STRUCTURE struc_name: CAPABILITY str_var 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client', ACCESS INPUT 
            ASK STRUCTURE cl: CAPABILITY z$ 
            PRINT z$ 
        20  END 
 
        RNH 
        INDEXED,INPUT 

DESCRIPTION:

Given a structure expression, ASK STRUCTURE: CAPABILITY sets str_expr to a comma delimited string containing one or more of the following: INDEXED, RELATIVE, INPUT, OUTPUT

Table 14-1 Structure Types
Structure Type Description
RELATIVE You can access a structure, using a relative record number, with statements such as ASK/SET STRUCTURE...RECORD.
INDEXED The structure is indexed; you can access it by key with statements such as SET STRUCTURE...KEY.
INPUT You can read from the structure.
OUTPUT You can write to the structure.
null string The structure is not currently open.

14.8.6 ASK STRUCTURE: EXTRACTED

FORMAT:

        ASK STRUCTURE struc_name: EXTRACTED num_var 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
            EXTRACT STRUCTURE cl 
            END EXTRACT 
            ASK STRUCTURE cl: EXTRACTED z 
            PRINT 'Records found: '; z 
        20  END 
 
        RNH 
        Records found:  13 

DESCRIPTION:

ASK STRUCTURE: EXTRACTED asks the operating system for the last extracted count for the structure specified.

14.8.7 ASK STRUCTURE: ID

FORMAT:

        ASK STRUCTURE struc_name: ID str_var 

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:

The ASK STRUCTURE: ID statement asks the operating system for the ID of a structure and returns it in the string variable str_var.

14.8.8 ASK STRUCTURE: POINTER

FORMAT:

        ASK STRUCTURE struc_name: POINTER num_var 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
            EXTRACT STRUCTURE cl 
            END EXTRACT 
            FOR EACH cl 
              ASK STRUCTURE cl: POINTER ptr 
              PRINT ptr, cl(last) 
            NEXT cl 
        20  END 
 
        RNH 
         1                Smith 
         2                Jones 
         3                Kent 
         4                Johnson 
         5                Waters 
         6                Errant 
         7                Brock 
         8                Cass 
         9                Porter 
         10               Derringer 
         11               Farmer 

DESCRIPTION:

From within a FOR EACH...NEXT STRUCTURE_NAME block, ASK STRUCTURE: POINTER asks the structure for the number of the current record pointer.

14.8.9 ASK STRUCTURE: RECORD

FORMAT:

        ASK STRUCTURE struc_name: RECORD num_var 

EXAMPLE:

        10  OPEN STRUCTURE ml: NAME 'tti_run:maint_log' 
            EXTRACT STRUCTURE ml 
              ASK STRUCTURE ml: RECORD ml_rec 
              PRINT ml_rec, ml(cost) 
            END EXTRACT 
        20  END 
 
        RNH 
         1                      $450.00 
         2                    $3,200.00 
         3                      $370.00 
         4                    $1,200.00 
         5                      $600.00 
         6                      $770.00 

DESCRIPTION:

ASK STRUCTURE: RECORD asks for the relative record number of the current record and places that number in the numeric variable given.

14.8.10 ASK STRUCTURE: RECORDSIZE

FORMAT:

        ASK STRUCTURE struc_name: RECORDSIZE int_var 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
        20  ASK STRUCTURE cl: RECORDSIZE recsize 
        30  PRINT 'Logical recordsize: '; recsize 
        40  END 
 
        RNH 
        Logical recordsize:   400 

DESCRIPTION:

The ASK STRUCTURE: RECORDSIZE statement returns the record size of the structure data file.

14.8.11 ASK STRUCTURE: ACCESS

FORMAT:

        ASK STRUCTURE struc_name: ACCESS str_var 

EXAMPLE:

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

DESCRIPTION:

The ASK STRUCTURE: ACCESS statement retrieves the access rules for the specified structure. Security level, data file read, write, update, and delete rules are returned.

14.8.12 ASK |SET STRUCTURE: TIMEOUT

FORMAT:

        ASK STRUCTURE struc_name: TIMEOUT int_var 
        SET STRUCTURE struc_name: TIMEOUT int_expr 

DESCRIPTION:

The ASK STRUCTURE: TIMEOUT statement asks for the current TIMEOUT setting.

The SET STRUCTURE: TIMEOUT statement is used when a record is locked for over the int_expr. INTOUCH then returns a TIMEOUT error.

14.8.13 ASK | SET STRUCTURE #string_expr . . .

FORMAT:

        ASK STRUCTURE #string_expr. . . 
        SET STRUCTURE #string_expr. . . 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
            str$ = 'CL' 
            fld$ = 'ID' 
            do_work 
            STOP 
 
        20  ROUTINE do_work 
            ASK STRUCTURE #str$, FIELD #fld$: DESCRIPTION dsc$ 
            PRINT 'Description is: '; dsc$ 
            END ROUTINE 
        
        30  END 
 
        RNH 
        Description is: Client ID number 

DESCRIPTION:

You can use a string expression for the structure name in an ASK STRUCTURE #string_expr or SET STRUCTURE #string_expr statement. This allows you to write generalized code to work for several structures.

14.8.14 ASK STRUCTURE: ENGINE

FORMAT:

        ASK STRUCTURE struc_name : ENGINE str_var 

EXAMPLE:

        10  OPEN STRUCTURE cl : name 'tti_run:vendor' 
        20  ASK STRUCTURE  cl : ENGINE ename$ 
        30  PRINT 'DATABASE ENGINE is: '; ename$ 
        40  END 
 
        RNH 
        DATABASE ENGINE is: RMS 

DESCRIPTION:

The ASK STRUCTURE: ENGINE statement returns the name of the database engine (record management system) being used for the specified structure in str_var.

14.9 SET STRUCTURE

The SET STRUCTURE statement is used to change various device and structure characteristics from within your programs.

FORMAT:

        SET STRUCTURE struc_name: struc_option [num_var | str_var] 

SET STRUCTURE sets characteristics of structures. struc_name is the name of the structure whose characteristics are being set. struc_option is the option you are setting. The options are explained in the following sections.

14.9.1 SET STRUCTURE: CURRENT

FORMAT:

        SET STRUCTURE struc_name: CURRENT str_expr 

EXAMPLE:

        10  DIM a$(100) 
            LET i = 0 
        20  OPEN STRUCTURE cl: NAME 'tti_run:client' 
        30  EXTRACT STRUCTURE cl 
            END EXTRACT 
        40  FOR EACH cl 
              PRINT cl(last); ', '; cl(first) 
              INPUT 'Would you like to see this record (Y/N)': yn$ 
              IF  yn$ = 'Y'  THEN    
                LET i = i + 1 
                ASK STRUCTURE cl: CURRENT a$(i) 
              END IF 
            NEXT cl 
        50  PRINT 
            FOR j = 1 TO i 
              SET STRUCTURE cl: CURRENT a$(j) 
              PRINT cl(last); ','; cl(first), cl(state), cl(phone) 
            NEXT j 
        60  END 
 
        RNH 
        Errant, Earl      Would you like to see this record (Y/N)? Y 
        Abott, Al         Would you like to see this record (Y/N)? Y 
        Brock, Bud        Would you like to see this record (Y/N)? N 
        Cass, Cathy       Would you like to see this record (Y/N)? N 
        Derringer, Dale   Would you like to see this record (Y/N)? Y 
        Farmer, Fred      Would you like to see this record (Y/N)? Y 
        Errant, Earl       CA       (408) 844-7676 
        Abott, Al          NY       (202) 566-9892 
        Derringer, Dale    CA       (818) 223-9014 
        Farmer, Fred       FL       (305) 552-7872 

DESCRIPTION:

The CURRENT option sets the current record to that specified by the str_expr. The str_expr contains the information for the current record for the record management system you are using. You can use ASK STRUCTURE: CURRENT to store a current record value into a string variable.

When INTOUCH executes a SET STRUCTURE: CURRENT statement, it uses the structure name and sets the current record to the value specified by the string variable. The structure must be open and str_expr must contain a value stored with the ASK STRUCTURE: CURRENT statement.

If you use a null string for the value, INTOUCH sets the structure to no current record and sets _EXTRACTED to zero.

        SET STRUCTURE struc_name: CURRENT '' 

14.9.2 SET STRUCTURE, FIELD: KEY

FORMAT:

        SET STRUCTURE struc_name, FIELD field_expr: KEY str_expr 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
            LINE INPUT 'Enter an ID': id$ 
            SET STRUCTURE cl, FIELD id: KEY id$ 
            IF  _EXTRACTED = 0  THEN 
               MESSAGE ERROR: 'Not found' 
            ELSE 
               PRINT cl(id), cl(last) 
            END IF 
        20  END 
 
        RNH 
        Enter an ID? 80561 
        80561               Derringer 

DESCRIPTION:

The FIELD option lets you get a record by means of a key field in a structure. You can use SETUP's "SHOW FIELDS" menu option (see Chapter 16, Creating Structures, Field Definitions with SETUP) to see the field names. The FIELD option is currently used only with the KEY or PARTIAL KEY option. The KEY option specifies the key to look for. The key is contained in str_expr.

The above example shows how to look in the CLIENT structure for an ID.

_EXTRACTED contains the number of records extracted. If the operation fails, _EXTRACTED will be 0 and an error message will be displayed.

14.9.3 SET STRUCTURE, FIELD: PARTIAL KEY

FORMAT:

        SET STRUCTURE struc_name, FIELD field_expr: PARTIAL KEY str_expr 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
            INPUT 'Name': name$ 
            SET STRUCTURE cl, FIELD last: PARTIAL KEY name$ 
            PRINT cl(id); ' '; cl(last) 
        20  END 
 
        RNH 
        Name? D 
        80561 Derringer 

DESCRIPTION:

This statement retrieves the first record matching the partial key in str_expr.

14.9.4 SET STRUCTURE: ID

FORMAT:

        SET STRUCTURE struc_name: ID str_expr 

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:

SET STRUCTURE: ID sets a structure to a structure ID that you have stored previously into a string variable with the ASK STRUCTURE: ID statement. Once you have used the SET STRUCTURE: ID statement, you can access the structure with the new structure name (STR in the example). By using these statements, you can write generalized routines when you do not know which structure you are going to access until run time.

14.9.5 SET STRUCTURE: POINTER

FORMAT:

        SET STRUCTURE struc_name: POINTER num_expr 

EXAMPLE:

        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
            EXTRACT STRUCTURE cl 
            END EXTRACT 
            SET STRUCTURE cl: POINTER 3 
            PRINT cl(id); ' ' ; cl(last) 
        20  END 
 
        RNH 
        20000 Kent 

DESCRIPTION:

This statement sets the structure to the nth record extracted. The statement is useful after you have done an extract, because it provides random access to any record extracted. There is no error message if there are no records extracted, or if the number given is out of range. If the number is valid, _EXTRACTED is set to 1; otherwise, it is set to 0.

14.9.6 SET STRUCTURE: RECORD

FORMAT:

        SET STRUCTURE struc_name: RECORD num_expr 

EXAMPLE:

        10  OPEN STRUCTURE ml: NAME 'tti_run:maint_log' 
            SET STRUCTURE ml: RECORD 3 
            PRINT ml(cost) 
        20  END 
 
        RNH 
            $370.00        

DESCRIPTION:

SET STRUCTURE: RECORD sets the structure to the record number given. The statement works only for structures that support relative record access.

14.9.7 SET STRUCTURE: EXTRACTED 0

FORMAT:

        SET STRUCTURE struc_name: EXTRACTED 0 

EXAMPLE:

        10  OPEN STRUCTURE vend: NAME 'tti_run:vendor' 
            SET STRUCTURE vend: EXTRACTED 0 
        20  END 

DESCRIPTION:

Setting the number of records extracted to zero causes a new collection to be started. The SET STRUCTURE struc_name : EXTRACTED 0 statement is used in conjunction with the EXTRACT STRUCTURE struc_name: APPEND statement.

14.9.8 SET STRUCTURE, SET, USING: EXPRESSION 'owner'

FORMAT:

        SET STRUCTURE struc_name1, SET 'set_name', USING struc_name2: EXPRESSION 'owner' 

EXAMPLE:

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

DESCRIPTION:

This statement used for DBMS handling, fetches the owner of the structure specified by struc_name1. The structure specified by struc_name2 is the owner of struc_name1 with the set given in set_name.

14.9.9 SET STRUCTURE, SET: EXPRESSION 'owner'

FORMAT:

        SET STRUCTURE struc_name1, SET 'set_name': EXPRESSION 'owner' 

EXAMPLE:

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

DESCRIPTION:

This statement is used for DBMS handling.

14.9.10 SET STRUCTURE, SET, USING, FIELD: KEY

FORMAT:

        SET STRUCTURE struc_name1, SET 'set_name', USING 'struc_name2', 
                FIELD field_expr: KEY str_expr 

EXAMPLE:

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

DESCRIPTION:


Next page... | Table of Contents