TIBCO ActiveMatrix BusinessWorks Plug-in for IBM i User's Guide ™

TIBCO ActiveMatrix BusinessWorks Plug-in for IBM i User's Guide ™
TIBCO ActiveMatrix BusinessWorks™ Plug-in
for IBM i User's Guide
Software Release 7.0
November 2014
Two-Second Advantage®
2
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH
EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY
(OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE
EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY
OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND
CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED
SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE
CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD
OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)
OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER
LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE
SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND
YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE
BOUND BY THE SAME.
This document contains confidential information that is subject to U.S. and international copyright laws
and treaties. No part of this document may be reproduced in any form without the written
authorization of TIBCO Software Inc.
TIBCO, Two-Second Advantage, TIBCO ActiveMatrix BusinessWorks, TIBCO Business Studio, TIBCO
ActiveMatrix BusinessWorks Plug-in for IBM i, and TIBCO Enterprise Administrator are either
registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other
countries.
All other product and company names and marks mentioned in this document are the property of their
respective owners and are mentioned for identification purposes only.
THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT
ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED
AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE
VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.
THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL
ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE
CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO
SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)
AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.
THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR
INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,
INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.
Copyright © 2003-2014 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
3
Contents
TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Plug-in Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Creating a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Creating an IBMi Shared Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Configuring a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Debugging and Running a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Checking Output of an Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Deploying Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Generating an EAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
IBMi Shared Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
IBMi Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
MonitorQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
CallProgram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
ReadMessageQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
ReadQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
CallServiceProgram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
WriteQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Creating a Message Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Managing Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Setting Up Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Exporting Logs to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
4
TIBCO Documentation and Support Services
All TIBCO documentation is available on the TIBCO Documentation site, which can be found here:
https://docs.tibco.com
Product-Specific Documentation
Documentation for TIBCO products is not bundled with the software. Instead, it is available on the
TIBCO Documentation site. To directly access documentation for this product, double-click the
following file: TIBCO_HOME/release_notes/TIB_bwpluginibmi_version_docinfo.html.
The following documents for this product can be found in the TIBCO Documentation site:
●
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
●
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i Installation
●
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i Release Notes
How to Contact TIBCO Support
For comments or problems with this manual or the software it addresses, contact TIBCO Support as
follows:
●
For an overview of TIBCO Support, and information about getting started with TIBCO Support,
visit this site:
http://www.tibco.com/services/support
●
If you already have a valid maintenance or support contract, visit this site:
https://support.tibco.com
Entry to this site requires a user name and password. If you do not have a user name, you can
request one.
How to Join TIBCOmmunity
TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a
place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers
forums, blogs, and access to a variety of resources. To register, go to:
http://www.tibcommunity.com
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
5
Plug-in Overview
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i plugs into TIBCO ActiveMatrix
BusinessWorks, which bridges TIBCO ActiveMatrix BusinessWorks with an IBM i system. You can use
this plug-in to operate the objects on an IBM i system.
TIBCO ActiveMatrix BusinessWorks is an easy to use integration product suite for enterprise, web, and
mobile applications. It uses the Eclipse graphical user interface (GUI), TIBCO Business Studio, for
defining business processes and the process engine to execute them.
TIBCO ActiveMatrix BusinessWorks supports plug-ins to extend the palette functionality. After
installing the TIBCO ActiveMatrix BusinessWorks Plug-in for IBM i, an IBMi Shared Resource and
IBMi palette become available in TIBCO Business Studio. You can add the plug-in activities to design
the business processes, and integrate them with BusinessWorks process. At run time, the plug-in
activities are executed as part of the BusinessWorks process. Each plug-in consists of various activities
that share common functionality and properties. The following six activities are included in IBMi
Palette:
●
MonitorQueue: Use this activity to listen a data queue on an IBM i system.
●
CallProgram: Use this activity to invoke application programs on an IBM i system.
●
ReadMessageQueue: Use this activity to read messages from a message queue on an IBM i system.
●
ReadQueue: Use this activity to read messages from a data queue on an IBM i system.
●
CallServiceProgram: Use this activity to invoke service programs on an IBM i system.
●
WriteQueue: Use this activity to write messages to a data queue on an IBM i system.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
6
Getting Started
A typical workflow using the plug-in to achieve different goals includes creating a process, testing it in
the debugger, and deploying the application.
TIBCO ActiveMatrix BusinessWorks uses the Eclipse graphical user interface (GUI) provided by TIBCO
Business Studio to define business processes and generate Enterprise Archives (EAR files). The EAR
files are deployed and run in the ActiveMatrix BusinessWorks runtime, and managed by using TIBCO
Enterprise Administrator (TEA).
The typical workflow using the plug-in includes:
1. Creating a Project
2. Creating an IBMi Shared Resource
3. Configuring a Process
4. Debugging and Running a Process
5. Deploying Applications
Creating a Project
Projects are BusinessWorks application modules that are created in TIBCO Business Studio. A project
contains various resources.
Procedure
1. Open TIBCO Business Studio using one of the following ways:
●
Microsoft Windows: click Start > All Programs > TIBCO > bw6 > TIBCO Business Studio
version_number > Studio for Designers.
●
Linux or Mac OS: run the TIBCO Business Studio executable file located in the TIBCO_HOME/
studio/version_number/eclipse directory.
2. From the menu, click File > New > BusinessWorks Resources.
3. Click BusinessWorks Application Module in the BusinessWorks Resource Wizard. Click Next.
There are several ways to open the New BusinessWorks Application Module dialog and
create a new project in TIBCO Business Studio. See the TIBCO ActiveMatrix
BusinessWorks documentation for more information.
4. Type a name for the project that you are creating in the Project name field.
5. Keep the Use default location, Create empty process, and Create Application check boxes selected.
Click Finish.
Result
A project and an application are created and displayed in the Project Explorer view. The Process editor
opens automatically.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
7
Creating an IBMi Shared Resource
To use the activities in TIBCO ActiveMatrix BusinessWorks Plug-in for IBM i, you need to create an
IBMi shared resource. The IBMi shared resource describes the connection between the plug-in and the
IBM i system .
Procedure
1. Expand the created project in the Project Explorer view.
2. Right-click the Resources folder and select New > IBMi Connection.
3. Type a name in the Resource Name field in the IBMi Connection dialog. Click Finish.
4. Configure the IBMi shared resource in the IBMi Connection editor, as described in IBMi Shared
Resource.
5. Click Test Connection to validate the connection.
Configuring a Process
Processes define the business logic. After you created a project, configure the process by adding
activities, conditions, and services.
Procedure
1. Select an activity from the Palette view and drop it in the Process editor.
For example, select and drop the Timer activity from the General Activities palette, and the
CallProgram activity from the IBMi palette.
2. Click
to create links between the activities and configure the condition types.
3. Configure the added activities, as described in IBMi Palette.
An IBMi shared resource is required when configuring the activities. See Creating an IBMi
Shared Resource for more details on how to create the IBMi shared resource.
4. Click File > Save to save the project.
Debugging and Running a Process
Debug the application you have configured to ensure that the application configuration is correct.
Procedure
1. Open the process you have configured in TIBCO Business Studio.
2. On the menu bar, click Run > Debug Configurations.
3. Click BusinessWorks Application > BWApplication in the left panel.
4. Ensure that only the application you want to debug and run is selected in the Applications tab in
the right panel.
5. Click the Advanced tab and click Browse to locate the logback file.
By default, the log files are located in the TIBCO_HOME\bw\version\config\design\logback
directory and error logs are captured. See Managing Logs for more details.
6. Click Debug.
TIBCO Business Studio changes to the Debug perspective. Logs are displayed in the Console view.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
8
Checking Output of an Activity
After debugging the application, you can check the output of activities.
Procedure
1. In the Debug perspective, expand BWApplication, and click the activity in the upper-left panel.
2. In the upper-right panel, click the Job Data view and click Output.
Result
The output of the MonitorQueue activity is displayed.
You can also check the activity output in the plug-in logs. See Managing Logs for more
information.
Deploying Applications
After deploying BusinessWorks applications, you can manage them by using TIBCO Enterprise
Administrator.
Prerequisites
The following tasks are required before deploying applications:
●
Creating a Project.
●
Generating an EAR File.
A typical workflow of deployment includes:
1. Uploading an EAR file.
2. Deploying an application.
3. Configuring an application.
4. Starting an application.
You can deploy an application EAR file by using the command-line mode with the bwadmin utility.
See TIBCO ActiveMatrix BusinessWorks Administration for more details about how to deploy an
application.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
9
Generating an EAR File
Application archives are enterprise archive (EAR) files that are created in TIBCO Business Studio. An
EAR file is required when deploying an application.
Prerequisites
An application project has already been created, as described in Creating a Project.
There are many ways to generate an EAR file, the following is one method. See TIBCO ActiveMatrix
BusinessWorks Administration for more information.
Procedure
1. Go to the File Explorer view and click the Open Directory to Browse
icon.
2. Select the folder where you want to generate the EAR file and click OK.
The new folder is displayed in the File Explorer view.
3. Drag the application from the Project Explorer view to the new folder in the File Explorer view.
The EAR file is generated with the name project_name.application_1.0.0.ear.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
10
IBMi Shared Resource
Use the IBMi shared resource to create a connection with an IBM i system.
General
The General panel contains the following fields:
Field
Module
Property?
Description
Package
No
The name of the package where the shared resource is located.
Name
No
The name to be displayed as the label for a shared resource in the
process.
Description
No
Provide a short description for a shared resource.
IBMi Configuration
The IBMi Configuration panel contains the following fields:
Field
Module
Property?
Server Name
Yes
The IP address or system name of the IBM i system that the plug-in
connects to.
User
Yes
The IBM i system user name.
Description
The user name is used to connect the IBM i system when
configuring the connection at design time. Ensure the user has full
authority for the library specified in the Work Library field.
Password
Yes
The password for a user of the IBM i system.
Use SSL for
Connection
No
Select this check box to use SSL connection to connect to the IBM i
system.
File for CA
No
The certificate file to verify the identity of a client. Click
navigate to the directory where the file is located.
to
This field is displayed when the Use SSL for Connection
check box is selected.
Password for
CA
Yes
The password that is configured when you using the keytool utility
to generate a key store.
This field is displayed when the Use SSL for Connection
check box is selected.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
11
Field
Module
Property?
Work Library
Yes
Description
Specifies the library used to generate a temporary object lists and as
a default library.
Type the library name manually or click
Library dialog to select a library.
Library List
Yes
to open the Select
Specifies the library list on an IBM i system. A library list on the IBM
i system is equivalent to PATH on Microsoft Windows platform or
LD_LIBRARY_PATH on UNIX platforms. Type the library name
manually, or click
libraries.
to open the Select Library dialog to select
If you select multiple libraries in the Library List field,
add a comma or a semicolon between each library.
Test Connection Button
Click Test Connection to test whether the specified configuration fields result in a valid connection to
the IBM i system.
At run time, when the plug-in cannot connect to an IBM i system, the plug-in makes three attempts to
reconnect to the IBM i system, and the time interval between each reconnection is 5 seconds.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
12
IBMi Palette
The IBMi palette contains activities that can be added to your business processes.
The palette contains the following six activities:
●
MonitorQueue
●
CallProgram
●
ReadMessageQueue
●
ReadQueue
●
CallServiceProgram
●
WriteQueue
MonitorQueue
Use the MonitorQueue activity to listen a data queue on an IBM i system.
General
The General tab contains the following fields:
Field
Process
Property?
Module
Property?
Name
No
No
IBMi
Connection
No
Yes
Description
The name to be displayed as the label for an activity
in a process.
Click
to select an IBMi shared resource.
If no matching IBMi shared resources are found,
click Create Shared Resource to create one. See
Creating an IBMi Shared Resource for more details.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
13
Field
Process
Property?
Module
Property?
Data Queue
Yes
Yes
Description
The name of the data queue that you want to
monitor. The format of the data queue name is
library_name/data_queue_name.
Type the date queue name manually or click
to
open the Fetch Object dialog to select a data queue.
●
If the data queue you specified in this
field does not exist, after clicking
verification, a Request data queue
data_queue_name does not exist.
Create a new request data
queue? message is displayed in a popup window. Click OK to create a data
queue on IBM i system, click Cancel to
cancel creating a data queue.
●
Peek Used
No
No
The plug-in supports the wildcard
queries, you can also use the *LIBL/
data_queue_name format to specify a
data queue.
If this checkbox is selected, the plug-in monitors the
data queue by periodically peeking into the queue
to find out if there are messages to retrieve.
If this check box is not selected, the plug-in
continuously monitors the data queue.
Key Used
No
No
Select this check box to specify a key filter when
monitoring a keyed data queue.
If this check box is selected, and the data
queue you specified in the Data Queue
field is not a keyed data queue, the
verification is failed.
Key Value
Yes
Yes
Enter a value for the key.
If the length of the entered value is the same as the
length of the key defined in the data queue, the
MonitorQueue activity filters the message using the
length of the value.
If you enter nothing in this field, the MonitorQueue
activity has no filter of the key.
This field is enabled when the Key Used
check box is selected.
Is Shared
No
No
Select this check box to retrieve a message which
contains shared message when monitoring.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
14
Field
Shared
Message
Polling
Interval
(millisecond
s)
Process
Property?
Module
Property?
Yes
Yes
Yes
Description
Enter the value of the shared message to retrieve the
message containing this value from the data queue.
Yes
●
This field is enabled when the Is
Shared check box is selected.
●
To retrieve a message which contains
the shared message, when using the
WriteQueue activity to write message
to a data queue, in the Advanced tab
of the WriteQueue activity, after
loading parameter, add an item firstly
under the entry node, and ensure the
data type, the length of the item, are
same as the value in this filed.
The time interval (in milliseconds) that the activity
retrieves message from a data queue. The default
value is 0.
After the configuration, click verification to test whether the specified configuration fields result in a
valid connection to an IBM i system.
Description
A short description of the MonitorQueue activity.
Advanced
In the Advanced tab, you can customize the message schema to monitor the message from a data
queue.
Click Load parameter to initialize a message schema. To create a message schema, see Creating a
Message Schema.
Column Name
Description
Schema
The schema that you want to define.
●
If the Is Shared check box is selected in the General tab, a
sharedMessage item is displayed in this column. The IBMi
type of the shared message only can be Character.
●
If the data queue is a keyed data queue, and the verification
is passed in the General tab, a key item is displayed in this
column.
Description
A short description of the parameter.
IBMi Type
The data type of the parameter that is defined on an IBM i system.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
15
Column Name
Description
Plugin Type
The data type used in this plug-in, it is correspond the data type on an IBM
i system.
Sequence
Enter an integer for the corresponding item or schemaNode.
The entered value indicates the maximum occurrences that the attribute
appears in the Output tab.
Sequence Key
This field contains an XPath expression that specifies the order in which
the process run. Process instances with sequencing keys that have the same
value are executed sequentially in the order in which the process instances
were created.
Custom Job Id
This field contains an XPath expression that specifies a custom jobID for
the process instance. This ID is displayed in the TIBCOAdministrator View
Service dialog, and it is also available in the $_processContext process
variable.
Output
The following is the output for the MonitorQueue activity.
Output Item
Data Type
Description
Success
Boolean
A value of true indicates the operation succeeded.
A value of false indicates the operation failed.
Results
Complex
If the operation is successful, all the messages are displayed under
the Results node. Otherwise, nothing is displayed under the Results
node.
Fault
The Fault tab lists exceptions that are thrown by the MonitorQueue activity:
Fault
Thrown When...
IBMiPluginException
The plug-in fails to get a status response due to a plug-in error.
ActivityTimedOutException
The plug-in fails to get a status response due to a timeout error.
IBMiParameterConvertExcept
ion
The plug-in fails to convert the schema parameters.
IBMiRemoteException
The plug-in fails to communicate with an IBM i system.
CallProgram
Use the CallProgram activity to invoke application programs running on an IBM i system.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
16
General
The General tab contains the following fields:
Field
Process
Property?
Module
Property?
Name
No
No
IBM i
Connection
No
Yes
Description
The name to be displayed as the label for an
activity in the process.
Click
to select an IBMi shared resource.
If no matching IBMi shared resources are found,
click Create Shared Resource to create one. See
Creating an IBMi Shared Resource for more
details.
Program
Object
Yes
Yes
The name of the program object (*PGM object).
The format of the program object name is
library_name/program_name.
You can type the program object name manually,
or click
to open the Fetch Object dialog. All
libraries are listed in the dialog, you can expand
the library to view the list of available program
(*PGM) objects.
The plug-in supports the wildcard
queries, you can also use the *LIBL/
program_name format to specify a
program object.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
17
Field
Process
Property?
Module
Property?
Source File
Yes
Yes
Description
The name of the source file that contains the
program source member. The format of the source
file name is library_name/source_file_name.
Type the source file name manually, or click
to
open the Fetch Object dialog. All libraries are
listed in the dialog, you can expand each library to
view a list of available file (*FILE) objects.
The plug-in supports the wildcard
queries, you can also use the *LIBL/
source_file_name format to specify a
source file.
Source
Member
Yes
Yes
The name of a program source member. The
source member contains the message schema.
Wait Time
(seconds)
Yes
Yes
Specify a time interval (in seconds) to wait for the
completion of a program object invocation.
For example, if you set the value to 10, the activity
waits 10 seconds before timing out and moving
onto the next activity. In this 10 seconds, the
program object invocation can succeed or fail.
If you set the value to 0, the activity waits
indefinitely until the program object execution
finishes.
Description
A short description of the CallProgram activity.
Advanced
In the Advanced tab, you can load the message schema from the IBM i system in real time. Also, you
can customize a message schema, see Creating a Message Schema for more information.
Click Load parameter to load the message schema from the IBM i system, click Refresh Schema to
synchronize the input elements with the following information:
Column Name
Description
Schema
The schema of the object which is defined on the IBM i system.
Description
A short description of a parameter.
IBMi Type
The data type of a parameter that is defined on an IBM i system.
Plugin Type
The data type used in this plug-in, it is correspond the data type on the IBM i
system.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
18
Column Name
Description
Sequence
Enter an integer for the corresponding item or schemaNode.
The entered value indicates the maximum occurrences that the attribute appears
in the Input tab.
For example, if you enter 3 as the sequence value for a NAME parameter, then in
the Input tab, you can right-click the NAME parameter and click Duplicate to
create a same NAME parameter. You can create two NAME parameters at most
because the specified sequence is 3.
Input
The input for the CallProgram activity vary depending on the message schema in the Advanced tab.
Output
The following is the output for the CallProgram activity:
Output
Item
Data Type
Description
Success
Boolean
A value of true indicates the operation succeeded.
A value of false indicates the operation failed.
Results
Complex
If the operation is successful, all parameter names and their values
are displayed under the Results node. If the operation is failed,
only the parameter names displayed under the Results node.
●
JobID: The ID of a job. Each unit of work that is processed by
the IBM i system is called a job. A job is uniquely identified by
a job ID assigned by the system when the job is started.
●
Messages: The error message occurs at run time.
Fault
The Fault tab lists exceptions that are thrown by the CallProgram activity:
Fault
Thrown When...
IBMiPluginException
The plug-in fails to get a status response due to a plug-in error.
ActivityTimedOutException
The plug-in fails to get a status response due to a timeout error.
IBMiParameterConvertExcept
ion
The plug-in fails to convert the schema parameters.
IBMiRemoteException
The plug-in fails to communicate with an IBM i system.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
19
ReadMessageQueue
Use the ReadMessageQueue activity to read a message from the message queue on an IBM i system.
The message queue is the data queue that used to store the system error messages.
General
The General tab contains the following fields:
Field
Process
Property?
Module
Property?
Name
No
No
IBMi
Connection
No
Yes
Description
The name to be displayed as the label for an activity
in the process.
Click
to select an IBMi shared resource.
If no matching IBMi shared resources are found,
click Create Shared Resource to create one. See
Creating an IBMi Shared Resource for more details.
Data Queue
Yes
Yes
The name of a message queue (*MSGQ) to read
message from. The format of the data queue name is
library_name/message_queue_name.
Type the message queue name manually, or click
to open the Fetch Object dialog. All libraries
are listed in the dialog, you can expand each library
to view a list of available message queues (*MSGQ).
The plug-in supports the wildcard
queries, you can also use the *LIBL/
message_queue_name format to specify a
message queue.
Description
A short description of the ReadMessageQueue activity.
Input
The following is the input for the ReadMessageQueue activity:
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
20
Input Item
Data Type
Description
JobID
Integer
The ID of a job. Each unit of work that is processed by the IBM i
system is called a job. A job is uniquely identified by a job ID
assigned by the system when the job is started.
Output
The following is the output for the ReadMessageQueue activity:
Output Item
Data Type
Description
Success
Boolean
A value of true indicates the operation succeeded.
A value of false indicates the operation failed.
If the operation is succeeded, the following elements and their values are displayed under the
Results node.
MessageID
String
The ID of the error message.
Message
String
The system error message.
Fault
The Fault tab lists exceptions that are thrown by the ReadMessageQueue activity:
Fault
Thrown When...
IBMiPluginException
The plug-in fails to get a status response due to a plug-in
error.
ActivityTimedOutException
The plug-in fails to get a status response due to a timeout
error.
IBMiParameterConvertException
The plug-in fails to convert the schema parameters.
IBMiRemoteException
The plug-in fails to communicate with an IBM i system.
ReadQueue
Use the ReadQueue activity to read messages from a data queue.
General
In the General tab of the ReadQueue activity, you can specify a data queue to read message from.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
21
Field
Process
Property?
Module
Property?
Name
No
No
IBMi
Connection
No
Yes
Description
The name to be displayed as the label for an activity
in the process.
Click
to select an IBMi shared resource.
If no matching IBMi shared resources are found,
click Create Shared Resource to create one. See
Creating an IBMi Shared Resource for more details.
Data Queue
Yes
Yes
The name of the data queue(*DTAQ) to read
message from. The format of the data queue name is
library_name/data_queue_name.
Type the data queue name manually, or click
to
open the Fetch Object dialog. All libraries are listed
in the dialog, you can expand each library to view a
list of available data queues.
●
If the data queue you specified in this
field does not exist, after clicking
verification, a Request data queue
data_queue_name does not exist.
Create a new request data
queue? message is displayed in a popup window. Click OK to create a data
queue on IBM i system, click Cancel to
cancel creating a data queue.
●
The plug-in supports the wildcard
queries, you can also use the *LIBL/
data_queue_name format to specify a
data queue.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
22
Field
Process
Property?
Module
Property?
Description
Key Value
Yes
Yes
Enter a value for the key.
If the length of the entered value is the same as the
length of the key defined in the data queue, the
ReadQueue activity filters the message using the
length of the value.
If you enter nothing in this field, the ReadQueue
activity has no filter of the key.
●
This field is enabled when the Key
Used check box is selected.
●
If the data queue you specified in the
Data Queue field is not a keyed data
queue, and you enter a value in this
field, the verification is failed.
Is Shared
No
No
Select this check box to retrieve the messages which
contains the shared message.
Shared
Message
Yes
Yes
Enter the value of the shared message to retrieve the
message containing this value from the data queue.
MaxWaitTi
me
Yes
Yes
(millisecond
s)
●
This field is enabled when the Is
Shared check box is selected.
●
To read a message which contains the
shared message, when using the
WriteQueue activity to write message
to a data queue, in the Advanced tab
of the WriteQueue activity, after
loading parameter, add an item firstly
under the entry node, and ensure the
data type, the length of the item, are
same as the value in this filed.
The maximum time (in milliseconds) to wait if the
data queue contains no messages. The default value
is 0.
After the configuration, click verification to test whether the specified configuration result in a valid
connections to the data queue.
Description
A short description of the ReadQueue activity.
Advanced
In the Advanced tab of the ReadQueue activity, you can customize a message schema to read the
message from a data queue.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
23
Click Load Parameter to initialize a message schema. To create a message schema, see Creating a
Message Schema for more information.
Column Name
Description
Schema
The schema that you want to define.
●
If the Is Shared check box is selected in the General tab, a
sharedMessage item is displayed in this column. The data type of
the shared message only can be Character.
●
If the data queue is a keyed data queue, and the verification is
passed in the General tab, a key item is displayed in this column.
Description
A short description of the parameter.
IBMi Type
The data type of the parameter that is defined on an IBM i system.
Plugin Type
The data type used in this plug-in, it is correspond with the data type on the IBM
i system.
Sequence
Enter an integer for the corresponding item or schemaNode.
The entered value indicates the maximum occurrences that the attribute appears
in the Output tab.
Input
The input tab contains the following item:
Input Item
Description
dataqueue
The name of the data queue(*DTAQ) to read message from. The format of
the data queue name is library_name/data_queue_name.
If you enter nothing in this item, the ReadQueue activity reads the
message from the data queue you specified in the Data Queue
field in the General tab.
If you enter a data queue name which is different from the data queue you
specified in the Data Queue field in the General tab, the ReadQueue
activity reads the message from the data queue in the Input tab.
Output
The following is the output for the activity:
Output Item
Data Type
Description
Success
Boolean
A value of true indicates the operation succeeded.
A value of false indicates the operation failed.
Results
Complex
If the operation is successful, all the messages are displayed under
the Results node. Otherwise, nothing is displayed under the Results
node.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
24
Fault
The Fault tab lists exceptions that are thrown by the ReadQueue activity:
Fault
Thrown When...
IBMiPluginException
The plug-in fails to get a status response due to a plug-in error.
ActivityTimedOutException
The plug-in fails to get a status response due to a timeout error.
IBMiParameterConvertExcept
ion
The plug-in fails to convert the schema parameters.
IBMiRemoteException
The plug-in fails to communicate with an IBM i system.
CallServiceProgram
Use the CallServiceProgram activity to invoke the service programs running on an IBM i system.
General
The General tab contains the following fields:
Field
Process
Property?
Module
Property?
Name
No
No
IBMi
Connection
No
Yes
Description
The name to be displayed as the label for an activity
in the process.
Click
to select an IBMi shared resource.
If no matching IBMi shared resources are found,
click Create Shared Resource to create one. See
Creating an IBMi Shared Resource for more details.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
25
Field
Program
Object
Process
Property?
Module
Property?
Yes
Yes
Description
The name of the service program object (*SRVPGM
object). The format of the service program object
name is library_name/service_program_name.
Type the service program object name manually, or
click
to open the Fetch Object dialog. All
libraries are listed in the dialog, you can expand the
library to view the list of available service program
(*SRVPGM) objects.
The plug-in supports the wildcard
queries, you can also use the *LIBL/
service_program_name format to specify a
service program object.
Procedure
Name
Yes
Yes
The name of the procedure in the service program
object.
Return Type
No
No
The data type of the values that is returned from a
service program call. Two types are available:
Source File
Yes
Yes
●
Numeric: A 4-byte signed integer returns.
●
Void: The value 0 returns.
The name of the source file that contains the service
program source member. The format of the source
file name is library_name/source_file_name.
You can type the service program object name
manually, or click
to open the Fetch Object
dialog. All libraries are listed in the dialog, you can
expand the library to view the list of available
service file (*FILE) objects.
The plug-in supports the wildcard
queries, you can also use the *LIBL/
source_file_name format to specify a source
file.
Source
Member
Yes
Yes
The name of a program source member. The source
contains the message schema.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
26
Field
Wait Time
(seconds)
Process
Property?
Module
Property?
Yes
Yes
Description
Specify a time interval to wait for the completion of
a service program object invocation.
For example, if you set value to 10, the activity waits
10 seconds before timing out and moving onto the
next activity. In this 10 seconds, the service program
object invocation can succeed or fail.
If you set the value to 0, the activity waits
indefinitely until the service program object
execution finishes.
Description
A short description of the CallServiceProgram activity.
Advanced
In the Advanced tab, you can load parameters from an IBM i system in real time. Also, you can
customize a message schema, see Creating a Message Schema for more information.
Click Load parameter to load the message schema from the IBM i system, click Refresh Schema to
synchronize the input elements with the following information:
Column Name
Description
Schema
The schema of the object which is defined on the IBM i system.
Description
A short description of the parameter.
IBMi Type
The data type of the parameter that is defined on an IBM i system.
Plugin Type
The data type used in this plug-in, it is correspond with the data type on the IBM
i system.
Sequence
Enter an integer for the corresponding item or schemaNode.
The entered value indicates the maximum occurrences that the attribute appears
in the Input tab.
For example, if you enter 3 as the sequence value for a NAME parameter, then in
the Input tab, you can right-click the NAME parameter and click Duplicate to
create a same NAME parameter. You can create two NAME parameters at most
because the specified sequence is 3.
Input
The input elements for CallServiceProgram activity vary depending on the message schema in the
Advanced tab.
Output
The following is the output for the CallServiceProgram activity:
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
27
Output Item
Data Type
Description
Success
Boolean
A value of true indicates the operation succeeds.
A value of false indicates the operation fails.
Results
Complex
If the operation is successful, all parameters and their values are
displayed under the Results node. Otherwise, only the parameter
names are displayed under the Results node.
●
JobID: The ID of a job. Each unit of work that is processed by the
IBM i system is called a job. A job is uniquely identified by a job
ID assigned by the system when the job is started.
●
Messages: The error message occurs at run time.
Fault
The Fault tab lists exceptions that are thrown by the CallServiceProgram activity:
Fault
Thrown When...
IBMiPluginException
The plug-in fails to get a status response due to a plug-in error.
ActivityTimedOutException
The plug-in fails to get a status response due to a timeout error.
IBMiParameterConvertExcept
ion
The plug-in fails to convert the schema parameters.
IBMiRemoteException
The plug-in fails to communicate with an IBM i system.
WriteQueue
Use the WriteQueue activity to write messages to a data queue on an IBM i system.
General
The General tab contains the following fields:
Field
Process
Property?
Module
Property?
Name
No
No
Description
The name to be displayed as the label for an activity
in the process.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
28
Field
IBMi
Connection
Process
Property?
Module
Property?
No
Yes
Description
Click
to select an IBMi shared resource.
If no matching IBMi shared resources are found,
click Create Shared Resource to create one. See
Creating an IBMi Shared Resource for more details.
Data Queue
Yes
Yes
The name of the data queue(*DTAQ) to write
messages to. The format of the data queue name is
library_name/data_queue_name.
Type the data queue name manually, or click
to
open the Fetch Object dialog. All libraries are listed
in the dialog, you can expand each library to view a
list of available data queues.
The plug-in supports the wildcard
queries, you can also use the *LIBL/
data_queue_name format to specify a data
queue.
Description
A short description of the WriteQueue activity.
Advanced
In the Advanced tab, you can customize a message schema to write messages to a data queue.
Click Load Parameter to initialize a message schema. To create a message schema, see Creating a
Message Schema for more information.
Column Name
Description
Schema
The schema that you want to define.
If the data queue you want write message to is a keyed data queue,
after clicking Load Parameter, a key item is displayed in this column.
Description
A short description of the parameter.
IBMi Type
The data type of a parameter that is defined on an IBM i system.
Plugin Type
The data type used in this plug-in, it is correspond the data type on the IBM i
system.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
29
Column Name
Description
Sequence
Enter an integer for the corresponding item or schemaNode.
The entered value indicates the maximum occurrences that the attribute appears
in the Input tab.
For example, if you enter 3 as the sequence value for a NAME parameter, then in
the Input tab, you can right-click the NAME parameter and click Duplicate to
create a same NAME parameter. You can create two NAME parameters at most
because the specified sequence is 3.
Input
The input elements for WriteQueue activity vary depending on the message schema you defined in the
Advanced tab. The input tab contains the following element:
Input Item
Description
dataqueue
The name of the data queue(*DTAQ) to write message to. The format of the
data queue name is library_name/data_queue_name.
If you enter nothing in this element, the WriteQueue activity
writes the message to the data queue you specified in the Data
Queue field in the General tab.
If you enter a data queue name which is different from the data queue you
specified in the Data Queue field in the General tab, the WriteQueue
activity write the message to the data queue in the Input tab.
Output
The following is the output for WriteQueue activity:
Output Item
Data Type
Description
Success
Boolean
A value of true indicates the operation succeeded.
A value of false indicates the operation failed.
Fault
The Fault tab lists exceptions that are thrown by the WriteQueue activity:
Fault
Thrown When...
IBMiPluginException
The plug-in fails to get a status response due to a plug-in error.
ActivityTimedOutException
The plug-in fails to get a status response due to a timeout error.
IBMiParameterConvertExcept
ion
The plug-in fails to convert the schema parameters.
IBMiRemoteException
The plug-in fails to communicate with an IBM i system.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
30
Creating a Message Schema
TIBCO ActiveMatrix BusinessWorks Plug-in for IBM i allows you to customize the message schema in
the Advanced tab.
Prerequisites
Before creating a message schema, ensure all the configuration in the General tab is valid.
Procedure
1. Click the Advanced tab of an activity.
2. Click Load Parameter to initialize a message schema, an entry item is displayed in the Schema
column.
For the CallProgram activity and CallServiceProgram activity, click Load Parameter to
load the message schema from the IBM i system, then you can customize the message
schema.
3. Right-click the entry item and click add Item to add a schema item.
For the CallProgram activity and CallServiceProgram activity, there is no entry item in the
Schema column. Right-click anywhere in the Schema column and click add Item to add a
schema item.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
31
4. Configure the added item:
a) Double-click the item to change the item name.
The item name cannot be a number or start with a number. The following characters are escaped
when they are used as part of the item name or schemaNode name:
Character
Escaped to
`
__grave_
~
__tilde_
!
__excl_
@
__AT_
#
__HASH_
$
__DOLLAR_
%
__percnt_
^
__caret_
&
__amp_
*
__ast_
(
__lpar_
)
__rpar_
-
__-
=
__equals_
+
__plus_
|
__verbar_
\
__bsol_
?
__quest_
<
__It_
>
__gt_
b) Enter a description in the corresponding Description column.
c) By default, the character type is used as the IBMi type for the added schema item. To change the
to select a data type
IBMi type, double-click the corresponding IBMi Type column, and click
from the pop-up window. The following table shows the relationship between the IBMi type and
the Plugin Type.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
32
IBMi Type
Length
(Default
Value)
Precision
Plugin Type
Binary1
Uneditable
(3)
Uneditable
byte
Binary2
Uneditable
(5)
Editable
short
Uneditable
(10)
Editable
Binary8
Uneditable
(20)
Uneditable
long
Character
Editable
(None)
Uneditable
string
Date
Uneditable
(10)
Uneditable
date
Double
Uneditable
(8)
Uneditable
double
Float
Uneditable
(4)
Uneditable
float
Graphic
Editable
(None)
Uneditable
string
indicator
Uneditable
(1)
Uneditable
boolean
PackedDeci
mal
Editable
(None)
Editable
decimal
Time
Uneditable
(8)
Uneditable
time
Uneditable
(26)
Uneditable
Binary4
TimeStamp
If the precision of Binary2 type is not
0, The Plugin type is decimal.
integer
If the precision of Binary4 type is not
0, The Plugin type is decimal.
If you select this data type, you must
use the YYYY-MM-DD format for
input.
If you select this data type, you must
use the HH:mm:ss format for input.
dataTime
If you select this data type, you can
use either the YYYY-MMDDTHH:mm:ss format or the YYYY-
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
33
IBMi Type
Length
(Default
Value)
Precision
Plugin Type
MM-DDTHH:mm:ss+HH:mm format
for input.
Unicode
Editable
(None)
Uneditable
string
Unsigned
Binary 1
Uneditable
(3)
Uneditable
unsignedByte
Unsigned
Binary 2
Uneditable
(5)
Uneditable
unsignedShort
Unsigned
Binary 4
Uneditable
(10)
Uneditable
unsignedInt
Unsigned
Binary 8
Uneditable
(20)
Uneditable
unsignedLong
Zoned
Decimal
Editable
(None)
Editable
decimal
Varying
Editable
(None)
Uneditable
string
d) Enter an integer in the corresponding Sequence column. The entered value indicates the number
of occurrences that the item appears in the Input tab.
For example, if you enter 3 as the sequence value for a NAME item, then in the Input tab, you
can right-click the NAME item and click Duplicate
For the MonitorQueue activity and the ReadQueue activity, the entered value indicates
the number of occurrences that the item appears in the Output tab.
5. Right-click the entry item and click add schemaNode to add a schemaNode.
For the CallProgram activity and CallServiceProgram activity, right-click anywhere in the
Schema column and click add schemaNode to add a schemaNode.
6. Configure the added schemaNode:
a) Double-click the schemaNode to change the schemaNode name.
The schemaNode name cannot be a number or start with a number. And some
characters are escaped when they used as part of the schemaNode name, see Escaped
Characters for more information.
b) Enter a description in the corresponding Description column.
c) Enter an integer in the corresponding Sequence column. The entered value indicates the number
of occurrences that the schemaNode appears in the Input tab.
For example, if you enter 3 as the sequence value for a Contact schemaNode, then in the Input
tab, you can right-click the Contact schemaNode and click Duplicate to create a same Contact
schemaNodes. You can create two Contact schemaNodes at most because the specified sequence
is 3.
For the MonitorQueue activity and the ReadQueue activity, the entered value indicates
the number of occurrences that the schemaNode appears in the Output tab.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
34
7. After creating the message schema, click Refresh Schema to synchronize the input elements with
the message schema.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
35
Managing Logs
Logs are used to trace and troubleshoot the plug-in exceptions.
A logback.xml file is located in the TIBCO_HOME\bw\version\config\design\logback directory.
Update this file to Setting Up Log Levels and Exporting Logs to a File.
Log Levels
The plug-in captures logs at different levels.
Log Level
Description
Info
Indicates normal plug-in operations. No action is needed. A tracing message
tagged with Info indicates that a significant processing step is reached, and
logged for tracking or auditing purposes. Only info messages preceding a
tracking identifier are considered as significant steps.
Warn
Indicates that an abnormal condition is found. Processing continues, but special
attention from an administrator is recommended.
Error
Indicates that an unrecoverable error has occurred. Depending on the error
severity, the plug-in may continue with the next operation or may stop
altogether.
Debug
Indicates a developer-defined tracing message.
Trace
Includes all information regarding the running process.
Setting Up Log Levels
By default, the log level is Error . The plug-in allows you to change the log level to trace different
messages.
If neither the plug-in log nor the BusinessWorks log is configured in the logback.xml file, the error
logs of the plug-in are displayed in the Console view by default.
If the plug-in log is not configured but the BusinessWorks log is configured in the logback.xml file, the
configuration for the BusinessWorks log is implemented by the plug-in.
Procedure
1. Navigate to the TIBCO_HOME\bw\version\config\design\logback directory and open the
logback.xml file.
2. Add the following node in the User loggers area to specify the log level for the plug-in.
<logger name="com.tibco.bw.palette.as400.runtime">
<level value="DEBUG"/>
</logger>
The level tag defines the log level and the value is Info , Warn, Error, Debug or Trace.
When the level is set to Debug, the input and output for the plug-in activities are also
displayed in the Console view. See Log Levels for more details regarding each log level.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
36
3. Optional: Add the following node in User loggers area to specify the log level for all the activities
except for the MonitorQueue activity.
<logger name="com.tibco.bw.palette.as400.runtime.ActivityNameActivity">
<level value="DEBUG"/>
</logger>
For each activity, The ActivityName is:
●
CallProgram: ProgramCall
●
CallServiceProgram: ServiceProgramCall
●
ReadMessageQueue: ReadMessageQueue
●
ReadQueue: ReadQueue
●
WriteQueue: WriteQueue
For example, if you want to set the log level of the CallProgram activity to Debug, you need to add
the following node:
<logger name="com.tibco.bw.palette.as400.runtime.ProgramCallActivity">
<level value="DEBUG"/>
</logger>
For MonitorQueue activity, you need to add the following node to set the log level:
<logger name="com.tibco.bw.palette.as400.runtime.MonitorEventSource">
<level value="DEBUG"/>
</logger>
For the activities that are not configure with specific log levels, they still inherit log levels
configured for the plug-in or BusinessWorks.
4. Save the file.
Exporting Logs to a File
Modify the logback.xml file to export plug-in logs to a file.
Procedure
1. Navigate to the TIBCO_HOME\bw\version\config\design\logback directory and open the
logback.xml file.
When deploying an application in TIBCO Enterprise Administrator, you need to
navigated to the TIBCO_HOME\bw\version\domains\mydomain\appnodes\myspace
\mynode directory to find the logback.xml file.
2. Add the following node to specify the file location.
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
<file>c:/bw6-ibmi.log</file>
<encoder>
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36}-%msg%n</pattern>
</encoder>
</appender>
The file tag defines the location to which the log to be exported and the value is the absolute path
of the file.
You also have to add the file name in the file path.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
37
3. Add the following node to the root node at the bottom of the logback.xml file to enable exporting
the logs to a file.
<appender-ref ref="FILE" />
<root level="DEBUG">
<appender-ref ref="STDOUT" />
<appender-ref ref="FILE" />
</root>
4. Save the file.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
38
Error Codes
The exceptions that are thrown by the plug-in are listed with corresponding descriptions and
resolutions.
Error Code and Error
Message
ERROR_OCCURED_RE
TRIEVE_RESULT.errorC
ode=590002
Role
Category
Description
Resolution
errorRole
BW-Plugin
An IOException
occurs while
retrieving XML
output from the
activity.
No action.
errorRole
BW-Plugin
An exception occurs
when executing the
activity.
Check the activity
configuration.
errorRole
BW-Plugin
The object that the
activity operates on
does not exist.
Check the object
name.
errorRole
BW-Plugin
Some errors occurs
when performing
operations on the
object.
Depends on the
content of the error
message.
errorRole
BW-Plugin
An error occurs when
communicating with
the IBM i system.
Depends on the
content of the error
message.
IOException occurred
while retrieving XML
Output for activity
[{0}].
ERROR_OCCURED_EX
ECUTE.errorCode=5900
04
Exception occurred
while execute the
activity [{0}].
ERROR_COMMON_OB
JECT_NOEXIST.errorCo
de=590005
the object of
activity {0} is not
exist. The details
message is {1}.
ERROR_COMMON_RU
N_COMPLETE.errorCo
de=590006
there are some
errors to run the
IBMi object {0}.The
details message is
{1}.
ERROR_COMMON_RU
N_IO.errorCode=590007
an error occurs
while communicating
with the IBMi to run
the object of the
activity{0}.The
details message is
{1}.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
39
Error Code and Error
Message
ERROR_COMMON_RU
N_SEC.errorCode=59000
8
Role
Category
Description
Resolution
errorRole
BW-Plugin
A security error or
authority error occurs
when communicating
with the IBM i system.
Check the CA file.
errorRole
BW-Plugin
An error occurs when
running the activity.
Check the activity
configuration.
errorRole
BW-Plugin
An error occurs when
creating a connection
to the IBM i system at
runtime.
Check the
parameters for the
connection.
errorRole
BW-Plugin
The format of the
program object that
the CallProgram
activity operates on is
invalid.
Check the program
object format is
valid.
errorRole
BW-Plugin
The program object
that the CallProgram
activity operates on is
null.
Check the program
object.
errorRole
BW-Plugin
The format of the
service program object
that the
CallServiceProgram
activity operates on is
invalid.
Ensure the service
program object
format is valid.
a security or
authority error
occurs while
communicating with
the IBMi. The
details message is
{0}.
ERROR_COMMON_RU
N.errorCode=590009
the error occurs
when run the
activity. The
details message is
{0}.
ERROR_COMMON_CR
EATE_CONNECTION.e
rrorCode=590010
the error occurs
when create IBMi
connection for
runtime. The details
message is {0}.
ERROR_PROGRAMCA
LL_INIT_CHECK.errorC
ode=520001
The format of
program object is
invalid.
ERROR_PROGRAMCA
LL_INIT_CHECK_NUL
L.errorCode=520002
The program object
is null.
ERROR_SERVICEPROG
RAMCALL_INIT_CHEC
K.errorCode=530001
The format of
program object is
invalid.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
40
Error Code and Error
Message
ERROR_SERVICEPROG
RAMCALL_INIT_CHEC
K_NULL.errorCode=530
002
Role
Category
Description
Resolution
errorRole
BW-Plugin
The object that
CallServiceProgram
activity operates on is
null.
Check the service
program object.
errorRole
BW-Plugin
The format of the data
queue that
ReadQueue activity
operates on is invalid.
Check the data
queue format.
errorRole
BW-Plugin
The data queue that
ReadQueue activity
operates on is null.
Check the data
queue.
errorRole
BW-Plugin
The format of the data
queue that
WriteQueue activity
operates on is invalid.
Check the data
queue format.
errorRole
BW-Plugin
The data queue that
WriteQueue activity
operates on is null.
Check the data
queue.
errorRole
BW-Plugin
The MonitorQueue
activity failed to start.
Depends on the
content of the error
message.
errorRole
BW-Plugin
The MonitorQueue
activity failed to stop.
Depends on the
content of the error
message.
The program object
is null.
ERROR_READQUEUE_
INIT_CHECK.errorCode
=540001
The format of
program object is
invalid.
ERROR_READQUEUE_
INIT_CHECK_NULL.err
orCode=540002
The program object
is null.
ERROR_WRITEQUEUE
_INIT_CHECK.errorCod
e=550001
The format of
program object is
invalid.
ERROR_WRITEQUEUE
_INIT_CHECK_NULL.e
rrorCode=550002
The program object
is null.
ERROR_MONITOR_ST
ART_FAILED.errorCode
=560001
Event source
starting is failed,
details:{0}
ERROR_MONITOR_ST
OP_FAILED.errorCode=
560002
Event source
stopping is failed,
details:{0}
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
41
Error Code and Error
Message
ERROR_MONITOR_PR
OCESS_DATA_FAILED.
errorCode=560003
Role
Category
Description
Resolution
errorRole
BW-Plugin
An error occurs when
MonitorQueue
activity running.
Depends on the
content of the error
message.
errorRole
BW-Plugin
The format of the data
queue that the
MonitorQueue
activity monitoring is
invalid.
Check the data
queue format.
errorRole
BW-Plugin
The data queue that
you want to monitor
is null.
Check the data
queue
errorRole
BW-Plugin
The format of the
message queue is
invalid.
Check the message
queue format.
errorRole
BW-Plugin
The message queue is
null.
Check the message
queue.
Error happened when
process the posted
data, details:{0}
ERROR_MONITOR_INI
T_CHECK.errorCode=56
0004
The format of data
queue is invalid.
ERROR_MONITOR_INI
T_CHECK_NULL.error
Code=560005
The data queue is
null.
ERROR_READMESSAG
EQUEUE_INIT_CHECK
.errorCode=580004
The format of data
queue is invalid.
ERROR_READMESSAG
EQUEUE_INIT_CHECK
_NULL.errorCode=5800
05
The data queue is
null.
TIBCO ActiveMatrix BusinessWorks™ Plug-in for IBM i User's Guide
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement