Please enable JavaScript to view this site.

A-Shell Reference

Subroutines written in BASIC are much easier to develop and deploy, and thus BASIC will most likely be the language of choice for most future subroutines development. However, there are a couple situations where BASIC may not be the best choice. One is where the subroutine performs some low-level, execution-intensive, performance-critical function. Obviously, subroutines written in C (and compiled to machine code and then linked directly into the A-Shell executable) will execute more efficiently, both in the calling overhead and in the instruction execution cycle. This is probably not a major issue, since A-Shell executes so fast. But if you were writing a routine to, say, convert from ASCII to EBCDIC or even to sort an array, it would probably be noticeably quicker in C. (Fortunately, we already offer subroutines written in C for both of those functions.)

The second situation where BASIC is at a disadvantage in subroutine development is where the subroutine needs access to internal A-Shell data structures or functions. However, in most of those cases, specialized knowledge of the data structures or functions is needed anyway, and thus we would be the most logical one to develop such routines. So this probably isn’t much of a practical restriction for developers in the field either.

There is another difference between the way the two types of subroutines execute, but it isn’t obvious whether it is an advantage or a disadvantage. In the case of subroutines written in C, they execute as "true" subroutines, meaning completely within the calling process. In fact, there is very little difference between a BASIC function, such as INSTR() and an equivalent subroutine written in C. They both consist of a single run-time opcode token followed by a list of parameters, and they are both implemented internally in C, and execute completely within the execution environment and stack of the calling program.

Subroutines written in BASIC, on the other hand, are loaded from disk (unless already in memory) and executed in a separate, temporarily allocated memory space. They are still part of the original process and original job, but they have a separate stack and separate BASIC environment, which starts from scratch at the start of the subroutine, just like it does when you CHAIN to a new program. It is in fact very similar to what happens when you use xcall AMOS,"RUN xxxxx" (provided the OPTIONS=AMOS_RUNSBR setting is present in miame.ini). The most obvious consequence of this is that regardless of how badly the subroutine screws up, there are only two ways it can abort the calling program. One is by explicitly calling a particular MIAMEX function (discussed below under "Use End to Return to Calling Program..."). The other is by crashing A-Shell itself, since the subroutine is running in the same instance of the A-Shell executable as the calling program was. (But we’d like to think that crashing A-Shell is more or less impossible, so we don’t need to dwell on this possibility!) Otherwise, regardless of how the subroutine ends, either gracefully or otherwise, it will release its resources and the calling program will resume at the next statement. Be sure to read the following topic on Error Trapping, which relates closely to this topic.