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. |
| When a function reports a failure, you can run FFTRACE with CF9SUPPORT enabled under File/Applications to see details of the error. |
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.
returns a UNC file name for the file name specified in the srcfilename parameter.
returns the passed filename or pathname with the extension changed to that supplied. The extension may be specified with or without a leading '.'. To remove an extension, just use a single . (with or without single quotes) as the second parameter.
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. From build 9.1.0.370, the function will attempt to create the destination folder if it does not already exist.
CreatePDFThumbNails(srcfaxfilename, destfilename [, cols [, 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 if the input file 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 (remember to use single quotes if it contains commas). 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.
For an example of CreatePDFThumbnails, see SCRIPTS\REPORTSEND.IIF.
CreateThumbNail(srcfaxfilename, destfilename [, zoomfactor=8]|[, custom])
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, or can it be specified as a keyword custom, which causes an external program to be called whose command-line must be specified in variable THUMB_CUSTOM. The standard Windows image formats .BMP, .GIF, .JPG (or .JPEG) and .PNG are supported for the output thumbnail image. For an example of creating an .SVG thumbnail file with an external third party utility, see this topic. This function returns T if the thumbnail image was successfully created or F on failure.
If the source TIF file is missing or contains a non-faxable TIF file, the function will substitute a blank Letter/A4 size page, which will be reduced in size by the specified factor. A customer supplied TIF file may be supplied instead in the variable THUMB_BLANK before calling the function. A successful substitution will cause the function to return 'T'' and the THUMB_REPLACED variable will be set to a non-empty value. Note that the function may still report a failure if there is a problem saving the resized file.
Converts a date in the input format specified by the SF_DATE_FORMAT using the specified Windows locale ID for the output. Use an LCID of 0 to signify the current locale. Windows locale values can be found here. If the LCID is not a valid Windows LCID, the current locale will be used.
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.
converts the specified date to the number of days since midnight of December 30, 1899.
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.
Parses the passed email address to extract the effective address, then returns T (true) if a matching public key file (.CER) for the address exists in the FAXFACTS\CERTIFICATES folder (with @ replaced by # in its filename). The value returned is F (false) if the address is not a valid e-mail address or the certificate file is not present.
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'.
returns T (true) if the specified folder path exists or F (false) if it does not.
EMailBuild(displayname, mailbox, domain, commentstring)
Create a full email address string from the passed components. The displayname and commentstring may optionally be enclosed in double-quotes and parentheses respectively; if you supply the surrounding characters, you must escape (with a preceding \ character) any embedded occurrences of the same characters. The mailbox must be double-quoted if it contains blank or non-ASCII characters. The effective address will be formed from mailbox@domain and will be enclosed in angle-brackets when other components are present. It is possible to create an invalid e-mail address with badly-formed components. All parameters are required.
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(expression, precision)
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.
returns the file name extension for the specified filename. The extension will include the leading period.
returns the base file name, excluding the path but including the file extension, for the specified filename.
returns the path name portion without the trailing backslash for the specified filename.
returns the root portion of the base file name, excluding the path and the file extension.
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.
Completes the search operation commenced with FindFirst. If you fail to call this function it will be called automatically at channel 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. Only one search at a time can be performed on each channel, and the previous search will be closed automatically if FindFirst is called more than once during a call. 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). The search is closed automatically when an empty string has been returned.
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. The search is closed automatically when an empty string has been returned. Read the description for FindFirst for more information.
Format(format, parm1, parm2, …, 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. Note that the syntax for the format specification should be familiar to a C programmer, but there are small differences from sprintf().
GetAddress(address), GetDisplayName(address), GetComment(address),
GetMailBox(address), GetDomain(address)
Parse the passed full email address and return, respectively, the effective address (mailbox@domain), the display name in double-quotes, the comment text (in parentheses), the mailbox (local name) and the domain. If the EMailValidate function returns false when passed the same address, some of the results of these functions may be undefined and the FUNCTION_RESULT value will be 1.
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(filename, keyword, token [, 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(filename, varname)
Returns the value of the variable name specified in a $var_def command in the file specified in the first parameter.
Returns a Windows Globally Unique Identifier (GUID).
GetIniFileValue(inifile, section, key)
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(reghive, regkey, regvalue)
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(string, nToken, separators)
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 [, ResultMsg])
performs an HTTP or HTTPS GET operation to the specified URL (for example https://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 default port is 80 unless an override is provided (preceded by a colon) in the URL. 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. On error, the result string will be empty and the error will be reported in ResultMsg, if supplied, and in the CF9SUPPORT output in FFTRACE. If the ResultMsg parameter is supplied, it will be cleared if the GET operation succeeds. The default connection timeout is one minute, unless a variable HTTP_CTO is set to an override value (in milliseconds) before calling the function.
HTTPGetFile(URL, Query, Pathname)
performs an HTTP or HTTPS 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 default port is 80 unless an override is provided (preceded by a colon) in the URL. The query will be URL-encoded (e.g. embedded space converted to %20) The returned string from the Get is written to a file with the supplied pathname, with UTF-8 encoding, and the function return value is T if successful, F on failure. If you plan to download an HTML document in this way for faxing, it may be easier to use an http:// URL on a $fax_filename command: this method also allows the use of Javascript in the document. The default connection timeout is one minute, unless a variable HTTP_CTO is set to an override value (in milliseconds) before calling the function.
performs an HTTP or HTTPS POST operation to the specified URL sending the specified text (often as JSON or XML). The http:// or https:// prefix must be included in the URL. The returned string is truncated at 8192 characters (the maximum size of a CopiaFacts variable value) if longer. The default port is 80 unless an override is provided (preceded by a colon) in the URL. To send a JSON post, see the $json operator in $set_var. The result is the HTTP status text of the sever response (OK for success) or an error message. The default connection timeout is one minute, unless a variable HTTP_CTO is set to an override value (in milliseconds) before calling the function.
converts the number of days nDays to a date by adding the value in nDays to the base date of December 30, 1899.
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.
converts specified seconds since midnight in nSecs to a time string hh:mm:ss.
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.
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.
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.
returns T (true) if the specified date is valid or F (false) if it is not.
returns T (true) if the specified time is valid or F (false) if it is not.
returns the length in characters of the specified string.
LookupExcel(keyvalue, keycolumn, resultcolumn)
uses a value in an Excel keycolumn to return a value from another column. The path of an XLS or XLSX file must be available in variable LOOKUP_EXCEL_PATH. For the first row in which the keyvalue is found in column keycolumn, the value in resultcolumn is returned. Comparison is not case-sensitive, and only the first or only sheet in the file is searched. The column values may either be specified as an index number (base 1) or the Excel column letter(s): for example B is equivalent to 2 and AA is equivalent to 27. An empty value is returned if there are fewer than resultcolumn columns on the row. If the key is matched, FUNCTION_RETURN will contain 0; if no match for KEY is found, an empty value is returned and FUNCTION_RETURN will contain 1. For error results, see Error Codes.
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.
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.
returns a new date that is the result of adding the number of days in nDays to the specified date.
returns a new time that is the result of adding the number of seconds in nSecs to the specified time.
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 x parameter applies to TIF files only: the letter G 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. And the letter E causes empty pages without image data to be included in the total.
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(filename, lineno)
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), SetDisplayName(address, displayname),
SetMailBox(address, mailbox), SetDomain(address, domain), SetComment(address, comment)
Parse the passed full email address and return it after substituting or adding, respectively, the effective address (mailbox@domain. without angle-brackets), the display name (in double-quotes) the comment text (in parentheses), the mailbox and the domain. It is recommended to check the passed full address first using the EMailValidate function. The display name and the comment may be passed with or without their double-quotes and parentheses respectively. If the passed address is not valid the returned value from the Set.. function will be undefined and the FUNCTION_RETURN value will be 1.
StringReplace(source, search, replace [, 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.
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/yyyy, mm/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.
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.
Converts a time in the input format specified by the SF_TIME_FORMAT using the specified Windows locale ID to format the output. Use an LCID of 0 to signify the current locale. Windows locale values can be found here. If the LCID is not a valid Windows LCID, the current locale will be used.
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.
converts specified time to the number of seconds since midnight.
Returns a copy of specified string with any leading and trailing spaces removed.
appends a line specified in text to the end of the file with the specified file name. 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. Special characters may also be inserted using <#nnn> where nnn is a three-digit character number. 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 file name would contain a variable name to make it unique to a CopiaFacts channel, 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.
WriteUnicodeLine(filename, text [, utf8|unicode])
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. 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 file name would contain a variable name to make it unique to a CopiaFacts channel, but this function is thread-safe so can be used to append to a common text file. The entire file is rewritten with the specified encoding, or with system default encoding if the third parameter is omitted.
