Tag Archives: module

HMG-IDE In Short

Posted on by vivaclipper

HMG-IDE Harbour MiniGUI Integrated Development Environment is a comprehensive and highly sophisticated project management utility. It is also extremely facilitated to easily use.

It’s possible to build and manage an entire project from scratch under this utility; without needing cryptic batch command ( .bat ) file, without interesting endless compiler / linker switches, etc.

HMG-IDE is more than a project maker :

  •  A clever form editor
  •  A database files ( Tables ) manager
  •  A report builder / editor

HMG-IDE_InShort

HMG-IDE come as two flawor : ANSI and Unicode versions. Dont worry about it, this two version works almost exectly same; only difference is Unicode supoort. You may use either depending on either your need to Unicode or not.

HMG-IDE has four part :

– Control Panel : This main window is constituted on a menu bar and a tool box, having many command buttons with descriptive tool tips.

– Project Browser : You can view, select and inspect all project elements in this window. henever you add or exclude a project element (module (program source file), form, resource, report …), IDE automatically updates the project browser.

– Object Inspector : This window is for view and change properties and events of GUI elements in your forms.

– Form design board : A chalk board for designing forms and directing its graphical elements.

 

Quick Start to Migration

Posted on by vivaclipper

Chapter I – Text to text conversion

In Clipper world, “migration” means “convert a DOS based Clipper program to Windows”. This is a dream of every Clipper – DOS programmer.

 Before all, we need clarify some terms:

May be found multiple ways for convert a DOS based Clipper program to Windows. In general, DOS programs are runs in “text” mode and Windows program runs in “Graphic” mode; and this is what meant by term “migration”.

Converting a text mode program to directly GUI (Graphical User Interface) is a painful job. First, we need to find a Compiler with GUI support, or a GUI library usable with a specific compiler. If we have more than one opportunity ( yes, it is so ) we need make a choice between them.

For make a right selection we need learn, understand specialties of each option and differences between them.

Believe me, this is an endless way 😦

Instead, let’s begin with simpler thing: convert a DOS text mode program to Windows text mode program.

Question: Without GUI, what meaning will be to migrate from DOS to Windows?

Answer: Good question and like all good question, answer isn’t easy.

First, modern OSs moves away day to day from DOS conditions; memory problems, screen problems, codepage problems, etc… By the time, building / running 16 bit executable becomes more difficult day to day.

Whereas Harbour already is a 32 / 64 bit compiler.

Second, all DOS Compilers for Clipper are commercial and registration required products; furthermore they are almost out of sold for this days; what compiler you could use?

And third, Harbour is best free compiler and the best way to use a free GUI tool for xBase language.

So, beginning with using Harbour in text mode is the best start point, I think.

First step is downloading and install HMG or Harbour. If you didn’t past this step yet please refer previous articles in this section or “Links” page of this blog.

The easiest way for using Harbour compiler is calling hbmk2, the wonderful project maker for Harbour compiler.

Depending your installation, hbmk2 may be in different locations; such as C:\Harbour\bin or c:\hmg\harbour\bin or anything else.

Hereafter I will assume that your hbmk2 is in C:\hmg\Harbour\bin. If your installation is different, please modify above examples.

Second step is assign an empty folder (directory) for work / test affairs; say C:\test.

And the third step is copying your Clipper program(s) to this folder.

But don’t rush; we have some precautions:

– Better way is starting with a single-program project; if you haven’t written a new one. Don’t uses for now projects have multiple program file.

 – Your program may have some “national” characters and these characters may be differently shown between DOS and Windows. If so, you may want fix manually these differences via a Windows based text editor. Or use a program if you have one. Harbour has a clever tool (HB_OEMTOANSI() function) is usable for this purpose.

 – In Clipper it’s possible a program file without module (procedure / function) definition. If you have such file(s), enclose your code with PROCEDURE — RETURN statement pair.

– Every Harbour project must have one and only one MAIN module (procedure / function). The first procedure / function in your single program file will be considered as MAIN module of your project. (In HMG, name of this module must be “main” also).

– Almost all Clipper commands, statement, functions, pseudo functions, manifest constants etc are usable almost in the same ways with Clipper. May be exist some very few and very rare differences, and of course solving methods for its.

For compile process we will use command box (DOS / console window) of Windows. You can open a console window, with the menu Start -> Run -> cmd or selecting it in the “Command Prompt” from the Start Menu \ All Programs.

 – “Command / console window” size may not appropriate for easy use. You may

      – use a MODE ( DOS ) command :

         MODE CON LINES=54 COLS=148

       or

   – adding a SetMode() statement at the beginning of MAIN module of your project. For example:

       SetMode( 25,  80 )  // 25 line 80 column same as standard 
                           // DOS screen ( but not full screen ! )
       SetMode( 48, 128 )  // 48 line 128 column, may be more readable

Now, we are ready to begin: Enter this command in console window :

 C:\hmg\harbour\bin hbmk2 <mainPrgName>

You don’t need any SET command (such as PATH etc) before this command; hbmk2 will find all necessary paths / files.

For running executable after compile, add a -run switch to the command line :

 C:\hmg\harbour\bin hbmk2 <mainPrgName> -run

Of course, you need supply name of your main .prg file in place of <mainPrgName>.

Note that you don’t need a separate “linking” step; hbmk2 will do everything for you.

You may use this

 C:\hmg\harbour\bin hbmk2 <mainPrgName>

command via a batch ( .bat ) command file (such as “build.bat”) too. In this way you can apply compiling process without console window; run .bat file by double click in the Windows Explorer. In this case you may need add a PAUSE command at end of .bat file.

That’s all.

You know, a program file may contains more than one module (procedure / function). So you may develop your project by adding new modules to your single program file.

In this step you don’t need trying extra features, extensions of Harbour. Before that adventure your primary need is to convert existing project Clipper to Harbour.

When you reach a level of multiple-program file project:

– Basic rules are the same: the first module in the your program file is MAIN module of your project.

If your .prg files contains:

  SET PROCEDURE TO <procedure_File_Name>

 and / or

   #include <procedure_File_Name>

 you may or may not continue using these statement.

 – The shortest way for compiling a multiple-file project is use a .hbp ( Harbour Projet ) file. This is a text file and its simplest form is a file contains list of your .prg files. For example:

myprog01.prg
myprog02.prg
myprog03.prg
myprog04.prg

and the compile command is the same :

  C:\hmg\harbour\bin hbmk2 <mainProjectFileName>

In this case you don’t need to use SET PROC… and #include … statement and this is the better way.

Because hbmk2 applies “incremental” compiling, that is compiles only modified files.

Under normal circumstances, any module in any program file is callable in anywhere in the project. If you have some modules that exclusive to this program file, you may use STATIC keyword at the beginning of PROCEDURE / FUNCTION statement. For example:

STATIC FUNCTION OpenTable()

With this syntax you will prevent calling this module outside of this .prg file and the possibility of using this module name into other .prg files.

Example :

Take “A typical Harbour Program” in the “Harbour Sample” page.

As seen at .pdf file by given link, this sample program borrowed from official reference guide of a Clipper compiler. That is, in fact this is a Clipper program and it will may compile with Harbour and run without any modification.

Let’s try.

– Copy and paste this sample and save in your PC with a name say “typical.prg”.

– Comment out the line for now.

 #include "Database.prg" // Contains generic database functions

– Call hbmk2:

 C:\hmg\harbour\bin hbmk2 typical -run

 Note: While working / playing on programs, you may encounter some error messages like:

  Error F0029  Can't open #include file xxx
  Error E0002  Redefinition of procedure or function xxx
  Error: Referenced, missing, but unknown function(s): xxx
  undefined reference to HB_FUN_xxx

 Please don’t panic !

    “Error” is salt and pepper of programming play ! 😉

 The worst situation isn’t getting error, but is unable to stay !

   The “HB_FUN_xxx” may be seen weird at first meet. The “HB_FUN_” is a prefix given by system ( compiler ) to your function; so you need search erroneous point into tour program files without this prefix.

Now, let’s continue to our “typical” program:

If you compile the program with commented out #include … line, possibly it will work, by opening main menu:

Typical_1

But what’s that?

When selected a menu item (except “Quit”) we can’t see other than an empty screen!

Again, don’t panic!

This situation too is not very rare !

If you use vertical scroll bar of command / console window, you will notice that your screen is considerably much longer than seen !

To avoid this conflict, ( as stated above ) we need use a SetMode() function call at top of our Main() procedure ( but AFTER LOCAL statement ! ) :

  SetMode( 24, 79 )

 And now everything is OK.

Typical_2

In fact, not really everything, we have a few “fine adjustment”.

Cut and paste the section after “// Database.prg” to a separate “Database.prg” file, un-comment the “#include …” line and then re-compile.

In this case we have a “multiple prg” project. As stated earlier, better way is using a .hbp file instead of “#include …” statements.

Now comment out ( or delete now ) the #include line.

Build a new text file with name “typical.hbp” and with this content :

Typical.prg
DataBase.prg

And recall hbmk2 without any modification :

C:\hmg\harbour\bin hbmk2 typical -run

That’s all !

Congratulations !

Now you have a multiple-prg project  !

Linker Terms

Posted on by vivaclipper

Dynamic Overlay :

Allows a module’s code to be divided into pages to be brought into and out of memory on a least recently used basis.

Freeformat :

The suggested command interface for .RTLink, allowing you to specify linker commands in any order on the command line. It is easier to create, examine and change FREEFORMAT command lines. It is compatible with the Plink86-Plus syntax.

Group :

An Intel 8086 addressing classification defining a collection of segments to be addressed using the same segment register. Note that a group is not a section but rather a logical concept used only for addressing.

Incremental Linking :

The ability to link only the modules of an application that have been changed, greatly increasing the speed in which the link occurs.

See Also: Linking, Module

Library :

A file containing one or more object modules. Modules are extracted by linker and combined with object files to form an executable (.EXE) file or a prelink library (.PLL) file.

Linking :

The process in which object files and libraries are combined and references are resolved to produce a relocatable memory image (generally, an executable).

Map File (.MAP) :

The map file (.MAP) contains information about symbol and segment addresses within the memory image created by .RTLink. It is generated when requested through the use of the appropriate command line switch. A map file generated during a link will have much more information than one produced during the creation of a prelinked library. During the .PLL creation, only symbols, names, and some relative addresses are known. During a link, the final memory layout is known, and a more detailed map can be created.

Module :

A portion of the object code that is a discrete unit. If any part of a module is linked, the entire module must be linked.

Overlay :

A section of an executable program that shares memory with other sections of the same program. An overlay is read into memory when the code residing in it is requested by the root (nonoverlayed) section or another overlay.

See Also: Dynamic Overlay

Positional :

The POSITIONAL command interface requires that certain items appear on the input line in a specific order. This syntax is similar to Microsoft LINK interface. Because this syntax limits the use of .RTLink overlays to one overlay area, it is recommended that the FREEFORMAT syntax be used.

Prelinked Library :

Part of the executable program that is stored external to the .EXE file. Prelinked libraries are created before producing an executable in a multistep link. This allows you to create a runtime library with code that you access from different programs, considerably speeding up the linking process.

Root :

A special section of the program that has the lowest address of all sections. This is the first section of the program loaded into memory by DOS or the RTLINKST.COM startup code. Other sections are loaded by the overlay manager.

Section :

Load module portion of an .EXE or .OVL file loaded into memory as a single unit. In a program with overlays, the root section containing the main program module loads when the program is executed. Other sections are loaded as overlays when modules within them are invoked.

See Also: Dynamic Overlay, Linking

Segment :

Code or data handled by the linker as a indivisible unit.

Static Overlay :

A section of the program that is not always resident in RAM, and shares memory with other sections. The section that is currently in use is loaded into memory, allowing a larger program to execute in less available RAM.

Swapfile :

Also known as the workfile, used by .RTLink to swap data and code in and out of memory during the linking process.

Symbol :

An assigned name for a value representing a constant or the address of code or data. There are four types of symbols used by the linker defined as follows:

. Absolute symbol: a constant

. Relative symbol: address of code or data

. Public symbol: accessed by modules other than the module in which they are defined. Public symbols are used to share procedures and variables between modules. As such, the relative address of a public symbol is assigned by the compiler during compilation.

. External symbol: a public symbol not defined in the current module. Generally, these are references into CLIPPER.LIB or EXTEND.LIB, but the compiler generates them whenever there is a procedure or user-defined function referenced but not compiled into the current module.

Undefined Symbol :

An unresolved symbol) that was never declared public by a module, but which is referenced by another module. After the public symbol definition is encountered, the symbol becomes defined (resolved). When a symbol is referenced, but not defined, it is said to be undefined.

Workfile :

See : Swapfile

Modular Programming Terms

Posted on by vivaclipper

Data Independence :

The technique of writing a program, function, or procedure in such a way that it will be able to perform its operation on data supplied to it without a built-in description of the data format.

Encapsulation :

Generically, the design of a function or program that obeys the principle of information hiding. A function or program is said to be encapsulated if other programs or functions have no knowledge of its inner workings. A data structure is said to be encapsulated if knowledge of its internal organization is limited to a single function or module.

See Also: Information Hiding, Lexical Scoping, Modularity, Side Effect

Hidden :

The resulting state of a module of a program written to conform to the principals of information hiding.

See Also: Information Hiding

Modularity :

Roughly, a measure of a system’s adherence to the principles of modular programming. The principles of modular programming are not precisely defined, but may be said to comprise these basic ideas: programs should be organized as well-defined modules; modules should correspond with syntactic units of the programming language (such as functions or source files); a module should accomplish a well-defined task; a module should interact with as few other modules as possible; interactions between modules should be explicitly specified in the source code for the modules; modules should obey the principle of information hiding.

See Also: Encapsulation, Information Hiding, Lexical Scoping, Side Effect

Module :

Generically, a procedure or function (or a set of related procedures and functions) that can be treated as a unit. Sometimes used to refer specifically to the code in a single object file, normally the result of compiling a single source file.

See Also: Object File, Program File

Side Effect :

An unexpected effect of executing a function or program. When a function changes the state of a system in a way that is not explicitly specified by the function’s name or calling protocol, the change is called a side effect. Reliance on side effects is contrary to the principles of modular programming.

See Also: Encapsulation, Information Hiding, Lexical Scoping, Modularity