After you open a FAX Event using FAXOpen, the FAXRead function
allows you to read the information contained in the control file.
File Handle Required - Valid File handle obtained with
FAXOpen.
Destination Required - String variable in which to place the
read information in.
Byte Count Optional - The number of bytes to read into
Destination.
Default Value: SIZE( Destination )
NOTE: If the Byte Count is greater than SIZE( Destination ), Byte
Count will be reset to SIZE( Destination ). The
information read will conform to the specification laid out
in appendix A.
Return Data Type: uLONG
Return Value: Number of bytes actually read.
Example:
Event = FAXFindNext( )
IF Event < 0
TYPE( 'Error Finding Next FAX Event: ' & |
CvtNum2Hex( abs( Event ) ) )
END
FileHand = FAXOpen( Event )
IF FileHand < 0
TYPE( 'Error Opening FAX Event: ' & |
CvtNum2Hex( abs( FileHand ) ) )
END
Bytes# = FAXRead( FileHand, FAXBuff )
TYPE( 'Event Status: ' & sub( FAXBuff, 3, 1 ) )
See Also: FAXOpen, FAXClose
FAXClose( ) (close a FAX event file)
FAXClose( <File Handle> )
The FAXClose function closes a file opend with FAXOpen.
File Handle Required - Valid File handle obtained with
FAXOpen.
Return Data Type: uLONG
Return Value: 0 - Success.
Other - DOS Errorcode.
Example:
Event = FAXFindNext( )
IF Event < 0
TYPE( 'Error Finding Next FAX Event: ' & |
CvtNum2Hex( abs( Event ) ) )
END
FileHand = FAXOpen( Event )
IF FileHand < 0
TYPE( 'Error Opening FAX Event: ' & |
CvtNum2Hex( abs( FileHand ) ) )
END
Bytes# = FAXRead( FileHand, FAXBuff )
TYPE( 'Event Status: ' & sub( FAXBuff, 3, 1 ) )
Close# = FAXClose( FileHand )
If ~Close# = 0
Do ErrMsg
.
See Also: FAXOpen
FAXDeleteOne( ) (delete a FILE from event Queue)
FAXDeleteOne( Event Handle
<Task Queu>
<Receive File Number> )
The FAXDeleteOne() function deletes one or more files in a
specific Queue.
Note: The delete files flag (gct:Delete_Flag) in the G_Control
group 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).
Event Handle Required - Event handle.
Task Queue Optional - Task Queue to access. Interpreted as
follows:
TaskQueue (0) - Delete Control File in Task
Queue and corresponding Group
File, if it exists.
RecvQueue (1) - Delete a file or files
associated with an event in the
Receive Queue.
LogQueue (2) - Delete Control File in Log Queue
and corresponding Group Log File
if it exists.
Default Value - TaskQueue (0)
Receive File Number Optional - 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.
Default Value - 0 - Delete all files.
Return Data Type: LONG
Return Value: 0 - Success.
< 0 - CAS Errorcode.
Example:
Event = FAXFindNext( )
IF Event < 0
TYPE( 'Error Finding Next FAX Event: ' & |
CvtNum2Hex( abs( Event ) ) )
END
FileHand = FAXOpen( Event )
IF FileHand < 0
TYPE( 'Error Opening FAX Event: ' & |
CvtNum2Hex( abs( FileHand ) ) )
END
Bytes# = FAXRead( FileHand, FAXBuff )
TYPE( 'Event Status: ' & sub( FAXBuff, 3, 1 ) )
Close# = FAXClose( FileHand )
If ~Close# = 0
Do ErrMsg
.
Status# = FAXDeleteOne( Event, TaskQueue, 0 )
If Status# < 0
Do ErrMsg
.
See Also: FAXDeleteAll
FAXDeleteAll( ) (delete ALL CONTROL FILES from event Queue)
FAXDeleteAll( Task Queue )
The FAXDeleteAll() function deletes ALL control files in a
specific Queue.
Task Queue Required - Task Queue to delete from. Interpreted
as follows:
TaskQueue (0) - Delete all Control Files in the
Task Queue, including all Group
Files.
RecvQueue (1) - Delete all Control Files in the
Receive Queue and all received
files.
LogQueue (2) - Delete all Control Files in the
Log Queue, including all Group
Files.
Return Data Type: LONG
Return Value: 0 - Success.
< 0 - CAS Errorcode.
Example:
Status# = FAXDeleteAll( TaskQueue )
If Status# < 0
Do ErrMsg
END
See Also: FAXDeleteOne
FAXGetEventD( ) (get event execution date)
FAXGetEventD( Event Handle
<Task Queue> )
The FAXGetEventD() function gets the date associated with a given
event handle.
Event Handle Required - Event handle of the event whose date
you want to obtain. Obtained with
FAXFind???, or returned by
FAXSubmitQueue/FAXSendOneFile.
Task Queue Optional - Task Queue to find event in.
interpreted as follows:
TaskQueue (0) - Search Control Files in the
Task Queue.
RecvQueue (1) - Search Control Files in the
Receive Queue.
LogQueue (2) - Search Control Files in the Log
Queue.
Default Value - TaskQueue
Return Data Type: uLONG
Return Value: Clarion DATE (LONG)
Example:
Event = FAXFindNext( )
IF Event < 0
TYPE( 'Error Finding Next FAX Event: ' & |
CvtNum2Hex( abs( Event ) ) )
END
Date# = FAXGetEventD( Event, TaskQueue )
Type( 'Event Date: ' & format( Date#, @d1 ) )
See Also: FAXSetEventD, FAXGetEventT
FAXSetEventD( ) (set event execution date)
FAXSetEventD( Event Handle
<Event Date> )
The FAXGetEventD() function gets the date associated with a given
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 causes the transmission to occur
immediately.
Event Handle Required - Event handle of the event whose date
you want to set. Obtained with
FAXFind???, or returned by
FAXSubmitQueue/FAXSendOneFile.
Event Date Optional - Date for event to occurr.
Default Value - 00/00/0000 (Today)
Return Data Type: LONG
Return Value: 0 - Success.
< 0 - CAS Errorcode.
Example:
Event = FAXFindNext( )
IF Event < 0
TYPE( 'Error Finding Next FAX Event: ' & |
CvtNum2Hex( abs( Event ) ) )
END
Date# = FAXGetEventD( Event, TaskQueue )
Type( 'Event Date: ' & format( Date#, @d1 ) )
IF Date# <> Today()
Result# = FAXSetEventD( Event, Today() )
END
See Also: FAXGetEventD, FAXSetEventT
FAXGetEventT( ) (get event execution time)
FAXGetEventT( Event Handle
<Task Queue> )
The FAXGetEventT() function gets the time associated with a given
event handle.
Event Handle Required - Event handle of the event whose time
you want to obtain. Obtained with FAXFind??? or
returned by FAXSubmitQueue/FAXSendOneFile.
Task Queue Optional - Task Queue in which to find event.
Interpreted as follows:
TaskQueue (0) - Search Control Files in the
Task Queue.
RecvQueue (1) - Search Control Files in the
Receive Queue.
LogQueue (2) - Search Control Files in the Log
Queue.
Default Value - TaskQueue
Return Data Type: uLONG
Return Value: Clarion TIME (LONG)
Example:
Event = FAXFindNext( )
IF Event < 0
TYPE( 'Error Finding Next FAX Event: ' & |
CvtNum2Hex( abs( Event ) ) )
END
Time# = FAXGetEventT( Event, TaskQueue )
Type( 'Event Date: ' & format( Time#, @t1 ) )
See Also: FAXSetEventT, FAXGetEventD
FAXSetEventT( ) (set event execution time)
FAXSetEventT( Event Handle
<Event Time> )
The FAXSetEventT() function sets the time associated with a given
event handle.
This function is valid only for events that the local computer
initiates.
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 selects 12:00 AM.
Event Handle Required - Event handle of the event whose date
you want to set. Obtained with FAXFind??? or
returned by FAXSubmitQueue/FAXSendOneFile.
Event Date Optional - Time for event to occur.
Default Value - 12:00AM
Return Data Type: LONG
Return Value: 0 - Success.
< 0 - CAS Errorcode.
Example:
Event = FAXFindNext( )
IF Event < 0
TYPE( 'Error Finding Next FAX Event: ' & |
CvtNum2Hex( abs( Event ) ) )
END
Date# = FAXGetEventD( Event, TaskQueue )
Type( 'Event Date: ' & format( Date#, @d1 ) )
IF Date# <> Today()
Result# = FAXSetEventT( Event, Clock() )
END
See Also: FAXGetEventT, FAXSetEventD
FAXGetEDB( ) (get external data block)
FAXGetEDB( EDB Group )
The FAXGetEDB() returns the information contained in the external
data block. The External Data Block contains additional
information about the current Resident Manager installation such
as the name of the default logo file.
EDB Group Required - Group in which to place information.
Group Structure:
G_EDB Group,pre(edb)
CASMajorV byte !CAS Manager Major Version
CASMinorV byte !CAS Manager Minor Version
MngrDir cSTRING(68) !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.
PhoneBook cSTRING(13) !Name of default phonebook file. This
!file is assumed to be in the Resident
!Manager and software directory.
LogoFile cSTRING(13) !Name of default logo file. This file
!is assumed to be in the Resident
!Manager and software directory. The
!user specifies this name when
!installing the software.
SenderName cSTRING(32) !Default sender name. The user
!specifies this name when installing the
!software.
CSID cSTRING(21) !CSID (the CCITT identification of the
!fax device).
Reserved byte,dim(107) !Reserved.
.
Return Data Type: LONG
Return Value: 0 - Success.
< 0 - CAS Errorcode.
Example:
Result# = FAXGetEDB( G_EDB )
IF Result# < 0
DO ErrMsg
ELSE
TYPE( 'FAX CITT Identifier: ' & edb:CSID )
END
FAXRecState( ) (get/set receive state)
FAXRecState( Get_Set
<Ring Count> )
The FAXRecState() 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.
Get_Set Required - Parameter specifying whether to get or
set the receive state.
Valid values - GetState (0) Get Receive State.
SetState (1) Set Receive State.
Ring count Optional - Required only if SetState is selected.
Specifies the number of rings on which
the FAX Hardware should answer.
Default Value - 0 - Turn off Auto Answer
Return Data Type: LONG
Return Value: GetState - Number of rings on which FAX will
answer.
SetState - 0 - Success.
< 0 - CAS Errorcode.
Example:
Rings = FAXRecState( GetState, )
IF Rings > 0
TYPE( 'FAX Set to answer on ring: ' & Rings )
ELSE
Rings = FAXRecState( SetState, 1 )
IF Rings = 0
TYPE( 'FAX Set to answer on ring: 1' )
ELSE
TYPE( 'Could not set Answer state.' )
END
END
FAXQStatus( ) (get Queue status)
FAXQStatus( <Task Queue>
<Return Value> )
The FAXQStatus() function returns the current status of a queue
you specify.
Task Queue Optional - Task Queue on which to report.
This is interpreted as follows:
TaskQueue (0) - Search Control Files in the
Task Queue.
RecvQueue (1) - Search Control Files in the
Receive Queue.
LogQueue (2) - Search Control Files in the Log
Queue.
SendEvents (3) - Search for only send events.
RecvEvents (4) - Search for only receive events.
Default Value - TaskQueue
Return Value Optional - Specifies the value you wish to
examine.
This is interpreted as follows:
Task Queue = TaskQueue, RecvQueue, or LogQueue
1 = Return 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.
2 = Return current number of Control Files in
this queue.
3 = Return current number of received files.
(This register is non-zero only if you
request the status of the Receive Queue by
specifying RecvQueue.) The value in this
register is incremented for each file
received.
Task Queue = SendEvents
1 = Return number of successful sends since the
Resident Manager was started. Including
events cancelled by the user.
2 = Return number of unsuccessful sends since the
Resident Manager was started. Including
warnings.
Task Queue = RecvEvents
1 = Return number of successful sends since the
Resident Manager was started. Including
events cancelled by the user.
2 = Return number of unsuccessful sends since the
Resident Manager was started. Including
warnings.
Default Value - 1
Return Value: Described above
Example:
Sends = FAXQStatus( SendEvents, 1 )
TYPE( 'There have been ' & Sends & |
' successful sends since your computer was started.' )
FAXGetHwStat( ) (get Hardware status)
FAXGetHwStat( <Status Group> )
The FAXGetHwStat() function 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 FAXCurrentEvent() and
FAXQStatus() functions or examine the Control File,
instead of using this function.
Status Group A group of 128 Bytes whose structure is specified
by the Hardware manufacturer.
Return Value: 0 - Success.
< 0 - CAS Errorcode.
FAXDiags( ) (run diagnostics)
FAXDiags( <Start_Report> )
The FAXDiags() function runs a set of diagnostics or reports on
their progress.
Start_Report Optional - Start or Report diagnostics flag.
Valid Values - 0 - Report progress of diagnostics.
1 - Start running diagnostics.
Default Value - 0 - Report progress of
diagnostics.
Return Data Type: LONG
Return Value: If request was to start running diagnostics (1),
the return value contains either a 0 (diagnostics
successfully begun) or a negative error code.
If request was to report the progress of
diagnostics, the return value contains a 40H
(diagnostics in process) or some other
non-negative number indicating that diagnostics
passed. If the return value contains a negative
number, the diagnostics failed and the value
indicates the reason for failure. The values are
hardware-dependent. Contact your communications
hardware manufacturer for information on the
failure codes.
Example:
IF ~FAXDiags( 1 )
Do ErrMsg
END
FAXMoveFile( ) (move received file)
FAXMoveFile( Event Handle,
New Name,
Receive File Number )
The FAXMoveFile() function 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.
Event Handle Required - Event handle of the receive event whose
file you want to move. Obtained with FAXFind???.
New Name Required - A new path and name of the file. This
file must not exist already.
Receive File Number Required - This number specifies which file
to move. The number is interpreted as
follows:
1 - First received file
2 - Second received file
3 - Third received file
n - nth received file
Return Data Type: LONG
Return Value: 0 - Success.
< 0 - CAS Errorcode.
Example:
Return# = FAXMoveFile( Event, 'C:\RECV.FAX', 1 )
IF Return# < 0
DO ErrMsg
END
FAXSetCvrStat( ) (set cover page status flag)
FAXMoveFile( Event Handle,
<Read Flag> )
The FAXSetCvrStat() function sets the Cover Page Read flag
(gct:Cover_Read) 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.
Event Handle Required - Event handle of the receive event whose
cover page you want to set as read. Obtained with
FAXFind???.
Read Flag Optional - Set the read status of the cover page.
Valid values - False (0) - Cover page not read.
True (1) - Cover page read.
Default value - False (0) - Cover page not read.
Return Data Type: LONG
Return Value: 0 - Success.
< 0 - CAS Errorcode.
Example:
Return# = FAXSetCvrStat( Event, True )
IF Return# < 0
DO ErrMsg
END
CvtHex2Num( ) (convert HEX value to numeric)
CvtHex2Num( HEX Value )
The CvtHex2Num() function converts a HEX (string) value to a
numeric.
HEX Value Required - Hexidecimal (string) value to be
converted. Using the notation '3E8', do not add
an 'h' to the end.
Return Data Type: uLONG
Return Value: Clarion uLONG equivalent to the HEX Value.
Example:
Value# = CvtHex2Num( '3E8' )
See also: CvtNum2Hex
CvtNum2Hex( ) (convert numeric to HEX value)
CvtNum2Hex( Numeric Value )
The CvtNum2Hex() function converts a numeric value to a HEX
(string).
Numeric Value Required - Numeric value to be converted to its
Hexidecimal (string) equivalent.
Return Data Type: STRING
Return Value: HEX STRING equivalent to the numeric Value.
Example:
Value# = CvtNum2Hex( 1000 )
See also: CvtHex2Num
Long2DosD( ) (convert Clarion date to DOS Date)
Long2DosD( Clarion Date )
The Long2DosD() function converts a Clarion date (long) to the
DOS equivalent (DOS file date format is a convention that DOS
uses for storing the date and time in two-byte fields).
Clarion Date Required - Clarion date (long) to be converted to
its DOS (2 byte) equivalent.
Return Data Type: LONG
Return Value: LONG representing the DOS date for the input
Clarion date.
Example:
DosDate# = Long2DosD( Today() )
Long2DosT( ) (convert Clarion time to DOS time)
Long2DosT( Clarion Time )
The Long2DosT() function converts a Clarion time (long) to the
DOS equivalent (DOS file time format is a convention that DOS
uses for storing the date and time in two-byte fields).
Clarion Time Required - Clarion time (long) to be converted to
its DOS (2 byte) equivalent.
Return Data Type: LONG
Return Value: LONG representing the DOS time for the input
Clarion time.
Example:
DosDate# = Long2DosD( Clock() )
Control File Structure
G_Control Group,pre(gct) ! Begin Group Structure.
EventType byte(0)
Event type:
0 - Send.
1 - Receive.
2 - Polled Send.
3 - Polled Receive.
4 - Group Send (V1.2).
5 - Group Polled Receive (V1.2).
-1 (0FFH) - Serious hardware error not associated
with an ordinary event.
TransType byte(0)
Transfer type:
0 - 200x200 dpi, fax mode.
1 - 100x200 dpi, fax mode.
2 - File transfer mode.
EventStat Short(0)
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.
Negative value - Error.
SendTime uShort(0)
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.
SendDate uShort(0)
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.
Files2Send uShort(0)
Number of files to transfer (maximum 32766).
FTRReserv uShort(0)
Reserved - Set to 0.
PhoneNum cString(47)
Phone number to call (or filename of Group File
(V1.2)). For non-group events, place a phone
number in this field. 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.
ApplicTag cString(64)
Application-specific tag field. Will always be
set to 'Fax Sent with C3Fax v1.01'.
CASReserv byte(0)
Reserved - Set to 0.
Con_Sec byte(0)
Time length of phone connection: seconds (0-59).
Has no meaning for parent Control Files.
Con_Min byte(0)
Time length of phone connection: minutes (0-59).
Has no meaning for parent Control Files.
Con_Hrs byte(0)
Time length of phone connection: hours (0-23).
Has no meaning for parent Control Files.
Total_Pg uLong(0)
Total number of pages in all files. Has no meaning
for parent Control Files.
Pages_Tran uLong(0)
Number of pages transmitted so far. Has no meaning
for parent Control Files.
Files_Tran uShort(0)
Number of files transmitted so far. Has no meaning
for parent Control Files.
Cover_Flag byte(0)
Cover page flag:
0 - Do not send a cover page.
1 - Send a cover page.
Total_Err uShort(0)
Number of transmission errors reported by the
hardware for all transmissions controlled by this
Control File. Has no meaning for parent Control
Files.
Delete_Flag byte(0)
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.
0 - Do not delete files after event.
1 - Delete files if event is successful.
2 - Always delete files after event.
NOTES:
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.
Parent_Hndl uShort(0)
Event handle for parent event (V1.2). The
Resident Manager assigns this handle. This handle
is zero if there is no parent event.
CASReserv2 byte(0),dim(73)
Reserved - Set to 0.
Cover_Read byte(0)
Cover page read flag (V1.2). Initialized to zero.
The application can use FAXSetCvrStat function 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.
No_Header byte(0)
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.
Remote_CSID cString(21)
Remote CSID (the CCITT identification of the fax
device, set by the Resident Manager).
To_Name cString(32)
Destination Name (To: field).
From_Name cString(32)
Sender Name (From: field).
Logo_Name cString(80)
Path and name of PCX logo file (maximum size 1728
x 800 pels). A fully qualified pathname for the
file (including the drive) must be entered.
FileType byte(0)
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.
TxtSize byte(0)
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)
FileStat byte(0)
Status of this file:
0 - Untouched
1 - Has been opened
2 - Has been moved
3 - Has been deleted
4 - Not yet received
ByteTran uLong(0)
Bytes of this file transmitted so far. Has no
meaning for parent Control Files.
FileSize uLong(0)
Size in bytes of this file.
Page_Tran uShort(0)
Number of pages in this file transmitted so far.
Has no meaning for parent Control Files.
Page_Count uShort(0)
Number of pages in this file.
FileName cString(80)
Path and name of file to send. A fully qualified
pathname for the file (including the drive) must
be entered.
Eighth_Incs byte(0)
If you set the Inches field (Page Legnth) 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.
Page_Len byte(0)
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 inch specified in
the 1/8 inch field (Eighth_Incs).
-1 - ASCII pages end with form feeds only.
All other values are reserved.
FReserve byte(0),dim(31)
Reserved - Set to 0.
.
Control File Structure
G_Control Group,pre(gct) ! Begin Group Structure.
EventType byte(0)
Event type:
0 - Send.
1 - Receive.
2 - Polled Send.
3 - Polled Receive.
4 - Group Send (V1.2).
5 - Group Polled Receive (V1.2).
-1 (0FFH) - Serious hardware error not associated
with an ordinary event.
TransType byte(0)
Transfer type:
0 - 200x200 dpi, fax mode.
1 - 100x200 dpi, fax mode.
2 - File transfer mode.
EventStat Short(0)
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.
Negative value - Error.
SendTime uShort(0)
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.
SendDate uShort(0)
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.
Files2Send uShort(0)
Number of files to transfer (maximum 32766).
FTRReserv uShort(0)
Reserved - Set to 0.
PhoneNum cString(47)
Phone number to call (or filename of Group File
(V1.2)). For non-group events, place a phone
number in this field. 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.
ApplicTag cString(64)
Application-specific tag field. Will always be
set to 'Fax Sent with C3Fax v1.01'.
CASReserv byte(0)
Reserved - Set to 0.
Con_Sec byte(0)
Time length of phone connection: seconds (0-59).
Has no meaning for parent Control Files.
Con_Min byte(0)
Time length of phone connection: minutes (0-59).
Has no meaning for parent Control Files.
Con_Hrs byte(0)
Time length of phone connection: hours (0-23).
Has no meaning for parent Control Files.
Total_Pg uLong(0)
Total number of pages in all files. Has no meaning
for parent Control Files.
Pages_Tran uLong(0)
Number of pages transmitted so far. Has no meaning
for parent Control Files.
Files_Tran uShort(0)
Number of files transmitted so far. Has no meaning
for parent Control Files.
Cover_Flag byte(0)
Cover page flag:
0 - Do not send a cover page.
1 - Send a cover page.
Total_Err uShort(0)
Number of transmission errors reported by the
hardware for all transmissions controlled by this
Control File. Has no meaning for parent Control
Files.
Delete_Flag byte(0)
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.
0 - Do not delete files after event.
1 - Delete files if event is successful.
2 - Always delete files after event.
NOTES:
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.
Parent_Hndl uShort(0)
Event handle for parent event (V1.2). The
Resident Manager assigns this handle. This handle
is zero if there is no parent event.
CASReserv2 byte(0),dim(73)
Reserved - Set to 0.
Cover_Read byte(0)
Cover page read flag (V1.2). Initialized to zero.
The application can use FAXSetCvrStat function 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.
No_Header byte(0)
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.
Remote_CSID cString(21)
Remote CSID (the CCITT identification of the fax
device, set by the Resident Manager).
To_Name cString(32)
Destination Name (To: field).
From_Name cString(32)
Sender Name (From: field).
Logo_Name cString(80)
Path and name of PCX logo file (maximum size 1728
x 800 pels). A fully qualified pathname for the
file (including the drive) must be entered.
FileType byte(0)
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.
TxtSize byte(0)
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)
FileStat byte(0)
Status of this file:
0 - Untouched
1 - Has been opened
2 - Has been moved
3 - Has been deleted
4 - Not yet received
ByteTran uLong(0)
Bytes of this file transmitted so far. Has no
meaning for parent Control Files.
FileSize uLong(0)
Size in bytes of this file.
Page_Tran uShort(0)
Number of pages in this file transmitted so far.
Has no meaning for parent Control Files.
Page_Count uShort(0)
Number of pages in this file.
FileName cString(80)
Path and name of file to send. A fully qualified
pathname for the file (including the drive) must
be entered.
Eighth_Incs byte(0)
If you set the Inches field (Page Legnth) 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.
Page_Len byte(0)
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 inch specified in
the 1/8 inch field (Eighth_Incs).
-1 - ASCII pages end with form feeds only.
All other values are reserved.
FReserve byte(0),dim(31)
Reserved - Set to 0.
.
The following is an excerpt from the DCA/Intel CAS Specification:
Error Codes
An error code consists of two parts: an error class and an error
subcode. The error class is the first two HEX digits returned,
and the error subcode is the second two HEX digits returned. The
error class indicates the general type of operation in which the
error occurred. Examples of general operations are manipulation
of the schedule and manipulation of a Control File. 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 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.
NOTE: Error codes returned as a Clarion LONG may be converted to
the Hexadecimal equivalent using:
Variable = CvtNum2Hex( Abs( Return Value ) ).
Table of Error Codes
ErrorClassSubcodeDescription0Class: Fax warnings (not an error)000000No error000202Bad scanline count000303Page sent with errors, couldn't resend000404Receive data lost000505Invalid or missing logo file000606File name does not match nonstandard
format (NSF) header000707File size does not match nonstandard
format (NSF) header1Class: DOS warnings; data was sent. The
error subcode is the error returned by
DOS. Examples are:010111Invalid function number010515Access denied010616Invalid handle01xx1...(See the DOS Technical Reference)2Class: Fatal errors. The function
failed or the data was not sent.020020Multiplex handler failed020121Unknown command (bad function number)020222Event not found (bad event handle)020323Attempted to Find Next before Find First020424No more events020727Invalid Queue type (bad Queue number)020828Bad Control File020929Communication board is busy020A2AInvalid command parameter020B2BCan not un-install the Resident Manager020C2CFile already exists0280280Unknown task type (not a Send or Poll
event)0281281Bad phone number0282282Bad PCX file header0283283Unexpected EOF0284284Unexpected disconnect0285285Exceeded maximum dialing retries0286286No files specified for Send event0287287Communication board timeout0288288Received more than 1023 (maximum) pages
of data0289289Manual connect posted too long ago028A28AHardware command set error028B28BBad nonstandard format (NSF) header file3Class: Fatal DOS errors, data not sent.
The error subcode is the error returned
by DOS. Examples are:030232File not found030333Path not found03xx3...(See the DOS Technical Reference Manual)4Class: Fax errors040141Remote unit not Group 3 compatible040242Remote unit did not send its
capabilities040343 Remote unit requested disconnect040444 Remote unit is not capable of file
transfers040545 Exceeded retrain or fax resend limit040646 Line noise or local and remote unit do
not agree on a bit rate040747 Remote unit disconnected after receiving
data040848 No response from remote unit after
sending data040949 Capabilities of remote unit are not
compatible040A4A No dial tone - check phone line and cord
(V1.2)040B4B Invalid response from remote unit after
sending data040D4D Phone line dead or remote unit
disconnected040E4E Timeout while waiting for secondary dial
tone (V1.2)0411411Invalid command from remote after
receiving data0415415Tried to receive from incompatible
hardware041F41FUnexpected end of file while receiving045C45CReceived data overflowed input buffer045D45DRemote hardware unexpectedly stopped
sending data045E45ERemote hardware did not send any data045F45FRemote hardware took too long to send
fax scan line0463463Cannot get through to remote unit0464464User cancelled event5Class: 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. Information specific to
an application in a control file in the
Log Queue. To do this, the application
must set the status of the 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
the 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 the event field then
contains the error code.6Class: 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.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.
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 (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