Programmer's Overview                             

The DCA/Intel CAS provides a standard programming interface that allows
software developers to access the communication services provided by
hardware.  The software that implements CAS (called the Resident Manager)
controls the interface to the hardware and allows multiple
applications/processes to use the hardware without conflict.

To use the CAS interface, an application submits data-communication events
to the Resident Manager.  The Resident Manager then schedules the event and
performs the necessary data transfer without further interaction with the
application.  An application that is using the CAS interface does not need
to monitor, maintain, or service a communications event.  The Resident
Manager performs these events for the application, in the background.

The Resident Manager provides a kernel of primitives (control files and
function calls) that set up data communication events, schedule the events
for execution, and check the results of the event.  The set of CAS
primitives has purposely been kept simple and generic, both to support as
many types of applications as possible and to relieve certain classes of
applications from being forced to use functions specific to other classes.

Applications access CAS functions through interrupt 2FH (Multiplex
interrupt on DOS versions 3.0 and above).  Similar to DOS function calls
accessed through interrupt 21H, CAS functions are accessed by loading
registers with defined values, issuing an interrupt 2FH, and examining the
values returned in the appropriate registers.

The following convention is used for function calls:

     Register     Usage

     AH             Multiplex Number (0CBH)
     AL             Function Code
     BX             Event Handle
     CX             File Number
     CX, DX         Date, Time
     DS:DX          Pointer to Data Area
     DL             Queue
                    0 - Task Queue
                    1 - Receive Queue
                    2 - Log Queue

All multiplex interrupts require a unique multiplex number.  For all Intel
CAS implementations, this number is 0CBH.

                           Events and Control Files                           

The Resident Manager currently supports the following six data-
communication events:

  Send         The local computer transmits information to a remote device
               (fax machine or computer).

  Receive      The local computer receives information from a remote
               device.

  Polled Send  The local computer waits for a remote device to call and
               then automatically sends information to it.

  Polled Receive The local computer calls a remote device and receives
               information from it.

  Group Send   (V1.2) The local computer transmits the same information to
               multiple remote devices.

  Group Polled The local computer calls multiple remote devices and
   Receive (1.2) receives information from them.

Each event has one or more Control Files associated with it.  A Control
File contains information about an event that the Resident Manager uses to
schedule, execute, and report the status of the event.  For example, the
Control File for a send event contains the phone number, date, and time
information for the event.

                                    Queues                                    

To manage the events presented to it, the Resident Manager places the
Control Files associated with these events in queues.  Three types of
queues are supported: a Task Queue, a Receive Queue, and a Log Queue.

  Task Queue   contains a list of pending events that the application
               running on the local computer has initiated.  Pending events
               can be send, polled send, polled receive, group send, and
               group polled receive events.

  Receive Queue contains a list of events that the local computer has
               received from a remote device.

  Log Queue    contains a record of all the events that have been
               completed, aborted, or terminated with an error.

These event queues allow the Resident Manager to schedule and monitor
events.  They also allow an application to check on the status of events.

                          Using the Resident Manager                          

To initiate an event, the application must first create a Control File for
the event.  This file contains information such as the name of the file (or
files) to send, the phone number of the destination, and the date and time
for transmission.  The application then submits the Control File for the
event to the Resident Manager and receives back a unique event handle.  The
application uses the event handle to keep track of that particular event.

Note:     Event handles are never 0.

While an event is pending, the Resident Manager keeps the Control File for
the event in the Task Queue.  When it is time to process the event, the
Resident Manager takes the event's Control File off the Task Queue and
sends the necessary information about the event to the communications
hardware.  While the event is being processed (that is, while it is the
current event), its Control File is not on any queue; however, the
application can access information about the current event by using the CAS
Get Current Event Status function.

Once the event is completed, successfully or not, the Resident Manager
updates the status information in the event's Control File and moves the
file to the Log Queue.  The application can then use the CAS functions to
examine the Control Files in the log queue and determine the status of
completed events.

Note:   The event handle for an event remains the same even
        though the Control File for the event has been moved from
        the task queue to the log queue.

For receive events, the Resident Manager receives data from the remote
device and stores it in a disk file.  Once the receive event is completed,
the Resident Manager creates a Control File for the event and places copies
of it in both the Receive Queue and the Log Queue.  The application can
then use CAS functions to examine the Control Files in the Receive and Log
Queues and to open files of received data.

The Resident Manager saves the Control Files in the Receive and Log Queues
until  the application explicitly deletes them.  The data files that are
received from a remote device are also saved until the application
explicitly saves them or deletes.  Data files that are sent to a remote
device can be saved after they are sent or automatically deleted, according
to how the application sets up the Control File.

                             Group Events (V1.2)                              

Group events are events in which the same activity is carried out between
the local computer and several remote devices.  For example, with a group
send event, the local computer can send the same file (or files) to a group
of several remote devices.  Or, with a group polled receive, the local
computer polls a group of remote devices to receive information from them.

For group events, the application must set up two files:  a parent Control
File that defines the event to be carried out and a Group File that defines
the group of individuals that the event is going to be directed to.

When the parent Control File for a group event is submitted to the Task
Queue, the Resident Manager assigns an event handle to the group (or
parent) event.  It also examines the Group File and assigns an event handle
to each group member.  This latter event handle is used to identify the
instance of the group event (called a sub-event) that is processed for that
group member.

Each time a sub-event is completed, the Resident Manager creates a Control
File in the Log Queue for that sub-event.

When all the sub-events associated with a parent event have been processed,
the Resident Manager moves the Control File for the parent event to the Log
Queue.  It also moves the Group File to the Log Queue.  This file is the
same as the original Group File, except that the status fields are filled
in for each individual and the event handle fields are filled in with the
event handle corresponding to each sub-event.

If a group event is cancelled, the Resident Manager ceases processing all
the sub-events associated with that event.

                                Control Files                                 

A Control File contains the specific control information (who to call, when
to call, etc.) for a given send or receive event.  Some fields in a Control
File are meaningful only in certain instances.  For example, the "Time
length of phone connection" fields are not meaningful in a Control File for
a pending Send event and will contain zeros.

                                 Conventions                                  

In the description of the Control File that follows, several terms are used
that require further explanation.  These include ASCIIZ string, DOS file
time format, and phone number.

ASCIIZ String

An ASCIIZ string is simply a string of ASCII characters followed by a zero
byte to indicate the end of the string.

DOS File Date and Time Format

DOS file date and time format is a convention that DOS uses for storing the
date and time in two-byte fields.

 See Also Register Conventions Error Codes

Copyright © 1985 to 2022 Beta Systems                            Last modified: Wednesday, January 05, 2022 .