# The mco_seq_join_TYPE C Function

> The `mco_seq_join_TYPE()` C function takes a metaiterator in input and produces the result sequence of the same type. (This function is not to be confused with the generated

> `CLASS_FIELD_join()` API!)

> The input metaiterator parameter is an "iterator of iterators", i.e. special kind of iterator which provides a way to concatenate multiple sequences by traversing its elements until it reaches the end of the sequence, then it takes the next iterator and iterates through it and so on.

> The metaiterator structure has the following form:

>         typedef struct mco_seq_meta_iterator_t_
>         {
>             mco_seq_meta_iterator_next_t next;
>             mco_seq_meta_iterator_first_t first;
>             mco_seq_iterator_t iterator; /* iterator initialized by call to next */
>             void* user_data; /* user context can be provided through this field  */
>         } mco_seq_meta_iterator_t, *mco_seq_meta_iterator_h;

> The intent of this function is to combine an eXtremeDB record iterator (or cursor) with a sequence iterator since sequences are normal eXtremeDB field types, i.e. a sequence field belongs to the record. For example, consider the following schema:

>         #define uint4 unsigned<4>
>         #define MAX_SYMBOL_LEN 21

>         declare database stockdb;

>         class Quote
>         {
>             char<MAX_SYMBOL_LEN> symbol;
>             sequence<date asc> day;
>             sequence<float> price;

>             unique tree<symbol> by_sym;
>         };

> The sequence price specifies the price for a particular stock Quote. The Quote table has as primary key the index by_sym on field symbol. If one wishes to calculate the total price for all quotes, it would be necessary to iterate through all of the records in the Quote table, calculate the total price for each record using `mco_seq_agg_sum_float()` on the sequence price, and then sum all of these results.

> The `mco_seq_join_TYPE()` API allows one to construct a metaiterator to perform this operation more efficiently. The metaiterator traverses the Quote table and returns sequence iterators for the price field. Then one can apply the `mco_seq_agg_sum`() to the result of `mco_seq_join_float()` to get the required total sum.

> Clearly this function requires some programming to implement the metaiterator. The following sample code demonstrates how to use `mco_seq_join_float()` and `mco_seq_agg_max_float()` to obtain the maximum low for all quotes. We will use a more realistic Quote table:

>         #define uint4 unsigned<4>
>         #define MAX_SYMBOL_LEN 21

>         declare database stockdb;

>         class Quote
>         {
>             char<MAX_SYMBOL_LEN> symbol;
>             sequence<date asc> day;
>             sequence<float> low;
>             sequence<float> high;
>             sequence<float> open;
>             sequence<float> close;
>             sequence<uint4> volume;
>             sequence<char<15>> day_str;

>             unique tree<symbol> by_sym;
>         };

> The application specific `user_data` is provided to the metaiterator using the following structure:

>         typedef struct quote_low_dsc_t
>         {
>             mco_trans_h trans; // Transaction handle
>             mco_cursor_t quote_cursor; // Cursor for Quote records
>             Quote quote; // Current Quote record
>         } quote_low_dsc;

> The metaiterator's `first` and `next` functions are implemented as follows:

>         MCO_RET join_low_first(mco_seq_meta_iterator_h meta_iterator)
>         {
>             quote_low_dsc *ud = (quote_low_dsc *)meta_iterator->user_data;
>             MCO_RET rc = mco_cursor_first(ud->trans, &ud->quote_cursor);
>             if (rc != MCO_S_OK)
>                 return rc;
>             CHECK(Quote_from_cursor(ud->trans, &ud->quote_cursor, &ud->quote));
>             CHECK(Quote_low_iterator(&ud->quote, &meta_iterator->iterator));
>             return MCO_S_OK;
>         }

>         MCO_RET join_low_next(mco_seq_meta_iterator_h meta_iterator)
>         {
>             quote_low_dsc *ud = (quote_low_dsc *)meta_iterator->user_data;
>             MCO_RET rc = mco_cursor_next(ud->trans, &ud->quote_cursor);
>             if (rc != MCO_S_OK)
>                 return rc;
>             CHECK(Quote_from_cursor(ud->trans, &ud->quote_cursor, &ud->quote));
>             CHECK(Quote_low_iterator(&ud->quote, &meta_iterator->iterator));
>             return MCO_S_OK;
>         }

> Now the function join() initializes the metaiterator and the Quote cursor, then calls `mco_seq_join_float()` to obtain a sequence of all of the low sequence elements for all Quote records. Then the maximum value is extracted from the result of calling `mco_seq_agg_max_float()` with the combined low sequences:

>         void join(mco_db_h db)
>         {
>             mco_seq_iterator_t all_low_it;
>             mco_seq_iterator_t min_low_it;
>             mco_seq_iterator_t count_low_it;
>             mco_seq_meta_iterator_t low_meta_it;
>             MCO_RET rc;
>             float min_low;
>             quote_low_dsc muluser_data;

>             CHECK(mco_trans_start(db, MCO_READ_ONLY, MCO_TRANS_FOREGROUND, &user_data.trans));
>             printf("--- JOIN --------------------\n");

>             /* Initialize the metaiterator */
>             low_meta_it.next = join_low_next;
>             low_meta_it.first = join_low_first;
>             low_meta_it.user_data = &user_data;

>             /* Initialize the cursor over all Quote objects */
>             CHECK(Quote_by_sym_index_cursor(user_data.trans, &user_data.quote_cursor));

>             CHECK(mco_seq_join_float(&all_low_it, &low_meta_it));

>             /* now all_low_it is a sequence which consists of all low sequences
>               for all Quote objects */

>             CHECK(mco_seq_agg_max_float(&min_low_it, &all_low_it));
>             CHECK(mco_seq_next_float(&min_low_it, &min_low));

>             printf("Maximum of lows: %g\n", min_low);

>             CHECK(mco_trans_commit(user_data.trans));
>         }