|
| |
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.
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.
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.
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.
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.
See Also Group Event fields in the Control File Error Codes |