Liren Large Software Subsidy 5

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

/ Liren Large Software Subsidy 5 / 05.iso / a / a081 / 2.ddi / CTFXX.EXE / CAS120.TXT next >

Wrap

Text File | 1990-09-27 | 98.5 KB | 4,222 lines

DCA/Intel Communicating Applications Specification Version 1.2 Copyright π 1988, 1989, 1990. 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-004 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: SatisFAXtion 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 Recent News About CAS .................................... 1 Introduction ............................................. 5 Additional Copies of CAS ................................. 5 Programmer's Overview .................................... 6 Events and Control Files ............................ 7 Queues .............................................. 7 Using the Resident Manager .......................... 8 Group Events (V1.2) ...................................... 8 Control Files ............................................ 9 Conventions ......................................... 9 Control File Format ................................. 11 Control File Fields With Special Meanings for Group Events (V1.2) 15 File Transfer Record (FTR) .......................... 15 Group File Format (V1.2) ............................ 17 Sequence of Events for Transmitting and Receiving Files .. 18 Transmitting a Single File .......................... 18 Transmitting Multiple Files as a Single Event ....... 18 Receiving Files ..................................... 18 Transmitting to a Group (Group Send) (V1.2) ......... 19 Receiving from a Group (Group Polled Receive) (V1.2) 19 Function Table ........................................... 21 Get Installed State (00H) ................................ 22 Submit a Task (01H) ...................................... 23 Abort the Current Event (02H) ............................ 24 Find First Entry in Queue (05H) .......................... 26 Find Next Entry in Queue (06H) ........................... 28 Open a File (07H) ........................................ 29 Delete a File (08H) ...................................... 31 Delete All Files (in a queue, 09H) ....................... 32 Get Event Date (0AH) ..................................... 33 Set Task Date (0BH) ...................................... 34 Get Event Time (0CH) ..................................... 35 Set Task Time (0DH) ...................................... 36 Get External Data Block (0EH) ............................ 37 Get/Set Autoreceive State (0FH) .......................... 38 Get Current Event Status (10H) ........................... 39 Get Queue Status (11H) ................................... 40 Get Hardware Status (12H) ................................ 41 Run Diagnostics (13H) .................................... 42 Move Received File (14H) ................................. 43 Submit a Single File to Send (15H) ....................... 44 Unload Resident Manager (16H) ............................ 46 Set Cover Page Status (17H) .............................. 47 Error Codes .............................................. 49 Phonebook Format ......................................... 51 PCX Format ............................................... 53 Data Encoding ....................................... 54 File Header ......................................... 54 DCX Format ............................................... 55 ASCII File Interpretation for Fax Transmission ........... 55 DCA/Intel Communicating Applications Specification V1.2 iii Glossary ................................................. 57 iv DCA/Intel Communicating Applications Specification V1.2 DCA/Intel Communicating Applications Specification V1.2 v Recent News About CAS The following changes or enhancements have been made to the Communicating Applications Specification (CAS) in Version 1.2. These features should not be used by CAS applications designed to run on earlier CAS versions. (Refer to function OEH on page 37 for information on how to determine the CAS version number.) In this specification, version 1.2 changes and enhancements are designated with the label (V1.2). Page 8 Group Events CAS now supports group events in which the same activity is carried out between the local computer and several remote devices (fax machines or remote computers). Two types of group events are supported: Group Send and Group Polled Receive. Page 10 Phone Numbers When specifying a phone number, you can now include A, B, C, and D, which specifies the keys on the additional column of keys on some of the newer telephones. Also, W is now supported, which causes the hardware to wait for a subsequent dial tone. Page 11 Control File The following fields of the Control File are either new or have enhanced features. Refer to the description of the Control File field beginning on Page 11 for details. Offset Length Description 0 1 Event type. Group Send and Group Polled Receive event types have been added. 2 2 Status of event. A negative error code value causes the event to be submitted directly to the Log Queue. 12 47 Phone number to call (or filename of Group File). For group events, the filename of the group file is entered in this field. 140 1 Delete files flag. New field. DCA/Intel Communicating Applications Specification V1.2 - 1 - 141 2 Event handle for parent event. New field. 196 20 Reserved for internal use by CAS implementations. New field. 216 1 Cover page read flag. New field. 217 1 Suppress Page Headers. New field. Page 15 Required Fields in a Control File for a Group Event When a Control File is the parent Control File for a group event (Group Send or Group Polled Receive), certain fields of the Control File have special meaning (as described on page 15). Page 16 File Transfer Record (FTR) The File Type field (offset 0) of the File Transfer Record now supports two new file formats: HP PCL Level IV and Epson FX85 file formats. These file types are optional and are not required to be supported by all CAS implementations. Page 17 Group File Format When the event type in a Control File (offset 0) is 4 (Group send) or 5 (Group Polled Receive), the application must also create a Group File that contains information about the members of the group. The file name of the Group File must then be placed in the "Phone number to call" field of its associated Control File to link the two files. The Group File contains multiple records, one for each member of the group. Refer to Page 17 for a detailed description of the Group File format. Page 19 Transmitting and Receiving Group Events The section beginning on page 15 titled "Transmitting to a Group (Group Send)" and "Receiving from a Group (Group Polled Receive) describes the steps a programmer must follow to transmit and receive group events with CAS. Page 23 Submit a Task Function The Submit a Task function (01H) now supports Group Send and Group Polled Receive events. - 2 - DCA/Intel Communicating Applications Specification V1.2 Page 29 Open a File Function The Open a File function (07H) now supports group files. Page 40 Get Queue Status Function The Get Queue Status function (11H) supports two new values for register DL (3 and 4). These values have been added to allow applications to efficiently determine when sends and receives have occurred. Page 47 Set Cover Page Status Function The function Set Cover Page Status (17H) is a new function. It is provided to allow an application to set and clear the new Cover Page Read flag (offset 216) of the Control File. Page 49 Error Codes Two new classes of error codes have been added: Class 5 for application specific errors and Class 6 for CAS implementation specific errors. Also, two new class 4 error codes have been defined: 040AH (No dial tone - check phone line and cord) and 040EH (Timeout while waiting for secondary dial tone). DCA/Intel Communicating Applications Specification V1.2 - 3 - - 4 - DCA/Intel Communicating Applications Specification V1.2 Introduction The DCA/Intel Communicating Applications Specification (CAS) defines a standard, high-level programming interface for data communications applications. It offers software developers a simple and straightforward method for adding data communications functions to their products. This interface is independent of the hardware and software used to implement the underlying communications facilities. This shields software developers from the details typically associated with using communications hardware. It also permits developers to code their applications to the interface and to be assured that their applications will work with new generations of hardware products. CAS is designed to support a wide variety of communications hardware. Version 1.2 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, CAS will evolve to add functions appropriate for other hardware. Version 1.2 of CAS requires DOS 3.0 or later. Additional Copies of CAS To obtain additional copies of this specification, contact Intel at one of the following numbers: (503) 629-7000 (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 an ASCII version of this specification if you have a touch-tone phone and an Intel fax board (Connection CoProcessor or SatisFAXtion). FaxBack is available 24 hours a day. You can reach FaxBack by calling: (800) 525-3019 (Inside the U.S. or Canada) (503) 629-7576 (Outside the U.S. or Canada) The document number is 0006. DCA/Intel Communicating Applications Specification V1.2 - 5 - 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. - 6 - DCA/Intel Communicating Applications Specification V1.2 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 receives information Receive (V1.2) 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. DCA/Intel Communicating Applications Specification V1.2 - 7 - 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. - 8 - DCA/Intel Communicating Applications Specification V1.2 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. The format of the date is: DCA/Intel Communicating Applications Specification V1.2 - 9 - 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. 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 A,B,C,D Specifies keys in the additional column of keys (that is, the 1633 Hz high-group frequency) on some telephones. (V1.2) , Causes the hardware to pause when dialing. ! 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). When used, this character must be the first character in the phone number. W Causes the hardware to wait for a subsequent dial tone. This is useful when waiting for a tone for an outside line. (V1.2) All other characters are reserved. - 10 - DCA/Intel Communicating Applications Specification V1.2 Control File Format Listed below is the general format of a Control File. The fields preceded by bullets (■■) are fields the application must fill in when creating a Control File. Other fields are filled in by the Resident Manager and must be set to 0 when creating the Control File. For a receive 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 - Group Send (V1.2) 5 - Group Polled Receive (V1.2) 6-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, 3, 4, or 5. The value 1 is used by the Resident Manager when creating a Control File for a receive event. The value -1 is not valid for Control Files and results in an error. ■■ 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 send events (this field doesn't apply for polled receive or group polled receive events). For file transfers, the sending Resident Manager supplies information from the Control File as a header for the file transmission. The receiving Resident Manager can then use this header information to create a Control File for the receive event. DCA/Intel Communicating Applications Specification V1.2 - 11 - Offset Length Description 2 2 Status of event: 0 - Successfully completed. 1 - Waiting to be processed. 2 - Number dialed or event in progress. 3 - Connection made -- sending. 4 - Connection made -- receiving. 5 - Event was aborted. 6-32,767 - Reserved. Negative value - Error. Note: The Resident Manager ordinarily sets the value in this field to indicate the status of the event. When the Control File is created, this field should normally be set to "0." (The following information is new for V1.2.) If the field is set to a negative value when the event is submitted (for example, if it is set to one of the class 5 error codes), the event will be added directly to the Log Queue and will not be processed. (Refer to the section later in this section titled "Error Codes.") ■■ 4 2 Time you want to send the information (used for send events only). For receive events, this is the time the receive event occurred. The format is in DOS file date and time format. ■■ 6 2 Date you want to send the information (used for send events only). 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 (or filename of Group File (V1.2)), as an ASCIIZ string. For non-group events, place a phone number in this field. (The following information is new for V1.2.) For group events, place the filename of the Group File (without specifying the drive or path) in this field. The Group File must be in the same directory as the Control File for the parent event when the event is submitted. - 12 - DCA/Intel Communicating Applications Specification V1.2 Offset Length Description 59 64 Application-specific tag field, as an ASCIIZ string. 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 is received as a file transfer this field will have meaning in the Control File for the receive event. If a file is received 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). Has no meaning for parent Control Files. 125 1 Time length of phone connection: minutes (0-59). Has no meaning for parent Control Files. 126 1 Time length of phone connection: hours (0-23.) Has no meaning for parent Control Files. 127 4 Total number of pages in all files. Has no meaning for parent Control Files. 131 4 Number of pages transmitted so far. Has no meaning for parent Control Files. 135 2 Number of files transmitted so far. Has no meaning for parent Control Files. ■■ 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. Has no meaning for parent Control Files. ■■ 140 1 Delete files flag (V1.2). Determines whether or not the files listed in the File Transfer Records (FTRs) are deleted after the event is completed. (The FTR use and format is describe later in this specification in the section titled "File Transfer Record (FTR).") 0 - Don't delete files after event 1 - Delete files if successful 2 - Always delete files after event 3-127 - Reserved. DCA/Intel Communicating Applications Specification V1.2 - 13 - Offset Length Description Note: This field is valid in a Control File for event types 0 (send), 2 (polled send), and 4 (group send). If the event type is a group send and the value of the delete files flag is 1 (delete if successful), the files will only be deleted if all sub-events have been successfully completed. If the event is a group send and the value of the flag is 2 (always delete), the files will be deleted after all sub-events have been attempted. If the delete files flag is set to 2 (always delete), the files will always be deleted whether the event is successful, cancelled by the user, or aborted during transmission due to line or board errors. 141 2 Event handle for parent event (V1.2). The Resident Manager assigns this handle. Initialize to zero. This handle is zero if there is no parent event. 143 53 Reserved. Set to zero. 196 20 Available for internal use by CAS implementations (V1.2). Set to zero. This field is available for CAS implementations to use for internal flags and other features. 216 1 Cover page read flag (V1.2). Initialize to zero. The application can use CAS function 17H to set this field to indicate whether or not the user has read the cover page. 0 - cover page not read 1 - cover page read 2-127 - reserved ■■ 217 1 Suppress Page Headers (V1.2). This field only has meaning for faxes. Setting this field to 1 causes the line of fax addressing information at the top of each fax page to be suppressed. 0 - Page Headers 1 - No Page Headers 2-127 - reserved 218 21 Remote CSID (the CCITT identification of the fax device), as an ASCIIZ string (set by the Resident Manager). Set to zero. ■■ 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. A fully qualified pathname for the file (including the drive) must be entered. ■■ 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. - 14 - DCA/Intel Communicating Applications Specification V1.2 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. Control File Fields With Special Meanings for Group Events (V1.2) If the event type for a Control File is 4 (Group Send) or 5 (Group Polled Receive), the fields shown below for the parent event's Control File have the following functions: Offset Length Description 1 1 Transfer Type. Not used for group events. The transfer type for each member event is defined in the group file. 12 47 Filename of Group File. ASCIIZ string that must be a DOS filename. Do not give the path. This file must be in the same the directory as the parent Control File when the group event is submitted. 239 32 Destination Name, ASCIIZ string. For group events, this field can contain a group identifier (or it can be left blank). 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 (■■) 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 file type, text size, and page length fields. In both cases, set the other fields to zero. DCA/Intel Communicating Applications Specification V1.2 - 15 - 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-15 Reserved 16-31 - (V1.2) Reserved for printer file formats. At this time, code 16 is assigned to the HP PCL Level IV file format and code 17 is assigned to the Epson FX85 format. These codes are optional and may not be supported by all CAS implementations. 32-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. Has no meaning for parent Control Files. 7 4 Size in bytes of this file. 11 2 Number of pages in this file transmitted so far. Has no meaning for parent Control Files. 13 2 Number of pages in this file. ■■ 15 80 Path and name of file to send, as an ASCIIZ string. A fully qualified pathname for the file (including the drive) must be entered. ■■ 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. - 16 - DCA/Intel Communicating Applications Specification V1.2 Group File Format (V1.2) When the event type in a Control File (offset 0) is 4 (Group send) or 5 (Group Polled Receive), the application must also create a Group File that contains information about the members of the group. The file name of the Group File must then be placed in the "Phone number to call" field of its associated Control File to link the two files. No pathname is given for the Group File. Instead, the Group File must reside in the same directory as its associated Control File. The Group File contains multiple records, one for each member of the group. Note: Entries in this file must be for individuals. There is no mechanism for nesting groups. A record in the Group File has the following format: Offset Length Description 0 1 Transfer type for individual sub-event. Values are 0 - 200x200 dpi, fax mode 1 - 100x200 dpi, fax mode 2 - File transfer mode 3-127 - Reserved 1 2 Individual status. The status of a sub-event. Set to zero. Values correspond to the Status of Event field in a Control File: 0 - Successfully completed 1 - Waiting to be processed 2 - Number dialed or event in progress 3 - Connection made -- sending 4 - Connection made -- receiving 5 - Event was cancelled 6-32767 - Reserved Negative numbers - Error. 3 47 Phone Number to Call. This is the phone number of the group member this record pertains to. An ASCIIZ string. 50 32 Destination Name. The group member's destination name as an ASCIIZ string. 82 2 Event Handle. This is the event handle of the sub-event associated with this group member. The Resident Manager assigns this value. Initialize to zero. 84 44 Reserved. 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. DCA/Intel Communicating Applications Specification V1.2 - 17 - 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. 3. Create a 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 Control File for the receive event.. 4. For each File Transfer Record in the 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 Control File and continue with step 8. - 18 - DCA/Intel Communicating Applications Specification V1.2 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 Control File. 7. Invoke function 08H (Delete a File) to delete the 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. Transmitting to a Group (Group Send) (V1.2) 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 (or files) you wish to transmit. 3. Create a parent Control File that includes one File Transfer Record (FTR) for each file you wish to transmit. Include the filename of the group file for the event (created in step 4) in the phone number field (offset 12) of the Control File. 4. Create a Group File that includes one record for each member of the group you are transmitting data to. 5. Invoke function 01H (Submit a Task). 6. Check for errors in sending. Receiving from a Group (Group Polled Receive) (V1.2) 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 a parent Control File for a group polled receive event. Include the filename of the group file for the event (created in step 3) in the phone number field (offset 12) of the Control File. 3. Create a Group File that includes one record for each member of the group you are receiving from. 4. Invoke function 01H (Submit a Task). 5. Perform the steps described above in the section titled "Receiving Files." DCA/Intel Communicating Applications Specification V1.2 - 19 - - 20 - DCA/Intel Communicating Applications Specification V1.2 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 Set Cover Page Status (V1.2)...........................17H Reserved.........................................18H - 80H DCA/Intel Communicating Applications Specification V1.2 - 21 - 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 (0EH) - 22 - DCA/Intel Communicating Applications Specification V1.2 01H Submit a Task Description: The Submit a Task function (01H) schedules a send, a polled send, a polled receive, a group send, or a group polled receive event. Before invoking this function, you must first create a Control File for the event (and a group file if the event is a group send or group polled receive event). The function adds this 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. Once the event is completed, the Resident Manager automatically moves the Control File for the event from the Task Queue to the Log Queue (that is, copies the Control File from the Task Queue to the Log Queue, renames the copy, and deletes the original Control File from the Task Queue). For Polled Receive events, a copy of the Control File is also placed in the Receive Queue. (The following information is new for V1.2.) For group events, the parent Control File and the Group File are moved to the Log Queue when the task is complete. Input: AH = Multiplex number AL = 01H DS:DX points to ASCIIZ path and name of Control File Return: AX = Positive event handle or negative error code Note: Files associated with a event must remain in existence until the event is complete or an error results. See Also: Submit a Single File to Send (015H) DCA/Intel Communicating Applications Specification V1.2 - 23 - 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) - 24 - DCA/Intel Communicating Applications Specification V1.2 03H - 04H Reserved These functions are reserved. DCA/Intel Communicating Applications Specification V1.2 - 25 - 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 dialed or event in progress. 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. - 26 - DCA/Intel Communicating Applications Specification V1.2 05H Find First Entry in Queue If the queue is empty, this function returns error code 204H (no more events) in the AX register. Note that the number in register AX is the negative (2's complement) of the error code (that is, FDFCH.) See Also: Find Next Entry in Queue (06H) Open a File (07H) DCA/Intel Communicating Applications Specification V1.2 - 27 - 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 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) - 28 - DCA/Intel Communicating Applications Specification V1.2 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 event 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. The application should use the normal DOS function (3EH) to close that handle when it is finished with it. 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 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. 3 - Open group file in Task Queue (V1.2) 4 - Open group file in Log Queue (V1.2) DCA/Intel Communicating Applications Specification V1.2 - 29 - 07H Open a File Return: AX = 0 if successful or a negative error code. BX = DOS file handle for the requested file. See Also: Submit a Task (01H) Find First Entry in Queue (05H) Find Next Entry in Queue (06H) Move Received File (14H) - 30 - DCA/Intel Communicating Applications Specification V1.2 08H Delete a File Description: The Delete a File function (08H) deletes one or more files in a specific Queue. Note: The delete files flag (offset 140) in the Control File for an event can cause the Resident Manager to automatically delete all the files associated with the event after the event has been successfully completed (flag set to 1) or after the event has been attempted (flag set to 2). 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 Control File (including the 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 and corresponding Group File, if it exists. 1 - Delete a file or files associated with an event in the Receive Queue. 2 - Delete Control File in Log Queue and corresponding Group Log File if it exists. 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.2 - 31 - 09H Delete All Files (in a queue) Description: The Delete All Files function (09H) deletes all Control Files in the specified queue Input: AH = Multiplex number AL = 09H DL = Queue: 0 - Delete all Control Files in the Task Queue, including all Group Files. 1 - Delete all Control Files in the Receive Queue and all received files. 2 - Delete all Control Files in the Log Queue, including all Group Files. Return: AX = 0 if successful or a negative error code See Also: Delete A File (08H) - 32 - DCA/Intel Communicating Applications Specification V1.2 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) See Also: Set Task Date (0BH) Get Event Time (0CH) DCA/Intel Communicating Applications Specification V1.2 - 33 - 0BH Set Task Date Description: The Set Task Date function (0BH) sets the execute date of a Control File specified by the event handle. This function is valid only for events that the local computer initiates. Note: Setting the date for an event to a value that is earlier than the current date (or setting registers CX, DH, and DL to zero) 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) Return: AX = 0 if successful or a negative error code See Also: Get Event Date (0AH) Set Task Time (0DH) - 34 - DCA/Intel Communicating Applications Specification V1.2 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 See Also: Get Event Date (0AH) Set Task Time (00H) DCA/Intel Communicating Applications Specification V1.2 - 35 - 0DH Set Task Time Description: The Set Task Time function (0DH) sets the execute time of a Control File specified by the event handle. This function is valid only for events in the Task Queue, not for events in the Receive or Log Queues. Note: Setting the time for a event to a value that makes the date and time earlier than the current date and time causes the transmission to occur immediately. Setting the time to zero (setting registers CH, CL, and DH to zero) selects 12:00 AM. 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. Return: AX = 0 if successful or a negative error code See Also: Set Task Date (0BH) Get Event Time (0CH) - 36 - DCA/Intel Communicating Applications Specification V1.2 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 the pathname of the directory containing Resident Manager configuration files and other software that implements 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.2 - 37 - 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 - 38 - DCA/Intel Communicating Applications Specification V1.2 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). If there is no current event, error code 202H is returned. Note that the number in register BX is the negative (2's complement) of the error code (that is, FDFEH.) 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.2 - 39 - 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 3 - Find status of Send Events 4 - Find status of Receive Events Return: If DL = 0, 1, or 2 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. If DL = 3 (V1.2) AX = Number of successful sends since the Resident Manager was started, including events cancelled by the user. BX = Number of unsuccessful sends since the Resident Manager was started, including warnings. If DL = 4 (V1.2) AX = Number of received file transfer events since the Resident Manager was started BX = Number of received fax events since the Resident Manager was started - 40 - DCA/Intel Communicating Applications Specification V1.2 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.2 - 41 - 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 non-negative 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. - 42 - DCA/Intel Communicating Applications Specification V1.2 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.2 - 43 - 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 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. The file sent using this function must be in ASCII, PCX, or DCX format. 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 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. Offset Length Description 6 32 Destination Name, as an ASCIIZ string (To: field) 38 80 Path and name of the file to send, as an ASCIIZ string - 44 - DCA/Intel Communicating Applications Specification V1.2 15H Submit a Single File to Send 118 47 Phone number to call, as an ASCIIZ string 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. The file is not deleted when the event is completed. See Also: Submit A Task (01H) DCA/Intel Communicating Applications Specification V1.2 - 45 - 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 events. If there is a event 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 events 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 send, or if the manager or corresponding communications board is busy doing a event. 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. - 46 - DCA/Intel Communicating Applications Specification V1.2 17H Set Cover Page Status (V1.2) Description: The Set Cover Page Status function (17H) sets the Cover Page Read flag (offset 216) in the Control File for the specified event. The Resident Manager checks the Log Queue and the Receive Queue for the specified Control File. This function and the Cover Page Read flag provide applications with a means of recording whether or not the user has read the cover page. Input: AH = Multiplex number AL = 17H BX = Event handle CL = Cover page status 0 - Not read 1 - Read Return: AX = 0 if successful or a negative error code DCA/Intel Communicating Applications Specification V1.2 - 47 - 18H - 80H Reserved These functions are reserved. - 48 - DCA/Intel Communicating Applications Specification V1.2 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 Receive 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 - 49 - DCA/Intel Communicating Applications Specification V1.2 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, data not sent. 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 040A 4 A No dial tone - check phone line and cord (V1.2) 040B 4 B Invalid response from remote unit after sending data 040D 4 D Phone line dead or remote unit disconnected 040E 4 E Timeout while waiting for secondary dial tone (V1.2) 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 - 50 - DCA/Intel Communicating Applications Specification V1.2 Error Class Subcode Description 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 5 Class: Application specific errors (V1.2) Applications can use the class 5 error codes to record information specific to an application in a Control File in the Log Queue. To do this, the application must set the status of event field (offset 2 in the Control File) to the negative value (2's complement) of the selected error code. For example, if the error code is 501H, the status of event field is set to FAFFH. When the application submits the event to the Task Queue, using the Submit a Task function (01H), the Resident Manager bypasses the Task Queue and places the Control File directly on the Log Queue. The status of event field then contains the error code. 6 Class: CAS implementation specific errors (V1.2) Manufacturers implementing CAS can use the class 6 error codes to define additional error conditions unique to their hardware. Manufacturers are urged to use these codes sparingly since they will not be consistent across all CAS implementations. Be sure to document class 6 error codes clearly in end-user documentation so that users can interpret these codes correctly if CAS applications display them. Phonebook Format This phonebook format is used by Intel's fax applications, 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. DCA/Intel Communicating Applications Specification V1.2 - 51 - 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 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 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. - 52 - DCA/Intel Communicating Applications Specification V1.2 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. 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 not exceed 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. DCA/Intel Communicating Applications Specification V1.2 - 53 - 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. (No line wrapping is performed.) 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. 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 1727. 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. - 54 - DCA/Intel Communicating Applications Specification V1.2 Offset Length Description 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. 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 page length can be set to other lengths using the Page Length fields of the FTR (offsets 95 and 96). 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. DCA/Intel Communicating Applications Specification V1.2 - 55 - 0A Line feed. Current line is output. Moves the "printhead" to the beginning of the next line. - 56 - DCA/Intel Communicating Applications Specification V1.2 Value Description 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. 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 earlier in this specification titled "Control Files" for information on text size selection.) Lines should not be wider than the page width. After 11 inches have passed vertically from the top of the current page, a new page is started. DCA/Intel Communicating Applications Specification V1.2 - 57 - Glossary Control File: A file created by either an application or the Resident Manager that contains information needed to complete an event or information about an already completed event. Current Event: The communications event that the hardware is currently processing. While an event is the current event, its Control File is not in any of the Resident Manager's queues. 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 Send (fax or file), a Polled Send, a Polled Receive, a Receive (fax or file), a Group Send (V1.2), or a Group Polled Receive (V1.2). Event handle: A unique non-zero 15-bit value that the Resident Manager assigns to an event to keep track of it. Group (V1.2): A selection of remote devices that you are going to send the same file (or set of files) to or that you are going to receive information from. Two types of events use groups: Group Send and Group Polled Receive. Group File (V1.2): A file that lists the individual destinations for a group event. Group Polled Receive (V1.2): An event in which the local computer calls a group of remote devices to receive information. Group Send (V1.2): An event in which one or more files are sent to a group of remote devices. Log Queue: A queue of Control Files and group files for events that have been completed (or aborted). 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. Parent Control File (V1.2): The Control File for a Group Send or Group Polled Receive event. Polled Receive: An event that allows a machine to call other machines to receive a transmission. Polled Send: An event 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. - 58 - DCA/Intel Communicating Applications Specification V1.2 Receive: An event (Fax or file transfer) in which a local computer receives data from a remote device. Receive Queue: A queue of controls files for events that the local computer has received. Resident Manager: A terminate-and-stay-resident program that manages events in the "background." It provides the functional interface to applications. Send: An event (Fax or file Transfer) in which the local computer sends data to a remote device. Task Queue: A queue of Control Files for send, polled send, polled receive, group send, or group polled receive events that are waiting to be executed. DCA/Intel Communicating Applications Specification V1.2 - 59 -