Server Command Configuration

Once a job has been processed by the XML Server (providing the client did not request a preview), the server will run its server command.

Note: The server command cannot be set per invocation, if multiple commands are required multiple XML Server s must be used

The server command is a command that is sent to the system to manipulate the output document. Usually this will involve printing or e-mailing the document, but there are no restrictions on what the command can do other than those imposed by your system. No built in server commands are provided. The command is free-form and is specified using the <SERVER_COMMAND> element.

The server command uses token substitution to pass parameters to the system. The tokens consist of a % character followed by a letter (it is case-insensitive). Tokens that appear in the server command string are substituted with the relevant value of the token just before the server command is executed for each job. The tokens are listed in Server Command Configuration below.

Table 1. XML Server Command Tokens
Token	Meaning
`%p`	The name of the printer is being set to either the default printer ID attribute on the Users table (i.e. the user trying to print the document) or the default printer name as specified in the XML server configuration.
`%t`	The name of the paper tray as specified in the job configuration received from the client, or the default paper tray as specified in the server configuration.
`%u`	The name of the connecting user, or the default username specified in the server configuration. This could be the application username that the user logged in as.
`%e`	The e-mail address of the connecting user, or the default e-mail address specified in the server configuration. This can be used if you want to e-mail the result of the XML job back to the user. For example, you could configure a server to e-mail PDF to a user as well as print the PostScript output. You could even use this to configure two servers where one supplies e-mailed copies and the other generates hard-copies.
`%f`	The name of the file where the document was saved. This will be a generated temporary file name and will not include that path to the file. The file extension will depend on the specified job type and will default to.pdf.
`%d`	The directory where the temporary file is located. You may use a trailing directory separator character and then specify `%d%f` or you can leave out the character and use, for example, `%d/%f`. The XML Server will not insert one for you. Care should be taken to use the correct separator character for your system.
`%%`	If you want to use a `%` character in a command but not as a token, use `%%` instead. The first `%` will be removed before invoking the command.

For example, if the server command is specified as:

mail -s 'Your Print Job' %e

the %e token will be replaced with the e-mail address specified for the job (or the default e-mail address if none was supplied).

For more complex server commands it may be necessary to wrap the actual commands in a batch/script files. This batch file is then executed via a server command such as:

<SomeLocation>/MyBatch.bat 'Your Print Job' %e

The server command tokens are not available in the batch file but are only replaced in the server command specified in the server configuration file and must be passed into the batch program as normal parameters.

The main consideration when writing a server command is to identify whether you want the output document of the XML Server piped to your command or stored in a temporary file for your command to process. This can be chosen by setting one of the mutually exclusive <USE_TMP_FILE> or <USE_PIPE> elements in your configuration.

If you opt to use a temporary file. The document data will be written to the temporary file and then the server command will be executed. The XML Server will not delete the temporary file for you. You should have your server command do that if that is what you wish. The temporary file will be named using the value of the TMP_FILE_ROOT element with a sequence number and the appropriate extension appended according to the job type. For example, if the value was temp, and the job type was XMLPrintStreamConstants. kJobTypePDF the first file generated by the XML Server would be temp0.pdf, the next file temp1.pdf, etc. This is useful if you start several XML Server s that all share the same temporary directory to avoid servers over-writing each others temporary files. The file will be created in the directory specified by the <TMP_DIRECTORY> element in the configuration. This element should contain an absolute path or a path relative to the directory in which the XML Server was started. The directory name and the generated file name are made available to your command using the %d and %f tokens respectively.

If you opt to use a pipe, your command will be executed and the XML Server will begin to write document data to the standard input of the command. No temporary file will be created. There is, however, an issue that must be resolved when using pipes: if the command write buffered data to standard error or standard output that is not read by any process, once the buffer is full, the command may block. As no process will ever read from the streams, the command will remain blocked indefinitely; in other words, it hangs. There are two methods that can be employed to avoid this. The first is to ensure that all unused output from your command is redirected to a device that will read all the output and ensure the process does not block. The second is to have the XML Server do this for you using the <USE_STDOUT_SINK> and <USE_STDERR_SINK> elements. While the former method is recommended where possible, the use of the XML Server sinks can help in situations or on systems where it is not possible. Both elements cause threads to be created in the XML Server to read and discard data output by the server command.

More details on how to write server commands are provided in the section including samples below.