Procedural-File I/O Related Actions
START BATCH POST and END BATCH POST
The Actions START BATCH POST and END BATCH POST are procedural actions which can only be used within User Defined Functions. These Actions indicate that all the Data Updation Actions falling between the Actions START BATCH POST and END BATCH POST must be updated to the database in Batches. Instead of the data being directly updated to the database, the data is updated to a temporary file, and once the Batch Size limit is reached, the entire data is flushed from the temporary file into the database.
A Batch is a set of objects, wherein the batch size can be specified by the TDL Programmer as an optional parameter to the Action START BATCH POST. In the absence of this parameter, the default size of the batch is considered as 100 Objects. On encountering the batch size limit, the temporary file posts/flushes the data into the Tally database. On completion of the posting of the previous batch of data, the subsequent batch posting iteration takes place, and this cycle continues till the entire data is updated to the database. The bigger the batch size, the lesser the total number of batches, and the better the performance. The operation will be accomplished faster if the Batch Size specified is optimal. A very high Batch Size, beyond a particular point, may also deteriorate the performance. Hence, striking the right balance and specifying the optimal batch size is important to achieve the best performance.
Syntax
START BATCH POST [:<Batch Size>]
NEW OBJECT: <Object Type>: <Object Name> : <Forced Update Flag>
Action 1
Action 2
:
:
Action n
SAVE TARGET
END BATCH POST
Where,
<Batch Size> is the size of each batch.
Note: In the absence of Action END BATCH POST , the End of the User Defined Function is assumed as the end of Batch Posting. However, it is recommended to specify END BATCH POST , especially in presence of nested loops/ large volume of data.
Example
[Function : Create Ledgers]
Parameter : pNumberofLedgers : Number : 1000
000 : START BATCH POST : 500
010 : For Range : i : Number: 1: ##pNumberofLedgers
020 : New Object : Ledger
030 : Set Value : Name : “Customer ” + $$String:##i
040 : Set Value : Parent : “Sundry Debtors”
050 : Create Target
060 : End For
070 : END BATCH POST
In this example, when the Function “Create Ledgers” is invoked, 1000 Ledgers, ranging from “Customer 1” to “Customer 1000”, are created under the group ‘Sundry Debtors’. If the Batch Posting feature was not used, the database files would get locked and released for updating every object, and this would continue till all the Objects were updated. Thus, 1000 cycles would take place, affecting the performance adversely. However, with Batch Posting approach, these Objects are updated in 2 batches of 500 Objects each, i.e., the database is locked and released only twice, thus improving the performance vastly. The impact of this enhancement can be observed during updation of data of large volume. For instance, the following table shows the statistics of time taken for creating 1000 ledgers using the given code, but with different Batch Size:
|
Particulars |
Batch Size |
Approx. time taken |
|
Without Actions START BATCH POST and END BATCH POST |
NA |
3 Minutes 29 Seconds |
|
With Actions START BATCH POST and END BATCH POST |
100 |
4 Seconds |
|
500 |
2 Seconds |
|
|
1000 |
1 Second |
Table 1. Batch Posting Statistics
As seen in the table, with the usage of the Actions START BATCH POST and END BATCH POST, the time taken reduces significantly. Also, it is noticed that with increase in the Batch Size, the performance keeps improving. The operation will be accomplished faster if the specified Batch Size is equal to the total number of Objects being updated, i.e., in this case, specifying the Batch Size as 1000 will give optimal performance as 1000 objects will be posted to the database at a time.
Limitation
Greater the Batch Size, better the performance of data updation. However, the database files are locked from the beginning till the end of the write operation of each Batch. This results in unavailability of the Database for data updation from other sources executing parallelly, like data entry in a Multi-User Environment, Data Synchronization, etc. Thus, a higher value of Batch Size will improve the performance, but will slow down the simultaneous updation of Data. Hence, determining the Optimal Batch Size is necessary to strike the right balance for getting the best performance. A very high Batch Size, beyond a particular point, may deteriorate the performance.
Points to remember
- ● Actions START BATCH POST and END BATCH POST are not be used in a nested manner. If used so, only the first instance is considered, while the remaining ones are ignored.
- ● A Batch can only be ended or closed in a Function where it is initiated. If the user misses the closing part, the System will END the batch implicitly.
- ● One must backup the data prior to using the Batch Posting Feature, as incorrect usage of the same may lead to corruption/loss of data.
- ● For Import of Data also, we have a parameter similar to Batch Size, i.e., Import Batch Size, which can be used to improve the performance while Importing Data. This parameter can be specified in Tally.INI, in the absence of which, it is set to 100 by default. Setting this parameter to a higher value will decrease the time taken for Import, but will increase the wait time for other simultaneous data updation operations. Setting it to -1 will disable the Batch Posting feature for Import of Data, which means that the Data Import would consume a longer time, as every Object would need to be updated to the database individually.
Format Excel Sheet
Action Format Excel Sheet is used to set the cell properties of Excel sheet. It accepts two parameters.
Syntax
Format Excel Sheet : <PropertyName> : <PropertyParms>
where,
< PropertyName > is a system keyword for an Excel cell property, viz.,ColumnWidth or CellTextWrap.
< PropertyParms > is a list of required parameters for the specified PropertyName and the number of parameters vary based on the PropertyName.
Example
[Function: FileIOExcel]
Variable : InputFile : String : “D:SampExcel.xls”
010 : Open File: ##InputFile : Excel : Write
020 : Format Excel Sheet: CellTextWrap : 5 : 6 : Yes
030 : Format Excel Sheet: ColumnWidth: 1 : 30
040 : Close Target File
In the above example, CellTextWrap is the PropertyName and “5: 6: Yes” is the parameter required for the CellTextWrap property.
Supported Properties
ColumnWidth
Syntax
ColumnWidth: <ColumnNumber> : <Width>
where,
< ColumnNumber > is used to specify the column number whose width is to be modified.
< Width > is the number used to set the new width of the column. Unit of measurement used for this parameter is Points.
CellTextWrap
Syntax
CellTextWrap:<RowNumber>:<ColumnNumber>[:<Enablewrapping>]
where,
< RowNumber > is used to specify the row number of the cell.
< ColumnNumber > is used to specify the column number of the cell.
< Enablewrapping > is an optional parameter which specifies whether to wrap the text or not. The default value of this parameter is Yes.
An expression can also be specified in any of the parameters for the action.
OPEN FILE
It is used to open a text/excel file for read/write operations. The file can reside in Hard Disk, in the main memory or on FTP/HTTP site. Also, it is used to open a file for read/write operations.
If no parameters are used, then a memory buffer will be created, which will act as a file. This file will be in both read/wrItemode and will act as both the source and the target context. Based on the mode specified (read/write), the file automatically becomes the source file or the target file, respectively.
Syntax
OPEN FILE [:<File Name> [:<File Format> [:<Open Mode> [:<Encoding>]]]]
Where,
<File Name> can be any expression which evaluates to a regular disk file name like C:\Output.txt, or to an HTTP/FTP site like “ftp://ftp.tallysolutions.com/Output.txt”
<File Format> can be Text or Excel. By default, ‘Text’ mode will be considered, if not specified. Also, during the opening of an existing file, if the mode does not match, the Action will fail.
<Open Mode> can be Read / Write. By default, it is Read. If a file is opened for ‘Read’ purpose, then it must exist. If ‘Write’ mode is specified, and the file exists, it will be opened for updating. If the file does not exist, a new file is created. If the file is opened in ‘Write’ mode, it is possible to read from the file as well.
<Encoding> can be ASCII or Unicode. If not specified, ‘Unicode’ is considered as the default value for ‘Write’ Mode. In ‘Read’ mode, this parameter will be ignored and considered, based on the encoding of the file being read.
Example: 1
10 : OPEN FILE : “Output.txt” : Text : Write : ASCII
A Text File ‘Output.text’ is opened in ‘Write’ mode under the Tally application Folder, and if it already exists, the same will be opened for appending purpose.
Example: 2
10 : OPEN FILE : “http://www.tallysolutions.com/Output.txt” : Text
A Text File ‘Output.text’ is opened in ‘Write’ mode at the HTTP URL specified. If the file already exists, the same will be opened for appending purpose.
Example: 3
10 : OPEN FILE : “C:\Output.xls” : Excel : Read
An Excel File ‘Output.xls’ is opened in ‘Read’ mode under C drive, and if the file does not exist, the Action will fail.
Please refer to the functions like $$MakeFTPName and $$MakeHTTPName for constructing the FTP and HTTP URLs using the various parameters like server name, username, password, etc. Refer to Tally.Developer 9 Function Browser for help on usage.
CLOSE FILE and CLOSE TARGET FILE
A file which is opened for Read/Write operation needs to be closed, once all the read/write operations are completed. However, if the files are not closed explicitly by the programmer, these are closed by default when the function is returned. But, it is always recommended to close the file after the operations are completed.
Files which are opened in the current function can only be closed by it. If a function inherits the file contexts from the caller function, then it cannot close these files; however, it can open its own instances of the files. In such cases, the caller context files will not be accessible.
CLOSE FILE
This action is used to close an opened source file.
Syntax
CLOSE FILE
Example
10 : OPEN FILE : “Output.xls” : Excel : Read
|
|
30 : CLOSE FILE
In this example, the Excel file ‘Output.xls’, which is opened for reading purpose, is closed.
CLOSE TARGET FILE
This action is used to close an opened target file.
Syntax
CLOSE TARGET FILE
Example
10 : OPEN FILE : “Output.txt” : Text : Write
|
|
|
30 : CLOSE TARGET FILE
In this example, the text file ‘Output.txt’, which is opened for writing purpose, is closed.
WRITE FILE
This action is used to append a file with the text specified. The ‘write’ operation always starts from the end of the file. This Action always works on the target file context.
Syntax
WRITE FILE : <TextToWrite>
Where,
<TextToWrite> can be any expression evaluating to the data that needs to be written to the file.
Example
10 : OPEN FILE : “Output.txt” : Text : Write
20 : WRITE FILE : “Krishna”
30 : CLOSE TARGET FILE
Here, a txt file ‘Output.txt’ is opened in ‘write’ mode and the content ‘Krishna’ is appended at the end of the file.
WRITE FILE LINE
This action is similar to WRITE FILE, but it also places a new line character (New Line/Carriage Return) after the text. All the subsequent ‘writes’ begin from the next line. This action always works on the target context.
Syntax
WRITE FILE LINE : <TextToWrite>
Where,
<TextToWrite> can be any expression evaluating to the data that needs to be written to the file.
Example
10 : OPEN FILE : “Output.txt” : Text : Write
20 : WRITE FILE LINE : “Line 1”
30 : WRITE FILE LINE : “Line 2”
40 : CLOSE TARGET FILE
Here, a txt file ‘Output.txt’ is opened in ‘Write’ mode, and two more lines are appended at the end of the file.
TRUNCATE FILE
This action removes the contents of the file by setting the file pointer to the beginning of the file and inserting an ‘end of file’ marker. It can be used to erase all characters from an existing file, before writing any new content to it.
Syntax
TRUNCATE FILE
Example
10 : OPEN FILE : “Output.txt” : Text : Write
20 : TRUNCATE FILE
30 : WRITE FILE : “New Value”
40 : CLOSE TARGET FILE
In this example, the entire contents of the existing txt file ‘Output.txt’ are removed and ‘New Value’ is inserted subsequently.
SEEK FILE
This action operates on the Target File Context. It is used to move the file pointer to a location as specified by the number of characters. As we already know that it is possible to Read and Write from the Target File context, all the subsequent Reads and Writes will be starting from this position. By Default, if the file position is not specified, the ‘Read’ pointer will be always be from the beginning of file and the ‘Write’ pointer will be from the end of the file.
Note: It has already been covered how to Read from the Target File context by using the function $$ TgtFile .
Syntax
SEEK FILE : <File Position>
Where,
<File Position> can be any expression, which evaluates to a number which is considered as the number of characters.
SEEK SOURCE FILE
This action works on a source file context. It sets the current file pointer to the position specified. Zero indicates the beginning of the file and -1 indicates the end of the file. The file position is determined in terms of the characters. All the subsequent reads begin from this position onwards.
Syntax
SEEK SOURCE FILE : <File Position>
Where,
<File Position> can be any expression evaluating to a number, which is the no. of characters.
Example
10 : OPEN FILE : “Output.txt” : Text : Read
20 : SEEK SOURCE FILE : 2
30 : LOG : $$FileRead
40 : CLOSE FILE
In this example, the first line of the file ‘Output.txt’ is read, starting from the 3rd character.
SET ACTIVE SHEET
This action is used to change the Active Sheet during Read and Write operations.
Syntax
SET ACTIVE SHEET : <Sheet Name>
Where,
<Sheet Name> is an expression evaluating to a string, which is considered as name of the sheet.
Example
10 : OPEN FILE : “Output.xls” : Excel : Read
20 : SET ACTIVE SHEET : “Sheet 2”
30 : Log : $$FileReadCell:1:1
40 : CLOSE FILE
In this example, an Excel sheet Output.xls is opened in Read mode, ‘Sheet 2’ is made active and the content is read from the first cell.
Writing to a File
Various actions have been introduced in order to write to an excel file. These Actions operate on the Target File context. The scope of these Actions is within the TDL procedural block (User Defined Functions), where the file is opened and the context is available.
ADD SHEET
This action adds a sheet in the current workbook opened for writing. The sheet will always be inserted at the end. If a sheet with the same name already exists, it will be made as active.
Syntax
ADD SHEET : <Sheet Name>
Where,
<Sheet Name> is an expression evaluating to a string, which is considered as name of the sheet.
Example
10 : OPEN FILE : “Output.xls” : Excel : Write
20 : ADD SHEET : “New Sheet”
Here, an existing Excel sheet ‘Output.xls’ is opened in ‘Write’ mode and the new sheet ‘New Sheet’ is inserted at the end of the workbook.
REMOVE SHEET
This action removes the specified sheet from the current workbook. The entire contents of the sheet will be removed. This action will fail if the workbook has only one sheet, or if the specified sheet name does not exist in the workbook.
Syntax
REMOVE SHEET : <Sheet Name>
Where,
<Sheet Name> is an expression evaluating to a string, which is considered as name of the sheet.
Example
10 : OPEN FILE : “Output.xls” : Excel : Write
20 : ADD SHEET : “New Sheet”
30 : REMOVE SHEET : “Sheet1”
In this example, a workbook is created with a sheet named ‘New Sheet’.
RENAME SHEET
This action renames a worksheet.
Syntax
RENAME SHEET : <Old Sheet Name> : <New Sheet Name>
Where,
<Old Sheet Name> and <New Sheet Name> can be any expression, evaluating to a string, which will be considered as the name of the sheet.
Example
01 : OPEN FILE : “Output.xls” : Excel : Write
02 : RENAME SHEET : @@OldSheetName : @@NewSheetName
04 : CLOSE TARGET FILE
In this example, the existing sheet is renamed with a new sheet name.
WRITE CELL
This action writes the specified content at the cell address specified by the row and column number of the currently active sheet.
Syntax
WRITE CELL : <Row No> : <Column No> : <Content To be Written>
Where,
<Row No> and <Column No> can be any expression which evaluates to a number, which can be used to identify the cell
<Content To be Written> can be any expression which evaluates to data, which needs to be filled in the identified cell.
Example
10 : OPEN FILE : “Output.xls” : Excel : Write : ASCII
15 : ADD SHEET : “New Sheet”
20 : WRITE CELL : 1 : 1 : “Krishana”
30 : CLOSE TARGET FILE
It opens an Excel File ‘Output.xls’, adds a new sheet, and in that sheet, the first cell will have the content as ‘Krishna’.
WRITE ROW
This action writes multiple cell values at a specified row in the Active sheet. The no. of values separated by commas are written, starting from initial column no. specified, for the row specified.
Syntax
WRITE ROW : <Row No> : <Initial Column No> : <Comma Separated Values>
Where,
<Row No> and <Initial Column No> can be any expression which evaluates to a number, which can be used to identify the cell.
Comma Separated Values can be expressions separated with comma, which evaluate to data that needs to be filled, starting from the cell mentioned by ‘Row Number’ and ‘Initial Column Number’.
Example
10 : OPEN FILE : “Output.xls” : Excel : Write
20 : ADD SHEET : “New Sheet”
30 : WRITE ROW : 1 : 1 : @@Val1, @@Val2
40 : CLOSE TARGET FILE
Here, cells (1,A) and (1,B) are filled with the values from expressions ‘Val1’ and ‘Val2’.
WRITE COLUMN
This action writes multiple cell values at a specified column in the Active sheet. The no. of values separated by commas are written starting from the initial row no., specified for the column.
Syntax
WRITE COLUMN : <Initial Row No> : <Column No> : <Comma Separated Values>
Where,
<Initial Row No> and <Column No> can be any expression, evaluating to a number, which can be used to identify the cell.
Comma Separated Values can be expressions separated with comma, which evaluate to data that needs to be filled, starting from the cell mentioned by ‘Initial Row Number’ and ‘Column Number’.
Example
10 : OPEN FILE : “Output.xls” : Excel : Write
20 : ADD SHEET : “New Sheet”
30 : WRITE Column : 5 : 5 : @@Val3, @@Val4
40 : CLOSE TARGET FILE
In this example, cells (5, E) and (6,E) are filled with the values from expressions ‘Val3’ and ‘Val4’.
