GetLine

Gets a specified line or search string from a text file and then stores the line in a String tag.

Function	Group	Execution	Windows	Embedded	Thin Client
GetLine	File	Synchronous	Supported	Supported	Supported

Syntax

GetLine( strFileName, Search, "tagStore", optNumCase, "optOveflowTag", optRunFromServer )

strFileName

A string value enclosed in quotes, or the name of a String tag that contains the value, specifying the name of the file to be searched. The name can be a fully qualified file path (e.g., C:\File.txt) or a simple file name (e.g., File.txt). In the latter case, the project will search for the file in the following paths:

Local Station: The project will search for the file in the project folder and Web sub-folder.
Thin Client: If the parameter optRunFromServer is set to 0, the path where the file will be searched is undetermined. If is set to 1, it will search for the file in the URL typed in the Browser, and if the file is not found, in the Backup URL.

Note: For Web-enabled projects, we recommend setting the optRunFromServer parameter to 1 and placing your files in the project's Web sub-folder.

Search

There are two options for this parameter, based on the data type of the value you give it:

If it is a string value or tag, then the function will search the text file for the first occurance of the string and then copy the entire line that contains the occurance to the tag specified by tagStore. Additional occurances are counted (see Returned Values below) but not copied.
If it is a numeric value or tag, then the function will go to that line number in the text file and then copy the line to the tag specified by tagStore. The first line of the file is line 0.

tagStore

Name of the String tag receiving the contents of the line pointed to by the function. This name must be enclosed in quotes; if it isn't, then the function will use the contents of the tag rather than its name.

optNumCase

Optional numeric tag specifying whether the search is case-sensitive.

0: Not case-sensitive
1: Case-sensitive

optOverflowTag

Optional numeric tag receiving the result of overflow verification.

0: OK
1: Overflow

optRunFromServer

Optional numeric tag ignored when the function is called on local stations. On Thin Clients, this parameter indicates the following:

0: Retrieves the file from the Thin Client machine (do not use this value with non-fully qualified names)
1: Retrieves the file from the Web Server. If the file name is not a URL, then the function will ignore the project path and search for the file in the URL where the screen files are located.

Returned value

If the function is successfully executed, then it returns the total number lines in which the search string was found. Otherwise, the function returns one of the following errors:

0	String was not found in the target file
-1	File not found
-2	Invalid `strFileName` parameter
-3	Invalid `strSeqChar` parameter
-4	Invalid `strStoreTag` parameter
-5	Invalid `optNumCase` parameter
-6	Invalid `optNumOverflowTag` parameter
-7	Invalid number of parameters
-8	Invalid line number

Notes

Note: This function only supports ASCII and UTF-16LE text encoding. (UTF-16LE is the Unicode implementation that is natively supported by Windows.) If you use this function to get text from a UTF-8 or UTF-16BE encoded file, then you may see some invalid characters.

Important: This function can only read up to 509 characters in a single function call. If a line has more than 509 characters (i.e., 507 alphanumeric + CR + LF), then the function will read it as two or more lines. This will also increase the effective line count for the purposes of the Search parameter. So, for line 100 that has 1024 characters (i.e., 1022 alphanumeric + CR + LF), the function must be called three times:

GetLine( "C:\FileName.txt", 100, "strTagStore[1]")  //Reads the first 509 characters
GetLine( "C:\FileName.txt", 101, "strTagStore[2]")  //Reads the second 509 characters
GetLine( "C:\FileName.txt", 102, "strTagStore[3]")  //Reads the last 6 characters

After this, line 101 of the source file is actually counted by the function as line 103. Therefore, to avoid unnecessarily complicated line counting, you should make sure the source file is limited to 509 characters per line.

Examples

Tag Name	Expression
Tag	`GetLine( "C:\TechRef v61.doc", "Studio version 6.1", "ReturnedLine" )` // Gets the first occurance of "Studio version 6.1".
Tag	`GetLine( "C:\Readme.txt", 1, "ReturnedLine", 0, "Overflow" )` // Gets the second line of the file.