Document Keyword Replace Service

The Document Keyword Replace service enables you to find and replace text within a document.
The following table provides an overview of the Document Keyword Replace service:

System name Document Keyword Replace Service

Graphical Process Modeler All Services

(GPM) category

Description The Document Keyword Replace Service allows you to replace user-defined
keywords in a document. This can be used to manipulate hexadecimal or string
values in a document. A keyword can be replaced with either a replacement string or
the contents of a document.

Preconfigured? A preconfigured instance is available for use with the SyncEngine.

Business usage Because of disparities between how different trading partners' enterprise systems
process data, the format of the data that is exchanged between trading partners often
needs to be manipulated before sending or after receiving or in some cases, on both
sides of the transmission.

Usage example Assume that the VAN used by your trading partner expects each line of data to be
terminated with a Carriage Return and Line Feed, and the data from your enterprise
system is terminated by tilde (~) characters. You would use the DocKeywordReplace
service to convert the tildes into Carriage Return / Line Feed characters, before
transmitting the data to your trading partner.

Requires third party files? No

Platform availability All supported Gentran Integration Suite platforms

Related services None

Application requirements None

Initiates business No
processes?

Invocation Runs as part of a business process.

Business process context This service uses the primary document.

considerations

Returned status values Success Document Keyword Replace service was successful.
Error Document Keyword Replace service was unsuccessful.

Restrictions None

Implementing the Document Keyword Replace Service

To implement the Document Keyword Replace service, complete the following tasks:
1. Create a Document Keyword Replace service configuration. See Creating a Service Configuration.

Sterling Commerce, Inc. 321

2. Configure the Document Keyword Replace service. See Configuring the Document Keyword Replace
Service on page 322.
3. Use the Document Keyword Replace service in a business process.

Configuring the Document Keyword Replace Service

To configure the Document Keyword Replace service, use the following BPML parameters in your business
process:

BPML Description

keyword<x> Keyword that the service should look for. Required.

<x> refers to a sequential number starting with 1. This allows you to make multiple
replacements. For example: keyword1, keyword2, keyword3, etc.
Note: Each keyword must have a corresponding replace. Otherwise, it will be ignored
and you may receive an error message. All subsequent
keyword<x>/replace<x> pairs will also be ignored.
Note: Always define each keyword<x>/replace<x> pair sequentially. For example, do
not specify a keyword2/replace2 pair and a keyword4/replace4 pair without a
keyword3/replace3 pair between them.

keywordtype<x> Type of keyword. Optional. Valid values are hex and string. Default is string.
<x> refers to a sequential number starting with 1. This allows you to make multiple
replacements. For example: keywordtype1, keywordtype2, keywordtype3, etc.
Note: This parameter is optional in either mode.
Note: If double byte characters are specified in the keyword<x> parameter, this
parameter must be set. Additionally, if double byte characters are specified in
the keyword<x> or replace<x> parameters, this parameter must be set to string.

replace<x> Replacement text that the service should use to replace the keyword. Required. Valid
values are hex and string. Default is string.
<x> refers to a sequential number starting with 1. This allows you to make multiple
replacements. For example: replace1, replace2, replace3, etc.
Note: Each replace must have a corresponding keyword. Otherwise, it will be ignored
and you will receive an error message.
Note: Always define each keyword<x>/replace<x> pair sequentially. For example, do
not specify a keyword2/replace2 pair and a keyword4/replace4 pair without a
keyword3/replace3 pair between them.

replacetype<x> Type of replacement text. Optional. Valid values are hex and string. Default is string.
<x> refers to a sequential number starting with 1. This allows you to make multiple
replacements. For example: replacetype1, replacetype2, replacetype3, etc.
Note: This parameter is optional in either mode.
Note: If double byte characters are specified in the replace<x> parameter, this
parameter must be set. Additionally, if double byte characters are specified in
the keyword<x> or replace<x> parameters, this parameter must be set to string.

Sterling Commerce, Inc. 322

BPML Description

keystart Characters to add to the beginning of the keyword when the service looks for the string to
replace. Optional. Default is ${.
Note: Do not specify a value for this parameter if useKeywordDefaults is set to true
and you are using String mode.
Note: This parameter can also be specified in Gentran Integration Suite or in the GPM.
However, special characters (for example, characters such as parentheses and
brackets) must be specified using BPML.
Note: This parameter is not used if literal_mode is set to true.

keyend Characters to add to the end of the keyword when the service looks for the string to
replace. Optional. Default is }.
Note: Do not specify a value for this parameter if useKeywordDefaults is set to true
and you are using String mode.
Note: This parameter can also be specified in Gentran Integration Suite or in the GPM.
However, special characters (for example, characters such as parentheses and
brackets) must be specified using BPML.
Note: This parameter is not used if literal_mode is set to true.

mode Specifies the mode to use. Optional. Valid values:

Document streams in a complete document in place of a keyword
String does a simple string replacement
Default is String.
Note: This parameter is not used if literal_mode is set to true.

useKeywordDefaults Whether to add the characters specified in keystart and keyend, or their default values, to
the start and end of the keyword you are looking for. Optional. Valid values:
true Add the characters specified in keystart and keyend, or the default values, to
the start and end of the keyword. This is the default setting.
false Do not add any characters to the start and end of the keyword.
Note: This parameter is not used if literal_mode is set to true.

literal_bufferSize Specifies the size of the buffer used for literal replacements. Optional. Default is 10240
bytes (10 KB).
Note: This parameter can also be specified in the Graphical Process Modeler (GPM).

literal_mode Whether to use high speed literal replacements (literal mode). Valid values: true, false.
Note: Literal mode provides high speed performance by limiting processing overhead.
You should use this mode unless you specifically need the capabilities of the
other modes. The following parameters are not used if literal_mode is set to
true:
keystart
keyend
mode
useKeywordDefaults
Note: This parameter can also be specified in the GPM.

Sterling Commerce, Inc. 323

BPML Description

literal_readAheadSize Specifies the size of the read-ahead buffer used for literal replacements. Optional. Default
is 8192 bytes (8 KB). To ensure proper operation, the value specified for this parameter
must be smaller than the value specified for the literal_bufferSize parameter.
Note: This parameter can also be specified in the GPM.

Choosing a Mode
There are three modes available in the Document Keyword Replace service.
Literal Mode
Because Literal mode operation limits processing overhead and performs the search and replace functions
only once, this mode is ideal for high-speed replacement operations. You should always use the Document
Keyword Replace service in Literal mode, unless you:
need to replace a keyword with the contents of a document (use Document mode).
need recursive replacement capability (use String mode).
are working with the Synchronization Engine adapters (see Synchronization Engine Adapters).
need parameters not available in Literal mode (use String mode).
Note: Because Literal mode limits processing overhead, some parameters are not available in Literal
mode. Use String mode if you need these parameters. See literal_mode on page 323 for a list of these
parameters.
Place the service in Literal mode by setting the literal_mode parameter to true. For more information on
setting this parameter, see Configuring the Document Keyword Replace Service on page 322.
In literal mode, you can also support character deletion.
String Mode
The String mode offers more options and the ability to do recursive replacements. This is the default mode.
Place the Document Keyword Replace service in String mode by setting the mode parameter to String, or
by not specifying a mode. Ensure the literal_mode parameter is set to false. For more information on setting
this parameter, see Configuring the Document Keyword Replace Service on page 322. String mode allows
the use of the following parameters:
keywordtype
replacetype
keystart
keyend
mode
useKeywordDefaults
Some situations where you should use String mode include:
You need the optional parameters available in String mode
You are working with the Synchronization Engine adapters (see Synchronization Engine Adapters)

Sterling Commerce, Inc. 324

 You need to do recursive replacements
Note: Because String mode operates recursively, the service contains a mechanism to prevent endless
loops when using String mode. You should always test your configuration. If you find that any
expected replacements were not made, check your keyword and replace parameter settings. For
example, if you set up the Document Keyword Replace service to replace the string ABC with the
string ABCD, while in String mode, the service will not allow it. Because the replace parameter
value (ABCD) contains the keyword parameter value (ABC), if the service was allowed to run, the
result would be an endless series of replacement iterations as shown below:
Iteration 1 ABC
Iteration 2 ABCD
Iteration 3 ABCDD
Iteration 4 ABCDDD
Iteration 5 ABCDDDD
This would continue in the same manner endlessly
Document Mode
If you need to replace a string with a complete document, use the Document mode. Place the Document
Keyword Replace service in Document mode by setting the mode parameter to Document. For more
information on setting this parameter, see Configuring the Document Keyword Replace Service on page 322.

Business Process Examples

In the following examples, a notation of #x?? is the hexadecimal equivalent of an unprintable character (??
represents a hexadecimal number).
Note: You cannot just cut and paste (and then run) these examples; you must insert the process name at the
beginning of the BPML (such as the following example in which you would replace somename
with the actual name of the process) and ensure you defined a valid service instance:
<process name="somename">
<!-- within a process, you can have sequences, assigns, and operations -->
</process>

Literal Mode
This sample Business Process searches for all line feed characters and replaces them with a carriage return
and tilde:
Note: In the example below, &#x0a; is a hex notation is a character entity reference that is defined by
html (see http://www.w3.org/TR/REC-html40/sgml/entities.html for more information).
<process name="test">
<sequence>
<operation name="DocKeywordReplaceImpl">
<participant name="myDocKeywordReplaceImplService"/>
<output message="outmsg">
<assign to="." from="*" />
<assign to="literal_mode">true</assign>
<assign to="literal_bufferSize">102400</assign>

Sterling Commerce, Inc. 325

<assign to="literal_readAheadSize">8192</assign>
<assign to="keyword1">~</assign>
<assign to="replace1" from="string('&#x0a;')"/>
<assign to="keyword2" from=string('&#x0d;&#x7e;')/>
<assign to="replace2">Ninety</assign>
</output>
<input message="inmsg">
<assign to="." from="*" />
</input>
</operation>
</sequence>
</process>

For the sample business process above, this is the Primary Document before it is run through the Document
Keyword Replace service:
ISA*00* *00* *08*9262390000
*14*9252050234*020129*0525*U*00400*000010006*0*P*:
GS*PD*345345345*9252050234*20020129*0525*10006*T*004010
ST*852*000010874
XQ*G*20020128*20020202
XPO*L774211-01
N9*VR*0103103*MEASLES ANIMAL HAVEN
N1*ST*CHART WHSE - LKLD - (942)*9*0069220090942
LIN**UA*003500005221
ZA*QA*594*CA*007*20020128
LIN**UA*003500048553
ZA*QA*594*CA*007*20020128
LIN**UA*003500005537
ZA*QA*576*CA*007*20020128
LIN**UA*003500048571
ZA*QA*800*CA*007*20020128
LIN**UA*003500048501
ZA*QA*600*CA*007*20020128
CTT*5
SE*1*000010874
GE*1*10006
IEA*1*000010006

For the sample business process above, this is the Primary Document after it is run through the Document
Keyword Replace service:
ISA*00* *00* *08*9262390000
*14*9252050234*020129*0525*U*00400*000010006*0*P*:~ ----- Note a Tilde was added
to the end of each line
GS*PD*345345345*9252050234*20020129*0525*10006*T*004010~
ST*852*000010874~
XQ*G*20020128*20020202~
XPO*L774211-01~
N9*VR*0103103*MEASLES ANIMAL HAVEN~
N1*ST*CHART WHSE - LKLD - (942)*9*0069220090942~
LIN**UA*003500005221~
ZA*QA*594*CA*007*20020128~
LIN**UA*003500048553~
ZA*QA*594*CA*007*20020128~
LIN**UA*003500005537~

Sterling Commerce, Inc. 326

ZA*QA*576*CA*007*20020128~
LIN**UA*003500048571~
ZA*QA*800*CA*007*20020128~
LIN**UA*003500048501~
ZA*QA*600*CA*007*20020128~
CTT*5~
SE*1*000010874~
GE*1*10006~
IEA*1*000010006~

Document Mode
Note: The path of the replaceX parameter must include a document name from ProcessData. In the
following example, replacementDocument is the name of the document in ProcessData.
<process name="test">
<sequence>
<operation name="DocKeywordReplace">
<participant name="myDocKeywordReplaceService"/>
<output message="toService">
<assign to="." from="*"/>
<assign to="mode">Document</assign>
<assign to="keyword1">someKeywordToReplace</assign>
<assign to="replace1">/ProcessData/replacementDocument</assign>
<assign to="keyword2">anotherKeywordToReplace</assign>
<assign to="replace2">/ProcessData/PrimaryDocument</assign>
</output>
<input message="fromService">
<assign to="." from="*"/>
</input>
</operation>
</sequence>
</process>

String Mode
<process name="test">
<sequence>
<operation name="DocKeywordReplaceImpl">
<participant name="myDocKeywordReplaceImplService"/>
<output message="outmsg">
<assign to="." from="*" />
<assign to="keyword1">GLN</assign>
<assign to="replace1">0008586666221</assign>
<assign to="keyword2">GTIN</assign>
<assign to="replace2" from="string(myData/GTIN)" />
<assign to="keyword3">USERNAME</assign>
<assign to="replace3" from="'user1'" />
<assign to="keystart" from="'$('" />
<assign to="keyend" from="'$)'" />
</output>
<input message="inmsg">
<assign to="." from="*" />
</input>
</operation>
</sequence>
</process>

Sterling Commerce, Inc. 327

Character Deletion Example
Gentran Integration Suite now supports character deletion as exemplified in the following BPML
assignment:
<process name="DocKeywordRemoveExample">
<sequence name="Sequence Start">
<operation name="Document Keyword Replace">
<participant name="SomeDocKeywordReplaceInstance"/>
<output message="DocKeywordReplaceInputMessage">
<assign to="." from="*"/>
<assign to="literal_mode">true</assign>
<assign to="literal_bufferSize">102400</assign>
<assign to="literal_readAheadSize">8192</assign>
<assign to="keyword1">111111</assign>
<assign to="replace1" from="string('')"/>
<assign to="keyword2">ABC</assign>
<assign to="replace2" from="string('')"/>
</output>
<input message="inmsg">
<assign to="." from="*"/>
</input>
</operation>
</sequence>
</process>

Sterling Commerce, Inc. 328