INTOUCH® 4GL
A Guide to the INTOUCH Language


Previous page... Table of Contents

This statement fetches the first struc_name1 record using the key given in str_expr within the set, set_name, where struc_name2 is the owner.

14.9.11 SET STRUCTURE, SET, USING

FORMAT:

        SET 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' 
            SET STRUCTURE class, SET 'class_part', USING part 
        30  END 

DESCRIPTION:

This statement is used for DBMS handling and fetches the first struc_name1 within a set. The record referred to by struc_name2 is the owner.


Chapter 15
File Handling

Files are places where information is stored. You can access files from within your INTOUCH programs. Files exist outside of your program. Therefore, when your program ends, the file and the information in it still exists. The next time you run the program, you can access the file, remove old information from it and store new information in it.

Files are stored on devices: disks, tapes, etc.. They are stored under file specifications, which include a device name. For information on file names and file specifications, see Section 17.1, File Specifications and the Command Language and DCL User's Guide of the OpenVMS documentation set.

The following pages describe the INTOUCH statements used to manipulate files.

15.1 OPEN #chnl_num: NAME ...

FORMAT:

        OPEN #chnl_num: NAME 'file_spec' 
               [, ACCESS INPUT| OUTPUT | OUTIN ] [, UNFORMATTED] 
               [, UNIQUE] [, OPTIMIZE OFF] 

EXAMPLE:

        10  OPEN #1: NAME 'test_file.tmp', ACCESS OUTPUT 
            PRINT #1: 'This is the first line of text.' 
            PRINT #1: 'This is the second line of text.' 
        20  CLOSE #1 
        30  OPEN #1: NAME 'test_file.tmp', ACCESS INPUT 
            LINE INPUT #1: line_1$, line_2$ 
            PRINT line_1$ 
            PRINT line_2$ 
        40  CLOSE #1 
 
        RNH 
        This is the first line of text. 
        This is the second line of text. 

PURPOSE:

OPEN opens a file so you can read from it and write to it. You can also use OPEN to create a file.

DESCRIPTION:

OPEN either opens an existing file or creates a new one. #chnl_num is the channel number associated with the file. chnl_num can be any integer number in the range of 1 to 95. (0 is the channel number associated with the terminal. Channel number 0 cannot be opened or closed.) The channel number is used to refer to the file. The channel number must be unique. If a channel number is already associated with an open file, an exception is generated.

file_spec gives the file specification of the file being opened. The file specification can be any string expression.

15.1.1 OPEN Options

The OPEN statement has several options. Multiple options are separated with commas.

15.1.1.1 ACCESS Option

The ACCESS option specifies one of three input/output options. These options tell INTOUCH whether you want to input (read) data, output (store) data or input and output data.

ACCESS INPUT

ACCESS OUTPUT

ACCESS OUTIN

15.1.1.2 UNFORMATTED Option

When you write to a file opened as UNFORMATTED, the writes are done without any carriage control. This allows various character sequences to be sent to the channel without having CR/LF (carriage return/line feed) sequences sent as well.

        10  OPEN #1: NAME 'tt:', ACCESS OUTPUT, UNFORMATTED 
        20  FOR i = 1 TO 10 
              PRINT #1: i; 
            NEXT i 
        30  END 
 
        RNH 1  2  3  4  5  6  7  8  9  10 

15.1.1.3 OPTIMIZE OFF Option

When you specify OPTIMIZE OFF, the file is opened without any of the INTOUCH I/O optimizations.

        10  OPEN #2: NAME 'report.txt', OPTIMIZE OFF 
        20  END 

15.1.1.4 UNIQUE Option

When the UNIQUE option is used, the file is created with a unique name. These are usually temporary work or holding files for listings, etc.

        10  OPEN #12: UNIQUE, ACCESS OUTPUT 
        20  ASK #12: NAME x$ 
        30  PRINT x$ 
        40  CLOSE #12 
        50  END 
 
        RNH 
        SYS$SCRATCH:TMP_B90001.TMP 

The following example illustrates how to create uniquely named files based on file_spec.

        10  OPEN #12: NAME 'payroll', UNIQUE, ACCESS OUTPUT 
        20  ASK #12: NAME x$ 
        30  PRINT x$ 
        40  CLOSE #12 
        50  END 
 
        RNH 
        SYS$SCRATCH:PAYROLL_AE0001.TMP 

15.2 CLOSE #chnl_num

FORMAT:

        CLOSE [#chnl_num | ALL] 

EXAMPLE:

        10  OPEN #1: NAME 'test_file.lis', ACCESS OUTPUT 
        20  PRINT #1: 'This is the first line.' 
        30  PRINT #1: 'Here is the second line.' 
        40  CLOSE #1 
        50  END 

PURPOSE:

CLOSE #chnl_num closes a file. CLOSE ALL closes all files. You should close your files before your program ends.

DESCRIPTION:

CLOSE closes a file from further access. Once a file is closed, data cannot be stored in it or read from it. chnl_num is the channel number associated with the file. (The channel number is assigned in the OPEN statement.) The channel number can be given as any numeric expression.

15.3 PRINT #chnl_num

The PRINT #chnl_num statement writes data to a file so the data can be referenced at a later time.

FORMAT:

        PRINT #chnl_num [, USING print_mask]: [TAB(col){, | ;}] [expr {, | ;} 
                                              [TAB(col){, | ;}] expr...] 

EXAMPLE:

        10  OPEN #1: NAME 'test.tmp', ACCESS OUTPUT 
            PRINT #1, USING '{UCASE}?': 'first line' 
            PRINT #1: TAB(5); 'second line' 
            CLOSE #1 
        20  OPEN #1: NAME 'test.tmp', ACCESS INPUT 
            LINE INPUT #1: record_1$, record_2$ 
            PRINT record_1$ 
            PRINT record_2$ 
            CLOSE #1 
        30  END 
 
        RNH 
        FIRST LINE 
            second line 

DESCRIPTION:

PRINT writes data to a file. The file must be open and have a channel number associated with it. chnl_num is the channel number and it can be any numeric expression. expr is the expression being stored in the file. When INTOUCH executes a PRINT statement, it evaluates the expression and stores its value in the file. The expression is optional. A PRINT statement without an expression writes a blank line to the file.

15.4 INPUT #chnl_num: var, var...

FORMAT:

        INPUT #chnl_num: var, var... 

EXAMPLE:

        10  OPEN #1: NAME 'number.dat', ACCESS OUTPUT 
            PRINT #1: 1; 2; 3 
            CLOSE #1 
        20  OPEN #1: NAME 'number.dat', ACCESS INPUT 
            INPUT #1: a, b, c 
            PRINT a; b; c 
        30  CLOSE #1 
        40  END 
 
        RNH 
         1  2  3 

DESCRIPTION:

The INPUT #chnl_num statement is used to read the data stored in a file. The file must be open and have a channel number associated with it. The simplest version of the INPUT statement is:

        INPUT #chnl_num: var 

chnl_num is the channel number associated with the file. The channel number can be any integer expression. var is the variable the data is assigned to. Each time data is input from a file, it must be assigned to a variable. The data input must match the variable's data type. INTOUCH inputs data sequentially starting at the beginning of the file.

15.4.1 Inputting Multiple Variables

One INPUT statement can be used to input data into a number of variables. The variables in the INPUT list must be separated by commas.

        INPUT #chnl_num: var, var, var... 

INTOUCH inputs data sequentially, starting from the beginning of the file. INTOUCH continues inputting data until all the variables in the list have values.

        10  DIM num(10) 
            OPEN #1: NAME 'number.dat', ACCESS OUTPUT 
        20  PRINT #1: 1 
            PRINT #1: 2 
            PRINT #1: 3 
        30  CLOSE #1 
        40  OPEN #1: NAME 'number.dat', ACCESS INPUT 
        50  FOR i = 1 TO 3 
              INPUT #1: num(i) 
              PRINT num(i); 
            NEXT i 
        60  CLOSE #1 
        70  END 
 
        RNH 
         1  2  3 

If the variable and data types don't match, an exception will be generated.

If an attempt is made to input more data than the file contains, an exception is generated.

15.5 LINE INPUT #chnl_num: str_var, str_var...

FORMAT:

        LINE INPUT #chnl_num [, EOF num_var]: str_var, str_var... 

EXAMPLE:

        10  OPEN #1: NAME 'test_file.tmp', ACCESS INPUT 
        20  LINE INPUT #1: line_1$, line_2$ 
            PRINT line_1$, line_2$ 
        30  CLOSE #1 
        40  END 
 
        RNH 
        This is the first line of text.         This is the second line of text. 

DESCRIPTION:

LINE INPUT #chnl_num reads a line of text from a file. Everything on the line including commas, quotation marks, semi-colons, etc., is accepted as part of the input line.

The file must be open and have a channel number associated with it. The simplest version of the LINE INPUT statement is:

        LINE INPUT #chnl_num: str_var 

chnl_num is the channel number associated with the file. The channel number can be any integer expression. str_var is the variable to which data is being assigned. When INTOUCH executes the LINE INPUT statement, it reads a line from the file and assigns it to the string variable specified.

LINE INPUT accepts as the input data, everything from the beginning of the line up to the first line terminator. The contents of the line---including commas, quotation marks, tabs, leading and trailing spaces, etc.---are assigned to the string variable specified. A string variable must be specified. If a numeric variable is specified, an error will result. If the line being read is empty, INTOUCH assigns a null string to the string variable.

15.5.1 EOF Option

The EOF option of LINE INPUT causes INTOUCH to return a TRUE/FALSE value indicating when the end-of-file has been reached. This eliminates the need for an error handler when reading files. The format is:

        LINE INPUT #chnl_num, EOF num_var: str_var 

        10  ven_ch = _CHANNEL 
            OPEN #ven_ch: NAME 'test_file.tmp' 
            DO 
              LINE INPUT #ven_ch, EOF endfile?: datafile$ 
              IF  endfile?  THEN  EXIT DO 
              PRINT 'line was: '; datafile$ 
            LOOP 
            CLOSE #1 
        20  END 
 
        RNH 
        line was: This is the first line of text. 
        line was: This is the second line of text. 

_CHANNEL is the next available channel number.

15.5.2 Multiple Variables

LINE INPUT can be used to read several lines of data from a file. To read more than one item, separate the string variables with commas. Lines are read sequentially, starting from the beginning of the file, and assigned to the variables listed.

        10  OPEN #1: NAME 'test_file.tmp', ACCESS INPUT 
        20  LINE INPUT #1: line_1$, line_2$ 
            PRINT '1  '; line_1$ 
            PRINT '2  '; line_2$ 
        30  CLOSE #1 
        40  END 
 
        RNH 
        1  This is the first line of text. 
        2  This is the second line of text. 

If an attempt is made to input more data than the file contains, INTOUCH generates an exception.

15.6 ASK #chnl_num:

FORMAT:

        ASK #chnl_num: [NAME str_var][, ZONEWIDTH num_var] [, MARGIN num_var] 
                       [, CURRENT str_var] 

EXAMPLE:

        10  OPEN #3: NAME 'storage.dat', ACCESS OUTPUT 
        20  ASK #3: ZONEWIDTH x 
            PRINT 'The current print zone width is'; x 
        30  CLOSE #3 
        40  END 
 
        RNH 
        The current print zone width is 20 

PURPOSE:

Use ASK #chnl_num to find what various characteristics a device is set to.

DESCRIPTION:

ASK returns the characteristic of the device specified and stores the value in a num_var or str_var. chnl_num is an optional channel number. If no channel number is specified, INTOUCH checks the default device. If a channel number is specified, INTOUCH checks the device associated with that channel number.

15.6.1 ASK Options

An option must be included in the ASK #chnl_num statement. The ask options currently available are described below.

ZONEWIDTH num_var

ASK #chnl_num: ZONEWIDTH finds the print zone width of the device specified and assigns the value to the numeric variable num_var.

        10  OPEN #3: NAME 'storage.dat', ACCESS OUTPUT 
        20  ASK #3: ZONEWIDTH x 
            PRINT 'The current print zone width is'; x 
        30  CLOSE #3 
        40  END 
 
        RNH 
        The current print zone width is 20 

MARGIN num_var

ASK MARGIN finds the right margin of the device specified and assigns its value to the numeric variable num_var.

        10  OPEN #3: NAME 'test_file.tmp', ACCESS OUTPUT 
        20  ASK #3: MARGIN marg 
            PRINT 'The current margin is'; marg 
        30  CLOSE #3 
        40  END 
 
        RNH 
        The current margin is 132 

CURRENT str_var

ASK #chnl_num: CURRENT is used to store a current record value into the str_var.

        10  OPEN #1: NAME 'temp.tmp', ACCESS OUTPUT 
            FOR z = 1 TO 20 
              PRINT #1: 'This is line number '; z 
            NEXT z 
            CLOSE #1 
        20  OPEN #1: NAME 'temp.tmp' 
            FOR i = 1 TO 5 
              LINE INPUT #1: a$ 
            NEXT i 
            ASK #1: CURRENT c$ 
            PRINT '5th item was: '; a$ 
        30  FOR i = 1 TO 5 
              LINE INPUT #1: a$ 
            NEXT i 
            PRINT '10th item was: '; a$ 
        40  SET #1: CURRENT c$ 
            LINE INPUT #1: a$ 
            PRINT 'Back to 5th item again: '; a$ 
        50  CLOSE #1 
        60  END      
        
        RNH 
        5th item was: This is line number  5 
        10th item was: This is line number  10 
        Back to 5th item again: This is line number  5 

NAME str_var

ASK #chnl_num: NAME asks the INTOUCH operating system for the file specification of the file open on channel #chnl_num and stores the value into str_var.

        10  out_ch = 12 
        20  OPEN #out_ch: NAME 'sys$scratch:minutes.lis', & 
                ACCESS OUTPUT 
        30  ASK #out_ch: NAME x$ 
        40  PRINT x$ 
        50  CLOSE #out_ch 
        60  END 
 
        RNH 
        USER:[TESTER]MINUTES.LIS 

15.7 SET #chnl_num: expr

FORMAT:

        SET # chnl_num: [ ZONEWIDTH num_expr ] [, MARGIN int_expr] 
                        [, CURRENT str_expr] 

EXAMPLE:

        10  OPEN #3: NAME 'storage.dat', ACCESS OUTPUT 
        20  ASK #3: ZONEWIDTH x 
            PRINT 'The current print zone width is'; x 
            SET #3: ZONEWIDTH 35 
            ASK #3: ZONEWIDTH x 
            PRINT 'The new print zone width is'; x 
        30  CLOSE #3 
        40  END 
 
        RNH 
        The current print zone width is 20 
        The new print zone width is 35 

DESCRIPTION:

SET #chnl_num sets various device characteristics. chnl_number is a channel number. If no channel number is specified, INTOUCH sets the default device (the terminal). If a channel number is specified, INTOUCH sets the device associated with that channel number.

When a device characteristic is SET, it remains set until the device is closed. Therefore, if the terminal is SET, it will remain SET until you exit from the INTOUCH environment or the SET statement is used again.

15.7.1 SET #chnl_num: Options

An option must be included with the SET #chnl_num statement. The set options currently available are described below:

ZONEWIDTH num_expr

SET #chnl_num: ZONEWIDTH sets the print zone width of the device specified to the number designated. num_expr indicates the width to set the device's print zones. See above example.

MARGIN int_expr

SET #chnl_num: MARGIN sets the right margin on the device specified to the number indicated. int_expr specifies the column to set the margin to. The margin must be greater than the zonewidth.

        10  OPEN #3: NAME 'storage.dat', ACCESS OUTPUT 
        20  SET #3: MARGIN 45 
            PRINT #3: REPEAT$('1234567',10) 
            CLOSE #3 
        30  OPEN #3: NAME 'storage.dat', ACCESS INPUT 
            DO 
              LINE INPUT #3, EOF endfile?: item$ 
              IF  endfile?  THEN  EXIT DO 
              PRINT item$ 
            LOOP 
        40  CLOSE #3 
        50  END 
 
        RNH 
        123456712345671234567123456712345671234567123 
        4567123456712345671234567 

CURRENT str_expr

SET #chnl_num: CURRENT sets the current record to that specified by str_expr. The str_expr contains the information for the record you want to make current.

        10  OPEN #1: NAME 'temp.tmp', ACCESS OUTPUT 
            FOR z = 1 TO 20 
              PRINT #1: 'This is line number '; z 
            NEXT z 
            CLOSE #1 
        20  OPEN #1: NAME 'temp.tmp' 
            FOR i = 1 TO 5 
              LINE INPUT #1: a$ 
            NEXT i 
            ASK #1: CURRENT c$ 
            PRINT '5th item was: '; a$ 
        30  FOR i = 1 TO 5 
              LINE INPUT #1: a$ 
            NEXT i 
            PRINT '10th item was: '; a$ 
        40  SET #1: CURRENT c$ 
            LINE INPUT #1: a$ 
            PRINT 'Back to 5th item again: '; a$ 
        50  CLOSE #1 
        60  END      
        
        RNH 
        5th item was: This is line number  5 
        10th item was: This is line number  10 
        Back to 5th item again: This is line number  5 

15.8 Deleting Files

15.8.1 KILL

FORMAT:

        KILL str_expr 

EXAMPLE:

        5   ! DANGER -- Executing this program will DELETE a file
 
        10  INPUT 'What file do you want to delete': file$ 
        20  KILL file$ 
        30  END 
 
        RNH 
        What file do you want to delete? 

PURPOSE:

Use KILL to delete a file from within your program.

DESCRIPTION:

KILL searches for and deletes the file specified in str_expr, the string expression. You must include the full file name with extension. If you do not include a version number, KILL will delete the most recent version only.


Next page... | Table of Contents