Copyright © TIBCO Software Inc. All rights reserved.
Copyright © TIBCO Software Inc. All rights reserved.


Chapter 1 Using the TIBCO iProcess Objects Director : Configuring the TIBCO iProcess Objects Director

Configuring the TIBCO iProcess Objects Director
The TIBCO iProcess Objects Director is configured with the use of process attributes in the Process Manager, using the following command line:
SWDIR\util\swadm set_attribute MachID DIRECTOR ProcInst AttrName AttrValue
where:
MachID = Machine ID. If 0 (zero) is specified, the attribute is set on all machines in the cluster.
ProcInst = Instance of the TIBCO iProcess Objects Director process. If 0 (zero) is specified, the attribute is set on all instances of TIBCO iProcess Objects Director on the machine specified by MachID. (Note - Using 0 (zero) for ProcInst for the TCP_SERVICE_NAME or UDP_SERVICE_NAME process attributes causes a “base” TCP or UDP port to be established. This is used to determine the TCP or UDP port for each instance of TIBCO iProcess Objects Director when using multiple instances of TIBCO iProcess Objects Director. For more information, see TCP and UDP Ports When Running Multiple Instances of the Director.)
AttrName = Name of the process attribute.
AttrValue = Value to assign to the process attribute.
TIBCO iProcess Objects Director Process Attributes
The following table lists the process attributes that are used to control TIBCO iProcess Objects Director.
 
PICK_METHOD (Cont.)
PICK_METHOD (Cont.)
PICK_METHOD (Cont.)
Note: A transaction consists of a request from the client to the TIBCO iProcess Objects Server, and the response from the TIBCO iProcess Objects Server back to the client. It is synonymous with "message" request/response (it has nothing to do with database transactions). This pick method allows you to balance load based on network traffic (for example, messages) rather than connections.
 
PICK_METHOD (Cont.)
Note: A transaction consists of a request from the client to the TIBCO iProcess Objects Server, and the response from the TIBCO iProcess Objects Server back to the client. It is synonymous with "message" request/response (it has nothing to do with database transactions). This pick method allows you to balance load based on network traffic (i.e., messages) rather than connections. The total transaction count for a TIBCO iProcess Objects Server can be determined using the TotTransCnt property on the SWNodeInfoEx object (TIBCO iProcess Objects), or the getTotalTransCnt method on the vANode object (TIBCO iProcess Server Objects).
Format : MachineID|InstanceNum=Load
If the value of this parameter is set to 0, TIBCO iProcess Objects Director chooses a new TIBCO iProcess Objects Server instance that has a new SAL session started. If the value of this parameter is set to 1, the TIBCO iProcess Objects Server instance that has opened a SAL session for this user is allocated to the user.
Note: This attribute is not defined on a newly installed TIBCO iProcess Objects Director. To use this attribute, you must explicitly assign a value to it using the swadm set_attribute command. For more information about this command, see "Set a Process Attribute" in TIBCO iProcess Engine Administrator’s Guide.
Specify a “service name” that will map to the TCP port number. This requires that you add the service name to the %SystemRoot%\System32\Drivers\Etc\Services file (Windows) or /etc/services file (UNIX) that maps the service name to the TCP port used as the base TCP port.
To configure the TIBCO iProcess Objects Director to use a static TCP port, either specify the desired TCP port number in this process attribute, or specify a “service name” that will map to the TCP port number. If using a service name, you must add the service name to the %SystemRoot%\System32\Drivers\Etc\Services file (Windows) or /etc/services file (UNIX) that maps the service name to the TCP port on which you want the TIBCO iProcess Objects Director to listen for client connections.
Specify a “service name” that will map to the UDP port number. This requires that you add the service name to the %SystemRoot%\System32\Drivers\Etc\Services file (Windows) or /etc/services file (UNIX) that maps the service name to the UDP port on which you want the TIBCO iProcess Objects Director to listen for UDP messages/broadcasts.
TCP and UDP Ports When Running Multiple Instances of the Director
When running multiple instances of TIBCO iProcess Objects Director, the TCP_SERVICE_NAME and UDP_SERVICE_NAME process attributes work somewhat differently than the other process attributes, as follows:
TCP_SERVICE_NAME
The following is the process a TIBCO iProcess Objects Director goes through to establish a TCP port when it starts up:
1.
The TIBCO iProcess Objects Director looks to see if an instance-specific TCP_SERVICE_NAME process attribute is defined for the instance of TIBCO iProcess Objects Director that is starting. For example, if instance 2 of TIBCO iProcess Objects Director is starting, it looks to see if set_attribute was executed for TCP_SERVICE_NAME using a ProcInst of 2. If an instance-specific TCP_SERVICE_NAME was defined, it uses the TCP port specified.
2.
If an instance-specific TCP_SERVICE_NAME process attribute has not been defined, the TIBCO iProcess Objects Director will look to see if a “base” TCP_SERVICE_NAME process attribute has been defined (set_attribute was executed using a ProcInst of 0). If a base TCP_SERVICE_NAME process attribute has been defined, it adds the instance number (minus 1; because the base number is used by instance 1) to the base TCP port number to determine the TCP port for that TIBCO iProcess Objects Director (for example, if the base TCP port number is 10000, instance 3 of the TIBCO iProcess Objects Director will use TCP port 10002).
3.
If neither the instance-specific nor the “base” TCP_SERVICE_NAME process attribute has been defined, it defaults to dynamic, causing the operating system to assign the port number when TIBCO iProcess Objects Director is started.
For more information about specifying the TCP port, see the TCP_SERVICE_NAME process attribute on TCP_SERVICE_NAME.
UDP_SERVICE_NAME
The following is the process a TIBCO iProcess Objects Director goes through to establish a UDP port when it starts up:
1.
The TIBCO iProcess Objects Director looks to see if an instance-specific UDP_SERVICE_NAME process attribute is defined for the instance of TIBCO iProcess Objects Director that is starting. For example, if instance 2 of TIBCO iProcess Objects Director is starting, it looks to see if set_attribute was executed for UDP_SERVICE_NAME using a ProcInst of 2. If the instance-specific UDP_SERVICE_NAME was defined, it uses the UDP port specified (or if “None” is specified, it will not open a UDP port).
2.
If an instance-specific UDP_SERVICE_NAME process attribute has not been defined, the TIBCO iProcess Objects Director will look to see if a “base” UDP_SERVICE_NAME process attribute has been defined (set_attribute was executed using a ProcInst of 0). If a base UDP_SERVICE_NAME process attribute has been defined, it adds the instance number (minus 1; because the base number is used by instance 1) to the base UDP port number to determine the UDP port for that TIBCO iProcess Objects Director (for example, if the base UDP port is 55670, instance 3 of TIBCO iProcess Objects Director will use port number 55672).
3.
If neither the instance-specific nor the “base” UDP_SERVICE_NAME process attribute has been defined, the first instance of TIBCO iProcess Objects Director is assigned port 28001 (the default for TIBCO iProcess Objects Directors), instance 2 is assigned 28002, and so on.
For more information about specifying the UDP port, see the UDP_SERVICE_NAME process attribute on UDP_SERVICE_NAME.
Accessing a TIBCO iProcess Objects Director
The way in which you access a TIBCO iProcess Objects Director depends on whether you are using TIBCO iProcess Objects or TIBCO iProcess Server Objects, as follows:
TIBCO iProcess Objects
A TIBCO iProcess Objects client accesses TIBCO iProcess Objects Directors using one of the following methods:
Auto-discovery UDP Broadcast  The client can send out a UDP broadcast to auto-discover TIBCO iProcess Objects Directors on the LAN segment. By default, TIBCO iProcess Objects Directors listen for UDP broadcasts on UDP port 28001. You can change this for a TIBCO iProcess Objects Director using the UDP_SERVICE_NAME process attribute (see UDP_SERVICE_NAME). For each TIBCO iProcess Objects Director that responds to the broadcast, an SWNodeInfo object is added to the SWEnterprise. NodeInfos list.
For more information about UDP broadcasts, see TIBCO iProcess Objects Programmer’s Guide.
Directed UDP Message  Using the AddNode or AddNodeEx method, the client can direct a UDP message to a TIBCO iProcess Objects Director (AddNodeEx allows you to direct the UDP to a specific instance of the Director). If directed to a TIBCO iProcess Objects Director, the AddNode/AddNodeEx method's IsDirector parameter must be set to True. If TIBCO iProcess Objects Director responds to the UDP message, an SWNodeInfo object representing TIBCO iProcess Objects Director is added to the SWEnterprise. NodeInfos list.
For more information about directed UDP messages, see TIBCO iProcess Objects Programmer’s Guide.
Manually Creating an SWNodeInfo Object  Using the MakeNodeInfo, MakeNodeInfoEx, or MakeNodeInfoByTag method, the client can manually add the SWNodeInfo object to the NodeInfos list (MakeNodeInfoEx allows you to add a specific instance of TIBCO iProcess Objects Director). If the SWNodeInfo object is to represent a TIBCO iProcess Objects Director, the MakeNodeInfo/MakeNodeInfoEx method's IsDirector parameter must be set to True when it is called.
For more information about manually creating an SWNodeInfo object, see TIBCO iProcess Objects Programmer’s Guide.
 
TIBCO iProcess Server Objects
A TIBCO iProcess Server Objects client accesses TIBCO iProcess Objects Directors using one of the following methods:
Auto-discovery UDP Broadcast   The client can send out a UDP broadcast to auto-discover TIBCO iProcess Objects Directors on the LAN segment by calling the getNodes method on sNodeManager. This method returns an array of vNode objects, one for each TIBCO iProcess Objects Director that responds to the UDP broadcast. By default, TIBCO iProcess Objects Directors listen for UDP broadcasts on UDP port 28001. You can change this for a TIBCO iProcess Objects Director using the UDP_SERVICE_NAME process attribute (see UDP_SERVICE_NAME).
For more information about UDP broadcasts, see TIBCO iProcess Server Objects Programmer’s Guide.
Directed UDP Message  The client can issue a directed UDP message to a TIBCO iProcess Objects Director by calling the verifyNode method on sNodeManager. If TIBCO iProcess Objects Director to which the UDP message was directed responds, the method call returns a vNode object that represents that TIBCO iProcess Objects Director. By default, TIBCO iProcess Objects Directors listen for UDP messages on UDP port 28001. You can change this for a TIBCO iProcess Objects Director using the UDP_SERVICE_NAME process attribute (see UDP_SERVICE_NAME).
For more information about directed UDP messages, see TIBCO iProcess Server Objects Programmer’s Guide.
Manually Creating a vNodeId Object  If you have all of the required information (node name, computer name, IP address, and TCP port), you can construct a vNodeId object that represents the TIBCO iProcess Objects Director. The aIsDirector parameter in the vNodeId constructor must also be set to True to indicate that the object represents a TIBCO iProcess Objects Director.
For more information about manually creating an SWNodeInfo object, see TIBCO iProcess Server Objects Programmer’s Guide.
Connecting to a TIBCO iProcess Objects Server via a Director
The way in which you connect to a TIBCO iProcess Objects Server via a TIBCO iProcess Objects Director depends on whether you are using TIBCO iProcess Objects or TIBCO iProcess Server Objects, as follows:
TIBCO iProcess Objects
The key of the SWNodeInfo object (available in the Key property) obtained through one of the methods described in the previous subsection identifies whether the object represents a TIBCO iProcess Objects Server or Director, as follows:
SWNodeInfo.Key = ComputerName|NodeName|IsDirector|InstanceNumber
If IsDirector = Y, it represents a Director; if IsDirector = N, it represents a Server.
Once the client has an SWNodeInfo object that represents a TIBCO iProcess Objects Director, the key from that object can be passed in the NodeKeys parameter of the Login method:
Login (NodeKeys, Password, [UserName])
If the NodeKey represents a Director (IsDirector = Y), the Director will use the “pick method” specified when the Director was configured to determine which TIBCO iProcess Objects Server the client should connect to. Internally, a TCP connection is established between the client and the TIBCO iProcess Objects Server that the Director selected. From the user’s standpoint, the selection and connection to the TIBCO iProcess Objects Server is transparent. All future transmissions while that user is logged in are made directly to the TIBCO iProcess Objects Server instance.
Note that if the client fails to connect to the TIBCO iProcess Objects Server (for example, an invalid user name or password is passed), it will NOT be logged in the TIBCO iProcess Objects Director’s log. Once TIBCO iProcess Objects Director gives the client a TIBCO iProcess Objects Server to log into, communication with TIBCO iProcess Objects Director is complete. You must use the TIBCO iProcess Objects Server’s log to troubleshoot this type of problem.
TIBCO iProcess Server Objects
To connect to a TIBCO iProcess Objects Server via a TIBCO iProcess Objects Director, you must have a vNodeId object that represents the Director (the vNode object returned by getNodes or verifyNode can be cast to a vNodeId object).
Pass the vNodeId object that represents TIBCO iProcess Objects Director in the constructor for the desired Server Object. For example:
sUser(vNodeId aNodeId,
      String aUserName,
      String aPassword)
 
If the vNodeId object represents a TIBCO iProcess Objects Director, the Director will use the “pick method” specified when the Director was configured to determine which TIBCO iProcess Objects Server the Server Object should connect to. Internally, a TCP connection is established between the Server Object and the TIBCO iProcess Objects Server that the Director selected. From the user’s standpoint, the selection and connection to the TIBCO iProcess Objects Server is transparent. All future transmissions while that user is logged in are made directly to the Server instance.
Note that if the client fails to connect to the TIBCO iProcess Objects Server (for example, an invalid user name or password is passed), it will NOT be logged in the TIBCO iProcess Objects Director’s log. Once the TIBCO iProcess Objects Director gives the Server Object a TIBCO iProcess Objects Server to log into, communication with TIBCO iProcess Objects Director is complete. You must use the TIBCO iProcess Objects Server log to troubleshoot this type of problem.
Director-Related Properties and Methods
The following subsections described the Director-related properties and methods for TIBCO iProcess Objects and TIBCO iProcess Server Objects.
TIBCO iProcess Objects
An SWNodeInfo object that represents a TIBCO iProcess Objects Director contains properties and methods that provide information about that instance of the Director.
ClientCnt  The number of TIBCO iProcess Objects Servers that the Director knew about when the SWNodeInfo object was obtained.
ClusterId  This property is used to uniquely identify the node to which the Director is associated. It consists of the "client/server" RPC port number found in the engines' swdefs file, and the machine name on which the database is installed.
ComputerName   The name of the machine on which TIBCO iProcess Objects Director is installed.
DirectorNodeInfos  Returns a list of SWNodeInfo objects, one for each TIBCO iProcess Objects Server the Director knows about. This list is updated dynamically as TIBCO iProcess Objects Servers are added to or removed from the process_config table.
Note: If there is an SWNodeInfo object in this list that represents a TIBCO iProcess Objects Server that has a status other than swAvailable, the following properties on that SWNodeInfo object will return an empty string: SWEOSrvVersion, SWEOSrvName, SWEOSrvDesc, SWVersion, and ClusterId.
InstanceNumber   The instance number of TIBCO iProcess Objects Director.
IsDirector  This identifies whether the SWNodeInfo object represents a TIBCO iProcess Objects Server or Director. True = Director; False = Server.
Key  A string that identifies the specific TIBCO iProcess Objects Director. This key can be passed in the NodeKeys parameter of the Login method to cause the Director to select a Server.
Status  This returns the current status of TIBCO iProcess Objects Director. This value is enumerated using the SWNodeInfoStatusType enumeration (for example, swAvailable, swNotRunning, etc.)
SWEOSrvDesc  Defaults to “TIBCO iProcess Objects Director”. This is set with the UDP_SERVICE_DESC process attribute (see UDP_SERVICE_NAME).
SWEOSrvName  Defaults to “SPODirector.”
SWEOSrvVersion  The version number of TIBCO iProcess Objects Director.
SWVersion  The version of TIBCO iProcess Engine.
TCPPort  This identifies the TCP port on which TIBCO iProcess Objects Director communicates with clients. This port is established on the Director using the TCP_SERVICE_NAME process attribute (see TCP_SERVICE_NAME).
Interface  The interface version number of TIBCO iProcess Objects Director. Note that this number is generally not used to determine compatibility between the client and TIBCO iProcess Objects Director – compatibility is determined by TIBCO iProcess Objects Director when the client attempts to connect to TIBCO iProcess Objects Director.
InterfaceEqual  This method allows you to determine whether or not the TIBCO iProcess Objects Director’s interface version number is equal to the value passed in the method call.
InterfaceNewer  This method allows you to determine whether or not the TIBCO iProcess Objects Director’s interface version number is newer (greater) than the value passed in the method call.
 
 
 
 
 
 
 
 
TIBCO iProcess Server Objects
The following describes the methods on the vNode and vNodeId objects that provide information about TIBCO iProcess Objects Director when those objects represent a TIBCO iProcess Objects Director.
getName  The name of the node the Director is associated with.
getComputerName  The name of the machine on which TIBCO iProcess Objects Director is installed.
getIPAddress  The IP address of the machine on which TIBCO iProcess Objects Director is installed.
getTCPPort  The TCP port on which TIBCO iProcess Objects Director communicates with clients. This port is established on the Director using the TCP_SERVICE_NAME process attribute (see TCP_SERVICE_NAME).
isDirector  This identifies whether the vNodeId object represents a TIBCO iProcess Objects Server or a TIBCO iProcess Objects Director. True = Director; False = Server.
getStatus  The current status of TIBCO iProcess Objects Director. This value is enumerated using the SWNodeInfoStatusType enumeration (for example, swAvailable, swNotRunning, etc.)
getSEOSrvDesc  Defaults to “TIBCO iProcess Objects Director”. This is set with the UDP_SERVICE_DESC process attribute (see UDP_SERVICE_DESC).
getSEOSrvName  Defaults to “SPODirector.”
getSEOSrvVersion  The version number of TIBCO iProcess Objects Director.
getSWVersion  The version of TIBCO iProcess Engine.
getClientCnt  The number of TIBCO iProcess Objects Servers that the Director knew about when the vNode object was obtained.
getClusterId  This method is used to uniquely identify the node to which the Director is associated. It consists of the "client/server" RPC port number found in the engines' swdefs file, and the machine name on which the database is installed.
getInstance  The instance number of TIBCO iProcess Objects Director.
 
The sNodeManager object also contains a method that allows you to determine the TIBCO iProcess Objects Servers that TIBCO iProcess Objects Director knows about.
The getManagedNodes method returns an array of vNodeId objects, one for each TIBCO iProcess Objects Server that TIBCO iProcess Objects Director knows about. This list is updated dynamically as TIBCO iProcess Objects Servers are added to or removed from the process_config table.
Pagable Lists/SWXLists of Work Items
If you are using a TIBCO iProcess Objects Director to connect to a TIBCO iProcess Objects Server, be aware that a pageable list (TIBCO iProcess Server Objects) or SWXList (TIBCO iProcess Objects) of work items or predicted work items is tied to a specific instance of the TIBCO iProcess Objects Server. If a pageable list/SWXList of work items or predicted work items is created, that list can only be accessed on the specific instance of the TIBCO iProcess Objects Server where it was created. This is not just limited to getting the work items on the pageable list, but also to the method calls on work items obtained from the pageable list/SWXList. This is because the list holds state to the Work Item Server.
TIBCO iProcess Objects Director Logging
The following logs are used by TIBCO iProcess Objects Director:
TIBCO iProcess Objects Director Log  Process attributes are used to specify the type and amount of information to write to this log. For more information, see TIBCO iProcess Objects Director Log.
UNIX System Log (UNIX systems only)  Errors and other operational information generated by TIBCO iProcess Objects Director are written to this standard UNIX log. This log also contains errors/information messages from other UNIX facilities and programs running on the box. For more information, see UNIX System Log.
Windows Event Log (Windows systems only)  Errors and other operational information generated by TIBCO iProcess Objects Director are written to this standard Windows log. This log also contains errors/information messages from other Windows processes and programs running on the box.
You can control whether or not messages are written to this log using the WRITEERRSTOEVENTLOG process attribute — see WRITEERRSTOEVENTLOG.
dir_error File (UNIX systems only)  This TIBCO iProcess Objects Director-specific error file is created when the Director is installed. It contains error messages generated by TIBCO iProcess Objects Director. It is located in the $SWDIR/logs directory (where $SWDIR is the directory in which TIBCO iProcess Engine is installed).
TIBCO iProcess Objects Director Log
The first time TIBCO iProcess Objects Director is used, it creates a log file that records messages generated by TIBCO iProcess Objects Director. The name and location of the TIBCO iProcess Objects Director log file are as follows:
Windows  SWDIR\logs\spodirectorXX.log
UNIX  $SWDIR/logs/spodirectorXX.log
where XX is the instance number of TIBCO iProcess Objects Director. If only a single Director process is running, this will be “01”.
To change the log files directory, specify the directory in the staffpms file located in the SWDIR\etc directory. For more information, see "Configuring Log Files Directory" in TIBCO iProcess Engine Administrator’s Guide.
The amount and type of data written to the TIBCO iProcess Objects Director log is controlled by the following process attributes:
LOG_LEVEL  level of information written to the log.
LOG_CATEGORIES  the categories of information to write to the log.
LOG_FILE_MAX_SIZE  the maximum size of the log file.
LOG_FILE_MAX_ARCHIVES  the number of archive log files to create if the log rolls over. See the Archived TIBCO iProcess Objects Director Log Files section below.
TRACE_MSG  flag specifying whether network (request/response) messages are written to the log. Note that request/response messages are written to the log if the LOG_LEVEL attribute is set to 4 (Debug), regardless of the setting of this attribute.
These are described in more details in the table on the preceding pages.
The TIBCO iProcess Objects Director log is formatted in the same way as the TIBCO iProcess Objects Server log — for information about this format, see TIBCO iProcess Objects Server Administrator’s Guide.
Archived TIBCO iProcess Objects Director Log Files
If the TIBCO iProcess Objects Director log file reaches the maximum size specified by the LOG_FILE_MAX_SIZE process attribute, the log is rolled over. If desired, you can specify that when the log rolls over, the previous log file is archived. This is specified using the LOG_FILE_MAX_ARCHIVES process attribute. The default is to not save archived log files.
Archiving log files can be useful if you want to collect many MB of debug log, but you don’t want to deal with a very large log file by setting LOG_FILE_MAX_SIZE to a large value.
Archived log files are named spodirectorXX_archive_n.log, where XX is the instance number of TIBCO iProcess Objects Director, and n is a counter that is incremented each time the log rolls over (starting at 1). For example, if the LOG_FILE_MAX_ARCHIVES process attribute is set to 2, the first time the log rolls over, it is saved as spodirectorXX_archive_1.log. The next time it rolls over, it is saved as spodirectorXX_archive_2.log. If it rolls over again, it is saved as spodirectorXX_archive_3.log, but spodirectorXX_archive_1.log will be deleted because it is only saving two archives.
UNIX System Log
When running TIBCO iProcess Objects Director in a UNIX environment, error messages can be written to the standard UNIX system log (other UNIX facilities and programs also write errors/information messages to this log). You can control whether or not messages are written to this log using the WRITEERRSTOEVENTLOG process attribute — see WRITEERRSTOEVENTLOG.
The location of the UNIX system log can be configured on each UNIX system, but the usual locations are /var/adm/messages on Solaris, /var/adm/syslog/syslog.log on HPUX, /var/log/messages on Linux, and various log files in the /var/adm directory on AIX.
All syslog messages are categorized by the type of “subsystem” or “facility” that originated the message, and by the “priority” given the message. The “subsystems” are areas such as “kernel” (message generated by the kernel, i.e., UNIX itself), “user” (messages from various user programs), “mail,” “daemon,” “auth,” and “lpr.” There are also “local” subsystems (local0 through local7) that are reserved for local program use. The TIBCO iProcess Objects Director uses one of these — local0.
Within each subsystem, there are various priority levels. In TIBCO iProcess Objects Director, the priorities that are used correspond to the debug log levels/types. They are:
local0.info  includes “info,” “notice,” “warn,” and “err”
local0.notice  includes “notice,” “warn,” and “err”
local0.warn  includes “warn,” and “err”
local0.err  includes “err” only
Notice that each priority also includes the levels below it.
The UNIX system log file is controlled by the configuration file /etc/syslog.conf. You could optionally choose to send all TIBCO iProcess Objects Director messages to a different file by adding a line similar to the following to the syslog.conf file:
local0.info /var/adm/spo_director_messages_only
Note that whenever the syslog.conf file is changed, the syslogd daemon must be sent a SIGHUP signal. For example:
kill -HUP ‘cat /etc/syslog.pid’
 
 

Copyright © TIBCO Software Inc. All rights reserved.
Copyright © TIBCO Software Inc. All rights reserved.