The table below summarizes the job commands you can use in your command packets. The remainder of this section describes each command in full.
Command | Description |
|---|---|
This command cancels a job. | |
This command returns the version and build number for the Pageflex Server installation you are running. | |
This command returns the length of the job queue. Pageflex Server returns the number of commands in the queue and the number of jobs waiting to be processed. | |
This command returns the status of a job that a Pageflex Server engine is processing or has processed. | |
This command retrieves the task log. | |
This command restarts all engines in a Pageflex Server cluster. | |
This command submits a job to Pageflex Server. |
This command cancels a job in the queue. If Pageflex Server is processing the job, it finishes the current document before cancelling the rest of the job. It does not create the remaining documents in the job, and it does not delete any documents it already created. If the job is still in the queue, this command cancels the entire job.
■ Required elements
■ Optional elements
None
■ Response to command
Standard response (R0000000)
Note: Not supported by Studio ID Server.
Example Command Packet for CancelJob
To cancel a job with the transaction ID A0000033, send the following command packet.
<?xml version="1.0"?>
<?pf_command version="1.0"?>
<pfjob:job_command xmlns:pfjob="http://www.pageflex.com/schemas"
name="CancelJob">
<pfjob:job_variables>
<pfjob:var name="_sys_TransactionID">A0000033</pfjob:var>
</pfjob:job_variables>
</pfjob:job_command>
This command returns the version and build number for the Pageflex Server installation you are running.
■ Required elements
None
■ Optional elements
None
■ Response to command
Standard response (R0000000) followed by the build number for Pageflex Server.
Example Command Packet for GetBuildString
There are no required elements for this command. You can send the following command packet at any time.
<?xml version="1.0"?>
<?pf_command version="1.0"?>
<pfjob:job_command xmlns:pfjob="http://www.pageflex.com/schemas"
name="GetBuildString">
</pfjob:job_command>
This command returns the number of commands and number of jobs that are in the Pageflex Server queue. Commands and jobs remain in the queue until they are completed.
■ Required elements
None
■ Optional elements
_sys_QueueName
■ Response to command
Standard response (R0000000) followed by the number of commands and then the number of jobs in the queue. These numbers are returned for legacy reasons. In most cases, the numbers will be the same as there is no longer a difference between the two. If you do not specify a queue the code returns these items for the default queue for the port over which you are sending the command packet.
Example Command Packet for GetJobQueueLen without queue
There are no required elements for this command. You can send the following command packet at any time.
<?xml version="1.0"?>
<?pf_command version="1.0"?>
<pfjob:job_command xmlns:pfjob="http://www.pageflex.com/schemas"
name="GetJobQueueLen">
</pfjob:job_command>
Example Command Packet for GetJobQueueLen with queue
This example returns the number of commands and then the number of jobs in the queue named “MyQueueName.”
<?xml version="1.0"?>
<?pf_command version="1.0"?>
<pfjob:job_command xmlns:pfjob="http://www.pageflex.com/schemas"
name="GetJobQueueLen">
<pfjob:job_variables>
<pfjob:var name="_sys_QueueName">MyQueueName</pfjob:var>
</pfjob:job_variables>
</pfjob:job_command>
This command returns the status for an individual job submitted to Pageflex Server.
■ Required elements
Job Variable: _sys_TransactionID
■ Optional elements
None
■ Response to command
Standard response (R0000000) followed by a status code.
Description | |
|---|---|
Job is waiting in the job queue | |
Job is processing but is not done | |
Request has been made to cancel the job | |
Request has been made to delete the job | |
Job has been cancelled or deleted by an API command | |
At least one document, but not all, has been processed | |
Job succeeded with no errors | |
Job failed |
Example Command Packet for GetJobStatus
To get the status of a job with the transaction ID A0000032, send the following command packet.
<?xml version="1.0"?>
<?pf_command version="1.0"?>
<pfjob:job_command xmlns:pfjob="http://www.pageflex.com/schemas"
name="GetJobStatus">
<pfjob:job_variables>
<pfjob:var name="_sys_TransactionID">A0000032</pfjob:var>
</pfjob:job_variables>
</pfjob:job_command>
This command retrieves a specific task log.
■ Required elements
Job Variable: _sys_TransactionID
■ Optional elements
None
■ Response to command
The response from this will be something like:
11/26/2008 2:35:59 PM, (Information): Pageflex Server 7.0.0.950
11/26/2008 2:35:59 PM, (Information): Task 720 created with transaction name A0000737
11/26/2008 2:35:59 PM, (Information): Task 720 has been assigned to engine 548 by PFSvr_ChannelViaPort on MACHINE01
11/26/2008 2:35:59 PM, (Information): Task status updated from ASSIGNED to WORKING
11/26/2008 2:35:59 PM, (Information): Engine 548 on host MACHINE01 has begun working on task 720 as user NT AUTHORITY\SYSTEM
11/26/2008 2:35:59 PM, (Information): Machine name: MACHINE01
11/26/2008 2:35:59 PM, (Information): Project file: C:\Pageflex\Projects\BusinessCard\BusinessCard-Ur.pf
11/26/2008 2:35:59 PM, (Information): Template file: C:\Pageflex\Projects\BusinessCard\BusinessCard.xdt
11/26/2008 2:35:59 PM, (Information): Job name: Bitmap single
11/26/2008 2:35:59 PM, (Information): Output folder: C:\Pageflex\PageflexServer\Output\Final\A0000737
11/26/2008 2:35:59 PM, (Information): Temp folder: C:\Pageflex\PageflexServer\Output\Final\A0000737
11/26/2008 2:35:59 PM, (Information): Document 1 - Starting document
11/26/2008 2:35:59 PM, (Error): Document 1 - No value for variable: Firstname, not OK to publish.
11/26/2008 2:35:59 PM, (Information): Document 1 - Completed successfully
11/26/2008 2:35:59 PM, (Error): Job failed due to one or more critical errors
11/26/2008 2:36:00 PM, (Information): Task status updated from WORKING to FAILED
11/26/2008 2:36:00 PM, (Information): Document creation finished, 0 document(s) created, 0 page(s) rendered
11/26/2008 2:36:00 PM, (Information): Transaction A0000737 ended
Example Command Packet for GetTaskLog
To get the task log of a job with the transaction ID A0000737, send the following command packet:
<?xml version='1.0' ?>
<?pf_command version='1.0'?>
<pfjob:job_command xmlns:pfjob='http://www.pageflex.com/schemas' name='GetTaskLog'>
<pfjob:job_variables>
<pfjob:var name='_sys_TransactionID'>A0000737</pfjob:var>
</pfjob:job_variables>
</pfjob:job_command>
When you submit this command, all engines in the cluster finish processing jobs and then exit. Server then starts a new pool of engines. This command is useful when performing changes that require the engines to be restarted for the changes to take effect. For example, you may need to restart a Pageflex Server host machine that hosts task engines after installing custom fonts.
Note: Restarting servers unnecessarily can adversely affect overall cluster performance. You should use this command with care. Additionally, Pageflex Server does not authenticate the user. There are no security features to prevent unauthorized use of this command.
■ Required elements
None
■ Optional elements
None
■ Response to command
Standard response (R0000000)
Example Command Packet for RestartServer
<?xml version="1.0" ?>
<?pf_command version="1.0"?>
<pfjob:job_command xmlns:pfjob="http://www.pageflex.com/schemas" name="RestartServer">
</pfjob:job_command>
This command is a request to Pageflex Server to process a job.
■ Required elements
Job variables: ProjectName JobName
■ Optional elements
job_variables (other than those listed above)
doc_variables
■ Response to command
Standard response (R0000000) and the transaction ID if the job is accepted
-or-
Response code and an error message.
■ Studio ID Server jobs should specify the project-type attribute and set it to “StudioID”.
When you send this command, Pageflex Server does the following.
1 Pageflex Server parses the command packet and checks the syntax. If the packet is syntactically correct, it returns a transaction ID for the job. Otherwise, it returns an error message.
2 Next, Pageflex Server locates the project file, and opens the job specified in the command packet. It matches the names of the variables in the command packet with the names of the variables defined in the project file. The matching variables are set to the values the command packet specifies. Variables not in the command packet retain the values set in the project.
3 If the job has a data source, Pageflex Server creates the “real” SQL query by substituting actual values for the variables in the WHERE clause of the SQL query template. If you manually entered an SQL query to set up the job, it uses the query you typed.
4 Pageflex Server connects to the profile database specified in the project, and submits the query to establish values for any profile variables not included in the command packet. If the project uses a content data source, it runs any necessary operations or queries to set the values for the content variables.
Note: If Pageflex Server fails to establish values for any variable, it returns an error message. A variable may have an empty value if its definition allows Pageflex Server to publish it with an empty value.
5 Once the variables are resolved, Pageflex Server composes the pages of the documents.
Example Command Packet for SubmitJob
A project uses the following variables.
■ Job Variables:
ProjectName "c:\proj\travel.pf"
JobName "Job 1"
■ Document Variables:
FirstName "Pat"
LastName "Smith"
BodyText "<body><_char>Special Package</_char></body>"
Picture "starburst.tif"
The following command packet submits this information to Pageflex Server.
<?xml version="1.0"?>
<?pf_command version="1.0"?>
<pfjob:job_command xmlns:pfjob="http://www.pageflex.com/schemas"
name="SubmitJob">
<pfjob:job_variables>
<pfjob:var name="ProjectName">c:\proj\travel.pf</pfjob:var>
<pfjob:var name="JobName">Job 1</pfjob:var>
</pfjob:job_variables>
<pfjob:doc_variables>
<pfjob:var name="FirstName">Pat</pfjob:var>
<pfjob:var name="LastName">Smith</pfjob:var>
<pfjob:var name="BodyText">
<body><_char>Special Package</_char></body>
</pfjob:var>
<pfjob:var name="Picture">starburst.tif</pfjob:var>
</pfjob:doc_variables>
</pfjob:job_command>
Note: Notice that the value for the variable BodyText must use the XML character entity names for the symbols used for the XML tags.
The Picture variable is defined in the project as an image variable. You do not need to include the full path to the image file since Pageflex Server assumes image files are stored in the “Images” folder for the project. See the Pageflex Server Guide for details.