Segmented Key Field

A key field can be defined which consists of two or more fields. If the fields which make up this key field are not adjoining (i.e. one after the other), this is called a segmented key field. Key fields consisting of two or more fields, whether segmented or not, must have a length that equals the total length of all the segments that make up the key field.

INTOUCH can extract records using a segmented key. The following is an example.

A record has the following field definitions:

Field Name Starting Position Length --------------- ----------------- ------ CUSTOMER_NUMBER 1 5 CUSTOMER_NAME 6 30 CREATE_DATE 36 8

To define a segemented key that consists of CREATE_DATE plus CUSTOMER_NUMBER, you would define another field that starts at the first position of the first segment of the key with the length being the sum of the lengths of all of the segments:

Field Name Starting Position Length --------------- ----------------- ------ DATE_CUST_KEY 36 13

To extract using this key:

EXTRACT STRUCTURE customer, FIELD date_cust_key: PARTIAL KEY "19960201" . . END EXTRACT

The above statement would extract all customer records created on 01-Feb-1996.

16.5 SHOW Procedure

You can use the arrow keys to select the Show procedure from the SETUP procedures menu.

SETUP Vn.n 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 Option-------+ | Show | Brief field display | | Modify structure | Full field display | |-------------------| List fields | | Create data file | Structure | | EXIT +------------------------+ +---------------------+ EXIT = Exit \ = Back HELP = Help

The SHOW procedure has four options:

• The Brief field display creates a listing of the fields showing some of the definition information.
• The Full field display creates a listing of the fields showing all of the definition information.
• The List fields option creates a listing of the defined fields.
• The Structure option displays information about the structure file.

SETUP creates the listings in report format so that you can display the field and structure information on your screen, print a hardcopy or save the information on disk.

After a report is created, you can select an output option from the Output Options menu. The default is Screen which will display the report to your screen. The line under the Output Options menu tells you the name of the temporary report file that was created.

+--------------------- Output Options ---------------------+ | Screen | System Printer | Laser Printer | | Printer Port | Save to Disk | EXIT | +----------------------------------------------------------+ Ready to print user:[tester]setup_show_definition_210006.tmp

If you are in the middle of displaying a report and want to exit out of the display, enter [CTL/Z] and you will return to the Output Options menu.

To return to the SETUP procedures menu, you can use the arrow keys to select the EXIT option or press "\" (backslash key).

16.5.1 Brief Field Display

Example 16-7 SHOW - Brief Field Display Example

08-Mar-1996 Definitions for: CUSTOMER.DEF Page: 1 Field Name Description First Length Occurs Last Dtype Print Mask --------------- ----------------- ----- ------ ------ ----- ----- ---------- CUSTNBR Customer number 1 5 1 5 CH none Semantics : none NAME Customer name 6 25 1 30 CH none Semantics : none ADDR1 Address line 1 31 25 1 55 CH none Semantics : none ADDRESS Address array 31 25 1 55 CH none Semantics : none

16.5.2 Full Field Display

Example 16-8 SHOW - Full Field Display Example

08-Mar-1996 Definitions for: CUSTOMER.DEF Page: 1 Field Name Description First Length Occurs Last Dtype Print Mask --------------- ----------------- ----- ------ ------ ----- ----- ---------- CUSTNBR Customer number 1 5 1 5 CH none Semantics : none Prompt text: Customer number Heading : Cust# Help : none Screen mask: none Validations: none NAME Customer name 6 25 1 30 CH none Semantics : none Prompt text: Customer name Heading : Customer name Help : none Screen mask: none Validations: none

16.5.3 List Fields Display

The List Fields Display shows the field name, description, first position of the field, field length and data type.

Example 16-9 SHOW - Fields List Display Example

08-Mar-1996 CUSTOMER.DEF - FIELDS Page: 1 Field Name Description First Length DT -------------------------------- ------------------------------ ----- ------ -- CUSTNBR Customer number 1 5 CH NAME Customer name 6 25 CH ADDR1 Address line 1 31 25 CH ADDRESS Address array 31 25 CH ADDR2 Address line 2 56 25 CH CITY City 81 20 CH STATE State 101 2 CH ZIP Zip 103 5 CH

16.5.4 Structure Display

The Structure option of SHOW displays information about the structure and security access levels.

Example 16-10 SHOW - Structure Display Example

08-Mar-1996 Structure: CUSTOMER.STR Page: 1 Structure name : CUSTOMER.STR Dataset : CUSTOMER.DAT Record system : RMS Data dictionary: CUSTOMER.DEF Access levels : SECURITY:N, READ:N, WRITE:N, UPDATE:N, DELETE:N

16.6 MODIFY STRUCTURE Procedure

• change the general structure information.
• change the structure security level information and the read, write, update and delete access levels.

SETUP Vn.n 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-----+ | Modify structure | General information | |-------------------| Security information | | Create data file +-------------------------+ | EXIT | +---------------------+ EXIT = Exit \ = Back HELP = Help

You can use the arrow keys to select the Modify structure procedure from the SETUP procedures menu and then select one of the two modify structure options.

16.6.1 Modify Structure General Information

SETUP Vn.n Set Up INTOUCH 4GL Data Structures Structure name : CUSTOMER.STR Database engine: RMS Dataset : CUSTOMER.DAT Data dictionary: CUSTOMER.DEF +Database Engine+ | RMS | | RDB | | DBMS | | USERBASE | | POISE | | FASTFILE | | S1032 | | INGRES | | DBASE3 | | ADABAS | | ORACLE | |---------------| | EXIT | +---------------+ EXIT = Exit \ = Back HELP = Help

You will be prompted for:

• Database engine
• Dateset
• Data dictionary

You can either press [Return] at the prompts to keep the current information or enter new information. If you need clarification on any of the prompts, you can refer back to the SETUP Prompts section in this chapter.

After the last prompt is answered, the STR file will be updated with the new information.

You will be returned to the SETUP procedures menu where you can select another option or exit SETUP.

16.6.2 Modify Structure Security Information

SETUP Vn.n Structure Security and Access Levels Structure security level: N Read access level : N Update access level : N Write access level : N Delete access level : N Structure security level? N Security levels are A to Z EXIT = Exit \ = Back HELP = Help

You will be prompted for:

• Structure security level information
• Read, update, write and delete access level information

You can either press [Return] at the prompts to keep the current information or enter new information.

Structure security level

Enter the security level associated with this structure.

The security level is a single letter in the range of A to Z.

Security level A is the highest level of security. Security level Z is the lowest level of security.

Read access level

Enter the access level required to read a data record in this structure.

The read access level is a single letter in the range A to Z. A is the most restricted access level. Z is the least restricted.

When an attempt is made to read a record from this structure, INTOUCH will compare the structure security level to the read access level. If the read access level is lower than the structure security level, the read request will be allowed.

For example:

Structure level Read access level Access --------------- ----------------- ------ K R Allowed K E Denied K K Allowed

Update, Write, Delete access levels

Enter the access levels required to update, write, delete data records in this structure. Answer each of the prompts with a letter from A to Z.

After the last prompt is answered, the STR file will be updated with the new security information.

You will be returned to the SETUP procedures menu where you can select another option or exit SETUP.

16.7 CREATE Procedure

SETUP Vn.n             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

Selecting the Create data file option from the SETUP procedures menu will allow you to create a data file.

After the CREATE option has been selected, the create screen will be displayed and you will be prompted for some information.

Example 16-11 CREATE Procedure RMS Input Screen

SETUP Vn.n Creating RMS data file: CUSTOMER.DAT File organization: Recordsize : +RMS File Organization+ | Indexed | | Sequential | +---------------------+ EXIT = Exit \ = Back HELP = Help

RMS File Organization

Select how you want your file to be organized. The options are:

• INDEXED - the data file record contains one or more key fields
• SEQUENTIAL - the data file record contains no key fields

If you are going to be sorting and/or extracting data from the RMS file you are creating, the indexed file organization is more efficient than the sequential organization. This is especially true if you have large files.

An indexed file contains one or more indexed key fields which allow programs to locate and access file data very quickly without having to read through the file to locate records.

A sequential file has no key fields and accessing file data can be very slow and time consuming. Locating data in a sequential file requires reading every record in the file to find all occurrences of the data.

If you select Indexed file organization, you will be asked for the key fields in later prompts.

Record size

Enter the record size that you want for this data file.

The default record size is 25% larger than the actual length of the fields defined. This allows room for adding new fields to the record without having to expand the record size.

The legal record sizes depend on the database engine (file management system) you use. For RMS, sizes range from 1 to approximately 32000.

If no additional information is required to create this data file, you can enter "Y"es at the Proceed with file creation prompt and your data file will be created using the appropriate database engine.

Primary key field

Select the field from the list of defined fields, that you want to use as the primary key field. The first field is the default.

RMS indexed files require at least one key field, the primary key field.

You can refer back to the "DEFINE Procedure" section for information on key fields.

SETUP Vn.n Creating RMS data file: CUSTOMER.DAT File organization: INDEXED Recordsize : 181 Primary key : Key 2 : +Primary Key Field Name+ Key 3 : | CUSTNBR | Key 4 : | NAME | Key 5 : | ADDR1 | Key 6 : | ADDRESS | Key 7 : | ADDR2 | Key 8 : | CITY | Key 9 : | STATE | Key 10 : | ZIP | | BALANCE | | CONTACT | | PHONE | |----------------------| | EXIT | +----------------------+ EXIT = Exit \ = Back HELP = Help

Allow duplicates

You can control whether the data to be stored in the RMS key field will be unique (only one occurrence of the data in the key field) or allow duplicates (multiple occurrences of the data in the key field).

Data access works most efficiently with unique key fields.

Normally, the PRIMARY key field is set up to allow only unique data in the field (i.e. NO duplicates) and the other key fields (ALTERNATE key fields) can be unique or not.

If you want more than one key field, select the fields you want to use as ALTERNATE key fields. Selecting All keys defined ends key field selection.

You will be asked if you want to proceed with file creation. Enter Y to create the data file.

After the file has been created, you will be returned to the SETUP procedures menu.

16.8 Defining COBOL Record Fields

The program expects the text file to contain a single COBOL record definition statement. The file must be in one of the following formats:

• An ANSI formatted file which contains line numbers in columns 1-6 and comments in columns 72-80.
• A TERMINAL formatted file which has no reserved columns at the beginning and end of the lines.

The file name or file specification that is to be defined can be up to 63 characters in length if the screen margin is set at 80. If the margin is set to 132, 115 characters are allowed.

16.8.1 Define Example

The sample text file COBOL_TEST.RECORD contains the following record definition statement:

01 test_rec. 05 code pic x. 05 desc pic x(20). 05 amount pic s9(5)v99 comp. 05 tbl occurs 3 times. 10 tbl-code pic x(5). 10 tbl-desc pic x(25).

To run the program, enter the following at the "$" prompt:

$ INTOUCH/SOURCE TTI_RUN:COBOL_DEF

The program screen will be displayed:

COBOL_DEF Vn.n Create INTOUCH Definition from COBOL Definition COBOL copy-lib: ANSI format : COBOL copy-lib? _______________________________________________________________ EXIT = Exit \ = Back HELP = Help

At the "COBOL copy-lib?" prompt, enter the file name. In this example, the file name is COBOL_TEST.RECORD.

At the "Is file in ANSI format (Y/N)? NO__" prompt, press the [Return] key to take the "NO" default because the COBOL_TEST.RECORD file is not in ANSI format, it is in TERMINAL format.

To proceed, enter "Y" at the "Proceed with definition creation (Y/N)?" prompt.

The program processes the COBOL_TEST.RECORD file and creates the COBOL_TEST.DEF file.

You are returned to the "COBOL copy-lib?" prompt. Enter EXIT to exit the program.