In the following function descriptions, all date and time arguments will be shown for clarity in USA format. However, the default input format is LOCAL and so the routines will normally expect for example dd/mm/yyyy in the UK and yyyy.mm.dd in Japan. You can switch between LOCAL and USA input parameter formats by making an assignment to the SF_DATETIME_PARM control variable as described in Function Syntax. Any date or time used as an input parameter must match the LOCAL or USA input format.

The FFTESTAS utility is provided to test the operation of Application Support functions.  It displays the syntax of each function and you can enter sample parameters to see how they will be processed.

       

CalcBizDays(mm/dd/yyyy, mm/dd/yyyy)

calculates the number of business days between the two specified dates. The starting date is the earlier of the two dates and it is counted as a business day if it is a business day. The ending date, or the later of the two dates, is not counted as a business day. So the ending date will not be included in the count. See IsBusinessDay and IsHoliday for additional definitions.

CalcBizDays2(mm/dd/yyyy, mm/dd/yyyy)

calculates the number of business days between the two specified dates. The starting date is the earlier of the two dates and is not counted as a business day if it is a business day. The ending date, or the later of the two dates, is counted as a business day if it is a business day. So the starting date will not be included in the count.  See IsBusinessDay and IsHoliday for additional definitions.

CalcBizDays3(mm/dd/yyyy, mm/dd/yyyy)

calculates the number of business days spanning the two specified dates. The starting date is the earlier of the two dates and it is counted as a business day if it is a business day. The ending date, or the later of the two dates, is also counted as a business day if it is a business day. See IsBusinessDay and IsHoliday for additional definitions.

CalcBizDays4(mm/dd/yyyy, mm/dd/yyyy)

calculates the number of business days between the two specified dates. The starting date is the earlier of the two dates and is not included in the count. The ending date, or the later of the two dates, is not included in the count. See IsBusinessDay and IsHoliday for additional definitions.

CFGetFileURL(srcfilename [,orig])

returns a local file URL name for the file name specified in the srcfilename parameter.  This adds file:/// to the start of the path and changes backslashes to slashes.  Earlier releases added file:// and to retain this format, add a second parameter of orig to the function call.

CFGetUNCName(srcfilename)

returns a UNC file name for the file name specified in the srcfilename parameter.

CompareOCRText(input, match, mismatches, subs, case, ignore [, subsets])

This function performs a loose comparison of text which has typically been generated as output from an OCR operation, to determine whether a match exists. The parameters are used as follows:

input the input text string to be compared.
match the expected text.
mismatches the allowed number of mismatches. Comparison will proceed until this number is exceeded.
subs the allowed number of substitutions (see subsets below). A value of -1 allows unlimited substitutions.
case use the keyword True if the comparison is to be case-sensitive or False if it is not.
ignore use the keyword True if you want to ignore unmatched spaces in the input text or False if you do not. Some OCR conversions might pick up an extra space between letters. If you specify True and the input character is a space and the match character is not, the comparison will ignore the space and move on to the next character in the input string to test against the match character.
subsets optional substitution sets which specify alternatives which may be substituted for a character which has been incorrectly recognized in an OCR conversion or other process (no actual substitutions take place). A set consists of a string of characters enclosed in square brackets ([…]). The first character of the set is the character to be matched. The remaining characters are characters that will be considered valid in satisfying the comparison against the match character. For example a set specified as [:;,.] allows you to accept a semicolon(;), comma(,), or period (.) as a valid match for a colon(:). Substitution sets are only tested when there is no exact match on a character test. You may omit this parameter if you do not wish to allow the use of substitutions in comparisons. Otherwise you may specify as many sets as you wish enclosing each set in square brackets. Once you exceed the allowed substitutions in a test, then no further substitution tests will be made and a difference will be recorded as a mismatch.

This function returns T if the input and match strings are equal according to the comparison rules or F if they are not.

ConvertFile(srcfilename, destfilename)

Converts a single- or multi-page TIF file to PDF or vice-versa.  In addition this function performs all the functions of GCSINGLE.  Please refer to the GCSINGLE topic for the allowable combinations of source and destination file extensions, and the significance of the case of the file extension in relation to the size of the output pages.  Where variables from the third (FST) parameter are mentioned in the GCSINGLE topic, for this function the variables and commands referenced will instead be those in the current call or FS file.  The function returns either the number of pages converted, or a negative number indicating an error.

       This function is for special applications only: normally when a TIF file is to be faxed from a PDF original, or a PDF is to be e-mailed from a TIF original, an automatic conversion will be done and this function is not involved.

CopyFile(srcfilename, destfilename)

Copies source file srcfilename to destination file destfilename. This function will overwrite the destination file if it exists. This function returns T if the copy is successful or F if the copy fails.  Note that the system variables DELETETHISFILE, MOVETARGET and MOVETHISFILE can be used for file delete and move functions.

CreatePDFThumbNails(srcfaxfilenamedestfilename [, cols=4 [, page [, text [, font ]]]])

Creates a PDF containing thumbnail images from all pages of the input fax file name. The PDF is saved in the file specified in the second parameter. The thumbnail images are reduced to fit the number of columns specified in the third parameter across each page, and up to the same number down each page.  This parameter defaults to 8, and values from 1 to 8 are allowed, but you can optionally add 10 to this value to cause only the first page to be rendered.  A page number is added in the bottom left corner of each thumbnail. The page parameter can be Letter or A4 (default is A4 if omitted).  The text parameter can contain up to four lines of HTML text which will be placed above the thumbnails on each page of the output file.  The font parameter defaults to Arial; Courier and Times are the only allowed options.  This function returns T if the thumbnail image was successfully created or F on failure.  See also ConvertFile for simple conversion between TIF and PDF.

CreateThumbNail(srcfaxfilenamedestfilename [, zoomfactor=8])

Creates a thumbnail image from the first page of the input fax file name. The thumbnail image is saved in the file specified in the second parameter. The thumbnail image is reduced by the factor specified in the third parameter, which defaults to 8 (one-eighth the original linear dimensions). Values from 1 to 16 are allowed for this parameter.  The standard Windows image formats .BMP, .GIF and .JPG (or .JPEG) are supported for the thumbnail image. This function returns T if the thumbnail image was successfully created or F on failure.

DateConvert(mm/dd/yyyy, lcid)

Converts a date to the format specified by the SF_DATE_FORMAT using the specified Windows locale ID.  Use an LCID of 0 to signify the current locale.  Windows locale values can be found here, (or here for XP/2003).

DateDiff(mm/dd/yyyy, mm/dd/yyyy)

returns the difference in days between the first and second date. This will be a negative value if the second date is earlier than the first.

DateToInt(mm/dd/yyyy)

converts the specified date to the number of days since midnight of December 30, 1899.

DayOfWeek(mm/dd/yyyy)

converts specified date to a numeric value representing the day of the week (1 = Sunday … 7 = Saturday). The system variable DOW returns the current day in the same format.

DecodeDataMatrix(filename [, inifilename])

scans a TIF or PDF file to find a DataMatrix symbol, and attempts to decode it. The value returned is the decoded message, empty if no symbol could be found/decoded.  See Using DataMatrix Symbols for details of the decoding process and the INI options.  If the verbose option is set, variables will also be set containing the co-ordinates of the symbol.

DoesFileExist(filename)

returns T (true) if the specified file exists or F (false) if it does not. The $ife command performs a similar function and also allows the specification of a minimum file size to qualify for 'existence'.

DoesPathExist(pathname)

returns T (true) if the specified folder path exists or F (false) if it does not.

EMailBuild(mailbox, domain, commentstring)

Create a full email address string from the passed components.  The comment string may optionally be enclosed in parentheses or double quotes: if not, it will be double-quoted unless it contains a double-quote character, in which case parentheses will be added unless it contains a parenthesis.  The effective address will be formed from mailbox@domain and will be enclosed in angle-brackets.  It is possible to create an invalid e-mail address with badly-formed components.  All parameters are required: if you do not need a comment string, use concatenation instead.

EMailValidate(address)

returns T (true) if the e-mail address can be parsed into its components, and F (false) otherwise.  Note that the mailbox and domain components are not individually validated.  Examples of failure cases include: two @ in effective address; unquoted comment text with an effective address having no angle brackets; mismatched angle brackets, double-quotes or parentheses.  The check covers common failure cases, but it is not guaranteed that the result rejects all invalid addresses.

Evaluate(expressionprecision)

returns the value of the arithmetic expression using the specified precision to format the result. Precision is specified as w.d where w is the minimum width of the returned value and d (following the decimal point) is the number of decimal places to return. The result is rounded to the decimal place specified. If you wish to round up the result, then you need to add the appropriate value. For example, if you are rounding up two decimal places, you should add .005 to the expression. The expression may contain parentheses, arithmetic operators, and built-in mathematical functions as described below. The result will be padded with leading spaces to the minimum width of the result (including decimal point). If you wish to pad the result with leading zeroes instead of spaces then specify the width with a leading zero. For example 5.2 will return a field of at least 5 characters in width, including the decimal point and two decimal places, and padded with leading spaces if necessary. If the precision is specified as 05.2, the result will be padded with leading zeroes instead.

ExtractFileExt(filename)

returns the file name extension for the specified filename. The extension will include the leading period.

ExtractFileName(filename)

returns the base file name, excluding the path but including the file extension, for the specified filename.

ExtractFilePath(filename)

returns the path name portion without the trailing backslash for the specified filename.

ExtractFileRoot(filename)

returns the root portion of the base file name, excluding the path and the file extension.

Faxable(filename [,RELN])

returns T *true) if the file is deemed to be faxable, F (false) otherwise.  One or more of the option letters R E L N may be used to relax the definition of faxable, accept landscape faxes, or disallow wide faxes: see the FAXABLE utility for details.

FindClose

Completes the search operation commenced with FindFirst.  If you fail to call this function it will be called automatically at line reset.

FindFirst(searchpathspec [, typecode [, attributes]])

This is the first function called to search for files or folder entries using the path and search specification in the first parameter. The parameters are used as follows:

searchpathspec This parameter should contain a path and a file specification using standard Windows wildcard file search specifications. Some samples are shown here:

C:\MyStuff\Customers\*.doc searches for files with .doc (MS Word) file extension in folder C:\MyStuff\Customers

C:\Temp\XM*.TIF searches for files with .TIF (image) extension and whose names begin with letters XM followed by any other sequence of characters in folder C:\Temp

C:\Temp\XM??ABC.txt searches for files with .txt (text) extension whose names begin with the letters XM followed by any two characters and ending with the letters ABC in folder C:\Temp

typecode This parameter specifies that files and/or folders should be returned, using one or both of the letters F and D respectively. At least one of these letters must be specified.
attributes Use A, H, S, R to find Archived, Hidden, System and Read-only files respectively (in addition to normal files). When omitted, only archived and normal files are returned.

The value returned by the function is the filename (without path) of the first matching file found (or an empty string if no matching file was found).

FindNext

This function finds the next file that matches the path and file specification and returns the filename of the next matching file if one is found or an empty string if not found. Read the description for FindFirst for more information.

Format(formatparm1parm2, …, parmN)

Returns a formatted string using the format specification in the format parameter. Each subsequent parameter is formatted according to the corresponding format specifier in the format string. The result is the format string with the format specifiers replaced by the corresponding formatted parameters specified in the second through last parameters. There should be one format specifier for each additional parameter.

GetAddress(address), GetComment(address), GetDomain(address), GetMailBox(address)

Parse the passed full email address and return, respectively, the effective address (mailbox@domain), the comment text (in quotes or parentheses, or outside angle brackets), the domain and the mailbox.  If the EMailValidate function returns false when passed the same address, some of the results of these functions may be undefined.

GetDefaultADSIPath

Returns the default Active Directory naming context for use in accessing Active Directory data.  If a context cannot be obtained, the result is empty.

GetFFConfigData(filenamekeywordtoken [, occurrence [, stripquotes]])

Returns the specified token for the specified keyword command in the CopiaFacts configuration file. The parameters are used as follows:

filename the CopiaFacts configuration file to be read.
keyword the command keyword (with leading $ sign)
token the token number on the command, with the first token following the keyword being numbered 1.
occurrence the numbered occurrence of the keyword in the file to be read. If omitted, this parameter is taken to be 1.
stripquotes the keyword true or false to specify whether double-quotes are to be stripped from the parameter before it is returned. If omitted, false is assumed.

GetFFVarDefData(filenamevarname)

Returns the value of the variable name specified in a $var_def command in the file specified in the first parameter.

GetGUID

Returns a Windows Globally Unique Identifier (GUID).

GetIniFileValue(inifilesectionkey)

This function returns a value from an INI file named in the inifile parameter for the section and key named in the second and third parameters respectively. If the key or section cannot be found then an empty value is returned.

GetRegistryValue(reghiveregkeyregvalue)

This function searches the registry hive specified by reghive for the registry key specified by regkey and the value specified by regvalue. The registry hive must be one of the literal constants or their common abbreviations in the following list: HKEY_LOCAL_MACHINE, HKLM, HKEY_CURRENT_USER, HKCU, HKEY_CLASSES_ROOT, HKCR, HKEY_USERS, or HKEY_CURRENT_CONFIG. If the value contains binary data then up to 256 bytes are read and returned as a string of hexadecimal characters with two characters for each byte of binary data. If the key or value cannot be found then an empty value is returned. On 64-bit systems only, you can optionally use HKCU64, HKCR64 or HKLM64 to read registry settings made by 64-bit applications. CopiaFacts applications (other than print drivers on 64-bit systems) are currently 32-bit applications and by default only see the 32-bit registry values.

GetToken(stringnTokenseparators)

returns the token specified by nToken from the string, where tokens are separated by any of the characters specified in the separators argument. If the string or the separators parameter contains a comma the whole parameter must be enclosed in single quotes.  The character sequence <TAB> if present in the separators parameter is replaced by a single TAB character before performing the operation.  TAB characters will normally only be found in lines read by ReadTextLine.

HTTPGet(URL, Query)

performs an HTTP GET operation to the specified URL (for example http://www.copia.com:80) sending the specified query (the part after the question-mark).  The question-mark should not be included with either parameter. The port used is 20 unless overridden.  The query is URL-encoded (e.g. embedded space converted to %20) The returned string is truncated at 8192 characters (the maximum size of a CopiaFacts variable value) if longer.  Use

HTTPPost(Server, Text, [Port])

performs an HTTP POST operation to the specified HTTP server (do not include http://) sending the specified text (usually as XML).  The returned string is truncated at 8192 characters (the maximum size of a CopiaFacts variable value) if longer.

IntToDate(nDays)

converts the number of days nDays to a date by adding the value in nDays to the base date of December 30, 1899.

IntToHex(valuedigits)

converts a decimal value in a string to a hexadecimal string with at least the passed number of digits and left zero fill. The output string does not have a '$' or '0x' prefix.  A hexadecimal input value preceded by '$' or '0x' or '0X' is also accepted as input.

IntToTime(nSecs)

converts specified seconds since midnight in nSecs to a time string hh:mm:ss.

IsBusinessDay(mm/dd/yyyy)

returns T (true) if the specified date is a business day or F (false) if it is not. The default for non-business days is Saturday and Sunday: to override this please contact Copia support for information.

IsHoliday(mm/dd/yyyy)

returns T (true) if the specified date is a holiday or F (false) if it is not.  The default is that no holidays are defined. Specific holiday dates can be set: please contact Copia support for information.

IsNumeric(value)

returns T (true) if the specified value is numeric or F (false) if it is not. The number may contain decimal positions using the local decimal separator character.

IsValidDate(mm/dd/yyyy)

returns T (true) if the specified date is valid or F (false) if it is not.

IsValidTime(hh:mm:ss)

returns T (true) if the specified time is valid or F (false) if it is not.

Length(string)

returns the length in characters of the specified string.

MakeDirectory(path)

creates directories as necessary to establish the specified path. Returns T if the directory exists after the operation, or F if the directory was not created.

NewBizDate(mm/dd/yyyynDays)

returns the date that is the number of business days specified by nDays from the specified date. The number of business days may be negative or positive.

NewDate(mm/dd/yyyynDays)

returns a new date that is the result of adding the number of days in nDays to the specified date.

NewTime(hh:mm:ssnSecs)

returns a new time that is the result of adding the number of seconds in nSecs to the specified time.

OCRConvertDocument(imageoutputfile [, page] [, exportformat])

This function invokes OmniPage automation to perform an OCR scan and conversion of the image specified in the first parameter to any of the export formats supported by OmniPage. The output of the conversion is placed in the file specified in the second parameter. The optional third parameter specifies a single page of the image for conversion. The default value for the page parameter is zero, which means that the entire document will be converted.

 

If a non-zero page parameter is specified, it must be within the range of one through the number of pages in the image. The image file must be a faxable TIFF format that is supported by the CopiaFacts engine. Any fax received through the CopiaFacts engine should meet this criterion. The page parameter is primarily used to extract the cover page of a received fax to scan it for routing information.

 

The optional fourth parameter is used to specify an export format string for OmniPage. When no export format is supplied, the function uses the file extension of the output file to determine one. An extension of .doc uses the string ‘Microsoft Word 2000, XP’. An extension of .rtf uses the string ‘WordPad’. An extension of .pdf uses the string ‘PDF’. An extension of .txt uses the string ‘Text with line breaks’. The use of any other file extension for the output file requires an export format in the fourth parameter. If one is not supplied, the function returns with a parameter error (1) in the system variable FUNCTION_RETURN.

 

This function may be used to perform any conversion supported by OmniPage automation available in OmniPage Office Pro versions 12, 14, or 15. The image to be converted only needs to be faxable TIFF when you are converting a single page of the image. If OmniPage is not installed or an incorrect version of OmniPage is installed the function returns with a -11 in the system variable FUNCTION_RETURN.

 

If the conversion succeeds the result returned will be zero. A negative result indicates an internal error writing the specified page of a single page conversion. Other positive error codes are listed in DLL Error Codes.

 

When an exception occurs or OmniPage fails to launch, the trace will normally provide additional information. Keep in mind that OCR scanning and conversion take time. A three-page fax may take approximately 20 – 30 seconds to convert depending upon processor speed, memory, and other factors. Scanning results will also vary with the quality of the image being scanned.

PageCount(filename [,G])

Returns the number of pages in a PDF or TIF file.  For a TIF file with extension .1, the function will count the number of pages in the successively-numbered files. A file with another extension, or a missing or incorrect file, will return either 0 or a negative value.  The G option letter applies to TIF files only, and causes the count to include good pages preceding an invalid page: without this option, a file containing one or more invalid pages will return 0.

Pos(substringstring)

Returns the starting position of substring within specified string. If the substring is not found within the string, this function will return 0.  This function is case-sensitive.

ReadTextLine(filenamelineno)

returns a line of text from the file with the specified filename if the line number specified in lineno is within the number of lines in the file. The first line is line number 1. This function should only be used for ASCII text files with lines separated by carriage return/line feeds. The line will be truncated if longer than 2048 characters.  TAB characters in the text are not expanded and remain as single characters.

SetAddress(address, effectiveaddress), SetComment(address, comment),

SetDomain(address, domain), GetMailBox(address, mailbox)

Parse the passed full email address and return it after substituting or adding, respectively, the effective address (mailbox@domain), the comment text (in quotes or parentheses, or outside angle brackets), the domain and the mailbox.  If the EMailValidate function returns false when passed the returned address, some of the passed variables were invalid.

StringReplace(sourcesearchreplace [, ignorecase] [, all] [, regex])

returns the source string with either one or all occurrences of the search string replaced by the replace string.  The keywords may be specified in any order.  Without the all keyword, only the first occurrence is replaced. The ignorecase keyword supports Unicode characters.  The regex keyword treats the search string as a Regular Expression, and the replace string as a Regular Expression replacement string.  In the regular expression replacement, you  can use either $1, $2, $3... or \1, \2, \3... as back-references (see www.regular-expressions.info/refreplace.html for more information.

StrToInt(string)

Converts a hexadecimal value (which must be preceded by '$' or '0x' or '0X') to a decimal value returned in a string. Passed decimal values without the hexadecimal prefix indicator are also returned unchanged.

TestDate(mm/dd/yyyymm/dd/yyyy)

compares the two dates and returns 0 if they are equal, -1 if the first date is earlier than the second, and 1 if the first date is later than the second.

TestTime(hh:mm:sshh:mm:ss)

compares the two times and returns 0 if they are equal, -1 if the first time is earlier than the second, and 1 if the first time is later than the second.

TimeConvert(hh:mm:ss, lcid)

Converts a time to the format specified by the SF_TIME_FORMAT using the specified Windows locale ID.  Use an LCID of 0 to signify the current locale.  Windows locale values can be found here, (or here for XP/2003).

TimeDiff(hh:mm:ss, hh:mm:ss)

returns the difference in seconds between the first time and the second time. This will be a negative value if the second time is earlier than the first.

TimeToInt(hh:mm:ss)

converts specified time to the number of seconds since midnight.

Trim(string)

Returns a copy of specified string with any leading and trailing spaces removed.

WriteTextLine(filenametext)

appends a line specified in text to the end of the file with the specified filename. Special character sequences <TAB>, <CR> and <LF> may be used to insert a tab, carriage return, or line feed respectively into the text. These special character sequences must appear in uppercase. If the file does not exist, it will be created. Returns T (true) if the file is written or F (false) if write fails. We strongly recommend not writing FS files into any CopiaFacts queue folder with this function. Use a $type fsfile infobox instead. Unpredictable results will occur if you ignore this recommendation.  Usually the filename would contain a variable name to make it unique to a line/thread, but this function is thread-safe so can be used to append to a common text file.  The text is written with system default encoding.