Administering the server on i5/OS

Installing WebSphere Business Integration Server Express on i5/OS creates many i5/OS objects on the i5/OS system. The following table describes these objects:

Table 5. i5/OS Objects
Item Name Description
User profile QWBISVR44 Default user profile which owns all of the installed content and under which jobs run.
Library QWBISVR44 Contains all i5/OS native objects.
Job descriptions QWBIxxxx, where xxxx is unique for each process. Helps identify the jobs running in the subsystem and can be customized for individual jobs. To view the job descriptions, use WRKJOBD JOBD(QWBISVR44/*ALL).
Interchange Server Express Instance QWBIDFT44 Installation creates, configures and deploys the collaboration foundation to the server, along with content to run any installed samples.
MQ Queue Manager QWBIDFT44.QUEUE.MANAGER Installation creates a queue manager, along with a MQ listener on the default port.
DB2/400 database QWBIDFT44 Repository for the QWBIDFT44 InterChange Server.
Subsystem description QWBISVR44/QWBISVR44 Contains attributes for the QWBISVR44 Subsystem in which i5/OS processes run.
TCP/IP automatic start server QWBISVR44 Automatically starts the subsystem with the activation of the TCP/IP automatic start servers.
Auto-start job QWBITNAMES The name server necessary for the InterChange Server, Adapters, and Tools to communicate with each other. Uses the default port for the name server.
Auto-start job QWBIDFT44 Starts the installed InterChange Server.
HTTP Server and WebSphere Application Server ICSMON44 HTTP Server and WebSphere Application Server Instances.

Running the server on i5/OS

Support for i5/OS runs in the QWBISVR44 subsystem, under user profile name QWBISVR44. i5/OS assigns a unique job description object for each of the following components:

Considerations for jobs

When searching for jobs, use WRKACTJOB SBS (QWBISVR44). For each component, the job names match the job description names.

Several jobs, associated with the named jobs in the subsystem, exist which do not need management, for example, QP0ZSPWP, QP0ZSPWT, and QZSHSH.

Other jobs, for example, QWBIDFT44, verify your server status and adapter status, for example, QWBIJTEXTC for the JText adapter. It is recommended, but not necessary, that you create different job names and descriptions for each instance of an adapter if you are running multiples of the same adapter, for example, two JText adapters.

On i5/OS, all jobs run using the CCSID of the QWBISVR44 user profile to the QCCSID system value. If your system is running the 5026 or 290 Japanese CCSIDs, you must change the CCSID parameter of the QWBISVR44 user profile to 5035 in order for the product to function correctly.

Removing QWBISVR44 as an auto-start TCP server

If you do not want to have WebSphere Business Integration Server Express automatically start when TCP/IP starts on your system, use the RMVTCPSVR SVRSPCVAL(*QWBISVR44) command to remove QWBISVR44 as an auto-start TCP server.

Removing automatically started InterChange Servers

If you do not want to have the subsystem automatically start when TCP/IP starts on your system, and do not want the QWBIDFT44 server to automatically start, use the remove_autostart_server.sh script to remove the automatically started InterChange Server from the subsystem.

Before running this script, first run the QSH CL command to enter the QShell environment. Use the following syntax for the remove_autostart_server.sh script:

/QIBM/ProdData/WBIServer44/bin/remove_autostart_server.sh QWBIDFT44

Auto-starting the name server

It is recommended that you leave the name server as an auto-start job in the subsystem. Auto-starting this job enables a monitor to detect when the subsystem or system is ending in a controlled manner. Without this monitor, the QWBISVR44 subsystem and its jobs will not end as a result of a controlled end.

Auto-starting InterChange Server, Adapter agents and Object Discovery agents

To automatically start the InterChange Server, Adapter agents and Object Discovery agents, run the start_server.sh (for InterChange Server), specific adapter scripts, for example, start_JText.sh, or the object discovery agent scripts, for example, start_JDBCODA.sh directly with the QWBISVR44 subsystem.

All executables, the repository database and specific files are secured to the user profile, it is important to use the QWBISVR44 subsystem. Additionally, always run InterChange Server under the QWBISVR44 user profile to avoid unpredictable authority problems.

If you want the adapter agent jobs to run under a different user profile, change the user parameter in the job description from QWBISVR44 to the different user profile. This would be helpful if it is necessary to prohibit the QWBISVR44 user profile from accessing application data secured by a different user profile,

Note:
It is not recommended that you use QSHell from the i5/OS command entry to run these scripts, since this will result in the jobs running in the QINTER subsystem, under the user profile used during login.

Changing the IBM ORB port

Perform the following steps to change the IBM ORB port:

  1. Open the file /QIBM/UserData/WBIServer44/bin/CWSharedEnv.sh.
  2. Change the ORB_PORT value from 14500 to the appropriate port value.
  3. Stop the subsystem.
  4. Restart the subsystem using the new port.

If you are using any Windows client tools, you must change the CWSharedEnv.bat file in the product directory, end any active tool and restart the tool.

Note:
If necessary, you can also designate a different host or system alias for the ORB_HOST.

Changing the MQ listener port

When creating a server instance, you can specify the MQ listener port using the create_instance.sh script. Perform the following steps to change the MQ listener port:

  1. Open the file /QIBM/UserData/WBIServer44/instanceName/InterchangeSystem.cfg.
  2. Change the MQ listener port value, for example, in the lines below, change 1416 to the new port number.
    <tns:name>PORT</tns:name>
    <tns:value xml:space="preserve">1416</tns:value>
    Note:
    Use caution when editing this file or you may cause the InterChange Server not to start.
  3. Change the RQSDTA port in the job description to port number 1417, for example:
    CHGJOBD JOBD(QWBISVR44/QWBIDFT44) RQSDTA('QSYS/CALL
    PGM(QWBISVR44/QWBIDFT44) PARM(QWBIDFT44 ''1417'')')
    Note:
    By default, this port shares a name with the InterChange Server and resides in the QWBISVR44 library.

Changing the InterChange Server Repository name

When creating a server instance, you can specify the InterChange Server Repository name using the create_instance.sh script. Perform the following steps to change the repository name:

Note:
If you change the Interchange Server Repository name for a server instance, the delete_instance.sh script will not delete the Instance Server repository database. You will have to manually delete the Instance Server Repository using the drop collection SQL command.

  1. Import the server repository to a project in System Manager.
  2. Stop the QWBISVR44 subsystem.
  3. Run STRSQL from i5/OS command entry.
  4. Run CREATE COLLECTION(newname), where newname is the new name for the repository.
    Note:
    The STRSQL profile has *RWX authority to the new repository. Use the EDTOBJAUT command and the *RWX authority to make QWBIDFT44 the new owning profile.
  5. Edit DATA_SOURCE_NAME in three locations (jdbc:db2:localhost/newName) in /QIBM/UserData/WBIServer44/instanceName/InterchangeSystem.cfg, where newName is the new name of the repository.
  6. Stop the instance name server using System Manager, using the stop_server_gracefully.sh script or by ending the QWBISVR44 subsystem.
  7. Start the SQL server and run drop collection instanceName, where instanceName is the name for the InterChange Server.
  8. Ignore any CPA7025 message you receive.
  9. Run the submit_ics_server.sh script to start the server.

Changing the queue manager name

When creating a server instance, you specify the queue manager name using the create_instance.sh script. Perform the following steps to change the queue manager name:

  1. Enter the CHGJOBD JOBD(QWBISVR44/QWBIDFT44) command and click F4 to prompt on the parameters.
  2. Edit the RQSDTA value to replace the existing queue manager value. For example, the queue manger name for the default instance is QWBIDFT44.QUEUE.MANAGER. Replace the existing queue manager name with the new name, preserving the spaces at the end of the queue manager name, if necessary, so that the queue manager name string is 48 characters or greater.
  3. Edit the queue manager name in /QIBM/UserData/WBIServer44/instanceName/InterchangeSystem.cfg to the new queue manager name.
  4. Stop the instance name server using System Manager, using the stop_server_gracefully.sh script or by ending the QWBISVR44 subsystem.
  5. Use the ENDMQM and DLTMQM commands to stop and delete the instanceName.QUEUE.MANAGER queue manager.
  6. Run the submit_ics_server.sh script to start the server.

i5/OS scripts

WebSphere Business Integration Server Express ships with many scripts unique to i5/OS. These scripts are located in the /QIBM/ProdData/WBIServer44/bin directory.

The following sections describe each script in detail.

add_autostart_adapter.sh

This script sets up to automatically deploy the adapter agent, when the InterChange Server is started with the QWBISVR44 subsystem. The script also adds information to the auto-start job for the server instance, allowing the server instance to submit a job for the adapter agent.

Syntax

The following is the syntax for the add_autostart_adapter.sh:

add_autostart_adapter.sh adapterName instanceName startScript jobDescription

where:

Example

The following is an example for the JText adapter:

add_autostart_adapter.sh JText QWBIDFT44 /QIBM/UserData/WBIServer44/QWBIDFT44/connectors/JText/start_JText.sh QWBIJTEXTC

add_autostart_server.sh

This script configures the InterChange Server to start automatically with the subsystem. When creating a server instance using the create_instance.sh script, the instance is set to automatically start with the subsystem. If you remove this functionality using the remove_autostart_server.sh script, use the add_autostart_server.sh to reset to autostart.

Syntax

The following is the syntax for the add_autostart_server.sh:

add_autostart_server.sh serverName jobDescription,

where:

create_instance.sh

This script creates a new Interchange Server instance, along with new directories in /QIBM/UserData/WBIServer44 for the InterChange Server. This script also copies the installed adapters to this directory, creates a repository DB2/400 database and MQ queue with the same name as the instance, creates an MQ listener for the MQ queue with the specific port number, and adds an auto-start job entry to the QWBISVR44 subsystem for the new InterChange Server.

Syntax

The following is the syntax for the create_instance.sh:

create_instance.sh [ -rrepositoryName ] [ -qqueueManagerName [ -exists ] ] [ -uuser -ppassword ] [ -dsystem -ndbUser -wdbPassword ] serverName mqPortNumber httpPortNumber

delete_instance.sh

This script deletes an Interchange Server instance, as well as the directories for the server in /QIBM/UserData/WBIServer44, the repository DB2/400 database for the server, and the auto-start job entry for the server from the QWBISVR44 subsystem description. This script does not delete the existing queue manager for the server.

Note:
If you change the Interchange Server Repository name for a server instance, the delete_instance.sh script will not delete the Instance Server repository database. You will have to manually delete the Instance Server Repository using the drop collection SQL command.
Syntax

The following is the syntax for the delete_instance.sh:

delete_instance.sh instanceName,

where:

remove_autostart_adapter.sh

This script removes the auto-start designation from an adapter agent that is currently being automatically started with a server instance, as well as editing the auto-start job for the InterChange Server instance and removing the statements that submit the adapter agent job.

Syntax

The following is the syntax for the remove_autostart_adapter.sh:

remove_autostart_adapter.sh adapterName instanceName,

where:

remove_autostart_server.sh

This script removes the auto-start designation from an InterChange Server instance, as well as removing the auto-start job entry for the InterChange Server instance from the QWBISVR44 subsystem.

Syntax

The following is the syntax for the remove_autostart_adapter.sh:

remove_autostart_server.sh instanceName,

where:

set_ics_server_mode.sh

This script sets the mode of the InterChange Server. This script applies the new mode, either design, production, testOn or testOff, the next time InterChange Server starts.

Syntax

The following is the syntax for the set_ics_server_mode.sh:

set_ics_server_mode.sh instanceName mode,

where:

stop_server_gracefully.sh

This script gracefully stops InterChange Server from a CL program or command entry on the i5/OS and is equivalent to System Manager or System Monitor issuing a shutdown graceful command.

Syntax

The following is the syntax for the stop_server_gracefully.sh:

stop_server_gracefully.sh instanceName,

where:

Note:
If RBAC is enabled, the stop_server_gracefully.sh also requires the
-uusername and -ppassword parameters.

stop_adapter.sh

This script stops an adapter agent job gracefully when it is not practical to use System Manager or System Monitor.

Syntax

The following is the syntax for the stop_adapter.sh:

stop_adapter.sh instanceName adapterName,

where:

Example

The following is an example for the JText adapter:

stop_adapter.sh QWBIDFT44 JText

submit_adapter.sh

This script submits an adapter agent job to run in the QWBISVR44 subsystem. You must start the QWBISVR44 subsystem before using this command.

Syntax

The following is the syntax for the submit_adapter.sh:

submit_adapter.sh adapterName instanceName startScript jobDescription [parm5] [parm6] [parm7],

where:

Example

The following is an example for the JText adapter:

submit_adapter.sh JText QWBIDFT44 /QIBM/UserData/WBIServer44/QWBIDFT44/connectors/JText/start_JText.sh QWBIJTEXTC -c/ QIBM/UserData/WBIServer44/QWBIDFT44/connectors/JText/JText.cfg

submit_ics_server.sh

This script submits an InterChange Server instance job to run in the QWBISVR44 subsystem, providing the logic necessary to run a batch job using start_server.sh script. This script includes optional parameters 2 through 6, allowing you to pass parameters to the start_server.sh script through the submit_ics_server.sh script.

Syntax

The following is the syntax for the submit_ics_server.sh:

submit_ics_server.sh instanceName [parm2] [parm3] [parm4] [parm5] [parm6],

where:

submit_name_server.sh

This script submits the name server job to run in the QWBISVR44 subsystem.

submit_oda.sh

This script submits an object discovery agent job to run in the QWBISVR44 subsystem, providing the necessary logic to submit a job in subsystem QWBISVR44 to run the script name passed as parameter 1.

Syntax

The following is the syntax for the submit_oda.sh:

submit_oda.sh startODAScript jobDescription,

where:

Example

The following is an example for the JDBC ODA:

submit_oda.sh /QIBM/ProdData/WBIServer44/product/oda/JDBC/start_JDBCODA.sh QWBIJDBODA

User profile security for i5/OS

For security reasons, it may be necessary to change the user profile under which the adapter agent processes run, for example, the JDBC database authorities or JText directories or files. Changing the user profile prohibits the QWBISVR44 user profile from accessing these adapter processes.

Perform the following steps to change the user profile:

  1. Use the CHGJOBD CL command to change the job description for the adapter agent. Set the USER parameter to the new user profile.
  2. Use the GRTOBJAUT CL command to grant the new user profile authority to the new job description, by setting the USER parameter to the new user profile and the AUT parameter to either *READ or *EXECUTE.
  3. Use the GRTOBJAUT CL command to grant the new user profile authority to the QWBISVR44 library, by setting the USER parameter to the new user profile and the AUT parameter to either *READ or *EXECUTE.
  4. Use the GRTOBJAUT CL command to grant the new user profile authority to the QWBISVR44 subsystem description, by setting the USER parameter to the new user profile and the AUT parameter to either *READ or *EXECUTE.
  5. Use the GRTOBJAUT CL command to grant the new user profile authority to the QWBISVR44 class, by setting the USER parameter to the new user profile and the AUT parameter to either *READ or *EXECUTE.
  6. Use the CHGAUT CL command to grant the new user profile authority to the directory that houses the connector in the Integrated File System by setting the USER parameter to the new user profile and the DTAAUT parameter to *RWX.

Stopping the subsystem with i5/OS

When stopping the subsystem using i5/Os, the code includes a sigaction handler that controls the ENDSBS *CNTRLD action. This handler allows the QWBISVR44 subsystem to end in a controlled manner by gracefully terminating the InterChange Server, as well as any jobs or adapters running on the local system. When this completes, the handler self-terminates.

Copyright IBM Corp. 2004, 2005