Converters

About Converters

Converters allow GCBASIC to read files that have been created by other programs. A converter can convert these files into GCBASIC libraries, or any GCBASIC instruction, or a GCBASIC dataset.

A typical use case is when you have a data source file from another computer system and you want to consume the data within your GCBASIC program. The data source file could be a database, graphic, reference data, or music file. The converter will read these source files and convert them into a format that can be processed by GCBASIC. The conversion process is completed by an external application, which can be written by the developer, or you can use one of the converters provided with the GCBASIC release.

The GCBASIC release includes converters for BMP files and standard text files.

With an appropriate converter installed, and an associated #include to these non-GCBASIC files, GCBASIC will detect the file extension and hand the processing to the external converting program. When the external converting program has completed, GCBASIC will then continue with the converted source file as a GCBASIC source file.

An example of a converter is one that reads an existing picture file, converts the picture file to a GCB table, and then refers to the picture file’s table to display the picture on a GLCD.

Conversion is achieved by including a command within the source program to transform external data. The command used is the #include instruction, followed by the data source. An example: 

    'Convert ManLooking.BMP to a GCBASIC usable format.

    #include <..\converters\ManLooking.BMP>

The inclusion of the #include line within a GCBASIC program will trigger the following process:

  1. GCBASIC will examine the ..\converters folder structure for a configuration file that will handle the file extension specified in the include statement.
  2. GCBASIC will examine the configuration file(s) *.INI for command line instructions.
  3. GCBASIC will then examine the folder structure for the source file and the target transformed file. If the source file is older than the transformed file, the next step will not be executed; go to step 6.

  4. GCBASIC will execute the command as specified within the configuration file to transform the source file to the target file.

    The conversion program must create the output file with the extension specified in the configuration file. If the include statement has an extension of .TXT, and the configuration file states the input file extension as .TXT and the output as .GCB, the converted file must have the extension .GCB. 

    #include <..\converters\ManLooking.BMP>

    If the ini file specifies the input as BMP and the output as GCB, then the expected file is ..\converters\ManLooking.GCB.

  5. GCBASIC will attempt to include the transformed target file (with the file extension as specified in the configuration file) within the GCBASIC program.
  6. GCBASIC will resume normal processing of the GCBASIC program, including the transformed target file, and therefore normal compiling and error handling.

For example programs see here.

More about Converters

  1. The configuration file

    The configuration file MUST have the extension .INI. No leading spaces are permitted in the configuration file. Specification of the configuration file. The file has these items: desc, in, out, and exe. Where: 

    desc         : Is the description shown in GCGB
in           : Is the source file extension to be transformed
out          : Is the target transformed file extension.
exe          : Is the executable to be run for this specific configuration file.
params       : Optional, the required parameters to be passed from the compiler. Example:  params = %filename% %chipmodel%
deletetarget : Optional, will always recreate the target transformed file. The default is to retain the target transformed file unless the source has changed. Options are Y or N

    You can have multiple configuration files within the ..\converters folder structure.

    GCBASIC will examine all configuration files to match the extension specified in the #include command.

    Example 1:

    The BMP (Black and White) conversion configuration file is called BMP2GCBasic.ini. The source extension is .bmp, the transformed file extension is .GCB, and the executable is called BMP2GCBASIC.exe. 

    desc = BMP file (*.bmp)
in = bmp
out = GCB
exe = BMP2GCBASIC .exe

    An example:

    #include <..\converters\ManLooking.BMP>

    Will be converted by BMP2GCBASIC.EXE to ..\converters\ManLooking.GCB

    Example 2:

    The data file conversion configuration file is called TXT2GCB.ini. The source extension is .TXT, the transformed file extension is .GCB, and the command line called is AWKRUN.BAT. 

    desc = Infrared Patterns (*.txt)
in = txt
out = GCB
exe = awkrun.bat

    An example:

    #include <..\converters\InfraRedPatterns.TXT>

    Will be converted by AWKRUN.BAT to ..\converters\InfraRedPatterns.GCB

    This example would require a supporting batch file and a script process to complete the transformation.

  2. Conversion Executable

    The conversion executable may be written in any language (compiled or interpreted).

    The conversion executable MUST create the converted file with the correct file extension as specified in the configuration file.

    The conversion executable will be passed one parameter - the source file name. Using example 1, the conversion executable would be passed ..\converters\ManLooking.BMP.

    The conversion executable MUST create a GCBASIC-compatible source file. Any valid commands/instructions are permitted.

  3. Installation

    The INI file, the source file, and the conversion executable MUST be located in the ..\converters folder. The converters folder is relative to the GCBASIC.EXE compiler folder.

Example 3: Converter Program

This program converts InfraRedPatterns.TXT into InfraRedPatterns.GCB, which will have a GCBASIC table called DataSource. This example is located in the converter folder of the GCBASIC installation. 

  #chip 16f877a, 16
  #include <..\converters\InfraRedPatterns.TXT>

  dir portb out

  ' These must be WORDs as this could be a large table.
  dim TableReadPosition, TableLen as word

  dir portb out

  ' Read the table length
  TableReadPosition = 0
  ReadTable DataSource, TableReadPosition, TableLen          ' <<< reading the table length stored at position 0


  Do Forever
      For TableReadPosition = 1 to TableLen step 2
          ReadTable DataSource, TableReadPosition, TransmissionPattern
          ReadTable DataSource, TableReadPosition+1 , PulseDelay
          portb = TransmissionPattern
          wait PulseDelay ms
      next
  Loop

Key line: ReadTable DataSource, TableReadPosition, TableLen — the converter stores the pattern count as the first entry of the generated DataSource table, so the program reads it once at position 0 before looping over the actual transmission/delay pairs that follow.

Example 4: Dynamic Import

This program converts a chip-specific configuration file into manifest.GCB, which will have GCBASIC functions called DataIn and DataOut. This example is located in the converter folder of the GCBASIC installation. 

    #chip 16f18326

    #include <..\converters\manifest.mcc>

    DataOut ( TX, RA0 )  'this method is created during the convert process. It does not exist without the converter.
    DataIn  ( Rx, RC6 )  'this method is created during the convert process. It does not exist without the converter.

This example would use the optional parameters params and deletetarget in the converter configuration file, as follows: 

    desc = PPS file (*.PPS)
    params = %filename% %chipmodel%
    in = mcc
    out = GCB
    exe = DataHandler.exe
    deletetarget= y

Example 5: Add Build Numbers and Time/Date Details to Your Programs

This converter is used to expose two string variables, as follows:

    GCBBuildStr
    GCBBuildTimeStr

The user code is simple. Using the #include statement, specify any filename with the extension .cnt. As follows: 

    #include "GCBVersionNumber.cnt"

Complete code would look like this - this is not optimised, and simply shows the use of the exposed strings.

    #include "GCBVersionNumber.cnt"

    dim versionString as string * 40
    versionString = "Max7219 build"+GCBBuildStr
    versionString = versionString + "@"+GCBBuildTimeStr
    Print versionString

This outputs the following, where 20 is the current build number and the date/time is correct for the build time.

    Max7219 build20@01-06-2021 08:00:21
    Commence main program

This works because the supporting INI file instructs the compiler to call a utility that automatically creates a build number tracker file and the supporting string functions. The utility creates a tracker file and the method files in the same folder as your source program, so each tracker is specific to each project. The converter requires the following files - these are included with your installation. 

    GCBVersionStamp.exe - the utility called by the converter capability.
    cnt2gcb.ini - the supporting ini file used by the compiler to handle this converter.

See Also:

  • #include — the directive that triggers conversion
  • ReadTable — reading a converted table, as used above
Prev  Up  Next
  Home