Support DLL functions are invoked using the following syntax:
$set_var varname "$fn:functionname(parmlist)"
The items in this example have the following significance:
|varname||the name of a variable to be set, normally without an @ prefix.|
|$fn:||a required identifier prefix.|
|functionname||the name of one of the provided functions listed below. Note that these are not functions that have normal entry points within the DLL that can be called from other programs. Function names are not case-sensitive.|
|parmlist||a list of parameters that must be supplied to the function, in parentheses. Parameters must be comma-separated. Each parameter may optionally be enclosed in single quotes (') and must be enclosed in single quotes if it contains commas or leading or trailing spaces. Otherwise leading and trailing spaces are trimmed from parameters so you can use whatever spacing you prefer for appearance. You must enclose the entire function syntax in double quotes (") if any portion of it contains a space.|
|For parameter values in single quotes which contain single-quote characters, the embedded single-quote character must be repeated. See the description of $set_var for an example.|
Functions may not be 'nested' in the parameter list. You must assign to an intermediate variable and use that variable in the parameter list of the subsequent function. Normal CopiaFacts variables may be used anywhere in the function name or parameter list with the usual @ syntax.
If the function is successful, the variable varname will contain the result of the function and the system variable FUNCTION_RETURN will contain a value of zero. If one of the function parameters was missing or invalid then FUNCTION_RETURN will contain a value of 1 and an empty value will be assigned to the specified variable varname.
Serious errors during function evaluation (for example an invalid path name) will result in a negative value being placed in FUNCTION_RETURN as described in Error Codes, This will normally cause a run-time error and processing of the infobox will be terminated. However the functions which are documented as returning an F on failure will not result in a run-time error when a serious error occurs: only an F will be assigned to the value.
For the functions are documented as returning a T/F value to indicate success or failure, you should always check that the value in @varname is T, and take appropriate action if not. Do not rely an F value to indicate an error, because if the error was caused by bad syntax early in the evaluation of the function, for example if the function name has a typo, the value assigned to varname might be empty.
Dates and Times
Dates and times passed into the functions as arguments may either use USA sequence and delimiters (mm/dd/yyyy, hh:mm:ss) or LOCAL sequence and delimiters, determined by the Windows locale settings on your machine. The default is LOCAL. You can change the setting during a call by assigning a value USA or LOCAL to control variable SF_DATETIME_PARM. This only changes the expected format of input parameters to the functions and has no effect on output formats.
We strongly recommend using four-digit years when supplying a parameter passed to any of the date functions. If a date supplied to a function contains only two digits of year, then a century value is added to the supplied date. The century used for this purpose is based on a 'pivot year' which is the current year less 50 years. Thus in 2002, a passed year of 51 becomes 2051 and a passed year of 52 becomes 1952.
Two special control variables control 'output' date formats for function results. Assignments to SF_DATE_FORMAT and SF_TIME_FORMAT variables may be made at any time to change the format returned by subsequent function calls, and these variables may also be set as defaults in CFG, USR/UJP or FS files. Strings composed as described in the Date Formats and Time Formats topics can be assigned to these variables, which affect only the current call. If the variables are not defined or set to an empty value then the Windows short date format (in the USA, normally mm/dd/yyyy) is used for date and the Windows short time format (in the USA, normally hh:mm:ss) for time values. For the purposes of all these function calls, the SF_DATE_FORMAT and SF_TIME_FORMAT variables are interpreted in the current system locale.
The date routines make use of non-business day information which has been set using the 'Set Non-Working Days' button on the Options page of the COPIAFACTS program (this data is recorded in FFCFG.INI in the base CopiaFacts folder). However if there is a file called HOLIDAYS.TXT in the CopiaFacts Application Data folder the routines will use Saturday and Sunday as normal non-working days and will read holiday information from this file. HOLIDAYS.TXT may contain up to 60 holiday dates in LOCAL date format and should only be used to specify holiday dates. This file is read in whenever COPIAFACTS starts and whenever the last modification date of the file has changed since the last function call.