Version
Chapter 8
NaturalFax Demonstration Programs and Utilities
8.1 About the Demonstration Programs and Utilities
8.2 Using Voice and Fax: caller
8.3 Using Voice and Fax: faxback
8.4 Receiving a Fax: nfxrecv
8.5 Sending a Fax: nfxsend
8.6 Verifying TIFF-F or TIFF-S Format: nfxcheck
8.7 Converting TIFF-F or TIFF-S Files: nfxcnvrt
8.8 Merging TIFF-F or TIFF-S Files: nfxmerge
8.9 Splitting TIFF-F or TIFF-S Files: nfxsplit
8.10 Converting ASCII Files: nfxtxttf
8.1 About the Demonstration Programs and Utilities
Each program, when invoked from the command line without providing arguments, displays an example usage statement that describes the necessary arguments.
NaturalFax provides the following demonstration programs and utilities:
Program
Description
caller
Uses voice and fax functions to call a host system running
faxback
, then requests and receives a fax.
faxback
Uses voice and fax functions to receive a call, play a prompt menu, and respond to input by sending a fax to the caller.
nfxrecv
Receives a fax.
nfxsend
Sends a fax.
nfxcheck
Verifies the specified file is in TIFF-F or TIFF-S format. Retrieves its page format attributes, number of lines per page, and bad line indications.
nfxcnvrt
Converts an input TIFF-F or TIFF-S file to an output TIFF-F or TIFF-S file with the specified attributes for encoding, resolution, page width, and bad line management.
nfxmerge
Merges multiple TIFF-F or TIFF-S input files into a single TIFF-F or TIFF-S output file.
nfxsplit
Splits a single TIFF-F or TIFF-S file into multiple TIFF-F or TIFF-S files.
nfxtxttf
Converts an ASCII text file to a TIFF-F or TIFF-S file.
NaturalFax provides source code for
nfxsend
,
nfxrecv
,
faxback
, and
caller
.
Note:
The simplest and most direct NaturalFax demonstration programs are
nfxsend
and
nfxrecv
. Use them for a quick demonstration of basic NaturalFax image transfer capabilities.
8.2 Using Voice and Fax: caller
Name
caller
Purpose
Uses voice and fax functions to call a host system running
faxback
, then requests and receives a fax.
Usage
caller
[
options
]
options
are:
Option
Description
Default
-b
n
Specifies the AG or CG board number
n
.
0
-q
Specifies that the board is a QX 2000 board.
AG/CG board
-s
n:m
Specifies the stream and timeslot.
0:0
-r
resolution
Specifies the resolution (
low
,
high
, or
superhigh
).
low
-e
encoding
Specifies the encoding (
1D
,
2D
,
MMR
, or
TIFF_S
).
1D
-c
mode
Specifies conversion mode:
y
= yes
(NFX_OTF_ALWAYS
)
m
= maybe (
NFX_OTF_ONLY_IF_FAIL
)
n
= no (
NFX_OTF_NEVER
)
m
-p
protocol
Specifies the protocol (TCP name).
nocc
-d
telno
Specifies the telephone number.
No default.
-E
Toggles using ECM mode when encoding is 1D or 2D.
Do not use ECM.
-v
Toggles verbose reporting of event information.
Non-verbose mode.
Description
Use
caller
to automate running
faxback
.
caller
places a call to the host running
faxback
, requests a document by sending a touchtone, and receives the faxed document using NaturalFax, Natural Access, and ADI service functions. DTMF tones are used to synchronize
faxback
and
caller
.
caller
begins by initializing the Natural Access environment, and then opens the ADI service on a context associated with the specified board, stream, and timeslot. It places the call, and after detecting the DTMF tone that signals the end of the prompt menu, it generates the DTMF tone that corresponds to a request for a document catalog.
caller
then creates a document queue, enqueues nonexistent files that will store the received documents, sets receive parameters, and receives the document when
faxback
transmits it.
Specifying TIFF-S encoding causes the calling application to receive a file using TIFF-S attributes of 1D encoding, LOW resolution, and A4 pagewidth. TIFF-S encoding overrides any values specified on the command line.
caller
monitors all events until it receives the
NFXEVN_SESSION_DONE
event, and takes appropriate actions if the call is disconnected or if a board error occurs. After the fax has been received, the document queue is destroyed, and
caller
is set to place another call.
caller
runs in an infinite loop. Enter
Ctrl+C
to terminate the demonstration program.
8.3 Using Voice and Fax: faxback
Name
faxback
Purpose
Uses voice and fax functions to receive a call, play a prompt menu, and respond to input by sending a fax to the caller. It can receive input from a live caller, or from the simulated caller provided by the
caller
demonstration program.
Usage
faxback
[
options
]
options
are:
Option
Description
Default
-b
n
Specifies the AG or CG board number
n
.
0
-q
Specifies that the board is a QX 2000 board.
AG/CG board
-s
n:m
Specifies the stream and timeslot.
0:0
-r
resolution
Specifies the resolution (
low
,
high
, or
superhigh
).
low
-e
encoding
Specifies the encoding (
1D
,
2D
, or
MMR
).
1D
-c
mode
Specifies conversion mode:
y
= yes (
NFX_OTF_ALWAYS
)
m
= maybe (
NFX_OTF_ONLY_IF_FAIL
)
n
= no (
NFX_OTF_NEVER
)
m
-p
protocol
Specifies the protocol (TCP name).
nocc
-E
Toggles using ECM mode when encoding is 1D or 2D.
Do not use ECM.
-v
Toggles verbose reporting of event information.
Non-verbose mode.
Description
faxback
demonstrates using voice, DTMF detection, and fax functions during a single telephone call. It uses API functions from NaturalFax, Natural Access, and the ADI service. This demonstration application plays a fixed prompt menu to the caller, allows the caller to select a document, and faxes the document back to the caller.
The demonstration begins by initializing the Natural Access environment, and then opens the ADI service on a context associated with the specified board, stream, and timeslot.
When
faxback
receives a call, it plays a voice menu prompt that requests that the caller enter DTMF tones to select a document.
faxback
initializes a document queue, then uses DTMF detection to determine which document(s) the caller has selected. Then
faxback
enqueues the document(s), sets transmit parameters, and transmits the requested document(s).
faxback
monitors all events until it receives the
NFXEVN_SESSION_DONE
event, and takes appropriate actions if the call is disconnected or if a board error occurs. After the fax is transmitted, the document queue is destroyed, and
faxback
returns to waiting for the next incoming call.
faxback
runs in an infinite loop. Enter
Ctrl+C
to terminate the demonstration program.
This program may be used interactively by calling it from a fax machine, or in conjunction with another NaturalFax demonstration program,
caller
, for automated testing. DTMF tones are used to synchronize
faxback
and
caller
.
faxback
begins by initializing the Natural Access environment, and then opens the ADI service on a context associated with the specified board, stream, and timeslot. It places the call, and after detecting the DTMF tone that signals the end of the prompt menu, it generates the DTMF tone that corresponds to a request for a document catalog.
caller
then creates a document queue, enqueues temporary files, sets receive parameters, and receives the document when
faxback
transmits it.
caller
monitors all events until it receives the
NFXEVN_SESSION_DONE
event, and takes appropriate actions if the call is disconnected or if a board error occurs. After the fax has been received, the document queue is destroyed, and
caller
places another call.
caller
runs in an infinite loop. Enter
Ctrl+C
to terminate the demonstration program.
8.4 Receiving a Fax: nfxrecv
Name
nfxrecv
Purpose
Demonstrates receiving a fax. Use
nfxrecv
to receive a fax from a fax terminal, or from the
nfxsend
demonstration program.
Usage
nfxrecv
[
options
]
filename1
[
filename2
[ ... ]]
options
are:
Option
Description
Default
-b
n
Specifies the AG or CG board number
n
.
0
-q
Specifies that the board is a QX 2000 board.
AG/CG board
-s
n:m
Specifies the stream and timeslot.
0:0
-r
resolution
Specifies the resolution (
low
,
high
, or
superhigh
).
low
-e
encoding
Specifies the encoding (
1D
,
2D
,
MMR,
or TIFF_S
).
1D
-c
mode
Specifies conversion mode:
y
= yes (
NFX_OTF_ALWAYS
)
m
= maybe (
NFX_OTF_ONLY_IF_FAIL
)
n
= no (
NFX_OTF_NEVER
)
m
-p
protocol
Specifies the protocol (TCP name).
nocc
-w
pagewidth
Specifies the page width (A4, B4, A3).
A4
-E
Toggles using ECM mode when encoding is 1D or 2D.
Do not use ECM.
-v
Toggles verbose reporting of event information.
Non-verbose mode.
Description
nfxrecv
receives a fax using NaturalFax and Natural Access functions. The Natural Access environment is initialized and the ADI service is opened with the specified board, stream, and timeslot.
The fax document queue is created and the specified files are enqueued. Then the call is answered, the receive parameters are set, and the fax is received.
Specifying
TIFF-S
encoding causes the calling application to receive a file using TIFF-S attributes of 1D encoding, LOW resolution, and A4 pagewidth. TIFF-S encoding overrides any values specified on the command line.
While waiting for the
NFXEVN_SESSION_DONE
event, all events are monitored, and appropriate action is taken in case the call is disconnected or a board error occurs. After the fax has been received, the application releases the call, destroys the document queue and the event queue, and closes the context.
8.5 Sending a Fax: nfxsend
Name
nfxsend
Purpose
Demonstrates sending a fax. Use
nfxsend
to send a fax to a fax terminal, or to the
nfxrecv
demonstration program.
Usage
nfxsend
[
options
]
filename1
[
filename2
[ ... ]]
options
are:
Option
Description
Default
-b
n
Specifies the AG or CG board number
n
.
0
-q
Specifies that the board is a QX 2000 board.
AG/CG board
-s
n:m
Specifies the stream and timeslot.
0:0
-r
resolution
Specifies the resolution (
low
,
high
, or
superhigh
).
low
-e
encoding
Specifies the encoding (
1D
,
2D
, or
MMR
).
1D
-
c
mode
Specifies conversion mode:
y
= yes (
NFX_OTF_ALWAYS
)
m
= maybe (
NFX_OTF_ONLY_IF_FAIL
)
n
= no (
NFX_OTF_NEVER
)
m
-p
protocol
Specifies protocol (TCP name).
nocc
-d
telno
Specifies the telephone number.
No default.
-w
pagewidth
Specifies the page width (A4, B4, or A3).
A4
-E
Toggles using ECM mode when encoding is 1D or 2D.
Do not use ECM.
-v
Toggles verbose reporting of event information.
Non-verbose mode.
-a
subadd
Specifies the sub-address.
Not used.
-R
modemrate
Specifies the modem type and modem rate: Options are:
V17_14400
V17_12000
V17_9600
V17_7200
V29_9600
V29_7200
V27_4800
V27_2400
V17_14400
Description
nfxsend
sends a fax using NaturalFax and Natural Access functions. The Natural Access environment is initialized and the ADI service is opened with the specified board, stream, and timeslot.
The fax document queue is created and the specified files are enqueued. Then the call is placed, the transmit parameters are set, and the fax is sent.
While waiting for the
NFXEVN_SESSION_DONE
event, all events are monitored, and appropriate action is taken in case the call is disconnected or a board error occurs. After the fax has been sent, the application releases the call, destroys the document queue and the event queue, and closes the context.
8.6 Verifying TIFF-F or TIFF-S Format: nfxcheck
Name
nfxcheck
Purpose
Determines if the input file is in TIFF-F or TIFF-S format. If the file is in TIFF-F or TIFF-S format,
nfxcheck
reports its page format attributes, number of lines per page, and bad line indications.
Usage
nfxcheck
input_file
Description
If the input file is not a TIFF-F or TIFF-S file,
nfxcheck
displays an error message. Refer to
Appendix A
for a list of possible error codes. If the input file is a TIFF-F file,
nfxcheck
displays the following information:
Page attributes
Number of lines per page
Bad line indication
This utility does not report the TIFF profile used to create the document. A TIFF-F file can use the same page attributes for encoding, resolution and pagewidth as a TIFF-S file, so the utility cannot differentiate between a TIFF-F file and a TIFF-S file.
The input file is not altered or modified.
8.7 Converting TIFF-F or TIFF-S Files: nfxcnvrt
Name
nfxcnvrt
Purpose
Converts image format characteristics of an input TIFF-F or TIFF-S file, either according to default values or as specified in the command line, and saves the modified file under a designated new name.
Usage
nfxcnvrt
input_file
output_file
[
convert_encoding
[
convert_resolution
[
convert_page_width
[
convert_bad_line
]]]]
Unless you specify different attributes in the command line arguments,
nfxcnvrt
uses the following default values:
convert_encoding
1D
convert_resolution
LOW
convert_page_width
A4
convert_bad_line
REPT
You can set any of the image format characteristics to any of their allowed values, as follows:
Format Characteristic
Allowed Values
convert_resolution
HIGH
LOW
SUPER_HIGH
convert_encoding
1D
2D
MMR
TIFF_S
convert_page_width
A4
B4
A3
convert_bad_line
DROP
REPT
TICK
NONE
Description
The default attributes constitute image format capabilities that are found in every fax terminal. Any file processed by
nfxcnvrt
using its default values can be transmitted to, or received by, any fax terminal, regardless of its capabilities.
A screen message displays the number of pages processed when
nfxcnvrt
completes the conversion.
When you specify
TIFF-S
encoding, the utility converts the output file using TIFF-S attributes of 1D encoding, LOW resolution, and A4 pagewidth. TIFF-S encoding overrides any values specified on the command line.
To repair any bad lines in a file, run
nfxcnvrt
and specify an output format that is the same as the input format. This process removes bad lines by dropping the line, repeating the previous line, or replacing the line with a blank line and a tick mark in the margin, depending on the value selected for
convert_bad_line
. The original image cannot be reconstructed.
8.8 Merging TIFF-F or TIFF-S Files: nfxmerge
Name
nfxmerge
Purpose
Merges multiple input TIFF-F or TIFF-S files into a single output TIFF-F or TIFF-S file.
Usage
nfxmerge
output_file
input_file1
input_file2
[
input_file3
[ ... ]]
Description
nfxmerge
copies several TIFF-F or TIFF-S document files into one output TIFF-F or TIFF-S file.
A screen message displays the number of pages processed when
nfxmerge
completes the operation.
The input files are not altered; the image format characteristics are not modified.
8.9 Splitting TIFF-F or TIFF-S Files: nfxsplit
Name
nfxsplit
Purpose
Splits a single input TIFF-F or TIFF-S file into multiple output TIFF-F or TIFF-S files.
Usage
nfxsplit
input_file
output_file1
output_file2
[
output_file3
[ ... ]]
Description
nfxsplit
copies one page of the input file into each output file. If the input file contains more pages than there are named output files,
nfxsplit
copies all remaining pages into the last named output file. If the input file contains fewer pages than there are named output files, the extra files are not used.
The image format characteristics of the input file are not altered.
A screen message displays the number of pages processed when
nfxsplit
completes the operation.
8.10 Converting ASCII Files: nfxtxttf
Name
nfxtxttf
Purpose
Converts an ASCII text file to a TIFF-F file.
Usage
nfxtxttf
input_file
output_file
[
-s
]
Description
nfxtxttf
converts an ASCII text file to a TIFF-F or TIFF-S file. The default output TIFF-F file has the following attributes: 1D encoding, HIGH resolution, and A4 page width.
When you use the
-s
option, a TIFF-S file is created. The TIFF-S file has 1D encoding, LOW resolution, and A4 pagewidth.
Use this utility to prepare simple cover pages to fax.
The environment variable
NMSTEXTFONT
must be defined to run this utility. See
Section 2.2,
Setting Environment Variables
for details.
Version
Want to send us feedback on our documentation? Email:
Tech_Pubs@nmss.com
Copyright © 2001, NMS Communications Corporation. All rights reserved.
Version
Version