Chapter - 7 : Frequently Asked Questions

---

This chapter provides answers to commonly asked questions.

Is XML the same as HTML?

No. XML is primarily a data exchange format and contains the data definitions and the data. HTML can contain data and layout, however the definitions of the data are not defined in tags (such as <author>) as they are in XML. These tags are defined in a schema.

To portray XML data in a page layout an XSL (Extensible Stylesheet Language) file is required. This would contain information such as position, fonts, and so on.

The benefits of XML over HTML are that it is becoming an industry standard accepted format for data transfer and it has a more defined structure. When an XML file has a valid structure it is known as being well formed.

Who developed the XML parser?

The system uses the Expat XML parser, which was originally developed for Netscape. It is a third-party library. You cannot plug in your own parser. Here are some links if you want more information on Expat:

http://expat.sourceforge.net/

http://sourceforge.net/projects/expat/

What is an XML tag?

XML tags are created like HTML tags. There is a start tag and a closing tag.

<TAG>content</TAG>

The closing tag uses a slash after the opening bracket. The text between the brackets is called an element. Keep in mind...

• Tags are case sensitive.
• Starting tags always need a closing tag.
• All tags must be nested properly.
• Comments can be used in the same way as HTML, for instance <!--Comments-->

Empty tags can be defined as <TAG/>. Empty tags do not require a closing tag.

What is an XML attribute?

Elements in XML can use attributes. The syntax is:

<element attribute-name=”attribute-value”>…</element>

The value of an attribute needs to be quoted, even if it contains only numbers. For example:

<car color = “red”>Volvo</car>

The same entry could be defined without using attributes:

What is a schema?

A schema is a map of the structure of the data. This is presented in an XML type layout. Using the sample XML file on the previous page the schema for this would be as shown below.

What XML standards are accepted by Documaker and Docupresentment applications?

XML standards are set and defined by the W3C organization (www.w3c.org). This is a consortium of over 450 organizations that set and define common standards and protocols in use on the World Wide Web. Documaker and Docupresentment applications use the XML 1.0 standard and will support the following encoding:

• UTF-8
• ISO-8859-1
• US-ASCII

You should be able to use any of these encodings to pass information to Docupresentment, DSI APIs or Documaker Server. Docupresentment sends back UTF-8.

Are ampersands (&) and octothorpes (#) supported in XML files?

Yes, however some characters must be defined as entity references or character references. For instance, you can use octothorpes in XML files as shown here:

<message>Use #1 before using #2</message>

Entity references begin with an ampersand (&) and end with a semicolon (;). These are predefined codes within the XML specification for commonly used characters. Here are some examples:

Character	In XML
&	&
“	"
‘	'
>	>
<	&lt;

Character references begin with an ampersand and an octothorpe (&#) and end with a semicolon (;) . These are used for characters which are not commonly used and do not already have entity references pre-defined.

Here are some examples:

Character	In XML
é	é
í	í
ü	ü

Refer to the W3C (www.w3c.org) for more information on special characters.

What tag names cannot be used in XML?

There are a number of restrictions for tag names. These include:

• No tag names can start with xml.
• Tag names cannot start with underscores or numbers.
• Names cannot contain semicolons (:).
• There cannot be a space after the opening < character.

Reserved words are defined by the W3C. Some of the words that cannot be used include:

If	Typeswitch	Item	Node
Element	Attribute	Comment	Child
Text	Processing-instruction	ID	Key

For a full list of reserved words refer to the W3C (www.w3c.org).

How do you send an XML input file to Documaker?

You can use these two rules to send an XML file to Documaker:

• XMLFileExtract - Used when you point to a flat file which contains references to multiple XML files. For example, this method can be used if the key information is in the flat file and the triggering and variable data is in the XML file.
• UseXMLExtract - Used when you have one XML file containing all transactions.

See the Rules Reference for more information.

How do you export an XML file from Documaker Workstation?

To configure the import and export capabilities of Documaker Workstation:

1. Open the FSISYS.INI file in the resource library for which you want to use export files. You can use any text editor to open this file.

2. Locate the ExportFormats control group. Add the following line:

   XML =09=;XM;XML Export;WXMW32->WXMExportXML

   Here is an example, which assumes 09 is not already being used.

   < ExportFormats >

   09=;XM;XML Export;WXMW32->WXMExportXML

What are the Unicode capabilities of XML?

The Documaker and Docupresentment XML parser supports the following encodings: UTF-8, ISO-8859-1, and US-ASCII. The input XML file must use one of these encodings or should not specify an encoding at all. Here is an example of an XML header that specifies UTF-8 encoding:

<?xml version="1.0" encoding="UTF-8" ?>

If you do not specify an encoding, the system uses an encoding of ISO-8859-1. You can find more information on encoding standards in the Using Unicode Support manual located at:

http://www.oracle.com/us/support/index.html

How do you set up Docupresentment to use XML?

If you are using Docupresentment as the message server, you must also add the INI options shown below to let Documaker Workstation retrieve an archived record from Docupresentment and load data into a form set before any data is entered by a user.

The archived record is retrieved using the Key1, Key2, and KeyID entered on the New Form Set window. For this to happen, you must set up the following request type in the DOCSERV.INI file for Docupresentment:

You can use any name for the archive library, as long as the same MRL name is used in Documaker Workstation. You can set up this feature as an entry or import hook:

or

If you set it up as an entry or import hook, you must also set up these INI options:

Option	Description
DSIUseNTUserID	Set this option to Yes to use the NT user ID. The default is No. This gives you a way to pass the NT user ID in the queue instead of the normal DMWS ID.
DSIVars	Enter variable;value, where variable is the variable name and value is its value. This lets you identify a constant list of variables to be sent in the queue.
DSIIgnoreTimeoutError	Enter Yes to continue processing if a timeout occurs. The default is No. This gives you a way to ignore a timeout when waiting on a return queue.
DSIAttachedVarFile	The default is DOCC_XML. Set this option to the attachment name if it differs from DOCC_XML. This gives you a way to specify the variable name the XML file is attached to.
DSIImportLevel	This option is typically used by programmers. Enter 2 if you want the hook to operate on the FAP_MSGOPEN level. Enter 3 if you want it to operate on the FAP_MSGRUN level. The default is 2.
DSITimeout	Enter the number of milliseconds you want for the time-out. The default is 60000 milliseconds or 60 seconds.
DSIReqType	Enter the name of the request type of the message placed in the queue. The default is GETXML.
DSIRecordDFD	Enter the name of a DFD file. The system tries to match variable fields sent in the request to field values in this DFD file. It then attaches the DFD record to the end of the message.

If the request for an XML file comes back with an error, as opposed to a time out, Docupresentment displays an error message.

Can the SOAP standard be used with Docupresentment?

Docupresentment version 1.7 added a new open and documented queue control message format based on XML and the evolving SOAP standard. The XML message format is supported by the MSMQ and MQSeries queues, but is not supported by the generic queue system that ships with the base Docupresentment product. The base product queues use a proprietary message format.

You can find more information on the XML and SOAP on the W3C WEB site:

http://www.w3.org/

You can also find information about SOAP messages with attachments at:

http://www.w3.org/tr/soap-attachments

Note: Skywire Software will follow the evolving standards of SOAP and UDDI and move toward universal messaging. The first version of the DSI message format is based on XML and complies with many of the initial standards for SOAP message envelopes. Later versions will move transactions and servers toward fuller SOAP and UDDI compliance.

Skywire Software has used message queuing as a means of serializing requests and responses between loosely coupled clients and servers without requiring one-to-one connections. MQ Series has evolved into a standard program-to-program message bus for integrating loosely coupled applications.

Docupresentment includes the client and server sides of the DSI (document server interface) system and of the DQM (document queuing and messaging) system. These interface layers help manage connections between multiple simultaneous clients and multiple simultaneous servers. The DQM layer provides a logical abstract layer over the physical process of accessing the queue, so one implementation can support and switch between multiple queuing systems. This layer supports these models:

• A generic system that ships with Docupresentment (handled by DCBLIB)
• Support for Microsoft MSMQ (handled by MQLIB)
• Support for IBM MQ Series (handled by QSRLIB)

The DSI system provides a logical abstract layer over the physical process of assembling, delivering, and parsing of a message, so the initiator of the message does not have to know the physical format of the message, and is insulated from internal software changes to the message format between product versions.

For instance, you can use the DSI messaging client with Documaker Workstation so Documaker Workstation can work with

• External systems via either MQ Series or MSMQ messaging middleware.
• Docupresentment as a bridge to a legacy system to retrieve data for import.

The first ability means second is optional. You can also use your own internal programs and interface using MQSeries.

The advantage of having a logical abstract layer is that it lets you deploy applications for different message queuing systems without requiring program changes. Only minimal setup changes are required to test or deploy the same application with a different queuing system. By abstracting the message format, applications are insulated from internal changes to the message format and can use the Skywire Software APIs to correctly assemble or disassemble messages.

The disadvantage of message format abstraction is that non-Skywire Software applications might be required to use Skywire Software APIs to communicate with Skywire Software applications.

On some platforms, it may not be practical to invoke these APIs. The proprietary nature of the original message format further complicates the issue.

If you are integrating with Docupresentment as the server, the message format documentation is not necessary. If, however, you are integrating with another application, the message format may be needed if you do not use Docupresentment APIs and you can communicate via MQSeries.

For additional information on SOAP and Docupresentment, see the Docupresentment Guide.

How can Docupresentment run Documaker using XML job-tickets?

You can set up Docupresentment to run Documaker as a subordinate process. Web clients communicate with Docupresentment using queues. Docupresentment communicates with Documaker via XML files called job tickets and job logs.

This diagram illustrates the process:

Docupresentment can start or stop Documaker as needed, without user interaction. One Docupresentment session controls one Documaker process. You can, however, implement multiple Docupresentment sessions and have multiple Documaker processes as well. Keep in mind these limitations:

• You can only run Documaker in single step mode.
• You must run Documaker on Windows NT, Windows XP, or Windows 2000.
• Different resource setups for Documaker are supported, but Documaker processing restarts if resources are changed, eliminating the performance benefits. This should not be a problem because it is unlikely multiple Documaker setups will be used with a single Docupresentment implementation. You can, however, experience problems testing a system with multiple setups.
• During processing, some INI options can be changed by the client. Since some Documaker rules use static variables and store INI values in memory, it is possible that a client will be unable to change an INI option if those Documaker rules are used. To handle these situations, you must restart Documaker.

For more information, see the Docupresentment Guide and the Docupresentment SDK Reference.

Can you use DAL with XML files?

You can use DAL XML API functions to let Documaker applications access specified XML documents and retrieve XML data via a DAL script. There are two scenarios in which you would use DAL XML API functions:

Scenario 1

A Documaker program, such as GenData, loads an XML document and extracts the XML tree at the transaction level using the XMLFileExtract rule. This rule creates a list type DAL variable with a default name of %extract and pushes it onto the DAL stack.

Then you can call other XML API functions in a DAL script to access the XML tree and extract XML data.

Here are examples of the form set and image rules you would add and a DAL script that would call the XML API functions.

Add this in the AFGJOB.JDT file:

;XMLFileExtract;2;File=.\deflib\test.xml

The rule loads the XML file and creates a list type DAL variable to pass the XML tree to the XML API function.

Add this in your DDT file:

;0;0;DALXMLSCRIPT;0;9;DALXMLSCRIPT;0;9;;DAL;Call("TEST.DAL");N;N;N;N;4792;19444;11010;

TEST.DAL is the name of the DAL script file. DALXMLSCRIPT is the name of the variable field in the FAP file.

Here is an example of the DAL script:

Scenario 2

You can also load the XML document and create the XML tree at a specific field by calling the LoadXMLList rule from a DAL script. You must set the calling procedure in the DDT file as shown in Scenario 1.

Here is an example of DAL script file:

For more information, see the DAL Reference.

Are triggers set the same way when you use XML files in Documaker?

No, triggers are set differently when you use XML. The XML file should contain the names of the forms to trigger.

If the FORM.DAT has all recipients set to zero copy counts, then those forms will be removed from the form set. The recipient copy count should be set in the FORM.DAT file. For example, based on

You can do simple triggering based on the existence of a node. For example, this

/child::car

would trigger a form if car is a child of the root node. You could make it trigger two of the same forms because there are two cars.

The system supports value matching. So you can do the following:

/child::car[child::driver="Tom"]

Or, you can use the RecipIf rule to trigger an image with custom rule parameters, as shown in this example:

A={!/child::car/child::driver 1,7}::if
(A='Tom ')::return("^1^")::end::;

If there is such a value in that element in the XML file, the image would trigger. For this to work, define the offset of the variable attribute as 1 and the length of the data you want to compare.

For more information, see the Documaker Administration Guide.

Can you use the Concat rule with XML?

You cannot use the Concat rule with XML files. Instead, use a DAL script. Here is an example:

;0;0;CITYSTATEZIP;0;30;CITYSTATEZIP;0;30;;DAL;csz=@("ADDR-CITY")&', '&@("ADDR-STATE")&' '&@("ADDR-ZIP")::Return csz)::;;N;N;N;N;135;1972;16010;

See the DAL Reference for more information.

Can you use the SetAddr rule with XML?

You cannot use the SetAddr rules with XML files. Instead, use the RemoveWhiteSpace rule to remove the white space from between fields. This rule works similarly to the SetAddr rules, but is not address specific.

See the Rules Reference for more information.

Can you use the PrintIf rule with XML?

You cannot use the PrintIf rule with XML files. Instead, use a DAL script. Here is an example:

;0;0;COMPANY;0;8;COMPANY;0;8;;DAL;if (@("PRINTIFSUB")="A")THEN ANSWER1="Accident":: elseif (@("PRINTIFSUB")="C")THEN ANSWER1= "Casualty"::end::return (ANSWER1)::;N;N;N;N;11292;919;12010;

See the DAL Reference for more information.

How does Documaker deal with empty tags in XML files?

Documaker and Docupresentment use the same XML loading routine. The XML loading routine does not care whether you define all of the fields that might occur in a FAP file, nor does it care whether if field data is missing, so no error is produced when you load an XML file with missing field tags.

Just make sure the XML file you are loading is valid according to Documaker’s XML standards.

If, however, you export the form set, you may get similar same results — if the FAP files were loaded, the empty fields are written into the XML file with no data. If the FAP files are not loaded, the system only includes those fields created during the run — which is usually limited to just the fields with data.

The entries you can use to indicate empty tags are:

How are overflows defined?

When you define the SetOvFlow rule in the AFGJOB.JDT file, use the XML tag shown here:

;SetOvFlwSym;1;covsym,xml,1;

When you define the IncOvSym rule in the DDT file, use the XML tag, shown here:

;IncOvSym;covsym,xml;

If an image contains XML data on the same level, use the !descendant parameter instead of XPath:

The data for <fieldb> and <fieldc> are on the same level so you cannot use an XPath of:

You would have to use:

How do you handle overflow within overflow using XML?

Use the SetRecipFromImage rule with the XML overflow variable to get this to work.

Image A (which overflows will trigger image B using the SetRecipFromImage rule)
Image B (which overflows will trigger image C using the SetRecipFromImage rule)

and so on...

See the Rules Reference for more information.

Can you use the LoadExtractData and UseXMLExtract rules in single-step mode?

When running in single- or two-step mode, omit the LoadExtractData rule. Including it makes the GenData program enter a processing loop.

You can use the UseXMLExtract rule in single-step, two-step, or multi-step mode. When you use this rule in multi-step mode, place it after the LoadExtractData rule. In single-step or two-step mode, place it after the NoGenTrnTransactionProc rule.

You do not have to use the UseXMLExtract rule with the LoadExtractData rule when running in single-step or two-step mode.

Which version of XML does Transall support?

XML version 1.0 is compliant with Transall. Transall version 10.2 (20011101) supports both reading and writing XML files.

How do you write HTML pages to output XML via Docupresentment?

Modify the RECIPS.HTM page to add an XML option to the drop-down box on the page. Here is an example:

Then modify the DAP.INI file to make sure the PrtType control group is set to XML and not PDF, as follows:

What are some common XML-related errors?

Here is a list of common errors reported to Oracle Support concerning XML, Documaker, and Docupresentment:

Problem	Solution
I get an error message when trying the InitQueue method of the DSICoAPI library. In the trace file this information is reported: Mon Nov 12 08:34:13 2001 DUTLoadLibrary error. Cannot load DCBW32.DLL (DCBW32.DLL).Error: Mon Nov 12 08:34:13 2001 * DUTDefErrorExit Mon Nov 12 08:34:13 2001 * Cannot QueryProcAddr <0> <0> DCBSysInit	This is caused by the security settings on the server sharing. Revise these settings and provide users with access to all areas with content.
I have a display problem in the Blackline version. The system is not correctly merging the XML file with the style sheet (TEXTMERGE.XSL).	Some features were added to the style sheet that require MSXML 3.0 to work properly. After installing MSXML 3.0, which installed the MSXML3.DLL, and un-registering the MSXML.DLL, the Blackline feature should work properly.
XML files are delete periodically, before another process can pick them up.	For XML, you have to include TimeOut option in the HTMLFileCache control group. Enter the timeout value in seconds.
I need to write a DAL script to do conditional triggering using native XML.	Use the UseXMLExtract or XMLFileExtract rule to load the XML file and extract the XML tree at the transaction level. As part of this process, the system creates a list type DAL variable with a default name of %extract.
The XML data does not get mapped if the value within the element starts on a new line with leading spaces.	A single exclamation mark (!) removes the leading white space. To keep the space, use two exclamation marks (!!).