Option Syntax

This section explains how to use function options in esProc.

1.7.1 esProc function options

Many functions in esProc can use function options with which the same function can have various work patterns. The basic format of function options is f@o(…) in which o is f function’s option. For example:

	A	B
1	2004-5-5	2014-7-7
2	=interval(A1,B1)
3	=interval@y(A1,B1)
4	=interval@m(A1,B1)

We use interval function to compute the number of days between two dates. In expressions in A3 and A4, @y and @m are interval function’s options. With these options, the function will use the year and the month as computational units in computing the interval between dates. Function options empower a function to meet multiple needs by extending its functionality, slim down the function library and avoid using too many function parameters. The number of days, years and months between the two dates are computed respectively in A2, A3 and A4, as shown below:

   

1.7.2 Common function options

Some esProc function options are commonly used by many functions.

Ø  @1 and @a

The two options are frequently used by positioning, selection and joining functions , such as A.pos(), A.select(), A.pmax(), A.pselect(), A.minp(), P.align(), etc.

The use of @a option makes functions that by default return the first-found eligible member return all eligible members. Contrary to @a, functions that by default return all eligible members will return only the first one the query finds by using @1 option.

Let’s look at the uses of these two options through some examples:

	A
1	[1,2,3,4,3,2,1,2,3,2,1]
2	=A1.pos(2)
3	=A1.pos@a(2)
4	=A1.pselect(~==1)
5	=A1.pselect@a(~==1)

The results of A2, A3, A4 and A5 are as follows:

   

	A
1	=demo.query("select * from CITIES")
2	=A1.select(left(NAME,1)=="C")
3	=A1.select@1(left(NAME,1)=="C")
4	=A2.align([6,35,40],STATEID)
5	=A2.align@a([6,35,40],STATEID)

A2 selects cities whose names start with a C:

A3 gets the first city whose name starts with a C:

A4 finds the first city with each of the STATEIDs - 6, 35 and 40:

A5 searches for all cities with STATEIDs 6, 35 and 40 and group them by state:

By the way, since it’s difficult to distinguish between the number 1 and the lowercase letter l, esProc uses the former in most of its options.

One other thing is that the same option used in different functions could have different meanings. For example, @a used in positioning functions means returning all eligible records, while in functions for file writing, like f.write() and f.export(), it means appending.

Ø  @z

@z option is often used in functions related to order, like sort, locate, select, etc., inlcuding A.rank(), A.sort(), A.pos(), A.pselect(), A.select() and so on.

	A
1	[1,2,3,4,3,2,1,2,3,2,1]
2	=A1.pos@z(2)
3	=A1.sort@z ()
4	=demo.query("select * from CITIES")
5	=A4.select@z(STATEID:5)

With @z option, locating or selecting data in a sequence or a table sequence will be executed from back to front. Thus in this example, A2 returns the position of the last 2: 

A3 returns a sorting result in descending order:

Records obtained in A5 are also arranged in reverse order:

Ø  @b

Functions for data location and selection, such as A.pos(), A.pselect(), A.select(), often use the @b option. This option indicates that a more efficient binary search algorithm will be used for data querying, but with the prerequisite that A is ordered; otherwise the result may be wrong.

	A
1	=demo.query("select * from CITIES")
2	=A1.select@b(STATEID:5)
3	=A1.sort(STATEID)
4	=A3.select@b(STATEID:5)

Since data in A1 is not ordered by STATEID, only one record is obtained by A2 with the binary search enabled by @b option:

While A4 obtains the correct result because data is already sorted in A3:

But it is different when @b is used for file reading and writing in functions like f.import(), f.export(), f.cursor(). In that case, a file will be input and output in a binary format. Binary files in esProc are called bin files, with extension being btx. Bin files save storage space and can be transmitted and processed faster.

1.7.3 Using multiple options

esProc allows using multiple compatible options together in no particular order. For example:

	A
1	[1,2,3,4,3,2,1,2,3,2,1]
2	=A1.pos@az(2)
3	=A1.pos@za(2)
4	=demo.query("select * from CITIES")
5	=A4.select@1z(STATEID:5)

Both A2 and A3 get same result when they look for all positions of all 2s in A1 backwards:

A5 finds the first city whose STATEID is 5 from back to front:

Note: Some function options are mutually exclusive, and they can’t work together. These include @a and @1, as well as @t and @b options of f.import() function.