2.1 Overview of Configuring NaturalFax

2.2 Setting Environment Variables

2.2.1 Setting Environment Variables Under Windows

2.2.2 Setting Environment Variables Under UNIX

2.3 Modifying the Natural Access Configuration File

2.3.1 NaturalFax Services

2.3.2 Sample Natural Access Configuration File

2.4 Modifying the Board Configuration File

2.4.1 Configuring AG Quad Boards

2.4.2 Configuring AG Boards

2.4.3 Configuring CG Boards

2.4.4 Sample AG Quad T1 Configuration File

2.4.5 Sample AG 2000/200 Configuration File

2.4.6 Sample AG 4000/1600 Configuration File

2.4.7 Sample CG 6000C Configuration File

2.5 Verifying NaturalFax

2.5.1 Verifying the NaturalFax Library

2.5.2 Sending and Receiving a Fax

2.1 Overview of Configuring NaturalFax

Before you develop applications using NaturalFax, configure NaturalFax for your system. Follow these steps:

1. Set the environment variables for your platform.

2. Modify the Natural Access configuration file to define all services that the application will use.

3. Modify the board configuration file to allocate the DSPs for fax functions and to specify the NaturalFax runtime software to be downloaded when the board initializes.

4. Verify that NaturalFax is properly installed and configured.

2.2 Setting Environment Variables

This section describes how to set the environment variables for the following platforms:

• Windows

• UNIX

2.2.1 Setting Environment Variables Under Windows

During software installation, the installation program modified the following environment variables (unless you specified not to):

NFXTEXTFONT=c:\nms\nfx\text.fnt
NFXHEADERFONT=c:\nms\nfx\header.fnt

If you changed the default directory during installation, replace c:\nms with the path you specified for your system.

If you specified that the installation should not modify the environment variables, modify the variables yourself using the Windows Control Panel, before running any NaturalFax applications.

Proceed to Section 2.3 to complete your installation.

2.2.2 Setting Environment Variables Under UNIX

You must add or modify the environment variables NFXTEXTFONT and NFXHEADERFONT for the user environment in which the NaturalFax application will run. You can run a NaturalFax application from any user environment, including the superuser environment, if the environment variables for that user are properly configured. Make sure that these environment variables are added to the appropriate user environment.

To set the NaturalFax environment variables:

1. Open a Terminal window.

2. Log in as the designated user for the NaturalFax application. If you will be running the NaturalFax application from the root user environment, log in as root at your shell's command prompt by entering:
   su -

3. Enter the password when prompted.

4. With your text editor, open the shell script file executed by the user's login shell as part of the login sequence.
   For the Bourne or Korn shell, edit the /.profile file to add the following environment variables:

5. Create the environment variable NFXTEXTFONT to specify the text font file. For example:
   NFXTEXTFONT=/opt/nms/nfx/text.fnt
   export NFXTEXTFONT

6. Create the environment variable NFXHEADERFONT to specify the header font file. For example:
   NFXHEADERFONT=/opt/nms/nfx/header.fnt
   export NFXHEADERFONT
   For the C shell, edit the /.login file to add the following environment variables:

7. Create the environment variable NFXTEXTFONT to specify the text font file. For example:
   setenv NFXTEXTFONT /opt/nms/nfx/text.fnt

8. Create the environment variable NFXHEADERFONT to specify the header font file. For example:
   setenv NFXHEADERFONT /opt/nms/nfx/header.fnt

Save the modified shell script file and exit the text editor.

For the changes to the user's environment parameters to take effect in every open UNIX window in which that user is logged in, log out and then log back in as the designated user.

Proceed to Section 2.3 to complete your installation.

2.3 Modifying the Natural Access Configuration File

If you use the Natural Access Server (ctdaemon) as part of your application environment, define all services that the application uses by specifying the service and service manager names in the Natural Access configuration file (cta.cfg). You can perform tracing on any Natural Access service specified in cta.cfg, including the NaturalFax services.

For more information about ctdaemon and cta.cfg, see the Natural Access Developer's Reference Manual.

Note: You can develop and run a NaturalFax application without specifying its services in cta.cfg, but you must explicitly define the services and service managers in your application code. For more information, see Section 3.3.1, Initializing NaturalFax.

2.3.1 NaturalFax Services

A NaturalFax application typically uses the following services:

This service...	With this service manager...	Provides the...
NFX	NFXMGR	NaturalFax API.
FAX	FAXMGR	Group 3 fax protocol (ITU T.30).
FXM	ADIMGR for AG and CG boards QDIMGR for QX 2000 boards	Interface to the hardware for sending or receiving a fax.
ADI	ADIMGR for AG and CG boards QDIMGR for QX 2000 boards	Natural Access call control API.
OAM	OAMMGR	Functions for configuring, monitoring, and testing boards. Natural Access Server (ctdaemon) must be running.

The default cta.cfg file includes the ADI and OAM services. Ensure that cta.cfg also includes the NFX, FAX, and FXM services. cta.cfg is located in the following directories:

• Windows: \nms\ctaccess\cfg

• UNIX: /opt/nms/ctaccess/cfg
  Note: An application performing only fax file image conversions, and not fax transmission or reception, does not require the FAX or FXM services.

2.3.2 Sample Natural Access Configuration File

The following code excerpt from a sample cta.cfg shows the NaturalFax services in bold:

#==========================================================================
# cta.cfg
#
# This is an example of a file that specifies CT Access configuration.
# It allows you to:
#   - specify generic operational settings that apply to CT Access
#     Server, ctdaemon, and all CT Access applications.
#     Note: these settings can be overwritten by a CT Access
#     application via ctaInitialize.
#   - specify application specific settings
#   - specify CT Access Server and ctdaemon specific settings
#   - redefine service specific parameter defaults
#
#==========================================================================



#==========================================================================
# CT Access System Configuration (ctasys)
#
# Valid options are:
#   Service = name, dll        - tells the daemon about available "services"
#                              - tells the CT Access server what
#                                "services" to export
#
# Note: NCC should always precede ADI when both services are listed.
#==========================================================================
[ctasys]
Service = ncc, adimgr
Service = adi, adimgr
Service = dtm, adimgr
Service = ppx, ppxmgr
Service = swi, swimgr
Service = vce, vcemgr
Service = oam, oammgr

Service = nfx, nfxmgr  # add this line for NaturalFax
Service = fax, faxmgr  # add this line for NaturalFax

Service = fxm, adimgr  # add this line for NaturalFax with
                       # AG boards or CG boards
Service = fxm, qdimgr  # add this line for NaturalFax with
                       # QX 2000 boards

#==========================================================================
# CT Access application configuration (application)
#
#==========================================================================
[application]
# CTAmode = {0|1|2}  - Execution mode for CT Access application
# 0 - Library mode(default)
# 1 - Server mode (requires CT Access Server to be running)
# 2 - Multi mode (requires CT Access Server to be running)
CTAmode = 0

# ContextNameUniqueness = {0|1}  - Specification of responsibility for 
#                                  the context name uniqueness
#                                  (application or CT Access Server)
# 0 - CT Access Server is responsible for the context name uniqueness.
#     Allow context name modification by CT Access server to ensure
#     name uniqueness (default)
# 1 - Application is responsible for the context name uniqueness.
#     Disallow context name modification by CT Access server, 
#     uniqueness error expected from CT Access server
ContextNameUniqueness = 0



#==========================================================================
# CT Access Server configuration (server)
#
#==========================================================================
[server]
# ParmFlags = {0|1|2}   -  CT Access Server parameter flags
# 0 - Parameter management done by CT Access Server. Ignore parameters
#     in ctdaemon (default).
# 1 - Parameter management done by CT Access ctdaemon
#     (requires ctdaemon to be running; otherwise CT Access Server
#      exits).
# 2 - Parameter management done by CT Access ctdaemon if running; 
#     otherwise done by CT Access Server.
ParmFlags = 0

# TraceMode = {0|1|2}   -  CT Access Server trace mode
# 0 - Disable tracing (default)  
# 1 - Enable tracing; immediate write to trace memory (default mode) 
#     (requires ctdaemon to be running)
# 2 - Write trace memory on error only; keep local trace memory for each
#     context  
TraceMode = 0

# Remote tracing parameters
#   TraceMask = mask           - defines the default tracing mask
#   TraceFile = filename       - defines trace file name
#   StartTraceServer = {0|1}   - 0 disables starting of remote-trace server
#   StartWebServer = {0|1}     - 0 disables starting of built-in web server
#   StartCtaServer = {0|1}     - 0 disables starting of built-in CT
#                                Access server
#   HttpPort = num             - TCP port on which web-server should listen
#   TracePort = num            - TCP port on which trace-server should listen
#   TraceMaxControllers = num  - num. clients allowed to set tracemask
#   TraceMaxMonitors = num     - num. clients allowed to monitor trace msgs
TraceMask = 0
# TraceFile = cta.log
StartTraceServer = 1            
StartWebServer   = 1            
StartCtaServer   = 1            
HttpPort  = 1100                
TracePort = 1101                
TraceMaxControllers =  1        
TraceMaxMonitors    = 10        



#==========================================================================
# CT Access Default Parameter Changes (ctapar)
#
# Valid syntax for changes is:
#   service[.x].category.field = value
#
#==========================================================================
[ctapar]

# by default, no changes are made


#==========================================================================
[eof]

2.4 Modifying the Board Configuration File

NMS OAM uses board configuration files to load and initialize all AG and CG boards in your system. To use NaturalFax in your AG- or CG-based system, you must modify the board configuration file to

• Explicitly allocate the DSPs on the board to perform fax functions.

• Specify the NaturalFax runtime software to be downloaded at board initialization.
  Note: If you are running NaturalFax on a QX 2000-based system, no modifications are necessary. If you have a combination of QX and AG boards in your system, you need to modify only the AG board configuration file.

Use the sample board configuration files provided with NaturalFax as models. Choose a configuration file that corresponds to the AG and/or CG hardware installed in your system.

For more information about...	Refer to...
Fax performance	Chapter 4 - Optimizing Performance.
NMS OAM	The NMS OAM System User's Manual.
The keywords specified for each board	The board-specific installation and developer's manual.

The following table lists some of the sample configuration files for boards that support NaturalFax. The table includes the NMS OAM configuration files that invoke these files. The configuration files are located in the following directories:

Windows: \nms\ag\cfg
\nms\oam\cfg

UNIX: /opt/nms/ag/cfg
/opt/nms/oam/cfg

Note: These configuration files are valid for both CompactPCI and non-CompactPCI boards.

Board	Board Configuration File	Description	NMS OAM Configuration File
AG Dual T, AG Quad T	agpiqt1fax.cfg	mu-law fax transmit and receive configuration file	agqt1fax_oamsys.cfg
AG Dual E, AG Quad E	agpiqe1fax.cfg	A-law fax transmit and receive configuration file	agqe1fax_oamsys.cfg
AG 2000/200 AG 2000/400	agpi2fax.cfg	mu-law fax transmit and receive configuration file	ag2fax_oamsys.cfg1
AG 2000/200 AG 2000/400	agpi2faxa.cfg	A-law fax transmit and receive configuration file	ag2fax_oamsys.cfg1
AG 2000-BRI	agpi2bri_fax.cfg	mu-law fax transmit and receive configuration file	ag2brifax_oamsys.cfg
AG 2000-BRI	agpi2bri_faxa.cfg	A-law fax transmit and receive configuration file	ag2brifax_oamsys.cfg
AG 4000/800	agpi4_8fax.cfg	mu-law fax transmit and receive configuration file	ag4fax_oamsys.cfg
AG 4000/800	agpi4_8faxa.cfg	A-law fax transmit and receive configuration file	ag4fax_oamsys.cfg
AG 4000/1600	agpi4fax.cfg	mu-law fax transmit and receive configuration file	ag4fax_oamsys.cfg
AG 4000/1600	agpi4faxa.cfg	A-law fax transmit and receive configuration file	ag4fax_oamsys.cfg
AG 4000/3200	agpi4dfax.cfg	mu-law fax transmit and receive configuration file	ag4dfax_oamsys.cfg
AG 4000/3200	agpi4dfaxa.cfg	A-law fax transmit and receive configuration file	ag4dfax_oamsys.cfg
CG 6000	cgfax.cfg	mu-law fax and IVR configuration file	cgfax_oamsys.cfg
CG 6000	cgfaxa.cfg	A-law fax and IVR configuration file	cgfax_oamsys.cfg
CG 6000	cgfax_t37.cfg	mu-law fax and VoIP configuration file	cgfax_oamsys.cfg
CG 6000	cgfaxa_t37.cfg	A-law fax and VoIP configuration file	cgfax_oamsys.cfg
CG 6000	cgfax_t37t38.cfg	mu-law fax, T.38 (FoIP) and one complex vocoder configuration file	cgfax_oamsys.cfg
CG 6000	cgfaxa_t37t38.cfg	A-law fax, T.38 (FoIP) and one complex vocoder configuration file	cgfax_oamsys.cfg
CG 6100C	cg61efax.cfg	A-law fax transmit and receive configuration file	cg61efax_oamsys.cfg
QX 2000	None.	Not required	None.

1 When using this configuration file on an AG 2000C board, change the product name in the file to AG 2000C.

2.4.1 Configuring AG Quad Boards

To run NaturalFax on an AG Quad board, modify the board configuration file as follows:

1. Verify that the DLMFiles keyword includes fax.leo:
   DLMFiles[x] = fax.leo

2. Verify that the the DSP.C5x.DSPFiles keyword includes the following files:
   For AG Quad T/Dual T boards:
   DSP.C5x.DSPFiles = m4r_baud.dsp, m4x_tx.dsp, m4r_300.dsp, m4x_300.dsp, voice.dsp, m4r_samp.dsp, m4x_17.dsp
   For AG Quad E/Dual E boards:
   DSP.C5x[0..7].Files = m4r_baud.dsp m4rsampa.dsp dtmf_a.dsp voice_a.dsp callp_a.dsp tone_a.dsp m4x_txa.dsp m4x_17a.dsp m4r_300a.dsp m4x_300a.dsp

3. Save the changes to the board configuration file and exit the text editor.

4. Run NMS OAM to configure and initialize the AG board(s) as specified in the oamsys.cfg file.

2.4.2 Configuring AG Boards

To run NaturalFax on AG boards, modify the board configuration file as follows:

1. Verify that the DLMFiles keyword includes ag2fax.leo:
   DLMFiles[x] = ag2fax.leo

2. Verify that the DSP.C5x[x].Image keyword includes the following files:
   For mu-law:
   DSP.C5x[x].Image = ag2fax.c54
   For A-law:
   DSP.C5x[x].Image = ag2faxa.c54

3. Save the changes to the board configuration file and exit the text editor.

4. Run NMS OAM to configure and initialize the AG board(s) as specified in the oamsys.cfg file.

2.4.3 Configuring CG Boards

To run NaturalFax on a CG board, modify the board configuration file as follows:

1. Verify that the DLMFiles keyword specifies cg6fax as one of the downloadable modules (DLMs) for the board. For example:
   DLMFiles[1] = cg6fax

2. Verify that the DSP.C5x[x].Files keyword identifies nmsfax as one of the data processing modules (DPMs) loaded on specific DSPs. For example:
   DSP.C5x[1..31].Files = nmsfax voice tone dtmf echo callp ptf mf

3. Verify that the Resource[0].Definitions keyword identifies nmsfax as one of the data processing functions (DPFs) loaded on the DSPs. For example:
   Resource[0].Definitions = (dtmf.det_all & ptf.det_2f & (nmsfax |
   (voice.rec_24 & (voice.play_24_100 |
   voice.play_24_150 | voice.play_24_200)) |
   tone.gen))

4. Save the changes to the board configuration file and exit the text editor.

5. Run NMS OAM to configure and initialize the CG board(s) as specified in the oamsys.cfg file.

2.4.4 Sample AG Quad T1 Configuration File

The following sample configuration file sets up an AG Quad T1 board for NaturalFax using mu-law:

#--------------------------------------------------------------
#                     agpiqt1fax.cfg
#
#  --- Alliance Generation Plug-Ins Configuration ---
#
# Sample configuration file for AG-Quad T1 with NaturalFax
#
# Board settings:
#   Product = AG_Quad_T1  
#--------------------------------------------------------------

# Uncomment the appropriate Trunk Control Protocol(s)

TCPFiles[0] = nocc.tcp    # "no trunk control" protocol
TCPFiles[1] = wnk0.tcp    # 2-way wink protocol

DLMFiles[0] = fax.leo

XLaw = MU-LAW

CCMode = none
RunFile = sysqn.run

Clocking.HBus.ClockSource = OSC 
Clocking.HBus.ClockMode = STANDALONE 

NetworkInterface.T1E1[0..3].LineCode  = AMI_ZCS
NetworkInterface.T1E1[0..3].FrameType = D4

DSP.C5x.DSPFiles = m4r_baud.dsp m4r_samp.dsp dtmf.dsp voice.dsp callp.dsp tone.dsp m4x_tx.dsp m4x_17.dsp m4r_300.dsp m4x_300.dsp
DSP.C5x[0..7].Limits[0..9]=7

2.4.5 Sample AG 2000/200 Configuration File

The following sample configuration file sets up an AG 2000/200 board for NaturalFax using mu-law:

#--------------------------------------------------------------
#                       agpi2fax.cfg
#
#  --- Alliance Generation Plug-Ins Configuration ---
#
# Sample configuration file for AG-2000/200 or AG-2000/400 with
# NaturalFax
#
# Board settings:
#   Product = AG_2000  
#--------------------------------------------------------------

# Uncomment the appropriate Trunk Control Protocol(s)

TCPFiles[0] = nocc.tcp    # "no trunk control" protocol
TCPFiles[1] = lps0.tcp    # Loopstart protocol

DLMFiles = gtp.leo voice.leo svc.leo ag2fax.leo
DSP.C5x[0].Image = ag2fax.c54

XLaw = MU-LAW

Clocking.HBus.ClockSource = OSC 
Clocking.HBus.ClockMode   = STANDALONE 

DSP.C5x[1..3].Files = mf signal callp  tone  dtmf  ptf  voice
# Default DSP file for AG 2000

2.4.6 Sample AG 4000/1600 Configuration File

The following sample configuration file sets up an AG 4000/1600 board for NaturalFax using mu-law:

#--------------------------------------------------------------
#                           agpi4fax.cfg
#
#  --- Alliance Generation Plug-Ins Configuration ---
#
# Sample configuration file for AG-4000/1600  with NaturalFax
#
# Board settings:
#   Product = AG_4000_2T1  
#--------------------------------------------------------------

# Uncomment the appropriate Trunk Control Protocol(s)

TCPFiles[0] = nocc.tcp    # "no trunk control" protocol
TCPFiles[1] = wnk0.tcp    # 2-way wink protocol

DLMFiles = gtp.leo voice.leo svc.leo ag2fax.leo
DSP.C5x[7..15].Image = ag2fax.c54

XLaw = mu-LAW

Clocking.HBus.ClockSource = OSC    
Clocking.HBus.ClockMode   = STANDALONE 


NetworkInterface.T1E1[0..1].LineCode  = AMI_ZCS   
NetworkInterface.T1E1[0..1].FrameType = D4



DSP.C5x.DSPFiles = mf  callp  tone  dtmf  ptf  voice   # default DSP file for AG 4000

2.4.7 Sample CG 6000C Configuration File

The following sample configuration file configures a CG 6000C board to run voice with NOCC:

#####################################################################
#
#                           cgfax.cfg
#     
#     CG 6000 Boot configuration file for a T1 with voice and fax
#     using MU-law.
#
#
#####################################################################
                                                                                                                                                                                                    
Clocking.HBus.ClockMode                          = STANDALONE
Clocking.HBus.ClockSource                        = OSC
Clocking.HBus.ClockSourceNetwork                 = 1
TCPFiles                                         = nocc  wnk0
DSPStream.VoiceIdleCode[0..3]                    = 0x7F 
                                                                                                        
DSPStream.SignalIdleCode[0..3]                   = 0x00
NetworkInterface.T1E1[0..3].Type                 = T1
NetworkInterface.T1E1[0..3].Impedance            = DSX1
NetworkInterface.T1E1[0..3].LineCode             = B8ZS
NetworkInterface.T1E1[0..3].FrameType            = ESF
NetworkInterface.T1E1[0..3].SignalingType        = CAS
DSP.C5x[0..31].Libs[0]                           = cg6klibu
DSP.C5x[0..31].XLaw                              = MU_LAW

DSP.C5x[1..31].Files                             = nmsfax voice tone dtmf echo callp ptf mf
DSP.C5x[0].Files                                 = qtsignal tone dtmf echo callp ptf mf
Resource[0].Name                                 = RSC1
Resource[0].Size                                 = 120
Resource[0].TCPs                                 = nocc  wnk0
Resource[0].Definitions                          = ( dtmf.det_all &  ptf.det_2f & ( nmsfax | (voice.rec_24 & (voice.play_24_100 | voice.play_24_150 | voice.play_24_200)) | tone.gen ))
DLMFiles[0]                                      = cg6krun
DLMFiles[1]                                      = cg6fax
DebugMask                                        = 0x0
                                                                                                                                                                                                    

2.5 Verifying NaturalFax

After you install and configure the NaturalFax software, verify that the system is operational before you continue.

2.5.1 Verifying the NaturalFax Library

Use the Natural Access version checker utility, ctavers, to verify that the NaturalFax software can be successfully loaded. The Natural Access version checker verifies that all the Natural Access libraries defined in the Natural Access configuration file (cta.cfg) are accessible. The version checker program displays a list of the versions of all the Natural Access components.

See Section 2.3.2 for more information about the Natural Access configuration file.

To run ctavers, enter ctavers from the command line.

2.5.2 Sending and Receiving a Fax

Use nfxsend and nfxrecv to send and receive a test fax. You can use the sample TIFF_F file, sample.tif, to verify your installation.

Refer to Sending a Fax: nfxsend and Receiving a Fax: nfxrecv for more information.