Realtime Interface Co-Processor
DOS Support User's Guide

Version 1.04 (June 1996)


Table of Contents

About This Guide

  • The Users of This Guide
  • How This Guide Is Organized
  • How to Use This Guide
  • Related Publications
  • Reference Publications
  • Chapter 1. General Product Description

  • Overview
  • Hardware Requirements
  • Software Requirements
  • Chapter 2. Installing the Software

  • Installation Requirements
  • Installation Instructions
  • Step 1. Create the Co-Processor Parameter File
  • Step 2. Install the Device Driver
  • Step 3. Install the Interrupt Handler
  • Step 4. Install the Realtime Control Microcode
  • Chapter 3. Parameter File Description

  • ICAPARM.PRM Parameter File Definition
  • Parameter File Example
  • System Configuration With an ICAPARM.PRM File
  • System Configuration Without an ICAPARM.PRM File
  • Chapter 4. Interrupt Handler/Device Driver

  • Installing the Device Driver
  • Installing the Interrupt Handler
  • Chapter 5. Application Loader Utility

  • Starting the Application Loader
  • Chapter 6. Preparing/Installing Application Tasks

  • Preparing Application Tasks
  • Installing Application Tasks
  • Chapter 7. Assembler Language Macro Modules

  • List of Assembler Language Macro Modules
  • Including Assembler Macros in Your Program
  • Linking the Assembler Macros
  • Sample Skeleton
  • General Error Handling
  • Descriptions of Assembler Language Macro Modules
  • DEFCGROUP
  • DEFDGROUP
  • DEFCOMGROUP
  • ICACMD
  • ICAFPARM
  • ICAINBUF
  • ICAINIT
  • ICALOC
  • ICAMACDATA
  • ICAOUTBUF
  • ICAPAG2P
  • ICAPAG2S
  • ICAPHY2P
  • ICAPEERCLOSE
  • ICAPEEROPEN
  • ICAPEERSEND
  • ICAQINT
  • ICAREL
  • ICARET
  • ICARSET
  • ICARSV
  • ICASEG2P
  • ICASTAT
  • ICASTATX
  • ICAVRET
  • ICAVRETM
  • ICAVSET
  • ICAVSETM
  • ICAWINDOW
  • Chapter 8. Function Calls to the Interrupt Handler

  • Internal ICAPARM Parameter Table
  • Interrupt Vector 7Fh Function Calls
  • Set Vector
  • Find Parameters
  • Reserve
  • Release
  • Reset
  • PeerOpen
  • PeerClose
  • PeerSend
  • No Operation
  • Query Version
  • Chapter 9. Online Dump Facility

  • Output Files
  • Loading the Online Dump Facility
  • Dumping a Co-Processor Adapter
  • Changing the Dump Drive
  • Arming a Co-Processor Adapter
  • Restoring a Co-Processor Adapter
  • Resetting a Co-Processor Adapter
  • Chapter 10. Dump Formatter Facility

  • Output Files
  • Dump Formatter Facility Invocation
  • Dump Formatter Facility Profile
  • Profile Parameters
  • Supplied Profile
  • Appendix A. Message List

  • Interrupt Handler Messages
  • Application Loader Utility Messages
  • Online Dump Facility Messages
  • Appendix B. DOS 5.0 Considerations

    Appendix C. The Ignore Feature and OS/2 2.0

    INTERNATIONAL BUSINESS MACHINES PROVIDES THIS PUBLICATION "AS IS," WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in revisions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

    It is possible that this publication may contain references to, or information about, IBM products (machines or programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

    (C) Copyright IBM Corporation 1988, 1990
    All rights reserved.


    About This Guide

    This guide provides technical information on installing and using the Realtime Interface Co-Processor DOS Support Version 1.04 product, which supports the Realtime Interface Co-Processor family of adapters--including:

    Throughout this guide, the term "co-processor adapter" refers to any adapter in the Realtime Interface Co-Processor family of adapters listed above.

    The Users of This Guide

    The information in this guide is intended for software designers, programmers, plant equipment installation personnel, technicians, and anyone who needs to understand the use and operation of the Realtime Interface Co-Processor DOS Support.

    The user should be familiar with the system unit and DOS; therefore, this guide does not explain terminology, except for terms specific to the Realtime Interface Co-Processor family of adapters and the Realtime Control Microcode.


    How This Guide Is Organized

    The Realtime Interface Co-Processor DOS Support User's Guide is organized as follows:


    How to Use This Guide

    This guide provides both user's guide and reference information, and should be used with other technical documents for the co-processor adapter.

    The following conventions are used in this guide:


    Related Publications

    Related books in the Realtime Interface Co-Processor library include:


    Reference Publications

    You may need to use one or more of the following publications for reference with this guide:


    Chapter 1. General Product Description


    Overview

    The Realtime Interface Co-Processor DOS Support product is a package of program services that provides an interface between applications running under DOS and tasks running on the co-processor adapter.

    DOS Support is intended to be used with both IBM and non-IBM products. IBM does not exercise any control over the hardware or the software of non-IBM products. The user is responsible for finding out if the non-IBM products are compatible with Realtime Interface Co-Processor DOS Support. IBM does not assume any responsibility for selection of any non-IBM products, nor does it give out any information on the products, their performance, price, or maintenance.


    Hardware Requirements

    The following are minimum hardware requirements for the Realtime Interface Co-Processor DOS Support Version 1.04 product:


    Software Requirements

    The following are minimum software requirements for the Realtime Interface Co-Processor DOS Support Version 1.04 product:


    Chapter 2. Installing the Software

    This chapter provides a guide for installing the software for the IBM co-processor adapter.


    Installation Requirements

    Before proceeding with the software installation, you need the following:


    Installation Instructions

    The installation procedures include the following:

    During the installation steps, the following apply in explaining commands entered at the DOS level:

    Step 1. Create the Co-Processor Parameter File

    The co-processor parameter file, ICAPARM.PRM, is a user-created ASCII file that the interrupt handler uses to initialize the installed co-processor adapters. The file defines the identification parameters for each co-processor adapter installed in the system unit.

    The parameter file is not required for the following co-processor adapters:

    The parameter file may be used, however, to override the MAXTASK, MAXPRI, MAXQUEUE, and MAXTIME configuration parameters for the adapters. (For more information on the default configuration values, see "System Configuration With an ICAPARM.PRM File" and "System Configuration Without an ICAPARM.PRM File".)

    Instructions

    To create the parameter file, use your text editor or the DOS command: COPY CON. The file can reside in the default directory, in the same directory as the interrupt handler (file ICAINTH.COM), or in the root directory. Include one line (record) of identification parameters for each co-processor adapter installed in the system unit (an example follows). Each record defining a co-processor adapter must:

    The order in which a record is placed in the file determines the logical card number of the co-processor adapter. The first record defines logical co-processor adapter 0; the second record, logical co-processor adapter 1h; and so on.

    Note:

    When there is no ICAPARM.PRM file, the logical co-processor adapter numbers start with 0 for the co-processor adapter in the lowest-numbered slot in the system unit.

    Example

    The following example shows the parameter file for a system unit with two co-processor adapters installed:

    
    
    
    # 02A0 0 6C 10 10 10 10 0F E010 ; First co-processor adapter
    
    # 0AA0 0 6D 10 10 10 10 0F E010 $ Last  co-processor adapter
    
    
    
       |   |  |  |  |  |  |  |   |
    
       |   |  |  |  |  |  |  |   |
    
       |   |  |  |  |  |  |  |   |
    
       |   |  |  |  |  |  |  |   +---- Compare degate 1 and 0
    
       |   |  |  |  |  |  |  +-------- Compare degate 2
    
       |   |  |  |  |  |  +----------- MAXTIME
    
       |   |  |  |  |  +-------------- MAXQUEUE
    
       |   |  |  |  +----------------- MAXPRI
    
       |   |  |  +-------------------- MAXTASK
    
       |   |  +----------------------- Page value
    
       |   +-------------------------- Meg value
    
       +------------------------------ Co-processor adapter
    
                                         I/O address
    
    
    For more information on the parameters, see Chapter 3 "Parameter File Description".

    Step 2. Install the Device Driver

    The DOS device driver, ICAINTH.SYS, is one of the interrupt handler files, and its main function is to disable interrupts from the co-processor adapters until the interrupt handler (ICAINTH.COM) is invoked.

    The device driver is not required for the following co-processor adapters:

    The device driver is required in the following co-processor adapter environments: If all four conditions exist in environment 1, ICAINTH.SYS is required. Environment 2, a PS/2 Model 25 or 30, always requires the device driver.

    Instructions

    To install the DOS Device Driver, do the following:

    1.
    Copy the device driver file, ICAINTH.SYS, to the system unit's boot drive.

    2.
    Create an entry in the system unit's CONFIG.SYS file.

    Add a line of the following format to the CONFIG.SYS file. (Example entries are provided at the end of this step.)

    The ICAINTH.SYS CONFIG.SYS entry has the following syntax:

    
         DEVICE = [d:][\path\]ICAINTH.SYS CO-PROC_NUM(S)...
    
    
    Where:

    CO-PROC_NUM(S)... is a list of between one and 16 physical co-processor adapter numbers separated by spaces. These physical co-processor adapter numbers are exactly one hexadecimal character, and can be in either uppercase or lowercase.

    Examples

    Sample CONFIG.SYS entries follow:

    Example 1:
    ICAINTH.SYS is located in the root directory of the boot drive, and disables interrupts from physical co-processor adapters 0 and Ah with base I/O addresses 02A0h and 2AA0h until ICAINTH.COM is installed.

    DEVICE = ICAINTH.SYS 0 a

    Example 2:
    ICAINTH.SYS is located in a directory called \XYZ on drive C, and disables interrupts from physical co-processor adapter Fh, which has a base I/O address of 3EA0h.

    DEVICE = C:\XYZ\ICAINTH.SYS F

    For additional information on the device driver and the interrupt handler, see Chapter 4, "Interrupt Handler/Device Driver".

    Step 3. Install the Interrupt Handler

    The main functions of the interrupt handler, ICAINTH.COM, are to:

    Instructions

    The Interrupt Handler can be either manually installed each time, or it can be automatically installed as part of the AUTOEXEC.BAT file during system power-up or re-boot.

    Manual Installation

    To manually load the interrupt handler, issue the following command:

    > d:\path\ICAINTH

    Where:

    d:\path\ designates the drive and path where ICAINTH.COM resides.

    Wait for a message to be displayed. If you have more than one co-processor adapter installed or if an error occurs, it could take about 20 seconds for the message to appear. The following message is displayed when the interrupt handler is successfully loaded:

    ICAINT000I ** ICAINTH IS INSTALLED AND RUNNING. **

    If a different message is displayed, see "Appendix A: Message List" for the recommended action.

    Automatic (AUTOEXEC.BAT) Installation

    To automatically load the interrupt handler during power-up or re-boot, use your text editor to enter the same commands you would enter manually (ICAINTH) as a line in the AUTOEXEC.BAT file. For more information on the AUTOEXEC.BAT file, see the IBM Disk Operating System (DOS) manual.

    For further information on the interrupt handler, see Chapter 4 "Interrupt Handler/Device Driver.

    For DOS 5.0 and OS/2 2.0 users, see also "Appendix B: DOS 5.0 Considerations", and "Appendix C: Ignore Feature and OS/2 2.0".

    Step 4. Install the Realtime Control Microcode

    The IBM Realtime Control Microcode is the control program for the co-processor adapter and must be loaded on the co-processor adapter before any user tasks are loaded. The Realtime Control Microcode's file name is either ICAAIM.COM or ICARCM.COM, as described under the instructions that follow. The application loader utility (ICALOAD.COM) is used to load the Realtime Control Microcode onto the co-processor adapter. (For more information on the application loader, see Chapter 5 "Application Loader Utility".)

    Instructions

    For the Realtime Interface Co-Processor, the Realtime Interface Co-Processor Multiport, the Realtime Interface Co-Processor Multiport/2, the X.25 Interface Co-Processor/2, and the ISDN Interface Co-Processor/2, use the following command to load the Realtime Control Microcode onto the co-processor adapter:

    > ICALOAD n1 ICAAIM.COM 0

    For the Realtime Interface Co-Processor Portmaster Adapter/A and the Realtime Interface Co-Processor Multiport Adapter, Model 2, use the following command to load the Realtime Control Microcode to the co-processor adapter:

    > ICALOAD n1 ICARCM.COM 0

    The logical co-processor adapter number (n1) is determined by the order in which the co-processor's identification record appears in the ICAPARM.PRM file, starting with 0 for the first record.

    Note:

    When there is no ICAPARM.PRM file, the logical co-processor adapter numbers start with 0 for the co-processor adapter in the lowest-numbered slot in the system unit.
    The 0 at the end of the command line is the task number; Realtime Control Microcode must always be loaded as task 0. If the Realtime Control Microcode is successfully loaded, the following message is displayed:

    LOD000I ** NORMAL TERMINATION ** CARD/TASK LOADED = n100 **

    If a different message is displayed, see "Appendix A: Message List", for the corrective action.

    Note:

    If you are also installing the IBM Realtime Interface Co-Processor Extended Services product, you can install it at this point. For installation instructions for the Extended Services product, see the Realtime Interface Co-Processor Extended Services User's Guide, or the Realtime Interface Co-Processor Extended Services License Information and Starting Instructions booklet.

    Information on preparing and installing application tasks is in "Chapter 6. Preparing/Installing Application Tasks".


    Chapter 3. Parameter File Description

    This chapter provides a detailed description of the user-created parameter file (ICAPARM.PRM), which tells the interrupt handler how to initialize the installed co-processor adapters.

    The ICAPARM.PRM file is not required for the following co-processor adapters:

    A parameter file may be created, however, to override the MAXTASK, MAXPRI, MAXQUEUE, and MAXTIME configuration parameters for the adapters.

    ICAPARM.PRM Parameter File Definition

    The ICAPARM.PRM file is a user-created ASCII file that defines identification parameters for the co-processor adapters installed in your system unit. The file consists of one record (line) for each co-processor adapter.

    The general rules to consider when defining the ICAPARM.PRM file are that:

    
    +---------+-----------------------+--------+------------------+
    
    |         |                       | Field  |                  |
    
    |  Field  |   Field Name          | Size   |  Value/Range     |
    
    +---------+-----------------------+--------+------------------+
    
    |         |   Beginning record    |   -    |        #         |
    
    |         |   delimiter           |        |                  |
    
    +---------+-----------------------+--------+------------------+
    
    |   1     |   Co-processor adapter|        |                  |
    
    |         |   base I/O address    | Word   |  02A0h - 3EA0h   |
    
    +---------+-----------------------+--------+------------------+
    
    |   2     |   Meg Value           | Byte   |    00h           |
    
    +---------+-----------------------+--------+------------------+
    
    |   3     |   Page Value          | Byte   |    00h - 7Fh     |
    
    +---------+-----------------------+--------+------------------+
    
    |   4     |   MAXTASK             | Byte   |    00h - F8h     |
    
    +---------+-----------------------+--------+------------------+
    
    |   5     |   MAXPRI              | Byte   |    01h - FFh     |
    
    +---------+-----------------------+--------+------------------+
    
    |   6     |   MAXQUEUE            | Byte   |    00h - FEh     |
    
    +---------+-----------------------+--------+------------------+
    
    |   7     |   MAXTIME             | Byte   |    00h - FEh     |
    
    +---------+-----------------------+--------+------------------+
    
    |   8     |   Compare degate 2    | Byte   |    00h - FFh     |
    
    +---------+-----------------------+--------+------------------+
    
    |   9     |   Compare degate 1    | Word   |  0000h - FFFFh   |
    
    |         |   and 0               |        |                  |
    
    +---------+-----------------------+--------+------------------+
    
    |         |   Ending record       | -      |  If last         |
    
    |         |   delimiter           |        |  co-processor    |
    
    |         |                       |        |  adapter,        |
    
    |         |                       |        |  $, else ;       |
    
    +---------+-----------------------+--------+------------------+
    
    

    Parameter File Example

    The following example shows the parameter file for a system unit with two co-processor adapters installed.

    
    # 02A0 00 6C 10 10 10 10 0F E010 ; First co-processor adapter
    
    # 0AA0 00 6D 10 10 10 10 0F E010 $ Last  co-processor adapter
    
    
    
       |   |  |  |  |  |  |  |   |
    
       |   |  |  |  |  |  |  |   |
    
       |   |  |  |  |  |  |  |   |
    
       |   |  |  |  |  |  |  |   +---- Compare degate 1 and 0
    
       |   |  |  |  |  |  |  +-------- Compare degate 2
    
       |   |  |  |  |  |  +----------- MAXTIME
    
       |   |  |  |  |  +-------------- MAXQUEUE
    
       |   |  |  |  +----------------- MAXPRI
    
       |   |  |  +-------------------- MAXTASK
    
       |   |  +----------------------- Page value
    
       |   +-------------------------- Meg value
    
       +------------------------------ Co-processor adapter
    
                                       I/O address
    
    
    In the example above, the meg value of 0 and the page value of 6Ch in the first line indicate that the co-processor adapter's shared window is located at physical address 0D8000h. The meg value of 0 and the page value of 6Dh in the second line indicate that the co-processor adapter's shared storage window is located at physical address 0DA000h. The compare degate values of 0Fh and E010h indicate that the co-processor adapters will reset if physical address 0FE010h is accessed on the system unit. Physical address 0FE010h is an address in ROM accessed during system restart.

    The Programmable Option Select (POS), part of the Personal System/2 architecture, configures part of the Realtime Interface Co-Processor Multiport/2, X.25 Interface Co-Processor/2, Realtime Interface Co-Processor Portmaster Adapter/A, and ISDN Interface Co-Processor/2. POS replaces jumpers and switches used for initializing hardware adapters. The Meg and Page fields are initialized by POS and override the values entered in the parameter file. See the IBM Realtime Interface Co-Processor Multiport/2 Guide to Operations, the IBM Realtime Interface Co-Processor Portmaster Adapter/A Guide to Operations, the IBM Realtime Interface Co-Processor Firmware Technical Reference, the IBM Realtime Interface Co-Processor, Realtime Interface Co-Processor Multiport, Realtime Interface Co-Processor Multiport/2 Technical Reference, the X.25 Interface Co-Processor/2 Technical Reference, and the ISDN Interface Co-Processor/2 Technical Reference for more information on POS.

    Parameter Field Definitions

    This section defines each parameter field of the ICAPARM.PRM file.

    Beginning Record Delimiter
    
    -----------------------------------------------------------
    
        Length        One character # (number sign)
    
    -----------------------------------------------------------
    
        Range         #
    
    -----------------------------------------------------------
    
        Description   The first character of each record must
    
                      be a #.
    
    -----------------------------------------------------------
    
    
    Co-Processor Adapter Base I/O Address
    
    -----------------------------------------------------------
    
        Length         Word           Physical Co-Processor
    
                                          Adapter Number
    
    -----------------------------------------------------------
    
        Value          02A0h         Co-Processor Adapter 0
    
                       06A0h         Co-Processor Adapter 1
    
                       0AA0h         Co-Processor Adapter 2
    
                       0EA0h         Co-Processor Adapter 3
    
                       12A0h         Co-Processor Adapter 4
    
                       16A0h         Co-Processor Adapter 5
    
                       1AA0h         Co-Processor Adapter 6
    
                       1EA0h         Co-Processor Adapter 7
    
                       22A0h         Co-Processor Adapter 8
    
                       26A0h         Co-Processor Adapter 9
    
                       2AA0h         Co-Processor Adapter 10
    
                       2EA0h         Co-Processor Adapter 11
    
                       32A0h         Co-Processor Adapter 12
    
                       36A0h         Co-Processor Adapter 13
    
                       3AA0h         Co-Processor Adapter 14
    
                       3EA0h         Co-Processor Adapter 15
    
    -----------------------------------------------------------
    
        Description   This value is set by the switches on
    
                      the Realtime Interface Co-Processor,
    
                      the Realtime Interface Co-Processor
    
                      Multiport, and the Realtime Interface
    
                      Co-Processor Multiport Adapter, Model 2.
    
                      When using the Realtime Interface
    
                      Co-Processor Multiport/2, the X.25
    
                      Interface Co-Processor/2, the Realtime
    
                      Interface Co-Processor Portmaster
    
                      Adapter/A, and the ISDN Interface
    
                      Co-Processor/2 this value is selected
    
                      with the reference diskette for your
    
                      system unit. For more information on
    
                      address switches, see your co-processor
    
                      adapter's Guide to Operations manual.
    
                      Starting at this value, eight
    
                      input/output addresses are used.
    
    
    Megabyte Value
    
    -----------------------------------------------------------
    
        Length        Byte
    
    -----------------------------------------------------------
    
        Range         00h
    
    -----------------------------------------------------------
    
        Description   The megabyte value indicates which
    
                      megabyte of system unit storage is
    
                      used for the co-processor adapter's
    
                      window.  A megabyte value of 0 indicates
    
                      that the window is located in the
    
                      first megabyte of system unit storage.
    
                      This field must be 00h when using the
    
                      Realtime Interface Co-Processor DOS
    
                      Support.
    
    
    
                      When using the Realtime Interface
    
                      Co-Processor Multiport/2, the X.25
    
                      Interface Co-Processor/2, the
    
                      Realtime Interface Co-Processor
    
                      Portmaster Adapter/A, and the
    
                      ISDN Interface Co-Processor/2, this
    
                      value is selected with the reference
    
                      diskette for your system unit.
    
    
    Page Value
    
    -----------------------------------------------------------
    
        Length        Byte
    
    -----------------------------------------------------------
    
        Range         00h-7Fh
    
    -----------------------------------------------------------
    
        Description   The page value is an offset (in
    
                      increments of 8KB) within the megabyte
    
                      specified by the megabyte value.  This
    
                      value indicates the location of the
    
                      co-processor adapter's shared storage
    
                      window within the specified megabyte.  A
    
                      page value of 0 indicates the window
    
                      is located at the beginning of the
    
                      megabyte specified by the megabyte value.
    
                      When assigning the location of the co-
    
                      processor, the adapter's shared storage
    
                      window should not overlap the window of
    
                      another co-processor adapter.  In
    
                      addition, regions are 128KB wide and are
    
                      defined by the type of memory devices
    
                      that reside in those regions.  If a
    
                      co-processor adapter is configured as an
    
                      8-bit device, it cannot reside in the
    
                      same 128KB region as a 16-bit device.
    
                      Conversely, if a co-processor adapter is
    
                      configured as a 16-bit device, it cannot
    
                      reside in the same 128KB region as an
    
                      8-bit device.
    
    
    
                      When using the Realtime Interface
    
                      Co-Processor Multiport/2, the X.25
    
                      Interface Co-Processor/2, the Realtime
    
                      Interface Co-Processor Portmaster
    
                      Adapter/A, and the ISDN Interface
    
                      Co-Processor/2, this value is selected
    
                      with the reference diskette for your
    
                      system unit.
    
    
    MAXTASK
    
    -----------------------------------------------------------
    
        Length        Byte
    
    -----------------------------------------------------------
    
        Range         00h-F8h
    
    -----------------------------------------------------------
    
        Description   This is the highest task number that can
    
                      be loaded on a given co-processor adapter.
    
                      Task 0 is used by the Realtime Control
    
                      Microcode.  This value should be selected
    
                      carefully to avoid reserving unnecessary
    
                      space in the Realtime Control Microcode's
    
                      data area.
    
    
    MAXPRI
    
    -----------------------------------------------------------
    
        Length        Byte
    
    -----------------------------------------------------------
    
        Range         01h-FFh
    
    -----------------------------------------------------------
    
        Description   This is the highest priority level that
    
                      may be assigned to a task loaded on this
    
                      co-processor adapter.  This value should
    
                      be selected carefully to avoid reserving
    
                      unnecessary space in the Realtime Control
    
                      Microcode's data area.
    
    
    MAXQUEUE
    
    -----------------------------------------------------------
    
        Length        Byte
    
    -----------------------------------------------------------
    
        Range         00h-FEh
    
    -----------------------------------------------------------
    
        Description   This is the highest queue number
    
                      available for application tasks
    
                      executing on the co-processor adapter.
    
                      This value should be selected carefully
    
                      to avoid reserving unnecessary space in
    
                      the Realtime Control Microcode's data
    
                      area.
    
    
    MAXTIME
    
    -----------------------------------------------------------
    
        Length        Byte
    
    -----------------------------------------------------------
    
        Range         00h - FEh
    
    -----------------------------------------------------------
    
        Description   This is the highest timer number reserved
    
                      for application tasks executing on the
    
                      given co-processor adapter. This value
    
                      should be selected carefully to avoid
    
                      reserving unnecessary space in the
    
                      Realtime Control Microcode's data area.
    
    
    Compare Degate 2
    
    -----------------------------------------------------------
    
        Length        Byte
    
    -----------------------------------------------------------
    
        Range         00h-FFh
    
    -----------------------------------------------------------
    
        Description   When this address, in conjunction with
    
                      Compare Degate 1 and 0, is accessed by
    
                      the system unit, the co-processor
    
                      adapter's shared storage window
    
                      automatically degates from the system
    
                      unit memory bus.
    
                      If the system unit architecture
    
                      only supports 1 megabyte of memory,
    
                      this parameter is limited to 00h - 0Fh.
    
                      00h - FFh is valid only in a system
    
                      designed for 16 megabytes of memory.
    
                      This field should have a value of 0
    
                      to disable the feature.
    
                      The Compare Degate fields are undefined
    
                      on the Realtime Interface Co-Processor
    
                      Multiport/2 , the X.25 Interface Co-
    
                      Processor/2, the Realtime Interface
    
                      Co-Processor Portmaster Adapter/A,
    
                      and the ISDN Interface Co-Processor/2
    
                      adapters. Shared storage automatically
    
                      degates from the system unit bus when
    
                      the system is re-booted without turning
    
                      off the system (soft reset).
    
    
    
                      For a list of the recommended addresses,
    
                      see "Recommended Compare Degate
    
                      Addresses," later in this section.
    
    
    Compare Degate 1 and 0
    
    -----------------------------------------------------------
    
        Length        Word
    
    -----------------------------------------------------------
    
        Range         0000h-FFFFh
    
    -----------------------------------------------------------
    
        Description   When this address, in conjunction with
    
                      Compare Degate 2, is accessed by the
    
                      system unit, the co-processor adapter
    
                      automatically degates its shared
    
                      storage window from the system unit
    
                      bus (see "Compare Degate 2").  To
    
                      disable this feature, the field has
    
                      a value of 0.
    
    
    
                      For a list of the recommended addresses,
    
                      see the following chart.
    
    

    Recommended Compare Degate Addresses

    Following are the recommended Compare Degate addresses for the ICAPARM.PRM file definition:

    
    -----------------------------------------------------------
    
     System unit               Compare Degate    Compare Degate
    
                                     2              1 and 0
    
    -----------------------------------------------------------
    
     IBM 5531, 7531, or 7532         0F              E010
    
     Industrial Computer;
    
     PC XT; PC AT; PS/2
    
     Model 25 or 30;
    
     IBM 5531, 7531 and
    
     7532 Industrial
    
     Computer
    
    -----------------------------------------------------------
    
     IBM 7552 Industrial             0C              0000
    
     Computer
    
    -----------------------------------------------------------
    
     IBM 7541, 7542, 7561            Any             Any
    
     7562 and 7568                   value           value
    
     Industrial
    
     Computer;
    
     PS/2 Model 50, 50Z
    
     55, 60, 70, or 80
    
    
    Ending Record Delimiter
    
    -----------------------------------------------------------
    
        Length        1 character
    
    -----------------------------------------------------------
    
        Range         ; or $
    
    -----------------------------------------------------------
    
        Description   The last character in the definition
    
                      record for a co-processor adapter should
    
                      be a ; (semicolon). If this is the last
    
                      record in the file, the last character
    
                      should be a $ (dollar sign). If a system
    
                      does not have the $ character, the ASCII
    
                      equivalent of $ (24h) should be used.
    
    

    System Configuration With an ICAPARM.PRM File

    If a parameter file is defined, the interrupt handler first processes the co-processor adapters listed in that file. The first entry in the parameter file defines logical co-processor adapter 0; the second entry, logical co-processor adapter 1; and so on. After the parameter file entries are processed, the interrupt handler scans the system unit slots for additional Realtime Interface Co-Processor Multiport/2, Realtime Interface Co-Processor Portmaster Adapter/A, X.25 Interface Co-Processor/2, and ISDN Interface Co-Processor/2 adapters. (These adapters do not require an ICAPARM.PRM file.) If additional adapters from this group are installed, they are configured to the default values that follow, and are assigned logical card numbers following the numbers of the adapters defined in the parameter file. Numbering continues with the co-processor adapter in the lowest-numbered slot in the system unit and proceeds in ascending order.

    For example, if the configuration file contains the following:

    
    #   0AA0   00   6C   10   10   10   10   0F   E010;
    
    #   06A0   00   6D   10   10   10   10   0F   E010$
    
    
    and the slots are configured as follows:
    
                        Co-Processor at
    
        Slot              base address
    
    -----------------------------------------------------------
    
          1                   02A0
    
          2                   0AA0
    
          3                   06A0
    
          4                   0EA0
    
    
    
    
    
    The logical card number assignments are:
    
    
    
    
    
        Logical Card
    
           Number         Base Address
    
    -----------------------------------------------------------
    
             0                0AA0
    
             1                06A0
    
             2                02A0
    
             3                0EA0
    
    

    System Configuration Without an ICAPARM.PRM File

    If no parameter file is used, the interrupt handler initializes the Realtime Interface Co-Processor Multiport/2, the Realtime Interface Co-Processor Portmaster Adapter/A, the X.25 Interface Co-Processor/2 and the ISDN Interface Co-Processor/2 adapters to the following default values:

    I/O Base Address:
    This value is read from the card's POS registers. They should be set with the system unit Reference Diskette.

    Window Location (Meg and Page):
    These values are read from the card's POS registers. They should be set with the system unit Reference Diskette.

    MAXTASK:
    Set to default value of 0x10 (decimal 16);
    set to default value of 0x20 (decimal 32) for the ISDN Interface Co-Processor/2.

    MAXPRI:
    Set to default value of 0x10 (decimal 16);
    set to default value of 0x0A (decimal 10) for the ISDN Interface Co-Processor/2.

    MAXQUEUE:
    Set to default value of 0x50 (decimal 80);
    set to default value of 0x20 (decimal 32) for the ISDN Interface Co-Processor/2.

    MAXTIME:
    Set to default value of 0x32 (decimal 50);
    set to default value of 0x33 (decimal 51) for the ISDN Interface Co-Processor/2.

    Compare Degate Addresses:
    Undefined. Adapter storage automatically degates after a soft reset of the host on the Realtime Interface Co-Processor Multiport/2, X.25 Interface Co-Processor/2, Realtime Interface Co-Processor Portmaster Adapter/A, and ISDN Interface Co-Processor/2 adapters.
    If these defaults do not meet the requirements of your system configuration, create an entry in the ICAPARM.PRM file to override the defaults. An ICAPARM.PRM file is required for the Realtime Interface Co-Processor, the Realtime Interface Co-Processor Multiport, and the Realtime Interface Co-Processor Multiport Adapter, Model 2.

    Chapter 4. Interrupt Handler/Device Driver

    The interrupt handler consists of three files:

    The main functions of the interrupt handler, ICAINTH.COM, are to: The main function of ICAINTH.SYS is to disable interrupts from the co-processor adapters until ICAINTH.COM is invoked. The main function of ICAINTH.MSG is to provide the messages used by ICAINTH.COM.

    Device Driver Environments

    The device driver is required in the following co-processor adapter environments:

    If all four conditions exist in environment 1, ICAINTH.SYS is required. Environment 2, a PS/2 Model 25 or 30, always requires the device driver.

    The device driver is required in the preceding environments to disable interrupts from all co-processor adapters until the interrupt handler, ICAINTH.COM, is invoked. This ensures that unexpected co-processor adapter interrupts do not dominate the shared interrupt level(s). When ICAINTH.COM is installed, co-processor adapter interrupts are enabled and any pending interrupts are handled.

    The device driver is not required for the following co-processor adapters:


    Installing the Device Driver

    To install the DOS Device Driver:

    1.
    Copy the device driver file, ICAINTH.SYS, to the system unit's boot drive.

    2.
    Create an entry in the system unit's CONFIG.SYS file.

    Add a line of the following format to the CONFIG.SYS file. (Example entries are provided at the end of this step.)

    The ICAINTH.SYS CONFIG.SYS entry has the following syntax:

    
         DEVICE = [d:][\path\]ICAINTH.SYS CO-PROC_NUM(S)...
    
    
    Where CO-PROC_NUM(S)... is a list of between one and 16 physical co-processor adapter numbers separated by spaces. These physical co-processor adapter numbers are exactly one hexadecimal character, and can be in either uppercase or lowercase.

    The co-processor physical adapter numbers and base I/O addresses have the following relationship:

    
    -----------------------------------------------------------
    
    Physical Co-Processor        Base I/O
    
    Adapter Number               Address
    
    -----------------------------------------------------------
    
          0h                      02A0h
    
          1h                      06A0h
    
          2h                      0AA0h
    
          3h                      0EA0h
    
          4h                      12A0h
    
          5h                      16A0h
    
          6h                      1AA0h
    
          7h                      1EA0h
    
          8h                      22A0h
    
          9h                      26A0h
    
          Ah                      2AA0h
    
          Bh                      2EA0h
    
          Ch                      32A0h
    
          Dh                      36A0h
    
          Eh                      3AA0h
    
          Fh                      3EA0h
    
    

    Examples

    Sample CONFIG.SYS entries follow:

    Example 1:
    ICAINTH.SYS is located in the root directory of the boot drive, and disables interrupts from physical co-processor adapters 0h and Ah with base I/O addresses 02A0h and 2AA0h until ICAINTH.COM is installed.

    DEVICE = ICAINTH.SYS 0 a

    Example 2:
    ICAINTH.SYS is located in a directory called \XYZ on drive C, and disables interrupts from physical co-processor adapter Fh, which has a base I/O address of 3EA0h.

    DEVICE = C:\XYZ\ICAINTH.SYS F


    Installing the Interrupt Handler

    The Interrupt Handler can be either manually installed each time, or it can be automatically installed as part of the AUTOEXEC.BAT file during system power-up or re-boot.

    Manual Installation

    To manually load the interrupt handler, issue the following command:

    > d:\path\ICAINTH

    Where d:\path\ designates the drive and path where ICAINTH.COM resides.

    Wait for a message to be displayed. If you have more than one co-processor adapter installed or if an error occurs, it could take about 20 seconds for the message to appear. The following message is displayed when the interrupt handler is successfully loaded:

    ICAINT000I ** ICAINTH IS INSTALLED AND RUNNING. **

    If a different message is displayed, see Appendix A, "Message List," in this manual, for the recommended action.

    Automatic (AUTOEXEC.BAT) Installation

    To automatically load the interrupt handler during power-up or re-boot, use your text editor to enter the same commands you would enter manually (ICAINTH) as a line in the AUTOEXEC.BAT file. For more information on the AUTOEXEC.BAT file, see the IBM Disk Operating System (DOS) manual.

    DOS 5.0 and OS/2 2.0 Considerations

    For DOS 5.0 and OS/2 2.0 considerations, see Appendixes B and C.


    Chapter 5. Application Loader Utility

    The application loader utility (ICALOAD.COM) is used to load the Realtime Control Microcode or tasks to the co-processor adapter. The loader utility can be invoked from the keyboard or a .BAT file, or it may be called from another program using DOS facilities.

    The file names for the application loader are:

    When using ICALOAD.COM, the ICALOAD.MSG file must be located in either the current directory, the root directory, or the directory where ICALOAD.COM is located.

    Note:

    The Interrupt Handler (ICAINTH.COM) must be loaded before the application loader is invoked.
    The first task loaded onto a co-processor adapter must be the Realtime Control Microcode (file ICAAIM.COM or ICARCM.COM), provided with the co-processor adapter. After the Realtime Control Microcode is loaded, the user may load application tasks onto the co-processor adapter. Each task must have a unique task number that is assigned when the task is loaded. The MAXTASK field in the parameter file (ICAPARM.PRM) defines the highest task number under which a task can be loaded.

    The following example loads the Realtime Control Microcode onto co-processor adapter 0:

    > ICALOAD 0 ICAxxx.COM 0

    Where xxx = AIM for the Realtime Interface Co-Processor, the Realtime Interface Co-Processor Multiport, the Realtime Interface Co-Processor Multiport/2, or the X.25 Interface Co-Processor/2; xxx = RCM for the Realtime Interface Co-Processor Portmaster Adapter/A or the Realtime Interface Co-Processor Multiport Adapter, Model 2. The first 0 (hexadecimal) represents the first logical co-processor adapter number as defined in the ICAPARM.PRM file. The last 0 (hexadecimal) represents the task number, which is always 0 for Realtime Control Microcode.

    Realtime Control Microcode Version 1.x does not support the passing of parameters.

    Realtime Control Microcode Version 2.x supports the following parameters:

    Note:
    Parameters 1 and 2 may be used at the same time by separating the parameters with a blank. For example: These parameters may be passed together and in any order; that is, they are not mutually exclusive and not order dependent.
    The loader can load .EXE or .COM files only. The maximum length of a COM file is 64K bytes, while the length of an EXE file is restricted by the amount of free storage on the co-processor adapter at the time the load is attempted.

    The loader sets up the initial values for the Code Segment Register, Data Segment Register, Stack Segment Register, and Stack Pointer Register in the task header.


    Starting the Application Loader

    The application loader requires command line parameters, as shown below, to indicate which task to load and how it should be loaded. The first three parameters are required, while the remaining parameters are shown within brackets to indicate that they are optional. The brackets cannot be used in the actual invocation line.

    The parameters must appear in the order in which they are listed in the following paragraphs. Each parameter must be separated by either a space or a comma. If a parameter is to be skipped but a later parameter is to be used, a comma must be used in place of the skipped parameter. (Examples follow the parameter descriptions.) The loader parameters are:

    ICALOAD CO-PROC_NUM,TASK_FILE,TASK_NUM[,START][,LOW/HIGH]
    [,BOUND][,MSG][(PARMS]

    Where

    ICALOAD
    The name of the loader program.
    CO-PROC_NUM
    The logical co-processor adapter number (hexadecimal) where the task is to be loaded. The adapter number is determined by the position of this co-processor adapter's descriptor in the ICAPARM.PRM file. This parameter is required.
    TASK_FILE
    The file name, including the extension, of the task to be loaded. A drive and path may be specified if the task is not in the current directory. This parameter is required.
    TASK_NUM
    The task number (hexadecimal) to be assigned to the task to be loaded. Realtime Control Microcode must be loaded as task 0. Application tasks may be loaded in the hexadecimal range of 1 to the MAXTASK value, as assigned in the ICAPARM.PRM file. This parameter is required.
    START
    The start flag. The letter S indicates that the task should be started after it is loaded. The letter L indicates that the task should only be loaded. If this parameter is not used, the task is started by default.
    LOW/HIGH
    The flag for loading in high or low co-processor adapter memory. Specify the string HIGH to load the task at the highest possible address and LOW to load the task at the lowest possible address. The default load location in co-processor adapter storage is the highest possible address.

    Note:

    RCM V1.3 or greater must be installed to use this option.
    BOUND
    The memory boundary in paragraphs that the task should be loaded on. The default task load boundary is one paragraph (16 bytes). If a boundary other than one paragraph is required, the required boundary can be entered in this parameter. The boundary must be an exact power of two (only one bit on in the entire word). This optional parameter should be entered in hexadecimal format (without the trailing "h").
    MSG
    The message flag. If this parameter is not specified, messages are displayed by default. The letter N indicates that application loader messages should be suppressed.

    If messages are suppressed, the loader returns a return code upon completion. This return code is the same as the loader message number. Therefore, if messages are suppressed and a non-zero return code is received from the loader, the meaning of the return code can be found by looking at the loader message with the same message number. The messages are described in Appendix A of this manual.

    PARMS
    Parameters passed to the task. All the characters beyond the "(" on the command line are passed to the task along with the task name. If parameters are specified, the task name, a single space, and all the characters following the "(" are copied to the task parameter area. The task name is converted to upper case. The parameters are copied to offset 001Ch in the task's header segment. The maximum length of the parameter area is 128 bytes. The parameters are passed as a NULL terminated string.

    Examples

    Following are application loader examples:

    In the first example, the task USERTASK.EXE is loaded on co-processor adapter 1 as task 2 with messages suppressed and no parameters. All other parameters have the default values.

    >ICALOAD 1 USERTASK.EXE 2,,,,N

    The following example loads the task TASK.EXE as task 1 on co-processor adapter 0.

    >ICALOAD 0 TASK.EXE 1

    The next example loads the task TASK.EXE as task 2 on co-processor adapter 1. The task is passed the parameter string "parameter string".

    >ICALOAD 1 C:\TASK.EXE 2 (parameter string


    Chapter 6. Preparing/Installing Application Tasks

    This chapter provides overview information on preparing and installing application tasks.


    Preparing Application Tasks

    Tasks that run on the co-processor adapters can be written in assembly language or C language. For information on the development of C tasks, see the IBM Realtime Interface Co-Processor C Language Support User's Guide (at least Version 1.02). The rest of this section discusses development of assembler language tasks.

    Application tasks must have either the .COM or .EXE format, and can be developed with IBM Macro Assembler/2.

    See the file READ.ME included with the IBM Realtime Interface Co-Processor DOS Support Programs for information on the files necessary for assembly. Refer to the IBM Macro Assembler/2 manual for details concerning parameters.

    Commands and Parameters

    To prepare your tasks, you need to assemble, link, and (if using .COM format) convert your assembly language programs before you install them on the co-processor adapter. The required commands and parameters are listed here, followed by examples.

    Assemble command--use the following command to assemble your program:

    
          MASM source, object, list, cross-ref[/parm]...;
    
    
    Reference: IBM Macro Assembler/2.
    Error Reference: IBM Macro Assembler/2.

    Link command--use the following command to link your program:

    
    LINK objlist, runfile, mapfile, liblist[parm]...;
    
    
    Reference: IBM Disk Operating System (DOS) manual,"The Linker (Link) Program."

    Error Reference: IBM Disk Operating System (DOS) manual, Appendix A, "Messages".

    Conversion command--if your source is written in .COM format, use the following command to convert the .EXE file to a .COM file:

    
    

    EXE2BIN [d:][path][filename] [d:][path][filename]

    Reference: IBM Disk Operating System (DOS) Technical Reference manual, EXE2BIN Command.

    Error Reference: IBM Disk Operating System (DOS) Technical Reference manual.

    Example

    The following example takes the task source file mytask.asm and creates an executable task file mytask.com:

    
    >MASM mytask;
    
    >LINK mytask,,, mylib
    
    
    If this warning message is displayed: "Warning: No stack segment.," and your source code is written in .COM format, convert the .EXE file to a .COM file by entering:

    >EXE2BIN mytask mytask.COM

    Reference: IBM Disk Operating System (DOS) Technical Reference manual, EXE2BIN Command.

    Error Reference: IBM Disk Operating System (DOS) Technical Reference manual.


    Installing Application Tasks

    After the interrupt handler and Realtime Control Microcode are installed and your application tasks are constructed, you can use the application loader utility (ICALOAD.COM) to install your application tasks on the co-processor adapter. Each task must be assigned a unique task number. The MAXTASK field in the parameter file, ICAPARM.PRM, defines the highest task number that can be assigned to a task to be loaded.

    To install a task, issue the following command:

    > ICALOAD n1 taskname.ext n2

    Where n1 is the logical co-processor adapter number (hexadecimal), taskname.ext is the name (including extension) of the application task, and n2 is the task number (hexadecimal) assigned to the task to be loaded.

    If the task is successfully loaded, the following message is displayed:

    > LOD000I ** NORMAL TERMINATION.** CARD/TASK LOADED = n1n2

    If a different message is displayed, see Appendix A, "Message List," for the recommended action.

    Once your application tasks are successfully loaded on the co-processor adapter, the tasks are ready to communicate with system unit applications.


    Chapter 7. Assembler Language Macro Modules

    Assembler language macro modules are provided to simplify communications between the co-processor adapter and system unit applications written in Macro Assembler/2. These macros provide a higher level of interface than communicating directly to the tasks on the co-processor adapter or communicating through the interrupt handler.


    List of Assembler Language Macro Modules

    Following is a list and brief description of each assembler macro. A detailed description of each module is provided later in the chapter.

    
    -----------------------------------------------------------
    
      Name          Function
    
    -----------------------------------------------------------
    
      DEFCGROUP     Macro to group user code segments for an
    
                    .EXE file with those of ICAMAC.MAC and
    
                    ICAEMAC.LIB.
    
    
    
      DEFDGROUP     Macro to group user data segments for an
    
                    .EXE file with those of ICAEMAC.MAC and
    
                    ICAEMAC.LIB.
    
    
    
      DEFCOMGROUP   Macro to group user segments for a .COM
    
                    file with those of ICAMAC.MAC and
    
                    ICACMAC.LIB.
    
    
    
      ICACMD        Macro to issue a command to a task on a
    
                    particular co-processor adapter.
    
    
    
      ICAFPARM      Macro to return a pointer to a particular
    
                    co-processor adapter's ICAPARM parameter
    
                    table entry.
    
    
    
      ICAINBUF      Macro to return a pointer to the Input
    
                    Buffer for the task number on a particular
    
                    co-processor adapter.
    
    
    
      ICAINIT       Macro to initialize the other macros for
    
                    DOS.  This Macro verifies compatibility
    
                    with the interrupt handler.
    
    
    
      ICALOC        Macro to return the segment value of the
    
                    co-processor adapter's window in system
    
                    unit storage.
    
    
    
      ICAMACDATA    Macro to set up the data area to be used
    
                    by the other macros.
    
    
    
      ICAOUTBUF     Macro to return the pointer to the Output
    
                    Buffer for the requested task number on a
    
                    specified co-processor adapter.
    
    
    
      ICAQINT       Macro to query the interrupt flag of a
    
                    particular task on a particular
    
                    co-processor adapter.
    
    
    
      ICASEG2P      Macro to convert a co-processor address
    
                    in segment:offset format to
    
                    page:offset format.
    
    
    
      ICAPAG2S      Macro to convert a co-processor address
    
                    in page:offset format to segment:offset
    
                    format.
    
    
    
      ICAPAG2P      Macro to convert a co-processor
    
                    page:offset address to a 32-bit
    
                    physical address.
    
    
    
      ICAPHY2P      Macro to convert a co-processor
    
                    32-bit physical address to a
    
                    page:offset address.
    
    
    
      ICAPEEROPEN   Macro to establish an application as a
    
                    peer task within the system unit
    
                    processor.  A peer handle is acquired
    
                    to identify the task.
    
    
    
      ICAPEERCLOSE  Macro to release the peer handle and
    
                    prevent further reception of peer request
    
                    blocks.
    
    
    
      ICAPEERSEND   Macro to send a peer request block to
    
                    another peer task.
    
    
    
      ICAREL        Macro to release the CPU Page Selector for
    
                    a particular co-processor adapter.
    
    
    
      ICARET        Macro to return from an interrupt routine
    
                    that was entered via a jump vector
    
                    previously set by ICAVSETM macro.
    
    
    
      ICARSET       Macro to issue a hardware reset command to
    
                    the co-processor adapter.
    
    
    
      ICARSV        Macro to reserve the CPU Page Selector.
    
    
    
      ICASTAT       Macro to return the primary status byte
    
                    code for a given task number.
    
    
    
      ICASTATX      Macro to return the location of the
    
                    secondary status field for a given task.
    
    
    
      ICAVRET       Macro to return a specified number of
    
                    interrupt flags to the interrupt handler.
    
    
    
      ICAVRETM      Macro to return a vector acquired using
    
                    the ICAVSETM macro.
    
    
    
      ICAVSET       Macro to request the setup of interrupt
    
                    flags that can be queried using ICAQINT.
    
    
    
      ICAVSETM      Macro to set an interrupt jump vector for
    
                    a particular task on a particular
    
                    co-processor adapter.
    
    
    
      ICAWINDOW     Macro to alter the CPU Page Selector.
    
    

    Including Assembler Macros in Your Program

    The co-processor adapter assembly interface is a macro library named ICAMAC.MAC and two object file libraries named ICAEMAC.LIB and ICACMAC.LIB. The ICAEMAC library is used for .EXE files and ICACMAC is used for .COM files. System unit application source code is written with the macros imbedded. The user can either imbed the actual ICAMAC.MAC file in the application source or INCLUDE the file using the Macro Assembler Pseudo-Op, "INCLUDE." An assembler macro module is invoked with the assembler command to execute a macro. The format for invocation is:

    module_name <parm1, ..., parmn>

    Refer to the IBM Macro Assembler/2, Assemble, Link and Run for a complete explanation of the usage and control of macros.

    Parameters are passed via registers and on the command invocation line.

    Note:

    A general convention used among some of the macros requires the applications program ID of the calling program to be an entry parameter. See the macro descriptions for more information.
    When Macro Assembler/2 and Link/2 are used to compile/link existing "exe" programs, it may be necessary to use the /A option at compile time and the /NOG option at link time to remain compatible with previous Macro Assembler versions. Refer to the IBM Macro Assembler/2, Assemble, Link and Run manual for more information.

    Linking the Assembler Macros

    Following an error-free assembly, the application program's object code must be linked with one of the link libraries. This gives the imbedded macros access to previously-assembled routines that are called frequently by the macros. The determination of which object library to use is based on whether or not the application program is to have separate code and data segments (as in some .EXE files) or to have the code and data segments combined (as in all .COM files). The following rules apply:

    These library routines can increase efficiency with respect to size and maintenance, and provide better readability of source listings.

    To access these library routines, your application programs must issue certain macros to define and control the grouping and placement of the user segments. These required macros are:

    The user must assume macro-defined values initially for specified segment registers. This is done using the Macro Assembler Pseudo-Op, "ASSUME".

    In an .EXE file, CGROUP must be assumed for the code segment and DGROUP must be assumed for the data segment. In an .EXE file with common code and data segments, COMGROUP must be assumed for both the code and data segments. In a .COM file, COMGROUP must be assumed for both the code and data segments. The following is an acceptable EXE ASSUME statement:

    
      ASSUME CS:CGROUP,DS:DGROUP,SS:USER_STACK_SEG,ES:NOTHING
    
    
    The following is an acceptable COM ASSUME statement:
    
      ASSUME CS:COMGROUP,DS:COMGROUP
    
    
    Note that user values can be assumed for the stack and extra segments, because restrictions are only placed on the data and code segments. The value assumed for the data and code segments must also be current at the time that any macro is issued. In other words, the user may change any segment register during program execution, but the values of CGROUP and DGROUP must be current in the CS and DS registers prior to any macro invocation.

    Sample Skeleton

    Sample skeletons are provided in the files EXESKEL.ASM and COMSKEL.ASM with the IBM Realtime Interface Co-Processor DOS Support Programs. The skeletons are sample source code models for .EXE and .COM files.


    General Error Handling

    The carry flag is set to one (1) if an error condition is detected. The error status code is returned to the calling program in the AL register.

    
    -----------------------------------------------------------
    
      AL Code   Meaning            Cause
    
    -----------------------------------------------------------
    
    
    
        01h     Invalid            Valid co-processor adapter
    
                co-processor       numbers are those defined
    
                number             in the ICAPARM.PRM file,
    
                                   described in Chapter 3.
    
    
    
        02h     Invalid task       Valid task numbers are those
    
                number             that are less than or equal
    
                                   to the value defined for
    
                                   MAXTASK, described in
    
                                   Chapter 3.
    
    
    
        04h     Co-processor       The logical co-processor
    
                adapter inactive   adapter number is defined
    
                but ICAPARM        in the ICAPARM.PRM file,
    
                parameters exist   but the co-processor
    
                                   adapter is not functional.
    
                                   For example, the base I/O
    
                                   address switch setting may
    
                                   be valid in the table, but
    
                                   no co-processor adapter
    
                                   is installed.
    
    
    
        05h     Page Selector      The specified Page Selector
    
                already reserved   is already reserved by
    
                                   another program.
    
    
    
        06h     Invalid output     The output buffer is smaller
    
                buffer size        than the value defined in
    
                                   the byte count entry
    
                                   parameter.
    
    
    
        07h     Invalid PC         The PC Select Byte value in
    
                Select Byte        the interface block was not
    
                value              FFh or FEh prior to issuing
    
                                   this command. The problem
    
                                   must be isolated before
    
                                   further processing can
    
                                   occur.
    
    
    
        08h     Invalid Primary    The task's Primary Status
    
                Status Byte        Byte value in the Interface
    
                value              Block is usually set to an
    
                                   invalid state by the
    
                                   Realtime Control Microcode.
    
                                   These invalid states
    
                                   include:
    
                                   - Task not loaded and
    
                                   initialized
    
                                   - Busy
    
                                   - Output buffer busy
    
                                   (if data specified).
    
                                   The Primary Status
    
                                   Byte value is returned
    
                                   in the AH register.
    
    
    
        09h     Command not        The Realtime Control
    
                accepted           Microcode rejected the
    
                                   command by setting the
    
                                   PC Select Byte to FEh
    
                                   to indicate an error
    
                                   condition.
    
    
    
        0Ah     No resident        The interrupt handler
    
                Interrupt          (ICAINTH.COM) is not
    
                Handler            installed and executing.
    
    
    
        0Bh     Invalid            The interrupt handler
    
                interrupt          (ICAINTH.COM) version
    
                handler            is incompatible with
    
                version.           the Assembler Language
    
                                   Macro version.
    
    
    
        0Ch     Address out        The address specified is
    
                of range           invalid for the given
    
                                   co-processor adapter.
    
    
    
        0Dh     PeerHandle         A peer handle is not
    
                not available      available to be opened.
    
    
    
        0Eh     Unknown            An unknown peer handle
    
                peer handle        was specified.
    
    
    
        0Fh     Invalid            An invalid command was
    
                command            specified.
    
    

    Descriptions of Assembler Language Macro Modules

    A description of each of the Assembler Language Modules is provided in the remainder of this chapter.

    DEFCGROUP

    The DEFCGROUP macro groups user code segments for an .EXE file with those of ICAMAC.MAC and ICAEMAC.LIB.

    Invocation:

    DEFCGROUP  user_segments

    Function

    This macro is required in an .EXE file if any other macros are to be used. It groups user code segments with those of ICAMAC.MAC and ICAEMAC.LIB.

    Note:

    The DEFDGROUP macro must also be used.
    Entry Parameters
    
    user_segments = List of application-defined code segments.
    
    
    Note:
    If more than one segment is passed, the segment names must be enclosed within the following characters, < >, and must be separated by commas.
    
    Example with one code segment:
    
    
    
           DEFCGROUP CSEG
    
    
    
    Example with multiple code segments:
    
    
    
           DEFCGROUP   <CSEG1, CSEG2>
    
    
    Exit Parameters

    None.

    Error

    None.

    DEFDGROUP

    The DEFDGROUP macro groups user data segments for an .EXE file with those of ICAMAC.MAC and ICAEMAC.LIB.

    Invocation:

    DEFDGROUP   user_segments

    Function

    This macro is required in an .EXE file if any other macros are to be used. It groups the user data segments with those of ICAMAC.MAC and ICAEMAC.LIB.

    Note:

    The DEFCGROUP macro must also be used.

    Entry Parameters

    
    user_segments = List of application-defined data segments.
    
    
    Note:
    If more than one segment is passed, the segment names must be enclosed within the following characters, < >, and must be separated by commas.
    
    Example with one data segment:
    
    
    
           DEFDGROUP DSEG
    
    
    
    Example with multiple data segments:
    
    
    
           DEFDGROUP   <DSEG1, DSEG2>
    
    
    Exit Parameters

    None.

    Errors

    None.

    DEFCOMGROUP

    The DEFCOMGROUP macro groups user segments for a .COM file with those of ICAMAC.MAC and ICACMAC.LIB.

    Invocation:

    DEFCOMGROUP   user_segments

    Function

    This macro is required in a .COM file if any other macros are to be used. It groups user segments with those of ICAMAC.MAC and ICACMAC.LIB. It may also be used with an .EXE file that has the code and data segments in the same group. In this case, the ICACMAC.LIB is used instead of the ICAEMAC.LIB.

    Entry Parameters

    
    user_segments = List of application-defined segments.
    
    
    Note:
    If more than one segment is passed, the segment names must be enclosed within the following characters, < >, and must be separated by commas.
    
    Example with one segment:
    
    
    
           DEFCOMGROUP CSEG
    
    
    
    Example with multiple data segments:
    
    
    
           DEFCOMGROUP   <CSEG, DSEG>
    
    
    Exit Parameters

    None.

    Errors

    None.

    ICACMD

    The ICACMD macro issues a command to a task or to the Realtime Control Microcode.

    Invocation:

    ICACMD

    Function

    This macro issues a system unit to co-processor adapter command to a co-processor adapter task or to the Realtime Control Microcode. This macro does not wait for an interrupt response from the task.

    Entry Parameters

    AH =
    Logical co-processor adapter number.
    AL =
    Co-processor adapter task number.
    CX =
    Byte count of parameters; 0 if none.
    DL =
    The command to be issued.
    DS:BX =
    Pointer to the parameters if CX is not equal to 0.
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
    
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor number
    
    
    
        02h     Invalid co-processor
    
                task number
    
    
    
        04h     Co-processor adapter inactive
    
                but ICAPARM parameters exist
    
    
    
        06h     Invalid output buffer size
    
    
    
        07h     Invalid PC Select Byte value
    
                 AH = PC Select
    
    
    
        08h     Invalid Primary Status Byte
    
                value
    
                 AH = Status
    
    
    
        09h     Command not accepted
    
    

    ICAFPARM

    The ICAFPARM macro returns a pointer to a co-processor adapter's ICAPARM parameter table entry.

    Invocation:

    ICAFPARM

    Function

    This macro returns a pointer to a co-processor adapter's ICAPARM parameter table entry, resident in the DOS interrupt handler's memory. A detailed definition and explanation of this table is provided in "Chapter 8. Function Calls to the Interrupt Handler".

    Entry Parameters

    AH = Logical co-processor adapter number.

    Exit Parameters

    Carry flag =
    0 if no error; 1 if error.
    ES =
    Segment pointer to ICAPARM parameter table entry.
    DX =
    Offset pointer to ICAPARM parameter table entry.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAINBUF

    The ICAINBUF macro returns a pointer to the input buffer for a task number.

    Invocation:

    ICAINBUF

    Function

    This macro returns the offset and page pointer to the input buffer and the length of the input buffer for a task on a co-processor adapter.

    Entry Parameters

    AH =
    Logical co-processor adapter number.
    AL =
    Co-processor adapter task number.
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Buffer page number if no error; error code if error.
    CX =
    Buffer length in bytes.
    DX =
    Offset pointer within the page buffer.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        02h     Invalid task number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAINIT

    The ICAINIT macro initializes the other macros for DOS.

    Invocation:

    ICAINIT  [EXT]

    Function

    This module is required to initialize the other macros for DOS, and must precede all other executable macros. This macro must be located in the code segment, and must be invoked in "main" modules.

    Entry Parameters

    [EXT] =
    Optional parameter, CMAC (default) or EMAC.
    Where:
     
    CMAC =
    Module is to be linked with ICACMAC.LIB;
    EMAC =
    Module is to be linked with ICAEMAC.LIB.
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        0Ah     No resident interrupt handler
    
    
    
        0Bh     Invalid interrupt handler
    
                version
    
    

    ICALOC

    The ICALOC macro returns the segment value of the co-processor adapter's window in system unit storage.

    Invocation:

    ICALOC

    Function

    This macro returns the value of the location I/O port for a co-processor adapter. This defines where in the system unit's storage the co-processor adapter storage window resides.

    Entry Parameters

    AH = Logical co-processor adapter number.

    Exit Parameters

    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    ES =
    Segment of the co-processor adapter window in system unit storage.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAMACDATA

    The ICAMACDATA macro sets up the data areas to be used by the other macros.

    Invocation:

    ICAMACDATA  [EXT]

    Function

    This is a required macro to set up the data areas of the other macros. This macro must be issued in the data segment of an .EXE program or in a data area of a .COM program. The data segment in which this macro is used must be the current data segment when any other macros are issued. There is no executable code in this macro. This macro can be used in either the "main" module of a group of modules to be linked together or in the auxiliary modules. In the auxiliary modules, it must have a parameter.

    Entry Parameters

    [EXT] =
    Optional parameter to specify in an auxiliary file.
    Where:
     
    null =
    Module is a Main module;
    CMAC =
    Module is an auxiliary module to be linked with ICACMAC.LIB;
    EMAC =
    Module is an auxiliary module to be linked with ICAEMAC.LIB.
    Note:
    A "main" module contains the actual data used by the macros. There is only one main module in an executable file. An "auxiliary" module declares all reference to macro data as external. There can be multiple auxiliary modules in an executable file. The actual data used by the macros is stored in the main module.
    Exit Parameters

    None.

    Errors

    None.

    ICAOUTBUF

    The ICAOUTBUF macro returns a pointer to the output buffer for the requested task number.

    Invocation:

    ICAOUTBUF

    Function

    This macro returns the offset and page pointer to the output buffer and the length of the output buffer for a task on a co-processor adapter.

    Entry Parameters

    AH =
    Logical co-processor adapter number.
    AL =
    Co-processor adapter task number.
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Buffer page number if no error; error code if error.
    CX =
    Buffer length in bytes.
    DX =
    Offset pointer within the page buffer.
    Errors
    
    ----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        02h     Invalid task number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAPAG2P

    The ICAPAG2P macro converts a co-processor adapter address in a page:offset format to a 32-bit physical address format.

    Invocation:

    ICAPAG2P

    Function

    This macro converts a co-processor adapter address in a page:offset format to a 32-bit physical address format. The resulting address is computed relative to the current co-processor adapter shared storage window size.

    Entry Parameters

    
    AH = Logical co-processor adapter number
    
    AL = co-processor adapter page number to translate
    
         (relative to current page size).
    
    DX = co-processor adapter offset to translate
    
         (relative to current page size).
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    ES =
    32-bit physical address (high 16 bits)
    DX =
    32-bit physical address (low 16 bits)
    CX =
    Current shared storage window size in bytes
    
    -----------------------------------------------------------
    
      CX         Meaning
    
    -----------------------------------------------------------
    
      1FFFh       8KB shared storage window
    
    
    
      3FFFh      16KB shared storage window
    
    
    
      7FFFh      32KB shared storage window
    
    
    
      FFFFh      64KB shared storage window
    
    
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAPAG2S

    The ICAPAG2S macro converts a co-processor adapter address in page:offset format to segment:offset.

    Invocation:

    ICAPAG2S

    Function

    This macro converts a co-processor adapter address in page:offset format to segment:offset. The resulting segment:offset is computed relative to the current co-processor adapter shared storage window size. For the Realtime Interface Co-Processor Portmaster Adapter/A, a page:offset address greater than 1MB is returned with an address-out-of-range warning and a 32-bit physical address.

    Entry Parameters

    
    AH = Logical co-processor adapter number.
    
    AL = Co-processor adapter page.
    
    DX = Co-processor adapter offset.
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    ES =
    Translated segment.
    DX =
    Translated offset.
    CX =
    Current shared storage window size in bytes.
    
    -----------------------------------------------------------
    
      CX         Meaning
    
    -----------------------------------------------------------
    
      1FFFh       8KB shared storage window
    
    
    
      3FFFh      16KB shared storage window
    
    
    
      7FFFh      32KB shared storage window
    
    
    
      FFFFh      64KB shared storage window
    
    
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    
    
        0Ch     Address out of range
    
                ES = 32-bit physical
    
                     address (high)
    
                DX = 32-bit physical
    
                     address (low)
    
                CX = Current shared
    
                     storage window
    
                     size
    
    

    ICAPHY2P

    The ICAPHY2P macro converts a co-processor adapter address in a 32-bit physical address format to page:offset format.

    Invocation:

    ICAPHY2P

    Function

    This macro converts a co-processor adapter address in a 32-bit physical address format to page:offset format. The resulting page:offset is computed relative to the current co-processor adapter shared storage window size.

    Entry Parameters

    
    AH = Co-processor adapter logical card number.
    
    ES = 32-bit physical address (high 16 bits).
    
    DX = 32-bit physical address (low 16 bits).
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error
    AL =
    Translated page number if no error; error code if error.
    DX =
    Translated offset
    CX =
    Current shared storage window size in bytes
    
    -----------------------------------------------------------
    
      CX        Meaning
    
    -----------------------------------------------------------
    
      1FFFh      8KB shared storage window
    
    
    
      3FFFh     16KB shared storage window
    
    
    
      7FFFh     32KB shared storage window
    
    
    
      FFFFh     64KB shared storage window
    
    
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    
    
        0Ch     Address out of range
    
    

    ICAPEERCLOSE

    The ICAPEERCLOSE macro returns a peer handle to the system and prevents further reception of peer request blocks.

    Invocation:

    ICAPEERCLOSE

    Function

    This macro returns a peer handle to the system and prevents any further reception of peer request blocks.

    Entry Parameters

    CX = Peer handle

    Exit Parameters

    Carry flag =
    0 if no error; 1 if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        0Eh     Unknown peer handle
    
    
    
        0Fh     Invalid command
    
    

    ICAPEEROPEN

    The ICAPEEROPEN macro establishes an application as a peer task within the processor.

    Invocation:

    ICAPEEROPEN

    Function

    This macro establishes an application as a peer task within the system unit processor. The application provides a command handler routine that is called upon receipt of a peer command; a peer handle is returned to identify the task.

    The peer command handler:

    Upon arrival of a peer request block, control is given to the peer command handler. Upon entry to the command handler, a doubleword pointer to the incoming peer request block is on the stack. The layout of the stack frame is as follows:
    
      SS:SP       Far return address
    
      SS:SP + 4   Doubleword peer request
    
                  block pointer
    
    
    The command handler should exit via a far return and leave the peer request block pointer on the stack.

    Note:

    The command handler is called at the interrupt level and must preserve the state of the machine.
    Entry Parameters
    
    ES = Segment of peer command handler.
    
    DX = Offset of peer command handler.
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    CX =
    Peer handle.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        0Dh     Peer Handle not available
    
    
    
        0Fh     Invalid command
    
    

    ICAPEERSEND

    The ICAPEERSEND macro sends a peer request block to another peer task.

    Invocation:

    ICAPEERSEND

    Function

    This macro sends a peer request block to another peer task.

    Entry Parameters

    
    ES = Segment of peer request block
    
    DX = Offset of peer request block
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        09h     Command not accepted
    
    
    
        0Fh     Invalid command
    
    

    ICAQINT

    The ICAQINT macro queries the interrupt flag of a particular task on a particular co-processor adapter.

    Invocation:

    ICAQINT

    Function

    This macro queries the interrupt flag for a task on a co-processor adapter. The flags must have been previously declared using ICAVSET. The status is returned in the zero flag to indicate whether or not an interrupt occurred. If an interrupt occurred, the zero flag is set to 0 (off); if an interrupt did not occur, the zero flag is set to 1 (on). The interrupt flag is cleared if it was on.

    Restrictions

    If the AL register contains an invalid task number, no error is generated. The zero flag, upon return, indicates that no interrupt occurred.

    Note:

    This macro requires the following prerequisites:
    Entry Parameters
    AH =
    Logical co-processor adapter number.
    AL =
    Co-processor adapter task number.
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Zero flag =
    0 if interrupt occurred;
    
          1 if no interrupt occurred
    
    
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        02h     Invalid task number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAREL

    The ICAREL macro releases the CPU Page Selector.

    Invocation:

    ICAREL

    Function

    This macro releases use of a co-processor adapter CPU Page Selector. An application program ID is required to prove ownership of the CPU Page Selector. The ID should be the same as the ID used to reserve the CPU Page Selector with the ICARSV macro.

    Entry Parameters

    AH =
    Logical co-processor adapter number.
    DL =
    Application program ID (adapter task number).
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    
    
        05h     Page Selector already
    
                reserved
    
    

    ICARET

    The ICARET macro returns from an interrupt routine that was entered via a jump vector previously set by ICAVSETM macro.

    Invocation:

    ICARET label

    Function

    This macro must be used to return to the DOS interrupt handler from a co-processor adapter interrupt. The ICAVSETM macro must have been used to set up an entry into the user's program. To return from that entry, the ICARET macro is used.

    Entry Parameters

    Label =
    Is the label of the interrupt routine to return from.
    Note: The label must be the same label used with the ICAVSETM macro that set up the entry to the routine from which a return is requested.
    Example:
    ICARET LABEL
    Exit Parameters

    None.

    Errors

    None.

    ICARSET

    The ICARSET macro issues a hardware reset command to the co-processor adapter.

    Invocation:

    ICARSET

    Function

    This macro issues a hardware reset on the co-processor adapter.

    Restrictions: Special consideration should be given before this macro is executed. The Realtime Control Microcode and all loaded applications tasks will be unloaded. The hardware will be set to the same initialized state as when the power-on self-test (POST) is executed. This macro does not return control to the system unit application program until the co-processor adapter PROM power-on-self-test services has completed. This delay may take up to 20 seconds.

    Entry Parameters

    
    AH = Logical co-processor adapter number.
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICARSV

    The ICARSV macro reserves the CPU Page Selector.

    Invocation:

    ICARSV

    Function

    This macro reserves the use of a co-processor adapter's CPU Page Selector.

    Entry Parameters

    
    AH = Logical co-processor adapter number.
    
    DL = Application program ID (adapter task number).
    
    
    
      Note: The application program ID is used to determine
    
      ownership of the CPU Page Selector.  The CPU Page
    
      Selector can only be released with the same ID.
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    
    
        05h     Page Selector already
    
                reserved
    
    

    ICASEG2P

    The ICASEG2P macro converts a co-processor adapter address in segment:offset format to page:offset.

    Invocation:

    ICASEG2P

    Function

    This macro converts a co-processor adapter address in segment:offset format to page:offset. The resulting page:offset is computed relative to the current co-processor adapter shared storage window size.

    Note:

    On the Realtime Interface Co-Processor Portmaster Adapter/A, this routine assumes a one-to-one page mapping in the Portmaster/A translate table; therefore, applications using Portmaster/A expanded memory should use physical addresses. Refer to the Realtime Interface Co-Processor Firmware Technical Reference for more information on the translate table and expanded memory.
    Entry Parameters
    
    AH = Logical co-processor adapter number.
    
    ES = Co-processor adapter segment.
    
    DX = Co-processor adapter offset.
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Translated page number if no error; error code if error.
    DX =
    Translated offset.
    CX =
    Current shared storage window size in bytes.
    
    -----------------------------------------------------------
    
      CX         Meaning
    
    -----------------------------------------------------------
    
      1FFFh       8KB shared storage window
    
    
    
      3FFFh      16KB shared storage window
    
    
    
      7FFFh      32KB shared storage window
    
    
    
      FFFFh      64KB shared storage window
    
    
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICASTAT

    The ICASTAT macro returns the Primary Status Byte code for a given task number.

    Invocation:

    ICASTAT

    Function

    This macro returns the Primary Status Byte value in the Interface Block for a task on a co-processor adapter.

    Entry Parameters

    
    AH = Logical co-processor adapter number.
    
    AL = Co-processor adapter task number.
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Primary Status Byte if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        02h     Invalid task number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICASTATX

    The ICASTATX macro returns the location of the secondary status field for a given task.

    Invocation:

    ICASTATX

    Function

    This macro returns the offset, page pointer, and length of the secondary status field for a task on a co-processor adapter.

    Entry Parameters

    
    AH = Logical co-processor adapter number.
    
    AL = Co-processor adapter task number.
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Status page if error; error code if error.
    CX =
    Status buffer length in bytes.
    DX =
    Status buffer offset within the page.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        02h     Invalid task number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAVRET

    The ICAVRET macro returns a specified number of interrupt flags to the interrupt handler.

    Invocation:

    ICAVRET  [MAXVECT]

    Function

    This macro returns a specified number of interrupt flags (MAXVECT) to the interrupt handler. These interrupt flags are acquired using the ICAVSET macro. MAXVECT is a constant or equated value. It must have the same value as used by the ICAVSET macro to acquire the interrupt flags. This module should be used if a task has issued the ICAVSET macro and is going to terminate. A "well-behaved" task must first issue a ICAVRET to return the flags to avoid unpredictable results generated from an interrupt using that vector. This macro always returns the flag for the level 1 error task (task 254).

    Entry Parameters

    AH =
    Logical co-processor adapter number.
    MAXVECT =
    Optional parameter for the number of interrupt flags to be returned (default - MAXTASK).
    Example
    Return all MAXVECT interrupt flags:
    
        MOV     AH,0  ; select co-processor
    
                      ; adapter # 0
    
        ICAVRET       ; return all 254 flags
    
    
     
    Return first 10 interrupt flags:
    
        MOV     AH,1  ; select co-processor
    
                      ; adapter # 1
    
        ICAVRET 10    ; return first 10 flags
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
      01h       Invalid co-processor
    
                adapter number
    
    
    
      04h       Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAVRETM

    The ICAVRETM macro returns a vector acquired using the ICAVSETM macro.

    Invocation:

    ICAVRETM LABEL

    Function

    This macro returns a vector that was acquired via the ICAVSETM macro to the interrupt handler. It should be used before the program terminates. If the program terminates before returning the vector, unpredictable results may occur.

    Entry Parameters

    AH =
    Logical co-processor adapter number
    AL =
    Co-processor adapter task number
    LABEL =
    Must be the same LABEL that was used in the ICAVSETM
    macro call to acquire the vector.
    Example--
    Invocation of macro:
    
    MOV      AH,0  ; Select co-processor adapter # 0
    
    MOV      AL,10 ; Task number ten
    
    
    ICAVRETM LABEL ; Entry point label
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        02h     Invalid task number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAVSET

    The ICAVSET macro requests the set up of interrupt flags that can be queried using ICAQINT.

    Invocation:

    ICAVSET  [MAXVECTOR]

    Function

    This macro sets up interrupt flags for tasks on a co-processor adapter that can interrupt the system unit. It sets up the interrupt bit table for the specified co-processor adapter. Flags, which the system unit application task can poll through the ICAQINT macro, are declared. All interrupt vectors are set in the interrupt handler to one entry point in the macro that handles interrupts for the co-processor adapter for task numbers 0-MAXVECTOR. If MAXVECTOR is not specified, storage for 254 vectors is reserved and MAXTASK flags are set from the interrupt handler. This macro always reserves a flag for the level 1 error task (task 254).

    Entry Parameters

    AH =
    Logical co-processor adapter number.
    [MAXVECTOR] =
    Optional parameter to indicate the maximum number of tasks on a co-processor adapter that can interrupt.
    Example
    
    MOV     AH,0   ; select co-processor adapter # 0
    
    ICAVSET        ; set up interrupt flags
    
                   ; for all tasks
    
    MOV     AH,1   ; select co-processor adapter # 1
    
    ICAVSET 10     ; set up interrupt flags
    
                   ; for first 10
    
                   ; tasks plus Realtime
    
                   ; Control Microcode
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAVSETM

    The ICAVSETM macro sets an interrupt jump vector for a particular task on a particular co-processor adapter.

    Invocation:

    ICAVSETM label

    Function

    This macro sets up an interrupt jump vector for a task on a specific co-processor adapter. This macro works for tasks 1 through MAXTASK and for the Realtime Control Microcode and Level 1 error (254h). This macro is to be used where the application program wants to be directly interrupted. The application program must return from the interrupt by using the ICARET macro.

    Entry Parameters

    AH =
    Logical co-processor adapter number.
    AL =
    Co-processor adapter task number.
    Label =
    Is the near label at the entry point of the
    interrupt routine.
    Example
    
    MOV   AX,0001h ;co-processor adapter 0, task 1
    
    ICAVSETM LABEL ;
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    DX =
    Old vector offset.
    ES =
    Old vector segment.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        02h     Invalid task number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    ICAWINDOW

    The ICAWINDOW macro alters the CPU Page Selector.

    Invocation:

    ICAWINDOW

    Function

    This macro changes the co-processor adapter window selector to point to a specific co-processor adapter's storage page.

    Entry Parameters

    
    AH = Logical co-processor adapter number.
    
    AL = Co-processor adapter storage page number.
    
    DL = Application program ID.
    
    
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Old page value if no error; error code if error.
    AH =
    Old page value.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
        01h     Invalid co-processor
    
                adapter number
    
    
    
        04h     Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    
    
        05h     Page Selector already
    
                reserved
    
    

    Chapter 8. Function Calls to the Interrupt Handler

    Interrupt handler services are available through the use of the interrupt vector 7Fh function calls, described in this section.


    Internal ICAPARM Parameter Table

    A resident internal table called the ICAPARM parameter table is constructed when the interrupt handler is installed. The table contains the information supplied from the user-created ICAPARM.PRM ASCII file that is accessed during the interrupt handler installation process. This parameter table should not be confused with the ICAPARM.PRM file described in Chapter 3. This table may be accessed by application programs through calls via the Interrupt Vector 7Fh. The "INT 7Fh" instruction is used to call the Interrupt Handler.

    The format of the ICAPARM parameter table is:

    
    -----------------------------------------------------------------
    
                                                     Valid
    
      Byte      Name         Description             Values
    
    -----------------------------------------------------------------
    
      00h-01h   I/O_addr     Co-processor            02A0    22A0
    
                             base I/O                06A0    26A0
    
                             address                 0AA0    2AA0
    
                                                     0EA0    2EA0
    
                                                     12A0    32A0
    
                                                     16A0    36A0
    
                                                     1AA0    3AA0
    
                                                     1EA0    3EA0
    
    
    
      02h       last         Last co-processor       Zero if
    
                             adapter indicator       last entry
    
    
    
      03h       meg          Meg value for           Variable,
    
                             the 8K page             depending on
    
                             window segment          system unit
    
                             in system unit          memory
    
                             storage                 architecture
    
    
    
      04h       page         Window                  00h-7Fh
    
    
    
      05h       maxtask      Highest task number     00h-FDh
    
                             that can be loaded
    
                             on the co-processor
    
                             adapter
    
    
    
      06h       maxpri       Highest priority        01h-FFh
    
                             level on the
    
                             co-processor adapter
    
    
    
      07h       maxqueue     Highest user queue      00h-FEh
    
                             number on the
    
                             co-processor adapter
    
    
    
      08h       maxtime      Highest software        00h-FEh
    
                             timer number on
    
                             the co-processor
    
                             adapter
    
    
    
      09h       cadmeg       Compare Degate 2        00h-FFh
    
    
    
      0Ah -     cadword      Compare Degate 0 and 1  0000h-
    
      0BH                                            FFFFh
    
    
    
      0Ch       reserved 1   Reserved
    
    
    
      0Dh       reserved 2   Reserved
    
    
    
      0Eh       reserved 3   Reserved
    
    
    
      0Fh       reserved 4   Reserved
    
    
    
      10h       level        System unit              FFh if
    
                             interrupt level used     inactive
    
                             by the co-processor      co-proc.
    
                             adapter                  adapter.
    
                                                      See the
    
                                                      Hardware
    
                                                      Tech. Ref.
    
    
    
      11h-12h   vectorptr    Address of the
    
                             interrupt vectors that
    
                             the DOS interrupt
    
                             handler jumps to when
    
                             servicing co-processor
    
                             adapter interrupts.
    
    
    
    
    
      13h       windowsize   Size of the co-          See
    
                             processor adapter's      Windowsize
    
                             shared storage           bit
    
                             window                   definition
    
    
    
      14h       adapter      Co-processor adapter     See
    
                             type                     Adapter
    
                                                      bit
    
                                                      definition
    
    
    
      15h       EIB ID for   Electrical Interface     See the
    
                port 0       Board ID for port 0      co-proc.
    
                                                      adapter's
    
                                                      Hardware
    
                                                      Tech. Ref.
    
    
    
      16h       EIB ID for   Electrical Interface     Same as
    
                port 1       Board ID for port 1      for port 0
    
    
    
      17h       Phy. slot    The physical slot        FFh if
    
                number       number where an          N/A
    
                             adapter is installed
    
    
    
      18h       Clocking     The clocking options     00h if
    
                opt. ports   for ports 0 and 1        N/A
    
                0 and 1
    
    
    
      19h-1Fh   Reserved     Reserved
    
    

    Windowsize bit definition:

    
        X   X   X   X   X   A   B   C
    
    
    
         Where:
    
    
    
        A   B   C
    
    -------------------
    
        0   0   0       8KB shared storage window
    
    
    
        0   0   1      16KB shared storage window
    
    
    
        0   1   0      32KB shared storage window
    
    
    
        0   1   1      64KB shared storage window
    
    
    
        X is undefined.
    
    
    Adapter bit definition:
    
        X   X   X   X   X   X   X   A
    
    
    
         Where:
    
    
    
        A
    
    ------------
    
        0         Co-processor adapter is the Realtime Interface
    
                  Co-Processor, Realtime Interface Co-Processor
    
                  Multiport, or Realtime Interface Co-Processor
    
                  Multiport Adapter, Model 2.
    
    
    
        1         Co-processor adapter is the Realtime Interface
    
                  Co-Processor Multiport/2, X.25 Interface
    
                  Co-Processor/2, Realtime Interface Co-Processor
    
                  Portmaster Adapter/A, or ISDN Interface
    
                  Co-Processor/2
    
    
    
        X is undefined.
    
    
    Associated Interface Modules
    
    -----------------------------------------------------------
    
        Type    Invocation   Name       Reference
    
    -----------------------------------------------------------
    
        Macro   ICAFPARM     ICAFPARM   Chapter 7
    
    

    Interrupt Vector 7Fh Function Calls

    Set Vector

    Sets the vector value for a task on a co-processor adapter.

    Invocation:

    INT 7Fh, AX = 0101h, BH = 0000 XXXX

    Function

    This function call replaces the interrupt vector in the Interrupt Handler's internal Vector Table with interrupt vectors to be used by application program's interrupt handlers. After changing the vector, the Interrupt Handler returns, as an exit parameter, the old (original) vector table entry. The ICAINTH jumps to the user-defined vector when handling an interrupt for that task number on the given co-processor adapter number. The application program should save the original vector table entry and exit its interrupt service routine by jumping on that old vector. This allows multiple user-defined interrupt vectors to be entered on one interrupt.

    Entry Parameters

    AX =
    0101h
    BH =
    0000 XXXX   Where XXXX = logical co-processor adapter number.
    BL =
    Task number (0 - MAXTASK for the specified co-processor adapter).
    ES =
    Segment value for new jump vector.
    DX =
    Offset value for new jump vector.
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    ES =
    Old jump vector segment (task is to jump on this vector when finished).
    DX =
    Old jump vector offset.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
      01h       Invalid co-processor
    
                adapter number
    
    
    
      02h       Invalid task number
    
    
    
      04h       Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    Find Parameters

    Returns a pointer to the ICAPARM parameter table entry for a co-processor adapter.

    Invocation:

    INT 7Fh, AX = 0101h, BH = 0001 XXXX

    Function

    This function call returns a pointer to the ICAPARM parameter table record for a given co-processor adapter.

    Note:

    If the co-processor adapter is inactive, the LEVEL field in the ICAPARM parameter table contains an 0FFh, the carry flag is set to 1, and the AL error code is 04h.
    Entry Parameters
    AX =
    0101h
    BH =
    0001 XXXX Where XXXX = logical co-processor adapter number.
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    ES =
    Segment value of ICAPARM parameter table.
    DX =
    Offset value of ICAPARM parameter table.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
      01h       Invalid co-processor
    
                adapter number
    
    
    
      04h       Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    

    Reserve

    Reserves a co-processor adapter CPU Page Selector.

    Invocation:

    INT 7Fh, AX = 0101h, BH = 0010 XXXX

    Function

    This function call reserves a co-processor adapter CPU Page Selector for a particular user program. This function is not required if only one program is running on the system unit.

    Entry Parameters

    AX =
    0101h
    BH =
    0010 XXXX Where XXXX = logical co-processor adapter number.
    DL =
    Application program ID

    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
      01h       Invalid co-processor
    
                adapter number
    
    
    
      04h       Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    
    
      05h       CPU Page Selector reserved
    
                by another program
    
    

    Release

    Releases a co-processor adapter CPU Page Selector for a particular user program.

    Invocation:

    INT 7Fh, AX = 0101h, BH = 0011 XXXX

    Function

    This function call releases the co-processor adapter CPU Page Selector that it previously reserved. No program can release the CPU Page Selector that was reserved by another program.

    Entry Parameters

    AX =
    0101h
    BH =
    0011 XXXX Where XXXX = logical co-processor adapter number.
    DL =
    Application program ID (DL=0 can also be used in a single user environment.)
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
      01h       Invalid co-processor
    
                adapter number
    
    
    
      04h       Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist
    
    
    
      05h       CPU Page Selector reserved
    
                by another program.
    
    

    Reset

    Resets the requested co-processor adapter.

    Invocation:

    INT 7Fh, AX = 0101h, BH = 0100 0000

    Function

    This function call resets the co-processor adapter. The control microcode and all other tasks are unloaded, and the co-processor adapter goes through its power-on self test (POST). If the POST is not successfully completed, the function timeouts and returns an error code.

    Entry Parameters

    AX =
    0101h
    BH =
    40h
    BL =
    logical co-processor adapter number
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
      01h       Invalid co-processor
    
                adapter number
    
    
    
      04h       Co-processor adapter
    
                inactive but ICAPARM
    
                parameters exist.
    
                (Adapter failed power-
    
                on self test.)
    
    

    PeerOpen

    Establishes an application as a peer task within the system unit.

    Invocation:

    INT 7Fh, AX = 0101h, BH = 0100 0001

    Function

    This function call causes an application to be viewed as a peer task. The application provides a command handler routine that is called when a peer command is received. A peer handle is returned to identify the task.

    The command handler:

    When a peer request block is received, control is given to the peer command handler. Upon entry to the command handler, a doubleword pointer to the incoming peer request block is on the stack. The layout of the stack frame is as follows:
    
      SS:SP       Far Return Address
    
    
    
      SS:SP + 4   Doubleword peer request
    
                  block pointer
    
    
    The command handler should exit via a far return and leave the peer request block pointer on the stack.

    Note:

    The command handler is called at the interrupt level and must preserve the state of the machine.
    Entry Parameters
    AX =
    0101h
    BH =
    41h
    ES =
    Segment value of peer command handler
    DX =
    Offset value of peer command handler
    Exit Parameters
    CX =
    Peer handle.
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
      0Dh       Peer handle not available
    
    
    
      0Fh       Invalid command
    
    

    PeerClose

    Closes a peer task.

    Invocation:

    INT 7Fh, AX = 0101h, BH = 0100 0010

    Function

    This function call returns a peer handle to the system and prevents further reception of peer request blocks.

    Entry Parameters

    AX =
    0101h
    BH =
    42h
    CX =
    Peer handle
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
      0Eh       Unknown peer handle
    
    
    
      0Fh       Invalid command
    
    

    PeerSend

    Sends a peer request block to another peer task.

    Invocation:

    INT 7Fh, AX = 0101h, BH = 0100 0011

    Function

    This function call sends a peer request block to another peer task.

    Entry Parameters

    AX =
    0101h
    BH =
    43h
    ES =
    Segment value of peer request block
    DX =
    Offset value of peer request block
    Exit Parameters
    Carry flag =
    0 if no error; 1 if error.
    AL =
    Unchanged if no error; error code if error.
    Errors
    
    -----------------------------------------------------------
    
      AL Code   Meaning
    
    -----------------------------------------------------------
    
      09h       Command not accepted
    
    
    
      0Fh       Invalid command
    
    

    No Operation

    Invocation:

    INT 7Fh, AX = 0101h, BH = 0111 XXXX

    Function

    This function returns with carry clear if the interrupt handler is resident. This function, in conjunction with comparing the INT 7Fh (doubleword location 0000:01FCh) vector for a 0:0 value, indicates whether or not the interrupt handler is resident. If the interrupt vector 7Fh is not 0, issue this function request to determine if the interrupt handler is resident. If the interrupt vector 7Fh is 0:0, the interrupt handler is not resident.

    Entry Parameters

    AX =
    0101h
    BH =
    0111 0000
    Exit Parameters
    Carry flag =
    0 if interrupt handler is resident;
    
           1 if interrupt handler is not resident.
    
    
    AL =
    Undetermined

    Query Version

    Returns the version of the installed Interrupt Handler.

    Invocation:

    INT 7Fh, AX = 101h, BH = 1000 0000

    Function

    This function returns the version of the interrupt handler. This service is provided for applications that have dependencies on the interrupt handler version.

    Entry Parameters

    AX =
    0101h
    BH =
    1000 0000  
    Exit Parameters
    
    -----------------------------------------------------------
    
      Version      1.0    1.01   1.02   1.03   1.04   1.05
    
    -----------------------------------------------------------
    
      Carry Flag    1      1      1      0      0      0
    
    
    
      DX            UC     UC     UC     3      4      5
    
    
    Note: UC = Unchanged.

    Errors

    Not applicable.


    Chapter 9. Online Dump Facility

    The Online Dump Facility (file DUMP.COM) is a debugging tool that dumps the memory contents and the I/O port values of a co-processor adapter to either diskettes or a fixed disk. The dump file can then be formatted for viewing and printing, using the Dump Formatter Facility (file FRMTDUMP.EXE), supplied with your DOS Support product. A dump can be done in one of three ways:


    Output Files

    The Online Dump Facility produces a system file called ICASYSn.DMP, where n is the hexadecimal number of the logical co-processor adapter.

    The file is in block-oriented format and has the following structure:


    Loading the Online Dump Facility

    To load the Online Dump Facility, do the following:

    1. Copy the Dump Facility to a fixed disk. Issuing the following DOS command:

      > COPY A: DUMP.* C:/V

      The following files are transferred:

      
      DUMP.COM
      
      DUMP.MSG
      
      
    2. Make the Dump Facility resident.

      The co-processor adapter cannot issue a dump request unless

      1) the co-processor adapter is "armed" to issue a prompt when it detects a dump condition, and

      2) the Dump Facility (DUMP.COM) is resident in memory. For information on arming a co-processor adapter, see "Arming a Co-Processor Adapter," later in this chapter.

      To make the DUMP.COM file resident, issue any form of the DUMP command. This invokes the Dump Facility and makes it resident in memory. For example, the command

      > DUMP A0

      activates the Online Dump Facility without arming a specific co-processor adapter. DUMP.COM becomes resident in memory, which allows an armed co-processor adapter to issue a prompt message if a dump condition occurs.


    Dumping a Co-Processor Adapter

    A dump can be done in either of the following ways:

    Note:
    After completion of a dump, your co-processor adapter must be reset and reloaded to enable you to continue to use it. See "Resetting a Co-Processor Adapter," later in this chapter.

    User-Initiated Dump

    A user-initiated dump can be done interactively using the Online Dump Facility menus or with a DUMP command that specifies the co-processor adapter number and the destination drive for the dump.

    Command Example

    The following command writes the dump data for logical co-processor adapter number 1 to default drive A.

    > DUMP 1

    Menu-Driven Example

    The following form of the Dump command invokes a menu-driven process:

    > DUMP

    When no co-processor adapter number is entered with this command, menus are displayed to allow you to select the co-processor adapter and the destination drive for the dump. If you select a diskette drive for the output, a message similar to the following is displayed:

    
         PLACE DISKETTE XX IN DRIVE A
    
    
    
         PRESS:
    
           1  TO CONTINUE DUMP OF RIC #
    
           2  TO SUSPEND DUMP AND RETURN TO DOS
    
           3  TO RESTART FROM THE BEGINNING
    
           9  TO ABORT DUMP AND RETURN TO DOS
    
    
    (RIC is an abbreviation of the Realtime Interface Co-Processor and refers to all of the co-processor adapters.)

    In response to this menu, insert a diskette in the proper drive and press 1.

    The Dump Facility writes two files on the diskette(s) or a fixed disk. The order, names, and descriptions of these files are:

    1. ICASYSn.DMP--storage of co-processor adapter data configuration data. This file must fit on a single diskette.

    2. ICAMEnii.DMP--storage of co-processor adapter RAM data.
    Where:

    ii = null if the file fits on a single diskette (or if using a fixed disk). If not, ii is a member of the sequence: 00, 01, 02, ..., 99. The first file is named ICAMEn00.DMP, and the second file is named ICAMEn01.DMP, and so on.

    Leave enough free space on your diskettes so that ICAMEnii.DMP does not span over 100 diskettes. All occurrences of these files on your root directory (if present) are erased prior to any data dump to diskette.

    Write the name of the file ICAMEnii.DMP on the corresponding diskette cover of each diskette. This enables the diskettes to be examined in the correct order when the diskettes are used later during correcting or debugging of your co-processor adapter hardware or software.

    Upon completion of the dump, send the diskettes to the appropriate service personnel, or format the dump for viewing or printing using the Dump Formatter Facility.

    Co-Processor-Adapter-Initiated Dump

    The co-processor adapter can be armed to request a dump by issuing a prompt, or it can be armed to generate an automatic dump. See "Arming a Co-Processor Adapter," for information of generating an automatic dump. This section describes the prompt-generated dump.

    When a co-processor adapter requests a dump, the following message is displayed to your screen:

    
       DUMP REQUEST:RICnn. TYPE "CONT" TO RESUME
    
    
    This is an "INFORM MESSAGE", where nn is the co-processor adapter number.

    Respond by typing:

    >CONT

    and continue with the application on which you are working. Any keystrokes in the type-ahead buffer are lost. You may perform the requested dump from the DOS command line at your convenience using the DUMP command to specify the destination drive.


    Changing the Dump Drive

    You can change the disk or diskette drive being used for dumping co-processor adapter data; the default dump drive for all co-processor adapters is drive A. You can specify a different drive for the dump data by issuing the Dump command followed by the desired drive. For example, the following command assigns the output to drive C:

    > DUMP c:

    The drive specification becomes effective immediately upon entering the command, even during a suspended dump.


    Arming a Co-Processor Adapter

    The co-processor adapter can be armed to do one of the following in response to a level 1 error on the co-processor adapter:

    You can arm a co-processor adapter by using the arm (A) option of the Dump command.

    The command can be issued from the DOS prompt line or it can be added to your AUTOEXEC.BAT file. If the command is added to your AUTOEXEC.BAT file, the co-processor adapter(s) is automatically armed during power-up and DUMP.COM is made resident.

    Following is the command syntax for arming a co-processor adapter:

    DUMP [A[RM]([n][,]...)]

    where DUMP A[RM]([n][,]...) specifies which co-processor adapters to arm.

    The following example arms logical co-processor adapters 0 and 1:

    DUMP A(0,1)

    To arm the co-processor adapter to automatically write the dump data to disk in response to a level 1 error, include in your AUTOEXEC.BAT file a dump command that specifies the co-processor adapter number and the destination drive. In this case, the co-processor is automatically dumped without user intervention. The user should verify that the dump drive has enough free storage before arming a co-processor adapter for an automatic dump.


    Restoring a Co-Processor Adapter

    Users can restore a previously-armed co-processor adapter. Restoring a co-processor adapter returns it to the state it was in prior to the last time it was armed. The adapter cannot request a dump while it is in a restored mode.

    An armed co-processor adapter can be restored by using the restore (R) option of the Dump command. Following is the syntax for the restore option:

    DUMP [R[ST]([n][,]...)]

    where n specifies which co-processor adapters to restore to their states prior to the last time they were armed. The following example restores logical co-processor adapter 1.

    DUMP R(1)


    Resetting a Co-Processor Adapter

    After a dump is completed, your co-processor adapter must be reset and reloaded to enable it to continue to be used.

    Reset your co-processor adapter after a dump in one of the following ways:

    1. Turn the system unit off and then on. This method has the disadvantage of corrupting all the data in your system unit's memory, plus all data in the co-processor adapters other than the one dumped.

    2. Use the ICARSET macro. If you write a program that stores a logical co-processor adapter number in the AH register and then use the ICARSET macro, the co-processor adapter corresponding to that co-processor adapter number is reset.
    After resetting the co-processor adapter, reload (install) the necessary programs as defined in this chapter and in "Chapter 2.".

    Chapter 10. Dump Formatter Facility

    The Dump Formatter Facility converts the machine-readable images generated by the DOS Support Online Dump Facility into a format for viewing and printing. This Dump Formatter Facility organizes the dump data into an easy-to-read format, using headers and blocks to group related information.

    The Dump Formatter Facility is provided with the Realtime Interface Co-Processor DOS Support Version 1.04 product; it is an EXE file named FRMTDUMP.EXE. Along with this file, a profile is provided to allow the selection of configuration parameters; that file is named FRMTDUMP.PRO.

    The Dump Formatter also provides a Copy and Combine function. This function is used when the data files generated by the Online Dump Facility are stored on several diskettes. In this case, the data files must be combined into a single disk or diskette before the files can be formatted by the Dump Formatter Facility. If the source drive and the destination drive are both diskette drives, the Copy and Combine function requires that they be different drives. However, if the source drive and destination drive are on a fixed disk, they may be on the same disk.


    Output Files

    The Dump Formatter Facility creates at least two files when formatting a dump of a co-processor adapters memory and I/O image:

    1. One file containing the memory image. This file is named MEMORYn.PRT, where n is the logical co-processor adapter number (hexadecimal).

    2. One file containing the I/O image. This file is named SYSINFOn.PRT, where n is the logical co-processor adapter number (hexadecimal).
    MEMORYn.PRT contains the formatted contents of co-processor adapter memory. SYSINFOn.PRT contains all information, other than the contents of memory, which includes co-processor adapter software version numbers, microprocessor register contents, I/O ports, the free-memory listing, and task information.

    Dump Formatter Facility Invocation

    If the dump files are on multiple diskettes, use the Copy and Combine function to create a single file before using the formatting function to format the file.

    Invoking the Copy and Combine Function

    To invoke the Dump Formatter Facility's Copy and Combine function, the following syntax is required:

    FRMTDUMP CC n < source < dest. > >

    
         Where:
    
    
    
             n = the logical co-processor adapter number
    
                            (hexadecimal).
    
    
    
    < source > = the path of the source dump data.
    
    
    
     < dest. > = the path of the destination (combined)
    
                 file.
    
    
    The following rules apply:
    1. If you specify only one path, it is assumed to be the source specification. The destination is assumed to be the current directory.

    2. If no drive or path is given, it is assumed that the root directory of drive A is the source and the current directory is the destination.

    3. The source drive cannot be the same as the destination drive if the drive is a diskette drive.

    4. Once the files are in their combined form (that is, they only have a single digit in the file name), they can be used to generate the final Dump Formatter Facility output files--SYSINFOn.PRT and MEMORYn.PRT.

    5. The source files must have the file names given them by the Online Dump Facility. The memory files (ICAMEnii.DMP) and the system file (ICASYSn.DMP) are required for the Copy and Combine operation.

    Invoking the Formatting Function

    To invoke the Dump Formatter Facility's Formatting function, the following syntax is required:

    FRMTDUMP n <M> <S> </O>

    
         Where:
    
    
    
           n  = the logical co-processor adapter number
    
                           (hexadecimal).
    
    
    
          <M> = causes the generation of MEMORYn.PRT.
    
    
    
          <S> = causes the generation of SYSINFOn.PRT.
    
    
    
         </O> = is the profile override feature.
    
    
    The following rules apply:

    1. If neither "M" nor "S" is specified, only the file MEMORYn.PRT is generated.

    2. The generated output files of the Dump Formatter Facility are placed in the current directory on the current drive.

    3. The /O override feature allows the user to enter new values for the following profile parameters: TITLE, USER_SEG, MEMLIST, and TASKLIST. Setting new parameter values does not alter the profile.
    The file FRMTDUMP.MSG contains the error messages for the Dump Formatter Facility.

    Dump Formatter Facility Profile

    You can tailor the Dump Formatter Facility output for different printers and different co-processor adapter dumps by setting variables in the Dump Formatter Facility profile (FRMTDUMP.PRO). You can use an ASCII text editor to change the profile. Before the Dump Formatter Facility generates SYSINFOn.PRT or MEMORYn.PRT, it attempts to locate FRMTDUMP.PRO. It examines the following directories in this order:

    If the Dump Formatter Facility (FRMTDUMP.EXE) is renamed in DOS Version 3.3 or higher, the filename of the profile must be changed to the same name. For example, changing the executable module name to "FORMDUMP.EXE" would cause the Dump Formatter Facility to look for the profile in "FORMDUMP.PRO".

    If the profile cannot be found, the default parameters are used. The default printer-specific parameters are for the IBM Graphics Printer.

    The following conventions apply to profile parameters:


    Profile Parameters

    Following is a list of the Dump Formatter Facility profile parameters:

    BOXCHARS
    - Printer codes for box characters.

    You can also specify the printer codes for generating box characters in the output files. Add the following line to the profile to set these parameters:

    
         BOXCHARS  = nn [,] nn [,] nn [,] nn [,] nn [,] nn
    
                     [,] nn [,] nn [,] nn [,] nn [,] nn
    
    

    Each "nn" represents the ASCII character code of a box character. The 11 codes are assigned in the order listed in the following table. The printer codes for the IBM Graphics Printer are also listed in the table. If the codes are not set or if there is an error in the list of codes, they default to the box characters of the IBM Graphics Printer.

    
         Vertical Bar         Default value = B3h (179 decimal)
    
    
    
         Horizontal Bar       Default value = C4h (196 decimal)
    
    
    
         Upper-left corner    Default value = DAh (218 decimal)
    
    
    
         Upper-right corner   Default value = BFh (191 decimal)
    
    
    
         Lower-right corner   Default value = D9h (217 decimal)
    
    
    
         Lower-left corner    Default value = C0h (192 decimal)
    
    
    
         Horizontal line      Default value = C3h (195 decimal)
    
         stops on vertical
    
         line from right
    
    
    
         Horizontal line      Default value = B4h (180 decimal)
    
         stops on vertical
    
         line from left
    
    
    
         Vertical line        Default value = C2h (194 decimal)
    
         stops on horizontal
    
         line from bottom
    
    
    
         Vertical line        Default value = C1h (193 decimal)
    
         stops on horizontal
    
         line from top
    
    
    
         Horizontal-vertical  Default value = C5h (197 decimal)
    
         line cross
    
    

    FORM_FEED - Printer formfeed sequence.

    This is the printer sequence for generating a formfeed. To set this parameter, add the following line to the profile:

    
         FORM_FEED = NONE | nn[[,]nn]...
    
    
    A list of up to 16 ASCII character codes can be entered for the formfeed sequence. This allows the user to set the profile for whatever printer is being used. If more than 16 codes are specified, or if any code exceeds 255, the default value 0Ch (12 decimal) is used. 0Ch is the standard ASCII code for formfeed.

    Specifying FORM_FEED = NONE indicates that no formfeed character exists for the printer being used. Instead, blank lines are printed in place of the formfeed character to bring the printer to the top of the next page. The PAGE_LINES parameter tells the Dump Formatter Facility how many blank lines to print.

    LONG - Complete memory listings

    If the keyword LONG is included in the profile, every line of memory is displayed regardless of the contents of memory. Omitting the keyword LONG can make the memory file MEMORYn.PRT shorter because redundant lines of memory are not redisplayed.

    MEMLIST - Memory dumped by location

    This parameter affects the contents of MEMORYn.PRT, but not of SYSINFOn.PRT. It specifies which blocks of memory are to be included in the output.

    To set this parameter, add the following line to the profile:

    
         MEMLIST = [ ALL ] [ NONE ] [ (NN [,]
    
         [+]NN) [,] ] ...
    
    
    Specifying ALL means that all co-processor adapter memory locations will be displayed in MEMORYn.PRT. Specifying NONE means that none of co-processor adapter memory will be displayed in MEMORYn.PRT.

    Ranges of co-processor adapter memory can be specified in terms of paragraphs (16 bytes). Ranges can be either a lower and upper bound or a lower bound and a length. Specifying (NN1 NN2) gives memory contents from paragraphs NN1 to NN2, inclusive. NN1 and NN2 specify paragraph boundaries and are numbers with the same range as described earlier. Either can be the smaller number, or they do not need to be ordered.

    Specifying (NN1 +NN2) gives memory contents starting at paragraph NN1 and continuing for NN2 paragraphs. For example,

    
         MEMLIST = (1000h, +20h)
    
    
    designates a total of 20h consecutive paragraphs, starting at paragraph 1000h (start address = 1000:0000).

    Some examples of the MEMLIST line follow:

    
         MEMLIST = ALL
    
    
    gives the contents of all installed co-processor adapter memory.
    
         MEMLIST = (1000h, 1FFFh) (3000h, 3FFFh)
    
    
    gives the memory contents of memory addresses 1000:000 through 1FFF:000F; also gives memory addresses 3000:0000 through 3FFF:000F.

    Note: Memory addresses 2000:0000 through 2FFF:000F are not generated.

    
         MEMLIST = (1000h, +1000h) (3000h, +1000h)
    
    
    gives the same results as the previous example.

    The default value for MEMLIST is NONE. The keywords ALL or NONE override parameters to the left of them. If conflicting keywords are found, the last (right-most) one overrides the others.

    PAGE_LINES - The Number of lines per page

    If a formfeed code is not available on your printer, this allows the Dump Formatter Facility to compute how many blank lines to generate.

    To set this parameter, add the following line to the profile:

    
         PAGE_LINES = nn
    
    
    The default value is 66 lines per page.

    POSTSTRING - Printer postfix sequence

    This sequence comes last in the MEMORYn.PRT and SYSINFOn.PRT files. Use it to return the printer to a desired state (for example, 80 character-per-line mode and 8 lines per inch).

    To set this parameter, add the following line to the profile:

    
         POSTSTRING = NONE | [nn[,]...]
    
    
    Specifying NONE results in no string being generated at the end of MEMORYn.PRT or SYSINFOn.PRT.

    The length of this string cannot exceed 256 bytes. If more than 256 integers are entered, or if any integer exceeds a value of 255, the default sequence of POSTSTRING is used.

    The default sequence is as follows:

    
         POSTSTRING = 12h
    
    
    This character sequence stops compressed character mode printing on the IBM Graphics Printer.

    PRESTRING - Printer prefix sequence

    This is the sequence that comes first in the MEMORYn.PRT and SYSINFOn.PRT files. Use it to force the printer into a desired state.

    To set this parameter, add the following line to the profile:

    
         PRESTRING = NONE | [ nn [,] ...]
    
    
    Specifying NONE results in no string being presented at the start of MEMORYn.PRT or SYSINFOn.PRT. The file then begins with formatted output, instead of printer-specific information.

    The length of this string cannot exceed 256 bytes; that is, no more than 256 integers can be presented on the line in FRMTDUMP.PRO. If more than 256 integers are presented, or if any integer exceeds a value of 255, the default sequence of PRESTRING is used.

    The Dump Formatter Facility defaults to the following:

    
         PRESTRING = 18h, 0Fh, 1Bh, 41h, 12, 1Bh, 32h,
    
                     1Bh, 36h, 1Bh, 39h, 1Bh, 43h, 66, 1Bh,
    
                     46h, 1Bh, 48h, 1Bh, 54h, 1Bh, 55h, 0
    
    
    This character sequence is for the IBM Graphics Printer and performs the following in this order:
    1. Clears the printer buffer
    2. Shifts the printer to compressed character mode (132 characters per line)
    3. Sets line spacing to six lines per inch
    4. Selects character set 2 on the IBM Graphics Printer
    5. Cancels any ignore paper end command
    6. Sets the page length to 66 lines per page
    7. Turns off printing in emphasized mode
    8. Turns off printing in double strike mode
    9. Turns off printing in superscript mode or subscript mode
    10. Sets the printer for bidirectional printing.
    Printer codes are explained in depth in the user's printer manual.

    PRINT_LINES - The Number of lines to print per page

    This parameter allows you to set the actual number of lines you want printed on a page. This parameter applies to SYSINFOn.PRT and MEMORYn.PRT. It cannot exceed the value of the PAGE_LINES parameter.

    To set this parameter, add the following line to the profile:

    
         PRINT_LINES = nn
    
    
    The default value is 60 lines per page.

    REPCHARSET - Representable character set

    Use this parameter to control characters.

    Characters are entered as a series of ASCII character code ranges or individual ASCII character codes. ASCII character code ranges are represented as two integers separated by a comma or a space, inside parentheses. All the characters within the range, including the lower and upper bounds, are added to the representable character set. Integers represent individual ASCII character codes.

    To set this parameter, add the following line to the profile:

    
         REPCHARSET = [(nn[,]nn) | nn[,]...]
    
    
    For example, a representable character set of 30 and the range 32 through 255 might be entered as follows:
    
         REPCHARSET = 30,(32,255)
    
    
    The period (.) cannot be removed from the set, even if it is omitted from the REPCHARSET parameter.

    TASKLIST - Task memory dumped

    This parameter affects only the contents of MEMORYn.PRT. It specifies a list of the tasks to be included in the output. If a task is included in the list, all of its memory is stored in formatted form in MEMORYn.PRT.

    To set this parameter, add the following line to the profile:

    
         TASKLIST = [ ALL ] [NONE ] [[-|+] nn ] [,] ...
    
    
    where nn is a task number.

    Specifying ALL adds all tasks and their associated memory to MEMORYn.PRT. Specifying NONE subtracts all task-related output from MEMORYn.PRT. The list of tasks to be included may be modified by specifying task numbers individually. A minus sign (-) in front of a task number removes it from the list of tasks being printed. A plus sign (+) in front of a task number adds it to the list of tasks being printed.

    Note: If a task number does not have a "+" or a "-" preceding it, "+" is assumed.

    Some examples of the TASKLIST line follow. The first example shows how to display all tasks except task 210.

    
         TASKLIST = ALL -210
    
    
    The second example shows how to display tasks 15h and 16h.
    
         TASKLIST = 15h 16h
    
    
    The default setting for TASKLIST is NONE.

    TITLE - Title for formatted output

    This parameter assigns a title to the Dump Formatter Facility output files. This title is printed at the top of each page in the MEMORYn.PRT and SYSINFOn.PRT files.

    To set this parameter, add the following line to the profile:

    
         TITLE = title_string
    
    
    The title string ends with a carriage return; that is, it must fit on a single line.

    TITLE has the character string "Untitled" as its default.

    USER_SEG - User-Selected Segment

    This parameter sets a special field indicating memory addresses with an offset from a user-selected segment.

    An address falling in the 64KB block of memory starting at this selected segment appears in the form segment:offset. The offset is from the beginning of the user-selected segment. Memory addresses outside the 64KB block are not displayed since different segment values are required to represent these addresses.

    To set this parameter, add the following line to the profile:

    
         USER_SEG = NN
    
    
    The default for this parameter is segment 0044h, which is the start of the co-processor adapter Interface Block (IB).

    Supplied Profile

    The following profile is supplied under filename FRMTDUMP.PRO. This profile contains default values (the values are assumed if FRMTDUMP.PRO cannot be found). The profile need not be present for the Dump Formatter Facility to work.

    Note: Printer-specific parameters are for the IBM Graphics Printer.

    Supplied FRMTDUMP.PRO profile.

    
    BOXCHARS = B3H,C4H,DAH,BFH,D9H,C0H,C3H,B4H,
    
               C2H,C1H,C5H
    
    FORM_FEED = 0CH
    
    MEMLIST = NONE
    
    PAGE_LINES = 66
    
    POSTSTRING =  12H
    
    PRESTRING = 18H,0FH,1BH,41H,12,1BH,32H,1BH,
    
                36H,1BH,39H,1BH,43H,66,1BH,
    
                46H,1BH,48H,1BH,54H,1BH,55H,0
    
    PRINT_LINES= 60
    
    REPCHARSET =  (32, 255)
    
    TASKLIST =  NONE
    
    TITLE = Untitled
    
    USER_SEG = 44H
    
    

    Appendix A. Message List

    This appendix contains messages you may see while using the following:


    Interrupt Handler Messages

    ICAINTH.COM will search for ICAINTH.MSG in the current directory, the directory from which ICAINTH.COM was loaded, and the root directory. If ICAINTH.MSG is not found in these directories, ICAINTH.COM prints an informational message and continues operation, defaulting to internal English messages.

    The format of an Interrupt Handler message is:

    
      ICAINTnnnt ** MESSAGE TEXT
    
    
    
      Where:  nnn = Assigned message number
    
                t = Message type where:
    
                    I = Information
    
                    E = Fatal error
    
    
    When the Interrupt Handler (ICAINTH.COM) is invoked from a system unit program via the DOS function call to execute a program, the parameter "DOS ERRORLEVEL" is set equal to the appropriate error number listed in the following paragraphs. You may then examine the error code and perform your own error handling. In some messages, a DOS code is displayed. This is the AX error code value returned from DOS.

    ICAINT000I ** ICAINTH IS INSTALLED AND RUNNING. **

    Explanation: This message indicates that the interrupt handler has successfully completed the initialization phase and is installed.

    Action: No action is required.

    ICAINT001E ** FILE OPEN ERROR.** DOS CODE = nnnn FILE = xxxxxxx.xxx

    Explanation: Indicates that either the ICAINTH.MSG or ICAPARM.PRM file cannot be opened.

    Action: The four-digit DOS CODE should be cross-referenced via the DOS Technical Reference.

    ICAINT002E ** FILE READ ERROR. ** DOS CODE = nnnn FILE = xxxxxxxx.xxx

    Explanation: Indicates that an error occurred while reading the ICAINTH.MSG or ICAPARM.PRM file.

    Action: The four-digit DOS CODE should be cross-referenced via the DOS Technical Reference.

    ICAINT003E ** FILE CLOSE ERROR. ** DOS CODE = nnnn FILE = xxxxxxxx.xxx

    Explanation: Indicates that the ICAINTH.MSG. or ICAPARM.PRM file cannot be closed.

    Action: The four-digit DOS CODE should be cross-referenced via the DOS Technical Reference.

    ICAINT004I ** NOT ALL RECORDS READ. ** FILE = xxxxxxxx.xxx

    Explanation: Indicates that either the specified file is too large to fit into local storage or it contains an insufficient number of records. This file is either the message file ICAINTH.MSG or the parameters file ICAPARM.PRM.

    Action: This message is for your information only. Installation of the Interrupt Handler will continue. You may wish to replace or correct the specified file.

    ICAINT005I ** INTERRUPT LEVEL NOT FOUND -- CARD IGNORED ** BASE I/O ADDR = xxxxx

    Explanation: Indicates that an interrupt level indicated by the base I/O address switch settings cannot be read from one of the installed co-processor adapters or the co-processor adapter itself is not functional. After this message is displayed, ICAINTH.COM should continue to install. A user program can inspect the internal parameter table to determine the installation error. This message may take up to 20 seconds to display.

    Action: This message is for your information only. Installation of the Interrupt Handler will continue. You may wish, however, to check the jumpers on the co-processor adapter. Valid jumper settings for the various interrupt levels can be found in the co-processor adapter's Guide to Operations document. It is also possible that the co-processor adapter's shared memory window has been mistakenly located in the same region as a DOS 5.0 Upper Memory Block (UMB). Observe the messages displayed when emm386.exe installs.

    ICAINT006I ** INVALID INTERRUPT LEVEL. ** LEVEL = xxxx

    Explanation: Indicates that the interrupt level read from the co-processor adapter is invalid.

    Action: This message is for your information only. Installation of the Interrupt Handler will continue. You may choose to reset the jumpers on the co-processor adapter to a valid interrupt level. Refer to the co-processor adapter's Guide to Operations document for information on valid interrupt levels.

    ICAINT007E ** INVALID ICAPARM.PRM ENTRY. **

    Explanation: Indicates that one or more of the ICAPARM.PRM entries is invalid.

    Action: Examine the ICAPARM.PRM file to ensure that 1) all entries are preceded by #; 2) that the last entry is terminated with a $, and all other entries are terminated with a ; and 3) that all parameters are within their legal size limitations.

    ICAINT008E ** INVALID CHARACTER IN ICAPARM.PRM. ** CHAR = x

    Explanation: Indicates that one or more characters in an ICAPARM.PRM entry is invalid. Valid entries are all hexadecimal digits in ASCII format.

    Action: Check the ICAPARM.PRM file to ensure that all characters are valid hexadecimal numeric entries.

    ICAINT009E ** INVALID FILE FORMAT-EXTRA RECORDS IGNORED.** FILE = ICAPARM.PRM

    Explanation: Indicates that the ICAPARM.PRM file contains too many records. Sixteen co-processor adapters are supported for one system unit; therefore, only 16 ICAPARM.PRM records are allowed.

    Action: Correct the ICAPARM.PRM file by deleting unnecessary records.

    ICAINT010I ** CONFLICTING POS/ICAPARM.PRM DATA; POS DATA ASSUMED. **

    ICAINT010I ** LOGICAL CARD=nn

    Explanation: Indicates that the Interrupt Handler has found conflicting co-processor adapter SETUP configuration data and ICAPARM.PRM data; this is an information message. The Interrupt Handler will continue to install and assume the POS SETUP configuration information. The internal ICAPARM.PRM table will contain the POS SETUP configuration data.

    Action: Ensure that the ICAPARM.PRM file and the SETUP configuration data are compatible by modifying the ICAPARM.PRM file or reconfiguring the adapter, using the IBM Personal System/2 Reference Diskette Set Configuration procedures.

    ICAINT011E ** NO CO-PROCESSOR ADAPTERS INSTALLED. **

    Explanation: Indicates that the Interrupt Handler, after searching the slots in the system unit, found no co-processor adapters installed. The Interrupt Handler will not install.

    Action: Install a Realtime Interface Co-processor adapter in the system unit.

    ICAINT012I ** INVALID WINDOW SIZE--CARD IGNORED. ** BASE I/O ADDRESS = xxxx

    Explanation: Indicates that the co-processor adapter with base address xxxx has an invalid shared storage window size.

    Action: Change the co-processor adapter window size to 64KB or less.

    ICAINT013E ** INTERRUPT HANDLER ALREADY INSTALLED. **

    Explanation: Indicates that the interrupt handler was previously installed during an installation attempt.

    Action: Either reset other co-processor adapter via the ICARSET macro or re-boot the system and re-load the interrupt handler.

    ICAINT014E ** INVALID CHARACTER IN COMMAND LINE, REMAINING LINE IGNORED. ** CHAR='x'

    Explanation: Indicates that the interrupt handler, ICAINTH.COM, was passed characters that are not usable in an "ignore" context. The only acceptable characters are: 'I', 'i', '(', 0 through 9, A through F (upper or lower case), ',', and ')'.

    Action: Reinstall the interrupt handler in compliance with the criteria described in Appendix C concerning use of the ignore feature.

    ICAINT015E ** MISSING OPEN PARENTHESIS '(' AFTER IGNORE REQUEST. **

    Explanation: Indicates that the interrupt handler, ICAINTH.COM, was supplied an I or i signifying an intent to use the "ignore a co-processor adapter" feature, but the I or i was not followed by a left parenthesis.

    Action: Reinstall the interrupt handler in compliance with the criteria described in Appendix C concerning use of the ignore feature.

    ICAINT016E ** ENTRY FOR IGNORED CARD FOUND IN ICAPARM FILE. CARD NOT IGNORED. ** BASE I/O ADDRESS = xxxx

    Explanation: Indicates that the user is requesting the interrupt handler, ICAINTH.COM, to perform mutually exclusive options that cannot occur simultaneously.

    Action: The user must decide whether to ignore the co-processor adapter card or include it. A card appearing in the ICAPARM.PRM file will not be ignored. If it is desired to ignore the card, the card's entry must be removed from the ICAPARM.PRM file. Reinstall the interrupt handler in compliance with the criteria described in Appendix C concerning use of the ignore feature.

    ICAINT017I ** MISSING CLOSE PARENTHESIS ')' AFTER IGNORE REQUEST. **

    Explanation: Indicates that the user invoked the "ignore a co-processor adapter" feature but did not provide the close parenthesis to signify the end of the parameters. All specified cards will still be ignored.

    Action: At the next invocation of ICAINTH.COM, install the interrupt handler in compliance with the criteria described in Appendix C concerning use of the ignore feature.


    Application Loader Utility Messages

    ICALOAD.COM will search for ICALOAD.MSG in the current directory, the directory from which ICALOAD.COM was loaded, and the root directory. If ICALOAD.MSG is not found in these directories, ICALOAD.COM will print an informational message and continue operation, defaulting to internal English messages.

    The format of an Application Loader Utility message is:

    
      LODnnnt ** MESSAGE TEXT
    
    
    
      where:  nnn = Assigned message number
    
                t = Message type where:
    
                    I = Information
    
                    E = Fatal error
    
    
    When the Application Loader Utility (ICALOAD.COM) is invoked from another program via the DOS function call to execute a program, the parameter "DOS ERRORLEVEL" is set equal upon return to the appropriate error number listed in the following paragraphs. You may then examine the error code and perform your own error handling.

    LOD000I ** NORMAL TERMINATION. ** CARD/TASK LOADED = nnmm

    Explanation: This message indicates that the Application Loader Utility has successfully loaded the specified task. The nn is the co-processor adapter number where the task is loaded; the mm is the task number of the task loaded.

    Action: No action is required.

    L0D001E ** FILE OPEN ERROR. ** DOS CODE = nnnn FILE = xxxxxxxx.xxx

    Explanation: Indicates that the specified file cannot be opened. The FILE designation refers either to the ICALOAD.MSG message file or to the application task file being loaded.

    Action: The four-digit DOS CODE should be cross-referenced via the DOS Technical Reference.

    LOD002E ** FILE READ ERROR. ** DOS CODE = nnnn FILE = xxxxxxxx.xxx

    Explanation: Indicates that an error occurred while reading the specified file. The FILE designation refers to either the ICALOAD.MSG message file or the task being loaded.

    Action: The four-digit DOS CODE should be cross-referenced via the DOS Technical Reference.

    LOD003E ** FILE CLOSE ERROR. ** DOS CODE = nnnn FILE = xxxxxxxx.xxx

    Explanation: Indicates that the specified file cannot be closed. The FILE designation refers to either the ICALOAD.MSG message file or the applications task file being loaded.

    Action: The four-digit DOS CODE should be cross-referenced via the DOS Technical Reference.

    LOD004E ** INVALID MESSAGE FILE ** FILE = ICALOAD.MSG

    Explanation: Indicates that the ICALOAD.MSG message file is invalid.

    Action: Replace or correct the ICALOAD.MSG message file and invoke the Application Loader Utility again.

    LOD005E ** INVALID CHARACTER ON COMMAND LINE. ** CHAR = x

    Explanation: Indicates that an invalid character was encountered on the command line. Valid characters are 0-9 and A-F hexadecimal values.

    Action: Review the input parameters for an invalid alphabetic character and replace it with the correct value. Note that the value of CHAR is the first invalid character encountered. Review the command line carefully for any more invalid characters.

    LOD006E ** ICAINTH FOUND ERROR. ** ICAINTH CODE = xxyy

    Explanation: Indicates that a function call to the Interrupt Handler was not successful.

    Action: Examine the ICAINTH CODE and take appropriate action. The ICAINTH CODE is in the AX register, and may be interpreted as follows:

    
     xx = 01h = First byte of Interrupt Handler function code
    
     yy = Error code where:
    
          01h = Invalid co-processor adapter number
    
          02h = Invalid task number
    
          04h = Co-Processor adapter inactive but
    
                ICAPARM parameters exist.
    
    
    LOD007E ** INVALID TASK NUMBER. ** TASK NUMBER = nn

    Explanation: Indicates that the specified task number is invalid (greater than the MAXTASK value defined via ICAPARM.PRM file).

    Action: Either alter ICAPARM.PRM MAXTASK entry or re-invoke the Application Loader Utility with a valid task number.

    LOD008E ** SEVERE DEVICE ERROR. ** CARD = nn

    Explanation: Indicates that an interrupt was received from task number FEh.

    Action: Inspect the Realtime Control Microcode secondary status field. Information regarding handling of this type of asynchronous error handling may be found in the Asynchronous Error Handling section in the Realtime Interface Co-Processor Firmware Technical Reference.

    LOD009E ** TASK 0 ALREADY LOADED. ** STATUS = nn

    Explanation: Indicates that the task 0 control program is already loaded. Task number 0 is reserved for the co-processor adapter control program. This may be either the Realtime Control Microcode as supplied by IBM or your own custom control program. The STATUS indicator reports the value of the Realtime Control Microcode's Primary Status Byte in the Interface Block. For an explanation of the status field, refer to the Realtime Interface Co-Processor Firmware Technical Reference.

    Action: Either re-invoke the Application Loader Utility with the correct task number or issue a hardware reset command to the co-processor adapter to unload the task 0 control program.

    LOD010E ** TASK 0 INVALID STATUS. ** STATUS = nn

    Explanation: Indicates that the Realtime Control Microcode's (task 0 control program) error bit in the Primary Status Byte in the Interface Block has been overwritten.

    Action: Examine the secondary status field for further error details and then issue a hardware reset to the co-processor adapter to clear any error. First, determine the cause of how the "error" bit was modified. A hardware reset may be necessary to clear the co-processor adapter and reset all error conditions. For an explanation of the status field, refer to the Realtime Interface Co-Processor Firmware Technical Reference.

    LOD011E ** TASK 0 NOT LOADED AND INITIALIZED. ** STATUS = nn

    Explanation: Indicates that an attempt to load an applications task before the Realtime Control Microcode (task 0 control program) was loaded and initialized has occurred.

    Action: Load the Realtime Control Microcode (task 0 control program); then load the specified task. For an explanation of the status field, refer to the Realtime Interface Co-Processor Firmware Technical Reference.

    LOD012E ** TASK 0 FOUND ERROR. ** STATUS = nn

    Explanation: The Realtime Control Microcode (task 0 control program) found an error while performing the Request Task Load and Start Task commands. The STATUS field is the current value of the Realtime Control Microcode (task 0 control program) Primary Status Byte in the Interface Block.

    Action: The value of the Realtime Control Microcode's (task 0 control program) secondary status field should be examined. For an explanation of the status field, refer to the Realtime Interface Co-Processor Firmware Technical Reference.

    LOD013E ** TASK ERROR FLAG ON. ** STATUS = nn

    Explanation: Indicates that the specified task's "error" bit in its Primary Status Byte in the Interface Block is set to 1.

    Action: Debug the task or re-load the task (after unloading it). For an explanation of the status field, refer to the Realtime Interface Co-Processor Firmware Technical
    Reference
    .

    LOD014E ** TASK ALREADY LOADED. ** STATUS = nn

    Explanation: Indicates that the specified task is already loaded. The task's Primary Status Byte value in the Interface Block is displayed in the STATUS field.

    Action: Either unload the task and re-issue the "Load task" command or correct the specified task number on the command line.

    LOD015E ** INVALID TASK FORMAT. ** FILE = xxxxxxxx.xxx

    Explanation: Indicates that the specified file is not a valid .COM or .EXE task file. Note that the file extension characters must be "COM" or "EXE".

    Action: Examine the source code of the task or the file extension name and correct it.

    LOD016E ** TASK 0 OUTPUT BUFFER SIZE INVALID. ** STATUS = nn

    Explanation: Indicates that the Realtime Control Microcode's (task 0 control program) Buffer Control Block output buffer size has been overwritten and is invalid.

    Action: Examine the Realtime Control Microcode's Secondary Status Field for further error details and then issue a hardware reset to the co-processor adapter to clear any error. First, determine the cause of how the buffer control block was modified. A hardware reset may be necessary to clear the co-processor adapter and reset all error conditions.

    LOD017E ** COMMAND NOT ACCEPTED. ** STATUS = nn

    Explanation: Indicates that the Realtime Control Microcode's (task 0 control program) command has not been accepted. The Realtime Control Microcode code and/or data has been inadvertently modified.

    Action: Issue a hardware reset to the co-processor adapter and reload the Realtime Control Microcode (task 0 control program) and all application tasks on the co-processor adapter.

    LOD018E ** CANNOT START TASK -- TASK NOT LOADED. ** STATUS = nn

    Explanation: Indicates that the specified task was not correctly assigned the "loaded" state in its Primary Status Byte following the Load Task command. This signals that the task's code and/or data has been inadvertently modified.

    Action: Issue a hardware reset to the co-processor adapter and reload the Realtime Control Microcode (task 0 control program) and all application tasks.

    LOD019E ** FILE RELOCATION ERROR. ** DOS CODE = xxxx FILE =xxxxxxx.xxx STATUS = nn

    Explanation: Indicates that an error occurred while attempting to relocate the specified file from the system unit to the co-processor adapter card.

    Action: The four-digit DOS CODE should be cross-referenced via the DOS Technical Reference.

    LOD023E ** NO DEVICE RESPONSE. ** CARD = nn STATUS = nn

    Explanation: Indicates that the Application Loader Utility has not received an interrupt from the co-processor adapter in the allocated time, which is specified at approximately 5 seconds. This situation can be generated from a software error on the system unit side or from a co-processor adapter hardware error.

    Action: Examine the Realtime Control Microcode (task 0 control program) Primary Status Byte and determine whether or not the task is loaded and started. A valid status indicator is a status of "loaded and initialized," or not "busy," or "output buffer not busy." The diagnostics test can be used to identify hardware errors. If a software failure is indicated, isolate the problem and correct the software failure.

    LOD024E ** INVALID PC SELECT BYTE. ** PC SELECT = nn

    Explanation: Indicates that an invalid PC Select Byte in the Interface Block was found prior to issuing the Request to Load command. This signals that there was an error in some previous system unit<-->co-processor adapter communication or this area of storage was inadvertently overwritten.

    Action: First, isolate the error. Then, the recommended course of action to recover from the error is to issue a hardware reset to the co-processor adapter to clear the condition.

    LOD025E ** INTERRUPT HANDLER NOT RESIDENT. **

    Explanation: Indicates that the Interrupt Handler is not resident, and thus the Application Loader Utility cannot be executed.

    Action: Invoke the Interrupt Handler and re-issue the Load Task command to load the Realtime Control Microcode (task 0 control program).

    LOD026E ** INVALID TASK LENGTH. ** LENGTH = xxxx

    Explanation: Indicates that the load module length specified in the task header of the .COM file is greater than the actual file size. No part of the file is loaded.

    Action: Resolve the difference between the task header length and the file length of the load module and re-invoke the Application Loader Utility.

    LOD027E ** INVALID INTERRUPT HANDLER VERSION. **

    Explanation: Indicates that the version of the installed interrupt handler is not compatible with the ICALOAD.COM version. This condition occurs when ICAINTH.COM V1.0, V1.01, or V1.02 is installed and ICALOAD V1.04 is invoked.

    Action: Install ICAINTH V1.03 and re-invoke the Application Loader Utility.

    LOD028E ** DOS ERROR. ** DOS CODE = %nnnn

    Explanation: A call to DOS returned the error code nnnn displayed in the message.

    Action: The four-digit DOS CODE should be cross-referenced via the DOS Technical Reference.


    Online Dump Facility Messages

    Note: The format of an Online Dump Facility message is:

    
      ICADUMnnnt TEXT
    
    
    
      where:  nnn = Assigned message number
    
                t = Message type where:
    
                    I = Information
    
                    E = Error
    
    
    ICADUM000I RIC DUMP SUPPORT PROGRAM INSTALLED

    Explanation: Indicates that the Online Dump Facility (DUMP.COM) is now resident.

    (RIC is an abbreviation of the Realtime Interface Co-Processor and refers to all of the co-processor adapters.)

    Action: Request a dump of any installed co-processor adapter using the DUMP command.

    ICADUM001I DUMP.MSG MESSAGE FILE NOT FOUND OR INVALID

    Explanation: Indicates that a version of DOS lower than 3.0 is being used and DUMP.MSG is not in the current or root directory. This message also appears on units on where the "COUNTRY=" parameter in the CONFIG.SYS file is other than 001 when DOS is 3.0 or higher and DUMP.MSG is not in the current directory, the root directory, or the same directory as DUMP.COM.

    Action: Copy DUMP.MSG to the current or root directory.

    ICADUM0030E BAD PARAMETER(S) ENTERED. STATE OF RIC(S) NOT CHANGED

    Explanation: Indicates that an unrecognized parameter was typed after the "DUMP" directive on the DOS command line. No action concerning any co-processor adapter is taken by the Online Dump Facility; a list of commands appears.

    (RIC is an abbreviation of the Realtime Interface Co-Processor and refers to all of the co-processor adapters.)

    Action: Enter a correct DUMP command on the DOS command line.

    ICADUM037E INTERRUPT HANDLER NOT RESIDENT

    Explanation: Indicates that the interrupt handler has not yet been installed.

    Action: Install the interrupt handler

    DUMP DATA WILL NOT FIT ON FIXED DISK d! DUMP OF RIC nn RESTARTED AND SUSPENDED. TO RESUME DUMP, ENTER "DUMP" FROM DOS

    Explanation: Indicates that the hard disk does not have the free space available to contain the DUMP data. The nn indicates the co-processor adapter logical co-processor adapter number; the d is the drive character.

    (RIC is an abbreviation of the Realtime Interface Co-Processor and refers to all of the co-processor adapters.)

    Action: Provide more free space by erasing unnecessary files on your hard disk or by changing the dump output destination to a diskette device. Then enter "DUMP" at the DOS command line to restart the dump.

    DUMP REQUEST:RICnn. TYPE "CONT" TO RESUME

    Explanation: Indicates that a co-processor adapter has requested the user to perform a dump. The nn is the co-processor adapter logical number.

    (RIC is an abbreviation of the Realtime Interface Co-Processor and refers to all of the co-processor adapters.)

    Action: Type CONT to continue your application. Then dump the co-processor adapter requesting the dump, using the DUMP command.

    RIC nn NOT RESPONDING

    Explanation: Indicates that communication cannot be established with the co-processor adapter to perform a dump. This indicates that the co-processor adapter has its non-maskable interrupts (NMIs) disabled, its memory degated, or is in need of service. The nn is the co-processor adapter logical co-processor adapter number.

    (RIC is an abbreviation of the Realtime Interface Co-Processor and refers to all of the co-processor adapters.)

    Action: Determine if the co-processor adapter's NMIs are disabled or memory is degated.

    TOO MANY DISKETTES

    Explanation: Indicates the DUMP report output has filled the maximum 100 diskettes allowed and has not yet been completed.

    Action: Erase unnecessary files on your diskettes or use diskettes with more free space available. The dump is automatically restarted.

    
    ICADUM0431
    
    DISKETTE FULL!
    
    USE ANOTHER DISKETTE.
    
    
    Explanation: Indicates that you are trying to dump to a full diskette. This message also appears if you try to save the ICASYSn.DMP file on a diskette that does not have enough free space to contain it (this is unlikely because the cluster size on most diskettes and fixed disks is larger than the space needed to contain the ICASYSn.DMP file).

    Action: Use diskettes with more free space available.

    
    ICADUM044E DOS ERROR ENCOUNTERED: ff:eeee
    
    
    Explanation: Indicates that DUMP.COM has encountered an unexpected DOS error. The ff represents the DOS function number (a two-character hexadecimal number) in use when the error was encountered. The eeee represents the error code (a four-character hexadecimal number) returned from that DOS function.

    Action: No action; the dump is automatically restarted.

    
    ICADUM045E INVALID INTERRUPT HANDLER VERSION
    
    
    Explanation: Indicates that the installed Interrupt Handler is not compatible with the DUMP.COM version. This condition occurs when ICAINTH.COM V1.0, V1.01, or V1.02 is installed and DUMP V1.4 is invoked.

    Action: Install ICAINTH V1.03 and re-invoke the Dump Facility.


    Appendix B. DOS 5.0 Considerations

    This appendix provides (in a question and answer format) the items to consider when you are using DOS 5.0.

    QUESTION #1:

    How do I avoid conflicts between a Realtime Interface Co-Processor (ARTIC) adapter and expanded memory drivers, and how can I tell if a memory conflict has occurred?

    ANSWER:

    One possible symptom of a memory conflict is receiving the error message "Interrupt level not found--card ignored. ** Base I/O Addr=xxxx". Please note that there could be other reasons why this error might occur.

    The method that the DOS expanded memory drivers use to find a page frame to access expanded memory may conflict with the ARTIC adapter. Expanded memory is viewed by paging 16KB pages into a page frame in a similar fashion to the ARTIC adapter's shared storage window.

    When an expanded memory driver installs (during reboot when DOS installs device drivers), it searches the memory region A0000h-EFFFFh for a 16KB or 64KB page frame to use to access the expanded memory. The problem is that during device driver initialization, the ARTIC adapter memory has not been gated and is not visible on the system unit bus (it becomes visible later when the interrupt handler is installed). Because of this, the expanded memory driver may attempt to use the same memory region as the ARTIC adapter. This will cause the interrupt handler to fail when it gates the ARTIC memory during initialization. To avoid a memory conflict between an ARTIC adapter and an expanded memory driver:

    QUESTION #2:

    What do I need to do to enable a Realtime Interface Co-Processor (ARTIC) adapter to run with DOS 5.0 Upper Memory Block (UMB) support?

    ANSWER:

    If you want to enable the DOS UMB support in a system that contains an ARTIC adapter, you must add an additional parameter to the EMM386 expanded memory driver in CONFIG.SYS to avoid any conflict between the DOS upper memory blocks and the ARTIC adapter. The ARTIC adapter family includes the following adapters:

    To determine the proper parameters for CONFIG.SYS, follow these steps:

    1. Determine the type of ARTIC adapter installed:

      If your system contains any of the following adapters, proceed with step 2.

      If your system contains any of the following adapters, proceed with step 3.
    2. Determine the ARTIC shared storage window location in a Micro Channel(4) system:

      Boot your system reference diskette, select Set Configuration, and then select View Configuration. For each of the ARTIC adapters installed in the system, make a note of the Shared Storage Window Location and Size configured for each adapter. These numbers should look something like any of the following sample entries:

      The first pair of hexadecimal numbers in these entries are the physical location of the ARTIC shared storage window. This range of memory must be excluded from DOS upper memory block usage. These physical addresses must be converted to segment addresses to be used as parameters to the EMM386 driver in CONFIG.SYS. To convert these addresses, simply drop the last digit and the H from each address. With the preceding examples, the converted addresses are as follows.

      Skip to step 4 with your converted values.

    3. Determine the ARTIC shared storage window location in a non-Micro Channel system:

      In non-Micro Channel systems, the ARTIC shared storage window location is controlled via the ICAPARM.PRM file used by the interrupt handler, ICAINTH.COM. To determine the shared storage window location, find the ICAPARM.PRM file currently in use by the interrupt handler and display it. There should be one entry in the file for each ARTIC adapter installed. A sample ICAPARM.PRM file for a system with two ARTIC adapters is as follows:

      Make note of the third numeric value in each entry and use the following table to convert to the proper value for CONFIG.SYS.
      
      ICAPARM.PRM   CONFIG.SYS      ICAPARM.PRM   CONFIG.SYS
      
         Value        Value            Value        Value
      
      -----------   ----------      -----------   ----------
      
          50        A000-A1FF           68        D000-D1FF
      
          51        A200-A3FF           69        D200-D3FF
      
          52        A400-A5FF           6A        D400-D5FF
      
          53        A600-A7FF           6B        D600-D7FF
      
          54        A800-A9FF           6C        D800-D9FF
      
          55        AA00-ABFF           6D        DA00-DBFF
      
          56        AC00-ADFF           6E        DC00-DDFF
      
          57        AE00-AFFF           6F        DE00-DFFF
      
          58        B000-B1FF           70        E000-E1FF
      
          59        B200-B3FF           71        E200-E3FF
      
          5A        B400-B5FF           72        E400-E5FF
      
          5B        B600-B7FF           73        E600-E7FF
      
          5C        B800-B9FF           74        E800-E9FF
      
          5D        BA00-BBFF           75        EA00-EBFF
      
          5E        BC00-BDFF           76        EC00-EDFF
      
          5F        BE00-BFFF           77        EE00-EFFF
      
          60        C000-C1FF           78        F000-F1FF
      
          61        C200-C3FF           79        F200-F3FF
      
          62        C400-C5FF           7A        F400-F5FF
      
          63        C600-C7FF           7B        F600-F7FF
      
          64        C800-C9FF           7C        F800-F9FF
      
          65        CA00-CBFF           7D        FA00-FBFF
      
          66        CC00-CDFF           7E        FC00-FDFF
      
          67        CE00-CFFF           7F        FE00-FFFF
      
      
      For the preceding sample parameter file, the converted values for CONFIG.SYS would be C000-C1FF and C200-C3FF.

      Proceed to step 4 with your converted values.

    4. Update CONFIG.SYS:

      The values for each ARTIC adapter obtained in steps 1 through 3 now need to be added to the entry for the EMM386.SYS driver in CONFIG.SYS. This is done by adding the values for each ARTIC adapter to the line that installs EMM386.SYS; the values are preceded by the characters "X=".

      For example, if the current EMM386.SYS entry is

      and you have a single ARTIC adapter with a window at C000-C1FF, the updated entry would be as follows:

      As another example, if the current EMM386.SYS entry is

      and you have two ARTIC adapters with windows at D400-D7FF and C200-C3FF, the updated entry would be as follows:

      Refer to the DOS 5.0 manual for additional information on the parameters to the EMM386.SYS driver.

      Note that if the location of the ARTIC shared storage window is ever reconfigured, these steps must be repeated to determine the proper entries in CONFIG.SYS.

    5. Optimize memory usage:

      Note:

      The following are advanced optimization steps that require an in-depth understanding of memory usage.
      The steps you have just completed enable the ARTIC adapter and the DOS upper memory block support to coexist. You may wish to optimize the memory configuration in your system to take full advantage of available memory. By reconfiguring the location of the ARTIC shared storage window (and/or other adapters), you may be able to increase the amount of memory available in upper memory blocks or increase the contiguous size of individual upper memory blocks.

      The goal of rearranging the memory allocation, is to provide as large a contiguous space as possible for the usage of the upper memory block support. This requires that all shared memory adapters be configured such that the memory address they use is contiguous and at the low or high end of the available address space between 640KB and 1MB. The system memory, adapter shared memory, ROM BIOS and DOS UMB address space cannot overlap -- each must be assigned to unique address areas. Typically, only the shared memory assignments can be changed and the DOS UMB support will take whatever area is left.

      For example, if there are two ARTIC adapters in a system configured with shared storage windows at C800-C9FF and D000-D1FF, the UMB memory is broken in pieces. By moving the ARTIC shared storage windows to DC00-DDFF and DE00-DFFF, a larger contiguous upper memory block can be allocated and used by DOS.

      Note that the DOS MEM command can be used to display the upper memory blocks and assist in determining the optimum configuration.

    QUESTION #3:

    Is the Realtime Interface Co-Processor DOS Support compatible with the DOS 5.0 UMB support?

    ANSWER:

    The latest DOS Support components are supported in a DOS 5.0 UMB.


    Appendix C. The Ignore Feature and OS/2 2.0

    The DOS Support interrupt handler, icainth.com, now incorporates a feature that provides the capability to ignore certain Realtime Interface Co-Processor (ARTIC) cards.

    The latest DOS Support components are supported in OS/2 2.0 multiple virtual DOS machines (MVDM), with the following restriction. The interrupt handler (ICAINTH) can be installed in an MVDM if no Portmaster Adapter/A adapters are installed in the system. If a Portmaster is installed, ICAINTH can still be installed, but the Realtime Control Microcode must be loaded with the "no peer" option. If a Portmaster is installed and an attempt is made to load the Realtime Control Microcode without the "no peer" option, busmaster operations will fail and the Realtime Control Microcode will not load.

    The Realtime Control Microcode, icarcm.com, can be loaded with the "no peer" option by passing a load parameter of '1' to the Realtime Control Microcode. An example of this follows:

    Additional information about the Realtime Control Microcode's "no peer" option is in the Realtime Interface Co-Processor Firmware Technical Reference.

    The advantage of the "ignore a co-processor adapter" feature is that icainth.com no longer has to own every ARTIC card that is installed. Multiple invocations of icainth.com, which are now possible in the MVDM modes of OS/2 2.0, can separately own distinct ARTIC cards. This can be done by telling each instance of the interrupt handler to ignore the adapters that it is not accessing.

    The invocation of the ignore feature is accomplished by typing the following on the same command line: icainth, followed by either an upper or lower case 'I', then a left parenthesis '('. Follow that with the physical card number of the card you wish to ignore.

    Note:

    The ARTIC at Base I/O address 2A0 has a physical card number of 0.
    If you wish to ignore more than one ARTIC card, separate the physical card numbers by either commas or spaces. When all physical card numbers are entered, conclude the command line with a right parenthesis ')'.

    For example, if you wanted to ignore physical cards 0 and 2, but not 1, you would type the following:

    To ignore physical cards 4 and B: Because the ignore feature distinguishes the ARTICs by physical card numbers, and the ARTICs cannot be physically numbered higher than F, the only valid entries for the ignore feature are 0 through 9 and A through F (upper or lower case). Any other entries passed to icainth will be flagged as errors and not used.

    Note:

    An ARTIC card that appears in the ICAPARM.PRM file will not be ignored. Therefore, if the card you wish to ignore appears in your ICAPARM.PRM file, the card's entry must be removed from that file.

    Footnotes:
    
    (1)   IBM is a registered trademark of International Business
    
          Machines Corporation in the U.S.A. and other countries.
    
    
    
    (2)   Macro Assembler/2 and C/2 are trademarks of
    
          International Business Machines Corporation
    
          in the U.S.A. and other countries.
    
    
    
    (3)   For Multiport/2 and X.25 users: the steps for
    
          indicating to DOS the location of the ARTIC shared
    
          storage window are not necessary for the Multiport/2
    
          or X.25 adapters.  DOS 5.0 automatically detects the
    
          Multiport/2 and X.25 window location.
    
    
    
    (4)   Micro Channel is a trademark of International
    
          Business Machines Corporation in the U.S.A. and
    
          other countries.
    
    
     

    Last modified: March 25, 1999