x

The testfuncs5 tool is used to investigate the changes in iFL syntax between 5.x and 6.x. The tool becomes available in the command line console when the iwxmigrate extension is installed. The command line arguments are modeled after the testfuncs tool which is used to test functions in the latest version of the compiler. A short help message can be requested by typing the following command:

help tool testfuncs5

For example:

Enter command:>help tool testfuncs5
Tests iFl expressions from a previous version of the language
tool testfuncs5 [<xmlInput>] [-lang <lang>] [-notree] [-noeval] [-debug] [-parse] [-string]
    xmlInput = Filename of XML document or string to operate on
    -lang    = input language level, values are 5.5sp2 or 5.6, default is
     5.5sp2
    -notree  = do not show the abstract syntax trees
    -noeval  = do not evaluate the function
    -debug   = Turn on debug traces
    -parse   = Turn on parse traces
    -string  = When used, xmlInput is a string rather than a file name

To enter the command loop of the tool, type the following command:

tool testfuncs5

At the prompt, enter an expression and hit enter. The expression will be parsed by the 5.x compiler and again by the 6.x compiler. If the parse trees are not equivalent, a new 6.x expression will be proposed and parsed. The parse trees will be displayed to clearly see what the syntax migrator is doing. Then the 5.x and the 6.x parse trees will be evaluated by their respective interpreter. The two values are shown and if they are different, a warning is printed.

It is possible to choose the version of your input language. For example, to choose the 5.6 version of the compiler, start the testfuncs5 tool by entering the following command:

tool testfuncs5 -lang 5.6

By default, the testfuncs5 tool provides a very simple document for those functions that require an XML document during evaluation. You can provide your own XML document if required by specifying a file name:

tool testfuncs5 mydoc.xml

You can also specify a very simple flat document directly if you specify the -string option. The flat document is useful in testing string functions such as _before().

tool testfuncs5 "this is a string" -string

You can request less output by specifying the -notree or the -noeval option. On the other hand, you may request more output by specifying the -parse and -debug options.

Besides simply evaluating expressions entered on the command line, the tool accepts some special support commands. The special commands that are available are listed in the following table:

Command	Purpose
end	Ends the utility tool. A blank line also ends the tool.
help <functionname>	Displays the syntax for the named function.
set <registername> <value>	Defines the special register and gives it a value. The register can be used in subsequent expression evaluations.
show	Displays the current document being used for testing.

The following is an example where the expression was compatible and the value is the same:

funcs5->set reg1 1
stored
funcs5->sreg(reg1)
Original expression is compatible
-------------------------------------------
Parse tree of original expression in 5.5sp2:
<superroot>
   <sreg>sreg(reg1)
      <p-literal>reg1</p-literal>
   </sreg>
</superroot>
-------------------------------------------
Parse tree of original expression:
<superroot>
   <sreg>
      <literal>reg1</literal>
   </sreg>
</superroot>
Value of original expression: 1
Value of upgraded expression: 1

The following example shows an expression that must be modified to preserve the original semantics. Notice how an upgraded expression is proposed on the second line and a third parse tree is printed for it. In this example, the XPath expression does not match any nodes so the evaluation returns empty string.

funcs5->xpath(/x)
Original expression needs a document for execution
Expression upgraded to: _iwxpath(/x)
-------------------------------------------
Parse tree of original expression in 5.5sp2:
<superroot>
   <XPATH>xpath(/x)
      <literal>/x</literal>
   </XPATH>
</superroot>
-------------------------------------------
Parse tree of original expression:
<superroot>
   <xpath>
      <literal>/x</literal>
   </xpath>
</superroot>
-------------------------------------------
Parse tree of upgraded expression:
<superroot>
   <_iwxpath>
      <literal>/x</literal>
   </_iwxpath>
</superroot>
Value of original expression:
Value of upgraded expression:

This example shows the introduction of explicit concatenation to obtain the same scope for the left argument of an infix operator. A warning is shown because the values obtained are not identical. After closer examination, the difference is deemed beneficial because the result in 6.x is more accurate.

Enter command:>tool testfuncs5 -notree
testfuncs5 Version 6.0.1  (Build nnnnn)
<default/>
funcs5->set reg1 1
stored
funcs5->sreg(reg1)1 + 2.5
Expression upgraded to: _concat(_sreg(reg1), 1) + 2.5
Value of original expression: 13
Value of upgraded expression: 13.5
VALUES ARE DIFFERENT

iFL Migration Rules lists the rules that are applied when upgrading an expression from 5.x to 6.x.

x

The migrate5 tool can be used to migrate applications from 5.x to 6.x. The tool becomes available when the iwxmigrate extension is installed. The following components can be migrated:

• User-defined configuration special registers
• XML schemas
• Retry time settings, trace settings, and iwse SOAP settings
• 5.x LDAP configuration into a default provider
• 5.x JDBC provider configuration into a default provider
• 5.x SSL and SMIME keystore settings into one or more keystore (and truststore) providers. SSL and SMIME providers that reference the newly migrated providers.

Warning: The migrate5 tool has the potential to change a lot of files. It is highly recommended to backup your files before you start working with it. The tool can automate a lot of the mechanical work, but a complete successful migration is ultimately the responsibility of the application developer.

The first step of migration involves the copying of the 5.x components into the 6.x installation. This can be done with the familiar deployment tools like the Package Manager and Archive Manager found under the Tools menu of the iWay Service Manager console. By leaving the deployment task to the existing tools, migrate5 can concentrate on the intricacies of migration.

The migrate5 tool can upgrade a list of configurations, the registry or a single file. The configurations and the registry must be within the 6.x installation. The assumption is they contain 5.x components that have just been deployed by one of the deployment tools mentioned above. It can be convenient to run migrate5 on a single file outside a 6.x installation to learn more about the migration. Obviously, the effect will not be visible until the file is physically copied to the 6.x installation. A short help message can be requested by typing the following command:

help tool migrate5

For example:

Enter command:>help tool migrate5
Assists in migrating configurations from a previous version
tool migrate5 [<config>*] [-file <file>] [-registry] [-lang <lang>] [-update]
    <config>*  = list of configuration names separated by spaces
    <file>     = path to a single file to migrate
    -registry  = migrate components in the registry
    -lang      = input language level, values are 5.5sp2 or 5.6, default
                 is 5.5sp2
    -update    = default is preview mode, add this option to save changes
    -force     = migrate all files, default is to skip already migrated
                 files

This tool does not have a command loop. When the tool is called, it migrates the files in place and terminates. A summary of the migration will be printed on the screen and a more detailed log will be saved in a file. The log is always appended to the file. Remember to scroll to the end of the file to see the latest run.

iFL expressions will be upgraded to the latest syntax. You can use the previously mentioned testfuncs5 tool to study how iFL migration works. See iFL Migration Rules for the set of iFL migration rules. To choose the version of the language in the input file, use the -lang option.

The tool can locate some agents that might have different behavior from previous releases. The application developer needs to validate the agent configuration and possibly make appropriate changes.

When migrating a dictionary, the tool looks for some settings that can be automatically converted to providers. For example, if the LDAP settings are present, they can be migrated to a Directory provider. If the S/MIME keystore settings are present, they can be migrated to a KeyStore provider. Similarly, if the SSL keystore settings are present, they can be migrated to a KeyStore provider and an SSLContext provider.

By default, the tool runs in preview mode. For example, if you type the following command, a log is produced in the myfile.log file that lists all of the changes that would be applied together with some recommendations about some agents.

tool migrate5 -file myfile.xml

The file myfile.xml will not be modified.

Use the -update option to apply the modifications. To convert a single file in place, type this command:

tool migrate5 -file myfile.xml -update

This will backup myfile.xml to myfile.xml.orig and apply changes in place. The detailed log will appear in myfile.log. The input file can be a dictionary, a GUI process flow or a compiled process flow.

Files created with 6.x or already migrated to 6.x will not be considered for migration. This avoids problems where a 6.x expression is interpreted as a 5.5 expression and the meaning is lost. If you need to override this behavior, you can add the -force option to always run the migration regardless of the file version.

The following example shows the result of running the tool on a sample dictionary file. In general, the screen displays which files are processed and important messages that require special attention.

migrate5 Version 6.0.0  (Build 21221)
Migration of dictionary C:\iWay\6.0\components\extensions\iwxmigrate\test\data\config.xml
    WARNING in /edaxml/listener[text()='file1']/file[text()='_eval(_concat("sreg(", sreg(nameholder), ")"))']
    The argument of the _eval() function must be migrated manually.
    The XDIterXMLSplit agent has a new implementation. Verify the configuration of the agent
        at /edaxml/listener[text()='file1']/agent[@name='xmlsplit1']
    The XDPFFileOps agent (from File wizard) has a new implementation using the iWay standard
        status document. Verify the status document use at /edaxml/listener[text()='file1']/agent[@name='fileops1']
    XDSQLWriter and XDBaseCorrelDriver exits require conversion to use JNDI datasource.
        Use JDBC settings from these components to create a JDBC data provider.
Detailed trace is in C:\iWay\6.0\components\extensions\iwxmigrate\test\data\config.log
Found 14 upgrade(s), 1 warning(s) and 3 recommendation(s) in 1 file(s)

The detailed log file produced by the previous command is shown below. Notice how the location within the directory is represented by an XPath expression. When the log represents the migration of a process flow, the location will mention the name of the process flow node instead.

===============================================================================
migrate5 Version 6.0.0  (Build 21221)
2009/10/06 11:37:46
Migration of dictionary C:\iWay\6.0\components\extensions\iwxmigrate\test\data\config.xml
    Upgraded expression in /edaxml/system/define/agent/name[text()='CONSTANT']/parm[@name='constant']
       from: a''b
       to: a'b
    Upgraded expression in /edaxml/system/define/registers/parm[@name='reg1']
       from: sreg(a)-2
       to: _concat(_sreg(a), -2)
    Upgraded expression in /edaxml/listener[text()='file1']/file[text()='_eval(_concat("sreg(", sreg(nameholder), ")"))']
       from: _eval(_concat("sreg(", sreg(nameholder), ")"))
       to: _eval(_concat("\"sreg(\", ", _sreg(nameholder), ", \")\""))
    WARNING in /edaxml/listener[text()='file1']/file[text()='_eval(_concat("sreg(", sreg(nameholder), ")"))']
    The argument of the _eval() function must be migrated manually.
    The XDIterXMLSplit agent has a new implementation. Verify the configuration of the agent
        at /edaxml/listener[text()='file1']/agent[@name='xmlsplit1']
    The XDPFFileOps agent (from File wizard) has a new implementation using the iWay standard
        status document. Verify the status document use at /edaxml/listener[text()='file1']/agent[@name='fileops1']
    Upgraded expression in /edaxml/listener[text()='file1']/eda:control/eda:replyto[@name='httpreplyto']/
eda:param[@name='secure']
       from: 4 = sreg(a)
       to: "4 " = _sreg(a)
    Upgraded expression in /edaxml/listener[text()='file1']/eda:control/eda:errorto[@name='emailerrorto']/
eda:param[@name='compression']
       from: _exists(/root/secure)
       to: _iwexists(/root/secure)
    Upgraded expression in /edaxml/listener[text()='file1']/preparse[@name='entag1']/parm[@name='tag']

       from: "tag"
       to: tag
    Upgraded expression in /edaxml/listener[text()='file1']/encrypt[@name='encrypt1']/
eda:if/cond[text()='COND(XPATH(/x), ge, 4)']
       from: COND(XPATH(/x), ge, 4)
       to: _cond(_iwxpath(/x), ge, 4)
    Upgraded expression in /edaxml/listener[text()='file1']/out_reviewer[@name='outreviewer']/
parm[@name='where']
       from: sreg(iwayhome)\debug-2.log
       to: _concat(_sreg(iwayhome), "\\debug-2.log")
    Upgraded expression in /edaxml/listener[text()='file1']/registers/register[@name='rega']
       from: _decode(sreg(a))
       to: _decode64(_sreg(a))
    Upgraded expression in /edaxml/listener[text()='file1']/document[text()='doc1']/
agent[@name='XDConstantAgent_1']/parm[@name='constant']
       from: _xml(<elem attr=''sreg(a)''/>)
       to: _xml(<elem attr='_sreg(a)'/>)
  Created an LDAP provider named ldap based on the old LDAP settings
  Created a Keystore provider named sslkeystore based on the old SSL Keystore settings
  Created an SSLContext provider named sslcontext that uses the Keystore named sslkeystore
  Created a Keystore provider named smimekeystore based on the old SMIME Keystore settings
    XDSQLWriter and XDBaseCorrelDriver exits require conversion to use JNDI datasource.
    Use JDBC settings from these components to create a JDBC data provider.
Created backup file C:\iWay\6.0\components\extensions\iwxmigrate\test\data\config.xml.orig

To convert a whole configuration, type its name on the command line. For example:

tool migrate5 base -update

This will backup each file to a similarly named file with a .orig extension. The changes are done in place in the original files. The detailed log will appear in the file migration.log in the configuration directory. The files considered are the dictionary, configuration process flows and published registry process flows (both GUI and compiled). It is possible to migrate multiple configurations at the same time if you list all their names separated by spaces. For example:

tool migrate5 base config1 config2 -update

To convert the registry, use the -registry option. For example:

tool migrate5 -registry -update

This will enumerate components in the registry and convert them one by one. The components considered are: decryptors, emitters, encryptors, listeners, pre-emitters, pre parsers, reviewers, services, parameters and register sets. After components, registry process flows are converted. Before a file is modified, a backup is made in a similarly named file with a .orig extension. The detailed log will be saved in the file migration.log in the root installation directory.