Get started with direct file I/O support in IBM Informix 4GL
Easy access to files from your database application
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 holder | Description |
---|---|
int_var | An integer variable that contains the file descriptor for the file to be opened. |
string or string_var | A quoted string or a string variable that contains the pathname of the file to be opened. Length is restricted to 255 bytes. |
option_comma_list | A 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
Option | Description |
---|---|
READ | Open the file in read mode. |
WRITE | Open the file in write mode. |
APPEND | Open the file in append mode. Before each write, the file offset is positioned at the end of the file. |
CREATE | If the file does not exist, it is created. |
EXCLUSIVE | Used with the CREATE option.
If the file already exists, the operation returns an error.
|
FORMAT | Specifies 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. |
DELIMITER | Specifies 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 holder | Description |
---|---|
int_var | An 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 holder | Description |
---|---|
int_var | An integer variable that contains the file descriptor for the file to be opened. |
var_list | List 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 holder | Description |
---|---|
int_var | An integer variable that contains the file descriptor for the file to be written to. |
var_list | List 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 holder | Description |
---|---|
int_var_1 | An integer variable that contains the file descriptor for the open file that is to have its offset repositioned. |
int_var_2 | An integer value or an integer variable that specifies the file offset to be used for repositioning. |
int_var_3 | An 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.