INTOUCH® 4GL
A Guide to the INTOUCH Language


Previous page... Table of Contents

Chapter 16
Creating Structures, Field Definitions with SETUP

16.1 SETUP--Overview

INTOUCH works with data in any record management system. SETUP tells INTOUCH where data files are located and what record management systems are used. Once you have defined your structures with SETUP, you can use INTOUCH's structure statements to manipulate the data.

SETUP now supports the following database engines:

Procedures

The following procedures are available in SETUP:

Each of the SETUP procedures is described in detail on the following pages.

16.1.1 Entering SETUP

To enter SETUP, type CALL SETUP at the INTOUCH prompt.

Example 16-1 To Use SETUP


INTOUCH CALL SETUP

SETUP will ask you a number of questions including:

Example 16-2 SETUP Prompts


SETUP V4.2 Set Up INTOUCH 4GL Data Structures Structure name : Database engine: Dataset : Data dictionary: Structure name? _______________________________________________________________ EXIT = Exit \ = Back HELP = Help

You can create a new structure by entering new file names or you can modify existing structures by selecting them at the prompts.

Once you have specified the structure you want to work with, you can define fields in the structure or display field definitions.

16.2 SETUP Prompts

This section describes the SETUP prompts and your options for answering them.

When you are using SETUP and are at any of the prompts, you can enter HELP or press the Help key to get information about the prompt.

Default answers are provided for many of the prompts. If you want to accept the answer provided, press the Return key at the prompt. If you do not want to use the default, type your answer over the default.

If you want to go back to a previous prompt, use the "\" (backslash key) to back up.

16.2.1 Structure Name

Enter a structure name. This can be a new name or the name of an existing structure. If you are creating a new structure, this will be the name of the structure file. The default extension for the file is .STR. The structure file contains:

Your structure name can be any VMS file specification. (See the chapter INTOUCH Running Under VMS for information on VMS file specifications.)

16.2.2 Database engine

Use the arrow keys to select the database engine (record management system) used by this structure. INTOUCH supports these systems:

(You can refer to the INTOUCH Interfaces to Database Engines manual for more information.)

If you are creating a new structure, the default will be RMS. If you are modifying an existing data structure, the default will be the database engine (record management system) specified in the structure file. FASTFILE is an INTOUCH record management system designed for speed.

16.2.3 Dataset

Enter the name of the data file (dataset) you will be using with this structure. If this is a new structure, the default data file name will be the same as the structure name. The default extension is .DAT.

You can use the same data file for a number of structures. For instance, you might use the CUSTOMER data file for both the CUSTOMER and the SALES structures:

          structure files      data file 
 
             CUSTOMER.STR         | 
                         \        | 
                          \       v 
                           \
                            CUSTOMER.DAT 
                           / 
                          / 
                         / 
                SALES.STR              

Your dataset name can be any VMS file specification. (See the chapter INTOUCH Running Under VMS for information on VMS file specifications.)

Rdb dataset

If the database engine is Rdb, the input format will be different. An Rdb database consists of tables. Each structure corresponds to one table. For Rdb, the dataset is the name of a table in the Rdb database.

        FORMAT:         table_name IN rdb_database 
 
        EXAMPLE:        employee in rdb_data:personnel 

DBMS dataset

For a DBMS dataset, you need to specify the DBMS record name and the name of the DBMS root file. Optionally, you can add the name of the subschema.

If the subschema is not given, the DEFAULT_SUBSCHEMA is assumed.

        FORMAT:         record_name IN [subschema_name FOR ] root_file 
 
        EXAMPLES:       part in datadisk:[parts]dbmparts 
 
                        part in ss0001 for datadisk:[parts]dbmparts 

INGRES dataset

For an INGRES dataset, you need to specify the INGRES table name. The INGRES database to use is specified by the symbol INT_INGRES_DBNAME.

        FORMAT:         table_name 
 
        EXAMPLE:        employee 

ADABAS dataset

For an ADABAS dataset, you need to specify the file number and the database number.

        FORMAT:         file_number IN database_number 
 
        EXAMPLE:        6 IN 1 

ORACLE dataset

For an ORACLE dataset, you need to specify the ORACLE table name.

        FORMAT:         table_name 
 
        EXAMPLE:        emp 

16.2.4 Data dictionary

Enter the name of the definition file you will be using with this structure. If you are creating a new structure, the default definition file name will be the same as the structure name. The default extension is .DEF.

As with the data file, you can use the same definition file for a number of structures. In fact, you can create any combination of definition, data and structure files:

 
structure files          data file          definition files 
 
      CUSTOMER.STR                      CUSTOMER.DEF 
                  \                    / 
                   \                  / 
                    \                / 
                     \              /   
                      \CUSTOMER.DAT/  
                      /            \
                     /              \
                    /                \
                   /                  \ 
          SALES.STR                    SALES.DEF 
 

Your definition file name can be any VMS file specifications. (See the chapter INTOUCH Running Under VMS for information on VMS file specifications.)

There are three special definition file names allowed. If the database engine for this structure can supply the field information and you want to use these native definitions, enter NONE as the definition file name and INTOUCH will use the definitions embedded in the database engine with the fields.

These database engines can supply the field definitions:

If you are using a database engine that supports native field definitions (Rdb, for example) and you would like to augment the native definitions with additional definitions, you can enter a definition file name prefixed with AUG>. This will create an augmented definition file. The native field names will be available along with any fields defined in the augmented definition file. Typically, augmented definitions are used to supply report headings, prompt text and print masks.

For example, if you have an Rdb table which contains of the following native fields:

                Name            Start           Length 
                -----           -----           ------ 
                fielda             1              10 
                fieldb            11               5 
                fieldc            16              10 

and you want to define a field (an index) consisting of "fielda" and "fieldb", you can create an augmented data dictionary and define the index you want.

If you are using CDD, you can enter CDD> and a name of a CDD/Plus Directory and recordname:

                       CDD>DEVDISK:[DEVINT.CDDTEST]CUSTOMER 
                           ^                      ^^      ^ 
                           |                      ||      | 
                           +----------------------++------+ 
                              Directory name        record 
                                                    name 

CDD/Plus access is read only at this time.

After the structure information has been entered, the SETUP Procedure Menu will be displayed and you can select the SETUP procedure you want to perform.

16.3 SETUP Procedures

Example 16-3 SETUP Procedures


SETUP V4.2 Set Up INTOUCH 4GL Data Structures Structure name : CUSTOMER.STR Database engine: RMS Dataset : CUSTOMER.DAT Data dictionary: CUSTOMER.DEF +---Setup Procedure---+ | Define fields | | Show [>| | Modify structure [>| |---------------------| | Create data file | | EXIT | +---------------------+ EXIT = Exit \ = Back HELP = Help

The following procedures are available in SETUP:


Note

Depending on the database engine chosen and the definition file selected, you might not have all of these options.

To select the SETUP procedure you want to perform, use the arrow keys to highlight your selection and then press Return. You can also enter in the first few characters and press Return.

16.4 DEFINE Procedure

You can use the DEFINE procedure to define the fields in a structure. The DEFINE procedure is also used to modify and delete field definitions.

When the Define fields menu option is selected, the field definition input screen is displayed.

Example 16-4 Field Definition Input Screen


SETUP V4.2 Definitions for CUSTOMER.STR Fieldname : Classification : Description : Data type : First position : length: Occurs: Semantics : Prompt text : Report heading : Print mask : Screen mask : Help text : Access rules : Validation rules: Field name? _________________________________ Enter -fieldname to delete a field EXIT = Exit \ = Back HELP = Help

You will be asked first for the name of the field you wish to add, modify or delete. You will then be prompted for information about the field.

16.4.1 Field name

Enter the field name you wish to add, modify or delete. If you are adding a new field, the field name will be used to identify this field. If there are existing fields, you can use one of the SHOW options to get a list of the current field names.

If you wish to delete a field, enter a minus sign (-) followed by the field name. For example:

                Field name? -phone

The field name:

If you are modifying a field, the defaults for the rest of the DEFINE prompts will be your original responses. You can keep these defaults by pressing the Return key at the prompt. You can change the defaults by typing over the responses.

16.4.2 Classification

Enter the field class or press Return to accept the default of none.

The classification is optional.

Classification refers to a field class in the CLASSIFICATION data dictionary. Field classes are pre-defined commonly used data fields.

Using Classifications

There are cases when you use the same field type in a record or in several datasets. When this occurs, setting up a field class will save time in defining fields and help to ensure data integrity.

If, for example, you had a home phone field, work phone field and alternate phone field in your record, you would need to define the three phone fields using different field names but the same characteristics. The phone fields would all be 10 numeric characters in length and be printed in the format (123) 456-7890.

To ensure that all the phone numbers are defined exactly the same, you could define a phone class in the CLASSIFICATION data dictionary. The class name could be PHONE and be defined with the length (10), semantics (num), print mask ((###~)~ ###~-####) and validations (digits; minlength 10).

Then, whenever you want to define a phone number type field, you would enter the field name, HOME_PHONE for example, with PHONE as the classification and the classification data would automatically become the default answers to the remaining DEFINE prompts. If you did not want to use a particular default, you can simply type in a different answer at the prompt.

You would also be able to use the PHONE classification when defining phone fields in other dataset records.

Before you can use field classifications, you must first define the field classes in the CLASSIFICATION data dictionary.

Creating Field Classes

Field classes are defined the same way as any other data field. However, these fields are located in a specific data file called TTI_RUN:CLASSIFICATION. To create a field class, perform the following steps:

  1. Get into SETUP.
  2. Enter TTI_RUN:CLASSIFICATION as the structure name. The following information will be displayed:

            Structure name :  TTI_RUN:CLASSIFICATION.STR 
            Database engine:  RMS 
            Dataset        :  NONE 
            Data dictionary:  TTI_RUN:CLASSIFICATION.DEF 
    
  3. Select the Define fields procedure.
  4. At the field name prompt, enter the field class name you want to use (i.e. PHONE).
  5. Go through each of the prompts and set up the characteristics you want this field class to have.

You can set up as many field classes as you wish.

Using an Alternate Classification File

If you do not want to use the provided TTI_RUN:CLASSIFICATION data file, you can create one of your own. For example, you could create a structure such as CLASS_NAMES for your field classes. However, if you choose to do this, you MUST define the file as follows:

SETUP will then retrieve classification data from CLASS_NAMES instead of TTI_RUN:CLASSIFICATION.

Generated Defaults

After the classification prompt is answered, SETUP displays either the class defaults or defaults generated by SETUP to assist you in defining the field.

Example 16-5 DEFINE Screen showing field class generated defaults


SETUP V4.2 Definitions for CUSTOMER.STR Fieldname : HOME_PHONE Classification : PHONE Description : Home phone Data type : CH First position : 14 length: 10 Occurs: 1 Semantics : NUM, RJ Prompt text : Home phone Report heading : Home Phone Print mask : (###~)~ ###~-#### Screen mask : none Help text : none Access rules : NORMAL Validation rules: digits; minlength 10 Description? Home phone____________________ EXIT = Exit \ = Back HELP = Help

Example 16-6 DEFINE Screen showing SETUP generated defaults


SETUP V4.2 Definitions for CUSTOMER.STR Fieldname : HOME_PHONE Classification : none Description : Home phone Data type : CH First position : 14 length: Occurs: 1 Semantics : UC Prompt text : Home phone Report heading : Home Phone Print mask : none Screen mask : none Help text : none Access rules : NORMAL Validation rules: none Description? Home phone____________________ EXIT = Exit \ = Back HELP = Help

16.4.3 Description

Enter a description of the field. The description can consist of any characters on the keyboard and be up to 30 characters long.

If you are adding this field, the default description is the field name with any "$", "%", "_" characters changed to spaces.

The description will be used as the default prompt text.

16.4.4 Data type

Enter the data type for this field. The data type is the internal representation of the data. The most common type is CH (character) which is the default. The data type will be one of the following:
AC ASCII counted string
AP Pointer to ASCII counted
C3 COBOL comp-3, also known as packed decimal; the C3 data type also supports the VAX DECIMAL data type
CH Character
DS Date stamp (length=8)
EB EBCDIC
FL Floating point
GF G-Float
IN Integer (signed)
IU Integer (unsigned)
PF Packed floating
PZ Packed zipcode
QS Quadword (signed)
RO Right overpunch
RS Right sign separate
UN Undefined
ZE Zoned EBCDIC
ZN Zoned numeric; used by DIBOL

The DATE (DS) attribute is currently only used by applications and has no effect within INTOUCH.

16.4.5 First position

Enter the position at which this field will start. Character positions are numbered sequentially. For example: Figure 16-1 Character Positions

 
                   ID        CONTACT 
                   ----------------------------------------------- 
                   | | | | | | | | | | | | | | | | | | | | | | | | 
                   |       |         |         |         |      
         positions 1       5        10        15        20      
 

In the above diagram, the ID field starts at position 1 and ends at position 5. The CONTACT field starts at position 6, etc.

Fields generally follow each other directly. Therefore, the first position of a new field is usually one more than the last position used. If the last position used was ten, the next field would start at eleven. INTOUCH automatically defaults to the correct sequential position.

Defining existing RMS file fields

If you are defining fields for an existing RMS file, you must keep in mind that the starting position of an RMS file record is 0 and in INTOUCH, the starting position is 1. (RMS is 0 oriented, whereas INTOUCH is 1 oriented.) For example, if the RMS file field starts in position 0, when you define this field in INTOUCH, you must define the field as starting in position 1. If the RMS field starts in position 20, you would use 21 as the starting position, etc.


Next page... | Table of Contents