Using the Internet Document Server. Oracle 2.2

PDF

Документ

Chapter 2 Using the Internet

Document Server

This chapter provides information on the capabilities of the Internet Document Server and its architecture. This chapter also tells you how to set up the Internet

Document Server.

OTE

For information on installing IDS, see the IDS

Installation Guide .

You’ll find this information:

•

Overview on page 11

•

Using Multiple Servers on page 46

•

Setting Up a Windows NT Service on page 50

•

Handling Multi-threaded Requests on page 51

•

Using Rules Written in Other Scripting Languages on page 54

•

Using IDS as a Client to Another IDS on page 55

•

Monitoring IDS with SNMP Tools on page 60

•

Managing IDS Instances on page 62

•

Sending Results and Receiving Requests in

Multiple Formats on page 71

•

Logging and Tracing on page 74

•

Configuring IDS on page 93

•

Referencing Attachment Variables on page 102

•

Using the Message Queues on page 105

•

Using the Java Message Service (JMS) on page 111

Chapter 2

Using the Internet Document Server

•

Using WebSphere MQ on page 114

•

Using HTTP on page 127

•

Using Multiple Bridges on page 131

•

Submitting Batch Requests on page 133

•

Printing in Duplex Mode to PCL Printers on page 135

•

Using IDS to Distribute Email on page 136

•

Using IDS to Run Documaker on page 145

•

Using the XML Messaging System on page 159

•

Connecting to an SQL Database on page 167

•

Using the Thin Client Forms Publisher on page 172

•

Pausing IDS on page 173

•

Executing Request Types at Run Time on page 176

•

Publishing Your Forms on the Web on page 178

•

Formatting Text with XML Markup on page 183

•

Encrypting and Decrypting Data Files on page 184

•

Using Multiple Attachment Values with the Same Name on page 185

•

Converting XML Files Using a Template on page 188

•

Customizing Your System on page 192

•

Handling Security Issues on page 195

•

Using the FAP2XML Utility on page 197

•

Using LDAP Support on page 198

•

Using Default Time-outs for DSILIB-Based Client Applications on page 199

•

Running Timed Requests on page 201

•

In-Process Rendering for DPAView on page 202

•

Using DAL Functions for WIP Column Access on page 203

•

Using Enterprise Web Processing Services on page 205

Overview

VERVIEW

The Internet Document Server lets users connect to the server via the Internet. Executing back-end applications, however, requires additional components. These additional components are called

bridges. These bridges provide bridge components, software rules, document templates, and other files necessary to process documents.

The Internet Document Server lets users communicate via standard Internet methods using a standard web browser. No other specialized client software is required to use the

Internet Document Server; however, additional bridge components may require additional browser plug-ins, such as Adobe’s Acrobat Reader. The Internet Document

Server runs on a Microsoft Windows or Sun Solaris server running a web server package.

OTE

See Processing Documents Using the Internet on page 1 for more information on Oracle Insurance’s related products.

Keep in mind, as you read through the following examples, that XML standards as defined by the W3C require you to substitute text characters that are not in XML tags (for example, between <entry> and </entry> tags) as

escape sequences. The characters that require substitution are listed in the following table. If you cut and paste an XML example from this or other Docupresentment documentation into an XML configuration file, you will have to manually make these substitutions.

For this character

(less than)

(greater than)

& (ampersand)

' (apostrophe)

“ (quotation mark)

Use this escape sequence

The following diagram shows you how the system operates.

Chapter 2

Using the Internet Document Server

Distributed Clients

World Wide

Web Client

Intranet Client

Web Server

World Wide

Web Client

Front-end components talk to IDS via the DSI API.

These components provide communications and an interface which gather client requests, translate those requests for IDS, and then translate the results for the client’s use.

Local or

Batch Client

Front-End (Client) Components

Custom Client

Module

Java-based Custom

Client Module

Java Server Pages

(JSP) Custom Client

Module

ActiveX-based

Custom Client

Module (Windows)

Active Server Pages

(ASP) Custom Client

Module (Windows)

Internet

Document

Server

DSI API

Document Processing Server

Back-end components include the bridges to other applications, rules which process the data, the data or archives being processed, and document sets. These components communicate with

IDS

via the DSI API.

DSI API

Bridges

Back-End Components

Processing Rules

Data, Document

Sets or Archives

Overview

REATING

RONT

-E

ND

OLUTIONS

You can use either JSP (Java server pages) or ASP (active server page) to create front-end solutions, as shown in the previous illustration.

OTE

Keep in mind ASP is a Microsoft product and is not available on Solaris.

Internet Document

Server

ASP

Internet Information

Server (IIS)

Internet Document

Server

JSP

JSP-enabled application server (such as Tomcat or WebSphere)

SING

JSP

With JSP, the HTML content is included in the JSP page. There is no separate template.

To help you more quickly create your front end solutions, we provide the DSI JavaBean to communicate with Internet Document Server. This bean is in IDSJSP.jar.

Browser

Browser Browser

Application server with JSP support (such as Tomcat, WebLogic, or WebSphere)

JSP

AddRequest ClearRequest ProcessRequest

The DSI JavaBean

(IDSJSP.jar)

Internet Document Server

Chapter 2

Using the Internet Document Server

SING THE

IDSJSP J

AVA

EAN

As shown in this illustration, the IDSJSP bean collects requests and results. The bean has the following properties and methods.

Properties

Property

waittime timeout

Description

The time in between tries for ProcessRequests.

The total time to wait for the ProcessRequest.

Methods

Method

AddRequest

AddAllRequest

ProcessRequest

GetResult

ClearRequest

ClearResult

Description

AddRequest(Object key, Object value)

Adds name/value fields to the record to send to the IDS rule.

AddAllRequest(javax.servlet.ServletResponse request)

Adds all name/value fields from the request objects to the records to send to the IDS rule.

ProcessRequest()

Sends all the name/value and request types to IDS rules. Processes the

IDS rule and gets return records from the IDS rule and returns them as type HashMap.

GetResult(Object key)

Gets the return record value from the IDS rule index using the key from the internal result.

ClearRequest()

Clears attachment variables out of the request. Use after ProcessRequest and before the next set of AddRequest calls.

ClearResult()

Clears the result.

Using ASP

With ASP, the HTML page is included with the ASP page. There is no separate template.

Furthermore, the processing is done in each ASP page instead of in DCLTW32.EXE. On the other hand, ASP also requires more coding effort.

To help you more quickly create your front end solutions, we created IDSASP

(IDSASP.DLL).

Internet Document

Server

IDSASP ASP

Internet

Information Server

(IIS)

Overview

With IDSASP, you can use the ASP Session Collector and ProcessQ or you can bypass the Session Collector using ProcessRQ, as shown in the following illustration.

Browser

Browser Browser

Internet Information Server (IIS)

ASP

Session Collector

AddReq ClearReq ClearRes

Request

Collection

Result

Collection

The IDSASP Object

(IDSASP.DLL)

ProcessQ ProcessRQ

Call AddToQueue/GetQueueRec

Internet Document Server

SING THE

IDSASP O

BJECT

As shown in this illustration, the IDSASP object collects requests and results. To communicate with IDS using ASP through DSIAPI, the system includes an ActiveX

DSO named

IDSASP.DLL. This DSO has the following properties and methods.

Properties

Property

hInstance oDSI

Request

Result

Description

Type: Long

DSI Instance Handle is created by InitSession() in IDSASP.

Type: DSICoAPI

DSI Handle.

Type: Collection

Request Collection in IDSASP.

Type: Collection

Result Collection in IDSASP.

Chapter 2

Using the Internet Document Server

Property

ShowAtt

WaitTime

TimeOut

Description

Type: Boolean

When set to True, the system prints the request and result when you call the

ProcessQ or ProcessRq method. Use this property for debugging.

Type: Long

Retry time in the processing queue. The default is 1000 milliseconds.

Type: Long

Time-out in milliseconds. The default is 15000 milliseconds.

Methods

Method

AddReq

Description

Syntax: AddReq (ByVal Name As String, ByVal Value As String)

Call this method to add a request to IDSASP request collection.

ClearReq

ClearRes

Syntax: ClearReq()

Call this method to clear the IDSASP request collection.

Syntax: ClearRes()

Call this method to clear the IDSASP result collection.

Called by ASP when the object is instantiated.

OnEndPage

OnStartPage Called by ASP when the object is released.

ProcessQ Syntax: ProcessQ()

Call this method to...

- Retrieve the name/value pair from the ASP session collection and add it to the queue.

- Release the record into the queue for IDS to process.

- Read back the result from IDS. Retry time and time-out are defined in the

WaitTime and TimeOut properties.

- Store the results in the ASP session collection.

ProcessRq Syntax: ProcessRq()

Call this method to...

- Retrieve the name/value pair from the IDSASP request collection and add it to the queue.

- Release the record into the queue for IDS to process.

- Read back the result from IDS. Retry time and time-out are defined in the

WaitTime and TimeOut properties.

- Store the results in the IDSASP result collection.

ReadBinFile Syntax: ReadBinFile(ByVal bFileName As String)

Call this method to read the binary file from the local hard disk and store as a binary array.

Overview

Using the ProcessQ method

Using the ProcessRq method

Sending and Receiving Attachment Fields

The IDSASP.DLL provides two ways to send and receive attachment fields to and from

DSIAPI: using the ProcessQ method and using the ProcessRq method.

Here is an example of using session collection with the ProcessQ method:

CrLf = Chr(13) + Chr(10) set DSI = Server.CreateObject("IDSASP.DSI")'create DSI handle session.Abandon

'Clear Session for i=1 to Request.Form.Count'Read Attachment and Create session

Collection session(Request.Form.Key(i))=Request.Form(i) next

DSI.ProcessQ

'Execute Request From Attachment

'Loop To display all of the records.

For i=1 to session("RECORDS")

alink = "recips.asp"

alink = alink & "?USERID=" &

Server.URLEncode(session("USERID"))

alink = alink & "&ArcKey=" & Server.URLEncode(session("RECORDS"

& cstr(i) & ".ArcKey"))

alink = alink & "&REQTYPE=RCP"

alink = alink & "&CONFIG=" &

Server.URLEncode(session("CONFIG"))

alink = alink & "&COMPANY=" &

Server.URLEncode(session("RECORDS" & i & ".Company"))

alink = alink & "&LOB=" & Server.URLEncode(session("RECORDS" & cstr(i) & ".Lob"))

alink = alink & "&POLICYNUM=" &

Server.URLEncode(session("RECORDS" & cstr(i) & ".PolicyNum"))

alink = alink & "&RUNDATE=" &

Server.URLEncode(session("RECORDS" & cstr(i) & ".RunDate"))

Response.Write "<TR><TD><B>"

Response.Write "<A HREF=" & alink & ">" & session("RECORDS" & i & ".Company") & "</A></TD>"

Response.Write "<TD>" & session("RECORDS" & cstr(i) & ".Lob")

& "</TD>"

Response.Write "<TD>" & session("RECORDS" & cstr(i) &

".PolicyNum") & "</TD>"

Response.Write "<TD>" & session("RECORDS" & cstr(i) &

".RunDate") & "</TD>"

Response.Write "</TR>" & CrLf next

Here is an example of using the IDSASP.DLL request and result collection properties with the ProcessRq method.

CrLf = Chr(13) + Chr(10) set DSI = Server.CreateObject("IDSASP.DSI")'create DSI handle

'Read Input Parameter from INPUT FORM and send request to DSI

Chapter 2

Using the Internet Document Server

Sample Pages

Page 1 for i=1 to Request.Form.Count

DSI.AddReq Request.Form.Key(i),Request.Form(i) next

DSI.ProcessRq

'Execute Request

'Loop display Response Pair for i=1 to DSI.Result("RECORDS").Value

alink = "recips.asp"

alink = alink & "?USERID=" &

Server.URLEncode(DSI.Result("USERID").value)

alink = alink & "&ArcKey=" &

Server.URLEncode(DSI.Result.Item("RECORDS" & cstr(i) &

".ArcKey").value)

alink = alink & "&REQTYPE=RCP"

alink = alink & "&CONFIG=" &

Server.URLEncode(DSI.Result("CONFIG").value)

alink = alink & "&COMPANY=" &

Server.URLEncode(DSI.Result("RECORDS" & i & ".Company").value)

alink = alink & "&LOB=" &

Server.URLEncode(DSI.Result.Item("RECORDS" & cstr(i) &

".Lob").value)

alink = alink & "&POLICYNUM=" &

Server.URLEncode(DSI.Result.Item("RECORDS" & cstr(i) &

".PolicyNum").value)

alink = alink & "&RUNDATE=" &

Server.URLEncode(DSI.Result.Item("RECORDS" & cstr(i) &

".RunDate").value)

Response.Write "<TR><TD><B>"

Response.Write "<A HREF=" & alink & ">" & DSI.Result("RECORDS"

& i & ".Company").value & "</A></TD>"

Response.Write "<TD>" & DSI.Result.Item("RECORDS" & cstr(i) &

".Lob").value & "</TD>"

Response.Write "<TD>" & DSI.Result.Item("RECORDS" & cstr(i) &

".PolicyNum").value & "</TD>"

Mh=Left(DSI.Result.Item("RECORDS" & cstr(i) &

".RunDate").value,2)

Dt=Mid(DSI.Result.Item("RECORDS" & cstr(i) &

".RunDate").value,3,2)

Yr=Right(DSI.Result.Item("RECORDS" & cstr(i) &

".RunDate").value,2)

Dat=Cdate(Mh & "/" & Dt & "/" & Yr)

Response.Write "<TD>" & FormatDateTime(Dat,1) & "</TD>"

Response.Write "</TR>" & CrLf next

Here are some sample pages:

This page sends a request from the browser with two file attachments.

Overview

<table>

Page 2

This page receives an HTTP request from page 1, parses the request, and uploads the files.

'create an instance of the object which calls parseData

set o = server.CreateObject("IDSASP.DSI")

'o.bDebug = true

o.parseData()

'write the element count in the request collection

response.write "count=" & o.request.count & "<BR><BR>"

'indicate if the request is a multipart request

response.write "Multipart=" & o.bMultipart & "<BR>"

'taverse through the request collection and write the name / value pairs

for i = 1 to o.request.count

name = o.request.Item(i).Name

value = o.getRequest(name)

response.write "(" & name & ") = (" & value & ")<br>"

'if the request is a multipart request, then process the attachments

if o.bMultipart = true then

for each attachment in o.attachments

if IsObject(attachment) then

name = attachment.name

response.write "attachment name=" &name & "<BR>"

file = attachment.file

response.write "file name=" & file & "<BR>"

ftype = attachment.ftype

response.write "file type=" & ftype & "<BR>"

encoding = attachment.encoding

response.write "encoding=" & encoding & "<BR>"

buffer = attachment.buffer

response.write "buffer length=" & Len(buffer) & "<BR>"

'write attachment to disk

path = o.upLoad(name, "c:\inetpub")

Showing a PDF File

ASP provides two ways to show a PDF file: using the Response.Redirect method and using the Read ReadBinFile method.

Chapter 2

Using the Internet Document Server

Using the

Response.Redirect

method

Here is an example of showing a PDF file using the Response.Redirect method. You must enter a URL.

<%@ Language=VBScript %>

Set DSI = Server.CreateObject("IDSASP.DSI")'create DSI handle session.Abandon

'Clear Session

For i=1 to Request.Form.Count'Read Attachment and Create session

Collection

Next session(Request.Form.Key(i))=Request.Form(i)

DSI.ProcessQ

'Execute Request From Attachment

HostAddr=Request.ServerVariables("HTTP_HOST")'Get Host Name

PrintFile=session("REMOTEPRINTFILE")'Get Full Printed Filename with Path

StartPoint=instr(1,PrintFile,"\")'Look for \ sign

NameWidth=len(PrintFile)-StartPoint'Filename Length

FileName=Mid(PrintFile,StartPoint+1,NameWidth)'Get Filename

Url="http://" & HostAddr & "/doc-html/" & Filename'Construct

URL

Set DSI = nothing then

If instr(1,Request.ServerVariables("HTTP_USER_AGENT"),"IE")<>0

'Check IE Browser

<HTML>

</BODY>

</HTML>

Else

Response.Redirect Url

End If

Overview

Using the Read

ReadBinFile method

Here is an example of showing a PDF file using the Read ReadBinFile method in the

IDSASP.DLL file, you must enter the local path.

<%@ Language=VBScript %>

Dim Stream set DSI = Server.CreateObject("IDSASP.DSI")'create DSI handle

'Attach Input Parameter from INPUT FORM for i=1 to Request.Form.Count

DSI.AddReq Request.Form.Key(i),Request.Form(i)

DSI.ProcessRq

'Send Queue to DSI

Response.Buffer=True

Pth=Request.ServerVariables("PATH_TRANSLATED")

DsiPath=left(pth,instr(4,pth,"\"))'Get Path of Docserv

PrintFile=DsiPath & DSI.Result("REMOTEPRINTFILE").Value

Response.ContentType = "application/pdf"

Stream = DSI.ReadBinFile(PrintFile)

Response.BinaryWrite(Stream)

Response.End

%> set DSI = nothing

Chapter 2

Using the Internet Document Server parseData

Parameters

Returns

Using the HTTP Parsing and Uploading APIs

The following APIs in IDSASP let you parse HTTP requests into separate request and attachments collections and provide a way to process multipart/form-data form requests.

• parseData

• getRequest

• getAttachment

• getBuffer

• upLoad

Multiple file attachments are parsed into attachments collections in IDSASP. Files can then be uploaded (written to disk) to the web server via the upLoad API.

Attachment objects can also be retrieved from the attachments collection via the getAttachment API. Attachment objects contain properties for each attachment as well as an attachment buffer that contains the actual file attachment contents.

You can also retrieve file attachment contents as buffers from the attachments collection via the getBuffer API. The parseData API can also parse non multipart/form-data HTTP requests. Use the getRequest API to retrieve name/value pairs from the request collection.

In addition, you can also see Sample Pages on page 21 .

Use this API to parse HTTP requests into separate request and attachments collections.

Regular name/value pairs in an HTTP request are parsed into request collection. File attachments are parsed into an attachments collection. The parseData API can parse multipart/form-data HTTP requests as well as non multipart/form-data requests. Call this API at the beginning of an ASP script to parse the HTTP request from a submitted form.

None

Nothing getRequest

Use this API to retrieve name/value pairs from the request collection instead of the

Request.Form API calls.

Parameters

Returns

Parameter Description

name A string value that represents the name of a key in the request collection.

A string value with the value in request collection for key name.

Overview getAttachment

Use this API to return an attachment object from the attachments collection. This API retrieves not only the file attachment contents, but also its properties. The attachment object returned contains these properties:

Property

name

File

Ftype

Buffer

Encoding

Description

This is the actual name of the attachment in the HTTP request. Its value corresponds to the value of the file form tag used to submit the attachment in the

HTTP request.

A string value that contains the file name and extension of the attachment. Its value corresponds to the file name of the File form tag used to submit the attachment.

A string value that contains the extension (file type) of the attachment.

A string buffer holding the file attachment contents.

The actual encoding type used by the browser when the file attachment was submitted.

Parameters

Returns

Parameter Description

name A string value that represents the name of a key in the attachments collection.

An attachment object containing the file attachment contents as well as properties for the attachment.

getBuffer

Use this API to retrieve attachments as buffers.

Parameters

Parameter Description

name A string value that represents the name of the attachment in the Attachment object within the attachments collection. This value should be the same as that of the file form tag name used to send an attachment in an HTTP request.

Returns

A string buffer containing the contents of the file attachment in the attachments collection.

Chapter 2

Using the Internet Document Server upLoad

Use this API to write an attachment object's buffer contents from the attachments collection to disk. This API lets you upload file attachments to disk on the web server.

Parameters

Parameter Description

name A string value that represents the name of the attachment in the attachment object within the attachments collection. This name is the same as the file form tag used to send the attachment from the browser in an HTTP request.

Path A string value that specifies the full path where you want the attachment written.

Returns

The full path and file name of the file uploaded, if successful.

Sample Pages

Page 1

Here are some sample pages:

This page sends a request from the browser with two file attachments.

<table>

Overview

Page 2

This page receives an HTTP request from page 1, parses the request, and uploads the files.

'create an instance of the object which calls parseData

set o = server.CreateObject("IDSASP.DSI")

'o.bDebug = true

o.parseData()

'write the element count in the request collection

response.write "count=" & o.request.count & "<BR><BR>"

'indicate if the request is a multipart request

response.write "Multipart=" & o.bMultipart & "<BR>"

'taverse through the request collection and write the name / value pairs

for i = 1 to o.request.count

name = o.request.Item(i).Name

value = o.getRequest(name)

response.write "(" & name & ") = (" & value & ")<br>"

'if the request is a multipart request, then process the attachments

if o.bMultipart = true then

for each attachment in o.attachments

if IsObject(attachment) then

name = attachment.name

response.write "attachment name=" &name & "<BR>"

file = attachment.file

response.write "file name=" & file & "<BR>"

ftype = attachment.ftype

response.write "file type=" & ftype & "<BR>"

encoding = attachment.encoding

response.write "encoding=" & encoding & "<BR>"

buffer = attachment.buffer

response.write "buffer length=" & Len(buffer) & "<BR>"

'write attachment to disk

path = o.upLoad(name, "c:\inetpub")

Chapter 2

Using the Internet Document Server

26 addSessionVar

Using the XMLSession Rules

Use the XMLSession rules to save state information across multiple IDS servers and across multiple web servers. Session information for each client session is saved as an

XML file on the server side. This also increases security as session information no longer resides on the web server.

You can store, retrieve, and save files using the XMLSession rules. You can retrieve the session information as rowset on the client side and it is also accessible using session methods available in IDSASP and IDSJSP.

For more information about these methods and rules, see

• IDSASP Methods on page 29

• IDSJSP Methods on page 31

• XMLSession Rules on page 33

IDSASP Methods

Here are the IDSASP methods:

Use this method to add a name/value pair to the session collection. You can include these parameters:

Parameter Description

name The name of the name/value pair to add to the session.

Value The value of the name/value pair to add to the session.

getSessionVar

Here is an example: dsi.addSessionVar "USERID", "FORMAKER"

Use this method to return a string containing the value of name in the session collection.

You can include these parameters:

Parameter Description

name The name of the name/value pair to retrieve from the session.

removeSessionVar

Here is an example: userid = dsi.getSessionVar("USERID")

Use this method to remove a name/value pair from the session collection. You can include these parameters:

Parameter Description

name The name of the name/value pair to remove from the session.

Here is an example:

Overview addSessionObject dsi.removeSessionVar "USERID"

Use this method to add a binary or text buffer to hold the contents for a file to the session collection. You can include these parameters:

Parameter Description

name The name of the object name to add to the session.

Buffer A binary or text buffer holding the contents of a file to add to the session.

getSessionObject

Here is an example: dsi.addSessionObject "FILE1", buffer

Use this method to retrieve a buffer that holds the contents of a file from the session collection. You can include these parameters:

Parameter Description

name The name of the object to retrieve from the session.

Opt An integer value that indicates whether the object should be retrieved as a binary or text buffer (1=text, 2=binary) removeSessionObject

Here is an example: buffer = dsi.getSessionObject("FILE1", 1) binBuf = dsi.getSessionObject("FILE2", 2)

Use this method to remove an object from the session collection. You can include these parameters:

Parameter Description

name The name of the object to remove from the session.

Here is an example: dsi.removeSessionObject "FILE1"

Chapter 2

Using the Internet Document Server addSessionVar

IDSJSP Methods

Here are the IDSJSP methods:

Use this method to add a name/value pair to the session map. You can include these parameters:

Parameter Description

name Enter a string that contains the name of the name/value pair to add to the session map.

Value Enter a string that contains the value of the name/value pair to add to the session map.

removeSessionVar

This method has no return value. Here is an example: dsimsg.addSessionVar("USERID", "FORMAKER");

Use this method to remove a name/value pair from the session map. You can include these parameters:

Parameter Description

name Enter a string that contains the name of the name/value pair to remove from the session map.

getSessionVar

This method has no return value. Here is an example: dsimsg.removeSessionVar("USERID");

Use this method to retrieve a name/value pair from the session map. You can include these parameters:

Parameter Description

name Enter a string that contains the name of the name/value pair to retrieve from the session map.

This method returns a string containing the value of the name/value pair in the session map. Here is an example:

String userid = dsimsg.getSessionVar("USERID");

Overview addSessionObject

Use this method to add a file buffer to the to the session map. You can include these parameters:

Parameter Description

name Enter a string that contains the name of the file buffer to add to the session map.

Buffer A byte array holding the contents of a file.

removeSessionObject

This method has no return value. Here is an example: dsimsg.addSessionObject("FILE1", buffer1);

Use this method to remove a file buffer from the session map. You can include these parameters:

Parameter Description

name Enter a string that contains the name of the file buffer to remove from the session map.

getSessionObject

This method has no return value. Here is an example:

dsimsg.removeSessionObject("FILE1");

Use this method to retrieve a file buffer from the session map. You can include these parameters:

Parameter Description

name Enter a string that contains the name of the file buffer to retrieve from the session map.

This method returns a byte[] array containing the buffer retrieved from the session map.

Here is an example: byte[] buff = dsimsg.getSessionObject("FILE1");

Chapter 2

Using the Internet Document Server initSession

XMLSession Rules

Here are the XMLSession rules:

Use this rule to initialize a session. This rule generates a unique session ID and generates a session file with unique ID. If a SESSION rowset is present in the request, the rule also adds the rowset to the session file. If the SESSION rowset is missing in the request, a blank unique session rowset is generated and added to the session file.

The SESSION rowset is returned in the result.

Input variables

Variable

XMLSESSION

Description

(Optional) This variable contains a unique identifier for the session. If present, it is used to generate a new session. Otherwise, the rule generates a unique identifier for the new session.

XMLSESSIONTIMEOUT (Optional) Specifies the session timeout in seconds. The default is

1800 seconds.

Use this INI option to specify a global share for multiple IDS processes:

< GlobalData >

Path =

Output variables

Variable

XMLSESSION

RESULTS

Description

This variable contains the unique identifier for the session if the session is valid. Otherwise, the value will be

INVALID.

Success or failure termSession

Use this rule to terminate a session. This rule removes the session file associated with the unique ID.

Input variables

Variable

XMLSESSION

Description

This variable contains the unique ID for the session to be removed.

Use this INI option to specify a global share for multiple IDS processes:

< GlobalData >

Path =

Overview

Output variables

Variable

XMLSESSION

RESULTS

Description

This variable contains the unique identifier for the session. This attachment variable contains

REMOVED if the session was terminated successfully. Otherwise, the value will be

INVALID.

Success or failure updateSession

Use this rule to update the unique session file with the SESSION rowset in the request message and return the updated rowset in the result.

Input variables

Variable

XMLSESSION

Description

This variable contains the unique ID for the session to be updated.

XMLSESSIONTIMEOUT (Optional) Specifies the session timeout in seconds.The default is

1800 seconds.

Use this INI option to specify a global share for multiple IDS processes:

< GlobalData >

Path =

Output variables

Variable Description

XMLSESSION This variable contains the unique identifier for the session if the session is valid. Otherwise, the value will be

EXPIRED if the session has expired, or

INVALID if the session is no longer valid.

RESULTS Success or failure purgeXMLSessions

Use this rule to remove expired sessions.

Input variables

None. Use this INI option to specify a global share for multiple IDS processes:

< GlobalData >

Path =

Output variables

Variable

RESULTS

Description

Success or failure.

Chapter 2

Using the Internet Document Server saveFile

Use this rule to save the contents of an XML node from a session file as a new file to disk and to add an attachment variable to the result message with the full path and file name of the file saved.

Input variables

Variable

XMLSESSION

Description

This variable contains the unique identifier for the session.

INPUTVAR

OUTPUTVAR

PRINTPATH

FILETYPE

The name of the SESSION rowset variable containing the data that is to be saved to disk.

The name of the attachment variable to add to the output message indicating the full path and file name of the file saved.

(Optional) Specifies the output path for the output file. If omitted, the output file is written to the current IDS directory.

(Optional) Specifies the file type for the output file. If omitted, the default extension DAT is used.

Use this INI option to specify a global share for multiple IDS processes:

< GlobalData >

Path =

Output variables

Variable

(variable)

Description

An attachment variable whose name is specified by OUTPUTVAR input attachment variable - will hold a String value indicating the full path and file name of the file saved to disk.

XMLSESSION This variable contains the unique identifier for the session if the session is valid. Otherwise, the value will be will be

EXPIRED if the session has expired, or

INVALID if the session is no longer valid.

RESULTS Success or failure

Overview

SING

IDSXML

You can use IDSXML as a guide to processing the errors.xml file in a Microsoft ASP environment.

OTE

IDSXML is not a COM+ component so do not register it under the Component

Services Microsoft Management Console snap-in. The component should only be registered under the current IDS directory on the IDS client (the web server).

Keep in mind IDSXML requires Microsoft XML parser 4.0 (MSXML 4.0). Please make sure you have this before you use IDSXML.

Properties

IDSXML is a Win32 COM component. IDSXML provides XML parsing and XSL processing APIs for ASP. Here is a description of the properties and APIs provided by this component:

This table shows you the properties:

Name

Formset

FormsetSelectionList

Type Description

collection A collection of form objects string A comma-delimited string of options selected from a form set. These values are expected:

- form

- form.copycount.recipient

- form.image

- form.image.copycount. recipient

See also

XMLProcessFormset

XMLUpdateFormset

Methods

Here is an example:

DEC PAGE,DEC PAGE.1.AGENT,DEC PAGE.1.COMPANY,

DEC PAGE.1.INSURED,DEC PAGE.q1snam,DEC PAGE.q1mdc1,DEC

PAGE.q1mdc2,DEC PAGE.q1mdc3, DEC PAGE.q1mdc3.1.INSURED

IDSXML includes these methods:

• XMLTransformErrors on page 37

• XMLTransformErrors2 on page 38

• XMLLoadINI on page 39

• XMLLoadXML on page 40

• XMLLoadXSL on page 40

• XMLGetGroupOptionValue on page 41

• XMLGetValue on page 41

• XMLGetGroup on page 41

• XMLUpdateGroup on page 42

Chapter 2

Using the Internet Document Server

Syntax

• XMLBuffer on page 44

• XMLLoadProcessor on page 44

• XMLAddParameterToXSL on page 44

• XMLTransformWithXSL on page 45

• XMLProcessWithXSL on page 46

• XMLUpdateFormset on page 47

• XMLProcessFormset on page 47

XMLTransformErrors

Use this method to transform a result message into useful HTML output. This method takes an XML buffer from a result message that contains errors, an errors XML file that contains error descriptions, and an XSL template which is used to transform the XML message into HTML output that describes errors returned by IDS.

XMLTransformErrors xmlbuf, xmlFile, xslFile

Parameter Description

xmlBuf Enter the name of the XML buffer that contains the message returned by IDS.

This message contains errors returned by IDS.

xmlFile Enter the name of the errors file that contains all error codes recognized by IDS.

This file is produced by IDS and contains additional information, causes, and resolutions for each error.

The errors file is used by this method to transform the message returned by IDS into useful HTML output. This is a file that ships with IDS (errors.xml).

xslFile Enter the name of the XSL template you want the method to use to transform the XML buffer and errors XML file into HTML information about errors returned by IDS.

This is a template that ships with IDS (errors.xsl).

Example

In this example, page one detects an error, captures the buffer that contains the error, and redirects to the error processing page, which is page 2.

Page1: processRequest.asp

<% set DSI = server.CreateObject("IDSASP.DSI")

For i=1 to Request.Form.Count

DSI.AddReq Request.Form.Key(i), Request.Form(i)

On Error Resume Next

DSI.ProcessRq

If Err.Number <> 0 Then

Err.Clear

Overview

End if path = Request.ServerVariables("APPL_PHYSICAL_PATH") results = DSI.Result("RESULTS").Value

errors = DSI.Result("ERRORS").Value

If Len(results) = 0 OR results <> "SUCCESS" OR CInt(errors) > 0 then

Session("xmlbuf") = DSI.GetSOAPMessage

set dsi = nothing

Response.Redirect "error.asp"

End if

Set DSI = Nothing

Page2: error.asp

<% set o = Server.CreateObject("IDSXML.XML") xmlbuf = Session("xmlbuf") xmlFile = Server.MapPath("xml\errors.xml") xslFile = Server.MapPath("xsl\errors.xsl")

Syntax

Example o.XMLTransformErrors xmlbuf, xmlFile, xslFile

XMLTransformErrors2

Use this method to transform a result message into useful HTML output. This method takes as input an XML buffer from a result message from IDS that contains errors and an

XSL template which is used to transform the XML message into HTML output that describes the errors returned.

XMLTransformErrors2 xmlbuf, xslfile

Parameter

xmlBuf xslFile

Description

Enter the name of the XML buffer that contains the message returned by IDS.

This message contains errors returned by IDS.

Enter the name of the XSL template you want the method to use to transform the XML buffer into HTML information that contains the errors returned by

IDS.

This is a template that ships with IDS (default.xsl).

In this example, page one detects an error, captures the buffer that contains the error, and redirects to the error processing page, which is page 2.

Page1: processRequest.asp

Chapter 2

Using the Internet Document Server

<% set DSI = server.CreateObject("IDSASP.DSI")

For i=1 to Request.Form.Count

DSI.AddReq Request.Form.Key(i), Request.Form(i)

On Error Resume Next

DSI.ProcessRq

If Err.Number <> 0 Then

Err.Clear

End if path = Request.ServerVariables("APPL_PHYSICAL_PATH") results = DSI.Result("RESULTS").Value

errors = DSI.Result("ERRORS").Value

If Len(results) = 0 OR results <> "SUCCESS" OR CInt(errors) > 0 then

Session("xmlbuf") = DSI.GetSOAPMessage

set dsi = nothing

Response.Redirect "error.asp"

End if

Syntax

Set DSI = Nothing

Page2: error.asp

<% set o = Server.CreateObject("IDSXML.XML") xmlbuf = Session("xmlbuf") xslFile = Server.MapPath("xsl\default.xsl") o.XMLTransformErrors2 xmlbuf, xslFile

XMLLoadINI

Use this method to load an XML INI file into memory. Use this method before calling other methods that retrieve information from an XML document.

XMLLoadINI sIni

Parameter Description

sINI Enter the full path and file name of the XML document you want to load. This can also be a buffer that contains an XML document.

Overview

Example

Syntax

Here is an example of the format of the XML document:

<QUEUEMANAGER>QALAB1</QUEUEMANAGER>

<REQUESTQ>REQUESTQ</REQUESTQ>

<RESULTQ>RESULTQ</RESULTQ>

</GROUP>

</GROUP>

</policy>

</GROUP>

</GROUPS>

Here is an example: set o = Server.CreateObject("IDSXML.XML") sIni = Server.MapPath("ini.xml") o.XMLLoadIni(sIni)

XMLLoadXML

Use this method to load an XML document into memory before an XSL transformation occurs.

XMLLoadXML sXML

Parameter Description

sXML Enter the full path and file name of the XML document you want to load. This can also be a buffer that contains an XML document.

Example

Syntax

Here is an example: sXML = Server.MapPath("xml\test.xml") o.XMLLoadXML(sXML)

XMLLoadXSL

Use this method to load an XSL template into memory before an XSL transformation occurs.

XMLLoadXSL sXSL

Chapter 2

Using the Internet Document Server

Example

Syntax

Parameter

sXSL

Description

Enter the full path and file name of the XSL template you want to load. This can also be a buffer that contains an XSL template.

Here is an example: sXSL = Server.MapPath("xsl\test.xsl") o.XMLLoadXSL(sXSL)

XMLGetGroupOptionValue

Use this method to return a value from an XML node. Use the XMLLoadINI method before you use this method.

XMLGetGroupOptionValue sGroup, sOption

Parameter Description

sGroup Enter the group name to use for retrieving a value.

sOption Enter the option name to use for retrieving a value.

Example

Syntax

Example

Here is an example: set o = Server.CreateObject("IDSXML.XML") sIni = Server.MapPath("ini.xml") o.XMLLoadINI(sIni) val = o.XMLGetGroupOptionValue("MQSERIES", "CLIENT") set o = nothing

XMLGetValue

Use this method to return a value from a node in an XML tree using xPath. Use the

XMLLoadINI method before you use this method.

XMLGetValue xPath

Parameter Description

xPath Enter a fully qualified xPath value to the node in the XML document tree.

Here is an example: set o = Server.CreateObject("IDSXML.XML") sIni = Server.MapPath("ini.xml") o.XMLLoadINI(sIni) val=o.XMLGetValue("//GROUP[@NAME='TEST']/policy/num") set o = nothing

Overview

Syntax

Example

XMLGetGroup

Use this method to return an INI group as a buffer, as an object, or as a new file. Use the

XMLLoadINI method before you use this method.

XMLGetGroup sGroup, iOption, sDir

Parameter Description

sGroup Enter the name of the INI group you want returned. iOption sDir

Choose one of these options:

1 - Return the INI group as a buffer.

2 - Return the INI group as an object.

3 - Save the INI group as a new file.

Only include this parameter if you entered three (3) for the iOption parameter.

Enter the name of the directory in which you want the system to save the new

XML file.

Here is an example:

<% set o = server.createobject("IDSXML.XML") sIni = Server.MapPath("ini.xml") o.XMLLoadINI(sIni)

'return MQSeries group as buffer

Buffer = o.XMLGetGroup("MQSERIES", 1, "")

'return MQSeries group as object

Set MQSeriesGroup = o.XMLGetGroup("MQSERIES", 2, "")

'traverse through the group object and print all pairs

For i = 1 to MQSeriesGroup.Count

name = MQSeriesGroup(i).name

value = MQSeriesGroup(i).Value

response.write name & "=" & value & "<BR>"

'access a particular value val = MQSeriesGroup("CLIENT").Value

'write the MQSeries group as a new file into cache directory o.XMLGetGroup "MQSERIES", 3, "Cache"

'cleanup set MQSeriesGroup = nothing set o = nothing

Chapter 2

Using the Internet Document Server

Syntax

XMLUpdateGroup

Use this method to update a group in an XML document via a Group Object parameter.

This method reads the group object's properties and updates the XML document's matching group with the object's properties. The method then returns the updated XML document as a buffer or saves it to disk. Use the XMLLoadINI method before you use this method.

XMLUpdateGroup sGroup, oGroup, iOption, sOut

Parameter Description

sGroup Enter the name of the group you want to update.

oGroup iOption sOut

Enter the name of the group object you want to use to update a matching group in an XML document.

Choose one of these options to indicate what you want done with the updated file:

1 - Return the updated XML INI file as a buffer.

2 - Save the updated XML INI file as a file.

3 - Return only the updated group as a buffer.

4 - Save only the updated group as a file.

Only use this parameter if the iOption parameter is set to two (2) or four (4).

Enter the full path and file name for saving the XML document.

Example

Here is an example:

Set o = Server.CreateObject("IDSXML.XML") sIni = Server.MapPath("ini.xml") o.XMLLoadINI(sIni)

Set PrtOpt = o.XMLGetGroup("PRINTOPTIONS", 2, "")

PrtOpt("ALLRECIPIENTS").Value = "YES"

PrtOpt("PRTDOWNLOADFONTS").Value = "YES"

PrtOpt("PRTTYPE").Value = "XML"

PrtOpt("PRTSENDCOLOR").Value = "NO"

PrtOpt("PRTPAGENUMBERS").Value = "NO"

PrtOpt("PRTPRINTVIEWONLY").Value = "NO"

PrtOpt("PRTTEMPLATEFIELDS").Value = "YES"

'update the xml ini file and return the updated file as a buffer

Buffer = o.XMLUpdateGroup("PRINTOPTIONS", PrtOpt, 1, "")

'update the xml ini file and save it to disk o.XMLUpdateGroup "PRINTOPTIONS", PrtOpt, 2, "POpt.xml"

'update the group and return the updated group as a buffer

Buffer2 = o.XMLUpdateGroup ("PRINTOPTIONS", PrtOpt, 3, "")

'update the group and save the updated group as a new file o.XMLUpdateGroup "PRINTOPTIONS", PrtOpt, 4, "newPOpt.xml"

Overview

Syntax

Example

'cleanup

Set PrtOpt = Nothing

Set o = Nothing

XMLBuffer

Use this method to return a buffer for an XML document. Use XMLLoadINI method before you use this method.

XMLBuffer sFile

Parameter Description

sFile Enter the full path and file name of the XML document.

Here is an example:

<% set o = Server.CreateObject("IDSXML.XML")

InputFormset = Server.MapPath("xml\OriginalFormset.xml")

Buffer = o.XMLBuffer(InputFormset)

Response.write Buffer set o = nothing

Syntax

Example

XMLLoadProcessor

Use this method to l oad an XSL template into memory and to load the XSL processor based on that template. Use this method before you call the XMLAddParameterToXSL or

XMLProcessWithXSL methods.

XMLLoadProcessor sXSL

Parameter Description

sXSL Enter the full path and file name to an XSL template or a buffer that contains an

XSL template.

Here is an example: set o = server.createobject("IDSXML.XML") template = Server.MapPath("xsl\test.xsl") o.XMLLoadProcessor(template)

Chapter 2

Using the Internet Document Server

Syntax

Example

XMLAddParameterToXSL

Use this method to add a parameter to internal XSL processor. For instance, you can use this method to add parameters before processing with an XSL template that expects parameters. Use the XMLLoadProcessor method before you call this method.

XMLAddParameter2XL name, value

Parameter Description

name Enter the name of the parameter to add to the XSL template.

value Enter the value of the parameter to add to the XSL template.

Here is an example:

Syntax set o = Server.Createobject("IDSXML.XML") sXML = Server.MapPath("xml\test.xml") sXSL = Server.MapPath("xsl\test.xsl") o.XMLLoadXML(sXML) o.XMLLoadProcessor(sXSL) o.XMLAddParameterToXSL "color", "blue" o.XMLProcessWithXSL 1 , "" set o = nothing

XMLTransformWithXSL

Use this method to transform an XML document with an XSL template. Use the

XMLLoadXML and XMLLoadXSL methods before you call this method. Use this method to process XML documents with XSL templates that do not expect parameters.

XMLTransformWithXSL Option, sPath

Parameter Description

Option Choose one of these options:

1 - Return the transformation result as a string and write the result to the screen.

2 - Return the transformation result as a string.

3 - Write the transformation result to disk using the path specified by sPath parameter. This also returns the transformation result as a string.

sPath Only include this parameter if you entered three (3) for the Option parameter.

Enter the full path and file name of the file you want to use for writing the transformation result to disk.

Overview

Example

Here is an example:

Syntax

Example set o = Server.Createobject("IDSXML.XML") sXML = Server.MapPath("xml\test.xml") sXSL = Server.MapPath("xsl\test.xsl") o.XMLLoadXML(sXML) o.XMLLoadXSL(sXSL) o.XMLTransformWithXSL 1, "" set o = nothing

XMLProcessWithXSL

Use this method to transform an XML document using an XSL template that expects parameters. You should use the XMLAddParameterToXSL method to add the parameters expected by the style sheet before you call this method. Also use the

XMLLoadProcessor method before you call this method.

XMLProcessWithXSL Option, sPath

Parameter Description

Option Choose one of these options:

1 - Return the transformation result as a string and write the result to the screen.

2 - Return the transformation results as a string.

3 - Write the transformation result to disk using the path specified by sPath parameter. This also returns the transformation result as a string.

sPath If you set the Option parameter to three (3), enter the full path and file name of the file you want to use for writing the transformation result to disk.

Here is an example:

<% set o = Server.Createobject("IDSXML.XML") sXML = Server.MapPath("xml\test.xml") sXSL = Server.MapPath("xsl\test.xsl") o.XMLLoadXML(sXML) o.XMLLoadProcessor(sXSL) o.XMLAddParameterToXSL "color", "blue" o.XMLProcessWithXSL 1 , ""

Chapter 2

Using the Internet Document Server

Syntax

Example

Syntax

Example set o = nothing

XMLUpdateFormset

Use this method to update an XML form set. This method takes as input a buffer that contains an XML form set or a string that specifies the full path and file name for an

XML form set. The method uses the FormsetSelectionList property, which contains a comma-delimited string of forms, images, and recipients, to modify the form set.

This method generates a unique name for the updated form set and saves it as a new

XML document. It returns the full path and name of the new XML document.

XMLUpdateFormset sXML

Parameter Description

sXML Enter the full path and file name of an XML form set or a buffer that contains an

XML form set.

sDir Enter the name of a directory into which you want to save the updated form set.

Here is an example:

<% set o = Server.CreateObject("IDSXML.XML")

InputFormset = Server.MapPath("original.xml") o.FormsetSelectionList = "DEC PAGE,DEC PAGE.1.AGENT,DEC

PAGE.1.COMPANY,DEC PAGE.1.INSURED,DEC PAGE.q1snam,DEC

PAGE.q1mdc1,DEC PAGE.q1mdc2,DEC PAGE.q1mdc3"

OutFormset = o.XMLUpdateFormset(InputFormset, "Cache") set o = nothing

XMLProcessFormset

Use this method to process a form set. This method takes as input a buffer that contains an XML form set or a string that specifies the full path and file name of an XML form set. The method parses the XML form set and converts it into a public form set collection property. The form set collection contains form objects and each form object contains images and recipients.

XMLProcessFormset xmlBuffer

Parameter Description

xmlBuffer Enter the full path and file name of an XML form set or a buffer that contains the XML form set you want loaded and returned as a collection.

Here is an example: set o = Server.CreateObject("IDSXML.XML")

Overview

InputFormset = Server.MapPath("xml\OriginalFormset.xml")

Buffer = o.XMLBuffer(InputFormset) o.XMLProcessFormset Buffer

For i = 1 To o.Formset.Count

formName = o.Formset.Item(i).NAME

formID = Pad(formName)

html = "<input type=checkbox name=SELECTION value=" & formID & _

" onclick='FormSelect(this);'>" & formName

form = "FORM." & CStr(i)

oTree.Add "root", form, html, bExpand, "page.gif"

html = "Recipients"

FRPCS = "FRECIPIENTS" & CStr(i)

oTree.Add form, FRPCS, html, bExpand, "mydoc.gif"

For k = 1 To o.Formset.Item(i).Recipients.Count

recipientName = o.Formset.Item(i).Recipients.Item(k).NAME

recipientCnt = o.Formset.Item(i).Recipients.Item(k).CopyCount

recipientID = formID & "." & recipientCnt & "." & recipientName

html = "<input type=checkbox name=SELECTION value=" & recipientID & _

">" & recipientName

recipient = "RECIPIENT" & "." & CStr(i) & "." & CStr(k)

oTree.Add FRPCS, recipient, html, bExpand, "n.gif"

For j = 1 To o.Formset.Item(i).Images.Count

imageName = o.Formset.Item(i).Images.Item(j).NAME

imageID = formID & "." & imageName

html = "<input type=checkbox name=SELECTION value=" & imageID

& ">" & _

"<font color=blue>" & imageName & "</font>"

image = "IMAGE." & CStr(i) & "." & CStr(j)

oTree.Add form, image, html, bExpand, "help_page.gif"

For k = 1 To o.Formset.Item(i).Images.Item(j).Recipients.Count

recipientName = o.Formset.Item(i).Images.Item(j).Recipients.Item(k).NAME

recipientCnt = o.Formset.Item(i).Images.Item(j).Recipients.Item(k).CopyCount

recipientID = formID & "." & imageName & "." & recipientCnt

& "." & recipientName

html = "<input type=checkbox name=SELECTION value=" & recipientID & ">" & _

recipientName

recipient = "RECIPIENT" & "." & CStr(i) & "." & CStr(j)

& "." & CStr(k)

oTree.Add image, recipientID, html, bExpand, "n.gif"

Chapter 2

Using the Internet Document Server

SING

ULTIPLE

ERVERS

To further increase performance, you can set up multiple servers. Each server you set up helps process client requests. You can set up additional servers in a variety of ways, as this diagram shows:

IDS Server

With this server setup, a single IDS Server processes requests from the queue. Both are physically located on the same computer.

Queue

IDS Server

Queue

Computer

With this server setup, a multiple IDS Servers processes requests from the queue. Both the servers and the queue are physically located on the same computer.

Computer

IDS Server

With this server setup, a multiple IDS Servers on multiple computers process requests from the queue.

Queue

IDS Server

Computer Computer

To determine which server setup will work best for you, first determine if your transactions are CPU or I/O (input/output) intensive. Then take a look at the test results we have compiled.

Using Multiple Servers

Determining if Your Transactions are CPU or I/O Intensive

To determine if the transactions the server is processing are CPU or I/O intensive, look at the Windows Task Manager:

• If the CPU gauge shows around 100% CPU usage with no other applications running, the transactions are

CPU intensive.

• If the CPU gauge shows less than 80% CPU usage, the transactions are, most likely,

I/O intensive (this includes network I/O).

Here are some scenarios and recommendations:

Scenario

Low transaction volume. Each transaction takes a few seconds to process.

Recommended Server Setup

No changes in configuration are required. One server should be able to process all of the requests within reasonable period of time.

High transaction volume. Each transaction takes a few seconds to process.

If clients are getting the

time-out waiting for Server error message, increase the time-out value for the clients. To do this, set TimeOut INI option in the ReqType:XXX control group. You can set this option for each request type. This lets you set it to a higher value for requests which take longer to process. The default time-out for each request type is

60 seconds.

To increase total throughput, try adding a second server. Keep in mind that adding a second server does not let you process twice as many transactions. You will probably see a performance increase of around 10-20 percent.

Any volume. Each transaction takes a few

minutes to process.

Mostly I/O intensive.

You may see this scenario when the rules have to retrieve data from a mainframe computer via ODBC or DB2, or when the rules have to do a lot of file processing.*1

In this situation, try adding additional servers on the same computer as the original server.

Any volume. Each transaction takes

minutes to process. Mostly CPU intensive.

You may see this scenario if you use a lot of calculation-intensive rules. In this scenario, the best solution is to add a second server on a

separate computer. If you want to add more servers, add them on separate computers so you end up with a computer for each server.

*1 The number of ODBC connections to MVS is limited by MVS and ODBC drivers. You cannot exceed this limit.

Chapter 2

Using the Internet Document Server

Performance Measurements when Using Multiple Servers

To help you choose the right server setup for your needs, here are some test results compiled from multiple server runs.

These tests were run with a specified number of servers and clients. The servers were started from the command line, so there is no built-in web server overhead or limitations.

For these tests, all clients ran at the same time. In typical implementations, you seldom have all users working on the server at the same time.

Clients Number of servers Number of transactions per hour

Short transactions, each takes about 1 second or less

20 1 1680

1825

1583 (note the performance degradation)

40 1 1211

Not CPU intensive transactions, each takes about 40 seconds

263

CPU intensive transactions (100% CPU usage in the NT task manager), each takes about 10 seconds

2 (same PC)

2 (different PC)

372

372 (no difference)

754

Using Multiple Servers

Specifying the INI file to use

Setting Up Additional Servers

You can start multiple instances of IDS by default. Running multiple instances of IDS is generally required for performance reasons.

You control the number of instances IDS starts using this Configuration option:

</section>

The default is two (2). You can enter a number from 1 to 10.

You can specify the name and location of the DAP.INI file you want to use in the

DPRInit rule as shown here:

<entry name=”function”>dprw32->DPRInit,500,d:\docserv\dap.ini</ entry>

</section>

Separate parameters with commas.

The first parameter specifies the file cache. The default FAP file cache is 1000. The second parameter specifies where to find the INI file.

DAP.INI is the default file name.

OTE

This approach does not work with the DPRCoLogin rule. Use the DPRLogin rule instead.

Chapter 2

Using the Internet Document Server

ETTING

P A

INDOWS

ERVICE

You can configure the Internet Document Server to run as a Windows service.

OTE

Do not install the Internet Document Server and Internet Document Master

Server as a Windows NT service until you have checked to make sure the system was properly installed.

To set up the Internet Document Server as a Windows service, go to the directory where it is installed and run the batch file, DS-SERVICE.BAT. This will install IDS as a service called

Docupresentment Server.

To uninstall Internet Document Server as a Windows service, go to the directory where it is installed and run the batch file, DS-SERVICE-UNINSTALL.BAT.

When running as a service, messages usually written to the console's standard output are written to a text file named DS-STDOUT.TXT. The messages usually written to the console's standard error are written to a text file named DS-STDERR.TXT.

Handling Multi-threaded Requests

ANDLING

ULTI

THREADED

EQUESTS

IDS can run multiple requests at the same time in separate threads of execution. If the requests run are safe to run in multiple threads and are mixed between I/O-based and computation-based, then running some requests in multiple threads can be an alternative to running multiple instances of IDS.

An instance of IDS has a main thread that initializes global data and is the default for running all requests. You can configure IDS to start extra threads to run some requests.

This is done in the docserv.xml configuration file, in the ‘BusinessLogicProcessor’ section:

Entry Description

RequestProcessors Indicates how many extra threads to set up to run requests. If the entry is set to zero (0), no extra threads are set up and all requests are run serially.

To specify that a request can be run in an extra thread, in the docserv.xml configuration file, create a 'MultiThreadedRequests' subsection in the 'BusinessLogicProcessor' section:

<entry name="Request">FTPSEND</entry>

</section>

All requests mentioned in this section will be run in multiple threads if the

'RequestProcessors' entry is set up.

Each thread has its own separate input and output state to keep track of message variables and attachments per request being run, so code in rules that read or change message variables or attachments will not interfere with other requests running at the same time.

This includes calls to:

• DSIMessage.getMsgVar, DSIMessage.setMsgVar, and so on in the Java and scripting rules.

• DSIJQueue.LocateAttachVar, DSIJQueue.AddAttachVar, and so on in the IDS version 1.x Java rules.

• DSILocateAttachVar, DSIAddAttachVar, and so on in the C rules.

This does not mean all rules are safe to run in multiple threads, just that calls to the DSI

API code do not prevent rules from being run in multiple threads. For example,

Documaker code is not safe to run in multiple threads. If you need to run multiple

Documaker-related requests at the same time, you must run multiple instances of IDS.

Chapter 2

Using the Internet Document Server

INI vs. THREADINI control sections

Threads and Inter-Rule data in C rules

IDS version 1.x has a INI control section where global data is created and destroyed.

Since IDS version 2.x can have multiple threads, you need a way to create and destroy data needed by each thread. This is done with the THREADINI control section. The

THREADINI control section is run once for each thread as it is started and once for each thread when it is stopped. An example of code needing this is COM setup in Windows; every thread in Windows that will be running COM code needs to initialize COM for that thread. Here is a sample INI and THREADINI control section:

<entry name="function">irlw32->;IRLInit</entry>

<entry name="function">dprw32->;DPRInit</entry>

</section>

<entry name="function">DSICoRul->;Init</entry>

</section>

IDS rules written in C use the functions DSICreateValue, DSILocateValue, and

DSIDestroyValue to create data in one part of code to use in other parts of code.

A common usage of these functions is to allocate data in the DSI_MSGINIT part of a function, use it in the DSI_MSGRUNF and DSI_MSGRUNR parts of a function, and free the data in the DSI_MSGTERM part of a function. All this is done inside a single request.

A less common usage is to set up data in the INI request used for the entire runtime of

IDS. Rules in the INI request type have their DSI_MSGINIT code run when IDS starts and their DSI_MSGTERM code run when IDS shuts down. This means data allocated with DSICreateValue in the DSI_MSGINIT part of a INI request rule function is available for all other requests run by IDS. This data is usually read-only, for example configuration information from the DAP.INI file and MRLs set up by the DPRInit function.

Since IDS can run requests in multiple threads simultaneously, each thread needs it's own set of data for running requests plus access to the global configuration information. And, at the same time, each thread needs to remain compatible with C rules using the

DSICreateValue, DSILocateValue and DSIDestroyValue functions. This is done by having two data contexts for data:

global and thread-local.

Global context is when IDS is running rules in the INI request type. The INI rules are run with DSI_MSGINIT before the other rule threads are created, and the rules are run with DSI_MSGTERM after the other threads are destroyed. Thread-local context is when all other requests are run.

When the functions DSICreateValue and DSIDestroyValue are called during global context the values are put in global data; in thread-local context the values are put in thread-local data.

When DSILocateValue is called in thread-local context, the thread-local data is first checked to see if has the data. If the value is in thread-local data, it is returned. If not, then global data is checked, and returned if it is there. Only if the value is missing in both places will DSILocateValue indicate that the data is not found.

This allows C rules using DSICreateValue, DSILocateValue, and DSIDestroyValue to run in multiple threads but remain compatible with previous versions of IDS.

Handling Multi-threaded Requests

Threads and Inter-Rule data in Java and scripting rules

Since Java rules are based on objects that have their own state, this use of the C DSI-Value functions is not required. When Java rules are used with transaction scope, an instance of the class will remain for the run of the request, so data can be put in member variables and will remain. There are functions available that do the same thing for passing data from one rule to another or for use in one rule if it is run in static scope.

The RequestState object passed in to a Java rule has the methods putObject, getObject, and removeObject. Since each thread has its own RequestState object, you can use these functions to keep track of data for each request. These functions let you store any type of object, not just byte arrays like the C functions.

To pass data between C and Java rules, use the RequestState methods createVar, locateVar, and destroyVar. These correspond to the C functions DSICreateValue,

DSILocateValue, and DSIDestroyValue, so they can only use byte arrays for passing data.

The data context setup is also the same as for these C functions.

To set up and use Java global data, use the GlobalVarStorage class from the

DocuCorpUtil library.

SING THE

AVA

EST

TILITY

IDS includes a Java threads test utility you can run to send requests to IDS using single or multiple threads. It also supports attachments and rowsets. You can also feed it a debug message file, such as a receive.msg file generated by IDS (see the ReceiveMessage log4j category in the logconf.xml file under the docserv directory) which can contain more than one transaction that was previously processed. This can be useful in recreating or duplicating a set of transactions for testing.

You can invoke the test utility via the threads script shipped with IDS.

OTE

If you invoke the test utility without any arguments, it displays usage information.

For more information, see the HTML documentation for the com.docucorp.test.threads class that is included with Java SDK.

You must have Java version 5 or later installed to use this test utility.

Chapter 2

Using the Internet Document Server

SING

ULES

RITTEN IN

THER

CRIPTING

ANGUAGES

IDS can run rules written in scripting languages. In addition to rules written in Java, C, and Visual Basic, IDS adds rules written in scripting languages (Java Script, Python, and so on) for debugging, fast prototyping, or rarely run rules.

In a REQTYPE section, add a rule entry such as:

<entry name="function">script;test.py;runRule</entry>

This rule entry uses the runRule function in the Jython script file (TEST.PY).

The following example programs do the same thing. The first is in JavaScript, the second in Jython, a dialect of Python that runs under Java Virtual Machines. You can find information about which languages are available and where to get them at: http://jakarta.apache.org/bsf/index.html

Here is a JavaScript example rule: function runRule(requestState, idsArgs, idsMessage) {

switch (idsMessage) {

case IDSConstants.init :

break;

case IDSConstants.runForward :

break;

case IDSConstants.runReverse :

text = requestState.getOutput().getMsgVar("LANGUAGE");

if (text == null) {

text = "JavaScript";

} else {

text = text + " and JavaScript";

}

requestState.getOutput().setMsgVar("LANGUAGE", text);

break;

case IDSConstants.terminate :

break;

}

return IDSConstants.success;

}

Here is a Jython example rule: def runRule(requestState, idsArgs, idsMessage):

if idsMessage == IDSConstants.runReverse:

text = requestState.getOutput().getMsgVar("LANGUAGE")

if text is None:

text = "Jython"

else:

text = text + " and Jython"

requestState.getOutput().setMsgVar("LANGUAGE", text)

return IDSConstants.success

Using IDS as a Client to Another IDS

SING

IDS

AS A

LIENT TO

NOTHER

IDS

You can set up an IDS installation running under Linux and use the RunRP rules to archive data from Documaker output into a Documanage archive stored on a Windows

NT computer. To do this, you must set up your system as explained below.

OTE

This solution can also be used for other situations, such as when you need to execute rules across platforms.

IDS

Client

Queues

(Set 1)

Linux

IDS

Server 1

(multiple instances)

Documaker

(GenData)

Queues

(Set 2)

IDS

Server 2

(multiple instances)

Archive

(Documanage)

Windows NT

The archive process

The IDS client submits an XML extract file to IDS (IDS Server 1). On this request IDS

Server 1 executes the RunRP rules. After Documaker executes and prior to this transaction being complete, IDS Server 1 has access to NA file, POL file, and NEWTRN file. These files are attached to the request to IDS Server 2 (on Windows NT).

IDS Server 2 archives data into Documanage and returns the error code. IDS Server 1 receives the return code from IDS Server 2, adds all the attachment variables from IDS

Server 2 to the output attachment, and replies to the IDS client. IDS Server 2 does not use GenArc or single-step GenData to archive, which reduces the number of resource and setup files needed on Windows NT.

Chapter 2

Using the Internet Document Server

The retrieval process

Syntax

The IDS client submits the request to retrieve data to IDS Server 1. IDS Server 1 submits the request to get the DPA file to IDS Server 2. The IDS Server 2 gets the DPA file from

Documanage, attaches it to the SOAP message and sends the reply to IDS Server 1. IDS

Server 1 receives the Documaker file, runs rules to produce a PDF file and sends the PDF file to the client (this can be done as a file on disk or attached to the SOAP message).

Keep in mind:

• MQSeries is used as a queuing system in both places

• Java rules are used to send messages from IDS Server 1 to IDS Server 2 so JVM has to be available on Linux platform to execute Java rules.

• Some of the Documaker resources (like DFD files, INI files) must be available to both IDS implementations and must be kept in sync. One way to synchronize resources is by using mounted volumes from Windows NT to Linux to IDS Server

2 on Windows NT has access to the same physical files as IDS Server 1 on Linux.

• You use the IDSClientRule to make IDS act as a client to another implementation of

IDS. This rule is explained below:

Using the IDSClientRule

Use this rule to have IDS act as an IDS client to send a request to a second IDS. You can set communications parameters to talk to the second IDS and request parameters to set up request types and other attachment variables to send to the second IDS.

The attachment variables and files you want to send can be hard-coded or retrieved as attachment variables from the first IDS. Attachment variables returning from the second

IDS can be put in the input or output queue of the first IDS.

If the second IDS returns files in its result, the files can be written to disk with unique names and cached. The unique names of the files are stored in attachment variables for use by other rules. The rule can be run on the run forward or run reverse message.

Keep in mind that only MQSeries setups are supported. This rule has transaction scope and the method in the Java class is

callRequest. The syntax of the function line in a request is shown here: function = dsijrule->JavaRunRule,;com/docucorp/ids/rules/

IDSClientRule;CALL;transaction;callRequest;ARG,MESSAGEFILE=call.propert

ies&REQUESTFILE=call.txt&TIMEOUTSEC=15&RUN=RUNF&DEBUG=Y&DESTINATION=OUT

PUT

Parameter

MESSAGEFILE

REQUESTFILE

TIMEOUTSEC

RUN

Description

This parameter points to the file that holds the settings for communicating with the second copy of IDS.

This parameter points to the file that holds attachment variables and files that are sent as a request to the second IDS.

Indicates the number of seconds to wait for a reply from the second IDS.

Indicates the request message during which the rule will run. This parameter is either

RUNF for the run forward message or RUNR for the run reverse message.

Using IDS as a Client to Another IDS

Parameter

DEBUG

DESTINATION

Description

Determines if debugging messages are put in the Java rule log file. The default is No.

This parameter says which queue will get the results back from the second copy of IDS. The default is OUTPUT.

You can set communications parameters to talk to the second IDS. This is done by setting up the file referenced in the MESSAGEFILE rule parameter.

Here is a sample IDSClientRule communications properties file. Parameters are explained by comment lines above the parameters:

This indicates the class that implements queuing, in this case MQSeries: queuefactory.class=com.docucorp.messaging.mqseries.DSIMQMessageQueu

eFactory

This indicates the class that formats the DSIMessage to send to IDS. Uncomment this line to communicate with IDS version 1.6, leave it commented for subsequent versions:

#marshaller.class=com.docucorp.messaging.data.marshaller.LegacyByte

ArrayDSIMessageMarshaller

The following are sample MQSeries parameters. This is the queue manager for system hosting MQSeries: mq.queue.manager=QM_pdtest

This specifies the MQSeries channel the messaging client and IDS use to communicate: mq.queue.channel=SCC_pdtest

The MQSeries communication can be either in

bindings mode (the program is running on the same machine as the MQSeries server) or in

client mode (the program is running on a different machine and communicates with the MQSeries server through TCP/IP). If the setting

mq.tcpip.host is defined, the system uses client mode, otherwise it uses bindings mode: mq.tcpip.host=10.10.10.10

This specifies the TCP/IP port the MQSeries server is listening to.

1414 is most commonly used.

mq.tcpip.port=1414

A client program sends requests out and gets results in: mq.outputqueue.name=requestq mq.inputqueue.name=resultq

This determines how long, in seconds, the MQSeries server keeps a message in the queue if a program does not get it.

mq.outputqueue.expiry=120

Here is the complete example: queuefactory.class=com.docucorp.messaging.mqseries.DSIMQMessageQueu

eFactory

#marshaller.class=com.docucorp.messaging.data.marshaller.LegacyByte

ArrayDSIMessageMarshaller

Chapter 2

Using the Internet Document Server mq.queue.manager=QM_pdtest mq.queue.channel=SCC_pdtest mq.tcpip.host=10.10.10.10

mq.tcpip.port=1414 mq.outputqueue.name=requestq mq.inputqueue.name=resultq mq.outputqueue.expiry=120

Attachment variables and files to send can be hard coded or retrieved as attachment variables from the first IDS. This is done in the file mentioned in the REQUESTFILE parameter. The file can have these sections:

• [MESSAGES] for attachment variables in

name=value pairs

• [TEXTFILES] for sending text files

• [BINARYFILES] for sending binary files

• [RECEIVEDFILES] for the handling of files returned from the second IDS

[TEXTFILES] and [BINARYFILES] have

file ID=file location pairs, listing the name that the file data can be identified by and where to get the file's information. Here is a sample

REQUESTFILE:

[MESSAGES]

REQTYPE=CUSTOMREQUEST

USERID=GUEST

[TEXTFILES]

TEXT1=/home/fap/text1.txt

TEXT2=/home/fap/text2.txt

[BINARYFILES]

BIN1=/home/fap/binary1.bin

BIN2=/home/fap/binary2.bin

You can use attachment variables from the current running state of IDS as values in any of the above sections. For example:

~GetAttach VARIABLENAME,INPUT will use an attachment variable from the input queue

~GetAttach VARIABLENAME,OUTPUT will use an attachment variable from the output queue. If instead of the name of an attachment variable, you use an asterisk (*), every attachment variable from that queue will be sent. Here is an example

~GetAttachment *,INPUT

This tells the system to ignore the attachment variable name. If you use an asterisk (*), the request type of the request to send is not changed. An explicit

REQTYPE is required in the REQUESTFILE file.

For the [RECEIVEDFILES] section, the string to the left of the equals sign (=) is the name of the file coming back from the second IDS. To the right of the equals sign is the name of the attachment variable that contains the unique name and path of the generated file, the directory where the file will be stored, and, optionally, the number of seconds to cache the file. The default cache is 3600. For text files, the system appends

.txt. For binary files, it appends

.bin.

Using IDS as a Client to Another IDS

Here is a complete example of a request file:

[MESSAGES]

REQTYPE=CUSTOMREQUEST

DUMMY = ~GetAttach *, INPUT

[TEXTFILES]

TEXT1=c:\fap\text1

[BINARYFILES]

BIN1= ~GetAttach BINFILE, OUTPUT

[RECEIVEDFILES]

ZZZT=MYTEXT, ., 1800

ZZZB=MYBIN, c:\fap, 600

In this example after the run, if the current directory is c:\docserv, then the file sent in

ZZZT would be stored in c:\docserv\1729530022133082002.txt

That file name would be stored in the attachment variable MYTEXT and the file sent in

ZZZB would be stored in: c:\fap\6229680022133082002.bin

That file name would be stored in the attachment variable MYBIN. The text file,

(c:\docserv\1729530022133082002.txt) would be cached by IDS for 1800 seconds. The binary file (c:\fap\6229680022133082002.bin) would be cached by IDS for 600 seconds.

Chapter 2

Using the Internet Document Server

ONITORING

IDS

WITH

SNMP T

OOLS

You can connect IDS to SNMP agents (SNMP server programs) so performance data can be viewed by SNMP monitors (SNMP client programs). The connection is done with the

SNMP AgentX protocol, so you can use any SNMP agent program that supports AgentX.

If an AgentX-enabled SNMP agent is not available for a particular platform, IDS includes a Java-based SNMP agent application you can use. This version includes a Management

Information Base (MIB) file, that can be used by SNMP monitor programs to map text names and data types to the MIB number addresses for SNMP objects.

The primary server reports the number of instances of IDS that are running. Each instance will report:

• The amount of time since it started running.

• The amount of time since the last restart.

• The number of successful transactions.

• The number of transactions that caused errors.

• The number of times the instance has been restarted.

• The amount of time needed to run the last transaction.

• The request type of the last transaction.

• The amount of time needed to run the longest transaction so far.

• The request type of the longest transaction so far.

• The number of transactions that have occurred in the last minute.

• The number of transactions that have occurred in the ten last minutes.

• The number of transactions that have occurred in the last hour.

To monitor IDS with SNMP tools, in the docserv.xml configuration file, create an SNMP subsection under the DocumentServer, messaging subsection, as shown here:

</section>

Entry

Enabled

MasterAddress

Description

Determines whether or not SNMP support is enabled. The default is No.

Is the IP address of where the master SNMP agent program is running. The default is localhost.

MasterProtocol Is the communications protocol for communicating with the SNMP agent program. You can enter

UDP for communicating with IDS's included agent or

TCP for communicating with other AgentX-based SNMP agent programs, such as net-snmp. The default is UDP.

Monitoring IDS with SNMP Tools

Entry

MasterPort

Description

Is the port the master SNMP agent program uses for the AgentX protocol.

The default is 705.

ONITORING

EQUESTS

The SNMP monitoring capabilities in IDS allow the monitoring of extra requests and rules by performance monitoring applications, such as LoadRunner.

You can have up to five statistics monitors to measure performance by SNMP. Each monitor measures either an entire request or an individual rule in a request. For each monitor, the time it takes to execute each

message part (initialization, run forward, run reverse, and terminate) as well as the total time for execution is available.

OTE

The MIB file can use these monitors, but it is not required.

To enable the statistics monitors, in the docserv.xml configuration file, in the

DocumentServer section, add a StatisticsMonitors subsection, as shown here:

...

</section>

Each Monitor entry can be the name of a request or the name of a request followed by a slash ( / ) and a number. The number is the number of the active entry in the request section. For example, for this request type...

<entry name="function">atcw32->ATCLogTransaction</entry>

<entry name="function">atcw32->ATCLoadAttachment</entry>

<entry name="function">dprw32->DPRSetConfig</entry>

<entry name="function">dprw32->DPRTermDB</entry>

<entry name="function">dprw32->DPRInitLby</entry>

<entry name="function">atcw32->ATCUnloadAttachment</entry>

<entry name="function">dprw32->DPRRetrieveFormset</entry>

<entry name="function">dprw32->DPRPrint</entry>

<entry name="function">dprw32->DPRProcessTemplates</entry>

</section>

The monitor entry

PRT/7 would refer to the DPRRetrieveFormset rule and PRT/8 would refer to the DPRPrint rule.

Chapter 2

Using the Internet Document Server

ANAGING

IDS

NSTANCES

You can use the Watchdog process to manage and monitor IDS instances. The

Watchdog process is started, stopped, and configured as a service. It is then responsible for managing and monitoring the IDS instances.

The Watchdog process monitors the health of each instance and restarts it or stops it when needed. You can also configure the Watchdog process through log4j to send email notifications when an instance encounters a fatal or mission-critical error.

The Watchdog process also monitors the idle time for each instance and starts additional ones when all running instances are under load. You have these options:

OTE

Define these options in the DocumentServer section of the docserv.xml file. Do not confuse these options with similar options for the HTTP router process in the same file. The router is a different process and it does not support load balancing.

Options

Instances

UseLoadBalancing

MaxInstances

Description

(Optional) The number of IDS instances Watchdog should start at startup. The default is two (2).

(Optional) This option controls whether Watchdog checks the idle time of the instances that are running and starts additional ones when all of them are busy.

Instances are considered busy when their idle time is less than the value provided in the MinIdleTimeSeconds option. Watchdog uses the value provided in the

IdleTimeChecks option to determine the number of idle time checks to run before it starts additional instances.

When additional instances are started for load balancing purposes, they are shut down by Watchdog if their idle time exceeds the value in the MaxIdleTimeSeconds option.

The maximum number of instances running is the value for the

MaxInstances

option (including the instances configured in the

Instances

option). Watchdog checks the idle time of the current instances at the interval specified in the IdleTimeCheckIntervalSeconds and if all are busy, it starts an additional number of instances equal to the value provided in the IncrementCount option.

Please note that Watchdog does not start checking the busy time of the current instances until the time provided in the IdleTimeCheckDelaySeconds option is reached.

Make sure the value for the delay is ample enough to provide for all instances to start and reach an idle time equal to or greater than the value provided for the

MinIdleTimeSeconds option.

You can enter Yes (or True) or No (or False). The default is Yes.

(Optional) This option controls the maximum number of instances that can run when the UseLoadBalancing option is enabled. The default is the number of processors times two.

Managing IDS Instances

Options

IncrementCount

IdleTimeCheckIntervalSeconds

IdleTimeCheckDelaySeconds

IdleTimeChecks

MinIdleTimeSeconds

MaxIdleTimeSeconds

MaxTransactions

MaxReportIntervalSeconds

MaxUpTimeSeconds

Description

(Optional) This option controls how many additional instances are started during the current check when all instances running are busy and the UseLoadBalancing option is enabled. The default is two (2).

(Optional) This option controls how often Watchdog checks the idle time of the instances that are running to determine if they are busy so it can start additional ones when the UseLoadBalancing option is enabled. The default is 60 seconds.

(Optional) This option controls the initial delay before the first idle time check is performed by Watchdog when the

UseLoadBalancing option is enabled. This time should be ample enough to allow all instances to start and reach an idle time equal to or greater than the value provided for the

MinIdleTimeSeconds option. The default is 120 seconds.

(Optional) This option defines the number of consecutive

Idle time checks that must fail, meaning all instances were busy during each check, before more instances are started when the UseLoadBalancing option is enabled. Each check takes place at the IdleTimeCheckIntervalSeconds interval. The default is two (2).

(Optional) This option controls the minimum idle time for each instance. The idle time represents how long it has been since an IDS instance processed the last request. If

Watchdog detects an instance has an idle time less than the value provided for this option, it considers it busy for the purpose of load balancing. The default is five (5) seconds.

(Optional) This option controls the maximum idle time for an additional instance. The idle time represents how long it has been since an IDS instance processed the last request. If Watchdog detects an instance which was started for the purpose of load balancing has reached an idle time greater than the value provided for this option, it sends the instance a shutdown request. The default is 120 seconds.

(Optional) This option controls the maximum number of transactions an instance can process before it is restarted by Watchdog. Enter -

1 to disable this option. The default is 10000.

(Optional) This option controls the maximum time interval that can elapse without an instance reporting back to Watchdog before it is restarted. The default is 120 seconds.

(Optional) This option controls the maximum time interval an instance can run before it is restarted by

Watchdog. Enter -

1 to disable this option. The default is

28800 seconds (8 hours).

Chapter 2

Using the Internet Document Server

Options

MaxRestarts

RestartIntervalSeconds

MaxMemoryUsagePercent

MemoryChecks

CheckIntervalSeconds

UseJMX

Description

(Optional) This option controls the maximum number of restart attempts that can occur within a time interval specified by the RestartIntervalSeconds option before

Watchdog shuts down.

Use this option to prevent Watchdog from attempting to restart instances infinite times when they cannot be started due to configuration errors and so on. The default is five restarts.

(Optional) This option controls the interval used with the

MaxRestarts option to determine if Watchdog is having a problem starting instances and to prevent continuous or infinite restart attempts. The default is 60 seconds.

(Optional) This option controls the maximum percentage of the total JVM memory that can be used by an instance before Watchdog will restart it.

Note that the total memory used in this calculation does not include any memory used by native code. This option is used with the MemoryChecks option. The default is 95.

(Optional) This option controls the total count of consecutive memory checks that must be present, where the memory usage by an instance exceeds the value provided for the MaxMemoryUsagePercent option for each check, at which point Watchdog will restart it.

The interval for each memory check is controlled by the

CheckIntervalSeconds option. The default is -1, which disables this option.

(Optional) This option controls the time interval used by

Watchdog to check the health of each instance. The default is one (1) second.

(Optional) This option controls whether JMX is used to monitor additional health metrics for each instance.

Enabling this option lets Watchdog also monitor class loading, memory usage, garbage collection, and deadlocks in Java code for each instance.

Note that enabling this option requires an additional and separate TCP/IP port for each instance so that it can be started with a JMX agent.

You can enter Yes (or True) or No (or False). The default is No.

Only use this option for debugging or testing purposes.

Do not use this option in production mode because it causes extra overhead and it requires additional ports be used.

Managing IDS Instances

Options

JMXPort

JMXCheckIntervalSeconds

JMXMemoryChecks

JMXVerboseMemory

JMXVerboseClassLoader

WaitForShutdownSeconds

OrderedRestartIntervalSeconds

Description

(Optional) This option controls the starting JMX port to use when starting each instance with a JMX agent if the

UseJMX option is enabled.

Note that the starting port value should consider that each additional instance that is started will try to use a continuous/incremental port number. The default starting port value is 49163.

(Optional) This option controls the time interval used to run JMX checks for each instance when the UseJMX option is enabled. The default is 60 seconds.

(Optional) This option controls the total count of consecutive JMX memory checks that must be present, where the memory usage by an instance exceeds the value provided for the MaxMemoryUsagePercent option for each check, at which point Watchdog will restart it.

The interval for each check is controlled by the

JMXCheckIntervalSeconds option. The default is -1, which disables this option.

(Optional) This option controls whether Watchdog turns on verbose memory to output GC statistics for each IDS instance when the UseJMX option is enabled. You can enter Yes (or True) or No (or False). The default is No.

(Optional) This option controls whether Watchdog turns on verbose class loading for each IDS instance when the

UseJMX option is enabled. You can enter Yes (or True) or

No (or False). The default is No.

(Optional) This option controls how long Watchdog waits for an instance to shut down after it issues a shutdown command and before it terminates the instance. The default is 20 seconds.

(Optional) This option controls the interval used for restarting each of the IDS instances in a sequential/ ordered manner when the MaxTransactions or

MaxUpTime options are used.

Watchdog restarts one instance at a time and waits for an amount of time equal to the value specified for this option before it restarts the next one and so on until it has restarted all of them.

If you set this option to less than 60 seconds, you can negatively affect performance. The default is 60 seconds.

Chapter 2

Using the Internet Document Server

Determining the instance number of a server

Categories and appenders used by

Watchdog

You can determine the exact instance number of the (IDS) server the rule is running on.

For instance, you can use this to determine which TCP/IP port to use when IDS has to talk to the GenData process. This DSI variable can be accessed from an IDS rule:

IDSINSTANCE

The value is a character array of a zero-based value. For example, on the primary IDS the value will be zero (0), on first secondary instance it will be one (1), and so on. To get the value, the rule has to call DSILocateValue().

Here are the Log4J categories and appenders used by Watchdog (see logconf.xml file included in the docserv directory):

• These mail categories and appenders are used to send email notifications during mission critical errors, such as when IDS has a fatal exception:

<appender-ref ref="EMAIL"/>

</category>

<!--

-->

</layout>

</appender>

• This category is used to log informational output by Watchdog:

<appender-ref ref="watchdog-stdout"/>

<appender-ref ref="watchdog-allroll"/>

</category>

• These categories and appenders are used to log debug and error messages by

Watchdog. Change the Priority value to 'DEBUG' to log debug messages.

Managing IDS Instances

<appender-ref ref="watchdog-stdout"/>

<appender-ref ref="watchdog-allroll"/>

</category>

</layout>

</appender>

</layout>

</appender>

• These categories and appenders are used by each Watchdog instance monitor thread to log information for each instance monitored separately. Change the Priority value to 'DEBUG' to log debug messages.

<appender-ref ref="instance-stdout"/>

<appender-ref ref="instance-allroll"/>

</category>

</layout>

</appender>

</layout>

</appender>

Chapter 2

Using the Internet Document Server

Watchdog section

• These categories and appenders are used to log debug and error information for IPC

(Inter-Process Communication) messages between Watchdog and the instances.

Change the Priority value to 'DEBUG' to log debug messages.

<appender-ref ref="connector-stdout"/>

<appender-ref ref="connector-allroll"/>

</category>

</layout>

</appender>

</layout>

</appender>

A watchdog configuration file can contain multiple sections, each with its own set of options. Here are some examples:

Here is an example of the Watchdog section:

</section>

<entry name="StartArguments">-Djava.endorsed.dirs=lib/ endorsed -Xmx256m -Ddsimessage.debug=N -Dmarshaller.output=N -cp

.;lib/DocucorpStartup.jar -Dids.configuration=docserv.xml -

Dlogging.configuration=logconf.xml com.docucorp.startup.Startup com.docucorp.ids.DocumentServer</entry>

Managing IDS Instances

</section>

</configuration>

These JVM options are supported:

Option Description

-Dwatchdog.configuration

(Optional) The name of the XML configuration file for watchdog.

The default is docserv.xml.

-Dlog4j.configuration

-Dwatchdog.prefix

(Optional) The name of the XML configuration file for LOG4J.

The default is logconf.xml.

(Optional) A unique string that should be used as the prefix for all

Watchdog files/locks generated on disk.

Use this option when running more than one Watchdog instance from the same directory.

Scenario 1

Scenario 2

Here are some examples:

A platform contains a single CPU and the default values are used for the Instances option and for load balancing.

In this case, the default value of Instances will be two (2) and the default value of

MaxInstances will also be two (2) so no load balancing will occur.

A platform contains four CPUs and the default values are used for the Instances option and for load balancing.

In this case the default value of Instances is two (2) and the default value of MaxInstances is 8. The default increment count will be two (2), the default minimum idle time will be 5 seconds, and the default maximum idle time will be 120 seconds.

Chapter 2

Using the Internet Document Server

Scenario 3

Load balancing will occur and Watchdog will check the idle time of any running instances every 60 seconds. If each of the instances running has an idle time that is less than 5 seconds, Watchdog deems them all busy and starts two additional instances. Watchdog then continues on to the next check interval.

These steps are repeated during each check interval until the total number of instances running reaches eight. If any of the running instances were started for the purpose of load balancing and reach an idle time greater than 120 seconds, they are shut down by

Watchdog.

A platform contains four CPUs and the value for the Instances option is set to 20 and the default values are used for load balancing.

In this case the value for MaxInstances will be eight but the value for the instances will be greater than the value for the maximum instances that can be reached during load balancing so no load balancing will occur.

Sending Results and Receiving Requests in Multiple Formats

ENDING

ESULTS AND

ECEIVING

EQUESTS IN

ULTIPLE

ORMATS

The HTTP-based and queue-based messaging systems in IDS can accept messages in multiple formats and will return results in the same format as the request. This is done so

IDS can communicate with third-party products that would find it difficult to produce messages in current IDS-compatible formats.

The translation is done by

marshaller code that translates a foreign message format into the message format used internally by IDS (

com.docucorp.messaging.data.DSIMessage).

Marshallers are Java objects that implement the interface

com.docucorp.messaging.data.marshaller.DSIMessageMarshaller, which is documented in the

SDK Reference.

Objects of the DSIMessage class hold the message variables and attachments passed in as input to IDS and the output message variables and attachments produced by processing requests in IDS.

The most important functions for marshallers are shown here:

Marshaller Takes

marshall A DSIMessage as an input and produces an object that is suitable for sending to a client application via messaging. unmarshall An object from a client application and a DSIMessage, and uses the Object to fill in data in the DSIMessage.

isType An object from a client application and determines if it is in the format of the marshaller.

The messaging systems, both HTTP-based and queue-based, keep a list of marshallers for formats that they recognize. When a message comes in from a client application, a messaging system compares the message's format against the formats will recognizes using the isType function for each marshaller.

If there is a match the incoming data is translated into a DSIMessage with the marshallers unmarshall function and the DSIMessage, holding the request to be processed, is used as input into the main request processing in IDS. This produces an output DSIMessage holding message variables and attachments. The output DSIMessage is translated into the same format as the input message and sent back to the client application.

As a default, the HTTP-based messaging system understands the SOAP with MIME

Attachments format. (See Using HTTP on page 125 for more information.) The default marshallers for the queue-based messaging system understand the SOAP with MIME

Attachments format and the binary format used by IDS version 1.6 and earlier.

The queue-based messaging system currently works with WebSphere MQ, formerly known as MQSeries, and Java Message Service based queues. Both queuing systems can deliver messages as text (a Java string) and binary (a Java array of bytes), so marshallers can work with either format. The HTTP-based messaging system only recognizes text with HTTP headers, such as Content-length, so marshallers written to work with HTTP must work within these limitations.

Chapter 2

Using the Internet Document Server

Configuring and Deploying Marshallers

To configure IDS to recognize custom marshallers, you can add a marshallers section to either of these sections:

• 'BusinessLogicProcessor', subsection 'messaging', subsection 'queue'

• 'BusinessLogicProcessor', subsection 'messaging', subsection 'http'

For example, in the docserv.xml configuration file, in section 'BusinessLogicProcessor', subsection 'messaging', subsection 'queue' create a 'marshallers' section and add these entries:

<entry name="marshaller.class">com.docucorp.messaging.data.marshaller.Lega

cyByteArrayDSIMessageMarshaller</entry>

<entry name="marshaller.class">com.docucorp.messaging.data.marshaller.SOAP

MIMEDSIMessageMarshaller</entry>

</marshallers>

This sets up the queuing system to use these two formats for receiving and sending requests. If no entries are specified then IDS defaults to SOAP with attachments and legacy IDS byte format.

OTE

If a custom marshaller list is added to the configuration file, the default marshallers are not automatically added to the list. This allows greater customization. If you want to also use the default marshallers in messaging, you must add them to the marshallers list in addition to the custom marshallers.

Using the DSIMessage marshaller class

To deploy your marshaller code, package the Java class files in a JAR file and put it in the

/lib subdirectory under where IDS was installed. The next time IDS starts your custom marshallers will be available.

IDS version 2.1 added the DSIMessage marshaller class called

XSLTTemplateDSIMessageMarshaller.

For marshalling, the marshaller starts with the usual SOAP/XML format of a

DSIMessage, then uses that as the source of a XSLT transformation to convert the SOAP message to a third-party XML format.

For unmarshalling, the marshaller starts with a third-party XML format and the XSLT transformation converts it to the Docupresentment SOAP/XML format, which is then unmarshalled into a DSIMessage object.

In addition to the usual marshalling methods, the marshaller adds methods to pass in the files holding the XSLT templates, or the text of the XSLT template directly.

OTE

This marshaller is mainly used in IDS rules, so there is no configuration-based setup of XSLT templates for marshalling and unmarshalling. You set up the

XSLT with Java methods in the XSLTTemplateDSIMessageMarshaller class.

Sending Results and Receiving Requests in Multiple Formats

These methods set up XSLT templates for the marshaller:

• public void setMarshallerText(String text)

This method sets the XSLT text for marshalling messages (converting to a foreign format).

• public void setMarshallerFilename(String filename)

This method sets the file that holds the XSLT for marshalling messages (converting to a foreign format). The file is loaded into the marshaller filter.

• public void setUnmarshallerText(String text)

This method sets the XSLT text for unmarshalling messages (converting from a foreign format).

• public void setUnmarshallerFilename(String filename)

This method sets the file that holds the XSLT for unmarshalling messages

(converting from a foreign format). The file is loaded into the unmarshaller filter.

Chapter 2

Using the Internet Document Server

OGGING AND

RACING

Severity levels

Logging categories

There are several ways you can configure IDS to log messages. For instance, you can configure IDS to:

• Log only events based on their severity, from debug messages to fatal errors.

• Control where logging messages are sent, whether they go to files, the Windows event logger, into emails, and so on.

• Include and format the relevant information, such as time of day, elapsed time since

IDS was started, where the message came from, which thread the code is currently running in, and so on.

Logging in IDS is based on the Log4j logging library. A complete description of Log4j's capabilities is available at http://jakarta.apache.org/log4j

IDS logging is configured by the file specified in the Java system property

'logging.configuration'. If this property is not set, the default is to look for the logconf.xml file in the current directory. This file is checked periodically for changes by IDS when it is running, so it is possible to change logging options while IDS is running. IDS does not need to restart when a logging change is made.

Logging messages have a severity level assigned to them. This is used to determine if and when a logging message is written. From least to most severe, the severity levels are:

• DEBUG

• INFO

• WARN

• ERROR

• FATAL

When setting up logging you can decide what kind of messages to receive by picking a severity level. Any messages at that severity level and those more severe are output. For example, if you choose a severity level of WARN, only WARN, ERROR, or FATAL messages are sent, while DEBUG and INFO messages are suppressed. For diagnosing problems, the severity level would be set to DEBUG to produce more messages.

What messages to log and where to log them is determined by logging categories or

loggers.

Categories are based on a hierarchy of names or words separated by periods. As an example,

DocumentServer would be a parent category to DocumentServer.output and

DocumentServer.error. When a parent category is assigned a severity level, all children categories inherit it as their default. Children categories can override these defaults.

For example, if the

DocumentServer category's severity level is set to WARN and the

DocumentServer.output category's severity is set to INFO, then only DocumentServer and

DocumentServer.error will use WARN.

Logging and Tracing

The

DocumentServer.output category is where normal runtime messages for IDS are sent, such as the startup message and how many transactions were completed at shutdown or restart time. Common errors encountered during configuration and rule setup are sent to the

DocumentServer.error category. Since these messages are in logging categories, they can be sent to multiple places in addition to being printed on the console. There are other categories that have debugging messages and you may be asked to activate these by

Support.

OTE

For additional information, see Using Logging Categories to Access the Internal

Format of Requests on page 94 .

Logging appenders

Logging formats

The destinations for logging messages are known as

appenders, since new logging messages are appended to the end of the file, event log, and so on. The most common appenders are for the console and for files.

A category can send messages to multiple appenders. Like severity levels, appenders inherit from parent categories, but unlike severity levels, appenders are added to the parent appenders and do not override the parent category's settings. This inheritance can be turned off, as shown in the logging example.

In addition to the logging message itself, other information can be configured to be output with the logging message, such as the date and time the logging occurred, the severity level of the message, and so on. In Log4j the formatting strings are called

conversion

patterns, which you will see in the logging example. You can arrange the formatting commands in any order. Text not part of a formatting command is sent verbatim, so you can use commas, dashes, and other characters to separate the formatted text.

You may want to set up conversion patterns for different appenders. For example, you may want to include the date and time on a message going to a file but excluding it from a message going to the Windows Event Log, since the message's date and time are logged by the Event Logger.

Here are some of the common formatting commands:

Parameter Description

%m The actual message being logged.

A system-dependent newline character.

The category of the message.

Date and time, down to the millisecond, when the message was generated.

Elapsed time, in milliseconds, since the application was started.

Severity level (priority) of the message generated.

The name of the Java thread that generated the message.

Logging example

This is an example logging configuration file. This table shows how the various categories output messages:

Chapter 2

Using the Internet Document Server

Category

DocumentServer

DocumentServer.output

DocumentServer.error

Outputs messages

With a WARN security level or higher

With an INFO security level or higher

That go to the console

That go to the console, a logging file, and to the Windows Event

Logger.

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

<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration debug="false">

<param name="ConversionPattern"

value="%-5p [%t] %r: %c{1} - %m\n"/>

</layout>

</appender>

<param name="ConversionPattern" value=" %d %-5p [%t]: %c{1}

%m\n"/>

</layout>

</appender>

<param name="ConversionPattern" value=" Docupresentment

Server: %m\n"/>

</layout>

</appender>

<appender-ref ref="stdout" />

<appender-ref ref="rollfile" />

<appender-ref ref="ntevent" />

</category>

Logging and Tracing

<appender-ref ref="stdout" />

</category>

<appender-ref ref="stdout" />

</category>

<root>

</root>

</log4j:configuration>

AMING

OGGING

ESSAGES

IDS includes a Log4j Appender class lets you control the naming of the files logging messages are written to. The full name of the class is: com.docucorp.ids.serverutils.IDSFileAppender

When this class is used as part of the logging setup, you can use IDS-specific variables.

The IDS-specific variables are:

Variable

~INSTANCE

~SERVERGUID

~THREADID

~UPTIME

~LASTRESTART

Description

The

instance number of the server being run. A primary server has an instance number of zero (0) and secondary instances are numbered starting at one (1). For example, running three instances of IDS, one primary and two secondary, the instances are numbered 0, 1, and 2.

A IDS GUID identifier unique to each IDS instance but not recycled upon restart. When IDS is started, the primary instance and any secondary instances are assigned a unique identifying string. These strings are assigned to the same instance of IDS if it is shut down and restarted. The GUID strings remain the same until the number of instances is changed in the docserv.xml configuration file.

Each thread in IDS is given a name. You can use this name as part of the file name. Since the same code may run in different threads during the lifetime of an IDS session, and since the thread ID can be printed during a logging message, you would seldom need to use this option.

An exception is for debugging the HTTP subsystem of IDS, where each

HTTP message is run in a pool of threads.

The date and time of when the instance of IDS was started.

The date and time of the most recent restart of this instance of IDS.

Chapter 2

Using the Internet Document Server

Variable Description

~CURRENTTIME The current date and time. The time can be measured down to the millisecond so this option is handy for debugging time-critical and performance issues.

The ~UPTIME, ~LASTRESTART, and ~CURRENTTIME options are followed by a formatting parameter which ends with a semicolon (;). The formatting options are based on Java's SimpleDateFormat class. You can find full documentation for these formatting options at: http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html

The formatting characters are:

K z a k

'' w

E m s h

M d

Symbol Meaning

G era designator y year month in year day in month hour in am/pm (1~12) hour in day (0~23) minute in hour second in minute millisecond day in week day in year day of week in month week in year week in month am/pm marker hour in day (1~24) hour in am/pm (0~11) time zone escape for text single quote

Text

Number)

Number

Text

Delimiter

Literal

Number

Text

Number

Presentation

Text

Number

Text & Number

Number

Example

1996

July & 07

978

Tuesday

189

2 (2nd Wed in July)

Pacific Standard Time

Logging and Tracing

Here are some sample formats:

Sample

MM-dd-yyyy

Explanation

Two digits for the month, two digits for the day, and four digits for the year.

MMMM-dd-yyyy The month spelled out, two digits for the day, and four digits for the year.

yyyyMMddHHmmssSSSS A 4-digit year, 2-digit month, 2-digit day, 2-digit hours in day, 2digit minutes in day, 2-digits seconds in a minute, and 4-digit milliseconds in a second.

In this format, sorting alphabetically is the same as sorting by date.

As a Log4j Appender, the IDSFileAppender has several parameters that are set in the logging configuration file, usually named

logconf.xml. The parameters are:

Parameter Description

File The name of the file to write. This can be a static file name or a dynamic file name created using the above options.

Append

If True, the next logging message is appended to the end of the file. If false, the file is first erased. The default is True.

If True, the file is closed after the message is written. This can be useful if you want to edit, move, or delete the file while IDS is still running. The default is

False.

If the name of a file changes between two logging calls, for example if you are using

~LASTRESTART and IDS is restarted, or if you are using ~CURRENTTIME and the time changes by a sufficient amount, the old file is automatically closed.

Using combinations of Append and Close can produce different effects. With Append as

False and Close as True, only one logging message will be in the file at any time. This can be handy when debugging messages passed in and out of IDS.

If Append is True and Close is False, the file acts like a regular FileAppender. In fact, if you are running only one instance of IDS and you do not want to change the file name, use the regular FileAppender since it is slightly faster than the IDSFileAppender.

IDSFileAppender has to re-evaluate the file name for each logging message. Setting

Append to True and Close to True gives you an ever-growing file that you can move, delete, edit, and so on.

Here are some examples:

The IDSFileAppender is used in the

appender elements in the logging configuration.

Chapter 2

Using the Internet Document Server

</layout>

</appender>

This produces a separate log file for each instance of IDS. If there are a total of three instances running, a primary and two secondaries, these log files are created:

• server-0.log

• server-1.log

• server-2.log

</layout>

</appender>

This produces a log file and which is written to until the hour changes. The system then starts writing to a new file. The date/time formatting is for the month, day, and hour, so on October 15, from noon until 1 pm, logging entries are written to the

server-101512.log file. From 1 pm to 2 pm, logging entries are written to the

server-101513.log file, and so on.

SING

OGGING

ATEGORIES

To make it easier to debug problems in IDS, you can use logging categories to sort messages IDS receives from client programs and messages it sends to client programs.

You can have the system treat all messages the same or distinguish between messages from message queues (WebSphere MQ or JMS) and messages from HTTP.

Combining the use of the message categories with options in the IDSFileAppender provides the same functionality as the

send.msg and receive.msg message debugging of IDS version 1.8, but also allows other options.

The categories are as follows:

• SendMessage.queue

• ReceiveMessage.queue

• SendMessage.http

• ReceiveMessage.http

As with other Log4j categories, the categories are hierarchical, so using category names

SendMessage and ReceiveMessage will use the same category for both queue and HTTP-based messages.

Since the messages are handled as Log4j categories, they can have all the destinations of other categories, such as files, the NT Event logger, email, and so on.

Here are some examples. When looking at the examples, remember that for each request, a message is first received by IDS then a message is sent.

Logging and Tracing

This combination of categories and appenders gives the same behavior as in IDS version

1.8. When the categories are set to

DEBUG, any received messages are placed in the receive.msg file. Any sent messages are placed in the send.msg file. When new messages are processed, either by queues or HTTP, they are placed in the receive.msg and send.msg files.

</layout>

</appender>

</layout>

</appender>

<appender-ref ref="receivemessage" />

</category>

<appender-ref ref="sendmessage" />

</category>

This set of categories and appenders puts the received messages and sent messages in the same file, with one file for each instance of IDS that is running. Since Append is False for receiving and Append is True for sending, this file is overwritten for each receive/send pair. The header

Received: is added in front of the received message and Sent: is placed in front of the sent message.

</layout>

</appender>

Chapter 2

Using the Internet Document Server

</layout>

</appender>

<appender-ref ref="receivecombined" />

</category>

<appender-ref ref="sendcombined" />

</category>

In this example you distinguish between messages handled by the queues and messages handled by HTTP. The queue messages are placed in receive.msg and send.msg, but since the HTTP messages are handled simultaneously by multiple threads, the HTTP messages include the thread ID in the file names.

The system also notes the categories and sub-categories. In the categories with HTTP,

additivity is set to False, meaning the HTTP categories should not use appenders from the

SendMessage and ReceiveMessage categories.

</layout>

</appender>

</layout>

</appender>

</layout>

Logging and Tracing

</appender>

</layout>

</appender>

<appender-ref ref="receivemessage" />

</category>

<appender-ref ref="sendmessage" />

</category>

<appender-ref ref="receivehttp" />

</category>

<appender-ref ref="sendhttp" />

</category>

OGGING

NFORMATION ABOUT

EQUESTS

IDS lets you store information about a request in a database for later viewing or processing. IDS logs information about a request (transaction) in any Java Database

Connectivity (JDBC) compliant database. You can find additional information about

JDBC at http://java.sun.com/products/jdbc/

On Windows computers, Open Database Connectivity (ODBC) is available, and Java has built-in drivers to ODBC connections.

Request logging automatically rolls over and starts new database tables on a daily or weekly basis and you can configure IDS to automatically delete old database tables. The configuration file can specify how many days or weeks of log tables to keep when purging old tables.

Chapter 2

Using the Internet Document Server

OTE

Set up a separate database for IDS transaction logs. When purging old tables,

all tables that do not qualify as the most recent transaction logs are deleted from the database.

IDS lets you use a browser to display request logs and sort and filter the requests. You can display logs from just a single database table or from multiple tables.

When IDS sends result messages back to client programs, it includes these message variables:

Variable Description

IDSHOSTNAME Contains the host name of the machine running IDS.

IDSGUID Cntains the unique ID for the running instance of IDS.

Request logging configuration

With this information you can track a message back to a particular instance of IDS running on a particular machine, even if all messages are logged to a common place.

To add this capability, go to the DOCSERV.XML configuration file and find the

BusinessLogicProcessor section. Then create a TransactionLogDatabase subsection, as shown here:

<entry name="class">sun.jdbc.odbc.JdbcOdbcDriver</entry>

<entry name="time.type">weekly</entry>

<entry name="time.startofweek">monday</entry>

<entry name="Reqtype">REQTYPE</entry>

<entry name="UserID">USERID</entry>

<entry name="Password">PASSWORD</entry>

</section>

Parameter

class

URL userid password

Description

The JDBC Java class that connects to the database. In this example, we are using Java's built in ODBC connectivity in Windows.

The JDBC-based name of the database that tables will be written into. This will vary for different JDBC drivers, but somewhere will include the database name, in this case TRAN_LOG. Consult your JDBC driver documentation on setting up this URL.

The user name for logging in to the database.

The password for the specified user name.

Logging and Tracing

Parameter

time.type

time.count

time.startofweek

close.database

columns

Description

Either

daily or weekly, specifying how often to roll over into a new database table.

How many of the most recent tables in the database to keep when deleting old tables. This will be either the most recent days or weeks worth of information, depending on the time.type setting.

When time.type is weekly, this specifies what day of the week to start a new database table.

Whether or not to close the database after writing a transaction to the transaction database. Setting this to Y or N will depend on how many database connections are available to the database and how often transactions are logged.

This subsection holds any number of entries specifying the column names in the database. The entry name is the name of the column that will be used in the database. The entry value is the name of the message variable in the output that will be written in the column.

Accessing the transaction database through IDS

IDS includes requests and HTML pages to let a user view the transaction log database from a browser. To begin, start a web browser and go to this URL http://localhost:49152/request?REQTYPE=LOGMETADATA

localhost:49152 refers to the IP address and port that IDS is set up for HTTP messaging.

You will see a screen similar to this:

The Transaction Log Date field specifies which day's worth of records that results will be pulled from. Use the calendar button next to this field to pick another date. If data is being collected in weekly mode, you can check the View All Log Entries field to select data from all the records in a week's database table, not just the data for one day.

Chapter 2

Using the Internet Document Server

The Field column lists all the data fields you can display. You can choose individual fields or select them all. The numeric drop-down box next to each field name can be used to select the display priority. The first fields to display will have a display priority of 1, then all fields with a display priority of 2, and so on.

The Filter field lets you filter each field by a value. Enter a value for filtering, then choose an operation to perform on the filter.

Use the Order By column to sort a column's information, ascending or descending. The numeric drop-down box picks the ordering priority, with 1 having the highest priority.

After you pick the settings and click Submit, a screen similar to this one appears:

Accessing the transaction database directly

All the previously selected columns appear. Use the Previous and Next buttons to move through the selected records. Click Return to Query to return to the selection page.

Since the transaction database is a regular JDBC compliant database it can be accessed through any database program that uses JDBC or the database's native format. This section explains the naming and data format conventions used in the transaction database.

The database name is just the name of the database set up by you or your database administrator.

The names of tables in the database will all start with the string

TRANLOG followed by the date that data is first written into the table. The format is shown here:

TRANLOGyyyymmdd

Parameter Description

TRANLO

All tables start with this string.

yyyy mm

Year

Month (01 - 12)

Logging and Tracing

Parameter Description

dd Day of the month (01 - 31)

For example, a table starting on September 1, 2003 would be named:

TRANLOG20030901

Each row in the database table begins with a column named

TRANSACTIONTIME, a

23-character string that is the key for the row. In SQL, this is known as a

CHAR(23). The string is the time of the transaction, to millisecond precision, formatted in a way that sorting the table on the column sorts the logs by date and time recorded. The format is: yyyy/mm/dd:hh:nn:ss.xxx

hh nn ss xxx

Parameter Description

yyyy Year mm dd

Month (01 - 12)

Day of the month (01 - 31)

Hour in the day (00 - 23)

Minute in hour (00 - 59)

Second in minute (00 - 59)

Millisecond in second (000 - 999)

The names of the other columns in the table row are generated from the IDS configuration, and each column type is a variable-length string, known in SQL as a

VARCHAR(255).

UERYING

RANSACTION

NFORMATION

You can use the getMetaData and the QueryTranLogs Java rules to query transaction information. These rules let you monitor information such as the amount of server time spent for each request, the requests that failed, user IDs, and passwords.

These rules use the TransactionLogDatabase section in the docserv.xml file to build a connection to the log database.

OTE

See Logging Information about Requests on page 86 for information on how to set up the transaction log database.

You can use the logmetadata and logrecords XSL templates with the version 2.

HTTP server to query transaction information from the log database. Information can be found by matching a table name based on the date specified in the web user interface, the time type (daily or weekly) for the table, and the starting day for the table.

Here is an example of a URL that uses the web interface:

Chapter 2

Using the Internet Document Server

88 http://localhost:49152/request?reqtype=logmetadata

getMetaData

This rule displays meta-data about the log database. The rule returns the field count, which is the number of fields available in each table. This information is set up in the

TransactionLogDatabase section of the docserv.xml file. The rule also returns each of the field names that correspond to the field count and the TransactionLogDatabase section.

Field names are returned as attachment variables field

1 through fieldn, where n is the field count. The getMetaData rule also returns the table time type being used for the transaction log database which can be daily or weekly.

This information is set up in the TransactionLogDatabase section of the XML file. The rule also returns a table count which corresponds to the number of tables currently present in the log database. Furthermore, the rule also returns each table name as attachment variables table

1 through tablen, where n corresponds to the table count value.

Input attachments

Variable Description

REQTYPE LOGMETADATA

Output attachments

Variable

FIELDCOUNT

FIELD1...FIELDn

Description

The number of fields in each table within the transaction log database.

The name of each field in the transaction log database tables, where

n corresponds to FIELDCOUNT.

TABLETIMETYPE The table time type, a setting in the TransactionLogDatabase section of the docserv.xml file.

TABLECOUNT The number of tables present in the transaction log database.

TABLE1...TABLEn

The name of each table present in the log database, where

n corresponds to TABLECOUNT.

OTE

Use this rule with the logmetadata xslt template and the HTTP server that comes with version 2.

. Keep in mind you must first set up logging (see Logging

Information about Requests on page 86 ) before you can use this rule.

Here is a sample URL: http://localhost:49152/request?reqtype=logmetadata

Here is a sample request type:

<entry name="function">atcw32->;ATCLogTransaction</entry>

<entry name="function">java;com.docucorp.ids.rules.

IDSTransactionRule;;static;reportTimes;INCLUDEMS</entry>

<entry name="function">atcw32->;ATCLoadAttachment</entry>

Logging and Tracing

<entry name="function">irlw32->;IRLCopyAttachment</entry>

<entry name="function">java;com.docucorp.ids.rules.

TransactionLogRSRule;;transaction;getMetaData;</entry>

</section>

QueryTranLogs

Use this rule to query the transaction log database and return a recordset of transactions.

OTE

See Logging and Tracing on page 77 for information on how to set up the transaction log database.

Input attachments

Variable

REQTYPE

SQLCMD

SQLTABLENAME

SQLFIELDS

SQLWHERE

SQLORDERBY

SQLTIMEOUT

SQLABSOLUTEPAGE

SQLPAGESIZE

SQLEXACTMATCH

Description

The request type that contains the QueryTranLogs rule. This should be LOGRECORDS when you are using the logrecords.xsl template.

(Optional) An SQL select statement for the query.

(Optional) The table name of the database log that is to be queried, such as TRANLOG20030121.

(Optional) A comma delimited list of selection fields to use for to the query. Here is an example: reqtype,results,userid,password

(Optional) The filters specified for the query. Here is an example: reqtype like 'sss%' and userid = 'FORMAKER' and password <> 'I'

(Optional) The sort order criteria to use in the query, such as: reqtype asc, password desc, userid asc

(Optional) The SQL connection time-out, specified in seconds. The default is 300 seconds.

(Optional) The current page to display for the query. This is used in recordset paging. The default is one (1).

(Optional) The number of records to return for a query. The default is 10.

(Optional) Enter Yes if the system should only display the records for the date specified. Enter No if you want it to display all the records in the current table.

Output attachments

Variable

SQLCMD

SQLPAGESIZE

Description

The generated SQL query string.

The number of records returned for the query.

Chapter 2

Using the Internet Document Server

Variable

FIRSTPAGE

LASTPAGE

Description

Returns True if the records returned for the query are the first page.

Otherwise, the system returns False.

Returns True if the records returned for the query are the last page.

Otherwise, the system returns False.

The number of fields used in the query.

SQLSELECTION

FIELDCOUNT

SELECTIONFIELDS A rowset containing the names of each of the fields returned by the query.

RECORD1....RECORDn

Rowsets for each record returned in the query, where n is the last record returned in the query. (this value should be equal to that of

SQLPAGESIZE if LASTPAGE is False)

OTE

Use this rule with the logrecords xslt template and the HTTP server that comes with version 2.0 or higher.

By default the rule tries to use the SQLCMD input attachment. If it is not found or its value is omitted, the rule then tries to build a select statement using the

SQLTABLENAME, SQLFIELDS, SQLWHERE, and SQLORDERBY input attachment variables.

Here is a sample request type:

<entry name="function">atcw32->;ATCLogTransaction</entry>

<entry name="function">java;com.docucorp.ids.rules.

IDSTransactionRule;;static;reportTimes;INCLUDEMS</entry>

<entry name="function">atcw32->;ATCLoadAttachment</entry>

<entry name="function">irlw32->;IRLCopyAttachment</entry>

<entry name="function">java;com.docucorp.ids.rules.

TransactionLogRSRule;;transaction;QueryTranLogs;</entry>

</section>

ONITORING

ERFORMANCE

TATISTICS

IDS lets you use Java Management Extensions (JMX) to monitor performance data. This lets external JMX monitoring applications track performance data and is similar to SNMP support.

JMX support is built-in to Java versions 1.5 and higher, but IDS includes JMX libraries that let you monitor IDS with Java 1.4 versions. For Java 1.4 versions, IDS uses the JMX

Message Protocol (JMXMP), based on Sun's Reference Implementation of the JMX

Remote API.

In the docserv.xml configuration file, in the DocumentServer section, create a JMX subsection, as shown here:

Logging and Tracing

</section>

The

Enabled entry determines whether JMX support is enabled. The default is No.

The

JMXMP entry is the TCP/IP port where the JMX Messaging Protocol (JMXMP) will be supported. Each instance of IDS will have its own JMXMP port starting with this number. If you omit this entry, JMXMP support is not enabled.

In addition to compiling application-wide statistics automatically, IDS can also track performance times for a specific request or for a specific function in a request. You can set this up in the configuration. In the DocumentServer section, create a

StatisticsMonitors subsection, as shown here:

</section>

To monitor an entire request, enter the request's name, such as

SSS. To monitor a specific function within a request, specify the request's name, a slash (/), and the line number of the function inside the request, such as

SSS/5.

For each monitor you list, IDS tracks the most recent timings for the Initialize, Run

Forward, Run Reverse, and Terminate messages, and the total time for all messages run.

For general information about JMX, see: http://java.sun.com/products/JavaManagement/

Windows

UNIX

ENERATING A

OGGING

ONFIGURATION

ILE

IDS includes a LogConfConvert.xsl template which you can use to generate a logconf.xml file from the docserv.xml file.

The template takes into account the XMLMessage, XMLMessageAppend,

TransactionTime, and RuleTime options in the Debug section of the docserv.xml file during the generation of the logconf.xml file.

A logconfcovert script file is also included in the docserv directory which you can use to run the command necessary for the conversion process, as shown here: java -cp .;.\lib\DocucorpUtil.jar com.docucorp.util.XslTransformer source=docserv.xml template=LogConfConvert.xsl output=logconf.xml

java -cp .:./lib/DocucorpUtil.jar com.docucorp.util.XslTransformer source=docserv.xml template=LogConfConvert.xsl output=logconf.xml

SING

OGGING

ATEGORIES TO

CCESS THE

NTERNAL

Chapter 2

Using the Internet Document Server

ORMAT OF

EQUESTS

To make it easier to debug problems which can occur when translating requests and results, the system includes logging categories you can use to see the internal data format of received requests and sent results. The categories are as follows:

• DSIMessage.ReceiveMessage.queue

• DSIMessage.SendMessage.queue

• DSIMessage.ReceiveMessage.http

• DSIMessage.SendMessage.http

As with other Log4j categories, the categories are hierarchical so using category names

DSIMessage.SendMessage and DSIMessage.ReceiveMessage will use the same category for both queue and HTTP-based messages.

Since the messages are handled as Log4j categories, they can have all the destinations of other categories, such as files, the NT Event logger, email, and so on.

A combination of categories and appenders will add the internal data format of messages to the end of receive.msg and send.msg files, adding useful information about how the messages are translated.

Use the following Log4j appenders to add the internal data information to the receive.msg and send.msg files:

</layout>

</appender>

</layout>

</appender>

Use these appenders with the following Log4j categories:

<appender-ref ref="dsireceivemessage"/>

</category>

<appender-ref ref="dsisendmessage"/>

</category>

Configuring IDS

ONFIGURING

IDS

The IDSConfig program lets you perform the following tasks to make it easier to configure IDS:

• Running IDSConfig on page 97

• Creating New Files on page 97

• Adding Nodes on page 97

• Adding Nodes with Text on page 97

• Editing Nodes on page 98

• Copying Nodes on page 98

• Moving Nodes on page 98

• Adding Attributes on page 98

• Adding Comments on page 99

• Adding Text on page 99

• Adding a Request or Function on page 99

• Adding an IDS Function on page 99

• Converting DOCSERV.INI or DOCCLIENT.INI Files into XML Format on page

100

• Adding a Section or Entry on page 100

• Locating Text on page 100

• Importing Configuration Information on page 100

• Configuring MQSeries Buffer Sizes on page 101

• Testing File Transmission on page 102

Chapter 2

Using the Internet Document Server

Running IDSConfig

To run the IDSConfig program, use the syntax shown below: java -classpath <path to xerces.jar>;<path to xalan.jar>;<path to

DocuCorpUtil.jar>;<path to idsconfig.jar> com.docucorp.idsconfig.idsconfig

Here is an example: java.exe -classpath d:\jars\xerces.jar;d:\jars\xalan.jar;d:\jars\DocuCorpUtil.jar; d:\jars\idsconfig.jar; com.docucorp.idsconfig.idsconfig

OTE

To run IDSConfig, you must have idsconfig.xml and idsrules.xml stored in the working directory.

Creating New Files

To create a new file, follow these steps:

Select the File, New option.

Select the appropriate type of configuration file: client or server.

Depending on the type of configuration you chose, the system creates a new XML file base or template file named either docservtp.xml or docclienttp.xml.

Adding Nodes

Follow these steps to add a node:

Choose one of these options:

Right click the parent node to which you want to add a child node.

Select the parent node, then choose the Edit, Add Node option.

Select the parent node, then click the Add Node button.

Select the parent node, then press I

NSERT

Enter the name you want to assign to the node and click Ok.

Enter

Text if you want to create a Text node. Otherwise, leave it blank.

Adding Nodes with Text

Follow these steps to add a node with text:

Choose one of these options:

Right click the parent node to which you want to add a child node.

Select the parent node, then choose the Edit, Add Node option.

Select the parent node, then click the Add Node button.

Configuring IDS

Select the parent node, then press I

NSERT

Enter the name you want to assign to the node and click Ok.

Enter

Text and click Ok.

Editing Nodes

Follow these steps to edit a node:

Click once to select the node. The system highlights the node.

Press F2 or click again to edit the node.

Press E

NTER

when finished or press E

at any time to cancel editing.

Move as a child node

Move as previous node

Copying Nodes

Follow these steps to copy a node:

Click to select the node you want to copy.

Press and hold the C

TRL

key while dragging the source node onto the destination node. Drop the source node by releasing the mouse button.

The system copies the source node and adds it as a child of the destination node.

Moving Nodes

There are two ways to move nodes:

Select the node you want to move.

Drag and drop the source node onto the destination node.

The system adds the source node as a child of destination node.

Select the node you want to move.

Press and hold the S

HIFT

key, then drag and drop the source node onto the destination node.

The system inserts the source node before the destination node.

Adding Attributes

Follow these steps to add attributes:

Right click the attribute header.

Select the Add Attribute option.

Enter the value of the attribute and press E

NTER

Chapter 2

Using the Internet Document Server

Adding Comments

Follow these steps to add comments:

Choose one of these options:

Right click the node to which you want to add a comment and choose Add comment from the popup menu

Select the node, then click the Add comment button.

Select the node, then press C

TRL

+M.

Enter your comment and click Ok when you are finished.

Adding Text

Follow these steps to add text:

Right click the node to which you want to add text.

Select the Add Text option.

Enter the text. Press E

NTER

when finished or E

to cancel.

Adding a Request or Function

The IDSConfig program provides a quick way to add request types and functions. Follow these steps:

Right click on the Configuration and select the Add Request option.

Enter the name of the request type and click Ok.

Right click on the section name you just added and select the Add Function option.

Type in the name of the function you want to add and press E

NTER

The new function is added to the request type node.

Adding an IDS Function

The IDSConfig program provides a quick way to add an IDS function.

OTE

Be sure to store the functions you add in the idsrules.xml. file.

Right click on the node to which you want to add functions and select Add

IDSFunction. The Add IDS Function window appears.

Use the S

HIFT

and C

TRL

keys to select multiple functions in the Basic Functions area.

Once you have selected the functions you want to add, drag them into the

Destination area or click the >> button.

Configuring IDS

OTE

You can rearrange the order of the functions in Destination area using your mouse.

Click Ok when you are finished.

Converting DOCSERV.INI or DOCCLIENT.INI Files into XML

Format

You can use IDSConfig to convert a DOCSERV.INI or DOCCLIENT.INI file into an

XML format file.

Select the File, Convert INI file option.

Enter the following information:

The name of the INI file you want to convert

The name you want assigned to the XML output file

The name of the XSL file (DocumentClientConvert.xsl or

DocumentServerConvert.xsl) and the MQ Series Server if it exists

Click Start to start the conversion. Click Close when it finishes.

Adding a Section or Entry

Follow these steps to add a section or entry

Right click the node to which you want to add a section or entry.

Select the Add Section or Add Entry option.

If you are adding a section, enter the section name

If you are adding an entry, enter the entry name and text

Click Ok when you are finished.

Locating Text

You can use Find and Find Next to locate text.

Click to select the beginning searching node.

Press C

TRL

+F, then enter the text and click Find to start searching. The system locates the matching text.

You can continue searching the same text by pressing F3.

Importing Configuration Information

You can import configuration information into your main configuration file. IDS lets you import configuration information into either the older IDS version 1.x INI configuration files or the newer IDS version 2.x XML configuration files.

Chapter 2

Using the Internet Document Server

Most control groups (INI) or sections (XML) of the imported configurations are added to the end of the main configuration file. This means that if there are control groups or sections with the same name in both the main configuration and in the imported configurations, the entries in the control group or section in the main configuration takes precedence. These control groups and sections, however, are exceptions to this rule:

• ReqType:INI

• ReqType:THREADINI

• ReqType:SAR

If these control groups or sections exist in the imported configurations, the entries in the imported control groups and sections are merged into the corresponding control groups or sections in the main configuration file — so in this case the entries in the imported file take precedence.

Here is an example section from an XML-based configuration file:

<entry name="import">documanage_requests.ini</entry>

<entry name="import">ipps_requests.ini</entry>

</section>

OTE

In version 2.1 and later, IDS detect changes to imported configurations via the

INIFiles or configuration-imports sections in the docserv.xml file and reload them into memory when there is a change.

Configuring MQSeries Buffer Sizes

You can increase the default buffer size of MQSeries messages and make the buffer size a setting you can maintain with a configuration entry.

• In server configuration files, the entry is put in the "BusinessLogicProcessor" section, "messaging" subsection, "queue" subsection.

• In client configuration files, the entry is put in the "DocumentClient" section,

"messaging" subsection, "queue" subsection.

The entry is:

This setting indicates the initial size of the buffer allocated to hold an incoming message.

If the message is larger than this size, a buffer is allocated that is large enough to hold the message and the application tries again. The default is 131072 (128K).

If you know that most of your messages will be smaller than 128k, you can decrease the buffer size for lower overhead for memory allocation. If, however, the majority of your messages will be larger, increase the buffer size to avoid situations where it takes multiple getMessage calls to get a message.

Configuring IDS

Testing File Transmission

Use the DSITEST utility to test the transfer of files to and from IDS. Here is an example of the syntax and parameters for this utility:

OTE

By default, the DSITEST utility runs in Java mode. You can, however, run it in

C mode. To switch modes, open DSITEST in a text editor and follow the instructions at the beginning of the script.

Syntax dsitestw /time /waitonlast / display /nowait /reqtype /msg /notrans

/noattachs /norcvs /atcfile /rcvfile

Parameter

Time

Description

Displays total seconds for all operations.

Do not include NoRCVs, ATCFile, or RCVFile with this parameter because those parameters contain user prompts that affect the time.

WaitOnLast Waits on the last message before capturing the ending time.

Display Displays the resulting DSI Soap XML message that contains the name/value pairs for each transaction.

NoWait

ReqType

MSG

NoTrans

NoAttchs

Do not wait for the server before adding next message to queue.

The IDS request type. The default is SSS.

The name of the file that contains the request name/value pairs.

The total number of transactions to process.

NoRCVs

ATCFile

RCVFile

The total number of file attachments to send per transaction using the

DSISendFile API. If you include this parameter, the program expects an input file named SENDFILES.MSG that contains the information for each attachment to send.

The total number of file attachments to receive per transaction via the

DSIReceiveFile API. If you include this parameter, the program expects an input file named RECEIVEFILES.MSG that contains the information for each attachment to receive.

A single file attachment to send via the DSISendFile API. The program prompts the user for the attachment ID, file name, and encoding type.

A single file attachment to receive via the DSIReceiveFile API. The program prompts the user for the attachment ID and file name.

Neither the case nor the order of the parameters is important.

You can include these parameters on the command line or place them in an input file named PARAMS.MSG. On the command line, separate parameters with slashes (/), dashes (-), or spaces:

DSITESTW /time=yes

DSITESTW -time=yes

Chapter 2

Using the Internet Document Server

DSITESTW time=yes

If you include the parameters in the PARAMS.MSG file, format them as shown in this example of the PARAMS.MSG file: time=yes waitonlast=no display=yes nowait=no reqtype=LGN notrans=50 msg=prt.msg noattchs=0 norcvs=0 atcfile=yes rcvfile=yes

Here is an example of how you could execute this program from the command line: dsitesw time=yes display=yes notrans=2 reqtype=prt msg=c:\prt.msg

Here is an example of the PRT.MSG file:

USERID=FORMAKER

Arckey=00345A0D5600000008 reqtype=PRT config=RPEX1 company=1199999 lob=Lee policynum=Roswell, Ga 30015 rundate=021705 printpath=\10.8.10.137\Websrvr_client\html

If the NoAttchs parameter is greater than zero, the program expects an input file named

SENDFILES.MSG which contains a list of the attachments to send. Use either

NoAttachs or ATCFile, but not both.

Use the ATCFile parameter when you only want to send one file attachment. The

ATCFile parameter uses command line parameters for the attachment ID, file name, and encoding type. Here is an example of the ATTACHMENTS.MSG file: name=RPEX1INI file=X:\IDS\AddlSrvrs\rpex1.ini type=TEXT name=TESTPDF file=X:\websrvr_client\html\test.pdf type=BINARY

If the NoCRVs parameter is greater than zero, the program expects an input file named

RECEIVEFILES.MSG, which contains a list of attachments to receive. Include either

NoRCVs or RCVFile, but not both.

100

Configuring IDS

Use the RCVFile parameter when you only want to receive one attachment. The RCVFile parameter uses command line parameters for the attachment ID and file name. Here is an example of the RECEIVEFILES.MSG file: name=PDFFILE1 file=X:\\IDS\\AddlSrvrs\\Output\\file1.pdf name=PDFFILE2 file=X:\\IDS\\AddlSrvrs\\Output\\file2.pdf

If you omit the request type from the command line or the PARAMS.MSG file, the program uses SSS as the default request type.

101

Chapter 2

Using the Internet Document Server

EFERENCING

TTACHMENT

ARIABLES

IDS lets you reference the attachment variable from an INI file. You can use this technique with the DAP.INI, CONFIG.INI and DOCSERV.XML files.

OTE

This capability was previously added for the ATCSendFile and ATCReceiveFile rules. With version 2.

x , this capability should work for all requests and rules in

DOCSERV.XML, as well as the other sections imported from a DOCSERV.INI file.

Here is an example of how you reference an attachment variable via an INI option:

< Group >

Option = ~GetAttach VARNAME,QUEUE

To reference a message variable in a configuration XML file use the following syntax:

<entry name="Option">~GetAttach VARNAME,QUEUE</entry>

</section>

The VARNAME is the name of the variable. QUEUE specifies which queue to search for this value. For example, assume the attachment variable PRINTERTYPE specifies the printer type to use for output. IDS rules use this configuration XML option to determine the printer type (<Print>, PrtType =). In this case, you can modify the XML file as shown here:

<entry name="PrtType">~GetAttach PRINTERTYPE,INPUT</entry>

</section>

So when the rule gets a configuration option, the value will equal the value of the input queue variable PRINTERTYPE. When the rule gets a configuration XML option, the value equals the value of attachment variable PRINTERTYPE.

OTE

If ~GetAttach does not find the attachment variable it returns an empty string.

You can also use this to dynamically specify the file extension for the file created by

ATCReceiveFile rule when you want to import that file into Documanage. You can do this as shown here in the DOCSERV.XML file:

<entry name="function">atcw32->ATCReceiveFile,IMPORTFILE,V2IMP,*.

~GetAttach FILETYPE,INPUT,KEEP</entry>

The ATCReceiveFile rule finds the attachment variable FILETYPE and uses its value as the file extension of the generated file name. Note that there are no spaces between the asterisk and period (*.) and the tilde (~) prefacing

GetAttach. If you include a space there, it will also be in the file extension.

102

Referencing Attachment Variables

OTE

The IDS attachment variable contains the printer value for each recipient. Here is an example:

AGENT_OUTPUT=PRINTER1

The client code should be able to find URLPRINTER1 to determine the output file name.

SING

NICODE IN

TTACHMENT

ARIABLES

IDS supports Unicode, via UTF-8 encoding, in the setting and retrieving of values from attachment variables. The support is implemented via functions and defined constants in the DSILIB library. These functions are:

DSIAddAttachVarEx

DSIAddToAttachRecEx

DSILocateAttachVarEx

DSIAttachVarLengthEx

DSIAttachCursorFirstEx

DSIAttachCursorNextEx

DSIAttachCursorPrevEx

DSIAttachCursorLastEx

DSIAttachCursorValueEx

DSIAttachCursorValueLengthEx

DSIEncryptValueEx

These functions are similar to the

base versions of the functions, but have an extra encoding parameter that you can set to either DSIENCODING_SINGLE_BYTE or

DSIENCODING_UTF_8.

For example, when adding an attachment variable you can use...

DSIAddAttachVar(hdsi, DSI_OUTPUTQUEUE, "FIELD", szValue); or

DSIAddAttachVarEx(hdsi, DSI_OUTPUTQUEUE, "FIELD", szValue,

DSIENCODING_SINGLE_BYTE); or

DSIAddAttachVarEx(hdsi, DSI_OUTPUTQUEUE, "FIELD", szValue,

DSIENCODING_UTF_8);

When using the base versions of these functions, the default encoding is

DSIENCODING_SINGLE_BYTE, so the first two function calls would do the same thing.

DSIENCODING_SINGLE_BYTE uses Codepage 1252 encoding, which has a one-toone mapping between bytes and Unicode characters between 32 and 255,

except from 128 to 159, which maps some Unicode characters down into this range. For example, the

Unicode character for the Euro symbol (hex 20ac) is converted to a 128 (hex 80) and vice versa. This makes IDS compatible with how Documaker handles the Euro symbol.

103

Chapter 2

Using the Internet Document Server

DSIENCODING_UTF_8 uses UTF-8 encoding, which is a way to translate Unicode multibyte characters into a format compatible with null-terminated C language strings while retaining all the character information.

104

Using the Message Queues

SING THE

ESSAGE

UEUES

Docupresentment lets you use a queueing system that is based on an in-memory operation. This eliminates the need to use MQSeries in low volume production systems.

Choosing the Right Queuing Options

Choosing the right queueing options for your company can be a difficult process. There are several scenarios, as this table shows:

Installation

Single PC with a single server

Function

Used for demos and development. Not recommended for production use, even with low volumes.

Single PC with multiple servers

Multiple PCs with multiple servers

Here, multiple Docupresentment servers are set up on a single PC. This is recommended for low volume production systems. IDS cannot be a single point of failure because if one instance stops responding, the other instances pick up the work.

Here, multiple Docupresentment servers are installed on multiple PCs. This is recommended for high volume production systems.

To evaluate your system, answer these questions:

Is it a production system?

If yes, go to step 5.

If no, go to step 2.

Do you intend to use this system for performance testing?

If yes, go to step 5.

If no, go to step 3.

How many users will your system be servicing?

If more than one, go to step 5.

If only one, go to step 4.

Your system is demo or development system and you can use a single PC with a single server. You can use

HTTP. You can also use JMS or MQSeries, as they are a step up from HTTP queues.

Your system requires multiple servers. Go to step 6.

How many simultaneous users does your system need to handle? The common way to determine this is calculate 5% of the maximum number of users.

If your system must handle more than five simultaneous users, go to step 8.

If it only needs to handle less than five simultaneous users, go to step 7.

Your system is a low volume production system and can be set up as a single PC with multiple servers. For this scenario use JMS or MQSeries.

105

Chapter 2

Using the Internet Document Server

Your system is a high volume production system and should be set up as multiple

PCs with multiple servers. Use JMS or MQSeries.

This table summarizes the recommended queuing options:

PCs

Single

Multiple

Servers

Single

Multiple

Use this queue

HTTP. You can also use JMS or MQSeries, as they are a step up from HTTP queues.

JMS or MQSeries. HTTP can be used.

JMS or MQSeries. The use of HTTP queues is not recommended.

OTE

The default message queue handler for IDS 2.

is differs from that used for prior versions. In prior versions, IDS used xBase queues which placed messages in a physical file on disk. In version 2.0 or later, IDS uses a messaging system based on HTTP.

You do not have to do anything for the message queue system to work. All queue setup options have default values. Furthermore, any attempt to communicate with IDS will cause IDS to start if it has not already been started. It is, however, possible default port values may conflict with an application already in use, so you may have to make modifications in some cases.

Understanding the Router Process

You can use the HTTP router application to enable the client to communicate with multiple IDS servers. This application controls IDS processes and starts them as needed.

The client can start this process if it fails to connect to IDS. The router is a Java application that can be started manually with the file idsrouter.bat (idsrouter.sh on UNIX platforms).

Middleware queuing systems usually have the option to save messages that are not successfully delivered to their destination. The IDS router application also has the option to do this. Any messages it receives can be stored in a JDBC compliant database and they are automatically removed when they are sent to an instance of IDS. If the IDS router is stopped, any undelivered messages that are stored will be sent to IDS when the IDS router is started up again. The HTTP connections to client programs would be severed at this point, but the messages would still be processed by IDS (for example, to ensure archiving operations are done).

The default database settings for the IDS router uses a file-based database, so no database administration or startup of external processes are required. If you are going to use a different database, you will need to obtain the JDBC drivers for the database from your database administrator (usually in the form of JAR or ZIP files) and add these files in the

lib subdirectory under your IDS installation directory.

Under Windows platforms, the router process will have its own DOS window. If you press C

TRL

+C inside this DOS window, the router terminates and shuts down any instances of IDS it has started.

106

Using the Message Queues

Under Unix platforms, the router process will write its process ID to a file named

router-

pid. Sending a SIGINT (signal 2) to this process ID will cause the router to terminate and shut down any instances of IDS it has started. This is usually done with the 'kill' command in a separate terminal.

How HTTP Queues are Handled

Here is an overview of how the queues work by default:

When client tries to send a message it attempts to get a TCP/IP connection. If the connection fails, the client tries to start the router.

The router starts IDS instances if necessary. Two IDS instances are started by default.

The client program sends the message to the router process.

The router process gets the message and sends it to one of the instances of IDS.

IDS returns the response back to router.

The router process returns the message back to the client that initiated the transaction.

Here is an overview of how the system typically gets an IP address and port number. Keep in mind the HTTP queue system, by default, needs ports from 49152 to 49154 and all default IP addresses are localhost.

The client tries to talk to the router process on port 49152.

When the client starts the router process, it passes port 49152 to it.

The router process listens on port 49152.

When router starts the first instance of IDS, it passes port 49153 to it.

The primary IDS listens on port 49153 as it was passed as a parameter from the router.

The primary IDS starts the next IDS and passes port 49154 (incrementing its own port address by one).

The secondary IDS listens on port 49154.

Using the Router Section

In the DOCSERV.XML file, the router program uses the same settings in

DOCSERV.XML as IDS, as much as possible, to simplify setup. The settings used by both IDS and the router include the http port to listen to, the arguments for starting instances of IDS, and the number of instances to start.

There is an additional Router section in the configuration file for enabling and setting up the JDBC database that stores undelivered messages. This example shows the defaults:

107

Chapter 2

Using the Internet Document Server

<entry name="StartCommand">"INSTALLDIR/jre/bin/idsrouter.exe"</ entry>

<entry name="StartArguments">-Drouter -Xmx256m -cp lib/

DocucorpStartup.jar -Djava.endorsed.dirs=lib/endorsed -

Dids.configuration=docserv.xml -Dlogging.configuration=logconf.xml com.docucorp.startup.Startup com.docucorp.ids.router.IDSRouter</ entry>

<entry name="class">org.apache.derby.jdbc.EmbeddedDriver</ entry>

<entry name="URL">jdbc:derby:global/router-db;create=true</ entry>

<entry name="table">DOCUCORPROUTER</entry>

</section>

Option

StartCommand

StartArguments

StartDirectory

ReplyWaitSeconds

Definition

Specifies the command Watchdog uses to start the router.

Specifies the arguments Watchdog uses when starting the router.

Specifies the directory in which the router will start.

MaxMsgLength

MaxConnectionAttempts Limits the number of connection attempts to Docupresentment when Docupresentment keeps dropping the connection. This is useful when a message the router sends to Docupresentment causes

Docupresentment to fail and drop the connection. This option prevents the indefinite resending of problematic messages. The default is two (2).

Address Lets you bind the router to a specific network device IP address.

This is useful when there are multiple network interfaces available on the machine where Docupresentment is running. The router will bind to all local devices if this option is not provided.

enabled class

Defines how long the router waits for a reply from

Docupresentment before it closes the connection. The default is 30 seconds.

Lets you limit the message size of incoming messages. This helps prevent DOS attacks with large files. The default is 4194304 (bytes).

Determines whether the undelivered messages will be stored in a database for delivery at a later time.

The JDBC Database driver class for the database being used. If the default database is not used, contact your database administrator to get the driver files.

108

Using the Message Queues

Option

URL table userid password

Definition

The JDBC locator for the database being used. If the default database is not used, contact your database administrator for the proper locator string for the database.

The name of the table where you want the undelivered messages stored.

The user ID used to access the database.

The password for the user ID used to access the database.

SING

ULTIPLE

UEUING

YSTEMS

Prior to version 2.1, IDS would process requests that came in from HTTP and from one queuing system, such as MQSeries or JMS. With version 2.1 or later, IDS lets you use multiple queuing systems for processing messages, for example MQSeries and JMS queues can both be used in one instance of IDS.

To enable this, you must add queue sections to the BusinessLogicProcessor and messaging sections in the docserv.xml configuration file. Each queue section is processed and used to open a new set of input and output queues for requests and results.

Here is an excerpt from a configuration with multiple queuing systems enabled:

<entry name="marshaller.class">com.docucorp.messaging.data.marshaller.SOAP

MIMEDSIMessageMarshaller</entry>

</section>

<entry name="queuefactory.class">com.docucorp.messaging.mqseries.DSIMQMess

ageQueueFactory</entry>

<entry name="mq.queue.manager">queue1.manager</entry>

<entry name="mq.queue.channel">SCC_queue1.atl3nt03</ entry>

</section>

<entry name="marshaller.class">com.docucorp.messaging.data.marshaller.Seri

alizationDSIMessageMarshaller</entry>

</section>

<entry name="mq.queue.manager">queue2.manager</entry>

109

Chapter 2

Using the Internet Document Server

<entry name="mq.inputqueue.name">requestq</entry>

<entry name="mq.outputqueue.name">resultq</entry>

<entry name="mq.queue.channel">SYSTEM.DEF.SVRCONN</ entry>

</section>

110

Using the Java Message Service (JMS)

SING THE

AVA

ESSAGE

ERVICE

(JMS)

The Java Message Service API is a standard programming interface for sending and receiving messages across applications. JMS itself is not a product — it is a standard that implementers (businesses or open-source groups) develop their products for. Since it is a standard, any JMS implementation can be used by IDS merely by changing configuration information. No coding changes are required. You can find general information about

JMS at: http://java.sun.com/products/jms/

JMS is part of the J2EE standard. This means that any J2EE-compliant application server, such as WebSphere or WebLogic, has an implementation of JMS as part of the application server. Other companies provide stand-alone implementations. You can find a partial list of vendors at: http://java.sun.com/products/jms/licensees.html

Use an enterprise queuing system, such as a JMS implementation or WebSphere MQ, if your implementation has a high volume of use.

ETTING UP

JMS

The JMS resources needed for IDS to communicate with client programs are called JMS

administered objects. The necessary administered objects are a queue ConnectionFactory and two queues, one for requests (messages from clients to IDS) and one for results (messages from IDS to clients.

Different vendors implement the JMS in different ways so you will have to refer to the specific vendor’s documentation for setting up the queues and factory.

Since different vendors implement the JMS in different ways, there has to be a standard way to access the location of the queues and factory. This is done by another Java standard, the Java Naming and Directory Interface (JNDI). JNDI support is built into

IDS and clients but there are some names of resources that the JMS system administrator will have to provide to you, such as...

• Initial Context Factory – This is a name of vendor-specific Java programming code used to find the JMS administered objects.

• Provider URL – The location of the JMS administered objects.

• Security Principal (Optional) – The user ID, if required, needed to access the JMS administered objects.

• Security Credentials (Optional) – The password, if required, needed to access the

JMS administered objects.

• Queue ConnectionFactory Name – The name of the queue ConnectionFactory created during setup. The JMS implementation may have only one Queue

ConnectionFactory that it set up itself.

• Request and Result Queue Name – The names of the queues created for IDS communication.

111

Chapter 2

Using the Internet Document Server

For IDS, you must add these values to the docserv.xml file, in the

BusinessLogicProcessor section, messaging subsection, queue subsection. Here is an example:

. . .

<entry name="queuefactory.class">com.docucorp.messaging.jms.DSIJMSJNDIMess

ageQueueFactory</entry>

<entry name="jms.initial.context.factory">com.sun.jndi.fscontext.RefFSCont

extFactory</entry>

<entry name="jms.provider.URL">file:///C:/docserv/jndi/jms/

IDS2</entry>

<entry name="jms.security.principal">userid</entry>

<entry name="jms.security.credentials">password</entry>

<entry name="jms.inputqueue.connectstring">jmsrequestq</entry>

<entry name="jms.outputqueue.connectstring">jmsresultq</entry>

The entry

queuefactory.class tells IDS you’ll be using a JMS queuing system. The next four entries are for the standard JNDI entries.

jms.qcf.name is for the name of the JMS Queue

ConnectionFactory.

jms.inputqueue.connectstring and jms.outputqueue.connectstring are for the names of the queues for communication. Since this is the server, it receives requests as input and sends results as output.

Client programs use the file docclient.xml to store configuration information. Queue information would go in the DocumentClient section, messaging subsection, queue subsection. A client program that would use the same queues as this server would have this setup:

<entry name="queuefactory.class">com.docucorp.messaging.jms.

DSIJMSJNDIMessageQueueFactory</entry>

<entry name="jms.initial.context.factory">com.sun.jndi.

fscontext.RefFSContextFactory</entry>

<entry name="jms.provider.URL">file:///C:/docserv/jndi/jms/

IDS2</entry>

<entry name="jms.security.principal">userid</entry>

<entry name="jms.security.credentials">password</entry>

<entry name="jms.inputqueue.connectstring">jmsresultq</entry>

<entry name="jms.outputqueue.connectstring">jmsrequestq</ entry>

</section>

</section>

</section>

112

Using the Java Message Service (JMS)

For example, consider SwiftMQ, a JMS system that uses JNDI to let users find queues.

To add this capability go to the DOCSERV.XML configuration file and find the

BusinessLogicProcessor section. In the Messaging subsection, under the Queue subsection, you would have these entries:

<entry name="queuefactory.class">com.docucorp.messaging.jms.DSIJMSJNDIMess

ageQueueFactory</entry>

<entry name="jms.initial.context.factory">com.swiftmq.jndi.InitialContextF

actoryImpl</entry>

<entry name="jms.provider.URL">smqp://docserv:docserv@server:4001</ entry>

<entry name="jms.security.principal">userid</entry>

<entry name="jms.security.credentials">password</entry>

<entry name="jms.qcf.name">plainsocket@docservrouter</entry>

<entry name="jms.inputqueue.connectstring">requestq@docservrouter</ entry>

<entry name="jms.outputqueue.connectstring">resultq@docservrouter</ entry>

</section>

Entry

queuefactory.class

jms.initial.context.factory

Description

Specifies the IDS class that sets up JMS using JNDI.

Indicates the name of the Java class that interfaces a particular vendor's JMS implementation.

Specifies how to connect to the vendor's JMS implementation. jms.provider.URL

jms.security.principal

jms.qcf.name

(Optional) Indicates the JMS term for a user ID.

(Optional) Indicates the JMS term for a password.

Indicates the name of the vendor's

queue connection factory, a JMS term for how to find JMS queues. jms.inputqueue.connectstring

Indicates the name of the JMS input queue that will hold requests. jms.outputqueue.connectstring

Indicates the name of the JMS output queue that will hold results.

113

Chapter 2

Using the Internet Document Server

SING

EB

PHERE

WebSphere MQ, formerly known as MQSeries, is an IBM product you can use to send and receive messages across applications. You can find general information about

WebSphere MQ at: http://www.ibm.com/software/integration/wmq/

Use an enterprise queuing system, such as a JMS implementation or WebSphere MQ, if your implementation has a high volume of use.

For Windows and UNIX platforms, you can use the RUNMQSC tool to create queues and queue managers. You can use the WebSphere MQ Explorer GUI tool on Windows to create queues and queue managers on the local Windows and remote UNIX, Linux, or

Windows WebSphere MQ servers when configured for remote administration. When

WebSphere MQ installs on Windows, a queue manager is created if you select the option to install default configuration.

Java support for WebSphere MQ is included in version 5.3 and later. The Java libraries for WebSphere MQ can be used in either client mode (via TCP/IP) or in bindings mode

(where the Java application runs on the same machine as the MQSeries server), with the exception of OS/390 which must be run in bindings mode.

OTE

All queues are under a queue manager and there will be a queue manager for each machine that uses WebSphere MQ Server. The queue managers communicate with each another and pass the messages to the appropriate queue underneath.

When adding machines to the cluster, you can use a wizard through the WebSphere MQ

Explorer to set up the cluster. Even though the WebSphere MQ installation program creates a default cluster that uses the network domain name, it does not create the cluster sender channels needed to communicate between the repository machines.

114

Using WebSphere MQ

ETTING

P

EB

PHERE

The WebSphere MQ resources needed for IDS to communicate with client programs are two WebSphere MQ queues, one for requests (messages from clients to IDS) and one for results (messages from IDS to clients).

For IDS, add these values to the docserv.xml file, in the BusinessLogicProcessor section, messaging subsection, queue subsection. Here is an example:

. . .

<entry name="queuefactory.class"> com.docucorp.messaging.mqseries.DSIMQMessageQueueFactory</entry>

<entry name="mq.queue.manager">queue.manager</entry>

<entry name="mq.inputqueue.name">requestq</entry>

<entry name="mq.outputqueue.name">resultq</entry>

<entry name="mq.queue.channel">SCC_channel</entry>

The entry

queuefactory.class tells IDS you’ll be using a WebSphere MQ queuing system. The following are names of WebSphere MQ objects required for communication:

• mq.queue.manager

• mq.inputqueue.name

Client programs use the docclient.xml file to store configuration information. Queue information would go in the DocumentClient section, messaging subsection, queue subsection. A client program that would use the same queues as this server would have this setup:

<entry name="queuefactory.class">com.docucorp.messaging.mqseries.DSIMQMess

ageQueueFactory</entry>

<entry name="mq.queue.manager">queue.manager</entry>

<entry name="mq.inputqueue.name">resultq</entry>

<entry name="mq.outputqueue.name">requestq</entry>

<entry name="mq.queue.channel">SCC_channel</entry>

</section>

</section>

</section>

115

Chapter 2

Using the Internet Document Server

Using MSMQ

Use the DSIMSMQMessageQueue and DSIMSMQMessageQueueFactory classes to communicate via asynchronous messages through MSMQ on Windows platforms.

Support is provided for path names and direct format names. These platforms are supported:

• Windows 2000

• Windows XP

• Windows 2003 and later Windows operating systems

To enable MSMQ messaging, change the queue factory class in the configuration file to: com.docucorp.messaging.msmq.DSIMSMQMessageQueueFactory

Please refer to the HTML documentation shipped with the Java SDK for a description of the properties supported for the MSMQ message bus. In particular, see a description of the setProperties method in the com/docucorp/messaging/msmq/

DSIMSMQMessageQueueFactory class.

Property settings

Here is an example of the docserv.xml file:

<entry name="queuefactory.class">com.docucorp.messaging.msmq.

DSIMSMQMessageQueueFactory</entry>

<entry name="msmq.inputqueue.name">DIRECT=OS:jr\private$

\requestq</entry>

<entry name="msmq.outputqueue.name">DIRECT=OS:jr\private$

\resultq</entry>

</section>

Here is an example of the docclient.xml file:

<entry name="queuefactory.class">com.docucorp.messaging.msmq.

DSIMSMQMessageQueueFactory</entry>

<entry name="msmq.inputqueue.name">DIRECT=OS:jr\private$

\resultq</entry>

<entry name="msmq.outputqueue.name">DIRECT=OS:jr\private$

\requestq</entry>

</section>

Here is an example of the dsimessage.properties file: queuefactory.class=com.docucorp.messaging.msmq.DSIMSMQMessageQueueF

actory

# MSMQ for windows msmq.server.name=jr msmq.inputqueue.name=private$\resultq msmq.outputqueue.name=private$\requestq msmq.timeout=10000

116

Using WebSphere MQ

These components are required:

• DocucorpMsg.jar

• msmqlib.dll

Be sure to include the MSMQLIB.DLL in the system path so it is found at run time.

OTE

Testing has shown that when using direct format names to private queues, the queue used to read messages should be a local queue. This improves performance significantly (about 10 times) and avoids the generation of unnecessary TCP socket connections that is incurred when reading messages from a remote private queue.

If the IDS client and IDS server components reside on separate boxes, configure the client to read messages from a local private result queue. Configure the server to read messages from a local private request queue.

Using correlation IDs

Using the

ReceiveByCorrelationI

D API

Generating the message ID

IDS supports WebSphere MQ/JMS client applications that specify a correlation ID or a message ID in a request.

Client applications can specify a correlation ID in a request and retrieve a response with the same correlation ID. Client applications can also use the conventional method of correlating a response with a request by specifying a message ID in a request and retrieving a response with a correlation ID matching the message ID of the request.

IDS supports MSMQ 3.0 client applications that want to retrieve messages via the

ReceiveByCorrelationID API using the message ID property of the request message as the parameter.

On the server side, IDS sets the Correlation ID property of a response message equal to the value of the Message ID property of the request message when the UNIQUE_ID value of the request message is blank. For this reason, client side applications that want to retrieve a message by correlation ID, should make sure the UNIQUE_ID value of the request message is blank.

The message buses for IDS can generate the message ID for client applications during a request. A message bus generates the message ID when the putMessage method of the output queue provides a value of null or a blank value for the messageID argument.

The message ID generated by the message bus can then be retrieved through the getMessageID method of the output queue and used as the ID argument in the getMessage method of the input queue to retrieve a matching reply.

If a messageID value is provided to the putMessage method, then that value is used instead, with one exception — the MSMQ message bus only supports message bus generated message IDs.

Here is a Java example that lets the message bus generate the messageID for a client request: outputQueue.putMessage(null, reqObj);

String unique = outputQueue.getMessageID();

Object resObj = inputQueue.getMessage(unique, timeOutMillis, 3);

117

Chapter 2

Using the Internet Document Server

Using MSMQ direct format queue names

Here is a Java example that lets a client application define the message ID for a request:

UniqueStringGenerator usg = new UniqueStringGenerator();

String messageID = usg.generateUniqueString(32); outputQueue.putMessage(messageID, reqObj);

Object resObj = inputQueue.getMessage(messageID, timeOutMillis, 3);

These message buses support this functionality:

• Java: HTTP, JMS, MSMQ, MQSeries, and Mail

The IDSJSP package (Java) also supports this feature when used with the

DSIJavaMsg and DocucorpMsg packages. Use the setUniqueId method of a dsi or dsimsg bean to set the unique ID to null or a blank value to indicate you want the message bus to generate the message ID during a client request.

• Csharp: HTTP, MSMQ, and MQSeries

The DSIInterface class in the DocucorpDSI assembly (Csharp) also supports this feature when used with the DocucorpMsg assembly. Use the setUniqueId method of the DSIInterface class to set the unique ID to null or a blank value to indicate you want the message bus to generate the message ID during a client request.

You can set up the MSMQ_FileConvert control group to recognize path names, format names, and direct format names.

OTE

Before version 2.0, only path names were supported in the INI file and were converted into format names by the MSMQ API

MQPathNameToFormatName().

The system recognizes when you specify a format name in the INI file and skips the API call to MQPathNameToFormatName. For example, private queues cannot be accessed unless the direct name is used. So, if you are using a private queue but the IDS client and server are on different PCs, you must use direct format names.

Here is an example of the INI options you would set:

< DBTable:RequestQ >

DBHandler = MSMQ

< DBTable:ResultQ >

DBHandler = MSMQ

< MSMQ_FileConvert >

;requestq = FSINTSRV08\JRREQQ

;resultq = FSINTSRV08\JRRESQ requestq = DIRECT=TCP:10.8.10.137\PRIVATE$\JRREQQ resultq = DIRECT=TCP:10.8.10.137\PRIVATE$\JRRESQ

;requestq = DIRECT=OS:JDOE\PRIVATE$\JRREQQ

;resultq = DIRECT=OS:JDOE\PRIVATE$\JRRESQ

;requestq = PUBLIC=dc7b9469-dbae-11d6-ae6c-00104bd359c1

;resultq = PUBLIC=dc7b946c-dbae-11d6-ae6c-00104bd359c1

;requestq = .\private$\JRREQQ

;resultq = .\private$\JRRESQ

;requestq = PRIVATE=cdb19274-6146-4ab9-8679-

6e998943a938\00000016

118

Using WebSphere MQ

;resultq = PRIVATE=cdb19274-6146-4ab9-8679-6e998943a938\00000017

< RequestQ >

Name = requestq

< RESULTQ >

Name = resultq

Keep in mind these definitions:

ORMAT NAMES

. A format name is a unique name generated by MSMQ. The

MQPathNameToFormatName API normally converts a path name specified in the INI file into a format name by looking up the format name in the MSMQ MQIS. The format name is then used by the MQOpenQueue API to open a queue.

To avoid conversion of the path name into a format name, you can specify a format name in the INI file. Here are some examples:

PUBLIC=dc7b9469-dbae-11d6-ae6c-00104bd359c1

PRIVATE=cdb19274-6146-4ab9-8679-6e998943a938\00000016

IRECT FORMAT NAMES

. You can also specify a direct format name to avoid the path name to format name conversion and to skip the connection to the MQIS altogether. This, in essence, generates a One-HOP direct connection from one MSMQ box to another, which can be useful when you are connecting to a remote box that hosts private queues in an

MSMQ workgroup configuration. Here are some examples:

DIRECT=TCP:10.8.10.137\PRIVATE$\JRREQQ

DIRECT=OS:JDOE\PRIVATE$\JRREQQ

In the first example, the protocol specified is TCP and the IP address of the box hosting the private queues is specified.

In the second example,

OS indicates that the native protocol of the operating system where the private queues reside should be used and the NetBIOS name is specified instead of the IP address of the box hosting the queues. All connection information is contained within the direct format names to avoid a connection to the MQIS.

OTE

Direct format names are only supported in Windows NT 4.0 Service Pack 6a or later.

UEUE PATH NAMES

. MQLIB also supports specifying normal queue path names in the

INI file by calling the MQPathNameToFormatName API to convert them into the proper format name before calling the MQOpenQueue API. Here are some examples:

FSINTSRV08\JRREQQ

.\private$\JRREQQ

119

Chapter 2

Using the Internet Document Server

Queue pooling

When setting up the messaging parameters in a Java application to talk to IDS, you can specify that the message queues should be kept in a

pool of queues and reused throughout the life of the application. If a pooled connection is not used after 30 seconds, it may be removed from the pool and the queue is closed automatically. You can also close pooled connections manually.

Message pooling has these advantages:

• Reusing an existing, previously opened queue can be faster than opening a new queue connection for every communication with IDS.

• In an application there can be more threads of execution than there are available queue connections on the queuing server. Threads are automatically blocked until a connection to a queue is available. This keeps you from having to limit the number of threads to the number of available connections or creating some kind of multithreaded blocking.

This functionality is most useful in application servers, such as WebSphere, that host long-running, multi-threaded Java clients such as JSPs or servlets. No extra configuration is necessary on the web application, such as WebSphere.

To use queue connection pooling, you must make the following changes in your the client configuration file. This can be a properties file such as dsimsgclient.properties, if you are upgrading from IDS 1.x or a XML-based configuration file such as docclient.xml.

OTE

IDS version 2.

x detects which kind of configuration you have and loads it automatically.

In both the DSIJavaMsg and DocucorpMsg libraries, the settings for queue connections are passed to the libraries by Java properties objects. To enable and set up pooling, use these options:

Option

pooling.enabled

pooling.input.pool.size

pooling.output.pool.size

Description

Set to Y to enable pooling. The default is N.

Number of input queue connections to pool. The default is 10.

Number of output queue connections to pool. The default is 10.

Here is an example of a client properties file that would enable an input and output pool of 20 MQSeries connections. This file would normally be named dsimsgclient.properties.

pooling.enabled=Y pooling.input.pool.size=20 pooling.output.pool.size=20 queuefactory.class=com.docucorp.messaging.mqseries.DSIMQMessageQueu

eFactory mq.queue.manager=venus.queue.manager mq.inputqueue.name=RESULTQ mq.outputqueue.name=REQUESTQ mq.outputqueue.expiry=120 mq.tcpip.host=10.1.10.1 mq.queue.channel=SYSTEM.DEF.SVRCONN

120

Using WebSphere MQ mq.tcpip.port=1414

You must also make the following API changes if your implementation talks directly to the DocucorpMsg library, whether it’s in Java or JSP, to use queue connection pooling.

If you are using the DocucorpMsg library, pooled connections can only be obtained through the static method DocucorpMsgUtil.getQueueFactory(Properties props). This method returns a DSIMessageQueueFactory that may be pooled, but is used in the same manner as the previously unpooled DSIMessageQueueFactory objects.

If you are creating a multi-threaded command line program, any outstanding pooled connection can be closed with the static method

DocucorpMsgUtil.closePooledConnections(Properties props).

OTE

No code changes are needed for users of the DSIJavaMsg library.

SING

ECURITY

XITS

You can attach custom security exits to WebSphere MQ queues. Security exits are external libraries of code that can be installed and run in WebSphere MQ queues. For IDS, security exits consist of a Java class in a .jar file, with an optional native component.

To have a security exit installed and run, you need to know the name of the Java class for the security exit and the name of the .jar file that has the security exit.

In the docserv.xml configuration file, set up a queue section for WebSphere MQ queues.

In that section, add an entry similar to the one shown here:

<entry name="mq.customsecurityexit.classname">com.customer.

securityClassName<entry>

Substitute the name of the your security exit Java class name for: mq.customsecurityexit.classname

You must load the .jar file that has the custom security exit code. For application servers running Docupresentment client code, refer to the application server's documentation for information on modifying the classpath for the web application or for including a .jar file in a particular directory.

For Docupresentment server, you can either...

• Put the .jar file in the server's lib directory, or

• Modify how Docupresentment server is run by adding the System property com.skywiresoftware.extraClasspath

with a reference to any .jar files needed to run the security exit.

For example, for the docserver.bat file, you could add an entry like the one shown here:

-Dcom.skywiresoftware.extraClasspath=/path/to/security.exit.jar

121

Chapter 2

Using the Internet Document Server

SING

LIENT

ONNECTION

EFINITION

ABLES

The WebSphere message bus can read connection information from Client Connection

Definition Table (CCDT) files. The code can then use any queue manager listed in the

CCDT file to establish a connection.

OTE

Support for CCDT files in Java requires WebSphere MQ, version 6.0 or later.

Refer to the WebSphere MQ documentation for information about Client

Connection Definition Tables.

For additional information, see the description of the mq.ccdt.url property in the HTML documentation for the com.docucorp.messaging.mqseries.DSIMQMessageQueueFactory class. This information is included with the Java SDK.

SING

SSL C

ONNECTIONS

To use SSL connections the queue manager and server connection channel must be configured to use SSL. SSL connections are only supported in MQ client mode (version

5.3 or later).

See the security guide for your version of WebSphere MQ for information on how to configure a queue manager and server connection channel for SSL communication. A

Java key store must be available to IDS and it must contain a personal certificate issued by a trusted Certificate Authority (CA). This trusted CA must be present in the key repository used by the queue manager. The CA certificate must be part of the trusted certificates in the key repository used by the queue manager.

Also, the same CA certificate must be present in the Java keystore. If the personal certificate used by the queue manager was issued by another CA, then the CA certificate for it must also be present in the Java key store so the SSL handshake can be negotiated between the MQ Client (IDS) and the MQ Server (the queue manager).

If the server connection channel is configured to authenticate client certificates or to verify the Distinguished Name of client certificates via the SSLPeer property, the personal certificate in the Java key store must also contain the private key. The entry type in the

Java key store for the personal certificate should be '

keyEntry' instead of 'trustedCertEntry' in this case.

See the HTML documentation for the DSIMQSeriesMessageQueueFactory class, which is shipped with the IDS DSI Java SDK, for additional information on the MQ SSL properties. In particular, see the description of the setProperties method.

Here is an example of these configuration properties:

<entry name="mq.ssl.peername">CN=ssl_qmgr, C=US, S=GA, L=Atlanta,

O=Docucorp International, OU=PD</entry>

<entry name="mq.ssl.socketFactory.class"> com.docucorp.messaging.mqseries.DSIMQSSLSocketFactory</entry>

122

Using WebSphere MQ

<entry name="mq.ssl.keystore">c:/docserv/keystore/ java_certificate_store</entry>

<entry name="mq.ssl.keystore.pwd">changeit</entry>

<entry name="mq.ssl.truststore">c:/docserv/keystore/ java_certificate_store</entry>

<entry name="mq.ssl.truststore.pwd">changeit</entry>

SING THE

EPLY

O

UEUE

AME AND

EPLY

O

UEUE

ANAGER

AME

ROPERTIES

IDS checks for these MQ message properties during MQGET calls issued by IDS:

• replyToQueueManagerName

• replyToQueueName

If the properties are defined in the message, they are used to reply to a specific queue manager and queue — MQPUT1 calls are used instead of MQPUT calls in this case. In addition, if you are using the SOAP marshaller, reply messages will contain the

REPLYTOQUEUEMANAGER and REPLYTOQUEUE elements in the control block.

If the replyToQueueName property is not defined in the message received by IDS, the system uses the value defined in the mq.outputqueue.name property in the docserv.xml configuration file.

To use this functionality, client applications submitting requests to IDS should make sure the replyToQueueManagerName and replyToQueueName message properties are set.

UPPRESSING

UEUE

RROR

ESSAGES

Docupresentment can suppress queue error messages for a period of time. This helps you prevent unnecessary logging when a queue receiver or sender fails to connect to the queues because the message bus is down. These configuration options are supported at the queue section level in the docserv.xml file:

Option

MaxErrors

Description

Specifies the maximum number of consecutive errors a queue receiver or sender can have before error messages are suppressed. The default is 10.

SuppressErrorsIntervalSeconds Specifies how long error messages should be suppressed.

The default is 1800 seconds.

Here is an example:

123

Chapter 2

Using the Internet Document Server

<entry name="queuefactory.class">com.docucorp.messaging.mqseries.DSIMQMess

ageQueueFactory</entry>

<entry name="mq.queue.manager">queue_manager3</entry>

<entry name="mq.inputqueue.name">REQUESTQ</entry>

<entry name="mq.outputqueue.name">RESULTQ</entry>

<entry name="mq.queue.channel">CHANNEL1</entry>

</section>

ERSISTING

UEUE MESSAGES

Docupresentment can persist request and response messages during processing which lets you recover previously unprocessed messages during a restart.

OTE

: This topic does not pertain to HTTP queues.

The following docserv.xml file configuration options at the queue section level control the persistence behavior:

Option

Persistent

Description

Turns the persistence logic on or off. The default is False.

PersistentClassName The name of the implementation class that implements the com.docucorp.ids.persistence.PersistentAdapter interface. The default is com.docucorp.ids.persistence.io.FilePersistentAdapter.

The FilePersistentAdapter class will serialize and deserialize queue messages to and from the disk. This directory location is used for serialized messages: global/DocumentServer/

DocupresentmentInstanceName/

ReceiverOrSenderName/guid.message

Here are some examples: global/DocumentServer/IDS-1-RequestReceiver#1/

AD7397A4-E546-8230-3341-5307040150E0.message

global/DocumentServer/IDS-1-ResultSender#1/

AD7397A4-E546-8230-3341-5307040150E0.message

Here is an example:

124

Using WebSphere MQ

<entry name="queuefactory.class">com.docucorp.messaging.mqseries.DSIMQMess

ageQueueFactory</entry>

<entry name="mq.queue.manager">queue_manager2</entry>

<entry name="mq.inputqueue.name">REQUESTQ</entry>

<entry name="mq.outputqueue.name">RESULTQ</entry>

<entry name="mq.queue.channel">CHANNEL1</entry>

<entry name="PersistentClassName">com.docucorp.ids.persistence.io.FilePers

istentAdapter</entry>

</section>

URGING

ACHED

ILES

Docupresentment uses a file cache to determine when temporary files generated throughout different rules should be removed from disk.

Temporary files cached for removal are placed as entries in a properties file. Each entry contains the full path of the cached file and a time stamp that indicates when the file expires.

Cleanup is run on a separate thread that periodically looks up the entries in the file cache and determines if they have expired. When an entry expires, the system removes it from the cache and deletes the file associated with it.

OTE

The determination of when a temporary file expires depends on the expiration time or timeout value each rule uses when caching a file for removal. This means you can specify individual values for different rules when caching a file for removal. Furthermore, any rule that caches a temporary file for removal can also have its own INI values for determining the expiration value.

Here is a list of the file caching INI options used by the various Docupresentment rules

(these INI options should be placed in the INI file that matches the CONFIG attachment variable being used for the Docupresentment request type being invoked):

The CacheTime option is used by the RunRP rule to cache temporary files.

< RPRun >

CacheTime = 60 ;(default, value specified in minutes)

These options are used by the RunRP rule to cache temporary PDF and text files.

< IDSServer >

PrintFileCacheTime = 1800 ;(default, value specified in seconds)

TextFileCacheTime = 1800 ;(default, value specified in seconds)

The Timeout option is used by several Docupresentment rules to cache temporary XML files:

< HTMLFileCache >

Timeout = 7200 ;(default, value specified in seconds)

The Timeout option is used by the DPRPrint rule to cache temporary PDF files

125

Chapter 2

Using the Internet Document Server

< PDFFileCache >

Timeout = 7200 ;(default, value specified in seconds)

The Timeout option is used by EWPS rules to cache temporary output files

< EWPSFileCache >

Timeout = 7200 ;(default, value specified in seconds)

The following file caching configuration options are supported in the DocumentServer section of the docserv.xml file.

Option

FilePurgeList

Description

Specifies the name of the file cache to use. This file holds entries that correspond to files cached for removal and their expiration time stamp. The default is filecache.properties.

If there is more than one Docupresentment instance running, the first instance uses the file cache name specified in FilePurgeList configuration option. Instances that follow use fileCacheName.instanceNumber, where fileCacheName is the name specified by the FilePurgeList configuration option and instanceNumber is the number of the instance (instance numbers are zero-based). Here is an example:

If Docupresentment is using the Instances configuration property in docserv.xml file with a value of three (3) and the default file cache name of filecache.properties is used, then instance one will use the filecache.properties file name, instance two will use the filecache.properties.1 file name, and instance three will use the filecache.properties.2 file name.

FilePurgeTimeSeconds Specifies how often the thread that cleans up cached entries runs.

The default is 3600.

FileWriteThreshold Determines how many file cache entries can be held in memory before they are written to the file cache on disk. The default is zero

(0).

126

Using HTTP

SING

HTTP

In addition to processing requests received from enterprise queuing systems (WebSphere

MQ and JMS), IDS can receive requests through HTTP. You can configure IDS to use

HTTP-based messaging, queue-based messaging, or both.

HTTP messaging replaces the file-based xBase queues from earlier versions of IDS (prior to 2.0) as the low-volume messaging system. Like the xBase queues from earlier versions, there is no setup of an extra program to run the messaging system, plus HTTP messaging does not have the 64K limit of xBase queues.

Although you can use HTTP-based messaging for lower-volume installations, an enterprise-ready queuing system is recommended for higher-volume installations and in situations where requests should not be lost if IDS or IDS clients are halted.

The default format of messages sent to HTTP-based messaging is the SOAP with

Attachments format. The request type and message variables are in an XML message embedded into a SOAP envelope, and attachments are added in MIME format to the message. For more information, see Using the XML Messaging System on page 152 . You can find more information about SOAP and attachments at: http://www.w3.org/TR/SOAP/ http://www.w3.org/TR/SOAP-attachments

The combination of HTTP messaging and the SOAP format means that IDS can act as a

Web Services server for IDS requests. Web Services clients can send messages to IDS via

HTTP using the SOAP and SOAP With Attachments format. IDS processes the request and sends the result back to the Web Services client in SOAP format. A Java sample program, JAXMClient, is provided for testing and as a source code template so you can create your own Web Services clients using Sun's Java API for XML Messaging. You can find more information about the Java API for XML Message at: http://java.sun.com/xml/jaxm/index.html

OTE

No particular version of the SOAP protocol is required. In IDS version 1.8 and version 2.

the system does manual XML parsing to extract information, so versions are essentially ignored. No WSDL file is needed for a .NET client.

Setting up HTTP

For IDS, add these values to the docserv.xml file, in the BusinessLogicProcessor section, messaging subsection, http subsection:

...

<entry name="RequestPath">xslPath</entry>

<entry name="HtmlPath">htmlPath</entry>

</section>

127

Chapter 2

Using the Internet Document Server

128

Entry

port

WaitForResultMillis

HttpProcessors

RequestPath

HtmlPath

Address

Description

Indicates the http port that the first instance of IDS will be accessible from. If more than one instance is running they will use subsequent ports, starting with this one.

Indicates how long, in milliseconds, to wait for the request to be processed before timing out.

Indicates how many extra threads will be set up to accept http requests from clients.

Indicates where IDS will find customization XSL style sheets.

Indicates where IDS will find extra HTML-based information.

Allows binding the HTTP servers to a specific network interface address on the machine where Docupresentment is running. The

HTTP servers will bind to all local devices if this option is not used.

<entry name="queuefactory.class">com.docucorp.messaging.http.

DSIHTTPMessageQueueFactory</entry>

<entry name="http.url">http://localhost:49152</entry>

</section>

</section>

</section>

The entry

queuefactory.class tells the client program to use HTTP to communicate. http.url gives the name of the server machine and TCP/IP port to use.

OTE

The http subsection is also used by IDS when it processes ordinary requests via

HTTP messaging. See Using IDS to respond to requests via a browser on page

127 for more information.

Responding to URL requests

IDS can respond to requests formatted as a URL from a browser and display results in

HTML. You can customize the display for a particular request or use a default display which shows message variables, rowsets, and any errors encountered. An example URL is http://localhost:49152/ request?REQTYPE=SSS&USERID=USERID&PASSWORD=PASSWORD

Where

localhost is the IP address to contact, and 49152 is the port number at the IP address that IDS is using.

Using HTTP

Using IDS to respond to requests via a browser

You can add any number of message variables to the URL but attachments are not supported.

To use this capability you must make changes in the DOCSERV.XML configuration file.

First, find the BusinessLogicProcessor section, then locate the Messaging subsection. In this subsection, create an HTTP subsection, as shown here:

<entry name="RequestPath">xslPath</entry>

<entry name="HtmlPath">htmlPath</entry>

</section>

Entry

port

WaitForResultMillis

HttpProcessors

RequestPath

HtmlPath

Description

Indicates the http port that the first instance of IDS will be accessible from. If more than one instance is running they will use subsequent ports, starting with this one.

Indicates how long, in milliseconds, to wait for the request to be processed before timing out.

Indicates how many extra threads will be set up to accept http requests from clients.

Indicates where IDS will find customization XSL style sheets.

Indicates where IDS will find extra HTML-based information.

IDS can respond to requests directly from a web browser and display the results formatted as HTML. A web server is not needed for the display. This is useful for debugging purposes. You can customize the formatting for each request type, otherwise a default page appears showing any message variables and error messages for the request.

After a request is processed, the results are formatted in the SOAP with MIME

Attachments format. See Setting up HTTP on page 125 for more information. IDS looks for an XSL style sheet named:

REQTYPE.xsl

where

REQTYPE corresponds to the request type of the request. If this file is found, it is used to transform the SOAP XML. If there is no XSL style sheet for that request, a default style sheet is used. The default style sheet displays the message variables name/ value pairs in a table then lists any rowsets.

To have a request displayed in your browser, build a URL similar to: http://localhost:49152/ request?REQTYPE=SSS&USERID=USERID&PASSWORD=PASSWORD

localhost and 49152 are the TCP/IP address and port number where IDS is running.

Message variables are entered as NAME=VALUE pairs, separated by an ampersand (&).

The only required variable is REQTYPE. Any number of message variables can be added to the URL but attachments are not supported.

Here is an example:

129

Chapter 2

Using the Internet Document Server

Configuring IDS to handle HTTP requests

In the docserv.xml configuration file, in section 'BusinessLogicProcessor', subsection

'messaging' create an http subsection:

<entry name="RequestPath">xslPath</entry>

<entry name="HtmlPath">htmlPath</entry>

</section>

Parameter

port

WaitForResultMillis How long, in milliseconds, to wait for the request to be processed before timing out

HttpProcessors The number of extra threads to set up to process HTTP requests from clients.

RequestPath

Description

The HTTP port you access IDS from.

HtmlPath

Where IDS can find customization XSL style sheets. If you use a relative path, keep in mind the current directory is where IDS was installed.

Where IDS can find extra HTML-based information. If you use a relative path, keep in mind the current directory is where IDS was installed.

The http subsection is also used by IDS when it processes ordinary requests via HTTP messaging. See Using HTTP on page 125 for more information.

130

Using Multiple Bridges

SING

ULTIPLE

RIDGES

You can set up multiple bridges to use a single server. These bridges include Documaker

Bridge, the Documanage Bridge, the Printstream Bridge, and the Docuflex Bridge. There are two ways to do this:

• The simplest way is to combine all of the required INI options into the DAP.INI file, which is loaded by the DPRInit rule.

• The more advanced and recommended way is to use the DPRSetConfig rule and multiple INI files. This lets you set INI options specifically for each bridge (different values for the same INI option for different bridges).

OTE

The system expects to globally apply the values it finds in an INI file. You handle this by switching the context based on the attachment variable

CONFIG, using the DPRSetConfig rule.

In the DAP.INI file, you specify which INI files should be used for each of the CONFIG values, for example:

< Config:TIFF >

INIFile = tiff.ini

< Config:DAPARC >

INIFile = daparc.ini

The system supports multiple INI files, such as:

< Config:TIFF >

INIFile = tiff.ini

INIFile = myownini.ini

In the case of the usage of the DPRSetConfig rule and the appropriate INI values, for example if the DAP.INI file includes this setting:

< Config:TIFF >

INIFile = tiff.ini

The actual INI context used in the rules and bridges, will include the INI values from the

TIFF.INI and DAP.INI files. When using multiple INI files with the same INI options, but different values, the first INI value — the value from the first INI file — is returned when the rules ask for the INI value.

The only thing you have to watch out for is when the system expects multiple INI values.

For example, Documaker Bridge rules look for multiple INI values for the AppIdx options in the ArcRet control group. In this case, the system gets all of the matching values from the first INI file (TIFF.INI in this example) and then gets all of the matching

INI values from the DAP.INI file.

131

Chapter 2

Using the Internet Document Server

Here’s another example:

Assume IDS is installed with the Documanage and Printstream bridges. You create two

CONFIG values: TIFF and META. The DAP.INI file will include these options:

< Config:TIFF >

INIFile = tiff2pdf.ini

< Config:META >

INIFile = meta2pdf.ini

The Documaker-related INI options for each bridge should go into each of these INI files. You can optionally place common INI options in the DAP.INI file. You should use the DPRSetConfig rule in any rule list which includes request types and that intend to use DPR, TPD, or MTC rules.

The DPRSetConfig rule is located in DPRW32.DLL and runs on MSG_RUNF. Here is the example (from the DOCSERV.INI file of the rule list with this rule. This rule must run before any other rules which use Documaker code and expect Documaker-related

INI options.

< ReqType:MTC > function = atcw32->ATCLogTransaction function = atcw32->ATCLoadAttachment function = dprw32->DPRSetConfig function = atcw32->ATCUnloadAttachment function = mtcw32->MTCLoadFormset function = dprw32->DPRRotateFormsetPages function = mtcw32->MTCPrintFormset

OTE

The TPDInitRule rule should be in the list after DPRInit rule.

Request types and multiple bridges

When you install one bridge over another or develop a new bridge, keep in mind that some of the request types listed in the DOCSERV.INI or DOCCLNT.INI files may already be in use by another application or bridge.

If this happens, change your bridge or application to use an unused request type. The length of the request type string is not limited to three characters. You can enter up to 19 characters. Do not include any special characters, instead limit it to alphanumeric characters and underscores.

For example, suppose you are trying to use request type LGN, but it is already taken and the list of rules in the DOCSERV.INI file for this request type is not the same as you need.

In this situation, you could define your own request type, such as MYLGN and add the rules you need to DOCSERV.INI file under the ReqType:MYLGN control group. Be sure to change your application to use the MYLGN request type instead of LGN.

132

Submitting Batch Requests

UBMITTING

ATCH

EQUESTS

You can use the FILE2IDS utility to read a text file which contains a series of requests and submit those requests to an IDS server. Each line of the text file equals one request.

You specify the request type on the command line and the attachment variables are created from each line in the input file in this manner:

• Each line is broken into 1000 byte chunks (1000 is the default size, you can set the size using the /L parameter)

• Each chunk is added as attachment variable RECORDLINE

XX, where XX is the sequence number of the chunk.

The attachment variable RECORDPARTS specifies how many chunks are added.

OTE

The FILE2IDS is a Visual Basic program. You must have a VB runtime installed to run this program. You can click the Help button when you run FILE2IDS to see a summary of the various parameters.

To run the FILE2IDS utility, enter this command: file2ids /C /D /I /L /K /R /T /Name /W

All parameters are passed in with the equals (=) sign, for example:

/I=file.txt

Parameter Description

/C Specifies the value of the CONFIG attachment variable

/D Set to

On to turns on the debugging window and wait for the result from IDS.

The name of the file

Enter

Y or N to have the system wait or not wait for a key to be pressed in the debug window.

Specifies the line length. The default is 1000.

/Name

The request type. The default is Email.

The length of time in milliseconds before IDS times out. The default is 15000.

Lets you pass a name and value to the IDS rule in this format: /Name=Value. For instance, /ABC=BCD adds the attachment variable ABC with the value BCD.

The length of time in milliseconds IDS will wait before retrying. The default is

1000.

If you run the utility with no parameters, it displays a window which lets you then enter the parameters shown above.

133

Chapter 2

Using the Internet Document Server

The utility returns one of the following values:

Value Description

0 The utility completed its task and no errors occurred.

No input file information was found.

The utility was canceled before it ran. Typically, this indicates you clicked Exit on the window which asks for the parameters.

3 Other error.

134

Printing in Duplex Mode to PCL Printers

RINTING IN

UPLEX

ODE

TO

PCL

RINTERS

Windows does not let you print files that are a mixture of simplex and duplex pages from

Acrobat. The whole document has to be printed the same way. IDS, however, lets you print a file to a local PCL printer which preserves the file’s duplex information. There are two ways to do this:

• By inserting blank pages into a PDF file for the pages in simplex mode. This requires the system to create two PDF files, one for printing and one for viewing.

• By creating the PCL file, compressing the file, downloading the file, and then decompressing it for printing.

IDS can create compressed PCL files several ways:

• Using the IDS print rules. If you use the print rules, use the Compression attachment variable to create a compressed file. When used by Print Preview, you must also pass the Compression attachment variable to the DPRPrint rule. See the SDK Reference for more information about these rules.

• Using Documaker. If you create the file via Documaker, you set INI options to create the file. The PRTZCompressOutPutFunc function is called to compress the output files. To use this function to compress an output file such as a PCL print batch file, add these INI options:

< PrtType:PCL >

OutputMod = PRTW32

OutputFunc = PRTZCompressOutputFunc

• Using a Java application which can decompress the file and send it to a local printer.

The application is provided in the WindowsRawPrinter.jar file and it requires that you install the DSIJWP.DLL file.

OTE

The output is compressed, regardless of the file’s extension. You must decompress the file before you can print it.

135

Chapter 2

Using the Internet Document Server

SING

IDS

TO

ISTRIBUTE

MAIL

You can use the Internet Document Server to distribute email. The following illustration shows how it works with the GenData program, which is part of Documaker:

GenData program

Recipient batch used for email

File2IDS

IDS

Email

Service

OTE

Because the File2IDS utility is a Visual Basic program, the above scenario is only available for Windows environments.

The following scenario, which is available for both Windows and UNIX environments, shows how it works if you are using Documaker Bridge, but not the GenData program:

IDS client

email request

IDS

Email

Service

For either approach, to use the Internet Document Server to distribute email, you must modify these files:

• DOCSERV.XML

• DAP.INI

ODIFYING THE DOCSERV

XML

ONFIGURATION

ILE

This configuration file must contain the following section. These rules are used to take messages sent to IDS and send formatted email messages to an email server such SMTP.

The system supports text-based templates or HTML templates that can be sent as an attachment or used as the message body.

<entry name="function">atcw32->;ATCLogTransaction</entry>

<entry name="function">atcw32->;ATCLoadAttachment</entry>

136

Using IDS to Distribute Email

EmailDFD control group

Email2IDS control group

XML2Body control group

<entry name="function">dprw32->;DPRParseRecord</entry>

<entry name="function">dprw32->;DPRFindTemplate</entry>

<entry name="function">dprw32->;DPRAdd2Attachment</entry>

<entry name="function">dprw32->;DPRCreateEMailAttachment</entry>

<entry name="function">dprw32->;DPRMail</entry>

<entry name="function">atcw32->;ATCUnloadAttachment</entry>

</section>

Modifying the DAP.INI File

This INI file must contain the following control groups and options.

The DFD file specified by this option is used by the DPRParseRecord rule. The system expects to receive the email data from the client in fixed-length records defined by this

DFD. Using a DFD to define the record layout increases flexibility. This DFD can be identical to a batch recipient DFD, where the system is taking an output from the

GenData program and using it as input to the email server.

< EmailDFD >

File = .\dfd\attchdfd.dfd

This group is also used by the DPRParseRecord rule. The option (on the left) must match a field name in the DFD defined under the EmailDFD group. The DPRParseRecord rule copies the data to attachment variables used by other email rules (see the section on attachment variables). This lets you take fields defined in the DFD whatever they are named, and transfer the data to attachment variables that are used by other email rules.

< Email2IDS >

EmailAdd = ADDRESS

PullCode = REQTYPE

This control group is used by the DPRFindTemplate rule. Templates are used to predefine text for the body of an email, while variable data is inserted at indicated places within the body of text. The XML2Body control group defines which template files are used for the message body.

The options in the example below, such as e301, e302, and so on, are the values of the

ReqType used by the IDS. This value can come directly from the message the IDS receives or from the DPRParseRecord rule. The system must have the ReqType either in the ATTCHDFD.DFD file or set up in the Email2IDS control group.

< XML2Body > e301 = .\tmpl\e301.txt

e302 = .\tmpl\e302.txt

e303 = .\tmpl\e303.txt

e304 = .\tmpl\e304.txt

e305 = .\tmpl\e305.txt

e306 = .\tmpl\e306.txt

e307 = .\tmpl\e307.txt

e308 = .\tmpl\e308.txt

e309 = .\tmpl\e309.txt

e310 = .\tmpl\e310.txt

e311 = .\tmpl\e311.txt

e312 = .\tmpl\e312.txt

137

Chapter 2

Using the Internet Document Server

XML2Attach control group

EmailAdd2Attachment control group

Mail and MailType control groups

This control group is used when you need to use template processing to produce an attachment. This group functions just like the XML2Body control group except the output of the template processing is sent as an attachment.

< XML2Attach > e301 = .\tmpl\e301.txt

e302 = .\tmpl\e302.txt

e303 = .\tmpl\e303.txt

e304 = .\tmpl\e304.txt

e305 = .\tmpl\e305.txt

e306 = .\tmpl\e306.txt

e307 = .\tmpl\e307.txt

e308 = .\tmpl\e308.txt

e309 = .\tmpl\e309.txt

e310 = .\tmpl\e310.txt

e311 = .\tmpl\e311.txt

e312 = .\tmpl\e312.txt

The control group is used by the DPRAdd2Attachment rule to take values from the INI file for the email rules (see section on predefined attachment variable names).

< EmailAdd2Attachment > default = SUBJECT, Important notice

These control groups are used by the DPRMail rule to define the email protocol. See the

Documaker Workstation Administration Guide for information on setting up email support.

These options are identical to the ones set up in the FSIUSER.INI or FSISYS.INI files for a Documaker Workstation.

< Mail >

MailType = SMTP

< MailType:SMTP >

Name = Send Mail

Module = SMMW32.DLL

MailFunc = SMMSendSMTP

ReplyTo = [email protected]

From = [email protected]

AltFrom = Joe Jones

Port = 25

Server = 10.8.10.216

Debug = Yes

Option

Name

Module

Description

Name of the system (identifies the system on internal dialogs).

Name of the Documaker DSO that supports the email system.

MailFunc Exported DSO function name of the email handler.

138

Using IDS to Distribute Email

Option

ReplyTo

From

AltFrom

Port

Server

Debug

Description

For SMTP, this option lets you specify a reply-to address.

The system also lets you specify a different reply-to email address for each IDS transaction. Use this built-in function to specify an attachment variable which contains the value for the ReplyTo option:

< MailType:SMTP >

ReplyTo = ~GetAttach REPLYTO,INPUT

The value for the ReplyTo option is replaced by the value of the attachment variable in the input attachment with the name REPLYTO.

The first parameter is the name of the attachment variable, the second is the

INPUT or OUTPUT, specifying which attachment is used.

You can use the built-in INI function in the DAP.INI file or in a particular configuration INI file. You cannot use it in the DOCSERV.INI or DSI.INI files.

For SMTP, this option lets you specify who the email was from.

For SMTP, this option lets you specify an alternative from address, indicating where the email was from.

Enter the port.

Enter the address of the server.

Enter Yes to turn on debugging.

TTACHMENT

ARIABLES

SED BY

MAIL

ULES

Messages sent to the IDS are contain attachment variables. Attachment variables can also be used to send information from one rule to another. Some INI options refer to attachment variables. The attachment variables listed below are used by the email rules.

For more information on attachments and the email rules, see the SDK Reference .

Variable

XMLTEMPLATTACH

XMLTEMPLBODY

HTMLATTACHFILE

HTMLBODYFILE

Description

The DPRCreateEMailAttachment rule uses this variable to know which file to open as the template for the attachment. This variable is usually created by the DPRFindTemplate rule.

The DPRCreateEMailAttachment rule uses this variable to know which file to open as a template for the message body. This variable is usually created by the DPRFindTemplate rule.

The file name that contains the output from the template processing used for the attachment. This variable is created by the

DPRCreateEMailAttachment rule and contains a path to a file name—not the actual data.

The file name that contains the output from the template processing used for the message body. This variable is created by the

DPRCreateEMailAttachment rule and contains a path to a file name—not the actually data.

139

Chapter 2

Using the Internet Document Server

140

Variable

RECORDLINE(##)

RECORDPARTS

REQTYPE

Description

The variable that contains raw data sent to IDS from the client. The format of the data is defined by the DFD specified by the Path option in the EmailDFD control group. There can be any number of these variables but no variable can contain more than 1024 bytes of data. The variables must be defined as follows:

(RECORDLINE00 RECORDLINE01…RECORDLINE99)

These variables must be created by the client program. These variables are processed by the DPRParseRecord rule.

The number of RECORDLINE variables. Processed by the

DPRParseRecord rule.

The transaction identifier code. Used by the DPRFindTemplate and

DPRAdd2Attachment rules to determine which template to use for a particular message.

The email address. Serves as input for the DPRMail rule.

The body of email. Serves as input for the DPRMail rule.

The subject of the email.

A file attached to the email—no template processing.

ADDRESS

MSGBODY

SUBJECT

ATTACHMENT

SING

MAIL

ULES

You can use the following rules when working with email. For more information, see the

SDK Reference .

DPRParseRecord

Use this rule to assemble an attachment into a record and then convert to an XML tree.

This rule expects the RECORDLINE## and RECORDPARTS attachment variables in the message it receives. The rule performs the following operations.

Takes the data from each of the RECORDLINE## variables and appends them together into one record.

The data from this record is converted into an XML tree with variable names in the

ATTCHDFD.DFD file used as the variable names for the XML tree.

The data from the DFD variables can be transferred to attachment variables.

Therefore you can use any variable defined in the DFD to set any of the specific attachment variables listed in the previous section. The Email2IDS control group maps the DFD variable names to the attachment variable names. So you have two groups of variables; the attachment variables and the XML tree variables.

< Email2IDS >

DFD VARIABLE = ATTACHMENT VARIABLE

DPRFindTemplate

Use this rule to specify the template file. It expects a REQTYPE variable name to in the attachment. So the DPRParseRecord rule must be executed first to set the REQTYPE variable. It uses the XML2Body control group to define the templates to create the message body and the XML2Attach control group to set up email attachments.

Using IDS to Distribute Email

DPRAdd2Attachment

DPRCreateEMailAttach ment

Use this rule to set attachment variables from the INI file. It uses the

EmailAdd2Attachment control group in the INI file to set the variable names. It can use a default setting in the INI file or it can use a specific request type, or multiple request types.

< EmailAdd2Attachment > e301 = SUBJECT, Warning Notice e301 = ATTACHMENT, d:\ticket.doc

default = SUBJECT, Important notice

Use this rule to perform template processing. This rule can be used for the message body as well an attachment. Template processing uses a text or HTML file to define constant data. Variable data is then inserted at indicated places within the text.

Here is an example of a template text file. You must define the CurrentDate and

AcctName fields in the ATTCHDFD.DFD file.

DPRMail

<%descendant::COLUMN[ATTRIBUTE::NAME="CurrentDate"],%>

Dear <%descendant::COLUMN[ATTRIBUTE::NAME="AcctName"],%>,

Thank you for opening a certificate of deposit with DeepGreen Bank.

You will receive documents pertaining to your account in the mail shortly. If you have any questions, please email us at [email protected] or contact our Customer Care

Center at 1-888-888-8888.

Sincerely,

DeepGreen Bank

E301

Whether the template is used for the message body or an attachment depends on whether the request type was listed under the XML2Body or the XML2Attach control group. This is determined when the DPRFindTemplate rule is executed.

Use this rule to transfer the data from the attachment variables to the email server. IDS acts as a client to an email server such as Microsoft Exchange. The following attachment variables should be considered as input to this rule.

• ADDRESS

• MSGBODY

• SUBJECT

• ATTACHMENT

• HTMLATTACHFILE

• HTMLBODYFILE

141

Chapter 2

Using the Internet Document Server

DPRLog

Use this rule to confirm whether an email was sent by IDS. This rule stores information in a log file from either the attachment variables or the XML document created by the

DPRParseRecord rule. The DPRMail rule puts the RESULTS attachment variable into the output queue. If no RESULTS variable exists, then the DPRMail rule was not executed and no mail was sent.

SING THE

MAIL

US

IDS includes an email message bus you can use to receive request messages with or without file attachments from an email inbox. Replies can be emailed asynchronously with or without file attachments to the originators of the request messages.

You can also configure a reply email box as the default reply queue in the server or client configuration files, in which case test utilities or client applications using DSILIB or

DocucorpMsg Java package can also communicate with IDS via the email message bus.

The main body part of a request should be formatted in plain text and should contain the XML that should be used as the main body part of the MIME message. Here is an example:

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ envelope/">

<SOAP-ENV:Body>

<UNIQUE_ID>f9db68c1b1c67998662b6cee85a5bdd2</UNIQUE_ID>

</CTLBLOCK>

</MSGVARS>

</DSIMSG>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

The content of the main body part of a reply message can be formatted via an XSL template that is accessible to IDS and that is supplied via input message variable

MAIL.MARSHALLER.XSL.TEMPLATE. If an XSL template is not provided, IDS returns XML of a format similar to that in the example shown above for a request message.

Malformed email requests are logged in a bad-soap.log file along with a reference ID and

IDS will change the request type to EML and send a response along with the same reference ID back to the end user detailing the nature of the error.

For information on these properties, please see the HTML documentation shipped with

IDS. You will find this documentation in the following directory: dsi_sdk\java\docs\com\docucorp\messaging\mail\DSIMailMessageQueueFa ctory.html

Be sure to specify the MailDSIMessageMarshaller and the

DSIMailMessageQueueFactory classes for the marshaller and queue.factory properties.

142

Using IDS to Distribute Email

Here is an example of a queue configuration section for IDS (docserv.xml):

<entry name="marshaller.class">com.docucorp.messaging.data.marshaller.Mail

DSIMessageMarshaller</entry>

</section>

<entry name="queuefactory.class">com.docucorp.messaging.mail.DSIMailMessag

eQueueFactory</entry>

<entry name="mail.input.server">pop.gmail.com</entry>

<entry name="mail.input.user">requestq</entry>

<entry name="mail.input.password">pdtest123</entry>

<entry name="mail.input.queue">[email protected]</entry>

<entry name="mail.input.ssl.socketFactory.class">com.docucorp.messaging.ma

il.ssl.input.DSIMailSSLSocketFactory</entry>

<entry name="mail.input.ssl.socketFactory.fallback">false</ entry>

<entry name="mail.input.ssl.keystore">c:/docserv/keystore/ cacerts</entry>

<entry name="mail.input.ssl.keystore.pwd">changeit</entry>

<entry name="mail.input.ssl.truststore">c:/docserv/keystore/ cacerts</entry>

<entry name="mail.input.ssl.truststore.pwd">changeit</entry>

<entry name="mail.output.server">smtp.gmail.com</entry>

<entry name="mail.output.user">[email protected]</entry>

<entry name="mail.output.password">pdtest123</entry>

<entry name="mail.output.queue">[email protected]</entry>

<entry name="mail.output.ssl.socketFactory.class">com.docucorp.messaging.m

ail.ssl.output.DSIMailSSLSocketFactory</entry>

<entry name="mail.output.ssl.socketFactory.fallback">false</ entry>

<entry name="mail.output.ssl.keystore">c:/docserv/keystore/ cacerts</entry>

143

Chapter 2

Using the Internet Document Server

<entry name="mail.output.ssl.keystore.pwd">changeit</entry>

<entry name="mail.output.ssl.truststore">c:/docserv/keystore/ cacerts</entry>

<entry name="mail.output.ssl.truststore.pwd">changeit</entry>

</section>

144

Using IDS to Run Documaker

SING

IDS

TO

UN

OCUMAKER

You can set up IDS to run Documaker as a subordinate process, as shown below. Web clients communicate with IDS using queues. IDS communicates with Documaker via

XML files called

job tickets and job logs.

This diagram illustrates the process:

Web Client

VB\COM\

Java Client

IDS

XML Job

Ticket

Documaker

(GenData)

XML

Job Log

IDS can start or stop Documaker as needed, without user interaction. One IDS session controls one Documaker process. You can, however, implement multiple IDS sessions and have multiple Documaker processes as well.

Keep in mind these limitations:

• You can only run Documaker in single step mode. Consult the Documaker

Administration Guide for more information on single step processing.

• 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 IDS 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.

• IDS and Documaker must exist on the same node/server machine.

145

Chapter 2

Using the Internet Document Server docserv.xml file

DAP.INI file

RPEX1.INI file

ETTING

P

IDS

To set up IDS to run Documaker, make these changes in the following configuration files:

Make these changes in the docserv.xml file, or the configuration file the IDS is configured to use. Here is an example of how to add a request type for Documaker:

<entry name="function">atcw32->;ATCLogTransaction</entry>

<entry name="function">atcw32->;ATCLoadAttachment</entry>

<entry name="function">atcw32->;ATCUnloadAttachment</entry>

<entry name="function">dprw32->;DPRSetConfig</entry>

<entry name="function">rpdw32->;RPDCheckRPRun</entry>

<entry name="function">rpdw32->;RPDCreateJob</entry>

<entry name="function">rpdw32->;RPDProcessJob</entry>

</section>

If necessary, add two more request types, one to check if Documaker is running and one to stop Documaker. Here is an example:

<entry name="function">atcw32->;ATCLogTransaction</entry>

<entry name="function">atcw32->;ATCLoadAttachment</entry>

<entry name="function">atcw32->;ATCUnloadAttachment</entry>

<entry name="function">dprw32->;DPRSetConfig</entry>

<entry name="function">rpdw32->;RPDCheckRPRun</entry>

</section>

<entry name="function">atcw32->;ATCLogTransaction</entry>

<entry name="function">atcw32->;ATCLoadAttachment</entry>

<entry name="function">atcw32->;ATCUnloadAttachment</entry>

<entry name="function">dprw32->;DPRSetConfig</entry>

<entry name="function">rpdw32->;RPDStopRPRun</entry>

</section>

Also add the following IDS rule to the ReqType:INI section:

<entry name="function">rpdw32->;RPDStopRPRun</entry>

Add a configuration option for a the master resource library you will use. Here is an example which is based on the RPEX1 master resource library:

< Configurations >

CONFIG = RPEX1

< Config:RPEX1 >

INIFile = RPEX1.INI

Make these changes in the RPEX1.INI file (or the INI file you are using for your configuration):

< IDSServer >

ExtrPath = e:\fap\mstrres\rpex1\extract\

PrintPath = e:\fap\mstrres\rpex1\data\

WaitForStart = 60

SleepingTime = 500

MaxWaitTime = 120

146

Using IDS to Run Documaker

GENSemaphoreName = gendata

RPDSemaphoreName = rpdrunrp

PrintFileCacheTime = 7200

TextFileCacheTime = 7200

< RPDRunRP >

Executable = e:\rel101\shipw32\gendaw32.exe

Directory = e:\fap\mstrres\rpex1\

UserINI = e:\fap\mstrres\rpex1\fsiuser.ini

BaseLocation = http://10.8.10.69/fap/mstrres/rpex1/data/

< Printer >

PrtType

< Debug >

= PDF

RPDProcessJob = Yes

Setting up Multiple Internet Document Servers

The semaphores used by IDS and Documaker are global for a computer, so if you need multiple IDS processes on the same computer, each IDS process and subordinate

Documaker process should use different semaphore names.

Semaphore names are generated automatically by IDS for each instance. These names are passed to Documaker as command line parameters. No user intervention is needed.

To specify naming conventions for these semaphores, change these INI options:

< IDSServer >

GENSemaphoreName =

RPDSemaphoreName =

Keep in mind the names must be unique for a computer, so two IDS servers will have to use two different INI files specifying semaphore names.

Controlling Documaker

To control Documaker via IDS, use these IDS rules:

• RPDCheckRPRun - Makes sure Documaker is running. If Documaker 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 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 process.

• RPDStopRPRun - Receives the current process ID from the RPDRunProcess variable and then terminates Documaker.

For more information about these rules, see the SDK Reference .

147

Chapter 2

Using the Internet Document Server

If a critical error is encountered

IDS restarts Documaker Server (GenData) if it encounters a critical error and resubmits the transaction being processed when the error occurred. This helps you handle situations where you have sporadic memory access problems in custom or 3rd-party code.

OTE

Before the release of version 11.2 shared objects, when the GenData program started, the RPDProcessJob rule communicated with GenData via TCP/IP, sending the job ticket message to GenData and receiving a job log response. If the TCP/IP communication failed, the RPDProcessJob rule forced GenData to stop. This would prepare IDS for the next request.

Version 11.2 shared objects added the ability to automatically restart GenData after the process described above. After it confirms that GenData has been stopped, the RPDProcessJob rule calls the RPDCheckRPRun rule to restart

GenData and then calls itself to communicate with GenData and send the same job ticket.

To keep a copy of each transaction, an eight-digit index number is added to the job ticket and job log file names when they are downloaded for information in debug modes.

Also, the system includes these error messages which can appear if there is a TCP/IP failure:

Message

RPD0011

RPD0012

RPD0013

RPD0014

RPD0016

RPD0017

RPD0018

Description

Unexpected program termination of GenData.

Socket connection failure.

Can not unload job ticket to the msg buffer.

Can not load the msg buffer to the job log.

Socket time-out.

Time exceeded the MaxWaitForStart specification.

GenData failure.

The system includes additional information in the log trace file in case of failure. This includes the job ticket, the input attachment variables, and error messages. On the IDS side, this file is named

dprtrc.log. On the GenData side, this file is the trace file.

148

Using IDS to Run Documaker

Error file processing

You can use INI options to turn on or off the recording of error information when using

IDS to run Documaker. This can help in debugging.

To create an error file and write errors into the error file, include these options in the

Debug control group:

< Debug >

RPDCheckRPRun = Yes

RPDCreateJob = Yes

RPDProcessJob = Yes

RPDErrFile = rpderr.dat

Option Description

RPDCheckRPRun Enter Yes if you want to record any errors encountered when running this rule. If you enter No, errors produced while this rule is run are not recorded.

RPDCreateJob

RPDProcessJob

RPDErrFile

Enter Yes if you want to record any errors encountered when running this rule. If you enter No, errors produced while this rule is run are not recorded. Be sure to set this option to Yes to record GenData errors.

Enter Yes if you want to record any errors encountered when running this rule. If you enter No, errors produced while this rule is run are not recorded.

Enter the name of the error file. The system does not create an error file if you do not enter a name in this field.

Returning record IDs

When you use IDS to run Documaker with WIP and archive rules, the WIP and archived record IDs are written to the print log (PrtLog) file. Furthermore, the first WIP record ID and the first archived record ID are sent to a job log (JobLog) file and are also output as the following attachment variables.

Variable

WIPRECORDID

ARCRECORDID

Description

The first WIP record ID.

The first archived record ID.

These XML elements are added to both the PrtLog and JobLog files:

149

Chapter 2

Using the Internet Document Server

FSISYS.INI or

FSIUSER.INI file

ETTING

P

OCUMAKER

The first step is to set up Documaker to run in a single step mode. See the Documaker

Administration Guide for more information.

Keep in mind these considerations...

• If the Documaker programs and DSOs are located on the network, the start time for

Documaker can be significant. Keep in mind, however, that the start time only affects the first transaction. Subsequent transactions will process much more quickly. If the start time exceeds 10 seconds, consider changing the WaitForStart option to a higher value.

• All of the standard Documaker performance-related INI options are available even when IDS runs Documaker as a subordinate process. For best results, optimize

Documaker’s performance before using it with IDS.

• Documaker will run fastest if the resource files for Documaker, as well as input and output files, are physically located on the computer where IDS and Documaker are running.

• Documaker (GenData) automatically creates the XML export file from the transaction and returns the name as XMLOUTPUT and URLXMLOUTPUT.

In addition, you will need to make changes to your FSISYS.INI or FSIUSER.INI files and to your AFGJOB.JDT file.

Be sure to turn off all Documaker stop options, as shown here:

< GenDataStopOn >

BaseErrors = No

TransactionErrors = No

ImageErrors

FieldErrors

= No

< GenData >

ClearMsgFile

< PrintFormSet >

MultiFilePrint

LogFileType

LogFile

= Yes

= XML

= .\data\printlog.xml

Option Description

GenDataStopOn control group

BaseErrors Enter No to prevent the system from stopping on base-level errors.

TransactionErrors Enter No to prevent the system from stopping on transaction-level errors.

ImageErrors Enter No to prevent the system from stopping on image-level errors.

FieldErrors Enter No to prevent the system from stopping on field-level errors.

GenData control group

150

Using IDS to Run Documaker

Option

ClearMsgFile

Description

Enter Yes to clear the message file (MsgFile) before a job process starts.

This prevents the previous job’s information from being reused and is necessary when running in single-step mode. The default is No.

PrintFormSet control group

MultiFilePrint Enter Yes to generate multiple print files which have a 46-byte unique name.

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 MultiFilePrint option should only be used with the PDF, RTF,

HTML, and XML print drivers.

LogFileType

LogFile

Specify the type of the log file, such as XML or TEXT.

Specify the name and path of the log file, such as

\data\printlog.xml

If you omit the extension, the system uses the LogFileType option to determine the extension.

These INI options are optional:

< IDSServer >

SleepingTime = 500

GENSemaphoreName = gendata

RPDSemaphoreName = rpdrunrp

< Debug >

RULServerJobProc = Yes

Option

IDSServer control group

Description

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 Semaphore names are generated by IDS for each instance and are passed to Documaker as command line parameters. Use this option to specify naming conventions for semaphore names. The default is

gendata.

Keep in mind semaphore names must be unique for a computer, so two IDS servers will have to use two different INI files specifying semaphore names.

RPDSemaphoreName Semaphore names are generated by IDS for each instance and are passed to Documaker as command line parameters. Use this option to specify naming conventions for semaphore names. The default is

rpdrunrp.

Keep in mind semaphore names must be unique for a computer, so two IDS servers will have to use two different INI files specifying semaphore names.

Debug control group

151

Chapter 2

Using the Internet Document Server

AFGJOB.JDT file

Option

RULServerJobProc

Description

Enter Yes to get a copy of the job ticket file before the system removes it.

Prior to the release of version 11.1, you had to change the base rule from

RULStandardBaseProc, as shown here:

;ServerBaseProc;1;;

...

The ServerBaseProc rule replaced the RULStandardJobProc rule and let IDS run

Documaker as a separate,

stay alive process. This meant Documaker only had to start once and IDS could continue even if Documaker failed. For more information on the

ServerBaseProc rule, see the Rules Reference .

OTE

If you are running Documaker version 11.1 or higher, you do not have to substitute ServerBaseProc for RULStandardBaseProc.

Naming Conventions for Output Files

The output files from Documaker use the names generated by the IDS rules and submitted to Documaker in the job ticket file. If you need different names, provide them in the IDS request. In this case, you must make sure the names are unique or else they will be overwritten. The names generated by IDS can consist of up to 45 characters and are similar to the names generated by the DPRPrint rule in IDS.

The directory where the output files are created is determined in this manner:

• If the file name and path was provided, the system uses that information.

• If the file name was provided, but the path was omitted, the system looks for the path in the PRINTPATH attachment variable.

• If the path is not in the PRINTPATH attachment variable, the system looks for the

PrintPath option in the DSIServer control group.

• If no path was specified in the PrintPath option, the system places the output file in the current directory.

The extension of the output files is determined in this manner:

• If the name and extension was provided in the attachment, the system uses that information.

• If the name and extension were omitted, the system generates a name and uses the printer type as the extension for the print output files. For other files, the system looks for the FileExt option in the IDSServer control group to find the extension.

The default is

DAT.

152

Using IDS to Run Documaker

REATING

DPW F

ILES

You can generate a DPW file from GenData or from an import file using IDS. The code is structured as a print driver so setting it up is virtually the same as with print drivers.

The DPW library supports the INI2XML, WIP2DPW, and File2DPW control groups used by the WIP Edit plug-in. To generate a DPW file from Documaker, include these

INI options:

< Printers >

PrtType

< Printer >

= DPW

PrtType

< PrtType:DPW >

= DPW

PrintFunc = DPWPrint

Module = DPWW32

Debug = No

Set the Debug option to Yes to capture additional debug information to the trace log.

The PrtType:DPW group can also contain variable names that correspond to index element names in the DPW file. The values specified can be one of these formats: name = val

The value will be used as provided, where

val is the actual value provided.

name = ~GVM gvmname

If the DPW library is run under the GenData program, the value of the GVM variable matching the name provided is used, where

gvmname stands for the name provided.

name = ~GetAttach attachname

If the DPW library is run under IDS, the value of the attachment variable matching the name provided will be used, where

attachname stands for the name provided.

The system checks the index of the DPW file for the presence of any variables specified in the PrtType:DPW control group and, if present, it updates their values with those specified in the INI file.

153

Chapter 2

Using the Internet Document Server

On the IDS side

On the Documaker side

CCESSING

IDS A

TTACHMENT

ARIABLES IN

EN

ATA

There are times when the GenData program needs access to data passed from IDS which is not in the extract file. To meet this need, the GenData program can access IDS attachment variables as GVM variables. If a GVM variable with the same name already exists, its value does not change.

Here is how it works:

The RPDCreateJob rule adds any input attachment variables to the XML tree (job ticket) besides the existing variables, such as MsgFile, ErrFile, ExtrFile, LogFile, DbLogFile,

NaFile, PolFile, NewTrn, PrtLog, PrtType, ExtrPath, PrintPath, PrintBatches,

BatchFiles, IniOptions, EWPSRequest, EWPSResults, ShowErrors, WIPRECORDID,

XMLOUTPUT, and so on.

For example, if an attachment variable called RPDTEST is located and it has a value of

This is a test, it is added to the XML tree as shown here:

. . .

</JOBTICKET>

</DOCUMENT>

After the ServerJobProc rule receives the XML tree (job ticket), its child elements are used to update INI values or create GVM variables or both.

In IDS

SING

TCP/IP C

OMMUNICATIONS

IDS and GenData use TCP/IP (socket) to replace the job ticket/job log file I/O communication.

The RPDCheckRPRun rule sets up the host name and the port number for a GenData configuration by checking the HOST name and PORT number from these INI options:

< IDSServer >

MaxConfigAllowed = 10

Host = localhost

Port = 49300

Option Description

MaxConfigAllowed Enter the maximum number of configurations you want to allow. The default is 10.

Host

Port

Enter the host name. The default is localhost.

Enter the base IP port number. The default is 49300.

If you have multiple GenData configurations running over multiple IDS instances, the port number is generated based on the IDS instance number and the base IP port number, so you must decide the base IP port number and the range of IP port numbers. Note that the total number of IP port numbers is decided by:

154

Using IDS to Run Documaker instances (IDS instance number) x MaxConfigAllowed (allowed to open GenDatas)

If the current configuration differs from the previous configuration, the current configuration starts a GenData process with the assigned IP port number. Both the host name and port number are saved in the configuration structure and are appended to the configuration list. If the configuration exists, the configuration element is extracted and uses the saved host and port number as current.

OTE

TCP/IP communication is for shared objects 11.1 and above and can not be used with early versions.This rule checks the version to decide whether TCP/IP or file

I/O communication should be used before it starts a GenData process.

The RPDProcessJob rule uses the host name and port number to establish communication with GenData and sends a message that contains the XML document

(job ticket) to the server (GenData) when it detects that GenData has started. You can set the maximum time to wait for GenData to start using this INI option:

< IDSServer >

WaitForStart = 30

Option

WaitForStart

Description

Enter the maximum time to wait for GenData to start in seconds. The default is 30 seconds.

After IDS detects that GenData has started, it sends a message in XML format (the job ticket) and waits for GenData to finish and send back a response in XML format (the job log file). You can set the maximum time to wait for GenData to respond using this INI option:

< IDSServer >

MaxWaitTime = 30

Option

WaitForStart

Description

Enter the maximum time to wait for GenData to respond in seconds. The default is 30 seconds.

In GenData

If GenData does not start before the waiting time elapses, IDS displays this error message on the IDS side:

Unexpected Program Termination of GenData

As soon as GenData starts, it initiates the communication between IDS and GenData using the IP port number retrieved from the command line argument. It receives the job ticket document sent by IDS and continues the GenData process. You can set the maximum time to wait to receive a job ticket using this INI option:

< IDSServer >

MaxWaitTime = 30

155

Chapter 2

Using the Internet Document Server

Option Description

MaxWaitTime Enter the maximum time to wait to receive a job ticket in seconds. The default is 30 seconds.

After GenData finishes, the JOBLOG tree is unloaded into a message buffer and is sent to client side as a response message.

You can use options in the Debug control group to determine whether to unload the job ticket and job log files for reference purposes. On the IDS side, set this option to Yes to keep a copy of the job ticket:

< Debug >

RPDProcessJob = Yes

On GenData side, set this option to Yes to keep a copy of the job log:

< Debug >

RULServerJobProc = Yes

USTOMIZING THE

XECUTION OF

OCUMAKER

When IDS runs Documaker in multiple step mode, you can introduce special steps which occur between the GenTrn, GenData, and GenPrint steps. You can use these steps, for instance, to...

• Sort the TRNFILE or recipient batches

• Copy files to different locations

• Send files to the printer

• Notify an operator that steps were completed

The RPDRunRP rule can run a custom executable after each step in the process. Use these INI options to define the custom executable name and path:

< RPRun >

PostGenTrnExecutable =

PostGenDataExecutable =

PostGenPrintExecutable =

Option

PostGenTrnExecutable

PostGenDataExecutable

PostGenPrintExecutable

Description

Enter the name and path of the custom executable, such as a batch file or shell script, you want the system to run after it completes the

GenTrn step.

Enter the name and path of the custom executable, such as a batch file or shell script, you want the system to run after it completes the

GenData step.

Enter the name and path of the custom executable, such as a batch file or shell script, you want the system to run after it completes the

GenPrint step.

156

Using IDS to Run Documaker

By default, the following information is passed as parameters to each executable:

GenTrn – INI file, trnfile

GenData – INIfile, recipient batches

GenPrint – INI file, print file

These INI options are read from the FSIUSER.INI file to create the parameter list. The

FSIUSER.INI file is created by the RPDRunRP rule. This INI file is passed to

Documaker for each step. Internally, the RPDRunRP rule loads the FSIUSER.INI file and gets parameter information from it.

GenTrn parameters

< Data >

TrnFile = (parameter trnfile)

GenData parameters

The system reads all of the options under the Print_Batches control group to determine the recipient batches:

< Print_Batches >

Batch# = (paramter receipient batches )

GenPrint parameters

The system reads all of the print batches to determine the printer used and passes the port value for the printer as the parameter.

< Print_Batches >

Batch1 = (value ignored)

< Batch1 >

Printer = Printer1

< Printer1 >

Port = (parameter print file)

If any of the INI options are missing, the system logs an error. It will, however, try to run the post process without the missing parameter. Memory and list allocation errors result in failure and the system will not attempt to execute the outside process. Here is a list of the potential errors:

Error

Could not get INI option <Data> TrnFile GenTrn step

Could not create VMM list GenTrn step

Could not load INI file GenTrn step

Could not get INI context GenTrn step

Could not create VMM list GenData step

Could not load INI file GenData step

Could not get INI context GenData step

Could not create VMM list GenPrint step

Severity

non-fatal fatal fatal fatal fatal fatal fatal fatal

157

Chapter 2

Using the Internet Document Server

Error

Could not load INI file GenPrint step

Could not get INI context GenPrint step

Could not get INI option GenData step <group> <option>

Could not start process: [executable name and command line]

Memory re-allocation failed

Memory allocation failed

PROCStartProcess failed: [command line]

PROCWaitProcess failed: [executable name and command line]

PROCExitCodeProcess failed: [executable name and command line] fatal fatal fatal

Severity

fatal fatal non-fatal non fatal non fatal

158

Using the XML Messaging System

SING THE

XML

ESSAGING

YSTEM

The XML messaging system is an open and documented queue control message format based on XML and the evolving SOAP standard. The XML message format is supported by the JMS, WebSphere MQ, and HTTP messaging systems.

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

For information on using SOAP without a messaging system, see Using XML SOAP

Outside of Messaging Systems on page 158 .

OTE

Oracle Insurance 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.

Oracle Insurance has used message queuing as a means of serializing requests and responses between loosely coupled clients and servers without requiring one-toone connections.

Docupresentment includes the client and server sides of the DSI (document server interface) system and of the Oracle Insurance Messaging Library system. These interface layers help manage connections between multiple simultaneous clients and multiple simultaneous servers.

The Oracle Insurance Messaging Library provides a logical abstract layer over the physical process of accessing the queue, so one implementation can support and switch between multiple queueing systems.

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...

• Interface with external systems via messaging middleware.

• Interface with IDS 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 messaging middleware.

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.

159

Chapter 2

Using the Internet Document Server

The XML-based DSI message format

By abstracting the message format, applications are insulated from internal changes to the message format and can use the Oracle Insurance APIs to correctly assemble or disassemble messages.

The disadvantage of message format abstraction is that non-Oracle Insurance applications might be required to use Oracle Insurance APIs to communicate with Oracle

Insurance 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 IDS 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 IDS APIs.

The following topics outline the XML message file format.

The DSI message format complies with the following XML-based structure:

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ envelope">

<SOAP-ENV:Body>

<UNIQUE_ID> { guid hex string } </UNIQUE_ID> (required)

<REQTYPE> { message request type } </REQTYPE> (required)

<USERID> { user ID }</USERID> (optional)

<RESULTQMGR> { remote queue manager } </RESULTQMGR>

(optional)

<RESULTQ> { remote queue name } </RESULTQ> (optional)

<ATTACHMENT TYPE="TEXT or BINARY"> (optional)

<DELIMITER> { tag delimiter } </DELIMITER> (required for ATTACHMENT)

</ATTACHMENT>

</CTLBLOCK>

<MSGVARS> (required)

<VAR NAME="VAR NAME 1"> { MSG VAR CONTENT 1 } </VAR>

<VAR NAME="VAR NAME 2"> { MSG VAR CONTENT 2 } </VAR>

<VAR NAME="VAR NAME 3"> { MSG VAR CONTENT 3 } </VAR>

</MSGVARS>

</DSIMSG>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

MIME headers

... Optional attached text data

... Example: a flat text extract file

... Example: an XML data file

... Example: a base64 (MIME) text encoded binary file

MIME headers

160

Using the XML Messaging System

Without attachments

Please note:

• The essential component of the message format is the DSIMSG structure, which is encoded inside SOAP-ENV envelope and body structures.

• The indentation of the elements is intended to make it easier to read. Actual messages are not indented.)

• The message can contain attached files. Attached files are encoded inside a tagged structure outside the SOAP-ENV structure. Note that once tagged outside of the primary structure in this fashion, the message file itself is no longer well-formed

XML and cannot be viewed with some XML viewers. While it is not well-formed

XML, it is a valid SOAP with attachments format.

The DSI system manages the separation of the attached files from the message. Each

ATTACHMENT structure describes the controlling attributes of the attached files.

The TYPE attribute specifies the type and format of the attached file, either as

TEXT

(the default) or

BINARY

(MIME format). The DELIMETER element specifies a unique tag name, which is required to be inside the beginning and ending tag brackets to delimit the file data.

• Request and response messages have identical formats. The current specification does not require a distinction between

requests sent by the client and responses returned by the server.

• The client initiating the request generates the UNIQUE_ID. The server echoes the same unique identifier in the response.

• The type of request is identified by the REQTYPE element. Client and server applications must understand and agree on the identifier for the request, the nature of the work to be performed as a result, and the response to be generated.

• The RESULTQMGR and RESULTQ elements are optional, but will appear based on certain types of queue configurations.

• The MSGVARS structure provides the DSI attachment variables which would previously have been encoded using the DSIAddAttachVar rule in the IDS SDK.

Client Request Messages

Here are several example client request messages in XML format:

Here is an example of a client request message in XML format which does not include attachments

Content-Type: text/xml

Content-Transfer-Encoding: 8bit

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ envelope">

<SOAP-ENV:Body>

<UNIQUE_ID>a9ae6c91-1d1b-11d2-b21a-00c04fa357fa</UNIQUE_ID>

<REQTYPE>CLAIMS DATA</REQTYPE>

161

Chapter 2

Using the Internet Document Server

162

With attachments

</CTLBLOCK>

<VAR NAME="KEY2">CONTACT</VAR>

</MSGVARS>

</DSIMSG>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Here is an example of a client request message in XML format which does include attachments:

Content-Type: multipart/related; boundary=IDSMessage

--IDSMessage

Content-Type: text/xml

Content-Transfer-Encoding: 8bit

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ envelope">

<SOAP-ENV:Body>

<UNIQUE_ID>a9ae6c91-1d1b-11d2-b21a-00c04fa357fa</UNIQUE_ID>

<REQTYPE>CLAIMS DATA</REQTYPE>

<DELIMITER>CLAIMS-DATA</DELIMITER>

</ATTACHMENT>

</CTLBLOCK>

<VAR NAME="KEY2">CONTACT</VAR>

</MSGVARS>

</DSIMSG>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

--IDSMessage

Content-Type: application/ids

Content-Transfer-Encoding: 7bit

Content-ID: CLAIMS-DATA

{…data in a structured COBOL record appears here …}

--IDSMessage--

Using the XML Messaging System

With multiple attachments

Please note:

• The client initiates the request and generates the UNIQUE_ID. The server echoes back the same unique identifier in the response.

• The MSGVAR structure in this example provides the key fields necessary to access the claims data and create the exported data to be delivered to the client. A server application can receive more variables than are needed and should be set up to ignore those not applicable.

• The ATTACHMENT structure provides the

delimiter element, which is used to specify the delimiting string pattern that frames a data record passed as an attached file as a part of the message.

Here is an example of a client request message in XML format which has multiple attachments:

Content-Type: multipart/related; boundary=IDSMessage

(Please note that this new line must be included.)

--IDSMessage

Content-Type: text/xml

Content-Transfer-Encoding: 8bit

(Please note that this new line must be included.)

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ envelope">

<SOAP-ENV:Body>

<UNIQUE_ID>a9ae6c91-1d1b-11d2-b21a-00c04fa357fa</UNIQUE_ID>

<REQTYPE>CLAIMS DATA</REQTYPE>

<DELIMITER>CLAIMS-DATA</DELIMITER>

</ATTACHMENT>

<DELIMITER>CLAIMS-BINARY</DELIMITER>

</ATTACHMENT>

</CTLBLOCK>

<VAR NAME="KEY2">CONTACT</VAR>

</MSGVARS>

</DSIMSG>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

(Please note that this new line must be included.)

--IDSMessage

Content-Type: application/ids

Content-Transfer-Encoding: 7bit

Content-ID: CLAIMS-DATA

163

Chapter 2

Using the Internet Document Server

{…data in a structured COBOL record appears here …}

--IDSMessage

Content-Type: application/ids

Content-Transfer-Encoding: base64

Content-ID: CLAIMS-BINARY

(Please note that this new line must be included.)

{…data in a base64 encoding form appears here …}

--IDSMessage--

Server XML Response Messages

Here is an example of the XML response message from the server:

Content-Type: multipart/related; boundary=IDSMessage

(Please note that this new line must be included.)

--IDSMessage

Content-Type: text/xml

Content-Transfer-Encoding: 8bit

(Please note that this new line must be included.)

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ envelope">

<SOAP-ENV:Body>

<UNIQUE_ID>a9ae6c91-1d1b-11d2-b21a-00c04fa357fa</UNIQUE_ID>

<REQTYPE>CLAIMS DATA</REQTYPE>

</ATTACHMENT>

</CTLBLOCK>

<VAR NAME="RESULTS">SUCCESS</VAR>

</MSGVARS>

</DSIMSG>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

(Please note that this new line must be included.)

--IDSMessage

Content-Type: application/ids

Content-Transfer-Encoding: 7bit

Content-ID: DOCC-XML

(Please note that this new line must be included.)

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

<DESCRIPTION>Common Policy Declarations</DESCRIPTION>

164

Using the XML Messaging System

<SHEET>

<PAGE>

<FIELD NAME="DELIVERY">DELIVERY NOTE</FIELD>

<FIELD NAME="ON_ARRIVAL">ON ARRIVAL NOTE</FIELD>

<FIELD NAME="CLAIMANT_NAME">SUSAN FRIEDEN</FIELD>

<FIELD NAME="CLAIMANT_ADDRESS">ADDRESS HERE</FIELD>

<FIELD NAME="POLICY_NUMBER">POLICY NUM 22222</FIELD>

<FIELD NAME="SALUTATION">SALUTATION FIELD</FIELD>

<FIELD NAME="INSURING_COMPANY">INSURING COMPANY N</FIELD>

</SECTION>

</PAGE>

</SHEET>

</FORM>

</GROUP>

</DOCSET>

</DOCUMENT>

--IDSMessage--

Please note:

• The client generated UNIQUE_ID is echoed back in the response.

• The ATTACHMENT structure specifies the delimiter for the embedded XML export file. In this example, the file is called

DOCC-XML.

• The MSGVAR structure specifies the returned attachment variables, which include the results from the requested operation, returned in the variable named

RESULTS.

In this example, the result is

SUCCESS. If there is an error, the result is an error code and, typically, no XML export data is included.

• If you are transmitting messages between dissimilar platforms, say an EBCIDIC platform such as an MVS-based server application which is submitting messages to an ASCII platform such as a PC, you must set the message format attribute in the message descriptor to

string (text). This lets the MQ Series channel sender/receiver perform the EBCDIC-to-ASCII translation. Likewise, the QSRLIB layer of the

Oracle Insurance system sets the request message format to

string so the ASCII-to-

EBCDIC translation takes place. As a result, client and server applications are able to see the message data in the proper format and do not have to perform the translation themselves.

SING

XML SOAP O

UTSIDE OF

ESSAGING

YSTEMS

Using the DSIGetSOAPMessage and DSIGetSOAPMessageSize functions, you can code

IDS client applications (such as iDocumaker) with common APIs using XML DOM of the IDS SOAP XML message. See the SDK Reference for more information on these functions.

These APIs let client applications access the DSI XML message as a buffer in memory.

Access to IDS XML message is provided as a buffer in memory because of possible issues with the version of the DOM or XML parser the client application may be using.

Keep in mind the XML returned is a byte array using UTF-8 encoding.

165

Chapter 2

Using the Internet Document Server

OTE

The GetSOAPMessage is also available for the COM and Java APIs. (DSICO,

IDSASP and DSIJava).

166

Connecting to an SQL Database

ONNECTING TO

AN

SQL

ATABASE

IDSSQL is a set of ActiveX

DSOs (IDSSQL.DLL and IDSSQLRL.DLL) which you can use as a Microsoft ActiveX Data Objects (ADO) programming model.

These DSOs let you send SQL commands and receive records back from an SQL database. Instead of communicating directly with the database as an object, the IDSSQL

DLLs go through an IDS rule. This illustration shows how it works:

Application

(

Could be a Visual Basic or ASP application

)

IDSSQL.DLL

DSI API

IDS

IDSSQLRL.DLL

SQL

Database

167

Chapter 2

Using the Internet Document Server

Differences between Microsoft’s ADO and IDSSQL

Keep in mind these differences between ADO and IDSSQL:

• IDSSQL does not implement all features of Microsoft’s ADO and record set.

• The connection between IDSSQL and the SQL database automatically opens and closes on each execute.

• The new record insert into the database is made using the SQL insert command instead of the insert and update method in the ADO record set.

• Errors are returned through IDS record sets. So it good to have a record set even if the SQL command did not return any records.

Setting up IDSSQL

Follow these steps to set up IDSSQL:

Add these options to your DOCSERV.INI file:

< ReqType:IDSSQL >

Function = atcw32->ATCLoadAttachment

Function = DSICoRul->Invoke,IDSSQLRL.IDS->SQL

Function = atcw32->ATCUnloadAttachment

Set up the ODBC Data source name.

IDSSQL C

LASSES

Here are the properties and methods for IDSSQL.ADO and IDSSQL.IDSRC:

IDSSQL.ADO

Here are the properties and methods for IDSSQL.ADO:

Properties

Property

AbsolutePage

Description

The ordinal position of the current page. The default is zero (0).

If zero (0), all records queried by the SQLcommand are returned.

If set to something other than zero, only those records on the page are returned. The number of records on the page are determined by the

PageSize property.

CommandTimeOut The number of seconds to wait when executing a command before terminating the attempt and returning an error. If you set this property to zero, ADO will simply wait until the execution is complete. The default is 30 seconds.

DSN

PageSize

The ODBC data source name or the information used to create a connection to data source.

The number of records on a page. The default is 10.

168

Connecting to an SQL Database

Property

Password

SQLCommand

User

Description

The password used to connect to the database. A password is required if the DSN connection is not a trusted SQL Server connection.

The SQL statement.

The user ID used to connect to the database. The user ID is required if the DSN connection is not a trusted SQL Server connection.

Methods

Method

Execute

Description

Process SQL command.

Returns the record set requested by SQLCommand.

IDSSQL.IDSRC

Here are the properties and methods for IDSSQL.IDSRC, the IDS record set.

Properties

Property

BOF

EOF

Errors

Field

Fields

RecordCount

Description

True if the current record position is before the first record.

True if the current record position is after the last record.

Errors collection.

Each field of the current record.

Fields information collection.

The number of records currently in the record set.

Methods

Method

MoveFirst

MoveLast

MoveNext

MovePrevious

Description

Move to the first record in the record set and make that the current record.

Move to the last record in the record set and make that the current record.

Move to the next record in the record set and make that the current record.

Move to the previous record in the record set and makes that the current record.

XAMPLE

CRIPT

Here is an example in ASP:

<%@ Language=VBScript %>

<HTML>

169

Chapter 2

Using the Internet Document Server

Fields

<HEAD>

</HEAD>

<BODY>

CrLf = Chr(13) & Chr(10) set sql = Server.CreateObject("idssql.ado") 'Create IDS ADO Object set rc = Server.CreateObject("idssql.idsrc") 'Create IDS record set

ShowAllActivateAccount()

Sub ShowAllActivateAccount() sql.DSN = "COB_TEST"'ODBC Data source name sql.SQLCommand = "Select * from subscriberdata where ebppstatus =

'A'"

Set rc = sql.Execute()‘Execute Command

If rc.Errors.Count <> 0 Then‘Check for error

Response.write "Error source = " & rc.Errors(1).Source & "<BR>"

Response.write "Error Description = " & rc.Errors(1).Description

& "<BR>"

Else

<TR>

<TH>Account#</TH>

</TR>

‘Loop through all the return records and display the fields

For i = 1 To rc.RecordCount

Response.write "<TR>" & Crlf

Response.write "<TD>" & i & "</TD>"

Response.Write "<TD>" & rc.Field("Accountnumber") & "</TD>"

Response.Write "<TD>" & rc.Field("SubscriberFirstName") & " "

Response.Write rc.Field("SubscriberMiddleName") & " "

Response.Write rc.Field("SubscriberLastName") & " "

Response.Write "</TD>" & Crlf

Response.write "</TR>" & Crlf rc.MoveNext ‘Move to next record

</TABLE>

End If

End Sub

</BODY>

</HTML>

Here is an example of how you can access the name and data in the field of each record:

170

Connecting to an SQL Database set

For i = 1 To rc.RecordCount

‘Loop through all return record

Response.Write "========="

Response.Write "Record " & i

Response.Write "========="

For j = 1 To rc.Fields.Count‘Loop through all the fields in that record

Response.Write rc.Fields(j) & ":" ‘Display field name

Response.Write rc.Field(j)‘Display data in the field

You can access the data in the field using the name or index, such as:

Rc.Field(1) or Rc.Field(“SubscriberID”)

171

Chapter 2

Using the Internet Document Server

SING THE

HIN

LIENT

ORMS

UBLISHER

The Thin Client Forms Publisher lets web clients enter a user ID, password, and other information at login. Depending on how you set it up, IDS then returns a list of group1/ group2 combinations for the form set.

The web client can then choose a group1/group2 combination and submit it to IDS along with an effective date. The DPRSetConfig rule sets the effective date for use with Library

Manager.

IDS then returns a new XML form set (through the result queue) based on the group1/ group2 submittal. The Thin Client Forms Publisher loads the XML form set returned by

IDS and generates an HTML tree view.

The web client can then select the forms, images, recipients, and print options and submit a request to print the form set. Once submitted, the Thin Client Forms Publisher generates a new XML form set and sends it to IDS.

IDS retrieves the new XML form set, converts it into a FAP form set and prints it. IDS then sends the final output file to the Thin Client Forms Publisher through the queues.

The Thin Client Forms Publisher supports these print options: PDF, XML, PCL, AFP,

MET, and HTML.

Look at these examples for more information:

Example

/formpub

Uses

dp018.dll which you can use on Windows 2000 without IDS DLL files

/formpubnt idsasp.dll for standard messaging and dp018.dll for XML processing

These virtual directories are included in the IDS sample resources. Use

FORMAKER for the user ID and password when viewing the examples.

172

Pausing IDS

AUSING

IDS

When necessary, you can pause IDS processing and then restart it. For instance, suppose you are running a system with multiple instances of IDS, each running its own

Documanage Bridge, with each Documanage Bridge logging into a separate Documanage system.

In this scenario, you want IDS to become passive (stop processing requests) when the

Documanage system becomes unavailable and to become active again when the

Documanage system becomes available again.

This fail-over strategy avoids situations where IDS is processing requests which are failing because the bridge is having a problem with Documanage server.

To handle this scenario, you use a C or Java DSI API. This API lets a rule request that

IDS go into

pause mode. While in pause mode IDS will not receive requests from a queue and will execute only one request type PAUSE. The frequency of this request is defined using this option in the configuration file:

....

</section>

The entry PauseCheckIntervalSeconds is the interval that IDS will send PAUSE requests to itself when it is paused.

The Documanage Bridge calls the API and places IDS in pause mode when Documanage server becomes unavailable. The rule registered on the PAUSE request type checks to see if the Documanage server is available calls an API to resume the IDS operation.

You use these DSI APIs:

DSIQueryStatus

This API returns DSI specific status options via DSISTATUS_* flags. Use it to determine if IDS is in a paused mode. Here is a list of the available flags:

Flag

DSISTATUS_PAUSE

DSISTATUS_STOP

DSISTATUS_RESTART

DSISTATUS_RESUME

Description

Pause the server

Stop the server and exit the process

Restart the server

Resume the server after a pause

OTE

Setting the status to DSISTATUS_STOP is non-recoverable action. Once the server exits, no other actions are possible.

Syntax

DSIQueryStatus()

173

Chapter 2

Using the Internet Document Server

Returns

Errors

Parameter

hdsi plOptions

Description

handle to instance returned by DSIInitInstance pointer to a long for returning the DSISTATUS_* values.

DSIERR_SUCCESS or an error code.

Example

Message

DSIERR_INVPAR

DSIERR_INTERNA

Description

Invalid DSI instance handle or plOptions is NULL

Internal error

Here is an example: long lOpt; if ( DSIQueryStatus(hInstance,&lOpt) != DSIERR_SUCCESS ) {

... display error message

} if ( lOpt & DSISTATUS_PAUSE )

{ printf("Server is currently paused\n");

} if ( lOpt & DSISTATUS_STOP )

{ printf("Server is currently stopping\n");

}

DSISetStatus

This API sets DSI specific status options via DSISTATUS_* flags. Use it to pause IDS.

Here is a list of the available flags:

Flag

DSISTATUS_PAUSE

DSISTATUS_STOP

DSISTATUS_RESTART

DSISTATUS_RESUME

Description

Pause the server

Stop the server and exit the process

Restart the server

Resume the server after a pause

OTE

Setting the status to DSISTATUS_STOP is non-recoverable action. Once the server exits, no other actions are possible.

174

Pausing IDS

Syntax

Return values

Errors

DSISetStatus()

Parameter

hdsi plOptions

Description

handle to instance returned by DSIInitInstance pointer to a long for returning the DSISTATUS_* values.

DSIERR_SUCCESS or an error code.

Example

Message

DSIERR_INVPARM

DSIERR_INTERNAL

Description

Invalid DSI instance handle

Internal error

Here is an example: if ( DSISetStatus(hInstance,DSISTATUS_PAUSE) != DSIERR_SUCCESS ) {

... display error message

} printf("Server is currently paused\n")

When running a Java rule, the RequestState parameter has methods for pausing and resuming IDS as well as to check to see if it is currently paused.

Method

isRequestProcessorPaused pauseRequestProcessor resumeRequestProcessor

Description

Returns true if IDS is currently paused, false otherwise.

Tells IDS to pause and stop processing requests from queues and so on.

Tells IDS to resume processing requests from queues and so on.

175

Chapter 2

Using the Internet Document Server

AT

XECUTING

EQUEST

YPES

UN

IME

Example configuration file

Example data file

Example dynamic.htm

page

IDS lets you execute request types composed at run time. Client programs can specify their own XML configuration file with a set of request types to process. Multiple client programs can have request types with the same name but with a different set of rules to run. Request types no longer have to be present in the IDS configuration file.

To execute request types at run time, specify an attachment variable named DYNAMIC-

CONFIGURATION-FILE with a full path and file name for a configuration file accessible to IDS.

Here is an example:

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

<entry name="function">atcw32->ATCLoadAttachment</entry>

<entry name="function">atcw32->ATCUnloadAttachment</entry>

<entry name="function">atcw32->ATCSendFile,

RPOUTPUT,INSURED,BINARY</entry>

<entry name="function">atcw32->ATCReceiveFile,

EXTRACTFILE,EXTRFILE,c:\docserv\data\*.xml,KEEP</entry>

<entry name="function">dprw32->DPRSetConfig</entry>

<entry name="function">RPDW32->RPDCheckRPRun</entry>

<entry name="function">RPDW32->RPDCreateJob</entry>

<entry name="function">RPDW32->RPDProcessJob</entry>

</section>

</configuration>

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

<data>

<var name="INIOptions1.Group">Printer</var>

<var name="INIOptions1.Option">PrtType</var>

<var name="REQTYPE">POC-RUNRP-HTM</var>

<var name="DYNAMIC-CONFIGURATION-FILE">c:\docserv\runrp-poc-htmconfig.xml</var>

</data>

<file name="EXTRACTFILE">C:\msgclient\extract\poc.xml</file>

</attachments>

</message>

<html>

<head>

<h2>dynamic config test</h2>

<body>

<table>

176

Executing Request Types at Run Time

Example dynamic.asp

page

<tr>

<td>*Enter an xml message with name/value pairs to process</td>

<td><a href="data.xml">example</a></td><td><input name="xmlmessage" type="file"/></td>

</tr>

</table>

</form>

set parser = server.CreateObject("IDSASP.DSI")

parser.parseData()

message = parser.getBuffer("xml-message")

'***process the message file

processMessageFile message

parser.showAtt = 1

parser.ProcessRq

function processMessageFile(buffer)

set xml = Server.CreateObject("MSXML2.DOMDocument.4.0")

xml.loadxml(buffer)

set msgVars = xml.selectNodes("message/data/var")

for each var in msgVars

name = var.getAttribute("name")

value = var.text

parser.addReq name, value

set Attachments = xml.selectNodes("message/attachments/file")

for each attach in Attachments

name = attach.getAttribute("name")

value = attach.text

parser.SendFile name, value

end function

177

Chapter 2

Using the Internet Document Server

UBLISHING

OUR

ORMS

ON THE

EB

The system provides tools you can use to create one HTML file and a number of PDF files (one per FAP file). You can then publish these HTML and PDF files on your web server.

The HTML file lists all of the company, line of business (LOB), form, and image combinations from the FORM.DAT file. This file has links to PDF files which are created for each image.

To publish your form library, you have to put these HTML and PDF files in a web server contents directory. Once you have the HTML and PDF files in a contents directory, you can use your browser to open the HTML page and view the images.

OTE

The one PDF file per image concept does not work well in an environment which has a lot of small images. This concept works better with full page FAP files.

Use the following tools to publish your forms on the web:

• FORMPUB - This program provides a graphical interface from which you can run the FD2HTW32 and PTFMDW32 utilities.

• FD2HTW32 - This utility converts a FORM.DAT file into an HTML page. You can run this utility as a stand-alone program or from the FORMPUB tool.

• PTFMDW32 - This utility creates a PDF file for each image in the FORM.DAT file.

You can run this utility as a stand-alone program or from the FORMPUB tool.

• FAP2HTML - This utility lets you convert FAP files into HTML format for use with iPPS as data entry screens.

FORMPUB

This utility provides a graphical interface from which you can run the FD2HTW32 and

PTFMDW32 utilities. If you want to run these utilities as stand-alone programs, read the following descriptions of these programs.

178

Publishing Your Forms on the Web

Syntax

Parameters

FD2HTW32

Use this utility to convert a FORM.DAT file into an HTML page.

fd2htw32 [-i=<formdef>] [-ini= <inifile>] [-o=<outfile>] [d=<dirname>] i

Parameter Description

The form definition file from which to read. Defaults to the FORM.DAT file.

ini o d

The initialization file from which to read. Defaults to the FSIUSER.INI file.

The name of the output HTML file.

The name of the web server directory.

Syntax

Parameters

PTFMDW32

Use this utility to create a PDF file for each image in the FORM.DAT file.

ptfmdw32 [-i=<formdef>] [-ini=<inifile>] [-f=<formlib>] [x=<fxrfile>] [-o=<outdir>]

Parameter Description

-i=<formdef> The form definition file from which to read. Defaults to

FORM.DAT.

-ini=<inifile> The initialization file from which to read. Defaults to

FSIUSER.INI.

-f=<formlib>

-x=<fxrfile>

-o=<outdir>

Location of FAP files.

Full name of font cross-reference file (FXR file).

Location of output PDF files. Defaults to the same directory as FAP files.

179

Chapter 2

Using the Internet Document Server

FAP2HTML

Use this utility to convert FAP files into dynamic HTML files.

Program names

Windows 32-bit FAP2HTML.EXE

Syntax

FAP2HTML /I /TS /D /X /INI

Parameter Description

/I The name of the FAP file. You can use wildcards, such as *.FAP.

/ts

Include this parameter to tell the utility to produce HTML output for TerSub paragraphs. TerSub is a pre-and post-edit function which selects and assembles pre-written, standardized paragraphs as a time-saving feature.

Include this parameter to include output that can help you diagnose any problems that occur.

/INI

The name of the FXR file (font cross-reference file).

(Optional) The name of the INI file to use. The default is FSIUSER.INI.

T his utility creates an HTML file for each FAP files you specify. The utility appends the extension

HTM to the output files. You can then display the HTML files using a browser.

Keep in mind:

• Dynamic HTML commands require Microsoft Internet Explorer 4.0 or later.

• If the FAP form is complex, you may experience problems in older versions of

Internet Explorer. To avoid such problems, use Internet Explorer 6.0 or later.

• Using absolute positioning, dynamic HTML commands make the HTML page the exact size of the FAP page. This means you cannot zone the HTML file in a browser.

• A multipage FAP file is converted into multiple HTML files, one for each page.

Pages have

_p# appended to the FAP file name with the HTM extension. For example, the first page has

_1 appended to the end of the FAP file name with the

HTM extension. The second page has _2 appended to the end of the FAP file name with the

HTM extension, and so on.

• True Type font names are retrieved from the FXR (font cross-reference) file. The computer used to display the output HTML files must have these same fonts or the output may differ.

The mapping to the True Type font occurs in the Window32Subs control group.

Here you can specify, for example, a Times family font and map it to the True Type equivalent, Times New Roman. You do not have to change your FXR file, just make sure you have the correct mappings in the INI file.

• This utility does not convert logos. It will, however, set up references to the logo file.

You must use a graphics file conversion utility (not included) to convert the logo files into GIF or JPEG files.

• To create TerSub paragraphs, include the /TS and /D parameters.

180

Publishing Your Forms on the Web

INI Options

You can use these INI options to customize how the FAP2HTML utility works:

< PrtType:HTM >

SplitText =

Field =

Text =

TextMerge =

Box

Barcode

Bitmap =

ImagePath =

ImageExt

Table

FieldFontFudge =

DirLinks =

CollapsePage=

PageBreaks =

HR =

AllowInput =

Option

SplitText

Field

Text

TextMerge

Box

Barcode

Bitmap

Description

Use this option to specify the number of characters to output as a separate text label. If you set this set option to -1 (the default), each word is output as a separate word. If you set this option to zero (0), the system will not split the text.

Splitting the text on every character produces a better fidelity HTML file, but slows the performance of the utility and of the browser. The default value seems to produce good results. If you plan to later edit the HTML file, set this value to zero (0) so all the text is output together without positioning commands.

Enter No if you want to omit this kind of objects from the HTML file. The default is Yes.

181

Chapter 2

Using the Internet Document Server

Option

ImagePath

ImageExt

Description

Use this option to specify the location of the graphics files. Use a relative path, such as

/images/, so the reference to the logo will be output in the

HTML file with the attribute

SRC=”images/GRAPH1BB.jpg”

Be sure to use this option if you keep the graphics in a separate directory on the web server.

Use this option to specify the extension to use for references to graphic files.

The default is

JPG.

You will need to set this option to the correct value, if your bitmaps are converted into some other file format, such as GIF, PNG, or TIFF.

Table Use this option to specify if the dynamic HTML absolute positioning should be used for the text. The default is No.

When HTML tables are used for text positioning, the FAP lines and boxes are not output and the fidelity of the output document is low.

Set this option to Yes to edit the HTML text after the conversion.

FieldFontFudge Use this option to increase or decrease the font size for the input fields. The default is 0.535.

This option is necessary because browsers usually use fonts larger than the input fields, so the top or bottom of the text inside the input field is chopped off. When you use this option, the font size inside the input field is the font height times this value.

DirLinks

CollapsePage

PageBreaks

Use this option to add Next and Prev links on pages. The default is No.

Use this option to eliminate white space between HTML pages. The default is No.

Use this option to force a page break between pages during HTML print.

The default is Yes.

Use this option to display a line between HTML pages. You can configure the size, color and width. Here is an example:

HR = Size=2 Width=100% Color=Black

AllowInput Set this option to Yes to enable variable fields for entry. The default is No.

182

Formatting Text with XML Markup

ORMATTING

EXT WITH

XML M

ARKUP

iPPS and other Documaker clients can format multiline text fields in XML files. The

XML import loader and export unloader, which are the same for Documaker and IDS, support these formatting attributes:

Italic: <I>

Bold: <B>

Underline: <U>

Font <FONT>

Attributes:

SIZE=99 (point size)

FACE=(font family name)

COLOR=(hex color value, such as #FFFFFF)

Paragraph: <P> or <BR>

Attributes: ALIGN="CENTER" or "RIGHT"

If you omit the alignment, the system left justifies the text. Empty paragraphs use a

> element instead of

Here is an example multiline field input or output XML:

<FONT SIZE="15" FACE="Universal"><B>This is bold 15 points size font</B></FONT>

<FONT SIZE="10" FACE="Universal"><I><U>This is italic size 10 point font with underline</U></I></FONT>

</P>

If the font does not exist, the font locator looks for the best match based on font family name, point size, style, and weight.

If you omit the font information from the import file, the system uses the default font for the text area.

183

Chapter 2

Using the Internet Document Server

NCRYPTING

AND

ECRYPTING

ATA

ILES

IDS includes a utility you can use to encrypt and decrypt data files. The program is a Java class in the DocuCorpUtil.jar library. To run it, enter a command similar to the one shown here: java -cp DocuCorpUtil.jar com.docucorp.util.DataCrypt

Here is a summary of the parameters:

Parameter Description

-i Treat the text argument as a file name instead of text to encrypt/decrypt.

text The text to encrypt/unencrypt or the name of a file if the -i parameter is included.

The input file is overwritten with the new information.

-u Include this parameter if you want to decrypt the text or file instead of encrypting it. Encrypting is the default behavior for this utility.

If you omit all of the parameters, a usage message appears.

184

Using Multiple Attachment Values with the Same Name

SING

ULTIPLE

TTACHMENT

ALUES WITH

THE

AME

IDSASP and IDSJSP let you send and receive messages with multiple attachment variables which have the same name. To enable support for multiple attachment variables, set the ProcessAll property to True at the beginning of an ASP or JSP page See the example pages below.

In ASP you can simply traverse through the Request and Result collections as before to retrieve all entries for a message. In JSP you can use the getEntries() API to return a list of MsgVarEntry objects.

Here is an example ASP page:

set dsi = server.createobject("IDSASP.DSI")

dsi.ProcessAll = True

dsi.addReq "USERID", "DOCUCORP"

dsi.addReq "USERID", "FORMAKER"

dsi.addReq "USERID", "DEMO1"

dsi.addReq "USERID", "DEMO"

dsi.addReq "PASSWORD", "P1"

dsi.addReq "PASSWORD", "P2"

dsi.addReq "REQTYPE", "TEST_MVARS"

For I = 1 To dsi.Request.count

Response.Write "Request " & I & ": "

Response.Write dsi.Request(i).NAME & " = " & dsi.Request(i).Value

Response.Write "<BR>"

dsi.processRq

For I = 1 To dsi.Result.count

Response.Write "Result " & I & ": "

Response.Write dsi.Result(i).NAME & " = " & dsi.Result(i).Value

Response.Write "<BR>"

185

Chapter 2

Using the Internet Document Server

Here is an example JSP page:

<%@ page language="java" import="java.util.*,

java.net.*,

java.io.*,

com.docucorp.messaging.data.*" %>

<jsp:useBean id='dsi' scope='page' class='com.docucorp.ids.jsp.dsi'/

int _OUTPUTQUEUE = 1;

int _INPUTQUEUE = 2;

List entries = null;

dsi.setTimeout(30000);

//dsi.debugOn(response);

dsi.ProcessAll = true;

dsi.addRequest("USERID", "DOCUCORP");

dsi.addRequest("USERID", "FORMAKER");

dsi.addRequest("USERID", "DEMO1");

dsi.addRequest("USERID", "DEMO");

dsi.addRequest("PASSWORD", "P1");

dsi.addRequest("PASSWORD", "P2");

dsi.addRequest("REQTYPE", "TEST_MVARS");

entries = dsi.getEntries(_OUTPUTQUEUE);

for (int I =0; I <entries.size(); i++){

String k = MsgVarEntry.getName(entries, i);

String v = MsgVarEntry.getValue(entries, i);

out.println("Request: " + k + "=" + v + "<br>");

}

dsi.ProcessRequest();

entries = dsi.getEntries(_INPUTQUEUE);

for (int I =0; I <entries.size(); i++){

String k = MsgVarEntry.getName(entries, i);

String v = MsgVarEntry.getValue(entries, i);

out.println("Response: " + k + "=" + v + "<br>");

}

186

Using Multiple Attachment Values with the Same Name

getEntries

Use this API to return a list of MsgVarEntry objects. Each MsgVarEntry object contains a name and value property.

Parameters

Returns

Parameter Description

queue An integer value that indicates which queue the entries should be returned for: 1

= Output queue, 2 = Input queue.

A list of MsgVarEntry objects (see the JSP example page).

187

Chapter 2

Using the Internet Document Server

ONVERTING

XML F

ILES

SING A

EMPLATE

You can use the XsltTransformRule rule to transform input into the desired output based on an xsl template. For instance, you can transform an XML extract file located using the

EXTRFILE input attachment variable into a new output file or a set of XML files located in the path specified by the XMLPATH input attachment variable, appending the results from each one to the end of the file. You can also transform a single XML file located by the XMLFILE or SOURCE input attachment variables.

This rule can also transform the result XML message in the queue. The output depends on the xsl template provided.

This rule takes an argument of name RUNMSG which can have a value of 1-4 to specify whether the rule should be run in the INIT (1), TERM (2), RUNF (3), or RUNR (4) message. The default is RUNF (3) message if no RUNMSG argument is specified. This is useful when the rule that outputs the XML source does not run in the default RUNF message.

This rule also supports transformations with XSL parameters.

Variable

XMLPATH

EXTRFILE

XMLFILE

XSLTFILE

PRINTPATH

OUTFILE

DOCTYPE

XSLPARAMETERS

OUTPUTVAR

Description

(Optional) Specifies a path for multiple XML source files to be processed. The rule appends the transformation output for each source file to the end of the output file.

(Optional) Specifies the full path and name of the XML extract file to be transformed. If this variable is present, the rule transforms the extract file and replaces the EXTRFILE input attachment variable with the value of the new output file.

(Optional) Specifies the full path and name of an XML file to use as the source of the transformation.

Specifies the full path and name of the xsl template to use for the transformation.

(Optional) Specifies the path where the output file will be written.

(Optional) Specifies the output file name. If this variable is missing the rule generates a unique file name for the output file.

(Optional) Specifies the extension and file type of the output file. The default is .dat.

(Optional) An XML rowset which contains the name/value pairs for parameters to use in the xsl transformation.

(Optional) Defines the name of an additional attachment variable that holds the full path and name of the output file.

This is useful when running other rules after this rule that expect an attachment variable with a name other than the default of

XSLOUTPUT.

188

Converting XML Files Using a Template

Variable

SOURCE

Description

(Optional) Defines the name of an attachment variable in the output message that contains the full path and name of the XML source to be used for the transformation.

This is useful when running other rules prior to this rule which might output the XML source that needs to be transformed to a variable other than the expected variables (XMLFILE or EXTRFILE).

In addition, you can use this variable to indicate the source for the transformation should be the output XML message in the result queue instead of an XML file — set SOURCE equal to the value of RESULT in this case.

Here is an example of a request message:

<VAR NAME="REQTYPE">TRANSFORM2</VAR>

<VAR NAME="SOURCE">RESULT</VAR>

<VAR NAME="XSLTFILE">X:\\XSL\transform1.xsl</VAR>

<VAR NAME="x">LOOKUPVAR.XVALUE</VAR>

</ROW>

</ROWSET>

</MSGVARS>

In addition, each row of parameters for a transformation can contain a value of the format:

LOOKUPVAR.ATTACHVARNAME

Where ATTACHVARNAME is the name of an attachment variable in the output message. The rule then retrieves the value for the ATTACHVARNAME variable and uses it as the value for the parameter in the transformation. This is useful when you do not know the value of a parameter until run-time.

Here are example request types for the DOCSERV.INI file used in IDS 1.8:

[REQTYPE:TRANSFORM] function = atcw32->ATCLogTransaction function = atcw32->ATCLoadAttachment function = atcw32->ATCUnloadAttachment function = dsijrule->JavaRunRule,;com/docucorp/ids/rules/

XsltTransformRule;XSLTTRANSFORMER;transaction;transform; function = dprw32->DPRSetConfig function = atcw32->ATCSendFile,XSLOUTPUT,XSLOUTPUT,BINARY function = irlw32->IRLCopyAttachment

Here is a sample JSP page:

<%@ page language="java" import="java.util.,

java.net.,

java.io." %>

189

Chapter 2

Using the Internet Document Server

<jsp:useBean id='dsi' scope='page' class='com.docucorp.ids.jsp.dsimsg'/>

dsi.setTimeOut(30000);

dsi.debug_on(response); dsi.addRequest("REQTYPE", "TRANSFORM"); dsi.addRequest("XMLFILE", "X:\\input\\data.xml"); dsi.addRequest("XSLTFILE", "X:\\XSL\\transform1.xsl"); dsi.addRequest("doctype", "htm");

String record = "XSLPARAMETERS";

String rec = dsi.addAttachRec(record);

if (rec != null){

dsi.addToAttachRec(rec, "x", "1");

dsi.addToAttachRec(rec, "y", "1");

} dsi.processRequest(); byte buf[] = dsi.receiveFileAsBuffer("XSLOUTPUT");

if (buf != null){

out.println(new String(buf));

}

Here is a sample ASP page:

<%@ Language=VBScript %>

Set DSI = server.CreateObject("IDSASP.DSI")

DSI.clearReq

DSI.WaitTime = 250 ' Polling interval

DSI.Timeout = 1000000

DSI.ShowAtt = 1

DSI.AddReq "REQTYPE", "TRANSFORM"

DSI.AddReq "XMLFILE", "X:\\input\\data.xml"

DSI.AddReq "XSLTFILE", "X:\\XSL\transform1.xsl"

DSI.AddReq "doctype", "htm"

record = DSI.AddAttachRec("XSLPARAMETERS")

DSI.AddToAttachRec record, "x", "1"

DSI.AddToAttachRec record, "y", "2"

'On Error Resume Next

DSI.ProcessRq

190

Converting XML Files Using a Template

'If Err <> 0 then

'Err.Clear

'End if

result = DSI.Result("RESULTS").Value

Set DSI = Nothing

Response.Write("result: " & result & "<br>")

Response.End

191

Chapter 2

Using the Internet Document Server

USTOMIZING

OUR

YSTEM

IDS includes several bridges and example applications. These applications typically include windows or dialogs based on HTML and either JSP or ASP. Some dialogs present query result sets for subsequent user selection. The result sets are typically returned as attachment variables, accessible via DSI (or DSICo) API calls. Custom rules and request types can create other query results, and custom HTML dialogs and scripts can implement custom user dialog presentations of the information.

IDS version 1.7 enhanced the internal message format to an XML format based on evolving SOAP standards. You can use this XML format and bypass the DSI API layer, or you can continue to use the DSI APIs.

To help you build alternative dialogs to replace the standard dialogs in the bridges and applications and create new dialogs for other custom applications, the system returns query result sets as structured data in XML format.

The system creates elements inside the

DSIMSG

structure to contain the results of a search as descendants

ROWSET

tag. Each record (ROW) in the result set is stored in a

ROW

XML element, as a child of the

ROWSET

element. Please see the following example.

For many situations, you can use a non-hierarchical (single level) SQL-like ROW to represent hierarchically structured data by

flattening the columns into a single ROW. If, however, the resulting XML needs the multilevel hierarchy, send the XML as an attachment. For example, if a result set represented a Documaker form set (a list of available forms and images), this could be returned as an Oracle Insurance standard XML file attached to the message.

You can use DSI C APIs, Java, and COM to manipulate the XML result set. Java and VB return the XML from the

ROWSET

element as a string to be loaded into a DOM object by the client. The main reason the row set is returned as XML string or buffer and not as a DOM object is the versioning of DOM objects and XML parsers—IDS does not know what parser and what DOM object will be used by the client application. The C

APIs will allow the calling application to get first/next values from a ROWSET, including the name, instance number, data value, and so on.

The existing APIs that access the attachment variables by their old concatenated names still work for backward compatibility, so you do not have to change existing client code unless you want to take advantage of the newer methods.

The results of SSS (server statistics request) are shown in the example below in SOAP-

XML format, using both the original and the newer XML message layout for the result set. The number of rows in the LIBRARIES row set is reduced to two for a smaller sample.

Here is an example of the original XML layout:

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ envelope">

<SOAP-ENV:Body>

<UNIQUE_ID>4C6482AC643F4B91A9EA347977B8E186</UNIQUE_ID>

<USERID>DSICoTB</USERID>

192

Customizing Your System

</CTLBLOCK>

<VAR NAME="RESULTS">SUCCESS</VAR>

</MSGVARS>

</DSIMSG>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Here is an example of the newer XML layout:

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ envelope">

<SOAP-ENV:Body>

<UNIQUE_ID>4C6482AC643F4B91A9EA347977B8E186</UNIQUE_ID>

<USERID>DSICoTB</USERID>

</CTLBLOCK>

</ROW>

</ROW>

193

Chapter 2

Using the Internet Document Server

</ROWSET>

<VAR NAME="RESULTS">SUCCESS</VAR>

</MSGVARS>

</DSIMSG>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

The sample below corresponds to the row set shown above in the XML layout:

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

</ROW>

</ROW>

</ROWSET>

You can use these API functions to support row sets:

Function

DSIRowset2XML

Description

Use this rule to get a row set back as XML in memory.

DSIRowset2XMLSize Use this rule to get a size of row set back as XML in memory.

The GetRowsetXML function was also added to COM and Java APIs (DSICO, IDSASP and DSIJava). You can learn more about these functions in the SDK Reference .

194

Handling Security Issues

ANDLING

ECURITY

SSUES

THere are several security issues to consider as you set up the Internet Document Server and build your applications. These include

• Using firewalls

• Implementing security for web applications

SING

IREWALLS

Typically, you will use the Internet Document Server with some kind of firewall between the web server and the NT server where the Internet Document Server is installed. This lets you give the Internet Document Server access to archives and other sensitive data without permitting the same access to anyone with an Internet connection.

The Internet Document Server (IDS) sample setup included on the installation CD assumes no firewall exists. As you set up the Internet Document Server and your web server with a firewall between the two, keep these points in mind:

• The messaging system can use either WebSphere MQ, JMS, or HTTP. All of these messaging systems communicate with other computers via TCP/IP. The firewall must be configured to open the TCP/IP ports for a messaging system. Read your messaging system's manuals and firewall manuals to find out which ports are used and how to set it up.

• If you are using NT servers, those servers running the Internet Document Server should have TCP/IP networking installed.

• The web server should have an FTP (file transfer protocol) service configured and started.

• File communications from the web server to the Internet Document Server must use

FTP.

• For the FTP rules to work, your TCP/IP networking must be installed on the computer where the Internet Document Server is installed.

• Be sure to configure FTP server access with the appropriate user ID and passwords.

The Internet Document Server includes several rules for use with firewalls, such as the

IRLFileFTP and IRLInitFTP (Windows) or the FTPRule (Windows and UNIX) rules.

For more information on these rules, refer to the SDK Reference .

MPLEMENTING

ECURITY FOR

EB

PPLICATIONS

Some ASP customers use the ASP IDS and a web server for

hot-key applications. The system builds an URL with, for example, the account number and bill date. When this

URL is executed, it returns a PDF or HTML bill presented in a browser window.

A potential security problem is if the user changes the account number on the URL and retrieve someone else's bill or document. The system, however, can encrypt parts of the

URL to make it more difficult to see someone else's documents.

The COM object DSIEncr lets VB or an ASP page encrypt a value. The ASP syntax is as follows:

<%@ Language=VBScript %>

195

Chapter 2

Using the Internet Document Server

Response.Buffer=True

Set DSI = Server.CreateObject("DSI.DSIEncrypt")

val = "abc"

DSI.Encrypt val

Response.Write "Encrypted: abc as " + val + "<BR>"

DSI.Decrypt val

Response.Write "Decrypted as " + val

Response.End

Set DSI = nothing

The COM object is created by Server.CreateObject() method.

Two methods are available in this COM object, Decrypt and Encrypt. The Decrypt method is provided for testing purposes.

A simple implementation includes an ASP page which encrypts the account number on the URL before redirecting the user to the presentment web site.

Here is a sample URL without the encryption: http://webaddress/present.asp?ACCT_NO=1032714&BILLDATE=20020415

Here is a sample URL with encryption: http://webaddress/ present.asp?ACCT_NO=0zJxWr96vm1ZkniK7Cp0n&BILLDATE=20020415

The result of the encryption is a safe string for the URL so no additional encoding is required. There will be no special characters.

On the IDS side, you can use the DPRDecryptValue rule to decrypt the value before executing a search in the database. Here is an example of how you use this rule: function = dprw32->DPRDecryptValue,ACCT_NO

After this rule is executed on the RUNF message, the ACCT_NO in the attachment is replaced by the real value.

OTE

The encryption algorithm is proprietary.

196

Using the FAP2XML Utility

SING THE

FAP2XML

TILITY

You can use the FAP2XML utility to convert a FAP file into an XML file.

OTE

This utility is intended for iPPS manuscripting support and is not used by the

Documaker system. Neither IDS, Image Editor, or Documaker Studio can read the resulting file and turn it into a FAP or NA file.

Program names

Syntax

Windows FAP2XMLW.EXE

FAP2XMLW /i=FAPFile /o=XMLFile /x=FXRFile /ini=INIFile

Parameter Description

/I (Optional) Enter the name of the FAP file.

/O (Optional) Enter the name you want assigned to the XML file. The default is the name of the FAP file with an XML extension.

/INI

Enter the name of the font cross-reference file (FXR) file.

(Optional) Enter the name of the INI file which contains settings for this utility.

The utility looks in the MasterResource control group find the location of FAP and other files.

197

Chapter 2

Using the Internet Document Server

SING

LDAP

UPPORT

IDS supports the use of Lightweight Directory Access Protocol (LDAP), an application protocol for querying and modifying directory services running over TCP/IP.

IDS includes an LDAP API for Java. The JAVA DocucorpUtil package includes an

LDAP class which you can use to query an LDAP server for group information for a user.

For more information please see the LDAP.html documentation that ships with IDS located in the dsi_sdk\java\docs\com\docucorp\util directory and see the ldapTest class example which ships with IDS and is located in the dsi_sdk\java\samples\ldap directory.

OTE

If you are using JVM version 1.3, you must replace the jsse.jar file with the one from JVM version 1.4, which you can find at this location:

JAVA_HOME\jre\lib\ext

Searching a Directory

Information Tree

IDS also includes an LDAP API for C that you can use to query an LDAP server for group information for a user. These functions are supported in the API:

• LDAPInit

• LDAPTerm

• LDAPSearchDirectory

• LDAPGetErrorCode

• LDAPGetErrorMessage

For more information, see the SDK Reference .

You can search a Directory Information Tree (DIT) in an LDAP server. IDS includes the following rules for conducting LDAP queries to determine a user ID group or role membership:

• DPRSearchLDAP (C)

• search (Java)

These rules will look for all configuration options in rule arguments, a properties file, INI options, and input attachment variables, in that order. Option values found in more than one source override the previous value.

• For information on the DPRSearchLDAP rule, see Using the Documaker Bridge.

• For information on the Java rule search, refer to the dsidocs/com/Docucorp/DSI/ util/DSIJession.html documentation shipped with the Java SDK.

198

Using Default Time-outs for DSILIB-Based Client Applications

SING

EFAULT

IME

OUTS FOR

DSILIB-B

ASED

LIENT

PPLICATIONS

You can set default time-outs for DSILIB-based client applications. You set these defaults using these configuration entries in the docclient.xml file:

• DefaultTimeoutSeconds

• MaxTimeoutSeconds

• MinTimeoutSeconds

OTE

Examples of client-based applications that benefit from this feature are ASP pages using IDSASP.DLL, JSP pages using IDSJSP.jar, and the test programs

DSICOTB.EXE, DSITEST.EXE, and DSIEX.EXE.

For instance, suppose you have hundreds of web applications installed on a single IIS or

Java server and all of these applications are talking to the same IDS setup. Suppose some of these web applications have large time-out values which are not suitable for production mode, such as values longer than a few minutes. In this scenario, a transaction that takes a long time can tie up one thread on the web server. Since the total number of threads in the web server is limited, this can affect other applications.

Using these options, the system administrator can make sure that no matter what was specified as the time-out value, the actual time-out period is what the system administrator thinks it should be.

These entries go under the DocumentClient section in the docclient.xml file. Here is an example:

Entry

DefaultTimeoutSeconds

MaxTimeoutSeconds

MinTimeoutSeconds

Description

Use this entry when DSILIB-based client applications, such as dsiex, dsitest, and dsicotb test programs, provide a time-out value of zero (0) to DSIGetQueueRec calls to wait for a response message.

The default is 15 seconds.

Use this entry to set the upper limit for the time-out value when waiting for a response message. If a time-out value is specified for

DSIGetQueueRec calls and it is greater than

MaxTimeoutSecondsvalue, the MaxTimeoutSeconds is used instead.

There is no default.

Use this entry to set the lower limit for the time-out value when waiting for a response message. If a time-out value is specified for

DSIGetQueueRec calls and it is less than MinTimeoutSeconds value, the MinTimeoutSeconds is used instead.

There is no default.

199

Chapter 2

Using the Internet Document Server

OTE

It is possible that Microsoft Server script execution time-out limits could be set lower than the values specified for this feature. In those instances, the values of the Microsoft Server script execution time-out limits would be used. Please consult your Microsoft documentation for more information.

200

Running Timed Requests

UNNING

IMED

EQUESTS

You can run timed requests repeatedly or just in the primary instance. Use the following entry attributes for a timed request entry under the Timers section in docserv.xml file:

Entry attribute

RepeatInterval

Description

Enter true or yes (case sensitive) to tell IDS to convert the text value provided for the entry into seconds and run the timed entry at each interval specified. Here are some few examples.

This timed section runs every 120 seconds:

This timed section runs every 3720 seconds:

This timed section runs every 90 seconds:

If more than one IDS instance is running, any timed sections configured with the RepeatInterval attribute are run at a random interval using the interval seconds as the seed. Making sure they are not run at the same time by all IDS instances, allows other processing to take place.

The default lower bound is 60 seconds, meaning any timed section that is configured to use a time interval of less than 60 seconds will instead use the default value.

RunOnPrimaryInstanceOnly Enter yes or true (case sensitive) to make sure only the primary instance runs the timed section. For instance, you might want to do this when a timed section runs a synchronization rule that updates resources for a master resource library. This type of request would only need to be run once.

If you omit this attribute, all IDS instances will run each timed section. Here is an example:

201

Chapter 2

Using the Internet Document Server

N

-P

ROCESS

ENDERING

DPAV

FOR

IEW

With version 11.3 Shared Objects, you can create a bitmap representations of a DPA document without creating another instance of IDS. Before version 11.3, you had to have an additional dedicated instance of IDS to create the bitmaps.

DRLLIB detects whether it is running inside an instance of IDS or inside an external process. If DRLLIB detects that it is running inside IDS, it will use its own instance of

IDS to render the bitmap.

DPAView lets you create bitmaps from archived transactions in Documanage for display in Documanage Workstation. To do this, you have to have the following items set up:

• Documaker Server (publishing engine)

• An MRL set up to archive into Documanage (DBHandler:DMIA)

• Documanage version 6.5 and higher

• Documanage Bridge version 3.3

The DPA archives created by Documaker Server through the GenArc program must have been archived into Documanage.

You can enable additional tracing by setting the environment variable DRLDEBUG.

This feature also adds the DRLGetConfig API.

DRLGetConfig

Use this API to retrieve the CONFIG name for the DPA file processed by

DRLProcessDPAFile. You must call this API after running DRLProcessDPAFile.

These APIs are not supported in-process.

• DRLProcessPageDC

• DRLProcessPageBuffer

DRLGetConfig (hInstance) (config) (len)

Syntax

Parameters

Parameter

hInstance config len

Returns

DRLERR_* value

SING

DAL

UNCTIONS FOR

WIP C

OLUMN

CCESS

You can use the following DAL functions to set or retrieve WIP field data when

Docupresentment processes WIP or archived transactions:

Function

WIPKEY1

WIPKEY2

WIPKEYID

WIPFLD

SETWIPFLD

Enhancement

Returns the value of the Key1 WIP field. Requires no input parameters. Here is an example:

Val=WIPKEY1()

Returns the value of the Key2 WIP field. Requires no input parameters. Here is an example:

Val=WIPKEY2()

Returns the value of the KeyID WIP field. Requires no input parameters. Here is an example:

Val=WIPKEYID()

Returns the value of the specified WIP field data. This field must be defined in the WIP.DFD file. Requires one input parameter to indicate which key value to return. Here is an example:

Val=WIPFLD(“TranCode”)

Sets the value of the specified WIP field key and keeps it in memory until the job finishes. For example, this DAL script sets/changes CURRUSER to

DEMO1 and returns it:

SETWIPFLD(“CURRUSER","DEMO1");

Val=WIPFLD("CURRUSER");

Return Val;

There are several ways to run the DAL script, here are two examples:

• Using the ~DALRUN built-in INI function following a DAL script file, as shown in this example:

~DALRUN wipkey.dal

• Using the DPRExecuteDAL rule, as shown in the following request type:

[ ReqType:i_WipTest] function = atcw32->ATCLogTransaction function = atcw32->ATCLoadAttachment function = dprw32->DPRSetConfig function = atcw32->ATCUnloadAttachment function = dprw32->DPRGetWipFormset function = dprW32->DPRExecuteDAL,wipkey.dal,RUNF

You can also use the following built-in INI functions to retrieve WIP field data when

Docupresentment processes WIP or archived transactions:

• ~KEY1

• ~KEY2

• ~KEYID

• ~ORIGUSER

203

Chapter 2

Using the Internet Document Server

• ~CREATETIME

• ~MODIFYTIME

• ~FORMSETID

• ~ORIGFSID

• ~TRANCODE

• ~DESC

• ~WIPFIELD

All of these built-in functions except WIPFIELD do not require input parameters.

The WIPFLD function requires an input parameter that indicates the field data to return. Here is an example:

~WIPFLD FORMSETID

In this example, FORMSETID is the input parameter that specifies the field name.

204

Using Enterprise Web Processing Services

SING

NTERPRISE

EB

ROCESSING

ERVICES

Enterprise Web Processing Services (EWPS) make it easier to integrate applications, providing a set of web services for accessing the Documaker forms library and initiating real-time publishing operations. This helps you deliver the information requested by your clients, prospects, employees, and business partners.

Via EWPS you can use a number of essential mechanisms, such as WS-I SOAP interfaces for application integration, JSON for UI integration, or prepackaged business parts for design-time integration, to create a solution that uniquely meets your business needs.

Typical EWPS-enabled solutions include:

• Self-service publishing solutions

• Document search utilities

• Composition and workflow systems

• Systems that embed publishing artifacts into web pages

• Applications that help users create documents and forms

EWPS supports these protocols:

• SOAP (Simple Object Access Protocol).

• JSON (JavaScript Object Notation)

In addition, the EWPS Jmeter test script provides a set of examples for each service request operation. These examples can help you more quickly implement your system.

For more information on EWPS, see Introduction to Enterprise Web Processing

Services .

OTE

EWPS is not available on the UNIX platforms.

205

Chapter 2

Using the Internet Document Server

206