Loads character strings as records in the specified table. The records to be inserted can be indicated in the document itself within a variable string, or by referring to an absolute file with the full path.

When the process starts, a transaction opens and when the list of records is finished, it closes. If an error occurs with any of the registers, the system performs a reverse (rollback) and therefore no register is inserted.

Temporary tables with an automatically generated name are also supported (name specified with the "@" symbol).

1 table.load

<table.load
    columns='columns'
    colindexes='colindexes'
    colwidths='colwidths'
    date-format='date-format'
    decimal-format='decimal-format'
    delimiter='delimiter'
    autocommit='autocommit'
    encoding='encoding'
    enclosing-char='enclosing-char'
    gzip='gzip'
    firstRowIsHeader='firstRowIsHeader'
    replace='replace'
    primary-key-columns='primary-key-columns'
    debug='debug'
    table='table'
    counter-step='counter-step'
    counter-max='counter-max'
    encoding='encoding'
>
    <rows /> ?
    <instructions> ?
        <filter> ?
            <column name='name' /> +
        </filter>
        <onError> ?
            <instructions /> ?
        </onError>
    </instructions>
    <data count='count'> ?
        <rows /> ?
    </data>
</table.load>

Attributes
Name	Type	Required	Default	Description
Acolumns	string				List of columns (separated by comma) of the table table that you want to load.
Acolindexes	string				List of indexes (separated by a comma) that define the columns and the order in which they will be inserted in the table in superposition of the columns to be reported. This way columns a, b, c of the table of the database to be loaded are defined: when reporting 5,7,6 as load indexes, it is indicated that these positions in the load file will be the ones that are insert in the same order. It is mandatory to report the columns attribute together with colindexes .
Acolwidths	string				Limits the number of characters in the columns that will be inserted. The use according to the order of the columns to be inserted is considered. If this attribute is reported, the character limit must be defined for each of the columns to be inserted.
Adate-format	string				Date type value format.
Adecimal-format	string				Decimal Type Value Format.
Adelimiter	string				Value separator character, which indicates the beginning and end of each column. Sometimes it is required to use a special character as a delimiter, for example, the tabulation; For this purpose HTML coding is used; this way, the character corresponding to the tabulation is " ". If the system does not recognize the entered delimiter, it will issue a controlled error.
Aautocommit	number				Indicates how many records loaded closes the database transaction. In turn, activates a Counter object with the step equal to this value.
Aencoding	string			OS encoding	Indicates the original character encoding of the file you want to import.
Aenclosing-char	string				Character that allows to include the separator character. That is, when the separator character is within the area defined by the character defined here, it is not evaluated as a separator but is taken as the literal value of the column in which it is located. This always applies and, by default, this character is the double quote [""].
Agzip	boolean			false	A compressed file can be provided. Indicate the gzip = 'true' attribute. Loading data are required to come from a compressed file in any of the formats compatible with gzip .
AfirstRowIsHeader	boolean			false	If firstRowIsHeader = 'true' is indicated, the first line of data to load will be ignored.
Areplace	string			insert-first	In certain cases it is convenient to replace the content of certain data in the table with others. With the option replace it is possible to replace in those tables where there is a primary key. The data to be inserted will completely replace the records in which the primary key matches. Only those record fields that are reported in the table.load will be modified. There are two ways to replace: insert-first: In this option all data is inserted as if the table.load were executed in a conventional manner. When an error occurs because you cannot insert a record whose primary key already exists, the system captures the error and replaces the values with a simple update. update-first: Using this option, the system before inserting a record executes the update in the database. If no record is found to modify the record is inserted. For data loads in which most records are not going to find data, it is more convenient to execute the insert-first command; the opposite for duplicate data in which the use of update-first is recommended.
Aprimary-key-columns	string				List of comma separated columns that will form the "virtual" PK of the table. This option allows to define alternative PKs to those existing in the table itself. For example, the physical PK may be a serial field, but when loading, it can be defined that the PK to consider is a column of code in the table. This attribute only makes sense if the attribute replace has also been reported.
Adebug	boolean			false	If debug ='true' is indicated, debug data corresponding to the execution of the process will be generated.
Atable	string				Table name.
Acounter-step	number				If a value greater than zero is indicated, the system automatically creates a Counter object on the loading process with the step attribute indicated here.
Acounter-max	number				If a value greater than zero is indicated, the system automatically creates a Counter object on the loading process with the max attribute indicated here.
Aencoding	string				Indicates the encoding of the characters string to be processed, such as ISO-8859-1 or UTF-8. If it is not specified, the one defined in the configuration file for the server is used.

Arguments
Name	Type	Required	Unique	Nullable	Description
Erows
Einstructions
Efilter					Through this label it is possible to define formatting functions to be applied on certain columns. This can be a function <xsqlscript/>, a call to a local function or a call to another procedure <xsqlscript/>.
Ecolumn					Through this label it is possible to define formatting functions to be applied on certain columns. This can be a function <xsqlscript/>, a call to a local function or a call to another procedure <xsqlscript/>.
Aname	string				Name of the column to which the filter is applied.
EonError					Sentences to be executed in case of load error in one of the rows. If this argument exists, in case of an error the sentences are executed and the loading continues, instead of not completing execution or a rollback of the load operations is carried out.
Einstructions
Edata					It is simply a container of the values to load (rows) when filter functions are used. Consequently, only the load values within the data tag should be reported when filter functions are used; otherwise, they will be added directly to the tag table.load.
Acount	number				Activate a Counter object with the step equal to the value indicated here.
Erows					This can be a string with the records to be inserted with a line break between them or a reference to an absolute file containing the records. The examples show the two variants. In any case, there cannot be a line break leading the list of records since it would be interpreted as one more record to insert and the number of columns would not match that of the table generating the corresponding exception. So if it is a string in the program itself, the first record must be attached to the tag <string> (see example 1).

Exceptions

requires 1 arguments, received: [...]

Wrong number of arguments specified.

incorrect number of columns at line 1, [...] (table) != [...] (row)

An incorrect number of values has been indicated with respect to the number of columns in the table. This could also occur if there is a line break at the beginning of the load file.

expected <data> while found <...>

Formatting functions ( filters ) have been indicated and the values to be loaded are not within the data tag.

Delimiter specified '...' is incorrect. It should be single character.

A character code not considered as a delimiter is used.

Remarks

When the process starts, a transaction opens and when the list of records is finished, it closes. If any error occurs with any of the records, the system performs a reverse ( rollback ) and therefore no record is inserted.

Example

Load records contained in a string into a table..

Copy

<xsql-script name='table_load_sample1'>
    <body>
        <table name='persones'>
            <column name='dni'     type='char'    size='9'  />
            <column name='nom'     type='varchar' size='20' />
            <column name='cognom'  type='varchar' size='25' />
        </table>

        <table.load table='persones'>
               <!-- ATTENTION: There cannot be a line break because it would be interpreted as a record -->
               <!-- to be inserted where the number of columns would not match that of the table and  -->
               <!-- an exception would be generated, so the first record is attached to the  tag string.  -->
        <string>44018855Z|john|smith
		33873345A|kevin|swatch
		43829209O|peter|petrelli
		27364849E|george|lucas</string>
        </table.load>

        <print.sql>
            <select>
                <columns>*</columns>
                <from table='persones' />
            </select>
        </print.sql>
    </body>
</xsql-script>

The result of the example execution would be as follows:

Copy

+---------+----+---------+
    |dni      |nom |cognom1  |
    +---------+----+---------+
    |44018855Z|john|smith    |
    |33873345A|kevin|swatch  |
    |43829209O|peter|petrelli|
    |27364849E|george|lucas  |
    +---------+----+---------+

Example

Load records contained in a file into a table.

Copy

<xsql-script name='table_load_sample2'>
	<body>
		<table name='persones'>
			<column name='dni' type='char' size='9' />
			<column name='nom' type='varchar' size='20' />
			<column name='cognom' type='varchar' size='25' />
		</table>

		<table.load table='persones'>
			<!-- The file must be indicated as type absolute and indicating the complete
			    path in the attribute name. The content of the file is as follows: 44018855Z|john|smith 
				33873345A|kevin|swatch 43829209O|peter|petrelli 27364849E|george|lucas -->
			<file name="load.unl" type="absolute" />
		</table.load>

		<print.sql>
			<select>
				<columns>*</columns>
				<from table='persones' />
			</select>
		</print.sql>
	</body>
</xsql-script>

The result of the example execution would be as follows:

Copy

+---------+----+---------+
    |dni      |nom |cognom1  |
    +---------+----+---------+
    |44018855Z|john|smith    |
    |33873345A|kevin|swatch  |
    |43829209O|peter|petrelli|
    |27364849E|george|lucas  |
    +---------+----+---------+

Example

Load records from the program itself into a temporary table.

Copy

<xsql-script name='table_load_sample3'>
	<body>
		<table name='persones'>
			<column name='dni' type='char' size='9' />
			<column name='nom' type='varchar' size='20' />
			<column name='cognom' type='varchar' size='25' />
		</table>

		<table.load table='persones'>
			<!-- The file must be indicated as type absolute and indicating the 
			    complete path in the  attribute name. The content of the file is as follows: 
			    44018855Z|john|smith 
				33873345A|kevin|swatch 43829209O|peter|petrelli 27364849E|george|lucas -->
			<file name="load.unl" type="absolute" />
		</table.load>

		<print.sql>
			<select>
				<columns>*</columns>
				<from table='persones' />
			</select>
		</print.sql>
	</body>
</xsql-script>

The result of the example execution would be as follows:

Copy

+---------+----+---------+
    |dni      |nom |cognom1  |
    +---------+----+---------+
    |44018855Z|john|smith    |
    |33873345A|kevin|swatch  |
    |43829209O|peter|petrelli|
    |27364849E|george|lucas  |
    +---------+----+---------+

Example

Load in a table records contained in a file encoded in utf-8 being in an OS in another encoding (for example cp1552 of windows).

Copy

<xsql-script name='table_load_sample4'>
        <body>
            <table name='persones'>
                <column name='dni'     type='char'    size='9'  />
                <column name='nom'     type='varchar' size='20' />
                <column name='cognom'  type='varchar' size='25' />
            </table>

            <table.load table='persones' encoding='utf-8'>
                <!-- The file must be indicated as type absolute  and indicating the complete path in the name attribute. 
                    The content of the file in utf-8 is as follows:
    44018855Z|john|smith
    33873345A|kevin|swatch
    43829209O|peter|petrelli
    27364849E|george|lucas
                -->
                <file name="load.unl" type="absolute" />
            </table.load>

        </body>
    </xsql-script>

Example

Apply formatting with <filter> when loading data from a resultset: capitalize the values of a given column.

Copy

<xsql-script name='table_load_sample5'>
    <body>
        <table name='@tmp_sample' temp='y'>
            <column name='code'         type='char' size='6' />
            <column name='description'  type='varchar' size='60' />
        </table>
                        
        <table.load table='@tmp_sample' replace='insert-first'>
            <instructions>
                <onError>
                  <insert table='log_events'>
                              <column name='log_id'>0</column>
                              <column name='tablename'><p_table/></column>
                              <column name='msglog2'><p_error/></column>
                              <column name='line'><p_line/></column>
                              <column name='row'><p_row/></column>
                              <column name='col'><p_col/></column>
                  </insert>
                </onError>
                <filter>
                    <column name='code'><string.toUpperCase><code /></string.toUpperCase></column>
                </filter>
            </instructions>
            <data>
                <sql.toResultSet>
                    <select>
                        <columns>code1, name</columns>
                        <from table='tabori'/>
                    </select>
                </sql.toResultSet>
            </data>
        </table.load>
    </body>
</xsql-script>

As a result of the execution, the result of the select is obtained and loaded as if it were a physical file.

Example

Apply format with <filter> in the data load: add prefix to a mnemonic code.

Copy

<xsql-script name='table_load_sample6'>
    <body>
        <function name='local_addCodePrefix'>
            <args>
                <arg name='p_code'  type='string' />
            </args>
            <body>
                <return><string><date.year><date.today /></date.year>-<p_code /></string></return>
            </body>
        </function>

        <table name='@tmp_sample' temp='y'>
            <column name='code'     type='char'     size='10' />
            <column name='descri'   type='varchar'  size='60' />
        </table>

        <table.load table='@tmp_sample'>
            <instructions>
                <filter>
                    <column name='code'><local_addCodePrefix><code /></local_addCodePrefix></column>
                </filter>
            </instructions>
            <data>
                <string>
0001|ITEM 0001
0002|ITEM 0002
0003|ITEM 0003
                </string>
            </data>
        </table.load>

        <print.sql head='true'>
            <select>
                <columns>*</columns>
                <from table='@tmp_sample' />
            </select>
        </print.sql>
    </body>
</xsql-script>

The result of the example execution would be as follows:

Copy

+---------+---------+
|code     |descri   |
+---------+---------+
|2012-0001|ITEM 0001|
|2012-0002|ITEM 0002|
|2012-0003|ITEM 0003|
+---------+---------+

Example

Use <onError> for handling load errors without stopping or performing a rollback.

Copy

<xsql-script name='table_load_sample7'>
    <body>

        <function name='createtable'>
            <body>
                <nativesql>
!DROP TABLE test;
CREATE TABLE test(
    a char(10) not null, b CHAR(10) not null, c CHAR(10), d CHAR(10),
PRIMARY KEY (a, b)
)
                </nativesql>
            </body>
        </function>

        <function name='printtable'>
            <body>
                <println>printtable</println>
                <print.sql>
                    <select cache='false'>
                        <columns>*</columns>
                        <from table='test' />
                    </select>
                </print.sql>
            </body>
        </function>

        <function name='callback_error'>
            <args>
                <arg name='_table' />
                <arg name='_row' />
                <arg name='_col' />
                <arg name='_line' />
                <arg name='_error' />
            </args>
            <body>
                <println/>
                <println/>
                <println>Error loading data int table <_table /> at row: <_row/> column: <_col /> line: <_line /> cause: <_error /></println>
                <println/>
                <println/>
            </body>
        </function>
    <!-- SAMPLE: load delimited with interceptor funcions -->

    <println>LOAD INSTRUCTIONS</println>
    <createtable />

    <println>printing table 1</println>
    <printtable />


    <table.load
        table='test'
        columns='a,b,d'
        colindexes='2,1,3'
        delimiter=','
    >
    <instructions>
        <filter>
            <column name='a'>
                <string.toUpperCase><a/></string.toUpperCase>
            </column>
        </filter>
        <onError>
            <callback_error>
                <p_table />
                <p_row />
                <p_col />
                <p_line />
                <p_error />
            </callback_error>
         </onError>
    </instructions>
    <data>
        <string>
c1,b1,a1,d1,e1,f1
c3 this row will generate an exception
c2,b2,a2,dx
c3,b3,a3,d3
        </string>
    </data>
    <!--
    if source is a File we need to wrap it insise tag <data><file .. /></data
    to allow get1EvaluatedArguments pointing to File works
    -->
    </table.load>

    <println>printing table 2</println>
    <printtable />

    </body>
</xsql-script>

Example

Uso de enclosing-char.

Copy

<xsql-script name='table_load_sample7'>
    <body>
	
	        <function name='createtable'>
	            <body>
	                <nativesql>
	!DROP TABLE test;
	CREATE TABLE test(
	    a char(10) not null, b CHAR(10) not null, c CHAR(10), d CHAR(10),
	PRIMARY KEY (a, b)
	)
	                </nativesql>
	            </body>
	        </function>
	
	        <function name='printtable'>
	            <body>
	                <println>printtable</println>
	                <print.sql>
	                    <select cache='false'>
	                        <columns>*</columns>
	                        <from table='test' />
	                    </select>
	                </print.sql>
	            </body>
	        </function>
	
	    <println>LOAD INSTRUCTIONS</println>
	    <createtable />
	
	    <println>printing table 1</println>
	    <printtable />
	
	    <table.load
	        table='test'
	        delimiter=','
	
	    >
	    <data>
	        <string>
	Barcelona,Emp 1 S,A,Del 1, Dep 1
	Manresa,"Emp 2 S,A",Del 2, Dep 2
	        </string>
	    </data>
	    </table.load>
	
	    <println>printing table 2</println>
	<!--
	+=========+=========+=====+======+
	|a        |b        |c    |d     |
	+=========+=========+=====+======+
	|Barcelona|Emp 1 S  |A    |Del 1 |
	|Manresa  |Emp 2 S,A|Del 2|Dep 2 |
	+=========+=========+=====+======+
	-->
	    <printtable />
	
	
	    <println>LOAD INSTRUCTIONS</println>
	    <createtable />
	
	    <println>printing table 1</println>
	    <printtable />
	
	    <table.load
	        table='test'
	        delimiter=';'
	    >
	    <data>
	        <string>
	Barcelona;CUST;CLI;Del 1; Dep 1
	Manresa;"CUST;CLI";Del 2; Dep 2
	        </string>
	    </data>
	    </table.load>
	
	    <println>printing table 2</println>
	<!--
	+=========+========+=====+======+
	|a        |b       |c    |d     |
	+=========+========+=====+======+
	|Barcelona|CUST    |CLI  |Del 1 |
	|Manresa  |CUST;CLI|Del 2|Dep 2 |
	+=========+========+=====+======+
	-->
	    <printtable />
	
	
	    <table.load
	        table='test'
	        delimiter=';'
	        enclosing-char='\$'
	    >
	    <data>
	        <string>
	Barcelona;CUST;CLI;Del 1; Dep 1
	Manresa;$CUST;CLI$;Del 2; Dep 2
	        </string>
	    </data>
	    </table.load>
	
	    <println>printing table 2</println>
	<!--
	+=========+==========+=====+======+
	|a        |b         |c    |d     |
	+=========+==========+=====+======+
	|Barcelona|CUST      |CLI  |Del 1 |
	|Manresa  |$CUST;CLI$|Del 2|Dep 2 |
	+=========+==========+=====+======+
	-->
	    <printtable />
	</body>
</xsql-script>

Example

Load records contained in a file using the attribute colindexes.

Copy

<xsql-script name='table_load_sample2'>
	<body>
		<table name='persones'>
			<column name='dni' type='char' size='9' />
			<column name='nom' type='varchar' size='20' />
			<column name='cognom' type='varchar' size='25' />
		</table>

		<table.load table='persones' columns='dni, nom, cognom'
			colindexes='0,3,5'>
			<!-- The file must be indicated as type absolute and indicating the complete path 
			    in the attribute name. The content of the file is as follows: 44018855Z|jkjk|innecesario|john|blanco|smith 
				33873345A|jkjm|nulo|kevin|paja|swatch 43829209O|dasd|fijo|peter|gris|petrelli 
				27364849E|eqwe|atri|george|negro|lucas -->
			<file name="load.unl" type="absolute" />
		</table.load>

		<print.sql>
			<select>
				<columns>*</columns>
				<from table='persones' />
			</select>
		</print.sql>
	</body>
</xsql-script>

The result of the example execution would be as follows:

Copy

+---------+----+---------+
    |dni      |nom |cognom1  |
    +---------+----+---------+
    |44018855Z|john|smith    |
    |33873345A|kevin|swatch  |
    |43829209O|peter|petrelli|
    |27364849E|george|lucas  |
    +---------+----+---------+

Example

Load records contained in a file using the attribute colwidths.

Copy

<xsql-script name='table_load_sample2'>
	<body>
		<table name='persones'>
			<column name='dni' type='char' size='9' />
			<column name='nom' type='varchar' size='20' />
			<column name='cognom' type='varchar' size='25' />
		</table>

		<table.load table='persones' columns='dni, nom, cognom'
			colindexes='0,3,5' colwitdhs='1,1,10'>
			<!-- The file must be indicated as type absolute and indicating the complete path 
			    in the attribute name. The content of the file is as follows: 44018855Z|jkjk|innecesario|john|blanco|smith 
				33873345A|jkjm|nulo|kevin|paja|swatch 43829209O|dasd|fijo|peter|gris|petrelli 
				27364849E|eqwe|atri|george|negro|lucas -->
			<file name="load.unl" type="absolute" />
		</table.load>

		<print.sql>
			<select>
				<columns>*</columns>
				<from table='persones' />
			</select>
		</print.sql>
	</body>
</xsql-script>

The result of the example execution would be as follows

Copy

+---------+----+---------+
    |dni      |nom |cognom1  |
    +---------+----+---------+
    |4        |j   |smith    |
    |3        |k   |swatch   |
    |4        |p   |petrelli |
    |2        |g   |lucas    |
    +---------+----+---------+

Example

CUpload a file obtained from an FTP stream.

Copy

<xsql-script name='ftp_table_load'>
	<body>
		<nativesql>
			!DROP TABLE test;
			CREATE TABLE test(
			a char(10) not null, b CHAR(10) not null, c CHAR(10)
			)
		</nativesql>
		<ftp host='192.168.10.1' user='xxx' password=yyyy '>
			<ftp.put name='test.dat'>a1,b1,c1

				a2,b2,c2
				a3,b3,c3



			</ftp.put>
			<table.load table='test' delimiter=','>
				<ftp.getPipedInputStream name='test.dat' />
			</table.load>
		</ftp>
	</body>
</xsql-script>