R-6: COMPILER DIRECTIVES & OBJECT HANDLING The following section refers to the Blitz Compiler Directives, commands which affect how a program is compiled. Conditional compiling, macros, include files and more are covered in this chapter. Information regarding control of Blitz Objects is also listed in this section. Objects are Blitz's way of controlling speicalised data concerned with windows, shapes etc. USEPATH Pathtext USEPATH allows you to specify a 'shortcut' path when dealing with NEWTYPE variables. Consider the following lines of code: aliens()\x=160 aliens()\y=100 aliens()\xs=10 aliens()\ys=-10 USEPATH can be used to save you some typing, like so: USEPATH aliens() \x=160 \y=100 \xs=10 \ys=-10 Whenever Blitz encounters a variable starting with the backslash character ('\'), it simply inserts the current USEPATH text before the backslash. BLITZ The BLITZ directive is used to enter Blitz mode. For a full discussion on Amiga/Blitz mode, please refer to the programming chapter of the Blitz Programmers Guide. AMIGA The AMIGA directive is used to enter Amiga mode. For a full discussion on Amiga/Blitz mode, please refer to the programming chapter of the Blitz Programmers Guide. QAMIGA The QAMIGA directive is used to enter Quick Amiga mode. For a full discussion on Amiga/Blitz mode, please refer to the programming chapter of the Blitz Programmers Guide. INCLUDE Filename INCLUDE is a compile time directive which causes the specified file, Filename, to be compiled as part of the programs object code. The file must be in tokenised form (de: saved from the Blitz editor) - ascii files may not be INCLUDE'd. INCDIR may be used to specify a path for Filename. Filename may be optionally quote enclosed to avoid tokenisation problems. XINCLUDE Filename XINCLUDE stands for exclusive include. XINCLUDE works identically to INCLUDE with the exception that XlNCLUDE'd files are only ever included once. For example, if a program has 2 XINCLUDE statements with the same filename, only the first XINCLUDE will have any effect. INCDIR may be used to specify a path for Filename. Filename may be optionally quote enclosed to avoid tokenisation problems. INCBIN Filename INCBIN allows you to include a binary file in your object code. This is mainly of use to assembler language programmers, as having big chunks of binary data in the middle of a BASIC program is not really a good idea. INCDIR may be used to specify an AmigaDos path for Filename. Filename may be optionally quote enclosed to avoid tokenisation problems. INCDIR Pathname The INCDIR command allows you to specify an AmigaDos path to be prefixed to any. filenames specified by any of INCLUDE, XINCLUDE or INCBIN commands. Pathname may be optionally quote enclosed to avoid tokenisation problems. CNIF Constant Comparison Constant CNIF allows you to conditionally compile a section of program code based on a comparison of 2 constants. Comparison should be one of '<', '>', '=', '<>', '<=' or'>='. If the comparison proves to be true, then compiling will continue as normal. If the comparison proves to be false, then no object code will be generated until a matching CEND is encountered. CEND CEND marks the end of a block of conditionally compiled code. CEND must always appear somewhere following a CNIF or CSIF directive. CSIF "String" Comparison "String" CSIF allows you to conditionally compile a section of program code based on a comparison of 2 literal strings. Comparison should be one of '<', '>', '=', '<>', '<=' or'>='. Both strings must be quote enclosed literal strings. If the comparison proves to be true, then compiling will continue as normal. If the comparison proves to be false, then no object code will be generated until a matching CEND is encountered. CSIF is of most use in macros for checking macro parameters. CELSE CELSE may be used between a CNIF or CSIF, and a CEND to cause code to be compiled when a constant comparison proves to be false. CERR Errormessage CERR allows a program to generate compile-time error messages. CERR is normally used in conjunction with macros and conditional compiling to generate errors when incorrect macro parameters are encountered. Macro Macroname Macro is used to declare the start of a macro definition. All text following Macro, up until the next End Macro, will be included in the macro's contents. End Macro End Macro is used to finish a macro definition. Macro definitions are set up using the Macro command. Runerrson These two new compiler directives are for enabling and disabling error checking in different parts of the program, they override the settings in Compiler Options. Runerrsoff See description of Runerrson. Use Objectname Object# Use will cause the Blitz object specified by Objectname and Object# to become the currently used object. Free Objectname Object# Free is used to free a Blitz object. Any memory consumed by the object's existence will be free'd up, and in the case of things such as windows and screens, the display may be altered. Attempting to free a non-existent object will have no effect. USED ObjectName Used returns the currently used object number. This is useful for routines which need to operate on the currently used object, also interrupts should restore currently used object settings. Addr Objectname(Object#) Addr is a low-level function allowing advanced programmers the ability to find where a particular Blitz object resides in RAM. An appendix at the end of this manual lists all Blitz object formats. Maximum Objectname The Maximum function allows a program to determine the 'maximum' setting for a particular Blitz object. Maximum settings are entered into the OPTIONS requester, accessed throuh the 'COMPILER' menu of the Blitz editor.