DTWF_SEARCH

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

Purpose

Searches a text file for a string, returning the results into a Net.Data table.

Format

@DTWF_SEARCH(filename, transform, delimiter, table, searchFor, retry, linesToSearch, startline)

@DTWF_SEARCH(filename, transform, delimiter, table, searchFor, retry, linesToSearch)

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

@DTWF_SEARCH(filename, transform, delimiter, table, searchFor)

Parameters

Table 184. DTWF_SEARCH Parameters
Data Type Parameter Use Description
string filename INOUT The name of the file to search. On successful completion of the call, this parameter returns the fully qualified file name.
string transform IN The format of the file:
  • ASCIITEXT - writes the table to the file with a new-line character between column values and ignores the delimiter parameter.
  • DELIMITED - writes the table to the file with the delimiter specified in the delimiter parameter.
A new-line character in a file indicates the end of a row of a Net.Data macro table for ASCIITEXT and DELIMITED transforms.
string delimiter IN A character string to indicate the ends of values. This parameter is case sensitive. Ignored if transform is ASCIITEXT.
table table OUT The table variable into which the search results are placed. Three columns are returned:
  • The line in which the match was found
  • The field in which the match was found (for ASCIITEXT transform, this is always 1)
  • The value of the field that contained the search string

For non-OS/400 users: The maximum length of a row in an FFI table is 16383 characters. This limit includes a null character for each column in the Net.Data macro table.

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 linesToSearch INOUT The number of lines in the file to search. A value of 0 means all the lines in the file are searched or until the table is full; this is the default. Upon successful completion, the number of rows in the resulting table is returned by this parameter.
integer startline IN The line in the file to start searching from. The default is 1, which begins the search at the first record.

Return Codes

Table 185. DTWF_SEARCH Return Codes
Return Code Explanation
-1001 The server could not process a Net.Data request to allocate memory.
1001 An input parameter contained a NULL value.
1002 An input parameter contained a string value which consisted of the null-terminating character.
1003 An incorrect number of parameters were passed on a function call.
1004 A parameter passed on a function call, required to be a Net.Data macro table variable, was of a different variable type.
1005 A parameter passed on a function call, required to be a string variable, was of a different variable type.
1006 A literal string was passed on a function call for a parameter which was required to be an output parameter.
1007 A parameter contains a value which is not valid.
1010 Data was written to the table until it was full, and the remainder of the data was discarded.
2000 A flat file interface built-in function could not find the specified file.
2003 A flat file interface built-in function could not read a row of data into a table variable because the number of bytes in the row exceeded the maximum supported number of bytes.
2004 A flat file interface built-in function was attempting to find a file, but encountered a path in the FFI_PATH configuration file variable that was longer than the maximum supported number of bytes, which is 4095.
2005 A call to a system function failed.
2006 A flat file interface built-in function could not access the specified file because it was in use by this or another process and could not be shared in the specified mode.

Usage Notes

  1. The table that is returned for DTWF_SEARCH has three columns. The first two columns contain the row and the column number where the match is found; the last column contains the column value that contains the characters that are specified in the SearchFor parameter. For example, if the fourth row of the file contains matching characters in column three, the returned table has a row with the number 4 in the first column to indicate the row of the file that it came from; it has a number 3 in the second column to indicate which column of the file contains a match; and it has the complete column value in the third column.
  2. The SearchFor parameter cannot include the contents of the delimiter parameter.

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)


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