Internal Functions

arrtostr(arr$[all],str$,dlm$)

Converts array arr$[all] to delimited string str$, using dlm$ as delimiter.

arrset(arr$[all],col,row,cols,val$)

Sets val$ into the one-dimensional array at the position specified.  If val$ contains linefeeds, it is treated as a multi-row value, and the row increments for each additional row in val$.  The array is redimensioned as necessary to accommodate the row and position.

basename(file$)

Returns the base name, without path information, from the file name specified.  See also dirname().

bbxread(file$,key$,rec$,errcode)

Executes an instance of BBx, configured with the bbpath=path line in uf101d.ini, and obtains the record specified by key$ in file$.  If an error occurs in the BBx instance, it is returned in errcode.  An errcode value of –1 indicates no error occurred.  The variable rec$ can be DIMed as a string template, but be sure to use '=10' to define field separators, as the default separator in the ProvideX engine is a hex 8A rather than the BBx default hex 0A.  If it is not defined as a template, the raw record data is returned and may be parsed.

Here is an example:

prepage{

ky$=get(65,5,6)

dim rec$:"id:c(5*=10), *:c(1*=10), …, fax:c(9*=10)"

bbxread("/u/data/CUSTOMER",ky$,rec$,ec)

if ec=-1 then faxnum$=rec.fax$

}

catsegs(seg1$[,seg2$...])

Returns a pipe-delimited category index string, simplifying code-based library access to category indexes.

cdate(datestr$ [,fmt$])

Converts a text date to a date (Julian) number, suitable for date compares, calculations, and use in the dte() function.  The datestr$ can be a string in delimited format, based on the fmt$ string, or can be a simple string if digits in yyyymmdd[hhmmss] format.  The format can be mdy, dmy, or ymd and a delimited date is parsed according to that order.  

The default date format is defined in uf101d.ini (datefmt=mdy).

If a time is included, the value returned will include a fraction.  Note that the dte() function requires an integer for the day portion, and the time portion, if provided, is an hours value:

 x=cdate("12/31/2009 3:00 pm","mdy")

 x$=dte(int(x),fpt(x)*24:"%Mz/%Dz/%Yz %Hz:%Mz")

clientenv(name$)

Returns a client-side environment variable value.

cmtocols(centimeters)

cmtorows(centimeters)

Returns columns or rows, given a centimeter measure.

cnum(expression)

Returns a number from a text string, after stripping formatting characters such as commas and dollar signs.  Parentheses and minus signs indicate negative numbers.  Use this function, rather than the intrinsic num() function, to convert text to numbers if the text can contain punctuation.

count(str$,dlm$)

Counts elements of a string, parsed by a delimiter.

countq(str$,dlm$)

Counts elements of a string, parsed by a delimiter, honoring quoted strings.

cstrans(text$,fromcs$,tocs$)

Returns text$ after translating it from one character set to another.  Character set names include "uc", "utf16", or "utf-16" for unicode, or "utf8" or "utf-8" for UTF-8 encoding, or any of the character sets or symbol sets available in the UnForm unicode directory, such as 9j or 8859-1.  The default character set is 9j, a pcl symbol set similar to ISO 8859-1.

cut(col,row,cols,value$)

Returns the value text at position col, row, for cols columns, after setting the specified position to value$.  If value$ is null ("") or spaces, cut() effectively erases the text.  This is useful for moving data in text commands, such as text 10,60,{cut(10,59,10,"")}, which would cut text from 10,59 and move it to 10,60.

PostScript input not supported.

dataurlencode(fl$)

dataurldecode(str$)

dataurltype(str$)

dataurlext$(str$)

Return a file's contents as a data url, or decode a data url into a binary string value, the MIME type of a data url, or the file extension of a data url (based on the MIME type).

dbconnect(name$[,timeout[,errmsg$]])

Connects to the database source identified by name$.  The support server configuration is used to define the names and associate them with data source connection strings.  Typically done in a prejob code block.  Requires the Windows Support Server.  If executed as a function, returns 1 on success, or 0 on failure.

dbexecute(name$, command$, timeout, fdelim$, rdelim$, response$[,errmsg$])

Executes the SQL command cmd$ and sets zero or more result rows in response$.  Columns are delimited by fdelim$ (tab - chr(9) - by default).  Rows are delimited by rdelim$ (CR-LF - chr(13)+chr(10) - by default).  Requires the Windows Support Server, and a previously successful dbconnect() function execution in the current job.  If executed as a function, returns 1 on success, or 0 on failure.

deliver(filename$,to$,tags$ [,response$[,errmsg$]])

This function delivers the filename to a destination by fax or email, depending on the to$ value.  The rule is simple: if  to$ contains an "@" character, it is emailed.  Otherwise, it is faxed.

Tags are in the format name=value[,name=value ...].  Delimit each name=value pair with either commas or semicolons. The value can be quoted if it contains commas or semicolons.  Tags are substituted with values in the fax/email configuration lines found in deliver.ini.  

The deliver.ini file contains configuration information for delivery methods.  This file is documented in the Deliver Configuration chapter.  See also the Deliver command, which simplifies subjob management for delivery while printing batches of documents.

delpage(n)

Command removes page n, pages n+1 to end are shifted down.

PostScript input not supported.

dirname(file$)

Returns the directory portion of the file name provided.  The value returned uses forward slashes on all platforms, and does not include a trailing slash.  See also basename().

docidexists(lib$,doctype$,docid$)

Returns 1 if the document type and ID exists in the library, or 0 if not.

dtdel(filename$, title$, userid$, ip$ [,style [,errmsg$]])

Deliver filename$ to the userid$ and/or IP address specified (the ip address can include a session suffix).  The title$ will be presented to the user.  A style of 0 indicates deliver for optional viewing, and 1 indicates immediate popup.  If an error occurs, a message will be returned in errmsg$.  See the Desktop Delivery and Forms chapter for details.

If the filename$ parameter is a message starting with "msg:", it is treated as a popup message rather than a file.  For example: "msg:Check the printer for invoices" would display a message window with the indicated text as the content.

dtform(formname$, title$, userid$, ip$, datastr$, response [,timeout [,errmsg$]])

Deliver the HTML form formname$ to the userid$ and/or IP address specified.  The ip address can include a session suffix.  The title$ value is presented to the user for approval.  The datastr$ is a URL-encoded string that can be filled before the function is executed to provide default values for the form, and will contain URL-encoded data returned when the user submits the form.  The response code will be 0 if the form was submitted, 1 if the user cancelled the form, 2 if the form timed out, or 3 if the user refused the form.  The timeout can be specified to limit the amount of time the user has to accept the form (the default is 30 seconds).  If an unexpected error occurs, a message is returned in errmsg$.  See the Desktop Delivery and Forms chapter for details.

If timeout is set to -1, then the user will not be prompted to accept the form.  Instead, the form will be displayed immediately.  However, if the user is not present or the monitor is not running, the form will not be responded to and no timeout notification will occur.  Instead, the job will wait until terminated.  This option should only be used if the user is guaranteed to be present, such as a follow up form to one that was previously accepted and submitted immediately before.

The urlsetval and urlgetval functions can be used to create and parse the datastr$ values.

email(to$, from$, subject$, body$, attach$, cc$, bcc$, otherheaders$, login$, password$,logfile$)

Sends an email, assuming emailing is properly configured in the mailcall.ini file, using the information supplied.  The arguments are positional but need not all be supplied.  For example, email(trim(get(81,1,40)), "info@acme.com", "Please review", messagebody$) will send a plain message to the address stored at column 81, row 1, for 40 characters in the current page.  No attachment, carbon copy, etc. information will be used.  A logfile option may be used to capture SMTP communication information, but should be unique to ensure two jobs do not try to use the same file at the same time, which would cause an error.

As the arguments are positional, if you need to supply a login and password for the mail server to perform authentication, then all the arguments must be supplied, even if simply null ("").  Note that this email function is different from the email command, in that the job itself is not sent, and multiple emails can be sent during the job stream within code blocks.  This is useful, particularly in combination with the jobstore and jobexec functions, to develop batch email jobs.

The logfile argument may contain substitution tags as described in the deliver command.

entityencode(str$), entitydecode(str$)

Two functions that return str$ with HTML or XML entities encoded or decoded.  For example, in HTML, the "<" and ">" characters are meaningful for character markup, so to reference those characters literally, rather than as markup, they are encoded to "&lt;" and "&gt;", respectively.  When reading or writing data from a HTML page or XML document, it may be necessary to use these functions.

env(name$)

Returns the value of the operating system environment variable in name$, or in a literal quoted string.  Returns null ("") if the variable does not exist.

err=next

May be used for any err=label option in any function or statement.  Forces UnForm's error trapping to ignore an error.  You may, of course, name your own err=label if desired.

exec(expression)

Executes a barcode, bold, box, erase, font, image, italic, light, micr, move, shade, or text command from within the code block. Expression must be a single string value that contains the text of such a command, such as exec("box "+str(col)+","+str(row)+",30,2.5").  You can use the exec() function to add enhancements to a print job within the code block.  The function can be used in either prepage{} or precopy{} blocks.  Remember that some commands need quoted parameters to work properly.  For example, if you exec() a text command, be sure to add quote characters around the text to be printed, using one of three methods: double any internal quotes, use an expression that uses $22$, chr(34), or QUO for quotes

For example, exec("text 10,10," + chr(34) + message$ + chr(34) + ",cgtimes,10")

Any linefeed characters in the string are treated as command delimiters.  Passing multiple commands in one exec() can improve performance, perhaps noticeably if there are many exec's being performed in a job  Be sure if a text value contains linefeeds that are intended to print multiple lines that you substitute linefeed characters with the mnemonic "\n" sequence.  Note that the mget() function can return linefeed-delimited data.

exists(file$)

Returns 1 (true) if the file path specified exists, 0 (false) otherwise.

fileext(file$)

Returns the extension of file name provided, without the leading ".".  The extension is the segment of the name after the last ".".

finddata(text$[all], search$, coloffset, rowoffset, columns, result$[all])

Searches the text array for a search string, and returns each item found in the result$ array.  The data returned is based on the locations found, offset by the coloffset and rowoffset values, and the length specified.  Each result is trimmed of leading and trailing spaces.

The function returns the number of positions found, and the result$ array is indexed from 0 to the number of positions minus 1.  Result$[0] is the first item found, result$[1] is the second, and so on.

This function is useful for report mining, where specific types of rows contain the data desired.

See the findpos() function for a description of how the search$ string is interpreted.

findpos(text$[all],search$,result[all])

Searches the text array for a search string, and returns the number of locations found.  Each location found is returned in the response[all] array.  The result array is structured as follows:

result[0,0]=first column

result[0,1]=first row

result[1,0]=second column

result[1,1]=second row

The first dimension contains each position found, from 0 through the number of positions minus 1.  The second dimension contains column numbers in element 0, and  row numbers in element 1.

The search string can be a simple string, or a tilde (~) followed by a regular expression.  If the string contains a "@" character, then two, three, or four comma-separated digits should follow, indicating the starting column,row, and ending column,row to search in the text array.  If the ending row is not supplied, search ends at the last row in the array.  If the ending column is not supplied, all columns from the first column are searched.

"Total@50,45,54,66" will search for the word "Total" in columns 50 through 54, rows 45 through 66 in the array.

fitpage(pagenum [,"size" [,"charset"]]

Re-scales the specified page to the size specified, or the current paper size if not supplied.  The page overlay and text stream are both updated to reflect the new size.  If supplied, the character set is used when parsing the text extraction data.  It defaults to ISO-8859-1.

AFO jobs only.

formatnumbers(lines$,format$[,dlm$])

Formats number values in the lines, using a format mask.  The default delimiter is a linefeed ($0a$ or chr(10)).  A literal \n is also interpreted as a linefeed, in both lines$ and dlm$, and if present in lines$ will result in a response that contains \n rather than linefeeds.  The mask uses $, #, 0, -, . characters.  Example: formatnumbers(lines$,"$#,###,###.00-").

fromuc(text$,charset$)

Converts unicode text to single-byte  text in the character set specified.  Characters that are not present in the character set are replaced with a "?".  Returns the single-byte text.  Known character set tables are specified in the UnForm unicode directory.  Also, "utf8" or "utf-8" can be used to convert UTF-16 (Unicode) format to UTF-8, a common encoding for XML or HTML data.

get(col,row,cols)

Returns text from the text$[all] array, without substring or array out-of-bounds errors.

get(col,row,cols,trim$)

Same as get(), but with a trim "Y" or "N" option.

get(col,row,cols,trim$,page)

Same as get(), but with a trim "Y" or "N" option, and a page number option to retrieve information from any page of the job.

get(col,row,cols,trim)

Same as get(), but with a Boolean trim (0 or non-0) option.

get(col,row,cols,trim,page)

Same as get(), but with a Boolean trim (0 or non-0) option and a page number option.

getaddress(book$,entityid$,doctype$,address$)

Opens the address book specified, and fills the address$ template with data from the address book entry for entityid$ and doctype$.  The address book template can be referenced as address.entityid$, address.doctype$, address.entityname$, address.contactname$, address.sendto$, and address.combine.

The function returns 1 if successful, or 0  if not.                                

getarc(lib$,doctype$,docid$,subid$, filename$ [,errmsg$])

Retrieve an archive image to a user-specified or temporary file.

getcolumn(rows$,column[,first[,count[,fdelim$[,rdelim$]]]])

Slices a column from a block of delimited rows, returns fields delimited by $0A$.  fdelim$ defaults to $09$, rdelim$ to $0A$.  If first and count are  supplied, slice begins at row "first" and continues for "count" rows.  This provides easy pagination capabilities.

If count=0, slice continues to last row.

getdocidprop(lib$, doctype$ ,docid$, prop$)

Sets prop$ to a composite string containing properties about the document specified.  These properties include:

Prop.date$ - date in yyyymmdd format

Prop.time$ - time in hhmmss format (24-hour clock)

Prop.title$ - title string

Prop.entityid$ - entity id string

Prop.notes$ - notes, which can have CRLF line breaks

Prop.keywords$ - semi-colon delimited keywords

Prop.categories$ - semi-colon delimited categories with pipe-delimited segments

Prop.links$ - semi-colon delimited list of links

If the document type and ID does not exist in the library, each of the fields in the composite string will be empty.  Use the docidexists() function to determine if a document exists.

getfile(filename$)

Returns contents of filename$ as a string.  Can be used to load a file into a string.

getfilefield(filename$,key$ ,field)

getfilefield(filename$,key$ ,field, dlm$, quoted)

getfilerec(filename$,key$)

getfilerec(filename$,key$, dlm$, quoted)

Returns a record or field from a text file, given a key that matches the first field in each record.  The dlm$ field is a field delimiter, such as "," or chr(9) for comma or tab delimiters, and the quoted field is a Boolean (0=false, non-0=true) that indicates fields may be quoted, as would be the case in a csv file.  If no matching key is provided, the functions return an empty string.  If no dlm$ and quoted parameter is supplied, then a comma-separated-value format is presumed (dlm$=",", quoted=1).

These functions provide an efficient way of providing data to UnForm from applications.  For example, an application could export customer IDs and email addresses, and UnForm could lookup addresses by customer ID.

Files are parsed once and cached until they change, so subsequent retrievals are very fast.  Caching is permanent (across jobs).

Keys are limited to 127 bytes, so the first column must be limited accordingly.

In a quoted file, fields that contain a quote character must escape that character with a backslash, like "Board - 1' 2\" length".

getinival(filename$,section$[,name$])

Returns the section or, if name$ is supplied, the value of the name in the section specified, of the .ini formatted file specified.  .ini files are organized in to sections via [name] headers, and lines within the section contain name=value pairs.  When a full section is returned, each line is delimited by a linefeed character (chr(10) or $0a$).  This can be useful in cases where data is stored in .ini file format and UnForm needs to access it.  If filename$ doesn't exist, it is treated as ini file content.

getpage(n,arr$[all])  

Fills text array arr$[all] with page n data lines.

PostScript input not supported.

getpaircount(values$ [,delim$])

Returns the number of delimited pairs in value$.  For the string "id=00100,name=Acme Corp", the count would be two.  The default delimiter is a comma.

getpairvalue(values$,number[,delim$])

Returns the value of the specific name=value pair in the values$ string.  Pairs are delimited by commas unless delim$ is specified.  The first pair is number 1, the second is number 2.

getpairvalue("id=00100,name=Acme Corp",2) returns Acme Corp.

getpairvalue(values$,name$ [,delim$] [,casesensitive])

Returns the value associated with the name from the delimited list of pairs in values$.  The default delimiter is a comma.  If casesensitive is true (1), then the name must match exactly.  If the name is not found in values$, then null is returned.

getpairvalue("id=00100,name=Acme Corp","name") returns Acme Corp.

getpatternvalue(pattern1$,pattern2$, array$[ ] [,erasepat,[includepat] ])

Searches each element of the one-dimensional array for text that starts with pattern1$ and ends with pattern2$.  If either is null, returns from the beginning or end of the line. If either starts with ~, balance is a regular expression (use \~ to enable ~ as a search character).  

The text data found is returned, each element separated by a linefeed ($0A$), optionally with the pattern(s) included if includepat is true (non-zero).

If erasepat is true (non-zero) then the pattern and text found is removed from the line on which it is found.

Only the first match in each array element is returned.

getpatternvalue(pattern1$,pattern2$, searchtext$ [,erasepat,[includepat] ])

Searches searchtext$ for text that starts with pattern1$ and ends with pattern2$.  If either is null, returns from the beginning or end of the line. If either starts with ~, balance is a regular expression (use \~ to enable ~ as a search character).  

The text data found is returned, optionally with the pattern(s) included if includepat is true (non-zero).

If erasepat is true (non-zero) then the pattern and text found is removed from the line on which it is found.  Note searchtext$ must be passed as a variable, rather than a literal or expression, for this to work.

Only the first match in searchtext$ is returned.

getppdval(name$,option$)

Returns a value from the PPD file associated with the job, either a default file selected by the –p driver command line option, or one explicitly named with a –m command line option.  PPD files are generally used by PostScript printers to define command sequences for settings like duplex, bin, and tray selection.  The laser driver can also use a custom PPD file for defining PCL sequences for various printer options.  This function can be used to retrieve control sequences for use in boj, eoj, bop, or eop values.

getsubids(lib$,doctype$,docid$[,dlm$])

Returns a list of document archive sub ID’s, delimited by linefeeds or by the specified delimiter.

gettrans()

Returns the active translation file.

getuserprop(userid$,prop$)

This function fills the template variable prop$ with attributes for the specified user.  It returns 1 on success, or 0 if there is an error.  If there is an error, the template contains empty fields.  The template fields can be referenced as:

Prop.username$

Prop.email$

Prop.entityid$

Prop.companyname$

Prop.telephone$

Prop.groups$ (semicolon-delimited groups the user is a member of)

gproperty(name$)

Returns the DSC structured comment value of the given name from a AFO print stream.  The most common use for this is to obtain a document title from the PostScript data, such as title$=gproperty("Title").  Comments can be found in the header and trailer of the PostScript data.

gtextcount(page)

Returns the number of text elements found on the specified page.

This function is valid only for AFO jobs.

gtextitem(page,item,text$[,col [,row [,cols [,rows]]]]

Fills text$ with the specified text element identified by page and item, where item can range from 1 to the number of text elements on the page.  If supplied, will fill col, row, cols, and rows variables with the position and size of the text item.

This function is valid only for AFO jobs.

gtextfind(page, pattern$, txt$[all], rects[all])

Scans the specified page for text elements matching the specified pattern.  For each element selected, the text is added to txt$[n], and the position and size of the text is added to rects[n,0-3], where 0 is the column, 1 is the row, 2 is the columns, and 3 is the rows. n is 1-based, so the first array element is txt$[1], and rects[1,0].  In addition, the number of elements is supplied in rects[0,0].

Pattern$ can be a simple text phrase, which must be contained in a text element to be selected, or it may be in the format "~regexp" to search for a regular expression.  In addition, it may have a @col1,row1,col2,row2 suffix to limit the search to text elements enclosed by the specified rectangle.  To search for a value that includes a literal "@", use "\@".

The function returns the number of elements selected, which can be used to as the range of valid elements placed in txt$[all] and rects[all].  If the function returns 2, then txt$[1] and txt$[2] contain the first and second text elements selected.

This function is valid only for AFO jobs.

gtextword(page,item)

Returns the item specified, generally a word or phrase, from an AFO job print stream.  The item can be any number from 1 to the number of elements on the page (which can be determined with the gtextcount() function, above. If the page/item does not exist (out of range, for example), the function returns null ("").

This function is valid only for AFO jobs.

gtextwords(page, pattern$, direction$, col, row, cols, rows ,[filter$ [,instance [,rects[all] ] ] ] )

Returns a list of words found in a rectangular region relative to a search pattern.  Words from the same line are space-separated, with linefeeds ($0A$) delimiting rows.

Pattern$ can be a simple text phrase, which must be contained in a text element to be selected, or it may be in the format "~regexp" to search for a regular expression.  In addition, it may have a @col1,row1,col2,row2 suffix to limit the search to text elements enclosed by the specified rectangle.  To search for a value that includes a literal "@", use "\@".

The direction value must be u, up, d, down, l, left, r, or right.  This determines the direction from a found pattern to scan for words.  

The col and row values are offsets from the found pattern, and cols and rows values are dimensions from which to gather words.

Filter$ can be a text string or regular expression prefixed with "~".  Only words that include the text or match the regular expression are returned.

Instance is the occurrence of the search pattern on the page, if there is more than one.  It defaults to 1.

The rects[all] array will receive positions of the words in the same format as the rects[all] array returned by gtextfind().

This function is valid only for AFO jobs.

gtextwords(page, pattern$, wordoffset, wordcount ,[filter$ [,instance [,rects[all] ] ] ] )

Returns a space-separated list of words found adjacent or near a search pattern.

Pattern$ can be a simple text phrase, which must be contained in a text element to be selected, or it may be in the format "~regexp" to search for a regular expression.  In addition, it may have a @col1,row1,col2,row2 suffix to limit the search to text elements enclosed by the specified rectangle.  To search for a value that includes a literal "@", use "\@".

The wordoffset and wordcount values indicate  a relative word offset (positive or negative), and the number of words to return

Filter$ can be a text string or regular expression prefixed with "~".  Only words that include the text or match the regular expression are returned.

Instance is the occurrence of the search pattern on the page, if there is more than one.  It defaults to 1.

The rects[all] array will receive positions of the words in the same format as the rects[all] array returned by gtextfind().

This function is valid only for AFO jobs.

gtextwords(page, pattern$ , [,instance [,cutdef$ [,rects[all] ] ] ])

Returns a list of words matching a search pattern, optionally trimmed of specific data.  Words from the same line are space-separated, with linefeeds ($0A$) delimiting rows.

Pattern$ can be a simple text phrase, which must be contained in a text element to be selected, or it may be in the format "~regexp" to search for a regular expression.  In addition, it may have a @col1,row1,col2,row2 suffix to limit the search to text elements enclosed by the specified rectangle.  To search for a value that includes a literal "@", use "\@".

Instance is the occurrence of the search pattern on the page, if there is more than one.  It defaults to 1.

Cutdef$ can contain the word "cut" plus optional letters indicating what to cut from the words.  "Cut" by itself removes the matched pattern from the words.  "Cut L" removes characters to the left of the match.  "Cur R" removes characters to the right of the match.  "Cut LM" or "Cut RM" remove to the left or right, plus the match itself.

The rects[all] array will receive positions of the words in the same format as the rects[all] array returned by gtextfind().

This function is valid only for AFO jobs.

gtextwordsexec()

This is a utility function related to the various gtextwords(...) functions.  Whenever a gtextwords(...) function executes, it builds an exec()able string that highlights words found with a series of box commands.  Immediately after gtextwords(), capture this value and exec() it to highlight words.  Note that the page number specified in the gtextwords() function should match the page on which the exec() function executes.

ifn(boolean,true,false)

ifs(boolean,true$,false$)

Return the true or false number, or true$ or false$ string, based on the boolean value or expression, where 0 is false and non-0 is true. The ifn() function is used when returning a number, and ifs() when returning a string.

ifs(cust$>"", cust$, "n/a") would return the cust$ value if it is non-null, or "n/a" if it is.

imgx(imagefile$,units)

imgy(imagefile$,units)

These functions to return image x and y dimensions, helpful when trying to   scale an image to actual size.  Units indicate what is returned: 0=pixels, 1=inches,  2=cols/rows.

The function supports jpg, bmp, tif, and png formats.  If the file can't be opened or parsed, 0 is returned.

inchtocols(inches)

inchtorows(inches)

Return columns or rows, given a measurement in inches.

inspage(n,arr$[all])  

Inserts text array arr$[all] as page n, shifting existing pages as necessary.  If n is any number greater than the highest page number, or -1, a page is appended (i.e. inspage(999,x$[all]) will add page 3 to a 2-page job.

PostScript input not supported.

iszonepagehdr(str$)

Returns true (1) if the string is a page header from a grid zone or column, false (0) otherwise.  Normally used when parsing linefeed delimited ocr column data, to skip page header rows.

jobclose(id$…)

Closes and erases the temporary storage file associated with id$.  Open jobs are all automatically closed at the end of the primary job.

jobids(dlm$)

Returns a list of job ID values that are active, separated by the delimiter character specified.  Any ID supplied in a previous jobstore()  command and not closed with a jobclose() command will be returned.

jobexec(id$,output$,driver$,argstring$ [,async])

Executes a sub-UnForm job using the parameters given.  The id$ identifies a job with one or more pages previously stored with the jobstore() function.  The output$ value defines where the sub-job's output should go.  This can be a file name, like "/archive/"+invoice$+".pdf", a device name, like "//printsrv/hp4000", or a pipe/redirect, like ">lp –dhp4000 –oraw".  The driver$ argument can be set to one of the –p drivers supported by UnForm, such as laser or PDF.  The argstring$ contains any additional command line parameters you wish to add to the sub-job command line.  You can use any parameter supported by the uf101c client, though the -i, -o, and -­­p options are specified using the other three function arguments.

A rule set can check uf.subjob, as "if uf.subjob" or "if uf.subjob=1", to test if an instance is running from a jobexec() function.

The optional async flag can be set to a non-zero value to force the job to be executed asynchronously, so the jobexec() command returns as soon as the subjob is queued.  This operates via the rpq directory, which means the subjob will execute within a few seconds, as long as there is a job license available.  If not, the job will remain queued until a license is free.  Note that if you use this flag, the main job must be able to operate without the subjob output.  For example, if the main job is designed to email or fax a result of a subjob, it will fail.  Such processing should be moved into the subjob’s execution context.

jobfile(id$)

Returns the temporary text file associated with id$.

jobstore(id$ [,array$[all]])

Stores the content of the current page in a temporary file, identified by id$.  The value in id$ is user-defined, and each unique value stores content in a different temporary file.  The other job-related functions use the id$ value to select which file to use.  For example, you could store a whole job with an id$ of "job", and individual documents in jobs identified by their document number.  Each would be stored separately and could be jobexec'd separately.

If the optional array is supplied, then it, rather than the current page content, is written to the work file.  If supplied, the array must be a one-dimensional string array (i.e. dim myText$[66]).

lbound(arr$[all][,dimension])

Returns the lower-bound of the array arr$[all].  If arr$ contains multiple dimensions, you can specify which dimension.  For example, if arr$ is dimmed as x$[100,1:2], lbound(x$[all])=0, lbound(x$[all],2)=1.

left(str$,length)

Returns the leftmost length characters from str$, padding with spaces on the right to enforce length.  Note also the mid() and right() functions.

libexists(lib$)

Returns 0 if library lib$ doesn't exist, or 1 if it does.

linecalc(lns1$,lns2$,operator$ [,dlm$ [,allownull]])

Returns a delimited string based on performing an operation on each sequential pair of delimited elements from strings lns1$ and lns2$, such as adding, subtracting, or multiplying each pair, returning the result in a new string with the same delimiter and number of elements as exist in lns1$.  The default delimiter is a linefeed, which is recognized as either $0A$ or "\n" in lns1$ and lns2$.

Operator$ can be "+", "-", "*", or "/" to perform the respective arithmetic operation, or "$" to perform string concatenation.  When concatenating, add a suffix to the "$" to add the suffix between the concatenated values.  For example "$ " would add a space.

If both column values are null, the resulting line value will also be null unless the allownull value is true (non-0), which can result in adding two null values and printing "0".

log(msg$)

Writes a log entry to the server log file, logs/server.date.csv.

log(msg$,logfile$[,format$])

Logs a message (time stamped) to the specified file. The file is created if necessary.  If logfile$ is null, the server log is used.  If format$ is supplied, it is used as the mask for the time stamp.  The following character sequences are substituted in the format:

•%Yl – 4 digit year

•%Yz – 2-digit year

•%Mz – 2 digit month

•%Ms – short month name

•%Dz – 2-digit day

•%Ds – short day name

•%Hz – 2-digit hour (24 hour clock)

•%hz – 2-digit hour (12 hour clock)

•%mz – 2-digit minute

•%sz – 2-digit minute

If no format is supplied, this format "%Yl-%Mz-%Dz %Hz:%mz:%sz".  If the format is supplied but is null (""), then no time stamp is written.

logdeliver(to$, tags$ [,tags$ [,attachfile$ [,status$ [,errmsg$ [,respmsg$]]]]])

Writes a line to the delivery log using the values specified.  The tags$ argument can be used to log subject and body information in name=value pairs.  The status$ value can be null (""), in which case it is set to OK if errmsg$ is null, or ERR if not.

logjobmsg(msg$)

This function logs messages during Image Manager job runs.  It internally executes a jobdefs'logmsg(jobid$,msg$) method.

It is only valid in Image Manager job scripting.

logwarn(msg$)

Adds a message to the job's .err file, which is also presented when the design tool runs a preview that results in warning errors.

lower(expression)

Returns text in lowercase.

ltrim(str$)

Returns the value of str$, trimmed of leading spaces.

mailaddr(email$)

mailname(email$)

Given a full email designation, which includes a name in quotes and an address, often bracketed, these two functions return the address and name portions, respectively.

mcut(col,row,cols,rows,value$,lf$,trim$)

Returns multiple lines of text, optionally with line-feed delimiters and/or trimmed of spaces. The lf$ argument can be set to "Y" or "y" to add a line-feed character between each line; likewise, the trim$ argument can be set to "Y" or "y" to cause each line to be trimmed before returned.  In addition, mcut() assigns each line in the cut region to value$.  Use null ("") or spaces to erase the source text.

PostScript input not supported.

mget(col,row,cols,rows,lf$|lf,trim$|trim)

Returns multiple lines of text into a single string, optionally with a line-feed delimiter and/or trimmed of spaces.  This function is useful in conjunction with multi-line functionality of the text command.  The lf$ argument can be set to "Y" or "y" to add a line-feed character between each line; likewise, the trim$ argument can be set to "Y" or "y" to cause each line to be trimmed before returned.  Optionally use the boolean syntax, using 0 or 1 for linefeed off/on, and 0 or 1 for trim off/on.

Beware that if mget() results with linefeeds are used in an exec() function, you should substitute the linefeeds with the "\n" mnemonic sequence: sub(mget(1,20,10,40,1,1),$0a$,"\n").

mid(arg1$,arg2,arg3)

Safely returns a substring without generating an error 47 if the value in arg1$ isn't long enough to accommodate position arg2 and length arg3.  Note also the left() and right() functions.

mset(col,row,cols,rows,value$)  

Multi-line set function. Will work with multi-line value$, delimited with mnemonic \n character sequences or chr(10) values.

PostScript input not supported.

msfax(filename$, faxnum$, tags$ [, errmsg$])

Faxes filename$, normally an UnForm-generated PDF file, to the fax number specified in faxnum$.  Numerous supported tags can be specified in tags$, in the format tag1=value,tag2=value,...  Requires the Windows Support Server.  For more details, see the Windows Support Server chapter.

parse(str$,n,delimiter$)

Returns the nth element of the string str$, when parsed by the delimiter specified.  For example, parse("one,two",2,",") would return "two".  If the delimiter is null, then any white space delimiter is used.

parseq(str$,n,delimiter$)

This is the same as parse(), except that honors quoted values in the string str$, ignoring delimiters contained in them.

pdfpages(pdffile$)

Returns the number of pages in a PDF file.  The file must be in non-optimized format.

pdftoimage(fromfile$,tofile$,format$ [,resolution[,errmsg$]])

Uses Ghostscript, local to the server or via the Windows Support Server, to convert from PDF file fromfile$ to an image file tofile$, using the format format$.  Valid formats match those of the Ghostscript drivers defined in uf101d.ini.

If fromfile$ contains multiple file names separated by semicolons or linefeeds ($0a$), all the files are sent to Ghostscript for conversion.  Use this to create a pdf file composed of other pdf files:

files$="path1.pdf;path2.pdf;path3.pdf"

target$="allfiles.pdf"

pdftoimage(files$,target$,"pdf")

prm("name")

The prm() function has been added as a synonym to the gbl() and stbl() functions, which return global string table values typically associated with the –prm command line option.

proper(expression)

Returns text in Proper Case.

putaddress(book$,entityid$,doctype$,address$)

Opens the address book specified, and adds or updates the address entry identified by entityid$ and doctype$.  The address$ template can be created by execution of a getaddress() function, even from an invalid entityid$, then filled with appropriate values.  The entityid$ and doctype$ arguments are automatically copied to the address$ template.

The address book template fields can be referenced as address.entityid$, address.doctype$, address.entityname$, address.contactname$, address.to$, and address.combine.

putdocidprop(lib$, doctype$, docid$, prop$)

Updates the document properties of the document type and ID in the library specified.  The document properties are replaced with the values found in the composite string prop$.  These string properties are:

Prop.date$ - date in yyyymmdd format

Prop.time$ - time in hhmmss format (24-hour clock)

Prop.title$ - title string

Prop.entityid$ - entity id string

Prop.notes$ - notes, which can have CRLF line breaks

Prop.keywords$ - semi-colon delimited keywords

Prop.categories$ - semi-colon delimited categories with pipe-delimited segments

Prop.links$ - semi-colon delimited list of links

All properties found in the string are updated, so you must first read existing properties using the getdocidprop() function, then modify those properties desired, then update them with this function.

This function will not add new documents to a library.  It only updates existing ones.

putpage(n,arr$[all])  

Replaces page n with text array arr$[all].

PostScript input not supported.

range(str$,first,count,dlm$)

Returns a range of fields from the string str$, starting with the first field, for count fields, delimited by dlm$.  srange("1,2,3,4,5",2,3,",") would return "2,3,4".  Delimiters inside quotes are ignored.

removezonepagehdrs(str$)

Remove zone page header rows from linefeed delimited str$.  Typically used in filters that process ocr or column zones, so the data can be processed without regard to pages.  Also see the iszonepagehdr() function.

resolveexpr(str$)

Scans for expressions in braces, attempts to resolve them, and replaces the braced expressions with resulting values.  Provides a more convenient syntax than expression building in code.  Example: if a$="123.01", resolveexpr("a={a$}") returns "a=123.01".  When resolving code block variables, this is only valid inside code blocks.

If you need to escape braces in the string, such as in a regular expression that uses a length specifier such as {10}, use \{ and \}.

right(str$,length)

Returns the rightmost length characters from str$, padding with spaces on the left to enforce length.  Note also the left() and mid() functions.

rtrim(str$)

Returns the value of str$, trimmed of trailing spaces.

runjobon(server$ [,args$, [,errmsg$]])

Runs a copy of the current job on another UnForm server, using the local command line client.  The server$ value should be set to the name (and optional settings) of the server to run the job on.  The format is identical to the command line option -server.  Set additional or overriding arguments in args$, if necessary.  If an error occurs, it is logged and also passed back in errmsg$, if provided.  Since the job is run by a client command line, failure history is maintained per the client configuration, to allow recovery of failed jobs if necessary.

set(col,row,cols,value$)

Returns value$, after it places value$ in the text$[all] array at the position indicated.

PostScript input not supported.

setlogin(userid$,password$)

Sets the login and password to enable the library object to access a library.

An administrator can define secure passwords in the browser interface, and a password ID can be used in place of a plain text password.  The syntax is simply the ID with a "store:" prefix in the password$ field, such as "store:SQLUser1".

settrans(filename$)

Sets the translation file dynamically as the job runs.  This overrides what might be set via a -trans command line option.

sqlconnect(datasource$[,user$ ,pswd$ [,otheroptions$ [,errmsg$]]])

Connects to the data source specified, using the specified user, password and optional parameters.  Returns a channel on success, or 0 on failure, in which case the errmsg$ argument contains an error message.

An administrator can define secure passwords in the browser interface, and a password ID can be used in place of a plain text password.  The syntax is simply the ID with a "store:" prefix in the pswd$ field, such as "store:SQLUser1".

The channel returned is used for subsequent access to the database using sqlexecute() and sqlfetch() functions.

See the Database Access chapter for more information about database support.

sqlexecute(chan,command$[,errmsg$ [,result$ [,fdelim$ [,rdelim$]]]] )

Executes the SQL command specified, typically a SELECT statement, on the channel specified.  The channel must have been previously returned by a sqlconnect() function.  If result$ is supplied as an argument, then a sqlfetch() method is executed to fill result$ with all rows, and the number of rows fetched is returned.

sqlfetch(chan,result$[,count [,errmsg$ [,fdelim$ [,rdelim$]]]])

Fills result$ with some number of rows from the most recent SQL command executed on the channel with the sqlexecute() function.  Returns the number of rows filled.

The number of rows returned is determined by the count argument.  If not supplied, 1 row is returned, allowing a loop to be processed one row at a time.  If count is -1, then all available rows are returned.

The default field delimiter is a tab ($09$), but this can be specified with the fdelim$ argument.  The default row delimiter is a linefeed ($0A$), but this can be specified with the rdelim$ argument.

If an error occurs, errmsg$ will hold a message.

If no more rows are available, the function returns 0 and result$ is empty.

sshost(server$,port)

Sets the Windows Support Server hostname and port.  Default values are defined in the uf101d.ini file in the sshost and ssport settings.  This command allows for dynamic changing to a different server.

striplines(text$)

Returns text$, stripped blank lines from multi-line text, such as addresses.  As a byproduct, all CR characters are also removed, leaving simple LF line delimiters.

strtoarr(str$,arr$[all],dlm$)

Converts string str$ to an array arr$[all], by splitting str$ on delimiter dlm$

sub(str$,old$,new$)

Returns a string where all occurrences of old$ in str$ are replaced with new$.

subidexists(lib$,doctype$,docid$,subid$)

Returns 1 if the document type, document ID, and sub ID exists in the library, or 0 if not.

tempfile([ext$])

Creates and returns the name of a temporary file that is removed automatically at the end of the job.  The file will have a ".tmp" extension, unless an extension argument is provided.

textimage(text$, font$, size, cols, rows, color$, charset$, errmsg$)

Creates a bmp image using Image Magick based on the TrueType font, point size, and image size. For limited Unicode output, you can use this function instead of font embedding to avoid large output caused by embedding a full ttf font.  If a server-based version of Magick is unavailable, a Windows Support Server can be configured to support this function.

The font$ value is either a name found in the [fonts] section of the ufparam.txt file, or an actual TrueType font name.  On Unix this would be a font file, on Windows (or the support server) it would be the font name recognized by the operating system, such as Arial-Unicode-MS.  The size specifies the point size for the text.  The cols and rows define the image size.  If cols is 0, then the image will be sized to exactly fit the text.  Otherwise, the text is centered within the image.

The color setting can be "rgb rrggbb" (rr, gg, and bb are hexadecimal values 00-FF), or any color that Image Magick recognizes.

The charset defaults  to Windows ANSI (9J or iso8859-1).  Text is converted to utf-8 for Magick.  The function returns the name of the temporary .bmp file, which can be used in an image command expression.

Direct unicode can be supplied in text$ if charset$ is "uc".  To ensure the image isn't re-scaled incorrectly, use imgx/imgy functions  to obtain actual cols/rows sizes for use in the image command.

textfile(path$)

This function creates a file and returns a path name to that file.  The value of path$ is interpreted in three ways.  If null (""), a new temporary file is created, and will be erased automatically when the job is complete.  Optionally, the value may start with a period to force the extension of the temporary file to match the value, such as ".pdf".  Otherwise, the value should be a full path, and that file will be created and returned.  Such custom paths are not erased automatically at the end of the job.

textheight(text$, fontnum|fontname$, size, attr, cols [,linespacing])

Returns the text height, in rows, of text$, given the font number or name, size in points (or pitch if the font is mono-spaced),style attribute (0=normal, 1=bold, 2=italic, 3=bold italic), columns (for wrapping calculations), and optional line spacing.  This will be the equivalent height that would be used by the text command given the same attributes. If linespacing is not supplied, the default is based on the current lpi.

texttokeywords(str$[,maxkeywords])

Returns a semicolon-delimited list of unique keywords from a block of text in str$, which may include any white space, including line breaks.  The keyword construction honors the site's non-word and non-character settings, and the list is limited to maxkeywords words, if supplied.

textwidth(text$, fontnum|fontname$, size, attr)

Returns the text width in columns of text$ given the font number or name, size in points, and style attribute (0=normal, 1=bold, 2=italic, 3=bold italic).  The function honors the same font mapping as is used in regular UnForm processing for pdf, and understands the same fonts that are understood for internal calculations for justification, where laser fonts are loaded from the standard fonts.txt file, pdf fonts are mapped from these, and postscript fonts are loaded from .afm files in the psfonts directory.  For Postscript, the width is based on the Windows ANSI symbol set.

If the font is a TrueType font, and the text value doesn't appear to be unicode text, UnForm will implicitly convert it to unicode.  If the text is preencoded to unicode but does not contain any null ($00$) characters, add $0000$ to the string to prevent this implicit conversion.

touc(text$,charset$)

Converts single-byte text in the character set specified to unicode text.  Returns the unicode text.  Known character set tables are specified in the UnForm unicode directory.  Charset$ can also be "utf8" or "utf-8" to convert from UTF-8 to UTF-16 (or Unicode).

translate(name$ [,context$ [, forcecontext ] ])

Returns the value associated with the specified name, based on the translation file and current rule set.  The context value can be "text", "barcode", or "anchor", and if forcecontext is true (non-zero), only context-based names are searched.

trim(expression)

Returns expression after trimming spaces from the left and right side.

ttfchars(fontnum)

Returns a string made up of Unicode characters, two bytes per character, found in the True Type font mapped from the font number provided.

ubound(arr$[all][,dimension])

Returns the upper-bound of the array arr$[all].  If x$ contains multiple dimensions, you can specify which dimension.  For example, if arr$ is dimmed as x$[100,1:2], ubound(x$[all])=100, ubound(x$[all],2)=2.

upper(expression)

Returns text in UPPERCASE.

urlencode(str$)

urldecode(encodedstr$)

Return URL-encoded and decoded string values.  URL encoding substitutes %hex coding for non-printable values and also a number of characters that may be meaningful to URL parsing, such as "&" and "?".

urlgetfld(datastr$,name$)

Returns the value of the name$ field.  The value is returned without URL encoding.

mailto$=urlgetfld(datastring$,"to")

urlsetfld(datastr$,name$,value$)

Returns a URL-encoded string with the field name$ set to value$.  The field is added if necessary.

datastring$=urlsetfld(datastring$,"to",someone@somewhere.com)

urldelflds(datastr$,names$)

Returns the a URL-encoded string after removing the fields specified in name$ from the URL-encoded string datastr$.  Multiple fields can be separated by commas.

datastring$=urldelflds(datastring$,"to,from,subject,body")

urlgetnames$(datastr$)

Returns a list of field names in the data string.

fldlist$=urlgetnames$(datastring$)

count=parsec(fldlist$,",’)