Compiler Directive: Append

As of 2007 January, Append has been added to SiMPLE's list of compiler directives. (Compiler directives are non-executable statements that tell the compiler to perform certain operations. In SiMPLE, compiler directives are similar to keywords in that they always begin with an upper-case letter.)

As its name implies, Append allows you 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).

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 that contains program listing files.

*[Be aware that the Project folders that you create in "Drag & Drop" mode are
completely separate from the Projects that exist in the "Command-Line" mode.]

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 an (optional) library folder (named "LIBRARY") that resides inside a project. [The name "LIBRARY" is case insensitive, so any form of the name ("Library", "library", etc.) can be used.]

Every program in a project can append any library file from the Local Library in that project.

[If you are using SiMPLE in "Command-Line" mode, every project that you create (by using the "GO" command) has an empty Local Library folder already installed for you. But you will need to use DOS commands to access it. (For example, to create/access a file named "mytask" you might have to type something like: edit library\mytask.txt)]

The Global Library

The Global Library contains task (or function) modules which can be accessed by any program in any project. 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 in a folder named "LIBRARY" located right inside your "SiMPLE" folder. In the "LIBRARY" folder you will find a subfolder named "Pro" and another named "Ultra". Your modules should be placed either in the "Pro" folder or in the "Ultra" folder depending on whether they are intended to be used in the Pro-SiMPLE universe or in the Ultra-SiMPLE universe* (respectively). If your modules are intended to be used in either the Pro-SiMPLE universe or in the Ultra-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 "Pro" and "Ultra" folders
because all of the programs in a project are intended to be used in either one universe or the other.]

A "System" Folder

As you start creating one project after another, you are eventually going to need some place to put all of them (unless you want to end up having a very cluttered Windows desktop!) So just create a new folder, and then dump all of your Project folders into it! We will refer to this new folder as a "System" folder.

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

The general forms for using the Append compiler directive are:

Append L: module
Append U: module
Append P: module
Append E: module

where
"L:" indicates that module is located in the Local Library
"U:" indicates that module is located in the Global Library's "Ultra" subfolder
"P:" indicates that module is located in the Global Library's "Pro" 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 Pro-SiMPLE or Ultra-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 "Pro" or "Ultra" compiler directive at the beginning of your program listing automatically determine which of the two library's subfolders ("Pro" or "Ultra") 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 "D" drive, you would specify: "Append A: D:\mystuff\module.txt")

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

Let's Make It Happen! (...An Example)

We'll start by creating a Project folder (let's name it "Test") on our desktop. (You know the routine: Right-click, select "New", etc.)

Next, we'll create the project's Local Library folder inside the "Test" folder.

Now create a New Text Document in the "Library" folder, and then copy & paste the following listing into that new document:

Task Listing

When you are done, change the name of the text document to "face"

Our "face" task is now in the Local Library and ready to be used.

We will now write a program that calls the "face" task. Create a "New Text Document" in the "Test" folder, and then copy & paste the following listing into that new document:

Program Listing

(Notice that, when using "Drag & Drop" mode, you should never specify a handle after the "@" when calling a task in an append library, because the task has not yet been compiled.)

When you are finished, it is not necessary to rename the "New Text Document" (unless you want to). Just drag & drop it onto the "Drop SiMPLE Listing Here" icon.

Another Example

The Global Library contains an "Either/Or" module named "CODER.TXT" which allows you to encrypt/decrypt secret messages. Try running the following short program:

Task Listing

Some Final Words...

An Append does not actually modify your copy of the source listing. The appended text is brought in just long enough to compile your program, and then your listing is restored to its original form.

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. (However, even though libraries can contain an unlimited number of modules, no more than a total of 16 are allowed to be appended to any one program.)

A word of caution: When adding a new task/function listing to a library, be very careful that the name of the tasks/function does not conflict with the names of the tasks/functions that are already in the library!

Also, care must be exercised when appending tasks/functions 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.

In conclusion, the Append compiler directive offers only a crude capability for producing libraries, and there are limitations as to how they can be used. Still, it is a useful and fun feature to experiment with. However, anyone who is seriously interested in producing general purpose libraries should consider using SiMPLE's PUT command (available only in Command-Line mode) for making compiled libraries.


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