01 December 1991

The content below is simply a reformatting of text as published decades ago by 9640 NEWS. The opinions and views expressed are not my (Jedimatt42) own. The content is published here to preserve and make accessible the technical data contained within.

Taken from the disk distributions archived at http://ftp.whtech.com/Geneve/9640 News disks v1-3/pc99 disks/

Note: This is in the Disk for volume 2-5, but the contents in the disk volume 3-1 claims to be issue 2-5, and that these contents are to be released in volume 3-1.

TDEBDOC

TDEBUG - 9640 GENEVE Debugger 20-MAY-91

Copyright 1991 by LGMA Products

User Manual v5.01

Index

  1. Introduction
    1.1 Debugger Preparation
    1.2 Debugger Memory Usage

  2. General Syntax
    2.1 Specifying Symbols

  3. Debugger Commands
    3.1 L - Load Task/Symbol/Source Files
    3.2 S - Select Module (FORTRAN Only)
    3.3 B - BreakPoints Remove/Add
    3.4 M - Memory Inspect/Change
    3.5 Q - Quit Command
    3.6 R - Inspect or Change WP/SR/PC
    3.7 T - Trade Screen
    3.8 W - Inspect or Change Workspace Registers
    3.9 H - Hexadecimal Arithmetic
    3.10 G - Go Program into Execution
    3.11 X,Y,Z - X,Y or Z Bias
    3.12 D - Disassemble at Address
    3.13 V - View Source Files
    3.14 P - Display Program Parameters

  4. Known Bugs

  1. Introduction

TDEBUG is an extension of the 9640 FORTRAN Symbolic Debugger (FDEB) that allows use with ordinary MDOS tasks written in assembly language, c99, or TIC; as well as with FORTRAN.

TDEBUG allows you to start up any MDOS program under control of a debugger, examine memory locations, disassemble the program, emplace breakpoints, perform hexadecimal and decimal arithmetic; swap between debugger screen and user screen, set biases, and display various parameters about the program.

When utilized with 9640 FORTRAN programs, the 9640 Debugger allows you to view the source module, examine and alter variables by name, emplace breakpoints by source line number or FORTRAN label, select the scope of the module for debug, and control the termination of the program.

TDEBUG (aka FDEB) is normally distributed with the 9640 FORTRAN package, a commercial product available from:

          LGMA Products
          5618 AppleButter Hill Road
          Coopersburg, PA 18036

If you have purchased 9640 FORTRAN, then the upgraded TDEBUG is free for you to use; if you are NOT a 9640 FORTRAN customer, then this is a shareware product. Please remit $10.00 to LGMA PRODUCTS for use.

The debugger allows you to find errors in your program while it is actually running. You can read and write memory values, inspect and modify variable values, inspect and modify the program's workspace, and place breakpoints in your program which halt the program during execution.

1.1 Debugger Preparation

When using the debugger with FORTRAN programs, first compile the routines which you want to debug with the "DB" option. This will cause the compiler to produce symbol definitions for variables names, line numbers, and labels as part of the program's object. You must then create a "symbol" file in the link process (e.g. FLINK) which will then be used in the debugger.

To start the debugger, regardless of what language the program is written in, type:

      TDEBUG <command line options>

Note the command line options you should enter here are NOT for the debugger, but instead are for your MDOS program.

Once the debugger has been initiated, the screen will clear, and the following line will be displayed:

      LGMA All-Purpose Symbolic Debugger V5.01 (16MAY91)
      Copyright 1990, 1991 by LGMA Products
      Type ? for Help
      ]

The symbolic debugger is now ready to accept commands. The first step at this point would be to use the "L" command to load your program. If you are debugging a FORTRAN program, you can use the "L" command to also load your symbol and source files.

You may enter a question mark to obtain help information. For example, to obtain information on the available commands, you could type:

      ?

and a list of commands would be displayed. To obtain help on the MEMORY command, you could type:

      M ?

and specific information about the usage of the memory command would be displayed.

To execute your program, use the "G", GO command.

1.2 Debugger Memory Usage

The Debugger uses additional memory pages beyond the first 64k of memory. At least 128k of memory is needed to run the debugger and user task. If you are debugging a FORTRAN program, you may need more than 128k of memory, up to a maximum of 256k bytes.

This means to run the symbolic debugger, you may need to reduce the size of your RAM disk in your AUTOEXEC file, or remove the TIMODE statement from the AUTOEXEC file.

When initially loaded, the debugger is placed into the first 64kbyte memory bank (addresses z'00000' to z'0ffff'). When you use the "L" (Load) command, your MDOS task is loaded into the second 64kbyte memory bank (addresses z'10000' to z'1ffff').

If you are using FORTRAN, the symbol file is loaded either in spare memory located in the second memory bank (z'10000' to z'1ffff') or into the third 64kbyte memory bank (z'20000' to z'2ffff'). For FORTRAN, The source files are always loaded into the third 64k memory bank (z'30000' to z'3ffff').

For FORTRAN, If your source files exceed the 128kbytes allotted in the third and fourth memory banks, then an error message will be displayed when loading the source files. This would only occur on extremely large programs, and the solution would be to only load source files for the sources you are debugging.

When your user task is started using the G (GO) command, then the debugger and user task are "swapped" in the first two memory banks. Your program then executes in the first memory bank until a breakpoint, and execution error, or a stop or call exit statement is executed. The "swap" is again performed, and the debugger is reentered.

The debugger also uses the area from z'1e000' to z'1ffff' in VDP memory for its screen image (note that the debugger defines its own screen outside of MDOS). MDOS does not normally use this area.

The debugger also makes use of some memory locations in low ram, that may preclude it's use with other programs that steal the same area (e.g. the mouse driver in windows):

locations >4c to >60 - Breakpoint routines
locations >62 to >72 - Copy of Map Registers for Pages 0 to 15
locations >b4 to >d4 - Breakpoint routine Workspace Registers

2.0 General Syntax

The debugger syntax is a single letter command, followed by one or more optional arguments. Each argument must be seperated by at least one space character.

If you specify too many arguments or too few arguments in a command line, then an error will be displayed.

The debugger accepts as arguments hexadecimal constants, integer constants and symbol constants. The MDOS implementation of the debugger also accepts string constants.

Hexadecimal constants are specified as a normal hexadecimal number, e.g.:

      ABC
      12AB
      1

Integer constants can be specified by preceding them with the letter 'I', i.e.:

      I10
      I-16

The MDOS implementation of the debugger supports longword forms of the hexadecimal and integer constants, i.e.:

      ABCDEF123
      I12848623

The MDOS implementation of the debugger also supports string constants, specified as a quote character, an ascii string, and ended by a quote character:

      'GENEVE'
      'LGMA'

All commands require that the ENTER button be pressed after the end of the command. This is different than the debugger in the TI-99 GPL Editor/Assembler package.

As an example of value specification, the command:

H 10ABCD EF01

would be valid, as 10ABCD and EF01 are both hexadecimal numbers. The command:

H I1234 I6789

would also be valid, as 1234 and 6789 are both valid decimal numbers. The command:

H I10ABCD

would not be valid, however, as 10ABCD is not a valid decimal number.

2.1 Specifying Symbols

A Memory Location can be referred to by using a hexadecimal number. For FORTRAN tasks, you can also refer to a memory location by using a symbol name. A symbol can be a variable name, a line number, or a FORTRAN statement label. A symbol can be used on a command line in the same way as a value, but the symbol name must be preceded by a special character, depending on the symbol type, as follows:

      &mmmmmmmmm - Specifies a variable name mmmmmmmmm.
      %llll      - Specifies a line number llll.
      *aaaaa     - Specifies a FORTRAN label aaaaa.

For example, the following are all valid symbol specifications (assuming that the symbols exist in the symbol file):

      M &&ICHAR             (specifies FORTRAN variable ICHAR)
      B %20                 (specifies line number 20)
      B *1000               (specifies statement label 1000)

3.0 Debugger Commands

The following is a summary of the available commands:

     Letter       Description
     ======       ================================
       B         Remove/Add Breakpoints
       M         Memory Inspect/Change
       G         GO Program into Execution
       Q         Quit Debugger
       R         Inspect/Change WP, PC, or SR
       T         Trade Screen
       W         Inspect/Change Workspace Registers
       H         Hexadecimal Arithmetic
       L         Load File
       X         Set X Bias
       Y         Set Y Bias
       Z         Set Z Bias
       D         Disassemble at Address
       ?         Display Help Information

The following are commands which are only available in the MDOS implementation of the FORTRAN symbolic debugger

     Letter      Description
     ======      ================================

       P         Parameter Display
       V         View Source Module
       S         Select Module Scope

3.1 L- Load Task/Symbol/Source Files

The command letter L allows you to load a new task into the debugger. For FORTRAN, it also allows you to load the symbol file and source files.

This command is generally only executed once per debugging session, at the beginning of the session.

The file name for the task MUST be specified in the command line as the first parameter. For FORTRAN, the optional file name for the symbol file MUST be specified next, followed by any source files you may wish to include.

The format for the command is:

      L Task [symbol_file] [source file 1]...[source file n]

where:

      Task          : is the first file name of the MDOS task to be debugged, 
                      produced by the FORTRAN linker.

      symbol_file   : is the file name of the symbol file produced by the 
                      FORTRAN linker, and

      source_file_x : is up to eight additional source files which you may 
                      specify for the debugger to read in for use with the 
                      VIEW command.

The MDOS task is loaded in its entirety by the debugger. For example, if you linked an MDOS task, which produced three executable files: TESTEXE, TESTEXF, and TESTEXG, you could specify a command line of:

      L TESTEXE

and all three files would be loaded automatically.

The symbol file is the name of the symbol file produced by the linker. For example, if you linked a FORTRAN task, as above, and produced a symbol file with the /S option of TESTSYM, you could specify:

      L TESTEXE TESTSYM

If the original source file was made up of several source files called TESTA, TESTB, and TESTC, you could specify:

      L TESTEXE TESTSYM TESTA TESTB TESTC

Special notes concerning the use of the L command:

  1. Do NOT put any INCLUDED files on this command line (those files you may have specified in your program source with the FORTRAN INCLUDE statement). The INCLUDE files will be read in automatically as called for in your program source.

  2. Your MAIN program must be the first source file specified on the command line. It MUST be included if your are including any source files, and it MUST be first.

  3. It is important that your FORTRAN program being debugged not attempt to access memory locations less than z'40000', or else the debugger will not operate properly.

  4. As the source files are loaded, the FORTRAN statements are parsed by the debugger in the same manner as the FORTRAN compiler parses the statements. The parser within the debugger is somewhat simplified, however, and it is important that a PROGRAM, SUBROUTINE, FUNCTION, or INCLUDE statement be totally contained on a single source line. For example, the statement:

    PROGRAM TEST

would be parsed correctly by the debugger, whereas the statement:

   PROGRAM
  +         TEST

would not, even though both are perfectly valid FORTRAN statements.

  1. Loaded SOURCE modules must match the loaded symbol file. Do not attempt to load any source modules which are from a different program than you are debugging, or an error message will result.

  2. Assembly language source cannot be included in the debugger, since assembly object contains no debug information. Note that the disassembly feature of the MDOS debugger provides you with much of the same capability.

3.2 S- Select Module (FORTRAN Only)

The single command letter S allows you to select the module which you wish to place breakpoints or examine/modify variables.

After a symbol file has been loaded using the L command, the debugger automatically selects the FORTRAN main program module. If you wish to debug other modules, you must select them using the S command.

For example, the program you are debugging has two parts, a main program called TEST and a subroutine called ERRORPR. To select the subroutine for symbol file access, you would use the statement:

      S ERRORPR

After issuing the command, you can then access all of the symbols related to the ERRORPR subroutine, including local and common variables, line numbers, and statement labels.

To reselect the main program for access, you would type:

      S TEST

3.3 B- Breakpoints Remove/Add

The command letter B allows you to add a breakpoint, remove a breakpoint, or list the current open breakpoints. When a breakpoint is encountered by the computer, the debugger is called, and the breakpoint is removed. At this time the contents of the workspaces, memory, program variables, and registers can be inspected or altered using any of the other debugger commands. In addition, other breakpoints can be entered.

It is important that you always place a breakpoint on an executable instruction, rather than a data item. The best way to do this is to always place the breakpoint on the first word of the start of a FORTRAN statement, which will always be an instruction.

Adding a breakpoint:

To add a breakpoint, you enter the command "B", followed by an absolute memory address or symbol name. For example, the command:

      B A360

would set a breakpoint at memory address A360.

The commands:

      B %25
      B *9100

would cause breakpoints to be emplaced on line number 25 and statement label 9100.

Removing a breakpoint:

To remove a breakpoint, you enter the command "B", followed by an absolute memory address or symbol name, and the letter -. For example:

      B A360-

would remove the breakpoint from address A360, while the commands:

      B %25-
      B *9100-

would remove the breakpoints at line number 25 and statement label 9100.

Listing the current breakpoints

To list the current active breakpoints, you would enter the letter "B" with no arguments. For example, the command:

     B

might list the following:

       Locn   Module   Line  Label

       A360   TEST        0   0000
       A420   TEST       25   0000
       A560   ERRORPR    18   9100

where:

Locn - is the absolute memory location at which the breakpoint exists,
Module - is the module in which the breakpoint is contained (FORTRAN),
Line - is the line number at which the breakpoint is emplaced (0 if no symbol file present, or the line number cannot be located), and
Label - is the FORTRAN statement label at the breakpoint (0000 if no label can be located at the breakpoint address).

Deleting All Breakpoints:

To delete all open breakpoints, enter the command letter "B", followed by the minus sign (-). For example, the command:

      B -

would remove all open breakpoints. (note the space between the B and the minus sign, the space delimiter is required)

Breakpoint Execution:

When a breakpoint which you have set is encountered, the following message will be displayed:

      !Break @xxxx, WP=yyyy, SR=zzzz

The hexadecimal number @xxxx is the location at which the breakpoint occurred. The hexadecimal numbers yyyy and zzzz are the workspace pointer and status register, respectively. A debugger (]) prompt also appears, and you can enter debugger commands.

If a symbol file is present, the breakpoint will be listed in the same format as the breakpoint list command.

3.4 M- Memory Inspect/Change

The command letter M allows you to display or modify cpu or vdp memory, or display or modify local and common program variables.

If a single address is given, then the debugger enters the inspect/modify mode. If a range of addresses are given, then the debugger only displays the memory locations.

If a variable name symbol (one which begins with an ampersand, e.g. &ICHAR) is given, then the current value of the variable is displayed in its corresponding type (Integer *1, Integer *2, Integer *4, Single Precision, Double Precision, or Logical), and a new value can be entered.

Inspect/Change Memory

If a single address is given, then the debugger displays the specified memory address. If a number is then entered, the debugger modifies the memory location specified. If "ENTER" is depressed with no value, then the debugger displays the next location. If "FCTN/BACK" (f9 under MDOS) is entered or a period (.) is entered, then the debugger returns to command mode.

For example, the commands:

      M A360
      A360 = 1690
      A362 = C155 C260
      A364 =             <FCTN/BACK or F9 pressed>

would modify location A362 to a C260 (was C155). If the program line number 25 was located at memory location A360, then the following command would perform exactly the same operation:

      M %25

If the memory address is specified with the letter V following, then VDP memory is accessed rather than cpu memory. For example:

      M 0000V
      0000 = 3120 2020

would change the home position on the current TI-99 GPL screen from '31'X (ASCII 1) to '20'X (ASCII blank).

You can also display memory in different formats, i.e:

      M.B    - Memory BYTE format
      M.W    - Memory WORD format
      M.L    - Memory LONGWORD format

or example, to display the same memory locations as before in byte format, then the command:

      M.B A360
      A360 = 16
      A361 = 90
      A362 = C2
      A363 = 60 .

Other extensions to the MDOS implementation of the MEMORY command include:

  1. The memory display command now displays sixteen bytes per line.

  2. The addresses to display or modify can be specified in longword format. This allows you to access or display the full 128kbytes of VDP memory. For example, you may specify an address of:

      M 121ACV
    
  3. The key can be used to abort long displays of memory.

  4. Values may be entered as ASCII text strings (using quoted strings), symbol locations, and integer values as well as hexadecimal values.

  5. A new value response qualifier ("^") allows you to "back-up" to the previous modified value.

Inspect Memory

If a range of addresses are specified, then the memory locations specified are displayed on the screen, along with the character translation of the addresses. For example,

      M 0000V 0300

would display the contents of VDP memory locations '0000'x to '0300'x, which are the current screen contents. To display cpu memory, omit the V in the range of examples, as follows:

      M A000 A300

Displaying cpu memory can also be performed using the statement label and the line number symbol arguments. For example, to display the memory between statements 25 and 30, the following command could be given:

      M %25 %30

or to display from labels 9100 to 9200:

      M *9100 *9200

Inspect/Alter Variables

To inspect or alter a variable, give as an argument to the M command a variable name, preceded by an ampersand (&). For example, to display the value of the integer variable ICHAR, the command:

      M &ICHAR

could be given. This would cause the following to be displayed:

      ICHAR(   1) =  16706

The variable appears with a subscript (1), even though the variable may not have been declared as an array. At this point, you may enter a new value, press enter to see the next variable in the data area, or press Fctn/Back (f9 using the MDOS implementation of the debugger) to return to the debugger command mode.

Variables are normally displayed according to type. You can also modify the display/alter mode by typing a comma, followed by the single letter A or Z (for alphanumeric or hexadecimal) after the variable name. For example, the command:

      M &ICHAR,Z

would produce the display line:

      ICHAR(   1) = 4142

while the command line:

      M &ICHAR,A

would produce the command line:

      ICHAR(   1) = AB

showing the results of the Z and A qualifiers. The following table shows the display format for each type, with each qualifier:

  Type           No Qualifier       Z Format      A Format

  Integer *1          I6               Z2           A1
  Integer *2          I6               Z4           A2
  Integer *4          I12              Z8           A4
  Single Precision    E13.6            Z8           A4
  Double Precision    D13.6            Z16          A8

Caution: no subscript checking is performed by the debugger. Therefore it is possible to for you to enter a value in an array location which is outside the bounds of the array. Check the bounds of the array very closely before changing the array contents.

To save room in the symbol file, only the main program's definition of the blank common block is saved. This requires that the main program be compiled with the "DB" option, if you want to access variables in common.

FORTRAN dummy names (arguments in subroutines and function subprograms) are not saved in the symbol file, and as such are not accessable using the dummy name. To examine/ alter the arguments in the subroutine, select the calling program/subprogram and access it via the variable name.

You cannot use a symbol value in entering a new value for a variable. The new value must be the same in type as the displayed value. For example, the command:

      M &ICHAR
      ICHAR(    1) =    2  23

would be valid since the new value entered (23) is of the same type as displayed (integer). However, the command:

       M &ICHAR
       ICHAR(    1) =    2  1D2

would not be valid since the value entered (1D2) is hexadecimal and the display type is integer.

The following are some examples of the extended MDOS modification formats:

  1. The following example modifies VDP memory mapped at location z'400' in byte format. The user presses enter until location z'402' is displayed, he/she then "backs-up" by typing a caret (~) and enter, redisplaying location 402. He/she then exits using a period (.).

      M.B 400
      400 AC '.'
      401 16 '.'
      402 41 'A' 'C'
      403 42 'B' ~
      402 43 'C' .
    
  2. The following example shows integer format of modification, using the 'I' format:

      M 400
      400 AC16 '..' I1231
      402 4342 'CB' .
    

3.5 Q- Quit Command

The command letter Q causes the debugger to exit and return to the MDOS prompt.

3.6 R- Inspect or Change WP, PC, SR

The command letter R shows the workspace pointer, program counter, and status register and allows you to change their values. After you display a register, you can alter it by entering a new value, followed by ENTER.

The workspace pointer points to the program workspace. This value should always be z'8300' under TI-99 GPL mode or z'f000' under MDOS mode. It should never be changed.

The program counter points to where the program was executing when the debugger was entered, and represents the breakpoint location.

The status register contains the status (logical greater than, arithmetic greater than, equal, carry, overflow, odd parity, extended operation, and interrupt mask) at the time of the breakpoint. These are passed back to your program when the program is resumed.

    Status Register:

          0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
        |L>|A>|EQ|C |OV|OP|X |--|--|--|--|--|  INT. MASK|
        +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

    where:

        Name   Bit Number   Description

          L>      0          Logical Greater Than
          A>      1          Arithmetic Greater Than
          EQ      2          Equal To
          C       3          Carry
          OV      4          Overflow
          OP      5          Odd Parity
          X       6          Extended Operation
          -      7-11        Reserved
          INT.   12-15       Interrupt Mask
           MASK

For example, the command:

      R
      WP = FC60       <ENTER pressed>
      PC = A632 A600  <ENTER pressed>
      SR = 8000       <ENTER pressed>

would modify the program counter to A600 (was A632). When the program continues execution (by the Q or Quit command), it will resume execution at location A600 rather than A632.

Note the status register is decoded and active flags within the status are displayed. For example, a status register of z'3402' is displayed as:

      SR = 3402   /  /EQ/C /  /OV/  /  /  , level=2

which says that the EQual status bit is set, the Carry status bit is set, the OVerflow status bit is set, and the current interrupt level is level 2.

3.7 T- Trade Screen

The command letter T trades the debugger screen for the screen as it was when you entered the debugger. The current contents of the debugger screen are lost.

For example, the command:

      T

would remove the debugger screen, and replace it with the screen when you entered the debugger. To return to the debugger screen, depress any key.

3.8 W- Inspect/Change Workspace Registers

The command letter W displays all of your workspace registers, and their values if no workspace register number is given. If a workspace register number is given, it and its value are displayed and the value can be changed. After changing the value, you can press ENTER to enter the value and display the next workspace register. Pressing FCTN/BACK (f9 under MDOS) will return you to command mode without changing its value.

For example, the command:

      W

would display all 16 registers, while:

      W 1

would display only register 1, and also allow you to modify the register.

The following describes FORTRAN's usage of the sixteen registers:

R0, R1, R4, R9, R12 : Temporaries
R2 : Dynamic Pointer
R3 : Points to start of data area/this module.
R5, R6, R7, R8 : Extended Accumulator:
Integer *1 : R5 MSB
Integer *2 : R5
Integer *4 : R5, R6
Real *4 : R5, R6
Real *8 : R5, R6, R7, R8
R10 : Points to execution support package
R11 : Return for subroutine calls
R13, R14, R15 : Used for BLWP

The following describes TIC's usage of registers:

R0,R9,R10 : Non-saved temporaries
R1,R2,R3 : Rotating Temps
R4,R5,R6 : Saved Temporaries (register variables)
R7 : Frame Pointer
R8 : Return Value from Function
R11 : Return for Subroutine Calls
R12 : Address of "CALL" routine
R13 : Address of "RETURN" routine
R14 : Stack Pointer
R15 : Address of C$SWCH routine

3.9 H- Hexadecimal Arithmetic

The command letter H allows you to to add, subtract, multiply, divide and display the decimal equivalent of the two values entered. For example, the command:

      H A 6

would display the following:

      H1=000A H2=0006 H1+H2=0010
      H1-H2=0004 H1*H2=0000 003C
      H1/H2=0001 R 0004
      H1(I)=    10 H2(I)=     6

which represent the two values entered (H1 and H2) in hexadecimal, the sum, the difference, the product, the quotient, the remainder, and the equivalent values in integer decimal.

This command can be used to perform hexadecimal to decimal conversions, and vice versa. For example, the command:

      H I23

would display the values:

      H1=0017 H2=0000 H1+H2=0017
      H1-H2=0017 H1*H2=0000 0000
      H1/H2= 0000 R 0000
      H1(I)=  23  H2(I)=  0

converting the decimal value 23 to its equivalent hexadecimal 17.

You can also use this command to translate symbols to their hexadecimal and decimal memory locations. For example, the command:

      H %25

would display the values:

      H1=A360 H2=0000 H1+H2=A360
      H1-H2=A360 H1*H2=0000 0000
      H1/H2= 0000 R 0000
      H1(I)= -23712 H2(I)= 0

MDOS extensions to this command allow for integer *4 (longword) arguments, and symbol/string formats of constant expressions.

3.10 G- GO Program into Execution

The G command letter specifies that the debugger is to start the MDOS task into execution. If an address was specified in the command line, then the program will start executing at that execution address. If an address has NOT been specified, then the program will start at the address specified in the current program counter PC (see R command).

Command Format:

      G [address]

where: address is an optional execution address.

Return from the GO command is via one of the three following conditions:

  1. A user emplaced breakpoint was encountered.

  2. A FORTRAN execution error was detected, or

  3. A FORTRAN STOP or CALL EXIT statement was executed.

The following are examples of the GO command usage:

      G               start execution at PC
      G 0480          start execution at address >480
      G %50           start execution at line 50
      G *1000         start execution at label 1000

3.11 X,Y,Z - X, Y, and Z Bias

Three new commands allow you to specify an offset in a specified constant. These three commands are analogous to a "memory" button on a calculator they remember a 32-bit value which can be recalled later.

The command syntaxes are:

      X value
      Y value
      Z value

For example, using the MDOS implementation of the symbolic debugger, the following sets the X constant value to z'12341234':

      X 12341234

The following are other examples:

      Z I125         - set Z to integer 125
      Y %15          - set Y to location of line 15
      X *9100        - set X to location of label 9100
      X &XYZ         - set X to location of variable XYZ

You can then use these constants in any expression:

      M 0X 20X      - display memory from location 0+X to location 20+X

      B 0X          - put breakpoint on location 0+X

      H 123X 124YZ  - hexadecimal arithmetic on the values 123+X, and 124+Y+Z.

3.12 D- Disassemble at Address

The command letter D allows you to disassemble code starting at the specified start hexadecimal address, and continuing until the end address specified. The command format is:

      D start_address [end_address]

If the "end_address" parameter is not specified, then only ten bytes of the code will be disassembled.

Note that the start_address and end_address can also be specified as symbols. For example, to disassemble starting at line number 25 to line number 30, you could enter:

      D %25 %30

or to disassemble starting at FORTRAN label 100:

      D *100

or to disassemble string at location >0480, and continuing to location >7FF:

      D 480 7FF

The disassembler will replace hexadecimal values with symbol names, as follows:

a) line numbers are replaced by the % symbol, and the line number. For example, if line number 143 was mapped at location z'0464', then the following code:

      BL @>0464

would be replaced by:

      BL @%143

b) Variable names are replaced by the && symbol, and the variable name itself. For example, if the variable "ITEST" were mapped at location >EF10, then the code statement:

      MOV @>EF10,R5

would be replaced by:

      MOV &ITEST,R5

3.13 V- Viewing Source Files

The command letter V allows you to view the FORTRAN source files which make up the FORTRAN program you are debugging. This is useful to determine where breakpoints are to be placed, or where breakpoints have occurred.

The VIEW command format is:

      V start_line_number [end_line_number]

                        or

      V.D start_line_number [end_line_number]

The command letter V alone specifies displaying line numbers, line locations, and source lines only. The option command V.D specifies the source listing is to be interspersed with disassembled object code.

Both the starting and ending line numbers are specified in decimal. The ending line number argument is optional, and if omitted, only the starting line will be displayed.

Only source lines within the currently selected source module can be displayed. For example, to display lines 100 through 102, inclusive, in module SYMLOAD, you might specify:

      S SYMLOAD
      V 100 110
      100 04C2       if ( numbyte .le. 0 ) then
      101 04D0         call prnerr ( -1 )
      102 04DA         stop

To display the same lines with interspersed disassembly code, you might specify:

      V.D 100 102

      100 04C2       if ( numbyte .le. 0 ) then
          04C2 04C5         CLR R5
          04C4 1501         JGT @>04C8
          04C6 0705         SETO R5
          04C8 0505         NEG R5
          04CA 1602         JNE @>04D0
          04CC 0460         B   @>04DE
          04CE 04DE
      101 04D0       call prnerr ( -1 )
          04D0 06A0         BL @PRNERR
          04D2 84B8
          04D4 0140
          04D8 FFFF
      102 04DA       stop
          04DA 06A0         BL @STOP$
          04DC 8078

3.14 P- Display Program Parameters

The command letter P allows you to display information about the current debugging session. The letter P with no parameters is used to display overall debugger information, whereas the command letter P followed by a FORTRAN main program, subprogram, or assembly language DEF symbol name will display known information about that particular module.

The following is the syntax of the Parameter command:

      P               - displays overall debugger information
      P module_name   - displays information about the module

The following information is displayed in response to a command letter P:

a) The name of the FORTRAN task loaded on command line

b) The load address of the symbol file (0 if none)

c) The name and module pointer of the currently selected module (module scope)

d) The number of modules currently loaded in symbol/source files, the name of each module, and position within the symbol/source files.

The modules are shown in ascending location order, the order in which they are loaded in memory. The main program module is always first, followed by any FORTRAN function subprograms or subroutines, and then followed by any assembly language subroutines, including library routines.

The following information is displayed concerning an individual module:

a) The module name, and the starting location

b) FORTRAN variables, their starting address, the area in which they are located (common or local to module), and the variable type.

c) FORTRAN line numbers and starting locations. Note that FORTRAN does not save line numbers of comment lines, or line numbers of continuation lines.

d) FORTRAN labels and starting locations.

The following are examples of using the command letter "P":

      P                 - display overall information
      P TESTPROG        - display information about main
                          program called TESTPROG
      P SUB1            - display information about sub-
                          program called SUB1
  1. Known Bugs

a. TDEBUG will not work reliably with 9640 windows programs (look for a totally new windows debugger in the future).

b. The FORTRAN portion of TDEBUG has not been validated (i.e. loading and debugging FORTRAN tasks. Use the existing FDEB for these).

TIC_TXT

TIC - TI-99/4A and 9640 GENEVE C Compiler 08-DEC-91

Copyright 1991 by LGMA Products

User Manual v1.61

Index

  1. Introduction

  2. Running TIC

2.1 IBM (c) PC MSDOS Compiles
2.2 MYARC Geneve MDOS Compiles

  1. SYSGEN Versions

3.1 MSDOS Version of TIC
3.2 MYARC Geneve Version of TIC
3.2.1 Errors

  1. TIC Syntax

  2. Library Interfaces

5.1 C99 Compatibility Mode
5.2 TIC Native Mode

  1. Header Files

6.1 Header Files
6.2 XOP Routine
6.3 Example of Header Files and XOP Routine

===============================================================================

1. Introduction

TIC (TI-C) is a K&R style C compiler that compiles C source code into TI-99/4A and 9640 assembly language. It supports many more -C- features than c99; some features (e.g. the #asm directive) are lost.

TIC was derived from a 68000 based C compiler developed by Matthew Brandt. Matthew did a fantastic job in writing the original compiler. His attention to addressing modes and the modularity of the original compiler made the conversion of the 68000 C compiler to TMS9900 a reality.

The following statement is taken from the original Matthew Brandt 68000 compiler:

This compiler is intended as an instructive tool for personal use.
Any use for profit without the written consent of the author is
prohibited.

This author honors the intent of the original author.

Considerable effort has gone into making the compiler produce quality TMS9900 code. The author (LGMA Products) of this code is placing this compiler into the TI and MYARC user community as a shareware product. $20 is suggested as a donation for using of this compiler, please send contributions to:

          LGMA Products
          5618 AppleButter Hill Road
          Coopersburg, PA  18036

TIC does a fairly decent job of conditional branches and making use of various addressing modes of the TMS9900 processor to produce optimal code. Things could always be better, but my code sizes on the non-c99 compatible version are approaching the better MSDOS sizes (e.g. Turbo C and Microsoft C).

TIC supports two modes in compilation. A c99 compatibility mode allows you to generate programs that should be compatible with all c99 libraries (please let me know if you find cases that aren't). A non-c99 compatibility mode produces much more efficient code, but is NOT compatible with the c99 library routines. Why? ---

During implementation of TIC, it was found that by letting the stack grow "up" in memory (rather than "down" as using c99), then much more efficient "pushes" to the stack could be performed. Also, by saving several registers on the stack when subroutines were called, register optimizations on the code could be implemented. The result is almost a 2-1 reduction in the size of some programs (like TIC itself!).

Certainly much more could be done to trim the resulting source code. Experimentation has shown a point of diminishing return, by adding more code to the compiler to produce further optimizations, the danger of "over-optimizing" (e.g. producing code that doesn't work) becomes high and the compilations slow to a crawl.

TIC, with the exception of the normal C library routines, is written entirely in C. This allows portability of the compiler to various operating system environments. Three operating systems are currently supported:

    9640 GENEVE MDOS
    MSDOS
    Amiga DOS

Other operating systems are easily supported by simply recompiling/linking the compiler under those systems (assuming the system has a quality C compiler).

Creating and running a TIC program is quite simple and involves:

1. Creation of the source file on the target machine

2. Compilation of the source using the TIC compiler

3. Assembly of the resulting source using the TASM assembler or
   GenASM or QDA (note that QDA will truncate function/variable
   names greater than 6 characters).

4. Linkage of the object with library modules using the TASM loader
   or GenLink or QDL (note that the object will probably have to be linked
   with standard c99 libraries, as with any c99 program)

5. Running the program on the target machine

Note with a cross-compiler, it should be able to create runnable programs for either a TI-99/4A or a MYARC GENEVE 9640, just by linking to the correct c99 library for that machine.

============================================================================

2. Running TIC

Regardless of the machine environment, running TIC is essentially the same. The TIC compiler is invoked with the command line:

   TIC <options> filename1

where:

 <options>  are options specified in the form of +option or -option,
            depending on whether the option is to be added or
            removed.  There are five options:

            +I or +i -  Specify an include file directory

            +O or +o -  Turn ON ALL Optimization (default)
            -O or -o -  Turn OFF ALL Optimization

            +R or +r -  Turn ON Register Optimization (default)
            -R or -r -  Turn OFF Register Optimization

            +9       -  c99 compatible
            -9       -  not c99 compatible (more efficient, but
                        won't work with c99 libraries - default)

            +l or +L -  generate listing file (default)
            -l or -L -  turn off listing file

            +a or +A -  TASM compatibility (default)
            -a or -A -  GenASM compatibility

    filename  - is the -c- source file to compile; the filename is in
                the form of:

                       filename.c  -  for MSDOS & Amiga Versions
                       FILENAME_C  -  for Geneve Versions

                The compiler will produce output files of:

                       assembly source - FILENAME.S   or FILENAME_S
                       listing file    - FILENAME.L   or FILENAME_L
                       ref/def include -                 FILENAME_I

The FILENAME_S is an assembly language file suitable for compilation with the TASM assembler. It can also be assembled with the standard TI assembler (with restriction of 6 character labels) or Paul Charlton's GenASM (see note on -A option, above).

2.1 IBM (c) PC MSDOS compiles:

Examples of doing TIC compiles under MSDOS are:

    TIC +IC:\TIC\INCLUDE\ +OL9A SIEVE.C

specifies that:

the directory C:\TIC\INCLUDE\ contains header files (e.g. STDIO.H) that will be used in the compilation (and are referenced by filenames in brackets, e.g. #include <stdio.h>)

optimization, c99 compatibility, and listing files are turned ON

in this case, the files:

            SIEVE.S  -  Assembly Source file
            SIEVE.L  -  Listing file

will be produced.

    TIC +IC:\TIC\INCLUDE\ +IC:\TIC\ENVIRON\ +OLA -9 GENCODE.C

specifies that:

the directories C:\TIC\INCLUDE\ and C:\TIC\ENVIRON\ will be scanned for header files during compilation (for files that are specified with #include <> format), and

optimization (+O) and listing file (+L) and TASM compatibility (+A) are turned ON, and

c99 compatibility (-9) is turned OFF.

2.2 MYARC GENEVE MDOS compiles:

Examples of TIC compiles under MYARC 9640 GENEVE MDOS are:

    TIC +IE:INCLUDE/ +OL9 SIEVE_C

specifies that:

the directory E:INCLUDE/ is to be scanned for header files during compilation (for files that are specified with #include <> format), and

optimization, listing, and c99 compatibility are turned on.

In this case, the files:

       SIEVE_S -  Source file
       SIEVE_L -  Listing file
       SIEVE_I -  Include File for REF/DEF

will be produced.

Note that as of version 1.43; Native MDOS TIC forces all include file names to uppercase, e.g.:

       #include "stdio_h"

will cause the MDOS file name:

       STDIO_H

to be opened, not stdio_h.

=========================================================================

3 SYSGEN Versions

3.1 MSDOS Version of TIC

The MSDOS Version of the compiler is similar to the other versions. The MSDOS version has somewhat limited internal buffers (64k) in relation to the 68000 version (limited only by memory available) so that some programs may not compile under MSDOS (in the current version).

The MSDOS distribution kit places the following files in the directories:

  :\TIC\BIN

      TIC.EXE            -  The TIC compiler
      TASM.EXE           -  The Cross-Assembler
      LOADER.EXE         -  The Cross-Loader

Place the following in a -C- header directory:

   :\TIC\INCLUDE

      STDIO.H            -  Standard I/O routines (from c99 release)

Place the following in a -C- Library Directory:

   :\TIC\LIB

      CSUP               -  The C Supervisor Directory

3.2 GENEVE (c) MDOS Version of TIC

The GENEVE MDOS version of the compiler utilizes sophisticated memory swapping to gain an 85k workspace for the compiler, even though the compiler is over 50k in length. This allows compilation of fairly sophisticated C programs.

The total memory required to run the TIC compiler is 144k. TIC compilations will be faster if you do not enable the TIMODE in your startup sequence (TIMODE grabs fast memory which can be utilized in the compilation process).

The MDOS version is distributed with the following files:

   TIC, TID, TIE, TIF -  The program executables
   TIC_TXT            -  This file

TIC can also be used with Clint Pulley's modified E/A (for running under MDOS), with limitation of 6 character label names; or with Paul Charlton's GenASM. GenASM runs much faster than TASM; allows up to 31 character label names (just like TASM). However, if you use GenASM, you must use the -A option for full compatibility. When the -A option is chosen, then an additional _I file is created which contains externally referenced label names (since GenASM is a one-pass assembler, external REF's must be declared at the beginning of a file instead of at the end. Creating a _I file allows an include file to be created that has all of the external REF's, and is included at the start of the assembly file).

TIC is normally used with TASM, the TIC companion assembler. This assembler, like GenASM, supports long label names (up to 31 characters). Since it is a two-pass assembler, it doesn't need the -A option.

A typical compilation, assembly, and link would look something like:

        TIC +IHDS1.INCLUDES. -L SHELL_C
        TASM SHELL_S
        LDR SHELL_X,WINLIB,TICLIB SHELL

This produces a runnable program, called "SHELL".

When a compilation is started, TIC outputs file names as they are processed with the statement:

    Processing:      FILENAME_C

The user will note a delay when TIC finishes reading in a module, and before the assembly source file (the _S file) is produced. TIC provides at least five optimization passes at the assembly code before output, causing the delay.

On the Geneve, the assembly source output tokens are separated by a single space, e.g.:

    L10 MOV 0,1

whereas on the MSDOS version the TAB (09) character is used as a delimiter, e.g.:

    L10    MOV   0,1

3.2.1 Error Messages

The GENEVE version makes good use of extended memory to allow a large workspace for compilation. However, since the compiler is so optimizing, it requires a large amount of memory. The following error messages indicate memory problems when running the compiler:

a) Error - Not Enough Memory for Task - This is displayed if the compiler cannot allocate the 144k required for the TIC compiler. The solution is to reduce other memory requirements, like removing TIMODE from your AUTOEXEC, or reducing the size of your ramdisk.

b) Error - Stack Overflow - This is a catastrophic error that can occur while compiling a complex C program. You must reboot after this message is displayed as TIC does not close out any open files if this occurs. The only solution is to try and reduce the complexity of the program, perhaps make expressions simpler; remove nested loops, etc.

c) Error - Not Enough xxxxxx Memory - This occurs if the 85k workspace is exhausted. The only solution is to reduce the size of the module that caused the error (perhaps split the function module).

==============================================================================

4. TIC Syntax

Notes on TIC Syntax:

  1. The #asm and #endasm procs are not supported (this makes life converting c99 programs a bit complicated, as c99 programs were often written dropping to inline assembler).

The optimizing nature of the TIC compiler makes it such that support for #asm and #endasm is VERY difficult (also, #asm is not standard ANSI).

  1. The pre-processor is a simple K&R type pre-processor with minor extensions. The following pre-processor commands are supported:

     #define
     #ifdef
     #ifndef
     #else
     #endif
     #include (forms of "..." and <...> are supported, as well
      as nested includes.  Native TIC version supports up to
      (2) nested includes due to memory restrictions).
    
  2. The pre-processor supports simple constant expressions, like:

     #define MAXMACRO 100
     int macros[MAXMACRO+2];
    

A constant expression may contain a combination of symbol names, constants, and the operators +, -, *, and /. Evaluation of these operators is strictly "left to right".

  1. Long INT's, Floats, Doubles are not currently supported (TIC can be extended to these, but aren't currently fully implemented, be careful, TIC won't always flag these as errors).

  2. The "typedef" facility is not supported.

  3. The "recognized" c keywords are as follows:

       auto            break              case
       char            continue           default
       do             *double             else
       enum            extern            *float
       for             goto               if
       int            *long               register
       return          short              sizeof
       static          struct             switch
      +typedef         union              struct
       void            while
    

*recognized but not compiled correctly

+not recognized

==============================================================================

5.0 Library Interfaces

The TIC compiler offers two modes of compilation:

o Native TIC mode
o c99 compatibility mode

5.1 c99 compatibility mode

The c99 compatibility mode offers compatibility with current library routines coded for Clint Pulley's c99 small C compiler. Several characteristics of the c99 environment are:

  1. Registers are allocated as follows:

           R7 -  Frame Pointer
           R8 -  Working Register
         *R12 -  Address of "Call Subroutine"
         *R13 -  Address of "Return Subroutine"
          R14 -  Stack Pointer
          R15 -  Address of "Stack Push" Routine
    
  2. The stack grows "down" from high memory to low memory. On the Geneve the start of the stack is located at the high end of memory near >ffff. As items are pushed to the stack, then the stack pointer is decremented; i.e.:

        stack pointer:   >FFFE
          item pushed to stack via code:
                         BL  R15
        stack pointer:   >FFFC
    
  3. On a subroutine call, the calling parameters are pushed to stack and are allocated "forwards" in the stack, i.e.:

             MOV  param1,R8
             BL   R15         push to stack
             MOV  param2,R8
             BL   R15         push to stack
             BL   *R12        call subroutine
             DATA subr
    

within the subroutine:

             MOV  @2(R14),R1   get param1
             MOV  @4(R14),R2   get param2

Note that c99 compatibility mode will likely be dropped on the next version of TIC, to allow room in the compiler for other desirable features.

5.2 Native TIC mode

The native TIC mode is different primarily that the stack grows "up" in memory instead of "down", and that several registers are saved in function calls and popped in returns.

Moving the stack "upwards" allows optimized register pushes, i.e.:

       MOV  @param1,*R14+    uses TMS9900 auto increment

instead of the c99 method:

       MOV  @param1,R8       TMS9900 has no autodecrement
       BL   R15

Also, TIC utilizes R7 as a "frame" pointer. Auto-variables (those that are defined within the module scope) are always indexed from R7, i.e.:

       MOV  @2(7),8

Loads the second variable indexed from R7, which is the frame pointer.

  1. Registers are allocated as follows:

           R0 -  Wild card temporary
           R1 -  temporary
           R2 -  temporary
           R3 -  temporary
           R4 -  register variable
           R5 -  register variable
           R6 -  register variable
           R7 -  Frame Pointer
           R8 -  Working Register
           R9 -  used for 2-word mult/div
          R10 -  used for 2-word mult/div
          R11 -  BL return save
         *R12 -  Address of "Call Subroutine"
         *R13 -  Address of "Return Subroutine"
          R14 -  Stack Pointer
          R15 -  Pointer to C$SWCH routine
    
  2. The stack grows "up" from low memory to high memory. On the GENEVE the stack is located at >f120. As items are pushed to the stack, the stack pointer (R14) moves "upward" towards >ffff.

  3. Parameters are "pushed" to the stack as follows:

     char     -   16 bit word, right justified in word
     short    -   16 bit word
     pointer  -   16 bit word
    
  4. On a subroutine call, the calling parameters are pushed to stack and are allocated "forwards" in the stack, i.e.:

             MOV  @param1,*r8+   push to stack
             MOV  @param2,*r8+   push to stack
             BL   *R12           call subroutine
             DATA subr
    

within the subroutine:

             MOV  @-12(R7),R8    get first parameter
             MOV  @-14(R7),R8    get second parameter

Note the large offset (-12) to the first parameter. This is because a number of values are saved to the stack. The native TIC stack structure is:

         -n   parameter n
        -18   parameter 4  (if used)
        -16   parameter 3  (if used)
        -14   parameter 2  (if used)
        -12   parameter 1  (if used)
        -10   R11 save
         -8   R7  save
         -6   R4  save
         -4   R5  save
         -2   R6  save
 r7---->  0   Start of local variable area, First Local Variable
          2   Second Local Variable

when your routine is entered, r7 points to the start of the local variable area (and is actually equal to r14). The first usual instruction is:

           AI  R14,n  or INCT R14

where: "n" is the sum of the local variable sizes.

Example of native TIC routine:

         main ()
         {
         int i,j,k;
         atoi(i,j,k)
         }

         int atoi(i,j,k)
         int  i,j,k;
         {
         return i+j+k;
         }

Assembly output:

         * TIC Version 1.4 (14-Dec-90) (c) 1990 by LGMA PRODUCTS
                EVEN
         MAIN
                AI  14,>6              Allocate 6 bytes local for i,j,k
                MOV @>4(R7),*R14+      push k to stack
                MOV @>2(R7),*R14+      push j to stack
                MOV *R7,*R14+          push i to stack
                BL  *R12               call atoi
                EVEN
                DATA ATOI
                AI   R14,>FFFA         deallocate 6 bytes from stack
                MOV  R8,R1             not really needed
           L0
                B    *R13              return
           ATOI                        start of atoi routine
                MOV  @>FFF4(R7),R1     get i
                A    @>FFF2(R7),R1     add j
                A    @>FFF0(R7),R1     add k
                MOV  R1,R8             put result in r8 (for return value)
           L1
                B    *R13              and return
                EVEN
                DEF  MAIN
                DEF  ATOI
                END
  1. All arguments (with exception of long & floats) are passed as short (16 bit word) arguments on the stack. "char" arguments are passed right justified in the argument, e.g.:

          'A'   is passed as   >0041 on stack
    

TIC expects that all arguments are packed in short format, so if a char argument is used, it generates code to shift the argument properly for the TMS9900, e.g.:

          MOV  @-12(R7),R1
          SLA  R1,8
          LI   R2,>4100
          CB   R1,R2

will properly compare the first argument passed to the letter 'A'.

============================================================================

6.0 Header Files

6.1 Header Files

Header files are used extensively in the C programming language to allow the programmer to use symbols within the program to convey meaning. For example, the following C statements use symbols to perform set the video mode to graphics mode 6:

       registers[0] = SETVIDEOMODE;
       registers[1] = GRAPHIC6;
       xop ( VIDEOXOP, registers );

This provides readable source. The following source is equivalent to the previous code, but does not use symbols and therefore is not very readable:

       registers[0] = 0;
       registers[1] = 8;
       xop ( 6, registers );

The TIC package includes a number of header files that provide definition of the Geneve XOP Libraries. For a definition of what these libraries are and how they work, the most definitive document is contained within Paul Charlton's GenASM program. The 9640 Windows library is described in Beery Miller's 9640 Windows user manual. The video library is currently only defined as postings on various BBS's, and has non-working sections.

The header files provided are:

       keyboard_h  :     Keyboard Library
       genvideo_h  :     Video Library
       memory_h    :     Memory Library
       io_h        :     Input/Output Library
       utility_h   :     Utility Library
       math_h      :     Math Library
       windows_h   :     9640 Windows Library

These files can be used by placing the files in an "INCLUDE" directory. For example, suppose you place all six files in the "HDS1.INCLUDE" directory on your hard disk. You can then utilize the header files you need by placing the statement:

        #include < FILENAME_H >

in your C program, and using the option:

        TIC +IHDS1.INCLUDE.

on your TIC compile command line.

6.2 The XOP function

TIC includes a routine called "xop". XOP is a very low-level routine that takes as input from the user program:

a. An XOP Number to execute
b. A register list (up to 8 registers, registers 0 to 7 )

Using the XOP routine and the header libraries, the user can execute ANY MDOS XOP library function directly from C.

XOP Library Call Syntax:

    int xop ( xop#, register_list );

where:

    xop#              is a short int that contains the XOP number
                      to execute, and

    register_list     is a short int 8 word array that contains the
                      register list to pass to the XOP

XOP returns a ZERO if the result of the operation is , or a ONE if the result of the operation is . This allows you to check on the return status of certain XOPs like the keyboard XOP. XOP also returns the registers 0 to 7 in the "registers" array.

6.3 Examples of XOP and header files

The following is an example subroutine that sets the video mode to text mode (set mode text ):

#include <genvideo_h>
main()
{  int    registers[7];
   registers[0] = SETVIDEOMODE;
   registers[1] = TEXT1;           /* 40-column mode */
   xop ( VIDEOXOP, registers );
   printf ("video mode text 1 ");
}

If the includes were contained in the HDS1.INCLUDE directory, you could compile this with the statements:

TIC +IHDS1.INCLUDE. MAIN_C
TASM -M MAIN_C
LDR MAIN_X,TICLIB MAIN

Then run the program with:

MAIN

GENVIDEO_H

/*
**   Filename:            Video_h
**   Release:             Version 1.5
**   Date:                26/July/1991
**
**   This file contains the definitions for the MDOS Video library
**
**   Copyright 1991 by LGMA Products
**
**   Revision History:
**
**   26/Jul/91       Initial Release
*/
 
#define    VIDEOXOP     6        /* Video XOP Number */
 
/* Graphic Modes                                              */
 
#define    TEXT1         0            /* TEXT 1      40 x 26     2     N   */
#define    TEXT2         1            /* TEXT 2      80 x 26     2     N   */
#define    MULTICOLOR    2            /* MULTI       64 x 48    16     1   */
#define    GRAPHIC1      3            /* GRAPH1      32 x 24    16     1   */
#define    GRAPHIC2      4            /* GRAPH2      32 x 24    16     1   */
#define    GRAPHIC3      5            /* GRAPH3      256dx212d  16     2   */
#define    GRAPHIC4      6            /* GRAPH4      512dx212d  16     2   */
#define    GRAPHIC5      7            /* GRAPH5      512dx212d   4     2   */
#define    GRAPHIC6      8            /* GRAPH6      512dx212d  16     2   */
#define    GRAPHIC7      9            /* GRAPH7      256dx212d  32     2   */
 
/* Operations:                                                 */
#define    SETVIDEOMODE   0            /* Set Video Mode */
#define    GETVIDEOMODE   1            /* Get VideoM ode */
#define    SETCURPOS      2            /* Set Cursor Position */
#define    GETCURPOS      3            /* Get Cursor Position  */
#define    SETDISPAGE     4            /* Set Display Page */
#define    GETDISPAGE     5            /* Get Display Page */
#define    SCROLLWINUP    6            /* Scroll Window UP */
#define    SCROLLWINDOWN  7            /* Scroll Window DOWN */
#define    SCROLLWINLEFT  8            /* Scroll Window LEFT */
#define    SCROLLWINRIGHT 9            /* Scroll Window RIGHT */
#define    CALLCOLOR      10           /* Color (only in screen 3) */
#define    GCHARCOLOR     11           /* Get Character Color */
#define    SETBORDERCOLOR 12           /* Set Border Color */
#define    SETCOLPALLETTE 13           /* Set Color Pallette */
#define    SETPIXELCOLOR  14           /* Set Pixel Color */
#define    GETPIXELCOLOR  15           /* Get Pixel Color */
#define    SETVECTORCOLOR 16           /* Set Vector Color */
#define    COLORSRCH      17           /* Color Search */
#define    HBLOCKMOVE     18           /* Horizontal Block Move */
#define    HBLOCKCOPY     19           /* Horizontal Block Copy */
#define    LBLOCKMOVE     20           /* Logical Block Move */
#define    LBLOCKCOPY     21           /* Logical Block Copy */
#define    BSCROLLUP      22           /* Block Scroll Up */
#define    BSCROLLDOWN    23           /* Block Scroll Down */
#define    BSCROLLLEFT    24           /* Block Scroll Left */
#define    BSCROLLRIGHT   25           /* Block Scroll Right */
#define    SPRITEDEF      26           /* Sprite Definition */
#define    SPRITEDEL      27           /* Sprite Deletion */
#define    SPRITELOCATE   28           /* Sprite Location */
#define    SPRITEMOTION   29           /* Sprite Motion */
#define    SPRITECOLOR    30           /* Sprite Color */
#define    SPRITEPATTERN  31           /* Sprite Pattern */
#define    SPRITEMAGNIFY  32           /* Sprite Magnification Factor */
#define    SPRITEPOSITION 33           /* Sprite Position */
#define    SPRITECOINC    34           /* Sprite Coincidence Routine */
#define    SPRITEPATDEFGET 35          /* Sprite Pattern Definition/Return */
#define    CHARPATDEFGET  36           /* Character Pattern Definition/Return*/
#define    SETTEXTWINDOW  37           /* Set Text Window */
#define    GETTEXTWINDOW  38           /* Get Text Window */
#define    WRITETTY       39           /* Write Teletype */
#define    RESTORECHARSP  40           /* Restore Character Sprite Pattern */
#define    SETTEXTCOLOR   41           /* Set Text Color */
#define    WRITECHARSTRING 42          /* Write Character String */
#define    PRINTSCREEN    43           /* Print Screen */
#define    HCHARCOLOR     44           /* Horizontal Character/Color Write */
#define    VCHARCOLOR     45           /* Vertical Character/Color Write */
#define    HCHAR          46           /* Horizontal Character Write */
#define    VCHAR          47           /* Vertical Character Write */
#define    SETMOUSE       48           /* Set Mouse Position */
#define    GETMOUSE       49           /* Return Mouse Position */
#define    GETMOUSEREL    50           /* Get Mouse Relative Position */
#define    MAKESOUND      51           /* Make Sound XOP */
#define    SOUNDSTATUS    52           /* Return Sound Status */
#define    VWTR           53           /* VDP Write Registers */
#define    VRFR           54           /* VDP Read Registers */
#define    GETTABLES      55           /* Get Video Tables */
#define    GETPALREGS     56           /* Get Pallette Registers */

IO_H

/*
**   Filename:            io_h
**   Release:             Version 1.5
**   Date:                26/July/1991
**
**   This file contains the definitions for the MDOS I/O library
**
**   Copyright 1991 by LGMA Products
**
**   Revision History:
**
**   26/Jul/91       Initial Release
*/
 
#define    IOXOP          8        /* I/O Library XOP Number */
 
struct pab {
           char      opcode;       /* I/O Opcode */
           char      modeflags;    /* Mode Flags */
           char      errorcode;    /* Returned error code */
           char      highbufadr;   /* high buffer address */
           short     bufferadr;    /* buffer address */
           short     recordnum;    /* record number */
           short     recordlen;    /* record length */
           char      memorytype;   /* memory type */
           char      highcount;    /* high character count */
           short     charcount;    /* character count */
           char      statusbyte;   /* status byte */
           char      namelength;   /* name length */
           char      nametext[40]; /* string containing name */
};
 
/* error codes */
 
#define    NONEXISTENT    0        /* Non-Existent Device Name */
#define    WRITEPROTECT   1        /* Operation Aborted due to Write Prot */
#define    ATTRIBUTEERR   2        /* Bad Open Attribute */
#define    ILLEGALOPERA   3        /* Illegal operation */
#define    FREEBUFFERS    4        /* Out of Table Space, no free buffers */
#define    ENDOFFILE      5        /* Attempt to read past end of file */
#define    LOWLEVEL       6        /* Low Level Device Error (e.g. parity) */
#define    OTHERERRORS    7        /* All other errors */
 
/* Opcodes */
 
#define    OP_OPEN        0         /* Open a file */
#define    OP_CLOSE       1         /* Close a file */
#define    OP_READ        2         /* Read a record */
#define    OP_WRITE       3         /* Write a record */
#define    OP_RESTORE     4         /* Restore pointer to file */
#define    OP_LOAD        5         /* Load a file */
#define    OP_SAVE        6         /* Save a file */
#define    OP_DELETEF     7         /* Delete file */
#define    OP_DELETER     8         /* Delete Record */
#define    OP_STATUS      9         /* File Status check */
#define    OP_BREAD       10        /* Block Read */
#define    OP_BWRITE      11        /* Block Write */
#define    OP_PROTECT     12        /* Protect File */
#define    OP_RENAME      13        /* Rename file */
#define    OP_FORMAT      14        /* Format a device */

KEYBOARD_H

/*
**   Filename:            keyboard_h
**   Release:             Version 1.5
**   Date:                26/July/1991
**
**   This file contains the definitions for the MDOS Keyboard library
**
**   Copyright 1991 by LGMA Products
**
**   Revision History:
**
**   26/Jul/91       Initial Release
*/

#define    KEYXOP         5         /* Keyboard Library XOP Number */

/* Functions */

#define   USELAST      0         /* Use Last Keyboard Mode (must be good!) */
#define   USELEFT      1         /* Use Left Side of Keyboard */
#define   USERIGHT     2         /* Use Right Side of Keyboard */
#define   USESTANDARD  3         /* Use Standard Mode */
#define   USEPASCAL    4         /* Use Pascal Mode */
#define   USEBASIC     5         /* Use Basic Mode */
#define   BREAKCHECK   6         /* Break Key Check */
#define   RAWKEYCHECK  7         /* Raw Keyboard Check */

MATH_H

/*
**   Filename:            Math_h
**   Release:             Version 1.5
**   Date:                26/July/1991
**
**   This file contains the definitions for the MDOS MATH library
**
**   Copyright 1991 by LGMA Products
**
**   Revision History:
**
**   26/Jul/91       Initial Release
*/
 
#define    MATHXOP         10      /* MATH Library XOP Number */
 
#define    FCOMP     0             /* Floating Point Compare */
#define    FSUB      1             /* Floating Point Subtract */
#define    FADD      2             /* Floating Point Add */
#define    FMULT     3             /* Floating Point Multiply */
#define    FDIV      4             /* Floating Point Divide */
#define    PWR       5             /* Power Function */
#define    EXP       6             /* Exponential Function */
#define    LOG       7             /* Natural Logorithm */
#define    SQR       8             /* Square Root */
#define    COS       9             /* Cosine */
#define    SIN       10            /* Sine */
#define    TAN       11            /* Tangent */
#define    ATN       12            /* Arc-Tangent */
#define    GRI       13            /* Floating Point to Greatest Integer */
#define    CFI       14            /* Convert Floating to Integer */
#define    CIF       15            /* Convert Integer to Floating */
#define    CSINT     16            /* Convert string to integer */
#define    CSN       17            /* Convert sting to number */
#define    CNS       18            /* Convert float to string */

MEMORY_H

/*
**   Filename:            memory_h
**   Release:             Version 1.5
**   Date:                26/July/1991
**
**   This file contains the definitions for the MDOS Memory library
**
**   Copyright 1991 by LGMA Products
**
**   Revision History:
**
**   26/Jul/91       Initial Release
*/
 
#define    MEMORYXOP      7        /* Memory Manager XOP Number */
 
#define    AVAILMEMORY    0        /* Return Available Memory */
#define    ALLOCATEMEM    1        /* Allocate Memory */
#define    RELEASEMEM     2        /* Release Memory */
#define    MAPMEMORY      3        /* Map Memory */
#define    GETMEMLIST     4        /* Get Memory List */
#define    DECLARESHARE   5        /* Declare Shared Memory */
#define    RELEASESHARE   6        /* Release Shared Memory */
#define    USESHARED      7        /* Use Shared Memory */
#define    GETSIZESHARE   8        /* Get Size of Shared Memory */
#define    FREETASK       9        /* Free All Memory pages (system only) */
#define    GETMEMPAGE     10       /* Get Memory page (system only) */
#define    FREEMEMPAGE    11       /* Free memory page (system only) */
#define    FREEMEMNODE    12       /* Free memory node (system only) */
#define    LINKMEMNODE    13       /* Link memory node (system only) */
#define    GETMEMLISTS    14       /* Get Memory List (system only) */
 
#define    MAPPERREG     0xf110    /* Mapper Memory Address Start */
 

UTILITY_H

/*
**   Filename:            Utility_h
**   Release:             Version 1.5
**   Date:                26/July/1991
**
**   This file contains the definitions for the MDOS Utility library
**
**   Copyright 1991 by LGMA Products
**
**   Revision History:
**
**   26/Jul/91       Initial Release
*/
 
#define    UTILXOP          9       /* Utility Library XOP Number */
 
/* Functions */
 
#define    CHECKTIME      0         /* Check time for Validity */
#define    CONVTIMESTRING 1         /* Convert time to string */
#define    CONVSTRINGTIME 2         /* Convert string to time */
#define    CHECKDATE      3         /* Check date for Validity */
#define    CONVDATESTRING 4         /* Convert date to string */
#define    CONVSTRINGDATE 5         /* Convert string to date */
#define    CONVMMDDYYYY   6         /* Convert MMDDYYYY to Julian Date */
#define    RETURNDAYOFWK  7         /* Return the day of week */
#define    PARSEFILENAME  8         /* Parse File Name */
#define    LOADPROGRAM    9         /* Load Program Image Filename */

WINDOWS_H

/*
**   Filename:            Windows_h
**   Release:             Version 1.5
**   Date:                26/July/1991
**
**   This file contains the definitions for the MDOS Windows library
**   as defined by Beery Miller of 9640 NEWS
**
**   Copyright 1991 by LGMA Products
**
**   Revision History:
**
**   26/Jul/91       Initial Release
*/
 
#define    WINDOWXOP     11        /* Windows XOP Number */
 
/* 9640 Windows XOP Definitions */
 
#define ACQMULTI     0          /* Acquire MultiTasking Page for 9640 */
#define TEXTDISPLAY  1          /* Display a Null Terminated String */
#define KEYIN        2          /* Keyboard Input routine */
#define FORCEWIN     3          /* Force window to defined location */
#define MULTIOFF     4          /* Multi-tasking OFF */
#define MULTION      5          /* Multi-tasking ON  */
#define FORTYCOL     6          /* Set Windows to 40 Col (internal) */
#define DROPTASK     7          /* Drop Task */
#define BOXIT        8          /* Define a Shaded Window */
#define DROPWINDOW   9          /* Remove last defined window */
#define ACTSLEEP     10         /* Put windows to sleep */
#define DEACTSLEEP   11         /* Wake Up Windows */
#define TASK0PAGE    12         /* Return task 0 pages */
#define TASK7PAGE    13         /* Return task 7 pages */
#define VDPTOCPU     14         /* Fast VDP to CPU for graphic screens */
#define CPUTOVDP     15         /* Fast CPU to VDP for graphic screens */
 

-README (TICRUN)

TICRUN Release 1

(c) 1991 Clint Pulley

Release Notes

This archive contains release 1 of TICRUN, a run-time support package for the TIC 9640 Geneve C compiler.

Files are :

*_H         Header files for use with TIC
*_DOC       Documentation files

TICLIB      Object Library for TIC

LDR         Linking loader v4.0
OLU         Object Library Utility v3.1
LCV         Library Conversion Utility v1.0

FNFTST_C    Test program demonstrating use of fnfset/fnfind functions

Documentation files are pre-formatted and need only be copied to your printer. Be sure the paper is at the top of the page before printing each file.

LIB_DOC














TICRUN - Run-time Support for the TIC 9640 Geneve C Compiler Release 1 Copyright (c) 1991 Clint Pulley Reference Manual All software and documentation contained in this TICRUN release is copyright (c) 1991 by Clint Pulley. All rights reserved. This software carries no warranty, either written or implied, regarding its performance or suitability. The author does not guarantee that the software and documentation which comprise this release of TICRUN is free from error and does not accept responsibility for losses which might derive from its use. TIC is a trademark of LGMA Products, Coopersburg, Pennsylvania, USA. MYARC, MDOS, GENEVE and 9640 are trademarks of MYARC, Inc., Basking Ridge, New Jersey, USA. TI and TI-99/4A are trademarks of Texas Instruments, Inc., Dallas, Texas, USA. ******************************************************************* User-supported software (FAIRWARE) The TICLIB object library, associated software and documentation which comprise TICRUN are provided for your initial evaluation and subsequent use as user-supported software. All material in this release is copyright (c) 1991 by Clint Pulley (the author). Individuals and user groups are encouraged to distribute TICRUN freely provided that any charges levied do not exceed media and reasonable distribution costs. Only complete, unaltered copies of the release material may be distributed. No manufacturer or distributor other than 9640 News may include TICRUN as part of any commercial offering without express permission from the author. If you use TICRUN beyond an initial evaluation period you are morally obligated to send a minimum donation of $20.00 to the author. However, as much of TICRUN is based on the author's previous work (c99 and c99/MDOS), users who have sent donations for those packages may consider $10.00 to be an appropriate contribution. Your donation will help support further development of this product. If you develop useful applications using TICRUN you may market them commercially without payment of software royalties subject to these conditions : - The software and documentation must acknowledge the use of TICRUN and mention the author by name. - The author must be provided with a complimentary copy of the software and documentation as marketed, including updates. Please address correspondence of a technical nature to: Clint Pulley 38 Townsend Avenue Burlington, Ontario Canada L7T 1Y6 (416) 639-0583 (home) Compuserve 73247,3245 Delphi CLINTP Internet u001@cs.cciw.ca TICRUN is distributed by: 9640 News PO Box 752465 Memphis, TN 38175-2465 USA ******************************************************************* TICRUN - Run-time support for the TIC 9640 Geneve C Compiler Copyright (c) 1991 Clint Pulley Table of Contents Introduction ................................................. INT-1 The TICLIB Header Files and Object Library, Release 1 ........ LIB-1 1. TICLIB Header Files ..................................... LIB-1 2. Library Functions ....................................... LIB-2 2.1 Standard Input/Output Functions ( STDIO_H ) ......... LIB-2 2.1.1 Console Input/Output .......................... LIB-2 2.1.2 File Input/Output ............................. LIB-4 2.1.3 Formatted Input/Output ........................ LIB-8 2.1.4 MDOS-Specific Input/Output Functions .......... LIB-9 2.2 Character Handling Functions ( CTYPE_H ) ............ LIB-11 2.3 String Handling Functions ( STRING_H ) .............. LIB-11 2.4 Utility Functions ( STDLIB_H ) ...................... LIB-13 2.5 Time/Date Access Functions ( TIME_H ) ............... LIB-16 2.6 Video/Graphics Functions ( VIDEO_H ) ................ LIB-16 2.6.1 Graphic Input Functions ....................... LIB-17 2.6.2 Video Functions for Text and Graphics Modes ... LIB-17 2.6.3 Video Functions for Bitmap Graphics Modes ..... LIB-21 2.6.4 Sprite Functions for all Graphics Modes ....... LIB-24 3. Programming Information ................................. LIB-28 LDR v4.0 - a Linking Loader for MDOS ......................... LDR-1 OLU v3.1 - an Object Library Utility for MDOS ................ OLU-1 LCV v1.0 - an Object Library Conversion Utility for MDOS ..... LCV-1 . TICRUN - Run-time support for the TIC 9640 Geneve C Compiler Introduction TICRUN (TI-C-RUN) is a run-time support package for the TIC 9640 Geneve C Compiler which was developed by Al Beard of LGMA Products, Coopersburg, Pennsylvania, USA. TICRUN was developed with Al's full knowledge, approval and co-operation. TIC and TICRUN together comprise a complete development package for K&R style C programs on the Myarc Geneve 9640 Computer. The TICRUN package is made up of several components : - A set of header files which, when #included in any TIC program, make a substantial number of library functions available to the programmer. - The object library TICLIB which contains object modules for all of the functions available in TICRUN. - The linking loader LDR which links object files generated by TIC with all required functions in TICLIB and either runs the program or generates a program image file for later execution. - The object librarian OLU which provides facilities for creating and maintaining object libraries which can be used with LDR. - The library conversion utility LCV which converts object libraries generated by earlier versons of OLU into the current format. - Documentation for all components of TICRUN. The author has tried to make the standard functions in TICLIB conform to the behaviour described in K&R. This has not always been possible, especially in the case of file input/output as the record-based file structures designed by Texas Instruments for the TI-99/4A computer are quite different from (and in some ways, superior to) the simple byte-stream file structure used by Unix. Programmers who feel that these differences are an impediment to program development are invited to discuss them with the author. Much of TICRUN is based on the author's earlier work with small-c which resulted in the release of c99 and c99/MDOS. Thanks are due to the many TI-99/4A and Myarc Geneve users who supported these efforts. (c) 1991 Clint Pulley 12-08-91 Page INT-1 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB The TICLIB Header Files and Object Library Many facilities that are used in TIC programs are not part of the language but are provided as standard library functions written in TIC or assembler for use by TIC programs. These facilities include : - operations on characters and strings - accessing the time and date - storage allocation functions - input and output operations - video and graphics functions Each facility belongs to a particular function group. The correct way to use a facility is to have, at the beginning of the program, a #include directive to include the relevant header file for that function group. All functions in the group are then specified as to type and any functions actually referenced will be retrieved from the object library and linked to the user program at load time. For example, in order to use the string function "strlen" in a program, the TIC programmer should place a directive similar to #include <string_h> at the start of the program. This makes "strlen" (and all other functions declared in string_h) available for subsequent use. 1. TICLIB Header Files The header files provided with this release of TICLIB are: a) STDIO_H (Standard Input/Output) - Contains I/O definitions for console and file functions as well as declarations for all input/output functions. b) CTYPE_H (Character Handling) - Contains declarations for standard C character handling functions. c) STRING_H (String Handling) - Contains declarations for standard C string handling functions. d) STDLIB_H (Utility Functions) - Contains declarations for standard and MDOS-specific utility functions. e) TIME_H (Time/Date Access) - Contains declarations for time and date retrieval functions. f) VIDEO_H (Video/Graphics Functions) - Contains declarations for MDOS-specific video and graphics functions. (c) 1991 Clint Pulley 12-08-91 Page LIB-1 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB 2. Library Functions Each function is presented by a prototype which indicates the function type and arguments required. Functions which are not of type "void" will return a value. Arguments are of type int unless a type declaration appears with the prototype. When an argument must be preceded with the & operator this will be noted with the flag "< & >". Failure to provide the & will often lead to catastrophic errors! 2.1 Standard Input/Output Functions ( STDIO_H ) For convenience the input/output function descriptions have been divided into four subgroups. All functions have been implemented using MDOS system calls. 2.1.1 Console Input/Output -Read one character from the keyboard. int getchar(); Waits for a key to be pressed and returns the character value. The character is echoed to the screen. If the character is "ENTER", the screen spaces to the start of a new line and a value of 10 (EOL) is returned. If the character is CTRL-Z, -1 (EOF) is returned. The PASCAL (mode=4) keyboard scan mode is used in all TIC keyboard input. Pressing Control-C at any time during program execution results in a "clean" abort with any open files being closed. This may be disabled by storing 0 at location >00FE. -Write one character to the screen. int putchar(c); Writes the character whose ascii value is c to the screen. If c== 10 (EOL), the screen spaces to the start of a new line. If c==8 (BS), the cursor is backspaced. If c==12 (FF),the screen is cleared and the cursor is homed. If c is any other non-printing character, the action taken will be determined by the operating system (currently undocumented). The value of c is returned. -Read a line from the keyboard. char *gets(buff); ( char buff[81]; ) Reads one line from the keyboard into a character array. Characters are echoed to the screen as they are entered. The line is terminated with ENTER, CTRL-Z or the 80th character. The array is assumed to be 81 characters long and a null (0) character is appended to the end of the string. A value of buff is returned unless CTRL-Z is pressed. (c) 1991 Clint Pulley 12-08-91 Page LIB-2 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB In that case, NULL is returned. Use of the backspace key (FCTN-S) for inline editing is supported. -Write a string to the screen. void puts(string); ( char *string; ) Writes a string to the screen, stopping when it finds a null character. The null character is not written. The cursor is not spaced to the start of a new line unless newline (\n) is encountered. -Exit the program. void exit(c); Branches to the TIC exit function which closes any open files. The value of c may be between 0 and 7 and determines the type of exit as follows : c = 0,7 no exit message, returns to MDOS c = 1-6 err=c exit message, returns to MDOS -Locate the cursor on the screen. void locate(row,col); Places the cursor at the screen location specified by row and col. Subsequent screen output will start at the new cursor location. Row and column numbering start at 1 as in TI Basic. The validity of row and col is not checked. -Check keyboard status. int poll(c); Scans the keyboard and returns the key value (if one is pressed) or 0. If c != 0, the program will pause while a key is down. Characters are not echoed to the screen. This function may be used to provide a simple means of causing a program to wait until a key is pressed. Typical usage is : while(!poll(0)); -Change text mode screen colors. void tscrn(f,b); Changes the text mode screen colors to f (foreground) and b (background). The Basic color number convention (1-16) is used. Notes : a) The current video state may be determined by accessing the external variables s_mode (current video mode), s_wdth (current screen width) and s_hght (current screen height). To make these variables available for testing, provide a statement such as (c) 1991 Clint Pulley 12-08-91 Page LIB-3 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB extern int s_mode,s_wdth,s_hght; 2.1.2 File Input/Output In most of the file I/O functions which reference the argument "unit", the operation will default to the corresponding console I/O function if the value of unit is <= 0. For this reason, the values for stdin, stdout, and stderr as defined in STDIO_H are -1, -2 and -3. -Open a file. FILE fopen(name,mode); ( char *name,*mode; ) Opens the named file in the specified mode. Both name and mode must be strings or pointers to strings. Supported modes (as dictated by MDOS) are: display/variable display/fixed display/relative "r" - read "R" - read "I" - read "w" - write "W" - write "O" - read/write "a" - append "U" - update In addition to these "standard" processing modes, TICLIB adds two special processing modes to the fopen function. These modes allow switch extensions to be used with PIO and RS232 (eg. PIO.CR) in conjunction with current versions of MDOS such as 0.97H. Use of these modes with older versions of MDOS should not present problems. The special modes are : "s" - display/variable write with switch extensions "S" - display/fixed write with switch extensions Prefixing the mode descriptor with i will result in an internal file type. The mode character may be followed by a 1-3 digit record length. If this is omitted, a default length of 80 is assigned. If the file is opened for input and a record length of zero is specified, the actual record length of the existing file is utilized. The function ferrc(unit), issued immediately after fopen, can be used to obtain the record length. TIC file input/output allows up to 8 files to be open simultaneously. All files may have a record length of 128 bytes or less and one or two files may have record lengths of up to 256 bytes. Any legal MDOS filename of 40 characters or less may be used. By default, all alphabetic characters in filenames are mapped to upper case (see notes below for information about invoking case-sensitive filenames). A unit number is returned for use with the file I/O functions. This unit number must not be altered. If the open fails, NULL (0) is returned. The function fopenec may be used to obtain the error code for fopen. (c) 1991 Clint Pulley 12-08-91 Page LIB-4 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB Examples : a) Open A:MYFILE as D/V 80 to read - unit=fopen("a:myfile","r"); b) Open B:ZZ as I/F 128 to write - unit=fopen("b:zz","iW128"); c) Open PIO.CR as D/V 80 to write - unit=fopen("pio.cr","s"); -Close a file. int fclose(unit); ( FILE unit; ) Performs the appropriate file closing action and makes the unit available for another file. In the case of output files being written with putc, an incomplete line is lost. This function returns NULL if the close fails and non-null if it succeeds. All open files are closed automatically if a program terminates normally. -Read one character from a file. int getc(unit); ( FILE unit; ) Reads and returns the next character from the file corresponding to unit. If the end-of-line is reached a value of 10 (EOL) is returned. If the end-of-file is reached, a value of -1 (EOF) is returned. If an error occurs, -2 (ERR) is returned. -Write one character to a file. int putc(c,unit); ( FILE unit; ) Writes the character whose ascii value is c to the file. If c==10 (EOL), the actual write operation occurs. The value of c is returned. If an error occurs, -2 (err) is returned. -Read a string from a file. char *fgets(buff,col,unit); ( char buff[col]; FILE unit; ) Reads one line from the file into a character array. At most, col-1 characters will be transferred. A null character is appended to the end of the line. If a partial line is transferred, the remainder of the line is discarded. If unit<=0, gets is called and the value of col is ignored. This could result in buffer overflow. A value of buff is returned. If an end-of-file or error condition occurs, NULL is returned. -Write a string to a file. char *fputs(string,unit); ( char *string; FILE unit; ) Writes a string to a file, stopping when it finds a null character. Imbedded EOL characters act as record terminators, so multiple records can be generated by a single call to fputs. A value of buff is returned. On end-of-file or error, NULL is returned. (c) 1991 Clint Pulley 12-08-91 Page LIB-5 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB -Read a record from a file. int fread(buff,len,unit); ( char buff[len]; FILE unit; ) Reads the next record from the file into the buffer area starting at buff. At most, len bytes will be transferred. A null byte is NOT appended. If a partial record is transferred, the remainder is discarded. The actual number of bytes transferred is returned. If an end-of-file or error condition occurs, -2 (ERR) is returned. fread does not default to the console. -Write a record to a file. int fwrite(buff,len,unit); ( char buff[len]; FILE unit; ) Writes a record of len bytes from the buffer area starting at buff. If len is greater than the maximum record length for the file the record is truncated. No special action occurs for null or EOL bytes. The actual number of bytes transferred is returned. If an error condition occurs, -2 (ERR) is returned. fwrite does not default to the console. Note : fread/fwrite provide a binary I/O capability for applications such as printer control since all bytes are transferred regardless of value. fputs cannot be used for printer graphics since the first null byte in the output string terminates the transfer. If the buffer area is comprised of consecutive global variables and arrays then transfers can be made directly from/to the variables and arrays. If the first element of the buffer area is a scalar variable then its address (&var) must be used in the function call. -Set record number. void fseek(unit,recno); ( FILE unit; ) Sets the record number for the next I/O operation (fread or fwrite) on unit. This function provides a random access capability for files opened as relative. If a single fseek is followed by multiple fread or fwrite operations access becomes sequential starting with recno. -Rewind a file. void rewind(unit); (FILE unit; ) If a disk file is open for read or append it is rewound. All other cases are ignored. -Test for end-of file. int feof(unit); Returns a true value if the next read from unit would return an end-of-file error condition. Returns false otherwise. (c) 1991 Clint Pulley 12-08-91 Page LIB-6 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB -Get error code. int ferrc(unit); If the previous I/O operation resulted in an error, returns the error code. This function should be used only when an error has occurred. The returned value is meaningless otherwise. MDOS I/O error codes are : 1 - device is write-protected 2 - bad open attribute (filetype, record length, mode) 3 - illegal operation for this device 4 - out of space or no free buffers 5 - attempt to read past end-of-file 6 - device error (parity, bad media) 7 - other errors (eg. nonexistent file) This function cannot be used after fopen errors since unit is not valid at that time. If used immediately after a successful fopen, ferrc returns the actual record length of the file. -Get error code after fopen. int fopnec(); If the previous fopen call resulted in an error, return the error code. Two additional error codes are returned by this function : 8 - invalid fopen mode descriptor 9 - too many open files Notes : By default, TIC file I/O operations convert all lowercase characters in device, file and directory name arguments to upper case and uses the MDOS filename parser to determine actual device names. For situations where such actions are not desirable TIC file I/O provides global flag variables for the control of filename parsing and case sensitivity. If filename parsing is inhibited then filenames are passed to the MDOS file system exactly as specified by the programmer thereby avoiding any quirks in the current MDOS filename parser. If case sensitivity is invoked then filenames are passed to the parser without converting lower case characters to upper case. a) To control filename parsing, declare a global external variable as: extern int npflag; If npflag==0 (FALSE, the default value), filenames are parsed. If npflag!=0 (TRUE) then filename parsing does not occur. npflag may be set/cleared as required in the program. (c) 1991 Clint Pulley 12-08-91 Page LIB-7 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB b) To control filename case sensitivity, declare a global external variable as: extern int csflag; If csflag==0 (FALSE, the default value), filenames are upper case. If csflag!=0 (true) then filenames are case sensitive. csflag may be set/cleared as required in the program. 2.1.3 Formatted Input/Output In the functions described in this section arguments named arg1, arg2 etc. may be of any type. - Write formatted data to the screen. void printf(fmt,arg1,arg2,...) ( char *fmt; ) - Write formatted data to a file. void fprintf(unit,fmt,arg1,arg2,...) ( FILE unit; char *fmt; ) - Write formatted data to a string. void sprintf(string,fmt,arg1,arg2,...) ( char *string,*fmt; ) - Read formatted data from the keyboard. int scanf(fmt,&arg1,&arg2,...) ( char *fmt; ) < & > - Read formatted data from a file. int fscanf(unit,fmt,&arg1,&arg2,...) ( FILE unit; char *fmt; ) < & > - Read formatted data from a string. int sscanf(string,fmt,&arg1,...) ( char *string,*fmt; ) < & > Notes : a) The formatted input/output functions are discussed in detail by every introductory C text. The TIC versions perform as in standard C with these conversion modes : c - single character d - signed decimal o - octal s - character string u - unsigned decimal x - hexadecimal b) In order to provide inline editing for keyboard input, scanf was implemented using gets. As a result, no conversions occur until the (c) 1991 Clint Pulley 12-08-91 Page LIB-8 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB input line is ended with the Enter key. scanf has an internal 81 byte line buffer which is only reset on the first call to scanf. If more data items are entered than have been scanned, the remainder of the input line is available to the next scanf call. If the program is rerun by exit option this will also be true. c) The scanf functions return a count of the number of items converted. On error, end-of-file, or empty string (sscanf) conditions, EOF is returned. 2.1.4 MDOS-Specific Input/Output Functions These functions are not part of standard C but are included in STDIO_H for convenience. -Delete a file. int fdelete(filename); ( char *filename; ) Deletes the file specified by filename, which must be a string or pointer. No error conditions are returned. Returns 0 if successful, a non-zero error code if not. -Rename a file. int frename(old_name,new_name); ( char *old_name,*new_name; ) Renames the file specified by old_name to new_name. old_name should include the device name if required, new_name must consist of only the filename. Returns 0 if successful, a non-zero error code if not. - Create a directory. int fmkdir(dirname); ( char *dirname; ) Creates a directory. If dirname includes a path specification the directory is created at that location. Otherwise, the directory is created in the current directory/device. Returns 0 if successful, a non-zero error code if not. - Delete a directory. int frmdir(dirname); ( char *dirname; ) Deletes a directory. If dirname includes a path specification the directory is deleted at that location. Otherwise, the directory is deleted in the current directory/device. Returns 0 if successful, a non-zero error code if not. - Load a program file. int fload(fname,buffer,len) ( char *fname,buffer[len]; ) Transfers up to len bytes from the program file fname to buffer. Returns 0 if successful, a non-zero error code if not. (c) 1991 Clint Pulley 12-08-91 Page LIB-9 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB - Save a program file. int fsave(fname,buffer,len) ( char *fname,buffer[len]; ) Creates a program file fname of length len containing buffer. Returns 0 if successful, a non-zero error code if not. - Perform block/sector input/output These functions allow blocks to be read or written regardless of file type. They must be used with care as file/filesystem damage is possible. The functions are: int bread(fname,sector,nsect,buffer); int bwrite(fname,sector,nsect,buffer); Returns 0 if successful, a non-zero error code if not. Arguments are: char *fname : pointer to file or device name. If device ("a:", "DSK1.") accesses physical sectors on device. unsigned int sector : starting sector for operation. int nsect : number of sectors to read/write. char *buffer : pointer to buffer which must be large enough to contain the information. malloc is useful here. If nsect==0, the file ID information block is read/written as follows: bytes contents 0,1 extended record length, used for files with records longer than 255 bytes 2 file status flags: Bit: Msb 7 6 5 4 3 2 1 0 | | | | | | | +-> 0 - 0-DATA 1-PROGRAM | | | | | | +---> 1 - 0-ASCII 1-BINARY | | | | | +-----> 2 - RESERVED | | | | +-------> 3 - 0-NOT PROTECTED 1-PROTECTED | +-+-+---------> 4-6 - RESERVED +---------------> 7 - 0-FIXED 1-VARIABLE 3 # of records which can fit in a sector (256 bytes) 0 for program image, extended record lengths 4,5 number of sectors reserved for file 6 number of bytes used in last sector of file (0 means all 256 are used) 7 logical record length 0 for program image, extended record lengths 8,9 (bytes reversed) for fixed files, (highest used record number) for program image, variable files, number of sectors actually used (c) 1991 Clint Pulley 12-08-91 Page LIB-10 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB 10,11 date of creation bits: yyyy yyyM MMMd dddd 12,13 time of creation hhhh hmmm mmms ssss seconds are / 2, with remainder discarded 14,15 date of last change " 16,17 time of last change " 18,19 0 In this version of TICLIB, sectors greater than 65535 cannot be accessed. When TIC supports long integers this will be changed. 2.2 Character Handling Functions ( CTYPE_H ) These standard C functions accept an argument of type int or char. As they are often used intensively in text handling applications they have been written in assembler. - Test for character class. int isalpha(c); true if c is a letter int isupper(c); true if c is an uppercase letter int islower(c); true if c is a lowercase letter int isdigit(c); true if c is a decimal digit int isalnum(c); true if c is an alphanumeric character int isspace(c); true if c is a space, tab, CR, EOL or FF int ispunct(c); true if c is a punctuation character int isprint(s); true if c is a printing character (incl space) int isgraph(c); true if c is a graphic character (excl space) int iscntrl(c); true if c is a control character ( < 32 ) int isascii(c); true if c is an ASCII character ( < 128 ) int isxdigit(c); true if c is a hexadecimal digit - Convert lowercase letter to uppercase. int toupper(c); If c is a lowercase letter, returns the uppercase equivalent. Otherwise, returns c. - Convert uppercase letter to lowercase. int tolower(c); If c is an uppercase letter, returns the lowercase equivalent. Otherwise, returns c. 2.3 String Handling Functions ( STRING_H ) These functions provide fundamental string manipulation operations. Originally written in c99 by Tom Wible, they were converted to highly optimized assembler by Ken Caruthers and further improved by Clint Pulley. String usage is discussed in all standard C texts. (c) 1991 Clint Pulley 12-08-91 Page LIB-11 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB - Determine string length. int strlen(string); ( char *string; ) Returns the length of string, excluding the zero-byte terminator. - Compare two strings. int strcmp(str1,str2); ( char *str1,*str2); Compares str1 to str2 up to and including the terminator for str1. Returns a negative value if str1 < str2, a zero value if str1 == str2 and a positive value if str1 > str2. - Compare up to n characters of two strings. int stncmp(str1,str2,n); ( char *str1,*str2); (c99 form) int strncmp(str1,str2,n); ( char *str1,*str2); Compares at most n characters of str1 to str2. If the terminator is found in either string the comparison stops. Returns a negative value if str1 < str2, a zero value if str1 == str2 and a positive value if str1 > str2. - Search for a character in a string. int index(string,c); ( char *string; ) Searches string for the first occurrence of a character with the value c. Returns the character position or zero if c is not found. - Search for a character in a string, scanning from the right. int rindex(string,c); ( char *string; ) Searches string from the right for the first occurrence of a character with the value c. Returns the character position or zero if c is not found. - Concatenate two strings. char *strcat(str1,str2); ( char *str1,*str2; ) Copies str2 onto the end of str1. The character array pointed to by str1 must be long enough to contain the resulting string. Returns a pointer to str1. - Partially concatenate two strings. char *stncat(str1,str2,n); ( char *str1,*str2; ) (c99 form) char *strncat(str1,str2,n); ( char *str1,*str2; ) Copies at most n characters of str2 onto the end of str1. If the terminator is encountered in str2 the concatenation stops. The character array pointed to by str1 must be long enough to contain the resulting string. Returns a pointer to str1. (c) 1991 Clint Pulley 12-08-91 Page LIB-12 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB - Copy a string. char *strcpy(str1,str2); ( char *str1,str2; ) Copies str2 into str1. The character array pointed to by str1 must be long enough to contain str2. Returns a pointer to str1. - Partially copy a string. char *stncpy(str1,str2,n); ( char *str1,*str2; ) (c99 form) char *strncpy(str1,str2,n); ( char *str1,*str2; ) Copies at most n characters of str2 into str1. If the terminator is encountered in str2 the copy stops. The character array pointed to by str1 must be long enough to contain the resulting string. Returns a pointer to str1. 2.4 Utility Functions ( STDLIB_H ) This function group is a catch-all for many useful functions. - Allocate memory from free space. char *malloc(nbytes); Allocates nbytes of memory from available free space which extends from the end of the program image (SLAST) to location >EFFE in visible memory. Returns a pointer to the start of allocated space or 0 if insufficient memory is available. The value of mp is always even so space for char or int arrays may be assigned. For int, nbytes should be 2 * the number of elements required. On the first call to malloc, all unassigned pages in the 64k visible memory space are assigned. If the initial call cannot allocate the required memory, a message is displayed and execution is terminated. Memory allocation by successive calls is sequential. Typical usage : int *iar; /* instead of int iar[1000]; */ ... iar=malloc(2000); /* allocate an int [1000] array */ ... iar[0]=1; - Release previously allocated memory. char *free(mp); Release all previously allocated memory starting at mp, which must not be less than the start of free memory (SLAST). Returns mp if successful, NULL if mp < SLAST. Memory is usually released in the reverse order from which it was allocated. - Release all allocatable memory. void freeall(); (c) 1991 Clint Pulley 12-08-91 Page LIB-13 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB Resets free memory pointer to start of free memory (SLAST). - Convert a string to integer. int atoi(str); ( char *str; ) Converts the signed decimal string contained in str to an integer value. Conversion stops at the first non-decimal character after the (optional) - sign. - Convert an integer value to a signed decimal string. void itoa(n,str); ( char *str; ) Converts the integer value contained in n to a signed decimal string in str which must be long enough to contain the result. - Convert an integer value to an unsigned string using the specified base. void itoneb(n,str,b); ( char *str; ) Converts the value contained in n to an unsigned numeric string in str which must be long enough to contain the result. Conversion is performed using the mathematical base b. b is usually 2, 8, 10 or 16 but any other value up to 36 may be used. - Initialize the random seed. void randomize(); Initializes the starting seed for the random number generator to a random value. - Generate a 16-bit pseudo-random number. int rndnum(); Returns a random 16-bit integer which may take any value between -32768 and 32767. - Generate a pseudo-random number in a specified range. int rnd(i); Returns a random integer value in the range (0,i-1). - Generate sounds. void sound(duration,freq1,atten1[,freq2,atten2][,freq3,atten3] [,noise,attenn]); Generates one or more tones and noise. Arguments for freq2, freq3 and noise are optional as with Basic's CALL SOUND. Arguments are : (c) 1991 Clint Pulley 12-08-91 Page LIB-14 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB duration = +/- duration of sound in 1/60 sec (16.7 msec) units if +, waits for completion of previous sound if -, changes sound immediately freq1/2/3 = frequency of 1-3 tones in hertz (110 thru 32767) atten1/2/3 = attenuation of tones 1-3 in 2 db steps (0-15) noise = noise type : periodic white 0 = 6991 hz 4 = 6991 hz 1 = 3496 hz 5 = 3496 hz 2 = 1738 hz 6 = 1738 hz 3 = same as freq3 7 = same as freq3 attenn = attenuation of noise in 2 db steps (1-15) - Invoke the MDOS Command Line Interpreter. int callcli(command_string); ( char *command_string; ) Calls the MDOS Command Line Interpreter (CLI) to process the command in command_string. At MDOS 0.97h, only intrinsic commands may be processed (eg. dir, del, time etc.). Returns true if the running version of MDOS does not support this feature. CAUTION : Use of certain CLI commands (ie. copy) with MDOS 1.14/0.97h will result in the system crashing when batch files are executed later. This is believed to be an internal MDOS problem. - Compare a string with a pattern containing wildcard characters. int wmatch(pattern,str,len); ( char *pattern,*str; ) Compares string str of length len (excluding the zero-byte terminator) with string pattern which may contain the wildcard characters ? (match any single character) and * (match 0 or more characters) in any position. Returns true if the match is successful. - Search for filenames which match a pattern containing wildcard strings. Searching a directory for matching filenames involves the use of two functions. fnfset is invoked once to initialize the search and fnfind is invoked repeatedly to obtain each filename and type. int fnfset(name); ( char *name; ) Initialize the search for filenames matching the pattern in name which may include a path specification and a filename containing ? and * wildcard characters. If a path specification is not provided the current default directory is searched. Returns true if name contains wildcard characters. If fnfset returns false then name contains an actual filename and fnfind should not be called. char *fnfind(&ft); < & > Searches for the next filename match. Returns a pointer to the matched filename or NULL if no more matches are found. If successful, ft contains the filetype : 1=d/f, 2=d/v, 3=i/f, 4=i/v, (c) 1991 Clint Pulley 12-08-91 Page LIB-15 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB 5=program image. - Parse a path/file name string. char *parsfn(inptr,outptr); ( char *inptr, *outptr; ) Uses the MDOS filename parser to parse the string in inptr. The result is stored in outptr. A stack buffer is used to hold intermediate results so inptr and outptr may point to the same location. Returns outptr or NULL if the string cannot be parsed successfully. 2.5 Time/Date Access Functions ( TIME_H ) - Get current time. char *time(str); ( char str[10]; ) Accesses the system clock and stores the current time in str. Returns a pointer to str. - Get current date. char *date(str); ( char str[10]; ) Accesses the system clock and stores the current date in str. Returns a pointer to str. - Get day of week index. int dow(); Accesses the system clock and returns an index (1-7) to the day of the week. 2.6 Video/Graphics Functions ( VIDEO_H ) Most of the TIC video/graphics functions have been implemented using the MDOS video library functions available in version 0.97h. It should be noted that the efficiency of certain video functions is determined by their implementation in MDOS. In addition to the character functions documented below, the standard keyboard and screen functions (getchar, gets, scanf, putchar, puts, printf and locate) appear to work correctly with characters displayed in the text mode colors. Numbering conventions for character and pixel positions, colors, sprites and sprite position conform to Extended Basic usage and start at 1. In mode 7, the color number is an 8 bit value containing red, green and blue intensities encoded as gggrrrbb. Because of the large number of TIC video/graphics functions, this section of the manual has been divided into four logical groupings. (c) 1991 Clint Pulley 12-08-91 Page LIB-16 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB 2.6.1 Graphic Input Functions - Read from the keyboard. int key(u,&s); < & > Reads the keyboard in mode u, returns the character value of the key pressed. s contains the current keyboard status. Keyboard mode and status conform to TI-99/4A usage. The character is not echoed to the screen. - Read from a joystick. int joyst(u,&x,&y); < & > Reads joystick u (1 or 2) and stores the x and y values (0 for no displacement, +4 for positive, -4 for negative). The function value is true if x || y != 0, so this may be used as a quick check for joystick displacement. - Read from the mouse. int mouse(&x,&y); < & > Returns the relative x and y steps since the last mouse call. x and y are set to zero by the first call. The function value is the logical OR of: 1 - right button pressed 2 - middle button pressed 4 - left button pressed 2.6.2 Video Functions for Text and Graphics Modes MDOS supports the 9938 video processor in these modes : Mode Description Text Text Pixel Pixel # of # of Sprite Rows Cols Rows Cols Colors Pages Mode 0 40 column text 24 40 - - 2/16 32 - 1 80 column text 26 80 - - 2/16 16 - 2 Multicolor - - 48 64 16 32 1 3 Graphics 1 (character) 24 32 192 256 16 32 1 4 Graphics 2 (semi bitmap) 24 32 192 256 16 8 1 5 Graphics 3 (semi bitmap) 24 40 192 256 16 8 2 6 Graphics 4 (true bitmap) 26 40 212 256 16 4 2 7 Graphics 5 (true bitmap) 26 80 212 512 4 4 2 8 Graphics 6 (true bitmap) 26 80 212 512 16 2 2 9 Graphics 7 (true bitmap) 26 40 212 256 256 2 2 10 80 column text 24 80 - - 2/16 16 - Graphics 1 mode is the character graphic mode supported by TI Basic. Graphics 2/3 modes are the "bitmap" mode available on the TI-99/4A. (c) 1991 Clint Pulley 12-08-91 Page LIB-17 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB All functions have been verified in the text and/or true bitmap modes only as these are by far the most useful. Sprite and character functions have also been tested in Graphics 1 mode. - Set video mode. int vidmode(m); Sets video mode to m (0-9), returns the current border color. The text mode in effect at program start is stored for ^C exit. For bitmap modes, the background color will be the border color in effect at time of call. If in text mode before the call, mode is saved for txtmode(). The screen globals (s_mode, s_wdth, s_hght) are updated. Notes : a) If the bitmap graphics functions (described in subsection 3) are to be used, the grfmode function should be used instead of vidmode. b) If the ^C exit is to be disabled this should be done after the first call to vidmode or grfmode. - Restore text mode. void txtmode(); Restores video to the most recently used text mode. - Set border color. void setbor(c); Sets the border (backdrop) color to c. - Initialize and set display page. void inidpg(pg); Sets the display page to pg (0-n) and initializes video tables. The range of pg depends on the video mode in use. At program start and after an initial mode change page 0 is assigned. This function is used to provide multiple screens. A typical use is to present a "help" screen at program start using a page other than 0. At any time this screen can be redisplayed by calling setdpg. - Set display page. void setdpg(pg); Sets the display page to pg (0-n) without altering video tables. - Get display page. int getdpg(); (c) 1991 Clint Pulley 12-08-91 Page LIB-18 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB Returns the current display page number. - Get cursor position. void curpos(&row,&col); < & > Returns the current character cursor position in row and col. - Set text window for normal screen output. void settxw(tr,tc,br,bc); Defines a "hard" text window in the current page. All cursor positioning, normal screen output, and scrolling occur within this window. Each display page may have a different window. If a window is defined for display page 0 when the program exits, that window may remain in effect for command processing. A final call to settxw defining the entire screen as the window will eliminate this situation. Arguments are tr=character position of top row tc=character position of top column br=character position of bottom row bc=character position of bottom column - Get text window coordinates. void gettxw(&tr,&tc,&br,&bc); < & > Returns the text window coordinates currently in effect. Arguments are tr=character position of top row tc=character position of top column br=character position of bottom row bc=character position of bottom column - Scroll a block of text. These four functions scroll a block of text within a "soft" window on the screen. Normal screen output is not affected by these functions. Row and column coordinates refer to the entire screen. All function calls are of the form : void scrlwx(nl,rul,cul,rlr,clr,ch,f,b); scrlwx is one of the function names listed below. Arguments are nl = number of lines to scroll rul = row number of upper left corner of window cul = column number of upper left corner of window rlr = row number of lower right corner of window clr = column number of lower right corner of window ch = character value for blank lines f = foreground color for blank lines (c) 1991 Clint Pulley 12-08-91 Page LIB-19 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB b = background color for blank lines f and b are effective in graphic modes only but must be present in all calls. The functions names are scrlwu - scroll up scrlwd - scroll down scrlwl - scroll left scrlwr - scroll right - Display a character with horizontal repetition. void hchar(r,c,ch,n); Displays character ch at row r, column c and repeats n times horizontally. Text colors are used. - Display a character with vertical repetition. void vchar(r,c,ch,n); Displays character ch at row r, column c and repeats n times vertically. Text colors are used. - Display a character in specified colors with horizontal repetition. void hcharc(r,c,ch,n,f,b); Displays character ch at row r, column c and repeats n times horizontally. The foreground color is f, background is b. In Graphics 1 mode the colors for the character group are set. - Display a character in specified colors with vertical repetition. void vcharc(r,c,ch,n,f,b); Displays character ch at row r, column c and repeats n times vertically. The foreground color is f, background is b. In Graphics 1 mode the colors for the character group are set. - Define a character pattern. void chrdef(ch,iar); ( int iar[4]; ) Defines the character pattern for character ch (0-255). iar is a 4 element int array containing the (binary) pattern data. In text and true bitmap modes, characters are 6x8 pixels in size. The pattern arrays are usually defined by use of initializers (using hex data), but data can be manipulated (inverted, shifted, etc.) with TIC arithmetic operations. The following example will define character 128 : int pat[4]={ox2050,0x8888,0x8888,0x2050}; (c) 1991 Clint Pulley 12-08-91 Page LIB-20 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB ... chrdef(128,pat); As the standard character set (32-127) is not restored by MDOS at program exit, these character patterns should not be modified. - Retrieve a character pattern. void chrpat(ch,iar); ( int iar[4]; ) Retrieves the character pattern for character ch. iar is a 4 element int array which will contain the pattern data on return. - Get a character value. int gchar(r,c); Returns the value of the character displayed at row r, column c. - Get character and color values. int gcharc(r,c,&f,&b); < & > Returns the value of the character displayed at row r, column c. The foreground color is returned in f, the background color in b. - Set a color. void palette(c,red,green,blue); Sets color c (1-16) to the specified red, green and blue values (0-7). Altered colors remain in effect at program exit. The following values approximate the standard palette. Color Name Red Green Blue Color Name Red Green Blue 1 T'sparent 0 0 0 9 Md Red 7 1 1 2 Black 0 0 0 10 Lt Red 7 3 3 3 Md Green 1 6 1 11 Dk Yellow 6 6 1 4 Lt Green 3 7 3 12 Lt Yellow 6 6 4 5 Dk Blue 1 1 7 13 Dk Green 1 4 1 6 Lt Blue 2 3 7 14 Magenta 6 2 5 7 Dk Red 5 1 1 15 Gray 5 5 5 8 Cyan 2 6 7 16 White 7 7 7 This function is not useable with Graphics 7 mode. 2.6.3 Video Functions for Bitmap Graphics Modes Function names and calling sequences are, as far as possible, compatible with c99 and c99/MDOS. As a result, conversion of c99 bitmap programs to TIC graphics mode 4 is quite straightforward. The available true bitmap graphics modes are : (c) 1991 Clint Pulley 12-08-91 Page LIB-21 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB 4 - 256 x 212 x 16 colors 5 - 512 x 212 x 4 colors 6 - 512 x 212 x 16 colors 7 - 256 x 212 x 256 colors Pixel coordinates are referred to as row and column or x and y depending on usage. The two schemes are equivalent (row = y, column = x) with coordinates (1,1) referring to the upper left corner of the screen. All functions are implemented using MDOS video XOPS except for plot and getpix. These functions use direct VDP access to improve performance. - Set video mode to graphics 4-7. void grfmode(mode,c); Sets the video processor to the specified GRAPHICS mode (4-7) and changes the backdrop to color c. If mode is out of range, graphics 4 is selected. This function should be used instead of vidmode for selecting bitmap modes as the backdrop color is retained for use with other bitmap functions. The mode setting is performed by vidmode so ^C handling and updating of screen globals are as noted. - Clear the bitmap screen. void bitclr(); Clears the screen in bitmap graphics modes. putchar(FF) does not perform in the same manner. - Plot a single pixel. void plot(x,y,c); Displays a pixel in color c at (x,y). - Draw a line. void line(x1,y1,x2,y2,c); Draws a line in color c from (x1,y1) to (x2,y2). This is a 9938 hardware operation and is very fast. - Draw a rectangle. void rect(x1,y1,x2,y2,c); Draws a rectangle in color c with opposing corners at (x1,y1),(x2,y2). - Get pixel color value. int getpix(x,y); (c) 1991 Clint Pulley 12-08-91 Page LIB-22 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB Checks the pixel at (x,y), returns 0 if not set (pixel color=backdrop). Otherwise, returns the color value of the pixel. - Display a character. void bputch(chr,row,col,c); Displays the character chr at (row,col) in color c. - Display a character string. void bputs(row,col,c,str); ( char *str; ) Displays the string str starting at (row,col) in color c. - Blank out a character. void btblnk(row,col); Blanks the character cell at (row,col). - Scroll a block of pixels. These functions scroll a block of pixels in one of four directions within a pixel window on the screen. All function calls are of the form : void bscrlx(np,rul,cul,rlr,clr,c); bscrlx is one of the function names listed below. Arguments are np = number of pixels to scroll rul = row number of upper left corner cul = column number of upper left corner rlr = row number of lower right corner clr = column number of lower right corner c = pixel color for blank pixels The function names are bscrlu - bitmap scroll up bscrld - bitmap scroll down bscrll - bitmap scroll left bscrlr - bitmap scroll right - Move or copy a block of pixels. These functions move or copy a block of pixels using hardware capabilities of the 9938 video processor, so execution is very fast. The row and column numbers for the destination block must be higher than those of the source block. Each function uses a subset of the arguments listed below. The function arguments are (c) 1991 Clint Pulley 12-08-91 Page LIB-23 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB rns = row number of upper left corner of source block cns = column number of upper left corner of source block rnd = row number of upper left corner of destination block cnd = column number of upper left corner of destination block nr = number of rows in the block nc = number of columns in the block c = pixel color for blank pixels lgc = logical operation to be performed on destination pixels 0 = copy source to destination 1 = AND source with destination 2 = OR source with destination 3 = XOR source with destination 4 = copy NOT source to destination 8-12 = as above, but only when source is non-zero The functions (all of type void) are bithbm(rns,cns,rnd,cnd,nr,nc,c); Performs a high-speed move of a pixel block. Vacated pixels are set to color c. bithbc(rns,cns,rnd,cnd,nr,nc); Performs a high-speed copy of a pixel block. Source pixels are unchanged unless the blocks overlap. bitlbm(rns,cns,rnd,cnd,nr,nc,c,lgc); Performs a logical high-speed move of a pixel block. The logical operation is also in effect for setting the color of the vacated pixels. bitlbc(rns,cns,rnd,cnd,nr,nc,lgc); Performs a logical high-speed copy of a pixel block. Source pixels are unchanged unless the blocks overlap. In the logical functions, The requested operation is performed (bitwise) with the values of the source and destination pixels. These values are physical color numbers which are 1 less than the logical color numbers used in TIC. Some experimentation will be required to obtain the desired effect. The XOR operation can be quite useful because two identical XORs will result in the destination block being restored to its original form. 2.6.4 Sprite Functions for all Graphics Modes The 9938 video processor has two sprite modes. Both modes allow a maximum of 32 sprites. Mode 1 allows up to four sprites in a row to be fully visible, and one color per sprite. Mode 2 allows up to 8 sprites in a row to be fully visible and one color for each sprite row (up to 16 colors for a sprite). The true bitmap graphics modes use sprite mode 2. (c) 1991 Clint Pulley 12-08-91 Page LIB-24 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB Other characteristics of sprites are unchanged from the 99/4A. - Create a sprite. void sprite(spn,ch,c,dr,dc); Enables sprite spn (1-32) with sprite pattern ch (0-255) and color c, located at row dr, column dc. In mode 1, c is a color value (1-16). In mode 2, if c is a color value (<=16) sets all sprite row colors to c. Otherwise, c is the name of a 16 element imt array containing sprite row color values. - Delete a sprite. void spdel(spn); Deletes sprite spn. - Delete all sprites. void spdall(); Deletes all defined sprites. - Specify sprite color. void spcolr(spn,c); Sets sprite spn to color c. In mode 1, c is a color value (1-16). In mode 2, if c is a color value (<=16) sets all sprite row colors to c. Otherwise, c is the name of a 16 element imt array containing sprite row color values. - Specify sprite pattern. void sppat(spn,ch); Sets sprite pattern # for sprite spn to ch. - Specify sprite location. void sploct(spn,dr,dc); Locates sprite spn at row dr, column dc. - Specify sprite magnification. void spmag(f); Sets sprite magnification to f (1-4). - Specify sprite motion. void spmotn(spn,rv,cv); (c) 1991 Clint Pulley 12-08-91 Page LIB-25 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB Sets row velocity rv and column velocity cv for sprite spn. Motion starts as soon as non-zero velocities are set. - Get current sprite position. void spposn(spn,&rp,&cp); < & > Returns row position rp and column position cp for sprite spn. - Get sprite separation. int spdist(spn1,spn2); Returns the square of the distance (dsq) between sprites spn1 and spn2. - Get sprite/location separation. int spdrc(spn,r,c); Returns the square of the distance (dsq) between sprite spn and location (r,c). - Test sprite/sprite coincidence. int spcnc(spn1,spn2,tol); Returns true if the distance between sprites spn1 and spn2 is <= tol. - Test sprite/position coincidence. int spcrc(spn,r,c,tol); Returns true if the distance between sprite spn and location (r,c) is <= tol. - Test for coincidence of any sprites. int spcall(); Returns true if any sprites overlap. - Define a sprite pattern. void sppdef(spp,pat); ( int pat[4]; ) Defines sprite pattern spp (0-255) from the pattern data contained in pat. See chrdef for more information. - Retrieve a sprite pattern. void sppget(spp,pat); ( int pat[4]; ) Gets sprite pattern data for pattern spp. The 4 words of binary data (c) 1991 Clint Pulley 12-08-91 Page LIB-26 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB are stored in pat. Note : In MDOS, sprite patterns are not related to character patterns. At program start, no sprite patterns are defined. (c) 1991 Clint Pulley 12-08-91 Page LIB-27 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB 3. Programming Information - CPU Memory Usage MOOS reserves memory locations >0000 - >03FF, >F100 - >F13F and >FFFA - >FFFF for program interface and system functions. TIC reserves >F140 - >FFF8 for working storage, I/O buffers and the stack. As the stack grows up from >F300 while I/O buffers are assigned starting at >FF78 it is essential to confine local storage to a reasonable limit to avoid stack/buffer overlap. Since available stack space will be at least 2,000 bytes, this condition is not difficult to satisfy. When a program is invoked as a program image file, the TICLIB startup code will attempt to assign one page (8k) of fast static RAM starting at >E000 to maximize the speed of stack operations. If the program is invoked directly from LDR this assignment will fail as the page has already been assigned to dynamic RAM. In this case program execution will be slightly slower. When a program image file is loaded by MDOS, only those memory pages actually required for the load are allocated. If the malloc function is used to assign storage, all unassigned pages in the 64k visible memory space are allocated by the first call. This version of TICLIB does not provide functions to access memory outside the visible space. - PAD Usage TICLIB reserves PAD locations >F000 thru >F046 for its workspace and support code. MDOS reserves PAD locations >F080 thru >F0FF for system usage. PAD space from >F048 to >F07F can be used for fast scratchpad memory by use of pointers. - Video Mode Handling When a TIC program begins execution, the screen is in the text mode and colors which were in use by the MDOS command line interpreter. The function tscrn provides a means of changing the text colors. Other video functions may be used to change the video mode. The video mode in use prior to program exit remains in effect on return to MDOS. - Command Line Arguments TICLIB supports standard C command line argument passing. The main function may be defined as main(argc,argv); int argc; char *argv[]; argc contains the argument count (including program name) and argv contains pointers to each argument. As MDOS does not pass the actual program name, argv[0]="*" in TIC. Most C texts discuss command line argument processing in considerable detail. (c) 1991 Clint Pulley 12-08-91 Page LIB-28 TICLIB Object Library for 9640/Geneve TIC, Release 1 TICLIB - Pointer Usage One common cause of catastrophic errors in C programs (which often result in system lockup) is the use of pointers containing spurious values in statements such as *ptr = value; If ptr=0, the program will function correctly until exit but may lock up the system on attempting to return to MDOS. More immediate lockup can occur if the contents of ptr are non-zero but low in value (< 128). Similar problems may occur when calling functions which require value return pointers as parameters (eg. &x) if the address operator (&) is omitted. This problem is often referred to as a "rogue" pointer. (c) 1991 Clint Pulley 12-08-91 Page LIB-29

UTIL_DOC



LDR Linking Loader version 4.0 LDR LDR v4.0 - a Linking Loader for MDOS LDR is a linking loader which reads a command line file list containing the names of object files to be loaded into memory and object libraries to be searched for required object modules which are then loaded. The library search is single pass and sequential. LDR version 4 recognizes REF/DEF names up to 31 characters in length as generated by Al Beard's TASM assembler. Program Operation LDR runs in native (MDOS) mode on the 9640. It is invoked with the command line: LDR file_list [image_file] The filenames must be legal MDOS filenames and must not exceed 40 characters in length. Names in the file list are separated by commas with no imbedded spaces. The first file must be an object file. Loading and library searching are performed in the order in which file names occur in the list. For more information about library searching consult the Object Library documentation. LDR first stores zeroes in all of program memory (>0400 to >EFFF) and then begins loading at address >040C. When loading is complete, LDR stores a conditional linkage to an optional in-line debugger at >0400, a Branch instruction at >0408 and the last defined starting address at >040A. If no starting address was encountered, >040A contains >040C, so execution begins at the first location of the first object file loaded. If a module with the DEF name DEBUG$ was loaded the conditional linkage results in program control being transferred to this location prior to execution of the user program. If no errors occur, LDR generates a virtual external definition, SLAST, which points to the first free address in program memory. A load map listing starting and ending addresses, module names and object library names (if any) are displayed on the screen. When all files have been loaded, LDR checks for undefined REFs. If any are found, they are displayed and LDR exits. Otherwise, action depends on the the image_file parameter. If the image_file parameter is present, the program image is saved as 16k program image files using the provided filename. This option is only valid for relocateable files as LDR uses the program length information contained in the object files to determine the length of the image. SFIRST, SLAST and SLOAD are not used. If the image_filename parameter is absent, LDR branches to address >0400 to begin program execution. All 8 pages of visible memory are assigned. (c) 1991 Clint Pulley 12-07-91 Page LDR-1 LDR Linking Loader version 4.0 LDR For example, if the object files A:OBJ1, A:OBJ2 and the object library C:OBJLIB are to be loaded/searched and the program image is to be saved on files B:PROG1/B:PROG2 etc. the command line is : LDR A:OBJ1,A:OBJ2,C:OBJLIB B:PROG1 c99/MDOS users should note that none of the earlier DV80 library files may be used with this version of LDR. Pressing CTRL-C at any time terminates LDR. The available user memory is >040C to >EFFF. LDR resides in memory locations >F140 to >FFF0 so user programs which attempt to load outside the specified user memory range will probably cause LDR to crash. LDR uses paged memory for the REF/DEF table and requires 98,294 bytes of free memory. Running LDR with insufficient free memory will result in an error message and program termination. Glossary Object file : A display/fixed 80 file generated by the assembler. Object library : A display/variable 128 file generated by the Object Library Utility (OLU) version 3 containing one or more object modules. Object module : Header records followed by the image of a single object file. (c) 1991 Clint Pulley 12-07-91 Page LDR-2 LDR Linking Loader version 4.0 LDR LDR Object Library File Structure Object libraries for the 9640 linking loader (LDR) version 4 are display/variable 128 files whose internal structure is described below. The DV128 format was chosen to reduce the size of library files and to provide a convenient way for LDR to distinguish between version 4 libraries, DV80 version 3 libraries and DF80 object files. Object library structure The first record in a library file is the library identifier, defined as: Bytes 1-2 - 'L:' 3-12 - Library name, left justified, blank filled 13-22 - Date library created 23-32 - Time library created 33-42 - Date last updated 43-52 - Time last updated This record is followed by an unlimited number of object modules. The first record in each object module is the module identifier, defined as: Bytes 1-2 - 'M:' 3-12 - Module name, left justified, blank filled 13-14 - binary count of the number of DEFs in this module 15-24 - Date module inserted in library 25-34 - Time module inserted in library The header is followed by a number of external definition (DEF) specification records. Each record contains up to 4 DEF names, zero byte terminated. Each DEF name may be up to 31 characters in length. Names of less than six characters are padded to six characters with spaces. The total number of DEF names must equal the count in bytes 13-14 of the header. Although there is no formal limit to the number of DEFs, the total length (including zero byte terminators) of all DEF names in a single module must not exceed 1280 characters. The remainder of the module consists of a copy of the object file as produced by the assembler, with trailing blanks stripped from each record and the end-of-file record shortened to a single ':'. Module Order LDR performs a single-pass sequential search of object libraries. As a result, required modules may not be loaded if they are encountered before the modules which reference them. As a general rule, modules should be ordered within a library so that REFs/externs precede DEFs/entries in cases where the REF/DEFs are referenced only from within the library. REFs encountered in previously loaded files will (c) 1991 Clint Pulley 12-07-91 Page LDR-3 LDR Linking Loader version 4.0 LDR always result in the appropriate modules being loaded. Library Maintenance An object library utility (OLU version 3) is provided as a facility for library maintenance. OLU can be used to create, update and list contents of object libraries. An object library conversion utility (LCV) is provided to convert older DV80 object libraries to the DV128 format. (c) 1991 Clint Pulley 12-07-91 Page LDR-4 OLU Object Library Utility version 3.1 OLU OLU v3.1 - an Object Library Utility for MDOS The Object Library Utility (OLU) v3.1 provides maintenance facilities for object libraries which are used with the LDR v4.0 linking loader. Libraries may be created or updated and library contents may be listed on the screen or printer. On-line help is available at any prompt by pressing the ? key followed by the Enter key. Program Operation OLU runs in native (MDOS) mode on the 9640. It is invoked with the command line: OLU [directive_file] If the optional directive_file parameter is present, OLU will read all commands from that file. Otherwise, OLU will prompt for the desired function by displaying the prompt "?". Available functions are : c name1 - create a new object library on file "name1", l name1 [name2] - list the contents of object library "name1". "name2" is the [optional] output file (default is the screen), u name1 name2 - update from object library "name1" to new library "name2", q - quit OLU. Library Creation The create function will prompt for commands by displaying the prompt "c?". Available commands are : i name - insert object file "name" into the new library after any previously inserted files, e - close file "name1" and exit to the function prompt. Library Updating The update function will prompt for commands by displaying the prompt "u?". Available commands are : d name3 - delete object module "name3" from the library. All modules preceding "name3" are copied to the (c) 1991 Clint Pulley 12-07-91 Page OLU-1 OLU Object Library Utility version 3.1 OLU new library, i name3 [name4] - insert object file "name3" into the new library after module "name4", copying all modules up to and including "name4". If "name4" is absent, the object file is inserted at the current position of the new library, m name3 [name4] - merge object library "name3" into the new library after module "name4", copying all modules up to and including "name4". If "name4" is absent, the merge is performed at the current position of the new library, r name3 name4 - replace object module "name3" with object file "name4", copying all modules preceding "name3" to the new library, e - copy any remaining modules to the new library, close both library files and exit to the function prompt. Notes - Users of OLU must be aware of the module order dependency of the loader. LDR performs a single-pass sequential search of object libraries. As a result, required modules may not be loaded if they are encountered before the modules which reference them. As a general rule, modules should be ordered within a library so that REFs/externs precede DEFs/entries in cases where the REF/DEFs are referenced only from within the library. REFs encountered in previously loaded files will always result in the appropriate modules being loaded. - Functions, commands and file/module names may be entered in upper or lower case. File/module names are always transformed to upper case. Parameters enclosed in [brackets] are optional. - If a nonexistent module name is specified, all remaining modules are copied to the new library and an informative message is displayed. - If the new library file exists, OLU queries the user for permission to overwrite the file. - This version of OLU checks the length of the DEF list for each object file and will terminate if the length of the list exceeds 1280 bytes to avoid building object modules which LDR v4.0 cannot handle. Since the average length of a DEF entry is 10 characters or less this results in a limit of at least 128 DEF entries per object file. The only case where this limit is likely to be exceeded is that of a TIC program which has a large number of global variables or functions. Use of the "static" declaration for variables and functions which are not referenced from other modules will eliminate this situation. (c) 1991 Clint Pulley 12-07-91 Page OLU-2 LCV Object Library Conversion Utility version 1.0 LCV LCV v1.0 - an Object Library Conversion Utility for MDOS With the introduction of new versions of the Linking Loader (LDR v4.0) and the Object Library Utility (OLU v3.1) which are able to recognize REF/DEF names up to 31 characters in length the structure of object library files has changed. This library conversion utility is provided to convert old (DV80) object libraries to the new (DV128) format so that it is not necessary to rebuild existing object libraries. Program Operation LCV runs in native (MDOS) mode on the 9640. It is invoked with the command line: OLU old_library new_library LCV checks that old_library is an object library file and terminates if this is not true. The name of each object module is displayed as it is being converted. (c) 1991 Clint Pulley 12-07-91 Page LCV-1

CTYPE_H

/* ctype_h
**
** header for TIC standard character type functions
*/
int    isalnum(),isalpha(),isascii(),iscntrl();
int    isdigit(),isgraph(),islower(),isprint();
int    ispunct(),isspace(),isupper(),isxdigit();
int    tolower(),toupper();

STDIO_H

/* stdio_h
**
** header for TIC standard I/O
*/
/**/
int    getchar(),putchar(),poll();
char   *gets();
void   puts(),exit(),locate(),tscrn();
int    fopen(),fclose(),getc(),putc();
char   *fgets(),*fputs();
int    fread(),fwrite();
void   fseek(),rewind();
int    fdelete(),frename(),fmkdir(),frmdir();
int    fload(),fsave(),bread(),bwrite();
int    fopnec(),ferrc(),feof();
void   fprintf(),sprintf(),printf();
int    fscanf(),sscanf(),scanf();
/**/
#define FILE     int
#define stdin    -1
#define stdout   -2
#define stderr   -3
#define EOF      -1
#define ERR      -2
#define YES       1
#define NO        0
#define NULL      0
#define EOL      10
#define FF       12
#define BS        8
/* end of stdio_h */

STDLIB_H

/* stdlib_h
**
** header for TIC general utilities
*/
char   *malloc(),*free(),*fnfind(),*parsfn();
int    atoi(),rndnum(),rnd(),wmatch(),callcli(),fnfset();
void   freeall(),itoa(),itoneb(),randomize(),sound();

STRING_H

/* string_h
**
** header for TIC standard string functions
*/
int    strlen(),strcmp(),stncmp(),strncmp(),index(),rindex();
char   *strcat(),*stncat(),*strncat(),*strcpy(),*stncpy(),*strncpy();

TIME_H

/* time_h
**
** header for TIC standard clock functions
*/
char *time(),*date();
int dow();


VIDEO_H

/* video_h
**
** header for TIC video/graphics functions
*/
int    vidmode(),getdpg(),gchar(),gcharc(),getpix(),key(),joyst(),mouse();
void   txtmode(),curpos(),inidpg(),setdpg(),palette(),chrdef(),chrpat();
void   scrlwu(),scrlwd(),scrlwl(),scrlwr(),hchar(),vchar(),hcharc(),vcharc();
void   grfmode(),bitclr(),plot(),line(),rect(),bputch(),bputs(),btblnk();
void   bscrlu(),bscrld(),bscrll(),bscrlr(),bithbm(),bithbc(),bitlbm(),bitlbc();
void   setbor(),settxw(),gettxw();
int    spdist(),spdrc(),spcnc(),spcrc(),spcall();
void   sprite(),spdel(),spdall(),spcolr(),sppat(),sploct(),spmag(),spmotn();
void   spposn(),sppdef(),sppget();


FNFTST_C

/* test pgm for fnfind
**
** Usage: fnftst filename
**
** filename may contain ? and * wildcard characters
*/
#include <stdio_h>
#include <stdlib_h>

main(argc,argv) int argc; char **argv;
{ char *fptr; int ft;
  if(argc!=2) exit(7);
  if(!fnfset(argv[1]))
  { printf("fnfset failed for %s\n",argv[1]);
    exit(7);
  }
  while(fptr=fnfind(&ft)) printf("file = %s type = %d\n",fptr,ft);
}