Transcribe from another software

Beginning with version 4.5, TransBar has a "server" function that allows it to be used and controlled from another software.

This online documentation does not replace the commercial documentation that is advised to consult before continuing the technical aspect:

Summary, the TransBar server function

  1. A server? What is the goal?
  2. How does this server work?
  3. How to go further?
  4. Scan or command line?
  5. Transcription by scan
  6. Transcription by command line
  7. Folder "TransBar_Server" and subfolders
  8. Files "TransBar.version" and "TransBar.path"
  9. Instructions files
  10. Command lines for transcription
  11. Case of error in a command line
  12. Process-client number
  13. Transcription parameter
  14. Results
  15. Insurmountable errors
  16. Permanent launching by command line
  17. Permanent launching when starting the computer
  18. Sharing the "TransBar_Server" folder for network access
  19. Executing an instructions file by double-clicking
  20. Evaluation of the server function
  21. Samples of client-softwares

1 - A server? What is the goal?

The "server" function of TransBar allows external software, provided it has previously been specially programmed, to communicate data to code to recover back the corresponding data to print with a barcode font. This data can then be used to print immediately or be memorized next to the original data to be printed when desired.

The external software using TransBar are designated below as "client software".

This function will work in demo mode and degrade the information to be encoded as long as a license for the desired coding has not been purchased and entered in the tab "Manage the licenses of this software".

Back to summary

2 - How does this server work?

To adapt better to the needs and programming possibilities of the "clients" software, the "server" function of TransBar can run in two modes.

The "instant execution" mode requires an installation of TransBar on each client computer. The client software must launch TransBar by a particular command line, which carries some parameters (coding or barcode to obtain, transcription options) and data to code (one or more barcode of same coding). In this mode, whether or not TransBar already launched is irrelevant: an instant execution is immediately launched regardless of any permanent session which will continue to operate in parallel, the results are obtained in a few hundredths of a second in a file, in the clipboard or in the standard StdOut output, then the instant session ends with no window opened or proposed to open.

In "permanent execution" mode, a particular repertory of type "hot folder" is regularly scanned by TransBar looking for instructions files generated by the clients-software. Each instruction file contains a parameter portion and a data to code portion. TransBar responds in very little time for each instructions file, by a results file recorded in a result folder, where the client software can come to exploit it. This "permanent execution" mode can operate on a network (a server computer, one or more clients computers) provided the repertories of instructions and results, located on the server, are accessible to client computers. This mode also requires TransBar be previously launched, which can be done in a particular "single server" configuration dedicated to this purpose or in the traditional configuration "all functions".

Whatever its mode of execution, the server function does not modify the current settings of TransBar and does not take then into consideration: only count the settings transmitted by the instruction file or by command line.

Back to summary

3 - How to go further?

To go further, one must program the client-software, which is the responsibility of the licensee, of its service provider or of its reseller. This programming can be performed in the software and with the computer language of his choice.

A particular screen of TransBar "Program a client of the server" provides:

Some examples of clients developed with common languages are provided to quickly evaluate the solution or serve as concrete examples.

Reading the explanations that follow will however make it possible to better understand the different possibilities open to developers.

Back to summary

4 - Scan or command line?

Two approaches are possible to transmit instructions to the TransBar server function.

Transcription by scanning is the only possible when the client-software development system cannot launch TransBar by command line or if the TransBar and the client-software are not on the same computer, which will be the case if the client-software is not hosted by a Windows or MacOS system. This programming will require the ability to write and read files, a waiting loop of the availability of a file, and a watchdog to associate with this loop to maintain a lack of results. A function to temporarily stop the execution of the client-software will be helpful to let the time to the transcription. TransBar must have previously been launched in permanent execution, which can be done systematically at computer startup or in local server, by an asynchronous command line.

Transcription from the command line is the easiest to program. It requires that the client-software has a function to launch TransBar. If this launch is possible in synchronous mode, it will avoid a waiting loop of the results and the watchdog to associate with this loop to maintain a lack of results; otherwise, a function to temporarily stop the execution of the client-software will be helpful to let the time to the transcription; in the absence of these two functions, the running time may be important.

Back to summary

5 - Transcription by scan

To perform a transcription by scanning, a client software must:

  1. choose a free process number and located within the scope of the number of computers licensed, so in practice a process number per process-client;
  2. determine the name of the expected results file, which will include the process number according to a rule imposed by TransBar;
  3. verify that such a file is not already present in the "TransBar_Server: Results" sub-folder on the computer running TransBar, in which case it must destroy it;
  4. freely determine a final instruction file name, but it is prudent to include the process number in that name;
  5. verify that such a final instruction file is not already present in the "TransBar_Server: Instructions" subfolder located on the computer running TransBar, in which case it will have to destroy it under penalty of forbidding the renaming explained later;
  6. composing in a variable the contents of the instructions file, which will allow the writing of this file by a single call by the network;
  7. determine a transientinstructions file name starting with an Ascii 95 underscore "—" character, in which it is also prudent to integrate the process number. This can be the name chosen for the final instructions file name preceded by the underscore character;
  8. open this transient named file in the "TransBar_Server: Instructions" subfolder, by a function that re-creates or re-initializes it if it already exists;
  9. write the instructions variable in this transient named file, and then close it;
  10. rename this transient named instructions file from the final instructions file name, which will make this file "visible" to TransBar. This renaming ensures that TransBar will not start reading before the file has been closed, which would result in a partial read that causes a structural error or truncated data;
  11. assign to this instructions file the right to be read and written by TransBar. If the renaming did not affect the rights, it would be preferable to carry out this assignment before this renaming, but TransBar is assisted with a posteriori assignment;
  12. if possible, to launch TransBar in permanent session, thus in scanning, which will have no effect if it is already launched. For this, the simplest in local server is an asynchronous command line that will represent only a minimal loss of time if TransBar was already launched. This command line will be given the parameter "-o" for server-only execution, preferable for its speed of execution;
  13. scan the appearance of the results file in the "TransBar_Server: Results" subfolder. This waiting loop may usefully include a command temporarily stopping the execution of the client software to leave processor time to TransBar;
  14. open, read then close the results file. In the case of a multi-lines file, reading it first in a single variable will reduce the transfer time per network;
  15. possibly, destroy the results file to make it clear, but this is not an obligation since this operation will have to be repeated as a precaution to the following transcription.

It is careful:

Despite the habit that developers have of the use of files, transcription by scanning will often prove more complex than the transcription by command line, which it is advisable to consider prioritizing outside network transcription.

Back to summary

6 - Transcription by command line

Most computer languages offer a function to launch an external executable, for example:

Depending on the function or its parameters, the launch will be obtained:

By analogy with the launch by shell (batch files ".bat" or applications "cmd.exe" or "powershell.exe" on Windows, "" application on MacOS) all these processes are grouped by TransBar under the term "Launch by command line".

A command line is traditionally composed of the path of the executable followed by one or more optional parameters separated by the characters "space".
When the path of the executable includes spaces, it is often necessary to enclose it in quotes order Ascii 34.

When launched by command line, TransBar accepts different parameters. Four of them will result in instant server execution. This execution can be achieved in parallel with a permanent execution without link between the two and ends once its job is done.

These four parameters determine both the means of transmitting instructions and data to code:

and the way to get results:

Back to summary

7 - Folder "TransBar_Server" and subfolders

In many cases, the server function uses a particular folder/directory named "TransBar_Server" located on the main disk of the computer that supports TransBar.

This folder is created by TransBar when the operator demand viewing it via one of the links "Server folders" of the screens dedicated to the server function. It is created and should remain in the folder of shared documents between sessions and between applications. It is then accessible from all open sessions on this computer, and, as long as it has been defined as "shared", by any session opened on the internal network.

Three special use subfolders are created at the same time:

The subfolder "Instructions" is required only for transcription by scanning. When present, the scan function is activated as soon as TransBar is started for permanent execution.

The other two sub-folders, if deleted, will be recreated automatically by TransBar as soon as they become necessary.

Back to summary

8 - Files « TransBar.version" and « TransBar.path"

Four utility files are created or updated by TransBar, in the "TransBar_Server" folder, at each launch for permanent execution.

The file named "TransBar.version" stores the current version and sub-version number of TransBar in ASCII text format. It is provided for all purposes.

Three files store the path of the TransBar executable, each in a different encoding:

The path to the TransBar executable may vary, either as a result of a subsequent change to the installation, or as a result of an update to the executable. Being a constant path, the "TransBar.path" files will allow the client-software to acquire the current path of the TransBar executable and send it a transcription order per command line.

In the absence of accented characters in the paths, the single-byte files will be identical, but there is no guarantee that this absence of accented characters will be maintained in the future.

Under MacOS, the path stored by these files is that of the real executable, which is inside the "package" suffixed ".app".

Back to summary

9 - Instructions files

An instructions file must be obtained in text format in one of the following encodings:

and with one of the following end of lines:

It will include a minimum of 4 lines:

  1. the first will be composed of the keyword "§TransBar". This word and the end of the line that follows it will define:
    • the encoding of this file and the end-of-line used subsequently;
    • the encoding and end-of-line used by TransBar for the results.
    When the client-software language makes it possible to choose the encoding and end-of-lines of the files that it creates and reads, these elements must not be neglected, even if the instructions file does not carry most often accentuated chars, because it will perhaps not so for the results file. In UTF-8 encoding, the character "§" is a bit special: it is obtained by two bytes 194-167, which, if viewed as Windows Latin 1, would display "§". When an encoding header Byte Order Mark (BOM) is provided, it must be placed at the beginning of the first line and will be at the same place in the results file;
  2. the second line stores the client-process number that will determine the transcription method used by the server (operational or demonstration or error) and the name of the results file;
  3. the third line defines the transcription parameter. When the server execute an instructions file, it use the values of this parameter without changing the current settings of the operator interface of TransBar;
  4. the fourth line will store the first data to code.

Each following line will take another data to code.

If an end of line or, more generally, a non-displayable ASCII character must be included in data to code, it must be included as "§xx" where xx is the Ascii value to obtain.

An incorrect value in any of the first two lines of an instructions file leads to discontinuation of this file and a file structure error in the TransBar history.

Back to summary

10 - Command lines for transcription

Four command-line parameters induce an instant execution when followed by the secondary parameters they expect.

The parameter "-p" (Ascii 112) expects as second parameter the path of an instructions file that can be located anywhere (typically in the temporary folder) to provide a results file in the subfolder "TransBar_Server: Results".
This path must not be enclosed in quotes; it may include spaces, which should therefore not be replaced by "§32". When this solution is coupled with a launch in synchronous mode, it has the advantage on a transcription by scanning not request waiting loop, with the disadvantage of a response time higher than a scan in permanent only server.

The parameter "-f" (Ascii 102) expects four secondary parameters followed by data to code to provide a results file in the subfolder "TransBar_Server: Results".
The second parameter is the client-process number that will determine the transcription method used by the server (operational or demonstration or error) and the name of the results file.
The third parameter must be significant to the encoding of the results file.
The fourth parameter must be significant to the end of line char to use in the results file.
The fifth parameter is the transcription parameter which determines the coding and transcription options.
Each of the following parameters is a data to code.
This solution simplifies the previous in that it avoids the writing of an instructions file.

The parameter "-s" (Ascii 115) expects three secondary parameters followed by data to code to provide the results in the standard output StdOut.
The second parameter must be significant to the encoding for the output file.
The third parameter must be significant to the end of line char to use in the results file.
The fourth parameter is the transcription parameter which determines the coding and transcription options.
Each of the following parameters is a data to code.
This solution simplifies the previous in that it avoids reading a results file when stdout is available in return of the launch function.

The "-c" (Ascii 99) parameter expects a secondary parameter followed by data to code to provide the results in the clipboard.
The second parameter is the transcription parameter which determines the coding and transcription options. Each of the following parameters is a data to code.
This solution compensates the previous when standard output is not available in return of the launch function. Encoding and line-end character of the results are automatically standardized by the clipboard.

If a data to code transmitted by command line contains characters "space", "quote", "end of line" or non-printable Ascii characters, they must be expressed as "§xx" where xx is the Ascii value to obtain.

Every first parameter must be composed of the char "minus" (Ascii 45) followed by the lowercase letter. Every following parameter must be separated from the preceding by a "space" character (Ascii 32). When several data to code are transmitted by a single command line and one of these data is blank, it is advisable to express it by the character "§" to avoid that two contiguous "space" characters in the command line be reduced to one by the transfer function.

Examples of command lines are provided by the button "Obtain an example" of the screen "Program a client of the server".

Back to summary

11 - Case of error in a command line

When a command line appears in default in its first parameters, and whatever the validity of the data to code:

The client-software must guard these cases.

When the results are desired in a file (parameter "-p" or "-f"), the client-application must have previously checked that an identical file name is not already present, then:

When the results are desired in the standard StdOut output (parameter "-s"), the application-client must therefore:

When the results are desired in the clipboard, the application-client must have previously initialized the clipboard to a no-virgin known value then:

Back to summary

12 - Process-client number

The process-client number is only necessary when the results are to be obtained in a file. It will be integrated by TransBar in the name of this file to allow different client-softwares to intervene at the same time without confusing their results.

If this number is higher:

the transcription will be obtained depending on the setting of the tab "Transcribe from another software: Set the server function":

Back to summary

13 - Transcription parameter

The transcription parameter included in each instruction file and in each transcription command line is composed as follows:

In some cases, these five characters may be followed by other characters indicating the expected options. In order to obtain the parameter adapted to a specific case, it is therefore preferable to adjust TransBar's unit transcription on this case and then to obtain the transcription parameter from the "Obtain an example" menu of the screen "Program a client of the server".

Back to summary

14 - Results

The results will be the same whether obtained in a file, standard StdOut output or clipboard.

Each data to code in an instructions file or in a command line brings a line of data to print; a blank data to code brings a blank line result.

In a file or standard StdOut output, encoding and line breaks included in the instructions will be renewed.

In the clipboard, encoding and end of line breaks will be those of the default operating system.

When a data to code can not be transcribed, the corresponding result line will take one of the following:

or start with:

TransBar guarantees that a valid data to print never starts with the capital letter "E"; the client-software can simply check the first letter of a result row to react as it wants if "E", which always means an invalid data to code.

Back to summary

15 - Insurmountable errors

When a transcription error occurs (for example, when a character of the information to be coded is not acceptable), this error is transferred to the result and its processing is left to the care of the client-software.

But, when an error occurs without the form of the results (file, StdOut output or clipboard) or the name of the results file can be determined, this error is stored by TransBar to be displayed in an error history window.
If the origin of the error is a file received in the "Instructions" subfolder, TransBar attempts to move it to the "Errors" subfolder; if it does not succeed, it stops its scan to avoid recording a new error with each new scan, then immediately displays the error history window with a "locking error". This locking concerns only the scanning, the operator functions remaining available and executions in instantaneous server remaining possible in parallel.

In other cases, the functioning of the server can be ensured, a display of the error history will be obtained according to the preference recorded in the corresponding menu of the tab "Transcribe from another software: Set the server function" :

Back to summary

16 - Permanent launching by command line

Three command-line parameters will launch TransBar - as long as it did not already - in permanent session bypassing the choice previously made by the operator in the tab "Transcribe from another software: Set the server function".

The "-a" parameter (Ascii 97) will launch TransBar in permanent all functions execution. Its main window will always be displayed but may or may not stay behind according to the launch function used by the client-software.

The parameter "-w" (Ascii 119) will launch TransBar in permanent server only execution with pre-signaling timed window. If TransBar is already running and a window is forwarded, this window will not be the pre-signaling window. This launch is to be executed:

The "-o" parameter (Ascii 111) will launch TransBar in permanent server only execution without pre-signaling timed window. This launch may be renewed by the client-software on each request of a scanning transcription, with the only cost of a slight waste of time.

Two other parameters can sometimes be useful.

The "-r" parameter (Ascii 114) will launch TransBar accordance with the mode selected in the tab "Transcribe from other software". This setting is not useful on Windows, where it is mistaken for a lack of parameter. On MacOS, depending on the function launching the command line, a lack of parameter can sometimes lead to error; in this case, adding the parameter "-r" to the executable path will exceed this error.

The "q" parameter (Ascii 113) will force TransBar to quit a permanent execution. On MacOS, depending on the function launching the command line, this parameter may have no effect; it must then be replaced by an Apple Event Class "aevt" with identifier "quit" and target "fr.transbar.transbar".

A command line can receive only one parameter, which must be composed of the sign "minus" (Ascii 45) followed by the lowercase letter.

All corresponding command lines:

Back to summary

17 - Permanent launching when starting the computer

TransBar can be launched automatically when the computer starts up to constantly scan its instructions folder.

On Windows:

On MacOS:

Back to summary

18 - Sharing the "TransBar_Server" folder for network access

On Windows, the "TransBar_Server" folder is created by TransBar in the shared documents folder. The basic setting ensures the visibility of this folder and the items it stores from all the stations on the network. However, it may be necessary to resume this setting:

On MacOS, the "TransBar_Server" folder is created by TransBar in the "Shared" user space. This space, this folder and its subfolders are obtained with extended read and write rights for all users of the computer, ie for all sessions, but it is necessary to share them voluntarily for make them accessible on the network. For it :

It would also be possible to share only the folder "TransBar_Server", but this share would be lost in case of destruction-reconstruction of this file.

Back to summary

19 - Executing an instructions file by double-clicking

TransBar considers instruction files as documents. It is therefore possible to execute such a file by double-clicking it, provided that the extension of its name has been declared in connection with TransBar in the operating system.

When a sample instructions file is obtained from the screen "Program a client of the server" of TransBar, the extension for its name is ".transbar_instructions". This extension is not required and can be replaced by any other of your choice, but it is better to avoid the common extensions of type ".txt", ".text" if the client-software allows it.

To associate a file extension with TransBar:

Back to summary

20 - Evaluation of the server function

The server function of TransBar can be evaluated quickly by the "Xojo" client example available in English and French, Windows and MacOS.
In the absence of the necessary licenses, this evaluation will only allow you to obtain demonstration barcodes (always the same) and not the barcodes you want.
It can also, even without a license, be evaluated in detail, and even entirely adapted to a given problem, to obtain a set composed of your client-software and TransBar, in which it will be sufficient, once validated in all points, including response time, to enter the TransBar license keys to obtain an operational set, providing the desired variable barcodes.

The number of client-processes is not limited in an unlicensed operation, which makes it possible to evaluate multi-client architectures. However, this facility entails the risk of unintentionally obtaining a degraded results file in production due to a process-client number greater than that permitted by the licenses entered in TransBar.

Two methods make it possible to avoid this:

Back to summary

21 - Samples of client-softwares

Some examples of client-softwares are available in free of rights of use languages, allowing, in addition to performing them, to consult sources for inspiration or to suit a particular need.

The "Xojo" example, very complete, supplied as cross-platform Basic and executable, is particularly recommended for demonstrating or evaluating all the possibilities of the server function of TransBar.

Excel and OpenOffice/LibreOffice spreadsheets, calling TransBar by a built-in VisualBasic macro, are directly usable.

Back to summary