cursor()

Read(389) Label: cursor,

Here’s how to use cursor() function.

cursor()

Description:

 Call a cellset file and return the resut set returned from the execution of the file as a cursor.

Syntax:

cursor(dfx,…)

Note:

The function calls a cellset file and returns the resut set returned from the execution of the file as a cursor. When there are multiple return statements in the dfx file, first merge the result sets returned by the return statements, and then return the merge result as a cursor. These result sets of return must be of the same structure, or error will be reported. Use either an absolute path or a relative path to search for the dfx file. With the relative path, the search order is Class path –> Search path –> Main director.

Parameters:

dfx

Cellset file name

dfx’s parameter

Options:

@c

The dfx can be represented by a cell that corresponds to a subroutine defined by func() function

Return value:

Cursor

Example:

Here’s test.dfx cellset file under the main directory in which arg1 is the cellset parameter:

 

 

A

B

 

1

for arg1

 

 

2

 

=connect("demo").query("select * from GYMNASTICSWOMEN where ID=?",A1)

 

3

 

=B2.derive(avg(VAULT,UNEVENBARS,BALANCEBEAM,FLOOR):Average)

 

4

 

return B3

Perform a loop computation and return the result sets

 

 

A

 

1

=[5,10,20,25]

 

 

2

=cursor("test.dfx",A1)

Cll test.dfx, pass A1’s sequence as the value of parameter arg1, and return result as a cursor

3

=A2.fetch()

Fetch records from the cursor; the result is the union of returned result sets by the loop computation of test.dfx

4

=call("test.dfx",A1)

Use call function to call test.dfx but only the result set of the first loop is returned 

 

 

A

B

 

1

func

 

 

2

 

return A1.sum()

 

3

=cursor@c(A1,[2,5,7])

 

Call the code block whose master cell is A1

4

=A3.fetch()

 

14

cursor cs cursor … cursor

Description:

Define a channel for each cursor according to a specified cursor.

Syntax:

cursor cs

cursor

cursor

Note:

The statement defines a channel for each cursor according to cursor cs (the value of the cursor cell is a channel), traverses cs to perform a calculation over the channel in the code block and write the result into the cell of cursor.

Parameters:

cs

A cursor

A code block

Return value:

Result set of channel

Example:

 

A

B

 

1

=to(100000).new(rand(1000):f1,rand(1000):f2).cursor()

 

Generate a cursor

2

cursor A1

=A2.groups(f1:count(1))

Traverse cursor A1, calculate A2’s channel in B2’s code block and write the result to A2

3

cursor

=A3.groups(f2:count(1))

Same as the above

A. cursor()

Description:

Generate a cursor from a sequence.

Syntax:

A.cursor(k:n)

Note:

The function generates a cursor based on sequence A, divides the cursor data into n segments, and retrieves the kth segment. All segments will be retrieved if parameter k:n is absent.

Parameters:

A

A sequence

k

Segment number

n

The number of data segments; retrieve all data out when both k and n are omitted

Options:

@m

With this option:

A.  cursor@m(n) returns a multicursor; n is the number of segments; use the max number of parallel tasks defined in the designer as the number of segments if n is absent

B.  cursor@m(mcs,K:K’,...) divides an ordered sequence into several segments according to segmenting key K:K’ in sync with ordered multicursor mcs and returns them as a multicursor, too.

Return value:

Cursor/Multicursor

Example:

 

A

 

1

=demo.query("select * from SCORES")

 

2

=A1.cursor(1:3)

Divide the cursor generated from A1 into 3 segments, and retrieve the first one to return

3

=A1.cursor@m(3)

Return a multicursor

4

=demo.query("select * from STUDENTS").sort(ID)

Sort the table sequence by ID

5

=demo.query("select * from STUDENTS1").sort(ID).cursor@m()

Sort the table sequence by ID and return it as a multicursor

6

=A4.cursor@m(A5,ID:ID)

Divide A4’s table sequence into multiple segments by ID and return them as a multicursor

db .cursor()

Description:

Create a database cursor by executing an SQL statement and return it.

Syntax:

db. cursor(sql {,args …})

 

db.cursor(call dfx(){,args })

Connect to esProc-ODBC data source db to call the specified dfx file, and return result as a cursor

Note:

The function creates a database cursor by executing SQL and returns it. The cursor will be automatically closed after a full data scan.

Parameters:

db

Database connection

sql

A SQL statement, like select * from table.

args

If there are parameters in the SQL, they must get assigned; their values can be actual ones or args specified in query statement

Note: Parameters shall be separated by commas

dfx

A cellset file; can be specified using a relative path, which is relative to the search path, or an absolute path

Options:

@i

If the result set has only one column, the content of the returned cursor is a sequence

@d

Convert the numeric data type to the double data type, instead of the decimal data type

@x

Disconnect from the database automatically when the cursor is closed. This option applies to the database connection with connect only

Return value:

A cursor

Example:

 

A

B

C

 

1

=connect("demo")

 

2

=A1.cursor("select * from SCORES")

Return a cursor for retrieving data

3

=create(CLASS,STUDENTID,SUBJECT,SCORE)

Create a table sequence

4

for

 

 

5

 

if A4==1

=A2.skip(5)

When the loop number is 1, jump five rows forward

6

 

=A2.fetch(3)

Fetch three records from the cursor A2 at once

7

 

if B6==null

If B6 is empty, break the loop

8

 

 

Break

 

9

 

else

 

 

10

 

 

>A3.insert(0:B6,CLASS,STUDENTID,SUBJECT,SCORE)

Insert the records in B6 into A3

11

=A1.cursor@ix("select NAME from STUDENTS")

Use @x option to automatically disconnect from the database when the cursor is closed

12

=A11.fetch()

The content of the cursor is a sequence

13

=A1.cursor@i("select NAME from STUDENTS")

Error message saying Data Source demo is shutdown or wrong setup suggests that the data source hasn’t been enabled appears. This is because database connection is automatically closed when A11’s cursor is closed

14

=mysql.cursor@d("select * from ta")

 

15

=A14.fetch()

16

=myproc.cursor("call hsql(?)",10).fetch()

hsql.dfx is in the search path. Below is the file:

myproc is the esProc-ODBC data source name; the parameter value is 10. Below is the result:

17

=demo.cursor(“select * from dept  deptid<? and father=?”,arg1,arg2)

arg1 and arg2 are cellset parameters, whose default values are set as 10 and 1

18

=A17.fetch()

Related functions:

cs.fetch()

cs.skip()

f.cursor()

Description:

Create a cursor based on a file.

Syntax:

f.cursor()

f.cursor(Fi:type,…; k:n,s)

Note:

The function creates a cursor based on file f and returns it. The cursor will be automatically closed after a full data scan.

Parameters:

f

File object, only supporting the textual file object

Fi

Fields to be retrieved; all fields will be retrieved by default. The to-be-retrieved field(s) can be represented by their sequence numbers headed by the sign #

type

Field types, including bool, int, long, float, decimal, string, date, time and datetime. Data type of the first row will be used by default

s

User-defined separator. The default is tab. When the parameter is omitted, the comma preceding it can be omitted, too

k

The segment number

n

The number of segments. Retrieve the whole file when both k and n are omitted

Options:

@t

Use the first row of f as the field names. If omitted, use_1,_2,… as the default field names

@b

Retrieve data from the exported binary file, with the support for parameters Fi, k and n, and with no support for parameters type and s. Ignore options @t, @s, @i, @q and @m. The segmental retrieval could result in empty segment in cases when a file has only a very small number of records

@e

Make the function return null when Fi doesn’t exist in the file; raise an error when the option is absent 

@x

Delete the source file automatically on closing the cursor

@s

Not split the to-be-retrieved field when it is imported as a cursor whose content is a table sequence consisting of strings of a single field; in this case the parameters will be ignored

@i

If the result set has only one column, the content of the returned cursor will be a sequence

@q

Remove the quotation marks, if any, from the field strings, including the field names, in the first place, and handle escape sequences

@c

Use comma as the separator when the parameter s is absent, but the user-defined separator s should take priority when there is one

@m

With the option, the f.cursor@m(Fi:type,…;n,s) function returns a multicursor;  parameter n is the number of segments; use the max number of parallel tasks defined in the designer as the number of segments if the option is absent

@o

Use quotation marks as the escape character

@k

Retain the white space on both sides of the data item; without it a trim operation will be automatically performed

@d

Delete a record if it contains unmatching data types or data formats and start examining data by type

@n

Ignore and discard rows whose number of columns don’t match the first row

@v

Verify data type matching, and, if error reports, throw an exception, terminate the execution and output the content of the problem record

Return value:

A cursor

Example:

 

A

B

C

 

1

=file("D://Student.txt").cursor@tx()

Return the cursor for retrieving data, take the record in the first row as field names, and delete the file automatically when closing the cursor.

2

=create(CLASS,STUDENTID,SUBJECT,SCORE)

Construct a new table sequence

3

for

 

 

4

 

if A3==1

=A1.skip(5)

If the number of loop is 1, then skip 5 consecutive rows.

5

 

=A1.fetch(3)

Retrieve data from cursorA1, 3 rows each time

6

 

if B5==null

Jump out from the loop when B5 is null

7

 

 

Break

 

8

 

else

 

 

9

 

 

>A2.insert(0:B5,CLASS,STUDENTID,SUBJECT,SCORE)

Insert records in B5 into A2

10

=file("D://Department.txt").cursor@t(Dept,Manager;,"/")

=A10.fetch()

Below is Department.txt:

Contents of Department. txt are separated with the slashes and read out according to the specified fields of DEPT and MANAGER

11

=file("D://Department5.txt").cursor@t(;1:2)

=A11.fetch()

With Fi and s omitted, the function separates the cursor into 2 segments and retrieves the first one

12

=file("D:// EMPLOYEE. btx").cursor@b(GENDER;1:2)

=A12.fetch()

Retrieve the GENDER field of the bin file, EMPLOYEE.btx(a segmented binary file) exported through f.export@z(); by default the exported binary file includes field names .

13

=file("D://EMPLOYEE.btx").cursor@b(;1:2)

=A13.fetch()

Retrieve the segmented binary file, EMPLOYEE1.btx, exported by f.export@b(), divide the file contents into 2 parts, and get the first part

14

=file("D://Department.txt").cursor@ts()

= A14.fetch()

Won’t split fields, the cursor contains a table sequence consisting of a single string field

15

=file("D://StuName.txt").cursor@i()

=A15.fetch()

StuName.txt is a file containing only one field, so the content of the cursor is a sequence

16

=file("D://EMPLOYEE1.txt").cursor@tc()

=A16.fetch()

Retrieve the first segment of GENDER field of comma-seperated EMPLOYEE1.txt

17

=file("D://Department3.txt").cursor@e(EID)

=A17.fetch()

Return null since EID field can’t be found in Department3.txt; without @e option, error will be reported, saying EID: field is not found

18

=file("D://Department2.txt").cursor@tq(;,"|")

=A18.fetch()

Below is Department2.txt:  

B19’s result:

19

=file("D://Department.txt").cursor@tm(DEPT:string,MANAGER:int;3,"/")

 

The cursor is devided into 3 segments and the result of A19 is returned as a multicursor

20

=file("D://Sale1.txt").cursor(#1,#3)

=A20.fetch()

Below is the Sale1.txt file:

 Below is the result of B20:

21

=file("D:/Dep3.txt").cursor@qo()

=A21.fetch()

Here is the Dep3.txt file:

Return the result:

22

=file("D:/Dep1.txt").cursor@k()

=A22.fetch()

Retain the whitespace characters on both sides of the data item

 

23

=file("D:/Department1.txt").cursor@t(id:int,name;,"|")

=A23.fetch()

Return id and name fields of Department1.txt

24

=file("D:/Department1.txt").cursor@td(id:int,name;,"|")

=A24.fetch()

Delete a record containing unmatching data types; rows where id value is a are deleted

25

=file("D:/Department1.txt").cursor@tv(id:int,name;,"|")

=A25.fetch()

Verify data type matching, and, and if error reports, throw an exception, terminate the execution and output the content of the problem record; data type doesn’t match with rows where id value is a

 

26

=file("D:/Dep2.txt").cursor@tdn(id:int,name,surname;,"|")

=A26.fetch()

Here’s the file Dep2.txt:

Ignore row 6 and row 8 because the number of columns don’t match that in row 1

Related functions:

cs.fetch()

cs.skip()

db.cursor()

T.cursor( x:C,…;wi…;k:n )

Description:

Segment an entity table and return the cursor of a specified segment.

Synatax:

T.cursor(x:C,…;wi,…;k:n)

Note:

The function splits entity table T into n segments, computes data in the kth segment with expression x and the filtering condition wi, and returns the results as a cursor which contains a field named C. If T is an attached table, the queried data is allowed to include a parent table field.

Options:

@m

The T.cursor@m(x:C…;wi,...;n) function with this option generates a multicursor segmented into n parts. n is an integer; the function returns an ordinary cursor if n<2; use the max number of segments set inTool-Optionsif n is absent

Parameters:

T

An entity table

x

Expression

C

Column alias; can be omitted

wi

Filtering condition; multiple conditions are separated by comma(s) and they must be met at the same time. You can use expression K:Ti (K is a field in the entity table; Ti is a table sequence whose primary key is K) in a condition. The expression means filtering away records where K=Ti.find(K) is false. By default the whole result set is retrieved

k

A positive integer (kn) representing the kth segment

n

A positive integer representing the number of segments

Return value:

A single-thread cursor/multicursor

Example:

 

A

 

1

for 100

 

2

=to(10000).new(#:k1,rand():c1).sort@o(k1)

Generate data

3

=to(10000).new(#:k1,rand(10000):c2,rand()*1000:c3).sort@o(k1)

Generate data

4

=A2.cursor()

Return a cursor

5

=A3.cursor()

Return a cursor

6

=file("D:\\tb4.ctx")

 

7

=A6.create(#k1,c1;k1)

Create the composite table’s base table

8

=A7.append(A4)

Append cursor records to the base table

9

=A7.attach(table4,c2,c3)

Add an attached table to the base table

10

=A9.append(A5)

Append cursor records to the attached table

11

=A9.cursor(;c2<1000;2:3)

Divide records where value of c2 field is less than 1000 into 3 segments, and return a cursor of all columns in the second segment

12

=A11.fetch()

Fetch data from the cursor

13

=A7.cursor(;c1>0.99)

Retrieve some fields from the composite table’s base table

14

=A13.fetch()

 

15

=A9.cursor(k1,c1:b,c3;c3>999)

Based on composite table table4, retrieve k1 field and c1 field from the base table and rename c1 b; and, from the attached table, retrieve records where c3 field value is greater than 999

16

=A15.fetch()

 

17

==A9.cursor@m(;;3)

 

18

=create(k1,k2).record([1,"aa",2,"bb",3,"uh",6,"kkj",7,"fdf",10,"wwwww"]).keys(k1)

Return a table sequence where k1 is the primary key

19

=A6.create()

Open a composite table

20

=A19.cursor(;c1>0.3,k1:A18;1:3).fetch()

Get k1 and c1 fields from A19’s entity table with the condition that c1>0.3 and k1 field values exist in k1 field of A18’s table sequence

T.cursor( x,…;wi,... )

Description:

Return the specified column(s) in a cluster entity table/cluster memory table as a cluster cursor.

Syntax:

T.cursor(x,…;wi,...)

Note:

The function computes data in a cluster entity table/cluster memory table with expression x and the filtering condition w and returns the results as a cluster cursor. Perform file function and cursor function without using @z option over a cluster could cause a computational error.By default a duplicate table won’t be distributed among nodes.

Options:

@m

The function with this option generates a cluster multicursor synchronously segmented into n parts. n is an integer; the function returns an ordinary cursor if n<2; use the max number of segments set inTool-Optionsif n is absent. A duplicate table will be split on two levels, i.e. first distributed among nodes and then generate a multicursor from a segment on the node, when it works with @z.

@z

This option applies only to non-distributed cluster table; it distributes a cluster duplicate table/a cluster memory table among nodes for further processing

Parameters:

T

A cluster entity table/cluster memory table

x

Expression

wi

Filtering condition; multiple conditions are separated by comma(s) and they must be met at the same time. You can use expression K:Ti (K is a field in the entity table; Ti is a table sequence whose primary key is K) in a condition. The expression means filtering away records where K=Ti.find(K) is false.By default the whole result set is retrieved

n

A positive integer representing the number of segments

Return value:

A cluster (multi)cursor

Example:

 

A

 

1

=file@n("D:/tb4.ctx","169.254.121.62:8281")

Open a duplicate table file

2

=A1.create()

Create a cluster duplicate composite table

3

=A2.attach(table3)

Retrieve cluster entity table table3

4

=A2.cursor()

Return a cluster cursor

5

=A3.cursor(NAME,GENDER;EID<6)

 Return NAME field and GENER field where EID<6 as a cluster cursor

6

=file@0("tb4.ctx",["169.254.121.62:8281","192.168.31.72:8291"])

Open a duplicate file

7

=A6.create()

 

8

=A7.cursor@z()

Return the duplicate file that is segmented among nodes using @z option

9

=file@z("tb5.ctx","192.168.31.72:8281")

 

10

=A9.create(;;"@!*123")

 

11

=A10.cursor@m(;;3)

Generate a cluster multicursor that is segmented into 3 parts

12

=A10.cursor()

 

13

=A12.memory()

Generate a cluser memory table

14

=A13.cursor()

Return a cluster cursor

T.cursor( x:C,…;wi,...;mcs )

Description:

Synchronously segment an entity table according to a multicursor and return a multicursor.

Syntax:

T.cursor(x:C,…;wi,...;mcs)

Note:

The function synchronously segments entity table T according to multicursor mcs, during which T’s dimension and mcs’s key will be matched, and returns a multicursor; the way of distributing T and mscs among nodes must be the same and the fields for segmenting T and mcs should be consistent. If multiple entity tables are involved, use a multicursor as a reference to make sure the segmentation is synchronous.

Parameters:

T

An entity table

x

Expression

C

Column alias

wi

Filtering condition; multiple conditions are separated by comma(s) and they must be met at the same time. You can use expression K:Ti (K is a field in the entity table; Ti is a table sequence whose primary key is K) in a condition. The expression means filtering away records where K=Ti.find(K) is false. By default the whole result set is retrieved

mcs

A multicursor generated from an entity table

Return value:

A multicursor

Example:

 

A

 

1

for 100

 

2

=to(10000).new(#:k1,rand():c1).sort@o(k1)

Generate data

3

=to(10000).new(#:k1,rand(10000):c2).sort@o(k1)

 

4

=to(10000).new(#:k1,rand()*1000:c3).sort@o(k1)

 

5

=A2.cursor()

 

6

=A3.cursor()

 

7

=A4.cursor()

 

8

=file("D:\\cs1.ctx")

 

9

=A8.create(#k1,c1;k1)

Create the composite table’s base table where k1 is the key by which  records are segmented

10

=A9.append(A5)

 

11

=A9.attach(table1,#c2)

Add attached table table1 to the base table

12

=A11.append(A6)

 

13

=A11.cursor@m(;;2)

Segment entity table table1 and return the segments as a multicursor

14

=A9.attach(table2,c3)

Add attached table table2 to the base table

15

=A14.append(A7)

 

16

=A14.cursor(;;A13)

Segment entity table table2 according to table1’s multicursor

 

T.cursor( x:C,…;wi,...;mcs )

Description:

Synchronously segment a cluster entity table according to a cluster multicursor and return a cluster multicursor.

Syntax:

T.cursor(x;C,…;w;mcs)

Note:

The function synchronously segments cluster entity table T according to cluster multicursor mcs, during which T’s dimension and mcs’s key will be matched, and returns a cluster multicursor; the way of distributing T and mcs among nodes must be the same and the fields for segmenting T and mcs should be consistent. If multiple cluster entity tables are involved, use a cluster multicursor as a reference to make sure the segmentation is synchronous.

Parameters:

T

A cluster entity table

x

Expression

w

Filtering condition; multiple conditions are separated by comma(s) and they must be met at the same time. You can use expression K:Ti (K is a field in the entity table; Ti is a table sequence whose primary key is K) in a condition. The expression means filtering away records where K=Ti.find(K) is false. By default the whole result set is retrieved

mcs

A cluster multicursor generated from a cluster entity table

Return value:

A cluster multicursor

Example:

 

A

 

1

=file@z("D:/cs1.ctx","169.254.121.62:8281")

 

2

=A1.create()

Open a distributed cluster composite table

3

=A2.attach(table1)

Retrieve cluster entity table table1

4

=A3.cursor@m(;;2)

Return a cluster multicursor

5

=A2.attach(table2)

Retrieve cluster entity table table2

6

=A5.cursor(;;A4)

Segment cluster entity table table2 according to table1’s multicursor

 

T.cursor( C,…;wi,...; k:n )

Description:

Segment a memory table/cluster memory table and return cursor of the specified segment.

Syntax:

T.cursor(C,…;wi,...;k:n)

Note:

The function filters memory table T according to filtering condition wi, splits it into n segments and returns the kth segment as a cursor; return the cursor of the whole table if parameters are absent. For a cluster memory table, parameters k:n are invalid and can be omitted. Parameter C is one of T’s column; return all columns of T when C is absent. The function will return the filtered T when parameters k:n are absent. Parameters k:n have no meaning if T is a cluster memory table and thus will be omitted.

Note: Perform file function and cursor function without using @z option with them over a cluster could cause a computational error.

Parameters:

T

A memory table/cluster memory table

C

Column name in the memory table

wi

Filtering condition; multiple conditions are separated by comma(s) and they must be met at the same time. You can use expression K:Ti (K is a field in the entity table; Ti is a table sequence whose primary key is K) in a condition. The expression means filtering away records where K=Ti.find(K) is false.

k

A positive integer (kn) representing the kth segment

n

A positive integer representing the number of segments

Options:

@m

T.cursor@m(...;n) returns a multicursor segmented into n parts; n is an integer; the function returns an ordinary cursor if n<2; use the max number of segments set inTool-Optionsif n is absent

Return value:

A single-thread cursor/multicursor

Example:

 

A

 

1

=demo.cursor("select EID,NAME,GENDER from employee where EID< 10")

Return cursor of the retrieved data

2

=A1.memory()

Return a memory table

3

=A2.cursor(2:3).fetch()

Split the cursor generated from the memory table into 3 segments and get the 2nd one

4

=A2.cursor@m(3).fetch()

Use @m option to return a memory-table-generated multicursor that contains 3 segments

5

=file@n("D:/test.ctx","169.254.121.62:8281")

Open a duplicate file

6

=A5.create()

Create a duplicate cluster table

7

=A6.attach(table3)

Retrieve the cluster table table3

8

=A7.memory()

Return a cluster memory table object

9

=A8.cursor().fetch()

The cursor generated from a memory table hasn’t a segmentation parameter

10

=A2.cursor(EID,NAME;EID<80;2:3)

Split records where EID is less than 80 in A2’s memory table into 3 segments and return the 2nd segment consisting of EID and NAME fields

11

=A2.cursor@m(EID,NAME;EID<80;5)

Return a multicursor

T.cursor( …;w;mcs )

Description:

Divide a memory table in sync with a memory multicursor and return it also as a memory multicursor.

Syntax:

T.cursor(...;w;mcs)

Note:

The function filters memory table T according to filtering condition w and returns the table as a memory multicursor in sync with multicursor mcs. The ellipsis parameter, generally omitted, represents the selected field(s), and the semicolon after it must be alwasys present.

Parameters:

T

A memory table

w

Filtering condition

mcs

A multicursor generated from a memory table or a composite table

Return value:

A memory multicursor

Example:

 

A

 

1

==demo.cursor("select * from employee where EID < 10")

Return the retrieved data as a cursor

2

=A1.memory().keys(EID)

Return a memory table for which the key is set as EID

3

=file("d://emp.ctx").create().cursor@m()

Open a composite table and return it as a multicursor

4

=A2.cursor(;SALARY>8000;A3)

Return a memory multicursor in sync with A3’s multicursor

mcs.cursor(n)

Description:

Merge subcursors in a multicursor into a single cursor or a new multicursor with a smaller number of parallel subcursors.

Syntax:

mcs.cursor(n)

Note:

The function merges subcursors in a multicursor into a single cursor, which is the default, or a new multicursor with a smaller number, which is specified by parameter n, of parallel subcursors.

Parameters:

mcx

A memory table/a cluster memory table

n

Subcursor column name

Return value:

A common cursor or a multicursor

Example:

 

A

 

1

=file("D:\\dept2.txt").cursor@m()

Retrieve dept2.txt as a multicursor

2

=A1.fetch()

Fetch records from A1’s multicursor

3

=A2.cursor().groups(#3:FATHER;count(#1):TOTAL)

Merge the multicursor into a common cursor and perform grouping & aggregation