


                                     README
                      for Spontaneous Assembly, Version 3.0
                 (C) Copyright Acclaim Technologies, Inc., 1993


This document contains release notes for Spontaneous Assembly Version 3.0
as well as additions and/or corrections to the accompanying documentation.



General Notes


1.  WARNING! Although the video mode example (see page 18) does locate
    nonstandard video modes on many adapters, some adapters do not
    appropriately validate extended video mode requests. These adapters may
    hang the system if the wrong video mode is selected. In some remote
    cases, extended video mode requests could even damage the monitor.
    BASE TWO DEVELOPMENT ASSUMES NO RESPONSIBILITY FOR YOUR USE OF THIS
    EXAMPLE CODE.


2.  Due to assembler restrictions, when using MASM 5.1 all ASSUME statements
    must be preceded by a percent sign and a space ("% "). For example:

    % assume                cs:@codeseg


3.  Rebuilding any of the libraries requires MASM 6.0+ or TASM 1.0+.


4.  To use TASM's ideal mode, edit the include files and change all of the
    leading dots on macro names to leading underscores. The underscore macro
    naming convention must also be used in your code. For example, .CODESEG
    would be renamed and referenced as _CODESEG in the include file and in
    source code which uses it.


5.  When writing TSRs, most initializations are performed within transient
    code. To reduce resident code size, the windowing, multitasking, and
    virtual screen systems can all be initialized from the transient portion
    of the program.

    Already-initialized windowing, multitasking, and virtual screen systems
    become available to resident functions only after the resident entry point
    calls the appropriate ..._RESUME function. These systems can also be made
    available to EMS-relocatable functions if an EMS-relocatable entry point
    calls the appropriate E_..._RESUME function.

    CONSOLE_INIT should always be called by an entry point that uses the console
    I/O system. See page 21.


6.  If "out of memory" errors are encountered when assembling, the
    SA_EXTRN.INC file may be removed to reduce the memory requirements for
    assembling the file. If SA_EXTRN.INC is not used, all functions that are
    used by the module must be declared with the .EXTRN macro.


7.  MASM 6.0+ and TASM are recommended for writing TSRs. When using these
    assemblers, only the those check/save/restore functions that are
    actually used are linked into the final program.


8.  A "symbol space exceeded" error is possible when TLINK is used to link
    TSRs with a very large number of symbols along with the resident,
    transient, and EMS-relocatable libraries. To resolve this problem, an
    update to TLINK must be obtained from the Borland Support BBS at
    408/439-9096.




Documentation Additions/Corrections


1.  The T_WRAP bit of the t_statbyte field of the TASK structure is no
    longer used by the multitasking system. See pages 60, 64, and 218.


2.  The returns described for ASC_TO_DATE and ASC_TO_TIME on pages 147 and
    148 are incorrect. Instead, the SI register is modified to point to the
    first unconvertible character in instr (similar to the ASC_TO_...
    functions in the data conversion unit). The returns for ASC_TO_DATE
    should read as follows:

    JE if the conversion was successful.
    Date in dword format (date):
    DX      year (1980-2099)
    AH      month (1-12)
    AL      day (1-31)
    SI      address of the first character in instr which could not be converted

    JA if numeric overflow occurred.
    DX;AX   undefined
    SI      address of the first character in instr which could not be converted

    ...

    and for ASC_TO_TIME as follows:

    JE if the conversion was successful.
    Time in dword format (time):
    DH      hours (0-255)
    DL      minutes (0-59)
    AH      seconds (0-59)
    AL      hundredths of seconds (0-99)
    SI      address of the first character in instr which could not be converted

    JA if numeric overflow occurred.
    SI      address of the first character in instr which could not be converted

    ...

            
3.  The description of the "_CHRI" code in the Scripted I/O technical notes
    should refer to the "_CHRI" code instead of the "_LCHR" code. See page
    80.


4.  The __BCD scripted I/O code is incorrectly shown with 3 arguments
    throughout the documentation. The precision parameter is not supported
    for BCD types. The correct arguments are "__BCD, width, nformat". See
    pages 89, 155, 163, 214, 223, 228, 259, 271, and 279.


5.  The description of NSTART?.OBJ should read "DOSSEG ordering is used"
    instead of "TSR segment ordering is used". See page 106.


6.  ON_EXIT functions must perform far returns. See pages 247 and 248.


7.  PACK_CMPLINIT and UNPACK_CMPLINIT are not the same functions, as
    documented. In addition, completion percentages returned by GET_PACKCMPL
    and GET_UNPACKCMPL are measured since the last time the corresponding
    ..._CMPLINIT function was called (NOT since the
    compression/decompression system was initialized, as documented). See
    pages 28, 210, 218, 250, and 313.


8.  For PACK_CMPLINIT and UNPACK_CMPLINIT, the second paragraph under
    "Notes" should be deleted from the reference section. See pages 250 and
    313.


9.  TSR_INITC should not be used for TSRs that will run in an OS/2 DOS
    session. See page 304.


10. The critical error manager installed by TSR_INITC must perform a far
    return. See page 304.


11. The divide by zero function, critical error manager, and fail functions
    cannot be relocated to EMS memory in a TSR. See pages 118-119, 123-124,
    and 304-305.

12. A common problem encountered when writing TSRs is failure to allocate
    enough resident stack space. A symptom of insufficient stack space is
    crashing of the TSR in inconsistent places. Increasing the stack space
    whenever an unexplainable TSR problem is encountered will often solve
    the problem. See page 127.


13. If the virtual screen system is initialized to use disk buffering from
    resident or EMS-relocatable code, the corresponding resident or EMS-
    relocatable version of SET_VSWORKBUF must be called AFTER going
    resident. See page 268.


14. TSR_ENABLE allows programs to be reentered through interrupts before the
    program is resident. If TSR_ENABLE is used, the programmer must take
    steps to prevent the resident and transient portions of the program from
    using the same non-sharable program or system resources. See page 124
    and Appendix E.


15. A stack must always be created in a device driver TSR. See page 133.
    This support is provided in the TSR templates.


16. VIDEO_ON and VIDEO_OFF do not work on EGA adapters. See pages 316-317.


17. SET_VSWORKBUF must be called before VSCREEN_CREATE can be used to create
    a disk buffered screen. VSCREEN_CREATE returns the E_INSMEM error code
    if SET_VSWORKBUF has not been called with an adequate work buffer. See
    pages 140-141 and 318.


18. RESTORE_SCREEN returns JNC if the screen was restored successfully, and
    JNC if the adapter type specified in the saved screen information is
    invalid.


19. Contrary to the documentation, the REFRESH field of the VSCRN structure
    may be set to -1 to inherit the active video refresh state. See page
    141.


20. The reference section description for SET_ADAPTER fails to indicate that
    this function leaves the windowing system in an undefined state. The
    warning paragraph which appears under SET_DIMENS should also appear
    under SET_ADAPTER. See pages 264 and 266.


21. The source code example for locating nonstandard screen dimensions
    (pages 18-19) is incomplete, as follows:

    Currently documented as follows:

    mode_loop:      call    set_vmode       ;change to extended mode
                    call    is_textmode     ;is it a text mode?
                     jne    mode_next       ;  n: don't remember it
                    ...                     ;save mode (AL minus NOCLEAR)
                    push    ax              ;preserve current mode
                    call    get_dimens      ;get text mode screen dimensions
                    ...                     ;save dimensions (AX)
                    pop     ax
    mode_next:      inc     ax


    The example should be changed as follows:

    mode_loop:      call    set_vmode       ;change to extended mode
                    call    is_textmode     ;is it a text mode?
                     jne    mode_next       ;  n: don't remember it
                    push    ax
                    and     al,not NOCLEAR  ;strip NOCLEAR bit from mode
                    cmp     al,video_mode   ;was mode change successful?
                     jne    mode_skip       ;  n: don't use this mode
                    ...                     ;save mode (AL minus NOCLEAR)
                    call    get_dimens      ;get text mode screen dimensions
                    ...                     ;save dimensions (AX)
    mode_skip:      pop     ax
    mode_next:      inc     ax

    This code only works if the active virtual screen is currently open or if
    the virtual screen system is not in use.


22. If SET_VMODE is called to select an extended video mode on a non-open
    virtual screen, the screen dimensions are assumed to be 132x60 until the
    screen is opened and the actual screen dimensions can be determined. For
    this reason, 16K buffers are recommended for all extended video modes
    unless the mode and the actual screen dimensions for that mode are
    indicated in the screen descriptor dimensions before VSCREEN_CREATE is
    called. See pages 138-139.


23. The MONO video mode equate defined in version 2.0 has been renamed to
    MONO80, and a new MONO equate has been defined for use with the
    MONITOR_TYPE variable. References to MONO in the 2.0 manual should be
    changed to MONO80 to avoid confusion. (See the 2.0 reference section
    descriptions for GET_VMODE and SET_VMODE).


24. The virtual screen descriptors are incorrect in the virtual screen
    sample code (see page 143). The PRIMARY descriptor should be defined as
    "<-1,,,,,1,1>" and the SECONDARY descriptor should be defined as
    "<-2,,,,,0,0>" (each with one additional comma).


25. Functions installed with ON_EXIT must perform a far return (retf).

