Version 1.04 (June 1996)
Chapter 1. General Product Description
Chapter 2. Installing the Software
Chapter 3. Parameter File Description
Chapter 4. Interrupt Handler/Device Driver
Chapter 5. Application Loader Utility
Chapter 6. Preparing/Installing Application Tasks
Chapter 7. Assembler Language Macro Modules
Chapter 8. Function Calls to the Interrupt Handler
Chapter 9. Online Dump Facility
Chapter 10. Dump Formatter Facility
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.
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:
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.
The Realtime Interface Co-Processor DOS Support User's Guide is organized as follows:
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 books in the Realtime Interface Co-Processor library include:
This guide provides instructions for installing the Realtime Interface Co-Processor and Realtime Interface Co-Processor Multiport and describes the features of each. It also describes problem determination procedures.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.
This manual provides both hardware and software introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and anyone who needs to understand the use and operation of the co-processor adapter.
This guide provides instructions for installing the hardware necessary to use the Realtime Interface Co-Processor Multiport/2 and describes problem determination procedures.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.
This manual provides both hardware and software introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and anyone who needs to understand the use and operation of the co-processor adapter.
This guide provides instructions for installing the hardware necessary to use the X.25 Interface Co-Processor/2 and describes problem determination procedures.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are presented to complete repair.
This manual provides both hardware and software introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and anyone who needs to understand the use and operation of this co-processor adapter.
This guide provides instructions for installing the Realtime Interface Co-Processor Portmaster Adapter/A, describes the product features, and provides problem determination procedures.
This manual provides both introductory and reference information, and is intended for hardware designers who need to understand the design and operating characteristics of this co-processor adapter. (See also the Realtime Interface Co-Processor Firmware Technical Reference.)
This manual provides detailed information on the programmer interfaces to the Realtime Control Microcode for the family of Realtime Interface Co-Processor adapters. It is intended for hardware and software designers who need to understand the design and operating characteristics of the control microcode.
This manual is used in conjunction with either the Eight Port RS-232 Interface Board/A Hardware Maintenance Library or the Eight Port RS-422 Interface Board/A Hardware Maintenance Library. This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are also provided.
This kit is required for maintenance of the Realtime Interface Co-Processor Portmaster Adapter/A or the Realtime Interface Co-Processor Multiport Adapter, Model 2 when an RS-232 Interface Board/A is installed. This kit contains a card wrap connector, cable wrap connector(s), and instructions, and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A, Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Maintenance Library.
This kit is required for maintenance of the Realtime Interface Co-Processor Portmaster Adapter/A or the Realtime Interface Co-Processor Multiport Adapter, Model 2 when an RS-422 Interface Board/A is installed. This kit contains a card wrap connector, cable wrap connector(s), and instructions, and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A, Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Maintenance Library.
This guide provides instructions for installing the Realtime Interface Co-Processor Multiport Adapter, Model 2, describes the product features, and provides problem determination procedures.
This manual provides both introductory and reference information, and is intended for hardware designers who need to understand the design and operating characteristics of this co-processor adapter. (See also the Realtime Interface Co-Processor Firmware Technical Reference.)
This manual provides detailed information on the programmer interfaces to the Realtime Control Microcode for the family of Realtime Interface Co-Processor adapters. It is intended for hardware and software designers who need to understand the design and operating characteristics of the control microcode.
This manual is used in conjunction with either the Eight Port RS-232 Interface Board/A Hardware Maintenance Library or the Eight Port RS-422 Interface Board/A Hardware Maintenance Library. This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It provides step-by-step instructions for problem isolation to aid in identifying a FRU. Removal and replacement procedures are also provided.
This kit is required for maintenance of the Realtime Interface Co-Processor Multiport Adapter, Model 2 or the Realtime Interface Co-Processor Portmaster Adapter/A when an RS-232 Interface Board/A is installed. This kit contains a card wrap connector, cable wrap connector(s), and instructions, and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A, Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Maintenance Library.
This kit is required for maintenance of the Realtime Interface Co-Processor Multiport Adapter, Model 2 or the Realtime Interface Co-Processor Portmaster Adapter/A when an RS-422 Interface Board/A is installed. This kit contains a card wrap connector, cable wrap connector(s), and instructions, and is used in conjunction with IBM Realtime Interface Co-Processor Portmaster Adapter/A, Realtime Interface Co-Processor Multiport Adapter, Model 2 Hardware Maintenance Library.
This guide provides instructions for installing the hardware necessary to use the ISDN Interface Co-Processor/2.
This manual provides procedures for isolating and repairing any failure of a field replaceable unit (FRU). It also provides removal and replacement procedures.
This manual provides both hardware and software introductory and reference information, and is intended for hardware and software designers, programmers, engineers, and anyone who needs to understand the use and operation of this co-processor adapter.
This guide is available only as part of the Realtime Interface Co-Processor C Language Support product. The guide provides information on using the C Language Support product, a productivity aid that allows programmers to develop code for the system unit or the co-processor adapter in the C programming language. It explains the C interface routines and the method of compiling and linking C tasks for the co-processor adapter.
This guide explains the installation and loading of software, event management services, intertask communications services, asynchronous and synchronous communications support; provides information necessary for Realtime Interface Co-Processor Extended Services to interface with co-processor adapters; and describes the functions and capabilities of Realtime Interface Co-Processor Extended Services.
You may need to use one or more of the following publications for reference with this guide:
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.
The following are minimum hardware requirements for the Realtime Interface Co-Processor DOS Support Version 1.04 product:
The following are minimum software requirements for the Realtime Interface Co-Processor DOS Support Version 1.04 product:
This chapter provides a guide for installing the software for the IBM co-processor adapter.
Before proceeding with the software installation, you need the following:
The installation procedures include the following:
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:
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:
Note:
Records that do not begin with a # are treated as comments and are valid.
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 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".
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:
To install the DOS Device Driver, do the following:
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.
Sample CONFIG.SYS entries follow:
DEVICE = ICAINTH.SYS 0 a
DEVICE = C:\XYZ\ICAINTH.SYS F
The main functions of the interrupt handler, ICAINTH.COM, are to:
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.
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.
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".
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".)
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".
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:
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:
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.
+---------+-----------------------+--------+------------------+ | | | 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 ; | +---------+-----------------------+--------+------------------+
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.
-----------------------------------------------------------
Length One character # (number sign)
-----------------------------------------------------------
Range #
-----------------------------------------------------------
Description The first character of each record must
be a #.
-----------------------------------------------------------
-----------------------------------------------------------
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.
-----------------------------------------------------------
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.
-----------------------------------------------------------
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.
-----------------------------------------------------------
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.
-----------------------------------------------------------
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.
-----------------------------------------------------------
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.
-----------------------------------------------------------
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.
-----------------------------------------------------------
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.
-----------------------------------------------------------
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.
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
-----------------------------------------------------------
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.
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
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:
The interrupt handler consists of three files:
The device driver is required in the following co-processor adapter environments:
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:
To install the DOS Device Driver:
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
Sample CONFIG.SYS entries follow:
DEVICE = ICAINTH.SYS 0 a
DEVICE = C:\XYZ\ICAINTH.SYS F
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.
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.
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 DOS 5.0 and OS/2 2.0 considerations, see Appendixes B and C.
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:
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:
Realtime Control Microcode Version 2.01 or later allows a user to disable peer services by specifying an optional parameter of 1 (one) when invoking the application loader utility. For example:
> ICALOAD 0 ICARCM.COM 0 ( 1
Realtime Control Microcode Version 2.02 or later allows a user to specify an optional parameter of 2 (two) to enable a 32KB portion of random access memory specifically for EIB use. This parameter may be specified when invoking the application loader utility. For example:
> ICALOAD 0 ICARCM.COM 0 ( 2
Parameters 1 and 2 may be used at the same time by separating the parameters with a blank. For example: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.These parameters may be passed together and in any order; that is, they are not mutually exclusive and not order dependent.
> ICALOAD 0 ICARCM.COM 0 ( 1 2
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.
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
Note:
RCM V1.3 or greater must be installed to use this option.
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.
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
This chapter provides overview information on preparing and installing 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.
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.
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:
Reference: IBM Disk Operating System (DOS) Technical Reference manual, EXE2BIN Command.EXE2BIN [d:][path][filename] [d:][path][filename]
Error Reference: IBM Disk Operating System (DOS) Technical Reference manual.
The following example takes the task source file mytask.asm and creates an executable task file mytask.com:
>MASM mytask; >LINK mytask,,, mylibIf 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.
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.
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.
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.
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.
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:
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:
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:NOTHINGThe following is an acceptable COM ASSUME statement:
ASSUME CS:COMGROUP,DS:COMGROUPNote 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 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.
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.
A description of each of the Assembler Language Modules is provided in the remainder of this chapter.
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.
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.
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.
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
-----------------------------------------------------------
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
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
02h Invalid task number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
0Ah No resident interrupt handler
0Bh Invalid interrupt handler
version
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
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.
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
----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
02h Invalid task number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
----------------------------------------------------------- CX Meaning ----------------------------------------------------------- 1FFFh 8KB shared storage window 3FFFh 16KB shared storage window 7FFFh 32KB shared storage window FFFFh 64KB shared storage windowErrors
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
----------------------------------------------------------- CX Meaning ----------------------------------------------------------- 1FFFh 8KB shared storage window 3FFFh 16KB shared storage window 7FFFh 32KB shared storage window FFFFh 64KB shared storage windowErrors
-----------------------------------------------------------
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
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
----------------------------------------------------------- CX Meaning ----------------------------------------------------------- 1FFFh 8KB shared storage window 3FFFh 16KB shared storage window 7FFFh 32KB shared storage window FFFFh 64KB shared storage windowErrors
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
0Ch Address out of range
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
0Eh Unknown peer handle
0Fh Invalid command
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:
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
0Dh Peer Handle not available
0Fh Invalid command
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 blockExit Parameters
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
09h Command not accepted
0Fh Invalid command
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
- ICAINTH.COM
- ICAVSET macro.
1 if no interrupt occurred
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
02h Invalid task number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
05h Page Selector already
reserved
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
None.
Errors
None.
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
05h Page Selector already
reserved
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
----------------------------------------------------------- CX Meaning ----------------------------------------------------------- 1FFFh 8KB shared storage window 3FFFh 16KB shared storage window 7FFFh 32KB shared storage window FFFFh 64KB shared storage windowErrors
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
02h Invalid task number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
02h Invalid task number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
MOV AH,0 ; select co-processor
; adapter # 0
ICAVRET ; return all 254 flags
MOV AH,1 ; select co-processor
; adapter # 1
ICAVRET 10 ; return first 10 flags
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
MOV AH,0 ; Select co-processor adapter # 0 MOV AL,10 ; Task number tenICAVRETM LABEL ; Entry point label
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
02h Invalid task number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
MOV AX,0001h ;co-processor adapter 0, task 1 ICAVSETM LABEL ;
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
02h Invalid task number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
05h Page Selector already
reserved
Interrupt handler services are available through the use of the interrupt vector 7Fh function calls, described in this section.
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
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
02h Invalid task number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist
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
-----------------------------------------------------------
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
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
-----------------------------------------------------------
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.
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
-----------------------------------------------------------
AL Code Meaning
-----------------------------------------------------------
01h Invalid co-processor
adapter number
04h Co-processor adapter
inactive but ICAPARM
parameters exist.
(Adapter failed power-
on self test.)
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:
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
----------------------------------------------------------- AL Code Meaning ----------------------------------------------------------- 0Dh Peer handle not available 0Fh Invalid command
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
----------------------------------------------------------- AL Code Meaning ----------------------------------------------------------- 0Eh Unknown peer handle 0Fh Invalid command
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
----------------------------------------------------------- AL Code Meaning ----------------------------------------------------------- 09h Command not accepted 0Fh Invalid command
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
1 if interrupt handler is not resident.
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
----------------------------------------------------------- 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 5Note: UC = Unchanged.
Errors
Not applicable.
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:
>DUMP
>DUMP [n]
Where n is the logical co-processor adapter to dump. The default drive is drive A.
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:
To load the Online Dump Facility, do the following:
> COPY A: DUMP.* C:/V
The following files are transferred:
DUMP.COM DUMP.MSG
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.
A dump can be done in either of the following ways:
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.
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.
The following command writes the dump data for logical co-processor adapter number 1 to default drive A.
> DUMP 1
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:
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.
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 RESUMEThis 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.
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.
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:
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.
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)
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:
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.
The Dump Formatter Facility creates at least two files when formatting a dump of a co-processor adapters memory and I/O image:
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.
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:
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:
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 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:
Following is a list of the Dump Formatter Facility profile parameters:
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
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.
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.
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.
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.
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.
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:
To set this parameter, add the following line to the profile:
PRINT_LINES = nn
The default value is 60 lines per page.
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.
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.
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.
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).
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
This appendix contains messages you may see while using the following:
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.
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.
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:eeeeExplanation: 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 VERSIONExplanation: 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.
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:
If your system contains any of the following adapters, proceed with step 2.
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:
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:
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.
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
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.
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.
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.
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:
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:
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.
(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