SIMPOL Documentation

A SIMPOL program starts with one or more source files that are either in some ANSI 8-bit character encoding or else in Unicode (specifically in the pure 2-bytes per character form, not yet supporting windowing using aggregates). Unicode files should begin with a byte-order mark (BOM) in the form of Unicode character FEFF. If the data in the source file is in big endian (most significant byte first) order (typical for the Macintosh, Amiga, Atari ST, and other operating systems that are running or began on computers based on the Motorola CPU's starting with the MC68000) then the BOM must also be written in the big endian style, as FEFF. If the data is stored in little endian order, then the BOM must be written as FFFE. If the data is in Unicode and there is no BOM then the compiler will try to guess by analyzing the input. Files saved using the SIMPOL IDE will always have the correct BOM for Unicode files. Non-Unicode files do not have this issue, but have the problem that the 8-bit encoding of the source may not be interpreted in the same way on another computer or operating system if any characters above character value 127 are used.

Source files stored in ANSI format are typically stored with the extension sma. Those stored in Unicode format are stored with the extension smu. These extensions are not mandatory, but are recommended for interoperability with others and with any tools that may be created that may depend on the file name extensions. Source files stored by SIMPOL IDE's will always be stored in little-endian order even on big-endian operating systems.

A compiled program in SIMPOL typically ends with the extension smp. Another type of compiled SIMPOL program is a module. Unlike a program, a module does not have a main() function. It is pre-compiled and can either be loaded at runtime using the system function !loadmodulefile() or it can be concatenated onto the end of a compiled SIMPOL program in a type of static linking. Module files are normally given the extension sml. The SIMPOL IDE is designed to allow for both static and dynamic linking (whereby the dynamic onking is done by the SIMPOL program when it needs to load a module, not by some loader). This allows the greatest amount of flexibility when designing complex programs using SIMPOL since modules can be written to be reused by other programs and therefore do not have to be compiled into every single program that uses them. It also allows components to be compiled only when their source files have changed and means that not every component must be compiled into one monolithic program. This will result in faster compile times.

One important issue that is related to storing reusable functionality in separate modules is that of scope and visibility. Unless expressly exported in the source code, user-defined types and functions are not visible outside of the module. To make them visible, add the export keyword to the end of the function or type declaration as shown below:

type mytype1(mytype) embed export
  string ID embed
  type(mytype) next
end type

type mytype2(mytype) embed export
  string ID embed
  type(mytype) next
  integer index embed
end type

function getid(type(mytype) t) export
end function t.ID

Debugging information comes in various flavors. In SIMPOL we have reserved the extension smd for files that store debugging information as part of the compilation process. These files are not yet in use at the time of writing, but will be used in the future. Another extension that is in use currently is slg. This is a file that is created when an error occurs while running a SIMPOL program using one of the debug versions of the loader, either the standard loader file or the CGI version. When an error occurs, the debug versions of these programs will output a file of the same name as the program that is executing, but with the file name extension slg. This file will contain the error message and error number together with the reconstructed source code of the function with an indicator as to which line contained the problem.