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 | Mobile Access |
|---|---|---|---|---|---|---|
| GetLine | File | Synchronous | Supported | Supported | Supported | Not 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. |