Contents

Get started with direct file I/O support in IBM Informix 4GL

Easy access to files from your database application

Deepak Agrawal and Vishwas T. Mahadevaiah
Published on July 15, 2010

Many database applications make extensive use of input/output (I/O) operations to read a file and use its contents in the application, to write output from the application to a file, or both. To accomplish file I/O with earlier versions of IBM Informix 4GL (I4GL), you had to write a set of C functions that you could then call from I4GL to handle opening a file, reading from a file, writing into a file, and closing the file. However, there were many disadvantages associated with this method because it required the extra steps involved with creating your own functions.

Now, with the 7.50.xC4 release of I4GL, you can use standard syntax such as OPEN FILE, CLOSE FILE, etc. to implement file I/O operations. This gives you considerable flexibility that cannot easily be matched by user-written functions. With this new functionality you can:

  • Open a file by specifying the mode and other information
  • Read a file into program variables
  • Write to a file
  • Seek through a file
  • Close a file

I4GL file I/O syntax

This section gives a brief description of the file I/O operations that I4GL supports. The syntax of each operation is explained and illustrated with an example.

OPEN FILE

Description:

Use this operation to open a file. If the operation completes successfully, it stores a non-negative integer file descriptor in int_var, which is then used in subsequent operations such as READ, WRITE, SEEK, CLOSE, etc.. On failure, a suitable error message is displayed.

Note: There is not necessarily a simple relationship between the system-level file descriptor and the value returned by the OPEN FILE operation.

Syntax:

OPEN FILE int_var FROM string or string_var OPTIONS (option_comma_list)
Table 1. Description of the place holders for OPEN FILE
Place holderDescription
int_varAn integer variable that contains the file descriptor for the file to be opened.
string or string_varA quoted string or a string variable that contains the pathname of the file to be opened. Length is restricted to 255 bytes.
option_comma_listA comma-separated list of options specified by the user. Refer to Table 2 for details.

Options that can be specified on the option_comma_list are shown in Table 2.

Table 2. Options in option_comma_list
OptionDescription
READOpen the file in read mode.
WRITEOpen the file in write mode.
APPENDOpen the file in append mode. Before each write, the file offset is positioned at the end of the file.
CREATEIf the file does not exist, it is created.
EXCLUSIVEUsed with the CREATE option. If the file already exists, the operation returns an error.
FORMATSpecifies how data in the file is to be read.
csv— values are comma separated (and quoted when necessary).
load— values are separated by a delimiter. Default delimiter is |.
text— read one string per line. These options can be specified either as a quoted string or in a string variable.
DELIMITERSpecifies the delimiter to be used with load format. The default delimiter for load format is the pipe character (|).
For csv format, the delimiter must be comma (,) and for text format, the delimiter must be new line (\n).
If you try to specify any other delimiters for csv or text format, a suitable error message is displayed (refer to Listing 9 for an example).

Examples:

OPEN FILE fd1 FROM "/tmp/example1.4gl" OPTIONS (READ, FORMAT = "CSV")

The example above opens the file named /tmp/example1.4gl in READ mode. The file descriptor is saved in fd1. The format of the file is CSV, which means the comma character is used as the delimiter. 

OPEN FILE fd2 FROM "/tmp/example2.4gl" 
        OPTIONS (WRITE, APPEND, CREATE, FORMAT = "load", DELIMITER= '@')

The example above opens the file named /tmp/example2.4gl in WRITE APPEND mode. If the file does not exist, it is created. The file descriptor is saved in fd2. The format of the file is load and the delimiter is the @ character.

CLOSE FILE

Description:

Use this operation to close an opened file. This operation closes a file descriptor, so that it no longer refers to any file.

Syntax:

CLOSE FILE int_var
Table 3. Description of the place holder for CLOSE FILE
Place holderDescription
int_varAn integer variable that contains the file descriptor for the file opened.

Example:

CLOSE FILE fd1

In the example above, fd1 contains the file descriptor of the file that is to be closed.

READ

Description:

This operation attempts to read data from the file referenced by the file descriptor into the specified variables.

Syntax:

READ FROM int_var INTO var_list
Table 4. Description of the place holders for READ
Place holderDescription
int_varAn integer variable that contains the file descriptor for the file to be opened.
var_listList of program variables into which data read from the file is stored.

Example:

READ FROM fd1 INTO v1, v2, v3

In the example above, fd1 contains the file descriptor of the file to be read. v1, v2, and v3 are the program variables into which data read from the file is stored. These variables can be used within the program based on the program logic.

WRITE

Description:

This operation writes the data specified in the variable list into the file referenced by the file descriptor.

Syntax:

WRITE TO int_var USING var_list
Table 5. Description of the place holders for WRITE
Place holderDescription
int_varAn integer variable that contains the file descriptor for the file to be written to.
var_listList of program variables which have data to be written into the file.

Example:

WRITE TO fd1 USING v1, v2, v3

In the example above, fd1 contains the file descriptor of the file that will be written to. v1, v2, and v3 are the program variables that contain data to be written into the file. These variables can be used within the program based on the program logic.

SEEK

Description:

This operation repositions the offset of the open file associated with the file descriptor. Use the values START, LAST, or CURRENT to specify the position from which to move the offset. START is the default position value.

Syntax:

SEEK ON int_var_1 TO int_var_2 [FROM {START|LAST|CURRENT}] [INTO int_var_3]
Table 6. Description of the place holders for SEEK
Place holderDescription
int_var_1An integer variable that contains the file descriptor for the open file that is to have its offset repositioned.
int_var_2An integer value or an integer variable that specifies the file offset to be used for repositioning.
int_var_3An integer variable used to store the resulting file offset.

Examples:

SEEK ON fd1 TO var1

In the example above, fd1 contains the file descriptor of the file. The var1 variable contains the new offset position. 

SEEK ON fd1 TO 0 FROM LAST INTO var1

In the example above, fd1 contains the file descriptor of the file. The value of 0 repositions the file pointer to the beginning of the file. The new offset position is stored in the var1 variable.

File I/O statements in I4GL programs

File I/O statements are supported in the following I4GL components:

  • The IBM Informix 4GL C compiler
  • The IBM Informix Rapid Development System (RDS)

You can develop applications that use file I/O with either the I4GL C Compiler or I4GL RDS. This article uses the IBM Informix 4GL C compiler (c4gl) to demonstrate the file I/O feature. The same functionality could also be coded using IBM Informix RDS.

Opening a file with different scenarios

The code in Listing 1 opens a set of files in different modes and closes those files at the end of the program.

Listing 1. Sample code for OPEN FILE
MAIN

DEFINE              var_fd1                      INTEGER, 
                    var_fd2                      INTEGER, 
                    var_fd3                      INTEGER, 
                    var_fd4                      INTEGER, 
                    var_fd5                      INTEGER, 
                    var_fd6                      INTEGER, 
                    var_file_name                VARCHAR(30),
                    var_file_format              VARCHAR(30),
                    var_file_delim               VARCHAR(30)

LET var_file_name = "/tmp/file_deag1"
LET var_file_format = "TEXT"
LET var_file_delim = "\n"

OPEN FILE var_fd1 FROM "/tmp/file_deag2" OPTIONS 
 (READ,WRITE, CREATE,FORMAT = "load", DELIMITER= "@")

OPEN FILE var_fd2 FROM var_file_name OPTIONS 
 (WRITE, APPEND,  CREATE, FORMAT = "load", DELIMITER= "@")

OPEN FILE var_fd3 FROM "/tmp/file_deag3" OPTIONS 
 (WRITE, APPEND,  CREATE, FORMAT = "text", DELIMITER= "\n")
	
OPEN FILE var_fd4 FROM "/tmp/file_deag4" OPTIONS 
(WRITE, APPEND,  CREATE, FORMAT = "CSV", DELIMITER= ",")

OPEN FILE var_fd5 FROM "/tmp/file_deag5" OPTIONS 
 (WRITE, APPEND,  CREATE, FORMAT = "CSV")

OPEN FILE var_fd6 FROM "/tmp/file_deag6" OPTIONS 
 (WRITE, APPEND,  CREATE)

CLOSE FILE var_fd1

CLOSE FILE var_fd2

CLOSE FILE var_fd3

CLOSE FILE var_fd4

CLOSE FILE var_fd5

CLOSE FILE var_fd6

END MAIN

Writing the data in program variables into a file

The program in Listing 2 opens the file named file_deag1 in read, write mode. A set of data types that can be used in I4GL is written into the file. The file is closed at the end of the program.

Listing 2. Sample code for WRITE FILE (write1.4gl)
MAIN

DEFINE                var_fd1               INT,
                      var_big               BIGINT,
                      var_char1             CHAR,
                      var_char2             CHAR(30),
                      var_date              DATE,
                      var_dt                datetime hour to fraction(1),
                      var_dec1              DEC,
                      var_dec2              DECIMAL(20,4),
                      var_dec3              DECIMAL(20),
                      var_double            DOUBLE PRECISION,
                      var_float             FLOAT,
                      var_int1              INT,
                      var_int2              INTEGER,
                      var_interval          interval year(8) To month,
                      var_mony              MONEY,
                      var_nchar             NCHAR(20),
                      var_num               NUMERIC,
                      var_nvchar            NVARCHAR(20),
                      var_real              REAL,
                      var_smfloat           SMALLFLOAT,
                      var_smint             SMALLINT,
                      var_vchar             VARCHAR(20)  


LET var_big = 4567
LET var_char1 = 'd'
LET var_char2 = "deepak"
LET var_date = "01/29/2010"

LET var_dt = DATETIME(08:56:34.1) HOUR TO FRACTION(1)
LET var_dec1 = 19345.56
LET var_dec2 = 29345.76
LET var_dec3 = 39345.88
LET var_double = 2345.678

LET var_float = 245.678
LET var_int1 = 234
LET var_int2 = 456
LET var_interval = INTERVAL(12345678-11) YEAR(8) TO MONTH
LET var_mony = 4567.89

LET var_nchar = "Manyata"
LET var_nvchar = "IBM"
LET var_num = 2567.89
LET var_real = 567.87
LET var_smfloat = 908.02
LET var_smint = 567
LET var_vchar = "Embassy"

OPEN FILE var_fd1 FROM "/tmp/file_deag1" OPTIONS
 (READ,WRITE, CREATE, FORMAT = "load", DELIMITER= "|")

WRITE TO fd1 USING var_big, var_char1, var_char2, var_date

WRITE TO fd1 USING var_dt, var_dec1, var_dec2, var_dec3, var_double

WRITE TO fd1 USING var_float, var_int1, var_int2, var_interval, var_mony

WRITE TO fd1 USING var_nchar, var_nvchar, var_num, var_real, var_smfloat

WRITE TO fd1 USING var_smint, var_vchar

CLOSE FILE var_fd1

END MAIN
Listing 3. Output of write1.4gl
% c4gl write1.4gl -o write1
% ./write1 

% cat "/tmp/file_deag1"
4567|d|deepak                       |01/29/2010
08:56:34.1|19345.56|29345.7600|39345.88|2345.68
245.68|234|456|12345678-11|$4567.89
Manyata             |IBM|2567.89|567.87|908.02
567|Embassy

Reading data from the file into program variables

The program in Listing 4 opens the file named file_deag1 in read, write mode. Information present in the file is read into a set of data types that can be used in I4GL. The file is closed at the end of the program.

Listing 4. Sample code for READ FILE (read1.4gl)
MAIN

DEFINE                var_fd1               INT,
                      var_big               BIGINT,
                      var_char1             CHAR,
                      var_char2             CHAR(30),
                      var_date              DATE,
                      var_dt                datetime hour to fraction(1),
                      var_dec1              DEC,
                      var_dec2              DECIMAL(20,4),
                      var_dec3              DECIMAL(20),
                      var_double            DOUBLE PRECISION,
                      var_float             FLOAT,
                      var_int1              INT,
                      var_int2              INTEGER,
                      var_interval          interval year(8) To month,
                      var_mony              MONEY,
                      var_nchar             NCHAR(20),
                      var_num               NUMERIC,
                      var_nvchar            NVARCHAR(20),
                      var_real              REAL,
                      var_smfloat           SMALLFLOAT,
                      var_smint             SMALLINT,
                      var_vchar             VARCHAR(20)  

OPEN FILE var_fd1 FROM "/tmp/file_deag1" OPTIONS 
 (READ,WRITE, CREATE, FORMAT = "load", DELIMITER= "|")

READ FROM fd1 INTO var_big, var_char1, var_char2, var_date

READ FROM fd1 INTO var_dt, var_dec1, var_dec2, var_dec3, var_double

READ FROM fd1 INTO var_float, var_int1, var_int2, var_interval, var_mony

READ FROM fd1 INTO var_nchar, var_nvchar, var_num, var_real, var_smfloat

READ FROM fd1 INTO var_smint, var_vchar

CLOSE FILE var_fd1

DISPLAY var_big, var_char1, var_char2, var_date

DISPLAY var_dt, var_dec1, var_dec2, var_dec3, var_double

DISPLAY var_float, var_int1, var_int2, var_interval, var_mony

DISPLAY var_nchar, var_nvchar, var_num, var_real, var_smfloat

DISPLAY var_smint, var_vchar

END MAIN
Listing 5. Output of read1.4gl 
% c4gl read1.4gl -o read1
% ./read1
4567|d|deepak                       |01/29/2010
08:56:34.1|19345.56|29345.7600|39345.88|2345.68
245.68|234|456|12345678-11|$4567.89
Manyata             |IBM|2567.89|567.87|908.02
567|Embassy

Seeking the data from the file

The program in Listing 6 opens the file named file_deag1 in read, write mode. The file pointer is repositioned based on the offset specified and LAST. The file is closed at the end of the program. The offset is stored in a program variable and then displayed. Listing 7 shows the output from the program.

Listing 6. Code for seek File (seek1.4gl)
MAIN 

DEFINE                      var_fd1                 INT,
                            var_len                 INT,
                            var_ret_len             INT

LET var_len = 10

OPEN FILE var_fd1 FROM "/tmp/file_deag1" OPTIONS 
 (READ,WRITE, CREATE,FORMAT = "load", DELIMITER= "|")

SEEK ON fd1 TO 0 FROM LAST INTO var_ret_len

SEEK ON fd1 TO var_len FROM LAST INTO var_ret_len

SEEK ON fd1 TO var_len

DISPLAY var_ret_len

END MAIN
Listing 7. Output of seek1.4gl 
% c4gl seek1.4gl -o seek1
% ./seek1
        202

Error handling with I4GL file I/O

Specifying a delimiter that does not match the file format

As described in Table 2, files with a format of csv must use a comma delimiter and files with a format of text must use a new line delimiter. The program in Listing 8 attempts to open a text format file using the @ character as the delimiter. Listing 9 shows the error that I4GL throws in this case.

Listing 8. Code for open2.4gl
MAIN

DEFINE    var_fd1     INT

OPEN FILE var_fd1 FROM "/tmp/file_deag1" OPTIONS
 ( WRITE, APPEND,  CREATE, FORMAT = "text", DELIMITER= "@")

CLOSE FILE var_fd1

END MAIN
Listing 9. Output of open2.4gl 
% c4gl open2.4gl -o open2
% ./open2

Program stopped at "open2.4gl", line number 6.
4GL run-time error number -4818.
Delimiter should be comma, when format is CSV. It should be a
newline when format is TEXT.

Reading incompatible data into program variables

The program in Listing 10 reads an incompatible date string from a file and attempts to store it in a Date data type. Listing 11 shows the error message that is displayed.

Listing 10. Code for read2.4gl
MAIN

DEFINE           var_fd1         INT,
                 Var_big         BIGINT
                 var_date        DATE,
                 var_char1       CHAR,
                 var_char2       CHAR(30)

OPEN FILE var_fd1 FROM "/tmp/file_deag1" OPTIONS
 (READ,WRITE, CREATE, FORMAT = "load", DELIMITER= "|")

READ FROM fd1 INTO var_big, var_char1, var_date

-- As of now Negative testing is done for the date type above.
-- And it is same for other data types, when incompatible data is
-- read into a data type.

CLOSE FILE var_fd1

DISPLAY var_big, var_char1, var_char2, var_date

END MAIN
Listing 11. Output of read2.4gl 
% cat  /tmp/file_deag1
4567|d|deepak                       |01/29/2010
08:56:34.1|19345.56|29345.7600|39345.88|2345.68
245.68|234|456|12345678-11|$4567.89
Manyata             |IBM|2567.89|567.87|908.02
567|Embassy 

% c4gl read2.4gl -o read2
% ./read2

Program stopped at "read2.4gl", line number 50.
4GL run-time error number -1205.
Invalid month in date

Using non-integer data types in offset fields in SEEK operation

The program in Listing 12 tries to use the float data type in the offset return field. Listing 13 shows the error message that is displayed.

Listing 12. Code for seek2.4gl
MAIN 

DEFINE                 var_fd1         INT,
                       var_len         INT,
                       var_ret_len     FLOAT

LET var_len = 10

OPEN FILE var_fd1 FROM "/tmp/file_vish1" OPTIONS
 ( READ,WRITE, CREATE,FORMAT = "load", DELIMITER= "|")

SEEK ON fd1 TO var_len FROM LAST INTO var_ret_len

DISPLAY var_ret_len

END MAIN
Listing 13. Output of seek2.4gl 
% c4gl seek2.4gl -o seek2
%  ./seek2

MAIN 

DEFINE                 var_fd1         INT,
                       var_len         INT,
                       var_ret_len     FLOAT

LET var_len = 10

OPEN FILE var_fd1 FROM "/tmp/file_vish1" OPTIONS 
 ( READ,WRITE, CREATE,FORMAT = "load", DELIMITER= "|")

SEEK ON fd1 TO var_len FROM LAST INTO var_ret_len

DISPLAY var_ret_len
| 
|      The variable ret_len is not of type INTEGER or SMALLINT.  It cannot be
| used to specify and/or store offset in the seek operation.
| See error number -4831.

END MAIN

Summary

This article provided an introduction to the Informix 4GL file I/O operations available with the 7.50.xC4 release. It described the syntax of each of the operations and showed examples of how to use each operation. Example program listings show how the I/O operations can be used within an application. Finally, the article describes some of the common errors you may encounter when using the file I/O operations and how these errors are identified and handled by I4GL. File I/O support in IBM Informix 4GL provides flexibility and ease-of-use to users who want to develop I4GL applications that use file I/O operations.

Downloadable resources

Related topics

  • Use the IBM Informix Dynamic Server 11 Information Center to learn more about how to use the Informix family of products.
  • The 4GL topic in the IDS 11 Information center contains the 4GL 7.5 manuals.
  • Check out Informix Unleashed by Glenn Miller, Jim Prajesh, Jose Fortuny, and John McNally. Using a hands-on approach, this guide serves as a high-level tutorial for users who are new to Informix. It is also a helpful reference for those who know the product but need additional tips, tricks, and workarounds.
  • Use the Informix area on developerWorks to get the resources you need to advance your Informix skills.
  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.
static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=500351
ArticleTitle=Get started with direct file I/O support in IBM Informix 4GL
publish-date=07152010