Implementation-Specific Information for Intel Communications Products Supporting the DCA/Intel Communicating Applications Specification April 1993 Copyright (C) 1988-1993. All rights reserved. Intel Corporation 5200 N.E. Elam Young Pkwy. Hillsboro, OR 97124-6497 The information in this document has been developed by Intel Corporation. Although it has been released into the public domain and is not confidential or proprietary, this document is still the copyright and property of Intel Corporation. Disclaimer of Warranty INTEL CORPORATION EXCLUDES ANY AND ALL IMPLIED WARRANTIES, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. INTEL MAKES NO WARRANTY OF REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS SPECIFICATION, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. INTEL SHALL HAVE NO LIABILITY FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RESULTING FROM THE USE OR MODIFICATION OF THIS DOCUMENT. This document 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. ***************************************************************************** Introduction This document lists the CAS implementation-specific information for the Intel SatisFAXtion board, the Intel Connection CoProcessor board, and CASModem implementations (Class1, Class2, & SendFAX). It also describes the EP2DCX program for converting Epson FX-85 format files to DCX files. The two functions Get Hardware Status (12H) and Run Diagnostics (13H) return information that varies depending on the kind of hardware used to implement the specification. Be aware that if your code relies on the information returned by these functions, that code might not work correctly on hardware other than the Intel SatisFAXtion board or the Intel Connection CoProcessor board. In addition, Intel reserves the right to change without notice the information these functions return. Note: As of this writing, the Intel Connection CoProcessor board supports CAS Version 1.0 and the Intel SatisFAXtion board supports CAS Version 1.2. CAS Version 1.2 is a superset of Version 1.0 (that is, programs written to run on CAS Version 1.0 will also run on CAS Version 1.2). Caution: Normal foreground applications can make CAS calls at any time. However, because the Intel implementation of CAS may perform DOS file I/O operations when a CAS function is called, TSRs (terminate and stay resident programs) or other programs that run in the background should not make CAS calls when DOS file I/O cannot be performed. Normally, DOS file I/O cannot be performed when the DOS busy flag is set, except in a DOS idle interrupt service routine (int 28H). 12H - Get Hardware Status ------------------------- Description: The Get Hardware Status function (12H) returns the status of the communication hardware in the form of a 128-byte data structure. The calling program determines where the data structure is to be placed by setting the DS:DX registers to point to a 128-byte area in memory. Caution: The data structure and values returned by this function are hardware-dependent and will vary according to type of hardware used to implement the CAS services. To make your programs hardware independent, it is recommended that when possible 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, negative if not. If successful, the function fills the status area with hardware-dependent status information. See Also: Get Current Event Status (10H) Get Queue Status (11H) Returned Data Structure: ------------------------ The format of the data area pointed to by DS:DX is as follows, depending on whether the hardware is an Intel SatisFAXtion board, CASModem implementation, or an Intel Connection CoProcessor board. (In the following description, bits that are "set" have a value of 1.) SatisFAXtion Board: Offset Length Description 0 1 Bit fields indicating the status of the connection: Bit Description 0 Data modem in use. When this bit is set to 1, the fax image modem cannot be used until the data modem has hung up the connection. 1 Resolution of the fax image for the current page: 1 indicates coarse resolution (200 dpi x 100 dpi) and 0 indicates fine resolution (200 dpi x 200 dpi). 2 If set to 1, data buffer dumped on receive. 3 If set to 1, data is in the buffer. 4 If set to 1, the current mode is file transfer mode. 5 If set to 1, request for retransmit of last page has been made. 6 If set to 1, there is no data on the current page or file. This bit is only used when block transfers of pages or files is taking place. 7 If set to 1, the board is busy in T.30 CCITT fax protocol. 1 1 Board State Bits Description 0-2 T.30 CCITT protocol state. 2 1 0 Action State 0 0 0 Idle None 0 0 1 Dialing A 0 1 0 Answering A 0 1 1 Transmitting C 1 0 0 Receiving C 1 0 1 Pre-message B 1 1 0 Post-message D 1 1 1 Disconnect E 3-5 & 7 Current bit rate. 7 5 4 3 0 0 0 0 300bps 0 1 0 0 2400bps 0 1 0 1 4800bps 0 1 1 0 7200bps 0 1 1 1 9600bps 1 0 0 0 12200bps 1 0 0 1 14400bps 6 Handset jack active (off-hook). When this bit is set to 1, neither the fax image modem nor the data modem can be used (except for the current connection send or receive) until the device connected to the handset jack has been placed back on-hook. 2 1 Number of KBytes free in the buffer. 3 1 Number of pages or files in the buffer 4 1 Number of retries left to dial this number. The user sets the initial retry value in the SatisFAXtion SETUP program. The value is then automatically decremented each time a call is attempted. 5 1 Fax page number to retransmit. Used in conjunction with the "request for retransmit of last page" flag (offset 0, bit 5). 6 1 Current block transfer page or file. Number of the current page or file that is being transferred between the resident manager and the board (not necessarily the page or file that is currently being transmitted over the phone line). 7 1 Number of rings detected when receiving a call. Rings are counted only if auto-answer is enabled. 8 2 Error count. A 16 bit unsigned integer (byte 9 is most significant byte) that indicates the number of errors that have occurred during the connection. 10 4 Length of file being transferred in file transfer mode. 14 6 Reserved 20 1 FAX Hardware Type B = Satisfaxtion & Satisfaxtion 200 C = Net Satisfaxtion D = Satisfaxtion 400 E = Class 1 fax F = Class 2 fax G = Send Fax 21 13 Transfer agent name; ASCII string, null terminated. 34 5 Transfer agent version number; ASCII string, null terminated. 39 13 Resident loader name; ASCII string; null terminated. 52 5 Resident loader version number; ASCII string, null terminated. 57 21 Remote CSID; ASCII string, null terminated. 78 13 Resident manager name; ASCII string, null terminated. 91 5 Resident manager version number; ASCII string, null terminated. 96 32 Reserved. CASModem Implementations: Offset Length Description 0 1 Bit fields indicating the status of the connection: Bit Description 0 Data modem in use. When this bit is set to 1, the fax image modem cannot be used until the data modem has hung up the connection. 1 Resolution of the fax image for the current page: 1 indicates coarse resolution (200 dpi x 100 dpi) and 0 indicates fine resolution (200 dpi x 200 dpi). 2 Not used. 3 " ". 4 " ". 5 If set to 1, request for retransmit of last page has been made. 6 If set to 1, there is no data on the current page or file. This bit is only used when block transfers of pages or files is taking place. 7 If set to 1, the board is busy in T.30 CCITT fax protocol. 1 1 Board State Bits Description 0-2 T.30 CCITT protocol state. 2 1 0 Action State 0 0 0 Idle None 0 0 1 Dialing A 0 1 0 Answering A 0 1 1 Transmitting C 1 0 0 Receiving C 1 0 1 Pre-message B 1 1 0 Post-message D 1 1 1 Disconnect E 3-5 & 7 Current bit rate. 7 5 4 3 0 0 0 0 300bps 0 1 0 0 2400bps 0 1 0 1 4800bps 0 1 1 0 7200bps 0 1 1 1 9600bps 1 0 0 0 12200bps 1 0 0 1 14400bps 6 Not used (always 0) 2 1 Not Used. 3 1 " " . 4 1 Number of retries left to dial this number. The user sets the initial retry value in the SatisFAXtion SETUP program. The value is then automatically decremented each time a call is attempted. 5 1 Fax page number to retransmit. Used in conjunction with the "request for retransmit of last page" flag (offset 0, bit 5). 6 1 Current block transfer page or file. Number of the current page or file that is being transferred between the resident manager and the board (not necessarily the page or file that is currently being transmitted over the phone line). 7 1 Number of rings detected when receiving a call. Rings are counted only if auto-answer is enabled. 8 2 Not used (always 0). 10 4 Length of file being transferred in file transfer mode. 14 6 Reserved. 20 1 FAX Hardware Type. B = Satisfaxtion & Satisfaxtion 200 C = Net Satisfaxtion D = Satisfaxtion 400 E = Class 1 fax F = Class 2 fax G = Send Fax 21 13 Transfer agent name; ASCII string, null terminated. 34 5 Transfer agent version number; ASCII string, null terminated. 39 13 Resident loader name; ASCII string; null terminated. 52 5 Resident loader version number; ASCII string, null terminated. 57 21 Remote CSID; ASCII string, null terminated. 78 13 Not Used. 91 5 " ". 96 2 Port I/O Address. 98 1 IRQ#. 99 9 ASCIIZ Board ID 108 20 Reserved. Connection CoProcessor Board: Offset Length Description 0 1 Bit fields indicating the status of the transmission: 0-2 Reserved. 3 Set if file transfer mode is active 4-6 Reserved 7 Set if the hardware is busy sending or receiving 1 2 Reserved 3 1 Number of retries left to dial this number. The user sets the initial retry value in the Connection CoProcessor's INSTALL or SETUPCC programs. 4 1 Reserved 5 1 Bit fields indicating the phone line status: 0-2 Hardware sequence state 2 1 0 0 0 0 Idle 0 0 1 Dial 0 1 0 Answer 0 1 1 Transmit 1 0 0 Receive 1 0 1 Pre-message 1 1 0 Post-message 1 1 1 Disconnect 3 Set if buffer dumped on receive 4 Set if ring detected and auto-answer is enabled 5 Set if off hook (on line) 6 Set if Connection CoProcessor will be sending data 7 Reserved 6 1 Bit fields indicating the baud rate status 0-3 Reserved 4-6 Bit Rate Modem Mode 6 5 4 0 0 0 300 baud V.21 (HDLC) 1 0 0 2400 baud V.27 ter 1 0 1 4800 baud V.27 ter 1 1 0 7200 baud V.29 1 1 1 9600 baud V.29 7 Reserved 7 3 Reserved 10 1 Bit fields indicating additional hardware status: 0 Set if line length compensation bit 0 is set 1 Set if line length compensation bit 1 is set 2 0 - DMA channel 3 is in use 1 - DMA channel 1 is in use 3 Reserved 4 Set if ring is detected 5 Set if off hook 6 Set if Connection CoProcessor has control of the DAA (not latched) 7 Set if modem option is installed 11 1 Bit fields indicating configuration of COM ports, Interrupts, and I/O ports: 0-2 2 1 0 COM Port IRQ I/O port 0 0 1 COM 1 IRQ 4 I/O ports 3F8h - 3FFh 0 0 0 COM 2 IRQ 3 I/O ports 2F8h - 2FFh 0 1 1 COM 3 IRQ 4 I/O ports 3E8h - 3EFh 0 1 0 COM 4 IRQ 3 I/O ports 2E8h - 2EFh 1 1 1 COM 3 IRQ 5 I/O ports 3E8h - 3EFh 1 1 0 COM 4 IRQ 2 I/O ports 2E8h - 2EFh 3-7 Reserved 12 1 Bit fields indicating additional hardware status: 0 Set if 2400 bps (V.27 ter) enabled 1 Set if 4800 bps (V.27 ter) enabled 2 Set if 7200 bps (V.29) enabled 3 Set if 9600 bps (V.29) enabled 4-7 Reserved 13 1 Reserved 14 2 Error count (received errors or retransmission requests). This value is valid only when the Connection CoProcessor is busy. Thus it is reset when the board is idle. 16 4 Reserved 20 1 The character "A" if the Connection CoProcessor board is present. 21 9 Reserved. 30 21 CSID of the remote hardware 51 77 Reserved 13H - Run Diagnostics Description: The Run Diagnostics function (13H) runs a set of diagnostics on the board or reports on their progress. The value in register DL determines the action of function. Input: AH = Multiplex number AL = 13H DL = Mode: 0 - Report progress of diagnostics 1 - Start running diagnostics Return: Information about the diagnostics is returned in register AX, as described below: DL = 1 Start Running Diagnostics. Either a 0 (diagnostics successfully begun) or a negative error code is returned in AX. The error code is one of the CAS error codes (such as, Communications Board Busy). DL = 0 Report Progress of Diagnostics. One of the following values is returned in AX: Value Condition 0040H diagnostics in process 0000H diagnostics passed 1???H diagnostics failed If a negative number is returned, the individual bits of AX contain the information shown below, depending on the type of hardware being used (that is, SatisFAXtion board or Connection CoProcessor board.) (In the following description, bits that are "set" have a value of 1.) SatisFAXtion: Bits of AX Description 0 Set if 9600 bps fax modem device failed 1 Set if 2400 bps data modem device failed 2-15 Reserved CASModem Implementation: Diagnostics always succed for Class1, Class2, & SendFAX hardware. Connection Coprocessor: Bits of AX Description 0 Set if ROM checksum failed 1 Set if RAM failed 2 Set if SDLC chip failed 3 Set if 9600 bps fax modem module failed 4-15 Reserved ***************************************************************************** CAS Class 5 Errors Specific to FAXPOP.EXE Note: This section describes the CAS Class 5 errors that Intel's FAXPOP.EXE application uses. If your application does not log Class 5 errors, you can skip this section. A CAS 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; the error subcode indicates the specific kind of error that occurred. Class 5 error codes are reserved for application- specific errors. The Intel fax pop-up shipped with the SatisFAXtion board (FAXPOP.EXE) uses the CAS class 5 error codes listed in the following table. All codes are in hexadecimal. The full error code (class plus 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, the "Insufficient disk space" error code is returned in AX as FAFFH which is the negative (2's complement) of 0501H. Table of Error Codes Error Class Subcode Description 0500 5 00 Tried to send while in graphics mode 0501 5 01 Insufficient disk space 0502 5 02 Internal buffer overflow When FAXPOP Logs Class 5 Errors Normally, when FAXPOP detects an error, an error message is displayed on the monitor screen in a pop-up window. However, if the screen is in graphics mode and the user has set the SatisFAXtion software to not allow the pop-up to be displayed when in graphics mode, error messages cannot be displayed on the screen. Instead, they are logged as events in the log queue, using the class 5 error codes. The only information that is valid in this event record is the error code. **************************************************************************** PRN2FAX The Intel SatisFAXtion board and the FAX software allow any file that is in ASCII, DCX, or PCX format to be sent as a fax. The Intel FAXPOP program also allows a file that is in Epson FX-85 or HP-PCL-5 format to be sent as a fax. FAXPOP does this by converting the file from Epson FX or HP-PCL-5 format to DCX format. The program PRN2FAX.EXE (a small, command-line driven program , which is included with the SatisFAXtion board software) performs this same conversion. You will find more information on the PRN2FAX utility in the manual for your Intel fax card. Other applications software can use the PRN2FAX program to facilitate the sending of faxes directly from the application. For example, if a word processor provides output in Epson FX format, the word-processor software can execute PRN2FAX to convert the Epson FX output to DCX format. The resulting file can then be submitted to CAS and sent through a SatisFAXtion board or Connection CoProcessor board as a fax. Note: An Intel fax board must be installed to run PRN2FAX; otherwise, an error is generated. The following section describes the PRN2FAX command line format and parameters and the errors codes and messages that PRN2FAX generates. The printer-to-dcx DOS command line utility converts an Epson FX-85, PCL-5, or ASCII print file to a dcx-format file, suitable for submission to CAS for sending as a fax. The FX-85 printer is specifically emulated, but the entire Epson FX series of printers uses a similar command set, so print files designated for any Epson FX-series printer should work satisfactorily. The PCL-5 emulation does not support a few major features, namely HP-GL graphics commands, and print image modeling. All of the bitmap fonts and scalable typefaces that are built into the LaserJet III printer are supported, as well as all of the bitmap fonts found in HP's A-Z cartridges. The command line syntax to invoke the utility is: prn2fax [d:]infile[.ext] [d:][outfile.[ext]] /type [/p] [/s] [/o] [/help] [/?] Parameters enclosed in square brackets [] are optional. The parameters are described on the following page. Notes on parameters: infile - Any valid DOS pathname, no default extension. outfile - May be specified or not specified. If not specified, the output file will be placed on the same drive and in the same directory as the input file. It will have the same filename as the input file, but the filename extension will be .dcx. If specified, a valid DOS pathname is required. No default drive or directory information from the input filename is applied. If the filename does not have an extension, .dcx is appended to it. An exisiting file of the same name as the output file will be deleted without warning. /type - Emulation type, must be specified: /e - Epson FX-85 emulation. /h - HP PCL-5 emulation. /a - ASCII file emulation. /c - Compressed print ASCII file emulation. /p - Instead of a dcx-format file, a pcx-format file is produced. The entire document will be one, possibly very long, page. All references to .dcx file extensions will change to .pcx. Note: The HP emulator will only write the first page to the output file. /s - ("silent") All screen displays, including error messages, are suppressed. This option is intended for use when prn2fax is exec'd from other programs that will check the return code for errors. /o - ("override errors") Emulation will continue regardless of the number of command errors encountered in the input file. /help - Causes the PRN2FAX help screen to be displayed. When this or /? option is used, all other command line arguments are ignored. The help screen is shown on the next page. The command line parameters may be any combination of upper and/or lower case text. PRN2FAX HELP SCREEN PRN2FAX Vx.xx Copyright (c) 1992 Intel Corporation. All rights reserved. PRN2FAX infile[.ext] [dcxfile[.ext]] / [/P] [/S] [/O] [ ] = optional infile print file to be converted to DCX (or PCX) format. Can include a pathname. dcxfile DCX (or PCX) file created by PR2DCX. The default is the "infile" filename with the extension .DCX (or .PCX), placed in the "infile" drive and directory. .ext The file's extension. / Emulation type (required): /E = Epson FX-85, /H = HP PCL-5, /A = ASCII, /C = Compressed ASCII /P Produces a file in PCX (rather than DCX) format. /S Suppresses screen displays, including error messages. Use when executing PRN2FAX from programs that check the return code. /O Overrides errors so conversion continues regardless of the number of command errors in "infile". PCX FILE INCOMPATIBILITY BETWEEN EMULATORS When the /P option is used to generate a PCX file for an input file that is longer than one page, the Epson and ASCII emulators generate a single, extra long page that contains all of the output data. The HP emulator generates only the actual first page of the input file that is submitted for emulation. ERROR CONDITIONS "Input and output files must have different names." This message is generated when the input and output files are the same file, in the same directory, on the same drive. "Program terminated by Ctrl-Break." This message replaces the "Program terminated by ESC" message generated by the emulators. "Intel fax hardware required." This message is generated if there isn't an intel fax card installed. "No input file specified. (Type 'PRN2FAX /help' for more info)." "Syntax error or invalid command line option specified. (Type 'PRN2FAX /help' for more info)." "No emulation type specified. (Type 'PRN2FAX /help' for more info)." "More than one emulation type specified. (Type 'PRN2FAX /help' for more info)." "Too many files (maximum 2) specified. (Type 'PRN2FAX /help' for more info)." "Too many command line options (maximum 10) specified." For three specific DOS errors, the following text is added to the error message generated by the emulator, if the error applies to opening either the input file or the output file: DOS error 2, file not found, or DOS error 3, path not found "Check that you entered the correct filename." DOS error 15, invalid drive specification "Type in a valid drive." EXIT CODES When the utility completes execution, it provides an 8-bit exit code to DOS. An application that exec's the utility has access to this exit code after the utility completes. The exit code for error-free operation is zero. The exit code is formatted into three bit-fields: _______________ |_|_______|_____| 0 1 2 3 4 5 6 7 bit 0: 0 = DOS error 1 = Non-DOS error bit 1: Not used. bits 2 - 4: Type of DOS operation, if DOS error: 0 = open 1 = close 2 = read 3 = write 4 = seek bits 5 - 7: File that error is associated with, if DOS error: 0 = No file involved 1 = Input file 2 = output file 3 = pcx merge file 4 = emulator overlay file 5 = page image file 6 = soft font file bits 1-7: Error code, if non-DOS error (bit 0 = 1): 00h - No input file specified. 01h - Input and output file are the same file. 02h - Invalid command line option specified. 03h - No emulation type was specified. 04h - Multiple emulation types were specified. 05h - Too many command line options were specified. 06h - Too many files were specified. 07h - Utility was invoked with /help or /? option. 08h - Emulation was aborted by request. 09h - 99 output pages exceeded. 0ah - Error in header of a PCX merge file. 0bh - An invalid type of PCX file was specified. 0ch - A PCX merge file was too wide. 0dh - A PCX merge file had a data format error. 0eh - A PCX merge file had a premature end-of-file. 0fh - Disk full error. 10h - No Intel fax hardware installed. 11h - Format error in emulator overlay file. 12h - Not enough memory to load emulator overlay file. 13h - Unknown error while loading overlay file. 14h - Input file contained invalid printer commands. 15h - No output generated due to no vertical movement. 16h - Invalid command in emulator configuration file. 17h - Internal processing failure. 18h - Unknown emulator error. 19h - Menu object allocation error. 1ah - Reader object allocation error. 1bh - Writer object allocation error. 1ch - Page object allocation error. 1dh - Soft font allocation error. 1eh - Font allocation error. 1fh - Intellifont font list allocation error. 20h - Intellifont index file error. 21h - Intellifont typeface file error. 22h - Intellifont buffer allocation error. 23h - Intellifont cache allocation error. 24h - Soft font general error. 25h - Soft font allocation error. 26h - Soft font buffer allocation error. 27h - Reader general error. 28h - Input redirection error. 29h - Writer general error. 2ah - Output data encoding error. 2bh - Page image general error. 2ch - XMS error. 2dh - EMS error. 2eh - Page cursor error. 2fh - Soft font general allocation error. 30h - Soft font unknown error. 31h - Reader general allocation error. 32h - Reader unknown error. 33h - Writer general allocation error. 34h - Writer unknown error. 35h - Page image general allocation error. 36h - Page image unknown error. 37h - PCX merge unknown error. 38h - PCL redirection unknown error. 39h - Intellifont general error. 3ah - HP/GL-2 commands in input file.