Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PROGRAMS / UTILS / MODEMS / CAS.ZIP / CAS.TXT

Wrap

Text File | 1990-05-30 | 85.7 KB | 3,563 lines

DCA/Intel Communicating Applications Specification Version 1.0B Copyright (C) 1988, 1989. All rights reserved. Digital Communications Associates, Inc. 1000 Alderman Drive Alpharetta, GA 30201-4199 Intel Corporation 5200 N.E. Elam Young Pkwy. Hillsboro, OR 97124-6497 Intel Part Number: 301812-003 This specification was jointly developed by Digital Communications Associates, Incorporated and Intel Corporation. Although it has been released into the public domain and is not confidential or proprietary, the specification is still the copyright and property of Digital Communications Associates, Incorporated and Intel Corporation. Disclaimer of Warranty DIGITAL COMMUNICATIONS ASSOCIATES, INCORPORATED (DCA) AND INTEL CORPORATION EXCLUDE ANY AND ALL IMPLIED WARRANTIES, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. NEITHER DCA NOR INTEL MAKE ANY WARRANTY OF REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS SPECIFICATION, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. NEITHER DCA NOR INTEL SHALL HAVE ANY LIABILITY FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RESULTING FROM THE USE OR MODIFICATION OF THIS SPECIFICATION. This specification uses the following trademarks: Connection CoProcessor is a trademark and Intel is a registered trademark of Intel Corporation. DCA and Digital Communications Associates are registered trademarks of Digital Communications Associates, Incorporated. Table of Contents Introduction .............................................. 1 Addressing the Communication Problem ...................... 1 The CAS Architecture ...................................... 3 DCA/Intel CAS ........................................ 4 The Resident Manager ................................. 4 Transfer Agents ...................................... 4 Hardware ............................................. 4 Opportunities ............................................. 5 Additional Copies of CAS .................................. 5 Programmer's Overview ..................................... 6 Events and Control Files ............................. 6 Queues ............................................... 7 Using the Resident Manager ........................... 7 Control Files ............................................. 8 Conventions .......................................... 8 Control File Format .................................. 9 File Transfer Record (FTR) ........................... 12 Sequence of Events for Transmitting and Receiving Files ... 13 Transmitting a Single File ........................... 13 Transmitting Multiple Files as a Single Event ........ 13 Receiving Files ...................................... 14 Function Table ............................................ 15 Get Installed State (00H) ................................. 16 Submit a Task (01H) ....................................... 17 Abort a Current Event (02H) ............................... 18 Find First Entry in Queue (05H) ........................... 20 Find Next Entry in Queue (06H) ............................ 22 Open a File (07H) ......................................... 23 Delete a File (08H) ....................................... 25 Delete All Files (in a queue, 09H) ........................ 26 Get Event Date (0AH) ...................................... 27 Set Task Date (0BH) ....................................... 28 Get Event Time (0CH) ...................................... 29 Set Task Time (0DH) ....................................... 30 Get External Data Block (0EH) ............................. 31 Get/Set Autoreceive State (0FH) ........................... 32 Get Current Event Status (10H) ............................ 33 Get Queue Status (11H) .................................... 34 Get Hardware Status (12H) ................................. 35 Run Diagnostics (13H) ..................................... 36 Move Received File (14H) .................................. 37 Submit a Single File to Send (15H) ........................ 38 Unload Resident Manager (16H) ............................. 40 Error Codes ............................................... 42 Phone Number Specification ................................ 44 Phonebook Format .......................................... 44 PCX Format ................................................ 46 Data Encoding ........................................ 46 File Header .......................................... 47 DCX Format ................................................ 48 DCA/Intel Communicating Applications Specification V1.0B iii ASCII File Interpretation for Fax Transmission ............ 48 GLOSSARY .................................................. 50 iv DCA/Intel Communicating Applications Specification V1.0B Introduction The DCA/Intel Communicating Applications Specification (CAS) defines a standard communication programming interface for software developers. With this interface, software developers can add communication functions to their products in a straightforward and simple manner. This high-level interface provides functions for both sending and receiving information. This interface is independent of the hardware and software that provide the communications facilities. By making the interface hardware-independent, software developers can code their applications to the interface and be assured that their applications will work with new generations of hardware products. Version 1.0 of the CAS requires DOS 3.0 or later. Addressing the Communication Problem Today, end users often use one set of applications to create and modify information and another set to communicate the information to others. As a result, the communication process is often different and disjointed from the creation process. In many instances, electronic communication is complicated and demands a sophisticated user. The necessity of knowing about protocols, start bits, stop bits, and parity information prevents the average user from taking advantage of electronic communication. For an easier solution, end users can use paper methods for communicating information. Facsimile, Federal Express, and U.S. Mail are used extensively today. However, the recipient often needs the information in an electronic form to edit or enhance the data. Paper systems do not address this problem. What end users really need is a simple way to send electronic information in a wide variety of data formats (file transfer, fax, etc.). The easiest way for them to do this would be through applications that they're already familiar with. For example, using a favorite word processor, an end user could create a memo to be distributed to the sales offices. While in the word processor, the end user would invoke the "send" command. The underlying hardware and software would then distribute the memo using whatever communications technologies are required (facsimile, modem, MCI, etc.). DCA/Intel Communicating Applications Specification V1.0B - 1 - The DCA/Intel Communicating Applications Specification (CAS) is designed to allow software developers to easily integrate communications into their applications. The CAS programming interface is hardware-independent and shields software developers from the details typically associated with using communication hardware today. By using the CAS interface, software developers can offer new or enhanced communication features with less effort. As new hardware technologies become available, software developers can incorporate those new features with little or no additional coding. End-user ZDDDDDDDDDDDDBDDDDDDDDDADDDDBDDDDDDDDDDDDDDDDDDDD? ZDDDDDDADDDDD? ZDDDADDDD? ZDDDDDADDDDDD? ZDDDDDDADDDDDDD? 3 Word 3 3 Spread 3 3 Electronic 3 ... 3 In-House 3 3 Processors 3 3 Sheets 3 3 Mail 3 3 Applications 3 @DDDDDBDDDDDDY @DDDBDDDDY @DDDDDBDDDDDDY @DDDDDDBDDDDDDDY 3 3 3 3 @DDDDDDDDDDDDDADDDDDDDBDDDDDDADDDDDDDDDDDDDDDDDDDDY 3 ZDDDDDDDDDDDDDDADDDDDDDDDDDDDDDD? 3 3 3 CAS Software 3 3 and Hardware 3 3 3 @DDDDDDDDDDDDDDBDDDDDDDDDDDDDDDDY 3 ZDDDDDDDDDDDDDBDDDDDDADDDDDBDDDDDDDDD? ZDDDDDADDDD? ZDDADD? ZDDDADD? 3 3 MCI Mail 3 3 Fax 3 3 3270 3 ... Communication @DDDDDDDDDDY @DDDDDY @DDDDDDY Media With communications integrated into the application, end users can both create and communicate information without leaving their applications. The communication process has the same "look and feel" as their applications. Because the communication techniques are simplified, end users are more productive and require less sophistication. - 2 - DCA/Intel Communicating Applications Specification V1.0B The CAS Architecture The CAS architecture consists of four components: CAS, the Resident Manager, Transfer Agents, and the hardware. These components provide transparent communication for the end user while supporting a wide range of communication technologies. ZDDDDDDDDDDDDDDD? ZDDDDDDDDDDDDDDD? 3 Developer 3 3 Developer 3 ... 3 Application 1 3 3 Application 2 3 @DDDDDDBDDDDDDDDY @DDDDDDBDDDDDDDDY 3 3 3 3 @DDDDDDDDDDDDDDDDDDEDDDDDDDDDDDDDDY 3 DCA/Intel CAS 3 Programming Interface * -------------------------3---------------------------- 3 ZDDDDDDDDDDDDADDDDDDDDDDDDDDDD? 3 3 3 Resident Manager 3 3 3 @DDDDDDDDDDDDBDDDDDDDDDDDDDDDDY 3 ZDDDDDDDDDDDDADDDDDDDDDDDDDDDD? 3 3 3 Transfer Agents 3 3 3 @DDDDDDDDDDDDBDDDDDDDDDDDDDDDDY 3 3 ZDDDDDDDDDDDDDDDDDDABDDDDDDDDDDDDDDDDDDD? 3 3 3 ZDDDDDDADDDDD? ZDDDDDDDDDDADDDDDDDDD? ZDDDDDDADDDDDDDD? 3 3 3 3 3 3 3 Fax modem 3 3 Asynchronous modem 3 3 3270 Hardware 3 ... 3 3 3 3 3 3 @DDDDDDDDDDDDY @DDDDDDDDDDDDDDDDDDDDY @DDDDDDDDDDDDDDDY * The software developer is responsible for writing code using the CAS programming interface. The underlying software and hardware would be provided by the communication product vendor. DCA/Intel Communicating Applications Specification V1.0B - 3 - DCA/Intel CAS The DCA/Intel Communicating Applications Specification (CAS) is a programming interface for software developers. With this interface, the developer initiates a request by calling the Resident Manager. The Resident Manager handles all incoming and outgoing data. The Resident Manager The Resident Manager implements the DCA/Intel CAS. When sending, it takes the information from the application and determines the appropriate communication method and routing to reach the individual. Once it decides on the method of communication, the Resident Manager invokes the correct Transfer Agent to handle the actual transmission. When receiving, the Resident Manager receives and stores the information, and makes it available to the application. Transfer Agents In its simplest form, a Transfer Agent is a data dump truck. The Transfer Agent is responsible for moving the data to or from the desired location. It handles all issues concerning connecting, transmitting, and disconnecting from the recipient. Each service and protocol has a unique Transfer Agent. The Transfer Agent ensures that the data is transmitted reliably and reports any status information. The Transfer Agent can execute either on the PC microprocessor or, assuming an intelligent board, on the communication hardware. For intelligent hardware, Transfer Agents are downloaded from the PC. If the Transfer Agent executes on the communication hardware, the transmission can take place in the background. Therefore, the architecture supports multiple transfer agents and allows easy updating of existing agents. Hardware The DCA/Intel Communicating Applications Specification (CAS) is designed to support a wide variety of communications hardware. Version 1.0 of this specification provides functions that are applicable to fax modem hardware. This type of hardware can be used for both facsimile and file transfer. Over time, the DCA/Intel CAS will evolve to add functions appropriate for other hardware. Software developers who include CAS support in their applications can be assured of upward compatibility with future versions of the CAS. - 4 - DCA/Intel Communicating Applications Specification V1.0B Opportunities Using CAS functions, software developers can offer new features to their end users. With version 1.0, developers can treat remote fax machines as another output device and/or provide direct file transfer capability. Using the facsimile aspect of the specification, developers can treat fax machines as remote printers. For example, they can design word processors that let end users send memos to remote sales offices using facsimile transfer. Developers can even take the mail merge concept and combine it with fax technology to create new features such as fax merge. Also, they can design database report generation tools that send output to the fax machines in the field offices. The file transfer capabilities of the specification enable software developers to provide easy data-sharing capabilities for remote users. Word processing, spreadsheet, and database files can be easily transmitted by end users, allowing both parties to make more efficient edits and changes to working documents. Developers of LAN-based applications (such as E-mail, groupware, and shared databases) can also use CAS functions to easily extend the services of their products. These developers can use CAS functions to provide high- speed bridges between networks, high-speed links to support remote end- users, and fax gateways to communicate with non-PC users. Additional Copies of CAS You can obtain additional copies of this specification by contacting Intel at one of the following numbers: (800) 538-3373 (inside the U.S. or Canada) (503) 629-7354 (outside the U.S. or Canada) The Intel Electronic Bulletin Board contains an ASCII version of this specification that you can download with a modem using the XMODEM transfer protocol. You can reach the Bulletin Board 24 hours a day by calling: (503) 645-6275 Before you call, set your modem for 300, 1200, or 2400 bits per second; 8 data bits; no parity; and 1 stop bit. You can also obtain a copy of this specification if you have a touch-tone phone and a fax machine or Intel Connection CoProcessor. FaxBack is available 24 hours a day. You can reach FaxBack by calling: (503) 629-7576 DCA/Intel Communicating Applications Specification V1.0B - 5 - Programmer's Overview The DCA/Intel CAS provides a standard interface that allows multiple software developers to access the communication services provided by the hardware. The software that implements the CAS controls the interface to the hardware such that multiple applications/processes can use the hardware without conflict. The Resident Manager provides a kernel of primitives designed to allow software developers to implement support in a variety of possible applications. To support as many types of applications as possible and relieve certain classes of applications from being forced to use functions specific to other classes, the set of CAS primitives (functions) has been kept simple and generic. 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 The Resident Manager conceptually manages three queues of Control Files. Much of the information needed by applications is in the Control File. One queue is used for managing tasks created by applications to be sent out. A second queue is used for managing received data. The third queue is used to manage a historical log of activities. Events and Control Files Control Files contain information about events. An event can be one of several actions the Resident Manager can perform. These actions are: Send The local computer transmits information to a remote computer. Receive The local computer receives information from a remote computer. - 6 - DCA/Intel Communicating Applications Specification V1.0B Polled Send The local computer waits for a remote computer to call and then automatically sends information to it. Polled Receive The local computer calls a remote computer and receives information from it. Log The local computer records the details of a successful or unsuccessful communication activity. A subset of these events (Send, Polled Send, and Polled Receive) are started by the local computer and are called tasks. For tasks, the application usually creates the Control Files. In the case of a Receive or Log event, which are events initiated by the remote computer, the Resident Manager automatically creates the Control Files. Queues The Resident Manager maintains three queues internally: a Task Queue, a Receive Queue, and a Log Queue. The Resident Manager uses queues to manage Control Files. This management is needed to control when events occur and to provide uniform, collision-free access to Control Files for various applications. Any activity can be classified as a receive, a send, or a log activity. To avoid some bottlenecks, activities have been classified into the three groups such that one application may, for instance, examine the Log Queue while another application is preparing a send activity. These are two different classes of activities (events) and can occur simultaneously. Using the Resident Manager When an application wants to perform a task (a Send event, a Polled Receive event, or a Polled Send event), it must create a Task Control File. This file contains information such as the name of the file(s) to send, the phone number of the destination, and the date and time for transmission. The application then enters the task into the Resident Manager's Task Queue and receives a unique event handle which is used to keep track of this particular event. Note: Event handles are never 0. Upon completion of the task, the Resident Manager updates the status information in the Control File and transfers it to the Log Queue. At this point, the control file becomes a Log Control File. The application can then use the DCA/Intel CAS functions to query the Log Queue to check for the status of a completed task. Note: the event handle remains the same even though the event has changed from a task to a log event. For Receive events, the Resident Manager creates both a Receive Control File and a Log Control File. Each remains in existence until the application deletes the associated receive or log event. DCA/Intel Communicating Applications Specification V1.0B - 7 - Control Files The Resident Manager controls events with queues that rely on information contained in Control Files. Control files can refer to a scheduled task (a Task Control File), a current receive event (a Receive Control File), or a completed event (a Log Control File). Various 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 Task Control File for a 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. The format of the date is: Bits Description 0-4 A value from 1 to 31, indicating the day of the month (where 1 is the first day). 5-8 A value from 1 to 12, indicating the month of the year (where 1 is January, 2 is February, etc.). 9-15 A value from 0 to 119 (which corresponds to 1980 to 2099) indicating the year. The format of the time is: Bits Description 0-4 The number of two-second increments. 5-10 A value from 0 to 59, indicating the minutes. 11-15 A value from 0 to 23, indicating the hours. - 8 - DCA/Intel Communicating Applications Specification V1.0B Phone Numbers When specifying a phone number, you can include not only the digits 0 through 9 and the characters # and *, but also the following special characters: Character Description , Causes the hardware to pause when dialing. This is useful when waiting for a tone for an outside line. ! Signals a hook flash, for use with special PBX functions. P Specifies pulse dialing for rotary phones. T Specifies tone dialing for touch-tone phones. M Causes the hardware to use the current connection without dialing a new number (manual dialing). All other characters are ignored. Control File Format Listed below is the general format of a Control File. The fields preceded by bullets (77) and whose first lines are in bold are fields the programmer must fill in when creating a Control File for a task. Other fields are filled in by the Resident Manager and should be set to 0 when creating the Control File. For a receive or log event, the Resident Manager fills in all the fields. The Offset column indicates the offset of the field (in bytes) from the start of the file. The Length column indicates the length of the field in bytes. The values listed in the Description field are values, not bit positions. Multi-byte fields containing numeric, date, or time values have the least-significant byte first. When using high-level languages to create a Control File, make sure the data structures are packed (aligned on byte boundaries). Offset Length Description ** 0 1 Event type: 0 - Send 1 - Receive 2 - Polled Send 3 - Polled Receive 4 - 127 Reserved -1 (0FFH) - Serious hardware error not associated with an ordinary event. Note: When filling out this field, you must set it to 0, 2, or 3. The value 1 is used by the Resident Manager when creating a receive Control File. The value -1 is not valid for Task Control Files and results in an error. DCA/Intel Communicating Applications Specification V1.0B - 9 - Offset Length Description ** 1 1 Transfer type: 0 - 200x200 dpi, fax mode. 1 - 100x200 dpi, fax mode. 2 - File transfer mode. 3-127 - Reserved. Note: You must set the Transfer type field to 0, 1, or 2 for a send event (the field doesn't apply for a polled receive event). Setting this field to a value greater than 2 results in an error. 2 2 Status of event: 0 - Successfully completed. 1 - Waiting to be processed. 2 - Number has been dialed. 3 - Connection made -- sending. 4 - Connection made -- receiving. 5 - Send event was aborted. 6-127 - Reserved. 128-32,767 - Available for application-defined events. Negative value - error. Note: This field is set by the Resident Manager and should be set to "0" in a Task Control File. ** 4 2 For send events, this is the time you want to send the information. For receive events, this is the time the receive event occurred. The format is in DOS file date and time format. ** 6 2 For send events, this is the date you want to send the information. For receive events, this is the date the receive event occurred. The format is in DOS file date and time format. Note: Setting both the time and date fields to zero schedules the file to be sent immediately. Therefore, to send a file at once, zero the four bytes (long word) at offset 4. ** 8 2 Number of files to transfer, maximum 32766. ** 10 2 Offset in this control file of first File Transfer Record. Note: If you don't plan to include cover page text (described at offset 383), this field must specify offset 383. Otherwise, this field must specify the offset immediately after the cover page text. ** 12 47 Phone number to call, as an ASCIIZ string. Offset Length Description 59 64 Application-specific tag field, as an ASCIIZ string. - 10 - DCA/Intel Communicating Applications Specification V1.0B Note: This field is used by applications to identify Control Files that are "owned" by that application. For example, when an application creates control files, it can fill this field with a specific ASCII string. Later, when it checks Control Files, it can check for the same string to ensure that it handles only the Control Files that apply to it. If a file was sent using Non-Standard Format (NSF), this field will have meaning for a Receive Control File. If a file was sent as a fax, this field will be filled with zeros. ** 123 1 Reserved. Set to zero. 124 1 Time length of phone connection: seconds (0 - 59). 125 1 Time length of phone connection: minutes (0-59). 126 1 Time length of phone connection: hours (0-23.) 127 4 Total number of pages in all files. 131 4 Number of pages transmitted so far. 135 2 Number of files transmitted so far. ** 137 1 Cover page flag: 0 - Don't send cover page. 1 - Send cover page. 2-127 - Reserved. Note: If you plan to send only a cover page, set this field to 1 and the number of files to transfer (offset 8) to 0. Setting both fields to 0 results in an error. 138 2 Number of transmission errors reported by the hardware for all transmissions controlled by this Control File. ** 140 78 Reserved. Set to zero. 218 21 Remote CSID (the CCITT identification of the fax device), as an ASCIIZ string (set by the Resident Manager). ** 239 32 Destination Name, as an ASCIIZ string (To: field). ** 271 32 Sender Name, as an ASCIIZ string (From: field). ** 303 80 Path and name of PCX logo file (maximum size 1728 x 800 pels), as an ASCIIZ string. ** 383 var Cover page text, as an ASCIIZ string. the length is variable, as indicated by var, but a maximum of 36 lines of text is recommended (or else the received page might be longer than 11 inches). Lines can be separated by new line characters (0AH) or CR-LF pairs (0DH, 0AH). Lines longer than 80 characters are wrapped around. DCA/Intel Communicating Applications Specification V1.0B - 11 - Offset Length Description Note: The text field is not required to be present. If it is absent, the first File Transfer Record (FTR) must start at offset 383. In all cases, the field at offset 10 identifies the start of the first FTR. ** var var Table of 128-byte File Transfer Records (FTRs). The first FTR begins at the offset specified by the word at offset 10 of the control file. The following section describes the format of each FTR. File Transfer Record (FTR) Listed below is the general format of a File Transfer Record. These records appear at the end of the Control File, one for each file that is transferred as part of the event. Fields preceded by bullets (**) and whose first lines are in bold are fields the programmer must fill in when creating an FTR. Other fields are filled in by the Resident Manager software and should be set to 0 when creating the FTR. When creating an FTR for a file transfer, specify only the file name. When creating an FTR for a fax, you must also specify the text size and page length fields. In both cases, set the other fields to zero. The Resident Manager will fill in the other fields. Each FTR has the following format: Offset Length Description ** 0 1 File type (has meaning only for faxes): 0 - ASCII 1 - PCX 2 - DCX 3-127 - Reserved ** 1 1 Text size to use if file type is ASCII (has meaning only for faxes): 0 - 80 column by 66 lines (11 inches) 1 - 132 column by 88 lines (11 inches) 2-127 - Reserved 2 1 Status of this file: 0 - Untouched 1 - Has been opened 2 - Has been moved 3 - Has been deleted 4 - Not yet received 5-127 - Reserved 3 4 Bytes of this file transmitted so far. 7 4 Size in bytes of this file. 11 2 Number of pages in this file transmitted so far. 13 2 Number of pages in this file. - 12 - DCA/Intel Communicating Applications Specification V1.0B Offset Length Description ** 15 80 Path and name of file to send, as an ASCIIZ string. ** 95 1 If you set the Inches field (offset 96) to a value in the range 1 through 127, this field specifies the number of additional 1/8-inch increments in page length. If the Inches field is outside that range, this field has no meaning. This field has meaning only for faxes. ** 96 1 Page length in inches (has meaning only for faxes). 0 - Page length is 11 inches. 1-127 - Page length is the specified number of inches, plus the number of 1/8 inches specified in the 1/8 inches field (offset 95). -1 - ASCII pages end with form feeds only. All other values are reserved. ** 97 31 Reserved. Set to zero. Sequence of Events for Transmitting and Receiving Files This section provides an overview of the steps a programmer should follow to transmit and receive files using the DCA/Intel CAS function calls. Although these sections are general, they refer to specific function calls. Later sections of this specification provide detailed descriptions of the function calls. Transmitting a Single File 1. Invoke CAS function 00H (Get Installed State) to determine if the Resident Manager is installed. If it is, continue with the following steps. 2. Create the data file you wish to transmit. 3. Create the data structure required by function 15H (Submit a Single File to Send). 4. Invoke function 15H (Submit a Single File to Send). 5. Check for errors in sending. Transmitting Multiple Files as a Single Event 1. Invoke CAS function 00H (Get Installed State) to determine if the Resident Manager is installed. If it is, continue with the following steps. 2. Create the data files you wish to transmit. DCA/Intel Communicating Applications Specification V1.0B - 13 - 3. Create a Task Control File that includes one File Transfer Record (FTR) for each file you wish to transmit. 4. Invoke function 01H (Submit a Task). 5. Check for errors. Receiving Files 1. Invoke CAS function 00H (Get Installed State) to determine if the Resident Manager is installed. If it is, continue with the following steps. 2. Invoke function 05H (Find First Entry in Queue) to determine if any receive events have occurred. If a receive event has occurred, continue with the following steps. 3. Invoke function 07H (Open a File) to open the Receive Control File obtained in step 2. Check the application-specific tag field in the control file to determine if the receive event is of interest to your application. If the tag is appropriate, continue with step 4. Otherwise, invoke DOS function 3EH (Close File Handle) to close the Receive Control File and continue with step 8. 4. For each File Transfer Record in the Receive Control File, examine the "Status of this file" field to determine if the associated received file has been moved or deleted. For each received file that has not been moved or deleted, continue with step 5. If no such files remain, close the Receive Control File and continue with step 8. 5. Invoke function 14H (Move Received File) to move the received file to the appropriate directory or filename or invoke function 08H (Delete a File) to delete the received file. 6. Once you have moved, renamed, or deleted all the received files, invoke DOS function 3EH (Close File Handle) to close the Receive Control File. 7. Invoke function 08H (Delete a File) to delete the Receive Control File. 8. Invoke function 06H (Find Next Entry in Queue) to determine if additional receive events have occurred. If there are additional receive events, repeat steps 3 through 7. - 14 - DCA/Intel Communicating Applications Specification V1.0B Function Table Function Name Function Number Get Installed State....................................00H Submit a Task..........................................01H Abort the Current Event................................02H Reserved.........................................03H - 04H Find First Entry in Queue..............................05H Find Next Entry in Queue...............................06H Open a File............................................07H Delete a File..........................................08H Delete All Files (in a queue)..........................09H Get Event Date.........................................0AH Set Task Date..........................................0BH Get Event Time.........................................0CH Set Task Time..........................................0DH Get External Data Block................................0EH Get/Set Autoreceive State..............................0FH Get Current Event Status...............................10H Get Queue Status.......................................11H Get Hardware Status....................................12H Run Diagnostics........................................13H Move Received File.....................................14H Submit a Single File to Send...........................15H Unload Resident Manager................................16H Reserved.........................................17H - 80H DCA/Intel Communicating Applications Specification V1.0B - 15 - 00H Get Installed State Description: Get Installed State (00H) detects whether the Resident Manager is currently installed. Input: AH = Multiplex number AL = 00H Return: On return, AL contains the installed state as follows: AL = 00H Not installed AL = 01H Not installed, not OK to install AL = FFH Installed There is no error returned. See Also: Get External Data Block (OEH) - 16 - DCA/Intel Communicating Applications Specification V1.0B 01H Submit a Task Description: The Submit a Task function (01H) schedules a send, a polled send, or a polled receive event. Before invoking this function, you must first prepare a Task Control File. The function adds this Task Control File to the Task Queue. The event handle returned by this function is a positive integer that must be used in all subsequent references to this event. For sends and polled sends, once the event has completed, the Task Control File will automatically be deleted and a corresponding Log Control File created without programmer action. However, files associated with the event (the files to send) will not be deleted. For polled receives, neither the Task Control File nor the received files will be deleted. Input: AH = Multiplex number AL = 01H DS:DX points to ASCIIZ path and name of Task Control File Return: AX = Positive event handle or negative error code Note: Files associated with a task must remain in existence until the task is complete or an error results. See Also: Submit a Single File to Send (015H) DCA/Intel Communicating Applications Specification V1.0B - 17 - 02H Abort the Current Event Description: The Abort the Current Event function (02H) aborts the currently executing event. To prevent the execution of a pending event, use the Delete a File function (08H). Note: Terminating an event is not instantaneous. It might take up to 30 seconds. Input: AH = Multiplex number AL = 02H Return: AX = Event handle of aborted event or negative error code See Also: Delete a File (08H) - 18 - DCA/Intel Communicating Applications Specification V1.0B 03H - 04H Reserved These functions are reserved. DCA/Intel Communicating Applications Specification V1.0B - 19 - 05H Find First Entry in Queue Description: The Find First Entry in Queue function (05H) searches the queue you specify in the DL register for an event whose status matches the one you specify in the CX register. Entries in queues are ordered by the date and time in which the corresponding events occurred (or are scheduled to occur). Depending on the value you place in the DH register, the function searches for the earliest or latest such event. The function returns a 15-bit event handle of the entry it finds. Once you use this function to obtain an event handle, you can access the file associated with that event by calling the Open a File function (07H). Use the Find Next Entry in Queue function (06H) to find subsequent entries in the queue. Input: AH = Multiplex number AL = 05H CX = Status of the event you are seeking. This value is compared with the field at offset 2 of the Control File. 0 - Event has successfully completed. 1 - Event is waiting to be processed. 2 - Number has been dialed. 3 - Connection has been made -- sending. 4 - Connection has been made -- receiving. 5 - Event was aborted. -1 Chooses an event without regard to status. This value will probably be used most often. Other negative values Matches error codes in Control File. DH = Direction: 0 - Search forward chronologically (from the first occurring event to the last occurring event). 1 - Search backward chronologically (from the last occurring event to the first occurring event). DL = Queue to search: 0 - Find first control file in Task Queue. 1 - Find first control file in Receive Queue. 2 - Find first control file in Log Queue. Return: AX = 0 if successful or a negative error code. BX = Event handle for this file. If the queue is empty, this function returns error 204H (no more events) in the AX register. - 20 - DCA/Intel Communicating Applications Specification V1.0B 05H Find First Entry in Queue See Also: Find Next Entry in Queue (06H) Open a File (07H) DCA/Intel Communicating Applications Specification V1.0B - 21 - 06H Find Next Entry in Queue Description: After a call to the Find First Entry in Queue function (05H), you can step chronologically through a queue using the Find Next Entry in Queue function (06H). Each subsequent call to Find Next Entry in Queue returns the event handle of the next event chronologically (as set by function 05H) in the specified Queue. For example, if you set the Find First Entry function to search forward chronologically, the Find Next Entry function searches forward for the next entry that matches the specifications set with Find First Entry. If you set Find First Entry to search backwards chronologically, Find Next Entry also searches backwards. You must invoke the Find First Entry in Queue function (05H) prior to using the Find Next Entry in Queue function. Once you use this function to obtain an event handle, you can access the file associated with that event by calling the Open a File function (07H). Input: AH = Multiplex number AL = 06H DL = Queue to search: 0 - Find next control file in Task Queue 1 - Find next control file in Receive Queue 2 - Find next control file in Log Queue Return: AX = 0 if successful or a negative error code BX = Event handle for this file See Also: Find First Entry in Queue (05H) Open a File (07H) - 22 - DCA/Intel Communicating Applications Specification V1.0B 07H Open a File Description: After you obtain an event handle (by either scanning a Queue using the Find First Entry in the Queue (05H) and Find Next Entry in the Queue (06H) functions or by creating a task using the Submit a Task (01H) function), you can use the Open a File function (07H) to access the DOS file corresponding to the event. For events in the Task and Log Queues, this function opens the control file for the event. For events in the Receive Queue, this function opens either the control file or one of the received data files. This function opens the desired file in read-only mode and returns an ordinary DOS file handle. Input: AH = Multiplex number AL = 07H BX = Event handle CX = Receive file number. This file number specifies which file to open among those associated with a receive event. This number applies only to events in the Receive Queue and is ignored for events in the Task and Log Queues. The number is interpreted as follows: 0 - The Receive Control File. The format of this file is described earlier in this document. 1 - First received file. Corresponds to the first file in the list of received filenames (file transfer record 0). 2 - Second received file. 3 - Third received file. n - nth received file. DL = Queue: 0 - Open control file in Task Queue. 1 - Open control file in Receive Queue or the received data file specified in the CX register. 2 - Open control file in Log Queue. Return: AX = 0 if successful or a negative error code. BX = DOS file handle for the requested file. DCA/Intel Communicating Applications Specification V1.0B - 23 - 07H Open a File See Also: Submit a Task (01H) Find First Entry in Queue (05H) Find Next Entry in Queue (06H) Move Received File (14H) - 24 - DCA/Intel Communicating Applications Specification V1.0B 08H Delete a File Description: The Delete a File function (08H) deletes one or more files in a specific Queue. Input: AH = Multiplex number AL = 08H BX = Event handle CX = Receive file number. This number specifies which file to delete among those associated with a receive event. This number applies only to events in the Receive Queue and is ignored for events in the Task and Log Queues. The number is interpreted as follows: 0 - Delete all files associated with the specified Receive Control File (including the Receive Control File). 1 - Delete the first received file associated with the event handle. 2 - Delete the second received file associated with the event handle. n - Delete the nth received file associated with the event handle. DL = Queue: 0 - Delete control file in Task Queue. 1 - Delete a file or files associated with an event in the Receive Queue. 2 - Delete control file in Log Queue. Return: AX = 0 if successful or a negative error code. See Also: Abort the Current Event (02H) Delete All Files (09H) DCA/Intel Communicating Applications Specification V1.0B - 25 - 09H Delete All Files (in a queue) Description: The Delete All Files function (09H) deletes all Task Control Files, all Receive Control Files and the associated received files, or all Log Control Files. Input: AH = Multiplex number AL = 09H DL = Queue: 0 - Delete all control files in the Task Queue 1 - Delete all control files in the Receive Queue and all received files 2 - Delete all control files in the Log Queue Return: AX = 0 if successful or a negative error code See Also: Delete A File (08H) - 26 - DCA/Intel Communicating Applications Specification V1.0B 0AH Get Event Date Description: The Get Event Date function (0AH) gets the date associated with a given event handle. Input: AH = Multiplex number AL = 0AH BX = Event handle of the event whose date you want to obtain DL = Queue: 0 - Task Queue 1 - Receive Queue 2 - Log Queue Return: AX = 0 if successful or a negative error code CX = Year (1980 - 2099) DH = Month (1 - 12) DL = Day (1 - 31) Refer to the "DOS Date and Time Format" section earlier in this specification for more information on the format of the data returned. See Also: Set Task Date (0BH) Get Event Time (0CH) DCA/Intel Communicating Applications Specification V1.0B - 27 - 0BH Set Task Date Description: The Set Task Date function (0BH) sets the execute date of a Task Control File specified by the event handle. This function is valid only for task events, not for receive or log events. Note: Setting the date for a task event to a value that is earlier than the current date causes the transmission to occur immediately. Input: AH = Multiplex number AL = 0BH BX = Event handle CX = Year (1980 - 2099) DH = Month (1 - 12) DL = Day (1 - 31) Refer to the "DOS Date and Time Format" section earlier in this specification for more information on the format of the data in these registers. Return: AX = 0 if successful or a negative error code See Also: Get Event Date (0AH) Set Task Time (0DH) - 28 - DCA/Intel Communicating Applications Specification V1.0B 0CH Get Event Time Description: The Get Event Time function (0CH) gets the time associated with a given event handle. Input: AH = Multiplex number AL = 0CH BX = Event handle DL = Queue: 0 - Task Queue 1 - Receive Queue 2 - Log Queue Return: AX = 0 if successful or a negative error code CH = Hour (0 - 23) CL = Minutes (0 - 59) DH = Seconds (0 - 59) DL = 0 Refer to the "DOS Date and Time Format" section earlier in this specification for more information on the format of the data returned. See Also: Get Event Date (0AH) Set Task Time (0OH) DCA/Intel Communicating Applications Specification V1.0B - 29 - 0DH Set Task Time Description: The Set Task Time function (0DH) sets the execute time of a Task Control File specified by the event handle. This function is valid only for Task events, not Receive or Log events. Note: Setting the time for a task event to a value that makes the date and time earlier than the current date and time causes the transmission to occur immediately. Therefore, an easy way to execute a task immediately is to set the task time and task date to zero. Input: AH = Multiplex number AL = 0DH BX = Event handle CH = Hour (0 - 23) CL = Minutes (0 - 59) DH = Seconds (0 - 59) The value of DL is unused. Refer to the "DOS Date and Time Format" section earlier in this specification for more information on the format of the data in these registers. Return: AX = 0 if successful or a negative error code See Also: Set Task Date (0BH) Get Event Time (0CH) - 30 - DCA/Intel Communicating Applications Specification V1.0B 0EH Get External Data Block Description: The External Data Block contains additional information about the current Resident Manager installation (such as the name of the default logo file). Input: AH = Multiplex number AL = 0EH DS:DX points to a 256-byte EDB area Return: AX = 0 if successful or a negative error code EDB area is filled with the External Data Block The format of the External Data Block is as follows: (values in decimal): Offset Length Description 0 1 CAS major version number. 1 1 CAS minor version number. 2 68 ASCIIZ string specifying pathname to directory containing Resident Manager and other software that implements the CAS. The path ends with a backslash. The user specifies this name when installing the software. 70 13 Name of default phonebook file, as an ASCIIZ string. This file is assumed to be in the Resident Manager and software directory. 83 13 Name of default logo file, as an ASCIIZ string. This file is assumed to be in the Resident Manager and software directory. The user specifies this name when installing the software. 96 32 Default sender name, as an ASCIIZ string. The user specifies this name when installing the software. 128 21 CSID (the CCITT identification of the fax device) as an ASCIIZ string. 149 107 Reserved. DCA/Intel Communicating Applications Specification V1.0B - 31 - 0FH Get/Set Autoreceive State Description: The Get/Set Autoreceive State function (0FH) examines or alters the receive state of the hardware. If an event is in progress, the new autoreceive state will not take effect until the event is completed. Input: AH = Multiplex number AL = 0FH DL = Function code: 0 - get current autoreceive state 1 - set current autoreceive state to value in DH DH = Number of rings before answer or 0 to disable Return: AX = current autoreceive state or negative error code 0 - Autoreceive disabled positive number - Number of rings before the hardware answers - 32 - DCA/Intel Communicating Applications Specification V1.0B 10H Get Current Event Status Description: The Get Current Event Status function (10H) returns the status of the currently executing event. Input: AH = Multiplex number AL = 10H DS:DX points to a 512-byte status area Return: AX = 0 if successful or a negative error code BX = Event number of the current event (if the function completed without an error) This function fills the status area pointed to by DS:DX on entry with a truncated version of the Control File for the current event. This data structure is identical to the Control File structure with two exceptions: * Only one File Transfer Record (FTR) is included. The FTR included is the one controlling the current file transfer. * No cover page text field is included. Instead the current FTR begins at offset 383. Therefore, the end of the Control File has the following format: Offset Length Description 303 80 Path and name of PCX logo file (maximum size 1728 x 800 pels) 383 128 The File Transfer Record corresponding to the current event DCA/Intel Communicating Applications Specification V1.0B - 33 - 11H Get Queue Status Description: The Get Queue Status function (11H) returns the current status of a queue you specify. Input: AH = Multiplex number AL = 11H DL = Queue: 0 - Find status of Task Queue 1 - Find status of Receive Queue 2 - Find status of Log Queue Return: AX = Total number of changes made to this queue since the Resident Manager was started, or a negative error code. If the number of changes exceeds 7FFFH, the count begins again at 0. BX = Current number of Control Files in this queue. CX = Current number of received files. (This register is non-zero only if you request the status of the Receive Queue by specifying DL = 1.) The value in this register is incremented for each file received. - 34 - DCA/Intel Communicating Applications Specification V1.0B 12H Get Hardware Status Description: The Get Hardware Status function (12H) returns the status of the communication hardware. Caution: The values and structure returned by this function are hardware-dependent and will vary according to type of hardware used to implement the CAS services. It is recommended that you use the Get Current Event (10H) and Get Queue Status (11H) functions, or examine the Control File, instead of using this function. Input: AH = Multiplex number AL = 12H DS:DX points to a 128-byte status area Return: AX = 0 if successful or a negative error code. If successful, the function fills the status area with hardware-dependent status information. Contact the manufacturer of your communications hardware for information on the content and format of the status information. See Also: Get Task Status (10H) Get Queue Status (11H) DCA/Intel Communicating Applications Specification V1.0B - 35 - 13H Run Diagnostics Description: The Run Diagnostics function (13H) runs a set of diagnostics or reports on their progress. Input: AH = Multiplex number AL = 13H DL = Mode: 0 - Report progress of diagnostics 1 - Start running diagnostics Return: If request was to start running diagnostics (DL = 1), AX contains either a 0 (diagnostics successfully begun) or a negative error code. If request was to report the progress of diagnostics, AX contains a 40H (diagnostics in process) or some other positive number indicating that diagnostics passed. If AX contains a negative number, the diagnostics failed and the value indicates the reason for failure. The values are hardware-dependent. Contact the manufacturer of your communications hardware for information on the failure codes. - 36 - DCA/Intel Communicating Applications Specification V1.0B 14H Move Received File Description: The Move Received File function (14H) moves a received file to a different directory and gives it a new name. The new directory can be on a different device. Note: The path to the new directory must exist. This function cannot create directories. Input: AH = Multiplex number AL = 14H BX = Event handle CX = Receive file number (must be nonzero to specify a received file) 1 - First received file 2 - Second received file 3 - Third received file n - nth received file DS:DX = Pointer to a new path and name of the file (in the form of an ASCIIZ string). This file must not exist already. Return: AX = 0 if successful or a negative error code. DCA/Intel Communicating Applications Specification V1.0B - 37 - 15H Submit a Single File to Send Description: The Submit a Single File to Send function (15H) provides a simple method of sending a single file, either as a fax or as a file transfer. The function creates and submits the necessary Task Control File and returns the corresponding event handle (or negative error code). Before invoking this function, you must create a data structure (described later) that contains the appropriate information. Input: AH = Multiplex number AL = 15H DS:DX = Pointer to a variable-length data area, described later in this section Return: AX = positive event handle or a negative error code The format of the data area pointed to by DS:DX is as follows. The individual fields have the same meaning as in a Task Control File. Offset Length Description 0 1 Transfer type: 0 - 200x200 dpi, fax mode 1 - 100x200 dpi, fax mode 2 - File transfer mode 3-127 - Reserved. 1 1 Text size (if ASCII file, fax mode) 0 - 80-column 1 - 132-column 2-127 - Reserved. 2 2 Time to send, in DOS file date and time format 4 2 Date to send, in DOS file date and time format Note: Setting both the time and date fields to zero schedules the file to be sent immediately. Therefore, to send a file at once, zero the four bytes (long word) at offset 2. 6 32 Destination Name, as an ASCIIZ string (To: field) 38 80 Path and name of the file to send, as an ASCIIZ string Offset Length Description 118 47 Phone number to call, as an ASCIIZ string - 38 - DCA/Intel Communicating Applications Specification V1.0B 15H Submit a Single File to Send 165 64 Application-specific tag field, as an ASCIIZ string 229 1 Reserved; set to zero 230 1 Cover page flag: 0 - Don't send cover page 1 - Send cover page 2-127 - Reserved 231 23 Reserved; set to zero 254 var Cover text, as an ASCIIZ string. This text is sent if the cover page flag (offset 230) is set to 1. You must set all fields, except for the Application-Specific Tag field, before calling this function. However, you can set the Destination Name and Cover Text fields to the empty string, if desired. See Also: Submit A Task (01H) DCA/Intel Communicating Applications Specification V1.0B - 39 - 16H Unload Resident Manager Description: The Unload Resident Manager function (16H) unloads the Resident Manager from memory. Unloading frees the memory the Resident Manager used, making it available for other applications. However, once the Resident Manager is unloaded, the manager functions are no longer available. For example, unloading the manager from memory suspends all pending tasks. If there is a task which is scheduled to be sent in five minutes, it will not be sent until the manager is reloaded. Once the manager is reloaded, however, it will immediately send tasks that should have been sent while it was unloaded. In addition, when the manager is not installed, you cannot receive anything. Unloading the Resident Manager from memory will fail if a terminate and stay resident (TSR) program has been loaded after the manager, if there is a polled sent, or if the manager or corresponding communications board is busy doing a task. Input: AH = Multiplex number AL = 16H BX = 1234H CX = 5678H DX = 9ABCH Return: AX = 0 if successful or a negative error code This function returns error 209H if the communications board is busy. It returns error 20BH if it can't remove the Resident Manager. - 40 - DCA/Intel Communicating Applications Specification V1.0B 17H - 80H Reserved These functions are reserved. DCA/Intel Communicating Applications Specification V1.0B - 41 - Error Codes An error code consists of two parts, an error class and an error subcode. The error class is returned in AH and the error subcode is returned in AL. The error class indicates the general type of operation in which the error occurred. Examples of general operations are: manipulation of the schedule, manipulation of a Control File, etc. The error subcode can be a DOS error code or an error code defined by the Resident Manager. Error subcodes indicate the specific kind of error that occurred. This method of handling error codes allows an application to examine either the full error code returned in AX, or the class/subcode of an error individually. Error codes are listed in the following table. All codes are in Hexadecimal. Before each listing of specific errors is a description of the error class code. The full error code (class + subcode) is listed in the Error column, and the class and subcode are listed separately in the next two columns. When these errors are returned to an application, they are returned as the negative of these codes. For example, a "No more events" error will be returned in AX as 0FDFCH which is the negative (2's complement) of 0204H. Table of Error Codes Error Class Subcode Description 0 Class: Fax warnings (not an error) 0000 0 0 No error 0002 0 2 Bad scanline count 0003 0 3 Page sent with errors, couldn't resend 0004 0 4 Received data lost 0005 0 5 Invalid or missing logo file 0006 0 6 File name doesn't match nonstandard format (NSF) header 0007 0 7 File size doesn't match nonstandard format (NSF) header 1 Class: DOS warnings; data was sent. The error subcode is the error returned by DOS. Examples are: 0101 1 1 Invalid function number 0105 1 5 Access denied 0106 1 6 Invalid handle 01xx 1 ... (See the DOS Technical Reference) 2 Class: Fatal errors. The function failed or the data was not sent. 0200 2 0 Multiplex handler failed 0201 2 1 Unknown command (bad function number) 0202 2 2 Event not found (bad event handle) 0203 2 3 Attempted to Find Next before Find First - 42 - DCA/Intel Communicating Applications Specification V1.0B Error Class Subcode Description 0204 2 4 No more events 0207 2 7 Invalid Queue type (bad Queue number) 0208 2 8 Bad Control File 0209 2 9 Communication board is busy 020A 2 A Invalid command parameter 020B 2 B Can't uninstall the Resident Manager 020C 2 C File already exists 0280 2 80 Unknown task type (not a Send or Poll event) 0281 2 81 Bad phone number 0282 2 82 Bad PCX file header 0283 2 83 Unexpected EOF 0284 2 84 Unexpected disconnect 0285 2 85 Exceeded maximum dialing retries 0286 2 86 No files specified for Send event 0287 2 87 Communication board timeout 0288 2 88 Received more than 1023 (maximum) pages of data 0289 2 89 Manual connect posted too long ago 028A 2 8A Hardware command set error 028B 2 8B Bad nonstandard format (NSF) header file 3 Class: Fatal DOS errors. The error subcode is the error returned by DOS. Examples are: 0302 3 2 File not found 0303 3 3 Path not found 03xx 3 ... (See the DOS Technical Reference Manual) 4 Class: Fax errors 0401 4 1 Remote unit not Group 3 compatible 0402 4 2 Remote unit didn't send its capabilities 0403 4 3 Remote unit requested disconnect 0404 4 4 Remote unit isn't capable of file transfers 0405 4 5 Exceeded retrain or fax resend limit 0406 4 6 Line noise or the local and remote unit don't agree on a bit rate 0407 4 7 Remote unit disconnected after receiving data 0408 4 8 No response from remote unit after sending data 0409 4 9 Capabilities of remote unit aren't compatible 040B 4 B Invalid response from remote unit after sending data 040D 4 D Phone line dead or remote unit disconnected 0411 4 11 Invalid command from remote after receiving data 0415 4 15 Tried to receive from incompatible hardware 041F 4 1F Unexpected end of file while receiving 045C 4 5C Received data overflowed input buffer 045D 4 5D Remote hardware unexpectedly stopped sending data 045E 4 5E Remote hardware didn't send any data 045F 4 5F Remote hardware took too long to send fax scan line 0463 4 63 Can't get through to remote unit 0464 4 64 User canceled event DCA/Intel Communicating Applications Specification V1.0B - 43 - Phone Number Specification Digits (0-9), phone number characters (# and *), and the following special characters have meaning in a phone number field. All other characters are ignored. P - Switch to pulse dialing T - Switch to tone dialing , - Pause ! - Signal on-hook (flash) M - Manual dial Phonebook Format The phonebook is used by Intel's Main Application (CONNECT.EXE) but may be used by other applications as well. It is not actually a part of the DCA/Intel CAS. It has an extendible format that will be very useful for many applications. A phonebook file has two major parts, a header and a data space for the variable length records. Each record has a unique record number from 0 to 999. This number is always used to refer to the record. There is an array of record offsets in the phonebook header. The offset of record N from the beginning of the file is the (4 x N)th byte in the array. An offset of 0 means that the corresponding record number is unused. There are up to 10 variable ASCIIZ fields defined for any phonebook. The application that created the phonebook defines what they are called. Each variable field has a maximum length of 60 bytes. The names of these fields are stored in the header, and the values of these fields are stored with each record. The phonebook header looks like this: Offset Length Description 0 2 ID Field: must be 1AH BBH 2 1 Major version number (from Get External Data Block, function 0EH) 3 1 Minor version number 4 2 Number of records in the file, 0 to 1000 6 2 Number of unused bytes in the file, 0 to 32766 Offset Length Description 8 2 Number of variable fields in this phonebook, 0 to 10 10 150 Array of 10 variable field names, 15 bytes apiece, as ASCIIZ strings 160 4000 Array of record offsets, 4 bytes apiece - 44 - DCA/Intel Communicating Applications Specification V1.0B When a record is deleted, an offset of 0 is placed in the offset array and the length of the record is added to the unused bytes count. When a record is changed and its new length is larger than its old length, the record is written at the end of the file, its offset in the offset array is updated, and the number of freed bytes is added onto the unused bytes count. A record is variable in length. There are two types of records: Person and Group. Person Records look like this: Offset Length Description 0 2 Record ID 2 2 Number of groups the individual belongs to. 4 2 Number of bytes the record occupies. 6 1 Record type. This is 1 for a Person Record. 7 1 Type of hardware: 0 - Limited to fax 1 - Faxes and file transfer using fax modem 2-127 Reserved 8 32 ASCIIZ name. Must NOT be blank. 40 47 ASCIIZ phone number. At least one digit or M is required. 87 var ASCIIZ variable fields var var Array of 2-byte record IDs of groups that this person belongs to. Group records look like this: Offset Length Description 0 2 Record ID 2 2 Number of members in the group 4 2 Number of bytes the record occupies 6 1 Record type. This is 2 for a group record. 7 1 File transfer capability: 0 - At least one member doesn't have file transfer capability. 1 - All members have file transfer capability. 2-127 Reserved 8 32 ASCIIZ name. Must not be blank. 40 47 reserved - must be zeros. 87 var Array of 2-byte record IDs of the members in the group. The first four fields of both record types are basically the same, so a 40- byte record header can be read in from any record. DCA/Intel Communicating Applications Specification V1.0B - 45 - PCX Format Note: This section is adapted from "Technical Documentation for PC Paintbrush & Frieze Graphics," (C) 1985 ZSoft Corporation. To obtain this document, contact ZSoft Corporation at (404) 428-0008. A PCX format file stores one page image in the form of a rectangular bitmap. PCX files have a 128-byte header followed by compressed image data. The PCX file format allows for multiple colors each with multiple shades, but Fax Mode transfers require black and white, no shades. The PCX file format also allows for different resolutions, but a PCX file for Fax Mode transfer is interpreted as having 200 pels per inch both horizontally and vertically, no matter what the file header says. The PCX file format can handle very large page sizes, but for Fax Transfer mode, the bitmap width must be a less than 1728 pels (about 8.5 inches wide). Lengths are unlimited, since fax paper comes in rolls, but 2200 pels is 11 inches, and that is the recommended maximum length for easy handling by the receiver. Pel locations can be given in X,Y coordinates where the origin is at the top left corner of the page, X increases toward the right, and Y increases toward the bottom. Data Encoding The compression technique used is a simple run length encoding, where duplicate bytes (not bits) are compressed. To compress a bitmap, it is read one horizontal line at a time from top to bottom. Each line is read from left to right. The line is read eight pels at a time (one byte). Within a byte, the most significant bit corresponds to the leftmost pel. Runs of up to 63 bytes that are all the same are stored as a run pair: a count byte followed by the byte that repeats. The count byte of a run pair has the two most significant bits set, and the 6 other bits contain the count. If a byte of data does not repeat, it is stored just as is, unless it happens to have its two most significant bits set, in which case it is stored as run pair with a repeat count of one. - 46 - DCA/Intel Communicating Applications Specification V1.0B This is the algorithm for decompressing the byte stream from a PCX file: FOR each byte, X, read from the file IF the top two bits of X are 1's BEGIN runlength = 6 lowest bits of X data = net byte following X END ELSE BEGIN runlength = 1 data = X END File Header Here is the structure at the start of a PCX file for fax images: Offset Length Description 0 1 PCX ID, Must be 0Ah. 1 1 Version info. A value of 2 is suggested. Anything higher is allowed. 2 1 Encoding method. Must be 1. 3 1 Bits per pixel. Must be 1 for Fax Mode transfer. 4 2 X position of the upper left corner, usually 0. 6 2 Y position of the upper left corner, usually 0. 8 2 X position of the bottom right corner, maximum 1728. The difference between this field and the upper left corner X position plus 1 is the width of the bitmap. This width must be a multiple of 8. 10 2 Y position of the bottom right corner, 2200 recommended maximum. 12 2 Display card horizontal resolution. Ignored in Fax Transfer mode. A value of 640 is recommended for compatibility with Intel's Graphics Editor. 14 2 Display card vertical resolution. Ignored in Fax Transfer mode. A value of 200 is recommended for compatibility with Intel's Graphics Editor. 16 48 Palette information. Ignored in Fax Transfer mode. Should be 0's. 64 1 Reserved. Must be 0. 65 1 Number of color planes. Must be 1 for Fax Transfer Mode. 66 2 Horizontal line width in bytes, equal to (XRight - XLeft + 1)/8. 68 60 Reserved. Should be 0. The data for the first line starts immediately after the header. DCA/Intel Communicating Applications Specification V1.0B - 47 - DCX Format The DCX file format allows multiple pages to be stored in one file. A DCX file has a header followed by pages. Each page is exactly the same as a PCX file, including the PCX header for each bitmap. The DCX file header starts with a 4-byte integer ID used to verify the file type. This ID is always 987654321 (decimal). After the ID is a list of offsets into the file for the pages of the document. The list is a simple array of 4-byte integers, the last of which has a value of 0 to mark the end of the array. The first page is page 0, and the offset from the beginning of the file of the nth page is stored at array location n. The array has a maximum of 1024 entries, including the 0 terminator. This means that up to 1023 pages can be stored in one DCX file, and that the maximum size of the index is 4096 bytes. The index can be smaller if fewer than 1023 pages are in the file, though this is optional. ASCII File Interpretation for Fax Transmission ASCII text files are automatically converted to graphics by the hardware as the files are sent. The hardware interprets the text file in the same manner as a nonintelligent printer with 8.5- by 11-inch paper. The full IBM 8-bit character set, including characters from 80h to FFh, is supported (see the "Characters, Keystrokes, and Colors" section of the IBM Technical Reference). These special characters are recognized: Value Description 0D Carriage return. Moves "printhead" to column 0. Line contents are NOT erased. Overstrike is OK. 0A Line feed. Current line is output. Moves the "printhead" to the beginning of the next line. 0C Form feed. Causes the current page to end, and a new page is started. The "printhead" moves to the beginning of the top line of the new page. 08 Backspace. moves "printhead" back one space. Previous character is NOT erased. Overstrike is OK. 09 Tab. Moves "printhead" to next tabstop. Tabstops are every eight columns. 1A End of file. Interpretation of the file stops. This is optional, interpretation will stop at the end of the file if this character is not present. - 48 - DCA/Intel Communicating Applications Specification V1.0B Lines that are wider than the page wrap onto the next line. After 11 inches have passed vertically from the top of the current page, a new page is started. Two text sizes are available; An 80-column by 66-line text size, and a 132-column by 88-line text size. See the section on Control Files for text size selection. DCA/Intel Communicating Applications Specification V1.0B - 49 - GLOSSARY Control File: A file created by either an application or the Resident Manager that contains information necessary to complete an Event. External Data Block (EDB): Data used by the Resident Manager that may be of use to an application. Event: An action to be performed by the Resident Manager. This action can be a fax send, a File Transfer, a Polled Send, a Polled Receive, Receive, or Log action. Event handle: A unique non zero 15-bit value that the Resident Manager assigns to an event to keep track of it. Log Control File (LCF): A Control File containing status information about a completed (or aborted) Task or Receive. This Control File is created and maintained as part of the Resident Manager's Log Queue. Non-Standard Facilities (NSF): Any format different from the Facsimile transfer format as defined in the CCITT specification. Used to transfer files directly without first translating into a bit image. Polled Receive: An Event (one of the Task Events) that allows a machine to call other machines to receive a transmission. Polled Send: An Event (one of the Task Events) that allows a machine to be called by another machine before sending a transmission. Similar to a send except that the receiving machine initiates the transaction. Queue: A data structure internal to the Resident Manager that manages Control Files. Three types of Queues exist: Task, Receive, and Log. Receive Control File (RCF): A Control File containing information about a Receive Event. It refers to data files. Resident Manager: A terminate-and-stay-resident program that manages Events in the "background." It provides the functional interface to applications. Send: A Fax or File Transfer initiated by the Host machine. Task: A Fax or File Transfer, a Polled Receive, or a Polled Send Event. Task Control File (TCF): A Control File containing information about a Task. It contains the Task type as well as a list of files to send (if needed). - 50 - DCA/Intel Communicating Applications Specification V1.0B