HOWTO: Using ZSUBMIT
ZTN1013
ID: ZTN1013
This Zetafax technical note applies to:
- Zetafax 6.01 and later
Summary
One of the API methods of submitting a fax for sending is to create a file in a specific format, termed SUBMIT file format. This is an ASCII text file which usually contains details of the options to use in preparing the message, the recipients of the message, as well as the message text itself.
The message may then be sent using the ZSUBMIT program. This program may be installed to run continuously as one of the Zetafax server programs, regularly checking a particular directory for the existence of a SUBMIT format file. If one is found then it is interpreted and submitted to the fax server for sending - its progress may then be monitored using the workstation program as normal.
The ZSUBMIT program submits all messages as a given Zetafax user, and if required will monitor progress of the messages, limiting the number of outstanding messages at any one time or removing any entries which have been sent without errors. Files for sending via the ZSUBMIT program may also contain more than one message for sending - the program will split it into separate messages before submitting it to the server.
SUBMIT format files are also used by the Application Programmers Interface (API) routines to specify message options and text for sending. These routines allow user written application programs to send messages directly without using either the workstation or ZSUBMIT program. The ZSUBMIT program itself is written using these routines, and requires the API licence to run.
Note: To ensure your attachments are rendered correctly, a rendering add-on (DOCTIFF) is also required for all file types except for existing tiff files. The rendering add-on (DOCTIFF) is only available for version 8 and later systems.
More information
The SUBMIT file is a standard ASCII text file (multiple lines, each terminated with < CR> < LF> ). The file information about the options to be used in preparing a given message, the recipients, and the message text itself. The format is:
%%[MESSAGE]
(message option lines)
(message addressing lines)
%%[TEXT]
(text including message text fields)
or, if a separate file contains the message to be sent (e.g. to send a graphics file):
%%[MESSAGE]
(message option lines)
(message addressing lines)
%%[FILE]
(filename, including path)
Note that the first line of the file must be " %%[MESSAGE]" .
The section headings (" %%[MESSAGE]" and " %%[TEXT]" or " %%[FILE]" ), all message option and addressing lines, and the filename (if the second form is used) must start at the left of the line (i.e. there must be no spaces preceding them). Finally TAB characters should not be used in the file - they will be replaced with a space character.
Files submitted using the ZSUBMIT program may contain information about one or more messages by simply concatenating the files (i.e. the %%[MESSAGE] section for the second message follows the end of the %%[TEXT] or %%[FILE] sections for the first message, etc). The ZSUBMIT program splits the file into separate messages before submitting them to the server.
SUBMIT files used with the API functions may only contain information for a single message - everything from the first %%[TEXT] command to the end of the file is treated as message text. Certain of the functions only look at one of the two sections - in this case the other section may of course be omitted.
Message Options
These lines appear at the start of the %%[MESSAGE] section, before the addressing lines (i.e. before the first " To:" line). If omitted, all the lines (except the " Comment:" , " Attach" and " Charge" lines) default to the values specified for the given user. For files submitted by programs using the API functions, this is the user specified in the ZfAPIInit call. For files submitted using the ZSUBMIT program, it is the user specified in the User: line, either in the %%[MESSAGE] section (if given), or in the SETUP.INI file.
AFTER: time
where time specifies the earliest time that the message should be sent, for deferred sending. The format of the time field may be one of the following:
yy-mm-dd hh:mm:ss (date and time specified)
OFFPEAK (as defined in SETUP.INI)
If the time field is omitted the message is queued for sending immediately.
Purpose: Specifies when the message is to be sent.
Example: After: 94-02-22 18:00:00
ATTACH: files
where files is a comma separated list of graphics files to attach to the fax.
Purpose: Specifies the attachment files in the user's private graphics directory (Z-GRAPH) or in the system graphics directory. These are added to the end of the fax before sending. A maximum of 30 files may be specified.
Example: Attach: INFOPACK, PRICES
CHARGE: chargecode
where chargecode specifies the charge code to use for this message, and may be any text.
Purpose: Specifies the charge code to use for this message. Charge codes are stored in the Zetafax billing log when the fax completes, and may be used for charging the fax to a particular department or client.
Example: Charge: Sales Dept
COMMENT: comment
where comment is the message description (up to 40 characters long)
Purpose: Specifies the message description as displayed on the right of the workstation OUT window. If this line is omitted a message description detailing the first addressee is used.
Example: Comment: Smith and Co January invoice
COVERSHEET: coversheet
where coversheet is the name of the file to be used to generate a coversheet for the fax (1 to 8 characters long) or blank for no coversheet
Purpose: Specifies what coversheet to generate for the fax onto before sending
Example: Coversheet: COVSHEET
FORMAT: format
where format specifies the file format of the data file to be sent. The possible values of the format field (together with the data type and the associated data file extensions) are:
ASCII (ASCII text, unformatted - TXT)
EPSON Epson FX or LQ print spool file - EPN)
TIFF-NORMAL (100x200 dpi TIFF fax file - G3N)
TIFF-FINE (200x200 dpi TIFF fax file - G3F)
TIFF-SUPERFINE (400x200 dpi TIFF fax file - G3S)
Purpose: Specifies what format the data file is in. In a standard SUBMIT file (containing a %%[TEXT] section) the format should be " EPSON" or " ASCII" . Epson should be used if the message text contains any " %%" formatting commands (e.g. " %%[BOLD:ON]" ). If however the message text just contains ASCII text then the format should be specified as " ASCII" (or the line omitted), in which case the result will be the same as using the workstation to send an ASCII text file.
Example: Format: EPSON
FROM: sendername
where sendername is the originator of the fax
Purpose: Specifies the name which is put on the fax cover sheet as the sender of the fax (cf the From: field on the Zetafax addressing dialog box)
Example: From: Sam Smith
HEADER: header
where header is one or more of No, To, Fr, Dt and Ti (with no separating spaces), as follows:
No Page numbering (n/N)
To Name of recipient
Fr Name of sender
Dt Date
Ti Time
Purpose: Specifies the format of the header line to appear at the top of each page of the fax.
Example: Header: NoToFrDt
HOLD: hold
where hold is either " YES" or " NO" .
Purpose: Specifies whether the message will be held once it in the queue, meaning that it will not be sent until the user releases it (using the Zetafax workstation " File Release" or “Message” tab, “Release” on Zetafax 2011 command). This gives a similar effect to the " Hold for preview before sending" check box on the Zetafax workstation addressing dialog, allowing the fax to be checked on screen before sending.
Example: Hold: YES
LETTERHEAD: letterhead
where letterhead is the name of the file to be used as the letterhead (1 to 8 characters long) or blank for no letterhead
Purpose: Specifies what letterhead to merge the fax onto before sending
Example: Letterhead: LETTHEAD
NOTE: notes
where notes is the text for the notes field on the coversheet.
Purpose: Specifies the text which should appear on the coversheet. Multiple lines can be entered as multiple “Note:” commands.
Example: Note: Dear sir,
Note: Here is the information you requested.
Note: Sincerely yours,
Note: Sam Smith
PREVIEW: preview
where preview is either " YES" or " NO" .
Purpose: Specifies whether a preview file is to be prepared for this message. This is a copy of the fax prepared for the first recipient, which can be viewed using the " File View" option on the workstation (“Message” tab, “View” option for Zetafax2011). The default setting is " YES" , but if disk space is short and there is no requirement to view the faxes from a workstation then this parameter may be set to " NO" .
Note that to preview the fax on the Zetafax workstation before it is sent (in a similar way to the " Hold for preview before sending" check box on the workstation addressing dialog box) you should set this option to " YES" (the default), and also set the Hold: message option (qv)
Example: Preview: NO
PRIORITY: priority
where priority is one of " URGENT" , " NORMAL" or " BACKGROUND"
Purpose: Specifies the priority to be used when queuing the fax, in the same way as the " Priority" radio button on the workstation sending options dialog box.
Example: Priority: NORMAL
QUALITY: quality
where quality is one of " DRAFT" , " NORMAL" or " HIGH" .
Purpose: Specifies the resolution to be used when sending the fax, in the same way as the " Quality" radio button on the workstation sending options dialog box. For fax, " DRAFT" and " HIGH" will normally force the fax to be sent at standard (100x200 dpi) and fine (200x200 dpi) resolutions respectively, whilst " NORMAL" will send at whichever resolution has been specified by the system administrator in the system initialisation file.
Example: Quality: NORMAL
SUBJECT: subject
where subject is the text for the subject field on the coversheet.
Purpose: Specifies the text which should appear as the subject on the coversheet and in the Zetafax client.
Example: Subject: Your booking
USER: username
where username specifies a valid Zetafax user name.
Purpose: Specifies the Zetafax user submitting this file. The command may be omitted if the default user name specified in the [ZSUBMIT] section in the SETUP.INI initialisation file was not blank, or if submitting using the API " C" functions.
NOTE - this command can only be used in files submitted using the ZSUBMIT program (rather than using the API " C" function calls, where the name is specified in the ZfAPIInit function). The ZSUBMIT program can be configured to disable this command, if desired for permission or security reasons.
Example: User: JSMITH
Addressing Options
These lines appear in the %%[MESSAGE] section, after the message options lines detailed above. Note that a " To:" line must be first line specified (after the last message option line), before any other message addressing lines. The lines may be repeated if the message is to be sent to more than one person, with each repeated set starting with a " To:" line.
FAX: number
where number is the fax telephone number (cf the Zetafax address book editor fax number field) .
Purpose: Specifies the fax number to send the fax to. If the number is unknown at the time of creating the file the number can be omitted. The fax server will reject the send to that recipient, and the message can be resubmitted manually entering the fax number as required.
Default: None - mandatory field (unless LAN: line is specified - see below)
Example: Fax: 0256 759821
FIELD: fieldname text
where fieldname is a single word (i.e. without any spaces) giving the name of a FaxMerge field, and text is the string which will be substituted for the field.
Purpose: FaxMerge fields are identified in a document by the string " %%[fieldname]" (without the double quotes). When the fax is prepared for sending these fields are replaced with the text given, allowing faxes to multiple addressees to be personalised, for example. Multiple FIELD lines may be specified. NOTE - the Field lines are not retained if a message is resubmitted using the Zetafax workstation program (for example, to correct a fax number).
The following field names are reserved, and should not be used with this command:
COVERTEXT
ORGANISATION
DATE
PAGE
FROM
PAGES
LANDSCAPE
PORTRAIT
NAME
TIME
NOTES
Default: None - any fields not specified are left in the document with the leading " %%" removed.
Example: Field: Department Sales and Marketing
LAN: username
where username is the Zetafax username of the person to be sent to.
Purpose: Specifies the name of the Zetafax user for messages which are to be sent across the LAN (appearing in the user's IN window). This can be useful when testing applications to check the appearance of faxes to be sent without actually sending them to the remote user, in the same way as one might use Preview from the workstation.
Default: None - used as an alternative to the Fax: line
Example: LAN: FSmith
ORGANISATION: organisation
where organisation is the name of the company or organisation to which the fax recipient belongs
Purpose: The organisation name is used on the coversheet of the fax.
Default: blank
Example: Organisation: Smith and Sons Limited
TO: name
where name is the name of the person to whom the fax is to be sent.
Purpose: Specifies a recipient of the fax (cf the Coversheet Name field in the Zetafax address book). This name is used on the coversheet of the fax, on the header line of the fax, and also in the comment on the right hand side of the OUT window in the workstation display.
Default: None - mandatory line.
Example: To: Sam Smith
Text Options
These commands appear in the %%[TEXT] section and may be freely interspersed with the message text.
If you need to include the actual sequence %%[ in the fax you should write it as %%%[.
%%[APPEND:file]
where file is the base name of a graphics file in the Z-GRAPH directory.
Purpose: Appends a graphics image (e.g. a scanned information sheet) to the end of the message (similar to the Zetafax workstation " Attach" option). Up to 30 of these commands may be entered, and the named files will be added to the end of the message as new pages. This command can also be used in separate ASCII format files specified using the %%[FILE] option.
Example: %%[Append:INFOPAGE]
%%[BOLD:state]
where state is either " ON" or " OFF" .
Purpose: The %%[BOLD:ON] command causes all characters following to be printed in bold until either a %%[BOLD:OFF] command is encountered or the end of the %%[TEXT] section is reached.
Example: %%[Bold:ON]
%%[DATE]
Purpose: Inserts the date when the message is prepared for sending, in the format " 1st January 1994" . This command can also be used in separate ASCII format files specified using the %%[FILE] option.
Example: %%[Date]
%%[DOWN:distance]
where distance is the number of units to move down the page from the current position. A unit is approximately 1/100th of an inch.
Purpose: This command moves down the page a given distance and may be used, for example, to position the top line of text to fit within a merged form. Note that the first line of text prints approximately 0.7 inches below the top of the page.
Example: %%[Down:100]
%%[FONT:font]
where font is the font required, and is one of " ROMAN10" , " ROMAN12" , " ROMAN20" , " ROMAN5" , " ROMAN6" or " ROMANPS" giving 10cpi, 12cpi, 20cpi, 5cpi and 6cpi fixed space fonts, and proportional spaced font respectively.
Purpose: This command is used to set the font to be used for the remainder of that message (i.e. until the end of the %%[TEXT] section).
Example: %%[Font:ROMAN10]
%%[F O N T: name, size, weight/style]
where name is the name of the Windows TrueType font required, size its size, and weight/style either B (bold), I (italics) or U (underlined).
Purpose: This command is used to set the Windows TrueType font to be used for the remainder of that message (i.e. until the end of the %%[TEXT] section). Please note that the spaces between the letters are significant and should be used exactly as in the example. See technote ZTN1093, “Using TrueType fonts with ZSUBMIT” for further instructions on the F O N T command.
Example: %%[F O N T:Arial,]
%%[INSERT:file]
where file is the base name of a graphics file in the Z-GRAPH directory.
Purpose: Inserts a single page graphics image (e.g. a signature) at the current position on the page. The image is merged into the document - you must leave enough lines following the command blank if you wish to avoid the image overprinting the following text. This command can also be used in separate ASCII format files specified using the %%[FILE] option.
Example: %%[Insert:ABCLOGO]
%%[LANDSCAPE]
Purpose: This command causes the text which follows (until a %%[PORTRAIT] command or the end of this message, whichever comes first) to be printed in landscape orientation. The command must come before any other text - i.e. at the start of the first line following the %%[MESSAGE] command, or immediately after a %%[NEWPAGE] command (on the same line). This command can also be used in separate ASCII format files specified using the %%[FILE] option.
Example: %%[Landscape]
%%[LMARGIN:width]
where width is the size of the left hand margin in character widths. The width of each character is dependent upon the font being used.
Purpose: This command is used to set the left margin for the remainder of that message (i.e. until the end of the %%[TEXT] section). It should be placed at the start of a line. Note that the margin width excludes a strip of width 0.5 inches at the left of the page which may not be used (i.e. a value of 0 would set the left hand margin 0.5 inches from the left of the page).
Example: %%[LMargin:200]
%%[NEWPAGE]
Purpose: This command is used to start a new page.
Example: %%[NEWPAGE]
%%[PORTRAIT]
Purpose: This command cancels a previous %%[LANDSCAPE] command, reverting to portrait orientation. The command must come before any other text - i.e. at the start of the first line following the %%[MESSAGE] command, or immediately after a %%[NEWPAGE] command (on the same line). Note that the margin settings following a %%[PORTRAIT] command are different from the defaults for ASCII files, allowing slightly more of the page to be printed. This can be useful when overprinting forms, for example. This command can also be used in separate ASCII format files specified using the %%[FILE] option.
Example: %%[Portrait]
%%[RIGHT:distance]
where distance is the number of units to the right from the current position. A unit is approximately 1/100th of an inch.
Purpose: This command moves across the page to the right a given distance and may be used, for example, to position a word precisely within a form.
Example: %%[Right:100]
%%[TIME]
Purpose: Inserts the time when the message is prepared for sending, using a 24 hour clock, in the format " 12:34" . This command can also be used in separate ASCII format files specified using the %%[FILE] option.
Example: %%[Time]
%%[UNDERLINE:state] or %%[UL:state]
where state is either " ON" or " OFF" .
Purpose: The %%[UNDERLINE:ON] command causes all characters following to be printed underlined until either a %%[UNDERLINE:OFF] command is encountered or the end of the %%[TEXT] section is reached.
Example: %%[Underline:ON]
%%[fieldname]
where fieldname is the name of a FaxMerge field
Purpose: Inserts the text for the given field for that addressee. The following fieldnames are defined for all messages submitted using the API or ZSUBMIT program:
FROM NAME ORGANISATION
Other fields are only defined if they have been specified using the Field: message addressing line (see above). This command can also be used in separate ASCII format files specified using the %%[FILE] option.
Example: %%[Organisation]
References
For additional information on automating faxing, please see the following Zetafax technical notes:
ZTN1093-HOWTO: Using TrueType fonts with ZSUBMIT
Last updated: 16th May 2011 (ET/GW/EBLD/MW)