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

December 1991

###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

  5. 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

  3. SYSGEN Versions

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

  4. TIC Syntax

  5. Library Interfaces

    5.1 C99 Compatibility Mode 5.2 TIC Native Mode

  6. 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);
}