List of connection properties?

[Fr0sT]

Which props really require long descriptions? Most of them are pretty obvious and those which require explanations usually are directly derived from drivers so driver's docs will be better.

[marsupilami]

How about the fb_protocol option, that manages how Zeos builds firebird connection strings? The current documentation source from the release notes looks like this:

Code: Select all

\subsubsection{new connection parameter fb\_protocol}
\label{sec:Rev6_FirebirdInterbase_Changes_FBProtocol}

The new parameter "fb\_protocol" was introduced as a connection parameter.
With Firebird 3 this paramater switches Zeos to use url style connection strings.
This enables you to force the library to use xnet for connecting to the server, bypassing a local engine12.
This parameter also allows you to use the wnet (Named Pipes) protocol on older versions of Firebird and on Interbase.
For possible values of fb\_protocol see table \ref{tbl:Rev6_ValuesFbprotocol} on Page \pageref{tbl:Rev6_ValuesFbprotocol}.

\begin{table}
    \begin{tabular}{ p{1cm} p{13cm} }
    Value & Description \\ \hline
    inet & This will create a connection string to be used with TCP/IP. If the server name is empty, localhost will be used as the server name. \\ %\hline
    wnet & This will create a connection string to be used with named pipes. If the server name is empty, a connection to a local server will be created. \\ %\hline
    xnet & On Firebird 3 this will force the client library to use an xnet (shared memory) connection to a local server. On Interbase and Firebird 2.5 and below the embedded server cannot be forced to use xnet, while the regular client library will always use xnet in that case. The server name will be ignored with this setting. \\
    local & This value will try to do a local connection. This will only work with embedded servers. Regular client libraries will usually fall back into using xnet. \\
		\end{tabular}
    \caption{values for fb\char`_protocol}
    \label{tbl:Rev6_ValuesFbprotocol}
\end{table}

Also description for the date / time related connection parameters (DateReadFormat, DateWriteFormat, DateDisplayFormat, TimeReadFormat, TimeWriteFormat, , TimeDisplayFormat, DateTimeReadFormat, DateTimeWriteFormat, DateTimeDisplayFormat) is longer than just one or two sentences and doesn't relate to parameters of the database product:

Code: Select all

\subsection{Date and Time format settings}
\label{sec:Rev4_GeneralChanges_DateAndTimeFormatSettings}
Zeos now supports specifying date and time format settings that will be used if Zeos doesn't know how to correctly format date and time settings for the DBMS to understand them.
This feature gets used with emulated parameters in ADO - if the FoxPro driver is used for example.
These new parameters can be set in the TZConnection.Properties property.
The format of these parameters conforms to the usual Delphi standards.
The following new parameters are supported:
\begin{itemize}
\item DateReadFormat
\item DateWriteFormat
\item DateDisplayFormat
\item TimeReadFormat
\item TimeWriteFormat
\item TimeDisplayFormat
\item DateTimeReadFormat
\item DateTimeWriteFormat
\item DateTimeDisplayFormat
\end{itemize}
The ReadFormat parameters decribe the date and time formats as the data\-base sends them to the application.
The WriteFormat parameters describe the date and time formats as the application should send them to the database.
The DisplayFormat settings are used for strings that are supplied by the application to Zeos.
These settings can be used to solve problems on the following drivers:
\begin{itemize}
\item dblib (FreeTDS, mssql, sybase)
\item postgresql
\item mysql (depending on parameter preferprepared, used if preferprepared is not set)
\item ado (emulated parameters, see \ref{sec:Rev4_DriverSpecificChanges_Ado} \nameref{sec:Rev4_DriverSpecificChanges_Ado}, Page \pageref{sec:Rev4_DriverSpecificChanges_Ado})
\end{itemize}

So yes - most parameters relate to parameters in the client library documentation. But not all of them. And sometimes one wants to add a bit of explanation on how Zeos handles this parameter by default.

[Fr0sT]

Just a couple of params... not so much. And descriptions are not too large

[Fr0sT]

I made a little experiment

1. HelpInsight format

Code: Select all

const
  /// <summary>
  ///  Name of a user, same as <c>IZConnection.User</c> property
  /// </summary>
  /// <param name="TYPE"> STR </param>
  /// <param name="DBCs"> MySQL, Oracle </param>
  Prop_UID = 'username';

+ Contents instantly shown in IDE
+ Contents could be easily extracted and post-processed to generate Wiki page
- Text is too overloaded

clipboard.png

2. PasDoc format

Code: Select all

  {**
   Password of a user, same as `IZConnection.Password` property
   @param TYPE = STR
   @param DBCs = MySQL, Oracle }
  Prop_Pass = 'password';

+ Text is more compact
+ Consistent to other Zeos comment style
- PasDoc or a more complex parser is required to generate Wiki page

[marsupilami]

Hello Fr0st,

I made a little experiment

1. HelpInsight format

Code: Select all

const
  /// <summary>
  ///  Name of a user, same as <c>IZConnection.User</c> property
  /// </summary>
  /// <param name="TYPE"> STR </param>
  /// <param name="DBCs"> MySQL, Oracle </param>
  Prop_UID = 'username';

+ Contents instantly shown in IDE
+ Contents could be easily extracted and post-processed to generate Wiki page
- Text is too overloaded

Honestly this feels like abusing the format. <param> is a parameter - not a list of drivers that support something. Also I am not sure if it really helps to have that in help insight.

2. PasDoc format

Code: Select all

  {**
   Password of a user, same as `IZConnection.Password` property
   @param TYPE = STR
   @param DBCs = MySQL, Oracle }
  Prop_Pass = 'password';

+ Text is more compact
+ Consistent to other Zeos comment style
- PasDoc or a more complex parser is required to generate Wiki page

This is different - in a lot of ways. Firstly it supports the help insight comments, that I started to use and insert into Zeos. But then - I am not sure if this really helps users. If I were a user I would expect somthing like this:

General supported Parameters
param1
Decription for param1
param2
Decription for param1
...
firebird supported paramaters
param3
Decription for param3
param4
Decription for param4
...
postgresql supported paramaters
param3
Decription for param3
param5
Decription for param4
...

Even though param3 is suported by postgresql and by firebird, it has its mentioned in both chapters. I am not sure if pasdoc can do that. Hmm...

Anyway - in the end the one who does the work will decide what tools he chooses. Unfortunately I currently don't have the time to do this, so I will not choose any tool.

Has anybody ever tested what happens to our current doxygen documentation comments when using pasdoc? I really would like it if pasdoc could read them.

[Fr0sT]

Hello Jan,

Honestly this feels like abusing the format. <param> is a parameter - not a list of drivers that support something. Also I am not sure if it really helps to have that in help insight.

Well, this is just an example. There could be custom tags that will be ignored by HelpInsight. Although I've tested the popup hint and it could really be helpful to show which kind of values a parameter expects.

If I were a user I would expect somthing like this:

Sure, the form I suggest is just a source data, wiki page could be generated by some tool in more complex kind.

Has anybody ever tested what happens to our current doxygen documentation comments when using pasdoc? I really would like it if pasdoc could read them.

IIRC, I've run PasDoc on Zeos and it worked OK. It supports HelpInsight-style comments.

[aehimself]

I did not disappear, only extremely busy at work and out-of-work too (my private application started to show some unexpected bugs which needed a refactoring of several elements, doh). When I'm not busy the kid is draining my energy SO bad I don't even have the mood to clean the house a little bit...
So stay tuned, I'll get this task done. I only need to catch my breath first...

[aehimself]

This is something I wanted to achieve:

connprop_1.PNG

- Only valid parameters are visible for the specific connection
- Description is displayed about the selected parameter
- Upon editing only valid values can be entered / selected

My solution is a bit customized (depending on other modules of the application) and does not yet include properties for Interbase / Firebird (as I'm not using those at all). Once I have a full list of properties I can post the form .dfm and .pas so others can import it in their applications.

[marsupilami]

Once I have a full list of properties I can post the form .dfm and .pas so others can import it in their applications.

Nice work Maybe we need a new interface in Zeos - IZConnPropertyDescriptor - or something like that

[EgonHugeist]

Awesome! I did some unit refactoring to fullfill Fr0st perfect work accoring the props. So i moved all objects which are related to DBC from core to DBC. Means Fr0st' s ZConnProperties.pas is empty now(same to ZURL.pas), and i lifted all his colleced dbc props up to it's purposed package(except 2 mySQL embedded props), a breaking change i know. But in the past !ME! and others made some design problems. I just added some comments to Fr0st ZDbcProperties.pas with proposals, they are NOT an advice, just a guide. You've free hand guys! Keep up that good work! Open source rocks!

[aehimself]

Ughhh... so instead of 2 units I'll have to import... 10
Well then, I'll wait until your commit appears in Git; seems there's no purpose for me to proceed for the time being.

P.s.: I started to add URL links, so when I click on the "status bar" it'll redirect me to the page explaining deeper what a specific parameter is doing.

[EgonHugeist]

Ughhh... so instead of 2 units I'll have to import... 10

No that wasn't my intention. I moved all constans of (zcore)ZConnProperties.pas into Fr0sT's (dbc)ZDbcProperties.pas.
Two properties:

Code: Select all

  // Type: STR
  // Refer to MySql manual for details
  ConnProps_Datadir = MySQLProp_Datadir;
  // Type: STR
  // Path to library
  ConnProps_Library = MySQLProp_Library;

are refrencing the constants in ZPlainMySQLDriver.pas.
Means !all! properties Fr0sT found (except the firebird "isc_%" ... should we do that too?) which are used in zeos are collected in ZDbcProperties.pas now.

just the comments i added to ZdbcProperties yesterday morning:

Code: Select all

//EH @ Fr0sT and aehimself
//just a proposal which is not related to the docs you guys are planning
//it would be nice to have a PropertyEditor possibility for the DataSet guys
//we could define each prop to a rercord. In initialization part of the
//PropertyEditor unit we could load them into "something"
//much smarter would be to define all records into an static record of TZProperty
//like TZPropertyArray = Array[0..x] of TZProperty = ( ...... add all of them )
//that way a PropertyEditor could access the array directly and we would never
//forget to add that prop to the Editor unit.. would the docs work for array elements too?
//It's just an Proposal
Type
  TZPropertyType = (
    ptEmpty,
    ptBool,
    ptInteger,
    ptString,
    ptBoolOrString);
const
  cProptertyTypeDesc: Array[TZPropertyType] of String = (
    'no value expected',
    'boolean expresson like ''Y''/''YES''/''T''/''TRUE''/''ON''/<>0 in any case to enable, any other',
    'any ordinal number',
    'any string value',
    'either BOOL expression or string value');
type
  PZProperty = ^TZProperty;
  TZProperty = Record
    _Type: TZPropertyType;
    Name: String;
    Porpose: String;
  End;

  TZServerProviders = set of TZServerProvider;
  TZConnProperty = record
    Prop: TZProperty;
    Providers: TZServerProviders;
  end;

const
  ProposalConst: TZProperty = (
    _Type: ptEmpty;
    //add Doc here ?
    Name: 'proposal';
    Porpose: 'do what you want');

const ZPropertiesArray: array[0..1] of TZProperty = (
  (
    _Type: ptEmpty;
    Name: 'proposal';
    Porpose: 'do what you want you have free hand, open your mind (% (:EH'),
  (
    _Type: ptBoolOrString;
    Name: 'Idea';
    Porpose: 'just an idea for the gui guys..... hope it helps, (:EH')
  );

the idea is not complete because some properties are provider speciffic (resolvable for ODBC/OleDB/ADO only if connected) others are protocol releated and finllally some of them are for the datasets/IZStatemennts only(could be resolve by using a SET OF f.e.). So i propose you continue your afford and let's see what happens. According my typos in the example: you can keep them that code is just temporary...

[aehimself]

Sorry, in this case I misunderstood your comment. I thought it's the other way around (to move them from the centralized location to the individual units). My bad.

As for the proposal for the properties tbh I don't like the idea of allowing the user to change the underlying String data. Even if it's a boolean field, he can enter "Igen" (which is Yes in Hungarian for example) and complain later that it does not work. And I know that we have documented restrictions - so as how you should not cross a red light on the street. And we keep doing it. My idea is to take the control out of the hands of the dev, not even to allow something what will not work.

My initial design was something like this:

Code: Select all

TZConnectionProperty = Class
 strict private
  _displayname: String;
  _propertyname: String;
  _help: String;
  _protocol: String;
 strict protected
  PropValue: String;
 public
  Constructor Create(inPropertyName, inDisplayName, inHelp, inProtocol: String); ReIntroduce; Virtual;
  Property DisplayName: String Read _displayname;
  Property PropertyName: String Read _propertyname;
  Property Help: String Read _help;
  Property Protocol: String Read _protocol;
  Property AsString: String Read PropValue;
 End;

 TZConnectionStringProperty = Class(TZConnectionProperty)
 public
  Property Value: String Read PropValue Write PropValue;
 End;

 TZConnectionIntegerProperty = Class(TZConnectionProperty)
 strict private
  Procedure SetValue(Const inValue: Integer);
  Function GetValue: Integer;
 public
  Constructor Create(inPropertyName, inDisplayName, inHelp, inProtocol: String); Override;
  Property Value: Integer Read GetValue Write SetValue;
 End;

 TZConnectionBooleanProperty = Class(TZConnectionProperty)
 strict private
  Procedure SetValue(Const inValue: Boolean);
  Function GetValue: Boolean;
 public
  Constructor Create(inPropertyName, inDisplayName, inHelp, inProtocol: String); Override;
  Property Value: Boolean Read GetValue Write SetValue;
 End;

...and then have an array (or a dictionary) type container for all:

Code: Select all

 TZConnectionPropertyClass = Class Of TZConnectionProperty;

 TZConnectionProperties = Class
 strict private
  _proplist: TObjectDictionary<String, TZConnectionProperty>;
  Function Add(inPropertyClass: TZConnectionPropertyClass; inPropertyName, inDisplayName, inHelp, inProtocol: String): TZConnectionProperty;
  Function GetItems(inPropertyName: String): TZConnectionProperty;
 public
  Constructor Create; ReIntroduce;
  Destructor Destroy; Override;
  Property Items[inPropertyName: String]: TZConnectionProperty Read GetItems; Default;
 End;

The unit was "ready" but then I scrapped it and went for the faster, less versatile way:

Code: Select all

 TConnProp = Record
  PropertyName: String;
  DisplayName: String;
  Help: String;
  HelpURL: String;
  ValidValues: String;
 End;

 PConnProp = ^TConnProp;

...and then just creating a new PConnProp as the Data property of a ListView. My "change" method restricts the options in the appearing window if ValidValues are set (BOOL_DEFVAL = 'True' + sLineBreak + 'False'; INT_DEFVAL = #27; or empty for String) but still nothing stops me from filling the value with anything. I don't like this solution because of this, but it was faster and it works

[aehimself]

Modified my solution to use in-line editors so it's not depending on my application anymore. It does not look pretty because ComboBox simply ignores the height I want it to have. I also added the ImportFrom and an ExportTo methods so it should be able to read and write a ZConnection.Properties stringlist (untested, I'm storing properties differently in my app).

Feel free to check, try, modify or even add it as a property editor of the component (I have no experience in this, don't know how to do it).

Alas, properties are still incomplete.

[Fr0sT]

Michael, hmm, the proposal of using dbc-specific units (especially plain driver units with all the classes declared) in generic ZDbcProperties (which is pure constant unit) seems slightly non-logical to me. Probably we could have separate plain/ZPlainProperties unit only for internal use and copy values from it to ZDbcProperties.
Moreover, if you move all props from core/ZConnProperties.pas to dbc/ZDbcProperties.pas, the test/core/ZTestUrl and ZTestSysUtils should be moved to /dbc as well. Finally, I can't get why TZClientVariantManager was moved, it doesn't seem to use any of the dbc stuff (maybe I'm wrong though).
OTOH, having all props in one place is nice.

Btw, very good way to check correctness of Zeos hierarchy is to rename both dbc and component source folders, comment out ZTestDbc/ZTestComponents in test project and try to build it. Then uncomment dbc and build.