Transactional batch application setup instructions

This sample contains a XDCGIVT batch project which associates with an EJB project (XDCGIVTEJBs) and an EAR project (XDCGIVTEAR). The XDCGIVT application is a transactional batch application that reads and writes files.

Before you begin

  1. Install one of the following supported servers:
    • WebSphere® Application Server V8.5
    • WebSphere Application Server V8.0
    • WebSphere Application Server V8.0 with WebSphere Extended Deployment Compute Grid V8.0
    • WebSphere Application Server V7.0 with Feature Pack for Modern Batch
  2. Configure WebSphere Application Server to accept batch applications.
    Tip: The application server is not ready to accept batch applications, if you cannot open the Modern Batch job management console. For example, if you try to go to the Servers view, right-click the server and select Modern Batch Job Management Console you might get one of the following error messages:
    • For WebSphere Application Server V8.0 or V8.5:
      The webpage cannot be found
    • For WebSphere Application Server V7.0 with Feature Pack for Modern Batch:
      404 error:  JSPG0036E: Failed to find resource /jmc/console.jsp
    To overcome these error messages, complete the Configuring WebSphere Application Server to accept batch application task for your server and return to this page for information about running the sample.

About this task

To run the sample on the server, follow these steps:

Procedure

  1. Determine which supported version of the server you want to run this sample on by adding the server in the Servers view:
    • WebSphere Application Server V7.0
    • WebSphere Application Server V8.0
    • WebSphere Application Server V8.5
    1. To open the Servers view, go to the toolbar and select Window > Show View > Servers.
    2. To add a server entry, right-click in the Servers view and select New > Server. Follow the instructions in the New Server wizard, ensuring that you select either WebSphere Application Server V7.0, WebSphere Application Server V8.0 or WebSphere Application Server V8.5. For more details, see the Creating a WebSphere Application Server topic.
  2. Import the sample into your workspace:
    1. Click: Import Sample

      To use the sample, click Import sample, and save the compressed file to a directory on your workstation. After downloading the sample, import the sample project into your workspace: Click File > >Import > >Existing projects into workspace > >Select archive file, and then click Browse to find the downloaded sample project file

    2. In the Import wizard, accept the default settings and click Finish.
    3. If you want to run this sample on WebSphere Application Server V8.0 or V8.5, you must change the default setting for the targeted runtime environment. The default environment for this sample is set to WebSphere Application Server V7.0. The Sample Runtime Targeting wizard opens only if the workbench does not contain a WebSphere Application Server V7.0 runtime environment:
      • If the Sample Runtime Targeting wizard opens, the workbench does not contain a WebSphere Application Server V7.0 runtime environment:
        1. Select Manually install a compatible runtime or stub after importing the sample option and click Finish.
        2. In the Workspace Migration page, click Next.
        3. On the Workspace projects which need migration page, click Next.
        4. On the Migration Project Resources page, click Next.
        5. In the Server Runtimes list on the Undefined Server Runtime page, for the was.base.v7 entry, select WebSphere Application Server v8.0 or WebSphere Application Server v8.5 under the New Server Runtime column. Click Next.
        6. On the Complete Migration Startup page, click Finish.
        7. On the Migration Validation window, click OK.
      • If the Sample Runtime Targeting wizard does not open, the workbench contains a WebSphere Application Server V7.0 runtime environment:
        1. In the Enterprise Explorer view, right-click the SimpleCIEAR project and select Properties > Targeted Runtimes.
        2. Select the WebSphere Application Server V8.0 or WebSphere Application Server V8.5 check box, and click OK.
    4. When the import is complete, you can see the following projects in the Enterprise Explorer view:
      This is a screen capture of the Enterprise Explorer view containing the imported XDCGIVT sample projects.
  3. For a local WebSphere Application Server, create a database connection to a local Derby database:
    Important: Complete this step only if your WebSphere Application Server is on the same computer as the development workbench. For a remote WebSphere Application Server, you must skip this step for creating a local Derby database connection because you will create the IVTDB database on the same computer as the remote server.
    1. Right-click in the Database Connections folder in the Data Source Explorer view, and select New. The New Connection wizard opens.
    2. Under the Select a database manager list, select Derby.
    3. In the JDBC driver list, select Derby 10.2 - Embedded JDBC Driver Default.
    4. Click the Edit Driver Definition (This is a graphical icon of the Edit Driver Definition button.) button. The Edit Jar List wizard opens.
    5. Under the Driver files list, select the derby.jar entry and click the Remove JAR/Zip button. The Driver files list should now be empty.
    6. Use the Add JAR/Zip button to add the following four JAR files from the <WAS_directory>\derby\lib directory, where <WAS_directory> is the installation directory for a local WebSphere Application Server and then click OK:
      • derby.jar
      • derbyclient.jar
      • derbynet.jar
      • derbytools.jar
      Here is an example screen capture of adding the Derby JDBC driver files into the Edit Jar List wizard:
      This is a screen capture of the Edit Jar List wizard.
    7. In the New Connection dialog, under the Properties section in the Database location field, specify <workspace_directory>/XDCGIVT/IVTDB directory, where <workspace_directory> is the directory of your workspace. Click Finish.
    8. In the Data Source Explorer view, expand the Database Connections folder, right-click IVTDB, and select Disconnect.
  4. For a remote WebSphere Application Server, create the IVTDB database in the same computer as the remote server:
    Important: Complete this step only if your WebSphere Application Server is on a remote computer from the development workbench. For a local WebSphere Application Server, you must skip this step and proceed with the next step.
    1. Run the java –version command.

      By running the command, you can verify that Java™ Version 1.6 or later is installed and included in the PATH variable of your operating system.

    2. Locate the CreateIVTTablesDerby.ddl file:
      • For WebSphere Application Server V7.0 with Feature Pack for Modern Batch, a copy of the CreateIVTTablesDerby.ddl file is available in the following directory on the remote computer:

        This is a graphical icon for Linux.This is a graphical icon for HP-UXThis is a graphical icon for Solaris.This is a graphical icon for AIX.This is a graphical icon for z/OS<remote_WAS_directory>/feature_packs/BATCH/longRunning

        This is a graphical icon for Windows. <remote_WAS_directory>\feature_packs\BATCH\longRunning

        Where <remote_WAS_directory> is the installation directory of the remote WebSphere Application Server.
      • Alternatively, in the local computer running the workbench, you can find a local copy of the CreateIVTTablesDerby.ddl file in <workspace_directory>\XDCGIVT\data\ddl\CreateIVTTablesDerby.ddl where <workspace_directory> is the directory of your workspace. Create a copy of the CreateIVTTablesDerby.ddl file in the same computer as the remote server.
    3. Open a command prompt and change to the Derby database directory:

      This is a graphical icon for Linux.This is a graphical icon for HP-UXThis is a graphical icon for Solaris.This is a graphical icon for AIX.This is a graphical icon for z/OS<remote_WAS_directory>/derby/databases

      This is a graphical icon for Windows. <remote_WAS_directory>\derby\databases

    4. Run the following command:
      This is a graphical icon for Linux.This is a graphical icon for HP-UXThis is a graphical icon for Solaris.This is a graphical icon for AIX.This is a graphical icon for z/OS
      java -Djava.ext.dirs=<remote_WAS_directory>/derby/lib 
      -Dij.protocol=jdbc:derby: org.apache.derby.tools.ij 
      <path>/CreateIVTTablesDerby.ddl
      Where <remote_WAS_directory> is the installation directory of the remote WebSphere Application Server and <path> is the directory path to the CreateIVTTablesDerby.ddl file in the same computer as the remote server.
      For example:
      java -Djava.ext.dirs=/opt/IBM/WebSphere/AppServer/derby/lib 
      -Dij.protocol=jdbc:derby: org.apache.derby.tools.ij 
      /opt/IBM/WebSphere/AppServer/feature_packs/BATCH/longRunning/CreateIVTTablesDerby.ddl
      Tip: If the file path contains a space, you must escape the whitespace in the file path.
      This is a graphical icon for Windows.
      java -Djava.ext.dirs=<remote_WAS_directory>\derby\lib 
      -Dij.protocol=jdbc:derby: org.apache.derby.tools.ij 
      <remote_WAS_directory>\feature_packs\BATCH\longRunning\CreateIVTTablesDerby.ddl
      Where <remote_WAS_directory> is the installation directory of the remote WebSphere Application Server.
      For example:
      java -Djava.ext.dirs="C:\Program Files\IBM\WebSphere\AppServer\derby\lib" 
      -Dij.protocol=jdbc:derby: org.apache.derby.tools.ij 
      "C:\Program Files\IBM\WebSphere\AppServer\feature_packs\BATCH\longRunning\CreateIVTTablesDerby.ddl"
      Tip: If the file path contains a space, you must enclose the file path with quotations.
  5. Configure the datasource in the deployment descriptor:
    1. In the Enterprise Explorer view, expand the XDCGIVTEAR project, right-click the Deployment Descriptor: XDCGIVTEAR, and select Open. The Application Deployment Descriptor editor opens.
    2. Select the Deployment tab.
    3. In the Resource properties defined in the data source selected above list under the Data Source section, select databaseName and click the Edit button. The Edit Resource Property wizard opens.
    4. In the Value field, specify the file path to the IVTDB database. The file path depends if the database was created for a local or remote WebSphere Application Server; and the operating system running the server and database:
      For a local WebSphere Application Server
      This is a graphical icon for Linux.<workspace_directory>/XDCGIVT/IVTDB
      This is a graphical icon for Windows.<workspace_directory>\XDCGIVT\IVTDB
      Where <workspace_directory> is the directory of your workspace.
      For a remote WebSphere Application Server
      This is a graphical icon for Linux.This is a graphical icon for HP-UXThis is a graphical icon for Solaris.This is a graphical icon for AIX.This is a graphical icon for z/OS<remote_WAS_directory>/derby/databases/IVTDB
      This is a graphical icon for Windows.<remote_WAS_directory>\derby\databases\IVTDB
      Where <remote_WAS_directory> is the installation directory of the remote WebSphere Application Server.
    5. Click the OK button.
    6. Save the changes in the Application Deployment Descriptor editor by pressing Ctrl + s.
  6. Modify the input values to run the sample:
    Tip: You will need to repeat this step for each of the batch job files contained in the XDCGIVT sample.
    1. In the Enterprise Explorer, expand XDCGIVT > xJCL folders. You will find the following batch job files:
      XDCGIVTbyte2bytexJCL.xml
      Copies a byte file to another byte file and compares the two files.
      XDCGIVTtxt2db2txtxJCL.xml
      Copies a text file to a database, copies the entries in the database to another text file, and compares the two files.
      XDCGIVTtxt2txtxJCL.xml
      Copies one text file to another text file and compares the two files.
      Jobs are expressed using an Extensible Markup Language XML dialect called XML Job Control Language (xJCL). All jobs contain the following information:
      • The identity of the batch application that performs the work
      • One or more job steps that must be performed to complete the work
      • The identity of an artifact within the application that provides the logic for each job step
      • Key and value pairs for each job step to provide additional context to the application artifacts
      For more details, see Batch applications, jobs, and job definitions topic available in the Information Center for the WebSphere Application Server.
    2. Right-click one of the above batch job files and select Open. The XJCL editor opens.
    3. In the Design tab of the XJCL editor, under the Batch Job Structure section, expand Job (XDCGIVT) > Substitution properties nodes.

      Substitution properties define name and value pairs for symbolic variables. In a xJCL file, a symbolic variable is an expression of the form ${variable-name}, which is found outside a comment in an otherwise well-formed document. Substitution for symbolic variables occurs at run time. At run time, the string ${variable-name} is replaced with the value of the property when the xJCL file is issued.

      In each of the batch job files, there are two substitution properties which require modifications: inputDataStream and outputDataStream
      Table 1. . This table lists the default values specified for the inputDataStream and outputDataStream substitution properties.
        inputDataStream outputDataStream
      XDCGIVTbyte2bytexJCL.xml /data/input-txlist.txt /data/output-txlist.txt
      XDCGIVTtxt2db2txtxJCL.xml /data/input.txt /data/output.txt
      XDCGIVTtxt2txtxJCL.xml /data/input-text.txt /data/output-text.txt
      The table above lists the default values specified for the inputDataStream and outputDataStream substitution properties. You need to substitute /data/ with an existing directory on your file system that you have read and write permissions; and where you want the text files to be written when running this sample. For example, C:\temp\input.txt.
      Tip: The filename for the text files appends the job name and job number. For WebSphere Application Server for z/OS®, the text files must be converted to Extended Binary Coded Decimal Interchange Code (EBCDIC) to view the contents.
    4. In the XJCL editor, select the Property (inputDataStream) node (repeat this step for Property (outputDataStream) ). Under the Details section, in the Value field, replace /data/ with an existing directory on your file system directory. For example, C:\temp\input-txlist.txt.
    5. Save the changes in the XJCL editor by pressing CTRL+S.
  7. To run the sample on the server:
    1. In the Servers view, right-click the server and select Start. Wait for the server to start by checking in the Servers view that the state and status of the server changes to Started and Synchronized.
    2. In the Servers view, right-click the server and select Add and Remove. The Add and Remove wizard opens. Under the Available list, select the XDCGIVTEAR application and click the Add button. Click the Finish button in the Add and Remove wizard. Wait for the application to publish and start by checking in the Servers view that the state and status of the application changes to Started and Synchronized.
    3. In the Enterprise Explorer view, expand XDCGIVT > xJCL folders, right-click one of the XDCGIVT batch job file, select Run As > Modern Batch Job. The Run Configurations wizard opens.
    4. If security is enabled, select the Security is enable on this server check box to specify the server is secured. In the User ID field and Password fields, specify the user name and password for the job scheduler.
      Tip: You can find which user or group maps to the security roles, lradmin and lrsubmitter, by opening the Administrative Console and select System administration > Job scheduler > Security role to user/group mapping
    5. In the Run Configurations wizard, click the Run button to issue the batch job file. The Modern Batch Job Management Console opens.
  8. View the job and log in the Modern Batch Job Management Console:
    1. In the Modern Batch Job Management Console, on the left pane under the Job Management section, click the View jobs link. The job table displays and lists the jobs submitted.
      This is a screen capture of the of the Modern Batch Job Management Console.
    2. Under the Job ID column, click the XDCGIVT:<jobID> link. The job log displays. You can click the Download button to open or save a copy of the job log.
      A job log contains the following information:
      • A copy of the xJCL used to run the job, including xJCL substitution values.
      • A set of system messages that communicate the major life cycle events corresponding to the job. Example of system events that are recorded in a job log are the begin and end of a job and step.
      • A set of messages written to standard out and standard error by a job step program.
      For more details about job log, see the Job logs topic available in the Information Center for WebSphere Application Server.

Feedback