APPENDIX A: Predefined Constants The SPP language includes a number of predefined symbolic con- stants and macro definitions. These allow SPP programs to use keyword names for commonly used values. Included are various machine dependent constants describing the hardware and data types. Other symbolic constants are used for basic file I/O. All predefined constants are of type integer. The include files described here are automatically included when an SPP pro- gram is compiled. Language Definitions The value of these definitions may vary from one machine and host operating system to another. SPP code using the symbolic constants need not be modified, however, when porting software. The include file defining these macros is hlib$iraf.h. However, it is included implicitly by xc and the definitions are available at all times. You do not need to include it explicitly. Generic Constants Constant Meaning ------------------------------------------------------------------------ ARB Arbitrary; array dimension BOF Beginning of file BOFL Beginning of file EOF End of file EOFL End of file EOS End of string EOT End of tape ERR Error status return NO Opposite of YES (int flag) YES Opposite of NO (int flag) OK Status return, opposite of ERR NULL Invalid pointer --------------------------------------------------------------------- Table A.1: Generic Constants. Data Type Sizes These macros define the sizes of the fundamental SPP data types in units of char, the smallest addressable word. Macro Size Defined --------------------------------------------------------------------- SZ_BOOL Number of chars per bool SZ_CHAR Number of chars per char SZ_SHORT Number of chars per short SZ_INT Number of chars per int SZ_LONG Number of chars per long SZ_REAL Number of chars per real SZ_DOUBLE Number of chars per double SZ_COMPLEX Number of chars per complex SZ_POINTER Number of chars per pointer SZ_STRUCT Number of chars per struct SZ_USHORT Number of chars per ushort SZ_FNAME Maximum number of chars in a file name SZ_LINE Maximum number of chars in a line SZ_PATHNAME OS dependent file name size SZ_COMMAND Maximum size of command block --------------------------------------------------------------------- Table A.2: Sizes of SPP Data Types. Data Type Codes The data type codes are used, for example, in dynamic memory alloca- tion, in which it is necessary to know how many bytes each value occupies. The sizes are in units of chars, where a char usually occupies two bytes. The lines shown Example A.1 will allocate a short and double buffer, each of size elements. The resulting memory buffers will consist of different numbers of bytes, but will logically contain the same number of elements. Example A.1: Using Data Type Codes. Code Data Type --------------------------------------------------------------------- TY_BOOL Boolean TY_CHAR Character TY_SHORT Short integer TY_INT Integer TY_LONG Long integer TY_REAL Single precision real TY_DOUBLE Double precision real TY_COMPLEX Complex TY_POINTER Pointer TY_STRUCT Structure TY_USHORT Unsigned short integer (for image I/O only) TY_UBYTE Unsigned byte (for image I/O only) --------------------------------------------------------------------- Table A.3: Data Type Codes. File and Image I/O The macros described in this section are used in accessing text files, binary files, and images. File Types The file type specifies the kind of file to be read or written. Macro File Type --------------------------------------------------------------------- TEXT_FILE Plain text (ASCII) BINARY_FILE Binary, host dependent DIRECTORY_FILE Directory STATIC_FILE SPOOL_FILE Internal, no permanent location RANDOM SEQUENTIAL --------------------------------------------------------------------- Table A.4: File Types. File I/O Modes The mode parameters are used on opening the file and specify the man- ner in which the file will be accessed. Parameter I/O Mode --------------------------------------------------------------------- READ_ONLY Read only, no output READ_WRITE Read and write WRITE_ONLY Write only, no input APPEND Append to an existing file NEW_FILE New file TEMP_FILE Temporary file, deleted at task end NEW_COPY Copy of an existing file NEW_IMTE Alias for NEW_FILE NEW_STRUCT NEW_TAPE --------------------------------------------------------------------- Table A.5: File I/O Modes. I/O Streams Stream Name Contents --------------------------------------------------------------------- CLIN Standard input of the physical task CLOUT Standard output of the physical task STDIN Standard input STDOUT Standard output STDERR Standard error STDGRAPH Standard graph (usually a graphics terminal) STDIMAGE Standard image (usually an image display) STDPLOT Standard plot (usually a hardcopy plotter) --------------------------------------------------------------------- Table A.6: I/O Streams. The following example (Example A.2) opens two files. The first state- ment opens for reading an existing text file whose name is specified in the char variable fname. The second statement opens a new image whose name will be the string in imname. Example A.2: Opening Files. Indefinites Indefinite values may be used to flag data for specific purpose, to exclude from further consideration or indicate an error, for example. Each SPP data type has its own indefinite value. The actual value of the various indefinites may be different, so the appropriate one must be used. In addi- tion, there are macro functions to test values against INDEF. Values Value Data Type --------------------------------------------------------------------- INDEFS Short integer INDEFL Long integer INDEFI Integer INDEFR Single precision real INDEFD Double precision real INDEFX Complex INDEF Alias for INDEFR --------------------------------------------------------------------- Table A.7: Indefinite Values. Logical Functions These macros (Table A.8) define functions to test values against indefi- nite. There is a macro for each SPP data type. Example A.3 shows how to execute a block of code in the case where a particular value is indefinite. Function Data Type --------------------------------------------------------------------- IS_INDEFS() Short integer IS_INDEFL() Long integer IS_INDEFI() Integer IS_INDEFR() Single precision real IS_INDEFD() Double precision real IS_INDEFX() Complex IS_INDEF() Alias for IS_INDEFR() --------------------------------------------------------------------- Table A.8: Logical Functions. Example A.3: Executing Code with INDEF Values. Pointer Conversion These macros are used for pointer conversions in data structures. Since all dynamically allocated arrays share the same memory (implemented by Fortran COMMON and EQUIVALENCE), the correct offset to data types hav- ing different word sizes must be computed. These macros perform that computation. Note that there is no P2I or P2R since these are assumed to be the same size according to the Fortran standard. See "Macro Defini- tions" on page 16 for more discussion of SPP macros. Macro Purpose --------------------------------------------------------------------- P2C() Convert pointer to character P2S() Convert pointer to short integer P2L() Convert pointer to long integer P2D() Convert pointer to double precision real P2X() Convert pointer to complex --------------------------------------------------------------------- Table A.9: Pointer Conversion Macros. The following example from lib$gio.h is part of the definition of the gio data structure that maintains information about a plot. It defines (among other things) a string containing a label format. This is stored in a dynamically allocated char array. Example A.4: GIO Data Structures. Machine Parameters These macros relate to values specific to the host system architecture. These are defined in hlib$mach.h and must be included with the fol- lowing statement if they are to be used in code: include Parameter Contents --------------------------------------------------------------------- SZB_CHAR Machine bytes per char SZB_ADDR Machine bytes per address increment SZ_VMPAGE Page size (1 if no virtual memory) MAX_DIGITS Maximum digits in a number NDIGITS_RP Number of digits of real precision NDIGITS_DP Number of digits of precision (double) MAX_EXPONENT Maximum exponent, base 10 MAX_EXPONENTR Maximum exponent for single precision real MAX_EXPONENTD Maximum exponent for double precision real --------------------------------------------------------------------- Table A.10: Machine Parameters. Extreme Numbers Parameter Contents --------------------------------------------------------------------- MAX_SHORT Largest short integer MAX_INT Largest integer MAX_LONG Largest long integer MAX_REAL Largest single precision real; anything larger is INDEF MAX_DOUBLE Largest double precision real NBITS_BYTE Number of bits in a machine byte NBITS_SHORT Number of bits in a short integer NBITS_INT Number of bits in an integer EPSILONR Smallest e such that 1 + e > 1 EPSILOND Double precision epsilon EPSILON Alias for EPSILONR --------------------------------------------------------------------- Table A.11: Extreme Numbers. Byte Swapping Is byte swapping needed for a 2 or 4 byte MII integer or a 4 or 8 byte IEEE floating to convert to or from MII format on this machine? Parameter Contents --------------------------------------------------------------------- BYTE_SWAP2 Byte swap 2 byte MII integer? BYTE_SWAP4 Byte swap 4 byte MII integer? IEEE_SWAP4 Byte swap 4 byte IEEE integer? IEEE_SWAP8 Byte swap 8 byte IEEE integer? IEEE_USED Use IEEE? --------------------------------------------------------------------- Table A.12: Byte Swapping Boolean Parameters. Mathematical Constants Definitions of various mathematical constants are in hlib$math.h. Use the following statement to use the macros: include Values (listed in Table A.13) are given to 20 decimal places and therefore may be assigned to real or double variables without loss of precision. However, note that they are not explicitly double precision, in certain expressions in which implicit data type conversion occurs may result in truncation of precision. The definitions are from Abramowitz and Stegun, Handbook of Mathematical Functions, Chapter 1 [Abramowitz65]. Constant Value --------------------------------------------------------------------- SQRTOF2 E EXP_PI LN_2 LN_10 LN_PI LOG_E PI TWOPI FOURPI HALFPI SQRTOFPI RADIAN RADTODEG DEGTORAD GAMMA LN_GAMMA EXP_GAMMA --------------------------------------------------------------------- Table A.13: Mathematical Constants. Most of these are constants, except for the macros RADTODEG and DEGTORAD which convert between degrees and radians. For example the following procedure converts angles in an array from radians to degrees: Example A.5: Converting Radians to Degrees. Note that one might alternately use a vops procedure to accomplish the same result. Character and String-Related Definitions Character Types These macro definitions (Table A.14) test whether a single character (type char) is a member of a particular class of characters, lower case let- ter or white space, for example. They resolve to a logical (bool) value which may be used in boolean expressions, including conditional state- ments such as while or for. They are defined in lib$ctype.h and, if they are to be used in code, must be included with the statement: include Macro Definition --------------------------------------------------------------------- IS_UPPER() Upper case letters (A-Z)? IS_LOWER() Lower case letter (a-z)? IS_DIGIT() Numeral (0-9)? IS_PRINT() Printable character (!-~)? IS_CNTRL() Control character (CTRL-A - CTRL-_)? IS_ASCII() ASCII character (values 0-127 decimal)? IS_ALPHA Alphabetic character (A-Z or a-z)? IS_ALNUM() Alphanumeric character (A-Z, a-z, or 0-9)? IS_WHITE() White space (space or tab)? TO_UPPER() Convert to upper case TO_LOWER() Convert to lower case TO_INTEG() Convert character to digit TO_DIGIT() Convert numeral to ASCII value --------------------------------------------------------------------- Table A.14: Character Types. Note that these definitions work for ASCII, but not for EBCDIC (IBM). By using macros, this machine dependent knowledge of the character set is concentrated into a single file. For example for (ip = 1; IS_WHITE(str[ip]); ip = ip + 1) ; Finds the first non-white-space character in the string str. Token Definitions Tokens are the smallest recognized string fragments such as a word, number, or operator. The encoded values of the recognized tokens is defined in the include file lib$ctotok.h. See "Internal Formatting" on page 85. Token Value Interpretation --------------------------------------------------------------------- TOK_IDENTIFIER [A-Za-z][A-Za-z0-9_.$]* TOK_NUMBER 0-9][-+0-9.:xXa-fA-F]* TOK_OPERATOR All other printable sequences TOK_PUNCTUATION [:,;] or any control character TOK_STRING "..." TOK_CHARCON '\n', etc. TOK_EOS End of string TOK_NEWLINE End of line TOK_UNKNOWN9 Control characters --------------------------------------------------------------------- Table A.15: Tokens. VOS Library Includes Most VOS library package have an associated include file for constants and structures unique to that package. These are the most commonly needed include files for various packages. Package Include Files --------------------------------------------------------------------- etc time.h fmtio pattern.h, evexpr.h gio gset.h imio imhdr.h --------------------------------------------------------------------- Table A.16: VOS Library Includes.