FreeTDS Development Group

[Frediano Ziglio <freddyz77 AT tin.it>]

Il gio, 2002-12-05 alle 21:00, Lowden, James K ha scritto:
> Does anyone else get confused by inconsistent naming conventions in libtds?
> 
> (what is he talking about?)
> 
> Some are very nice and easy to grasp.  
> 
> TDSLOGIN *tds_alloc_login(void)
> TDSCONTEXT *tds_alloc_context(void)
> TDSSOCKET *tds_alloc_socket(TDSCONTEXT *context, int bufsize)
> TDSDYNAMIC *tds_alloc_dynamic(TDSSOCKET *tds, const char *id)
> 
> I need a TDSLOGIN*, so I call tds_alloc_login(); I see a call to
> tds_alloc_login(), and I expect a pointer to a TDSLOGIN structure to be
> returned.  
> 
> Some use "info" a little gratuitously:
> 
> TDSCONNECTINFO *tds_alloc_connect(TDSLOCINFO *locale)
> TDSENVINFO *tds_alloc_env(TDSSOCKET *tds)
> TDSRESULTINFO *tds_alloc_results(int num_cols)
> 

I think connection info is good (perhaps the only needed) cause we to
not store a connection (like TDSSOCKET) but information for connecting
to a server...

> Two whose names and types are not well matched:
> 
> TDSLOCINFO *tds_alloc_locale(void)
> TDSPARAMINFO *tds_alloc_param_result(TDSPARAMINFO *old_param)
> 
> Here are three I'd say are ill-defined:
> 
> void *tds_alloc_compute_row(TDSCOMPUTEINFO *res_info)
> void *tds_alloc_row(TDSRESULTINFO *res_info)
> unsigned char *tds_alloc_param_row(TDSPARAMINFO *info,TDSCOLINFO *curparam)
> 

Agree... I think there are only historic reason for this...
compute/param was different from normal result...
tds_alloc_row/tds_alloc_compute_row do the same things (best name should
be tds_alloc_results/tds_alloc_columns). tds_alloc_param_row... is the
best name I founded... it permit to add a single columns to data...
tds_results_add_column? not so good, cause column is already in
TDSRESINFO (first I add a column and then extend result... perhaps we
can do both?)

> Two that are very confusing:
> 
> TDSCOMPUTEINFO **tds_alloc_compute_results(TDS_INT *num_comp_results,
> TDSCOMPUTEINFO** ci, int num_cols, int by_cols)
> TDSCOMPUTEINFO *tds_alloc_compute_result(int num_cols, int by_cols)
> 
> +++
> 
> Only slowly (me being me) have I grasped that a column is described by
> TDSCOLINFO, while many columns are TDSRESULTINFO, or identical typedefs:
> TDSPARAMINFO and TDSCOMPUTEINFO.  
> 
> Doxygen looms.  Rather than documenting this hodgepodge in situ, I propose
> to revise it, wholesale, as follows:
> 
> 1.  Strike "INFO" from every typename and use a word instead, if possible.
> s/TDSCONNECTINFO/TDSCONNECTION/; s/TDSLOCINFO/TDSLOCALE/;
> s/TDSCOLINFO/TDSCOLUMN/.  Et cetera.  
> 
> 2.  Since TDSRESULTINFO, TDSPARAMINFO, and TDSCOMPUTEINFO are all the same
> thing, let's use one name.  I offer TDSRESULTDESC or TDSCOLUMNS.  Or just
> leave it TDSRESULTINFO.  
> 

Before collapsing think at cursor. Now every query return
rows/compute/params until query is finished. With cursor we can process
multiple query... This mean that results can be ROWS+n*COMPUTE or
PARAMS. This suggest to me that a new structure will contain information
for ROW and COMPUTE together. This is another result type too?
TDSCOLINFO contain information for columns but not data. Data are only
stored in RESULTS... perhaps is best to split row data from row info
(columns). So we can store even multiple row all with same column
information? Useful in array binding...

> 3.  Name the allocation routines after their types, unless the same type is
> allocated by several routines, e.g.:
>       TDSCONNECTINFO *tds_alloc_connect(TDSLOCINFO *locale)
>       becomes
>       TDSCONNECTION *tds_alloc_connection(TDSLOCALE *locale)
> 
> I don't think these changes will improve run-time or compile-time
> performance, but think-time should get much better.  
> 
> Comments solicited, as ever.  
> 
Ok.

freddy77