SQL FILE CODE COMMENTS (READ-ME)

SQL-File Technology web-page (index, instructions, etc.):
https://handicraft.remelias.ru/sdk/sql_file.html
See also:
— "SQL-project-list.txt";
— "SQL\Programming samples (SQL-file)\SQL-file-plain-samples.[ReadMe].txt".

Here are listed folders which are concerned significant in relation to use of SQL-File Technology.
Also some remarks concerning to organization of corresponding code are provided (SQL-file command utilities, samples, auxiliaries etc.).

Inside Handicraft-SDK file tree:

"HandicraftSDK" — root folder

*** MAIN FOLDERS UNDER THE ROOT (SQL-FILE FOUNDATION DETAILS): ***

"Auxiliary programs (sources)" — little projects of utilities (C#, C++)
[[
* "Command line" — C# projects for command line utilities located in "CMD-utilities" folder;
* "Far plugins" — tiny CPP-project of CmdCpAuto.dll (Far Manager plugin in the "Utilities" folder).
]]

"CMD-utilities" — $-commands (command-line): $sqltrans.cmd, $sqlupload.cmd, $sqltocsvexp.cmd, …
Each command prints its syntax being invoked without parameters (e.g. from Windows Explorer).
[[
* "Assemblies" — binary subprograms for $-commands: SqlCatPP.exe, SqlToCsvExport.exe, ConfirmationPause.exe, TypeInColor.exe, … ;
* "Shell" — auxiliary CMD (+instructions), for integration with Far Manager etc.
]]

"SQL" — SQLAUX library + samples (SQL-file)
[[
* "Programming samples (SQL-file)" — six simple samples in Enhanced T-SQL (SQL-projects – demos), are provided with corresponding "!ReadMe.txt";
* "SQLAUX" — scripting library (SQL, CMD) that is usually imported and consumed by typical SQL-file project.
See documentary header files (source view) and DB-object list (SQLAUX scripting lib.):
https://handicraft.remelias.ru/sdk/sqlaux/sqlaux_cmdsettings_txt.html — Source view(s) (SQL-file technology | Handicraft-SDK);
https://handicraft.remelias.ru/sdk/sql_file.html#sqlaux_programmatics — DB-object list (SQL-file technology | Handicraft-SDK).
* "Extralight-ORM test legacy sample (En+Ru)\MyFlat app. (MVC_Razor+TS+ADO+TSQL)" — advanced bilingual sample with SQL-file use:
ASP queries are in English (C#), and SQL-files are in Russian (SP in Enhanced T-SQL, with Cyrillic, contain English comments).
SQL-project is located in "SQL (DB-modelling)" subfolder.
THIS IS ADDITIONAL, ADVANCED SAMPLE.
]]
See also (EXTERNAL "BookRegistry app." etc.):
https://handicraft.remelias.ru/sdk/sql_file.html#samples (Samples (SQL-file) | Handicraft-SDK);
https://handicraft.remelias.ru/csweb/client_server_web.html (Client-Server.WEB (idea) | Handicraft-CODE).
The second reference is about "BookRegistry app.", that is an extra in relation to SQL-file technology (as for its complete SQL-project collection).
This is so-called EXTERNAL sample, i.e. not included into the SDK (not contained in "Handicraft-SDK"-only download).
It is available as additional download or a as part of full "Handicraft-CODE" pack (named as "Handicraft Toolkit").
=== SQL-file projects in "BookRegistry app." (from "Handicraft Toolkit"): ===
"BookRegistry\SQL (DB-modelling)": SQL-project base (tables, app.invisible subqueries);
"BookRegistry\SHARED\$ClientServer\!DB-queries (application SP)": application queries, C#/SQL side-by-side.
(Handicraft Toolkit download reference resides at the Handicraft-CODE home page: https://handicraft.remelias.ru/.)

"Utilities" — key utilities and miscellaneous auxiliaries
[[
* "Far plugins\CmdCpAuto plugin, build 100 (Far v3)" — CmdCpAuto, Far Manager plugin for automatic code-page selection in the embedded Far Editor,
when CMD/BAT file is being opened for editing (normally by F4-key).
Folder contains plugin DLLs (for x64/x86) and minimal instructions/comments in TXT
(about plugin behaviour and its installation into "%ProgramFiles%\Far Manager\Plugins" folder).
]]
See corresponding web-page (Utilities and other auxiliaries | Handicraft-SDK):
https://handicraft.remelias.ru/sdk/utilities_n_aux.html;
https://handicraft.remelias.ru/sdk/utilities_n_aux.html#cmdcpauto_in_folders_img;
https://handicraft.remelias.ru/sdk/utilities_n_aux.html#cmdcpauto_far_editor_img.


*** HOW TO INSTALL SQL-FILE (HANDICRAFT-SDK): ***

Installation is performed manually, this implies reading of following pages (1st reference is required to read):
https://handicraft.remelias.ru/sdk/sql_file_install.html (SQL-file installation | SQL-file technology | Handicraft-SDK);
https://handicraft.remelias.ru/sdk/sql_tools.html (SQL-tools | CMD-utilities | Handicraft-SDK);
https://handicraft.remelias.ru/sdk/sql_file.html (SQL-file technology | Handicraft-SDK).


*** SQL-TRANSLATION ($SQLTRANS-COMMAND ORGANIZATION): ***

SQL-translation in SQL-file is performed via $SQLTRANS command ("HandicraftSDK\CMD-utilities\$sqltrans.cmd"):
https://handicraft.remelias.ru/sdk/sql_tools.html#sqltrans — $SqlTrans command (SQL-tools | CMD-utilities | Handicraft-SDK);
https://handicraft.remelias.ru/sdk/sql_tools.html#sqltrans_syntax_print_img — $SQLTRANS syntax print (SQL-tools | CMD-utilities | Handicraft-SDK).

SQL-translation ($SQLTRANS command) is a compound operation.
Its main phases (internal steps) are listed below, but this is a brief explanation.
For deeper understanding in details it is recommended to look into CMD script-code of the utility ("HandicraftSDK\CMD-utilities\$sqltrans.cmd").

Stages of SQL-translation (internal steps):

1) "$sqltrans.cmd" receives SQL file names (or pattern) as parameter(s);

2) "$sql_settings.cmd" is called (if exists) from current translation folder, for the sake of environment preparation;

3) "SqlCatPP.exe" is invoked in order to form concatenated and lightly preprocessed SQL-source(s),
resulting SQL source is placed into "%TEMP%\$SQLTRANS\<datetime-stamp>.sql", in user profile temp. file store;
date and time stamp is used for temporary file naming;

4) "SQLCMD.EXE" (SQL Server command-line utility) is invoked by "$sqltrans.cmd", to execute earlier prepared SQL-source from %TEMP% folder,
SQL output TXT is places near into the same folder with same base name (as for the temporary SQL-script),
or into the current folder (if output report filename is specified for "$sqltrans.cmd" call).

Also $SQLTRANS may only prepare settings environment (SQL-settings variables generation), being called as:
— call $SQLTRANS "(SettingsOnly)" (in user defined command of complex SQL-translation);
— call $SQLTRANS "[SettingsOnly]" (invocation from "SSMS.cmd", IDE starter).
In addition to user defined commands, in settings-only mode it is used in "SSMS.cmd", that is advanced starter of the official IDE,
SQL Server Management Studio, so it is launched with a set of prepared environment variables, from the SQL-project (for parameterized SQL).
Environment preparation is initiated by "$sql_settings.cmd" (from the same folder as for SSMS.cmd),
which in it’s turn usually invokes "@<project_name>.cmd" (SQL-project settings in UTF-8 encoding, without BOM).


*** OTHER COMMANDS (SQL-FILE, $-CMD FROM "CMD-utilities" FOLDER): ***

"$sqlupload.cmd" — SQL-uploading command,
it is based on "bcp.exe" (one of SQL Server command-line utilities) and "$sqltrans.cmd" (to execute "$pre_upload.sql" and "$post_upload.sql" scripts).
Data are uploaded to SQL Server from text files (are specified through parameters for "$sqlupload.cmd").

"$sqltocsvexp.cmd" — simple data extraction command,
it is based on "SqlToCsvExport.exe", ADO.NET subprogram from "CMD-utilities\Assemblies" subfolder.
This utility simply saves SQL result-sets (one or more) into corresponding CSV.

"$confirmpause.cmd" — confirmation pause,
simple console mode dialog: "Press either <Enter> to continue or <Escape> to cancel . . . ".

"$typeincolor.cmd" — colored print of text file content:
This command is used by $SQLTRANS, to print SQL-error in red color, output text file from SQLCMD (SQL execution result/report).

FOR MORE INFORMATION PLEASE LOOK AT CORRESPONDING UTILITY SYNTAX PRINT
($-COMMANDS FROM "CMD-utilities" FOLDER AND EXE-SUBPROGRAMS FROM "CMD-utilities\Assemblies\…" SUBFOLDERS)!

See also: https://handicraft.remelias.ru/sdk/sql_tools.html (SQL-tools | CMD-utilities | Handicraft-SDK).

— — —