Section - 4 : Controlling Documaker Server

---

To control Documaker Server via Docupresentment, use these Docupresentment rules:

• RPDCheckAttachments - Checks the required input attachment variables and INI options before starting the GenData program.
• RPDCheckRPRun - Makes sure Documaker Server is running. If Documaker Server is not running, this rule starts it.
• RPDCreateJob - Finds the attachment variables for each of the values in the job ticket and adds them to the XML tree. The XML tree is added to the RPDJobTicket DSI variable so the next rule can use it.
• RPDProcessJob - Gets the XML tree from the RPDJobTicket variable and writes it to a file. This file is used as the job ticket which triggers the Documaker Server process.
• RPDStopRPRun - Receives the current process ID from the DSI variable RPDRunProcess and then terminates Documaker Server.

RPDCheckAttachments

Use this rule to check the required input attachment variables and INI options before starting the GenData program.

Syntax

Parameters

Parameter	Description
DSIHANDLE	hInstance DSI instance handle
char * pszParms	Pointer to rule parameter string unsigned long
ulMsg	DSI_MSG, such as DSI_MSGRUNF unsigned long
ulOptions	options

This rule runs before the RPDCheckRPRun rule. Using this rule, ReqType becomes:

The expected attachment variables are checked only if they are in the RPDAttachments control group. Here is an example:

If the ExtrFile option is required, the rule checks to see if it exists. Keep in mind the ExtrFile option includes a full path. If you omit the path, the system uses the path specified in the ExtrPath option as the default path.

This rule also checks these options in the RPDRunRP control group:

If the UserINI option does not include a drive letter, the system will look at the Directory option to find the path, so the full UserINI name becomes:

In other cases, you can set the UserINI option, as shown here:

So the full UserINI name becomes:

d:\ProgIDS\RP\Mstrres\Validate\W32exe\fsiuser.ini

This rule also makes sure the USERINI.INI file exists. For UNIX, if the first byte is “/”, the system looks at the UserINI option for the full path, for example:

UserINI = /ProgIDS/RP/Mstrres/Deflib

Otherwise, the system uses the path specified in the Directory option. Keep in mind that if you omit the UserINI option, the system uses the FSIUSER.INI file instead.

INI options

Returns

Success or failure.

Error messages

Message	Description
RPD0001	Can not locate variable #VARIABLE,# in the attachment list at #LOCATION,#.
RPD0004	Can not add variable #VARIABLE,# to attachment at #LOCATION,#.
RPD0007	File #FILENAME,# does not exists. Failed to #LOCATION,#.
RPD0009	The INI option #INIOPTION,# could not be located in the group #INIGROUP,#.

RPDCheckRPRun

Use this rule to make sure Documaker Server is running. If Documaker Server is not running, this rule starts it.

Syntax

Parameters

Parameter	Description
DSIHANDLE	hInstance DSI instance handle
char * pszParms	Pointer to rule parameter string unsigned long
ulMsg	DSI_MSG, such as DSI_MSGRUNF unsigned long
ulOptions	options

To determine if Documaker Server is running, the rule looks at the CONFIG value. If the CONFIG value is not the same as it was in the previous run, this rule stops and then restarts Documaker Server.

On the RUNF message, this rule looks to see if a Documaker Server process exists and starts one if needed. On the RUNR message, this rule stops the Documaker Server process if there was an error.

On DSI_MSGRUNF, this rule first checks to see if Documaker Server is running by detecting the gendata semaphore created by RULServerBaseProc rule. If the semaphore does not exist, Documaker Server is not running. This rule then starts Documaker Server and creates a semaphore called rpdrunrp.

This lets Documaker Server check the status of the Docupresentment by detecting the existence of the semaphore. It also lets Documaker Server terminate normally in case Docupresentment stops.

To handle situations where you have multiple master resource libraries (MRLs), the rule checks the CONFIG value for every job process to see if a new MRL is requested. If the CONFIG value changes, the rule stops the current Documaker Server process and starts another one which uses the new MRL.

On DSI_MSGRUNR, this rule terminates Documaker Server if errors occur.

Input attachment variables

Variable	Description
CONFIG	The configuration for the master resource library (MRL). See also the DPRSetConfig rule and the setup with multiple master resource directories.

Output DSI variables

Variable	Description
RPDRunProcess	This value is the process ID for the Documaker Server process.
RPDSemaphoreName	The semaphore name from the RPDSemaphore INI option.
GENSemaphoreName	The semaphore name from the GENSemaphore INI option.
RPDRunSemaphore	Stores the RPDSemaphore handle.
RPDJobLogName	The name of the job log file name to use.
RPDJobTicketName	The name of the job ticket file name to use.

INI options

You can use these INI options:

Option	Description
RPDRunRP control group
Executable	The name and path of the program you want to execute, such as d:\rpsetup\gendaw32.exe.
Directory	The path to the master resource library, where you want to run Documaker Server.
UserINI	(Optional) The name and path of the INI file you want to use. The default is the FSIUSER.INI located in the directory specified by the Directory option.
IDSServer control group
GENSemaphoreName	The name of the semaphore. The default is gendata.
RPDSemaphoreName	The name of the semaphore. The default is rpdrunrp.

Returns

Success or failure.

Error messages

Message	Description
RPD0001	Cannot locate variable #VARIABLE,# in the attachment list at #LOCATION,#.
RPD0004	Cannot add variable #VARIABLE,# to attachment at #LOCATION,#.
RPD0008	The call by #LOCATION,# to API #APINAME,# failed.
RPD0009	The INI option #INIOPTION,# can not be located in the group #INIGROUP,#.
RPD0010	Cannot create DSI variable #VARIABLE,#. #LOCATION,# failed.

RPDCreateJob

Use this rule to find the attachment variables for each of the values in the job ticket and add them to the XML tree. The XML tree is added to the RPDJOBTICKET DSI variable so the next rule can use it.

Keep in mind that the RPDCreateJob rule always adds the DbLogFile XML element to the job ticket. If a value for this element is not in the job ticket, a unique file name is generated and added. If an attachment variable or INI option is present but set to a blank value, the RPDCreateJob rule does not add the DbLogFile element.

Syntax

Parameters

Parameter	Description
DSIHANDLE	hInstance DSI instance handle
char * pszParms	Pointer to rule parameter string unsigned long
ulMsg	DSI_MSG, such as DSI_MSGRUNF unsigned long
ulOptions	options

On DSI_MSGRUNF, this rule creates the XML document for the job ticket that triggers the job processing. You should direct your results to designated directories and use unique file names, especially if you want to support multiple MRL setups, multiple Documaker Server processes, or multiple job processes.

You can change INI options via attachment variables. These changes are added onto the XML tree so Documaker Server can update the INI options in memory.

On DSI_MSGRUNR, this rule processes the XML document of the job log, and all values of the XML tree are added to the output attachment.

Input attachment variables

You can use these input attachment variables:

Variable	Description
ExtrFile	Extract file name and path. This is a required input file.
MsgFile	(Optional) Message file name and path. If you omit the path, the PrintPath attachment variable is used. If the PrintPath was omitted, the system uses the PrintPath defined in the IDSServer control group. If the file name is omitted, the system creates a 46-byte unique file name.
ErrFile	(Optional) Error file name and path. If you omit the path, the PrintPath attachment variable is used. If the PrintPath was omitted, the system uses the PrintPath defined in the IDSServer control group. If the file name is omitted, the system creates a 46-byte unique file name.
LogFile	(Optional) Log file name and path. If you omit the path, the PrintPath attachment variable is used. If the PrintPath was omitted, the system uses the PrintPath defined in the IDSServer control group. If the file name is omitted, the system creates a 46-byte unique file name.
DBLogFile	(Optional) DB log file name and path. If you omit the path, the PrintPath attachment variable is used. If the PrintPath was omitted, the system uses the PrintPath defined in the IDSServer control group. If the file name is omitted, the system creates a 46-byte unique file name.
NAFile	(Optional) NA file name and path. If you omit the path, the PrintPath attachment variable is used. If the PrintPath was omitted, the system uses the PrintPath defined in the IDSServer control group. If the file name is omitted, the system creates a 46-byte unique file name.
POLFile	(Optional) POL file name and path. If you omit the path, the PrintPath attachment variable is used. If the PrintPath was omitted, the system uses the PrintPath defined in the IDSServer control group. If the file name is omitted, the system creates a 46-byte unique file name.
NewTrn	(Optional) NewTrn file name and path. If you omit the path, the PrintPath attachment variable is used. If the PrintPath was omitted, the system uses the PrintPath defined in the IDSServer control group. If the file name is omitted, the system creates a 46-byte unique file name.
PrintBatchPath	The default path for print batches.
PrintBatches	The number of batches to print. If you enter zero or you do not enter this variable, no print batch information is updated. Your entry cannot exceed the number of printers listed in the PrinterInfo control group in the FSISYS.INI file.
PrintBatchesX	The name of a print batch, where X denotes the number of the print batch, continuing from one to PrintBatches. If omitted, the system creates a 46-byte unique name for the print batch. A print batch can have a full path. If it does not have a path, PrintPath is used. If PrintPath is omitted, the system uses the path specified in the PrintPath option in the Data control group.
BatchFiles	The number of batch files. If you enter zero or omit this option, no batch file information is updated. Your entry should not exceed the number of batch files listed in the Print_Batches control group in the FSISYS.INI file.
BatchFilesX	The name of the batch file. X denotes the number of the batch file, counting from one to the maximum. If you omit this option, the system creates a 46-byte unique name for the batch file. You can include a full path. If you omit the path, the system uses the PrintPath. If the PrintPath is omitted, the system uses the path specified in the PrintPath option in the IDSServer control group.
INIOptions	The number of other INI options to update.
INIOptionsX.Group	The INI group name you want to update.
INIOptionsX.Option	The INI option name you want to update.
INIOptionsX.Value	The value of the INI option you want to update. X indicates the number of INI options, counting from one to the maximum.

Output DSI variables

Variable	Description
RPDJOBTICKET	Job ticket variable. Its value is a XML document handle for the job ticket.

Input DSI variables

Variable	Description
RPDJOBLOG	Job log variable. Returns an XML document handle for the job log.

Output attachment variables

Variable	Description
ExtrFile	Extract file name and path.
MsgFile	Message file name and path.
ErrFile	Error file name and path.
LogFile	Log file name and path.
DBLogFile	DB log file name and path.
NAFile	NA file name and path.
POLFile	Pol file name and path.
NewTrn	NewTrn file name and path.
PrinterX	Name and path of print batches. X denotes the number of the print batches from one to the maximum.
BatchX	The name and path of the batch files. X denotes the number of batch files, from one to the maximum.
Results	Success or an error code from the Docupresentment rules.
RPResults	An error code from Documaker Server: 0=Success, 4=Warning, 8 or 16=Failure.

Note that the input attachments for PrintBatchX should be in the same order as those for PrinterX, as defined in the PrintInfo control group in the FSISYS.INI file. Also keep in mind that PrinterX and BatchX are option names you define in the PrintInfo and Print_Batches control groups.

INI options

Option	Description
IDSServer control group
PrintPath	Used as a default path for print batches and the rest of the output files.
PrintFileCacheTime	The length of time, in seconds, you want the system to store the print files. At expiration time, the system removes the print batch files. The default is 1800 (30 minutes). Note that only print files with the 46-byte unique name created by the system are cached.
TextFileCacheTime	The length of time, in seconds, you want the system to store the text files. At expiration time, the system removes the text files. The default is 1800 (30 minutes). Note that only text files with the 46-byte unique name created by the system are cached.
Printer control group
PrtType	The type of print batch file. Your entry must be consistent with the control group defined in the FSISYS.INI file. For instance, if you set up a PrtType:PDF control group there, enter PDF here.
RPDRunRP control group
BaseLocation	The URL to the output data directory. Your entry must be consistent with the PrintPath or other defined data path.

Returns

Success or failure.

Error messages

Message	Description
RPD0002	Cannot create #TAGNAME,# at #LOCATION,#.
RPD0003	Cannot create DSI variable #VARIABLE,# at #LOCATION,#.
RPD0004	Cannot add variable #VARIABLE,# to attachment at #LOCATION,#.
RPD0005	Cannot locate DSI variable #VARIABLE,# at #LOCATION,#.
RPD0006	DSI variable #VARIABLE,# does not contain valid data. Failed to #LOCATION,#.

RPDProcessJob

Use this rule to get the XML tree from the DSI variable RPDJobTicket and write it to a file written on the RUNF message. On the RUNR message, this rule waits for the job log file. The job log file is located in the same directory and is loaded as an XML file on the RUNR message.

Syntax

Parameters

Parameter	Description
DSIHANDLE	hInstance DSI instance handle
char * pszParms	Pointer to rule parameter string unsigned long
ulMsg	DSI_MSG, such as DSI_MSGRUNF unsigned long
ulOptions	options

The Docupresentment variable RPDJobLog is created with the XML job log. The RPDJobLog variable and the XML tree associated with it is destroyed in this rule on the TERM message.

You can set the maximum amount of time to wait using the MaxWaitTime option. On the RUNR message, this rule also removes the job log file from disk. You can also control the removal of the job log file with the RPDProcessJob INI option. This option is for debugging purposes only.

On DSI_MSGRUNF, this rule receives the XML document handle from the DSI variable RPDJobTicket, and writes the XML tree into the JOBTICKET.XML file specified in the Directory option.

On DSI_MSGRUNR, this rule waits until it receives the job log file (JOBLOG.XML), from Documaker Server. You specify how long the system should wait using the SleepingTime INI option. If the waiting time exceeds the limit, the rule stops Documaker Server.

The system locates a job log placed in the directory specified in the Directory INI option. The job log file is loaded into an XML document so the XML tree can be written out in attachments. Whether the JOBLOG.XML file should be removed, depends on your entry in the RPDProcessJob INI option.

Input Docupresentment variables

Variable	Description
RPDJobTicket	A job ticket variable. It returns the XML document handle for the job ticket.

Output files

File	Description
JOBTICKET.XML	A job ticket, which is a trigger for the Documaker Server process. It contains request information and information used to update INI options.

Output DSI variables

Variable	Description
RPDJobLog	The job log variable. Its value is an XML document handle for the job log.

INI options

Option	Description
RPDRunRP control group
Directory	Enter the path where you want to load and unload the JOBTICKET.XML and JOBLOG.XML files.
IDSServer control group
MaxWaitTime	Enter, in seconds, the maximum length of time you want Docupresentment to wait for the JOBLOG.XML file. The default is 60 seconds.
SleepingTime	Enter the time, in milliseconds, to specify how often Docupresentment should check for a job ticket. The default is 1000 (1 second).
WaitForStart	The length of time Docupresentment should wait for Documaker Server to start before assuming Documaker Server is not running. The default is 10 seconds. Adjust this value if the Documaker Server requires more time to start. If Documaker Server does not start within the allotted time, this rule returns an error and stops processing.
Debug control group
RPDProcessJob	Enter Yes to keep the JOBLOG.XML file. Enter No to remove it.

Return values

Success or failure.

Error messages

Message	Description
RPD0003	Cannot create the DSI variable #VARIABLE,# at #LOCATION,#.
RPD0004	Cannot add the variable #VARIABLE,# to attachment at #LOCATION,#.
RPD0005	Cannot locate the DSI variable #VARIABLE,# at #LOCATION,#.
RPD0006	The DSI variable #VARIABLE,# does not contain valid data. Failed to #LOCATION,#.
RPD0007	The file #FILENAME,# does not exist. Failed to #LOCATION,#.
RPD0008	The call by #LOCATION,# to API #APINAME,# failed.
RPD0009	The INI option #INIOPTION,# cannot be located in the group #INIGROUP,#.

RPDStopRPRun

Use this rule to stop Documaker Server. To do so, you need to execute the request type STOP as described in the topic, Setting Up Docupresentment.

This rule is also used as an INIT/TERM rule and is registered on Docupresentment under the ReqType:INI control group. You can use this rule to make sure that when Docupresentment stops, Documaker Server also stops.

Syntax

Parameters

Parameter	Description
DSIHANDLE	hInstance DSI instance handle
char * pszParms	Pointer to rule parameter string unsigned long
ulMsg	DSI_MSG, such as DSI_MSGRUNF unsigned long
ulOptions	options

This rule receives the current process ID from the DSI variable RPDRunProcess and then terminates Documaker Server.

Return values

Success or failure.

RULServerBaseProc

When you use Docupresentment to run Documaker Server, this rule replaces the RULStandardBaseProc rule and is registered as RULServerJobProc.

Syntax

;RULServerBaseProc;;;

Insert this rule in the AFGJOB.JDT file as the first rule.

This rule looks for a job ticket file in the current working directory and loads it as an XML file. All of the values on the XML tree are added to or updated in the INI options. After Documaker Server finishes processing, the rule checks the status. If there are errors, it returns a no more bases return code on the next iteration. This terminates Documaker Server.

This rule uses a polling technique—sleep a while and check for the file existence— which you can configure using INI options. The rule loads the job ticket and sets INI options used when running subsequent rules. On the post message, this rule creates a job log XML tree and writes it to disk. If any necessary values are missing from the XML job ticket, these values are generated and changed (or appended) in the INI context.

On RP_PRE_PROC_B, this rule creates a semaphore (gendata), which makes it possible for the Docupresentment RPDCheckRPRun rule to detect the status of Documaker Server when the next processing job starts.

This rule stays in waiting status and checks for the existence of job ticket file (JOBTICKET.XML) and the rpdrunrp semaphore. As soon as the job ticket file is detected, this rule loads it onto the XML tree and uses the contents of the XML tree to update INI options in memory.

If the rule does not detect the rpdrunrp semaphore, the rule terminates Documaker Server by returning a msgNO_MORE_BASES return code. It also creates a GVM variable (DSISERV) so the CUSInitPrint rule can re-initialize printers after the job process is complete. This GVM variable can be used by any of the Documaker Server rules to detect if the Documaker Server is running under Docupresentment, if different logic is needed.

On RP_POST_PROC_B, the rule writes out the job log file and removes the job ticket file. If the RULServerJobPRoc option is set to Yes, a copy of the file will be obtained for debugging purposes.

INI options

Use these INI options with this rule:

Option	Description
Data control group
DataPath	Used as the default path if you omit PrintPath.
ExtrFile	Enter the name and path of the extract file.
MsgFile	Enter the name and path of the message file.
ErrFile	Enter the name and path of the error file.
LogFile	Enter the name and path of the log file.
DBLogFile	Enter the name and path of the DB log file.
NAFile	Enter the name and path of the NA file.
POLFile	Enter the name and path of the POL file.
NewTrn	Enter the name and path of the NewTrn file.
PrinterInfo control group
Printer	Enter the designated printers for print batches.
Printer control group
Port	Enter the name of the print batch file for each designated printer. Note the group name is defined by the printer option in the PrinterInfo control group.
Print_Batches control group
Batch1	Then name of the batch file.
IDSServer control group
SleepingTime	Enter the amount of time in milliseconds you want the system to wait before it checks for a job ticket. The default is 1000 (1 second).
GENSemaphoreName	Enter the name of the semaphore. The default is gendata.
RPDSemaphoreName	Enter the name of the semaphore. The default is rpdrunrp.
Debug control group
RULServerJobProc	Enter Yes if you want errors appended to the ErrFile, the LogTrace file to record the trace, and the JobLog file to be renamed and saved.
PrintFormSet control group
MultiFilePrint	Enter Yes to generate multiple print files which use 46-byte unique names. To identify which recipients are in which print batch, enter No or omit this option.This causes the PrintFormSet rule to save the printer for the print batch along with its recipient information. The RULServerBaseProc rule then adds three new tags for each print batch file and adds them to the JOBLOG.XML file. For example, for the print batch file on PRINTER1, the system creates these new tags: <PRINTER1RECIP>Insured</PRINTER1RECIP> <PRINTER1CODE>001</PRINTER1CODE> <PRINTER1DESC>Insured Copy</PRINTER1DESC>
LogFileType	Specify the type of print log file, such as XML or TEXT.
LogFile	Enter the name and path of the print log file. If you omit the extension, the system uses the LogFileType option to determine the extension.

Input file

JOBTICKET.XML

Output file

JOBLOG.XML

ServerBaseProc

When you use Docupresentment to run Documaker Server, this rule replaces the RULStandardJobProc rule.

Syntax

;ServerBaseProc;;;

Insert this rule in the AFGJOB.JDT file as the first rule.

This rule looks for a job ticket file in the current working directory and loads it as an XML file. All of the values on the XML tree are added to or updated in the INI options. After Documaker Server finishes processing, the rule checks the status. If there are errors, it returns a no more bases return code on the next iteration. This terminates Documaker Server.

This rule uses a polling technique—sleep a while and check for the file existence— which you can configure using INI options. The rule loads the job ticket and sets INI options used when running subsequent rules. On the post message, this rule creates a job log XML tree and writes it to disk. If any necessary values are missing from the XML job ticket, these values are generated and changed (or appended) in the INI context.

On RP_PRE_PROC_B, this rule creates a semaphore (gendata), which makes it possible for the Docupresentment RPDCheckRPRun rule to detect the status of Documaker Server when the next processing job starts.

This rule stays in waiting status and checks for the existence of job ticket file (JOBTICKET.XML) and the rpdrunrp semaphore. As soon as the job ticket file is detected, this rule loads it onto the XML tree and uses the contents of the XML tree to update INI options in memory.

If the rule does not detect the rpdrunrp semaphore, the rule terminates Documaker Server by returning a msgNO_MORE_BASES return code. It also creates a GVM variable (DSISERV) so the CUSInitPrint rule can re-initialize printers after the job process is complete. This GVM variable can be used by any of the Documaker Server rules to detect if the Documaker Server is running under Docupresentment , if different logic is needed.

On RP_POST_PROC_B, the rule writes out the job log file and removes the job ticket file. If the RULServerJobPRoc option is set to Yes, a copy of the file will be obtained for debugging purposes.

INI options

Option	Description
Data control group
DataPath	Used as the default path if you omit PrintPath.
ExtrFile	Enter the name and path of the extract file.
MsgFile	Enter the name and path of the message file.
ErrFile	Enter the name and path of the error file.
LogFile	Enter the name and path of the log file.
DBLogFile	Enter the name and path of the DB log file.
NAFile	Enter the name and path of the NA file.
POLFile	Enter the name and path of the POL file.
NewTrn	Enter the name and path of the NewTrn file.
PrinterInfo control group
Printer	Enter the designated printers for print batches.
Printer control group
Port	Enter the name of the print batch file for each designated printer. Note the group name is defined by the printer option in the PrinterInfo control group.
Print_Batches control group
Batch1	Then name of the batch file.
IDSServer control group
SleepingTime	Enter the amount of time in milliseconds you want the system to wait before it checks for a job ticket. The default is 1000 (1 second).
GENSemaphoreName	Enter the name of the semaphore. The default is gendata.
RPDSemaphoreName	Enter the name of the semaphore. The default is rpdrunrp.
Debug control group
RULServerJobProc	Enter Yes to get a copy of the job ticket file before the system removes it.
PrintFormSet control group
MultiFilePrint	Enter Yes to generate multiple print files which use 46-byte unique names. To identify which recipients are in which print batch, enter No or omit this option.This causes the PrintFormSet rule to save the printer for the print batch along with its recipient information. The RULServerBaseProc rule then adds three new tags for each print batch file and adds them to the JOBLOG.XML file. For example, for the print batch file on PRINTER1, the system creates these new tags: <PRINTER1RECIP>Insured</PRINTER1RECIP> <PRINTER1CODE>001</PRINTER1CODE> <PRINTER1DESC>Insured Copy</PRINTER1DESC>
LogFileType	Specify the type of print log file, such as XML or TEXT.
LogFile	Enter the name and path of the print log file. If you omit the extension, the system uses the LogFileType option to determine the extension.

Input file

JOBTICKET.XML

Output file

JOBLOG.XML