fx_setparm( )

Description | Cautions | Example | Errors | See Also

Name:	int fx_setparm(dev, parm, valuep)
Inputs:	int dev	fax channel device handle
	unsigned long parm	parameter to set
	void *valuep	pointer to parameter value
Returns:	0 if success
	-1 if failure
Includes:	srllib.h
	dxxxlib.h
	faxlib.h
Category:	configuration
Mode:	synchronous

Description

The fx_setparm( ) function sets the fax parameter of an open fax channel device.

Parameter	Description
dev	Specifies the device handle for the fax channel obtained when the channel was opened.
parm	Specifies the define for the parameter ID to be set (see the alphabetical list of fax parameters and values on the pages that follow).
Valuep	Points to the location where the parm value is to be stored.

Many of the same parameter IDs are available for fx_setparm( ) and fx_getparm( ); any differences are noted. These functions allow you to configure an open fax channel device and retrieve the parameters set for that fax channel device.

The parameters are used to set (or read) the following categories of information:

• TIFF/F file:
  • delimiters to store fax in multiple TIFF/F files
  • Phase D continuation value for multi-page TIFF/F files
  • base page numbering scheme for TIFF/F file
  • level of TIFF/F tag checking
• fax page header:
  • graphical attributes, such as bold, underline, and format
  • date and time format
  • starting page number
  • user-defined text
• encoding scheme for data transmission and reception
• baud rate for data transmission and reception
• local and remote ID, phone number used for fax transmission and reception
• number of retry attempts for unsuccessful fax transmission
• percentage of acceptable bad scan lines
• subaddress routing information, phone number/extension used in routing a fax

The following summarizes the types of parameter IDs and their purpose. The defines for parameter IDs are described in more detail following this table, in alphabetical order.

TIFF/F file settings:
	FC_ENDDOC FC_SENDCONT FC_TFPGBASE FC_TFTAGCHECK	* delimiters for multiple TIFF/F files * Phase D value for multi-page TIFF/F * base page numbering scheme * level of TIFF/F tag checking
Fax page header settings:
	FC_HDRATTRIB FC_HDRDATEFMT FC_HDRTIMEFMT FC_HDRDATETIME FC_HDRSTARTPAGE FC_HDRUSER FC_HDRUSER2	* graphical attributes and format * date format * time format * user-defined date and time format * starting page number * user-defined text * user-defined text
Encoding scheme settings:
	FC_TXCODING FC_RXCODING	* encoding scheme for transmission * encoding scheme for reception
Baud rate settings:
	FC_TXBAUDRATE FC_RXBAUDRATE	* baud rate for transmission * baud rate for reception
Local and remote ID settings:
	FC_LOCALID FC_REMOTEID	* phone number used for transmission * phone number used for reception
Number of retry attempts setting:
	FC_RETRYCNT	* number of retries for unsuccessful transmit
Percentage of acceptable bad scan lines:
	FC_RTN FC_RTP	* percent before RTN is returned * percent before RTP is returned
Subaddress routing setting:
	FC_TXSUBADDR FC_REMOTESUBADDR	* phone number/ext. for fax routing * contents of T.30 SUB message
Font handles for ASCII to fax conversion:
	FC_FONT0 FC_FONT3	* font applied to ASCII text file * font applied to header

Define	Description
FC_ENDDOC	Bytes: 2
	Default: DFS_EOP
	Value set for fx_rcvfax( ) and fx_rcvfax2( ) to return when DFS_EOP, DFS_EOM or DFS_MPS is received in Phase D. Used to set delimiters to store pages of incoming fax data into more than one TIFF/F file. The default (DFS_EOP) stores incoming fax data in a single TIFF/F file. For more information, see Section 5.2.2. Storing Incoming Fax Data - Storing in Multiple TIFF/F Files. Valid values for FC_ENDDOC:
	DFS_ALL
		Receive function returns all FC_ENDDOC values; that is, selects all valid FC_ENDDOC values as delimiters when receiving fax data in a TIFF/F file.
	DFS_EOM
		End of Message. Stores individual pages of a multi-page fax into separate TIFF/F files. Execute fx_rcvfax( ) or fx_rcvfax2( ) in a loop, using a different file to store each page every time the receive fax function is called.
	DFS_EOP
		End of Procedure (default). Stores all incoming pages in a single multi-page TIFF/F file.
	DFS_MPS
		Multi-page Signal. Stores individual pages of a multi-page fax in separate TIFF/F files.
	DFS_REMOTESUBADDR
		Remote subaddress fax routing. Stores fax data for each subaddress in separate files.
FC_FONT0	Bytes: 4 Type: HFONT Default: similar to OEM_FIXED_FONT (12 point)
	Specifies the font handle to be used by fx_sendfax( ) or fx_sendascii( ) to render ASCII documents in the default font. In addition, this font handle is used to render ASCII documents in the font specified by DF_FONT_0 in the DF_ASCIIDATA structure or as specified by the control character F0 in the ASCII document itself. This font handle specifies one of two fonts that can be active at one time on a fax channel device. For further information on font handles, see Section 6.6.3. Overriding Fonts Set with fx_setparm( ). For details on how to obtain other font handles or character sets, see your Software Development Kit documentation.
	Note the following: The font handle must remain valid during the fax transmission; that is, the font handle must not be deleted until the fax transmission has completed. You must delete the handle when it is no longer needed. During multiple fax transmissions, if one transmission uses a different set of fonts and you want to restore the fonts to their original or default values, you must use fx_getparm( ) to obtain the default font handles for FC_FONT0 and FC_FONT3 before using fx_setparm( ) to redefine handles.
	Valid values are any Windows font handle including font handles created from font files supplied by Dialogic:
	Font Files				Description
	DEFAULT0.FON				English language character set, 12 point
	DEFAULT3.FON				English language character set, 9 point
	KATAKNA0.FON				Japanese Katakana language character set, approximately 12 point
	KATAKNA3.FON				Japanese Katakana language character set, approximately 9 point
FC_FONT3	Bytes: 4 Type: HFONT Default: similar to OEM_FIXED_FONT (9 point)
	Specifies the font handle to be used by fx_sendfax( ) or fx_sendascii( ) to render transmitted ASCII documents in the font specified by DF_FONT_3 in the DF_ASCIIDATA structure or as specified by the control character F3 in the ASCII document itself.
	This font handle specifies one of two font handles that can be active at one time on a fax channel device. FC_FONT3 also specifies the font for the header.
	For further information on font handles, see Section 6.6.3. Overriding Fonts Set with fx_setparm( ) on page 94. For details on how to obtain other font handles or character sets, see your Software Development Kit documentation. Valid values are the same as for FC_FONT0. See the NOTES for FC_FONT0 for additional information.
FC_HDRATTRIB	Bytes: 2
	Default: DF_HDRINSERT and DF_HDRFMT1
	Bitmap parameter that indicates specific graphical attributes applied to the fax header and the selection of a page header format. Valid values for FC_HDRATTRIB:
	DF_HDRBOLD
		Header text is bold.
	DF_HDRDISABLE
		Fax header is not included on the image page.
	DF_HDRFMT1
		Enable header format 1 (default format).
	DF_HDRFMT2
		Enable header format 2.
	DF_HDRINSERT
		Header text is inserted before the image. This increases the page length by the number of scan lines in the header (default).
	DF_HDRUNDERLINE
		Header text is underlined.
	If the DF_HDRFMT1 bit is set (default), the following information is included in the fax page header:
	<date> <time> <user field> From: <local ID> To: <remote ID> Page: <page #>
	<date> <time>: specified in FC_HDRDATEFMT and FC_HDRTIMEFMT. You can override this date and time string using FC_HDRDATETIME. <user field>: specified in FC_HDRUSER. Optional. <local ID>: specified in FC_LOCALID. The local station ID is implemented as a fax parameter that can be set at the user level. <remote ID>: specified in FC_REMOTEID. The remote station ID is automatically inserted, when available. This is a read-only parameter. <page #>: specified in FC_HDRSTARTPAGE. The page number is automatically inserted. There are 4 spaces between each field in the fax page header text. When the DF_HDRFMT2 bit is set, the user header information specified for the FC_HDRUSER2 parameter is placed in the fax page header. See the FC_HDRUSER2 parameter for details.
FC_HDRDATEFMT	Bytes: 2
	Default: DF_HDRDATEFMT_2
	Fax header date format. The date appears before the time specified in FC_HDRTIMEFMT. Both date and time are generated internally in the specified format.
	NOTE: You can override this format using FC_HDRDATETIME. When overriding this format, you must set either FC_HDRDATEFMT to DF_HDRDATEFMT_0 or FC_HDRTIMEFMT to DF_HDRTIMEFMT_0.
	Valid values for FC_HDRDATEFMT:
	DF_HDRDATEFMT_0
		Disable internal date generation; use user text string set in FC_HDRDATETIME
	DF_HDRDATEFMT_1
		Date appears as: MM-DD-YYYY
	DF_HDRDATEFMT_2
		Date appears as: MM/DD/YYYY
	DF_HDRDATEFMT_3
		Date appears as: DD-MM-YYYY
	DF_HDRDATEFMT_4
		Date appears as: DD/MM/YYYY
	DF_HDRDATEFMT_5
		Date appears as: YYYY-DD-MM
	DF_HDRDATEFMT_6
		Date appears as: YYYY/DD/MM
	DF_HDRDATEFMT_15
		Date appears as: day month dd YYYY (Example: Fri Sep 13 1999)
FC_HDRDATETIME	Default: NULL
	User-defined text for fax header date/time string - 27 character maximum null-terminated ASCII string (26 characters + NULL; left-justified). Overrides the default date/time format specified in FC_HDRDATEFMT and FC_HDRTIMEFMT. To enable this, you must set either FC_HDRDATEFMT to DF_HDRDATEFMT_0 or FC_HDRTIMEFMT to DF_HDRTIMEFMT_0. See these parameter descriptions for more information.
FC_HDRSTARTPAGE	Bytes: 2
	Default: 1
	Starting page number that appears in the fax page header for the first transmitted fax page. Valid values for FC_HDRSTARTPAGE:
	>= 1		Starting page number to display in the fax page header.
	When the fax page header DF_HDRFMT1 or DF_HDRFMT2 bit is set in the FC_HDRATTRIB parameter, at the beginning of a fax transmission the FC_HDRSTARTPAGE parameter is used to determine the page number to be displayed in the fax page header for the first transmitted fax page. On each subsequent page of the fax transmission, the page number is automatically increased by one.
	If the page number is greater than 99, only the last 2 digits of the page number are placed in the header.
	To set a starting page number other than the default (1), set FC_HDRSTARTPAGE before issuing the first fx_sendfax( ) of the fax transmission. It is up to the application to reset FC_HDRSTARTPAGE to the default (1) after the fax transmission is complete. For example, if a 5-page fax transmission is interrupted after sending only 3 pages, redial, set FC_HDRSTARTPAGE to 4, then issue fx_sendfax( ) to send the last 2 pages of the fax. The receiver would receive a 2-page fax with the pages numbered 4 and 5.
FC_HDRTIMEFMT	Bytes: 2
	Default: DF_HDRTIMEFMT_1
	Fax header time format. The time appears after the date specified in FC_HDRDATEFMT. Both date and time are generated internally in the specified format. You can override this format using FC_HDRDATETIME. When overriding this format, you must set either FC_HDRTIMEFMT to DF_HDRTIMEFMT_0 or FC_HDRDATEFMT to DF_HDRDATEFMT_0.
	Valid values for FC_HDRTIMEFMT:
	DF_HDRTIMEFMT_0
		Disable internal time generation; use user text string set in FC_HDRDATETIME
	DF_HDRTIMEFMT_1
		Time appears as: HH:MM am/pm (12-hour clock)
	DF_HDRTIMEFMT_2
		Time appears as: HH:MM (24-hour clock)
FC_HDRUSER	Default: NULL
	User-defined text that appears in the fax header of every transmitted fax page - 32 character maximum null-terminated ASCII string (31 characters + NULL; centered). If the string is greater than 31 characters, it is truncated. If it is less than 31 characters, it is centered.
FC_HDRUSER2	Default: NULL
	User-defined text for fax header - 133 character maximum null-terminated ASCII string (132 characters + NULL; centered).
	Allows your application to control the entire contents of the fax page header. To enable this feature, set the DF_HDRFMT2 bit in the FC_HDRATTRIB parameter. When enabled, the contents of FC_HDRUSER2 are placed in the fax page header instead of the contents of the default header format (DF_HDRFMT1). Two special escape sequences can be used in the FC_HDRUSER2 field:
	%R This sequence is replaced with the 20 character remote ID, if available. If the remote ID is not available and %R is specified, the %R is replaced with 20 spaces. If the %R is within the last 20 bytes of the FC_HDRUSER2 field, the remote ID is truncated to fit into the field. If you include the %R sequence, the maximum number of characters in the FC_HDRUSER2 field is 115 (114 characters + NULL). %P This sequence is replaced with the current fax page number. Only the last 2 digits are placed in the header. The current page number is automatically inserted for each page of the fax transmission (see FC_HDRSTARTPAGE). %% is interpreted as % and placed in the header.
	When using fx_getparm( ) to read FC_HDRUSER2, you must provide a 133 byte buffer (132 characters + NULL).
FC_LOCALID	Default: NULL
	Local identification - 21 character null-terminated ASCII string (20 characters + NULL, left-justified). This is the phone number your fax application uses for transmission. It is included in the data portion of the T.30 Call Subscriber Identification (CSI), Transmitting Subscriber Identification (TSI) and Calling Subscriber Identification (CIG) messages (the CIG message is used when polling is specified). The FC_LOCALID parameter value is specified by your application. If the length of the string exceeds the maximum value, it is truncated. If the length of the string is less than the maximum value, the string is left-justified and padded with blanks to equal 20 characters.
FC_REMOTEID	Default: NULL
	Remote identification - 21 character null-terminated ASCII string (20 characters + NULL). When the length of the string is less than the maximum value, the string is left-justified and padded with blanks to equal 20 characters.
	This is a read-only parameter, used by fx_getparm( ) only. It specifies the phone number used by the remote fax machine to transmit a fax to your fax application. It is included in the data portion of the T.30 Call Subscriber Identification (CSI), Transmitting Subscriber Identification (TSI) and Calling Subscriber Identification (CIG) messages (the CIG message is used in a polling fax transmission).
FC_REMOTESUBADDR	Bytes: 2
	Default: NULL
	Subaddress information sent by the remote transmitter -- 21 character NULL-terminated ASCII string (20 characters + NULL, left-justified). This is a read-only parameter, used by fx_getparm( ) only. It specifies the contents of the T.30 SUB message if the T.30 SUB message is included as part of the fax transmission. The SUB message is sent by the transmitter during Phase B negotiations. The FC_REMOTESUBADDR parameter is updated after each Phase B negotiation. The contents of the parameter are valid from the completion of a Phase B negotiation that contains a T.30 SUB message until the next Phase B negotiation. The application can use the subaddress information to route fax data to specified subaddresses. If the subaddress is less than 20 characters, the field is padded with spaces.

FC_RETRYCNT	Bytes: 2
	Default: DF_NORETRY
	The number of retry attempts for an unsuccessfully transmitted fax page. Valid values:
	DF_NORETRY				No retries
	DF_RETRY1				One retry
	DF_RETRY2				Two retries
	DF_RETRY3				Three retries
	DF_RETRYDCN				After specified number of retries, disconnect ("OR" this value with DF_RETRYn).
	To disconnect after the specified number of retry attempts, logically OR the retry count number value with the DF_RETRYDCN value (see the example in the fx_setparm( ) function reference). After the specified number of retry attempts, the send function fails with a -1 and the transmitter disconnects the fax call.
FC_RTN	Bytes: 2
	Default: 15
	Percent of bad scan lines acceptable for a fax page before an RTN (Retrain Negative) message is returned to the transmitter at the completion of the fax page (in Phase D). Valid values are integers between 1 and 100.
FC_RTP	Bytes: 2
	Default: 5
	Percent of bad scan lines acceptable for a fax page before an RTP (Retrain Positive) message is returned to the transmitter at the completion of the fax page (Phase D). Valid values are integers between 1 and 100. The following activities occur when FC_RTP and FC_RTN are set to their default values, where FC_RTP = 5 and FC_RTN = 15, and the level of bad scan lines received per page is as noted:
	Between 0 and 5 percent, the MCF (Message Confirmation) message is sent to the remote station.   Between 5 percent and 15 percent, the RTP (Retrain Positive) message is sent to the remote station. The next page is received after a training sequence.   Between 15 percent and 100 percent, the RTN (Retrain Negative) message is sent to the remote station, requesting retransmission of the current page.
	To determine the total number of RTN pages received (that is, the number of pages that required retransmission), call ATFX_RTNPAGES( ).
FC_RXBAUDRATE	Bytes: 2
	Default: DF_MAXBAUD
	Maximum preferred baud rate for incoming fax data. Capability varies by product; see Section 2.4. Key Product Features on page 8 for more information. Valid values:
	DF_MAXBAUD
		Maximum baud rate value for reception.
	DF_14400BAUD
		14400 baud reception
	DF_9600BAUD
		9600 baud reception
	DF_7200BAUD
		7200 baud reception
	DF_4800BAUD
		4800 baud reception
	Set this parameter to one of the supported baud rates if you wish to receive fax transmissions at a lower baud rate than the default. This parameter is useful when receiving fax transmissions over known noisy lines and you wish to explicitly set a lower initial baud rate. This saves time that would be taken in negotiating a lower baud rate.
	NOTE: The maximum receive baud rate for the channel is used if an invalid value is specified.
FC_RXCODING	Bytes: 2
	Default: DF_MH
	If supported, the encoding scheme in which the incoming fax data is stored in TIFF/F or raw file(s). Reset to MH when the channel is first opened. Valid values:
	DF_MH		Modified Huffman (default)
	DF_MMR		Modified Modified Read
	Calls to fx_rcvfax( ) or fx_rcvfax2( ) result in the storage of the incoming fax image data in the encoding scheme specified in FC_RXCODING. This value is in effect until it is reset.
	If you set the FC_RXCODING parameter value to DF_MMR, Dialogic recommends that you reset it to DF_MH (default) before exiting the program. This ensures encoding scheme compatibility with other fax application programs that expect all incoming fax data to be stored in the MH encoding scheme.
	If this parameter is set on an unsupported product, ATDV_LASTERR( ) returns an error, EFX_UNSUPPORTED.
FC_SENDCONT	Bytes: 2
	Default: DFC_EOM
	Phase D value to be used by the transmitter between pages of a multi-page TIFF/F file. Valid values:
	DFC_AUTO		Automatic Phase D Messaging. The fax library automatically determines the T.30 Phase D continuation value to be sent between pages of a multi-page TIFF/F file. This setting forces negotiation of Phase B when a page of a different width and/or resolution is found. If the following page has the same format as the current page, this setting bypasses Phase B negotiation for each page and saves transmit time.
	DFC_EOM		End of Message (T.30). End of current fax document page; more fax data to follow at a different resolution or width; return to Phase B and negotiate parameters for next fax document page. To maintain backward compatibility, this is the default setting. This setting forces the negotiation of Phase B after each page.
	DFC_MPS		Multi-Page Signal (T.30). End of current fax document page; next page is in the same format as the current page; proceed directly to Phase C. This setting bypasses Phase B negotiation for each page and saves transmit time.
FC_TFPGBASE	Bytes: 2
	Default: TF_BASE0
	Base page numbering scheme set for the TIFF/F file to send. This parameter accommodates TIFF/F file utilities that may not adhere to TIFF/F specifications which require the first page to be page zero. For most cases, this parameter may remain at the default setting. To determine the base page numbering scheme of the transmitted TIFF/F file, call the fax extended attribute ATFX_TFPGBASE( ) after the file transmission is completed. Valid values for FC_TFPGBASE:
	TF_AUTOPG			Automatic fax library adjustment for each zero or one base numbered TIFF/F file to be transmitted. Use this setting when you are unsure of the base page number scheme of the TIFF/F file. This setting may introduce additional disk I/O access time.
	TF_BASE0			Zero base page numbered TIFF/F file.
	TF_BASE1			One base page numbered TIFF/F file. Use this setting when you know the page number scheme of the TIFF/F to be transmitted is base 1.
	NOTE: Always use zero base page numbering when describing TIFF/F file pages to send in a DF_IOTT structure array. The fax library internally adjusts the page number depending on the TIFF/F file's page numbering scheme when FC_TFPGBASE is set to TF_BASE1 or TF_AUTOPG.
	To send TIFF/F files of both zero and one base page numbering scheme during the same fax session, do one of the following:
	Set FC_TFPGBASE to TF_AUTOPG before issuing fx_sendfax( ). The fax library automatically determines the base page numbering scheme for each TIFF/F file described in the DF_IOTT structures. Return control to the application to set the FC_TFPGBASE parameter value each time the TIFF/F file page numbering scheme changes. To do so, set the DF_IOTT structure io_type field to IO_EOT and the io_phdcont field to DFC_EOM for the last DF_IOTT TIFF/F file entry of a page numbering scheme type. Change the FC_TFPGBASE parameter to the appropriate value for the TIFF/F file described in the next DF_IOTT structure, then issue another fx_sendfax( ) function for the file(s) with the new page numbering scheme while the fax session is still active. For more information on DF_IOTT, see Section 7.6. DF_IOTT -- Fax Transmit Data Description.
FC_TFTAGCHECK	Bytes: 2
	Default: TF_MAXTAGS
	Level of TIFF/F tag checking. Valid values:
	TF_MAXTAGS				Check all mandatory tags; see Appendix A for TIFF/F tags and values.
	TF_MINTAGS				Check essential subset of mandatory tags. This accommodates TIFF/F files created by utilities that may not strictly adhere to TIFF/F requirements.
FC_TXBAUDRATE	Bytes: 2
	Default: DF_MAXBAUD
	Preferred maximum baud rate for fax transmission. Capability varies by product; see Section 2.4. Key Product Features on page 8 for more information. Valid values:
	DF_MAXBAUD
		Maximum baud rate value for transmission.
	DF_14400BAUD
		14400 baud transmission
	DF_9600BAUD
		9600 baud transmission
	DF_4800BAUD
		4800 baud transmission
	DF_2400BAUD
		2400 baud transmission
	Set this parameter to one of the supported baud rates if you wish to transmit at a lower baud rate than the default (DF_MAXBAUD). Although the Dialogic fax channel automatically steps down to a lower baud rate if the remote station is incapable of receiving at the default baud rate, specifying a lower transmit baud rate saves time that would be taken in negotiating a lower baud rate. Setting a lower baud rate is also useful when transmitting over noisy lines. Once the value is set, the selected preferred baud rate remains in effect until it is set again.
	NOTE: When DF_MAXBAUD is set, the value returned in fx_getparm( ) reflects the maximum transmission baud rate value based on the capability of the fax product.
FC_TXCODING	Bytes: 2
	Default: DF_MMR
	If supported, the preferred encoding scheme for data transmission over the phone line. For more information on FC_TXCODING and ECM, see Section 4.6.2. Specifying a Preferred Encoding Scheme for Transmission on page 60. Valid values for FC_TXCODING:
	DF_MH		Modified Huffman
	DF_MR		Modified Read
	DF_MMR		Modified Modified Read
	DF_ECM		Use ECM switch; ECM can be explicitly specified for Phase B negotiation in fax transmission. Use of ECM is determined by the receiver's capability.
	The FC_TXCODING value is used during Phase B negotiations with the remote receiver. The capabilities of the remote receiver determine the data transmission encoding scheme used over the phone line. The fax image data specified in the DF_IOTT structures is automatically converted to the negotiated encoding scheme at the time of transmission. Once the FC_TXCODING value is set, it remains in effect until it is set again.
	If FC_TXCODING is set on an unsupported product, ATDV_LASTERR( ) returns an EFX_UNSUPPORTED error.
	If an invalid fx_setparm( ) parameter value is specified, ATDV_LASTERR( ) returns an EFX_BADPARM error.
	You can specify the explicit use of ECM for fax data transmission when the remote station receiver has ECM capabilities. To do so, "OR" the DF_ECM bit flag with DF_MH, DF_MR, or DF_MMR when setting the FC_TXCODING parameter.
FC_TXSUBADDR	Default: NULL
	Subaddress information sent by the transmitter - 21 character NULL-terminated ASCII string (20 characters + NULL, right-justified). This parameter sets the telephone or extension numbers to be used as fax routing subaddresses. If the parameter value is less than 20 characters, the parameter value is padded with spaces to equal 20 characters. Valid characters are digits zero (0) through nine (9), and the asterisk (*). Extensions are separated by a single pound sign (#). Phone numbers are separated by two pound signs (##). If the first parameter in the subaddress field is a phone number, it should be preceded by a single pound sign (#). Examples of FC_TXSUBADDR values:
	Value					Description
	3765					single extension
	3765#3978#3767					multiple extensions
	#5551212#2767					phone number followed by an extension
	#5551234##5554321					phone number followed by another phone number
	#5551234#2767#2018					phone number followed by multiple extensions

Cautions

• You must pass the value of the parameter to be set in a variable cast as (void *) as shown in the function example.

Do not use the voice driver library function dx_setparm( ) to set fax parameter values.

Example

• Example 1: fx_setparm( )
• Example 2: fx_setparm( ) and FC_FONT0
  

  Example 1: fx_setparm( )

#include <stdio.h>  
#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <faxlib.h>  
int dev;  
unsigned short value;  
char *coname = "ABCDE Company";  
/*  
 * Open device using fx_open( ). Obtain Dialogic fax device  
 * handle in dev.  
 */  
.  
.  
/*  
 * Set retry count parameter to 2, disconnect after specified  
 * number of retries. FC_RETRYCNT uses 2 bytes (the variable value  
 * is of type unsigned short).  
 */  
value = DF_RETRYDCN|DF_RETRY2;  
if (fx_setparm(dev,FC_RETRYCNT,(void *)&value) == -1) {  
   printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
      ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
}  
/*  
 * Set the following fax page header parameters:  
 * Date format: MM-DD-YYYY  
 * Time format: HH:MM (24 hour)  
 * User text: ABCDE Company  
 */  
value = DF_HDRDATEFMT_1;  
if (fx_setparm(dev,FC_HDRDATEFMT,(void *)&value) == -1) {  
   printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
      ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
}  
value = DF_HDRTIMEFMT_2;  
if (fx_setparm(dev,FC_HDRTIMEFMT,(void *)&value) == -1) {  
   printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
      ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
}  
if (fx_setparm(dev,FC_HDRUSER,(void *)coname) == -1) {  
   printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
      ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
}




Example 2: fx_setparm( ) and FC_FONT0

#include <stdio.h>  
#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <faxlib.h>  
int dev;  
unsigned short value;  
HFONT hMyFont;  
/*  
 * Open device using fx_open( ). Obtain Dialogic fax device  
 * handle in dev.  
 */  
.  
.  
/*  
 * Use Windows API to get a font handle.  See the Microsoft  
 * Win32 API Programmer's Reference for other ways of getting  
 * font handles from resources.  
 */  
hMyFont = GetStockObject(OEM_FIXED_FONT);  
/* pass the handle to the fax library as one of the 2 internal fonts. */  
if (fx_setparm(dev,FC_FONT0,(void *)&hMyFont) == -1) {  
   printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
      ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
}  
/*  
 * when you use fx_sendfax( ) or fx_sendascii( ) to  
 * send an ASCII document, the control character <ESC>F0  
 * will use the font handle hMyFont to render the ASCII text.  
 */  
.  
.  
.  
fx_sendfax( ) ;  /* after specifying the font, send the fax */  
.  
.  
.  
deleteObject(hMyFont) ; /* delete the font handle */

Errors

See Appendix D for a list of error codes that may be returned for this function.

If you issue the function for a parameter that is not supported by your fax hardware channel, ATDV_LASTERR( ) returns an EFX_UNSUPPORTED error code.

See Also

• fx_getparm( )

Click here to contact Dialogic Customer Engineering