Net.Data Reference Guide

Flat File Interface

The flat file interface is a language environment that comes preconfigured for DB2 on most platforms. You can open, read, and manipulate data from flat file sources (plain text), as well as store data in flat files using the functions in the Net.Data macro.

Flat File Interface Delimiters

In order to improve performance, you can keep the Net.Data tablular output from a series of SQL requests in a flat file. You can retrieve the flat file in subsequent requests, instead of re-issuing the SQL requests.

Net.Data flat files can be created from Net.Data tables and Net.Data tables can be built from flat files. In order to make the transformations between the tables and flat files, you must define the mapping between columns in a table and records in a flat file. Delimiters provide a method for defining how portions of records in a flat file can be be separated and mapped to columns in a table, and how columns in a table can be mapped to records in a flat file.

There are two types of delimiters:

New line character (ASCIITEXT): Use this transformation when your table is made up of one column. Net.Data maps each record in the corresponding flat file onto a single row in the table. In this case, the regular new line character which separates records in the flat file is the only delimiter used.
New line character and delimiter string (DELIMITED): Use this transformation when your table is made up of multiple columns. When Net.Data creates a flat file record from a row in a table, it places the delimiter string as a separator between the items. When Net.Data rebuilds a table from a flat file, it uses the delimiter string to determine how much of each row to place in a column of the table. In this case, the regular new line character separates the records in the flat file that correspond to rows in the table, and the delimiter string separates the items within a single record.

You can use the DTWF_SEARCH function to retrieve certain records held in a flat file that was built from a Net.Data table. Specify a string in DTWF_SEARCH to return all the records that contain the string in the flat file as rows in a Net.Data table.

DTWF_APPEND

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Writes the contents of a table variable to the end of a file.

Syntax

@DTWF_APPEND(filename, transform, delimiter, table, retry, rows)

Parameters

Table 51. DTWF_APPEND Parameters

Data Type Parameter Use Description
string filename IN The name of the file to which the table variable's contents are added.
string transform IN The format of the file:

ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter.
DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.

string delimiter IN A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string table IN The table variable from which the records are read.
integer retry IN The number of times to retry if the file cannot be appended to immediately. The default is not to retry.
integer rows IN The maximum number of rows from table to append. The default is to append all the rows. Specifying 0 appends all rows.

Data Type	Parameter	Use	Description
string	`filename`	IN	The name of the file to which the table variable's contents are added.
string	`transform`	IN	The format of the file: ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter. DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.
string	`delimiter`	IN	A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string	`table`	IN	The table variable from which the records are read.
integer	`retry`	IN	The number of times to retry if the file cannot be appended to immediately. The default is not to retry.
integer	`rows`	IN	The maximum number of rows from table to append. The default is to append all the rows. Specifying 0 appends all rows.

Examples

Example 1:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
%}
@DTWF_APPEND(myFile, "DELIMITED", " ;", myTable)

Example 2:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
%}
@DTWF_APPEND(myFile, "ASCIITEXT", " ;", myTable)

Example 3:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
%}
@DTWF_APPEND(myFile, "ASCIITEXT", " ;", myTable, "0", "10")

DTWF_CLOSE

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Closes a file opened by DTWF_OPEN.

Syntax

@DTWF_CLOSE(filename, retry)

Parameters

Table 52. DTWF_CLOSE Parameters

Data Type Parameter Use Description
string filename IN The name of the file to close. The full path name of the file is returned when it is closed.
integer retry IN The number of times to retry if the file cannot be closed immediately. The default is not to retry.

Data Type	Parameter	Use	Description
string	`filename`	IN	The name of the file to close. The full path name of the file is returned when it is closed.
integer	`retry`	IN	The number of times to retry if the file cannot be closed immediately. The default is not to retry.

Examples

Example 1:

@DTWF_CLOSE(myFile, 5)

DTWF_DELETE

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Deletes records from a file. (Does not delete empty files.)

Syntax

@DTWF_DELETE(filename, transform, delimiter, retry, rows, startrow)

Parameters

Table 53. DTW_DELETE Parameters

Data Type Parameter Use Description
string filename IN The name of the file whose records are to be deleted.
string transform IN The format of the file:

ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter.
DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.

string delimiter IN A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
integer retry IN The number of times to retry if the file cannot be deleted immediately. The default is not to retry.
integer rows IN The maximum number of rows to delete. The default is to delete all the rows. Specifying 0 deletes all rows.
integer startrow IN The row number from which to begin deleting. A value of 1 means to begin deleting at the first row. If this value is greater than the number of rows in the file, the value is changed to the last record and returned as an error. The default is to start at 1.

Data Type	Parameter	Use	Description
string	`filename`	IN	The name of the file whose records are to be deleted.
string	`transform`	IN	The format of the file: ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter. DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.
string	`delimiter`	IN	A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
integer	`retry`	IN	The number of times to retry if the file cannot be deleted immediately. The default is not to retry.
integer	`rows`	IN	The maximum number of rows to delete. The default is to delete all the rows. Specifying 0 deletes all rows.
integer	`startrow`	IN	The row number from which to begin deleting. A value of 1 means to begin deleting at the first row. If this value is greater than the number of rows in the file, the value is changed to the last record and returned as an error. The default is to start at 1.

Examples

Example 1:

%DEFINE {
   myFile = "c:/private/myfile"
   myTable = %TABLE
   myWait = "5000"
   myRows = "2"
%}
@DTWF_DELETE(myFile, "Delimited", "|", myWait, myRows)

Example 2:

%DEFINE {
   myFile = "c:/private/myfile"
   myTable = %TABLE
   myStart = "1"
   myRows = "2"
%}
@DTWF_DELETE(myFile, "Asciitext", "|", "0", myRows, myStart)

DTWF_INSERT

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Inserts records into a file.

Syntax

@DTWF_INSERT(filename, transform, delimiter, table, retry, rows, startrow)

Parameters

Table 54. DTWF_INSERT Parameters

Data Type Parameter Use Description
string filename INOUT The name of the file to which records are inserted. The full path name of the file is returned.
string transform IN The format of the file:

ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter.
DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.

string delimiter IN A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string table IN The table variable from which records are inserted into table.
integer retry IN The number of times to retry if the file cannot be written to immediately. The default is not to retry.
integer rows IN The maximum number of rows to insert from table. The default is to insert all the rows. A value of 0 inserts all the rows.
integer startrow IN The row number from which to begin inserting. Specifying 1 means to begin inserting at the first row. If this value is greater than the number of rows in the file, the value is changed to the last record and returned as an error. The default is to start at 1.

Data Type	Parameter	Use	Description
string	`filename`	INOUT	The name of the file to which records are inserted. The full path name of the file is returned.
string	`transform`	IN	The format of the file: ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter. DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.
string	`delimiter`	IN	A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string	`table`	IN	The table variable from which records are inserted into table.
integer	`retry`	IN	The number of times to retry if the file cannot be written to immediately. The default is not to retry.
integer	`rows`	IN	The maximum number of rows to insert from table. The default is to insert all the rows. A value of 0 inserts all the rows.
integer	`startrow`	IN	The row number from which to begin inserting. Specifying 1 means to begin inserting at the first row. If this value is greater than the number of rows in the file, the value is changed to the last record and returned as an error. The default is to start at 1.

Examples

Example 1:

%DEFINE {
   myFile = "c:/private/myfile"
   myTable = %TABLE
   myWait = "3000"
%}
@DTWF_INSERT(myFile, "Delimited", "|", myTable, myWait)

Example 2:

%DEFINE {
   myFile = "c:/private/myfile"
   myTable = %TABLE
   myStart = "1"
   myRows = "2"
%}
@DTWF_INSERT(myFile, "Asciitext", "|", myTable, "0", myRows, myStart)

DTWF_OPEN

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Opens a file. The file is left open until it is closed with DTWF_CLOSE to let functions such as DTWF_READ and DTWF_WRITE open the file automatically without calling DTWF_OPEN.

Syntax

@DTWF_OPEN(filename, mode, retry)

Parameters

Table 55. DTWF_OPEN Parameters

Data Type Parameter Use Description
string filename INOUT The name of the file to open. The path and name of the file is returned.
string mode IN The type of access requested:

r - open an existing file for reading.
w-create a file for writing. (Destroys existing file of same name, if it exists.)
a - open a file for appending. Net.Data creates the file if it is not found.
r+ - open an existing file for reading and writing.
w+ - create a file for reading and writing. (Destroys existing file of same name, if it exists.)
a+ - open a file in append mode for reading or appending. Net.Data creates the file if it is not found.

integer retry IN The number of times to retry if the file cannot be opened immediately. The default is not to retry.

Data Type	Parameter	Use	Description
string	`filename`	INOUT	The name of the file to open. The path and name of the file is returned.
string	`mode`	IN	The type of access requested: r - open an existing file for reading. w-create a file for writing. (Destroys existing file of same name, if it exists.) a - open a file for appending. Net.Data creates the file if it is not found. r+ - open an existing file for reading and writing. w+ - create a file for reading and writing. (Destroys existing file of same name, if it exists.) a+ - open a file in append mode for reading or appending. Net.Data creates the file if it is not found.
integer	`retry`	IN	The number of times to retry if the file cannot be opened immediately. The default is not to retry.

Examples

Example 1:

%DEFINE {
  myFile = "c:/private/myfile"
  myMode = "r+"
%}
@DTWF_OPEN(myFile, myMode, "1000")

DTWF_READ

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Reads records from a file into a table variable.

Syntax

@DTWF_READ(filename, transform, delimiter, table, retry, rows, startrow, columns)

Parameters

Table 56. DTWF_READ Parameters

Data Type Parameter Use Description
string filename INOUT The name of the file whose records are read into a table variable. The path and name of the file is returned.
string transform IN The format of the file:

ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter.
DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.

string delimiter IN A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string table IN The table variable into which the file records are read.
integer retry IN The number of times to retry if the file cannot be read immediately. The default is not to retry.
integer rows IN The maximum number of file records to read into table. The default is to read all the records, or until the table is full. A 0 means to read until the end of the file. The number of rows in the resulting table is returned.
integer startrow IN The record in the file from which to start reading. The default is to start reading at the first record.
integer columns OUT Returns the number of columns in the table.

Data Type	Parameter	Use	Description
string	`filename`	INOUT	The name of the file whose records are read into a table variable. The path and name of the file is returned.
string	`transform`	IN	The format of the file: ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter. DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.
string	`delimiter`	IN	A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string	`table`	IN	The table variable into which the file records are read.
integer	`retry`	IN	The number of times to retry if the file cannot be read immediately. The default is not to retry.
integer	`rows`	IN	The maximum number of file records to read into table. The default is to read all the records, or until the table is full. A 0 means to read until the end of the file. The number of rows in the resulting table is returned.
integer	`startrow`	IN	The record in the file from which to start reading. The default is to start reading at the first record.
integer	`columns`	OUT	Returns the number of columns in the table.

Examples

Example 1:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
  myWait = "1000"
%}
@DTWF_READ(myFile, "DELIMITED", ";", myTable, myWait)

Example 2:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
  myWait = "0"
  myRows = "0"
  myStartrow = "1"
  myColumns = ""
%}
@DTWF_READ(myFile, "DELIMITED", ";", myTable, myWait, myRows,
             myStartrow, myColumns)

Example 3:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
%}
@DTWF_READ(myFile, "ASCIITEXT", ";", myTable, myColumns)
@DTW_TB_TABLE(myTable,"BORDER","")

DTWF_REMOVE

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Deletes an entire file.

Syntax

@DTWF_REMOVE(filename, retry)

Parameters

Table 57. DTW_REMOVE Parameters

Data Type Parameter Use Description
string filename INOUT The name of the file to delete. The path and name of the file is returned.
integer retry IN The number of times to retry if the file cannot be deleted immediately. The default is not to retry.

Data Type	Parameter	Use	Description
string	`filename`	INOUT	The name of the file to delete. The path and name of the file is returned.
integer	`retry`	IN	The number of times to retry if the file cannot be deleted immediately. The default is not to retry.

Examples

Example 1:

%DEFINE myFile = "c:/private/myfile"
@DTWF_REMOVE(myFile)

Example 2:

%DEFINE {
  myFile = "c:/private/myfile"
  myWait = "2000"
%}
@DTWF_REMOVE(myFile, myWait)

DTWF_SEARCH

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Returns result of a string search to a table variable.

Syntax

@DTWF_SEARCH(filename, transform, delimiter, table, searchFor, retry, rows, startrow)

Parameters

Table 58. DTWF_SEARCH Parameters

Data Type Parameter Use Description
string filename INOUT The name of the file to search. The path and name of the file found is returned.
string transform IN The format of the file:

ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter.
DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.

string delimiter IN A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string table IN The table variable into which the search results are placed. 3 columns are returned if transform is DELIMITED:

The row in which the match was found.
The column in which the match was found.
The matching column from the file.

string searchFor IN The string of characters to search for.
integer retry IN The number of times to retry if the file cannot be searched immediately. The default is not to retry.
integer rows IN The maximum number of rows to read into table. The default is to read all the rows or until table is full. Specifying 0 reads to the end of the file. The number of rows in the resulting table is returned by this parameter.
integer startrow IN The record in the file to start searching from. The default is 1, which begins the search at the first record.

Data Type	Parameter	Use	Description
string	`filename`	INOUT	The name of the file to search. The path and name of the file found is returned.
string	`transform`	IN	The format of the file: ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter. DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.
string	`delimiter`	IN	A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string	`table`	IN	The table variable into which the search results are placed. 3 columns are returned if transform is DELIMITED: The row in which the match was found. The column in which the match was found. The matching column from the file.
string	`searchFor`	IN	The string of characters to search for.
integer	`retry`	IN	The number of times to retry if the file cannot be searched immediately. The default is not to retry.
integer	`rows`	IN	The maximum number of rows to read into table. The default is to read all the rows or until table is full. Specifying 0 reads to the end of the file. The number of rows in the resulting table is returned by this parameter.
integer	`startrow`	IN	The record in the file to start searching from. The default is 1, which begins the search at the first record.

Examples

Example 1:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
  myWait = "1000"
  mySearch = "0123456789abcdef"
@DTWF_SEARCH(myFile, "DELIMITED", ";",
               myTable, mySearch, myWait)

Example 2:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
  mySearch = "answer:"
  myWait = "0"
  myRows = "0"
  myStartrow = "1"
%}
@DTWF_SEARCH(myFile, "DELIMITED", ";", myTable,
               mySearch, myWait, myRows, myStartrow)

DTWF_UPDATE

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Updates records of a file from a table variable.

Syntax

@DTWF_UPDATE(filename, transform, delimiter, table, retry, rows, startrow)

Parameters

Table 59. DTWF_UPDATE Parameters

Data Type Parameter Use Description
string filename IN The name of the file whose records are updated from a table variable.
string transform IN The format of the file:

ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter.
DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.

string delimiter IN A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string table IN The table variable from which the file records are updated.
integer retry IN The number of times to retry if the file cannot be written to immediately. The default is not to retry.
integer rows IN The maximum number of records to be updated from table. The default is to update all the records. 0 means to update all rows in the file.
integer startrow IN The first file record to update. The default is 1, which means to start updating at the beginning of the file. If the value is greater than the number of records in a file, the value is changed to indicate the number of the last record in the file and an error is returned.

Data Type	Parameter	Use	Description
string	`filename`	IN	The name of the file whose records are updated from a table variable.
string	`transform`	IN	The format of the file: ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter. DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.
string	`delimiter`	IN	A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string	`table`	IN	The table variable from which the file records are updated.
integer	`retry`	IN	The number of times to retry if the file cannot be written to immediately. The default is not to retry.
integer	`rows`	IN	The maximum number of records to be updated from table. The default is to update all the records. 0 means to update all rows in the file.
integer	`startrow`	IN	The first file record to update. The default is 1, which means to start updating at the beginning of the file. If the value is greater than the number of records in a file, the value is changed to indicate the number of the last record in the file and an error is returned.

Examples

Example 1:

%DEFINE {
   myFile = "c:/private/myfile"
   myTable = %TABLE
   myWait = "1500"
   myRows = "2"
%}
@DTWF_UPDATE(myFile, "Delimited", "|", myTable, myWait, myRows)

Example 2:

%DEFINE {
   myFile = "c:/private/myfile"
   myTable = %TABLE
   myStart = "1"
   myRows = "2"
%}
@DTWF_UPDATE(myFile, "Asciitext", "|", myTable, "0", myRows, myStart)

DTWF_WRITE

Purpose

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X
X X X

Writes the contents of a table variable to a file.

Syntax

@DTWF_WRITE(filename, transform, delimiter, table, retry, rows, startrow)

Parameters

Table 60. DTWF_WRITE Parameters

Data Type Parameter Use Description
string filename IN The name of the file the records of the table variable are written to. The path and name of the file is returned.
string transform IN The format of the file:

ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter.
DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.

string delimiter IN A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string table IN The table variable used to export rows to the file.
integer retry IN The number of times to retry if the file cannot be written to immediately. The default is to not retry.
integer rows IN The maximum number of file records to write. The default is to write the entire table. 0 means to write all records to the end of the file.
integer startrow IN The record number to start writing to in the file. The default is 1, which means to start at the first record. If a value beyond the end of the file is specified, the last row of the file is returned with an error.

Data Type	Parameter	Use	Description
string	`filename`	IN	The name of the file the records of the table variable are written to. The path and name of the file is returned.
string	`transform`	IN	The format of the file: ASCIITEXT - write the table to the file with a newline character between column values and ignore the delimiter parameter. DELIMITED - write the table to the file with the delimiter specified in the delimiter parameter.
string	`delimiter`	IN	A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
string	`table`	IN	The table variable used to export rows to the file.
integer	`retry`	IN	The number of times to retry if the file cannot be written to immediately. The default is to not retry.
integer	`rows`	IN	The maximum number of file records to write. The default is to write the entire table. 0 means to write all records to the end of the file.
integer	`startrow`	IN	The record number to start writing to in the file. The default is 1, which means to start at the first record. If a value beyond the end of the file is specified, the last row of the file is returned with an error.

Examples

Example 1:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
%}
@DTWF_WRITE(myFile, "DELIMITED", ";", myTable)

Example 2:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
%}
@DTWF_WRITE(myFile, "ASCIITEXT", ";", myTable, "5000")

Example 3:

%DEFINE {
  myFile = "c:/private/myfile"
  myTable = %TABLE
%}
@DTWF_WRITE(myFile, "ASCIITEXT", ";", myTable, "5000", "10", "50")

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]