Compiler Directive: Append


[Note: This webpage is intended for users of SiMPLE.]

Click Here to Read About SiMPLE


A compiler directive is a non-executable statement that tells the compiler to perform a certain operation. In SiMPLE, compiler directives are similar to keywords in that they always begin with an upper-case letter.

As its name implies, Append tells the compiler to temporarily append text files (i.e., listings) from a specified append library onto the end of your program listing file*, just as if you had copied and pasted those lines of text by hand.

*The appending is done in a "virtual" manner (i.e., to a temporary copy of your source listing). If you
later examine your original source listing, you will see that nothing in it has actually been changed.

What Is An "Append Library"?

An append library is simply a folder containing text files (usually referred to as "modules"), each of which is a task (or function) listing.

(During the remainder of this discussion, we will refer to "append libraries" as simply "libraries".)

Projects

As you probably already know, a project is simply a folder (inside your "SiMPLE Projects" folder) that contains program listing files.

Project folders provide a convenient way or organizing your programs into groups of commonality. If two or more of your programs all need to access the same tasks (or functions), just put the programs into a Project folder, and put the required task (or function) listings into the project's Local Library folder.

Local Libraries

A Local Library is merely a folder named "Library" that resides inside a project folder. Every program in a project folder can append any source listing file from the Local Library in that project.

The Global Library

The Global Library contains task (or function) modules which can be accessed by any program in any project folder. In other words, if several of your programs in different projects need to access the same tasks (or functions), just put the required task (or function) listings into the Global Library folder.

The Global Library is a folder named "Library" located on your root directory along with your "SiMPLE" folder. In the "Library" folder you will find a subfolder named "Dos" and another named "Win". Your modules should be placed either in the "Dos" folder or in the "Win" folder depending on whether they are intended to be used in the Dos-SiMPLE universe or in the Win-SiMPLE universe* (respectively). If your modules are intended to be used in either the Dos-SiMPLE universe or in the Win-SiMPLE universe, they should be placed directly in the "Library" folder itself rather than in one of the two subfolders.

*[Unlike the Global Library, the Local Library does not contain separate "Dos" and "Win" folders because
all of the programs in any given project folder are intended to be used in either one universe or the other.]

The "SiMPLE Projects" Folder

The "SiMPLE Projects" folder is merely the place where you store all of your project folders.


How To Make It All Happen... The Append Compiler Directive!

The general forms for using the Append compiler directive are:

Append L: module
Append W: module
Append D: module
Append E: module

where
"L:" indicates that module is located in the Local Library
"W:" indicates that module is located in the Global Library's "Win" subfolder
"D:" indicates that module is located in the Global Library's "Dos" subfolder
"E:" indicates that module is located directly inside the Global Library fol-
        der itself (rather than inside one of the Global Library's two subfolders)
        and can therefore be used with either Dos-SiMPLE or Win-SiMPLE
and
"module" specifies the name* of the library module to be appended.

*[It is not necessary to include the ".txt" extension when specifying the name.
But whatever name you choose must be no more than eight alpha-numeric characters
in length (not counting the extension). No spaces are allowed anywhere in the name.]

When appending modules from the Global library, you can also use:

Append G: module

which will let the "Dos" or "Win" compiler directive at the beginning of your program listing automatically determine which of the two library's subfolders ("Dos" or "Win") is to be used for appending the module.

One other form of the Append compiler directive is also available. If the module to be appended is at some arbitrary location, you can use:

Append A: path

to specify an Absolute path to the file. (For example, if you wanted to append a file named "module.txt" from a folder named "mystuff" on your "F" drive, you would specify: "Append A: F:\mystuff\module.txt")

Append compiler directives can appear anywhere in your program listing, but it is customary to place them at the very end.


Adding Your Own Modules to the Global Library

If you would like to add your own modules to the Global library, just place them into the proper subfolders (either the "Dos" folder or the "Win" folder) in the "Library" folder. Or if your modules can be used by either Dos-SiMPLE or Win-SiMPLE programs, you can place your modules directly into the "Library" folder itself. However . . .

It can become a little confusing if you have to remember which of your modules require an "Append W:", which require an "Append D:", which require an "Append E:", and which require an "Append G:" compiler directive when you invoke those modules from your main program.

To simplify matters, we suggest the following: If a module is intended for use by either Dos-SiMPLE or Win-SiMPLE programs, place that module into either the global "Library" folder itself, or into its "Dos" subfolder, or into its "Win" subfolder (but not into all three). Then, in the other two folders, create separate dummy modules that merely append the first one.

For example, the Global library's "coder" task is intended for use by either Dos-SiMPLE or Win-SiMPLE programs. So if you look at the "CODER.TXT" modules in the "Dos" folder and in the "Win" folder, you will see that they each consist of nothing more than an "Append E: coder" statement. (I.e., they merely append the "CODER.TXT" listing from the "Library" folder.)

If you handle your modules in this fashion, you can then properly append any modules in the Global library by using only the appropriate "Append G:" compiler directives at the end of your main program listings. (I.e., you can completely forget about whether you should use an "Append W:", an "Append D:", or an "Append E:" directive when appending a Global library module to a program. )

Unlike the Insert compiler directive, Appends are allowed to be cascaded. This means that the Append compiler directive can appear not only in the listing for the main program, but also in any of the library modules that are being appended (as was implied in the above discussion). However, even though libraries can contain an unlimited number of modules, no more than a total of 256 are allowed to be appended to any one program.

A word of caution: When adding a new module listing to a library, be very careful that the names of its tasks/functions do not conflict with the names of the other tasks/functions that are already in the library!

Also, care must be exercised when appending modules that use Common statements. If two unrelated tasks each declare the same (but functionally different) names to be in the common area, a conflict is sure to arise.


Some Final Words...

An Append does not actually modify your copy of the source listing. (You never see any of the appended lines of code.) The appended text is brought in just long enough to compile your program. Then, when the compilation is finished, all of the appended information is removed, and your source listing is restored to its original form.

In conclusion, the Append compiler directive offers only a somewhat crude capability for producing libraries, and there are limitations as to how they can be used. Still, append libraries are useful in that they provide the ability of easily viewing the source listing of any module in the library... an especially important feature if you are using modules that somebody else wrote. (No chance for a virus to be hidden away. )



  [ Webmaster | FAQ's | Home Page | Contact Us ]